@tiktool/live 2.12.3 → 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;

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;

package/dist/index.js

@@ -1626,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",
@@ -1643,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 }
@@ -1669,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 }
@@ -2183,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;
@@ -2618,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 {