@tiktool/live 2.11.1 → 2.11.2

package/README.md

@@ -77,40 +77,39 @@ There are **two ways** to receive TikTok LIVE events from `tik.tools`. Pick base
   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.
+- The signed WebSocket is opened from your runtime. TikTok sees the network identity of the host that runs the SDK.
+- Lowest per-stream cost — only the initial `ws_credentials` call is billed against your API key.
+- Suited to **low- to mid-volume** workloads from a single host.
+- High-volume setups should prefer Mode 2 for predictable, centrally-managed egress.
 
 ```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',
+    // Optional: route outbound WS + HTTP through a corporate / egress gateway
+    // proxy: 'http://USER:PASS@gateway.your-company.com:port',
 });
 ```
 
-Install `https-proxy-agent` if using `proxy`:
+If you set the optional `proxy` field, install the standard agent:
 
 ```bash
 npm install https-proxy-agent
 ```
 
-### Mode 2 — Relayed (via our proxy pool)
+### Mode 2 — Relayed (via TikTools managed edge)
 
 ```
   Your App  ◀──── wss://api.tik.tools/?... ────  tik.tools
                                                       │
-                                                      │ WS via
-                                                      │ rotated proxies
+                                                      │ managed edge
                                                       ▼
                                                    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.
+- The TikTools service handles the upstream TikTok session and forwards decoded events over a single WebSocket to your client.
+- Single, stable egress — your application connects only to `api.tik.tools`.
+- Recommended for **production scale**, multi-tenant deployments, or any environment that already centralizes outbound traffic.
 
 **Easiest — same SDK, one option:**
 
@@ -155,12 +154,10 @@ Use this when integrating from a non-Node runtime (Python, Go, Bun, browser) or
 
 | 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 |
+| WebSocket opens from | Your runtime | TikTools managed edge |
+| Setup | `new TikTokLive(...)` | `new TikTokLive({ ..., mode: 'relayed' })` |
+| Egress | Your host's network | Single endpoint: `api.tik.tools` |
+| Best for | Low- to mid-volume | Production scale, multi-tenant |
 
 ---
 

package/dist/index.d.mts

@@ -280,26 +280,26 @@ interface TikTokLiveOptions {
     /** 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).
+     * Optional outbound HTTP(S) gateway URL. When set, the SDK's outbound
+     * WebSocket and HTTP requests are routed through this gateway instead
+     * of the host's default network interface. Useful for environments that
+     * need a stable egress IP or that already centralize outbound traffic
+     * through a corporate gateway.
      *
      * 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.
+     *   - `'direct'` (default): SDK opens the WebSocket from your runtime to
+     *      TikTok using credentials signed by the TikTools sign server.
+     *      Best for low-volume use where you'd rather not stream events
+     *      through our infrastructure.
+     *   - `'relayed'`: SDK connects to the TikTools managed edge
+     *      (`wss://api.tik.tools/...`). The TikTools service handles the
+     *      upstream TikTok session and forwards decoded events to your
+     *      client. Best for production scale and for environments where
+     *      you want a single, stable egress through TikTools.
      *
      * The decoded events emitted are identical in both modes — code that
      * uses `client.on('chat', e => ...)` works without changes.

package/dist/index.d.ts

@@ -280,26 +280,26 @@ interface TikTokLiveOptions {
     /** 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).
+     * Optional outbound HTTP(S) gateway URL. When set, the SDK's outbound
+     * WebSocket and HTTP requests are routed through this gateway instead
+     * of the host's default network interface. Useful for environments that
+     * need a stable egress IP or that already centralize outbound traffic
+     * through a corporate gateway.
      *
      * 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.
+     *   - `'direct'` (default): SDK opens the WebSocket from your runtime to
+     *      TikTok using credentials signed by the TikTools sign server.
+     *      Best for low-volume use where you'd rather not stream events
+     *      through our infrastructure.
+     *   - `'relayed'`: SDK connects to the TikTools managed edge
+     *      (`wss://api.tik.tools/...`). The TikTools service handles the
+     *      upstream TikTok session and forwards decoded events to your
+     *      client. Best for production scale and for environments where
+     *      you want a single, stable egress through TikTools.
      *
      * The decoded events emitted are identical in both modes — code that
      * uses `client.on('chat', e => ...)` works without changes.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tiktool/live",
-    "version": "2.11.1",
+    "version": "2.11.2",
     "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",