@tiktool/live 2.8.0 → 2.9.0

package/README.md

@@ -65,6 +65,85 @@ await live.connect();
 
 ---
 
+## 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

package/dist/index.d.mts

@@ -279,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 {
@@ -302,7 +314,13 @@ 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;
     /**

package/dist/index.d.ts

@@ -279,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 {
@@ -302,7 +314,13 @@ 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;
     /**