@tiktool/live 2.4.5 → 2.4.7

package/dist/index.d.mts

@@ -203,6 +203,17 @@ interface TikTokLiveOptions {
     heartbeatInterval?: number;
     debug?: boolean;
     webSocketImpl?: any;
+    /**
+     * TikTok browser session ID cookie for authenticated connections.
+     * Enables ranklist API access and authenticated WebSocket features.
+     * Obtain from the user's tiktok.com browser cookies.
+     */
+    sessionId?: string;
+    /**
+     * TikTok target IDC region (e.g. 'useast5').
+     * Required when sessionId is provided — must match the account's region.
+     */
+    ttTargetIdc?: string;
 }
 interface RanklistUser {
     /** TikTok user ID */
@@ -356,12 +367,23 @@ declare class TikTokLive extends EventEmitter {
     private readonly maxReconnectAttempts;
     private readonly heartbeatInterval;
     private readonly debug;
+    private _sessionId?;
+    private _ttTargetIdc?;
     constructor(options: TikTokLiveOptions);
     connect(): Promise<void>;
     disconnect(): void;
     get connected(): boolean;
     get eventCount(): number;
     get roomId(): string;
+    /** Get the stored session ID (if any) */
+    get sessionId(): string | undefined;
+    /** Update the session ID at runtime (e.g. after TikTok login) */
+    setSession(sessionId: string, ttTargetIdc?: string): void;
+    /**
+     * Build a cookie header string for authenticated API requests (e.g. ranklist).
+     * Returns undefined if no session is set.
+     */
+    buildSessionCookieHeader(): string | undefined;
     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;
@@ -405,8 +427,10 @@ interface GetRanklistOptions {
 /**
  * Fetch ranked user lists from TikTok via the sign server.
  *
- * Requires `sessionCookie` for authentication — without it, TikTok
- * returns status 20003 ("Please login first").
+ * When `sessionCookie` is provided, the server returns a **sign-and-return**
+ * response with a signed URL that you must fetch from your own IP
+ * (TikTok sessions are IP-bound). Check for `sign_and_return: true` in
+ * the response to detect this mode.
  *
  * @example
  * ```ts
@@ -416,7 +440,19 @@ interface GetRanklistOptions {
  *     sessionCookie: 'sessionid=abc; sid_guard=def',
  *     type: 'online_audience',
  * });
- * console.log(data.data.ranks); // top gifters
+ *
+ * if (data.sign_and_return) {
+ *     // Fetch the signed URL from YOUR IP with your session cookie
+ *     const resp = await fetch(data.signed_url, {
+ *         method: data.method,
+ *         headers: { ...data.headers, Cookie: sessionCookie },
+ *         ...(data.body ? { body: data.body } : {}),
+ *     });
+ *     const tikData = await resp.json();
+ *     console.log(tikData); // TikTok's raw response
+ * } else {
+ *     console.log(data); // Direct TikTok response (no session)
+ * }
  * ```
  */
 declare function getRanklist(opts: GetRanklistOptions): Promise<RanklistResponse>;
@@ -448,6 +484,18 @@ interface GetRegionalRanklistOptions {
     type?: 'list' | 'entrance';
     /** Gap interval filter (default: "0") */
     gapInterval?: string;
+    /**
+     * TikTok session cookie string for authentication.
+     * Passed to the API server for proxied requests.
+     * Example: "sessionid=abc123; sessionid_ss=abc123"
+     */
+    sessionCookie?: string;
+    /**
+     * Client's real IP address (for deployed server scenarios).
+     * When running on a remote server, pass the end-user's IP so the
+     * API server can proxy the TikTok request from the correct IP.
+     */
+    clientIp?: string;
 }
 interface RegionalRanklistSignedResponse {
     /** Always 0 on success */

package/dist/index.d.ts

@@ -203,6 +203,17 @@ interface TikTokLiveOptions {
     heartbeatInterval?: number;
     debug?: boolean;
     webSocketImpl?: any;
+    /**
+     * TikTok browser session ID cookie for authenticated connections.
+     * Enables ranklist API access and authenticated WebSocket features.
+     * Obtain from the user's tiktok.com browser cookies.
+     */
+    sessionId?: string;
+    /**
+     * TikTok target IDC region (e.g. 'useast5').
+     * Required when sessionId is provided — must match the account's region.
+     */
+    ttTargetIdc?: string;
 }
 interface RanklistUser {
     /** TikTok user ID */
@@ -356,12 +367,23 @@ declare class TikTokLive extends EventEmitter {
     private readonly maxReconnectAttempts;
     private readonly heartbeatInterval;
     private readonly debug;
+    private _sessionId?;
+    private _ttTargetIdc?;
     constructor(options: TikTokLiveOptions);
     connect(): Promise<void>;
     disconnect(): void;
     get connected(): boolean;
     get eventCount(): number;
     get roomId(): string;
+    /** Get the stored session ID (if any) */
+    get sessionId(): string | undefined;
+    /** Update the session ID at runtime (e.g. after TikTok login) */
+    setSession(sessionId: string, ttTargetIdc?: string): void;
+    /**
+     * Build a cookie header string for authenticated API requests (e.g. ranklist).
+     * Returns undefined if no session is set.
+     */
+    buildSessionCookieHeader(): string | undefined;
     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;
@@ -405,8 +427,10 @@ interface GetRanklistOptions {
 /**
  * Fetch ranked user lists from TikTok via the sign server.
  *
- * Requires `sessionCookie` for authentication — without it, TikTok
- * returns status 20003 ("Please login first").
+ * When `sessionCookie` is provided, the server returns a **sign-and-return**
+ * response with a signed URL that you must fetch from your own IP
+ * (TikTok sessions are IP-bound). Check for `sign_and_return: true` in
+ * the response to detect this mode.
  *
  * @example
  * ```ts
@@ -416,7 +440,19 @@ interface GetRanklistOptions {
  *     sessionCookie: 'sessionid=abc; sid_guard=def',
  *     type: 'online_audience',
  * });
- * console.log(data.data.ranks); // top gifters
+ *
+ * if (data.sign_and_return) {
+ *     // Fetch the signed URL from YOUR IP with your session cookie
+ *     const resp = await fetch(data.signed_url, {
+ *         method: data.method,
+ *         headers: { ...data.headers, Cookie: sessionCookie },
+ *         ...(data.body ? { body: data.body } : {}),
+ *     });
+ *     const tikData = await resp.json();
+ *     console.log(tikData); // TikTok's raw response
+ * } else {
+ *     console.log(data); // Direct TikTok response (no session)
+ * }
  * ```
  */
 declare function getRanklist(opts: GetRanklistOptions): Promise<RanklistResponse>;
@@ -448,6 +484,18 @@ interface GetRegionalRanklistOptions {
     type?: 'list' | 'entrance';
     /** Gap interval filter (default: "0") */
     gapInterval?: string;
+    /**
+     * TikTok session cookie string for authentication.
+     * Passed to the API server for proxied requests.
+     * Example: "sessionid=abc123; sessionid_ss=abc123"
+     */
+    sessionCookie?: string;
+    /**
+     * Client's real IP address (for deployed server scenarios).
+     * When running on a remote server, pass the end-user's IP so the
+     * API server can proxy the TikTok request from the correct IP.
+     */
+    clientIp?: string;
 }
 interface RegionalRanklistSignedResponse {
     /** Always 0 on success */

package/dist/index.js

@@ -863,6 +863,8 @@ var TikTokLive = class extends import_events.EventEmitter {
   maxReconnectAttempts;
   heartbeatInterval;
   debug;
+  _sessionId;
+  _ttTargetIdc;
   constructor(options) {
     super();
     this.uniqueId = options.uniqueId.replace(/^@/, "");
@@ -873,6 +875,8 @@ var TikTokLive = class extends import_events.EventEmitter {
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
     this.heartbeatInterval = options.heartbeatInterval ?? 1e4;
     this.debug = options.debug ?? false;
+    this._sessionId = options.sessionId;
+    this._ttTargetIdc = options.ttTargetIdc;
   }
   async connect() {
     this.intentionalClose = false;
@@ -965,10 +969,17 @@ var TikTokLive = class extends import_events.EventEmitter {
       wsUrl = rawWsUrl.replace(/^https:\/\//, "wss://");
     }
     return new Promise((resolve, reject) => {
+      let cookieHeader = `ttwid=${ttwid}`;
+      if (this._sessionId) {
+        cookieHeader += `; sessionid=${this._sessionId}; sessionid_ss=${this._sessionId}; sid_tt=${this._sessionId}`;
+        if (this._ttTargetIdc) {
+          cookieHeader += `; tt-target-idc=${this._ttTargetIdc}`;
+        }
+      }
       this.ws = new import_ws.default(wsUrl, {
         headers: {
           "User-Agent": DEFAULT_UA,
-          "Cookie": `ttwid=${ttwid}`,
+          "Cookie": cookieHeader,
           "Origin": "https://www.tiktok.com"
         }
       });
@@ -1027,6 +1038,29 @@ var TikTokLive = class extends import_events.EventEmitter {
   get roomId() {
     return this._roomId;
   }
+  /** Get the stored session ID (if any) */
+  get sessionId() {
+    return this._sessionId;
+  }
+  /** Update the session ID at runtime (e.g. after TikTok login) */
+  setSession(sessionId, ttTargetIdc) {
+    this._sessionId = sessionId;
+    if (ttTargetIdc) this._ttTargetIdc = ttTargetIdc;
+  }
+  /**
+   * Build a cookie header string for authenticated API requests (e.g. ranklist).
+   * Returns undefined if no session is set.
+   */
+  buildSessionCookieHeader() {
+    if (!this._sessionId) return void 0;
+    const parts = [
+      `sessionid=${this._sessionId}`,
+      `sessionid_ss=${this._sessionId}`,
+      `sid_tt=${this._sessionId}`
+    ];
+    if (this._ttTargetIdc) parts.push(`tt-target-idc=${this._ttTargetIdc}`);
+    return parts.join("; ");
+  }
   on(event, listener) {
     return super.on(event, listener);
   }
@@ -1110,6 +1144,9 @@ async function getRanklist(opts) {
   if (data.status_code !== 0) {
     throw new Error(data.error || `Ranklist failed (status ${data.status_code})`);
   }
+  if (data.sign_and_return) {
+    return data;
+  }
   return data.data;
 }
 async function getRegionalRanklist(opts) {
@@ -1122,6 +1159,8 @@ async function getRegionalRanklist(opts) {
   if (opts.rankType) body.rank_type = opts.rankType;
   if (opts.type) body.type = opts.type;
   if (opts.gapInterval) body.gap_interval = opts.gapInterval;
+  if (opts.sessionCookie) body.session_cookie = opts.sessionCookie;
+  if (opts.clientIp) body.client_ip = opts.clientIp;
   const resp = await fetch(`${base}/webcast/ranklist/regional?apiKey=${ak}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },