@thestatic-tv/dcl-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Configuration options for StaticTVClient
+ */
+interface StaticTVConfig {
+    /** Your channel's API key from thestatic.tv studio */
+    apiKey: string;
+    /** Automatically start session tracking on init (default: true) */
+    autoStartSession?: boolean;
+    /** Interval for session heartbeats in ms (default: 30000) */
+    sessionHeartbeatInterval?: number;
+    /** Interval for video watching heartbeats in ms (default: 60000) */
+    watchHeartbeatInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom API base URL (default: https://thestatic.tv/api/v1/dcl) */
+    baseUrl?: string;
+}
+/**
+ * Channel information from the guide
+ */
+interface Channel {
+    id: string;
+    slug: string;
+    name: string;
+    streamUrl: string;
+    isLive: boolean;
+    currentViewers: number;
+    poster: string | null;
+    logo: string | null;
+    description: string;
+    socials: string | null;
+}
+/**
+ * VOD (Video on Demand) information
+ */
+interface Vod {
+    id: string;
+    title: string;
+    url: string;
+    thumbnail: string | null;
+    channelId: string;
+    createdAt: string;
+}
+/**
+ * Guide response from the API
+ */
+interface GuideResponse {
+    version: string;
+    sceneOwnerChannel: string;
+    channels: Channel[];
+    liveChannels: Channel[];
+    vods: Vod[];
+    meta: {
+        generatedAt: string;
+        totalChannels: number;
+        liveCount: number;
+        vodCount: number;
+    };
+}
+/**
+ * Session response from the API
+ */
+interface SessionResponse {
+    success: boolean;
+    sessionId?: string;
+    version: string;
+}
+/**
+ * Heartbeat response from the API
+ */
+interface HeartbeatResponse {
+    success: boolean;
+    channelSlug: string;
+    sceneOwnerChannel: string;
+    version: string;
+}
+/**
+ * Interaction response from the API
+ */
+interface InteractionResponse {
+    success: boolean;
+    action: 'like' | 'follow';
+    channelSlug: string;
+    alreadyExists: boolean;
+    version: string;
+}
+
+/**
+ * Guide module - fetch channel lineup from thestatic.tv
+ */
+
+declare class GuideModule {
+    private client;
+    private cachedChannels;
+    private cacheTimestamp;
+    private readonly cacheDuration;
+    constructor(client: StaticTVClient);
+    /**
+     * Get all channels from thestatic.tv
+     * Results are cached for 30 seconds
+     */
+    getChannels(forceRefresh?: boolean): Promise<Channel[]>;
+    /**
+     * Get only live channels
+     */
+    getLiveChannels(forceRefresh?: boolean): Promise<Channel[]>;
+    /**
+     * Get a specific channel by slug
+     */
+    getChannel(slug: string): Promise<Channel | undefined>;
+    /**
+     * Get VODs (videos on demand)
+     */
+    getVods(): Promise<Vod[]>;
+    /**
+     * Clear the channel cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * Session module - track visitor sessions in DCL scenes
+ *
+ * Works with both channel keys (dclk_) and scene keys (dcls_).
+ * Scene keys use /scene-session endpoint, channel keys use /session.
+ */
+
+declare class SessionModule {
+    private client;
+    private sessionId;
+    private heartbeatInterval;
+    private isActive;
+    constructor(client: StaticTVClient);
+    /**
+     * Get the appropriate session endpoint based on key type
+     */
+    private getEndpoint;
+    /**
+     * Start a new session
+     * Called automatically if autoStartSession is true
+     */
+    startSession(metadata?: Record<string, unknown>): Promise<string | null>;
+    /**
+     * Start the heartbeat interval
+     */
+    private startHeartbeat;
+    /**
+     * Send a session heartbeat
+     */
+    private sendHeartbeat;
+    /**
+     * End the current session
+     */
+    endSession(): Promise<void>;
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Check if a session is currently active
+     */
+    isSessionActive(): boolean;
+}
+
+/**
+ * Heartbeat module - track video watching metrics
+ */
+
+declare class HeartbeatModule {
+    private client;
+    private watchInterval;
+    private currentChannel;
+    private isWatching;
+    constructor(client: StaticTVClient);
+    /**
+     * Start tracking video watching for a channel
+     * Sends heartbeats every minute while watching
+     *
+     * @param channelSlug The slug of the channel being watched
+     */
+    startWatching(channelSlug: string): void;
+    /**
+     * Stop tracking video watching
+     */
+    stopWatching(): void;
+    /**
+     * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+     */
+    private sendHeartbeat;
+    /**
+     * Get the currently watched channel
+     */
+    getCurrentChannel(): string | null;
+    /**
+     * Check if currently watching
+     */
+    isCurrentlyWatching(): boolean;
+}
+
+/**
+ * Interactions module - like/follow channels from DCL scenes
+ */
+
+declare class InteractionsModule {
+    private client;
+    constructor(client: StaticTVClient);
+    /**
+     * Like a channel
+     * Requires the user to be connected with a wallet
+     *
+     * @param channelSlug The slug of the channel to like
+     * @returns The interaction response or null if failed
+     */
+    like(channelSlug: string): Promise<InteractionResponse | null>;
+    /**
+     * Follow a channel
+     * Requires the user to be connected with a wallet
+     *
+     * @param channelSlug The slug of the channel to follow
+     * @returns The interaction response or null if failed
+     */
+    follow(channelSlug: string): Promise<InteractionResponse | null>;
+}
+
+/**
+ * StaticTVClient - Main client for connecting DCL scenes to thestatic.tv
+ *
+ * Supports two key types:
+ * - dclk_* : Channel keys (full access - guide, heartbeat, interactions)
+ * - dcls_* : Scene-only keys (lite - session tracking only)
+ */
+
+/** Key type constants */
+declare const KEY_TYPE_CHANNEL = "channel";
+declare const KEY_TYPE_SCENE = "scene";
+declare class StaticTVClient {
+    private config;
+    private baseUrl;
+    private _keyType;
+    /** Guide module - fetch channel lineup (channel keys only) */
+    readonly guide: GuideModule | null;
+    /** Session module - track visitor sessions (all keys) */
+    readonly session: SessionModule;
+    /** Heartbeat module - track video watching (channel keys only) */
+    readonly heartbeat: HeartbeatModule | null;
+    /** Interactions module - like/follow channels (channel keys only) */
+    readonly interactions: InteractionsModule | null;
+    /**
+     * Create a new StaticTVClient
+     *
+     * @param config Configuration options
+     *
+     * @example
+     * ```typescript
+     * // Full access with channel key
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dclk_your_channel_key_here',
+     *   debug: true
+     * });
+     *
+     * // Lite mode with scene key (visitors only)
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_your_scene_key_here'
+     * });
+     * ```
+     */
+    constructor(config: StaticTVConfig);
+    /**
+     * Get the key type (channel or scene)
+     */
+    get keyType(): 'channel' | 'scene';
+    /**
+     * Check if this is a lite (scene-only) client
+     */
+    get isLite(): boolean;
+    /**
+     * Make an authenticated API request
+     * @internal
+     */
+    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Log a message if debug is enabled
+     * @internal
+     */
+    log(message: string, ...args: unknown[]): void;
+    /**
+     * Get the current configuration
+     * @internal
+     */
+    getConfig(): StaticTVConfig;
+    /**
+     * Cleanup when done (call before scene unload)
+     */
+    destroy(): Promise<void>;
+}
+
+export { type Channel, GuideModule, type GuideResponse, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type Vod };