@thestatic-tv/dcl-sdk 2.3.0-dev.0 → 2.3.0

package/dist/index.d.mts

@@ -1,5 +1,16 @@
+import { Entity as Entity$1 } from '@dcl/sdk/ecs';
 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
  */
@@ -9,12 +20,57 @@ interface PlayerData {
     /** Player's display name */
     name?: string;
 }
+
+type Entity = Entity$1;
 /**
  * Configuration options for StaticTVClient
  */
 interface StaticTVConfig {
     /** Your channel's API key from thestatic.tv studio */
     apiKey: string;
+    /**
+     * Video screen entity - SDK automatically manages VideoPlayer on this entity.
+     * When user selects a video from Guide or Admin plays a URL, it plays here.
+     *
+     * @example
+     * ```typescript
+     * const screen = engine.addEntity()
+     * Transform.create(screen, { position: Vector3.create(8, 3, 14), scale: Vector3.create(8, 4.5, 0.1) })
+     * MeshRenderer.setPlane(screen)
+     *
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_...',
+     *   videoScreen: screen  // SDK handles all video playback!
+     * })
+     * ```
+     */
+    videoScreen?: Entity;
+    /**
+     * Scene ID for Admin Panel API calls.
+     * Optional - defaults to API key ID if not provided.
+     */
+    sceneId?: string;
+    /**
+     * Callback when video URL should be played (Pro tier).
+     * If videoScreen is set, this is called AFTER SDK plays the video.
+     * Use for custom logic like logging, UI updates, etc.
+     */
+    onVideoPlay?: (url: string) => void;
+    /**
+     * Callback when video playback should stop (Pro tier).
+     * If videoScreen is set, this is called AFTER SDK stops the video.
+     */
+    onVideoStop?: () => void;
+    /**
+     * Callback for broadcast messages (Pro tier).
+     * Default: shows notification via staticTV.showNotification()
+     */
+    onBroadcast?: (text: string) => void;
+    /**
+     * Command handler for scene-specific commands (Pro tier).
+     * Called when admin triggers a command from the panel.
+     */
+    onCommand?: (type: string, payload?: Record<string, unknown>) => void;
     /** Automatically start session tracking on init (default: true) */
     autoStartSession?: boolean;
     /** Interval for session heartbeats in ms (default: 30000) */
@@ -37,11 +93,11 @@ interface StaticTVConfig {
      */
     player?: PlayerData;
     /**
-     * Guide UI configuration (channel keys only)
+     * Guide UI configuration
      */
     guideUI?: GuideUIConfig;
     /**
-     * Chat UI configuration (channel keys only)
+     * Chat UI configuration
      */
     chatUI?: ChatUIConfig;
 }
@@ -87,14 +143,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;
 }
 /**
@@ -189,7 +253,10 @@ interface ChatMessage {
     username: string;
     text: string;
     uid: string;
-    createdAt: any;
+    createdAt: Date | {
+        seconds: number;
+        nanoseconds: number;
+    } | string | number;
     isSystem?: boolean;
 }
 /**
@@ -237,7 +304,7 @@ interface VideoSlot {
  */
 type CommandHandler = (type: string, payload?: Record<string, unknown>) => void;
 /**
- * Custom scene tab definition for Full/Custom tier
+ * Custom scene tab definition for Pro tier
  */
 interface SceneTabDefinition {
     /** Tab label shown in the tab bar */
@@ -245,16 +312,17 @@ interface SceneTabDefinition {
     /** Unique tab ID */
     id: string;
     /** React-ECS component that renders the tab content */
-    render: () => any;
+    render: () => JSX.Element | null;
 }
 /**
  * Configuration options for AdminPanelModule
  */
 interface AdminPanelConfig {
     /**
-     * Scene ID for API calls
+     * Scene ID for API calls.
+     * Optional - defaults to API key ID if not provided.
      */
-    sceneId: string;
+    sceneId?: string;
     /**
      * Panel title (shown in header)
      */
@@ -277,8 +345,8 @@ interface AdminPanelConfig {
      */
     showModTab?: boolean;
     /**
-     * Custom scene tabs (Full/Custom tier only)
-     */
+       * Custom scene tabs (Pro tier)
+       */
     sceneTabs?: SceneTabDefinition[];
     /**
      * Command handler for scene-specific commands (e.g., elevator, lights)
@@ -309,6 +377,11 @@ interface AdminPanelConfig {
      * Enable debug logging
      */
     debug?: boolean;
+    /**
+     * Force admin access (for testing without server endpoint)
+     * WARNING: Only use during development!
+     */
+    forceAdmin?: boolean;
 }
 
 /**
@@ -354,13 +427,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';
     /**
@@ -486,7 +570,6 @@ declare class GuideUIModule {
     private currentPage;
     private itemsPerPage;
     private searchQuery;
-    private uiScale;
     private _currentVideoId;
     constructor(client: StaticTVClient, config?: GuideUIConfig);
     /**
@@ -536,7 +619,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;
@@ -570,7 +653,6 @@ declare class ChatUIModule {
     private inputText;
     private chatScrollOffset;
     private position;
-    private fontScale;
     private chatTimerId;
     private playerInfoTimerId;
     private isInitialized;
@@ -624,9 +706,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;
@@ -647,7 +731,7 @@ declare class ChatUIModule {
  * Provides in-scene admin controls:
  * - Video Tab: Stream control, video playback, slots
  * - Mod Tab: Scene admins, banned wallets, broadcast
- * - Custom Scene Tabs: Full/Custom tier
+ * - Custom Scene Tabs: Pro tier
  */
 
 declare class AdminPanelUIModule {
@@ -662,6 +746,8 @@ declare class AdminPanelUIModule {
     private customVideoUrl;
     private streamData;
     private streamFetched;
+    private videoState;
+    private videoStateFetched;
     private channelCreating;
     private channelCreateError;
     private channelDeleting;
@@ -682,8 +768,12 @@ declare class AdminPanelUIModule {
     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
+     * Initialize the admin panel - checks admin status and fetches video state
      */
     init(): Promise<void>;
     /**
@@ -694,6 +784,14 @@ declare class AdminPanelUIModule {
      * 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
      */
@@ -703,13 +801,22 @@ declare class AdminPanelUIModule {
      */
     get hasAccess(): boolean;
     /**
-     * Register a custom scene tab (Full/Custom tier)
-     */
+       * 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;
@@ -737,10 +844,10 @@ declare class AdminPanelUIModule {
 /**
  * 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
- * - pro: Full + Admin Panel (Video + Mod tabs)
+ * 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) */
@@ -750,38 +857,57 @@ declare class StaticTVClient {
     private config;
     private baseUrl;
     private _keyType;
+    private _keyId;
     private _disabled;
-    private _fullFeaturesEnabled;
+    private _tier;
+    private _standardFeaturesEnabled;
     private _proFeaturesEnabled;
-    /** Guide module - fetch channel lineup (full SDK only) */
+    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 SDK only) */
+    /** 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
      *
      * @param config Configuration options
      *
-     * @example
+     * @example Free tier (session tracking only):
+     * ```typescript
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_your_key_here'
+     * })
+     * ```
+     *
+     * @example Standard/Pro with video screen (SDK handles playback):
      * ```typescript
-     * let staticTV: StaticTVClient
+     * // Create your video screen
+     * const screen = engine.addEntity()
+     * Transform.create(screen, { position: Vector3.create(8, 3, 14), scale: Vector3.create(8, 4.5, 0.1) })
+     * MeshRenderer.setPlane(screen)
+     *
+     * // SDK handles everything - Guide selection + Pro admin controls just work
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_your_key_here',
+     *   videoScreen: screen  // That's it! SDK manages video playback
+     * })
      *
      * export function main() {
-     *   // All keys use dcls_ prefix - features determined by subscription
-     *   staticTV = new StaticTVClient({
-     *     apiKey: 'dcls_your_key_here'
-     *   })
-     *   // Session tracking starts automatically!
+     *   staticTV.setupUI()
      * }
      * ```
      */
@@ -795,8 +921,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;
     /**
@@ -805,28 +939,79 @@ 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;
+    private _currentVideoUrl;
+    /**
+     * Play a video on the configured videoScreen entity.
+     * Called by Guide UI and Admin Panel.
+     *
+     * @param url Video URL to play
+     */
+    playVideo(url: string): void;
+    /**
+     * Stop video playback on the configured videoScreen entity.
+     * Called by Admin Panel.
+     */
+    stopVideo(): void;
+    /**
+     * Get the currently playing video URL
+     */
+    get currentVideoUrl(): string;
+    /**
+     * Internal handler for Guide video selection
+     * @internal
+     */
+    _handleGuideVideoSelect(video: GuideVideo): void;
     /**
-     * Initialize full feature modules (guide, heartbeat, interactions, UI)
+     * Internal handler for broadcast messages
      * @internal
      */
-    private _initFullModules;
+    _handleBroadcast(text: string): void;
     /**
-     * Called by SessionModule when server confirms sdkType is 'full'
-     * Enables guide, chat, heartbeat, and interactions modules
+     * Initialize standard feature modules (guide, heartbeat, interactions, UI)
+     * @internal
+     */
+    private _initStandardModules;
+    /**
+     * Initialize pro feature modules (admin panel)
+     * @internal
+     */
+    private _initProModules;
+    /**
+     * 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;
     /**
@@ -834,52 +1019,122 @@ declare class StaticTVClient {
      */
     get hasProFeatures(): boolean;
     /**
-     * Get the SDK type (lite or full) - only available after session starts
+     * @deprecated Use `tier` instead
      */
     get sdkType(): 'lite' | 'full';
     /**
-     * Enable Pro features (Admin Panel with Video + Mod tabs)
-     * Call this after creating the client to add admin panel functionality.
+     * Configure Pro features (Admin Panel with Video + Mod tabs)
+     *
+     * **OPTIONAL**: If you set `videoScreen` in the constructor, you don't need
+     * to call this method - the Admin Panel will auto-enable with sensible defaults.
+     *
+     * Use this method only if you need:
+     * - Custom scene tab UI
+     * - Custom panel title/styling
+     * - Advanced command handlers
      *
      * @param config Admin panel configuration
      *
-     * @example
+     * @example Using videoScreen (recommended - no enableProFeatures needed):
      * ```typescript
-     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_...',
+     *   videoScreen: myScreen  // Admin Panel auto-enabled for Pro tier!
+     * })
+     * ```
      *
-     * // Enable admin panel
+     * @example Advanced: Custom scene tabs
+     * ```typescript
      * staticTV.enableProFeatures({
-     *   sceneId: 'my-scene',
      *   title: 'MY SCENE ADMIN',
-     *   onVideoPlay: (url) => videoPlayer.play(url),
-     *   onVideoStop: () => videoPlayer.stop(),
-     *   onBroadcast: (text) => showNotification(text)
+     *   sceneTabs: [{ label: 'LIGHTS', id: 'lights', render: () => <LightsTab /> }]
      * })
      * ```
      */
-    enableProFeatures(config: AdminPanelConfig): void;
+    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;
     /**
-     * Register a custom scene tab for the admin panel (Full/Custom tier)
-     * Must call enableProFeatures() first.
+     * 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.
      *
-     * @param tab The tab definition with label, id, and render function
+     * @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.registerSceneTab({
-     *   label: 'LIGHTS',
-     *   id: 'lights',
-     *   render: () => <MyLightsControls />
-     * })
+     * staticTV.showNotification('Stream started!')
+     * staticTV.showNotification('Custom message', 10000) // 10 seconds
      * ```
      */
-    registerSceneTab(tab: SceneTabDefinition): void;
+    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
@@ -904,4 +1159,4 @@ declare function getPlayerWallet(): string | null;
  */
 declare function getPlayerDisplayName(): string | null;
 
-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 SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, 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 };