@tiktool/live 2.9.0 → 2.10.0

package/dist/index.d.mts

@@ -291,6 +291,20 @@ interface TikTokLiveOptions {
      *   proxy: 'http://USER:PASS@p.webshare.io:80'
      */
     proxy?: string;
+    /**
+     * Connection mode.
+     *   - `'direct'` (default): SDK opens WebSocket directly to TikTok. TikTok
+     *      sees your IP. Cheapest on API quota. Limited to ~30 concurrent
+     *      streams per container before TikTok rate-limits.
+     *   - `'relayed'`: SDK connects to TikTools' managed relay
+     *      (`wss://api.tik.tools/?...`). We connect to TikTok on your behalf
+     *      from our rotated proxy pool. TikTok never sees your IP. No rate-
+     *      limit risk. Scales to thousands of concurrent streams.
+     *
+     * The decoded events emitted are identical in both modes — code that
+     * uses `client.on('chat', e => ...)` works without changes.
+     */
+    mode?: 'direct' | 'relayed';
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -315,6 +329,7 @@ declare class TikTokLive extends EventEmitter {
     private readonly _presetRoomId;
     private readonly _presetSessionId;
     private readonly proxyUrl;
+    private readonly mode;
     constructor(options: TikTokLiveOptions);
     /**
      * Build an HttpsProxyAgent when `proxy` option is set, else undefined.
@@ -367,6 +382,13 @@ declare class TikTokLive extends EventEmitter {
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;
+    /**
+     * Relayed-mode connect. Opens a plain WebSocket to TikTools' managed relay
+     * endpoint. Events arrive pre-decoded as `{event, data}` JSON envelopes.
+     * The SDK re-emits them on the same event names as Direct mode so user
+     * code is identical regardless of mode.
+     */
+    private _connectRelayed;
 }
 
 export { type BaseEvent, type BattleArmiesEvent, type BattleContributor, type BattleEvent, type BattleHost, type BattleItemCardEvent, type BattleTeam, type BattleTeamUser, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EnvelopeEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type StreamInfo, type StreamQuality, type StreamUrls, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };

package/dist/index.d.ts

@@ -291,6 +291,20 @@ interface TikTokLiveOptions {
      *   proxy: 'http://USER:PASS@p.webshare.io:80'
      */
     proxy?: string;
+    /**
+     * Connection mode.
+     *   - `'direct'` (default): SDK opens WebSocket directly to TikTok. TikTok
+     *      sees your IP. Cheapest on API quota. Limited to ~30 concurrent
+     *      streams per container before TikTok rate-limits.
+     *   - `'relayed'`: SDK connects to TikTools' managed relay
+     *      (`wss://api.tik.tools/?...`). We connect to TikTok on your behalf
+     *      from our rotated proxy pool. TikTok never sees your IP. No rate-
+     *      limit risk. Scales to thousands of concurrent streams.
+     *
+     * The decoded events emitted are identical in both modes — code that
+     * uses `client.on('chat', e => ...)` works without changes.
+     */
+    mode?: 'direct' | 'relayed';
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -315,6 +329,7 @@ declare class TikTokLive extends EventEmitter {
     private readonly _presetRoomId;
     private readonly _presetSessionId;
     private readonly proxyUrl;
+    private readonly mode;
     constructor(options: TikTokLiveOptions);
     /**
      * Build an HttpsProxyAgent when `proxy` option is set, else undefined.
@@ -367,6 +382,13 @@ declare class TikTokLive extends EventEmitter {
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;
+    /**
+     * Relayed-mode connect. Opens a plain WebSocket to TikTools' managed relay
+     * endpoint. Events arrive pre-decoded as `{event, data}` JSON envelopes.
+     * The SDK re-emits them on the same event names as Direct mode so user
+     * code is identical regardless of mode.
+     */
+    private _connectRelayed;
 }
 
 export { type BaseEvent, type BattleArmiesEvent, type BattleContributor, type BattleEvent, type BattleHost, type BattleItemCardEvent, type BattleTeam, type BattleTeamUser, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EnvelopeEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type StreamInfo, type StreamQuality, type StreamUrls, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };

package/dist/index.js

@@ -2147,6 +2147,7 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
   _presetRoomId;
   _presetSessionId;
   proxyUrl;
+  mode;
   constructor(options) {
     super();
     this.setMaxListeners(20);
@@ -2161,6 +2162,7 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
     this._presetRoomId = options.roomId || "";
     this._presetSessionId = options.sessionId || "";
     this.proxyUrl = options.proxy || "";
+    this.mode = options.mode || "direct";
   }
   /**
    * Build an HttpsProxyAgent when `proxy` option is set, else undefined.
@@ -2180,6 +2182,9 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
   async connect() {
     if (this._destroyed) throw new Error("Client has been destroyed. Create a new instance.");
     this.intentionalClose = false;
+    if (this.mode === "relayed") {
+      return this._connectRelayed();
+    }
     let ttwid = this._presetSessionId;
     let roomId = this._presetRoomId;
     let clusterRegion = "";
@@ -2635,6 +2640,73 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
       this.heartbeatTimer = null;
     }
   }
+  /**
+   * Relayed-mode connect. Opens a plain WebSocket to TikTools' managed relay
+   * endpoint. Events arrive pre-decoded as `{event, data}` JSON envelopes.
+   * The SDK re-emits them on the same event names as Direct mode so user
+   * code is identical regardless of mode.
+   */
+  async _connectRelayed() {
+    const host = this.signServerUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
+    const wsUrl = `${host}/?uniqueId=${encodeURIComponent(this.uniqueId)}&apiKey=${encodeURIComponent(this.apiKey)}`;
+    if (this.debug) console.log(`[TikTokLive] Relayed mode: ${wsUrl.replace(this.apiKey, "***")}`);
+    return new Promise((resolve, reject) => {
+      this.ws = new import_ws.default(wsUrl);
+      let firstOpen = true;
+      this.ws.on("open", () => {
+        this._connected = true;
+        this.reconnectAttempts = 0;
+        if (firstOpen) {
+          firstOpen = false;
+          resolve();
+        }
+        this.emit("connected");
+      });
+      this.ws.on("message", (raw) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          if (typeof msg !== "object" || !msg) return;
+          const evName = msg.event;
+          const evData = msg.data ?? msg;
+          if (!evName) return;
+          if (evName === "connected" || evName === "_journal" || evName === "ping" || evName === "pong") return;
+          if (evName === "roomInfo") {
+            const ri = {
+              roomId: evData.roomId || "",
+              wsHost: evData.wsHost || "",
+              clusterRegion: evData.clusterRegion || "",
+              connectedAt: evData.connectedAt || (/* @__PURE__ */ new Date()).toISOString()
+            };
+            this.emit("roomInfo", ri);
+            return;
+          }
+          this.emit(evName, evData);
+          this.emit("event", evData);
+        } catch {
+        }
+      });
+      this.ws.on("close", (code, reason) => {
+        this._connected = false;
+        const reasonStr = reason?.toString() || "";
+        this.emit("disconnected", code, reasonStr);
+        if (!this.intentionalClose && this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+          this.reconnectAttempts++;
+          const delay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts), 3e4);
+          if (this.debug) console.log(`[TikTokLive] Relayed reconnect in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+          setTimeout(() => {
+            this._connectRelayed().catch(() => {
+            });
+          }, delay);
+        }
+      });
+      this.ws.on("error", (err) => {
+        if (firstOpen) {
+          firstOpen = false;
+          reject(err);
+        } else this.emit("error", err);
+      });
+    });
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {