@tiktool/live 2.7.1 → 2.9.0

package/README.md

@@ -1,235 +1,505 @@
-<div align="center">
-
-# @tiktool/live
-
-### Connect to any TikTok LIVE stream in 4 lines of code.
-
-[![npm version](https://img.shields.io/npm/v/@tiktool/live?color=%23ff0050&label=npm&logo=npm)](https://www.npmjs.com/package/@tiktool/live)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?logo=node.js)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org)
-
-Real-time chat, gifts, viewers, battles, follows & 18+ event types from any TikTok livestream.
-
-[Quick Start](#-quick-start) · [Events](#-events) · [API](#-api-reference) · [Rate Limits](#-rate-limits) · [Get API Key](https://tik.tools)
-
-</div>
-
----
-
-## ⚡ Quick Start
-
-```bash
-npm install @tiktool/live
-```
-
-Get your free API key at [tik.tools](https://tik.tools)
-
-```typescript
-import { TikTokLive } from '@tiktool/live';
-
-const live = new TikTokLive({
-    uniqueId: 'tv_asahi_news',
-    apiKey: 'YOUR_API_KEY',
-});
-
-live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
-live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`));
-live.on('member', e => console.log(`${e.user.uniqueId} joined`));
-live.on('roomUserSeq', e => console.log(`Viewers: ${e.viewerCount}`));
-
-await live.connect();
-```
-
----
-
-## How It Works
-
-```
-    Your App                    tik.tools                    TikTok
-  +-----------+              +--------------+           +--------------+
-  |          -+-- sign_url -->  Signs URL   |           |              |
-  |  Your   <-+-- X-Bogus --|  with params |           |   TikTok     |
-  |  Code    |              |              |           |   WebSocket  |
-  |          -+------------ Connect directly ---------->|   Server     |
-  |          <-+------------ Live events (protobuf) <---|              |
-  +-----------+              +--------------+           +--------------+
-                            ^ Only interaction             ^ Direct from
-                              with our server                YOUR IP
-```
-
-- Your app connects directly to TikTok from your IP address
-- The sign server only generates cryptographic signatures (requires API key)
-- TikTok never sees the sign server
-- Built-in protobuf parser, no external dependencies
-
----
-
-## Events
-
-### Listening
-
-```typescript
-live.on('chat', (event) => {
-    event.user.uniqueId  // string
-    event.comment        // string
-});
-
-live.on('event', (event) => {
-    console.log(event.type, event);
-});
-```
-
-### Reference
-
-| Event | Type | Description | Fields |
-|-------|------|-------------|--------|
-| `chat` | `ChatEvent` | Chat message | `user`, `comment` |
-| `member` | `MemberEvent` | User joined | `user`, `action` |
-| `like` | `LikeEvent` | User liked | `user`, `likeCount`, `totalLikes` |
-| `gift` | `GiftEvent` | Gift sent | `user`, `giftName`, `diamondCount`, `repeatCount`, `combo` |
-| `social` | `SocialEvent` | Follow / Share | `user`, `action` |
-| `roomUserSeq` | `RoomUserSeqEvent` | Viewer count | `viewerCount`, `totalViewers` |
-| `battle` | `BattleEvent` | Link Mic battle | `status` |
-| `battleArmies` | `BattleArmiesEvent` | Battle teams | — |
-| `subscribe` | `SubscribeEvent` | New subscriber | `user`, `subMonth` |
-| `emoteChat` | `EmoteChatEvent` | Emote in chat | `user`, `emoteId` |
-| `envelope` | `EnvelopeEvent` | Treasure chest | `diamondCount` |
-| `question` | `QuestionEvent` | Q&A question | `user`, `questionText` |
-| `control` | `ControlEvent` | Stream control | `action` (3 = ended) |
-| `room` | `RoomEvent` | Room status | `status` |
-| `liveIntro` | `LiveIntroEvent` | Stream intro | `title` |
-| `rankUpdate` | `RankUpdateEvent` | Rank update | `rankType` |
-| `linkMic` | `LinkMicEvent` | Link Mic | `action` |
-| `unknown` | `UnknownEvent` | Unrecognized | `method` |
-
-### Connection Events
-
-| Event | Callback | Description |
-|-------|----------|-------------|
-| `connected` | `() => void` | Connected to stream |
-| `disconnected` | `(code, reason) => void` | Disconnected |
-| `roomInfo` | `(info: RoomInfo) => void` | Room info |
-| `error` | `(error: Error) => void` | Error |
-
----
-
-## API Reference
-
-### `new TikTokLive(options)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `uniqueId` | `string` | — | TikTok username (without @) |
-| `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
-| `signServerUrl` | `string` | `https://api.tik.tools` | Sign server URL |
-| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
-| `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
-| `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
-| `debug` | `boolean` | `false` | Debug logging |
-
-### Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `connect()` | `Promise<void>` | Connect to livestream |
-| `disconnect()` | `void` | Disconnect |
-| `connected` | `boolean` | Connection status |
-| `eventCount` | `number` | Total events received |
-| `roomId` | `string` | Current room ID |
-
----
-
-## Rate Limits
-
-All API requests require an API key. Get yours at [tik.tools](https://tik.tools).
-
-| Tier | Rate Limit | Endpoints | Price |
-|------|-----------|-----------|-------|
-| **Free** | 5/min | `sign_url`, `check_alive` | Free |
-| **Basic** | 30/min | + `fetch`, `room_info`, `bulk_live_check`, WS relay | Free (with key) |
-| **Pro** | 120/min | + `room_video`, all endpoints | Coming soon |
-
-The SDK calls the sign server **once per connection**, then stays connected via WebSocket. A free key is sufficient for most use cases.
-
----
-
-## Examples
-
-### Chat Bot
-
-```typescript
-import { TikTokLive } from '@tiktool/live';
-
-const live = new TikTokLive({
-    uniqueId: 'streamer_name',
-    apiKey: 'YOUR_API_KEY',
-});
-
-live.on('chat', (e) => {
-    if (e.comment.toLowerCase() === '!hello') {
-        console.log(`Hello, ${e.user.nickname}!`);
-    }
-});
-
-live.on('gift', (e) => {
-    if (e.repeatEnd) {
-        console.log(`${e.user.uniqueId} sent ${e.repeatCount}x ${e.giftName} (${e.diamondCount * e.repeatCount} diamonds)`);
-    }
-});
-
-await live.connect();
-```
-
-### OBS Overlay
-
-```typescript
-import { TikTokLive } from '@tiktool/live';
-import { WebSocketServer } from 'ws';
-
-const wss = new WebSocketServer({ port: 8080 });
-const live = new TikTokLive({
-    uniqueId: 'streamer_name',
-    apiKey: 'YOUR_API_KEY',
-});
-
-live.on('event', (event) => {
-    for (const client of wss.clients) {
-        client.send(JSON.stringify(event));
-    }
-});
-
-await live.connect();
-console.log('Forwarding events to ws://localhost:8080');
-```
-
----
-
-## TypeScript
-
-Full TypeScript support with type inference:
-
-```typescript
-import { TikTokLive, ChatEvent, GiftEvent } from '@tiktool/live';
-
-const live = new TikTokLive({
-    uniqueId: 'username',
-    apiKey: 'YOUR_API_KEY',
-});
-
-live.on('chat', (event: ChatEvent) => {
-    const username: string = event.user.uniqueId;
-    const message: string = event.comment;
-});
-
-live.on('gift', (event: GiftEvent) => {
-    const diamonds: number = event.diamondCount;
-    const isCombo: boolean = event.combo;
-});
-```
-
----
-
-## License
-
-MIT © [tiktool](https://tik.tools)
+<div align="center">
+
+# @tiktool/live
+
+### Connect to any TikTok LIVE stream in 4 lines of code.
+
+[![npm version](https://img.shields.io/npm/v/@tiktool/live?color=%23ff0050&label=npm&logo=npm)](https://www.npmjs.com/package/@tiktool/live)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org)
+
+Real-time chat, gifts, viewers, **PK battles with MVP breakdown**, **x2/x3 boosters**, gloves, mist, match-guide & 20+ event types from any TikTok livestream.
+
+[Quick Start](#-quick-start) · [Events](#-events) · [PK Battles](#-pk-battles) · [API](#-api-reference) · [Rate Limits](#-rate-limits) · [Get API Key](https://tik.tools)
+
+</div>
+
+---
+
+## ⚡ Quick Start
+
+```bash
+npm install @tiktool/live
+```
+
+Get your free API key at [tik.tools](https://tik.tools)
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({
+    uniqueId: 'tv_asahi_news',
+    apiKey: 'YOUR_API_KEY',
+});
+
+live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
+live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`));
+live.on('member', e => console.log(`${e.user.uniqueId} joined`));
+live.on('roomUserSeq', e => console.log(`Viewers: ${e.viewerCount}`));
+
+await live.connect();
+```
+
+---
+
+## How It Works
+
+```
+    Your App                    tik.tools                    TikTok
+  +-----------+              +--------------+           +--------------+
+  |          -+-- sign_url -->  Signs URL   |           |              |
+  |  Your   <-+-- X-Bogus --|  with params |           |   TikTok     |
+  |  Code    |              |              |           |   WebSocket  |
+  |          -+------------ Connect directly ---------->|   Server     |
+  |          <-+------------ Live events (protobuf) <---|              |
+  +-----------+              +--------------+           +--------------+
+                            ^ Only interaction             ^ Direct from
+                              with our server                YOUR IP
+```
+
+- Your app connects directly to TikTok from your IP address
+- The sign server only generates cryptographic signatures (requires API key)
+- TikTok never sees the sign server
+- Built-in protobuf parser, **zero external dependencies** (only `ws` for WebSocket)
+
+---
+
+## Connection Modes
+
+There are **two ways** to receive TikTok LIVE events from `tik.tools`. Pick based on scale and IP-exposure tolerance.
+
+### Mode 1 — Direct (default, this SDK)
+
+```
+  Your App  ──signs URL via──▶  tik.tools  ──returns signed URL──▶  Your App
+  Your App  ───────────────── WS direct to TikTok ───────────────▶  TikTok
+  Your App  ◀────────────────── live events ──────────────────────  TikTok
+```
+
+- **TikTok sees your IP.** Cheapest on our API quota (only the `ws_credentials` call is charged per connection).
+- Good for **up to ~30 concurrent streams** from one container.
+- Above that, TikTok's per-IP rate limit kicks in → frequent `code=1006` closes + reconnect loops.
+- **Solution at scale**: enable the `proxy` option (below) to dial through your own residential pool.
+
+```typescript
+const live = new TikTokLive({
+    uniqueId: 'creator_username',
+    apiKey: 'YOUR_TIKTOOLS_KEY',
+    // Optional: route WS + HTTP through your own proxy (recommended for 30+ streams)
+    proxy: 'http://USER:PASS@p.webshare.io:80',
+});
+```
+
+Install `https-proxy-agent` if using `proxy`:
+
+```bash
+npm install https-proxy-agent
+```
+
+### Mode 2 — Relayed (via our proxy pool, no SDK install)
+
+```
+  Your App  ◀──── wss://api.tik.tools/?uniqueId=X&apiKey=Y ────  tik.tools
+                                                                     │
+                                                                     │ WS via
+                                                                     │ rotated proxies
+                                                                     ▼
+                                                                  TikTok
+```
+
+- **TikTok sees our IPs** (rotated across hundreds of Webshare + residential proxies).
+- We absorb every per-IP rate-limit hit. Survives any block automatically.
+- Best for **30+ concurrent streams**, low-budget setups, or anyone who doesn't want their own IP fingerprinted by TikTok.
+- Costs slightly more per stream-hour (events stream through us, not signed-once direct).
+- No SDK install — plain `WebSocket`. Events arrive pre-parsed as JSON.
+
+```typescript
+import WebSocket from 'ws';
+
+const ws = new WebSocket(
+    `wss://api.tik.tools/?uniqueId=creator_username&apiKey=YOUR_KEY`
+);
+
+ws.on('message', raw => {
+    const msg = JSON.parse(raw.toString());
+    if (msg.event === 'chat')         console.log(msg.data.user.uniqueId, msg.data.comment);
+    if (msg.event === 'gift')         console.log(msg.data.user.uniqueId, msg.data.giftName, msg.data.diamondCount);
+    if (msg.event === 'battleArmies') console.log(msg.data);
+});
+```
+
+Event payloads are identical to Direct-mode `client.on('chat', …)` etc. — only the wrapping changes (`{event, data}` envelope vs the SDK's separate emit).
+
+### Side-by-side
+
+| Aspect | Direct (Mode 1) | Relayed (Mode 2) |
+|---|---|---|
+| TikTok sees | Your IP | Our rotated proxy pool |
+| Setup | `new TikTokLive(...)` | `new WebSocket(url)` |
+| Scale limit | ~30 streams / container IP | Thousands |
+| Per-event cost | 1× `ws_credentials` per (re)connect | 1× per event |
+| TikTok rate-limit risk | Yes (mitigated with `proxy`) | None — we handle it |
+| Best for | Hobby / single-creator | Production at scale |
+
+---
+
+## Events
+
+### Listening
+
+```typescript
+live.on('chat', (event) => {
+    event.user.uniqueId  // string
+    event.comment        // string
+});
+
+live.on('event', (event) => {
+    console.log(event.type, event);
+});
+```
+
+### Reference
+
+| Event | Type | Description | Fields |
+|-------|------|-------------|--------|
+| `chat` | `ChatEvent` | Chat message (with inline emotes) | `user`, `comment`, `emotes` |
+| `member` | `MemberEvent` | User joined | `user`, `action` |
+| `like` | `LikeEvent` | User liked | `user`, `likeCount`, `totalLikes` |
+| `gift` | `GiftEvent` | Gift sent | `user`, `giftId`, `giftName`, `diamondCount`, `repeatCount`, `combo`, `groupId` |
+| `social` | `SocialEvent` | Follow / Share | `user`, `action` |
+| `roomUserSeq` | `RoomUserSeqEvent` | Viewer count | `viewerCount`, `totalViewers` |
+| `battle` | `BattleEvent` | PK Battle start / status | `battleId`, `status`, `battleDuration`, `teams` |
+| `battleArmies` | `BattleArmiesEvent` | **PK score update + per-host MVP breakdown** | `battleId`, `teams`, `hosts[]`, `secsRemaining`, `serverTsMs`, `matchId`, `sessionId` |
+| `battleItemCard` | `BattleItemCardEvent` | **x2/x3 boosters, gloves, mist, thunder, extra-time, match-guide** | `effect`, `multiplier`, `senderUserId`, `iconUrl`, `iconKey`, `accentColor`, … |
+| `subscribe` | `SubscribeEvent` | New subscriber | `user`, `subMonth` |
+| `emoteChat` | `EmoteChatEvent` | Emote in chat | `user`, `emoteId`, `emoteUrl` |
+| `envelope` | `EnvelopeEvent` | Treasure chest | `diamondCount` |
+| `question` | `QuestionEvent` | Q&A question | `user`, `questionText` |
+| `control` | `ControlEvent` | Stream control | `action` (3 = ended) |
+| `room` | `RoomEvent` | Room status | `status` |
+| `liveIntro` | `LiveIntroEvent` | Stream intro | `roomId`, `title` |
+| `rankUpdate` | `RankUpdateEvent` | Hourly / weekly rank | `rankType`, `rankList` |
+| `linkMic` | `LinkMicEvent` | Link Mic guest action | `action`, `users` |
+| `unknown` | `UnknownEvent` | Unrecognized | `method` |
+
+### Connection Events
+
+| Event | Callback | Description |
+|-------|----------|-------------|
+| `connected` | `() => void` | Connected to stream |
+| `disconnected` | `(code, reason) => void` | Disconnected |
+| `roomInfo` | `(info: RoomInfo) => void` | Room info |
+| `error` | `(error: Error) => void` | Error |
+
+---
+
+## 🥊 PK Battles
+
+This SDK fully parses TikTok PK (Player-vs-Killer) battle protobufs, including
+**multi-guest** matches with up to 4 hosts per side and per-gifter MVP scores.
+
+### `battleArmies` — score updates during a PK
+
+Emitted every few seconds while a PK is active. The new `hosts[]` array gives
+you the **per-host breakdown** with each gifter's contribution sorted **MVP
+first** (highest score → lowest):
+
+```typescript
+live.on('battleArmies', (e) => {
+    console.log(`PK ${e.battleId} — ${e.secsRemaining}s remaining`);
+
+    for (const host of e.hosts ?? []) {
+        console.log(`  Host ${host.hostUserId} — total ${host.teamTotalScore}`);
+
+        // contributors[0] = MVP (highest gifter)
+        for (const [i, c] of host.contributors.slice(0, 3).entries()) {
+            console.log(`    #${i + 1} ${c.nickname || c.userId}: ${c.score}`);
+        }
+    }
+});
+```
+
+**Per-host fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `hostUserId` | `string` | TikTok userId of this side's host |
+| `teamTotalScore` | `number` | Total diamonds for this side |
+| `teamIdx` | `number` | Side index (0 = left, 1 = right, …) |
+| `contributors[]` | `BattleContributor[]` | Per-gifter breakdown, **sorted MVP first** |
+
+**Per-contributor fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `userId` | `string` | Gifter's TikTok userId |
+| `score` | `number` | Diamond score contributed |
+| `nickname` | `string` | Display nickname (may be empty) |
+
+**Timer & match identity:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `battleId` | `string` | Battle session tag |
+| `matchId` | `string` | Stable match ID across multi-round PK |
+| `sessionId` | `string` | Per-round session ID |
+| `secsRemaining` | `number` | Seconds left, computed from **TikTok server clock** (no VPS drift) |
+| `serverTsMs` | `number` | TikTok server-side ms epoch at frame emit |
+| `durationSec` | `number` | Total battle duration |
+| `endTimeMs` | `number` | Battle end ms epoch (alias for `battleStartMs + duration*1000`) |
+
+### `battleItemCard` — boosters / power-ups during a PK
+
+Fired when a gifter activates a special card: x2/x3 multipliers, gloves
+(crit), mist, thunder, extra-time, or match-guide. Includes the **card art**
+URL straight from TikTok's CDN — drop it into an OBS overlay as-is.
+
+```typescript
+live.on('battleItemCard', (e) => {
+    console.log(`${e.senderNickname} activated ${e.effect}`);
+
+    if (e.multiplier > 0) {
+        console.log(`  x${e.multiplier} multiplier for ${e.durationSec}s`);
+    }
+
+    // Use straight in an <img> tag — TikTok CDN
+    console.log(`  icon: ${e.iconUrl}`);
+    console.log(`  accent: ${e.accentColor}`);
+});
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `battleId` | `string` | The PK this card belongs to |
+| `cardType` | `number` | 2=gloves, 3=mist, 4=match_guide, 11=x3, … |
+| `effect` | `string` | `'gloves'` \| `'mist'` \| `'booster_x2'` \| `'booster_x3'` \| `'match_guide'` \| `'thunder'` \| `'extra_time'` \| raw key |
+| `effectKey` | `string` | Raw TikTok resource key |
+| `multiplier` | `number` | 2 or 3 for boosters, else 0 |
+| `senderUserId` | `string` | Gifter who activated it |
+| `senderNickname` | `string` | Display name of the sender |
+| `senderUniqueId` | `string` | Username (`@handle`) of the sender |
+| `senderAvatarUrl` | `string` | Sender's avatar (CDN URL) |
+| `activatedAtSec` | `number` | Unix seconds when activated |
+| `durationSec` | `number` | Active duration |
+| `endsAtSec` | `number` | Unix seconds when it ends |
+| `commentTemplate` | `string` | e.g. `"{0:user} sent 1 magic mist"` |
+| `iconUrl` | `string` | Full TikTok CDN URL for the card art (webp/jpeg) |
+| `iconKey` | `string` | Short id, e.g. `card_mist_v3`, `card_crit_v3`, `top3_buffer` |
+| `accentColor` | `string` | Hex color, e.g. `#BCD9E0` (mist blue), `#E0D4BC` (gloves tan) |
+
+### `battle` — PK lifecycle events
+
+Fired on start / status change / end. Use for PK ON/OFF banners.
+
+```typescript
+live.on('battle', (e) => {
+    // status: 1=ACTIVE, 2=STARTING, 3=ENDED, 4=PREPARING
+    if (e.status === 1) console.log('PK started');
+    if (e.status === 3) console.log('PK ended');
+});
+```
+
+---
+
+## API Reference
+
+### `new TikTokLive(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `uniqueId` | `string` | — | TikTok username (without @) |
+| `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
+| `signServerUrl` | `string` | `https://api.tik.tools` | Sign server URL |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
+| `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
+| `roomId` | `string` | — | Pre-resolved room ID (skips page fetch when paired with `sessionId`) |
+| `sessionId` | `string` | — | Pre-resolved `ttwid` cookie (skips page fetch when paired with `roomId`) |
+| `debug` | `boolean` | `false` | Debug logging |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `Promise<void>` | Connect to livestream |
+| `disconnect()` | `void` | Disconnect |
+| `getStreamUrl()` | `Promise<StreamInfo>` | Get FLV/HLS playback URLs for the live video |
+| `connected` | `boolean` | Connection status |
+| `eventCount` | `number` | Total events received |
+| `roomId` | `string` | Current room ID |
+
+---
+
+## Rate Limits
+
+All API requests require an API key. Get yours at [tik.tools](https://tik.tools).
+
+| Tier | Price (USD / week) | WS Connections | Rate limit |
+|------|--------------------|----------------|------------|
+| **Free** | $0 | 1 | 5 req/min |
+| **Basic** | $9 | 25 | 30 req/min |
+| **Pro** | $19 | 100 | 120 req/min |
+| **Ultra** | $58 | 250 | 600 req/min |
+
+The SDK calls the sign server **once per connection**, then stays connected
+via WebSocket. A free key is sufficient for most use cases.
+
+---
+
+## Examples
+
+### Chat Bot
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({
+    uniqueId: 'streamer_name',
+    apiKey: 'YOUR_API_KEY',
+});
+
+live.on('chat', (e) => {
+    if (e.comment.toLowerCase() === '!hello') {
+        console.log(`Hello, ${e.user.nickname}!`);
+    }
+});
+
+live.on('gift', (e) => {
+    if (e.repeatEnd) {
+        console.log(`${e.user.uniqueId} sent ${e.repeatCount}x ${e.giftName} (${e.diamondCount * e.repeatCount} diamonds)`);
+    }
+});
+
+await live.connect();
+```
+
+### Live PK Battle Dashboard
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({ uniqueId: 'streamer_name', apiKey: 'YOUR_API_KEY' });
+
+live.on('battle', e => {
+    if (e.status === 1) console.log('🥊 PK STARTED');
+    if (e.status === 3) console.log('🏁 PK ENDED');
+});
+
+live.on('battleArmies', e => {
+    console.log(`\n⏱  ${e.secsRemaining}s remaining`);
+    for (const host of e.hosts ?? []) {
+        const top = host.contributors[0];
+        console.log(`  ${host.hostUserId}: ${host.teamTotalScore}  ` +
+                    `(MVP: ${top?.nickname || top?.userId || '—'} ${top?.score ?? 0})`);
+    }
+});
+
+live.on('battleItemCard', e => {
+    const tag = e.multiplier > 0 ? `x${e.multiplier} BOOSTER` : e.effect.toUpperCase();
+    console.log(`💥 ${e.senderNickname} → ${tag} (${e.durationSec}s)`);
+});
+
+await live.connect();
+```
+
+### OBS Overlay
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+const live = new TikTokLive({
+    uniqueId: 'streamer_name',
+    apiKey: 'YOUR_API_KEY',
+});
+
+live.on('event', (event) => {
+    for (const client of wss.clients) {
+        client.send(JSON.stringify(event));
+    }
+});
+
+await live.connect();
+console.log('Forwarding events to ws://localhost:8080');
+```
+
+### HLS / FLV Playback URL
+
+```typescript
+const info = await live.getStreamUrl();
+console.log('HLS:', info.hlsPullUrl);
+console.log('FLV:', info.flvPullUrl);
+// Or pick a specific quality
+console.log('FULL_HD1 HLS:', info.streamUrls.FULL_HD1?.hls);
+```
+
+---
+
+## TypeScript
+
+Full TypeScript support with type inference:
+
+```typescript
+import {
+    TikTokLive,
+    ChatEvent,
+    GiftEvent,
+    BattleArmiesEvent,
+    BattleItemCardEvent,
+    BattleHost,
+    BattleContributor,
+} from '@tiktool/live';
+
+const live = new TikTokLive({
+    uniqueId: 'username',
+    apiKey: 'YOUR_API_KEY',
+});
+
+live.on('chat', (event: ChatEvent) => {
+    const username: string = event.user.uniqueId;
+    const message: string = event.comment;
+});
+
+live.on('gift', (event: GiftEvent) => {
+    const diamonds: number = event.diamondCount;
+    const isCombo: boolean = event.combo;
+});
+
+live.on('battleArmies', (event: BattleArmiesEvent) => {
+    for (const host of event.hosts ?? []) {
+        const mvp: BattleContributor | undefined = host.contributors[0];
+        if (mvp) console.log(mvp.nickname, mvp.score);
+    }
+});
+
+live.on('battleItemCard', (event: BattleItemCardEvent) => {
+    if (event.multiplier > 0) {
+        console.log(`x${event.multiplier} buff active for ${event.durationSec}s`);
+    }
+});
+```
+
+---
+
+## Changelog
+
+### 2.8.0 (2026-05-19)
+
+- **NEW** `battleItemCard` event — x2/x3 boosters, gloves, mist, thunder,
+  extra-time, match-guide. Includes `iconUrl`, `iconKey`, `accentColor` for
+  drop-in overlay use.
+- **NEW** `BattleArmiesEvent.hosts[]` — multi-guest PK breakdown with per-host
+  `contributors[]` sorted **MVP first**.
+- **NEW** `matchId`, `sessionId`, `serverTsMs`, `sessionTag`, `secsRemaining`
+  fields on `BattleArmiesEvent`.
+- Verified live against multi-guest battles 2026-05-19.
+
+---
+
+## License
+
+MIT © [tiktool](https://tik.tools)