@tiktool/live 2.9.0 → 2.10.1

package/README.md

@@ -97,22 +97,42 @@ Install `https-proxy-agent` if using `proxy`:
 npm install https-proxy-agent
 ```
 
-### Mode 2 — Relayed (via our proxy pool, no SDK install)
+### Mode 2 — Relayed (via our proxy pool)
 
 ```
-  Your App  ◀──── wss://api.tik.tools/?uniqueId=X&apiKey=Y ────  tik.tools
-                                                                     │
-                                                                     │ WS via
-                                                                     │ rotated proxies
-                                                                     ▼
-                                                                  TikTok
+  Your App  ◀──── wss://api.tik.tools/?... ────  tik.tools
+                                                      │
+                                                      │ WS via
+                                                      │ rotated proxies
+                                                      ▼
+                                                   TikTok
 ```
 
 - **TikTok sees our IPs** (rotated across hundreds of Webshare + residential proxies).
 - We absorb every per-IP rate-limit hit. Survives any block automatically.
 - Best for **30+ concurrent streams**, low-budget setups, or anyone who doesn't want their own IP fingerprinted by TikTok.
-- Costs slightly more per stream-hour (events stream through us, not signed-once direct).
-- No SDK install — plain `WebSocket`. Events arrive pre-parsed as JSON.
+
+**Easiest — same SDK, one option:**
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({
+    uniqueId: 'creator_username',
+    apiKey: 'YOUR_KEY',
+    mode: 'relayed',  // ← that's it
+});
+
+live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
+live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName}`));
+live.on('battleArmies', e => console.log(e));
+
+await live.connect();
+```
+
+Event names + payload shapes are **identical to Direct mode**. Switch back and forth by toggling `mode`.
+
+**Advanced — raw WebSocket (no SDK, your own client):**
 
 ```typescript
 import WebSocket from 'ws';
@@ -124,12 +144,12 @@ const ws = new WebSocket(
 ws.on('message', raw => {
     const msg = JSON.parse(raw.toString());
     if (msg.event === 'chat')         console.log(msg.data.user.uniqueId, msg.data.comment);
-    if (msg.event === 'gift')         console.log(msg.data.user.uniqueId, msg.data.giftName, msg.data.diamondCount);
+    if (msg.event === 'gift')         console.log(msg.data.user.uniqueId, msg.data.giftName);
     if (msg.event === 'battleArmies') console.log(msg.data);
 });
 ```
 
-Event payloads are identical to Direct-mode `client.on('chat', …)` etc. — only the wrapping changes (`{event, data}` envelope vs the SDK's separate emit).
+Use this when integrating from a non-Node runtime (Python, Go, Bun, browser) or when you want absolute control over the connection.
 
 ### Side-by-side
 
@@ -318,6 +338,8 @@ live.on('battle', (e) => {
 | `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
 | `roomId` | `string` | — | Pre-resolved room ID (skips page fetch when paired with `sessionId`) |
 | `sessionId` | `string` | — | Pre-resolved `ttwid` cookie (skips page fetch when paired with `roomId`) |
+| `proxy` | `string` | — | HTTP(S) proxy URL for Direct mode (e.g. `http://USER:PASS@host:port`). Requires `https-proxy-agent`. |
+| `mode` | `'direct' \| 'relayed'` | `'direct'` | Connection mode. See [Connection Modes](#connection-modes). |
 | `debug` | `boolean` | `false` | Debug logging |
 
 ### Methods
@@ -331,6 +353,32 @@ live.on('battle', (e) => {
 | `eventCount` | `number` | Total events received |
 | `roomId` | `string` | Current room ID |
 
+### REST endpoints (companion to the WS SDK)
+
+For lookups outside the live event stream, hit the sign server directly with your API key:
+
+| Endpoint | Method | Tier | Use case |
+|----------|--------|------|----------|
+| `/webcast/room_id` | POST | sandbox+ | `unique_id` → `room_id` |
+| `/webcast/room_info` | POST | sandbox+ | `unique_id` → `room_id` + `alive` + `title` |
+| `/webcast/check_alive` | GET/POST | sandbox+ | Is `room_id` currently live? |
+| `/webcast/bulk_live_check` | POST | basic+ | Batch check up to 500 users in one call |
+| `/webcast/live_status` | GET | sandbox+ | `unique_id` → live snapshot incl. viewer count |
+| `/webcast/user_profile` | GET | **pro+** | **`unique_id` → numeric `id`, `secUid`, nickname, bio, avatars, follower stats** |
+| `/webcast/resolve_user_ids` | POST | sandbox+ | Batch numeric `userId` → `unique_id` (reverse of `user_profile`) |
+| `/webcast/rankings` | GET | sandbox+ | Top gifters / hourly rank for a room |
+| `/webcast/room_video` | POST | basic+ | Get HLS / FLV stream URLs |
+| `/webcast/ws_credentials` | POST | sandbox+ | Get signed WS URL + ttwid (used by Direct mode under the hood) |
+
+**Need the streamer's numeric TikTok ID for a username?**
+
+```bash
+curl -H "X-Api-Key: YOUR_KEY" \
+  "https://api.tik.tools/webcast/user_profile?unique_id=anyuser"
+```
+
+Returns full profile JSON. Pro tier and above. Cached server-side for 24h — repeated lookups are free and instant.
+
 ---
 
 ## Rate Limits

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 = {