@tiktool/live 2.10.0 → 2.10.1

package/README.md

@@ -97,22 +97,42 @@ Install `https-proxy-agent` if using `proxy`:
 npm install https-proxy-agent
 ```
 
-### Mode 2 — Relayed (via our proxy pool, no SDK install)
+### Mode 2 — Relayed (via our proxy pool)
 
 ```
-  Your App  ◀──── wss://api.tik.tools/?uniqueId=X&apiKey=Y ────  tik.tools
-                                                                     │
-                                                                     │ WS via
-                                                                     │ rotated proxies
-                                                                     ▼
-                                                                  TikTok
+  Your App  ◀──── wss://api.tik.tools/?... ────  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.
+
+**Easiest — same SDK, one option:**
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({
+    uniqueId: 'creator_username',
+    apiKey: 'YOUR_KEY',
+    mode: 'relayed',  // ← that's it
+});
+
+live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
+live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName}`));
+live.on('battleArmies', e => console.log(e));
+
+await live.connect();
+```
+
+Event names + payload shapes are **identical to Direct mode**. Switch back and forth by toggling `mode`.
+
+**Advanced — raw WebSocket (no SDK, your own client):**
 
 ```typescript
 import WebSocket from 'ws';
@@ -124,12 +144,12 @@ const ws = new WebSocket(
 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 === 'gift')         console.log(msg.data.user.uniqueId, msg.data.giftName);
     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).
+Use this when integrating from a non-Node runtime (Python, Go, Bun, browser) or when you want absolute control over the connection.
 
 ### Side-by-side
 
@@ -318,6 +338,8 @@ live.on('battle', (e) => {
 | `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`) |
+| `proxy` | `string` | — | HTTP(S) proxy URL for Direct mode (e.g. `http://USER:PASS@host:port`). Requires `https-proxy-agent`. |
+| `mode` | `'direct' \| 'relayed'` | `'direct'` | Connection mode. See [Connection Modes](#connection-modes). |
 | `debug` | `boolean` | `false` | Debug logging |
 
 ### Methods
@@ -331,6 +353,32 @@ live.on('battle', (e) => {
 | `eventCount` | `number` | Total events received |
 | `roomId` | `string` | Current room ID |
 
+### REST endpoints (companion to the WS SDK)
+
+For lookups outside the live event stream, hit the sign server directly with your API key:
+
+| Endpoint | Method | Tier | Use case |
+|----------|--------|------|----------|
+| `/webcast/room_id` | POST | sandbox+ | `unique_id` → `room_id` |
+| `/webcast/room_info` | POST | sandbox+ | `unique_id` → `room_id` + `alive` + `title` |
+| `/webcast/check_alive` | GET/POST | sandbox+ | Is `room_id` currently live? |
+| `/webcast/bulk_live_check` | POST | basic+ | Batch check up to 500 users in one call |
+| `/webcast/live_status` | GET | sandbox+ | `unique_id` → live snapshot incl. viewer count |
+| `/webcast/user_profile` | GET | **pro+** | **`unique_id` → numeric `id`, `secUid`, nickname, bio, avatars, follower stats** |
+| `/webcast/resolve_user_ids` | POST | sandbox+ | Batch numeric `userId` → `unique_id` (reverse of `user_profile`) |
+| `/webcast/rankings` | GET | sandbox+ | Top gifters / hourly rank for a room |
+| `/webcast/room_video` | POST | basic+ | Get HLS / FLV stream URLs |
+| `/webcast/ws_credentials` | POST | sandbox+ | Get signed WS URL + ttwid (used by Direct mode under the hood) |
+
+**Need the streamer's numeric TikTok ID for a username?**
+
+```bash
+curl -H "X-Api-Key: YOUR_KEY" \
+  "https://api.tik.tools/webcast/user_profile?unique_id=anyuser"
+```
+
+Returns full profile JSON. Pro tier and above. Cached server-side for 24h — repeated lookups are free and instant.
+
 ---
 
 ## Rate Limits

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tiktool/live",
-    "version": "2.10.0",
+    "version": "2.10.1",
     "description": "TikTok LIVE API Client — Real-time chat, gifts, viewers, PK battles with MVP breakdown, x2/x3 boosters, gloves, mist, match-guide & 20+ event types from any TikTok livestream. Direct WebSocket connection.",
     "author": "tiktool",
     "license": "MIT",