@baasix/sdk 0.1.7 → 0.1.9

package/README.md

@@ -1053,6 +1053,57 @@ const channel = baasix.realtime
 channel.unsubscribe();
 ```
 
+### Custom Rooms
+
+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', {
+  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, metadata: Record<string,any> }, ...]
+
+// Send a message to all room members
+await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
+
+// Listen for room messages
+const unsubscribe = baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
+  console.log(`${data.sender.userId}: ${data.payload.text}`);
+});
+
+// Listen for users joining / leaving (joined event includes their metadata)
+baasix.realtime.onRoomUserJoined('game:lobby', (data) => {
+  console.log(`${data.metadata.username} joined`);
+});
+baasix.realtime.onRoomUserLeft('game:lobby', (data) => {
+  console.log(`${data.userId} left`);
+});
+
+// Kick a user — only the room creator can do this
+await baasix.realtime.kickFromRoom('game:lobby', 'target-user-id');
+
+// Listen for being kicked out (fires only on the kicked user's socket)
+baasix.realtime.onKicked('game:lobby', ({ kickedBy }) => {
+  console.log(`You were kicked by user ${kickedBy}`);
+  // Room listeners are automatically cleaned up after a kick
+});
+
+// Listen for ownership changes (fires for all members when creator changes)
+baasix.realtime.onRoomCreatorChanged('game:lobby', ({ newCreatorUserId }) => {
+  console.log(`New room owner: ${newCreatorUserId}`);
+});
+
+// Leave the room
+await baasix.realtime.leaveRoom('game:lobby');
+```
+
 ### Connection Management
 
 ```typescript

package/dist/index.cjs

@@ -3293,6 +3293,8 @@ var RealtimeModule = class {
   roomCallbacks = /* @__PURE__ */ new Map();
   // room -> event -> callbacks
   roomUserCallbacks = /* @__PURE__ */ new Map();
+  kickCallbacks = /* @__PURE__ */ new Map();
+  creatorChangedCallbacks = /* @__PURE__ */ new Map();
   connectionCallbacks = /* @__PURE__ */ new Set();
   reconnecting = false;
   connectionPromise = null;
@@ -3422,6 +3424,27 @@ var RealtimeModule = class {
             }
           });
         });
+        this.socket.on("room:kicked", (data) => {
+          const callbacks = this.kickCallbacks.get(data.room);
+          callbacks?.forEach((cb) => {
+            try {
+              cb(data);
+            } catch (e) {
+              console.error("[Baasix Realtime] Error in room kicked callback:", e);
+            }
+          });
+          this.cleanupRoomListeners(data.room);
+        });
+        this.socket.on("room:creator:changed", (data) => {
+          const callbacks = this.creatorChangedCallbacks.get(data.room);
+          callbacks?.forEach((cb) => {
+            try {
+              cb(data);
+            } catch (e) {
+              console.error("[Baasix Realtime] Error in room creator changed callback:", e);
+            }
+          });
+        });
         this.socket.connect();
       } catch (error) {
         this.connectionPromise = null;
@@ -3451,6 +3474,8 @@ var RealtimeModule = class {
     this.workflowCallbacks.clear();
     this.roomCallbacks.clear();
     this.roomUserCallbacks.clear();
+    this.kickCallbacks.clear();
+    this.creatorChangedCallbacks.clear();
   }
   /**
    * Check if connected to the realtime server
@@ -3670,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();
@@ -3721,6 +3757,113 @@ 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.metadata.username, m.isCreator ? '(owner)' : '');
+   * });
+   * ```
+   */
+  async getRoomMembers(roomName) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket.emit("room:members", { room: roomName }, (response) => {
+        if (response.status === "success") {
+          resolve(response.members);
+        } else {
+          reject(new Error(response.message || "Failed to get room members"));
+        }
+      });
+    });
+  }
+  /**
+   * Kick a user from a custom room. Only the room creator may call this.
+   *
+   * @example
+   * ```typescript
+   * await baasix.realtime.kickFromRoom('game:lobby', 'user-id-123');
+   * ```
+   */
+  async kickFromRoom(roomName, targetUserId) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket.emit(
+        "room:kick",
+        { room: roomName, userId: targetUserId },
+        (response) => {
+          if (response.status === "success") {
+            resolve();
+          } else {
+            reject(new Error(response.message || "Failed to kick user"));
+          }
+        }
+      );
+    });
+  }
+  /**
+   * Listen for being kicked from a room.
+   * The callback fires when the current user is removed by the room creator.
+   * Room listeners are automatically cleaned up after the kick.
+   *
+   * @example
+   * ```typescript
+   * baasix.realtime.onKicked('game:lobby', ({ kickedBy }) => {
+   *   console.log(`You were kicked by user ${kickedBy}`);
+   * });
+   * ```
+   */
+  onKicked(roomName, callback) {
+    if (!this.kickCallbacks.has(roomName)) {
+      this.kickCallbacks.set(roomName, /* @__PURE__ */ new Set());
+    }
+    this.kickCallbacks.get(roomName).add(callback);
+    return () => {
+      const callbacks = this.kickCallbacks.get(roomName);
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.kickCallbacks.delete(roomName);
+        }
+      }
+    };
+  }
+  /**
+   * Listen for room ownership changes (e.g. when the creator leaves).
+   *
+   * @example
+   * ```typescript
+   * baasix.realtime.onRoomCreatorChanged('game:lobby', ({ newCreatorUserId }) => {
+   *   console.log(`New room owner: ${newCreatorUserId}`);
+   * });
+   * ```
+   */
+  onRoomCreatorChanged(roomName, callback) {
+    if (!this.creatorChangedCallbacks.has(roomName)) {
+      this.creatorChangedCallbacks.set(roomName, /* @__PURE__ */ new Set());
+    }
+    this.creatorChangedCallbacks.get(roomName).add(callback);
+    return () => {
+      const callbacks = this.creatorChangedCallbacks.get(roomName);
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.creatorChangedCallbacks.delete(roomName);
+        }
+      }
+    };
+  }
   /**
    * Send a message to a room
    * 
@@ -3873,6 +4016,8 @@ var RealtimeModule = class {
   cleanupRoomListeners(roomName) {
     this.roomCallbacks.delete(roomName);
     this.roomUserCallbacks.delete(roomName);
+    this.kickCallbacks.delete(roomName);
+    this.creatorChangedCallbacks.delete(roomName);
   }
   // ===================
   // Channel (Room) API - Supabase-style