@tiktool/live 2.2.1 → 2.3.1

package/README.md

@@ -12,7 +12,7 @@
 
 **Real-time TikTok LIVE events — chat messages, gifts, follows, likes, battles, viewer counts, and 18+ event types — streamed directly to your application via WebSocket.**
 
-[Quick Start](#-quick-start) · [Events](#-events) · [REST API](#-rest-api-endpoints) · [Pricing](#-pricing) · [Get API Key](https://tik.tools)
+[Quick Start](#-quick-start) · [Events](#-events) · [API Utilities](#-api-utilities) · [REST API](#-rest-api-endpoints) · [Pricing](#-pricing) · [Get API Key](https://tik.tools)
 
 </div>
 
@@ -122,9 +122,102 @@ live.on('event', (event) => {
 
 ---
 
+## 🛠️ API Utilities
+
+The SDK includes server-side utilities for calling TikTool REST endpoints. These handle the **sign-and-return** flow automatically — resolving usernames to room IDs, fetching signed URLs, and returning actual TikTok data.
+
+### `callApi(options)` — High-Level Helper
+
+The easiest way to call any TikTool endpoint. Handles the full flow automatically:
+
+```typescript
+import { callApi } from '@tiktool/live';
+
+// Get stream video URLs for a user
+const streamData = await callApi({
+    apiKey: 'YOUR_API_KEY',
+    endpoint: '/webcast/room_video',
+    uniqueId: 'streamer_name',
+});
+
+// Get room info
+const roomInfo = await callApi({
+    apiKey: 'YOUR_API_KEY',
+    endpoint: '/webcast/room_info',
+    uniqueId: 'streamer_name',
+});
+
+// Use a custom server URL
+const data = await callApi({
+    serverUrl: 'https://your-server.com',
+    apiKey: 'YOUR_API_KEY',
+    endpoint: '/webcast/rankings',
+    uniqueId: 'streamer_name',
+    method: 'GET',
+});
+```
+
+#### `CallApiOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | API key from [tik.tools](https://tik.tools) |
+| `endpoint` | `string` | — | API path (e.g. `'/webcast/room_video'`) |
+| `uniqueId` | `string` | — | TikTok username to resolve |
+| `serverUrl` | `string` | `https://api.tik.tools` | Custom API server URL |
+| `method` | `'GET' \| 'POST'` | `'POST'` | HTTP method |
+| `extraBody` | `object` | — | Additional POST body fields |
+
+### `resolveRoomId(uniqueId)` — Username to Room ID
+
+Scrapes a TikTok live page to extract the `room_id`. Results are cached for 5 minutes. Returns `null` if the user is not live.
+
+```typescript
+import { resolveRoomId } from '@tiktool/live';
+
+const roomId = await resolveRoomId('streamer_name');
+if (roomId) {
+    console.log(`Room ID: ${roomId}`);
+}
+```
+
+### `resolveLivePage(uniqueId)` — Full Live Page Resolution
+
+Returns all live page metadata including the room ID, session cookie (`ttwid`), and cluster region. Used internally by `TikTokLive.connect()`. Returns `null` if the user is not live.
+
+```typescript
+import { resolveLivePage } from '@tiktool/live';
+
+const info = await resolveLivePage('streamer_name');
+if (info) {
+    console.log(`Room: ${info.roomId}, Region: ${info.clusterRegion}`);
+}
+```
+
+#### `LivePageInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `roomId` | `string` | Active room ID for the livestream |
+| `ttwid` | `string` | Session cookie for WebSocket auth |
+| `clusterRegion` | `string` | Server cluster region (e.g. `'us'`, `'eu'`) |
+
+### `fetchSignedUrl(response)` — Execute Signed URL Response
+
+Takes a sign-and-return API response and fetches the actual TikTok data from the signed URL.
+
+```typescript
+import { fetchSignedUrl } from '@tiktool/live';
+
+// After calling an API endpoint that returns action: 'fetch_signed_url'
+const tikTokData = await fetchSignedUrl(apiResponse);
+```
+
+---
+
 ## 🌐 REST API Endpoints
 
-The sign server at `api.tik.tools` exposes a full REST API alongside WebSocket signing. Basic endpoints (signing, live checks) are available on the free tier. Pro and Ultra plans unlock all endpoints with higher rate limits.
+The sign server at `api.tik.tools` exposes a full REST API alongside WebSocket signing. Endpoints use a **sign-and-return** pattern — when called with a `unique_id`, they return instructions for resolving the room ID; when called with a `room_id`, they return a signed URL to fetch data directly from TikTok. Use `callApi()` to handle this automatically.
 
 | Endpoint | Description |
 |----------|-------------|

package/dist/index.d.mts

@@ -219,4 +219,71 @@ declare class TikTokLive extends TypedEmitter {
     private stopHeartbeat;
 }
 
-export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, 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 SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };
+/**
+ * TikTool API utilities for the sign-and-return API flow.
+ *
+ * The API server returns signed URLs instead of fetching TikTok data directly.
+ * These utilities handle the two-step flow:
+ *   1. resolve_required — scrape TikTok HTML to get room_id
+ *   2. fetch_signed_url — use the signed URL to get actual TikTok data
+ *
+ * @module
+ */
+/**
+ * Resolved live page metadata from a TikTok live page.
+ */
+interface LivePageInfo {
+    /** Active room ID for the livestream */
+    roomId: string;
+    /** Session cookie required for WebSocket authentication */
+    ttwid: string;
+    /** Server cluster region (e.g. 'us', 'eu') */
+    clusterRegion: string;
+}
+/**
+ * Scrape a TikTok live page to extract room metadata.
+ * Returns the room ID, session cookie, and cluster region.
+ * Results are cached for 5 minutes. Returns `null` if the user is not live.
+ */
+declare function resolveLivePage(uniqueId: string): Promise<LivePageInfo | null>;
+/**
+ * Resolve a TikTok username to a room ID.
+ * Returns `null` if the user is not currently live.
+ * Results are cached for 5 minutes.
+ */
+declare function resolveRoomId(uniqueId: string): Promise<string | null>;
+interface SignedUrlResponse {
+    status_code: number;
+    action: string;
+    signed_url: string;
+    headers: Record<string, string>;
+    cookies: string;
+}
+/**
+ * Execute a signed-URL API response: fetch the signed URL and return the
+ * parsed JSON data from TikTok.
+ */
+declare function fetchSignedUrl(response: SignedUrlResponse): Promise<any>;
+interface CallApiOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** API endpoint path (e.g. '/webcast/room_video') */
+    endpoint: string;
+    /** TikTok unique_id to resolve */
+    uniqueId: string;
+    /** HTTP method (default: POST) */
+    method?: 'GET' | 'POST';
+    /** Additional body fields for POST requests */
+    extraBody?: Record<string, any>;
+}
+/**
+ * Call a TikTool API endpoint, handling the full
+ * resolve_required → room_id → signed_url → fetch flow automatically.
+ *
+ * Returns the actual TikTok data, or `null` if the user is not live.
+ */
+declare function callApi(opts: CallApiOptions): Promise<any>;
+
+export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTeam, type BattleTeamUser, type CallApiOptions, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EnvelopeEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type LivePageInfo, type MemberEvent, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SignedUrlResponse, type SocialEvent, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, callApi, fetchSignedUrl, resolveLivePage, resolveRoomId };

package/dist/index.d.ts

@@ -219,4 +219,71 @@ declare class TikTokLive extends TypedEmitter {
     private stopHeartbeat;
 }
 
-export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, 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 SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };
+/**
+ * TikTool API utilities for the sign-and-return API flow.
+ *
+ * The API server returns signed URLs instead of fetching TikTok data directly.
+ * These utilities handle the two-step flow:
+ *   1. resolve_required — scrape TikTok HTML to get room_id
+ *   2. fetch_signed_url — use the signed URL to get actual TikTok data
+ *
+ * @module
+ */
+/**
+ * Resolved live page metadata from a TikTok live page.
+ */
+interface LivePageInfo {
+    /** Active room ID for the livestream */
+    roomId: string;
+    /** Session cookie required for WebSocket authentication */
+    ttwid: string;
+    /** Server cluster region (e.g. 'us', 'eu') */
+    clusterRegion: string;
+}
+/**
+ * Scrape a TikTok live page to extract room metadata.
+ * Returns the room ID, session cookie, and cluster region.
+ * Results are cached for 5 minutes. Returns `null` if the user is not live.
+ */
+declare function resolveLivePage(uniqueId: string): Promise<LivePageInfo | null>;
+/**
+ * Resolve a TikTok username to a room ID.
+ * Returns `null` if the user is not currently live.
+ * Results are cached for 5 minutes.
+ */
+declare function resolveRoomId(uniqueId: string): Promise<string | null>;
+interface SignedUrlResponse {
+    status_code: number;
+    action: string;
+    signed_url: string;
+    headers: Record<string, string>;
+    cookies: string;
+}
+/**
+ * Execute a signed-URL API response: fetch the signed URL and return the
+ * parsed JSON data from TikTok.
+ */
+declare function fetchSignedUrl(response: SignedUrlResponse): Promise<any>;
+interface CallApiOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** API endpoint path (e.g. '/webcast/room_video') */
+    endpoint: string;
+    /** TikTok unique_id to resolve */
+    uniqueId: string;
+    /** HTTP method (default: POST) */
+    method?: 'GET' | 'POST';
+    /** Additional body fields for POST requests */
+    extraBody?: Record<string, any>;
+}
+/**
+ * Call a TikTool API endpoint, handling the full
+ * resolve_required → room_id → signed_url → fetch flow automatically.
+ *
+ * Returns the actual TikTok data, or `null` if the user is not live.
+ */
+declare function callApi(opts: CallApiOptions): Promise<any>;
+
+export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTeam, type BattleTeamUser, type CallApiOptions, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EnvelopeEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type LivePageInfo, type MemberEvent, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SignedUrlResponse, type SocialEvent, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, callApi, fetchSignedUrl, resolveLivePage, resolveRoomId };

package/dist/index.js

@@ -30,7 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  TikTokLive: () => TikTokLive
+  TikTokLive: () => TikTokLive,
+  callApi: () => callApi,
+  fetchSignedUrl: () => fetchSignedUrl,
+  resolveLivePage: () => resolveLivePage,
+  resolveRoomId: () => resolveRoomId
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -315,7 +319,8 @@ function parseWebcastMessage(method, payload) {
         repeatEnd,
         combo: repeatCount > 1 && !repeatEnd,
         giftType,
-        groupId
+        groupId,
+        giftPictureUrl: giftImageUrl
       };
     }
     case "WebcastSocialMessage": {
@@ -495,9 +500,140 @@ function parseWebcastResponse(payload) {
   return events;
 }
 
-// src/client.ts
+// src/api.ts
 var DEFAULT_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 var DEFAULT_SIGN_SERVER = "https://api.tik.tools";
+var pageCache = /* @__PURE__ */ new Map();
+var PAGE_CACHE_TTL = 5 * 60 * 1e3;
+async function resolveLivePage(uniqueId) {
+  const clean = uniqueId.replace(/^@/, "");
+  const cached = pageCache.get(clean);
+  if (cached && Date.now() - cached.ts < PAGE_CACHE_TTL) {
+    return cached.info;
+  }
+  try {
+    const resp = await fetch(`https://www.tiktok.com/@${clean}/live`, {
+      headers: {
+        "User-Agent": DEFAULT_UA,
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9"
+      },
+      redirect: "follow"
+    });
+    if (!resp.ok) return null;
+    let ttwid = "";
+    const setCookies = resp.headers.get("set-cookie") || "";
+    for (const part of setCookies.split(",")) {
+      const trimmed = part.trim();
+      if (trimmed.startsWith("ttwid=")) {
+        ttwid = trimmed.split(";")[0].split("=").slice(1).join("=");
+        break;
+      }
+    }
+    if (!ttwid && typeof resp.headers.getSetCookie === "function") {
+      for (const sc of resp.headers.getSetCookie()) {
+        if (typeof sc === "string" && sc.startsWith("ttwid=")) {
+          ttwid = sc.split(";")[0].split("=").slice(1).join("=");
+          break;
+        }
+      }
+    }
+    const html = await resp.text();
+    let roomId = "";
+    const sigiMatch = html.match(/id="SIGI_STATE"[^>]*>([^<]+)/);
+    if (sigiMatch) {
+      try {
+        const json = JSON.parse(sigiMatch[1]);
+        const jsonStr = JSON.stringify(json);
+        const m = jsonStr.match(/"roomId"\s*:\s*"(\d+)"/);
+        if (m) roomId = m[1];
+      } catch {
+      }
+    }
+    if (!roomId) {
+      const patterns = [
+        /"roomId"\s*:\s*"(\d+)"/,
+        /room_id[=/](\d{10,})/,
+        /"idStr"\s*:\s*"(\d{10,})"/
+      ];
+      for (const p of patterns) {
+        const m = html.match(p);
+        if (m) {
+          roomId = m[1];
+          break;
+        }
+      }
+    }
+    if (!roomId) return null;
+    const crMatch = html.match(/"clusterRegion"\s*:\s*"([^"]+)"/);
+    const clusterRegion = crMatch ? crMatch[1] : "";
+    const info = { roomId, ttwid, clusterRegion };
+    pageCache.set(clean, { info, ts: Date.now() });
+    return info;
+  } catch {
+  }
+  return null;
+}
+async function resolveRoomId(uniqueId) {
+  const info = await resolveLivePage(uniqueId);
+  return info?.roomId ?? null;
+}
+async function fetchSignedUrl(response) {
+  if (response.action !== "fetch_signed_url" || !response.signed_url) {
+    return null;
+  }
+  const headers = { ...response.headers || {} };
+  if (response.cookies) {
+    headers["Cookie"] = response.cookies;
+  }
+  const resp = await fetch(response.signed_url, { headers, redirect: "follow" });
+  const text = await resp.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+async function callApi(opts) {
+  const serverUrl = (opts.serverUrl || DEFAULT_SIGN_SERVER).replace(/\/$/, "");
+  const isGet = opts.method === "GET";
+  const ak = encodeURIComponent(opts.apiKey);
+  const url1 = isGet ? `${serverUrl}${opts.endpoint}?apiKey=${ak}&unique_id=${encodeURIComponent(opts.uniqueId)}` : `${serverUrl}${opts.endpoint}?apiKey=${ak}`;
+  const fetchOpts1 = isGet ? {} : {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ unique_id: opts.uniqueId, ...opts.extraBody })
+  };
+  const resp1 = await fetch(url1, fetchOpts1);
+  const data1 = await resp1.json();
+  if (data1.status_code === 0 && !["resolve_required", "fetch_signed_url"].includes(data1.action)) {
+    return data1;
+  }
+  if (data1.action === "fetch_signed_url") {
+    return fetchSignedUrl(data1);
+  }
+  if (data1.action === "resolve_required") {
+    const roomId = await resolveRoomId(opts.uniqueId);
+    if (!roomId) return null;
+    const url2 = isGet ? `${serverUrl}${opts.endpoint}?apiKey=${ak}&room_id=${encodeURIComponent(roomId)}` : `${serverUrl}${opts.endpoint}?apiKey=${ak}`;
+    const fetchOpts2 = isGet ? {} : {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ room_id: roomId, ...opts.extraBody })
+    };
+    const resp2 = await fetch(url2, fetchOpts2);
+    const data2 = await resp2.json();
+    if (data2.action === "fetch_signed_url") {
+      return fetchSignedUrl(data2);
+    }
+    return data2;
+  }
+  return data1;
+}
+
+// src/client.ts
+var DEFAULT_UA2 = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+var DEFAULT_SIGN_SERVER2 = "https://api.tik.tools";
 var TypedEmitter = class {
   _listeners = /* @__PURE__ */ new Map();
   on(event, fn) {
@@ -582,7 +718,7 @@ var TikTokLive = class extends TypedEmitter {
   constructor(options) {
     super();
     this.uniqueId = options.uniqueId.replace(/^@/, "");
-    this.signServerUrl = (options.signServerUrl || DEFAULT_SIGN_SERVER).replace(/\/$/, "");
+    this.signServerUrl = (options.signServerUrl || DEFAULT_SIGN_SERVER2).replace(/\/$/, "");
     if (!options.apiKey) throw new Error("apiKey is required. Get a free key at https://tik.tools");
     this.apiKey = options.apiKey;
     this.autoReconnect = options.autoReconnect ?? true;
@@ -596,48 +732,11 @@ var TikTokLive = class extends TypedEmitter {
     if (!this.WS) {
       this.WS = await resolveWebSocket(this.webSocketImpl);
     }
-    const resp = await fetch(`https://www.tiktok.com/@${this.uniqueId}/live`, {
-      headers: {
-        "User-Agent": DEFAULT_UA,
-        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
-        "Accept-Language": "en-US,en;q=0.9"
-      },
-      redirect: "follow"
-    });
-    let ttwid = "";
-    const setCookies = resp.headers.get("set-cookie") || "";
-    for (const part of setCookies.split(",")) {
-      const trimmed = part.trim();
-      if (trimmed.startsWith("ttwid=")) {
-        ttwid = trimmed.split(";")[0].split("=").slice(1).join("=");
-        break;
-      }
-    }
-    if (!ttwid && typeof resp.headers.getSetCookie === "function") {
-      for (const sc of resp.headers.getSetCookie()) {
-        if (typeof sc === "string" && sc.startsWith("ttwid=")) {
-          ttwid = sc.split(";")[0].split("=").slice(1).join("=");
-          break;
-        }
-      }
-    }
-    if (!ttwid) throw new Error("Failed to obtain session cookie");
-    const html = await resp.text();
-    let roomId = "";
-    const sigiMatch = html.match(/id="SIGI_STATE"[^>]*>([^<]+)/);
-    if (sigiMatch) {
-      try {
-        const json = JSON.parse(sigiMatch[1]);
-        const jsonStr = JSON.stringify(json);
-        const m = jsonStr.match(/"roomId"\s*:\s*"(\d+)"/);
-        if (m) roomId = m[1];
-      } catch {
-      }
-    }
-    if (!roomId) throw new Error(`User @${this.uniqueId} is not currently live`);
+    const pageInfo = await resolveLivePage(this.uniqueId);
+    if (!pageInfo) throw new Error(`User @${this.uniqueId} is not currently live`);
+    if (!pageInfo.ttwid) throw new Error("Failed to obtain session cookie");
+    const { roomId, ttwid, clusterRegion } = pageInfo;
     this._roomId = roomId;
-    const crMatch = html.match(/"clusterRegion"\s*:\s*"([^"]+)"/);
-    const clusterRegion = crMatch ? crMatch[1] : "";
     const wsHost = getWsHost(clusterRegion);
     const wsParams = new URLSearchParams({
       version_code: "270000",
@@ -648,7 +747,7 @@ var TikTokLive = class extends TypedEmitter {
       browser_language: "en-US",
       browser_platform: "Win32",
       browser_name: "Mozilla",
-      browser_version: DEFAULT_UA.split("Mozilla/")[1] || "5.0",
+      browser_version: DEFAULT_UA2.split("Mozilla/")[1] || "5.0",
       browser_online: "true",
       tz_name: "Etc/UTC",
       app_name: "tiktok_web",
@@ -695,7 +794,7 @@ var TikTokLive = class extends TypedEmitter {
       try {
         this.ws = new this.WS(connUrl, {
           headers: {
-            "User-Agent": DEFAULT_UA,
+            "User-Agent": DEFAULT_UA2,
             "Cookie": `ttwid=${ttwid}`,
             "Origin": "https://www.tiktok.com"
           }
@@ -874,6 +973,10 @@ var TikTokLive = class extends TypedEmitter {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TikTokLive
+  TikTokLive,
+  callApi,
+  fetchSignedUrl,
+  resolveLivePage,
+  resolveRoomId
 });
 //# sourceMappingURL=index.js.map