@manaobot/kick 1.0.0

package/src/chat/ChatClient.ts

@@ -0,0 +1,48 @@
+import type { RestClient } from "../rest/RestClient.ts";
+import type { ChatMessage } from "../../types";
+
+/**
+ * ChatClient provides access to Kick Chat APIs.
+ * @example
+ * await kick.chat.send({
+ *   content: "Hello world!"
+ * });
+ */
+export class ChatClient {
+  constructor(private rest: RestClient) {}
+
+  /**
+   * Send a message to the chat.
+   * * Requires scope:
+   * `chat:write`
+   * @param message The message object to send
+   * @returns A promise that resolves when the message is sent
+   * @example
+   * // Send a simple message
+   * await kick.chat.send({ content: "Hello Kick!" });
+   *
+   */
+  send(message: ChatMessage): Promise<void> {
+    return this.rest.fetch("/public/v1/chat", {
+      method: "POST",
+      body: JSON.stringify({
+        type: message.type ?? "bot",
+        content: message.content,
+      }),
+    });
+  }
+
+  /**
+   * Delete a chat message from a channel.
+   *
+   * * Requires scope:
+   * `moderation:chat_message:manage`: Execute moderation actions on chat messages
+   *
+   * @param messageId Message ID
+   */
+  delete(messageId: string): Promise<void> {
+    return this.rest.fetch(`/public/v1/chat/${messageId}`, {
+      method: "DELETE",
+    });
+  }
+}

package/src/rest/RestClient.ts

@@ -0,0 +1,39 @@
+import type { TokenManager } from "../auth/TokenManager.ts";
+
+export class RestClient {
+  private tokenManager?: TokenManager;
+
+  setTokenManager(tokenManager: TokenManager) {
+    this.tokenManager = tokenManager;
+  }
+
+  async fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    if (!this.tokenManager) {
+      throw new Error("TokenManager not set in RestClient");
+    }
+    const accessToken = await this.tokenManager.getAccessToken();
+
+    const response = await fetch(`https://api.kick.com${endpoint}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+        ...(options.headers || {}),
+      },
+    });
+
+    if (!response.ok) {
+      let suggestion = "";
+      if (response.status === 401) {
+        suggestion =
+          "Have you obtained access token or refreshed them? If so, make sure your scopes cover the requested endpoint.";
+      }
+
+      throw new Error(
+        `API request failed, response status: ${response.status}\n[SUGGESTION] ${suggestion}`,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+}

package/src/webhooks/NgrokAdapter.ts

@@ -0,0 +1,46 @@
+import { logger } from "../Logger.ts";
+
+type NgrokOptions = {
+  port?: number;
+  path?: string;
+  authtoken?: string;
+  domain?: string;
+  region?: string;
+  onUrl?: (url: string) => void;
+};
+
+export async function ngrokAdapter(options: NgrokOptions = {}) {
+  let ngrok: any;
+
+  try {
+    ngrok = await import("@ngrok/ngrok");
+  } catch {
+    throw new Error(
+      "@ngrok/ngrok is not installed. Install it with `npm install @ngrok/ngrok`.",
+    );
+  }
+
+  const port = options.port ?? 3000;
+  const path = options.path ?? "/kick/webhook";
+
+  const listener = await ngrok.connect({
+    addr: port,
+    domain: options.domain,
+    region: options.region,
+    authtoken: options.authtoken,
+    authtoken_from_env: !options.authtoken,
+  });
+
+  const fullUrl = `${listener.url()}${path}`;
+
+  options.onUrl?.(fullUrl);
+
+  logger.success("Ngrok tunnel established", { fullUrl });
+
+  return {
+    url: fullUrl,
+    async close() {
+      await listener.close();
+    },
+  };
+}

package/src/webhooks/WebhookRouter.ts

@@ -0,0 +1,135 @@
+import type { CreateServerOptions } from "../../types";
+import { webhookServer } from "./WebhookServer.ts";
+import { ngrokAdapter } from "./NgrokAdapter.ts";
+
+const KICK_PUBLIC_KEY_PEM = `
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq/+l1WnlRrGSolDMA+A8
+6rAhMbQGmQ2SapVcGM3zq8ANXjnhDWocMqfWcTd95btDydITa10kDvHzw9WQOqp2
+MZI7ZyrfzJuz5nhTPCiJwTwnEtWft7nV14BYRDHvlfqPUaZ+1KR4OCaO/wWIk/rQ
+L/TjY0M70gse8rlBkbo2a8rKhu69RQTRsoaf4DVhDPEeSeI5jVrRDGAMGL3cGuyY
+6CLKGdjVEM78g3JfYOvDU/RvfqD7L89TZ3iN94jrmWdGz34JNlEI5hqK8dd7C5EF
+BEbZ5jgB8s8ReQV8H+MkuffjdAj3ajDDX3DOJMIut1lBrUVD1AaSrGCKHooWoL2e
+twIDAQAB
+-----END PUBLIC KEY-----
+`.trim();
+
+export async function verifyKickWebhookSignature(params: {
+  messageId: string;
+  timestamp: string;
+  rawBody: string;
+  signature: string;
+}): Promise<boolean> {
+  const { messageId, timestamp, rawBody, signature } = params;
+  const payload = `${messageId}.${timestamp}.${rawBody}`;
+
+  const pemContents = KICK_PUBLIC_KEY_PEM.replace(
+    "-----BEGIN PUBLIC KEY-----",
+    "",
+  )
+    .replace("-----END PUBLIC KEY-----", "")
+    .replace(/\s+/g, "");
+
+  const binaryKey = Buffer.from(pemContents, "base64");
+
+  const publicKey = await crypto.subtle.importKey(
+    "spki",
+    binaryKey,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(payload);
+  const sigBuffer = Buffer.from(signature, "base64");
+
+  return await crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    publicKey,
+    sigBuffer,
+    data,
+  );
+}
+
+type Handler = (event: any, headers: Headers) => void | Promise<void>;
+
+export class WebhookRouter {
+  private handlers = new Map<string, Set<Handler>>();
+
+  constructor(
+    private readonly secret: string,
+    private readonly rest: any,
+  ) {}
+
+  on(eventType: string, handler: Handler) {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+    }
+    this.handlers.get(eventType)!.add(handler);
+  }
+
+  async handleRequest(params: {
+    rawBody: string;
+    headers: Record<string, string | string[] | undefined>;
+  }) {
+    const headers = params.headers;
+
+    const messageId = headers["kick-event-message-id"] as string;
+    const timestamp = headers["kick-event-message-timestamp"] as string;
+    const signature = headers["kick-event-signature"] as string;
+    const eventType = headers["kick-event-type"] as string;
+
+    if (!messageId || !timestamp || !signature || !eventType) {
+      throw new Error("Missing required Kick webhook headers");
+    }
+
+    const valid = await verifyKickWebhookSignature({
+      messageId,
+      timestamp,
+      rawBody: params.rawBody,
+      signature,
+    });
+
+    if (!valid) {
+      throw new Error("Invalid Kick webhook signature");
+    }
+
+    const payload = JSON.parse(params.rawBody);
+
+    const handlers = this.handlers.get(eventType);
+    if (!handlers) return;
+
+    for (const handler of handlers) {
+      await handler(payload, headers as any);
+    }
+  }
+
+  createServer(options: CreateServerOptions) {
+    return webhookServer(this, options);
+  }
+
+  async ngrok(options?: {
+    port?: number;
+    path?: string;
+    authtoken?: string;
+    domain?: string;
+    region?: string;
+    onUrl?: (url: string) => void;
+  }) {
+    return await ngrokAdapter(options);
+  }
+
+  async subscribe(options: { events: { name: string; version?: number }[] }) {
+    await this.rest.fetch("/public/v1/events/subscriptions", {
+      method: "POST",
+      body: JSON.stringify({
+        events: options.events.map((e) => ({
+          name: e.name,
+          version: e.version ?? 1,
+        })),
+        method: "webhook",
+      }),
+    });
+  }
+}

package/src/webhooks/WebhookServer.ts

@@ -0,0 +1,41 @@
+import type { WebhookRouter } from "./WebhookRouter";
+import type { CreateServerOptions } from "../../types";
+import { logger } from "../Logger.ts";
+
+export function webhookServer(
+  router: WebhookRouter,
+  options: CreateServerOptions = {},
+): Bun.Server<undefined> {
+  const port = options.port ?? 3000;
+  const path = options.path ?? "/kick/webhook";
+
+  const server = Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (req.method !== "POST" || url.pathname !== path) {
+        return new Response(null, { status: 404 });
+      }
+
+      try {
+        const rawBody = await req.text();
+        const headers = Object.fromEntries(req.headers.entries());
+
+        await router.handleRequest({
+          rawBody,
+          headers,
+        });
+
+        return new Response("OK", { status: 200 });
+      } catch (err) {
+        logger.error(err);
+        return new Response("Unauthorized", { status: 401 });
+      }
+    },
+  });
+
+  logger.success("Webhook server started", { port, path });
+
+  return server;
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/types/api.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @type GetCategoriesParams
+ * @property {number?} [cursor] - The cursor for pagination. (Minimum: 4, Maximum: 28)
+ * @property {number?} [limit] - The maximum number of categories to return. (Minimum: 1, Maximum: 1000)
+ * @property {string[]?} [name] - Category names.
+ * @property {string[]?} [tags] - Tags associated with the categories.
+ * @property {number[]?} [id] - Category IDs.
+ */
+export type GetCategoriesParams = {
+  cursor?: number;
+  limit?: number;
+  name?: string[];
+  tags?: string[];
+  id?: number[];
+};
+
+/**
+ * @interface KickChannel
+ * @property {string} slug - The unique identifier for the channel.
+ * @property {string} stream_title - The title of the current stream.
+ * @property {object} [category] - The category of the stream, if available.
+ * @property {number} category.id - The unique identifier for the category.
+ * @property {string} category.name - The name of the category.
+ */
+export interface KickChannel {
+  slug: string;
+  stream_title: string;
+  category?: {
+    id: number;
+    name: string;
+  };
+}
+
+export interface ChannelRewardBase {
+  background_color?: string;
+  cost: number;
+  description: string;
+  is_enabled?: boolean;
+  is_user_input_required?: boolean;
+  should_redemptions_skip_request_queue?: boolean;
+  title: string;
+}
+
+export interface KickChannelReward extends ChannelRewardBase {
+  id: string;
+  is_paused: boolean;
+}
+
+export interface GetChannelRewardsResponse {
+  data: KickChannelReward[];
+  message: string;
+}
+
+export interface GetRedemptionsParams {
+  reward_id?: string;
+  status?: "pending" | "fulfilled" | "canceled";
+  id?: string[];
+  cursor?: string;
+}
+
+export interface KickRedemption {
+  id: string;
+  redeemed_at: string;
+  redeemer: {
+    user_id: number;
+  };
+  status: string;
+  user_input?: string;
+}
+
+export interface RedemptionData {
+  redemptions: KickRedemption[];
+  reward: {
+    can_manage: boolean;
+    cost: number;
+    description: string;
+    id: string;
+    is_deleted: boolean;
+    title: string;
+  };
+}
+
+export interface GetRedemptionsResponse {
+  data: RedemptionData[];
+  message: string;
+  pagination: {
+    next_cursor: string | null;
+  };
+}
+
+export interface RedemptionActionResponse {
+  data: { id: string; reason: string }[];
+  message: string;
+}
+
+export type KickOkResponse = {
+  data: Record<string, never> | {};
+  message: string;
+};
+
+export type ModerationBanRequest = {
+  broadcaster_user_id: number;
+  user_id: number;
+  reason?: string;
+  duration?: number;
+};
+
+export type ModerationUnbanRequest = {
+  broadcaster_user_id: number;
+  user_id: number;
+};
+
+export type KickLivestream = {
+  broadcaster_user_id: number;
+  channel_id: number;
+  slug: string;
+  stream_title: string;
+  viewer_count: number;
+  language: string;
+  has_mature_content: boolean;
+  started_at: string;
+  thumbnail: string;
+  profile_picture: string;
+  custom_tags: string[];
+  category: {
+    id: number;
+    name: string;
+    thumbnail: string;
+  };
+};
+
+export type KickLivestreamsResponse = {
+  data: KickLivestream[];
+  message: string;
+};
+
+export type KickLivestreamStatsResponse = {
+  data: {
+    total_count: number;
+  };
+  message: string;
+};
+
+export type KickLeaderboardEntry = {
+  gifted_amount: number;
+  rank: number;
+  user_id: number;
+  username: string;
+};
+
+export type KickLeaderboardResponse = {
+  data: {
+    lifetime: KickLeaderboardEntry[];
+    month: KickLeaderboardEntry[];
+    week: KickLeaderboardEntry[];
+  };
+  message: string;
+};

package/types/auth.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents the response received when getting or refreshing tokens from Kick.
+ *
+ * - `access_token`: The access token used for authentication.
+ * - `refresh_token`: The refresh token used to obtain new access tokens.
+ * - `token_type`: (Optional) The type of the token, typically "Bearer".
+ * - `expires_in`: (Optional) The duration in seconds until the access token expires.
+ * - `scope`: (Optional) The scopes granted to the access token.
+ *
+ * @interface KickTokenResponse
+ * @property {string} access_token - The access token used for authentication.
+ * @property {string} refresh_token - The refresh token used to obtain new access tokens.
+ * @property {string} [token_type] - (Optional) The type of the token, typically "Bearer".
+ * @property {number} [expires_in] - (Optional) The duration in seconds until the access token expires.
+ * @property {string} [scope] - (Optional) The scopes granted to the access token.
+ */
+export interface KickTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type?: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+/**
+ * Options for Kick authentication including initial tokens and token update callback.
+ *
+ * - `initialTokens`: (Optional) Initial tokens to set up the authentication.
+ * - `onTokenUpdate`: (Optional) Callback function invoked when tokens are updated.
+ *
+ * @interface KickAuthOptions
+ * @property {KickTokenResponse} [initialTokens] - (Optional) Initial tokens to set up the authentication.
+ * @property {(tokens: KickTokenResponse) => void | Promise<void>} [onTokenUpdate] - (Optional) Callback function invoked when tokens are updated.
+ */
+export interface KickAuthOptions {
+  initialTokens?: KickTokenResponse;
+  onTokenUpdate?: (tokens: KickTokenResponse) => void | Promise<void>;
+}

package/types/chat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents a message in a chat interface.
+ * - `content`: The text content of the message.
+ * - `type`: The type of message, either from a "bot" or a "user". Defaults to "bot" if not specified.
+ *
+ * @interface ChatMessage
+ * @property {string} content - The text content of the message.
+ * @property {"bot" | "user"} [type] - The type of message, either "bot" or "user".
+ *
+ */
+export interface ChatMessage {
+  content: string;
+  type?: "bot" | "user";
+}

package/types/client.d.ts

@@ -0,0 +1,67 @@
+import type { KickAuthOptions } from "./auth";
+
+/**
+ * Available OAuth2 scopes for Kick API.
+ * @type {string}
+ */
+type KickScopes =
+  | "user:read"
+  | "channel:read"
+  | "channel:write"
+  | "channel:rewards:read"
+  | "channel:rewards:write"
+  | "chat:write"
+  | "streamkey:read"
+  | "events:subscribe"
+  | "moderation:ban"
+  | "moderation:chat_message:manage"
+  | "kicks:read";
+
+/**
+ * Options for initializing the KickClient.
+ *
+ * - `clientId`: The client ID of your Kick application.
+ * - `clientSecret`: The client secret of your Kick application.
+ * - `redirectUri`: The redirect URI for OAuth2 authorization.
+ * - `scopes`: The scopes required for your application.
+ * - `state`: Optional state parameter for OAuth2 authorization.
+ * - `auth`: Authentication options including token management.
+ *
+ * @example
+ * ```ts
+ * const client = new KickClient({
+ *   clientId: "your-client-id",
+ *   clientSecret: "your-client-secret",
+ *   redirectUri: "http://localhost:3000/callback",
+ *   scopes: ["chat:read", "chat:write"],
+ *   auth: {
+ *     initialTokens: {
+ *       access_token: "initial-access-token",
+ *       refresh_token: "initial-refresh-token",
+ *       expires_in: 7200,
+ *       scope: "chat:read chat:write",
+ *       token_type: "Bearer",
+ *     },
+ *   },
+ *   onTokenUpdate: (tokens) => {
+ *      console.log("Tokens updated:", tokens);
+ *   }
+ * });
+ * ```
+ *
+ * @interface KickClientOptions
+ * @property {string} clientId - The client ID of your Kick application.
+ * @property {string} clientSecret - The client secret of your Kick application.
+ * @property {string} redirectUri - The redirect URI for OAuth2 authorization.
+ * @property {KickScopes[]} scopes - The scopes required for your application.
+ * @property {string} [state] - Optional state parameter for OAuth2 authorization.
+ * @property {KickAuthOptions} [auth] - Authentication options including token management.
+ */
+export interface KickClientOptions {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes: KickScopes[];
+  state?: string;
+  auth?: KickAuthOptions;
+}

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client";
+export * from "./chat";
+export * from "./auth";
+export * from "./webhooks";

package/types/webhooks.d.ts

@@ -0,0 +1,35 @@
+export interface KickWebhookEvent<T = any> {
+  event: string;
+  data: T;
+  created_at: string;
+}
+
+export interface ChatMessageEvent {
+  message_id: string;
+  replies_to: string | null;
+  broadcaster: {
+    is_anonymous: boolean;
+    user_id: number;
+    username: string;
+    is_verified: boolean;
+    profile_picture: string;
+    channel_slug: string;
+    identity: any | null;
+  };
+  sender: {
+    is_anonymous: boolean;
+    user_id: number;
+    username: string;
+    is_verified: boolean;
+    profile_picture: string;
+    channel_slug: string;
+    identity: any | null;
+  };
+  content: string;
+  emotes: any[];
+  created_at: string;
+}
+export interface CreateServerOptions {
+  port?: number;
+  path?: string;
+}