tiktok-live-api 1.3.1 → 1.4.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 TikTool
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 TikTool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,7 +12,6 @@
 [![npm downloads](https://img.shields.io/npm/dm/tiktok-live-api)](https://www.npmjs.com/package/tiktok-live-api)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/npm/l/tiktok-live-api)](https://github.com/tiktool/tiktok-live-api/blob/main/LICENSE)
-[![Discord](https://img.shields.io/discord/1482387222912172159?logo=discord&label=Discord&color=5865F2)](https://discord.gg/y8TwuFBAmD)
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/tiktool/tiktok-live-api/main/tiktok-live-api.gif" alt="TikTok Live API Demo — real-time chat, gifts, and viewer events" width="700">
@@ -67,14 +66,14 @@ That's it. **No complex setup, no protobuf, no reverse engineering, no breakages
 
 ---
 
-## 🚀 Try It Now — 5-Minute Live Demo
+## 🚀 Try It Now — Live Demo
 
-Copy-paste this into a file and run it. Connects to a live TikTok stream, prints every event for 5 minutes, then exits. Works on the free Sandbox tier.
+Copy-paste this into a file and run it. Connects to a live TikTok stream and prints every event in real time. Works on the free Community tier — no time limit, runs as long as the stream is live.
 
 **Save as `demo.mjs` and run with `node demo.mjs`:**
 
 ```javascript
-// demo.mjs — TikTok LIVE in 5 minutes
+// demo.mjs — TikTok LIVE in real time
 // npm install tiktok-live-api
 import { TikTokLive } from 'tiktok-live-api';
 
@@ -91,11 +90,11 @@ client.on('member',      e => { events++; console.log(`👋 ${e.user.uniqueId} j
 client.on('follow',      e => { events++; console.log(`➕ ${e.user.uniqueId} followed`); });
 client.on('roomUserSeq', e => { events++; console.log(`👀 Viewers: ${e.viewerCount}`); });
 
-client.on('connected',    () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
-client.on('disconnected', () => console.log(`\n📊 Done! Received ${events} events.\n`));
+client.on('connected',    () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — streaming events...\n`));
+client.on('disconnected', () => console.log(`\n📊 Disconnected. Received ${events} events.\n`));
 
 client.connect();
-setTimeout(() => { client.disconnect(); }, 300_000);
+// Press Ctrl+C to stop. Community tier has no per-connection time limit.
 ```
 
 <details>
@@ -112,7 +111,7 @@ const LIVE_USERNAME = 'tv_asahi_news';
 const ws = new WebSocket(`wss://api.tik.tools?uniqueId=${LIVE_USERNAME}&apiKey=${API_KEY}`);
 let events = 0;
 
-ws.on('open', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
+ws.on('open', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — streaming events...\n`));
 ws.on('message', (raw) => {
   const msg = JSON.parse(raw);
   events++;
@@ -128,9 +127,8 @@ ws.on('message', (raw) => {
     default:            console.log(`📦 ${msg.event}`); break;
   }
 });
-ws.on('close', () => console.log(`\n📊 Done! Received ${events} events.\n`));
-
-setTimeout(() => ws.close(), 300_000);
+ws.on('close', () => console.log(`\n📊 Disconnected. Received ${events} events.\n`));
+// Press Ctrl+C to stop. Community tier has no per-connection time limit.
 ```
 
 </details>
@@ -153,7 +151,7 @@ client.connect();
 2. Sign up (no credit card required)
 3. Copy your API key
 
-The free Sandbox tier gives you 50 requests/day and 1 WebSocket connection.
+The free **Community** tier gives you 2,500 requests/day and 15 WebSocket connections with no per-connection time limit. Forever free.
 
 ## Environment Variable
 
@@ -373,24 +371,43 @@ client.on('gift', (event: GiftEvent) => {
 | **Maintenance** | ✓ Zero — we handle it | ✗ You fix breakages | ✗ You fix breakages |
 | **CAPTCHA Solving** | ✓ Built-in (Pro+) | ✗ | ✗ |
 | **Feed Discovery** | ✓ See who's live | ✗ | ✗ |
-| **Free Tier** | ✓ 50 requests/day | ✓ Free (unreliable) | ✓ Free (unreliable) |
+| **Free Tier** | ✓ 2,500 req/day, 15 WS, no time limit | ✓ Free (unreliable) | ✓ Free (unreliable) |
 | **ESM + CJS** | ✓ Both supported | ✓ | N/A |
 
 ## Pricing
 
 | Tier | Requests/Day | WebSocket Connections | Price |
 |------|-------------|----------------------|-------|
-| Sandbox | 50 | 1 (5 min) | Free |
-| Basic | 10,000 | 3 (8h) | $9/wk +tax |
-| Pro | 75,000 | 50 (8h) | $19/wk +tax |
-| Ultra | 300,000 | 250 (8h) | $58/wk +tax |
+| Community | 2,500 | 15 (no time limit) | Free forever |
+| Pro | 75,000 | 50 (8h) | from $59/mo +tax |
+| Ultra | 300,000 | 250 (8h) | from $219/mo +tax |
+| **Global Agency** | 300,000 | 500 (8h) + Firehose | $549/mo +tax |
 
 Full plan details at [tik.tools/pricing](https://tik.tools/pricing). Highlights:
 
-- **Sandbox** ($0): 50 req/day · 1 WS (5 min limit) · basic endpoints · signatures included
-- **Basic** ($9/wk): 10K req/day · 3 WS · all endpoints · 1 AI caption stream
-- **Pro** ($19/wk, **most popular**): 75K req/day · 50 WS · all endpoints · 5 AI caption streams · priority routing · chat support
-- **Ultra** ($58/wk): 300K req/day · 250 WS · 20 AI caption streams · **League Rankings API** (Ultra only) · 99.5% uptime SLA · priority chat support
+- **Community** ($0 forever): 2,500 req/day · 15 WS · no time limit · masked leaderboards. Designed for devs building apps — upgrade when you need real usernames. No datacenter proxies; calls must come from your own IP.
+- **Pro** (monthly): 75K req/day · 50 WS · unmasked leaderboards · CAPTCHA Solver · Feed Discovery · 5 AI caption streams · priority routing · chat support
+- **Ultra** (monthly): 300K req/day · 250 WS · 20 AI caption streams · **League Rankings API** unmasked · 99.5% uptime SLA · priority chat support
+- **Global Agency** ($549/mo): Everything in Ultra + **Live Gifter Firehose WS** (region/league/global filters, min-diamond threshold) + VIP Telegram alerts + VIP Web Vault (unmasked historical visual access)
+
+### Live Gifter Firehose — Global Agency
+
+Real-time gift event stream from our Dragonfly fan-out. Filter by region, league, or globally; cap by minimum diamond threshold. Mid-stream filter updates supported via `update_filter` frame, no reconnect needed.
+
+```js
+const ws = new WebSocket(
+  `wss://api.tik.tools/firehose/gifters?apiKey=${KEY}&mode=region&region=US%2B&min_diamonds=1000`
+)
+ws.on('message', (raw) => {
+  const evt = JSON.parse(raw)
+  // evt: { type:'gifter_alert', ts, gifter:{username,displayName,isAnonymous},
+  //        creator:{uniqueId}, gift:{name,totalDiamonds}, region }
+})
+// Update filter without reconnect
+ws.send(JSON.stringify({ type: 'update_filter', mode: 'global', min_diamonds: 5000 }))
+```
+
+Modes: `global` (all regions), `region` (single region code), `league` (region + league class, e.g. `B2`).
 
 ## Also Available
 

package/package.json

@@ -1,84 +1,84 @@
-{
-  "name": "tiktok-live-api",
-  "version": "1.3.1",
-  "description": "Unofficial TikTok LIVE API Client — Real-time chat, gifts, viewers, battles, and AI live captions from any TikTok livestream. Managed WebSocket API with 99.9% uptime.",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "tiktok",
-    "tiktok-live",
-    "tiktok-api",
-    "tiktok-live-api",
-    "tiktok-live-connector",
-    "tiktok-live-sdk",
-    "tiktok-websocket",
-    "tiktok-chat",
-    "tiktok-gifts",
-    "tiktok-bot",
-    "tiktok-data",
-    "tiktok-stream",
-    "tiktok-events",
-    "tiktok-viewer",
-    "live-streaming",
-    "live-chat",
-    "webcast",
-    "websocket",
-    "real-time",
-    "speech-to-text",
-    "captions",
-    "transcription",
-    "translation",
-    "tiktok-live-python",
-    "tiktok-tools",
-    "euler-stream",
-    "tiktoklive",
-    "tiktok-connector",
-    "tiktok-live-node",
-    "tiktok-live-js",
-    "tiktok-scraper",
-    "tiktok-monitoring",
-    "livestream-api"
-  ],
-  "author": {
-    "name": "TikTool",
-    "email": "support@tik.tools",
-    "url": "https://tik.tools"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tiktool/tiktok-live-api"
-  },
-  "bugs": {
-    "url": "https://github.com/tiktool/tiktok-live-api/issues"
-  },
-  "homepage": "https://tik.tools",
-  "dependencies": {
-    "ws": "^8.16.0"
-  },
-  "devDependencies": {
-    "@types/ws": "^8.5.10",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  }
-}
+{
+  "name": "tiktok-live-api",
+  "version": "1.4.1",
+  "description": "Unofficial TikTok LIVE API Client — Real-time chat, gifts, viewers, battles, and AI live captions from any TikTok livestream. Managed WebSocket API with 99.9% uptime.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "tiktok",
+    "tiktok-live",
+    "tiktok-api",
+    "tiktok-live-api",
+    "tiktok-live-connector",
+    "tiktok-live-sdk",
+    "tiktok-websocket",
+    "tiktok-chat",
+    "tiktok-gifts",
+    "tiktok-bot",
+    "tiktok-data",
+    "tiktok-stream",
+    "tiktok-events",
+    "tiktok-viewer",
+    "live-streaming",
+    "live-chat",
+    "webcast",
+    "websocket",
+    "real-time",
+    "speech-to-text",
+    "captions",
+    "transcription",
+    "translation",
+    "tiktok-live-python",
+    "tiktok-tools",
+    "euler-stream",
+    "tiktoklive",
+    "tiktok-connector",
+    "tiktok-live-node",
+    "tiktok-live-js",
+    "tiktok-scraper",
+    "tiktok-monitoring",
+    "livestream-api"
+  ],
+  "author": {
+    "name": "TikTool",
+    "email": "support@tik.tools",
+    "url": "https://tik.tools"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tiktool/tiktok-live-api"
+  },
+  "bugs": {
+    "url": "https://github.com/tiktool/tiktok-live-api/issues"
+  },
+  "homepage": "https://tik.tools",
+  "dependencies": {
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}