Package Exports
- kick-wss
- kick-wss/EventEmitter
- kick-wss/MessageParser
- kick-wss/WebSocketManager
- kick-wss/examples
- kick-wss/package.json
- kick-wss/types
Readme
Kick WebSocket
A lightweight and dependency-free library for connecting to Kick.com WebSockets.
Features
- 🚀 Lightweight: No external dependencies, uses native WebSocket only
- 🔌 Simple: Intuitive and easy-to-use API
- 🔄 Auto-reconnection: Configurable automatic reconnection
- 📊 Message Buffer: Optional, for data analysis
- 🎯 Event Filtering: Listen only to the events you need
- 🛠️ TypeScript: Full type support
- 📝 Debug Mode: Detailed logging for development
- 🌐 Browser Support: Full compatibility with modern browsers
- 📱 Mobile Ready: Optimized for mobile devices
Installation
Node.js
npm install kick-wssBrowser (CDN)
<!-- Minified version -->
<script src="https://unpkg.com/kick-wss@latest/dist/kick-wss.min.js"></script>
<!-- ES Modules -->
<script type="module">
import { KickWebSocket } from 'https://unpkg.com/kick-wss@latest/dist/kick-wss.min.js';
// Your code here
</script>Basic Usage
Node.js / Backend
import { KickWebSocket } from 'kick-wss';
// Create instance
const kickWS = new KickWebSocket({ debug: true });
// Connect to a channel
kickWS.connect('channel-name');
// Listen to chat messages
kickWS.on('ChatMessage', (message) => {
console.log(`${message.sender.username}: ${message.content}`);
});
// Listen to connection events
kickWS.on('ready', () => {
console.log('✅ Successfully connected');
});
kickWS.on('disconnect', ({ reason }) => {
console.log('❌ Disconnected:', reason);
});
kickWS.on('error', (error) => {
console.error('⚠️ Error:', error);
});Browser / Frontend
<!DOCTYPE html>
<html>
<head>
<title>Kick WebSocket Example</title>
</head>
<body>
<div id="messages"></div>
<script type="module">
import { KickWebSocket } from 'https://unpkg.com/kick-wss@latest/dist/kick-wss.min.js';
const kickWS = new KickWebSocket({ debug: true });
const messagesDiv = document.getElementById('messages');
kickWS.onChatMessage((message) => {
const messageEl = document.createElement('div');
messageEl.innerHTML = `<strong>${message.sender.username}:</strong> ${message.content}`;
messagesDiv.appendChild(messageEl);
});
kickWS.connect('xqc');
</script>
</body>
</html>🌐 Browser Compatibility
Supported Browsers
- Chrome 80+
- Firefox 72+
- Safari 13.1+
- Edge 80+
Compatibility Check
Polyfills (if needed)
<!-- For older browsers -->
<script src="https://cdn.jsdelivr.net/npm/whatwg-fetch@3.6.2/dist/fetch.umd.js"></script>For more details on browser usage, see BROWSER.md.
Convenience Methods
Listen to specific event types
// Chat messages only
kickWS.onChatMessage((message) => {
console.log('Message:', message.content);
});
// User bans only
kickWS.onUserBanned((ban) => {
console.log('Banned user:', ban.username);
});
// Subscriptions only
kickWS.onSubscription((sub) => {
console.log('New subscription:', sub.username);
});
// All chat events
kickWS.onChatEvents((event) => {
console.log('Chat event:', event);
});
// All user events
kickWS.onUserEvents((event) => {
console.log('User event:', event);
});
// All events in general
kickWS.onAllEvents((event) => {
console.log('Event:', event);
});Advanced Configuration
Available Options
const options = {
debug: false, // Show debug logs
autoReconnect: true, // Reconnect automatically
reconnectInterval: 5000, // Reconnection interval (ms)
enableBuffer: false, // Enable message buffer
bufferSize: 1000, // Maximum buffer size
filteredEvents: [] // Events to listen to (empty = all)
};
const kickWS = new KickWebSocket(options);Event Filtering
// Listen only to messages and bans
kickWS = new KickWebSocket({
filteredEvents: ['ChatMessage', 'UserBanned', 'Subscription']
});
// Or use the KICK_EVENTS constant for all available events
import { KICK_EVENTS } from 'kick-wss';
// Listen to all events
kickWS = new KickWebSocket({
filteredEvents: KICK_EVENTS
});
// Listen to specific categories
kickWS = new KickWebSocket({
filteredEvents: KICK_EVENTS.filter(event =>
event.includes('Chat') || event.includes('User')
)
});Message Buffer for Analysis
kickWS = new KickWebSocket({
enableBuffer: true,
bufferSize: 2000
});
// Get messages from buffer
const messages = kickWS.getMessageBuffer();
console.log(`Buffer has ${messages.length} messages`);
// Clear buffer
kickWS.clearMessageBuffer();Convenience Methods
Debug Mode
const kickWS = KickWebSocket.createDebug('channel-name');Available Events
Chat Events
ChatMessage: New chat messagesMessageDeleted: Messages deleted by moderatorsPinnedMessageCreated: Pinned messages
User Events
UserBanned: Banned usersUserUnbanned: Unbanned usersSubscription: New subscriptionsGiftedSubscriptions: Gifted subscriptions
Stream Events
StreamHost: When a channel hosts anotherPollUpdate: Poll updatesPollDelete: Deleted polls
System Events
ready: Connection establisheddisconnect: Connection closederror: Connection errorrawMessage: Raw WebSocket message
Data Structure
Chat Message
interface ChatMessageEvent {
id: string;
content: string;
type: 'message';
created_at: string;
sender: {
id: number;
username: string;
slug: string;
identity: {
color: string;
badges: string[];
};
};
chatroom: {
id: number;
};
}Other Events
Each event has its own data structure. See TypeScript types for details.
Practical Examples
Activity Logging Bot
import { KickWebSocket } from 'kick-wss';
const kickWS = new KickWebSocket({ debug: true });
// Connect to multiple channels
const channels = ['streamer1', 'streamer2', 'streamer3'];
channels.forEach(channel => {
const ws = new KickWebSocket();
ws.connect(channel);
ws.onChatMessage((message) => {
// Save to database
saveToDatabase({
channel,
user: message.sender.username,
message: message.content,
timestamp: message.created_at
});
});
ws.onUserBanned((ban) => {
console.log(`🚫 ${ban.username} banned in ${channel}`);
});
});Real-time Activity Analyzer
const kickWS = new KickWebSocket({
debug: true,
enableBuffer: true,
bufferSize: 2000,
filteredEvents: [
'ChatMessage',
'UserBanned',
'Subscription',
'GiftedSubscriptions'
]
});
kickWS.connect('popular-streamer');
let messageCount = 0;
let subscriberCount = 0;
let banCount = 0;
kickWS.onChatMessage(() => messageCount++);
kickWS.onSubscription(() => subscriberCount++);
kickWS.onUserBanned(() => banCount++);
// Report every minute
setInterval(() => {
console.log(`📊 Statistics for the last minute:
Messages: ${messageCount}
Subscriptions: ${subscriberCount}
Bans: ${banCount}
`);
// Reset counters
messageCount = 0;
subscriberCount = 0;
banCount = 0;
}, 60000);Notification System
const kickWS = new KickWebSocket();
kickWS.connect('monitored-channel');
kickWS.onChatMessage((message) => {
// Detect keywords
if (message.content.includes('!help') || message.content.includes('!admin')) {
sendNotification(`🚨 Help requested by ${message.sender.username}`);
}
});
kickWS.onUserBanned((ban) => {
sendNotification(`🔨 Banned user: ${ban.username}`);
});
kickWS.onSubscription((sub) => {
sendNotification(`⭐ New subscription: ${sub.username}`);
});
function sendNotification(message: string) {
// Implement your notification system
console.log('NOTIFICATION:', message);
}API Reference
Main Methods
connect(channelName: string): Promise<void>- Connect to a channeldisconnect(): void- Manual disconnecton(event, handler): void- Listen to an eventonce(event, handler): void- Listen to an event onceoff(event, handler): void- Stop listening to an eventisConnected(): boolean- Check if connectedgetConnectionState(): ConnectionState- Get connection state
Information Methods
getChannelName(): string- Current channel namegetChannelId(): number- Current channel IDgetMessageBuffer(): string[]- Get message bufferclearMessageBuffer(): void- Clear buffergetStats(): object- Get statisticsupdateOptions(options): void- Update configuration
Limitations
- 📖 Read-only: Does not send messages to chat
- 🔓 No Authentication: Only works with public chats
- 🌐 Requires Internet: Connection to Kick.com servers
Contributing
Contributions are welcome. Please:
- Fork the project
- Create a branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE file for details.
Support
- 🐛 Issues: GitHub Issues
- 📖 Documentation: Wiki
Kick WebSocket Lite - The simplest way to connect to Kick.com chats.