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

package/README.md

@@ -14,10 +14,12 @@ This SDK allows DCL scene builders to:
 
 ## Pricing
 
-| Mode | Price | Features |
+| Tier | Price | Features |
 |------|-------|----------|
-| **Lite** | $5/mo | Session/visitor tracking only |
-| **Full** | $10/mo | Guide UI, Chat UI, Heartbeat, Sessions, Interactions |
+| **Lite** | $5/mo | Session/visitor tracking, Guide button, Chat button |
+| **Full** | $10/mo | Lite + Guide UI, Chat UI, Heartbeat, Interactions |
+| **Pro** | $15/mo | Full + Admin Panel (Video tab, Mod tab) |
+| **Custom** | $20/mo | Pro + Custom scene tabs for scene-specific controls |
 
 > **All keys use `dcls_` prefix** - the server determines your subscription level.
 >
@@ -37,16 +39,16 @@ If you need to rotate your API key (e.g., if compromised), you can do so from th
 
 ## Example Scene
 
-Clone our starter scene to get started quickly:
+Clone our example scene to get started quickly:
 
 ```bash
-git clone https://github.com/thestatic-tv/thestatic-dcl-starter.git
-cd thestatic-dcl-starter
+git clone https://github.com/thestatic-tv/thestatic-dcl-example.git
+cd thestatic-dcl-example
 npm install
 npm start
 ```
 
-See the [starter repo](https://github.com/thestatic-tv/thestatic-dcl-starter) for a complete working scene.
+See the [example repo](https://github.com/thestatic-tv/thestatic-dcl-example) for a complete working scene with video player integration.
 
 ## Installation
 
@@ -58,18 +60,24 @@ npm install @thestatic-tv/dcl-sdk
 
 1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
-2. Initialize the client in your scene:
+2. Initialize the client in your scene's `main()` function:
 
 ```typescript
+import {} from '@dcl/sdk/math'
+import { engine } from '@dcl/sdk/ecs'
 import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
-const staticTV = new StaticTVClient({
-  apiKey: 'dcls_your_api_key_here',
-  debug: true // Enable for development
-})
+let staticTV: StaticTVClient
+
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_api_key_here'
+  })
+  // Session tracking starts automatically!
+}
 ```
 
-3. Fetch channels and display them:
+3. Fetch channels and display them (Full mode only):
 
 ```typescript
 // Get all channels
@@ -114,17 +122,21 @@ If you don't have a channel but want to track visitors to your scene:
 
 1. Get a scene key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
-2. Initialize with your scene key:
+2. Initialize with your scene key in `main()`:
 
 ```typescript
+import {} from '@dcl/sdk/math'
+import { engine } from '@dcl/sdk/ecs'
 import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
-const staticTV = new StaticTVClient({
-  apiKey: 'dcls_your_scene_key_here'
-})
+let staticTV: StaticTVClient
 
-// Session tracking starts automatically
-// Visitors are tracked when they enter your scene
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_scene_key_here'
+  })
+  // Session tracking starts automatically!
+}
 ```
 
 3. Check if running in lite mode:
@@ -162,12 +174,22 @@ Main client class for interacting with thestatic.tv.
 |----------|------|-------------|
 | `keyType` | `'channel' \| 'scene'` | The detected key type |
 | `isLite` | `boolean` | `true` if using a scene key (lite mode) |
+| `hasProFeatures` | `boolean` | `true` if pro features are enabled |
 | `guide` | `GuideModule \| null` | Guide module (null in lite mode) |
 | `session` | `SessionModule` | Session module (always available) |
 | `heartbeat` | `HeartbeatModule \| null` | Heartbeat module (null in lite mode) |
 | `interactions` | `InteractionsModule \| null` | Interactions module (null in lite mode) |
 | `guideUI` | `GuideUIModule \| null` | Guide UI module (null in lite mode) |
 | `chatUI` | `ChatUIModule \| null` | Chat UI module (null in lite mode) |
+| `adminPanel` | `AdminPanelUIModule \| null` | Admin panel (null until enableProFeatures() called) |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `enableProFeatures(config)` | Enable Pro tier admin panel |
+| `registerSceneTab(tab)` | Add custom scene tab (Custom tier) |
+| `destroy()` | Cleanup before scene unload |
 
 ### Guide Module (Full Mode Only)
 
@@ -215,19 +237,22 @@ staticTV.interactions.follow(channelSlug) // Follow a channel
 Built-in channel browser UI. You provide a callback to handle video selection.
 
 ```typescript
-// Configure in constructor
-const staticTV = new StaticTVClient({
-  apiKey: 'dcls_your_api_key',
-  guideUI: {
-    onVideoSelect: (video) => {
-      // Handle video playback in your scene
-      console.log('Playing:', video.name, video.src)
+let staticTV: StaticTVClient
+
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_api_key',
+    guideUI: {
+      onVideoSelect: (video) => {
+        // Handle video playback in your scene
+        console.log('Playing:', video.name, video.src)
+      }
     }
-  }
-})
+  })
 
-// Initialize the UI (call once after client is created)
-await staticTV.guideUI.init()
+  // Initialize the UI (call once after client is created)
+  staticTV.guideUI.init()
+}
 
 // Show/hide the guide
 staticTV.guideUI.show()
@@ -249,17 +274,20 @@ await staticTV.guideUI.refresh()
 Real-time chat with Firebase authentication.
 
 ```typescript
-// Configure in constructor
-const staticTV = new StaticTVClient({
-  apiKey: 'dcls_your_api_key',
-  chatUI: {
-    position: 'right',  // 'left', 'center', or 'right'
-    fontScale: 1.0
-  }
-})
+let staticTV: StaticTVClient
+
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_api_key',
+    chatUI: {
+      position: 'right',  // 'left', 'center', or 'right'
+      fontScale: 1.0
+    }
+  })
 
-// Initialize the chat (call once after client is created)
-await staticTV.chatUI.init()
+  // Initialize the chat (call once after client is created)
+  staticTV.chatUI.init()
+}
 
 // Show/hide the chat
 staticTV.chatUI.show()
@@ -276,23 +304,131 @@ const unread = staticTV.chatUI.unreadCount
 staticTV.chatUI.setChannel('channel-slug')
 ```
 
-### Rendering UI Components
+### Admin Panel Module (Pro Tier)
 
-The UI modules provide `getComponent()` methods that return React-ECS elements. Call these in your UI renderer:
+In-scene admin panel with Video and Mod tabs. Allows scene owners/admins to:
+- Control live streaming (start/stop, rotate keys)
+- Play videos from URL or predefined slots
+- Manage scene admins and banned wallets
+- Send broadcast messages to all players
 
 ```typescript
-import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
+import ReactEcs, { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
 
-// In your scene setup
+let staticTV: StaticTVClient
+
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_api_key'
+  })
+
+  // Enable admin panel (Pro tier)
+  staticTV.enableProFeatures({
+    sceneId: 'my-scene',           // Your scene ID from thestatic.tv
+    title: 'MY SCENE ADMIN',       // Panel header title
+    onVideoPlay: (url) => {
+      // Handle video playback in your scene
+      videoPlayer.play(url)
+    },
+    onVideoStop: () => {
+      videoPlayer.stop()
+    },
+    onVideoSlotPlay: (slot) => {
+      // Play a predefined video slot (slot1-slot5)
+      fetchAndPlaySlot(slot)
+    },
+    onBroadcast: (text) => {
+      // Show notification to all players
+      showNotification(text)
+    },
+    onCommand: (type, payload) => {
+      // Handle custom commands (kickAll, kickBanned, etc.)
+      handleCommand(type, payload)
+    }
+  })
+}
+
+// Render the admin panel
 ReactEcsRenderer.setUiRenderer(() => {
-  return (
-    <>
-      {/* Your other UI elements */}
-      {staticTV.guideUI?.getComponent()}
-      {staticTV.chatUI?.getComponent()}
-    </>
+  return staticTV.adminPanel?.getComponent()
+})
+
+// Toggle panel visibility
+staticTV.adminPanel.toggle()
+
+// Check if user has admin access
+if (staticTV.adminPanel.hasAccess) { ... }
+```
+
+#### Admin Panel Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sceneId` | `string` | required | Scene ID for API calls |
+| `title` | `string` | `'ADMIN PANEL'` | Header title |
+| `headerColor` | `{r,g,b,a}` | red | Header background color |
+| `showVideoTab` | `boolean` | `true` | Show Video tab |
+| `showModTab` | `boolean` | `true` | Show Mod tab (owners only) |
+| `onVideoPlay` | `(url) => void` | - | Called when video should play |
+| `onVideoStop` | `() => void` | - | Called when video should stop |
+| `onVideoSlotPlay` | `(slot) => void` | - | Called when slot is selected |
+| `onBroadcast` | `(text) => void` | - | Called for broadcast messages |
+| `onCommand` | `(type, payload) => void` | - | Called for custom commands |
+| `footerLink` | `string` | scene page | Link shown in footer |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+### Custom Scene Tabs (Custom Tier)
+
+Add your own scene-specific control tabs to the admin panel:
+
+```typescript
+import ReactEcs, { UiEntity, Button, Label } from '@dcl/sdk/react-ecs'
+
+// Enable pro features first
+staticTV.enableProFeatures({ sceneId: 'my-scene', ... })
+
+// Register custom tabs
+staticTV.registerSceneTab({
+  label: 'LIGHTS',
+  id: 'lights',
+  render: () => (
+    <UiEntity uiTransform={{ flexDirection: 'column', padding: 8 }}>
+      <Label value="Light Controls" fontSize={14} />
+      <Button value="Disco Mode" onMouseDown={() => setDiscoLights()} />
+      <Button value="Ambient" onMouseDown={() => setAmbientLights()} />
+      <Button value="Off" onMouseDown={() => turnOffLights()} />
+    </UiEntity>
   )
 })
+
+staticTV.registerSceneTab({
+  label: 'DOORS',
+  id: 'doors',
+  render: () => <MyDoorsControls />
+})
+```
+
+Custom tabs appear before the Video and Mod tabs in the tab bar.
+
+### Rendering UI Components
+
+The UI modules provide `getComponent()` methods that return React-ECS elements. Add the renderer **outside** your `main()` function:
+
+```typescript
+import ReactEcs, { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'
+
+// Outside main() - required by DCL
+ReactEcsRenderer.setUiRenderer(() => {
+  if (!staticTV) return null
+  return ReactEcs.createElement(UiEntity, {
+    uiTransform: { width: '100%', height: '100%', positionType: 'absolute' },
+    children: [
+      staticTV.guideUI?.getComponent(),
+      staticTV.chatUI?.getComponent()
+    ].filter(Boolean)
+  })
+})
 ```
 
 ## Metrics Attribution

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import ReactEcs from '@dcl/sdk/react-ecs';
+
 /**
  * Player identity data from DCL
  */
@@ -203,6 +205,111 @@ 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 Full/Custom 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: () => any;
+}
+/**
+ * Configuration options for AdminPanelModule
+ */
+interface AdminPanelConfig {
+    /**
+     * Scene ID for API calls
+     */
+    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 (Full/Custom tier only)
+     */
+    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;
+}
 
 /**
  * Guide module - fetch channel lineup from thestatic.tv
@@ -534,12 +641,106 @@ 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: Full/Custom 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 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;
+    /**
+     * Initialize the admin panel - checks admin status
+     */
+    init(): Promise<void>;
+    /**
+     * Check if current player is an admin for this scene
+     */
+    checkAdminStatus(): Promise<void>;
+    /**
+     * Toggle the admin panel open/closed
+     */
+    toggle(): 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 (Full/Custom tier)
+     */
+    registerSceneTab(tab: SceneTabDefinition): void;
+    private startStreamPolling;
+    private stopStreamPolling;
+    private fetchStreamData;
+    private refreshStreamStatus;
+    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
+ * - pro: Full + Admin Panel (Video + Mod tabs)
  */
 
 /** Key type constants (legacy - kept for compatibility) */
@@ -551,6 +752,7 @@ declare class StaticTVClient {
     private _keyType;
     private _disabled;
     private _fullFeaturesEnabled;
+    private _proFeaturesEnabled;
     /** Guide module - fetch channel lineup (full SDK only) */
     guide: GuideModule | null;
     /** Session module - track visitor sessions (all keys, null when disabled) */
@@ -563,6 +765,8 @@ declare class StaticTVClient {
     guideUI: GuideUIModule | null;
     /** Chat UI module - real-time chat UI (full SDK only) */
     chatUI: ChatUIModule | null;
+    /** Admin Panel module - Video/Mod tabs (pro SDK only) */
+    adminPanel: AdminPanelUIModule | null;
     /**
      * Create a new StaticTVClient
      *
@@ -570,16 +774,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);
@@ -626,10 +829,51 @@ declare class StaticTVClient {
      * Check if full features are enabled (server confirmed sdkType: 'full')
      */
     get hasFullFeatures(): boolean;
+    /**
+     * Check if pro features are enabled (admin panel)
+     */
+    get hasProFeatures(): boolean;
     /**
      * Get the SDK type (lite or full) - only available after session starts
      */
     get sdkType(): 'lite' | 'full';
+    /**
+     * Enable Pro features (Admin Panel with Video + Mod tabs)
+     * Call this after creating the client to add admin panel functionality.
+     *
+     * @param config Admin panel configuration
+     *
+     * @example
+     * ```typescript
+     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     *
+     * // Enable admin panel
+     * staticTV.enableProFeatures({
+     *   sceneId: 'my-scene',
+     *   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 (Full/Custom 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;
     /**
      * Cleanup when done (call before scene unload)
      */
@@ -660,4 +904,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 SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerWallet };