tiktok-live-api 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Type definitions for TikTok LIVE API events.
+ *
+ * These types provide IDE autocompletion and type safety
+ * when handling events from {@link TikTokLive} and {@link TikTokCaptions}.
+ *
+ * @packageDocumentation
+ */
+/** User profile attached to most LIVE events. */
+interface TikTokUser {
+    userId: string;
+    uniqueId: string;
+    nickname: string;
+    profilePictureUrl: string;
+    followRole: number;
+    isSubscriber: boolean;
+}
+/** Payload for `chat` events. */
+interface ChatEvent {
+    user: TikTokUser;
+    comment: string;
+    emotes: Array<{
+        emoteId: string;
+        image: string;
+    }>;
+}
+/** Payload for `gift` events. */
+interface GiftEvent {
+    user: TikTokUser;
+    giftId: number;
+    giftName: string;
+    diamondCount: number;
+    repeatCount: number;
+    repeatEnd: boolean;
+}
+/** Payload for `like` events. */
+interface LikeEvent {
+    user: TikTokUser;
+    likeCount: number;
+    totalLikes: number;
+}
+/** Payload for `member` (viewer join) events. */
+interface MemberEvent {
+    user: TikTokUser;
+    actionId: number;
+}
+/** Payload for `follow` and `share` events. */
+interface SocialEvent {
+    user: TikTokUser;
+    eventType: string;
+}
+/** Payload for `roomUserSeq` (viewer count) events. */
+interface RoomUserSeqEvent {
+    viewerCount: number;
+    topViewers: TikTokUser[];
+}
+/** Payload for `battle` events. */
+interface BattleEvent {
+    type: string;
+    teams: Array<Record<string, unknown>>;
+    scores: number[];
+}
+/** Payload for `caption` events from {@link TikTokCaptions}. */
+interface CaptionEvent {
+    text: string;
+    speaker: string;
+    isFinal: boolean;
+    language: string;
+}
+/** Payload for `translation` events from {@link TikTokCaptions}. */
+interface TranslationEvent {
+    text: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+}
+/** Payload for `credits` events from {@link TikTokCaptions}. */
+interface CreditsEvent {
+    total: number;
+    used: number;
+    remaining: number;
+}
+/** Connection event payload. */
+interface ConnectedEvent {
+    uniqueId: string;
+}
+/** Disconnection event payload. */
+interface DisconnectedEvent {
+    uniqueId: string;
+}
+/** Error event payload. */
+interface ErrorEvent {
+    error: string;
+}
+/**
+ * Map of event names to their payload types for {@link TikTokLive}.
+ */
+interface TikTokLiveEventMap {
+    chat: ChatEvent;
+    gift: GiftEvent;
+    like: LikeEvent;
+    follow: SocialEvent;
+    share: SocialEvent;
+    member: MemberEvent;
+    subscribe: SocialEvent;
+    roomUserSeq: RoomUserSeqEvent;
+    battle: BattleEvent;
+    envelope: Record<string, unknown>;
+    streamEnd: Record<string, unknown>;
+    roomInfo: Record<string, unknown>;
+    connected: ConnectedEvent;
+    disconnected: DisconnectedEvent;
+    error: ErrorEvent;
+    event: Record<string, unknown>;
+}
+/**
+ * Map of event names to their payload types for {@link TikTokCaptions}.
+ */
+interface TikTokCaptionsEventMap {
+    caption: CaptionEvent;
+    translation: TranslationEvent;
+    credits: CreditsEvent;
+    credits_low: CreditsEvent;
+    status: Record<string, unknown>;
+    connected: ConnectedEvent;
+    disconnected: DisconnectedEvent;
+    error: ErrorEvent;
+}
+
+/**
+ * TikTokLive — Connect to any TikTok LIVE stream via WebSocket.
+ *
+ * Receives real-time events: chat messages, gifts, likes, follows,
+ * viewer counts, battles, and more. Powered by the TikTool managed API.
+ *
+ * @example
+ * ```typescript
+ * import { TikTokLive } from 'tiktok-live-api';
+ *
+ * const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_KEY' });
+ *
+ * client.on('chat', (event) => {
+ *   console.log(`${event.user.uniqueId}: ${event.comment}`);
+ * });
+ *
+ * client.connect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link TikTokLive} constructor. */
+interface TikTokLiveOptions {
+    /** Your TikTool API key. Get one free at https://tik.tools */
+    apiKey?: string;
+    /** Auto-reconnect on disconnect (default: true). */
+    autoReconnect?: boolean;
+    /** Max reconnection attempts (default: 5). */
+    maxReconnectAttempts?: number;
+}
+type EventHandler$1<T> = (data: T) => void | Promise<void>;
+/**
+ * Connect to a TikTok LIVE stream and receive real-time events.
+ *
+ * @example
+ * ```typescript
+ * const client = new TikTokLive('username', { apiKey: 'KEY' });
+ * client.on('chat', (e) => console.log(e.comment));
+ * client.on('gift', (e) => console.log(`${e.giftName} worth ${e.diamondCount} 💎`));
+ * client.connect();
+ * ```
+ */
+declare class TikTokLive {
+    /** TikTok username (without @). */
+    readonly uniqueId: string;
+    /** Your TikTool API key. */
+    readonly apiKey: string;
+    /** Whether to auto-reconnect on disconnect. */
+    readonly autoReconnect: boolean;
+    /** Maximum reconnection attempts. */
+    readonly maxReconnectAttempts: number;
+    private _handlers;
+    private _ws;
+    private _connected;
+    private _intentionalClose;
+    private _reconnectAttempts;
+    private _eventCount;
+    /**
+     * Create a new TikTokLive client.
+     *
+     * @param uniqueId - TikTok username (without @)
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * const client = new TikTokLive('streamer', { apiKey: 'YOUR_KEY' });
+     * ```
+     */
+    constructor(uniqueId: string, options?: TikTokLiveOptions);
+    /** Whether the client is currently connected. */
+    get connected(): boolean;
+    /** Total number of events received this session. */
+    get eventCount(): number;
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name (chat, gift, like, follow, etc.)
+     * @param handler - Callback function
+     * @returns this (for chaining)
+     *
+     * @example
+     * ```typescript
+     * client.on('chat', (event) => console.log(event.comment));
+     * client.on('gift', (event) => console.log(event.giftName));
+     * ```
+     */
+    on<K extends keyof TikTokLiveEventMap>(event: K, handler: EventHandler$1<TikTokLiveEventMap[K]>): this;
+    on(event: string, handler: EventHandler$1<any>): this;
+    /**
+     * Remove an event handler.
+     *
+     * @param event - Event name
+     * @param handler - The handler to remove
+     */
+    off(event: string, handler: EventHandler$1<any>): this;
+    private _emit;
+    /**
+     * Connect to the TikTok LIVE stream.
+     *
+     * @returns Promise that resolves when connected, rejects on fatal error.
+     *
+     * @example
+     * ```typescript
+     * await client.connect();
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the stream.
+     */
+    disconnect(): void;
+    private _maybeReconnect;
+}
+
+/**
+ * TikTokCaptions — Real-time AI speech-to-text for TikTok LIVE streams.
+ *
+ * Transcribe and translate any TikTok LIVE stream in real-time.
+ * This feature is unique to TikTool Live — no other service offers it.
+ *
+ * @example
+ * ```typescript
+ * import { TikTokCaptions } from 'tiktok-live-api';
+ *
+ * const captions = new TikTokCaptions('streamer', {
+ *   apiKey: 'YOUR_KEY',
+ *   translate: 'en',
+ *   diarization: true,
+ * });
+ *
+ * captions.on('caption', (event) => {
+ *   console.log(`[${event.speaker}] ${event.text}`);
+ * });
+ *
+ * captions.connect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link TikTokCaptions} constructor. */
+interface TikTokCaptionsOptions {
+    /** Your TikTool API key. Get one at https://tik.tools */
+    apiKey?: string;
+    /** Target language code for real-time translation (e.g. "en", "es"). */
+    translate?: string;
+    /** Enable speaker identification (default: true). */
+    diarization?: boolean;
+    /** Auto-disconnect after N minutes (default: 60, max: 300). */
+    maxDurationMinutes?: number;
+}
+type EventHandler<T> = (data: T) => void | Promise<void>;
+/**
+ * Real-time AI speech-to-text for TikTok LIVE streams.
+ *
+ * @example
+ * ```typescript
+ * const captions = new TikTokCaptions('streamer', {
+ *   apiKey: 'KEY',
+ *   translate: 'en',
+ * });
+ * captions.on('caption', (e) => console.log(e.text));
+ * captions.on('translation', (e) => console.log(`→ ${e.text}`));
+ * captions.connect();
+ * ```
+ */
+declare class TikTokCaptions {
+    /** TikTok username (without @). */
+    readonly uniqueId: string;
+    /** Your TikTool API key. */
+    readonly apiKey: string;
+    /** Target translation language. */
+    readonly translate?: string;
+    /** Whether speaker diarization is enabled. */
+    readonly diarization: boolean;
+    /** Max session duration in minutes. */
+    readonly maxDurationMinutes?: number;
+    private _handlers;
+    private _ws;
+    private _connected;
+    private _intentionalClose;
+    /**
+     * Create a new TikTokCaptions client.
+     *
+     * @param uniqueId - TikTok username (without @)
+     * @param options - Configuration options
+     */
+    constructor(uniqueId: string, options?: TikTokCaptionsOptions);
+    /** Whether currently connected and receiving captions. */
+    get connected(): boolean;
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name (caption, translation, credits, status, error)
+     * @param handler - Callback function
+     *
+     * @example
+     * ```typescript
+     * captions.on('caption', (event) => {
+     *   const prefix = event.speaker ? `[${event.speaker}] ` : '';
+     *   console.log(`${prefix}${event.text}${event.isFinal ? ' ✓' : '...'}`);
+     * });
+     * ```
+     */
+    on<K extends keyof TikTokCaptionsEventMap>(event: K, handler: EventHandler<TikTokCaptionsEventMap[K]>): this;
+    on(event: string, handler: EventHandler<any>): this;
+    /** Remove an event handler. */
+    off(event: string, handler: EventHandler<any>): this;
+    private _emit;
+    /**
+     * Start receiving captions from the stream.
+     *
+     * @returns Promise that resolves when connected.
+     */
+    connect(): Promise<void>;
+    /** Stop receiving captions. */
+    disconnect(): void;
+}
+
+export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, type TranslationEvent };

package/dist/index.js

@@ -0,0 +1,291 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TikTokCaptions: () => TikTokCaptions,
+  TikTokLive: () => TikTokLive
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_ws = __toESM(require("ws"));
+var WS_BASE = "wss://api.tik.tools";
+var VERSION = "1.0.0";
+var TikTokLive = class {
+  /**
+   * Create a new TikTokLive client.
+   *
+   * @param uniqueId - TikTok username (without @)
+   * @param options - Configuration options
+   *
+   * @example
+   * ```typescript
+   * const client = new TikTokLive('streamer', { apiKey: 'YOUR_KEY' });
+   * ```
+   */
+  constructor(uniqueId, options = {}) {
+    this._handlers = /* @__PURE__ */ new Map();
+    this._ws = null;
+    this._connected = false;
+    this._intentionalClose = false;
+    this._reconnectAttempts = 0;
+    this._eventCount = 0;
+    this.uniqueId = uniqueId.replace(/^@/, "");
+    this.apiKey = options.apiKey || process.env.TIKTOOL_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error("apiKey is required. Get a free key at https://tik.tools");
+    }
+    this.autoReconnect = options.autoReconnect ?? true;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+  }
+  /** Whether the client is currently connected. */
+  get connected() {
+    return this._connected;
+  }
+  /** Total number of events received this session. */
+  get eventCount() {
+    return this._eventCount;
+  }
+  on(event, handler) {
+    if (!this._handlers.has(event)) {
+      this._handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this._handlers.get(event).add(handler);
+    return this;
+  }
+  /**
+   * Remove an event handler.
+   *
+   * @param event - Event name
+   * @param handler - The handler to remove
+   */
+  off(event, handler) {
+    this._handlers.get(event)?.delete(handler);
+    return this;
+  }
+  _emit(event, data) {
+    const handlers = this._handlers.get(event);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        const result = handler(data);
+        if (result instanceof Promise) {
+          result.catch(
+            (err) => console.error(`Error in '${event}' handler:`, err)
+          );
+        }
+      } catch (err) {
+        console.error(`Error in '${event}' handler:`, err);
+      }
+    }
+  }
+  /**
+   * Connect to the TikTok LIVE stream.
+   *
+   * @returns Promise that resolves when connected, rejects on fatal error.
+   *
+   * @example
+   * ```typescript
+   * await client.connect();
+   * ```
+   */
+  async connect() {
+    this._intentionalClose = false;
+    const uri = `${WS_BASE}?uniqueId=${this.uniqueId}&apiKey=${this.apiKey}`;
+    return new Promise((resolve, reject) => {
+      this._ws = new import_ws.default(uri, {
+        headers: { "User-Agent": `tiktok-live-api/${VERSION}` }
+      });
+      this._ws.on("open", () => {
+        this._connected = true;
+        this._reconnectAttempts = 0;
+        this._emit("connected", { uniqueId: this.uniqueId });
+        resolve();
+      });
+      this._ws.on("message", (raw) => {
+        try {
+          const event = JSON.parse(raw.toString());
+          this._eventCount++;
+          const eventType = event.event || "unknown";
+          const data = event.data || event;
+          this._emit("event", event);
+          this._emit(eventType, data);
+        } catch {
+        }
+      });
+      this._ws.on("close", () => {
+        this._connected = false;
+        this._emit("disconnected", { uniqueId: this.uniqueId });
+        this._maybeReconnect();
+      });
+      this._ws.on("error", (err) => {
+        this._emit("error", { error: err.message });
+        if (!this._connected) reject(err);
+      });
+    });
+  }
+  /**
+   * Disconnect from the stream.
+   */
+  disconnect() {
+    this._intentionalClose = true;
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+    this._connected = false;
+  }
+  async _maybeReconnect() {
+    if (this._intentionalClose || !this.autoReconnect || this._reconnectAttempts >= this.maxReconnectAttempts) {
+      return;
+    }
+    this._reconnectAttempts++;
+    const delay = Math.min(2 ** (this._reconnectAttempts - 1) * 1e3, 3e4);
+    await new Promise((r) => setTimeout(r, delay));
+    try {
+      await this.connect();
+    } catch {
+    }
+  }
+};
+
+// src/captions.ts
+var import_ws2 = __toESM(require("ws"));
+var CAPTIONS_BASE = "wss://api.tik.tools/captions";
+var VERSION2 = "1.0.0";
+var TikTokCaptions = class {
+  /**
+   * Create a new TikTokCaptions client.
+   *
+   * @param uniqueId - TikTok username (without @)
+   * @param options - Configuration options
+   */
+  constructor(uniqueId, options = {}) {
+    this._handlers = /* @__PURE__ */ new Map();
+    this._ws = null;
+    this._connected = false;
+    this._intentionalClose = false;
+    this.uniqueId = uniqueId.replace(/^@/, "");
+    this.apiKey = options.apiKey || process.env.TIKTOOL_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error("apiKey is required. Get a free key at https://tik.tools");
+    }
+    this.translate = options.translate;
+    this.diarization = options.diarization ?? true;
+    this.maxDurationMinutes = options.maxDurationMinutes;
+  }
+  /** Whether currently connected and receiving captions. */
+  get connected() {
+    return this._connected;
+  }
+  on(event, handler) {
+    if (!this._handlers.has(event)) {
+      this._handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this._handlers.get(event).add(handler);
+    return this;
+  }
+  /** Remove an event handler. */
+  off(event, handler) {
+    this._handlers.get(event)?.delete(handler);
+    return this;
+  }
+  _emit(event, data) {
+    const handlers = this._handlers.get(event);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        const result = handler(data);
+        if (result instanceof Promise) {
+          result.catch(
+            (err) => console.error(`Error in '${event}' handler:`, err)
+          );
+        }
+      } catch (err) {
+        console.error(`Error in '${event}' handler:`, err);
+      }
+    }
+  }
+  /**
+   * Start receiving captions from the stream.
+   *
+   * @returns Promise that resolves when connected.
+   */
+  async connect() {
+    this._intentionalClose = false;
+    let params = `uniqueId=${this.uniqueId}&apiKey=${this.apiKey}`;
+    if (this.translate) params += `&translate=${this.translate}`;
+    if (this.diarization) params += "&diarization=true";
+    if (this.maxDurationMinutes)
+      params += `&max_duration_minutes=${this.maxDurationMinutes}`;
+    const uri = `${CAPTIONS_BASE}?${params}`;
+    return new Promise((resolve, reject) => {
+      this._ws = new import_ws2.default(uri, {
+        headers: { "User-Agent": `tiktok-live-api/${VERSION2}` }
+      });
+      this._ws.on("open", () => {
+        this._connected = true;
+        this._emit("connected", { uniqueId: this.uniqueId });
+        resolve();
+      });
+      this._ws.on("message", (raw) => {
+        try {
+          const event = JSON.parse(raw.toString());
+          const msgType = event.type || "unknown";
+          this._emit(msgType, event);
+        } catch {
+        }
+      });
+      this._ws.on("close", () => {
+        this._connected = false;
+        this._emit("disconnected", { uniqueId: this.uniqueId });
+      });
+      this._ws.on("error", (err) => {
+        this._emit("error", { error: err.message });
+        if (!this._connected) reject(err);
+      });
+    });
+  }
+  /** Stop receiving captions. */
+  disconnect() {
+    this._intentionalClose = true;
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+    this._connected = false;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TikTokCaptions,
+  TikTokLive
+});