Kick.com API Client

📋 Table of Contents

• Installation
• Quick Start
• Chat System
• Webhook Events
• Channel Management
• Category System
• User Management
• Error Handling
• TypeScript Support
• Examples

📥 Installation

npm install @botk4cp3r/kick.jsapi
# or
yarn add @botk4cp3r/kick.js
# or
pnpm add @botk4cp3r/kick.js

🚀 Quick Start

const { KickClient } = require('@botk4cp3r/kick.js');

// Create client instance
const client = new KickClient({
    token: 'your-api-token',
    webhookPort: 3000,
    webhookPath: '/webhook',
    webhookBaseUrl: 'http://your-domain.com'
});

// Start webhook server and subscribe to events
async function init() {
    await client.startWebhookServer();
    
    // Subscribe to all available events
    await client.subscribeToEvents([
        'chat.message.sent',
        'channel.followed',
        'channel.subscription.new',
        'channel.subscription.renewal',
        'channel.subscription.gifts'
    ]);
    
    console.log('Bot is ready!');
}

// Listen for events
client.on('chatMessage', message => {
    console.log(`${message.sender.username}: ${message.content}`);
});

client.on('channelFollowed', data => {
    console.log(`New follower: ${data.follower.username}!`);
});

client.on('subscriptionNew', data => {
    console.log(`New sub: ${data.subscriber.username}!`);
});

// Send a chat message
await client.sendChatMessage({
    content: 'Hello World!',
    type: 'bot'
});

init().catch(console.error);

💬 Chat System

Send Bot Messages

// Simple bot message
await client.sendChatMessage({
    content: 'Hello from bot!',
    type: 'bot'
});

// Simple user message
await client.sendChatMessage({
    content: 'Hello! Kappa',
    type: 'user',
    broadcasterUserId: '123456'
});

Listen for Chat Events

// New messages
client.on('chatMessage', msg => {
    console.log(`${msg.sender.username}: ${msg.content}`);
    
    // Auto-respond to commands
    if (msg.content === '!ping') {
        client.sendChatMessage({
            content: 'Pong! 🏓',
            type: 'bot'
        });
    }
});

📡 Webhook Events

Start Webhook Server

const client = new KickClient({
    token: 'your-api-token',
    webhookPort: 3000,
    webhookPath: '/webhook',
    webhookBaseUrl: 'http://your-domain.com'
});

await client.startWebhookServer();

Subscribe to Events

// Subscribe to specific events
await client.subscribeToEvents([
    'chat.message.sent',
    'channel.followed',
    'subscription.new',
    'channel.subscription.renewal',
    'channel.subscription.gifts'
]);

// Listen for events
client.on('channelFollowed', data => {
    console.log(`New follower: ${data.follower.username}`);
});

client.on('subscriptionNew', data => {
    console.log(`New sub: ${data.subscriber.username}`);
});

Custom Event Handlers

client.on('chatMessage', async (message) => {
    // Command system example
    const commands = {
        '!ping': () => 'Pong! 🏓',
        '!discord': () => 'Join our Discord: discord.gg/example'
    };

    const command = message.content.toLowerCase();
    if (commands[command]) {
        await client.sendChatMessage({
            content: commands[command](),
            type: 'bot'
        });
    }
});

🎯 Event Subscriptions

Available Events

const AVAILABLE_EVENTS = {
    'chat.message.sent',        // New chat messages
    'channel.followed',         // When someone follows the channel
    'channel.subscription.renewal', // Subscription renewals
    'channel.subscription.gifts',   // Gifted subscriptions
    'channel.subscription.new'      // New subscriptions
};

Managing Subscriptions

// Get current subscriptions
const currentSubs = await client.getEventSubscriptions();
console.log('Current subscriptions:', currentSubs);

// Subscribe to specific events
const subscription = await client.subscribeToEvents([
    'chat.message.sent',
    'channel.followed'
]);

// Subscribe with custom webhook method
const webhookSub = await client.subscribeToEvents([
    'channel.subscription.new', 
    'channel.subscription.gifts'
]);

// Unsubscribe from events
await client.unsubscribeFromEvents(['subscription-id-1', 'subscription-id-2']);

Event Validation

// Validate incoming webhook
const isValid = await client.validateWebhook(headers, rawBody);
if (isValid) {
    console.log('Valid webhook event!');
}

Full Subscription Example

const client = new KickClient({
    token: 'your-api-token',
    webhookPort: 3000,
    webhookPath: '/webhook',
    webhookBaseUrl: 'https://your-domain.com'
});

// Start webhook server
await client.startWebhookServer();

// Subscribe to multiple events
await client.subscribeToEvents([
    'chat.message.sent',
    'channel.followed',
    'subscription.new',
    'subscription.renewal',
    'subscription.gifts'
]);

// Handle different events
client.on('chatMessage', msg => {
    console.log(`Chat: ${msg.sender.username}: ${msg.content}`);
});

client.on('channelFollowed', data => {
    console.log(`New follower: ${data.follower.username}`);
});

client.on('subscriptionNew', sub => {
    console.log(`New sub: ${sub.subscriber.username}`);
});

client.on('subscriptionRenewal', renewal => {
    console.log(`Renewal: ${renewal.subscriber.username}`);
});

client.on('subscriptionGifts', gifts => {
    console.log(`${gifts.gifter.username} gifted ${gifts.giftees.length} subs!`);
});

// Error handling
client.on('error', error => {
    console.error('Subscription error:', error);
});

Webhook Payload Examples

Chat Message Event

{
    eventType: 'chat.message.sent',
    payload: {
        messageId: '123456',
        content: 'Hello world!',
        sender: {
            id: '789',
            username: 'username',
            displayName: 'Display Name'
        },
        emotes: [
            {
                id: '123',
                name: 'Kappa',
                position: { start: 6, end: 11 }
            }
        ]
    }
}

Follow Event

{
    eventType: 'channel.followed',
    payload: {
        broadcaster: {
            id: '123',
            username: 'broadcaster'
        },
        follower: {
            id: '456',
            username: 'follower'
        }
    }
}

Subscription Event

{
    eventType: 'subscription.new',
    payload: {
        broadcaster: {
            id: '123',
            username: 'broadcaster'
        },
        subscriber: {
            id: '456',
            username: 'subscriber'
        },
        tier: 1,
        months: 1
    }
}

📺 Channel Management

Get Channel Info

// Get single channel
const channel = await client.getChannels(['123456']);

// Get multiple channels
const channels = await client.getChannels(['123', '456', '789']);

Update Channel

// Update stream title and category
await client.updateChannel({
    categoryId: '123',
    streamTitle: '🔴 New Stream Title!'
});

// Update just title
await client.updateChannel({
    streamTitle: '🔴 Playing Games!'
});

🎮 Category System

Search Categories

// Search all categories
const allCategories = await client.searchCategories();

// Search specific game
const gaming = await client.searchCategories('Minecraft');

// Get category by ID
const category = await client.getCategory('123');

👥 User Management

Get User Information

// Get single user
const user = await client.getUsers(['123456']);

// Get multiple users
const users = await client.getUsers(['123', '456', '789']);

🚨 Error Handling

try {
    await client.sendChatMessage({
        content: 'Test message'
    });
} catch (error) {
    if (error instanceof UnauthorizedError) {
        console.error('Token is invalid or expired');
    } else if (error instanceof ForbiddenError) {
        console.error('Insufficient permissions');
    } else if (error instanceof RateLimitError) {
        console.error(`Rate limited. Try again in ${error.retryAfter} seconds`);
    } else {
        console.error('Unknown error:', error.message);
    }
}

📝 TypeScript Support

import { 
    KickClient, 
    ChatMessageOptions,
    ChannelUpdateOptions,
    WebhookEventType
} from '@botk4cp3r/kick.js';

// Client with typed options
const client = new KickClient({
    token: string,
    webhookPort: number,
    webhookPath: string,
    webhookBaseUrl: string
});

// Typed message options
const messageOptions: ChatMessageOptions = {
    content: string,
    type: 'bot' | 'user',
    broadcasterUserId?: string
};

// Typed event handlers
client.on('chatMessage', (message: ChatMessage) => {
    console.log(message.content);
});

📚 Examples

Chat Bot Example

const { KickClient } = require('@botk4cp3r/kick.js');

const client = new KickClient({
    token: 'your-api-token',
    webhookPort: 3000,
    webhookPath: '/webhook',
    webhookBaseUrl: 'http://your-domain.com'
});

const commands = {
    '!help': 'Available commands: !help, !ping',
    '!ping': 'Pong! 🏓'
};

async function startBot() {
    try {
        // Start webhook server
        await client.startWebhookServer();
        
        // Subscribe to events
        await client.subscribeToEvents([
            'chat.message.sent',
            'channel.followed',
            'channel.subscription.new',
            'channel.subscription.renewal',
            'channel.subscription.gifts'
        ]);

        console.log('Bot started and subscribed to events!');
    } catch (error) {
        console.error('Failed to start bot:', error);
        process.exit(1);
    }
}

// Chat command handler
client.on('chatMessage', async (message) => {
    const command = message.content.toLowerCase();
    
    if (commands[command]) {
        await client.sendChatMessage({
            content: commands[command],
            type: 'bot'
        });
    }
});

// Event handlers
client.on('channelFollowed', async (data) => {
    await client.sendChatMessage({
        content: `Thanks for following, ${data.follower.username}! 🎉`,
        type: 'bot'
    });
});

client.on('subscriptionNew', async (data) => {
    await client.sendChatMessage({
        content: `Welcome to the team, ${data.subscriber.username}! 🎈`,
        type: 'bot'
    });
});

client.on('subscriptionRenewal', async (data) => {
    await client.sendChatMessage({
        content: `Thanks for resubbing, ${data.subscriber.username}! 💜`,
        type: 'bot'
    });
});

client.on('subscriptionGifts', async (data) => {
    await client.sendChatMessage({
        content: `Thanks ${data.gifter.username} for gifting ${data.giftees.length} subs! 🎁`,
        type: 'bot'
    });
});

startBot().catch(console.error);