tiktok-live-api 1.2.18 → 2.0.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import WebSocket from 'ws';
+
 /**
  * Type definitions for TikTok LIVE API events.
  *
@@ -54,12 +56,12 @@ interface SocialEvent {
     user: TikTokUser;
     eventType: string;
 }
-/** Payload for `roomUserSeq` (viewer count) events. */
+/** Payload for `roomUserSeq` / `roomUser` (viewer count) events. */
 interface RoomUserSeqEvent {
     viewerCount: number;
     topViewers: TikTokUser[];
 }
-/** Payload for `battle` events. */
+/** Payload for `battle` / `linkMicBattle` events. */
 interface BattleEvent {
     type: string;
     teams: Array<Record<string, unknown>>;
@@ -84,6 +86,60 @@ interface RoomPinEvent {
     /** User ID of the operator who pinned the message. */
     operatorUserId: string;
 }
+/** Payload for `superFan` events. */
+interface SuperFanEvent {
+    user: TikTokUser;
+    level: number;
+    displayType: string;
+}
+/** Payload for `superFanJoin` events. */
+interface SuperFanJoinEvent {
+    user: TikTokUser;
+    displayType: string;
+}
+/** Payload for `superFanBox` events. */
+interface SuperFanBoxEvent {
+    user: TikTokUser;
+    envelopeId: string;
+    diamondCount: number;
+}
+/** Payload for `barrage` events. */
+interface BarrageEvent {
+    user: TikTokUser;
+    label: string;
+    displayType: string;
+    content: string;
+}
+/** Payload for `emoteChat` / `emote` events. */
+interface EmoteChatEvent {
+    user: TikTokUser;
+    emoteId: string;
+    emoteUrl: string;
+}
+/** Payload for `question` / `questionNew` events. */
+interface QuestionEvent {
+    user: TikTokUser;
+    questionText: string;
+}
+/** Payload for `control` events. */
+interface ControlEvent {
+    action: number;
+}
+/** Payload for `liveIntro` events. */
+interface LiveIntroEvent {
+    title: string;
+    [key: string]: unknown;
+}
+/** Payload for `rankUpdate` events. */
+interface RankUpdateEvent {
+    rankType: string;
+    [key: string]: unknown;
+}
+/** Payload for `linkMic` events. */
+interface LinkMicEvent {
+    action: string;
+    [key: string]: unknown;
+}
 /** Payload for `caption` events from {@link TikTokCaptions}. */
 interface CaptionEvent {
     text: string;
@@ -117,6 +173,8 @@ interface ErrorEvent {
 }
 /**
  * Map of event names to their payload types for {@link TikTokLive}.
+ *
+ * Includes native TikTools events and TTLC-compatible aliases.
  */
 interface TikTokLiveEventMap {
     chat: ChatEvent;
@@ -126,16 +184,47 @@ interface TikTokLiveEventMap {
     share: SocialEvent;
     member: MemberEvent;
     subscribe: SocialEvent;
+    social: SocialEvent;
     roomUserSeq: RoomUserSeqEvent;
     battle: BattleEvent;
     roomPin: RoomPinEvent;
     envelope: Record<string, unknown>;
     streamEnd: Record<string, unknown>;
     roomInfo: Record<string, unknown>;
+    emoteChat: EmoteChatEvent;
+    question: QuestionEvent;
+    control: ControlEvent;
+    liveIntro: LiveIntroEvent;
+    rankUpdate: RankUpdateEvent;
+    linkMic: LinkMicEvent;
+    battleArmies: Record<string, unknown>;
+    room: Record<string, unknown>;
+    unknown: Record<string, unknown>;
+    superFan: SuperFanEvent;
+    superFanJoin: SuperFanJoinEvent;
+    superFanBox: SuperFanBoxEvent;
+    barrage: BarrageEvent;
+    /** @alias roomUserSeq */
+    roomUser: RoomUserSeqEvent;
+    /** @alias question */
+    questionNew: QuestionEvent;
+    /** @alias battle */
+    linkMicBattle: BattleEvent;
+    /** @alias battleArmies */
+    linkMicArmies: Record<string, unknown>;
+    /** @alias emoteChat */
+    emote: EmoteChatEvent;
     connected: ConnectedEvent;
     disconnected: DisconnectedEvent;
     error: ErrorEvent;
+    /** Catch-all: fires for every incoming event with full raw payload. */
     event: Record<string, unknown>;
+    /** rawData: fires for every event (TTLC compat). Same as `event`. */
+    rawData: Record<string, unknown>;
+    /** decodedData: fires for every event (TTLC compat). Same as `event`. */
+    decodedData: Record<string, unknown>;
+    /** websocketConnected: fires when WS connects (TTLC compat). */
+    websocketConnected: Record<string, unknown>;
 }
 /**
  * Map of event names to their payload types for {@link TikTokCaptions}.
@@ -177,10 +266,28 @@ interface TikTokCaptionsEventMap {
 interface TikTokLiveOptions {
     /** Your TikTool API key. Get one free at https://tik.tools */
     apiKey?: string;
+    /**
+     * Euler Stream API key — for users migrating from TikTok-Live-Connector.
+     * If provided and `apiKey` is not set, this is used as the API key.
+     * @alias apiKey
+     */
+    signApiKey?: string;
     /** Auto-reconnect on disconnect (default: true). */
     autoReconnect?: boolean;
     /** Max reconnection attempts (default: 5). */
     maxReconnectAttempts?: number;
+    /** @deprecated Handled server-side. Accepted for TTLC compatibility. */
+    processInitialData?: boolean;
+    /** @deprecated Handled server-side. Accepted for TTLC compatibility. */
+    fetchRoomInfoOnConnect?: boolean;
+    /** @deprecated Always enabled server-side. Accepted for TTLC compatibility. */
+    enableExtendedGiftInfo?: boolean;
+    /** @deprecated Accepted for TTLC compatibility. */
+    enableWebsocketUpgrade?: boolean;
+    /** @deprecated Accepted for TTLC compatibility. */
+    requestPollingIntervalMs?: number;
+    /** TikTok session ID for authenticated features. */
+    sessionId?: string;
 }
 type EventHandler$1<T> = (data: T) => void | Promise<void>;
 /**
@@ -203,12 +310,14 @@ declare class TikTokLive {
     readonly autoReconnect: boolean;
     /** Maximum reconnection attempts. */
     readonly maxReconnectAttempts: number;
-    private _handlers;
-    private _ws;
-    private _connected;
-    private _intentionalClose;
-    private _reconnectAttempts;
-    private _eventCount;
+    protected _handlers: Map<string, Set<EventHandler$1<any>>>;
+    protected _ws: WebSocket | null;
+    protected _connected: boolean;
+    protected _intentionalClose: boolean;
+    protected _reconnectAttempts: number;
+    protected _eventCount: number;
+    protected _roomId: string;
+    protected _roomInfo: Record<string, any> | null;
     /**
      * Create a new TikTokLive client.
      *
@@ -228,15 +337,16 @@ declare class TikTokLive {
     /**
      * Register an event handler.
      *
+     * Supports both native TikTools event names and TTLC-compatible aliases:
+     * - `roomUser` → `roomUserSeq`
+     * - `questionNew` → `question`
+     * - `linkMicBattle` → `battle`
+     * - `linkMicArmies` → `battleArmies`
+     * - `emote` → `emoteChat`
+     *
      * @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;
@@ -247,7 +357,7 @@ declare class TikTokLive {
      * @param handler - The handler to remove
      */
     off(event: string, handler: EventHandler$1<any>): this;
-    private _emit;
+    protected _emit(event: string, data: any): void;
     /**
      * Connect to the TikTok LIVE stream.
      *
@@ -263,6 +373,19 @@ declare class TikTokLive {
      * Disconnect from the stream.
      */
     disconnect(): void;
+    /**
+     * Get current connection state (TTLC-compatible).
+     */
+    getState(): {
+        isConnected: boolean;
+        roomId: string;
+        roomInfo: Record<string, any> | null;
+        uniqueId: string;
+    };
+    /**
+     * Get room info (TTLC-compatible).
+     */
+    getRoomInfo(): Record<string, any> | null;
     private _maybeReconnect;
 }
 
@@ -371,4 +494,140 @@ declare class TikTokCaptions {
     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 };
+/**
+ * TikTok-Live-Connector (TTLC) compatibility layer.
+ *
+ * Drop-in replacement for `WebcastPushConnection` from `tiktok-live-connector`.
+ * Users can switch to TikTools by changing a single import line:
+ *
+ * ```diff
+ * - const { WebcastPushConnection } = require('tiktok-live-connector');
+ * + const { WebcastPushConnection } = require('tiktok-live-api');
+ * ```
+ *
+ * All TTLC event names, constructor options, and methods are supported.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Control events matching TikTok-Live-Connector's ControlEvents.
+ */
+declare const ControlEvents: {
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly ERROR: "error";
+    readonly RAWDATA: "rawData";
+    readonly DECODEDDATA: "decodedData";
+    readonly STREAMEND: "streamEnd";
+    readonly WSCONNECTED: "websocketConnected";
+};
+/**
+ * Message events matching TikTok-Live-Connector's MessageEvents.
+ */
+declare const MessageEvents: {
+    readonly CHAT: "chat";
+    readonly MEMBER: "member";
+    readonly GIFT: "gift";
+    readonly ROOMUSER: "roomUser";
+    readonly SOCIAL: "social";
+    readonly LIKE: "like";
+    readonly QUESTIONNEW: "questionNew";
+    readonly LINKMICBATTLE: "linkMicBattle";
+    readonly LINKMICARMIES: "linkMicArmies";
+    readonly LIVEINTRO: "liveIntro";
+    readonly EMOTE: "emote";
+    readonly ENVELOPE: "envelope";
+    readonly SUBSCRIBE: "subscribe";
+    readonly BARRAGE: "barrage";
+    readonly SUPERFAN: "superFan";
+    readonly SUPERFANJOIN: "superFanJoin";
+    readonly SUPERFANBOX: "superFanBox";
+    readonly ROOMPIN: "roomPin";
+};
+/**
+ * Custom events matching TikTok-Live-Connector's CustomEvents.
+ */
+declare const CustomEvents: {
+    readonly FOLLOW: "follow";
+    readonly SHARE: "share";
+};
+interface WebcastPushConnectionOptions extends TikTokLiveOptions {
+    /** Euler Stream API key (maps to TikTools apiKey). */
+    signApiKey?: string;
+    /** @deprecated Handled server-side. Accepted for compatibility. */
+    processInitialData?: boolean;
+    /** @deprecated Handled server-side. Accepted for compatibility. */
+    fetchRoomInfoOnConnect?: boolean;
+    /** @deprecated Always enabled. Accepted for compatibility. */
+    enableExtendedGiftInfo?: boolean;
+    /** @deprecated Always true. Accepted for compatibility. */
+    enableWebsocketUpgrade?: boolean;
+    /** @deprecated Not used. Accepted for compatibility. */
+    enableRequestPolling?: boolean;
+    /** @deprecated Not used. Accepted for compatibility. */
+    requestPollingIntervalMs?: number;
+    /** TikTok session ID. */
+    sessionId?: string;
+    /** @deprecated Not used. Accepted for compatibility. */
+    clientParams?: Record<string, any>;
+    /** @deprecated Not used. Accepted for compatibility. */
+    requestHeaders?: Record<string, string>;
+    /** @deprecated Not used. Accepted for compatibility. */
+    websocketHeaders?: Record<string, string>;
+    /** @deprecated Not used. Accepted for compatibility. */
+    requestOptions?: Record<string, any>;
+    /** @deprecated Not used. Accepted for compatibility. */
+    websocketOptions?: Record<string, any>;
+    /** @deprecated Not used. Accepted for compatibility. */
+    signProviderOptions?: Record<string, any>;
+}
+/**
+ * Drop-in replacement for TikTok-Live-Connector's `WebcastPushConnection`.
+ *
+ * Accepts the exact same constructor signature and event names.
+ * Under the hood, connects to the TikTools managed WebSocket API
+ * for 99.9% uptime and zero maintenance.
+ *
+ * @example
+ * ```typescript
+ * // Before (TikTok-Live-Connector):
+ * // const { WebcastPushConnection } = require('tiktok-live-connector');
+ *
+ * // After (TikTools — one-line change):
+ * const { WebcastPushConnection } = require('tiktok-live-api');
+ *
+ * const connection = new WebcastPushConnection('username', {
+ *   signApiKey: 'YOUR_TIKTOOL_API_KEY', // Get free at tik.tools
+ * });
+ *
+ * connection.on('chat', (data) => {
+ *   console.log(`${data.uniqueId}: ${data.comment}`);
+ * });
+ *
+ * connection.connect();
+ * ```
+ */
+declare class WebcastPushConnection extends TikTokLive {
+    constructor(uniqueId: string, options?: WebcastPushConnectionOptions);
+    /**
+     * Get current connection state — TTLC-compatible shape.
+     *
+     * Returns the same structure as TikTok-Live-Connector's `getState()`.
+     */
+    getState(): {
+        isConnected: boolean;
+        upgradedToWebsocket: boolean;
+        roomId: string;
+        roomInfo: Record<string, any> | null;
+        availableGifts: never[];
+        uniqueId: string;
+    };
+    /**
+     * Get available gifts — TTLC-compatible.
+     * Note: Gift info is included in event payloads automatically.
+     */
+    getAvailableGifts(): any[];
+}
+
+export { type BarrageEvent, type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type ControlEvent, ControlEvents, type CreditsEvent, CustomEvents, type DisconnectedEvent, type EmoteChatEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveIntroEvent, type MemberEvent, MessageEvents, type QuestionEvent, type RankUpdateEvent, type RoomPinEvent, type RoomUserSeqEvent, type SocialEvent, type SuperFanBoxEvent, type SuperFanEvent, type SuperFanJoinEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, type TranslationEvent, WebcastPushConnection, type WebcastPushConnectionOptions };

package/dist/index.js

@@ -30,15 +30,32 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ControlEvents: () => ControlEvents,
+  CustomEvents: () => CustomEvents,
+  MessageEvents: () => MessageEvents,
   TikTokCaptions: () => TikTokCaptions,
-  TikTokLive: () => TikTokLive
+  TikTokLive: () => TikTokLive,
+  WebcastPushConnection: () => WebcastPushConnection
 });
 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 VERSION = "2.0.0";
+var EVENT_ALIASES = {
+  roomUserSeq: ["roomUser"],
+  question: ["questionNew"],
+  battle: ["linkMicBattle"],
+  battleArmies: ["linkMicArmies"],
+  emoteChat: ["emote"]
+};
+var REVERSE_ALIASES = {};
+for (const [native, aliases] of Object.entries(EVENT_ALIASES)) {
+  for (const alias of aliases) {
+    REVERSE_ALIASES[alias] = native;
+  }
+}
 var TikTokLive = class {
   /**
    * Create a new TikTokLive client.
@@ -58,8 +75,10 @@ var TikTokLive = class {
     this._intentionalClose = false;
     this._reconnectAttempts = 0;
     this._eventCount = 0;
+    this._roomId = "";
+    this._roomInfo = null;
     this.uniqueId = uniqueId.replace(/^@/, "");
-    this.apiKey = options.apiKey || process.env.TIKTOOL_API_KEY || "";
+    this.apiKey = options.apiKey || options.signApiKey || process.env.TIKTOOL_API_KEY || "";
     if (!this.apiKey) {
       throw new Error("apiKey is required. Get a free key at https://tik.tools");
     }
@@ -75,10 +94,17 @@ var TikTokLive = class {
     return this._eventCount;
   }
   on(event, handler) {
-    if (!this._handlers.has(event)) {
-      this._handlers.set(event, /* @__PURE__ */ new Set());
+    const nativeEvent = REVERSE_ALIASES[event] || event;
+    if (!this._handlers.has(nativeEvent)) {
+      this._handlers.set(nativeEvent, /* @__PURE__ */ new Set());
+    }
+    this._handlers.get(nativeEvent).add(handler);
+    if (nativeEvent !== event) {
+      if (!this._handlers.has(event)) {
+        this._handlers.set(event, /* @__PURE__ */ new Set());
+      }
+      this._handlers.get(event).add(handler);
     }
-    this._handlers.get(event).add(handler);
     return this;
   }
   /**
@@ -88,22 +114,47 @@ var TikTokLive = class {
    * @param handler - The handler to remove
    */
   off(event, handler) {
-    this._handlers.get(event)?.delete(handler);
+    const nativeEvent = REVERSE_ALIASES[event] || event;
+    this._handlers.get(nativeEvent)?.delete(handler);
+    if (nativeEvent !== event) {
+      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)
-          );
+    if (handlers) {
+      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);
+        }
+      }
+    }
+    const aliases = EVENT_ALIASES[event];
+    if (aliases) {
+      for (const alias of aliases) {
+        const aliasHandlers = this._handlers.get(alias);
+        if (aliasHandlers) {
+          for (const handler of aliasHandlers) {
+            try {
+              const result = handler(data);
+              if (result instanceof Promise) {
+                result.catch(
+                  (err) => console.error(`Error in '${alias}' handler:`, err)
+                );
+              }
+            } catch (err) {
+              console.error(`Error in '${alias}' handler:`, err);
+            }
+          }
         }
-      } catch (err) {
-        console.error(`Error in '${event}' handler:`, err);
       }
     }
   }
@@ -128,6 +179,7 @@ var TikTokLive = class {
         this._connected = true;
         this._reconnectAttempts = 0;
         this._emit("connected", { uniqueId: this.uniqueId });
+        this._emit("websocketConnected", { uniqueId: this.uniqueId });
         resolve();
       });
       this._ws.on("message", (raw) => {
@@ -136,14 +188,27 @@ var TikTokLive = class {
           this._eventCount++;
           const eventType = event.event || "unknown";
           const data = event.data || event;
+          if (eventType === "roomInfo") {
+            this._roomId = event.roomId || data.roomId || this._roomId;
+            this._roomInfo = data;
+          }
           this._emit("event", event);
+          this._emit("rawData", event);
+          this._emit("decodedData", event);
           this._emit(eventType, data);
+          if (eventType === "control" && data.action === 3) {
+            this._emit("streamEnd", data);
+          }
         } catch {
         }
       });
-      this._ws.on("close", () => {
+      this._ws.on("close", (code, reason) => {
         this._connected = false;
-        this._emit("disconnected", { uniqueId: this.uniqueId });
+        this._emit("disconnected", {
+          uniqueId: this.uniqueId,
+          code,
+          reason: reason?.toString()
+        });
         this._maybeReconnect();
       });
       this._ws.on("error", (err) => {
@@ -163,6 +228,23 @@ var TikTokLive = class {
     }
     this._connected = false;
   }
+  /**
+   * Get current connection state (TTLC-compatible).
+   */
+  getState() {
+    return {
+      isConnected: this._connected,
+      roomId: this._roomId,
+      roomInfo: this._roomInfo,
+      uniqueId: this.uniqueId
+    };
+  }
+  /**
+   * Get room info (TTLC-compatible).
+   */
+  getRoomInfo() {
+    return this._roomInfo;
+  }
   async _maybeReconnect() {
     if (this._intentionalClose || !this.autoReconnect || this._reconnectAttempts >= this.maxReconnectAttempts) {
       return;
@@ -284,8 +366,78 @@ var TikTokCaptions = class {
     this._connected = false;
   }
 };
+
+// src/compat.ts
+var ControlEvents = {
+  CONNECTED: "connected",
+  DISCONNECTED: "disconnected",
+  ERROR: "error",
+  RAWDATA: "rawData",
+  DECODEDDATA: "decodedData",
+  STREAMEND: "streamEnd",
+  WSCONNECTED: "websocketConnected"
+};
+var MessageEvents = {
+  CHAT: "chat",
+  MEMBER: "member",
+  GIFT: "gift",
+  ROOMUSER: "roomUser",
+  SOCIAL: "social",
+  LIKE: "like",
+  QUESTIONNEW: "questionNew",
+  LINKMICBATTLE: "linkMicBattle",
+  LINKMICARMIES: "linkMicArmies",
+  LIVEINTRO: "liveIntro",
+  EMOTE: "emote",
+  ENVELOPE: "envelope",
+  SUBSCRIBE: "subscribe",
+  BARRAGE: "barrage",
+  SUPERFAN: "superFan",
+  SUPERFANJOIN: "superFanJoin",
+  SUPERFANBOX: "superFanBox",
+  ROOMPIN: "roomPin"
+};
+var CustomEvents = {
+  FOLLOW: "follow",
+  SHARE: "share"
+};
+var WebcastPushConnection = class extends TikTokLive {
+  constructor(uniqueId, options = {}) {
+    const opts = {
+      ...options,
+      apiKey: options.apiKey || options.signApiKey
+    };
+    super(uniqueId, opts);
+  }
+  /**
+   * Get current connection state — TTLC-compatible shape.
+   *
+   * Returns the same structure as TikTok-Live-Connector's `getState()`.
+   */
+  getState() {
+    return {
+      isConnected: this._connected,
+      upgradedToWebsocket: this._connected,
+      roomId: this._roomId,
+      roomInfo: this._roomInfo,
+      availableGifts: [],
+      uniqueId: this.uniqueId
+    };
+  }
+  /**
+   * Get available gifts — TTLC-compatible.
+   * Note: Gift info is included in event payloads automatically.
+   */
+  getAvailableGifts() {
+    return [];
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ControlEvents,
+  CustomEvents,
+  MessageEvents,
   TikTokCaptions,
-  TikTokLive
+  TikTokLive,
+  WebcastPushConnection
 });