lightstream-sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,365 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/rest-client.ts
+class LightStreamRestClient {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async fetchJson(path, options = {}) {
+    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?.error || `HTTP ${res.status}`);
+    }
+    return data;
+  }
+  async issueToken(options) {
+    const res = await this.fetchJson("/api/v1/auth/tokens", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    return res.data;
+  }
+  async bulkCheckStreams(requests) {
+    const res = await this.fetchJson("/api/v1/streams/bulk-check", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ requests })
+    });
+    return res.results;
+  }
+  async getRoomStreamInfo(platform, channel) {
+    const res = await this.fetchJson(`/api/v1/rooms/${encodeURIComponent(platform)}/${encodeURIComponent(channel)}/stream-info`);
+    return res.data;
+  }
+  async getUserEarnings(platform, channel) {
+    const res = await this.fetchJson(`/api/v1/users/${encodeURIComponent(platform)}/${encodeURIComponent(channel)}/earnings`);
+    return res.data;
+  }
+  async getGiftsCatalog(platform = "tiktok") {
+    const res = await this.fetchJson(`/api/v1/gifts/catalog?platform=${encodeURIComponent(platform)}`);
+    return res.data;
+  }
+  async getLeaderboard(platform, timeframe = "daily", limit = 50) {
+    const res = await this.fetchJson(`/api/v1/rankings/leaderboard?platform=${encodeURIComponent(platform)}&timeframe=${encodeURIComponent(timeframe)}&limit=${limit}`);
+    return res.entries;
+  }
+  async searchRankings(channel, platform = "tiktok", timeframe = "daily") {
+    const res = await this.fetchJson(`/api/v1/rankings/search?channel=${encodeURIComponent(channel)}&platform=${encodeURIComponent(platform)}&timeframe=${encodeURIComponent(timeframe)}`);
+    return res.data;
+  }
+  moderation = {
+    mute: (platform, channel, targetUser, duration) => this.fetchJson("/api/v1/moderation/mutes", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, targetUser, duration })
+    }),
+    unmute: (platform, channel, targetUser) => this.fetchJson("/api/v1/moderation/mutes", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, targetUser })
+    }),
+    ban: (platform, channel, targetUser, reason) => this.fetchJson("/api/v1/moderation/bans", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, targetUser, reason })
+    }),
+    unban: (platform, channel, targetUser) => this.fetchJson("/api/v1/moderation/bans", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, targetUser })
+    }),
+    deleteMessage: (platform, channel, messageId) => this.fetchJson("/api/v1/moderation/messages", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, messageId })
+    }),
+    toggleComments: (platform, channel, enabled) => this.fetchJson("/api/v1/moderation/comments/toggle", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ platform, channel, enabled })
+    })
+  };
+}
+
+// src/errors.ts
+var 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"
+};
+
+class LightStreamError extends Error {
+  code;
+  details;
+  retryable;
+  timestamp;
+  constructor(payload) {
+    super(payload.message);
+    this.name = "LightStreamError";
+    this.code = payload.code;
+    this.details = payload.details;
+    this.retryable = payload.retryable ?? false;
+    this.timestamp = payload.timestamp;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      retryable: this.retryable,
+      timestamp: this.timestamp
+    };
+  }
+}
+
+// src/stream-client.ts
+class LightStreamStreamClient {
+  options;
+  ws = null;
+  _status = "idle";
+  listeners = new Map;
+  pingTimer = null;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  currentPlatform = null;
+  currentChannel = null;
+  constructor(options) {
+    this.options = options;
+  }
+  get status() {
+    return this._status;
+  }
+  setStatus(newStatus) {
+    if (this._status === newStatus)
+      return;
+    this._status = newStatus;
+    this.emit("status", newStatus);
+  }
+  connect(platform, channel) {
+    this.currentPlatform = platform;
+    this.currentChannel = channel.trim().toLowerCase();
+    return this.initSocket();
+  }
+  async initSocket() {
+    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;
+    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) => {
+          this.handleIncoming(typeof event.data === "string" ? event.data : event.data?.toString());
+        };
+        socket.onerror = (err) => {
+          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) {
+        this.handleFailure(LIGHTSTREAM_ERROR_CODES.INTERNAL_ERROR, err.message);
+        resolve();
+      }
+    });
+  }
+  handleIncoming(rawData) {
+    if (!rawData)
+      return;
+    let parsed;
+    try {
+      parsed = JSON.parse(rawData);
+    } catch {
+      return;
+    }
+    if (parsed.type === "pong")
+      return;
+    if (parsed.type === "connected") {
+      this.setStatus("connected");
+      const evt = {
+        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 = {
+        channel: parsed.channel || this.currentChannel,
+        platform: parsed.platform || this.currentPlatform,
+        isLive: false,
+        code: parsed.code || 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);
+      return;
+    }
+    if (parsed.event === "gift" || parsed.type === "gift") {
+      this.emit("gift", parsed.data);
+      return;
+    }
+    this.emit("raw", parsed);
+  }
+  handleFailure(code, message) {
+    this.setStatus("error");
+    const errPayload = {
+      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();
+    }
+  }
+  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);
+  }
+  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);
+  }
+  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() {
+    this.cleanupSocket();
+    this.setStatus("disconnected");
+    this.currentChannel = null;
+    this.currentPlatform = null;
+  }
+  on(event, handler) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set);
+    }
+    this.listeners.get(event).add(handler);
+  }
+  off(event, handler) {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+  }
+  emit(event, ...args) {
+    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);
+        }
+      }
+    }
+  }
+}
+
+// src/index.ts
+class LightStreamClient {
+  rest;
+  stream;
+  constructor(options) {
+    this.rest = new LightStreamRestClient({
+      baseUrl: options.baseUrl || "https://gateway.lightstream.lat",
+      apiKey: options.apiKey,
+      jwtKey: options.jwtKey || options.token
+    });
+    this.stream = new LightStreamStreamClient(options);
+  }
+}
+function createLightStreamClient(options) {
+  return new LightStreamClient(options);
+}
+export {
+  LIGHTSTREAM_ERROR_CODES,
+  LightStreamClient,
+  LightStreamError,
+  LightStreamRestClient,
+  LightStreamStreamClient,
+  createLightStreamClient
+};

package/dist/rest-client.d.ts

@@ -0,0 +1,45 @@
+import type { Platform, Timeframe } from './types.js';
+export interface RestClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    jwtKey?: string;
+}
+export declare class LightStreamRestClient {
+    private config;
+    constructor(config: RestClientConfig);
+    private fetchJson;
+    issueToken(options: {
+        expireAfterSeconds?: number;
+        allowedPlatforms?: Platform[];
+        allowedChannels?: string[];
+        maxWebSockets?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+        maxWebSockets: number;
+    }>;
+    bulkCheckStreams(requests: Array<{
+        platform: Platform;
+        channel: string;
+    }>): Promise<Array<{
+        platform: Platform;
+        channel: string;
+        isLive: boolean;
+        viewerCount: number;
+        title?: string;
+        cached?: boolean;
+    }>>;
+    getRoomStreamInfo(platform: Platform, channel: string): Promise<Record<string, unknown>>;
+    getUserEarnings(platform: Platform, channel: string): Promise<Record<string, unknown>>;
+    getGiftsCatalog(platform?: Platform): Promise<any[]>;
+    getLeaderboard(platform: Platform, timeframe?: Timeframe, limit?: number): Promise<any[]>;
+    searchRankings(channel: string, platform?: Platform, timeframe?: Timeframe): Promise<any>;
+    readonly moderation: {
+        mute: (platform: Platform, channel: string, targetUser: string, duration?: number) => Promise<unknown>;
+        unmute: (platform: Platform, channel: string, targetUser: string) => Promise<unknown>;
+        ban: (platform: Platform, channel: string, targetUser: string, reason?: string) => Promise<unknown>;
+        unban: (platform: Platform, channel: string, targetUser: string) => Promise<unknown>;
+        deleteMessage: (platform: Platform, channel: string, messageId: string) => Promise<unknown>;
+        toggleComments: (platform: Platform, channel: string, enabled: boolean) => Promise<unknown>;
+    };
+}

package/dist/src/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;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+import { LightStreamRestClient } from './rest-client.js';
+import { LightStreamStreamClient } from './stream-client.js';
+import type { ClientOptions } from './types.js';
+export declare class LightStreamClient {
+    readonly rest: LightStreamRestClient;
+    readonly stream: LightStreamStreamClient;
+    constructor(options: ClientOptions);
+}
+export declare function createLightStreamClient(options: ClientOptions): LightStreamClient;
+export * from './types.js';
+export * from './errors.js';
+export * from './rest-client.js';
+export * from './stream-client.js';

package/dist/src/rest-client.d.ts

@@ -0,0 +1,45 @@
+import type { Platform, Timeframe } from './types.js';
+export interface RestClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    jwtKey?: string;
+}
+export declare class LightStreamRestClient {
+    private config;
+    constructor(config: RestClientConfig);
+    private fetchJson;
+    issueToken(options: {
+        expireAfterSeconds?: number;
+        allowedPlatforms?: Platform[];
+        allowedChannels?: string[];
+        maxWebSockets?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+        maxWebSockets: number;
+    }>;
+    bulkCheckStreams(requests: Array<{
+        platform: Platform;
+        channel: string;
+    }>): Promise<Array<{
+        platform: Platform;
+        channel: string;
+        isLive: boolean;
+        viewerCount: number;
+        title?: string;
+        cached?: boolean;
+    }>>;
+    getRoomStreamInfo(platform: Platform, channel: string): Promise<Record<string, unknown>>;
+    getUserEarnings(platform: Platform, channel: string): Promise<Record<string, unknown>>;
+    getGiftsCatalog(platform?: Platform): Promise<any[]>;
+    getLeaderboard(platform: Platform, timeframe?: Timeframe, limit?: number): Promise<any[]>;
+    searchRankings(channel: string, platform?: Platform, timeframe?: Timeframe): Promise<any>;
+    readonly moderation: {
+        mute: (platform: Platform, channel: string, targetUser: string, duration?: number) => Promise<unknown>;
+        unmute: (platform: Platform, channel: string, targetUser: string) => Promise<unknown>;
+        ban: (platform: Platform, channel: string, targetUser: string, reason?: string) => Promise<unknown>;
+        unban: (platform: Platform, channel: string, targetUser: string) => Promise<unknown>;
+        deleteMessage: (platform: Platform, channel: string, messageId: string) => Promise<unknown>;
+        toggleComments: (platform: Platform, channel: string, enabled: boolean) => Promise<unknown>;
+    };
+}

package/dist/src/stream-client.d.ts

@@ -0,0 +1,26 @@
+import type { ClientOptions, ConnectionStatus, LightStreamEventMap, Platform } from './types.js';
+export declare class LightStreamStreamClient {
+    private options;
+    private ws;
+    private _status;
+    private listeners;
+    private pingTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private currentPlatform;
+    private currentChannel;
+    constructor(options: ClientOptions);
+    get status(): ConnectionStatus;
+    private setStatus;
+    connect(platform: Platform, channel: string): Promise<void>;
+    private initSocket;
+    private handleIncoming;
+    private handleFailure;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private cleanupSocket;
+    disconnect(): void;
+    on<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void;
+    off<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void;
+    private emit;
+}

package/dist/src/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/dist/stream-client.d.ts

@@ -0,0 +1,26 @@
+import type { ClientOptions, ConnectionStatus, LightStreamEventMap, Platform } from './types.js';
+export declare class LightStreamStreamClient {
+    private options;
+    private ws;
+    private _status;
+    private listeners;
+    private pingTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private currentPlatform;
+    private currentChannel;
+    constructor(options: ClientOptions);
+    get status(): ConnectionStatus;
+    private setStatus;
+    connect(platform: Platform, channel: string): Promise<void>;
+    private initSocket;
+    private handleIncoming;
+    private handleFailure;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private cleanupSocket;
+    disconnect(): void;
+    on<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void;
+    off<K extends keyof LightStreamEventMap>(event: K, handler: LightStreamEventMap[K]): void;
+    private emit;
+}