@tiktool/live 2.6.7 → 2.7.1

package/dist/index.d.mts

@@ -1,15 +1,13 @@
 import { EventEmitter } from 'events';
-import * as http from 'http';
 
 interface TikTokUser {
     id: string;
     nickname: string;
     uniqueId: string;
     profilePicture?: string;
-    profilePictureUrl?: string;
+    /** High-resolution avatar URL from protobuf field 11 (avatarLarge ~720x720) */
+    avatarLargeUrl?: string;
     badges?: string[];
-    /** User's gifter/spender level (1-50). Higher = more coins spent platform-wide. */
-    payGrade?: number;
 }
 interface BaseEvent {
     type: string;
@@ -20,6 +18,11 @@ interface ChatEvent extends BaseEvent {
     type: 'chat';
     user: TikTokUser;
     comment: string;
+    emotes?: Array<{
+        emoteId: string;
+        imageUrl: string;
+        placeInComment: number;
+    }>;
 }
 interface MemberEvent extends BaseEvent {
     type: 'member';
@@ -43,7 +46,6 @@ interface GiftEvent extends BaseEvent {
     combo: boolean;
     giftType: number;
     groupId: string;
-    giftPictureUrl?: string;
 }
 interface SocialEvent extends BaseEvent {
     type: 'social';
@@ -61,9 +63,9 @@ interface BattleTeamUser {
 }
 interface BattleTeam {
     hostUserId: string;
+    hostUser?: TikTokUser;
     score: number;
     users: BattleTeamUser[];
-    hostUser?: TikTokUser;
 }
 interface BattleEvent extends BaseEvent {
     type: 'battle';
@@ -71,45 +73,20 @@ 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;
-    };
-    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;
+    /** Battle start timestamp in milliseconds (from f18.f2) */
+    battleStartMs: number;
+    /** Total battle duration in seconds (from f18.f3, typically 300) */
+    battleDurationSeconds: number;
+    /** Seconds remaining in the battle, computed as max(0, duration - elapsed). Note: uses VPS clock, may be off by up to 30s */
+    timeLeftSeconds: number;
+    /** Battle end timestamp in milliseconds (battleStartMs + duration*1000). Use for clock-independent timer: Math.max(0, (endTimeMs - Date.now()) / 1000) */
+    endTimeMs: number;
 }
 interface SubscribeEvent extends BaseEvent {
     type: 'subscribe';
@@ -121,7 +98,6 @@ interface EmoteChatEvent extends BaseEvent {
     user: TikTokUser;
     emoteId: string;
     emoteUrl: string;
-    emoteName?: string;
 }
 interface EnvelopeEvent extends BaseEvent {
     type: 'envelope';
@@ -164,7 +140,7 @@ 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;
+type LiveEvent = ChatEvent | MemberEvent | LikeEvent | GiftEvent | SocialEvent | RoomUserSeqEvent | BattleEvent | BattleArmiesEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
 interface TikTokLiveEvents {
     connected: () => void;
     disconnected: (code: number, reason: string) => void;
@@ -178,8 +154,6 @@ 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;
@@ -197,7 +171,30 @@ interface RoomInfo {
     wsHost: string;
     clusterRegion: string;
     connectedAt: string;
-    ownerUserId?: string;
+}
+/** Quality tiers available for live stream video */
+type StreamQuality = 'FULL_HD1' | 'HD1' | 'SD1' | 'SD2' | 'origin' | string;
+/** Stream URLs for a specific quality level */
+interface StreamUrls {
+    /** FLV pull URL for this quality */
+    flv?: string;
+    /** HLS (m3u8) pull URL for this quality */
+    hls?: string;
+}
+/** Full stream info returned by getStreamUrl() */
+interface StreamInfo {
+    /** Room ID of the live stream */
+    roomId: string;
+    /** Whether the user is currently live */
+    alive: boolean;
+    /** Stream URLs keyed by quality (FULL_HD1, HD1, SD1, SD2) */
+    streamUrls: Record<StreamQuality, StreamUrls>;
+    /** Recommended default quality */
+    defaultQuality: StreamQuality;
+    /** Best available FLV URL (convenience shortcut) */
+    flvPullUrl?: string;
+    /** Best available HLS URL (convenience shortcut) */
+    hlsPullUrl?: string;
 }
 interface TikTokLiveOptions {
     uniqueId: string;
@@ -207,236 +204,10 @@ interface TikTokLiveOptions {
     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.
-     */
+    /** Pre-resolved room ID — skips direct TikTok page fetch when provided with sessionId */
     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;
-/** Streamer info in a feed room entry */
-interface FeedRoomOwner {
-    /** TikTok user ID */
-    id_str: string;
-    /** Username (@handle) */
-    display_id: string;
-    /** Display name */
-    nickname: string;
-    /** Avatar thumbnail URLs */
-    avatar_thumb?: {
-        url_list: string[];
-    };
-    /** Avatar large URLs */
-    avatar_large?: {
-        url_list: string[];
-    };
-}
-/** A single live room entry from the feed */
-interface FeedRoom {
-    /** Room ID */
-    id_str: string;
-    /** Stream title */
-    title: string;
-    /** Current viewer count */
-    user_count: number;
-    /** Stream cover image URL */
-    cover?: {
-        url_list: string[];
-    };
-    /** Streamer info */
-    owner: FeedRoomOwner;
-    /** Stream status (2 = live) */
-    status: number;
-    /** Stream start time (unix seconds) */
-    create_time?: number;
-    /** Like count */
-    like_count?: number;
-    /** Hashtag IDs */
-    hashtag_ids?: string[];
-}
-/** Signed-URL response from GET/POST /webcast/feed */
-interface FeedSignedResponse {
-    /** Always 0 on success */
-    status_code: number;
-    /** The signed TikTok URL to fetch */
-    signed_url: string;
-    /** Required headers */
-    headers: Record<string, string>;
-    /** Cookies to include (ttwid, sessionid, etc.) */
-    cookies?: string;
-    /** Region used */
-    region: string;
-    /** Channel ID used */
-    channel_id: string;
-    /** Remaining daily feed calls */
-    feed_remaining: number;
-    /** Daily feed call limit */
-    feed_limit: number;
-    /** Human-readable instructions */
-    note: string;
+    /** Pre-resolved ttwid session cookie — skips direct TikTok page fetch when provided with roomId */
+    sessionId?: string;
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -445,9 +216,12 @@ declare class TikTokLive extends EventEmitter {
     private reconnectAttempts;
     private intentionalClose;
     private _connected;
+    private _destroyed;
     private _eventCount;
     private _roomId;
-    private _ownerUserId;
+    private static readonly MAX_BATTLE_HOSTS;
+    private _battleHosts;
+    private _pendingHostResolves;
     private readonly uniqueId;
     private readonly signServerUrl;
     private readonly apiKey;
@@ -455,453 +229,55 @@ declare class TikTokLive extends EventEmitter {
     private readonly maxReconnectAttempts;
     private readonly heartbeatInterval;
     private readonly debug;
-    private _sessionId?;
-    private _ttTargetIdc?;
-    private readonly proxyAgent?;
-    private readonly _presetRoomId?;
-    private readonly _presetTtwid?;
+    private readonly _presetRoomId;
+    private readonly _presetSessionId;
     constructor(options: TikTokLiveOptions);
     connect(): Promise<void>;
     disconnect(): void;
+    /**
+     * Fully destroy the client, releasing all resources and listeners.
+     * After calling destroy(), the instance cannot be reused — create a new one.
+     */
+    destroy(): void;
     get connected(): boolean;
+    get destroyed(): 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.
+     * Get live stream video URLs for a TikTok user.
+     * Returns FLV & HLS URLs segmented by quality (FULL_HD1, HD1, SD1, SD2).
+     * This is a standalone method — no WebSocket connection required.
+     *
+     * @example
+     * ```ts
+     * const stream = await TikTokLive.getStreamUrl({
+     *   uniqueId: 'username',
+     *   apiKey: 'your-api-key',
+     * });
+     * if (stream.alive) {
+     *   console.log(stream.streamUrls.HD1?.hls); // HLS URL for HD quality
+     *   console.log(stream.flvPullUrl);           // Best FLV URL
+     * }
+     * ```
      */
-    buildSessionCookieHeader(): string | undefined;
+    static getStreamUrl(options: {
+        uniqueId: string;
+        apiKey: string;
+        signServerUrl?: string;
+        quality?: string;
+    }): Promise<StreamInfo>;
     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;
-}
-
-/**
- * TikTokCaptions — Real-time speech-to-text transcription and translation for TikTok LIVE streams.
- *
- * AI-powered audio transcription with speaker diarization, multi-language auto-detection,
- * real-time translation, and sub-second latency. Connects via WebSocket to the TikTool
- * captions relay for continuous streaming transcription.
- *
- * @example
- * ```ts
- * import { TikTokCaptions } from '@tiktool/live';
- *
- * const captions = new TikTokCaptions({
- *   uniqueId: 'username',
- *   apiKey: 'your-api-key',
- *   language: 'en',      // translate to English
- * });
- *
- * captions.on('caption', (data) => {
- *   console.log(`[${data.language}] ${data.text}`);
- * });
- *
- * captions.on('translation', (data) => {
- *   console.log(`[translated] ${data.text}`);
- * });
- *
- * await captions.start();
- * ```
- */
-
-interface TikTokCaptionsOptions {
-    /** TikTok username to transcribe (without @) */
-    uniqueId: string;
-    /** API key for authentication */
-    apiKey: string;
-    /** Source language hint (e.g. 'en', 'ja'). Leave empty for auto-detection. */
-    language?: string;
-    /** Target language for real-time translation (e.g. 'en', 'es', 'fr'). One language per session. */
-    translate?: string;
-    /** Enable speaker diarization to identify individual speakers (default: true) */
-    diarization?: boolean;
-    /** Max session duration in minutes before auto-disconnect (default: 60, max: 300) */
-    maxDurationMinutes?: number;
-    /** Custom server URL (default: wss://api.tik.tools) */
-    signServerUrl?: string;
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Auto-reconnect on disconnect */
-    autoReconnect?: boolean;
-    /** Max reconnect attempts (default: 5) */
-    maxReconnectAttempts?: number;
-}
-interface CaptionData {
-    /** Transcribed text */
-    text: string;
-    /** Detected source language */
-    language: string;
-    /** Whether this is the final version of this segment */
-    isFinal: boolean;
-    /** Confidence score (0-1) */
-    confidence: number;
-    /** Speaker identifier (if available) */
-    speaker?: string;
-    /** Start time in milliseconds */
-    startMs?: number;
-    /** End time in milliseconds */
-    endMs?: number;
-}
-interface TranslationData {
-    /** Translated text */
-    text: string;
-    /** Target language */
-    language: string;
-    /** Whether this is the final version */
-    isFinal: boolean;
-    /** Confidence score (0-1) */
-    confidence: number;
-    /** Speaker identifier (if available) */
-    speaker?: string;
-}
-interface CaptionCredits {
-    /** Credits remaining */
-    remaining: number;
-    /** Total credits purchased */
-    total: number;
-    /** Credits used in this session */
-    used: number;
-    /** Whether credits are low */
-    warning: boolean;
-}
-interface CaptionStatus {
-    /** Current status */
-    status: 'connecting' | 'waiting' | 'live' | 'transcribing' | 'ended' | 'switching_language' | 'language_switched' | 'stream_ended';
-    /** TikTok username */
-    uniqueId?: string;
-    /** Room ID (once resolved) */
-    roomId?: string;
-    /** Language (for language switch events) */
-    language?: string;
-    /** Status message */
-    message?: string;
-}
-interface CaptionError {
-    /** Error code */
-    code: string;
-    /** Human-readable error message */
-    message: string;
-}
-interface TikTokCaptionsEvents {
-    /** Fired for each transcription token */
-    caption: (data: CaptionData) => void;
-    /** Fired for each translated token */
-    translation: (data: TranslationData) => void;
-    /** Status changes (connecting, live, transcribing, etc.) */
-    status: (data: CaptionStatus) => void;
-    /** Credit balance updates */
-    credits: (data: CaptionCredits) => void;
-    /** Low credit warning */
-    credits_low: (data: {
-        remaining: number;
-        total: number;
-        percent: number;
-    }) => void;
-    /** Error events */
-    error: (data: CaptionError) => void;
-    /** WebSocket connected */
-    connected: () => void;
-    /** WebSocket disconnected */
-    disconnected: (code: number, reason: string) => void;
-}
-declare class TikTokCaptions extends EventEmitter {
-    private ws;
-    private _connected;
-    private intentionalClose;
-    private reconnectAttempts;
-    private readonly uniqueId;
-    private readonly apiKey;
-    private readonly serverUrl;
-    private readonly autoReconnect;
-    private readonly maxReconnectAttempts;
-    private readonly debug;
-    private readonly _translate;
-    private readonly _diarization;
-    private readonly _maxDurationMinutes;
-    private _language;
-    private streamAbortController;
-    private flvExtractor;
-    private streamUrl;
-    constructor(options: TikTokCaptionsOptions);
     /**
-     * Start real-time captions for the configured TikTok user.
-     * Connects to the captions WebSocket relay and begins transcription
-     * once the user goes live (or immediately if already live).
+     * Resolve unknown host user IDs via the sign server API.
+     * Caches results and re-emits the battleArmies event with enriched hostUser data.
      */
-    start(): Promise<void>;
-    /**
-     * Stop captions and disconnect.
-     */
-    stop(): void;
-    /**
-     * Switch the translation target language on-the-fly.
-     * Causes a brief interruption while the transcription engine reconfigures.
-     */
-    setLanguage(language: string): void;
-    /**
-     * Request a credit balance update from the server.
-     */
-    getCredits(): void;
-    /** Whether the WebSocket is currently connected */
-    get connected(): boolean;
-    /** The current target language */
-    get language(): string;
-    on<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
-    once<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
-    off<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
-    emit<K extends keyof TikTokCaptionsEvents>(event: K, ...args: Parameters<TikTokCaptionsEvents[K]>): boolean;
-    private buildWsUrl;
-    private send;
-    private handleMessage;
-    /**
-     * Connect to the TikTok FLV stream and extract audio.
-     * Sends binary audio buffers to the server via WebSocket.
-     */
-    private connectToStream;
-}
-
-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>;
-
-interface GetLiveFeedOptions {
-    /** API server URL (default: https://api.tik.tools) */
-    serverUrl?: string;
-    /** API key for authentication (Pro or Ultra tier required) */
-    apiKey: string;
-    /** Region code (default: 'US') */
-    region?: string;
-    /**
-     * Feed channel:
-     * - '87' = Recommended (default)
-     * - '86' = Suggested
-     * - '42' = Following
-     * - '1111006' = Gaming
-     */
-    channelId?: string;
-    /** Number of rooms to return (max 50, default 20) */
-    count?: number;
-    /** Pagination cursor from previous response (default: '0') */
-    maxTime?: string;
-    /** TikTok sessionid cookie — required for populated results */
-    sessionId?: string;
-    /** TikTok ttwid cookie */
-    ttwid?: string;
-    /** TikTok msToken cookie */
-    msToken?: string;
+    private resolveHostUsers;
+    private startHeartbeat;
+    private stopHeartbeat;
 }
-/**
- * Get a signed URL for fetching the TikTok LIVE feed.
- *
- * **Two-step pattern**: Returns a signed URL with headers and cookies.
- * Fetch the signed URL from your own IP to get the feed data.
- *
- * Requires **Pro** or **Ultra** API key tier.
- *
- * @example
- * ```ts
- * // Step 1: Get signed URL
- * const signed = await getLiveFeed({
- *     apiKey: 'your-pro-key',
- *     sessionId: 'your-tiktok-sessionid',
- *     region: 'US',
- *     count: 10,
- * });
- *
- * // Step 2: Fetch from YOUR IP
- * const resp = await fetch(signed.signed_url, {
- *     headers: { ...signed.headers, Cookie: signed.cookies || '' },
- * });
- * const data = await resp.json();
- * console.log(`Found ${data.data?.length || 0} live rooms`);
- *
- * // Step 3: Load more (pagination)
- * const nextSigned = await getLiveFeed({
- *     apiKey: 'your-pro-key',
- *     sessionId: 'your-tiktok-sessionid',
- *     maxTime: data.extra?.max_time || '0',
- * });
- * ```
- */
-declare function getLiveFeed(opts: GetLiveFeedOptions): Promise<FeedSignedResponse>;
-/**
- * Convenience: Get the feed AND fetch the signed URL in one step.
- * Returns the parsed JSON feed data from TikTok.
- *
- * @example
- * ```ts
- * const feed = await fetchFeed({
- *     apiKey: 'your-pro-key',
- *     sessionId: 'your-tiktok-sessionid',
- *     region: 'GR',
- *     count: 10,
- * });
- * for (const entry of feed.data || []) {
- *     const room = entry.data;
- *     console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
- * }
- * ```
- */
-declare function fetchFeed(opts: GetLiveFeedOptions): Promise<any>;
 
-export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type CaptionCredits, type CaptionData, type CaptionError, type CaptionStatus, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type FeedRoom, type FeedRoomOwner, type FeedSignedResponse, type GetLiveFeedOptions, 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, TikTokCaptions, type TikTokCaptionsEvents, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type TranslationData, type UnknownEvent, fetchFeed, getLiveFeed, getRanklist, getRegionalRanklist };
+export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTeam, type BattleTeamUser, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EnvelopeEvent, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type QuestionEvent, type RankUpdateEvent, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type StreamInfo, type StreamQuality, type StreamUrls, type SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };