@lagent_titi/kick.js-ts 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kacper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,501 @@
+# Kick.com API Client
+
+[![NPM Version](https://img.shields.io/npm/v/@botk4cp3r/kick.js)](https://www.npmjs.com/package/@botk4cp3r/kick.js)
+[![License](https://img.shields.io/npm/l/@botk4cp3r/kick.js)](https://github.com/BOT-K4CP3R/kick.api/blob/main/LICENSE)
+
+## 📋 Table of Contents
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Chat System](#-chat-system)
+- [Webhook Events](#-webhook-events)
+- [Channel Management](#-channel-management)
+- [Category System](#-category-system)
+- [User Management](#-user-management)
+- [Error Handling](#-error-handling)
+- [TypeScript Support](#-typescript-support)
+- [Examples](#-examples)
+
+## 📥 Installation
+
+```bash
+npm install @lagent_titi/kick.api-ts
+```
+
+## 🚀 Quick Start
+
+```javascript
+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
+```javascript
+// 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
+```javascript
+// 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
+```javascript
+const client = new KickClient({
+    token: 'your-api-token',
+    webhookPort: 3000,
+    webhookPath: '/webhook',
+    webhookBaseUrl: 'http://your-domain.com'
+});
+
+await client.startWebhookServer();
+```
+
+### Subscribe to Events
+```javascript
+// 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
+```javascript
+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
+```javascript
+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
+
+```javascript
+// 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
+
+```javascript
+// Validate incoming webhook
+const isValid = await client.validateWebhook(headers, rawBody);
+if (isValid) {
+    console.log('Valid webhook event!');
+}
+```
+
+### Full Subscription Example
+
+```javascript
+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
+```javascript
+{
+    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
+```javascript
+{
+    eventType: 'channel.followed',
+    payload: {
+        broadcaster: {
+            id: '123',
+            username: 'broadcaster'
+        },
+        follower: {
+            id: '456',
+            username: 'follower'
+        }
+    }
+}
+```
+
+#### Subscription Event
+```javascript
+{
+    eventType: 'subscription.new',
+    payload: {
+        broadcaster: {
+            id: '123',
+            username: 'broadcaster'
+        },
+        subscriber: {
+            id: '456',
+            username: 'subscriber'
+        },
+        tier: 1,
+        months: 1
+    }
+}
+```
+
+## 📺 Channel Management
+
+### Get Channel Info
+```javascript
+// Get single channel
+const channel = await client.getChannels(['123456']);
+
+// Get multiple channels
+const channels = await client.getChannels(['123', '456', '789']);
+```
+
+### Update Channel
+```javascript
+// 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
+```javascript
+// 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
+```javascript
+// Get single user
+const user = await client.getUsers(['123456']);
+
+// Get multiple users
+const users = await client.getUsers(['123', '456', '789']);
+```
+
+## 🚨 Error Handling
+
+```javascript
+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
+
+```typescript
+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
+```javascript
+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);
+```