@tiktool/live 2.8.0 → 2.10.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,32 @@ 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;
+    /**
+     * Connection mode.
+     *   - `'direct'` (default): SDK opens WebSocket directly to TikTok. TikTok
+     *      sees your IP. Cheapest on API quota. Limited to ~30 concurrent
+     *      streams per container before TikTok rate-limits.
+     *   - `'relayed'`: SDK connects to TikTools' managed relay
+     *      (`wss://api.tik.tools/?...`). We connect to TikTok on your behalf
+     *      from our rotated proxy pool. TikTok never sees your IP. No rate-
+     *      limit risk. Scales to thousands of concurrent streams.
+     *
+     * The decoded events emitted are identical in both modes — code that
+     * uses `client.on('chat', e => ...)` works without changes.
+     */
+    mode?: 'direct' | 'relayed';
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -302,7 +328,14 @@ declare class TikTokLive extends EventEmitter {
     private readonly debug;
     private readonly _presetRoomId;
     private readonly _presetSessionId;
+    private readonly proxyUrl;
+    private readonly mode;
     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;
     /**
@@ -349,6 +382,13 @@ declare class TikTokLive extends EventEmitter {
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;
+    /**
+     * Relayed-mode connect. Opens a plain WebSocket to TikTools' managed relay
+     * endpoint. Events arrive pre-decoded as `{event, data}` JSON envelopes.
+     * The SDK re-emits them on the same event names as Direct mode so user
+     * code is identical regardless of mode.
+     */
+    private _connectRelayed;
 }
 
 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

@@ -279,6 +279,32 @@ 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;
+    /**
+     * Connection mode.
+     *   - `'direct'` (default): SDK opens WebSocket directly to TikTok. TikTok
+     *      sees your IP. Cheapest on API quota. Limited to ~30 concurrent
+     *      streams per container before TikTok rate-limits.
+     *   - `'relayed'`: SDK connects to TikTools' managed relay
+     *      (`wss://api.tik.tools/?...`). We connect to TikTok on your behalf
+     *      from our rotated proxy pool. TikTok never sees your IP. No rate-
+     *      limit risk. Scales to thousands of concurrent streams.
+     *
+     * The decoded events emitted are identical in both modes — code that
+     * uses `client.on('chat', e => ...)` works without changes.
+     */
+    mode?: 'direct' | 'relayed';
 }
 
 declare class TikTokLive extends EventEmitter {
@@ -302,7 +328,14 @@ declare class TikTokLive extends EventEmitter {
     private readonly debug;
     private readonly _presetRoomId;
     private readonly _presetSessionId;
+    private readonly proxyUrl;
+    private readonly mode;
     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;
     /**
@@ -349,6 +382,13 @@ declare class TikTokLive extends EventEmitter {
     private resolveHostUsers;
     private startHeartbeat;
     private stopHeartbeat;
+    /**
+     * Relayed-mode connect. Opens a plain WebSocket to TikTools' managed relay
+     * endpoint. Events arrive pre-decoded as `{event, data}` JSON envelopes.
+     * The SDK re-emits them on the same event names as Direct mode so user
+     * code is identical regardless of mode.
+     */
+    private _connectRelayed;
 }
 
 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 };