@baasix/sdk 0.1.7 → 0.1.9

package/dist/index.d.cts

@@ -1076,8 +1076,26 @@ interface RoomUserEvent {
     room: string;
     userId: string | number;
     socketId: string;
+    metadata: Record<string, any>;
     timestamp: string;
 }
+interface RoomKickEvent {
+    room: string;
+    kickedBy: string | number;
+    timestamp: string;
+}
+interface RoomCreatorChangedEvent {
+    room: string;
+    newCreatorSocketId: string;
+    newCreatorUserId: string | number;
+    timestamp: string;
+}
+interface RoomMember {
+    socketId: string;
+    userId: string | number;
+    isCreator: boolean;
+    metadata: Record<string, any>;
+}
 interface SubscriptionCallback<T = any> {
     (payload: SubscriptionPayload<T>): void;
 }
@@ -1119,6 +1137,8 @@ declare class RealtimeModule {
     private workflowCallbacks;
     private roomCallbacks;
     private roomUserCallbacks;
+    private kickCallbacks;
+    private creatorChangedCallbacks;
     private connectionCallbacks;
     private reconnecting;
     private connectionPromise;
@@ -1249,20 +1269,31 @@ 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.
+     *
+     * @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');
+     * // Join a room with metadata
+     * await baasix.realtime.joinRoom('game:lobby', {
+     *   username: 'Alice',
+     *   avatar: 'https://example.com/alice.png',
+     *   team: 'blue',
+     * });
      *
-     * // Listen for messages
-     * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-     *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+     * // Listen for other users joining (includes their metadata)
+     * baasix.realtime.onUserJoined('game:lobby', (data) => {
+     *   console.log(data.metadata.username, 'joined');
      * });
      * ```
      */
-    joinRoom(roomName: string): Promise<void>;
+    joinRoom(roomName: string, metadata?: Record<string, any>): Promise<void>;
     /**
      * Leave a custom room
      *
@@ -1272,6 +1303,55 @@ declare class RealtimeModule {
      * ```
      */
     leaveRoom(roomName: string): Promise<void>;
+    /**
+     * 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)' : '');
+     * });
+     * ```
+     */
+    getRoomMembers(roomName: string): Promise<RoomMember[]>;
+    /**
+     * 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');
+     * ```
+     */
+    kickFromRoom(roomName: string, targetUserId: string | number): Promise<void>;
+    /**
+     * 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: string, callback: (data: RoomKickEvent) => void): () => void;
+    /**
+     * 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: string, callback: (data: RoomCreatorChangedEvent) => void): () => void;
     /**
      * Send a message to a room
      *

package/dist/index.d.ts

@@ -1076,8 +1076,26 @@ interface RoomUserEvent {
     room: string;
     userId: string | number;
     socketId: string;
+    metadata: Record<string, any>;
     timestamp: string;
 }
+interface RoomKickEvent {
+    room: string;
+    kickedBy: string | number;
+    timestamp: string;
+}
+interface RoomCreatorChangedEvent {
+    room: string;
+    newCreatorSocketId: string;
+    newCreatorUserId: string | number;
+    timestamp: string;
+}
+interface RoomMember {
+    socketId: string;
+    userId: string | number;
+    isCreator: boolean;
+    metadata: Record<string, any>;
+}
 interface SubscriptionCallback<T = any> {
     (payload: SubscriptionPayload<T>): void;
 }
@@ -1119,6 +1137,8 @@ declare class RealtimeModule {
     private workflowCallbacks;
     private roomCallbacks;
     private roomUserCallbacks;
+    private kickCallbacks;
+    private creatorChangedCallbacks;
     private connectionCallbacks;
     private reconnecting;
     private connectionPromise;
@@ -1249,20 +1269,31 @@ 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.
+     *
+     * @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');
+     * // Join a room with metadata
+     * await baasix.realtime.joinRoom('game:lobby', {
+     *   username: 'Alice',
+     *   avatar: 'https://example.com/alice.png',
+     *   team: 'blue',
+     * });
      *
-     * // Listen for messages
-     * baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
-     *   console.log(`${data.sender.userId}: ${data.payload.text}`);
+     * // Listen for other users joining (includes their metadata)
+     * baasix.realtime.onUserJoined('game:lobby', (data) => {
+     *   console.log(data.metadata.username, 'joined');
      * });
      * ```
      */
-    joinRoom(roomName: string): Promise<void>;
+    joinRoom(roomName: string, metadata?: Record<string, any>): Promise<void>;
     /**
      * Leave a custom room
      *
@@ -1272,6 +1303,55 @@ declare class RealtimeModule {
      * ```
      */
     leaveRoom(roomName: string): Promise<void>;
+    /**
+     * 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)' : '');
+     * });
+     * ```
+     */
+    getRoomMembers(roomName: string): Promise<RoomMember[]>;
+    /**
+     * 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');
+     * ```
+     */
+    kickFromRoom(roomName: string, targetUserId: string | number): Promise<void>;
+    /**
+     * 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: string, callback: (data: RoomKickEvent) => void): () => void;
+    /**
+     * 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: string, callback: (data: RoomCreatorChangedEvent) => void): () => void;
     /**
      * Send a message to a room
      *

package/dist/index.js

@@ -3291,6 +3291,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;
@@ -3420,6 +3422,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;
@@ -3449,6 +3472,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
@@ -3668,25 +3693,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();
@@ -3719,6 +3755,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
    * 
@@ -3871,6 +4014,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