@manaobot/kick 1.0.0

package/src/api/ChannelRewardsAPI.ts

@@ -0,0 +1,121 @@
+import type { RestClient } from "../rest/RestClient";
+import type {
+  KickChannelReward,
+  ChannelRewardBase,
+  GetChannelRewardsResponse,
+  GetRedemptionsParams,
+  GetRedemptionsResponse,
+  RedemptionActionResponse,
+} from "../../types/api";
+
+/**
+ * ChannelRewardsAPI provides access to Kick Channel Rewards APIs.
+ *
+ * Requires scopes:
+ * - channel:rewards:read
+ * - channel:rewards:write
+ *
+ * @example
+ * const rewards = await kick.api.channelRewards.get();
+ */
+export class ChannelRewardsAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Get all channel rewards for the authorized broadcaster.
+   */
+  async get(): Promise<GetChannelRewardsResponse> {
+    return this.rest.fetch("/public/v1/channels/rewards", {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Create a new channel reward.
+   */
+  async create(
+    body: ChannelRewardBase,
+  ): Promise<{ data: KickChannelReward; message: string }> {
+    return this.rest.fetch("/public/v1/channels/rewards", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Update an existing reward.
+   *
+   * Only the creating app can update a reward.
+   */
+  async update(
+    id: string,
+    body: Partial<ChannelRewardBase>,
+  ): Promise<{ data: KickChannelReward; message: string }> {
+    return this.rest.fetch(`/public/v1/channels/rewards/${id}`, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Delete a channel reward.
+   */
+  async delete(id: string): Promise<void> {
+    await this.rest.fetch(`/public/v1/channels/rewards/${id}`, {
+      method: "DELETE",
+    });
+  }
+
+  /**
+   * Retrieve reward redemptions.
+   */
+  async getRedemptions(
+    params: GetRedemptionsParams = {},
+  ): Promise<GetRedemptionsResponse> {
+    const search = new URLSearchParams();
+
+    if (params.reward_id) search.append("reward_id", params.reward_id);
+    if (params.status) search.append("status", params.status);
+    if (params.cursor) search.append("cursor", params.cursor);
+    params.id?.forEach((v) => search.append("id", v));
+
+    const query = search.toString();
+
+    return this.rest.fetch(
+      `/public/v1/channels/rewards/redemptions${query ? `?${query}` : ""}`,
+      { method: "GET" },
+    );
+  }
+
+  /**
+   * Accept redemptions (max 25).
+   */
+  async accept(ids: string[]): Promise<RedemptionActionResponse> {
+    return this.rest.fetch("/public/v1/channels/rewards/redemptions/accept", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ ids }),
+    });
+  }
+
+  /**
+   * Reject redemptions (max 25).
+   */
+  async reject(ids: string[]): Promise<RedemptionActionResponse> {
+    return this.rest.fetch("/public/v1/channels/rewards/redemptions/reject", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ ids }),
+    });
+  }
+}

package/src/api/ChannelsAPI.ts

@@ -0,0 +1,63 @@
+import type { RestClient } from "../rest/RestClient";
+import type { KickChannel } from "../../types/api";
+
+/**
+ * ChannelsAPI provides access to Kick Channel APIs.
+ *
+ * @example
+ * const channels = await kick.api.channels.get();
+ * const channels = await kick.api.channels.get({ slug: ["manaobot"] });
+ */
+export class ChannelsAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Retrieve channel information.
+   *
+   * - Provided no params, returns current authorized channel
+   * - Provide broadcaster_user_id[] OR slug[] only, not both
+   */
+  async get(params?: {
+    broadcaster_user_id?: number[];
+    slug?: string[];
+  }): Promise<{ data: KickChannel[] }> {
+    const search = new URLSearchParams();
+
+    if (params?.broadcaster_user_id && params?.slug) {
+      throw new Error(
+        "ChannelsClient.get(): cannot mix broadcaster_user_id and slug",
+      );
+    }
+
+    params?.broadcaster_user_id?.forEach((id) =>
+      search.append("broadcaster_user_id", String(id)),
+    );
+
+    params?.slug?.forEach((s) => search.append("slug", s));
+
+    const query = search.toString();
+
+    return this.rest.fetch(`/public/v1/channels${query ? `?${query}` : ""}`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Update livestream metadata for the authorized channel.
+   *
+   * Requires scope: channel:write
+   */
+  async update(body: {
+    category_id?: number;
+    custom_tags?: string[];
+    stream_title?: string;
+  }): Promise<void> {
+    await this.rest.fetch(`/public/v1/channels`, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+}

package/src/api/KicksAPI.ts

@@ -0,0 +1,37 @@
+import type { RestClient } from "../rest/RestClient";
+import type { KickLeaderboardResponse } from "../../types/api";
+
+/**
+ * KicksAPI provides access to Kick KICKs APIs.
+ *
+ * Required scope:
+ * - kicks:read
+ *
+ * @example
+ * const leaderboard = await kick.api.kicks.getLeaderboard({ top: 10 });
+ */
+export class KicksAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Get KICKs leaderboard for the authenticated broadcaster.
+   *
+   * @param params Optional query params
+   */
+  async getLeaderboard(params?: {
+    top?: number;
+  }): Promise<KickLeaderboardResponse> {
+    const search = new URLSearchParams();
+
+    if (params?.top) {
+      search.set("top", String(params.top));
+    }
+
+    const query = search.toString();
+
+    return this.rest.fetch(
+      `/public/v1/kicks/leaderboard${query ? `?${query}` : ""}`,
+      { method: "GET" },
+    );
+  }
+}

package/src/api/LivestreamsAPI.ts

@@ -0,0 +1,65 @@
+import type { RestClient } from "../rest/RestClient";
+import type {
+  KickLivestream,
+  KickLivestreamStatsResponse,
+  KickLivestreamsResponse,
+} from "../../types/api";
+
+/**
+ * LivestreamsAPI provides access to Kick Livestream APIs.
+ *
+ * @example
+ * const streams = await kick.api.livestreams.get({ limit: 10 });
+ */
+export class LivestreamsAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Get livestreams with optional filters.
+   *
+   * Supported filters:
+   * - broadcaster_user_id[]
+   * - category_id
+   * - language
+   * - limit
+   * - sort ("viewer_count" | "started_at")
+   */
+  async get(params?: {
+    broadcaster_user_id?: number[];
+    category_id?: number;
+    language?: string;
+    limit?: number;
+    sort?: "viewer_count" | "started_at";
+  }): Promise<KickLivestreamsResponse> {
+    const search = new URLSearchParams();
+
+    params?.broadcaster_user_id?.forEach((id) =>
+      search.append("broadcaster_user_id", String(id)),
+    );
+
+    if (params?.category_id)
+      search.set("category_id", String(params.category_id));
+    if (params?.language) search.set("language", params.language);
+    if (params?.limit) search.set("limit", String(params.limit));
+    if (params?.sort) search.set("sort", params.sort);
+
+    const query = search.toString();
+
+    return this.rest.fetch(
+      `/public/v1/livestreams${query ? `?${query}` : ""}`,
+      { method: "GET" },
+    );
+  }
+
+  /**
+   * Get livestream statistics.
+   *
+   * @example
+   * const stats = await kick.api.livestreams.getStats();
+   */
+  async getStats(): Promise<KickLivestreamStatsResponse> {
+    return this.rest.fetch("/public/v1/livestreams/stats", {
+      method: "GET",
+    });
+  }
+}

package/src/api/ModerationAPI.ts

@@ -0,0 +1,60 @@
+import type { RestClient } from "../rest/RestClient";
+import type {
+  ModerationBanRequest,
+  ModerationUnbanRequest,
+  KickOkResponse,
+} from "../../types/api";
+
+/**
+ * ModerationAPI provides access to Kick Moderation APIs.
+ *
+ * Required scope:
+ * - moderation:ban
+ *
+ * @example
+ * await kick.api.moderation.ban({ broadcaster_user_id: 123, user_id: 333, reason: "Not vibing" });
+ * await kick.api.moderation.timeout({ broadcaster_user_id: 123, user_id: 333, duration: 10 });
+ * await kick.api.moderation.unban({ broadcaster_user_id: 123, user_id: 333 });
+ */
+export class ModerationAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Ban a user (permanent ban).
+   * Omit `duration (minutes)` to ban permanently.
+   */
+  async ban(
+    body: Omit<ModerationBanRequest, "duration">,
+  ): Promise<KickOkResponse> {
+    return this.rest.fetch("/public/v1/moderation/bans", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Timeout a user for `duration` minutes.
+   */
+  async timeout(body: ModerationBanRequest): Promise<KickOkResponse> {
+    if (typeof body.duration !== "number") {
+      throw new Error(
+        "ModerationAPI.timeout(): duration is required (minutes)",
+      );
+    }
+
+    return this.rest.fetch("/public/v1/moderation/bans", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Unban a user OR remove an active timeout.
+   */
+  async unban(body: ModerationUnbanRequest): Promise<KickOkResponse> {
+    return this.rest.fetch("/public/v1/moderation/bans", {
+      method: "DELETE",
+      body: JSON.stringify(body),
+    });
+  }
+}

package/src/api/UsersAPI.ts

@@ -0,0 +1,72 @@
+import type { RestClient } from "../rest/RestClient";
+
+/**
+ * Parameters for retrieving users.
+ */
+export interface GetUsersParams {
+  /**
+   * User IDs to retrieve.
+   * If omitted, returns the currently authorized user.
+   */
+  id?: number[];
+}
+
+/**
+ * Kick User object returned by the API.
+ */
+export interface KickUser {
+  email?: string;
+  name: string;
+  profile_picture: string;
+  user_id: number;
+}
+
+/**
+ * Response returned from GET /public/v1/users
+ */
+export interface GetUsersResponse {
+  data: KickUser[];
+  message: string;
+}
+
+/**
+ * UsersAPI provides access to Kick User APIs.
+ *
+ * @example
+ * const users = await kick.api.users.get();
+ * console.log(users.data);
+ */
+export class UsersAPI {
+  constructor(private readonly rest: RestClient) {}
+
+  /**
+   * Retrieve user information.
+   *
+   * If no IDs are provided, the currently authorized user is returned.
+   *
+   * Requires scope:
+   * - user:read
+   *
+   * @param params Query parameters
+   * @returns Kick user data
+   *
+   * @example
+   * // Get current user
+   * const me = await kick.api.users.get();
+   *
+   * @example
+   * // Get specific users
+   * const users = await kick.api.users.get({ id: [123, 456] });
+   */
+  async get(params: GetUsersParams = {}): Promise<GetUsersResponse> {
+    const search = new URLSearchParams();
+
+    params.id?.forEach((v) => search.append("id", String(v)));
+
+    const query = search.toString();
+
+    return this.rest.fetch(`/public/v1/users${query ? `?${query}` : ""}`, {
+      method: "GET",
+    });
+  }
+}

package/src/auth/AuthManager.ts

@@ -0,0 +1,64 @@
+import { callbackServer } from "./CallbackServer.ts";
+import type { KickClient } from "../KickClient";
+
+type AuthorizedHandler = () => void | Promise<void>;
+
+/**
+ * AuthManager handles authentication lifecycle events and local callback servers.
+ * @example
+ * ```ts
+ * kick.auth.onAuthorized(() => {
+ *   console.log("Authenticated and ready!");
+ * });
+ * ```
+ */
+export class AuthManager {
+  private handlers = new Set<AuthorizedHandler>();
+  private readonly client: KickClient;
+
+  constructor(client: KickClient) {
+    this.client = client;
+  }
+
+  /**
+   * Register a callback to be executed when the client is authorized.
+   * @param handler Function to run on authorization
+   */
+  onAuthorized(handler: AuthorizedHandler) {
+    this.handlers.add(handler);
+  }
+
+  /**
+   * Trigger all registered authorization handlers.
+   * Internal use only.
+   */
+  async emitAuthorized() {
+    for (const handler of this.handlers) {
+      await handler();
+    }
+  }
+
+  /**
+   * Returns a promise that resolves once the client is authorized.
+   * @example
+   * await kick.auth.waitForAuthorization();
+   * console.log("Authorized!");
+   */
+  waitForAuthorization(): Promise<void> {
+    return new Promise((resolve) => {
+      this.onAuthorized(() => resolve());
+    });
+  }
+
+  /**
+   * Creates a temporary local server to handle OAuth2 redirects.
+   * @param options Server configuration
+   * @returns {Bun.Server<undefined>} Callback server instance
+   */
+  createCallbackServer(options?: {
+    port?: number;
+    path?: string;
+  }): Bun.Server<undefined> {
+    return callbackServer(this.client, options);
+  }
+}

package/src/auth/CallbackServer.ts

@@ -0,0 +1,57 @@
+import type { KickClient } from "../KickClient";
+import { logger } from "../Logger.ts";
+
+/**
+ * Configuration options for the local callback server.
+ */
+interface CallbackServerOptions {
+  /** @default 3000 */
+  port?: number;
+  /** @default "/callback" */
+  path?: string;
+}
+
+export function callbackServer(
+  client: KickClient,
+  options: CallbackServerOptions = {},
+): Bun.Server<undefined> {
+  const port = options.port ?? 3000;
+  const path = options.path ?? "/callback";
+
+  const server = Bun.serve({
+    port,
+    reusePort: true,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (req.method !== "GET" || url.pathname !== path) {
+        return new Response(null, { status: 404 });
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+
+      if (!code || state !== client.getState()) {
+        logger.error("Invalid OAuth callback: state mismatch or missing code");
+        return new Response("Invalid OAuth callback", { status: 400 });
+      }
+
+      try {
+        await client.exchangeCode(code);
+        await client.auth.emitAuthorized();
+
+        return new Response("Authorization success, you can close this tab.", {
+          status: 200,
+          headers: { "Content-Type": "text/plain" },
+        });
+      } catch (err) {
+        logger.error("OAuth exchange failed", err);
+        return new Response("Authorization failed", { status: 500 });
+      }
+    },
+  });
+
+  logger.success("Callback server started", { port, path });
+
+  return server;
+}

package/src/auth/OAuth.ts

@@ -0,0 +1,55 @@
+import type { KickTokenResponse } from "../../types";
+
+export async function exchangeCode(
+  code: string,
+  verifier: string,
+  clientId: string,
+  clientSecret: string,
+  redirectUri: string,
+): Promise<KickTokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    client_secret: clientSecret,
+    code_verifier: verifier,
+  });
+
+  const res = await fetch("https://id.kick.com/oauth/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: params.toString(),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Code exchange failed (${res.status})`);
+  }
+
+  return res.json() as Promise<KickTokenResponse>;
+}
+
+export async function refreshToken(
+  refreshToken: string,
+  clientId: string,
+  clientSecret: string,
+): Promise<KickTokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId,
+    client_secret: clientSecret,
+  });
+
+  const res = await fetch("https://id.kick.com/oauth/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: params.toString(),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Token refresh failed (${res.status})`);
+  }
+
+  return res.json() as Promise<KickTokenResponse>;
+}

package/src/auth/PKCE.ts

@@ -0,0 +1,13 @@
+export function createPkce(): {
+  verifier: string;
+  challenge: string;
+} {
+  const verifier = Buffer.from(
+    crypto.getRandomValues(new Uint8Array(32)),
+  ).toString("base64url");
+  const challenge = new Bun.CryptoHasher("sha256")
+    .update(verifier)
+    .digest("base64url");
+
+  return { verifier, challenge };
+}

package/src/auth/TokenManager.ts

@@ -0,0 +1,53 @@
+import type { KickTokenResponse } from "../../types";
+
+type RefreshFn = (refreshToken: string) => Promise<KickTokenResponse>;
+type TokenUpdateCallback = (tokens: KickTokenResponse) => void | Promise<void>;
+
+export class TokenManager {
+  private accessToken?: string;
+  private refreshToken?: string;
+  private expiresAt?: number;
+  private readonly onUpdate?: TokenUpdateCallback;
+
+  private readonly refreshFn: RefreshFn;
+  private refreshThresholdMs = 60_000; // refresh 60s before expiry
+
+  constructor(refreshFn: RefreshFn, onUpdate?: TokenUpdateCallback) {
+    this.refreshFn = refreshFn;
+    this.onUpdate = onUpdate;
+  }
+
+  setTokens(token: KickTokenResponse) {
+    this.accessToken = token.access_token;
+    this.refreshToken = token.refresh_token;
+
+    this.onUpdate?.(token);
+  }
+
+  async getAccessToken(): Promise<string> {
+    if (!this.accessToken) {
+      throw new Error("TokenManager not initialized");
+    }
+
+    if (!this.expiresAt) {
+      return this.accessToken;
+    }
+
+    const now = Date.now();
+
+    if (now >= this.expiresAt - this.refreshThresholdMs) {
+      await this.refresh();
+    }
+
+    return this.accessToken;
+  }
+
+  private async refresh() {
+    if (!this.refreshToken) {
+      throw new Error("No refresh token available");
+    }
+
+    const newToken = await this.refreshFn(this.refreshToken);
+    this.setTokens(newToken);
+  }
+}