@tiktool/live 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,251 @@
+<div align="center">
+
+# @tiktool/live
+
+### Connect to any TikTok LIVE stream in 3 lines of code.
+
+[![npm version](https://img.shields.io/npm/v/@tiktool/live?color=%23ff0050&label=npm&logo=npm)](https://www.npmjs.com/package/@tiktool/live)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org)
+
+Real-time chat, gifts, viewers, battles, follows & 18+ event types from any TikTok livestream.
+
+**No API key required** · **Zero config** · **Direct connection**
+
+[Quick Start](#-quick-start) · [Events](#-events) · [API](#-api-reference) · [Rate Limits](#-rate-limits)
+
+</div>
+
+---
+
+## ⚡ Quick Start
+
+```bash
+npm install @tiktool/live
+```
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({ uniqueId: 'tv_asahi_news' });
+
+live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
+live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`));
+live.on('member', e => console.log(`${e.user.uniqueId} joined`));
+live.on('roomUserSeq', e => console.log(`Viewers: ${e.viewerCount}`));
+
+await live.connect();
+```
+
+No API key, no configuration, no server setup. Install and connect.
+
+---
+
+## How It Works
+
+```
+    Your App                    tik.tools                    TikTok
+  +-----------+              +--------------+           +--------------+
+  |          -+-- sign_url -->  Signs URL   |           |              |
+  |  Your   <-+-- X-Bogus --|  with params |           |   TikTok     |
+  |  Code    |              |              |           |   WebSocket  |
+  |          -+------------ Connect directly ---------->|   Server     |
+  |          <-+------------ Live events (protobuf) <---|              |
+  +-----------+              +--------------+           +--------------+
+                            ^ Only interaction             ^ Direct from
+                              with our server                YOUR IP
+```
+
+- Your app connects directly to TikTok from your IP address
+- The sign server only generates cryptographic signatures
+- TikTok never sees the sign server
+- Built-in protobuf parser, no external dependencies
+
+---
+
+## Events
+
+### Listening
+
+```typescript
+live.on('chat', (event) => {
+    event.user.uniqueId  // string
+    event.comment        // string
+});
+
+live.on('event', (event) => {
+    console.log(event.type, event);
+});
+```
+
+### Reference
+
+| Event | Type | Description | Fields |
+|-------|------|-------------|--------|
+| `chat` | `ChatEvent` | Chat message | `user`, `comment` |
+| `member` | `MemberEvent` | User joined | `user`, `action` |
+| `like` | `LikeEvent` | User liked | `user`, `likeCount`, `totalLikes` |
+| `gift` | `GiftEvent` | Gift sent | `user`, `giftName`, `diamondCount`, `repeatCount`, `combo` |
+| `social` | `SocialEvent` | Follow / Share | `user`, `action` |
+| `roomUserSeq` | `RoomUserSeqEvent` | Viewer count | `viewerCount`, `totalViewers` |
+| `battle` | `BattleEvent` | Link Mic battle | `status` |
+| `battleArmies` | `BattleArmiesEvent` | Battle teams | — |
+| `subscribe` | `SubscribeEvent` | New subscriber | `user`, `subMonth` |
+| `emoteChat` | `EmoteChatEvent` | Emote in chat | `user`, `emoteId` |
+| `envelope` | `EnvelopeEvent` | Treasure chest | `diamondCount` |
+| `question` | `QuestionEvent` | Q&A question | `user`, `questionText` |
+| `control` | `ControlEvent` | Stream control | `action` (3 = ended) |
+| `room` | `RoomEvent` | Room status | `status` |
+| `liveIntro` | `LiveIntroEvent` | Stream intro | `title` |
+| `rankUpdate` | `RankUpdateEvent` | Rank update | `rankType` |
+| `linkMic` | `LinkMicEvent` | Link Mic | `action` |
+| `unknown` | `UnknownEvent` | Unrecognized | `method` |
+
+### Connection Events
+
+| Event | Callback | Description |
+|-------|----------|-------------|
+| `connected` | `() => void` | Connected to stream |
+| `disconnected` | `(code, reason) => void` | Disconnected |
+| `roomInfo` | `(info: RoomInfo) => void` | Room info |
+| `error` | `(error: Error) => void` | Error |
+
+---
+
+## API Reference
+
+### `new TikTokLive(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `uniqueId` | `string` | — | TikTok username (without @) |
+| `signServerUrl` | `string` | `https://api.tik.tools` | Sign server URL |
+| `apiKey` | `string` | — | API key for higher rate limits |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
+| `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
+| `debug` | `boolean` | `false` | Debug logging |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `Promise<void>` | Connect to livestream |
+| `disconnect()` | `void` | Disconnect |
+| `connected` | `boolean` | Connection status |
+| `eventCount` | `number` | Total events received |
+| `roomId` | `string` | Current room ID |
+
+---
+
+## Rate Limits
+
+| Tier | Rate Limit | API Key | Price |
+|------|-----------|---------|-------|
+| Free | 5 signs/min | No | Free |
+| Basic | 30 signs/min | Yes | Free (with key) |
+| Premium | 120 signs/min | Yes | Coming soon |
+
+Most users only need the free tier. The SDK calls the sign server once per connection, then stays connected via WebSocket.
+
+### Using an API Key
+
+```typescript
+const live = new TikTokLive({
+    uniqueId: 'username',
+    apiKey: 'your-api-key',
+});
+```
+
+---
+
+## Examples
+
+### Chat Bot
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({ uniqueId: 'streamer_name' });
+
+live.on('chat', (e) => {
+    if (e.comment.toLowerCase() === '!hello') {
+        console.log(`Hello, ${e.user.nickname}!`);
+    }
+});
+
+live.on('gift', (e) => {
+    if (e.repeatEnd) {
+        console.log(`${e.user.uniqueId} sent ${e.repeatCount}x ${e.giftName} (${e.diamondCount * e.repeatCount} diamonds)`);
+    }
+});
+
+await live.connect();
+```
+
+### OBS Overlay
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+const live = new TikTokLive({ uniqueId: 'streamer_name' });
+
+live.on('event', (event) => {
+    for (const client of wss.clients) {
+        client.send(JSON.stringify(event));
+    }
+});
+
+await live.connect();
+console.log('Forwarding events to ws://localhost:8080');
+```
+
+### Gift Tracker
+
+```typescript
+import { TikTokLive } from '@tiktool/live';
+
+const live = new TikTokLive({ uniqueId: 'streamer_name' });
+let totalDiamonds = 0;
+
+live.on('gift', (e) => {
+    if (e.repeatEnd || !e.combo) {
+        const diamonds = e.diamondCount * (e.repeatCount || 1);
+        totalDiamonds += diamonds;
+        console.log(`${e.user.uniqueId}: ${e.giftName} = ${diamonds} diamonds (Total: ${totalDiamonds})`);
+    }
+});
+
+await live.connect();
+```
+
+---
+
+## TypeScript
+
+Full TypeScript support with type inference:
+
+```typescript
+import { TikTokLive, ChatEvent, GiftEvent } from '@tiktool/live';
+
+const live = new TikTokLive({ uniqueId: 'username' });
+
+live.on('chat', (event: ChatEvent) => {
+    const username: string = event.user.uniqueId;
+    const message: string = event.comment;
+});
+
+live.on('gift', (event: GiftEvent) => {
+    const diamonds: number = event.diamondCount;
+    const isCombo: boolean = event.combo;
+});
+```
+
+---
+
+## License
+
+MIT © [tiktool](https://tik.tools)

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import { EventEmitter } from 'events';
+
+interface TikTokUser {
+    id: string;
+    nickname: string;
+    uniqueId: string;
+    profilePicture?: string;
+    badges?: string[];
+}
+interface BaseEvent {
+    type: string;
+    timestamp: number;
+    msgId: string;
+}
+interface ChatEvent extends BaseEvent {
+    type: 'chat';
+    user: TikTokUser;
+    comment: string;
+}
+interface MemberEvent extends BaseEvent {
+    type: 'member';
+    user: TikTokUser;
+    action: number;
+}
+interface LikeEvent extends BaseEvent {
+    type: 'like';
+    user: TikTokUser;
+    likeCount: number;
+    totalLikes: number;
+}
+interface GiftEvent extends BaseEvent {
+    type: 'gift';
+    user: TikTokUser;
+    giftId: number;
+    giftName: string;
+    diamondCount: number;
+    repeatCount: number;
+    repeatEnd: boolean;
+    combo: boolean;
+}
+interface SocialEvent extends BaseEvent {
+    type: 'social';
+    user: TikTokUser;
+    action: 'follow' | 'share' | string;
+}
+interface RoomUserSeqEvent extends BaseEvent {
+    type: 'roomUserSeq';
+    viewerCount: number;
+    totalViewers: number;
+}
+interface BattleEvent extends BaseEvent {
+    type: 'battle';
+    status: number;
+}
+interface BattleArmiesEvent extends BaseEvent {
+    type: 'battleArmies';
+}
+interface SubscribeEvent extends BaseEvent {
+    type: 'subscribe';
+    user: TikTokUser;
+    subMonth: number;
+}
+interface EmoteChatEvent extends BaseEvent {
+    type: 'emoteChat';
+    user: TikTokUser;
+    emoteId: string;
+}
+interface EnvelopeEvent extends BaseEvent {
+    type: 'envelope';
+    diamondCount: number;
+}
+interface QuestionEvent extends BaseEvent {
+    type: 'question';
+    user: TikTokUser;
+    questionText: string;
+}
+interface ControlEvent extends BaseEvent {
+    type: 'control';
+    action: number;
+}
+interface RoomEvent extends BaseEvent {
+    type: 'room';
+    status: string;
+}
+interface LiveIntroEvent extends BaseEvent {
+    type: 'liveIntro';
+    title: string;
+}
+interface RankUpdateEvent extends BaseEvent {
+    type: 'rankUpdate';
+    rankType: string;
+}
+interface LinkMicEvent extends BaseEvent {
+    type: 'linkMic';
+    action: number;
+}
+interface UnknownEvent extends BaseEvent {
+    type: 'unknown';
+    method: string;
+}
+type LiveEvent = ChatEvent | MemberEvent | LikeEvent | GiftEvent | SocialEvent | RoomUserSeqEvent | BattleEvent | BattleArmiesEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
+interface TikTokLiveEvents {
+    connected: () => void;
+    disconnected: (code: number, reason: string) => void;
+    roomInfo: (info: RoomInfo) => void;
+    error: (error: Error) => void;
+    chat: (event: ChatEvent) => void;
+    member: (event: MemberEvent) => void;
+    like: (event: LikeEvent) => void;
+    gift: (event: GiftEvent) => void;
+    social: (event: SocialEvent) => void;
+    roomUserSeq: (event: RoomUserSeqEvent) => void;
+    battle: (event: BattleEvent) => void;
+    battleArmies: (event: BattleArmiesEvent) => void;
+    subscribe: (event: SubscribeEvent) => void;
+    emoteChat: (event: EmoteChatEvent) => void;
+    envelope: (event: EnvelopeEvent) => void;
+    question: (event: QuestionEvent) => void;
+    control: (event: ControlEvent) => void;
+    room: (event: RoomEvent) => void;
+    liveIntro: (event: LiveIntroEvent) => void;
+    rankUpdate: (event: RankUpdateEvent) => void;
+    linkMic: (event: LinkMicEvent) => void;
+    unknown: (event: UnknownEvent) => void;
+    event: (event: LiveEvent) => void;
+}
+interface RoomInfo {
+    roomId: string;
+    wsHost: string;
+    clusterRegion: string;
+    connectedAt: string;
+}
+interface TikTokLiveOptions {
+    uniqueId: string;
+    signServerUrl?: string;
+    apiKey?: string;
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    heartbeatInterval?: number;
+    debug?: boolean;
+}
+
+declare class TikTokLive extends EventEmitter {
+    private ws;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    private intentionalClose;
+    private _connected;
+    private _eventCount;
+    private _roomId;
+    private readonly uniqueId;
+    private readonly signServerUrl;
+    private readonly apiKey?;
+    private readonly autoReconnect;
+    private readonly maxReconnectAttempts;
+    private readonly heartbeatInterval;
+    private readonly debug;
+    constructor(options: TikTokLiveOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    get connected(): boolean;
+    get eventCount(): number;
+    get roomId(): string;
+    on<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    once<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    off<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    emit<K extends keyof TikTokLiveEvents>(event: K, ...args: Parameters<TikTokLiveEvents[K]>): boolean;
+    private handleFrame;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+
+export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, 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 SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import { EventEmitter } from 'events';
+
+interface TikTokUser {
+    id: string;
+    nickname: string;
+    uniqueId: string;
+    profilePicture?: string;
+    badges?: string[];
+}
+interface BaseEvent {
+    type: string;
+    timestamp: number;
+    msgId: string;
+}
+interface ChatEvent extends BaseEvent {
+    type: 'chat';
+    user: TikTokUser;
+    comment: string;
+}
+interface MemberEvent extends BaseEvent {
+    type: 'member';
+    user: TikTokUser;
+    action: number;
+}
+interface LikeEvent extends BaseEvent {
+    type: 'like';
+    user: TikTokUser;
+    likeCount: number;
+    totalLikes: number;
+}
+interface GiftEvent extends BaseEvent {
+    type: 'gift';
+    user: TikTokUser;
+    giftId: number;
+    giftName: string;
+    diamondCount: number;
+    repeatCount: number;
+    repeatEnd: boolean;
+    combo: boolean;
+}
+interface SocialEvent extends BaseEvent {
+    type: 'social';
+    user: TikTokUser;
+    action: 'follow' | 'share' | string;
+}
+interface RoomUserSeqEvent extends BaseEvent {
+    type: 'roomUserSeq';
+    viewerCount: number;
+    totalViewers: number;
+}
+interface BattleEvent extends BaseEvent {
+    type: 'battle';
+    status: number;
+}
+interface BattleArmiesEvent extends BaseEvent {
+    type: 'battleArmies';
+}
+interface SubscribeEvent extends BaseEvent {
+    type: 'subscribe';
+    user: TikTokUser;
+    subMonth: number;
+}
+interface EmoteChatEvent extends BaseEvent {
+    type: 'emoteChat';
+    user: TikTokUser;
+    emoteId: string;
+}
+interface EnvelopeEvent extends BaseEvent {
+    type: 'envelope';
+    diamondCount: number;
+}
+interface QuestionEvent extends BaseEvent {
+    type: 'question';
+    user: TikTokUser;
+    questionText: string;
+}
+interface ControlEvent extends BaseEvent {
+    type: 'control';
+    action: number;
+}
+interface RoomEvent extends BaseEvent {
+    type: 'room';
+    status: string;
+}
+interface LiveIntroEvent extends BaseEvent {
+    type: 'liveIntro';
+    title: string;
+}
+interface RankUpdateEvent extends BaseEvent {
+    type: 'rankUpdate';
+    rankType: string;
+}
+interface LinkMicEvent extends BaseEvent {
+    type: 'linkMic';
+    action: number;
+}
+interface UnknownEvent extends BaseEvent {
+    type: 'unknown';
+    method: string;
+}
+type LiveEvent = ChatEvent | MemberEvent | LikeEvent | GiftEvent | SocialEvent | RoomUserSeqEvent | BattleEvent | BattleArmiesEvent | SubscribeEvent | EmoteChatEvent | EnvelopeEvent | QuestionEvent | ControlEvent | RoomEvent | LiveIntroEvent | RankUpdateEvent | LinkMicEvent | UnknownEvent;
+interface TikTokLiveEvents {
+    connected: () => void;
+    disconnected: (code: number, reason: string) => void;
+    roomInfo: (info: RoomInfo) => void;
+    error: (error: Error) => void;
+    chat: (event: ChatEvent) => void;
+    member: (event: MemberEvent) => void;
+    like: (event: LikeEvent) => void;
+    gift: (event: GiftEvent) => void;
+    social: (event: SocialEvent) => void;
+    roomUserSeq: (event: RoomUserSeqEvent) => void;
+    battle: (event: BattleEvent) => void;
+    battleArmies: (event: BattleArmiesEvent) => void;
+    subscribe: (event: SubscribeEvent) => void;
+    emoteChat: (event: EmoteChatEvent) => void;
+    envelope: (event: EnvelopeEvent) => void;
+    question: (event: QuestionEvent) => void;
+    control: (event: ControlEvent) => void;
+    room: (event: RoomEvent) => void;
+    liveIntro: (event: LiveIntroEvent) => void;
+    rankUpdate: (event: RankUpdateEvent) => void;
+    linkMic: (event: LinkMicEvent) => void;
+    unknown: (event: UnknownEvent) => void;
+    event: (event: LiveEvent) => void;
+}
+interface RoomInfo {
+    roomId: string;
+    wsHost: string;
+    clusterRegion: string;
+    connectedAt: string;
+}
+interface TikTokLiveOptions {
+    uniqueId: string;
+    signServerUrl?: string;
+    apiKey?: string;
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    heartbeatInterval?: number;
+    debug?: boolean;
+}
+
+declare class TikTokLive extends EventEmitter {
+    private ws;
+    private heartbeatTimer;
+    private reconnectAttempts;
+    private intentionalClose;
+    private _connected;
+    private _eventCount;
+    private _roomId;
+    private readonly uniqueId;
+    private readonly signServerUrl;
+    private readonly apiKey?;
+    private readonly autoReconnect;
+    private readonly maxReconnectAttempts;
+    private readonly heartbeatInterval;
+    private readonly debug;
+    constructor(options: TikTokLiveOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    get connected(): boolean;
+    get eventCount(): number;
+    get roomId(): string;
+    on<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    once<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    off<K extends keyof TikTokLiveEvents>(event: K, listener: TikTokLiveEvents[K]): this;
+    emit<K extends keyof TikTokLiveEvents>(event: K, ...args: Parameters<TikTokLiveEvents[K]>): boolean;
+    private handleFrame;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+
+export { type BaseEvent, type BattleArmiesEvent, type BattleEvent, 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 SubscribeEvent, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent };