@tiktool/live 2.4.4 → 2.4.6

package/dist/index.d.ts

@@ -1,28 +1,22 @@
+import { EventEmitter } from 'events';
+
 interface TikTokUser {
     id: string;
     nickname: string;
     uniqueId: string;
-    avatarUrl?: string;
+    profilePicture?: string;
     profilePictureUrl?: string;
-    followRole?: number;
     badges?: string[];
-    level?: number;
 }
 interface BaseEvent {
     type: string;
     timestamp: number;
     msgId: string;
 }
-interface ChatEmote {
-    id: string;
-    url: string;
-    name: string;
-}
 interface ChatEvent extends BaseEvent {
     type: 'chat';
     user: TikTokUser;
     comment: string;
-    emotes?: ChatEmote[];
 }
 interface MemberEvent extends BaseEvent {
     type: 'member';
@@ -64,9 +58,9 @@ interface BattleTeamUser {
 }
 interface BattleTeam {
     hostUserId: string;
-    hostUser?: TikTokUser;
     score: number;
     users: BattleTeamUser[];
+    hostUser?: TikTokUser;
 }
 interface BattleEvent extends BaseEvent {
     type: 'battle';
@@ -74,12 +68,43 @@ interface BattleEvent extends BaseEvent {
     status: number;
     battleDuration: number;
     teams: BattleTeam[];
+    battleSettings?: {
+        startTimeMs?: number;
+        duration?: number;
+        endTimeMs?: number;
+    };
 }
 interface BattleArmiesEvent extends BaseEvent {
     type: 'battleArmies';
     battleId: string;
     status: number;
     teams: BattleTeam[];
+    battleSettings?: {
+        startTimeMs?: number;
+        duration?: number;
+        endTimeMs?: number;
+    };
+}
+interface BattleTaskEvent extends BaseEvent {
+    type: 'battleTask';
+    taskAction: number;
+    battleRefId: string;
+    missionType: string;
+    multiplier: number;
+    missionDuration: number;
+    missionTarget: number;
+    remainingSeconds: number;
+    endTimestampS: number;
+    timerType: number;
+}
+interface BarrageEvent extends BaseEvent {
+    type: 'barrage';
+    msgType: number;
+    subType: number;
+    displayType: number;
+    duration: number;
+    defaultPattern: string;
+    content: string;
 }
 interface SubscribeEvent extends BaseEvent {
     type: 'subscribe';
@@ -91,6 +116,7 @@ interface EmoteChatEvent extends BaseEvent {
     user: TikTokUser;
     emoteId: string;
     emoteUrl: string;
+    emoteName?: string;
 }
 interface EnvelopeEvent extends BaseEvent {
     type: 'envelope';
@@ -133,7 +159,7 @@ interface UnknownEvent extends BaseEvent {
     type: 'unknown';
     method: string;
 }
-type LiveEvent = ChatEvent | MemberEvent | LikeEvent | GiftEvent | SocialEvent | RoomUserSeqEvent | BattleEvent | BattleArmiesEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
+type LiveEvent = ChatEvent | MemberEvent | LikeEvent | GiftEvent | SocialEvent | RoomUserSeqEvent | BattleEvent | BattleArmiesEvent | BattleTaskEvent | BarrageEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
 interface TikTokLiveEvents {
     connected: () => void;
     disconnected: (code: number, reason: string) => void;
@@ -147,6 +173,8 @@ interface TikTokLiveEvents {
     roomUserSeq: (event: RoomUserSeqEvent) => void;
     battle: (event: BattleEvent) => void;
     battleArmies: (event: BattleArmiesEvent) => void;
+    battleTask: (event: BattleTaskEvent) => void;
+    barrage: (event: BarrageEvent) => void;
     subscribe: (event: SubscribeEvent) => void;
     emoteChat: (event: EmoteChatEvent) => void;
     envelope: (event: EnvelopeEvent) => void;
@@ -164,6 +192,7 @@ interface RoomInfo {
     wsHost: string;
     clusterRegion: string;
     connectedAt: string;
+    ownerUserId?: string;
 }
 interface TikTokLiveOptions {
     uniqueId: string;
@@ -174,49 +203,155 @@ 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 */
+    id_str: string;
+    /** Display name */
+    nickname: string;
+    /** Username (@handle) */
+    display_id?: string;
+    unique_id?: string;
+    /** Avatar thumbnail URLs */
+    avatar_thumb?: {
+        url_list: string[];
+    };
+    /** Full avatar URLs */
+    avatar_medium?: {
+        url_list: string[];
+    };
+    /** Follower info */
+    follow_info?: {
+        follow_status: number;
+        follower_count: number;
+        following_count: number;
+    };
+}
+/**
+ * Entry from online_audience endpoint (in-room top gifters).
+ * Has explicit `rank` (1-based) and `score` fields.
+ */
+interface OnlineAudienceEntry {
+    rank: number;
+    score: number;
+    user: RanklistUser;
 }
-/** Result from solving a puzzle (slider) CAPTCHA */
-interface PuzzleSolveResult {
-    /** X position as proportion (0.0–1.0) of background width */
-    slide_x_proportion: number;
-    /** Absolute pixel X offset */
-    slide_x_px: number;
-    /** Confidence score (0.0–1.0) */
-    confidence: number;
-}
-/** Result from solving a rotate (whirl) CAPTCHA */
-interface RotateSolveResult {
-    /** Rotation angle in degrees (0–360) */
-    angle: number;
-    /** Confidence score (0.0–1.0) */
-    confidence: number;
-}
-/** Result from solving a shapes (3D matching) CAPTCHA */
-interface ShapesSolveResult {
-    /** First matching shape center */
-    point1: {
-        x: number;
-        y: number;
+/**
+ * Entry from anchor/rank_list endpoint (leaderboard/gifter rankings).
+ * Position is the array index. Uses `value` (not `score`).
+ */
+interface AnchorRankListEntry {
+    /** Gift value (diamonds/coins) */
+    value: number;
+    /** Rank category type (e.g. 3 = gifter) */
+    rank_type: number;
+    /** Time period type (e.g. 1 = hourly) */
+    rank_time_type: number;
+    /** Auto-thanks message configured by anchor */
+    auto_thanks_message?: string;
+    /** Schema URL for navigation */
+    schema_url?: string;
+    /** Highlight DM share status */
+    highlight_dm_share_status?: number;
+    /** Ranked user data */
+    user: RanklistUser;
+}
+interface RanklistSelfInfo {
+    rank: number;
+    score: number;
+    gap_description?: string;
+}
+/** Response from "online_audience" sub-endpoint — in-room top gifters */
+interface OnlineAudienceResponse {
+    status_code: number;
+    data: {
+        ranks: OnlineAudienceEntry[];
+        self_info?: RanklistSelfInfo;
+        currency?: string;
+        total?: number;
+    };
+}
+/** Response from "anchor_rank_list" sub-endpoint — gifter leaderboard */
+interface AnchorRankListResponse {
+    status_code: number;
+    data: {
+        rank_list: AnchorRankListEntry[];
+        /** Room where ranks were accumulated */
+        latest_room_id_str?: string;
+        /** Rank period start (unix timestamp) */
+        rank_time_begin?: number;
+        /** Rank period end (unix timestamp) */
+        rank_time_end?: number;
+        /** Whether to show rank summary */
+        show_rank_summary?: boolean;
+        /** Default rank type for this anchor */
+        default_rank_type?: number;
+    };
+}
+/** Entrance tab info from "entrance" sub-endpoint */
+interface EntranceTab {
+    title: string;
+    rank_type: number;
+    list_lynx_type?: number;
+}
+/** Entrance config for a single rank_type */
+interface EntranceInfo {
+    rank_type: number;
+    /** Whether the anchor appears in this ranking */
+    owner_on_rank: boolean;
+    /** Anchor's position in this ranking (0-based) */
+    owner_rank_idx?: number;
+    /** Current score in this ranking */
+    current_score?: number;
+    /** Countdown in seconds until ranking resets */
+    countdown?: number;
+    /** Window size in seconds (86400 = daily) */
+    window_size?: number;
+    /** Unix timestamp when ranking resets */
+    reset_time?: number;
+    /** Related tab to show when clicking this entrance */
+    related_tab_rank_type?: number;
+    /** Gap description with points needed to reach a rank */
+    affiliated_content?: {
+        gap_desc?: {
+            default_pattern: string;
+            pieces?: Array<{
+                string_value: string;
+                type: number;
+            }>;
+        };
     };
-    /** Second matching shape center */
-    point2: {
-        x: number;
-        y: number;
+    /** Class/League info */
+    class_info?: {
+        class_type: number;
+        star_count: number;
     };
-    /** Confidence score (0.0–1.0) */
-    confidence: number;
 }
+interface EntranceResponse {
+    status_code: number;
+    data: Array<{
+        group_type?: number;
+        Priority?: number;
+        data?: {
+            tabs?: EntranceTab[];
+            entrances?: EntranceInfo[];
+        };
+    }>;
+}
+type RanklistResponse = OnlineAudienceResponse | AnchorRankListResponse | EntranceResponse;
 
-type Listener = (...args: any[]) => void;
-declare class TypedEmitter {
-    private _listeners;
-    on(event: string, fn: Listener): this;
-    once(event: string, fn: Listener): this;
-    off(event: string, fn: Listener): this;
-    emit(event: string, ...args: any[]): boolean;
-    removeAllListeners(event?: string): this;
-}
-declare class TikTokLive extends TypedEmitter {
+declare class TikTokLive extends EventEmitter {
     private ws;
     private heartbeatTimer;
     private reconnectAttempts;
@@ -224,7 +359,7 @@ declare class TikTokLive extends TypedEmitter {
     private _connected;
     private _eventCount;
     private _roomId;
-    private _battleHosts;
+    private _ownerUserId;
     private readonly uniqueId;
     private readonly signServerUrl;
     private readonly apiKey;
@@ -232,119 +367,173 @@ declare class TikTokLive extends TypedEmitter {
     private readonly maxReconnectAttempts;
     private readonly heartbeatInterval;
     private readonly debug;
-    private readonly webSocketImpl?;
-    private WS;
+    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;
     emit<K extends keyof TikTokLiveEvents>(event: K, ...args: Parameters<TikTokLiveEvents[K]>): boolean;
-    private handleMessage;
     private handleFrame;
     private startHeartbeat;
     private stopHeartbeat;
 }
 
+interface GetRanklistOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** TikTok username to look up (auto-resolves room_id and anchor_id) */
+    uniqueId?: string;
+    /** Direct room ID (skip resolution) */
+    roomId?: string;
+    /** Direct anchor/owner ID (skip resolution) */
+    anchorId?: string;
+    /**
+     * TikTok session cookie string for authentication.
+     * Required — ranklist endpoints return 20003 without login.
+     * Example: "sessionid=abc123; sid_guard=def456"
+     */
+    sessionCookie?: string;
+    /**
+     * Which ranklist sub-endpoint to call:
+     * - "online_audience" (default) — top gifters with scores
+     * - "anchor_rank_list" — gifter ranking by rank_type
+     * - "entrance" — entrance UI metadata, tabs, gap-to-rank
+     */
+    type?: 'online_audience' | 'anchor_rank_list' | 'entrance';
+    /**
+     * For "anchor_rank_list" type only:
+     * - "1" = hourly ranking (default)
+     * - "8" = daily ranking
+     */
+    rankType?: string;
+}
 /**
- * TikTool API utilities for the sign-and-return API flow.
+ * Fetch ranked user lists from TikTok via the sign server.
  *
- * 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
+ * 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.
  *
- * @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.
+ * @example
+ * ```ts
+ * const data = await getRanklist({
+ *     apiKey: 'your-key',
+ *     uniqueId: 'katarina.live',
+ *     sessionCookie: 'sessionid=abc; sid_guard=def',
+ *     type: 'online_audience',
+ * });
+ *
+ * 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 resolveRoomId(uniqueId: string): Promise<string | null>;
-interface SignedUrlResponse {
+declare function getRanklist(opts: GetRanklistOptions): Promise<RanklistResponse>;
+
+interface GetRegionalRanklistOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication (Pro or Ultra tier required) */
+    apiKey: string;
+    /** TikTok username to look up (auto-resolves room_id and anchor_id) */
+    uniqueId?: string;
+    /** Direct room ID (skip resolution) */
+    roomId?: string;
+    /** Direct anchor/owner ID (skip resolution) */
+    anchorId?: string;
+    /**
+     * Ranking period:
+     * - "1" = Hourly
+     * - "8" = Daily (default)
+     * - "15" = Popular LIVE
+     * - "16" = League
+     */
+    rankType?: '1' | '8' | '15' | '16';
+    /**
+     * Sub-endpoint type:
+     * - "list" (default) — ranked users with scores
+     * - "entrance" — available ranking tabs/metadata
+     */
+    type?: 'list' | 'entrance';
+    /** Gap interval filter (default: "0") */
+    gapInterval?: string;
+}
+interface RegionalRanklistSignedResponse {
+    /** Always 0 on success */
     status_code: number;
-    action?: string;
+    /** Always "fetch_signed_url" */
+    action: string;
+    /** The signed TikTok URL to POST */
     signed_url: string;
+    /** HTTP method (always POST) */
+    method: string;
+    /** Required headers for the fetch */
     headers: Record<string, string>;
+    /** URL-encoded POST body */
+    body: string;
+    /** Cookies to include (ttwid etc.) — append your sessionid */
     cookies: string;
+    /** Human-readable note */
+    note: 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.
+ * Get a signed URL for fetching regional LIVE leaderboard data.
  *
- * Returns the actual TikTok data, or `null` if the user is not live.
- */
-declare function callApi(opts: CallApiOptions): Promise<any>;
-
-/**
- * Solve a puzzle (slider) CAPTCHA using the TikTool solver.
+ * **Two-step pattern**: TikTok sessions are IP-bound, so instead of
+ * server-side fetching, this returns a signed URL with headers/body
+ * that you POST from your own IP with your session cookie.
  *
- * @param apiKey - API key for authentication
- * @param puzzleB64 - Base64-encoded background image (PNG/JPEG)
- * @param pieceB64 - Base64-encoded puzzle piece image (PNG/JPEG)
- * @param serverUrl - Custom server URL (default: https://api.tik.tools)
- * @returns Solve result with slide position and confidence
- */
-declare function solvePuzzle(apiKey: string, puzzleB64: string, pieceB64: string, serverUrl?: string): Promise<PuzzleSolveResult>;
-/**
- * Solve a rotate (whirl) CAPTCHA using the TikTool solver.
+ * Requires **Pro** or **Ultra** API key tier.
  *
- * @param apiKey - API key for authentication
- * @param outerB64 - Base64-encoded outer ring image (PNG/JPEG)
- * @param innerB64 - Base64-encoded inner rotated image (PNG/JPEG)
- * @param serverUrl - Custom server URL (default: https://api.tik.tools)
- * @returns Solve result with rotation angle and confidence
- */
-declare function solveRotate(apiKey: string, outerB64: string, innerB64: string, serverUrl?: string): Promise<RotateSolveResult>;
-/**
- * Solve a shapes (3D matching) CAPTCHA using the TikTool solver.
+ * @example
+ * ```ts
+ * // Step 1: Get signed URL
+ * const signed = await getRegionalRanklist({
+ *     apiKey: 'your-pro-key',
+ *     roomId: '7607695933891218198',
+ *     anchorId: '7444599004337652758',
+ *     rankType: '8', // Daily
+ * });
  *
- * @param apiKey - API key for authentication
- * @param imageB64 - Base64-encoded CAPTCHA image with shape grid (PNG/JPEG)
- * @param serverUrl - Custom server URL (default: https://api.tik.tools)
- * @returns Solve result with two matching shape coordinates and confidence
+ * // Step 2: Fetch from YOUR IP with YOUR session
+ * const resp = await fetch(signed.signed_url, {
+ *     method: signed.method,
+ *     headers: { ...signed.headers, Cookie: `sessionid=YOUR_SID; ${signed.cookies}` },
+ *     body: signed.body,
+ * });
+ * const { data } = await resp.json();
+ * data.rank_view.ranks.forEach((r, i) =>
+ *     console.log(`${i+1}. ${r.user.nickname} — ${r.score} pts`)
+ * );
+ * ```
  */
-declare function solveShapes(apiKey: string, imageB64: string, serverUrl?: string): Promise<ShapesSolveResult>;
+declare function getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
 
-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 PuzzleSolveResult, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type RotateSolveResult, type ShapesSolveResult, type SignedUrlResponse, type SocialEvent, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, callApi, fetchSignedUrl, resolveLivePage, resolveRoomId, solvePuzzle, solveRotate, solveShapes };
+export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type GetRanklistOptions, type GetRegionalRanklistOptions, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type OnlineAudienceEntry, type OnlineAudienceResponse, type QuestionEvent, type RankUpdateEvent, type RanklistResponse, type RanklistSelfInfo, type RanklistUser, type RegionalRanklistSignedResponse, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, getRanklist, getRegionalRanklist };