@tiktool/live 2.12.2 → 2.13.0

package/README.md

@@ -23,7 +23,7 @@ Real-time chat, gifts, viewers, **PK battles with MVP breakdown**, **x2/x3 boost
 npm install @tiktool/live
 ```
 
-Get your free API key at [tik.tools](https://tik.tools)
+Get an API key at [tik.tools](https://tik.tools/pricing) (7-day free evaluation).
 
 ```typescript
 import { TikTokLive } from '@tiktool/live';
@@ -69,7 +69,7 @@ await live.connect();
 
 There are **two ways** to receive TikTok LIVE events from `tik.tools`. Pick based on scale and IP-exposure tolerance.
 
-### Mode 1 — Direct (default, this SDK)
+### Mode 1 - Direct (default, this SDK)
 
 ```
   Your App  ──signs URL via──▶  tik.tools  ──returns signed URL──▶  Your App
@@ -78,7 +78,7 @@ There are **two ways** to receive TikTok LIVE events from `tik.tools`. Pick base
 ```
 
 - The signed WebSocket is opened from your runtime. TikTok sees the network identity of the host that runs the SDK.
-- Lowest per-stream cost — only the initial `ws_credentials` call is billed against your API key.
+- Lowest per-stream cost - only the initial `ws_credentials` call is billed against your API key.
 - Suited to **low- to mid-volume** workloads from a single host.
 - High-volume setups should prefer Mode 2 for predictable, centrally-managed egress.
 
@@ -97,7 +97,7 @@ If you set the optional `proxy` field, install the standard agent:
 npm install https-proxy-agent
 ```
 
-### Mode 2 — Relayed (via TikTools managed edge)
+### Mode 2 - Relayed (via TikTools managed edge)
 
 ```
   Your App  ◀──── wss://api.tik.tools/?... ────  tik.tools
@@ -108,10 +108,10 @@ npm install https-proxy-agent
 ```
 
 - The TikTools service handles the upstream TikTok session and forwards decoded events over a single WebSocket to your client.
-- Single, stable egress — your application connects only to `api.tik.tools`.
+- Single, stable egress - your application connects only to `api.tik.tools`.
 - Recommended for **production scale**, multi-tenant deployments, or any environment that already centralizes outbound traffic.
 
-**Easiest — same SDK, one option:**
+**Easiest - same SDK, one option:**
 
 ```typescript
 import { TikTokLive } from '@tiktool/live';
@@ -131,7 +131,7 @@ 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):**
+**Advanced - raw WebSocket (no SDK, your own client):**
 
 ```typescript
 import WebSocket from 'ws';
@@ -216,7 +216,7 @@ live.on('event', (event) => {
 This SDK fully parses TikTok PK (Player-vs-Killer) battle protobufs, including
 **multi-guest** matches with up to 4 hosts per side and per-gifter MVP scores.
 
-### `battleArmies` — score updates during a PK
+### `battleArmies` - score updates during a PK
 
 Emitted every few seconds while a PK is active. The new `hosts[]` array gives
 you the **per-host breakdown** with each gifter's contribution sorted **MVP
@@ -224,10 +224,10 @@ first** (highest score → lowest):
 
 ```typescript
 live.on('battleArmies', (e) => {
-    console.log(`PK ${e.battleId} — ${e.secsRemaining}s remaining`);
+    console.log(`PK ${e.battleId} - ${e.secsRemaining}s remaining`);
 
     for (const host of e.hosts ?? []) {
-        console.log(`  Host ${host.hostUserId} — total ${host.teamTotalScore}`);
+        console.log(`  Host ${host.hostUserId} - total ${host.teamTotalScore}`);
 
         // contributors[0] = MVP (highest gifter)
         for (const [i, c] of host.contributors.slice(0, 3).entries()) {
@@ -266,11 +266,11 @@ live.on('battleArmies', (e) => {
 | `durationSec` | `number` | Total battle duration |
 | `endTimeMs` | `number` | Battle end ms epoch (alias for `battleStartMs + duration*1000`) |
 
-### `battleItemCard` — boosters / power-ups during a PK
+### `battleItemCard` - boosters / power-ups during a PK
 
 Fired when a gifter activates a special card: x2/x3 multipliers, gloves
 (crit), mist, thunder, extra-time, or match-guide. Includes the **card art**
-URL straight from TikTok's CDN — drop it into an OBS overlay as-is.
+URL straight from TikTok's CDN - drop it into an OBS overlay as-is.
 
 ```typescript
 live.on('battleItemCard', (e) => {
@@ -280,7 +280,7 @@ live.on('battleItemCard', (e) => {
         console.log(`  x${e.multiplier} multiplier for ${e.durationSec}s`);
     }
 
-    // Use straight in an <img> tag — TikTok CDN
+    // Use straight in an <img> tag - TikTok CDN
     console.log(`  icon: ${e.iconUrl}`);
     console.log(`  accent: ${e.accentColor}`);
 });
@@ -307,7 +307,7 @@ live.on('battleItemCard', (e) => {
 | `iconKey` | `string` | Short id, e.g. `card_mist_v3`, `card_crit_v3`, `top3_buffer` |
 | `accentColor` | `string` | Hex color, e.g. `#BCD9E0` (mist blue), `#E0D4BC` (gloves tan) |
 
-### `battle` — PK lifecycle events
+### `battle` - PK lifecycle events
 
 Fired on start / status change / end. Use for PK ON/OFF banners.
 
@@ -327,15 +327,15 @@ live.on('battle', (e) => {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `uniqueId` | `string` | — | TikTok username (without @) |
-| `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
+| `uniqueId` | `string` | - | TikTok username (without @) |
+| `apiKey` | `string` | - | **Required.** API key from [tik.tools](https://tik.tools) |
 | `signServerUrl` | `string` | `https://api.tik.tools` | Sign server URL |
 | `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
 | `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
 | `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`. |
+| `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 |
 
@@ -393,7 +393,7 @@ 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.
+Returns full profile JSON. Pro tier and above. Cached server-side for 24h - repeated lookups are free and instant.
 
 ---
 
@@ -403,16 +403,17 @@ All API requests require an API key. Get yours at [tik.tools](https://tik.tools)
 
 | Tier | Price | Requests/day | WS Connections | Notes |
 |------|-------|--------------|----------------|-------|
-| **Community** | Free forever | 2,500 | 15 (2h per WS) | Masked leaderboards. No datacenter proxies — calls run from your own IP. |
-| **Pro** | from $59/mo | 75,000 | 50 (8h) | Unmasked leaderboards · CAPTCHA Solver · Feed Discovery · 5 AI caption streams · priority routing |
-| **Ultra** | from $219/mo | 300,000 | 250 (8h) | Unmasked leagues · 20 AI caption streams · 99.5% uptime SLA · priority chat support |
-| **Global Agency** | $549/mo | 300,000 | 500 + Firehose | Everything in Ultra + **Live Gifter Firehose WS** (region/league/global + min-diamond filters) + VIP Telegram alerts + VIP Web Vault |
+| **Sandbox** | Free, 7-day evaluation | 5,000 | 3 (2h per WS) | Masked leaderboards. No datacenter proxies - calls run from your own IP. Refused after 7 days from account creation (WS close 4401, REST 403). |
+| **Basic** | $7/wk or $19/mo | 10,000 | 20 (8h per WS) | Datacenter proxies, bulk live check |
+| **Pro** | $15/wk or $49/mo | 75,000 | 50 (12h per WS) | Unmasked leaderboards · CAPTCHA Solver · Feed Discovery · priority routing |
+| **Ultra** | $45/wk or $149/mo | 300,000 | 250 (24h per WS) | Unmasked leagues · priority chat support |
+| **Agency** | $119/wk or $399/mo | 1,000,000 | 500 (24h per WS) + Firehose | Everything in Ultra + **Live Gifter Firehose WS** (region/league/global + min-diamond filters) + VIP Telegram alerts + VIP Web Vault |
 
 The SDK calls the sign server **once per connection**, then stays connected
-via WebSocket. The free Community tier caps each WebSocket at 2 hours and
-is sufficient for most use cases.
+via WebSocket. Sandbox, the free 7-day evaluation, caps each WebSocket at 2 hours;
+paid plans allow 8 to 24 hours per connection.
 
-### Live Gifter Firehose — Global Agency
+### Live Gifter Firehose - Agency
 
 Real-time gift event stream from Dragonfly fan-out. Filter by region, league,
 or globally; cap by minimum diamond threshold. Mid-stream filter updates
@@ -474,7 +475,7 @@ live.on('battleArmies', e => {
     for (const host of e.hosts ?? []) {
         const top = host.contributors[0];
         console.log(`  ${host.hostUserId}: ${host.teamTotalScore}  ` +
-                    `(MVP: ${top?.nickname || top?.userId || '—'} ${top?.score ?? 0})`);
+                    `(MVP: ${top?.nickname || top?.userId || '-'} ${top?.score ?? 0})`);
     }
 });
 
@@ -570,10 +571,10 @@ live.on('battleItemCard', (event: BattleItemCardEvent) => {
 
 ### 2.8.0 (2026-05-19)
 
-- **NEW** `battleItemCard` event — x2/x3 boosters, gloves, mist, thunder,
+- **NEW** `battleItemCard` event - x2/x3 boosters, gloves, mist, thunder,
   extra-time, match-guide. Includes `iconUrl`, `iconKey`, `accentColor` for
   drop-in overlay use.
-- **NEW** `BattleArmiesEvent.hosts[]` — multi-guest PK breakdown with per-host
+- **NEW** `BattleArmiesEvent.hosts[]` - multi-guest PK breakdown with per-host
   `contributors[]` sorted **MVP first**.
 - **NEW** `matchId`, `sessionId`, `serverTsMs`, `sessionTag`, `secsRemaining`
   fields on `BattleArmiesEvent`.

package/dist/index.d.mts

@@ -45,7 +45,18 @@ interface GiftEvent extends BaseEvent {
     repeatEnd: boolean;
     combo: boolean;
     giftType: number;
+    /**
+     * TikTok's combo group id: the same on every frame of one combo. Follow a
+     * combo with (user.id, giftId, groupId) and take its highest repeatCount.
+     */
     groupId: string;
+    /**
+     * Who received the gift, as a full-precision string: the host, or the
+     * guest in a multi-guest LIVE. '' when the frame did not state it.
+     */
+    toUserId: string;
+    /** Same as `toUserId`; matches the field name used by the relay events. */
+    receiverUserId: string;
 }
 interface SocialEvent extends BaseEvent {
     type: 'social';
@@ -55,6 +66,7 @@ interface SocialEvent extends BaseEvent {
 interface RoomUserSeqEvent extends BaseEvent {
     type: 'roomUserSeq';
     viewerCount: number;
+    /** TikTok's running viewer total for this LIVE; restarts with a new LIVE. */
     totalViewers: number;
 }
 interface BattleTeamUser {
@@ -230,6 +242,12 @@ interface TikTokLiveEvents {
     envelope: (event: EnvelopeEvent) => void;
     question: (event: QuestionEvent) => void;
     control: (event: ControlEvent) => void;
+    /** The host ended the LIVE (TikTok control action 3, or the relay's confirmed end). */
+    streamEnd: (event: {
+        type: 'streamEnd';
+        uniqueId: string;
+        reason: string;
+    }) => void;
     room: (event: RoomEvent) => void;
     liveIntro: (event: LiveIntroEvent) => void;
     rankUpdate: (event: RankUpdateEvent) => void;
@@ -444,6 +462,7 @@ declare class TikTokLive extends EventEmitter {
      * Resolve unknown host user IDs via the sign server API.
      * Caches results and re-emits the battleArmies event with enriched hostUser data.
      */
+    private _hostResolveUnavailable;
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/index.d.ts

@@ -45,7 +45,18 @@ interface GiftEvent extends BaseEvent {
     repeatEnd: boolean;
     combo: boolean;
     giftType: number;
+    /**
+     * TikTok's combo group id: the same on every frame of one combo. Follow a
+     * combo with (user.id, giftId, groupId) and take its highest repeatCount.
+     */
     groupId: string;
+    /**
+     * Who received the gift, as a full-precision string: the host, or the
+     * guest in a multi-guest LIVE. '' when the frame did not state it.
+     */
+    toUserId: string;
+    /** Same as `toUserId`; matches the field name used by the relay events. */
+    receiverUserId: string;
 }
 interface SocialEvent extends BaseEvent {
     type: 'social';
@@ -55,6 +66,7 @@ interface SocialEvent extends BaseEvent {
 interface RoomUserSeqEvent extends BaseEvent {
     type: 'roomUserSeq';
     viewerCount: number;
+    /** TikTok's running viewer total for this LIVE; restarts with a new LIVE. */
     totalViewers: number;
 }
 interface BattleTeamUser {
@@ -230,6 +242,12 @@ interface TikTokLiveEvents {
     envelope: (event: EnvelopeEvent) => void;
     question: (event: QuestionEvent) => void;
     control: (event: ControlEvent) => void;
+    /** The host ended the LIVE (TikTok control action 3, or the relay's confirmed end). */
+    streamEnd: (event: {
+        type: 'streamEnd';
+        uniqueId: string;
+        reason: string;
+    }) => void;
     room: (event: RoomEvent) => void;
     liveIntro: (event: LiveIntroEvent) => void;
     rankUpdate: (event: RankUpdateEvent) => void;
@@ -444,6 +462,7 @@ declare class TikTokLive extends EventEmitter {
      * Resolve unknown host user IDs via the sign server API.
      * Caches results and re-emits the battleArmies event with enriched hostUser data.
      */
+    private _hostResolveUnavailable;
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/index.js

@@ -496,6 +496,121 @@ var require_browser = __commonJS({
   }
 });
 
+// ../../node_modules/has-flag/index.js
+var require_has_flag = __commonJS({
+  "../../node_modules/has-flag/index.js"(exports2, module2) {
+    "use strict";
+    module2.exports = (flag, argv = process.argv) => {
+      const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
+      const position = argv.indexOf(prefix + flag);
+      const terminatorPosition = argv.indexOf("--");
+      return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
+    };
+  }
+});
+
+// ../../node_modules/supports-color/index.js
+var require_supports_color = __commonJS({
+  "../../node_modules/supports-color/index.js"(exports2, module2) {
+    "use strict";
+    var os = require("os");
+    var tty = require("tty");
+    var hasFlag = require_has_flag();
+    var { env } = process;
+    var forceColor;
+    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
+      forceColor = 0;
+    } else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) {
+      forceColor = 1;
+    }
+    if ("FORCE_COLOR" in env) {
+      if (env.FORCE_COLOR === "true") {
+        forceColor = 1;
+      } else if (env.FORCE_COLOR === "false") {
+        forceColor = 0;
+      } else {
+        forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
+      }
+    }
+    function translateLevel(level) {
+      if (level === 0) {
+        return false;
+      }
+      return {
+        level,
+        hasBasic: true,
+        has256: level >= 2,
+        has16m: level >= 3
+      };
+    }
+    function supportsColor(haveStream, streamIsTTY) {
+      if (forceColor === 0) {
+        return 0;
+      }
+      if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) {
+        return 3;
+      }
+      if (hasFlag("color=256")) {
+        return 2;
+      }
+      if (haveStream && !streamIsTTY && forceColor === void 0) {
+        return 0;
+      }
+      const min = forceColor || 0;
+      if (env.TERM === "dumb") {
+        return min;
+      }
+      if (process.platform === "win32") {
+        const osRelease = os.release().split(".");
+        if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
+          return Number(osRelease[2]) >= 14931 ? 3 : 2;
+        }
+        return 1;
+      }
+      if ("CI" in env) {
+        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI", "GITHUB_ACTIONS", "BUILDKITE"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
+          return 1;
+        }
+        return min;
+      }
+      if ("TEAMCITY_VERSION" in env) {
+        return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? 1 : 0;
+      }
+      if (env.COLORTERM === "truecolor") {
+        return 3;
+      }
+      if ("TERM_PROGRAM" in env) {
+        const version = parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
+        switch (env.TERM_PROGRAM) {
+          case "iTerm.app":
+            return version >= 3 ? 3 : 2;
+          case "Apple_Terminal":
+            return 2;
+        }
+      }
+      if (/-256(color)?$/i.test(env.TERM)) {
+        return 2;
+      }
+      if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM)) {
+        return 1;
+      }
+      if ("COLORTERM" in env) {
+        return 1;
+      }
+      return min;
+    }
+    function getSupportLevel(stream) {
+      const level = supportsColor(stream, stream && stream.isTTY);
+      return translateLevel(level);
+    }
+    module2.exports = {
+      supportsColor: getSupportLevel,
+      stdout: translateLevel(supportsColor(true, tty.isatty(1))),
+      stderr: translateLevel(supportsColor(true, tty.isatty(2)))
+    };
+  }
+});
+
 // node_modules/debug/src/node.js
 var require_node = __commonJS({
   "node_modules/debug/src/node.js"(exports2, module2) {
@@ -515,7 +630,7 @@ var require_node = __commonJS({
     );
     exports2.colors = [6, 2, 3, 4, 5, 1];
     try {
-      const supportsColor = require("supports-color");
+      const supportsColor = require_supports_color();
       if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
         exports2.colors = [
           20,
@@ -1511,12 +1626,18 @@ function parseWebcastMessage(method, payload) {
         }
       }
       let toUserId = "";
+      const receiverBuf = getBytes(f, 8);
+      if (receiverBuf) {
+        const r = parseUser(receiverBuf);
+        if (r.id && r.id !== "0") toUserId = r.id;
+      }
       const extraBuf = getBytes(f, 23);
-      if (extraBuf) {
-        const ef = decodeProto(extraBuf);
-        toUserId = String(getInt(ef, 8));
+      if (!toUserId && extraBuf) {
+        const id = getIntStr(decodeProto(extraBuf), 8);
+        if (id !== "0") toUserId = id;
       }
-      const groupId = toUserId || getStr(f, 11);
+      const rawGroup = getIntStr(f, 11);
+      const groupId = getStr(f, 11) || (rawGroup !== "0" ? rawGroup : "");
       return {
         ...base,
         type: "gift",
@@ -1528,7 +1649,9 @@ function parseWebcastMessage(method, payload) {
         repeatEnd,
         combo: repeatCount > 1 && !repeatEnd,
         giftType,
-        groupId
+        groupId,
+        toUserId,
+        receiverUserId: toUserId
       };
     }
     // Proto: WebcastSocialMessage { User user=2, WebcastMessageEvent event=1 }
@@ -1554,7 +1677,7 @@ function parseWebcastMessage(method, payload) {
     // Proto: WebcastRoomUserSeqMessage { int32 viewerCount=3 }
     case "WebcastRoomUserSeqMessage": {
       const viewerCount = getInt(f, 3) || getInt(f, 2);
-      const totalViewers = getInt(f, 1) || viewerCount;
+      const totalViewers = getInt(f, 7) || viewerCount;
       return { ...base, type: "roomUserSeq", totalViewers, viewerCount };
     }
     // Proto: WebcastLinkMicBattle { repeated WebcastLinkMicBattleItems battleUsers=10 }
@@ -2068,6 +2191,11 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
     if (this._destroyed) throw new Error("Client has been destroyed. Create a new instance.");
     this.intentionalClose = false;
     if (this.mode === "relayed") {
+      if (this._presetRoomId) {
+        console.warn(
+          `[TikTokLive] roomId=${this._presetRoomId} is ignored in mode:'relayed' - the managed relay resolves the room itself. Use mode:'direct' with roomId to pin an exact room (resolve it first via /webcast/bulk_live_check).`
+        );
+      }
       return this._connectRelayed();
     }
     let ttwid = this._presetSessionId;
@@ -2503,6 +2631,9 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
           }
           this.emit("event", evt);
           this.emit(evt.type, evt);
+          if (evt.type === "control" && evt.action === 3) {
+            this.emit("streamEnd", { type: "streamEnd", uniqueId: this.uniqueId, reason: "creator_offline" });
+          }
         }
       }
     } catch {
@@ -2512,8 +2643,12 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
    * Resolve unknown host user IDs via the sign server API.
    * Caches results and re-emits the battleArmies event with enriched hostUser data.
    */
+  // Set once the sign server refuses host resolution for this key (tier below
+  // Basic answers 403). Before this, every battle frame retried and filled the
+  // customer's API log with 403s they never asked for.
+  _hostResolveUnavailable = false;
   async resolveHostUsers(userIds, originalEvt) {
-    const toResolve = userIds.filter((id) => !this._pendingHostResolves.has(id));
+    const toResolve = this._hostResolveUnavailable ? [] : userIds.filter((id) => !this._pendingHostResolves.has(id));
     if (toResolve.length === 0) {
       this.emit("event", originalEvt);
       this.emit(originalEvt.type, originalEvt);
@@ -2531,7 +2666,9 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
         body: JSON.stringify({ user_ids: toResolve }),
         signal: AbortSignal.timeout(5e3)
       });
-      if (res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        this._hostResolveUnavailable = true;
+      } else if (res.ok) {
         const json = await res.json();
         if (json.data) {
           for (const [uid, info] of Object.entries(json.data)) {