@tiktool/live 2.7.0 → 2.8.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;
@@ -83,8 +101,62 @@ interface BattleArmiesEvent extends BaseEvent {
     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) */
+    /** 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;
+    /** 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';
@@ -138,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;
@@ -152,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;
@@ -234,7 +307,7 @@ declare class TikTokLive extends EventEmitter {
     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;
@@ -244,7 +317,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
@@ -278,4 +351,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;
@@ -83,8 +101,62 @@ interface BattleArmiesEvent extends BaseEvent {
     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) */
+    /** 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;
+    /** 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';
@@ -138,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;
@@ -152,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;
@@ -234,7 +307,7 @@ declare class TikTokLive extends EventEmitter {
     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;
@@ -244,7 +317,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
@@ -278,4 +351,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 };