kick-wss

v1.0.5

Published

a month ago

Lightweight dependency-free library for connecting to Kick.com WebSockets

Downloads

160

0High
0Medium
0Low

memelser

kick kick.com websocket chat streaming bot events real-time lightweight no-dependencies typescript browser client-side frontend cdn minified

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
📊 Event Filtering: Listen only to the events you need
🎯 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-wss

Browser (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/[email protected]/dist/fetch.umd.js"></script>

For more details on browser usage, see BROWSER.md.

Advanced Configuration

Available Options

const options = {
  debug: false,              // Show debug logs
  autoReconnect: true,       // Reconnect automatically
  reconnectInterval: 5000,   // Reconnection interval (ms)
  connectionTimeout: 10000,  // Connection timeout (ms)
  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')
  )
});

Using Enums for Events

// Import the KickEvent enum
import { KickEvent } from 'kick-wss';

// Use enum values for better type safety
kickWS.on(KickEvent.ChatMessage, (message) => {
  console.log(`${message.sender.username}: ${message.content}`);
});

// Filter events using enum values
kickWS = new KickWebSocket({
  filteredEvents: [
    KickEvent.ChatMessage,
    KickEvent.UserBanned,
    KickEvent.Subscription
  ]
});

Convenience Methods

Debug Mode

const kickWS = KickWebSocket.createDebug('channel-name');

Event Category Methods

// Listen to all chat events
kickWS.onChatEvents((event) => {
  console.log('Chat event:', event);
});

// Listen to all user events
kickWS.onUserEvents((event) => {
  console.log('User event:', event);
});

// Listen to all stream events
kickWS.onStreamEvents((event) => {
  console.log('Stream event:', event);
});

// Listen to all events
kickWS.onAllEvents((event) => {
  console.log('Any event:', event);
});

Available Events

Chat Events

ChatMessage: New chat messages
MessageDeleted: Messages deleted by moderators
PinnedMessageCreated: Pinned messages

User Events

UserBanned: Banned users
UserUnbanned: Unbanned users
Subscription: New subscriptions
GiftedSubscriptions: Gifted subscriptions
KicksGifted: Kicks gifts sent by users

Stream Events

StreamHost: When a channel hosts another
PollUpdate: Poll updates
PollDelete: Deleted polls

System Events

ready: Connection established
disconnect: Connection closed
error: Connection error
rawMessage: 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;
  };
}

Kicks Gifted Event

interface KicksGiftedEvent {
  gift_transaction_id: string;
  message: string;
  sender: {
    id: number;
    username: string;
    username_color: string;
  };
  gift: {
    gift_id: string;
    name: string;
    amount: number;
    type: string;
    tier: string;
    character_limit: number;
    pinned_time: number;
  };
  type: "kicks_gifted";
}

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

import { KickEvent } from 'kick-wss';

const kickWS = new KickWebSocket({
  debug: true,
  filteredEvents: [
    KickEvent.ChatMessage,
    KickEvent.UserBanned,
    KickEvent.Subscription,
    KickEvent.GiftedSubscriptions
  ]
});

kickWS.connect('popular-streamer');

let messageCount = 0;
let subscriberCount = 0;
let banCount = 0;

kickWS.on(KickEvent.ChatMessage, () => messageCount++);
kickWS.on(KickEvent.Subscription, () => subscriberCount++);
kickWS.on(KickEvent.UserBanned, () => 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 channel
disconnect(): void - Manual disconnect
on(event, handler): void - Listen to an event
once(event, handler): void - Listen to an event once
off(event, handler): void - Stop listening to an event
isConnected(): boolean - Check if connected
getConnectionState(): ConnectionState - Get connection state

Information Methods

getChannelName(): string - Current channel name
getChannelId(): number - Current channel ID
getConnectionState(): ConnectionState - Get connection state
isConnected(): boolean - Check if connected
updateOptions(options): void - Update configuration

WebSocket Configuration Methods

setWebSocketConfig(config): void - Set WebSocket URL and parameters
getWebSocketConfig(): WebSocketConfig - Get current WebSocket configuration
resetWebSocketConfig(): void - Reset to default configuration

Subscription Management Methods

subscribeToChannel(channel): void - Subscribe to additional channel
unsubscribeFromChannel(channel): void - Unsubscribe from channel
addCustomSubscriptions(channels): void - Add custom subscription channels
clearCustomSubscriptions(): void - Clear all custom subscriptions
getCustomSubscriptions(): object - Get current custom subscriptions

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.