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

package/README.md

@@ -5,475 +5,117 @@ Connect your Decentraland scene to [thestatic.tv](https://thestatic.tv) - the de
 [![npm version](https://img.shields.io/npm/v/@thestatic-tv/dcl-sdk?color=00e5e5)](https://www.npmjs.com/package/@thestatic-tv/dcl-sdk)
 [![DCL SDK](https://img.shields.io/badge/DCL%20SDK-7.x-blue)](https://docs.decentraland.org/)
 
-This SDK allows DCL scene builders to:
-- Track visitors to your Decentraland scene
-- Display the full thestatic.tv channel lineup in their scenes
-- Track video watching metrics
-- Enable likes/follows from within DCL
-- Get referral credit for driving traffic to channels
+## Features
 
-## Pricing
+- **Visitor Analytics** - Track visitors and session metrics
+- **Channel Guide** - Display live streams and VODs in your scene
+- **Watch Metrics** - Track video viewing time
+- **Interactions** - Enable likes/follows from within DCL
+- **Built-in UI** - Pre-built Guide and Chat components
+- **Admin Panel** - In-scene controls for Pro tier
 
-| Tier | Price | Features |
-|------|-------|----------|
-| **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.
->
-> **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.
-
-Get your key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) → DCL Scenes tab.
-
-### Coordinate Locking
-
-When you create a scene key, you'll be asked to confirm your parcel coordinates. **Once confirmed, coordinates are permanently locked** to prevent key reuse across different scenes. This ensures analytics accurately reflect a single scene.
-
-### Key Rotation
-
-If you need to rotate your API key (e.g., if compromised), you can do so from the dashboard without losing your subscription or analytics history. The old key is immediately invalidated.
-
-## Example Scene
-
-Clone our example scene to get started quickly:
-
-```bash
-git clone https://github.com/thestatic-tv/thestatic-dcl-example.git
-cd thestatic-dcl-example
-npm install
-npm start
-```
+## Quick Start
 
-See the [example repo](https://github.com/thestatic-tv/thestatic-dcl-example) for a complete working scene with video player integration.
+1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
-## Installation
+2. Install the SDK:
 
 ```bash
 npm install @thestatic-tv/dcl-sdk
 ```
 
-## Quick Start
-
-1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
-
-2. Initialize the client in your scene's `main()` function:
+3. Initialize in your scene:
 
 ```typescript
-import {} from '@dcl/sdk/math'
-import { engine } from '@dcl/sdk/ecs'
 import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
 let staticTV: StaticTVClient
 
 export function main() {
   staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key_here'
+    apiKey: 'your_api_key_here'
   })
-  // Session tracking starts automatically!
+  // Session tracking starts automatically
 }
 ```
 
-3. Fetch channels and display them (Full mode only):
-
-```typescript
-// Get all channels
-const channels = await staticTV.guide.getChannels()
+## Example Scene
 
-// Get only live channels
-const liveChannels = await staticTV.guide.getLiveChannels()
+Clone our starter scene to get up and running quickly:
 
-// Get a specific channel
-const channel = await staticTV.guide.getChannel('channel-slug')
+```bash
+git clone https://github.com/thestatic-tv/thestatic-dcl-starter.git
+cd thestatic-dcl-starter
+npm install
+npm start
 ```
 
-4. Track video watching:
+## Basic Usage
 
 ```typescript
-// When user enters video viewing area
-staticTV.heartbeat.startWatching('channel-slug')
+// Get channels (Standard/Pro tier)
+const channels = await staticTV.guide.getChannels()
+const liveChannels = await staticTV.guide.getLiveChannels()
 
-// When user leaves video viewing area
+// Track video watching
+staticTV.heartbeat.startWatching('channel-slug')
 staticTV.heartbeat.stopWatching()
-```
-
-5. Enable interactions:
 
-```typescript
-// Like a channel (requires wallet connection)
+// User interactions (requires wallet)
 await staticTV.interactions.like('channel-slug')
-
-// Follow a channel
 await staticTV.interactions.follow('channel-slug')
-```
 
-6. Cleanup before scene unload:
+// Check your tier
+console.log('Tier:', staticTV.tier) // 'free', 'standard', or 'pro'
 
-```typescript
+// Cleanup
 await staticTV.destroy()
 ```
 
-## Lite Mode (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 in `main()`:
-
-```typescript
-import {} from '@dcl/sdk/math'
-import { engine } from '@dcl/sdk/ecs'
-import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
-
-let staticTV: StaticTVClient
-
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_scene_key_here'
-  })
-  // Session tracking starts automatically!
-}
-```
-
-3. Check if running in lite mode:
-
-```typescript
-if (staticTV.isLite) {
-  console.log('Running in lite mode - session tracking only')
-}
-
-// guide, heartbeat, and interactions are null in lite mode
-if (staticTV.guide) {
-  const channels = await staticTV.guide.getChannels()
-}
-```
-
-## API Reference
-
-### StaticTVClient
-
-Main client class for interacting with thestatic.tv.
-
-#### Constructor Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `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) |
-| `debug` | `boolean` | `false` | Enable debug logging |
-
-#### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `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)
-
-```typescript
-staticTV.guide.getChannels()       // Get all channels (cached 30s)
-staticTV.guide.getLiveChannels()   // Get only live channels
-staticTV.guide.getChannel(slug)    // Get a specific channel
-staticTV.guide.getVods()           // Get VODs
-staticTV.guide.clearCache()        // Clear the channel cache
-```
-
-### Session Module
-
-Session tracking starts automatically by default.
-
-```typescript
-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
-```
-
-### Heartbeat Module (Full Mode Only)
-
-Track video watching. Each heartbeat represents 1 minute watched.
-
-```typescript
-staticTV.heartbeat.startWatching(channelSlug)  // Start tracking
-staticTV.heartbeat.stopWatching()               // Stop tracking
-staticTV.heartbeat.getCurrentChannel()          // Get currently watched channel
-staticTV.heartbeat.isCurrentlyWatching()        // Check if watching
-```
-
-### Interactions Module (Full Mode Only)
+## Built-in UI Components
 
-Like and follow channels. Requires wallet connection.
+The SDK includes pre-built UI for channel browsing and chat:
 
 ```typescript
-staticTV.interactions.like(channelSlug)   // Like a channel
-staticTV.interactions.follow(channelSlug) // Follow a channel
-```
-
-### Guide UI Module (Full Mode Only)
-
-Built-in channel browser UI. You provide a callback to handle video selection.
-
-```typescript
-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)
-      }
+staticTV = new StaticTVClient({
+  apiKey: 'your_api_key',
+  guideUI: {
+    onVideoSelect: (video) => {
+      // Handle video playback
+      console.log('Playing:', video.name)
     }
-  })
+  },
+  chatUI: {
+    position: 'right'
+  }
+})
 
-  // Initialize the UI (call once after client is created)
-  staticTV.guideUI.init()
-}
+// Initialize UI components
+staticTV.guideUI.init()
+staticTV.chatUI.init()
 
-// Show/hide the guide
-staticTV.guideUI.show()
-staticTV.guideUI.hide()
+// Show/hide
 staticTV.guideUI.toggle()
-
-// Check visibility
-if (staticTV.guideUI.isVisible) { ... }
-
-// Update "PLAYING" indicator
-staticTV.guideUI.currentVideoId = 'video-id'
-
-// Refresh data
-await staticTV.guideUI.refresh()
-```
-
-### Chat UI Module (Full Mode Only)
-
-Real-time chat with Firebase authentication.
-
-```typescript
-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)
-  staticTV.chatUI.init()
-}
-
-// Show/hide the chat
-staticTV.chatUI.show()
-staticTV.chatUI.hide()
 staticTV.chatUI.toggle()
-
-// Check visibility
-if (staticTV.chatUI.isVisible) { ... }
-
-// Get unread message count (for badge display)
-const unread = staticTV.chatUI.unreadCount
-
-// Switch channels
-staticTV.chatUI.setChannel('channel-slug')
 ```
 
-### Admin Panel Module (Pro Tier)
+## Pricing & Tiers
 
-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
+See [thestatic.tv/info](https://thestatic.tv/info) for current pricing and tier features.
 
-```typescript
-import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
-import ReactEcs, { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+All new keys include a **7-day free trial**.
 
-let staticTV: StaticTVClient
+## Documentation
 
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key'
-  })
+Full API reference and Pro tier features (Admin Panel, Custom Tabs) available at:
 
-  // 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 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
-
-This SDK implements dual attribution:
-
-- **Watched Channel**: Gets view metrics (minutes watched, likes, follows)
-- **Scene Owner**: Gets referral metrics (unique visitors, traffic driven)
-
-Your channel (linked to your API key) receives credit for all traffic your scene drives to thestatic.tv channels.
-
-## Types
-
-```typescript
-interface Channel {
-  id: string
-  slug: string
-  name: string
-  streamUrl: string
-  isLive: boolean
-  currentViewers: number
-  poster: string | null
-  logo: string | null
-  description: string
-}
-
-interface Vod {
-  id: string
-  title: string
-  url: string
-  thumbnail: string | null
-  channelId: string
-}
-```
-
-## Requirements
-
-- Decentraland SDK 7.0.0 or higher
-- API key from thestatic.tv
+- **Docs**: [thestatic.tv/info](https://thestatic.tv/info)
+- **Examples**: [github.com/thestatic-tv/thestatic-dcl-starter](https://github.com/thestatic-tv/thestatic-dcl-starter)
 
 ## Support
 
-- Documentation: [thestatic.tv/info](https://thestatic.tv/info)
-- Issues: [GitHub Issues](https://github.com/thestatic-tv/dcl-sdk/issues)
 - Discord: [thestatic.tv Discord](https://discord.gg/thestatic)
+- Issues: [GitHub Issues](https://github.com/thestatic-tv/dcl-sdk/issues)
 
 ## License