@tiktool/live 2.5.2 → 2.6.0

package/dist/index.d.ts

@@ -1,3 +1,581 @@
-export { TikTokLive } from './client.js';
-export { GetRanklistOptions, GetRegionalRanklistOptions, RegionalRanklistSignedResponse, getRanklist, getRegionalRanklist } from './api.js';
-export { AnchorRankListEntry, AnchorRankListResponse, BarrageEvent, BaseEvent, BattleArmiesEvent, BattleEvent, BattleTaskEvent, BattleTeam, BattleTeamUser, ChatEvent, ControlEvent, EmoteChatEvent, EntranceInfo, EntranceResponse, EntranceTab, EnvelopeEvent, GiftEvent, LikeEvent, LinkMicEvent, LiveEvent, LiveIntroEvent, MemberEvent, OnlineAudienceEntry, OnlineAudienceResponse, QuestionEvent, RankUpdateEvent, RanklistResponse, RanklistSelfInfo, RanklistUser, RoomEvent, RoomInfo, RoomUserSeqEvent, SocialEvent, SubscribeEvent, TikTokLiveEvents, TikTokLiveOptions, TikTokUser, UnknownEvent } from './types.js';
+import { EventEmitter } from 'events';
+import * as http from 'http';
+
+interface TikTokUser {
+    id: string;
+    nickname: string;
+    uniqueId: string;
+    profilePicture?: string;
+    profilePictureUrl?: string;
+    badges?: string[];
+    /** User's gifter/spender level (1-50). Higher = more coins spent platform-wide. */
+    payGrade?: number;
+}
+interface BaseEvent {
+    type: string;
+    timestamp: number;
+    msgId: string;
+}
+interface ChatEvent extends BaseEvent {
+    type: 'chat';
+    user: TikTokUser;
+    comment: string;
+}
+interface MemberEvent extends BaseEvent {
+    type: 'member';
+    user: TikTokUser;
+    action: number;
+}
+interface LikeEvent extends BaseEvent {
+    type: 'like';
+    user: TikTokUser;
+    likeCount: number;
+    totalLikes: number;
+}
+interface GiftEvent extends BaseEvent {
+    type: 'gift';
+    user: TikTokUser;
+    giftId: number;
+    giftName: string;
+    diamondCount: number;
+    repeatCount: number;
+    repeatEnd: boolean;
+    combo: boolean;
+    giftType: number;
+    groupId: string;
+    giftPictureUrl?: string;
+}
+interface SocialEvent extends BaseEvent {
+    type: 'social';
+    user: TikTokUser;
+    action: 'follow' | 'share' | string;
+}
+interface RoomUserSeqEvent extends BaseEvent {
+    type: 'roomUserSeq';
+    viewerCount: number;
+    totalViewers: number;
+}
+interface BattleTeamUser {
+    user: TikTokUser;
+    score: number;
+}
+interface BattleTeam {
+    hostUserId: string;
+    score: number;
+    users: BattleTeamUser[];
+    hostUser?: TikTokUser;
+}
+interface BattleEvent extends BaseEvent {
+    type: 'battle';
+    battleId: string;
+    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;
+    };
+    scoreUpdateTime?: number;
+    giftSentTime?: 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';
+    user: TikTokUser;
+    subMonth: number;
+}
+interface EmoteChatEvent extends BaseEvent {
+    type: 'emoteChat';
+    user: TikTokUser;
+    emoteId: string;
+    emoteUrl: string;
+    emoteName?: string;
+}
+interface EnvelopeEvent extends BaseEvent {
+    type: 'envelope';
+    envelopeId: string;
+    diamondCount: number;
+}
+interface QuestionEvent extends BaseEvent {
+    type: 'question';
+    user: TikTokUser;
+    questionText: string;
+}
+interface ControlEvent extends BaseEvent {
+    type: 'control';
+    action: number;
+}
+interface RoomEvent extends BaseEvent {
+    type: 'room';
+    status: number;
+}
+interface LiveIntroEvent extends BaseEvent {
+    type: 'liveIntro';
+    roomId: string;
+    title: string;
+}
+interface RankUpdateEvent extends BaseEvent {
+    type: 'rankUpdate';
+    rankType: string;
+    rankList: Array<{
+        user: TikTokUser;
+        rank: number;
+        score: number;
+    }>;
+}
+interface LinkMicEvent extends BaseEvent {
+    type: 'linkMic';
+    action: string;
+    users: TikTokUser[];
+}
+interface UnknownEvent extends BaseEvent {
+    type: 'unknown';
+    method: string;
+}
+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;
+    roomInfo: (info: RoomInfo) => void;
+    error: (error: Error) => void;
+    chat: (event: ChatEvent) => void;
+    member: (event: MemberEvent) => void;
+    like: (event: LikeEvent) => void;
+    gift: (event: GiftEvent) => void;
+    social: (event: SocialEvent) => void;
+    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;
+    question: (event: QuestionEvent) => void;
+    control: (event: ControlEvent) => void;
+    room: (event: RoomEvent) => void;
+    liveIntro: (event: LiveIntroEvent) => void;
+    rankUpdate: (event: RankUpdateEvent) => void;
+    linkMic: (event: LinkMicEvent) => void;
+    unknown: (event: UnknownEvent) => void;
+    event: (event: LiveEvent) => void;
+}
+interface RoomInfo {
+    roomId: string;
+    wsHost: string;
+    clusterRegion: string;
+    connectedAt: string;
+    ownerUserId?: string;
+}
+interface TikTokLiveOptions {
+    uniqueId: string;
+    signServerUrl?: string;
+    apiKey: string;
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    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;
+    /**
+     * HTTP agent for routing connections through a proxy.
+     * Pass an HttpsProxyAgent (or any http.Agent) to route both the
+     * initial HTTP request and WebSocket connection through a proxy.
+     *
+     * Example:
+     *   import { HttpsProxyAgent } from 'https-proxy-agent';
+     *   agent: new HttpsProxyAgent('http://user:pass@host:port')
+     */
+    agent?: http.Agent;
+    /**
+     * If you already know the room ID (e.g. from a leaderboard API),
+     * pass it here to skip the HTML page scrape entirely.
+     * This avoids geo-restriction issues and speeds up connection.
+     */
+    roomId?: string;
+    /**
+     * Pre-fetched ttwid cookie. When provided along with roomId,
+     * the library skips the HTTP fetch to tiktok.com entirely.
+     * Fetch once and share across multiple TikTokLive instances.
+     */
+    ttwid?: 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;
+}
+/**
+ * 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;
+            }>;
+        };
+    };
+    /** Class/League info */
+    class_info?: {
+        class_type: number;
+        star_count: number;
+    };
+}
+interface EntranceResponse {
+    status_code: number;
+    data: Array<{
+        group_type?: number;
+        Priority?: number;
+        data?: {
+            tabs?: EntranceTab[];
+            entrances?: EntranceInfo[];
+        };
+    }>;
+}
+type RanklistResponse = OnlineAudienceResponse | AnchorRankListResponse | EntranceResponse;
+
+declare class TikTokLive extends EventEmitter {
+    private ws;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    private intentionalClose;
+    private _connected;
+    private _eventCount;
+    private _roomId;
+    private _ownerUserId;
+    private readonly uniqueId;
+    private readonly signServerUrl;
+    private readonly apiKey;
+    private readonly autoReconnect;
+    private readonly maxReconnectAttempts;
+    private readonly heartbeatInterval;
+    private readonly debug;
+    private _sessionId?;
+    private _ttTargetIdc?;
+    private readonly proxyAgent?;
+    private readonly _presetRoomId?;
+    private readonly _presetTtwid?;
+    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 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;
+}
+/**
+ * Fetch ranked user lists from TikTok via the sign server.
+ *
+ * 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
+ * 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 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;
+    /**
+     * 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 */
+    status_code: number;
+    /** 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;
+}
+/**
+ * Get a signed URL for fetching regional LIVE leaderboard data.
+ *
+ * **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.
+ *
+ * Requires **Pro** or **Ultra** API key tier.
+ *
+ * @example
+ * ```ts
+ * // Step 1: Get signed URL
+ * const signed = await getRegionalRanklist({
+ *     apiKey: 'your-pro-key',
+ *     roomId: '7607695933891218198',
+ *     anchorId: '7444599004337652758',
+ *     rankType: '8', // Daily
+ * });
+ *
+ * // 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 getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
+
+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 };