lightstream-sdk 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+import type { LightStreamErrorCode } from './errors.js';
+export type Platform = 'tiktok' | 'kick' | 'twitch';
+export type Timeframe = 'hourly' | 'daily' | 'weekly' | 'all';
+export type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'offline' | 'reconnecting' | 'disconnected' | 'error';
+export interface ClientOptions {
+    baseUrl?: string;
+    wsUrl?: string;
+    apiKey?: string;
+    token?: string;
+    jwtKey?: string;
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    reconnectIntervalMs?: number;
+    pingIntervalMs?: number;
+}
+export interface StreamConnectedEvent {
+    channel: string;
+    platform: Platform;
+    isLive: true;
+    title?: string;
+    viewerCount?: number;
+    startedAt?: string;
+}
+export interface StreamOfflineEvent {
+    channel: string;
+    platform: Platform;
+    isLive: false;
+    code: LightStreamErrorCode;
+    message: string;
+}
+export interface ConnectionErrorEvent {
+    channel?: string;
+    platform?: Platform;
+    code: LightStreamErrorCode;
+    message: string;
+    details?: unknown;
+    retryable: boolean;
+}
+export interface ChatMessageEvent {
+    id: string;
+    platform: Platform;
+    channel: string;
+    user: {
+        id: string;
+        username: string;
+        displayName: string;
+        avatar?: string;
+        badges?: string[];
+    };
+    content: string;
+    timestamp: number;
+    emotes?: Array<{
+        name: string;
+        url: string;
+    }>;
+}
+export interface GiftEvent {
+    id: string;
+    platform: Platform;
+    channel: string;
+    user: {
+        id: string;
+        username: string;
+        displayName: string;
+        avatar?: string;
+    };
+    gift: {
+        id: string;
+        name: string;
+        value: number;
+        repeatCount: number;
+        repeatEnd: boolean;
+        iconUrl?: string;
+    };
+    timestamp: number;
+}
+export interface LightStreamEventMap {
+    status: (status: ConnectionStatus) => void;
+    connected: (event: StreamConnectedEvent) => void;
+    'stream:offline': (event: StreamOfflineEvent) => void;
+    error: (event: ConnectionErrorEvent) => void;
+    disconnected: (reason: string) => void;
+    chat: (event: ChatMessageEvent) => void;
+    gift: (event: GiftEvent) => void;
+    raw: (data: unknown) => void;
+}

package/examples/basic-connection.ts

@@ -0,0 +1,15 @@
+// examples/basic-connection.ts
+import { createLightStreamClient } from '../src/index.js'
+
+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', (s) => console.log('Status:', s))
+client.stream.on('connected', (e) => console.log('Stream live:', e))
+client.stream.on('stream:offline', (e) => console.log('Stream offline:', e))
+client.stream.on('chat', (c) => console.log(`[${c.platform}] ${c.user.displayName}: ${c.content}`))
+
+await client.stream.connect('twitch', 'shroud')

package/examples/bot-moderation.ts

@@ -0,0 +1,27 @@
+// examples/bot-moderation.ts
+import { createLightStreamClient, type ChatMessageEvent } from '../src/index.js'
+
+const BANNED_WORDS = ['spamword1', 'badlink.com', 'scam']
+
+const client = createLightStreamClient({
+  baseUrl: 'https://gateway.lightstream.lat',
+  wsUrl: 'wss://gateway.lightstream.lat/ws',
+  apiKey: process.env.LIGHTSTREAM_API_KEY!,
+})
+
+client.stream.on('chat', async (msg: ChatMessageEvent) => {
+  const hasBadWord = BANNED_WORDS.some((word) => msg.content.toLowerCase().includes(word))
+
+  if (hasBadWord) {
+    console.log(`🚨 Moderating message from ${msg.user.username} in ${msg.channel}...`)
+
+    // 1. Delete message
+    await client.rest.moderation.deleteMessage(msg.platform, msg.channel, msg.id)
+
+    // 2. Mute user for 5 minutes
+    await client.rest.moderation.mute(msg.platform, msg.channel, msg.user.username, 300)
+    console.log(`User ${msg.user.username} muted for 300s.`)
+  }
+})
+
+await client.stream.connect('kick', 'my_kick_channel')

package/examples/earnings-tracker.ts

@@ -0,0 +1,19 @@
+// examples/earnings-tracker.ts
+import { createLightStreamClient } from '../src/index.js'
+
+const client = createLightStreamClient({
+  baseUrl: 'https://gateway.lightstream.lat',
+  apiKey: process.env.LIGHTSTREAM_API_KEY!,
+})
+
+async function checkEarnings(platform: 'tiktok' | 'kick' | 'twitch', channel: string) {
+  const [streamInfo, earnings] = await Promise.all([
+    client.rest.getRoomStreamInfo(platform, channel),
+    client.rest.getUserEarnings(platform, channel),
+  ])
+
+  console.log('Stream Info:', streamInfo)
+  console.log('Earnings & Diamonds:', earnings)
+}
+
+await checkEarnings('tiktok', 'jesusquesillo')

package/examples/react-use-stream.tsx

@@ -0,0 +1,48 @@
+// examples/react-use-stream.tsx
+import { useEffect, useState, useRef } from 'react'
+import {
+  createLightStreamClient,
+  type ConnectionStatus,
+  type ChatMessageEvent,
+  type GiftEvent,
+  type Platform
+} from '../src/index.js'
+
+export interface UseLightStreamOptions {
+  platform: Platform
+  channel: string
+  token?: string
+  apiKey?: string
+}
+
+export function useLightStream({ platform, channel, token, apiKey }: UseLightStreamOptions) {
+  const [status, setStatus] = useState<ConnectionStatus>('idle')
+  const [isLive, setIsLive] = useState<boolean>(false)
+  const [chatMessages, setChatMessages] = useState<ChatMessageEvent[]>([])
+  const [gifts, setGifts] = useState<GiftEvent[]>([])
+  const clientRef = useRef<any>(null)
+
+  useEffect(() => {
+    const client = createLightStreamClient({
+      baseUrl: 'https://gateway.lightstream.lat',
+      wsUrl: 'wss://gateway.lightstream.lat/ws',
+      token,
+      apiKey,
+    })
+    clientRef.current = client
+
+    client.stream.on('status', setStatus)
+    client.stream.on('connected', () => setIsLive(true))
+    client.stream.on('stream:offline', () => setIsLive(false))
+    client.stream.on('chat', (msg) => setChatMessages((prev) => [...prev.slice(-99), msg]))
+    client.stream.on('gift', (gift) => setGifts((prev) => [...prev.slice(-49), gift]))
+
+    client.stream.connect(platform, channel)
+
+    return () => {
+      client.stream.disconnect()
+    }
+  }, [platform, channel, token, apiKey])
+
+  return { status, isLive, chatMessages, gifts, client: clientRef.current }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "lightstream-sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript/JavaScript SDK for LightStream Gateway (Unified TikTok, Kick, and Twitch Real-time Streaming, REST APIs, and Moderation)",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "QUICKSTART.md",
+    "LICENSE",
+    "examples"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outfile ./dist/index.mjs --target node --external ws && bun build ./src/index.ts --outfile ./dist/index.cjs --target node --format cjs --external ws && bun x tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "lightstream",
+    "tiktok",
+    "kick",
+    "twitch",
+    "livestream",
+    "realtime",
+    "websocket",
+    "moderation",
+    "sdk"
+  ],
+  "author": "LightStream Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LightCode-ctrl/gateway-lightstream.git"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+// src/errors.ts
+// Canonical LightStream Domain Error Taxonomy and helpers.
+
+export const LIGHTSTREAM_ERROR_CODES = {
+  STREAMER_OFFLINE: 'STREAMER_OFFLINE',
+  ROOM_NOT_FOUND: 'ROOM_NOT_FOUND',
+  AUTHENTICATION_FAILED: 'AUTHENTICATION_FAILED',
+  FORBIDDEN_CHANNEL: 'FORBIDDEN_CHANNEL',
+  RATE_LIMITED: 'RATE_LIMITED',
+  UPSTREAM_ERROR: 'UPSTREAM_ERROR',
+  TIMEOUT: 'TIMEOUT',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const
+
+export type LightStreamErrorCode = keyof typeof LIGHTSTREAM_ERROR_CODES
+
+export interface LightStreamErrorPayload {
+  code: LightStreamErrorCode
+  message: string
+  details?: unknown
+  retryable?: boolean
+  timestamp: string
+}
+
+export class LightStreamError extends Error {
+  readonly code: LightStreamErrorCode
+  readonly details?: unknown
+  readonly retryable: boolean
+  readonly timestamp: string
+
+  constructor(payload: LightStreamErrorPayload) {
+    super(payload.message)
+    this.name = 'LightStreamError'
+    this.code = payload.code
+    this.details = payload.details
+    this.retryable = payload.retryable ?? false
+    this.timestamp = payload.timestamp
+  }
+
+  toJSON(): LightStreamErrorPayload {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      retryable: this.retryable,
+      timestamp: this.timestamp,
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// src/index.ts
+// Entrypoint for the official LightStream TypeScript SDK.
+
+import { LightStreamRestClient } from './rest-client.js'
+import { LightStreamStreamClient } from './stream-client.js'
+import type { ClientOptions } from './types.js'
+
+export class LightStreamClient {
+  readonly rest: LightStreamRestClient
+  readonly stream: LightStreamStreamClient
+
+  constructor(options: ClientOptions) {
+    this.rest = new LightStreamRestClient({
+      baseUrl: options.baseUrl || 'https://gateway.lightstream.lat',
+      apiKey: options.apiKey,
+      jwtKey: options.jwtKey || options.token,
+    })
+    this.stream = new LightStreamStreamClient(options)
+  }
+}
+
+export function createLightStreamClient(options: ClientOptions): LightStreamClient {
+  return new LightStreamClient(options)
+}
+
+export * from './types.js'
+export * from './errors.js'
+export * from './rest-client.js'
+export * from './stream-client.js'

package/src/rest-client.ts

@@ -0,0 +1,143 @@
+// src/rest-client.ts
+// Typed HTTP REST client for LightStream Gateway Developer APIs.
+
+import type { Platform, Timeframe } from './types.js'
+
+export interface RestClientConfig {
+  baseUrl: string
+  apiKey?: string
+  jwtKey?: string
+}
+
+export class LightStreamRestClient {
+  constructor(private config: RestClientConfig) {}
+
+  private async fetchJson<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.config.baseUrl.replace(/\/+$/, '')}${path}`
+    const headers = new Headers(options.headers || {})
+    if (!headers.has('Accept')) headers.set('Accept', 'application/json')
+    if (this.config.apiKey) {
+      headers.set('x-api-key', this.config.apiKey)
+    } else if (this.config.jwtKey) {
+      headers.set('Authorization', `Bearer ${this.config.jwtKey}`)
+    }
+
+    const res = await fetch(url, { ...options, headers })
+    const data = await res.json()
+    if (!res.ok) {
+      throw new Error((data as { error?: string })?.error || `HTTP ${res.status}`)
+    }
+    return data as T
+  }
+
+  // Auth & Scoped Ephemeral Tokens
+  async issueToken(options: {
+    expireAfterSeconds?: number
+    allowedPlatforms?: Platform[]
+    allowedChannels?: string[]
+    maxWebSockets?: number
+  }): Promise<{ token: string; expiresAt: number; maxWebSockets: number }> {
+    const res = await this.fetchJson<{ ok: boolean; data: { token: string; expiresAt: number; maxWebSockets: number } }>(
+      '/api/v1/auth/tokens',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(options),
+      },
+    )
+    return res.data
+  }
+
+  // Streams & Rooms
+  async bulkCheckStreams(requests: Array<{ platform: Platform; channel: string }>): Promise<Array<{
+    platform: Platform
+    channel: string
+    isLive: boolean
+    viewerCount: number
+    title?: string
+    cached?: boolean
+  }>> {
+    const res = await this.fetchJson<{ ok: boolean; results: any[] }>('/api/v1/streams/bulk-check', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requests }),
+    })
+    return res.results
+  }
+
+  async getRoomStreamInfo(platform: Platform, channel: string): Promise<Record<string, unknown>> {
+    const res = await this.fetchJson<{ ok: boolean; data: Record<string, unknown> }>(
+      `/api/v1/rooms/${encodeURIComponent(platform)}/${encodeURIComponent(channel)}/stream-info`,
+    )
+    return res.data
+  }
+
+  async getUserEarnings(platform: Platform, channel: string): Promise<Record<string, unknown>> {
+    const res = await this.fetchJson<{ ok: boolean; data: Record<string, unknown> }>(
+      `/api/v1/users/${encodeURIComponent(platform)}/${encodeURIComponent(channel)}/earnings`,
+    )
+    return res.data
+  }
+
+  async getGiftsCatalog(platform: Platform = 'tiktok'): Promise<any[]> {
+    const res = await this.fetchJson<{ ok: boolean; data: any[] }>(
+      `/api/v1/gifts/catalog?platform=${encodeURIComponent(platform)}`,
+    )
+    return res.data
+  }
+
+  // Rankings
+  async getLeaderboard(platform: Platform, timeframe: Timeframe = 'daily', limit = 50): Promise<any[]> {
+    const res = await this.fetchJson<{ ok: boolean; entries: any[] }>(
+      `/api/v1/rankings/leaderboard?platform=${encodeURIComponent(platform)}&timeframe=${encodeURIComponent(timeframe)}&limit=${limit}`,
+    )
+    return res.entries
+  }
+
+  async searchRankings(channel: string, platform: Platform = 'tiktok', timeframe: Timeframe = 'daily'): Promise<any> {
+    const res = await this.fetchJson<{ ok: boolean; data: any }>(
+      `/api/v1/rankings/search?channel=${encodeURIComponent(channel)}&platform=${encodeURIComponent(platform)}&timeframe=${encodeURIComponent(timeframe)}`,
+    )
+    return res.data
+  }
+
+  // Moderation
+  readonly moderation = {
+    mute: (platform: Platform, channel: string, targetUser: string, duration?: number) =>
+      this.fetchJson('/api/v1/moderation/mutes', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, targetUser, duration }),
+      }),
+    unmute: (platform: Platform, channel: string, targetUser: string) =>
+      this.fetchJson('/api/v1/moderation/mutes', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, targetUser }),
+      }),
+    ban: (platform: Platform, channel: string, targetUser: string, reason?: string) =>
+      this.fetchJson('/api/v1/moderation/bans', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, targetUser, reason }),
+      }),
+    unban: (platform: Platform, channel: string, targetUser: string) =>
+      this.fetchJson('/api/v1/moderation/bans', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, targetUser }),
+      }),
+    deleteMessage: (platform: Platform, channel: string, messageId: string) =>
+      this.fetchJson('/api/v1/moderation/messages', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, messageId }),
+      }),
+    toggleComments: (platform: Platform, channel: string, enabled: boolean) =>
+      this.fetchJson('/api/v1/moderation/comments/toggle', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ platform, channel, enabled }),
+      }),
+  }
+}