@playcademy/sdk 0.0.1-beta.29 → 0.0.1-beta.30

package/dist/core/client.d.ts

@@ -433,6 +433,7 @@ export declare class PlaycademyClient {
         token: {
             get: () => Promise<import("./namespaces/realtime").RealtimeTokenResponse>;
         };
+        open(channel?: string): Promise<import("@playcademy/realtime/server/types").RealtimeChannel>;
     };
     /** Auto-initializes a PlaycademyClient with context from the environment */
     static init: typeof init;

package/dist/core/namespaces/realtime.client.d.ts

@@ -0,0 +1,129 @@
+import type { RealtimeChannel } from '@playcademy/realtime/server/types';
+/**
+ * Client-side implementation of a realtime communication channel.
+ * Manages a WebSocket connection to a specific game-scoped realtime channel.
+ *
+ * **Key Features**:
+ * - Automatic connection management with reconnection on token refresh
+ * - Type-safe message handling with JSON serialization/deserialization
+ * - Proper cleanup and resource management
+ * - Integration with the Playcademy messaging system for token updates
+ *
+ * **Connection Lifecycle**:
+ * 1. `connect()` - Establishes WebSocket connection with authentication
+ * 2. Message exchange via `send()` and `onMessage()` callbacks
+ * 3. Automatic reconnection on token refresh events
+ * 4. `close()` - Clean shutdown with proper resource cleanup
+ *
+ * @example
+ * ```typescript
+ * const client = new RealtimeChannelClient(
+ *   'game-123',
+ *   'chat',
+ *   () => getToken(),
+ *   'ws://localhost:3000'
+ * )
+ *
+ * await client.connect()
+ *
+ * client.onMessage((data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * client.send({ type: 'message', text: 'Hello!' })
+ *
+ * // Clean up when done
+ * client.close()
+ * ```
+ */
+export declare class RealtimeChannelClient implements RealtimeChannel {
+    private gameId;
+    private _channelName;
+    private getToken;
+    private baseUrl;
+    private ws?;
+    private listeners;
+    private isClosing;
+    private tokenRefreshUnsubscribe?;
+    constructor(gameId: string, _channelName: string, getToken: () => Promise<string>, baseUrl: string);
+    /**
+     * Establishes the WebSocket connection to the realtime server.
+     *
+     * **Connection Process**:
+     * 1. Obtains fresh authentication token
+     * 2. Constructs WebSocket URL with token and channel parameters
+     * 3. Creates WebSocket connection
+     * 4. Sets up event handlers for messages, errors, and disconnections
+     * 5. Registers for token refresh events
+     *
+     * **URL Format**: `ws://host/path?token=<jwt>&c=<channel>`
+     *
+     * @throws Error if token retrieval fails or WebSocket connection fails
+     */
+    connect(): Promise<RealtimeChannel>;
+    /**
+     * Sets up WebSocket event handlers for message processing and connection management.
+     *
+     * **Event Handling**:
+     * - `message`: Parses JSON and notifies all registered listeners
+     * - `close`: Handles both expected and unexpected disconnections
+     * - `error`: Logs WebSocket errors for debugging
+     */
+    private setupEventHandlers;
+    /**
+     * Sets up listener for token refresh events from the messaging system.
+     * When a token refresh occurs, the WebSocket connection is closed and reopened
+     * with the new token to maintain authentication.
+     */
+    private setupTokenRefreshListener;
+    /**
+     * Reconnects the WebSocket with a new authentication token.
+     *
+     * **Reconnection Process**:
+     * 1. Close existing connection with TOKEN_REFRESH code
+     * 2. Wait for close event to complete
+     * 3. Re-establish connection with new token
+     *
+     * @param token - The new authentication token (currently unused, relies on getToken())
+     */
+    private reconnectWithNewToken;
+    /**
+     * Sends a message to all members of this channel.
+     *
+     * **Message Format**: JSON-serialized payload
+     * **Delivery**: Best-effort, no acknowledgment or retry logic
+     *
+     * @param data - Any JSON-serializable data to send
+     */
+    send(data: unknown): void;
+    /**
+     * Registers a callback to be invoked when messages are received on this channel.
+     *
+     * **Message Processing**:
+     * - Messages are automatically JSON-parsed before delivery
+     * - Listener errors are caught and logged (won't affect other listeners)
+     * - Multiple listeners can be registered for the same channel
+     *
+     * @param callback - Function to call when messages are received
+     * @returns Unsubscribe function to remove this listener
+     */
+    onMessage(callback: (data: unknown) => void): () => void;
+    /**
+     * Closes the WebSocket connection and cleans up all resources.
+     *
+     * **Cleanup Process**:
+     * 1. Mark as intentionally closing (prevents reconnection attempts)
+     * 2. Remove token refresh listener
+     * 3. Close WebSocket with normal closure code
+     * 4. Clear all message listeners
+     */
+    close(): void;
+    /**
+     * Gets the name of this channel.
+     */
+    get channelName(): string;
+    /**
+     * Checks if the underlying WebSocket connection is currently open.
+     */
+    get isConnected(): boolean;
+}

package/dist/core/namespaces/realtime.d.ts

@@ -1,3 +1,4 @@
+import type { RealtimeChannel } from '@playcademy/realtime/server/types';
 import type { PlaycademyClient } from '../../types';
 /**
  * Response type for the realtime token API
@@ -10,7 +11,7 @@ export interface RealtimeTokenResponse {
  * Provides methods for realtime connectivity and features.
  *
  * @param client - The PlaycademyClient instance
- * @returns Realtime namespace with token-related methods
+ * @returns Realtime namespace with token-related methods and channel API
  */
 export declare function createRealtimeNamespace(client: PlaycademyClient): {
     /**
@@ -37,4 +38,47 @@ export declare function createRealtimeNamespace(client: PlaycademyClient): {
          */
         get: () => Promise<RealtimeTokenResponse>;
     };
+    /**
+     * Opens a realtime channel for game-scoped communication.
+     *
+     * **Channel Naming**:
+     * - Channels are automatically scoped to the current game
+     * - Channel names should be descriptive (e.g., "chat", "lobby", "map_forest")
+     * - The "default" channel is used if no name is specified
+     *
+     * **Connection Management**:
+     * - Each channel opens its own WebSocket connection
+     * - Connections automatically handle token refresh
+     * - Remember to call `channel.close()` when done to prevent resource leaks
+     *
+     * **Error Handling**:
+     * - Throws if no gameId is configured on the client
+     * - Throws if token retrieval fails
+     * - Throws if WebSocket connection fails
+     *
+     * @param channel - Channel name (defaults to "default")
+     * @returns Promise resolving to a RealtimeChannel instance
+     *
+     * @example
+     * ```typescript
+     * // Open the default channel
+     * const channel = await client.realtime.open()
+     *
+     * // Listen for messages
+     * const unsubscribe = channel.onMessage((data) => {
+     *   console.log('Received:', data)
+     * })
+     *
+     * // Send a message
+     * channel.send({ type: 'chat', message: 'Hello world!' })
+     *
+     * // Clean up when done
+     * unsubscribe()
+     * channel.close()
+     *
+     * // Open a named channel
+     * const chatChannel = await client.realtime.open('chat')
+     * ```
+     */
+    open(channel?: string): Promise<RealtimeChannel>;
 };

package/dist/index.js

@@ -1479,6 +1479,198 @@ function createSpritesNamespace(client) {
   };
 }
 
+// src/core/namespaces/realtime.client.ts
+class RealtimeChannelClient {
+  gameId;
+  _channelName;
+  getToken;
+  baseUrl;
+  ws;
+  listeners = new Set;
+  isClosing = false;
+  tokenRefreshUnsubscribe;
+  constructor(gameId, _channelName, getToken, baseUrl) {
+    this.gameId = gameId;
+    this._channelName = _channelName;
+    this.getToken = getToken;
+    this.baseUrl = baseUrl;
+  }
+  async connect() {
+    try {
+      const token = await this.getToken();
+      const wsUrl = this.baseUrl.replace(/^http/, "ws");
+      const url = `${wsUrl}?token=${encodeURIComponent(token)}&c=${encodeURIComponent(this._channelName)}`;
+      this.ws = new WebSocket(url);
+      this.setupEventHandlers();
+      this.setupTokenRefreshListener();
+      await new Promise((resolve, reject) => {
+        if (!this.ws) {
+          reject(new Error("WebSocket creation failed"));
+          return;
+        }
+        const onOpen = () => {
+          this.ws?.removeEventListener("open", onOpen);
+          this.ws?.removeEventListener("error", onError);
+          resolve();
+        };
+        const onError = (event) => {
+          this.ws?.removeEventListener("open", onOpen);
+          this.ws?.removeEventListener("error", onError);
+          reject(new Error(`WebSocket connection failed: ${event}`));
+        };
+        this.ws.addEventListener("open", onOpen);
+        this.ws.addEventListener("error", onError);
+      });
+      log.debug("[RealtimeChannelClient] Connected to channel", {
+        gameId: this.gameId,
+        channel: this._channelName
+      });
+      return this;
+    } catch (error) {
+      log.error("[RealtimeChannelClient] Connection failed", {
+        gameId: this.gameId,
+        channel: this._channelName,
+        error
+      });
+      throw error;
+    }
+  }
+  setupEventHandlers() {
+    if (!this.ws)
+      return;
+    this.ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        this.listeners.forEach((callback) => {
+          try {
+            callback(data);
+          } catch (error) {
+            log.warn("[RealtimeChannelClient] Message listener error", {
+              channel: this._channelName,
+              error
+            });
+          }
+        });
+      } catch (error) {
+        log.warn("[RealtimeChannelClient] Failed to parse message", {
+          channel: this._channelName,
+          message: event.data,
+          error
+        });
+      }
+    };
+    this.ws.onclose = (event) => {
+      log.debug("[RealtimeChannelClient] Connection closed", {
+        channel: this._channelName,
+        code: event.code,
+        reason: event.reason,
+        wasClean: event.wasClean
+      });
+      if (!this.isClosing && event.code !== CLOSE_CODES.TOKEN_REFRESH) {
+        log.warn("[RealtimeChannelClient] Unexpected disconnection", {
+          channel: this._channelName,
+          code: event.code,
+          reason: event.reason
+        });
+      }
+    };
+    this.ws.onerror = (event) => {
+      log.error("[RealtimeChannelClient] WebSocket error", {
+        channel: this._channelName,
+        event
+      });
+    };
+  }
+  setupTokenRefreshListener() {
+    const tokenRefreshHandler = async ({ token }) => {
+      log.debug("[RealtimeChannelClient] Token refresh received, reconnecting", {
+        channel: this._channelName
+      });
+      try {
+        await this.reconnectWithNewToken(token);
+      } catch (error) {
+        log.error("[RealtimeChannelClient] Token refresh reconnection failed", {
+          channel: this._channelName,
+          error
+        });
+      }
+    };
+    messaging.listen("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, tokenRefreshHandler);
+    this.tokenRefreshUnsubscribe = () => {
+      messaging.unlisten("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, tokenRefreshHandler);
+    };
+  }
+  async reconnectWithNewToken(_token) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.close(CLOSE_CODES.TOKEN_REFRESH, "token_refresh");
+      await new Promise((resolve) => {
+        const checkClosed = () => {
+          if (!this.ws || this.ws.readyState === WebSocket.CLOSED) {
+            resolve();
+          } else {
+            setTimeout(checkClosed, 10);
+          }
+        };
+        checkClosed();
+      });
+    }
+    await this.connect();
+  }
+  send(data) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      try {
+        const message = JSON.stringify(data);
+        this.ws.send(message);
+      } catch (error) {
+        log.error("[RealtimeChannelClient] Failed to send message", {
+          channel: this._channelName,
+          error,
+          data
+        });
+      }
+    } else {
+      log.warn("[RealtimeChannelClient] Cannot send message - connection not open", {
+        channel: this._channelName,
+        readyState: this.ws?.readyState
+      });
+    }
+  }
+  onMessage(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  close() {
+    this.isClosing = true;
+    if (this.tokenRefreshUnsubscribe) {
+      this.tokenRefreshUnsubscribe();
+      this.tokenRefreshUnsubscribe = undefined;
+    }
+    if (this.ws) {
+      this.ws.close(CLOSE_CODES.NORMAL_CLOSURE, "client_close");
+      this.ws = undefined;
+    }
+    this.listeners.clear();
+    log.debug("[RealtimeChannelClient] Channel closed", {
+      channel: this._channelName
+    });
+  }
+  get channelName() {
+    return this._channelName;
+  }
+  get isConnected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+}
+var CLOSE_CODES;
+var init_realtime_client = __esm(() => {
+  init_src();
+  init_messaging();
+  CLOSE_CODES = {
+    NORMAL_CLOSURE: 1000,
+    TOKEN_REFRESH: 4000
+  };
+});
+
 // src/core/namespaces/realtime.ts
 function createRealtimeNamespace(client) {
   return {
@@ -1486,15 +1678,26 @@ function createRealtimeNamespace(client) {
       get: async () => {
         return client["request"]("/realtime/token", "POST");
       }
+    },
+    async open(channel = "default") {
+      if (!client["gameId"]) {
+        throw new Error("gameId is required for realtime channels");
+      }
+      const realtimeClient = new RealtimeChannelClient(client["gameId"], channel, () => client.realtime.token.get().then((r) => r.token), client.getBaseUrl());
+      return realtimeClient.connect();
     }
   };
 }
+var init_realtime = __esm(() => {
+  init_realtime_client();
+});
 
 // src/core/namespaces/index.ts
 var init_namespaces = __esm(() => {
   init_runtime();
   init_games();
   init_credits();
+  init_realtime();
 });
 
 // src/core/static/init.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.0.1-beta.29",
+    "version": "0.0.1-beta.30",
     "type": "module",
     "exports": {
         ".": {