@baasix/sdk 0.1.8 → 0.1.10

package/dist/index.d.cts

@@ -1076,6 +1076,7 @@ interface RoomUserEvent {
     room: string;
     userId: string | number;
     socketId: string;
+    metadata: Record<string, any>;
     timestamp: string;
 }
 interface RoomKickEvent {
@@ -1093,6 +1094,20 @@ interface RoomMember {
     socketId: string;
     userId: string | number;
     isCreator: boolean;
+    metadata: Record<string, any>;
+}
+/**
+ * A single message from the room's history buffer, replayed when you join.
+ * Has the same shape as a live {@link RoomMessage} (minus the `room` field).
+ */
+interface RoomHistoryMessage {
+    event: string;
+    payload: any;
+    sender: {
+        userId: string | number;
+        socketId: string;
+    };
+    timestamp: string;
 }
 interface SubscriptionCallback<T = any> {
     (payload: SubscriptionPayload<T>): void;
@@ -1267,20 +1282,38 @@ declare class RealtimeModule {
     subscribeToExecution(executionId: string | number, callback: (data: WorkflowExecutionUpdate) => void): () => void;
     private handleWorkflowUpdate;
     /**
-     * Join a custom room for real-time communication
+     * Join a custom room for real-time communication.
+     *
+     * You can optionally attach metadata (e.g. display name, avatar, team) that
+     * will be visible to all other members via {@link getRoomMembers} and in
+     * `room:user:joined` events.
+     *
+     * Returns the room's message history (up to 200 messages) so late joiners
+     * can replay past messages immediately.
+     *
+     * @param roomName - The room to join.
+     * @param metadata - Optional key/value pairs stored alongside this member.
+     * @returns An object containing the buffered `history` for the room.
      *
      * @example
      * ```typescript
-     * // Join a room
-     * await baasix.realtime.joinRoom('game:lobby');
+     * const { history } = await baasix.realtime.joinRoom('game:lobby', {
+     *   username: 'Alice',
+     *   avatar: 'https://example.com/alice.png',
+     * });
+     *
+     * // Render past messages first
+     * history.forEach((msg) => renderMessage(msg));
      *
-     * // Listen for messages
+     * // Then listen for new ones
      * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-     *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+     *   renderMessage(data);
      * });
      * ```
      */
-    joinRoom(roomName: string): Promise<void>;
+    joinRoom(roomName: string, metadata?: Record<string, any>): Promise<{
+        history: RoomHistoryMessage[];
+    }>;
     /**
      * Leave a custom room
      *
@@ -1294,11 +1327,14 @@ declare class RealtimeModule {
      * Get the list of users currently in a room.
      * You must already be a member of the room to call this.
      *
+     * Each entry includes `userId`, `socketId`, `isCreator`, and `metadata`
+     * (the custom object the member passed to {@link joinRoom}).
+     *
      * @example
      * ```typescript
      * const members = await baasix.realtime.getRoomMembers('game:lobby');
      * members.forEach(m => {
-     *   console.log(m.userId, m.isCreator ? '(owner)' : '');
+     *   console.log(m.metadata.username, m.isCreator ? '(owner)' : '');
      * });
      * ```
      */
@@ -1337,18 +1373,27 @@ declare class RealtimeModule {
      */
     onRoomCreatorChanged(roomName: string, callback: (data: RoomCreatorChangedEvent) => void): () => void;
     /**
-     * Send a message to a room
+     * Send a message to a room.
+     *
+     * By default the message is stored in the room's history buffer so late
+     * joiners can replay it. Pass `{ history: false }` to broadcast without
+     * persisting (e.g. ephemeral cursor positions, typing indicators).
      *
      * @example
      * ```typescript
-     * // Send a chat message
+     * // Persisted — replayed to future joiners
      * await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
      *
-     * // Send a game event
-     * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 });
+     * // Ephemeral — broadcast only, never stored in history
+     * await baasix.realtime.sendToRoom('game:lobby', 'typing', { userId }, { history: false });
+     *
+     * // Game move — skips history
+     * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 }, { history: false });
      * ```
      */
-    sendToRoom(roomName: string, event: string, payload: any): Promise<void>;
+    sendToRoom(roomName: string, event: string, payload: any, options?: {
+        history?: boolean;
+    }): Promise<void>;
     /**
      * Listen for messages in a room with a specific event type
      *

package/dist/index.d.ts

@@ -1076,6 +1076,7 @@ interface RoomUserEvent {
     room: string;
     userId: string | number;
     socketId: string;
+    metadata: Record<string, any>;
     timestamp: string;
 }
 interface RoomKickEvent {
@@ -1093,6 +1094,20 @@ interface RoomMember {
     socketId: string;
     userId: string | number;
     isCreator: boolean;
+    metadata: Record<string, any>;
+}
+/**
+ * A single message from the room's history buffer, replayed when you join.
+ * Has the same shape as a live {@link RoomMessage} (minus the `room` field).
+ */
+interface RoomHistoryMessage {
+    event: string;
+    payload: any;
+    sender: {
+        userId: string | number;
+        socketId: string;
+    };
+    timestamp: string;
 }
 interface SubscriptionCallback<T = any> {
     (payload: SubscriptionPayload<T>): void;
@@ -1267,20 +1282,38 @@ declare class RealtimeModule {
     subscribeToExecution(executionId: string | number, callback: (data: WorkflowExecutionUpdate) => void): () => void;
     private handleWorkflowUpdate;
     /**
-     * Join a custom room for real-time communication
+     * Join a custom room for real-time communication.
+     *
+     * You can optionally attach metadata (e.g. display name, avatar, team) that
+     * will be visible to all other members via {@link getRoomMembers} and in
+     * `room:user:joined` events.
+     *
+     * Returns the room's message history (up to 200 messages) so late joiners
+     * can replay past messages immediately.
+     *
+     * @param roomName - The room to join.
+     * @param metadata - Optional key/value pairs stored alongside this member.
+     * @returns An object containing the buffered `history` for the room.
      *
      * @example
      * ```typescript
-     * // Join a room
-     * await baasix.realtime.joinRoom('game:lobby');
+     * const { history } = await baasix.realtime.joinRoom('game:lobby', {
+     *   username: 'Alice',
+     *   avatar: 'https://example.com/alice.png',
+     * });
+     *
+     * // Render past messages first
+     * history.forEach((msg) => renderMessage(msg));
      *
-     * // Listen for messages
+     * // Then listen for new ones
      * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-     *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+     *   renderMessage(data);
      * });
      * ```
      */
-    joinRoom(roomName: string): Promise<void>;
+    joinRoom(roomName: string, metadata?: Record<string, any>): Promise<{
+        history: RoomHistoryMessage[];
+    }>;
     /**
      * Leave a custom room
      *
@@ -1294,11 +1327,14 @@ declare class RealtimeModule {
      * Get the list of users currently in a room.
      * You must already be a member of the room to call this.
      *
+     * Each entry includes `userId`, `socketId`, `isCreator`, and `metadata`
+     * (the custom object the member passed to {@link joinRoom}).
+     *
      * @example
      * ```typescript
      * const members = await baasix.realtime.getRoomMembers('game:lobby');
      * members.forEach(m => {
-     *   console.log(m.userId, m.isCreator ? '(owner)' : '');
+     *   console.log(m.metadata.username, m.isCreator ? '(owner)' : '');
      * });
      * ```
      */
@@ -1337,18 +1373,27 @@ declare class RealtimeModule {
      */
     onRoomCreatorChanged(roomName: string, callback: (data: RoomCreatorChangedEvent) => void): () => void;
     /**
-     * Send a message to a room
+     * Send a message to a room.
+     *
+     * By default the message is stored in the room's history buffer so late
+     * joiners can replay it. Pass `{ history: false }` to broadcast without
+     * persisting (e.g. ephemeral cursor positions, typing indicators).
      *
      * @example
      * ```typescript
-     * // Send a chat message
+     * // Persisted — replayed to future joiners
      * await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
      *
-     * // Send a game event
-     * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 });
+     * // Ephemeral — broadcast only, never stored in history
+     * await baasix.realtime.sendToRoom('game:lobby', 'typing', { userId }, { history: false });
+     *
+     * // Game move — skips history
+     * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 }, { history: false });
      * ```
      */
-    sendToRoom(roomName: string, event: string, payload: any): Promise<void>;
+    sendToRoom(roomName: string, event: string, payload: any, options?: {
+        history?: boolean;
+    }): Promise<void>;
     /**
      * Listen for messages in a room with a specific event type
      *

package/dist/index.js

@@ -3693,28 +3693,44 @@ var RealtimeModule = class {
   // Custom Rooms API
   // ===================
   /**
-   * Join a custom room for real-time communication
-   * 
+   * Join a custom room for real-time communication.
+   *
+   * You can optionally attach metadata (e.g. display name, avatar, team) that
+   * will be visible to all other members via {@link getRoomMembers} and in
+   * `room:user:joined` events.
+   *
+   * Returns the room's message history (up to 200 messages) so late joiners
+   * can replay past messages immediately.
+   *
+   * @param roomName - The room to join.
+   * @param metadata - Optional key/value pairs stored alongside this member.
+   * @returns An object containing the buffered `history` for the room.
+   *
    * @example
    * ```typescript
-   * // Join a room
-   * await baasix.realtime.joinRoom('game:lobby');
-   * 
-   * // Listen for messages
+   * const { history } = await baasix.realtime.joinRoom('game:lobby', {
+   *   username: 'Alice',
+   *   avatar: 'https://example.com/alice.png',
+   * });
+   *
+   * // Render past messages first
+   * history.forEach((msg) => renderMessage(msg));
+   *
+   * // Then listen for new ones
    * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-   *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+   *   renderMessage(data);
    * });
    * ```
    */
-  async joinRoom(roomName) {
+  async joinRoom(roomName, metadata = {}) {
     if (!this.socket?.connected) {
       throw new Error("Not connected. Call connect() first.");
     }
     return new Promise((resolve, reject) => {
-      this.socket.emit("room:join", { room: roomName }, (response) => {
+      this.socket.emit("room:join", { room: roomName, metadata }, (response) => {
         if (response.status === "success") {
           this.setupRoomListeners(roomName);
-          resolve();
+          resolve({ history: response.history ?? [] });
         } else {
           reject(new Error(response.message || "Failed to join room"));
         }
@@ -3748,11 +3764,14 @@ var RealtimeModule = class {
    * Get the list of users currently in a room.
    * You must already be a member of the room to call this.
    *
+   * Each entry includes `userId`, `socketId`, `isCreator`, and `metadata`
+   * (the custom object the member passed to {@link joinRoom}).
+   *
    * @example
    * ```typescript
    * const members = await baasix.realtime.getRoomMembers('game:lobby');
    * members.forEach(m => {
-   *   console.log(m.userId, m.isCreator ? '(owner)' : '');
+   *   console.log(m.metadata.username, m.isCreator ? '(owner)' : '');
    * });
    * ```
    */
@@ -3849,25 +3868,33 @@ var RealtimeModule = class {
     };
   }
   /**
-   * Send a message to a room
-   * 
+   * Send a message to a room.
+   *
+   * By default the message is stored in the room's history buffer so late
+   * joiners can replay it. Pass `{ history: false }` to broadcast without
+   * persisting (e.g. ephemeral cursor positions, typing indicators).
+   *
    * @example
    * ```typescript
-   * // Send a chat message
+   * // Persisted — replayed to future joiners
    * await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
-   * 
-   * // Send a game event
-   * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 });
+   *
+   * // Ephemeral — broadcast only, never stored in history
+   * await baasix.realtime.sendToRoom('game:lobby', 'typing', { userId }, { history: false });
+   *
+   * // Game move — skips history
+   * await baasix.realtime.sendToRoom('game:123', 'move', { x: 10, y: 20 }, { history: false });
    * ```
    */
-  async sendToRoom(roomName, event, payload) {
+  async sendToRoom(roomName, event, payload, options = {}) {
     if (!this.socket?.connected) {
       throw new Error("Not connected. Call connect() first.");
     }
+    const history = options.history ?? true;
     return new Promise((resolve, reject) => {
       this.socket.emit(
         "room:message",
-        { room: roomName, event, payload },
+        { room: roomName, event, payload, history },
         (response) => {
           if (response.status === "success") {
             resolve();