lightstream-sdk 1.0.0

package/src/stream-client.ts

@@ -0,0 +1,250 @@
+// src/stream-client.ts
+// Real-time Raw WebSocket client for LightStream Gateway.
+
+import { LIGHTSTREAM_ERROR_CODES, type LightStreamErrorCode } from './errors.js'
+import type {
+  ClientOptions,
+  ConnectionStatus,
+  LightStreamEventMap,
+  Platform,
+  StreamConnectedEvent,
+  StreamOfflineEvent,
+  ConnectionErrorEvent,
+  ChatMessageEvent,
+  GiftEvent,
+} from './types.js'
+
+export class LightStreamStreamClient {
+  private ws: any = null
+  private _status: ConnectionStatus = 'idle'
+  private listeners: Map<string, Set<Function>> = new Map()
+  private pingTimer: any = null
+  private reconnectTimer: any = null
+  private reconnectAttempts = 0
+  private currentPlatform: Platform | null = null
+  private currentChannel: string | null = null
+
+  constructor(private options: ClientOptions) {}
+
+  get status(): ConnectionStatus {
+    return this._status
+  }
+
+  private setStatus(newStatus: ConnectionStatus) {
+    if (this._status === newStatus) return
+    this._status = newStatus
+    this.emit('status', newStatus)
+  }
+
+  connect(platform: Platform, channel: string): Promise<void> {
+    this.currentPlatform = platform
+    this.currentChannel = channel.trim().toLowerCase()
+    return this.initSocket()
+  }
+
+  private async initSocket(): Promise<void> {
+    if (!this.currentPlatform || !this.currentChannel) {
+      throw new Error('Platform and channel must be specified to connect')
+    }
+
+    this.cleanupSocket()
+    this.setStatus('connecting')
+
+    const baseWs = (this.options.wsUrl || 'wss://gateway.lightstream.lat/ws').replace(/\/+$/, '')
+    const url = new URL(baseWs)
+    url.searchParams.set('platform', this.currentPlatform)
+    url.searchParams.set('channel', this.currentChannel)
+
+    if (this.options.token) {
+      url.searchParams.set('token', this.options.token)
+    } else if (this.options.apiKey) {
+      url.searchParams.set('apiKey', this.options.apiKey)
+    }
+
+    const SocketCtor = typeof WebSocket !== 'undefined'
+      ? WebSocket
+      : ((await import('ws')).default as any)
+
+    return new Promise((resolve) => {
+      try {
+        const socket = new SocketCtor(url.toString())
+        this.ws = socket
+
+        socket.onopen = () => {
+          this.reconnectAttempts = 0
+          this.startHeartbeat()
+          resolve()
+        }
+
+        socket.onmessage = (event: any) => {
+          this.handleIncoming(typeof event.data === 'string' ? event.data : event.data?.toString())
+        }
+
+        socket.onerror = (err: any) => {
+          this.handleFailure(LIGHTSTREAM_ERROR_CODES.UPSTREAM_ERROR, err?.message || 'WebSocket connection error')
+        }
+
+        socket.onclose = () => {
+          this.cleanupSocket()
+          if (this._status !== 'disconnected' && this._status !== 'offline') {
+            this.setStatus('disconnected')
+            this.emit('disconnected', 'Socket connection closed')
+            this.scheduleReconnect()
+          }
+        }
+      } catch (err: any) {
+        this.handleFailure(LIGHTSTREAM_ERROR_CODES.INTERNAL_ERROR, err.message)
+        resolve()
+      }
+    })
+  }
+
+  private handleIncoming(rawData?: string) {
+    if (!rawData) return
+    let parsed: any
+    try {
+      parsed = JSON.parse(rawData)
+    } catch {
+      return
+    }
+
+    if (parsed.type === 'pong') return
+
+    if (parsed.type === 'connected') {
+      this.setStatus('connected')
+      const evt: StreamConnectedEvent = {
+        channel: parsed.channel || this.currentChannel!,
+        platform: parsed.platform || this.currentPlatform!,
+        isLive: true,
+        title: parsed.title,
+        viewerCount: parsed.viewerCount,
+        startedAt: parsed.startedAt,
+      }
+      this.emit('connected', evt)
+      return
+    }
+
+    if (parsed.type === 'offline') {
+      this.setStatus('offline')
+      const offlineEvt: StreamOfflineEvent = {
+        channel: parsed.channel || this.currentChannel!,
+        platform: parsed.platform || this.currentPlatform!,
+        isLive: false,
+        code: (parsed.code as LightStreamErrorCode) || LIGHTSTREAM_ERROR_CODES.STREAMER_OFFLINE,
+        message: parsed.message || 'The streamer is currently offline',
+      }
+      this.emit('stream:offline', offlineEvt)
+      return
+    }
+
+    if (parsed.type === 'error') {
+      this.handleFailure(parsed.code || LIGHTSTREAM_ERROR_CODES.INTERNAL_ERROR, parsed.message)
+      return
+    }
+
+    if (parsed.event === 'chat' || parsed.type === 'chat') {
+      this.emit('chat', parsed.data as ChatMessageEvent)
+      return
+    }
+
+    if (parsed.event === 'gift' || parsed.type === 'gift') {
+      this.emit('gift', parsed.data as GiftEvent)
+      return
+    }
+
+    this.emit('raw', parsed)
+  }
+
+  private handleFailure(code: LightStreamErrorCode, message: string) {
+    this.setStatus('error')
+    const errPayload: ConnectionErrorEvent = {
+      channel: this.currentChannel || undefined,
+      platform: this.currentPlatform || undefined,
+      code,
+      message,
+      retryable: code !== LIGHTSTREAM_ERROR_CODES.FORBIDDEN_CHANNEL && code !== LIGHTSTREAM_ERROR_CODES.AUTHENTICATION_FAILED,
+    }
+    this.emit('error', errPayload)
+    if (errPayload.retryable) {
+      this.scheduleReconnect()
+    }
+  }
+
+  private scheduleReconnect() {
+    if (this.options.autoReconnect === false) return
+    const maxAttempts = this.options.maxReconnectAttempts ?? 5
+    if (this.reconnectAttempts >= maxAttempts) return
+
+    this.reconnectAttempts++
+    this.setStatus('reconnecting')
+
+    const baseDelay = this.options.reconnectIntervalMs ?? 2000
+    const delay = Math.min(baseDelay * Math.pow(1.5, this.reconnectAttempts - 1), 30000)
+
+    this.reconnectTimer = setTimeout(() => {
+      this.initSocket().catch(() => {})
+    }, delay)
+  }
+
+  private startHeartbeat() {
+    const interval = this.options.pingIntervalMs ?? 30000
+    this.pingTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === 1) {
+        this.ws.send(JSON.stringify({ type: 'ping' }))
+      }
+    }, interval)
+  }
+
+  private cleanupSocket() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer)
+      this.pingTimer = null
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    if (this.ws) {
+      try {
+        this.ws.onclose = null
+        this.ws.onerror = null
+        this.ws.close()
+      } catch {}
+      this.ws = null
+    }
+  }
+
+  disconnect(): void {
+    this.cleanupSocket()
+    this.setStatus('disconnected')
+    this.currentChannel = null
+    this.currentPlatform = null
+  }
+
+  on<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set())
+    }
+    this.listeners.get(event)!.add(handler)
+  }
+
+  off<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void {
+    const handlers = this.listeners.get(event)
+    if (handlers) {
+      handlers.delete(handler)
+    }
+  }
+
+  private emit(event: string, ...args: any[]): void {
+    const handlers = this.listeners.get(event)
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(...args)
+        } catch (e) {
+          console.error(`Error in LightStream listener [${event}]:`, e)
+        }
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+// src/types.ts
+// Domain Types and Contracts for LightStream SDK.
+
+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
+}