@tiktool/live 2.10.1 → 2.11.1

package/README.md

@@ -349,10 +349,29 @@ live.on('battle', (e) => {
 | `connect()` | `Promise<void>` | Connect to livestream |
 | `disconnect()` | `void` | Disconnect |
 | `getStreamUrl()` | `Promise<StreamInfo>` | Get FLV/HLS playback URLs for the live video |
+| `getUserProfile(uniqueId?)` | `Promise<UserProfile>` | Resolve any TikTok username → numeric `id`, `secUid`, nickname, bio, avatars, follower stats |
 | `connected` | `boolean` | Connection status |
 | `eventCount` | `number` | Total events received |
 | `roomId` | `string` | Current room ID |
 
+### Static methods (no connection required)
+
+```typescript
+// Get numeric TikTok user ID + full profile for any @username (Pro tier+)
+const profile = await TikTokLive.getUserProfile({
+    uniqueId: 'dalga.ahmedov',
+    apiKey: 'YOUR_KEY',
+});
+profile.id;                  // "7355610677036581896"  ← numeric streamer ID
+profile.nickname;            // "🤍DENIZ🖤🌊"
+profile.secUid;              // signed TikTok user identifier
+profile.stats.followerCount; // 7945
+profile.avatarLarger;        // CDN URL
+
+// Get FLV/HLS playback URLs for any creator
+const stream = await TikTokLive.getStreamUrl({ uniqueId, apiKey });
+```
+
 ### REST endpoints (companion to the WS SDK)
 
 For lookups outside the live event stream, hit the sign server directly with your API key:

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);
   }