@baasix/sdk 0.1.8 → 0.1.9

package/README.md

@@ -1058,12 +1058,17 @@ 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
-await baasix.realtime.joinRoom('game:lobby');
+// Join a room — pass optional metadata stored alongside your membership
+await baasix.realtime.joinRoom('game:lobby', {
+  username: 'Alice',
+  avatar: 'https://example.com/alice.png',
+  team: 'blue',
+});
 
 // 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 }, ...]
+// [{ socketId: string, userId: string|number, isCreator: boolean, metadata: Record<string,any> }, ...]
 
 // Send a message to all room members
 await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
@@ -1073,9 +1078,9 @@ const unsubscribe = baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) =
   console.log(`${data.sender.userId}: ${data.payload.text}`);
 });
 
-// Listen for users joining / leaving
+// Listen for users joining / leaving (joined event includes their metadata)
 baasix.realtime.onRoomUserJoined('game:lobby', (data) => {
-  console.log(`${data.userId} joined`);
+  console.log(`${data.metadata.username} joined`);
 });
 baasix.realtime.onRoomUserLeft('game:lobby', (data) => {
   console.log(`${data.userId} left`);

package/dist/index.cjs

@@ -3695,25 +3695,36 @@ 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.
+   *
+   * @param roomName - The room to join.
+   * @param metadata - Optional key/value pairs stored alongside this member.
+   *
    * @example
    * ```typescript
-   * // Join a room
-   * await baasix.realtime.joinRoom('game:lobby');
-   * 
-   * // Listen for messages
-   * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-   *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+   * // Join a room with metadata
+   * await baasix.realtime.joinRoom('game:lobby', {
+   *   username: 'Alice',
+   *   avatar: 'https://example.com/alice.png',
+   *   team: 'blue',
+   * });
+   *
+   * // Listen for other users joining (includes their metadata)
+   * baasix.realtime.onUserJoined('game:lobby', (data) => {
+   *   console.log(data.metadata.username, 'joined');
    * });
    * ```
    */
-  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();
@@ -3750,11 +3761,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)' : '');
    * });
    * ```
    */