@baasix/sdk 0.1.10 → 0.1.11

package/README.md

@@ -1058,21 +1058,41 @@ channel.unsubscribe();
 Custom rooms enable real-time communication between users for chat, games, or collaborative features. The **first user to join** a room becomes its creator. If the creator leaves temporarily, ownership transfers to the next member — but the **original creator automatically reclaims ownership** when they rejoin. If the room empties and is recreated, the next joiner becomes the new owner.
 
 ```typescript
-// Join a room — pass optional metadata stored alongside your membership
-await baasix.realtime.joinRoom('game:lobby', {
+// Join a room — pass optional metadata stored alongside your membership.
+// Returns { history } — the room's last 200 messages, replayed for late joiners.
+const { history } = await baasix.realtime.joinRoom('game:lobby', {
   username: 'Alice',
   avatar: 'https://example.com/alice.png',
   team: 'blue',
 });
 
+// Replay buffered messages so the user sees missed events immediately
+// Each entry: { event, payload, sender: { userId, socketId }, timestamp }
+history.forEach((msg) => {
+  addMessageToUI(msg.sender.userId, msg.payload.text);
+});
+
 // Get current members (you must be in the room)
 // Each entry includes userId, socketId, isCreator, and metadata
 const members = await baasix.realtime.getRoomMembers('game:lobby');
 // [{ socketId: string, userId: string|number, isCreator: boolean, metadata: Record<string,any> }, ...]
 
-// Send a message to all room members
+// List all active rooms — no membership required
+const rooms = await baasix.realtime.listRooms();
+// [{ name: 'game:lobby', memberCount: 4 }, { name: 'chat:general', memberCount: 12 }]
+
+// Filter by name prefix — e.g. show only 'game:' rooms
+const gameRooms = await baasix.realtime.listRooms('game:');
+// [{ name: 'game:lobby', memberCount: 4 }, { name: 'game:arena', memberCount: 8 }]
+
+// Send a persisted message — stored in the history buffer (default)
 await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
 
+// Send an ephemeral message — broadcast only, NOT stored in history
+// Ideal for high-frequency events: cursors, typing indicators, presence pings
+await baasix.realtime.sendToRoom('game:lobby', 'typing', { userId }, { history: false });
+await baasix.realtime.sendToRoom('game:lobby', 'cursor', { x: 120, y: 340 }, { history: false });
+
 // Listen for room messages
 const unsubscribe = baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
   console.log(`${data.sender.userId}: ${data.payload.text}`);

package/dist/index.cjs

@@ -3791,6 +3791,39 @@ var RealtimeModule = class {
       });
     });
   }
+  /**
+   * List all active custom rooms, optionally filtered by a name prefix.
+   *
+   * Returns every room that currently has at least one member.
+   * You do **not** need to be a member of a room to list it.
+   *
+   * @param prefix - Optional prefix to filter rooms. E.g. `"game:"` returns only
+   *   rooms whose name starts with `"game:"`.
+   *
+   * @example
+   * ```typescript
+   * // All active rooms
+   * const rooms = await baasix.realtime.listRooms();
+   * // [{ name: 'game:lobby', memberCount: 4 }, { name: 'chat:general', memberCount: 12 }]
+   *
+   * // Only rooms whose name starts with 'game:'
+   * const gameRooms = await baasix.realtime.listRooms('game:');
+   * ```
+   */
+  async listRooms(prefix) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket.emit("room:list", { prefix: prefix ?? "" }, (response) => {
+        if (response.status === "success") {
+          resolve(response.rooms);
+        } else {
+          reject(new Error(response.message || "Failed to list rooms"));
+        }
+      });
+    });
+  }
   /**
    * Kick a user from a custom room. Only the room creator may call this.
    *