tiktok-live-api 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,290 @@
+# tiktok-live-api
+
+**Unofficial TikTok LIVE API Client for Node.js & TypeScript** — Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, viewer counts, battles, and more. Includes AI-powered live captions (speech-to-text). Powered by the [TikTool](https://tik.tools) managed API.
+
+[![npm](https://img.shields.io/npm/v/tiktok-live-api)](https://www.npmjs.com/package/tiktok-live-api)
+[![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)
+
+> This package is **not affiliated with or endorsed by TikTok**. It connects to the [TikTool Live](https://tik.tools) managed API service — 99.9% uptime, no reverse engineering, no maintenance required. Also available for [Python](https://pypi.org/project/tiktok-live-api/) and [any language via WebSocket](https://tik.tools/docs).
+
+## Install
+
+```bash
+npm install tiktok-live-api
+```
+
+```bash
+# or with yarn / pnpm / bun
+yarn add tiktok-live-api
+pnpm add tiktok-live-api
+bun add tiktok-live-api
+```
+
+## Quick Start
+
+```typescript
+import { TikTokLive } from 'tiktok-live-api';
+
+const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
+
+client.on('chat', (event) => {
+  console.log(`${event.user.uniqueId}: ${event.comment}`);
+});
+
+client.on('gift', (event) => {
+  console.log(`${event.user.uniqueId} sent ${event.giftName} (${event.diamondCount} 💎)`);
+});
+
+client.on('like', (event) => {
+  console.log(`${event.user.uniqueId} liked (total: ${event.totalLikes})`);
+});
+
+client.on('follow', (event) => {
+  console.log(`${event.user.uniqueId} followed!`);
+});
+
+client.on('roomUserSeq', (event) => {
+  console.log(`${event.viewerCount} viewers watching`);
+});
+
+client.connect();
+```
+
+That's it. **No complex setup, no protobuf, no reverse engineering, no breakages when TikTok updates.**
+
+## JavaScript (CommonJS)
+
+```javascript
+const { TikTokLive } = require('tiktok-live-api');
+
+const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
+client.on('chat', (e) => console.log(`${e.user.uniqueId}: ${e.comment}`));
+client.connect();
+```
+
+## Get a Free API Key
+
+1. Go to [tik.tools](https://tik.tools)
+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.
+
+## Environment Variable
+
+Instead of passing `apiKey` directly, you can set it as an environment variable:
+
+```bash
+# Linux / macOS
+export TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (CMD)
+set TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (PowerShell)
+$env:TIKTOOL_API_KEY="your_api_key_here"
+```
+
+```typescript
+import { TikTokLive } from 'tiktok-live-api';
+
+// Automatically reads TIKTOOL_API_KEY from environment
+const client = new TikTokLive('streamer_username');
+client.on('chat', (e) => console.log(e.comment));
+client.connect();
+```
+
+## Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `chat` | Chat message | `user`, `comment`, `emotes` |
+| `gift` | Virtual gift | `user`, `giftName`, `diamondCount`, `repeatCount` |
+| `like` | Like event | `user`, `likeCount`, `totalLikes` |
+| `follow` | New follower | `user` |
+| `share` | Stream share | `user` |
+| `member` | Viewer joined | `user` |
+| `subscribe` | New subscriber | `user` |
+| `roomUserSeq` | Viewer count | `viewerCount`, `topViewers` |
+| `battle` | Battle event | `type`, `teams`, `scores` |
+| `envelope` | Treasure chest | `diamonds`, `user` |
+| `streamEnd` | Stream ended | `reason` |
+| `connected` | Connected | `uniqueId` |
+| `disconnected` | Disconnected | `uniqueId` |
+| `error` | Error occurred | `error` |
+| `event` | Catch-all | Full raw event |
+
+All events are fully typed with TypeScript interfaces. Your IDE will show autocompletion for every field.
+
+## Live Captions (Speech-to-Text)
+
+Transcribe and translate any TikTok LIVE stream in real-time. **This feature is unique to TikTool Live — no other TikTok library offers it.**
+
+```typescript
+import { TikTokCaptions } from 'tiktok-live-api';
+
+const captions = new TikTokCaptions('streamer_username', {
+  apiKey: 'YOUR_API_KEY',
+  translate: 'en',       // translate to English
+  diarization: true,     // identify who is speaking
+});
+
+captions.on('caption', (event) => {
+  const speaker = event.speaker ? `[${event.speaker}] ` : '';
+  console.log(`${speaker}${event.text}${event.isFinal ? ' ✓' : '...'}`);
+});
+
+captions.on('translation', (event) => {
+  console.log(`  → ${event.text}`);
+});
+
+captions.on('credits', (event) => {
+  console.log(`${event.remaining}/${event.total} minutes remaining`);
+});
+
+captions.connect();
+```
+
+### Caption Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `caption` | Real-time caption text | `text`, `speaker`, `isFinal`, `language` |
+| `translation` | Translated caption | `text`, `sourceLanguage`, `targetLanguage` |
+| `credits` | Credit balance update | `total`, `used`, `remaining` |
+| `credits_low` | Low credit warning | `remaining`, `percentage` |
+| `status` | Session status | `status`, `message` |
+
+## Chat Bot Example
+
+```typescript
+import { TikTokLive } from 'tiktok-live-api';
+
+const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
+const giftLeaderboard = new Map<string, number>();
+let messageCount = 0;
+
+client.on('chat', (event) => {
+  messageCount++;
+  const msg = event.comment.toLowerCase().trim();
+  const user = event.user.uniqueId;
+
+  if (msg === '!hello') {
+    console.log(`>> BOT: Welcome ${user}! 👋`);
+  } else if (msg === '!stats') {
+    console.log(`>> BOT: ${messageCount} messages, ${giftLeaderboard.size} gifters`);
+  } else if (msg === '!top') {
+    const top = [...giftLeaderboard.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+    top.forEach(([name, diamonds], i) => {
+      console.log(`  ${i + 1}. ${name} — ${diamonds} 💎`);
+    });
+  }
+});
+
+client.on('gift', (event) => {
+  const user = event.user.uniqueId;
+  const diamonds = event.diamondCount || 0;
+  giftLeaderboard.set(user, (giftLeaderboard.get(user) || 0) + diamonds);
+});
+
+client.connect();
+```
+
+## TypeScript
+
+This package ships with full TypeScript support. All events are typed:
+
+```typescript
+import { TikTokLive, ChatEvent, GiftEvent } from 'tiktok-live-api';
+
+const client = new TikTokLive('streamer', { apiKey: 'KEY' });
+
+// Full autocompletion — your IDE knows the type of `event`
+client.on('chat', (event: ChatEvent) => {
+  console.log(event.user.uniqueId);  // ✓ typed
+  console.log(event.comment);        // ✓ typed
+});
+
+client.on('gift', (event: GiftEvent) => {
+  console.log(event.giftName);       // ✓ typed
+  console.log(event.diamondCount);   // ✓ typed
+});
+```
+
+## API Reference
+
+### `new TikTokLive(uniqueId, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `process.env.TIKTOOL_API_KEY` | Your TikTool API key |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts |
+
+**Methods:**
+- `client.on(event, handler)` — Register event handler
+- `client.off(event, handler)` — Remove event handler
+- `client.connect()` — Connect to stream (returns Promise)
+- `client.disconnect()` — Disconnect from stream
+- `client.connected` — Whether currently connected
+- `client.eventCount` — Total events received
+
+### `new TikTokCaptions(uniqueId, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `process.env.TIKTOOL_API_KEY` | Your TikTool API key |
+| `translate` | `string` | `undefined` | Target translation language |
+| `diarization` | `boolean` | `true` | Enable speaker identification |
+| `maxDurationMinutes` | `number` | `60` | Auto-disconnect timer |
+
+**Methods:**
+- `captions.on(event, handler)` — Register event handler
+- `captions.off(event, handler)` — Remove event handler
+- `captions.connect()` — Start receiving captions (returns Promise)
+- `captions.disconnect()` — Stop receiving captions
+- `captions.connected` — Whether currently connected
+
+## Why tiktok-live-api?
+
+| | tiktok-live-api | tiktok-live-connector | TikTokLive (Python) |
+|---|---|---|---|
+| **Stability** | ✓ Managed API, 99.9% uptime | ✗ Breaks on TikTok updates | ✗ Breaks on TikTok updates |
+| **TypeScript** | ✓ First-class, fully typed | Partial | N/A |
+| **Live Captions** | ✓ AI speech-to-text | ✗ | ✗ |
+| **Translation** | ✓ Real-time, 50+ languages | ✗ | ✗ |
+| **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) |
+| **ESM + CJS** | ✓ Both supported | ✓ | N/A |
+
+## Pricing
+
+| Tier | Requests/Day | WebSocket Connections | Price |
+|------|-------------|----------------------|-------|
+| Sandbox | 50 | 1 (60s) | Free |
+| Basic | 10,000 | 3 (8h) | $7/week |
+| Pro | 75,000 | 50 (8h) | $15/week |
+| Ultra | 300,000 | 500 (8h) | $45/week |
+
+## Also Available
+
+- **Python**: [`pip install tiktok-live-api`](https://pypi.org/project/tiktok-live-api/)
+- **Any language**: Connect via WebSocket: `wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY`
+- **Unreal Engine**: Native C++/Blueprint plugin
+
+## Links
+
+- 🌐 **Website**: [tik.tools](https://tik.tools)
+- 📖 **Documentation**: [tik.tools/docs](https://tik.tools/docs)
+- 🐍 **Python SDK**: [pypi.org/project/tiktok-live-api](https://pypi.org/project/tiktok-live-api/)
+- 💻 **GitHub**: [github.com/tiktool/tiktok-live-api](https://github.com/tiktool/tiktok-live-api)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,349 @@
+/**
+ * Type definitions for TikTok LIVE API events.
+ *
+ * These types provide IDE autocompletion and type safety
+ * when handling events from {@link TikTokLive} and {@link TikTokCaptions}.
+ *
+ * @packageDocumentation
+ */
+/** User profile attached to most LIVE events. */
+interface TikTokUser {
+    userId: string;
+    uniqueId: string;
+    nickname: string;
+    profilePictureUrl: string;
+    followRole: number;
+    isSubscriber: boolean;
+}
+/** Payload for `chat` events. */
+interface ChatEvent {
+    user: TikTokUser;
+    comment: string;
+    emotes: Array<{
+        emoteId: string;
+        image: string;
+    }>;
+}
+/** Payload for `gift` events. */
+interface GiftEvent {
+    user: TikTokUser;
+    giftId: number;
+    giftName: string;
+    diamondCount: number;
+    repeatCount: number;
+    repeatEnd: boolean;
+}
+/** Payload for `like` events. */
+interface LikeEvent {
+    user: TikTokUser;
+    likeCount: number;
+    totalLikes: number;
+}
+/** Payload for `member` (viewer join) events. */
+interface MemberEvent {
+    user: TikTokUser;
+    actionId: number;
+}
+/** Payload for `follow` and `share` events. */
+interface SocialEvent {
+    user: TikTokUser;
+    eventType: string;
+}
+/** Payload for `roomUserSeq` (viewer count) events. */
+interface RoomUserSeqEvent {
+    viewerCount: number;
+    topViewers: TikTokUser[];
+}
+/** Payload for `battle` events. */
+interface BattleEvent {
+    type: string;
+    teams: Array<Record<string, unknown>>;
+    scores: number[];
+}
+/** Payload for `caption` events from {@link TikTokCaptions}. */
+interface CaptionEvent {
+    text: string;
+    speaker: string;
+    isFinal: boolean;
+    language: string;
+}
+/** Payload for `translation` events from {@link TikTokCaptions}. */
+interface TranslationEvent {
+    text: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+}
+/** Payload for `credits` events from {@link TikTokCaptions}. */
+interface CreditsEvent {
+    total: number;
+    used: number;
+    remaining: number;
+}
+/** Connection event payload. */
+interface ConnectedEvent {
+    uniqueId: string;
+}
+/** Disconnection event payload. */
+interface DisconnectedEvent {
+    uniqueId: string;
+}
+/** Error event payload. */
+interface ErrorEvent {
+    error: string;
+}
+/**
+ * Map of event names to their payload types for {@link TikTokLive}.
+ */
+interface TikTokLiveEventMap {
+    chat: ChatEvent;
+    gift: GiftEvent;
+    like: LikeEvent;
+    follow: SocialEvent;
+    share: SocialEvent;
+    member: MemberEvent;
+    subscribe: SocialEvent;
+    roomUserSeq: RoomUserSeqEvent;
+    battle: BattleEvent;
+    envelope: Record<string, unknown>;
+    streamEnd: Record<string, unknown>;
+    roomInfo: Record<string, unknown>;
+    connected: ConnectedEvent;
+    disconnected: DisconnectedEvent;
+    error: ErrorEvent;
+    event: Record<string, unknown>;
+}
+/**
+ * Map of event names to their payload types for {@link TikTokCaptions}.
+ */
+interface TikTokCaptionsEventMap {
+    caption: CaptionEvent;
+    translation: TranslationEvent;
+    credits: CreditsEvent;
+    credits_low: CreditsEvent;
+    status: Record<string, unknown>;
+    connected: ConnectedEvent;
+    disconnected: DisconnectedEvent;
+    error: ErrorEvent;
+}
+
+/**
+ * TikTokLive — Connect to any TikTok LIVE stream via WebSocket.
+ *
+ * Receives real-time events: chat messages, gifts, likes, follows,
+ * viewer counts, battles, and more. Powered by the TikTool managed API.
+ *
+ * @example
+ * ```typescript
+ * import { TikTokLive } from 'tiktok-live-api';
+ *
+ * const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_KEY' });
+ *
+ * client.on('chat', (event) => {
+ *   console.log(`${event.user.uniqueId}: ${event.comment}`);
+ * });
+ *
+ * client.connect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link TikTokLive} constructor. */
+interface TikTokLiveOptions {
+    /** Your TikTool API key. Get one free at https://tik.tools */
+    apiKey?: string;
+    /** Auto-reconnect on disconnect (default: true). */
+    autoReconnect?: boolean;
+    /** Max reconnection attempts (default: 5). */
+    maxReconnectAttempts?: number;
+}
+type EventHandler$1<T> = (data: T) => void | Promise<void>;
+/**
+ * Connect to a TikTok LIVE stream and receive real-time events.
+ *
+ * @example
+ * ```typescript
+ * const client = new TikTokLive('username', { apiKey: 'KEY' });
+ * client.on('chat', (e) => console.log(e.comment));
+ * client.on('gift', (e) => console.log(`${e.giftName} worth ${e.diamondCount} 💎`));
+ * client.connect();
+ * ```
+ */
+declare class TikTokLive {
+    /** TikTok username (without @). */
+    readonly uniqueId: string;
+    /** Your TikTool API key. */
+    readonly apiKey: string;
+    /** Whether to auto-reconnect on disconnect. */
+    readonly autoReconnect: boolean;
+    /** Maximum reconnection attempts. */
+    readonly maxReconnectAttempts: number;
+    private _handlers;
+    private _ws;
+    private _connected;
+    private _intentionalClose;
+    private _reconnectAttempts;
+    private _eventCount;
+    /**
+     * Create a new TikTokLive client.
+     *
+     * @param uniqueId - TikTok username (without @)
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * const client = new TikTokLive('streamer', { apiKey: 'YOUR_KEY' });
+     * ```
+     */
+    constructor(uniqueId: string, options?: TikTokLiveOptions);
+    /** Whether the client is currently connected. */
+    get connected(): boolean;
+    /** Total number of events received this session. */
+    get eventCount(): number;
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name (chat, gift, like, follow, etc.)
+     * @param handler - Callback function
+     * @returns this (for chaining)
+     *
+     * @example
+     * ```typescript
+     * client.on('chat', (event) => console.log(event.comment));
+     * client.on('gift', (event) => console.log(event.giftName));
+     * ```
+     */
+    on<K extends keyof TikTokLiveEventMap>(event: K, handler: EventHandler$1<TikTokLiveEventMap[K]>): this;
+    on(event: string, handler: EventHandler$1<any>): this;
+    /**
+     * Remove an event handler.
+     *
+     * @param event - Event name
+     * @param handler - The handler to remove
+     */
+    off(event: string, handler: EventHandler$1<any>): this;
+    private _emit;
+    /**
+     * Connect to the TikTok LIVE stream.
+     *
+     * @returns Promise that resolves when connected, rejects on fatal error.
+     *
+     * @example
+     * ```typescript
+     * await client.connect();
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the stream.
+     */
+    disconnect(): void;
+    private _maybeReconnect;
+}
+
+/**
+ * TikTokCaptions — Real-time AI speech-to-text for TikTok LIVE streams.
+ *
+ * Transcribe and translate any TikTok LIVE stream in real-time.
+ * This feature is unique to TikTool Live — no other service offers it.
+ *
+ * @example
+ * ```typescript
+ * import { TikTokCaptions } from 'tiktok-live-api';
+ *
+ * const captions = new TikTokCaptions('streamer', {
+ *   apiKey: 'YOUR_KEY',
+ *   translate: 'en',
+ *   diarization: true,
+ * });
+ *
+ * captions.on('caption', (event) => {
+ *   console.log(`[${event.speaker}] ${event.text}`);
+ * });
+ *
+ * captions.connect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link TikTokCaptions} constructor. */
+interface TikTokCaptionsOptions {
+    /** Your TikTool API key. Get one at https://tik.tools */
+    apiKey?: string;
+    /** Target language code for real-time translation (e.g. "en", "es"). */
+    translate?: string;
+    /** Enable speaker identification (default: true). */
+    diarization?: boolean;
+    /** Auto-disconnect after N minutes (default: 60, max: 300). */
+    maxDurationMinutes?: number;
+}
+type EventHandler<T> = (data: T) => void | Promise<void>;
+/**
+ * Real-time AI speech-to-text for TikTok LIVE streams.
+ *
+ * @example
+ * ```typescript
+ * const captions = new TikTokCaptions('streamer', {
+ *   apiKey: 'KEY',
+ *   translate: 'en',
+ * });
+ * captions.on('caption', (e) => console.log(e.text));
+ * captions.on('translation', (e) => console.log(`→ ${e.text}`));
+ * captions.connect();
+ * ```
+ */
+declare class TikTokCaptions {
+    /** TikTok username (without @). */
+    readonly uniqueId: string;
+    /** Your TikTool API key. */
+    readonly apiKey: string;
+    /** Target translation language. */
+    readonly translate?: string;
+    /** Whether speaker diarization is enabled. */
+    readonly diarization: boolean;
+    /** Max session duration in minutes. */
+    readonly maxDurationMinutes?: number;
+    private _handlers;
+    private _ws;
+    private _connected;
+    private _intentionalClose;
+    /**
+     * Create a new TikTokCaptions client.
+     *
+     * @param uniqueId - TikTok username (without @)
+     * @param options - Configuration options
+     */
+    constructor(uniqueId: string, options?: TikTokCaptionsOptions);
+    /** Whether currently connected and receiving captions. */
+    get connected(): boolean;
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name (caption, translation, credits, status, error)
+     * @param handler - Callback function
+     *
+     * @example
+     * ```typescript
+     * captions.on('caption', (event) => {
+     *   const prefix = event.speaker ? `[${event.speaker}] ` : '';
+     *   console.log(`${prefix}${event.text}${event.isFinal ? ' ✓' : '...'}`);
+     * });
+     * ```
+     */
+    on<K extends keyof TikTokCaptionsEventMap>(event: K, handler: EventHandler<TikTokCaptionsEventMap[K]>): this;
+    on(event: string, handler: EventHandler<any>): this;
+    /** Remove an event handler. */
+    off(event: string, handler: EventHandler<any>): this;
+    private _emit;
+    /**
+     * Start receiving captions from the stream.
+     *
+     * @returns Promise that resolves when connected.
+     */
+    connect(): Promise<void>;
+    /** Stop receiving captions. */
+    disconnect(): void;
+}
+
+export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, type TranslationEvent };