lightstream-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LightStream
+
+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/QUICKSTART.md

@@ -0,0 +1,150 @@
+# LightStream SDK Quickstart Guide
+
+This guide walks you through setting up and running your first LightStream integration in 5 minutes.
+
+---
+
+## Prerequisites
+
+1. Node.js 18+, Bun, or Deno installed.
+2. A LightStream API Key.
+3. LightStream Gateway Base URL: `https://gateway.lightstream.lat`
+
+---
+
+## 1. Project Setup
+
+Create a new directory and install dependencies:
+
+```bash
+mkdir my-lightstream-bot
+cd my-lightstream-bot
+npm init -y
+npm install lightstream-sdk
+```
+
+---
+
+## 2. Hello World: Realtime Chat Listener
+
+Create `bot.js` (or `bot.ts`):
+
+```javascript
+import { createLightStreamClient } from 'lightstream-sdk';
+
+const client = createLightStreamClient({
+  baseUrl: 'https://gateway.lightstream.lat',
+  wsUrl: 'wss://gateway.lightstream.lat/ws',
+  apiKey: process.env.LIGHTSTREAM_API_KEY || 'YOUR_API_KEY'
+});
+
+client.stream.on('status', (status) => {
+  console.log(`[Status] ${status}`);
+});
+
+client.stream.on('connected', (evt) => {
+  console.log(`[Connected] Live on ${evt.platform} - ${evt.channel} (${evt.viewerCount} viewers)`);
+});
+
+client.stream.on('stream:offline', (evt) => {
+  console.log(`[Offline] Channel ${evt.channel} is not streaming right now.`);
+});
+
+client.stream.on('chat', (msg) => {
+  console.log(`💬 ${msg.user.displayName}: ${msg.content}`);
+});
+
+client.stream.on('gift', (gift) => {
+  console.log(`🎁 ${gift.user.displayName} sent ${gift.gift.name} x${gift.gift.repeatCount}`);
+});
+
+// Connect to TikTok, Kick, or Twitch
+client.stream.connect('kick', 'xqc');
+```
+
+Run the bot:
+
+```bash
+node bot.js
+```
+
+---
+
+## 3. Frontend Integration (Next.js / React)
+
+When building client-facing web applications or OBS overlays, **never** bundle your master API key in the client!
+
+### Step A: Backend API Route (`/api/get-stream-token`)
+```typescript
+import { createLightStreamClient } from 'lightstream-sdk'
+
+const serverClient = createLightStreamClient({
+  baseUrl: 'https://gateway.lightstream.lat',
+  apiKey: process.env.LIGHTSTREAM_MASTER_KEY!
+})
+
+export async function POST(req: Request) {
+  const { channel, platform } = await req.json()
+  
+  // Issue a 5-minute scoped token for this viewer/channel only
+  const { token, expiresAt } = await serverClient.rest.issueToken({
+    allowedPlatforms: [platform],
+    allowedChannels: [channel],
+    expireAfterSeconds: 300,
+    maxWebSockets: 1
+  })
+
+  return Response.json({ token, expiresAt })
+}
+```
+
+### Step B: React Component
+```tsx
+'use client'
+import { useEffect, useState } from 'react'
+import { createLightStreamClient, type ConnectionStatus } from 'lightstream-sdk'
+
+export function LiveChatWidget({ platform, channel }) {
+  const [messages, setMessages] = useState<string[]>([])
+  const [status, setStatus] = useState<ConnectionStatus>('idle')
+
+  useEffect(() => {
+    let client: any
+
+    async function init() {
+      // 1. Fetch ephemeral token from our secure server route
+      const res = await fetch('/api/get-stream-token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel })
+      })
+      const { token } = await res.json()
+
+      // 2. Connect client with ephemeral token
+      client = createLightStreamClient({ token })
+
+      client.stream.on('status', setStatus)
+      client.stream.on('chat', (msg) => {
+        setMessages((prev) => [...prev.slice(-49), `${msg.user.displayName}: ${msg.content}`])
+      })
+
+      await client.stream.connect(platform, channel)
+    }
+
+    init()
+
+    return () => {
+      client?.stream.disconnect()
+    }
+  }, [platform, channel])
+
+  return (
+    <div className="chat-container">
+      <div className="badge">Status: {status}</div>
+      <ul>
+        {messages.map((m, i) => <li key={i}>{m}</li>)}
+      </ul>
+    </div>
+  )
+}
+```

package/README.md

@@ -0,0 +1,178 @@
+# lightstream-sdk
+
+Official TypeScript & JavaScript SDK for the **LightStream Developer Platform**.
+
+Interact with **TikTok LIVE**, **Kick**, and **Twitch** using a single, unified client. LightStream provides real-time WebSockets, verified stream lifecycle management, rich metadata APIs, leaderboards, and unified cross-platform chat moderation.
+
+---
+
+## ✨ Features
+
+- **🌐 Unified Real-time WebSockets**: Connect to TikTok, Kick, and Twitch with one common interface and protocol.
+- **🛡️ Zero False Positives**: Connection state is strictly backed by upstream verification. The client emits `stream:offline` with `STREAMER_OFFLINE` when the channel is not live, guaranteeing that `connected` only fires when live data is flowing.
+- **⚡ Fast REST APIs**:
+  - **Bulk Live Check**: Check live status and viewer counts for up to 100 streamers in a single call.
+  - **Playback & Stream Info**: Retrieve HLS (`.m3u8`) playback streams and stream titles.
+  - **Monetization & Earnings**: Track gifts, bits, kicks, and estimated USD earnings.
+  - **Rankings & Leaderboards**: Query hourly, daily, and weekly creator leaderboards.
+  - **Cross-Platform Moderation**: Mute, ban, delete chat messages, and toggle comments across platforms.
+- **🔑 Scoped Ephemeral Tokens**: Generate secure, short-lived JWTs to embed directly in frontend applications or widgets without leaking master API keys.
+- **🔄 Resilient State Machine**: Built-in heartbeat (`ping`/`pong`), auto-reconnection with exponential backoff, and strict lifecycle states.
+- **📦 Isomorphic**: Works out of the box in Node.js, Bun, Deno, and modern web browsers.
+
+---
+
+## 🚀 Installation
+
+```bash
+# Using npm
+npm install lightstream-sdk
+
+# Using pnpm
+pnpm add lightstream-sdk
+
+# Using bun
+bun add lightstream-sdk
+```
+
+*(If consuming as a local package, you can also link it via `"file:../lightstream-sdk"`)*
+
+---
+
+## ⚡ Quick Start
+
+### 1. Connecting to a Live Stream (WebSocket)
+
+```typescript
+import { createLightStreamClient } from 'lightstream-sdk'
+
+const client = createLightStreamClient({
+  baseUrl: 'https://gateway.lightstream.lat',
+  wsUrl: 'wss://gateway.lightstream.lat/ws',
+  apiKey: 'your_api_key_here' // Or use ephemeral token: token: 'eyJ...'
+})
+
+// Track connection state machine
+client.stream.on('status', (status) => {
+  console.log('Connection status:', status)
+  // 'idle' | 'connecting' | 'connected' | 'offline' | 'reconnecting' | 'disconnected' | 'error'
+})
+
+// Guaranteed: Only fires when the channel is 100% verified LIVE
+client.stream.on('connected', (event) => {
+  console.log(`✅ Connected to ${event.platform} channel: ${event.channel}`)
+  console.log(`Viewers: ${event.viewerCount}, Title: ${event.title}`)
+})
+
+// Streamer is not streaming (Zero false positives)
+client.stream.on('stream:offline', (event) => {
+  console.warn(`⚠️ Channel ${event.channel} is currently offline. Code: ${event.code}`)
+})
+
+// Real-time Chat
+client.stream.on('chat', (msg) => {
+  console.log(`[${msg.platform}] ${msg.user.displayName}: ${msg.content}`)
+})
+
+// Real-time Gifts / Monetization
+client.stream.on('gift', (gift) => {
+  console.log(`🎁 ${gift.user.displayName} sent ${gift.gift.name} x${gift.gift.repeatCount} (${gift.gift.value} diamonds/coins)`)
+})
+
+// Handle errors
+client.stream.on('error', (err) => {
+  console.error(`❌ Error [${err.code}]: ${err.message}`)
+})
+
+// Connect to a channel
+await client.stream.connect('twitch', 'ninja')
+```
+
+---
+
+## 🛠️ REST API Usage
+
+### Bulk Check Live Status
+
+Check the status of multiple streamers simultaneously across different platforms:
+
+```typescript
+const results = await client.rest.bulkCheckStreams([
+  { platform: 'tiktok', channel: 'charlidamelio' },
+  { platform: 'kick', channel: 'xqc' },
+  { platform: 'twitch', channel: 'shroud' },
+])
+
+for (const stream of results) {
+  console.log(`${stream.platform}/@${stream.channel}: ${stream.isLive ? '🔴 LIVE' : '⚪ OFFLINE'} (${stream.viewerCount} viewers)`)
+}
+```
+
+### Issue Scoped Ephemeral Tokens (for Frontend / Overlays)
+
+Do not expose your master API key in client-side code! Issue a short-lived token instead:
+
+```typescript
+const { token, expiresAt } = await client.rest.issueToken({
+  allowedPlatforms: ['kick', 'twitch'],
+  allowedChannels: ['my_channel'],
+  expireAfterSeconds: 300, // 5 minutes
+  maxWebSockets: 2,
+})
+
+// The frontend can now safely connect:
+// const client = createLightStreamClient({ token })
+```
+
+### Unified Chat Moderation
+
+Perform moderation actions regardless of the platform:
+
+```typescript
+// Mute user for 60 seconds
+await client.rest.moderation.mute('tiktok', 'my_channel', 'spammer_username', 60)
+
+// Ban user
+await client.rest.moderation.ban('kick', 'my_channel', 'bad_actor', 'Violated rules')
+
+// Delete a message
+await client.rest.moderation.deleteMessage('twitch', 'my_channel', 'msg-uuid-123')
+
+// Disable chat comments
+await client.rest.moderation.toggleComments('tiktok', 'my_channel', false)
+```
+
+### Rankings & Leaderboards
+
+```typescript
+// Top streamers on TikTok today
+const topDaily = await client.rest.getLeaderboard('tiktok', 'daily', 20)
+console.log('Top Streamer:', topDaily[0])
+
+// Search streamer ranking
+const rank = await client.rest.searchRankings('my_streamer', 'tiktok', 'daily')
+console.log(`Position: #${rank.rank} with ${rank.score} points`)
+```
+
+---
+
+## 📖 Canonical Error Codes
+
+The SDK and Gateway use canonical, strongly typed error codes:
+
+| Code | Meaning | Action / Handling |
+| :--- | :--- | :--- |
+| `STREAMER_OFFLINE` | The channel exists but is not broadcasting live. | Display offline banner in UI. Do not expect stream data. |
+| `ROOM_NOT_FOUND` | The requested username/channel was not found. | Check spelling or channel username. |
+| `AUTHENTICATION_FAILED` | Invalid API key or expired token. | Refresh credentials. |
+| `FORBIDDEN_CHANNEL` | The ephemeral token is not authorized for this channel. | Generate a token with correct `allowedChannels`. |
+| `RATE_LIMITED` | Too many requests or concurrent connections. | Backoff and retry later. |
+| `UPSTREAM_ERROR` | Error from TikTok, Kick, or Twitch API. | Client will auto-reconnect if retryable. |
+| `TIMEOUT` | Connection attempt timed out. | Retry with exponential backoff. |
+| `INTERNAL_ERROR` | Unhandled gateway server error. | Contact support or check gateway status. |
+
+---
+
+## 📄 License
+
+MIT © 2026 LightStream

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export declare const LIGHTSTREAM_ERROR_CODES: {
+    readonly STREAMER_OFFLINE: "STREAMER_OFFLINE";
+    readonly ROOM_NOT_FOUND: "ROOM_NOT_FOUND";
+    readonly AUTHENTICATION_FAILED: "AUTHENTICATION_FAILED";
+    readonly FORBIDDEN_CHANNEL: "FORBIDDEN_CHANNEL";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly UPSTREAM_ERROR: "UPSTREAM_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type LightStreamErrorCode = keyof typeof LIGHTSTREAM_ERROR_CODES;
+export interface LightStreamErrorPayload {
+    code: LightStreamErrorCode;
+    message: string;
+    details?: unknown;
+    retryable?: boolean;
+    timestamp: string;
+}
+export declare class LightStreamError extends Error {
+    readonly code: LightStreamErrorCode;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    readonly timestamp: string;
+    constructor(payload: LightStreamErrorPayload);
+    toJSON(): LightStreamErrorPayload;
+}