@maravilla-labs/platform 0.1.27 → 0.1.28

package/src/media.ts

@@ -0,0 +1,101 @@
+/**
+ * Media service for video/audio room management.
+ *
+ * In production (Deno runtime) calls go through `Deno.core.ops`.
+ * In development they are proxied as HTTP requests to the dev-server.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface MediaRoomInfo {
+  name: string;
+  numParticipants: number;
+  maxParticipants: number;
+  createdAt: number;
+  active: boolean;
+}
+
+export interface MediaRoomInfoSettings {
+  maxParticipants?: number;
+  emptyTimeoutSecs?: number;
+}
+
+export interface MediaParticipantInfo {
+  identity: string;
+  name: string;
+  canPublish?: boolean;
+  canSubscribe?: boolean;
+  canPublishData?: boolean;
+}
+
+export interface MediaTokenResult {
+  token: string;
+  url: string;
+}
+
+export interface MediaService {
+  createRoom(roomId: string, settings?: MediaRoomInfoSettings): Promise<MediaRoomInfo>;
+  deleteRoom(roomId: string): Promise<void>;
+  listRooms(): Promise<MediaRoomInfo[]>;
+  generateToken(roomId: string, participant: MediaParticipantInfo): Promise<MediaTokenResult>;
+  mediaUrl(): Promise<string | null>;
+}
+
+// ── Remote (dev-server) implementation ───────────────────────────────
+
+export class RemoteMediaService implements MediaService {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  private async fetch(url: string, options: RequestInit = {}) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...this.headers, ...options.headers },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Media API error: ${response.status} - ${error}`);
+    }
+
+    return response;
+  }
+
+  async createRoom(roomId: string, settings: MediaRoomInfoSettings = {}): Promise<MediaRoomInfo> {
+    const response = await this.fetch(`${this.baseUrl}/api/media/rooms`, {
+      method: 'POST',
+      body: JSON.stringify({ roomId, settings }),
+    });
+    return response.json() as Promise<MediaRoomInfo>;
+  }
+
+  async deleteRoom(roomId: string): Promise<void> {
+    await this.fetch(`${this.baseUrl}/api/media/rooms/${encodeURIComponent(roomId)}`, {
+      method: 'DELETE',
+    });
+  }
+
+  async listRooms(): Promise<MediaRoomInfo[]> {
+    const response = await this.fetch(`${this.baseUrl}/api/media/rooms`);
+    return response.json() as Promise<MediaRoomInfo[]>;
+  }
+
+  async generateToken(roomId: string, participant: MediaParticipantInfo): Promise<MediaTokenResult> {
+    const response = await this.fetch(
+      `${this.baseUrl}/api/media/rooms/${encodeURIComponent(roomId)}/token`,
+      {
+        method: 'POST',
+        body: JSON.stringify(participant),
+      },
+    );
+    return response.json() as Promise<MediaTokenResult>;
+  }
+
+  async mediaUrl(): Promise<string | null> {
+    const response = await this.fetch(`${this.baseUrl}/api/media/url`);
+    const data = (await response.json()) as { url: string | null };
+    return data.url;
+  }
+}

package/src/realtime.ts

@@ -0,0 +1,286 @@
+// Maravilla Realtime Client
+// Extends REN with channels, pub/sub, and presence support
+// Uses WebSocket for bidirectional communication, SSE as fallback
+
+import { getOrCreateClientId } from './ren.js';
+
+export interface RealtimeEvent {
+  event: string;
+  channel: string;
+  data?: any;
+  from?: string;
+  userId?: string;
+  ts?: number;
+  metadata?: any;
+}
+
+export interface PresenceMember {
+  userId: string;
+  metadata?: any;
+  lastSeen?: number;
+}
+
+export interface RealtimeClientOptions {
+  /** WebSocket endpoint (default: auto-detect) */
+  wsEndpoint?: string;
+  /** Client ID (persistent across sessions) */
+  clientId?: string;
+  /** Auto-reconnect on disconnect (default: true) */
+  autoReconnect?: boolean;
+  /** Max reconnect backoff in ms (default: 15000) */
+  maxBackoffMs?: number;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+type EventCallback = (event: RealtimeEvent) => void;
+type Unsubscribe = () => void;
+
+export class RealtimeClient {
+  private wsEndpoint: string;
+  private clientId: string;
+  private ws: WebSocket | null = null;
+  private closed = false;
+  private attempt = 0;
+  private autoReconnect: boolean;
+  private maxBackoff: number;
+  private debug: boolean;
+
+  private channelListeners = new Map<string, Set<EventCallback>>();
+  private globalListeners = new Set<EventCallback>();
+  private presenceListeners = new Map<string, {
+    onJoin: Set<(member: PresenceMember) => void>;
+    onLeave: Set<(member: PresenceMember) => void>;
+  }>();
+  private subscribedChannels = new Set<string>();
+  private pendingMessages: string[] = [];
+
+  constructor(opts: RealtimeClientOptions = {}) {
+    this.wsEndpoint = opts.wsEndpoint || this.detectEndpoint();
+    this.clientId = opts.clientId || getOrCreateClientId();
+    this.autoReconnect = opts.autoReconnect !== false;
+    this.maxBackoff = opts.maxBackoffMs ?? 15000;
+    this.debug = !!opts.debug;
+  }
+
+  private detectEndpoint(): string {
+    if (typeof window !== 'undefined') {
+      const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      // Development mode (Vite on 5173)
+      if (window.location.port === '5173') {
+        return `ws://${window.location.hostname}:3001/_rt/ws`;
+      }
+      return `${proto}//${window.location.host}/_rt/ws`;
+    }
+    return 'ws://localhost:3001/_rt/ws';
+  }
+
+  private log(...args: any[]) {
+    if (this.debug) console.debug('[RealtimeClient]', ...args);
+  }
+
+  /** Connect to the realtime WebSocket server */
+  connect(): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+
+    const url = `${this.wsEndpoint}?cid=${encodeURIComponent(this.clientId)}`;
+    this.log('connecting', url);
+    this.closed = false;
+
+    try {
+      this.ws = new WebSocket(url);
+    } catch (e) {
+      this.log('WebSocket constructor failed', e);
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.onopen = () => {
+      this.attempt = 0;
+      this.log('connected');
+
+      // Re-subscribe to channels
+      for (const ch of this.subscribedChannels) {
+        this.sendRaw({ action: 'subscribe', channel: ch });
+      }
+
+      // Flush pending messages
+      for (const msg of this.pendingMessages) {
+        this.ws?.send(msg);
+      }
+      this.pendingMessages = [];
+    };
+
+    this.ws.onmessage = (ev) => {
+      try {
+        const event: RealtimeEvent = JSON.parse(ev.data);
+        this.log('received', event);
+        this.dispatch(event);
+      } catch (e) {
+        this.log('malformed message', ev.data, e);
+      }
+    };
+
+    this.ws.onerror = (ev) => {
+      this.log('error', ev);
+    };
+
+    this.ws.onclose = () => {
+      this.log('disconnected');
+      this.ws = null;
+      if (!this.closed && this.autoReconnect) {
+        this.scheduleReconnect();
+      }
+    };
+  }
+
+  private scheduleReconnect() {
+    const delay = Math.min(1000 * Math.pow(2, this.attempt++), this.maxBackoff);
+    this.log('reconnecting in', delay, 'ms');
+    setTimeout(() => this.connect(), delay);
+  }
+
+  private sendRaw(msg: Record<string, any>) {
+    const json = JSON.stringify(msg);
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(json);
+    } else {
+      this.pendingMessages.push(json);
+    }
+  }
+
+  private dispatch(event: RealtimeEvent) {
+    // Notify global listeners
+    this.globalListeners.forEach(cb => cb(event));
+
+    // Notify channel-specific listeners
+    if (event.channel) {
+      const listeners = this.channelListeners.get(event.channel);
+      if (listeners) {
+        listeners.forEach(cb => cb(event));
+      }
+    }
+
+    // Handle presence events
+    if (event.event === 'presence:join' || event.event === 'presence:leave') {
+      const presenceSet = this.presenceListeners.get(event.channel);
+      if (presenceSet) {
+        const member: PresenceMember = {
+          userId: event.userId || '',
+          metadata: event.metadata,
+          lastSeen: event.ts,
+        };
+        if (event.event === 'presence:join') {
+          presenceSet.onJoin.forEach(cb => cb(member));
+        } else {
+          presenceSet.onLeave.forEach(cb => cb(member));
+        }
+      }
+    }
+  }
+
+  /** Subscribe to messages on a channel */
+  subscribe(channel: string, callback: EventCallback, options?: { token?: string }): Unsubscribe {
+    if (!this.channelListeners.has(channel)) {
+      this.channelListeners.set(channel, new Set());
+    }
+    this.channelListeners.get(channel)!.add(callback);
+
+    // Send subscribe message if not already subscribed
+    if (!this.subscribedChannels.has(channel)) {
+      this.subscribedChannels.add(channel);
+      const msg: Record<string, any> = { action: 'subscribe', channel };
+      if (options?.token) {
+        msg.token = options.token;
+      }
+      this.sendRaw(msg);
+    }
+
+    return () => {
+      const listeners = this.channelListeners.get(channel);
+      if (listeners) {
+        listeners.delete(callback);
+        if (listeners.size === 0) {
+          this.channelListeners.delete(channel);
+          this.subscribedChannels.delete(channel);
+          this.sendRaw({ action: 'unsubscribe', channel });
+        }
+      }
+    };
+  }
+
+  /** Listen to all events across all channels */
+  onAny(callback: EventCallback): Unsubscribe {
+    this.globalListeners.add(callback);
+    return () => { this.globalListeners.delete(callback); };
+  }
+
+  /** Publish a message to a channel */
+  publish(channel: string, data: any, options?: { userId?: string }): void {
+    this.sendRaw({
+      action: 'publish',
+      channel,
+      data,
+      userId: options?.userId,
+    });
+  }
+
+  /** Get a presence handle for a channel */
+  presence(channel: string) {
+    if (!this.presenceListeners.has(channel)) {
+      this.presenceListeners.set(channel, {
+        onJoin: new Set(),
+        onLeave: new Set(),
+      });
+    }
+    const listeners = this.presenceListeners.get(channel)!;
+
+    return {
+      /** Join the channel with presence */
+      join: (userId: string, metadata?: any): void => {
+        this.sendRaw({
+          action: 'presence:join',
+          channel,
+          userId,
+          metadata,
+        });
+      },
+
+      /** Leave the channel */
+      leave: (): void => {
+        this.sendRaw({ action: 'presence:leave', channel });
+      },
+
+      /** Listen for users joining */
+      onJoin: (callback: (member: PresenceMember) => void): Unsubscribe => {
+        listeners.onJoin.add(callback);
+        return () => { listeners.onJoin.delete(callback); };
+      },
+
+      /** Listen for users leaving */
+      onLeave: (callback: (member: PresenceMember) => void): Unsubscribe => {
+        listeners.onLeave.add(callback);
+        return () => { listeners.onLeave.delete(callback); };
+      },
+    };
+  }
+
+  /** Get current client ID */
+  getClientId(): string {
+    return this.clientId;
+  }
+
+  /** Check if connected */
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /** Disconnect and stop reconnecting */
+  disconnect(): void {
+    this.closed = true;
+    this.ws?.close();
+    this.ws = null;
+    this.pendingMessages = [];
+    this.log('disconnected (manual)');
+  }
+}

package/src/remote-client.ts

@@ -1,4 +1,5 @@
 import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage } from './types.js';
+import { RemoteMediaService } from './media.js';
 
 /**
  * Remote KV namespace implementation that communicates with a development server.
@@ -383,12 +384,14 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
 
   const db = new RemoteDatabase(baseUrl, headers);
   const storage = new RemoteStorage(baseUrl, headers);
+  const media = new RemoteMediaService(baseUrl, headers);
 
   return {
     env: {
       KV: kvProxy,
       DB: db,
       STORAGE: storage,
-    }
+    },
+    media,
   };
 }

package/src/ren.ts

@@ -3,13 +3,16 @@
 // Reconnect w/ basic backoff; consumer filters self vs others using evt.src
 
 export interface RenEvent {
-  t: string;   // event type e.g. storage.object.created
-  r: string;   // resource domain e.g. storage, runtime
+  t: string;   // event type e.g. storage.object.created, realtime.message, presence.join
+  r: string;   // resource domain e.g. storage, runtime, realtime, presence
   k?: string;  // key (object key, deployment key, etc.)
   v?: string;  // version / etag
   ts?: number; // timestamp (ms)
   src?: string;// origin client id (if set on mutation request)
   ns?: string; // future namespace / tenant
+  ch?: string; // channel name (for realtime pub/sub)
+  data?: any;  // arbitrary payload (for realtime messages)
+  uid?: string;// user identity (for presence)
   [extra: string]: any;
 }
 
@@ -132,6 +135,12 @@ export class RenClient {
       'runtime.snapshot.ready',
       'runtime.worker.started',
       'runtime.worker.stopped',
+      // Realtime channel events
+      'realtime.message',
+      // Presence events
+      'presence.join',
+      'presence.leave',
+      'presence.update',
       // Meta events
       'ren.meta'
     ];

package/src/types.ts

@@ -542,4 +542,6 @@ export interface PlatformEnv {
 export interface Platform {
   /** Environment containing all available platform services */
   env: PlatformEnv;
+  /** Media service for video/audio room management (optional — available when media is configured) */
+  media?: import('./media.js').MediaService;
 }