@thestatic-tv/dcl-sdk 2.2.9 → 2.3.0-beta.0

package/dist/index.d.ts

@@ -1,3 +1,15 @@
+import ReactEcs from '@dcl/sdk/react-ecs';
+
+/**
+ * JSX namespace declaration for DTS generation compatibility.
+ * React-ECS uses custom JSX factory, this ensures types compile.
+ */
+declare global {
+    namespace JSX {
+        interface Element {
+        }
+    }
+}
 /**
  * Player identity data from DCL
  */
@@ -85,14 +97,22 @@ interface GuideResponse {
         vodCount: number;
     };
 }
+/**
+ * SDK tier levels - determines available features
+ * - free: Session tracking only (visitor metrics)
+ * - standard: Guide, Chat, Heartbeat, Interactions + session tracking
+ * - pro: Everything in Standard + Admin Panel
+ */
+type SDKTier = 'free' | 'standard' | 'pro';
 /**
  * Session response from the API
  */
 interface SessionResponse {
     success: boolean;
     sessionId?: string;
+    keyId?: string;
     keyType?: 'scene' | 'channel';
-    sdkType?: 'lite' | 'full';
+    sdkType?: SDKTier | 'lite' | 'full';
     version: string;
 }
 /**
@@ -187,7 +207,10 @@ interface ChatMessage {
     username: string;
     text: string;
     uid: string;
-    createdAt: any;
+    createdAt: Date | {
+        seconds: number;
+        nanoseconds: number;
+    } | string | number;
     isSystem?: boolean;
 }
 /**
@@ -203,6 +226,117 @@ interface ChatUIConfig {
      */
     fontScale?: number;
 }
+/**
+ * Stream channel data from the API
+ */
+interface StreamData {
+    hasChannel: boolean;
+    channelId: string | null;
+    channelName?: string;
+    isLive: boolean;
+    hlsUrl: string | null;
+    rtmpUrl?: string | null;
+    streamKey?: string | null;
+    currentViewers: number;
+    sparksBalance: number;
+    tier?: string;
+    /** True if user can claim the one-time streaming trial */
+    trialAvailable?: boolean;
+    /** Number of Sparks included in trial (240 = 4 hours) */
+    trialSparks?: number;
+}
+/**
+ * Video slot configuration
+ */
+interface VideoSlot {
+    id: string;
+    name: string;
+    url: string;
+}
+/**
+ * Command handler for scene-specific commands
+ */
+type CommandHandler = (type: string, payload?: Record<string, unknown>) => void;
+/**
+ * Custom scene tab definition for Pro tier
+ */
+interface SceneTabDefinition {
+    /** Tab label shown in the tab bar */
+    label: string;
+    /** Unique tab ID */
+    id: string;
+    /** React-ECS component that renders the tab content */
+    render: () => JSX.Element | null;
+}
+/**
+ * Configuration options for AdminPanelModule
+ */
+interface AdminPanelConfig {
+    /**
+     * Scene ID for API calls.
+     * Optional - defaults to API key ID if not provided.
+     */
+    sceneId?: string;
+    /**
+     * Panel title (shown in header)
+     */
+    title?: string;
+    /**
+     * Header background color (default: red)
+     */
+    headerColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * Show Video tab (default: true for Pro tier)
+     */
+    showVideoTab?: boolean;
+    /**
+     * Show Mod tab (default: true for owners)
+     */
+    showModTab?: boolean;
+    /**
+       * Custom scene tabs (Pro tier)
+       */
+    sceneTabs?: SceneTabDefinition[];
+    /**
+     * Command handler for scene-specific commands (e.g., elevator, lights)
+     * Called when admin triggers a command from the panel
+     */
+    onCommand?: CommandHandler;
+    /**
+     * Callback when video URL should be played
+     */
+    onVideoPlay?: (url: string) => void;
+    /**
+     * Callback when video playback should stop
+     */
+    onVideoStop?: () => void;
+    /**
+     * Callback when video slot is selected
+     */
+    onVideoSlotPlay?: (slot: string) => void;
+    /**
+     * Callback for broadcast messages
+     */
+    onBroadcast?: (text: string) => void;
+    /**
+     * Link shown in footer (default: scene page on thestatic.tv)
+     */
+    footerLink?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Force admin access (for testing without server endpoint)
+     * WARNING: Only use during development!
+     */
+    forceAdmin?: boolean;
+}
 
 /**
  * Guide module - fetch channel lineup from thestatic.tv
@@ -247,13 +381,24 @@ declare class GuideModule {
 declare class SessionModule {
     private client;
     private sessionId;
+    private _keyId;
     private heartbeatTimerId;
     private isActive;
-    private _sdkType;
+    private _tier;
     constructor(client: StaticTVClient);
     /**
-     * Get the SDK type returned by the server
-     * Determines what features are available (lite = sessions only, full = guide + chat + more)
+     * Get the API key ID (used as default sceneId for Pro users)
+     */
+    get keyId(): string | null;
+    /**
+     * Get the SDK tier returned by the server
+     * - free: Session tracking only
+     * - standard: Guide, Chat, Heartbeat, Interactions
+     * - pro: Everything + Admin Panel
+     */
+    get tier(): SDKTier;
+    /**
+     * @deprecated Use `tier` instead. Returns mapped value for compatibility.
      */
     get sdkType(): 'lite' | 'full';
     /**
@@ -379,7 +524,6 @@ declare class GuideUIModule {
     private currentPage;
     private itemsPerPage;
     private searchQuery;
-    private uiScale;
     private _currentVideoId;
     constructor(client: StaticTVClient, config?: GuideUIConfig);
     /**
@@ -429,7 +573,7 @@ declare class GuideUIModule {
     private handleChannelClick;
     /**
      * Get the guide UI component for rendering
-     * Returns toggle button when hidden, full panel when visible
+     * Always renders toggle button, plus panel when visible
      */
     getComponent: () => any;
     private renderLeftPanel;
@@ -463,7 +607,6 @@ declare class ChatUIModule {
     private inputText;
     private chatScrollOffset;
     private position;
-    private fontScale;
     private chatTimerId;
     private playerInfoTimerId;
     private isInitialized;
@@ -517,9 +660,11 @@ declare class ChatUIModule {
     private resetChatTimer;
     private parseServerTime;
     private formatTime;
+    /** Scale a dimension by shared uiScale */
+    private s;
     /**
      * Get the chat UI component for rendering
-     * Returns toggle button when hidden, full panel when visible
+     * Always renders toggle button, plus panel when visible
      */
     getComponent: () => any;
     private getPositionStyle;
@@ -534,12 +679,129 @@ declare class ChatUIModule {
     private renderToggleButton;
 }
 
+/**
+ * Admin Panel UI Module for The Static TV SDK (Pro Tier)
+ *
+ * Provides in-scene admin controls:
+ * - Video Tab: Stream control, video playback, slots
+ * - Mod Tab: Scene admins, banned wallets, broadcast
+ * - Custom Scene Tabs: Pro tier
+ */
+
+declare class AdminPanelUIModule {
+    private client;
+    private config;
+    private baseUrl;
+    private isAdmin;
+    private isOwner;
+    private panelOpen;
+    private activeTab;
+    private playerWallet;
+    private customVideoUrl;
+    private streamData;
+    private streamFetched;
+    private videoState;
+    private videoStateFetched;
+    private channelCreating;
+    private channelCreateError;
+    private channelDeleting;
+    private channelDeleteError;
+    private keyRotating;
+    private keyRotateStatus;
+    private streamControlling;
+    private streamControlStatus;
+    private pollIntervalId;
+    private trialClaiming;
+    private trialClaimError;
+    private sceneAdmins;
+    private bannedWallets;
+    private newAdminWallet;
+    private newBanWallet;
+    private broadcastText;
+    private modStatus;
+    private modsFetched;
+    constructor(client: StaticTVClient, config: AdminPanelConfig);
+    private log;
+    /** Scale a dimension by shared uiScale */
+    private s;
+    /** Get scaled theme */
+    private get theme();
+    /**
+     * Initialize the admin panel - checks admin status and fetches video state
+     */
+    init(): Promise<void>;
+    /**
+     * Check if current player is an admin for this scene
+     */
+    checkAdminStatus(): Promise<void>;
+    /**
+     * Toggle the admin panel open/closed
+     */
+    toggle(): void;
+    /**
+     * Show the admin panel
+     */
+    show(): void;
+    /**
+     * Hide the admin panel
+     */
+    hide(): void;
+    /**
+     * Check if the panel is currently open
+     */
+    get isOpen(): boolean;
+    /**
+     * Check if current user has admin access
+     */
+    get hasAccess(): boolean;
+    /**
+       * Register a custom scene tab (Pro tier)
+       */
+    registerSceneTab(tab: SceneTabDefinition): void;
+    private startStreamPolling;
+    private stopStreamPolling;
+    private fetchStreamData;
+    private refreshStreamStatus;
+    private fetchVideoState;
+    /**
+     * Play a video slot by ID - looks up URL and calls onVideoPlay
+     */
+    playSlot(slotId: string): void;
+    /**
+     * Auto-play the default slot if configured
+     */
+    private autoPlayDefault;
+    private createChannel;
+    private claimTrial;
+    private deleteChannel;
+    private startStream;
+    private stopStream;
+    private rotateStreamKey;
+    private fetchModData;
+    private addSceneAdmin;
+    private removeSceneAdmin;
+    private banWallet;
+    private unbanWallet;
+    private banKickPlayer;
+    private sendBroadcast;
+    private setActiveTab;
+    private SectionHead;
+    private TabBtn;
+    private VideoTab;
+    private ModTab;
+    /**
+     * Get the React-ECS component for the admin panel
+     */
+    getComponent: () => ReactEcs.JSX.Element | null;
+}
+
 /**
  * StaticTVClient - Main client for connecting DCL scenes to thestatic.tv
  *
- * All keys use dcls_ prefix. Features enabled based on sdkType from server:
- * - lite: Session tracking only
- * - full: Guide, Chat, Heartbeat, Interactions + session tracking
+ * All keys use dcls_ prefix. Features enabled based on tier from server:
+ * - free: Session tracking only (visitor metrics)
+ * - standard: Guide, Chat, Heartbeat, Interactions + session tracking
+ * - pro: Everything in Standard + Admin Panel (Video + Mod tabs)
  */
 
 /** Key type constants (legacy - kept for compatibility) */
@@ -549,20 +811,30 @@ declare class StaticTVClient {
     private config;
     private baseUrl;
     private _keyType;
+    private _keyId;
     private _disabled;
-    private _fullFeaturesEnabled;
-    /** Guide module - fetch channel lineup (full SDK only) */
+    private _tier;
+    private _standardFeaturesEnabled;
+    private _proFeaturesEnabled;
+    private _pendingProConfig;
+    /** Guide module - fetch channel lineup (standard/pro tier) */
     guide: GuideModule | null;
-    /** Session module - track visitor sessions (all keys, null when disabled) */
+    /** Session module - track visitor sessions (all tiers, null when disabled) */
     session: SessionModule | null;
-    /** Heartbeat module - track video watching (full SDK only) */
+    /** Heartbeat module - track video watching (standard/pro tier) */
     heartbeat: HeartbeatModule | null;
-    /** Interactions module - like/follow channels (full SDK only) */
+    /** Interactions module - like/follow channels (standard/pro tier) */
     interactions: InteractionsModule | null;
-    /** Guide UI module - channel browser UI (full SDK only) */
+    /** Guide UI module - channel browser UI (standard/pro tier) */
     guideUI: GuideUIModule | null;
-    /** Chat UI module - real-time chat UI (full SDK only) */
+    /** Chat UI module - real-time chat UI (standard/pro tier) */
     chatUI: ChatUIModule | null;
+    /** Admin Panel module - Video/Mod tabs (pro tier only) */
+    adminPanel: AdminPanelUIModule | null;
+    /** UI scale - fixed at 1.0. DCL's UI system auto-scales based on viewport. */
+    readonly uiScale: number;
+    /** Get the API base URL (for internal module use) */
+    getBaseUrl(): string;
     /**
      * Create a new StaticTVClient
      *
@@ -570,16 +842,15 @@ declare class StaticTVClient {
      *
      * @example
      * ```typescript
-     * // Full access with channel key
-     * const staticTV = new StaticTVClient({
-     *   apiKey: 'dclk_your_channel_key_here',
-     *   debug: true
-     * });
+     * let staticTV: StaticTVClient
      *
-     * // Lite mode with scene key (visitors only)
-     * const staticTV = new StaticTVClient({
-     *   apiKey: 'dcls_your_scene_key_here'
-     * });
+     * export function main() {
+     *   // All keys use dcls_ prefix - features determined by subscription
+     *   staticTV = new StaticTVClient({
+     *     apiKey: 'dcls_your_key_here'
+     *   })
+     *   // Session tracking starts automatically!
+     * }
      * ```
      */
     constructor(config: StaticTVConfig);
@@ -592,8 +863,16 @@ declare class StaticTVClient {
      */
     get isDisabled(): boolean;
     /**
-     * Check if this is a lite client (no full features)
-     * Returns true until session confirms sdkType is 'full'
+     * Get the current SDK tier (free, standard, or pro)
+     */
+    get tier(): SDKTier;
+    /**
+     * Check if this is a free tier client (session tracking only)
+     * Returns true until session confirms a higher tier
+     */
+    get isFree(): boolean;
+    /**
+     * @deprecated Use `isFree` instead. Kept for backward compatibility.
      */
     get isLite(): boolean;
     /**
@@ -602,40 +881,173 @@ declare class StaticTVClient {
      */
     request<T>(endpoint: string, options?: RequestInit): Promise<T>;
     /**
-     * Log a message if debug is enabled
+     * Log a debug message (only when debug: true)
      * @internal
      */
     log(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning (always shown)
+     * @internal
+     */
+    warn(message: string): void;
+    /**
+     * Log an error (always shown, user-friendly format)
+     * @internal
+     */
+    error(message: string, err?: unknown): void;
     /**
      * Get the current configuration
      * @internal
      */
     getConfig(): StaticTVConfig;
     /**
-     * Initialize full feature modules (guide, heartbeat, interactions, UI)
+     * Initialize standard feature modules (guide, heartbeat, interactions, UI)
+     * @internal
+     */
+    private _initStandardModules;
+    /**
+     * Initialize pro feature modules (admin panel)
      * @internal
      */
-    private _initFullModules;
+    private _initProModules;
     /**
-     * Called by SessionModule when server confirms sdkType is 'full'
-     * Enables guide, chat, heartbeat, and interactions modules
+     * Called by SessionModule when server returns the tier
+     * Enables modules based on tier level
+     * @internal
+     */
+    _enableFeaturesForTier(tier: SDKTier, keyId?: string | null): void;
+    /**
+     * @deprecated Use `_enableFeaturesForTier` instead
      * @internal
      */
     _enableFullFeatures(): void;
     /**
-     * Check if full features are enabled (server confirmed sdkType: 'full')
+     * Check if standard features are enabled (guide, chat, etc.)
+     */
+    get hasStandardFeatures(): boolean;
+    /**
+     * @deprecated Use `hasStandardFeatures` instead
      */
     get hasFullFeatures(): boolean;
     /**
-     * Get the SDK type (lite or full) - only available after session starts
+     * Check if pro features are enabled (admin panel)
+     */
+    get hasProFeatures(): boolean;
+    /**
+     * @deprecated Use `tier` instead
      */
     get sdkType(): 'lite' | 'full';
+    /**
+     * Configure Pro features (Admin Panel with Video + Mod tabs)
+     * Call this after creating the client to configure admin panel.
+     * The panel will auto-enable when server confirms Pro tier.
+     *
+     * @param config Admin panel configuration (optional - defaults work for basic usage)
+     *
+     * @example
+     * ```typescript
+     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     *
+     * // Simplest usage - just enable with callbacks:
+     * staticTV.enableProFeatures({
+     *   onVideoPlay: (url) => videoPlayer.play(url),
+     *   onVideoStop: () => videoPlayer.stop()
+     * })
+     *
+     * // Advanced usage - custom sceneId and title:
+     * staticTV.enableProFeatures({
+     *   sceneId: 'my-scene', // optional - defaults to API key ID
+     *   title: 'MY SCENE ADMIN',
+     *   onVideoPlay: (url) => videoPlayer.play(url),
+     *   onVideoStop: () => videoPlayer.stop(),
+     *   onBroadcast: (text) => showNotification(text)
+     * })
+     * ```
+     */
+    enableProFeatures(config?: AdminPanelConfig): void;
+    /**
+       * Register a custom scene tab for the admin panel (Pro tier)
+       * Must call enableProFeatures() first.
+       *
+       * @param tab The tab definition with label, id, and render function
+       *
+       * @example
+       * ```typescript
+       * staticTV.registerSceneTab({
+       *   label: 'LIGHTS',
+       *   id: 'lights',
+       *   render: () => <MyLightsControls />
+       * })
+       * ```
+       */
+    registerSceneTab(tab: SceneTabDefinition): void;
+    /**
+     * Close Admin/Guide panels (they share the same screen space)
+     * Chat is independent and stays open.
+     * @param except The panel that should stay open: 'admin' | 'guide'
+     */
+    closeOtherPanels(except: 'admin' | 'guide'): void;
+    /**
+     * Set up the UI renderer for all SDK panels
+     * Call this in your scene's main() function to render Guide, Chat, Admin panels.
+     * No need to create your own ui.tsx - the SDK handles everything.
+     *
+     * @example
+     * ```typescript
+     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     *
+     * export function main() {
+     *   staticTV.setupUI()
+     *   // That's it! All panels will render automatically
+     * }
+     * ```
+     */
+    setupUI(): void;
+    /**
+     * Show a notification message on screen
+     * Works with both SDK-rendered UI and custom UI setups.
+     *
+     * @param message The message to display
+     * @param durationMs How long to show (default 5000ms)
+     *
+     * @example
+     * ```typescript
+     * staticTV.showNotification('Stream started!')
+     * staticTV.showNotification('Custom message', 10000) // 10 seconds
+     * ```
+     */
+    showNotification(message: string, durationMs?: number): void;
     /**
      * Cleanup when done (call before scene unload)
      */
     destroy(): Promise<void>;
 }
 
+/**
+ * UI Renderer - SDK-level UI component that renders all panels
+ *
+ * This allows scenes to use the SDK's UI without needing their own ui.tsx file.
+ * Just call staticTV.setupUI() and all panels will render automatically.
+ */
+
+/**
+ * Show a notification message on screen
+ * @param message The message to display
+ * @param durationMs How long to show (default 5000ms)
+ */
+declare function showNotification(message: string, durationMs?: number): void;
+/**
+ * Set up the UI renderer for a StaticTVClient
+ * Call this in your scene's main() function after creating the client.
+ *
+ * @example
+ * ```typescript
+ * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+ * setupStaticUI(staticTV)
+ * ```
+ */
+declare function setupStaticUI(client: StaticTVClient): void;
+
 /**
  * Identity utilities for getting player information
  * Uses getUserData from ~system/UserIdentity for reliable data in both
@@ -660,4 +1072,4 @@ declare function getPlayerWallet(): string | null;
  */
 declare function getPlayerDisplayName(): string | null;
 
-export { type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, type PlayerData, type SceneStats, type SceneStatsResponse, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type Vod, fetchUserData, getPlayerDisplayName, getPlayerWallet };
+export { type AdminPanelConfig, AdminPanelUIModule, type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type CommandHandler, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, type PlayerData, type SDKTier, type SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerWallet, setupStaticUI, showNotification };