@thestatic-tv/dcl-sdk 1.0.0

package/README.md

@@ -0,0 +1,241 @@
+# @thestatic/dcl-sdk
+
+Connect your Decentraland scene to [thestatic.tv](https://thestatic.tv) - the decentralized streaming platform.
+
+This SDK allows DCL scene builders to:
+- 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
+
+| 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) |
+
+The SDK auto-detects your key type and enables/disables features accordingly.
+
+> **Free Trial**: New accounts get 7 days of free visitor tracking!
+
+## Example Scene
+
+Clone our example scene to get started quickly:
+
+```bash
+git clone https://github.com/thestatic-tv/dcl-example.git
+cd dcl-example
+npm install
+npm start
+```
+
+See the [example repo](https://github.com/thestatic-tv/dcl-example) for a complete working scene.
+
+## Installation
+
+```bash
+npm install @thestatic/dcl-sdk
+```
+
+## Quick Start
+
+1. Get your API key from [thestatic.tv/studio](https://thestatic.tv/studio) (DCL Integration tab)
+
+2. Initialize the client in your scene:
+
+```typescript
+import { StaticTVClient } from '@thestatic/dcl-sdk'
+
+const staticTV = new StaticTVClient({
+  apiKey: 'dclk_your_api_key_here',
+  debug: true // Enable for development
+})
+```
+
+3. Fetch channels and display them:
+
+```typescript
+// Get all channels
+const channels = await staticTV.guide.getChannels()
+
+// Get only live channels
+const liveChannels = await staticTV.guide.getLiveChannels()
+
+// Get a specific channel
+const channel = await staticTV.guide.getChannel('channel-slug')
+```
+
+4. Track video watching:
+
+```typescript
+// When user enters video viewing area
+staticTV.heartbeat.startWatching('channel-slug')
+
+// When user leaves video viewing area
+staticTV.heartbeat.stopWatching()
+```
+
+5. Enable interactions:
+
+```typescript
+// Like a channel (requires wallet connection)
+await staticTV.interactions.like('channel-slug')
+
+// Follow a channel
+await staticTV.interactions.follow('channel-slug')
+```
+
+6. Cleanup before scene unload:
+
+```typescript
+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/profile](https://thestatic.tv/profile) (DCL Scenes tab)
+
+2. Initialize with your scene key:
+
+```typescript
+import { StaticTVClient } from '@thestatic/dcl-sdk'
+
+const staticTV = new StaticTVClient({
+  apiKey: 'dcls_your_scene_key_here'
+})
+
+// Session tracking starts automatically
+// Visitors are tracked when they enter your scene
+```
+
+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 (`dclk_` for full, `dcls_` for lite) |
+| `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) |
+| `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) |
+
+### 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)
+
+Like and follow channels. Requires wallet connection.
+
+```typescript
+staticTV.interactions.like(channelSlug)   // Like a channel
+staticTV.interactions.follow(channelSlug) // Follow a channel
+```
+
+## 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
+
+## 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)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,297 @@
+/**
+ * Configuration options for StaticTVClient
+ */
+interface StaticTVConfig {
+    /** Your channel's API key from thestatic.tv studio */
+    apiKey: string;
+    /** Automatically start session tracking on init (default: true) */
+    autoStartSession?: boolean;
+    /** Interval for session heartbeats in ms (default: 30000) */
+    sessionHeartbeatInterval?: number;
+    /** Interval for video watching heartbeats in ms (default: 60000) */
+    watchHeartbeatInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom API base URL (default: https://thestatic.tv/api/v1/dcl) */
+    baseUrl?: string;
+}
+/**
+ * Channel information from the guide
+ */
+interface Channel {
+    id: string;
+    slug: string;
+    name: string;
+    streamUrl: string;
+    isLive: boolean;
+    currentViewers: number;
+    poster: string | null;
+    logo: string | null;
+    description: string;
+    socials: string | null;
+}
+/**
+ * VOD (Video on Demand) information
+ */
+interface Vod {
+    id: string;
+    title: string;
+    url: string;
+    thumbnail: string | null;
+    channelId: string;
+    createdAt: string;
+}
+/**
+ * Guide response from the API
+ */
+interface GuideResponse {
+    version: string;
+    sceneOwnerChannel: string;
+    channels: Channel[];
+    liveChannels: Channel[];
+    vods: Vod[];
+    meta: {
+        generatedAt: string;
+        totalChannels: number;
+        liveCount: number;
+        vodCount: number;
+    };
+}
+/**
+ * Session response from the API
+ */
+interface SessionResponse {
+    success: boolean;
+    sessionId?: string;
+    version: string;
+}
+/**
+ * Heartbeat response from the API
+ */
+interface HeartbeatResponse {
+    success: boolean;
+    channelSlug: string;
+    sceneOwnerChannel: string;
+    version: string;
+}
+/**
+ * Interaction response from the API
+ */
+interface InteractionResponse {
+    success: boolean;
+    action: 'like' | 'follow';
+    channelSlug: string;
+    alreadyExists: boolean;
+    version: string;
+}
+
+/**
+ * Guide module - fetch channel lineup from thestatic.tv
+ */
+
+declare class GuideModule {
+    private client;
+    private cachedChannels;
+    private cacheTimestamp;
+    private readonly cacheDuration;
+    constructor(client: StaticTVClient);
+    /**
+     * Get all channels from thestatic.tv
+     * Results are cached for 30 seconds
+     */
+    getChannels(forceRefresh?: boolean): Promise<Channel[]>;
+    /**
+     * Get only live channels
+     */
+    getLiveChannels(forceRefresh?: boolean): Promise<Channel[]>;
+    /**
+     * Get a specific channel by slug
+     */
+    getChannel(slug: string): Promise<Channel | undefined>;
+    /**
+     * Get VODs (videos on demand)
+     */
+    getVods(): Promise<Vod[]>;
+    /**
+     * Clear the channel cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * Session module - track visitor sessions in DCL scenes
+ *
+ * Works with both channel keys (dclk_) and scene keys (dcls_).
+ * Scene keys use /scene-session endpoint, channel keys use /session.
+ */
+
+declare class SessionModule {
+    private client;
+    private sessionId;
+    private heartbeatInterval;
+    private isActive;
+    constructor(client: StaticTVClient);
+    /**
+     * Get the appropriate session endpoint based on key type
+     */
+    private getEndpoint;
+    /**
+     * Start a new session
+     * Called automatically if autoStartSession is true
+     */
+    startSession(metadata?: Record<string, unknown>): Promise<string | null>;
+    /**
+     * Start the heartbeat interval
+     */
+    private startHeartbeat;
+    /**
+     * Send a session heartbeat
+     */
+    private sendHeartbeat;
+    /**
+     * End the current session
+     */
+    endSession(): Promise<void>;
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Check if a session is currently active
+     */
+    isSessionActive(): boolean;
+}
+
+/**
+ * Heartbeat module - track video watching metrics
+ */
+
+declare class HeartbeatModule {
+    private client;
+    private watchInterval;
+    private currentChannel;
+    private isWatching;
+    constructor(client: StaticTVClient);
+    /**
+     * Start tracking video watching for a channel
+     * Sends heartbeats every minute while watching
+     *
+     * @param channelSlug The slug of the channel being watched
+     */
+    startWatching(channelSlug: string): void;
+    /**
+     * Stop tracking video watching
+     */
+    stopWatching(): void;
+    /**
+     * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+     */
+    private sendHeartbeat;
+    /**
+     * Get the currently watched channel
+     */
+    getCurrentChannel(): string | null;
+    /**
+     * Check if currently watching
+     */
+    isCurrentlyWatching(): boolean;
+}
+
+/**
+ * Interactions module - like/follow channels from DCL scenes
+ */
+
+declare class InteractionsModule {
+    private client;
+    constructor(client: StaticTVClient);
+    /**
+     * Like a channel
+     * Requires the user to be connected with a wallet
+     *
+     * @param channelSlug The slug of the channel to like
+     * @returns The interaction response or null if failed
+     */
+    like(channelSlug: string): Promise<InteractionResponse | null>;
+    /**
+     * Follow a channel
+     * Requires the user to be connected with a wallet
+     *
+     * @param channelSlug The slug of the channel to follow
+     * @returns The interaction response or null if failed
+     */
+    follow(channelSlug: string): Promise<InteractionResponse | null>;
+}
+
+/**
+ * StaticTVClient - Main client for connecting DCL scenes to thestatic.tv
+ *
+ * Supports two key types:
+ * - dclk_* : Channel keys (full access - guide, heartbeat, interactions)
+ * - dcls_* : Scene-only keys (lite - session tracking only)
+ */
+
+/** Key type constants */
+declare const KEY_TYPE_CHANNEL = "channel";
+declare const KEY_TYPE_SCENE = "scene";
+declare class StaticTVClient {
+    private config;
+    private baseUrl;
+    private _keyType;
+    /** Guide module - fetch channel lineup (channel keys only) */
+    readonly guide: GuideModule | null;
+    /** Session module - track visitor sessions (all keys) */
+    readonly session: SessionModule;
+    /** Heartbeat module - track video watching (channel keys only) */
+    readonly heartbeat: HeartbeatModule | null;
+    /** Interactions module - like/follow channels (channel keys only) */
+    readonly interactions: InteractionsModule | null;
+    /**
+     * Create a new StaticTVClient
+     *
+     * @param config Configuration options
+     *
+     * @example
+     * ```typescript
+     * // Full access with channel key
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dclk_your_channel_key_here',
+     *   debug: true
+     * });
+     *
+     * // Lite mode with scene key (visitors only)
+     * const staticTV = new StaticTVClient({
+     *   apiKey: 'dcls_your_scene_key_here'
+     * });
+     * ```
+     */
+    constructor(config: StaticTVConfig);
+    /**
+     * Get the key type (channel or scene)
+     */
+    get keyType(): 'channel' | 'scene';
+    /**
+     * Check if this is a lite (scene-only) client
+     */
+    get isLite(): boolean;
+    /**
+     * Make an authenticated API request
+     * @internal
+     */
+    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Log a message if debug is enabled
+     * @internal
+     */
+    log(message: string, ...args: unknown[]): void;
+    /**
+     * Get the current configuration
+     * @internal
+     */
+    getConfig(): StaticTVConfig;
+    /**
+     * Cleanup when done (call before scene unload)
+     */
+    destroy(): Promise<void>;
+}
+
+export { type Channel, GuideModule, type GuideResponse, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type Vod };