@tiktool/live 2.10.0 → 2.11.0

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

@@ -370,6 +370,71 @@ declare class TikTokLive extends EventEmitter {
         signServerUrl?: string;
         quality?: string;
     }): Promise<StreamInfo>;
+    /**
+     * Resolve a TikTok username to the streamer's full public profile —
+     * numeric user ID, secUid, nickname, bio, avatars, follower stats.
+     *
+     * Useful when you need the numeric TikTok ID for a username (the inverse
+     * of `resolve_user_ids`, which only goes userId → username).
+     *
+     * Requires Pro tier+. Cached server-side for 24h.
+     *
+     * @example
+     * ```ts
+     * const profile = await TikTokLive.getUserProfile({
+     *   uniqueId: 'dalga.ahmedov',
+     *   apiKey: 'YOUR_KEY',
+     * });
+     * console.log(profile.id);                    // "7355610677036581896" (numeric)
+     * console.log(profile.nickname);              // display name
+     * console.log(profile.stats.followerCount);   // 12345
+     * console.log(profile.avatarLarger);          // CDN URL
+     * ```
+     */
+    static getUserProfile(options: {
+        uniqueId: string;
+        apiKey: string;
+        signServerUrl?: string;
+        /** Set `true` to bypass the 24h server cache (e.g. after the user updated their bio). */
+        nocache?: boolean;
+    }): Promise<{
+        id: string;
+        uniqueId: string;
+        secUid: string;
+        nickname: string;
+        signature: string;
+        verified: boolean;
+        avatarThumb: string;
+        avatarMedium: string;
+        avatarLarger: string;
+        stats: {
+            followerCount: number;
+            followingCount: number;
+            heartCount: number;
+            videoCount: number;
+        };
+    }>;
+    /**
+     * Instance shortcut — fetch the profile of the streamer this client is
+     * connected to (or any other user if `uniqueId` is passed).
+     */
+    getUserProfile(uniqueId?: string): Promise<{
+        id: string;
+        uniqueId: string;
+        secUid: string;
+        nickname: string;
+        signature: string;
+        verified: boolean;
+        avatarThumb: string;
+        avatarMedium: string;
+        avatarLarger: string;
+        stats: {
+            followerCount: number;
+            followingCount: number;
+            heartCount: number;
+            videoCount: number;
+        };
+    }>;
     on<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
     once<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
     off<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;

package/dist/index.d.ts

@@ -370,6 +370,71 @@ declare class TikTokLive extends EventEmitter {
         signServerUrl?: string;
         quality?: string;
     }): Promise<StreamInfo>;
+    /**
+     * Resolve a TikTok username to the streamer's full public profile —
+     * numeric user ID, secUid, nickname, bio, avatars, follower stats.
+     *
+     * Useful when you need the numeric TikTok ID for a username (the inverse
+     * of `resolve_user_ids`, which only goes userId → username).
+     *
+     * Requires Pro tier+. Cached server-side for 24h.
+     *
+     * @example
+     * ```ts
+     * const profile = await TikTokLive.getUserProfile({
+     *   uniqueId: 'dalga.ahmedov',
+     *   apiKey: 'YOUR_KEY',
+     * });
+     * console.log(profile.id);                    // "7355610677036581896" (numeric)
+     * console.log(profile.nickname);              // display name
+     * console.log(profile.stats.followerCount);   // 12345
+     * console.log(profile.avatarLarger);          // CDN URL
+     * ```
+     */
+    static getUserProfile(options: {
+        uniqueId: string;
+        apiKey: string;
+        signServerUrl?: string;
+        /** Set `true` to bypass the 24h server cache (e.g. after the user updated their bio). */
+        nocache?: boolean;
+    }): Promise<{
+        id: string;
+        uniqueId: string;
+        secUid: string;
+        nickname: string;
+        signature: string;
+        verified: boolean;
+        avatarThumb: string;
+        avatarMedium: string;
+        avatarLarger: string;
+        stats: {
+            followerCount: number;
+            followingCount: number;
+            heartCount: number;
+            videoCount: number;
+        };
+    }>;
+    /**
+     * Instance shortcut — fetch the profile of the streamer this client is
+     * connected to (or any other user if `uniqueId` is passed).
+     */
+    getUserProfile(uniqueId?: string): Promise<{
+        id: string;
+        uniqueId: string;
+        secUid: string;
+        nickname: string;
+        signature: string;
+        verified: boolean;
+        avatarThumb: string;
+        avatarMedium: string;
+        avatarLarger: string;
+        stats: {
+            followerCount: number;
+            followingCount: number;
+            heartCount: number;
+            videoCount: number;
+        };
+    }>;
     on<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
     once<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
     off<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;

package/dist/index.js

@@ -2496,6 +2496,52 @@ var TikTokLive = class _TikTokLive extends import_events.EventEmitter {
       hlsPullUrl: d.hls_pull_url || void 0
     };
   }
+  /**
+   * Resolve a TikTok username to the streamer's full public profile —
+   * numeric user ID, secUid, nickname, bio, avatars, follower stats.
+   *
+   * Useful when you need the numeric TikTok ID for a username (the inverse
+   * of `resolve_user_ids`, which only goes userId → username).
+   *
+   * Requires Pro tier+. Cached server-side for 24h.
+   *
+   * @example
+   * ```ts
+   * const profile = await TikTokLive.getUserProfile({
+   *   uniqueId: 'dalga.ahmedov',
+   *   apiKey: 'YOUR_KEY',
+   * });
+   * console.log(profile.id);                    // "7355610677036581896" (numeric)
+   * console.log(profile.nickname);              // display name
+   * console.log(profile.stats.followerCount);   // 12345
+   * console.log(profile.avatarLarger);          // CDN URL
+   * ```
+   */
+  static async getUserProfile(options) {
+    const serverUrl = (options.signServerUrl || DEFAULT_SIGN_SERVER).replace(/\/$/, "");
+    const uname = options.uniqueId.replace(/^@/, "");
+    const qs = new URLSearchParams({ unique_id: uname });
+    if (options.nocache) qs.set("nocache", "1");
+    const resp = await fetch(`${serverUrl}/webcast/user_profile?${qs}`, {
+      headers: { "x-api-key": options.apiKey }
+    });
+    const data = await resp.json();
+    if (data.status_code !== 0 || !data.data?.profile) {
+      throw new Error(data.error || `Failed to get user profile for @${uname}`);
+    }
+    return data.data.profile;
+  }
+  /**
+   * Instance shortcut — fetch the profile of the streamer this client is
+   * connected to (or any other user if `uniqueId` is passed).
+   */
+  async getUserProfile(uniqueId) {
+    return _TikTokLive.getUserProfile({
+      uniqueId: uniqueId || this.uniqueId,
+      apiKey: this.apiKey,
+      signServerUrl: this.signServerUrl
+    });
+  }
   on(event, listener) {
     return super.on(event, listener);
   }