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

package/README.md

@@ -14,11 +14,14 @@ This SDK allows DCL scene builders to:
 
 ## Pricing
 
-| Mode | Price | Key Prefix | Features |
-|------|-------|------------|----------|
-| **Lite** | $5/mo | `dcls_` | Session/visitor tracking only |
-| **Full** | $10/mo | `dclk_` | Guide, Heartbeat, Sessions, Interactions, **Guide UI**, **Chat UI** |
+| Tier | Price | Features |
+|------|-------|----------|
+| **Free** | $5/mo | Session/visitor tracking only |
+| **Standard** | $10/mo | Free + Guide UI, Chat UI, Heartbeat, Interactions |
+| **Pro** | $15/mo | Standard + Admin Panel (Video tab, Mod tab, Custom scene tabs) |
 
+> **All keys use `dcls_` prefix** - the server determines your subscription level.
+>
 > **Free Trial**: All new scene keys include a 7-day free trial!
 >
 > **Expiry Warnings**: You'll receive dashboard notifications at 7, 3, and 1 days before your subscription expires.
@@ -35,16 +38,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
 
@@ -56,18 +59,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: 'dclk_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
@@ -106,33 +115,40 @@ await staticTV.interactions.follow('channel-slug')
 await staticTV.destroy()
 ```
 
-## Lite Mode (Visitor Tracking Only)
+## Free Tier (Visitor Tracking Only)
 
 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:
+3. Check the current tier:
 
 ```typescript
-if (staticTV.isLite) {
-  console.log('Running in lite mode - session tracking only')
+// Check tier (free, standard, or pro)
+console.log('Current tier:', staticTV.tier)
+
+if (staticTV.isFree) {
+  console.log('Running in free tier - session tracking only')
 }
 
-// guide, heartbeat, and interactions are null in lite mode
+// guide, heartbeat, and interactions are null in free tier
 if (staticTV.guide) {
   const channels = await staticTV.guide.getChannels()
 }
@@ -148,7 +164,7 @@ Main client class for interacting with thestatic.tv.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `apiKey` | `string` | required | Your API key (`dclk_` for full, `dcls_` for lite) |
+| `apiKey` | `string` | required | Your API key (all keys use `dcls_` prefix) |
 | `autoStartSession` | `boolean` | `true` | Automatically start session tracking |
 | `sessionHeartbeatInterval` | `number` | `30000` | Session heartbeat interval (ms) |
 | `watchHeartbeatInterval` | `number` | `60000` | Watch heartbeat interval (ms) |
@@ -159,15 +175,28 @@ Main client class for interacting with thestatic.tv.
 | Property | Type | Description |
 |----------|------|-------------|
 | `keyType` | `'channel' \| 'scene'` | The detected key type |
-| `isLite` | `boolean` | `true` if using a scene key (lite mode) |
-| `guide` | `GuideModule \| null` | Guide module (null in lite mode) |
+| `tier` | `'free' \| 'standard' \| 'pro'` | Current subscription tier |
+| `isFree` | `boolean` | `true` if free tier (session tracking only) |
+| `hasStandardFeatures` | `boolean` | `true` if standard features enabled |
+| `hasProFeatures` | `boolean` | `true` if pro features enabled |
+| `guide` | `GuideModule \| null` | Guide module (null in free tier) |
 | `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) |
+| `heartbeat` | `HeartbeatModule \| null` | Heartbeat module (null in free tier) |
+| `interactions` | `InteractionsModule \| null` | Interactions module (null in free tier) |
+| `guideUI` | `GuideUIModule \| null` | Guide UI module (null in free tier) |
+| `chatUI` | `ChatUIModule \| null` | Chat UI module (null in free tier) |
+| `adminPanel` | `AdminPanelUIModule \| null` | Admin panel (null until enableProFeatures() called) |
+| `isLite` | `boolean` | **Deprecated**: Use `isFree` instead |
 
-### Guide Module (Full Mode Only)
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `enableProFeatures(config)` | Enable Pro tier admin panel |
+| `registerSceneTab(tab)` | Add custom scene tab (Pro tier) |
+| `destroy()` | Cleanup before scene unload |
+
+### Guide Module (Standard/Pro Tier)
 
 ```typescript
 staticTV.guide.getChannels()       // Get all channels (cached 30s)
@@ -186,9 +215,18 @@ staticTV.session.startSession()    // Manually start session
 staticTV.session.endSession()      // End session
 staticTV.session.getSessionId()    // Get current session ID
 staticTV.session.isSessionActive() // Check if session is active
+
+// Get scene stats (visitors, sessions, etc.)
+const stats = await staticTV.session.getStats()
+if (stats) {
+  console.log('Total sessions today:', stats.totalSessions)
+  console.log('Unique visitors:', stats.uniqueVisitors)
+  console.log('Total minutes watched:', stats.totalMinutes)
+  console.log('You are visitor #', stats.visitorNumber)
+}
 ```
 
-### Heartbeat Module (Full Mode Only)
+### Heartbeat Module (Standard/Pro Tier)
 
 Track video watching. Each heartbeat represents 1 minute watched.
 
@@ -199,7 +237,7 @@ staticTV.heartbeat.getCurrentChannel()          // Get currently watched channel
 staticTV.heartbeat.isCurrentlyWatching()        // Check if watching
 ```
 
-### Interactions Module (Full Mode Only)
+### Interactions Module (Standard/Pro Tier)
 
 Like and follow channels. Requires wallet connection.
 
@@ -208,24 +246,27 @@ staticTV.interactions.like(channelSlug)   // Like a channel
 staticTV.interactions.follow(channelSlug) // Follow a channel
 ```
 
-### Guide UI Module (Full Mode Only)
+### Guide UI Module (Standard/Pro Tier)
 
 Built-in channel browser UI. You provide a callback to handle video selection.
 
 ```typescript
-// Configure in constructor
-const staticTV = new StaticTVClient({
-  apiKey: 'dclk_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()
@@ -242,22 +283,25 @@ staticTV.guideUI.currentVideoId = 'video-id'
 await staticTV.guideUI.refresh()
 ```
 
-### Chat UI Module (Full Mode Only)
+### Chat UI Module (Standard/Pro Tier)
 
 Real-time chat with Firebase authentication.
 
 ```typescript
-// Configure in constructor
-const staticTV = new StaticTVClient({
-  apiKey: 'dclk_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()
@@ -274,23 +318,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'
+
+let staticTV: StaticTVClient
+
+export function main() {
+  staticTV = new StaticTVClient({
+    apiKey: 'dcls_your_api_key'
+  })
+
+  // Enable admin panel (Pro tier)
+  staticTV.enableProFeatures({
+    // sceneId is optional - defaults to your API key ID
+    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)
+    }
+  })
+}
 
-// In your scene setup
+// 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` | API key ID | Scene ID for API calls (optional - defaults to your API key ID) |
+| `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 (Pro 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