@thestatic-tv/dcl-sdk 1.0.7 → 2.0.1

package/README.md

@@ -1,51 +1,65 @@
-# @thestatic/dcl-sdk
+# @thestatic-tv/dcl-sdk
 
 Connect your Decentraland scene to [thestatic.tv](https://thestatic.tv) - the decentralized streaming platform.
 
+[![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
 
-## Two Modes
+## 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** |
+
+> **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
 
-| Mode | Key Prefix | Features | Get Key From |
-|------|------------|----------|--------------|
-| **Full** | `dclk_` | Guide, Heartbeat, Sessions, Interactions | Studio (channel owners) |
-| **Lite** | `dcls_` | Sessions only (visitor tracking) | Profile (all users) |
+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.
 
-The SDK auto-detects your key type and enables/disables features accordingly.
+### Key Rotation
 
-> **Free Trial**: New accounts get 7 days of free visitor tracking!
+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:
+Clone our starter scene to get started quickly:
 
 ```bash
-git clone https://github.com/thestatic-tv/dcl-example.git
-cd dcl-example
+git clone https://github.com/thestatic-tv/thestatic-dcl-starter.git
+cd thestatic-dcl-starter
 npm install
 npm start
 ```
 
-See the [example repo](https://github.com/thestatic-tv/dcl-example) for a complete working scene.
+See the [starter repo](https://github.com/thestatic-tv/thestatic-dcl-starter) for a complete working scene.
 
 ## Installation
 
 ```bash
-npm install @thestatic/dcl-sdk
+npm install @thestatic-tv/dcl-sdk
 ```
 
 ## Quick Start
 
-1. Get your API key from [thestatic.tv/studio](https://thestatic.tv/studio) (DCL Integration tab)
+1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
 2. Initialize the client in your scene:
 
 ```typescript
-import { StaticTVClient } from '@thestatic/dcl-sdk'
+import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
 const staticTV = new StaticTVClient({
   apiKey: 'dclk_your_api_key_here',
@@ -96,12 +110,12 @@ await staticTV.destroy()
 
 If you don't have a channel but want to track visitors to your scene:
 
-1. Get a scene key from [thestatic.tv/profile](https://thestatic.tv/profile) (DCL Scenes tab)
+1. Get a scene key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
 2. Initialize with your scene key:
 
 ```typescript
-import { StaticTVClient } from '@thestatic/dcl-sdk'
+import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
 const staticTV = new StaticTVClient({
   apiKey: 'dcls_your_scene_key_here'
@@ -150,6 +164,8 @@ Main client class for interacting with thestatic.tv.
 | `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) |
 
 ### Guide Module (Full Mode Only)
 
@@ -192,6 +208,91 @@ 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
+// 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)
+    }
+  }
+})
+
+// Initialize the UI (call once after client is created)
+await staticTV.guideUI.init()
+
+// Show/hide the guide
+staticTV.guideUI.show()
+staticTV.guideUI.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
+// Configure in constructor
+const staticTV = new StaticTVClient({
+  apiKey: 'dclk_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()
+
+// 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')
+```
+
+### Rendering UI Components
+
+The UI modules provide `getComponent()` methods that return React-ECS elements. Call these in your UI renderer:
+
+```typescript
+import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+
+// In your scene setup
+ReactEcsRenderer.setUiRenderer(() => {
+  return (
+    <>
+      {/* Your other UI elements */}
+      {staticTV.guideUI?.getComponent()}
+      {staticTV.chatUI?.getComponent()}
+    </>
+  )
+})
+```
+
 ## Metrics Attribution
 
 This SDK implements dual attribution:

package/dist/index.d.mts

@@ -34,6 +34,14 @@ interface StaticTVConfig {
      * })
      */
     player?: PlayerData;
+    /**
+     * Guide UI configuration (channel keys only)
+     */
+    guideUI?: GuideUIConfig;
+    /**
+     * Chat UI configuration (channel keys only)
+     */
+    chatUI?: ChatUIConfig;
 }
 /**
  * Channel information from the guide
@@ -124,6 +132,75 @@ interface SceneStatsResponse {
     sceneName: string | null;
     version: string;
 }
+/**
+ * Video data for the guide UI
+ */
+interface GuideVideo {
+    id: string;
+    name: string;
+    src: string;
+    isLive?: boolean;
+    isCreator?: boolean;
+    channelId?: string;
+    duration?: number;
+    requiresAuth?: boolean;
+}
+/**
+ * Featured playlist for the guide UI
+ */
+interface GuideFeaturedPlaylist {
+    name: string;
+    videos: GuideVideo[];
+}
+/**
+ * Configuration options for GuideUIModule
+ */
+interface GuideUIConfig {
+    /**
+     * Callback when user selects a video
+     * Developer should handle playback
+     */
+    onVideoSelect?: (video: GuideVideo) => void;
+    /**
+     * Current video ID (for "PLAYING" indicator)
+     */
+    currentVideoId?: string;
+    /**
+     * UI scale multiplier (default: 1.0)
+     */
+    uiScale?: number;
+}
+/**
+ * Chat channel data
+ */
+interface ChatChannel {
+    id: string;
+    name: string;
+}
+/**
+ * Chat message data
+ */
+interface ChatMessage {
+    id: string;
+    username: string;
+    text: string;
+    uid: string;
+    createdAt: any;
+    isSystem?: boolean;
+}
+/**
+ * Configuration options for ChatUIModule
+ */
+interface ChatUIConfig {
+    /**
+     * Chat panel position (default: 'right')
+     */
+    position?: 'left' | 'center' | 'right';
+    /**
+     * Font scale multiplier (default: 1.0)
+     */
+    fontScale?: number;
+}
 
 /**
  * Guide module - fetch channel lineup from thestatic.tv
@@ -279,11 +356,176 @@ declare class InteractionsModule {
     follow(channelSlug: string): Promise<InteractionResponse | null>;
 }
 
+/**
+ * Guide UI Module - provides channel/video browser
+ */
+declare class GuideUIModule {
+    private client;
+    private config;
+    private _isVisible;
+    private videos;
+    private featuredPlaylists;
+    private liveVideos;
+    private activeTab;
+    private currentPage;
+    private itemsPerPage;
+    private searchQuery;
+    private uiScale;
+    private _currentVideoId;
+    constructor(client: StaticTVClient, config?: GuideUIConfig);
+    /**
+     * Initialize the guide - fetch channel data
+     */
+    init(): Promise<void>;
+    /**
+     * Show the guide UI
+     */
+    show(): void;
+    /**
+     * Hide the guide UI
+     */
+    hide(): void;
+    /**
+     * Toggle guide visibility
+     */
+    toggle(): void;
+    /**
+     * Check if guide is visible
+     */
+    get isVisible(): boolean;
+    /**
+     * Set the currently playing video ID (for "PLAYING" indicator)
+     */
+    set currentVideoId(id: string | null);
+    /**
+     * Get the currently playing video ID
+     */
+    get currentVideoId(): string | null;
+    /**
+     * Get all videos
+     */
+    getVideos(): GuideVideo[];
+    /**
+     * Get live videos only
+     */
+    getLiveVideos(): GuideVideo[];
+    /**
+     * Refresh guide data
+     */
+    refresh(): Promise<void>;
+    private getBaseUrl;
+    private fetchGuideData;
+    private s;
+    private handleVideoSelect;
+    private handleChannelClick;
+    /**
+     * Get the guide UI component for rendering
+     */
+    getComponent: () => any;
+    private renderLeftPanel;
+    private renderMenuButton;
+    private renderRightPanel;
+    private renderCardGrid;
+    private renderGuideCard;
+    private renderCloseButton;
+}
+
+/**
+ * Chat UI Module - provides real-time chat functionality
+ */
+declare class ChatUIModule {
+    private client;
+    private config;
+    private _isVisible;
+    private _unreadCount;
+    private idToken;
+    private isSigningIn;
+    private isRegisteredUser;
+    private currentUsername;
+    private currentUserId;
+    private channels;
+    private currentChannelId;
+    private showChannelDropdown;
+    private channelPage;
+    private realMessages;
+    private systemMessages;
+    private inputText;
+    private chatScrollOffset;
+    private position;
+    private fontScale;
+    private chatTimerId;
+    private playerInfoTimerId;
+    private isInitialized;
+    constructor(client: StaticTVClient, config?: ChatUIConfig);
+    /**
+     * Initialize the chat system
+     */
+    init(): Promise<void>;
+    /**
+     * Show the chat UI
+     */
+    show(): void;
+    /**
+     * Hide the chat UI
+     */
+    hide(): void;
+    /**
+     * Toggle chat visibility
+     */
+    toggle(): void;
+    /**
+     * Check if chat is visible
+     */
+    get isVisible(): boolean;
+    /**
+     * Get unread message count
+     */
+    get unreadCount(): number;
+    /**
+     * Get current channel ID
+     */
+    get currentChannel(): string;
+    /**
+     * Switch to a different channel
+     */
+    setChannel(channelId: string): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    private getBaseUrl;
+    private performAuth;
+    private fetchChannels;
+    private fetchMessages;
+    private handleSend;
+    private generateBootSequence;
+    private fetchPlayerInfo;
+    private switchChannel;
+    private startChatLoop;
+    private chatLoop;
+    private resetChatTimer;
+    private parseServerTime;
+    private formatTime;
+    /**
+     * Get the chat UI component for rendering
+     */
+    getComponent: () => any;
+    private getPositionStyle;
+    private renderHeader;
+    private renderChannelButton;
+    private renderMessagesArea;
+    private renderSystemMessage;
+    private renderChatMessage;
+    private renderUserInfoBar;
+    private renderInputArea;
+    private renderChannelDropdown;
+}
+
 /**
  * StaticTVClient - Main client for connecting DCL scenes to thestatic.tv
  *
  * Supports two key types:
- * - dclk_* : Channel keys (full access - guide, heartbeat, interactions)
+ * - dclk_* : Channel keys (full access - guide, heartbeat, interactions, UI)
  * - dcls_* : Scene-only keys (lite - session tracking only)
  */
 
@@ -302,6 +544,10 @@ declare class StaticTVClient {
     readonly heartbeat: HeartbeatModule | null;
     /** Interactions module - like/follow channels (channel keys only) */
     readonly interactions: InteractionsModule | null;
+    /** Guide UI module - channel browser UI (channel keys only) */
+    readonly guideUI: GuideUIModule | null;
+    /** Chat UI module - real-time chat UI (channel keys only) */
+    readonly chatUI: ChatUIModule | null;
     /**
      * Create a new StaticTVClient
      *
@@ -375,4 +621,4 @@ declare function getPlayerWallet(): string | null;
  */
 declare function getPlayerDisplayName(): string | null;
 
-export { type Channel, GuideModule, type GuideResponse, 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 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 };