tiktok-live-nuxt 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present TikTool (tik.tools)
+
+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,241 @@
+<p align="center">
+  <img src="banner.png" alt="tiktok-live-nuxt" width="100%" />
+</p>
+
+<h1 align="center">tiktok-live-nuxt</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/tiktok-live-nuxt"><img src="https://img.shields.io/npm/v/tiktok-live-nuxt?color=%2300dc82&logo=nuxt.js&logoColor=white" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/tiktok-live-nuxt"><img src="https://img.shields.io/npm/dm/tiktok-live-nuxt?color=%2300dc82" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  Nuxt module for <a href="https://tik.tools">TikTok LIVE API</a> — real-time chat, gifts, viewers, battles & AI captions from any TikTok LIVE stream.
+</p>
+
+---
+
+```vue
+<script setup>
+const { messages, viewers, gifts, connected } = useTikTokLive('gbnews')
+</script>
+
+<template>
+  <div>
+    <p>👀 {{ viewers }} viewers</p>
+    <div v-for="msg in messages" :key="msg.data?.msgId">
+      <b>{{ msg.data?.user?.uniqueId }}:</b> {{ msg.data?.comment }}
+    </div>
+  </div>
+</template>
+```
+
+That's it. Auto-imported, reactive, auto-connects on mount. ☝️
+
+---
+
+## Quick Setup
+
+### 1. Install
+
+```bash
+# npm
+npm install tiktok-live-nuxt
+
+# pnpm
+pnpm add tiktok-live-nuxt
+
+# bun
+bun add tiktok-live-nuxt
+
+# yarn
+yarn add tiktok-live-nuxt
+```
+
+### 2. Configure
+
+Add to `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['tiktok-live-nuxt'],
+  tiktool: {
+    apiKey: 'YOUR_API_KEY' // Get free key → https://tik.tools
+  }
+})
+```
+
+Or via environment variable (recommended for production):
+
+```env
+TIKTOOL_API_KEY=your_api_key
+```
+
+### 3. Use
+
+```vue
+<script setup>
+const { messages, viewers, gifts, connected, error } = useTikTokLive('username')
+</script>
+```
+
+No imports needed — `useTikTokLive` is auto-imported by the module.
+
+---
+
+## SSR & Client-Side
+
+This composable uses **WebSocket** which only runs in the browser. It's designed to work correctly in both SSR and CSR modes:
+
+| Mode | Behavior |
+|------|----------|
+| **SSR** (`ssr: true`) | Server renders initial empty state. WebSocket connects on client hydration via `onMounted`. |
+| **SPA** (`ssr: false`) | WebSocket connects immediately on mount. |
+| **Client-only component** | Wrap in `<ClientOnly>` if you want to avoid SSR flash of empty state. |
+
+```vue
+<!-- Option 1: Works out of the box (SSR-safe) -->
+<script setup>
+const { messages, connected } = useTikTokLive('gbnews')
+</script>
+
+<!-- Option 2: Client-only wrapper (avoids empty state flash) -->
+<ClientOnly>
+  <TikTokChat username="gbnews" />
+</ClientOnly>
+```
+
+---
+
+## API Reference
+
+### `useTikTokLive(uniqueId, options?)`
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `uniqueId` | `string` | — | TikTok username (with or without `@`) |
+| `options.apiKey` | `string` | from config | Override the module-level API key |
+| `options.autoConnect` | `boolean` | `true` | Connect on mount |
+
+### Reactive Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `Ref<boolean>` | WebSocket connection state |
+| `viewers` | `Ref<number>` | Current viewer count |
+| `messages` | `Ref<TikTokEvent[]>` | Chat messages (last 100) |
+| `gifts` | `Ref<TikTokEvent[]>` | Gift events (last 50) |
+| `allEvents` | `Ref<TikTokEvent[]>` | All events (last 200) |
+| `eventCount` | `Ref<number>` | Total events received |
+| `error` | `Ref<string \| null>` | Last error message |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Manually connect (if `autoConnect: false`) |
+| `disconnect()` | Close the connection |
+| `on(event, handler)` | Register a custom event handler |
+
+---
+
+## Events
+
+```vue
+<script setup>
+const tiktok = useTikTokLive('gbnews')
+
+tiktok.on('chat', (data) => {
+  // data.user.uniqueId, data.comment
+})
+
+tiktok.on('gift', (data) => {
+  // data.user.uniqueId, data.giftName, data.diamondCount
+})
+
+tiktok.on('like', (data) => {
+  // data.user.uniqueId, data.likeCount
+})
+
+tiktok.on('follow', (data) => {
+  // data.user.uniqueId
+})
+
+tiktok.on('roomUserSeq', (data) => {
+  // data.viewerCount
+})
+</script>
+```
+
+| Event | Key Fields |
+|-------|-----------|
+| `chat` | `user.uniqueId`, `comment` |
+| `gift` | `user.uniqueId`, `giftName`, `diamondCount` |
+| `like` | `user.uniqueId`, `likeCount` |
+| `follow` | `user.uniqueId` |
+| `member` | `user.uniqueId` (viewer joined) |
+| `roomUserSeq` | `viewerCount` |
+| `battle` | `type`, `teams`, `scores` |
+
+---
+
+## Full Example
+
+```vue
+<script setup>
+const username = ref('gbnews')
+const tiktok = useTikTokLive(username.value)
+
+const topGifters = computed(() => {
+  const map = new Map()
+  for (const g of tiktok.gifts.value) {
+    const user = g.data?.user?.uniqueId
+    const diamonds = g.data?.diamondCount || 0
+    map.set(user, (map.get(user) || 0) + diamonds)
+  }
+  return [...map.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5)
+})
+</script>
+
+<template>
+  <div v-if="tiktok.error.value" class="error">{{ tiktok.error.value }}</div>
+
+  <div v-else-if="!tiktok.connected.value">Connecting to @{{ username }}...</div>
+
+  <div v-else>
+    <p>✅ Connected — 👀 {{ tiktok.viewers.value }} viewers — {{ tiktok.eventCount.value }} events</p>
+
+    <h3>💬 Chat</h3>
+    <div v-for="msg in tiktok.messages.value" :key="msg.data?.msgId">
+      <b>{{ msg.data?.user?.uniqueId }}:</b> {{ msg.data?.comment }}
+    </div>
+
+    <h3>🏆 Top Gifters</h3>
+    <div v-for="([name, diamonds], i) in topGifters" :key="name">
+      {{ i + 1 }}. @{{ name }} — {{ diamonds }} 💎
+    </div>
+  </div>
+</template>
+```
+
+---
+
+## Other SDKs
+
+| Platform | Package | Install |
+|----------|---------|---------|
+| **Node.js / TypeScript** | [tiktok-live-api](https://www.npmjs.com/package/tiktok-live-api) | `npm i tiktok-live-api` |
+| **Python** | [tiktok-live-api](https://pypi.org/project/tiktok-live-api/) | `pip install tiktok-live-api` |
+| **Any language** | [WebSocket API](https://tik.tools/docs) | `wss://api.tik.tools` |
+
+## Links
+
+- 🌐 [tik.tools](https://tik.tools) — Dashboard & API keys
+- 📖 [Documentation](https://tik.tools/docs)
+- 🎙️ [AI Live Captions](https://tik.tools/captions)
+- 💬 [Discord](https://discord.gg/y8TwuFBAmD)
+
+## License
+
+MIT — [tik.tools](https://tik.tools)

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,13 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /**
+     * Your TikTool API key. Get one free at https://tik.tools
+     * Can also be set via TIKTOOL_API_KEY environment variable.
+     */
+    apiKey?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,13 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /**
+     * Your TikTool API key. Get one free at https://tik.tools
+     * Can also be set via TIKTOOL_API_KEY environment variable.
+     */
+    apiKey?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "tiktok-live-nuxt",
+  "configKey": "tiktool",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,24 @@
+import { defineNuxtModule, createResolver, addImportsDir } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "tiktok-live-nuxt",
+    configKey: "tiktool",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    apiKey: ""
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const apiKey = options.apiKey || process.env.TIKTOOL_API_KEY || "";
+    nuxt.options.runtimeConfig.public.tiktool = {
+      apiKey
+    };
+    addImportsDir(resolver.resolve("runtime/composables"));
+  }
+});
+
+export { module as default };

package/dist/runtime/composables/useTikTokLive.d.ts

@@ -0,0 +1,56 @@
+import { type Ref } from 'vue';
+interface TikTokEvent {
+    event: string;
+    data: Record<string, any>;
+}
+interface UseTikTokLiveOptions {
+    /** Override the API key from module config */
+    apiKey?: string;
+    /** Auto-connect on mount (default: true) */
+    autoConnect?: boolean;
+    /** Events to listen for (default: all) */
+    events?: string[];
+}
+interface UseTikTokLiveReturn {
+    /** Whether the WebSocket is connected */
+    connected: Ref<boolean>;
+    /** Current viewer count */
+    viewers: Ref<number>;
+    /** Recent chat messages (last 100) */
+    messages: Ref<TikTokEvent[]>;
+    /** Recent gift events (last 50) */
+    gifts: Ref<TikTokEvent[]>;
+    /** All events (last 200) */
+    allEvents: Ref<TikTokEvent[]>;
+    /** Total events received */
+    eventCount: Ref<number>;
+    /** Last error */
+    error: Ref<string | null>;
+    /** Connect to the stream */
+    connect: () => void;
+    /** Disconnect from the stream */
+    disconnect: () => void;
+    /** Register a custom event handler */
+    on: (event: string, handler: (data: any) => void) => void;
+}
+/**
+ * Composable to connect to a TikTok LIVE stream and receive real-time events.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { messages, viewers, gifts, connected } = useTikTokLive('gbnews')
+ * </script>
+ *
+ * <template>
+ *   <div v-if="connected">
+ *     <p>👀 {{ viewers }} viewers</p>
+ *     <div v-for="msg in messages" :key="msg.data?.msgId">
+ *       {{ msg.data?.user?.uniqueId }}: {{ msg.data?.comment }}
+ *     </div>
+ *   </div>
+ * </template>
+ * ```
+ */
+export declare function useTikTokLive(uniqueId: string, options?: UseTikTokLiveOptions): UseTikTokLiveReturn;
+export {};

package/dist/runtime/composables/useTikTokLive.js

@@ -0,0 +1,112 @@
+import { ref, onMounted, onUnmounted } from "vue";
+import { useRuntimeConfig } from "#imports";
+export function useTikTokLive(uniqueId, options = {}) {
+  const config = useRuntimeConfig();
+  const apiKey = options.apiKey || config.public.tiktool?.apiKey || "";
+  const connected = ref(false);
+  const viewers = ref(0);
+  const messages = ref([]);
+  const gifts = ref([]);
+  const allEvents = ref([]);
+  const eventCount = ref(0);
+  const error = ref(null);
+  let ws = null;
+  const customHandlers = /* @__PURE__ */ new Map();
+  function on(event, handler) {
+    if (!customHandlers.has(event)) {
+      customHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    customHandlers.get(event).add(handler);
+  }
+  function emitCustom(event, data) {
+    const handlers = customHandlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(data);
+        } catch (e) {
+          console.error(e);
+        }
+      }
+    }
+  }
+  function connect() {
+    if (ws) return;
+    if (!apiKey) {
+      error.value = "No API key. Set it in nuxt.config.ts under tiktool.apiKey or via TIKTOOL_API_KEY env var.";
+      console.error("[TikTool]", error.value);
+      return;
+    }
+    const cleanId = uniqueId.replace(/^@/, "");
+    const url = `wss://api.tik.tools?uniqueId=${cleanId}&apiKey=${apiKey}`;
+    try {
+      ws = new WebSocket(url);
+    } catch (e) {
+      error.value = e.message;
+      return;
+    }
+    ws.onopen = () => {
+      connected.value = true;
+      error.value = null;
+      emitCustom("connected", { uniqueId: cleanId });
+    };
+    ws.onmessage = (evt) => {
+      try {
+        const event = JSON.parse(evt.data);
+        eventCount.value++;
+        const eventType = event.event || "unknown";
+        const data = event.data || event;
+        allEvents.value = [event, ...allEvents.value].slice(0, 200);
+        switch (eventType) {
+          case "chat":
+            messages.value = [event, ...messages.value].slice(0, 100);
+            break;
+          case "gift":
+            gifts.value = [event, ...gifts.value].slice(0, 50);
+            break;
+          case "roomUserSeq":
+            viewers.value = data.viewerCount || 0;
+            break;
+        }
+        emitCustom("event", event);
+        emitCustom(eventType, data);
+      } catch {
+      }
+    };
+    ws.onclose = () => {
+      connected.value = false;
+      ws = null;
+      emitCustom("disconnected", { uniqueId: cleanId });
+    };
+    ws.onerror = (e) => {
+      error.value = "WebSocket error";
+      emitCustom("error", { error: "WebSocket error" });
+    };
+  }
+  function disconnect() {
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+    connected.value = false;
+  }
+  const autoConnect = options.autoConnect !== false;
+  onMounted(() => {
+    if (autoConnect) connect();
+  });
+  onUnmounted(() => {
+    disconnect();
+  });
+  return {
+    connected,
+    viewers,
+    messages,
+    gifts,
+    allEvents,
+    eventCount,
+    error,
+    connect,
+    disconnect,
+    on
+  };
+}

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/logo.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_2" data-name="Layer 2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 90.68 90.68">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: url(#linear-gradient);
+      }
+    </style>
+    <linearGradient id="linear-gradient" x1="49.6" y1="49.98" x2="82.57" y2="85.91" gradientUnits="userSpaceOnUse">
+      <stop offset=".1" stop-color="#fff"/>
+      <stop offset=".98" stop-color="#bcbec0"/>
+    </linearGradient>
+  </defs>
+  <g id="Layer_1-2" data-name="Layer 1">
+    <path class="cls-1" d="M70.93,0H19.76C8.85,0,0,8.85,0,19.76v51.17c0,10.91,8.85,19.76,19.76,19.76h26.81c1.8,0,3.52-.71,4.79-1.98l37.6-37.6c1.11-1.11,1.73-2.61,1.73-4.18v-27.17c0-10.91-8.85-19.76-19.76-19.76ZM73.65,32.95c0,1.64-1.33,2.96-2.96,2.96h-13.42c-1.64,0-2.96,1.33-2.96,2.96v23.97c0,.5-.2.99-.56,1.34l-8.98,8.98c-.32.32-.75.5-1.2.5h-4.25c-1.64,0-2.96-1.33-2.96-2.96v-31.82c0-1.64-1.33-2.96-2.96-2.96h-13.41c-1.64,0-2.96-1.33-2.96-2.96v-12.95c0-1.64,1.33-2.96,2.96-2.96h50.69c1.64,0,2.96,1.33,2.96,2.96v12.95Z"/>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "tiktok-live-nuxt",
+  "version": "1.0.0",
+  "description": "Nuxt module for TikTok LIVE API — real-time chat, gifts, viewers, battles, and AI captions",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.mts",
+  "files": [
+    "dist",
+    "banner.png",
+    "logo.svg"
+  ],
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "tiktok",
+    "tiktok-live",
+    "tiktok-api",
+    "websocket",
+    "live-streaming",
+    "real-time",
+    "chat",
+    "gifts",
+    "captions",
+    "speech-to-text"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tiktool/tiktok-live-nuxt"
+  },
+  "homepage": "https://tik.tools",
+  "bugs": {
+    "url": "https://github.com/tiktool/tiktok-live-nuxt/issues"
+  },
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.16.0",
+    "tiktok-live-api": "^1.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^0.8.0",
+    "@nuxt/schema": "^3.16.0",
+    "nuxt": "^3.16.0",
+    "typescript": "^5.5.0"
+  }
+}