@manaobot/kick 1.0.0

package/example/05-users-api/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Example 05: Using Users API
+ *
+ * This template demonstrates how to use the Users API of the ManaoKick library.
+ * The bot will fetch and display user data once authorized.
+ * In the first run, it will print the access and refresh tokens to the console for
+ * you to save in your environment variables file (.env).
+ *
+ * Before running this code, ensure you have the following environment variables set:
+ * - KICK_CLIENT_ID
+ * - KICK_CLIENT_SECRET
+ *
+ * SCOPES: ["user:read"]
+ * Make sure to refresh the tokens and update your environment variables when scopes change.
+ */
+
+import { KickClient } from "../../src/KickClient.ts";
+import type { KickTokenResponse } from "../../types";
+
+// Initialize the KickClient with necessary credentials and scopes
+const kick = new KickClient({
+  clientId: Bun.env.KICK_CLIENT_ID!,
+  clientSecret: Bun.env.KICK_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/callback",
+  scopes: ["user:read"],
+  showLog: false,
+  auth: {
+    initialTokens: Bun.env.KICK_REFRESH_TOKEN
+      ? {
+          access_token: Bun.env.KICK_ACCESS_TOKEN!,
+          refresh_token: Bun.env.KICK_REFRESH_TOKEN!,
+        }
+      : undefined,
+    onTokenUpdate: (tokens: KickTokenResponse) => {
+      if (!Bun.env.KICK_REFRESH_TOKEN) {
+        console.log("\n[!] Copy these into your .env file:\n");
+        console.log(`KICK_ACCESS_TOKEN=${tokens.access_token}`);
+        console.log(`KICK_REFRESH_TOKEN=${tokens.refresh_token}`);
+        console.log(`\n====> Scopes granted: ${tokens.scope}`);
+      }
+
+      Bun.env.KICK_ACCESS_TOKEN = tokens.access_token;
+      Bun.env.KICK_REFRESH_TOKEN = tokens.refresh_token;
+    },
+  },
+});
+
+// If no refresh token is found, initiate the authorization flow
+if (!Bun.env.KICK_REFRESH_TOKEN) {
+  console.log(`Authorize the application by visiting:\n${kick.getAuthURL()}`);
+  kick.auth.createCallbackServer({ port: 3000 });
+  await kick.auth.waitForAuthorization();
+}
+
+// Confirm successful authorization
+console.log("\n[✔] Application authorized successfully!");
+
+const { data } = await kick.api.users.get();
+console.log("\n[✔] User data fetched successfully!");
+console.log(data);

package/example/06-channels-api/.env.example

@@ -0,0 +1,7 @@
+KICK_CLIENT_ID=[YOUR_CLIENT_ID_HERE]
+KICK_CLIENT_SECRET=[YOUR_CLIENT_SECRET_HERE]
+
+# These two lines below are the lines you need to fill in after getting tokens
+# After running the ./index.ts file
+KICK_ACCESS_TOKEN=
+KICK_REFRESH_TOKEN=

package/example/06-channels-api/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Example 06: Using Channels API
+ *
+ * This template demonstrates how to use the Channels API with the ManaoKick library.
+ * The bot will fetch and display current channel data once authorized.
+ * In the first run, it will print the access and refresh tokens to the console for
+ * you to save in your environment variables file (.env).
+ *
+ * Before running this code, ensure you have the following environment variables set:
+ * - KICK_CLIENT_ID
+ * - KICK_CLIENT_SECRET
+ *
+ * SCOPES: ["channel:read"]
+ * Make sure to refresh the tokens and update your environment variables when scopes change.
+ */
+
+import { KickClient } from "../../src/KickClient.ts";
+import type { KickTokenResponse } from "../../types";
+
+// Initialize the KickClient
+const kick = new KickClient({
+  clientId: Bun.env.KICK_CLIENT_ID!,
+  clientSecret: Bun.env.KICK_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/callback",
+  scopes: ["channel:read"],
+  showLog: false,
+  auth: {
+    initialTokens: Bun.env.KICK_REFRESH_TOKEN
+      ? {
+          access_token: Bun.env.KICK_ACCESS_TOKEN!,
+          refresh_token: Bun.env.KICK_REFRESH_TOKEN!,
+        }
+      : undefined,
+    onTokenUpdate: (tokens: KickTokenResponse) => {
+      if (!Bun.env.KICK_REFRESH_TOKEN) {
+        console.log("\n[!] Copy these into your .env file:\n");
+        console.log(`KICK_ACCESS_TOKEN=${tokens.access_token}`);
+        console.log(`KICK_REFRESH_TOKEN=${tokens.refresh_token}`);
+        console.log(`\n====> Scopes granted: ${tokens.scope}`);
+      }
+
+      Bun.env.KICK_ACCESS_TOKEN = tokens.access_token;
+      Bun.env.KICK_REFRESH_TOKEN = tokens.refresh_token;
+    },
+  },
+});
+
+// Authorization flow
+if (!Bun.env.KICK_REFRESH_TOKEN) {
+  console.log(`Authorize the application by visiting:\n${kick.getAuthURL()}`);
+  kick.auth.createCallbackServer({ port: 3000 });
+  await kick.auth.waitForAuthorization();
+}
+
+// Confirm successful authorization
+console.log("\n[✔] Application authorized successfully!");
+
+let { data } = await kick.api.channels.get();
+console.log("\n[✔] Channels fetched successfully!");
+console.log(data);

package/example/07-channel-rewards-api/.env.example

@@ -0,0 +1,7 @@
+KICK_CLIENT_ID=[YOUR_CLIENT_ID_HERE]
+KICK_CLIENT_SECRET=[YOUR_CLIENT_SECRET_HERE]
+
+# These two lines below are the lines you need to fill in after getting tokens
+# After running the ./index.ts file
+KICK_ACCESS_TOKEN=
+KICK_REFRESH_TOKEN=

package/example/07-channel-rewards-api/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Example 07: Using ChannelRewards API
+ *
+ * This template demonstrates how to use the ChannelRewards API with the ManaoKick library.
+ * The bot will fetch and display current channel rewards data once authorized.
+ * In the first run, it will print the access and refresh tokens to the console for
+ * you to save in your environment variables file (.env).
+ *
+ * Before running this code, ensure you have the following environment variables set:
+ * - KICK_CLIENT_ID
+ * - KICK_CLIENT_SECRET
+ *
+ * SCOPES: ["channel:rewards:write"]
+ * Make sure to refresh the tokens and update your environment variables when scopes change.
+ */
+
+import { KickClient } from "../../src/KickClient.ts";
+import type { KickTokenResponse } from "../../types";
+
+// Initialize the KickClient
+const kick = new KickClient({
+  clientId: Bun.env.KICK_CLIENT_ID!,
+  clientSecret: Bun.env.KICK_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/callback",
+  scopes: ["channel:rewards:write"],
+  showLog: false,
+  auth: {
+    initialTokens: Bun.env.KICK_REFRESH_TOKEN
+      ? {
+          access_token: Bun.env.KICK_ACCESS_TOKEN!,
+          refresh_token: Bun.env.KICK_REFRESH_TOKEN!,
+        }
+      : undefined,
+    onTokenUpdate: (tokens: KickTokenResponse) => {
+      if (!Bun.env.KICK_REFRESH_TOKEN) {
+        console.log("\n[!] Copy these into your .env file:\n");
+        console.log(`KICK_ACCESS_TOKEN=${tokens.access_token}`);
+        console.log(`KICK_REFRESH_TOKEN=${tokens.refresh_token}`);
+        console.log(`\n====> Scopes granted: ${tokens.scope}`);
+      }
+
+      Bun.env.KICK_ACCESS_TOKEN = tokens.access_token;
+      Bun.env.KICK_REFRESH_TOKEN = tokens.refresh_token;
+    },
+  },
+});
+
+// Authorization flow
+if (!Bun.env.KICK_REFRESH_TOKEN) {
+  console.log(`Authorize the application by visiting:\n${kick.getAuthURL()}`);
+  kick.auth.createCallbackServer({ port: 3000 });
+  await kick.auth.waitForAuthorization();
+}
+
+// Confirm successful authorization
+console.log("\n[✔] Application authorized successfully!");
+
+let { data } = await kick.api.rewards.get();
+console.log("\n[✔] Rewards fetched successfully!");
+console.log(data);

package/example/08-basic-chat-bot/.env.example

@@ -0,0 +1,7 @@
+KICK_CLIENT_ID=[YOUR_CLIENT_ID_HERE]
+KICK_CLIENT_SECRET=[YOUR_CLIENT_SECRET_HERE]
+
+# These two lines below are the lines you need to fill in after getting tokens
+# After running the ./index.ts file
+KICK_ACCESS_TOKEN=
+KICK_REFRESH_TOKEN=

package/example/08-basic-chat-bot/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Example 08: Basic Chat Bot Template
+ *
+ * This template will help you set up a basic chat bot using the ManaoKick library.
+ * The bot will listen for incoming chat messages and can be extended to respond or moderate.
+ * In the first run, it will print the access and refresh tokens to the console for
+ * you to save in your environment variables file (.env).
+ *
+ * Before running this code, ensure you have the following environment variables set:
+ * - KICK_CLIENT_ID
+ * - KICK_CLIENT_SECRET
+ *
+ *  SCOPES ["chat:write", "events:subscribe", "moderation:ban", "channel:read"]
+ *  Make sure to refresh the tokens and update your environment variables when scopes change.
+ */
+
+import { KickClient } from "../../src/KickClient.ts";
+import type { ChatMessageEvent, KickTokenResponse } from "../../types";
+
+const PREFIX = "!";
+
+// Initialize the KickClient
+const kick = new KickClient({
+  clientId: Bun.env.KICK_CLIENT_ID!,
+  clientSecret: Bun.env.KICK_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/callback",
+  scopes: ["chat:write", "events:subscribe", "moderation:ban", "channel:read"],
+  showLog: false,
+  auth: {
+    initialTokens: Bun.env.KICK_REFRESH_TOKEN
+      ? {
+          access_token: Bun.env.KICK_ACCESS_TOKEN!,
+          refresh_token: Bun.env.KICK_REFRESH_TOKEN!,
+        }
+      : undefined,
+    onTokenUpdate: (tokens: KickTokenResponse) => {
+      if (!Bun.env.KICK_REFRESH_TOKEN) {
+        console.log("\n[!] Copy these into your .env file:\n");
+        console.log(`KICK_ACCESS_TOKEN=${tokens.access_token}`);
+        console.log(`KICK_REFRESH_TOKEN=${tokens.refresh_token}`);
+        console.log(`\n====> Scopes granted: ${tokens.scope}`);
+      }
+
+      Bun.env.KICK_ACCESS_TOKEN = tokens.access_token;
+      Bun.env.KICK_REFRESH_TOKEN = tokens.refresh_token;
+    },
+  },
+});
+
+// Authorization flow
+if (!Bun.env.KICK_REFRESH_TOKEN) {
+  console.log(`Authorize the application by visiting:\n${kick.getAuthURL()}`);
+  kick.auth.createCallbackServer({ port: 3000 });
+  await kick.auth.waitForAuthorization();
+}
+
+// Confirm successful authorization
+console.log("\n[✔] Application authorized successfully!");
+
+// Handle incoming chat message events
+kick.webhooks.on("chat.message.sent", async (event: ChatMessageEvent) => {
+  const message = event.content;
+  if (message[0] !== PREFIX) return; // Ignore messages without the prefix
+
+  const args = message.slice(PREFIX.length).trim().split(/ +/);
+  const command = args.shift()!.toLowerCase();
+
+  switch (command) {
+    case "ping":
+      await kick.chat.send({ content: "pong 🏓" });
+      break;
+    case "love":
+      const loveTarget = args.join(" ") || event.sender.username;
+      const lovePercentage = Math.floor(Math.random() * 101);
+      await kick.chat.send({
+        content: `${event.sender.username} ❤️ ${loveTarget}: ${lovePercentage}%!`,
+      });
+      break;
+    default:
+      return;
+  }
+});
+
+// Set up ngrok to expose the webhook endpoint
+const { url, close } = await kick.webhooks.ngrok({
+  port: 5000, // Use the same port as the webhook server
+  path: "/kick/webhook",
+  domain: "topical-goshawk-leading.ngrok-free.app", // <==== Replace with YOUR OWN ngrok domain!
+  authtoken: Bun.env.NGROK_AUTHTOKEN,
+});
+
+console.log(`[✔] ngrok tunnel established at: ${url}`);
+
+// Create a webhook server to listen for incoming events
+kick.webhooks.createServer({ port: 5000, path: "/kick/webhook" }); // Use port that ngrok will forward to
+
+// Subscribe to webhooks once authorized
+kick.auth.onAuthorized(async () => {
+  await kick.webhooks.subscribe({
+    events: [{ name: "chat.message.sent" }],
+  });
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@manaobot/kick",
+  "version": "1.0.0",
+  "description": "Minimal Typescript library for managing Kick.com bot",
+  "main": "src/KickClient.ts",
+  "private": false,
+  "author": "Tinnaphat Somsang <tinvv@outlook.co.th>",
+  "scripts": {
+    "format": "biome format --write .",
+    "lint": "biome lint"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.14",
+    "@ngrok/ngrok": "^1.7.0",
+    "@types/bun": "^1.3.8"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "consola": "^3.4.2"
+  }
+}

package/qodana.yaml

@@ -0,0 +1,31 @@
+#-------------------------------------------------------------------------------#
+#               Qodana analysis is configured by qodana.yaml file               #
+#             https://www.jetbrains.com/help/qodana/qodana-yaml.html            #
+#-------------------------------------------------------------------------------#
+version: "1.0"
+
+#Specify inspection profile for code analysis
+profile:
+  name: qodana.starter
+
+#Enable inspections
+#include:
+#  - name: <SomeEnabledInspectionId>
+
+#Disable inspections
+#exclude:
+#  - name: <SomeDisabledInspectionId>
+#    paths:
+#      - <path/where/not/run/inspection>
+
+#Execute shell command before Qodana execution (Applied in CI/CD pipeline)
+#bootstrap: sh ./prepare-qodana.sh
+
+#Install IDE plugins before Qodana execution (Applied in CI/CD pipeline)
+#plugins:
+#  - id: <plugin.id> #(plugin id can be found at https://plugins.jetbrains.com)
+
+#Specify Qodana linter for analysis (Applied in CI/CD pipeline)
+linter: jetbrains/qodana-js:2025.1
+exclude:
+  - name: ES6MissingAwait

package/src/KickClient.ts

@@ -0,0 +1,172 @@
+import { RestClient } from "./rest/RestClient";
+import { createPkce } from "./auth/PKCE.ts";
+import * as OAuth from "./auth/OAuth.ts";
+import { ChatClient } from "./chat/ChatClient.ts";
+import type { KickClientOptions, KickTokenResponse } from "../types";
+import { TokenManager } from "./auth/TokenManager.ts";
+import { WebhookRouter } from "./webhooks/WebhookRouter.ts";
+import { AuthManager } from "./auth/AuthManager.ts";
+import { callbackServer } from "./auth/CallbackServer.ts";
+import { silent } from "./Logger.ts";
+import { CategoriesAPI } from "./api/CategoriesAPI.ts";
+import { UsersAPI } from "./api/UsersAPI.ts";
+import { ChannelsAPI } from "./api/ChannelsAPI.ts";
+import { ChannelRewardsAPI } from "./api/ChannelRewardsAPI.ts";
+import { LivestreamsAPI } from "./api/LivestreamsAPI.ts";
+import { ModerationAPI } from "./api/ModerationAPI.ts";
+import { KicksAPI } from "./api/KicksAPI.ts";
+
+/**
+ * The primary entry point for interacting with the Kick API.
+ * @example
+ * const kick = new KickClient({
+ *   clientId: Bun.env.KICK_CLIENT_ID!,
+ *   clientSecret: Bun.env.KICK_CLIENT_SECRET!,
+ *   redirectUri: "http://localhost:3000/callback",
+ *   scopes: ["chat:write", "events:subscribe"],
+ *   showLog: false,
+ *   auth: {
+ *     initialTokens: {
+ *       access_token: Bun.env.KICK_ACCESS_TOKEN!,
+ *       refresh_token: Bun.env.KICK_REFRESH_TOKEN!,
+ *     },
+ *     onTokenUpdate: (tokens: KickTokenResponse) => {*
+ *       Bun.env.KICK_ACCESS_TOKEN = tokens.access_token;
+ *       Bun.env.KICK_REFRESH_TOKEN = tokens.refresh_token;
+ *     },
+ *   },
+ * }); */
+export class KickClient {
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private readonly redirectUri: string;
+  private readonly scopes: string[];
+  private readonly state: string;
+  private pkceVerifier?: string;
+  private readonly tokenManager: TokenManager;
+  private rest = new RestClient();
+
+  public chat = new ChatClient(this.rest);
+  public webhooks: WebhookRouter;
+  public auth: AuthManager;
+  public readonly api: {
+    categories: CategoriesAPI;
+    users: UsersAPI;
+    channels: ChannelsAPI;
+    rewards: ChannelRewardsAPI;
+    livestreams: LivestreamsAPI;
+    moderation: ModerationAPI;
+    kicks: KicksAPI;
+  };
+
+  constructor(
+    options: KickClientOptions & { webhookSecret?: string; showLog?: boolean },
+  ) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.redirectUri = options.redirectUri;
+    this.scopes = options.scopes;
+    this.state =
+      options.state ??
+      Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("hex");
+
+    this.webhooks = new WebhookRouter(options.clientSecret, this.rest);
+
+    this.auth = new AuthManager(this);
+
+    this.tokenManager = new TokenManager(
+      (refreshToken) =>
+        OAuth.refreshToken(refreshToken, this.clientId, this.clientSecret),
+      options.auth?.onTokenUpdate,
+    );
+
+    this.api = {
+      categories: new CategoriesAPI(this.rest),
+      users: new UsersAPI(this.rest),
+      channels: new ChannelsAPI(this.rest),
+      rewards: new ChannelRewardsAPI(this.rest),
+      livestreams: new LivestreamsAPI(this.rest),
+      moderation: new ModerationAPI(this.rest),
+      kicks: new KicksAPI(this.rest),
+    };
+
+    if (options.auth?.initialTokens) {
+      this.tokenManager.setTokens(options.auth.initialTokens);
+      this.rest.setTokenManager(this.tokenManager);
+    }
+
+    if (!options.showLog) {
+      silent();
+    }
+  }
+
+  /**
+   * Generates the OAuth authorization URL and initializes PKCE verification.
+   * @returns The Kick authorization URL
+   */
+  getAuthURL(): string {
+    const { verifier, challenge } = createPkce();
+    this.pkceVerifier = verifier;
+
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      scope: this.scopes.join(" "),
+      state: this.state,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+    });
+
+    return `https://id.kick.com/oauth/authorize?${params}`;
+  }
+
+  /**
+   * Returns the current anti-forgery state string.
+   */
+  getState(): string {
+    return this.state;
+  }
+
+  /**
+   * Exchanges an authorization code for access and refresh tokens.
+   * @param code The code received from the OAuth callback
+   * @returns Kick token response
+   */
+  async exchangeCode(code: string): Promise<KickTokenResponse> {
+    if (!this.pkceVerifier) {
+      throw new Error("PKCE verifier missing");
+    }
+
+    const token = await OAuth.exchangeCode(
+      code,
+      this.pkceVerifier,
+      this.clientId,
+      this.clientSecret,
+      this.redirectUri,
+    );
+
+    this.tokenManager.setTokens(token);
+    this.rest.setTokenManager(this.tokenManager);
+
+    return token;
+  }
+
+  /**
+   * Manually refreshes the access token using a refresh token.
+   * @param refreshToken The refresh token to use
+   * @returns New Kick token response
+   */
+  async refreshToken(refreshToken: string): Promise<KickTokenResponse> {
+    return OAuth.refreshToken(refreshToken, this.clientId, this.clientSecret);
+  }
+
+  /**
+   * Starts a local server to handle the OAuth redirect and token exchange.
+   * @param options Server configuration options
+   * @returns The running Bun server instance
+   */
+  createAuthCallbackServer(options?: { port?: number; path?: string }) {
+    return callbackServer(this, options);
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,25 @@
+let createConsola: any;
+export let logger: any;
+
+export function silent() {
+  if (createConsola) {
+    logger = createConsola({ level: -1 });
+  }
+}
+
+try {
+  createConsola = (await import("consola")).createConsola;
+
+  logger = createConsola({
+    level: process.env.LOG_LEVEL
+      ? parseInt(process.env.LOG_LEVEL, 10)
+      : undefined,
+    defaults: {
+      tag: "@manao/kick",
+    },
+    fancy: true,
+  });
+} catch {
+  createConsola = null;
+  logger = console;
+}

package/src/api/CategoriesAPI.ts

@@ -0,0 +1,45 @@
+import type { RestClient } from "../rest/RestClient.ts";
+import type { GetCategoriesParams } from "../../types/api";
+
+/**
+ * CategoriesAPI provides access to Kick Category APIs.
+ *
+ * @example
+ * const categories = await kick.api.categories.get({ limit: 10 });
+ * console.log(categories.data);
+ */
+export class CategoriesAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Retrieve categories based on filters.
+   * * Allows filtering by cursor, limit, names, tags, or specific IDs.
+   *
+   * @param params Query parameters
+   * @returns Kick category data
+   *
+   * @example
+   * // Get categories with a limit
+   * const categories = await kick.api.categories.get({ limit: 5 });
+   *
+   * @example
+   * // Get specific categories by name
+   * const categories = await kick.api.categories.get({ name: ["Just Chatting", "Slots"] });
+   */
+  async get(params: GetCategoriesParams = {}): Promise<unknown> {
+    const search = new URLSearchParams();
+
+    if (params.cursor) search.set("cursor", params.cursor.toString());
+    if (params.limit) search.set("limit", params.limit.toString());
+    if (params.name) params.name.forEach((name) => search.append("name", name));
+    if (params.tags) params.tags.forEach((tag) => search.append("tags", tag));
+    if (params.id)
+      params.id.forEach((id) => search.append("id", id.toString()));
+
+    const query = search.toString();
+
+    return this.rest.fetch(`/public/v2/categories${query ? `?${query}` : ""}`, {
+      method: "GET",
+    });
+  }
+}