chore: initial relase

Author: GGESrv

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+package-lock.json
+.env
+.npm-cache/
+kick-tokens.json
+multi-streamers.json
+rotation-tokens.json
+*.tgz
+*.log

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2025-11-02
+
+- Initial release rebranded as **kapi-kit**
+- Complete coverage of Kick Public API endpoints with `KickApiClient`
+- OAuth helpers for client credentials, authorization code with PKCE, refresh, and revoke flows
+- Extensive example suite including single-channel and multi-stream bots
+- Error wrapper (`KickApiError`) with request id, status, and parsed response payload
+- Shared webhook utilities with signature + shared-secret validation

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kick Public API SDK contributors
+
+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.

README.md

@@ -0,0 +1,203 @@
+# kapi-kit · Kick Public API toolkit for Node.js 22 🚀
+
+[![npm version](https://img.shields.io/npm/v/kapi-kit.svg?label=npm)](https://www.npmjs.com/package/kapi-kit)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.0-6cc24a)](#requirements)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![coverage](https://img.shields.io/badge/endpoints-100%25-brightgreen.svg)](docs/coverage.md)
+
+`kapi-kit` is a batteries-included SDK for the [Kick Public API](https://github.com/KickEngineering/KickDevDocs). It is designed for modern Node.js runtimes (22+) and ships with everything you need to build bots, dashboards, or broadcaster tooling:
+
+- 🔐 **OAuth 2.1 helpers** with PKCE utilities, refresh rotation, and token revocation
+- 💬 **Chat client** ready for bot *and* broadcaster messages, including replies
+- 📺 **Livestream, channel, moderation, kicks, and users** endpoints behind a unified client
+- 🪝 **Webhook receivers** complete with signature verification and shared-secret support
+- 🧪 **Drop-in examples** for every endpoint, from quick scripts to production-ready bots
+- 🧰 **Multi-tenant bot framework** so multiple streamers can adopt your bot with a single deployment
+
+> **Status** – The codebase mirrors Kick’s public documentation as of 2025-10-27. Keep an eye on the [Kick Engineering announcements](https://github.com/KickEngineering/KickDevDocs) for new endpoints; extending `kapi-kit` is intentionally straightforward.
+
+---
+
+## Table of contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Quick start](#quick-start)
+4. [Authentication flows](#authentication-flows)
+5. [API tour](#api-tour)
+6. [Example gallery](#example-gallery)
+7. [Multi-stream bot architecture](#multi-stream-bot-architecture)
+8. [Endpoint coverage](#endpoint-coverage)
+9. [Roadmap](#roadmap)
+10. [Contributing](#contributing)
+11. [License](#license)
+
+---
+
+## Requirements
+
+- **Node.js 22.0.0 or newer** (built-in `fetch` is used throughout)
+- **npm** or any compatible package manager
+- A registered [Kick developer application](https://kick.com/apps) with the scopes you plan to use
+
+Check your environment quickly:
+
+```bash
+npm run lint
+```
+
+The command verifies Node.js version and `fetch` availability.
+
+---
+
+## Installation
+
+```bash
+npm install kapi-kit
+```
+
+or with pnpm:
+
+```bash
+pnpm add kapi-kit
+```
+
+`kapi-kit` ships as native ESM – just use standard `import` syntax.
+
+---
+
+## Quick start
+
+```js
+import { KickApiClient } from 'kapi-kit';
+
+const client = new KickApiClient({
+  accessToken: process.env.KICK_ACCESS_TOKEN, // must include chat:write to send messages
+});
+
+await client.sendChatMessage({
+  type: 'bot',
+  content: 'Hello Kick! 👋',
+});
+```
+
+> Need scopes? Head to **Kick Dev Portal → Your App → Scopes** and grant `chat:write`.
+
+---
+
+## Authentication flows
+
+| Scenario | Helper | Notes |
+| --- | --- | --- |
+| App-to-app calls (Client Credentials) | `KickAuthClient#getAppAccessToken` | Use when no broadcaster auth is required. |
+| Interactive login (Authorization Code + PKCE) | `createPkcePair`, `createAuthorizationUrl`, `KickAuthClient#exchangeCodeForToken` | Guides end-users through the consent screen. |
+| Refreshing access tokens | `KickAuthClient#refreshAccessToken` | Returns a *new* access and refresh token. Persist it! |
+| Revoking tokens | `KickAuthClient#revokeToken` | Works with either access or refresh tokens. |
+| Token introspection | `KickApiClient#introspectToken` | Confirms validity, scope, and expiry. |
+
+🚦 **First time implementing OAuth?** Run `node examples/token-rotation.js`. It walks through the PKCE flow, stores the refresh token, and keeps rotating it so it never expires.
+
+---
+
+## API tour
+
+`kapi-kit` exposes a single high-level client plus targeted helpers:
+
+```js
+import {
+  KickApiClient,
+  KickChatClient,
+  KickAuthClient,
+  createAuthorizationUrl,
+  createPkcePair,
+  KickApiError,
+} from 'kapi-kit';
+```
+
+| Area | Methods | Example |
+| --- | --- | --- |
+| **Chat** | `client.sendChatMessage`, `chat.sendMessage` | `examples/chat-send.js` |
+| **Channels** | `client.getChannels`, `client.updateChannelMetadata` | `examples/channels-get.js`, `examples/channels-update.js` |
+| **Livestreams** | `client.getLivestreams`, `client.getLivestreamStats` | `examples/livestreams-list.js` |
+| **Events** | `client.list/create/deleteEventSubscriptions` | `examples/events.js` |
+| **Moderation** | `client.banUser`, `client.unbanUser` | `examples/moderation.js` |
+| **Kicks** | `client.getKicksLeaderboard` | `examples/kicks-leaderboard.js` |
+| **Users** | `client.getUsers` | `examples/users.js` |
+| **Public key** | `client.getPublicKey` | `examples/public-key.js` |
+
+Every method accepts an optional `AbortSignal` and raises a `KickApiError` with `status`, `statusText`, `body`, and `requestId` fields on failure.
+
+---
+
+## Example gallery
+
+| Script | What it teaches | Typical use case |
+| --- | --- | --- |
+| `chat-send.js` | Send bot/broadcaster messages, replies, emotes | Simple bot posting updates |
+| `token-rotation.js` | Persistent refresh rotation + sample call | Long-running services |
+| `full-bot.js` | Single-channel bot with webhooks, `!ping`, `!title`, keep-alives | Bots for a single broadcaster |
+| `multi-stream-bot.js` | Multi-tenant bot with onboarding endpoint & webhook verification | SaaS bot adopted by many streamers |
+| `events.js` | Subscribe/unsubscribe/list webhook events | Dashboards & analytics |
+| `oauth-*` scripts | Client credentials, PKCE, refresh, revoke | Bootstrapping authentication flows |
+
+All scripts can be launched directly:
+
+```bash
+node examples/full-bot.js
+```
+
+Each script documents the environment variables it reads—search for `process.env` inside the file for a cheat-sheet.
+
+---
+
+## Multi-stream bot architecture
+
+`examples/multi-stream-bot.js` contains everything you need to run a “click to add bot” experience:
+
+1. **User clicks “Add Bot”** on your website → Kick redirects back with `code` + `code_verifier`.
+2. Your frontend POSTs `{ code, code_verifier }` (and the optional `redirect_uri`) to `POST /kick/streamers/add`, sending `Kick-App-Secret` in the header.
+3. The server exchanges the code for tokens, stores the refresh token in `multi-streamers.json`, subscribes to `chat.message.sent`, and schedules token refreshes + keep-alive messages for that broadcaster.
+4. Kick delivers chat events to `POST /kick/webhook`. The bot validates the signature *and* shared secret, then responds to commands:
+   - `!ping` → `!pong`
+   - `!title The New Title` updates the stream title
+   - Keep-alive messages post every 5 minutes as both bot and broadcaster.
+
+Token refreshes are automatically persisted. If a broadcaster revokes access, refresh attempts will start failing—handle that by removing them from the store or prompting them to re-authorize.
+
+---
+
+## Endpoint coverage
+
+See [docs/coverage.md](docs/coverage.md) for the full matrix mapping each Kick endpoint to SDK methods and runnable examples. It mirrors the official [Kick Dev Docs](https://github.com/KickEngineering/KickDevDocs).
+
+---
+
+## Roadmap
+
+- [ ] Streaming consumer for real-time chat without webhooks
+- [ ] Lightweight HTTP client plug-in (Axios/undici swap)
+- [ ] TypeScript type declarations (today we rely on JSDoc)
+- [ ] Optional Redis-backed token stores for multi-stream bots
+
+Got ideas or find a gap in Kick’s evolving API? Open an issue or PR—feedback is welcome!
+
+---
+
+## Contributing
+
+1. Fork the repository.
+2. Install dependencies and run the lint check:
+   ```bash
+   npm install
+   npm run lint
+   ```
+3. Add tests or examples if your change affects behaviour.
+4. Open a pull request against `main` describing the change and relevant Kick docs.
+
+---
+
+## License
+
+MIT © [Wydoyolo](https://github.com/Wydoyolo)
+
+Kick API documentation is owned by Kick. See the official docs for the latest platform terms.

docs/coverage.md

@@ -0,0 +1,27 @@
+# Kick Public API Coverage
+
+The SDK implements every endpoint listed in the [Kick Dev Docs](https://github.com/KickEngineering/KickDevDocs) public documentation. Use the table below to trace an endpoint in the official docs to the matching helper and runnable example in `kapi-kit`.
+
+| Kick Endpoint | SDK Method | Notes | Example Script |
+| --- | --- | --- | --- |
+| `POST /oauth/token` | `KickAuthClient#getAppAccessToken`, `#exchangeCodeForToken`, `#refreshAccessToken` | Client credentials, authorization code, and refresh flows | `examples/oauth-client-credentials.js`, `examples/oauth-authorization-code.js`, `examples/oauth-refresh.js` |
+| `POST /oauth/revoke` | `KickAuthClient#revokeToken` | Uses query-string token hint as documented | `examples/oauth-revoke.js` |
+| `POST /oauth/authorize` | `createAuthorizationUrl`, `createPkcePair` | Helper utilities for initiating PKCE authorization flows | `examples/token-rotation.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `POST /chat` | `KickApiClient#sendChatMessage`, `KickChatClient#sendMessage` | Supports bot & user message types, optional replies | `examples/chat-send.js`, `examples/chat-client.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `GET /categories` | `KickApiClient#searchCategories` | Handles pagination (`page`) | `examples/categories.js` |
+| `GET /categories/:category_id` | `KickApiClient#getCategoryById` | Returns full category payload | `examples/categories.js` |
+| `GET /channels` | `KickApiClient#getChannels` | Supports filtering by broadcaster IDs or slugs (mutually exclusive) | `examples/channels-get.js` |
+| `PATCH /channels` | `KickApiClient#updateChannelMetadata` | Updates category, title, and custom tags | `examples/channels-update.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `GET /events/subscriptions` | `KickApiClient#listEventSubscriptions` | Optional broadcaster filtering | `examples/events.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `POST /events/subscriptions` | `KickApiClient#createEventSubscriptions` | Accepts webhook subscriptions with event list validation | `examples/events.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `DELETE /events/subscriptions` | `KickApiClient#deleteEventSubscriptions` | Accepts multiple subscription IDs | `examples/events.js`, `examples/full-bot.js`, `examples/multi-stream-bot.js` |
+| `GET /livestreams` | `KickApiClient#getLivestreams` | Supports language, category, sort, limit, broadcaster filters | `examples/livestreams-list.js` |
+| `GET /livestreams/stats` | `KickApiClient#getLivestreamStats` | Returns livestream count | `examples/livestreams-stats.js` |
+| `GET /kicks/leaderboard` | `KickApiClient#getKicksLeaderboard` | Optional `top` parameter | `examples/kicks-leaderboard.js` |
+| `POST /moderation/bans` | `KickApiClient#banUser` | Supports optional timeout duration & reason | `examples/moderation.js` |
+| `DELETE /moderation/bans` | `KickApiClient#unbanUser` | Reverses bans/timeouts | `examples/moderation.js` |
+| `GET /public-key` | `KickApiClient#getPublicKey` | Exposes verification public key | `examples/public-key.js` |
+| `POST /token/introspect` | `KickApiClient#introspectToken` | Mirrors RFC 7662 output | `examples/token-introspect.js` |
+| `GET /users` | `KickApiClient#getUsers` | Fetches authorised user or list of IDs | `examples/users.js` |
+
+Every example is self-contained and can be executed directly after replacing placeholder credentials.

examples/categories.js

@@ -0,0 +1,11 @@
+import { KickApiClient } from 'kapi-kit';
+
+const client = new KickApiClient({ accessToken: 'YOUR_ACCESS_TOKEN' });
+
+const categories = await client.searchCategories({ query: 'music' });
+console.log('Search results:', categories);
+
+if (Array.isArray(categories) && categories.length > 0) {
+  const category = await client.getCategoryById(categories[0].id);
+  console.log('Category details:', category);
+}

examples/channels-get.js

@@ -0,0 +1,9 @@
+import { KickApiClient } from 'kapi-kit';
+
+const client = new KickApiClient({ accessToken: 'YOUR_ACCESS_TOKEN' });
+
+const byBroadcasterId = await client.getChannels({ broadcasterUserIds: [123456] });
+console.log('Channels by broadcaster id:', byBroadcasterId);
+
+const bySlug = await client.getChannels({ slugs: ['example-channel'] });
+console.log('Channels by slug:', bySlug);

examples/channels-update.js

@@ -0,0 +1,11 @@
+import { KickApiClient } from 'kapi-kit';
+
+const client = new KickApiClient({ accessToken: 'YOUR_ACCESS_TOKEN' });
+
+await client.updateChannelMetadata({
+  streamTitle: 'A better title for my stream',
+  categoryId: 123, // Replace with a category id from /categories.
+  customTags: ['speedrun', 'giveaway'],
+});
+
+console.log('Channel metadata update accepted.');

examples/chat-client.js

@@ -0,0 +1,11 @@
+import { KickChatClient } from 'kapi-kit';
+
+// Supply a chat:write token. Messages default to the authenticated channel when `type` is `bot`.
+const chat = new KickChatClient({ accessToken: 'YOUR_ACCESS_TOKEN' });
+
+const message = await chat.sendMessage({
+  content: 'Hello from KickChatClient!',
+  type: 'bot',
+});
+
+console.log(message);

examples/chat-send.js

@@ -0,0 +1,24 @@
+import { KickApiClient } from 'kapi-kit';
+
+// Replace with an access token that includes the `chat:write` scope.
+const client = new KickApiClient({
+  accessToken: 'YOUR_ACCESS_TOKEN',
+});
+
+// Send as the authenticated bot. Kick routes bot messages to the broadcaster
+// associated with the token.
+const botMessage = await client.sendChatMessage({
+  type: 'bot',
+  content: 'Message will be sent to the authenticated channel.',
+});
+
+console.log('Bot message:', botMessage);
+
+// Send as a broadcaster user by providing the broadcaster user id.
+const userMessage = await client.sendChatMessage({
+  type: 'user',
+  content: 'Message will be sent to the specified broadcaster channel.',
+  broadcasterUserId: 123456, // Replace with a real broadcaster user id.
+});
+
+console.log('User message:', userMessage);