@tiktool/live 2.7.1 → 2.9.0

package/dist/index.d.mts

@@ -74,6 +74,24 @@ interface BattleEvent extends BaseEvent {
     battleDuration: number;
     teams: BattleTeam[];
 }
+interface BattleContributor {
+    /** TikTok userId of the gifter */
+    userId: string;
+    /** Diamond score this gifter contributed to the host's team */
+    score: number;
+    /** Display nickname (may be empty if not set on the account) */
+    nickname: string;
+}
+interface BattleHost {
+    /** TikTok userId of the host on this PK side */
+    hostUserId: string;
+    /** Total diamonds for this host's team */
+    teamTotalScore: number;
+    /** Side index (0 = left side, 1 = right side, …) */
+    teamIdx: number;
+    /** Per-gifter breakdown, sorted MVP first (highest score → lowest). */
+    contributors: BattleContributor[];
+}
 interface BattleArmiesEvent extends BaseEvent {
     type: 'battleArmies';
     battleId: string;
@@ -87,6 +105,58 @@ interface BattleArmiesEvent extends BaseEvent {
     timeLeftSeconds: number;
     /** Battle end timestamp in milliseconds (battleStartMs + duration*1000). Use for clock-independent timer: Math.max(0, (endTimeMs - Date.now()) / 1000) */
     endTimeMs: number;
+    /** Stable match ID across multi-round PK (from top-level field 2). */
+    matchId?: string;
+    /** Per-round session ID (from top-level field 4). */
+    sessionId?: string;
+    /** TikTok server-side clock at frame emit (ms epoch). */
+    serverTsMs?: number;
+    /** Hex string tag used by TikTok for per-session matching (~34 chars). */
+    sessionTag?: string;
+    /** Total battle duration in seconds (from f18.f3). Alias for battleDurationSeconds. */
+    durationSec?: number;
+    /** Seconds remaining computed using TikTok server clock (no VPS drift). */
+    secsRemaining?: number;
+    /**
+     * Multi-guest host breakdown — one entry per host on a PK side.
+     * Each entry includes per-gifter contributors sorted MVP first.
+     */
+    hosts?: BattleHost[];
+}
+/**
+ * Battle Item Card event — booster multipliers (x2/x3), gloves, mist, thunder,
+ * extra-time, match-guide, etc. Emitted on `battleItemCard`.
+ */
+interface BattleItemCardEvent extends BaseEvent {
+    type: 'battleItemCard';
+    battleId: string;
+    /** 2=gloves/crit, 3=mist, 4=match_guide, 10=x2?, 11=x3, … */
+    cardType: number;
+    /** 'gloves' | 'mist' | 'booster_x2' | 'booster_x3' | 'match_guide' | 'thunder' | 'extra_time' | raw resource key */
+    effect: string;
+    /** Raw TikTok resource key (e.g. 'pm_mt_boost_crit_name'). */
+    effectKey: string;
+    /** 2 or 3 for booster_x2/x3, otherwise 0. */
+    multiplier: number;
+    senderUserId: string;
+    senderNickname: string;
+    senderUniqueId: string;
+    /** First CDN URL for sender's avatar (best-resolution). */
+    senderAvatarUrl: string;
+    /** Unix seconds when the buff activated. */
+    activatedAtSec: number;
+    /** Total active duration in seconds. */
+    durationSec: number;
+    /** Unix seconds when the buff ends. */
+    endsAtSec: number;
+    /** Comment template, e.g. "{0:user} sent 1 magic mist". */
+    commentTemplate: string;
+    /** Full TikTok CDN URL for the card art (webp/jpeg). */
+    iconUrl: string;
+    /** Short identifier e.g. 'card_mist_v3' / 'card_crit_v3' / 'top3_buffer'. */
+    iconKey: string;
+    /** Hex e.g. '#BCD9E0' (mist blue), '#E0D4BC' (gloves tan). */
+    accentColor: string;
 }
 interface SubscribeEvent extends BaseEvent {
     type: 'subscribe';
@@ -140,7 +210,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 | BattleItemCardEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
 interface TikTokLiveEvents {
     connected: () => void;
     disconnected: (code: number, reason: string) => void;
@@ -154,6 +224,7 @@ interface TikTokLiveEvents {
     roomUserSeq: (event: RoomUserSeqEvent) => void;
     battle: (event: BattleEvent) => void;
     battleArmies: (event: BattleArmiesEvent) => void;
+    battleItemCard: (event: BattleItemCardEvent) => void;
     subscribe: (event: SubscribeEvent) => void;
     emoteChat: (event: EmoteChatEvent) => void;
     envelope: (event: EnvelopeEvent) => void;
@@ -208,6 +279,18 @@ interface TikTokLiveOptions {
     roomId?: string;
     /** Pre-resolved ttwid session cookie — skips direct TikTok page fetch when provided with roomId */
     sessionId?: string;
+    /**
+     * Optional HTTP/HTTPS proxy URL. When set, the SDK's outbound WebSocket
+     * (and HTTP requests) tunnel through this proxy instead of your container's
+     * IP. Required when running 50+ concurrent direct connections to avoid
+     * TikTok's per-IP rate limiting (manifests as code=1006 abnormal closes).
+     *
+     * Format: `http://user:pass@host:port` or `http://host:port`.
+     *
+     * Example (Webshare residential):
+     *   proxy: 'http://USER:PASS@p.webshare.io:80'
+     */
+    proxy?: string;
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -231,12 +314,18 @@ declare class TikTokLive extends EventEmitter {
     private readonly debug;
     private readonly _presetRoomId;
     private readonly _presetSessionId;
+    private readonly proxyUrl;
     constructor(options: TikTokLiveOptions);
+    /**
+     * Build an HttpsProxyAgent when `proxy` option is set, else undefined.
+     * Lazy-required so users without proxy don't pay the dependency cost.
+     */
+    private getProxyAgent;
     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.
+     * After calling destroy(), the instance cannot be reused — create a new one.
      */
     destroy(): void;
     get connected(): boolean;
@@ -246,7 +335,7 @@ declare class TikTokLive extends EventEmitter {
     /**
      * 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.
+     * This is a standalone method — no WebSocket connection required.
      *
      * @example
      * ```ts
@@ -280,4 +369,4 @@ declare class TikTokLive extends EventEmitter {
     private stopHeartbeat;
 }
 
-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 };
+export { type BaseEvent, type BattleArmiesEvent, type BattleContributor, type BattleEvent, type BattleHost, type BattleItemCardEvent, 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 };

package/dist/index.d.ts

@@ -74,6 +74,24 @@ interface BattleEvent extends BaseEvent {
     battleDuration: number;
     teams: BattleTeam[];
 }
+interface BattleContributor {
+    /** TikTok userId of the gifter */
+    userId: string;
+    /** Diamond score this gifter contributed to the host's team */
+    score: number;
+    /** Display nickname (may be empty if not set on the account) */
+    nickname: string;
+}
+interface BattleHost {
+    /** TikTok userId of the host on this PK side */
+    hostUserId: string;
+    /** Total diamonds for this host's team */
+    teamTotalScore: number;
+    /** Side index (0 = left side, 1 = right side, …) */
+    teamIdx: number;
+    /** Per-gifter breakdown, sorted MVP first (highest score → lowest). */
+    contributors: BattleContributor[];
+}
 interface BattleArmiesEvent extends BaseEvent {
     type: 'battleArmies';
     battleId: string;
@@ -87,6 +105,58 @@ interface BattleArmiesEvent extends BaseEvent {
     timeLeftSeconds: number;
     /** Battle end timestamp in milliseconds (battleStartMs + duration*1000). Use for clock-independent timer: Math.max(0, (endTimeMs - Date.now()) / 1000) */
     endTimeMs: number;
+    /** Stable match ID across multi-round PK (from top-level field 2). */
+    matchId?: string;
+    /** Per-round session ID (from top-level field 4). */
+    sessionId?: string;
+    /** TikTok server-side clock at frame emit (ms epoch). */
+    serverTsMs?: number;
+    /** Hex string tag used by TikTok for per-session matching (~34 chars). */
+    sessionTag?: string;
+    /** Total battle duration in seconds (from f18.f3). Alias for battleDurationSeconds. */
+    durationSec?: number;
+    /** Seconds remaining computed using TikTok server clock (no VPS drift). */
+    secsRemaining?: number;
+    /**
+     * Multi-guest host breakdown — one entry per host on a PK side.
+     * Each entry includes per-gifter contributors sorted MVP first.
+     */
+    hosts?: BattleHost[];
+}
+/**
+ * Battle Item Card event — booster multipliers (x2/x3), gloves, mist, thunder,
+ * extra-time, match-guide, etc. Emitted on `battleItemCard`.
+ */
+interface BattleItemCardEvent extends BaseEvent {
+    type: 'battleItemCard';
+    battleId: string;
+    /** 2=gloves/crit, 3=mist, 4=match_guide, 10=x2?, 11=x3, … */
+    cardType: number;
+    /** 'gloves' | 'mist' | 'booster_x2' | 'booster_x3' | 'match_guide' | 'thunder' | 'extra_time' | raw resource key */
+    effect: string;
+    /** Raw TikTok resource key (e.g. 'pm_mt_boost_crit_name'). */
+    effectKey: string;
+    /** 2 or 3 for booster_x2/x3, otherwise 0. */
+    multiplier: number;
+    senderUserId: string;
+    senderNickname: string;
+    senderUniqueId: string;
+    /** First CDN URL for sender's avatar (best-resolution). */
+    senderAvatarUrl: string;
+    /** Unix seconds when the buff activated. */
+    activatedAtSec: number;
+    /** Total active duration in seconds. */
+    durationSec: number;
+    /** Unix seconds when the buff ends. */
+    endsAtSec: number;
+    /** Comment template, e.g. "{0:user} sent 1 magic mist". */
+    commentTemplate: string;
+    /** Full TikTok CDN URL for the card art (webp/jpeg). */
+    iconUrl: string;
+    /** Short identifier e.g. 'card_mist_v3' / 'card_crit_v3' / 'top3_buffer'. */
+    iconKey: string;
+    /** Hex e.g. '#BCD9E0' (mist blue), '#E0D4BC' (gloves tan). */
+    accentColor: string;
 }
 interface SubscribeEvent extends BaseEvent {
     type: 'subscribe';
@@ -140,7 +210,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 | BattleItemCardEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
 interface TikTokLiveEvents {
     connected: () => void;
     disconnected: (code: number, reason: string) => void;
@@ -154,6 +224,7 @@ interface TikTokLiveEvents {
     roomUserSeq: (event: RoomUserSeqEvent) => void;
     battle: (event: BattleEvent) => void;
     battleArmies: (event: BattleArmiesEvent) => void;
+    battleItemCard: (event: BattleItemCardEvent) => void;
     subscribe: (event: SubscribeEvent) => void;
     emoteChat: (event: EmoteChatEvent) => void;
     envelope: (event: EnvelopeEvent) => void;
@@ -208,6 +279,18 @@ interface TikTokLiveOptions {
     roomId?: string;
     /** Pre-resolved ttwid session cookie — skips direct TikTok page fetch when provided with roomId */
     sessionId?: string;
+    /**
+     * Optional HTTP/HTTPS proxy URL. When set, the SDK's outbound WebSocket
+     * (and HTTP requests) tunnel through this proxy instead of your container's
+     * IP. Required when running 50+ concurrent direct connections to avoid
+     * TikTok's per-IP rate limiting (manifests as code=1006 abnormal closes).
+     *
+     * Format: `http://user:pass@host:port` or `http://host:port`.
+     *
+     * Example (Webshare residential):
+     *   proxy: 'http://USER:PASS@p.webshare.io:80'
+     */
+    proxy?: string;
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -231,12 +314,18 @@ declare class TikTokLive extends EventEmitter {
     private readonly debug;
     private readonly _presetRoomId;
     private readonly _presetSessionId;
+    private readonly proxyUrl;
     constructor(options: TikTokLiveOptions);
+    /**
+     * Build an HttpsProxyAgent when `proxy` option is set, else undefined.
+     * Lazy-required so users without proxy don't pay the dependency cost.
+     */
+    private getProxyAgent;
     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.
+     * After calling destroy(), the instance cannot be reused — create a new one.
      */
     destroy(): void;
     get connected(): boolean;
@@ -246,7 +335,7 @@ declare class TikTokLive extends EventEmitter {
     /**
      * 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.
+     * This is a standalone method — no WebSocket connection required.
      *
      * @example
      * ```ts
@@ -280,4 +369,4 @@ declare class TikTokLive extends EventEmitter {
     private stopHeartbeat;
 }
 
-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 };
+export { type BaseEvent, type BattleArmiesEvent, type BattleContributor, type BattleEvent, type BattleHost, type BattleItemCardEvent, 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 };