@base44-preview/sdk 0.8.11-pr.58.0494dbf → 0.8.11-pr.58.a137910

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
-export type { EntitiesModule, EntityHandler, RealtimeEventType, RealtimeEvent, RealtimeCallback, Subscription, } from "./modules/entities.types.js";
+export type { EntitiesModule, EntityHandler, RealtimeEventType, RealtimeEvent, RealtimeCallback, SubscribeOptions, Subscription, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationPackage, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule } from "./modules/functions.types.js";

package/dist/modules/entities.js

@@ -24,6 +24,24 @@ export function createEntitiesModule(configOrAxios, appIdArg) {
         },
     });
 }
+/**
+ * Creates a stable hash from a query object for room naming.
+ * @internal
+ */
+function hashQuery(query) {
+    const sortedKeys = Object.keys(query).sort();
+    const normalized = sortedKeys
+        .map((k) => `${k}:${JSON.stringify(query[k])}`)
+        .join("|");
+    // Simple hash function
+    let hash = 0;
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
 /**
  * Parses the realtime message data and extracts event information.
  * @internal
@@ -37,6 +55,7 @@ function parseRealtimeMessage(dataStr) {
             data: parsed.data,
             id: parsed.id || ((_a = parsed.data) === null || _a === void 0 ? void 0 : _a.id),
             timestamp: parsed.timestamp || new Date().toISOString(),
+            previousData: parsed.previousData,
         };
     }
     catch (_b) {
@@ -119,24 +138,51 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
             });
         },
         // Subscribe to realtime updates
-        subscribe(callback) {
-            const room = `entities:${appId}:${entityName}`;
+        subscribe(callbackOrIdOrQuery, callbackOrOptions, optionsArg) {
+            let room;
+            let callback;
+            let options;
+            // Parse overloaded arguments
+            if (typeof callbackOrIdOrQuery === "function") {
+                // subscribe(callback, options?)
+                room = `entities:${appId}:${entityName}`;
+                callback = callbackOrIdOrQuery;
+                options = callbackOrOptions;
+            }
+            else if (typeof callbackOrIdOrQuery === "string") {
+                // subscribe(id, callback, options?)
+                room = `entities:${appId}:${entityName}:${callbackOrIdOrQuery}`;
+                callback = callbackOrOptions;
+                options = optionsArg;
+            }
+            else {
+                // subscribe(query, callback, options?)
+                const queryHash = hashQuery(callbackOrIdOrQuery);
+                room = `entities:${appId}:${entityName}:query:${queryHash}`;
+                callback = callbackOrOptions;
+                options = optionsArg;
+            }
+            const eventFilter = options === null || options === void 0 ? void 0 : options.events;
             // Get the socket and subscribe to the room
             const socket = getSocket();
             const unsubscribe = socket.subscribeToRoom(room, {
                 update_model: (msg) => {
                     // Only process messages for our room
-                    if (msg.room !== room) {
+                    if (msg.room !== room)
                         return;
-                    }
                     const event = parseRealtimeMessage(msg.data);
-                    if (!event) {
+                    if (!event)
+                        return;
+                    // Apply event type filter if specified
+                    if (eventFilter && !eventFilter.includes(event.type)) {
                         return;
                     }
                     callback(event);
                 },
             });
-            return unsubscribe;
+            return {
+                unsubscribe,
+            };
         },
     };
 }

package/dist/modules/entities.types.d.ts

@@ -14,15 +14,27 @@ export interface RealtimeEvent<T = Record<string, any>> {
     id: string;
     /** ISO 8601 timestamp of when the event occurred */
     timestamp: string;
+    /** For update events, contains the previous data before the change */
+    previousData?: T;
 }
 /**
  * Callback function invoked when a realtime event occurs.
  */
 export type RealtimeCallback<T = Record<string, any>> = (event: RealtimeEvent<T>) => void;
 /**
- * Function returned from subscribe, call it to unsubscribe.
+ * Options for subscribing to realtime updates.
  */
-export type Subscription = () => void;
+export interface SubscribeOptions {
+    /** Filter events by type. Defaults to all types. */
+    events?: RealtimeEventType[];
+}
+/**
+ * Handle returned from subscribe, used to unsubscribe.
+ */
+export interface Subscription {
+    /** Stops listening to updates and cleans up the subscription. */
+    unsubscribe: () => void;
+}
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -273,20 +285,87 @@ export interface EntityHandler {
      * Receives notifications whenever any record is created, updated, or deleted.
      *
      * @param callback - Function called when an entity changes.
-     * @returns Unsubscribe function to stop listening.
+     * @param options - Optional configuration for filtering events.
+     * @returns Subscription handle with an unsubscribe method.
      *
      * @example
      * ```typescript
      * // Subscribe to all Task changes
-     * const unsubscribe = base44.entities.Task.subscribe((event) => {
+     * const subscription = base44.entities.Task.subscribe((event) => {
      *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
      * });
      *
      * // Later, unsubscribe
-     * unsubscribe();
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Subscribe only to create events
+     * const subscription = base44.entities.Task.subscribe(
+     *   (event) => console.log("New task:", event.data),
+     *   { events: ["create"] }
+     * );
+     * ```
+     */
+    subscribe(callback: RealtimeCallback, options?: SubscribeOptions): Subscription;
+    /**
+     * Subscribes to realtime updates for a specific entity record.
+     *
+     * Receives notifications when the specified record is updated or deleted.
+     *
+     * @param id - The unique identifier of the record to watch.
+     * @param callback - Function called when the entity changes.
+     * @param options - Optional configuration for filtering events.
+     * @returns Subscription handle with an unsubscribe method.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to a specific task
+     * const subscription = base44.entities.Task.subscribe("task-123", (event) => {
+     *   if (event.type === "update") {
+     *     console.log("Task updated:", event.data);
+     *   } else if (event.type === "delete") {
+     *     console.log("Task was deleted");
+     *   }
+     * });
+     * ```
+     */
+    subscribe(id: string, callback: RealtimeCallback, options?: SubscribeOptions): Subscription;
+    /**
+     * Subscribes to realtime updates for records matching a query.
+     *
+     * Receives notifications for records that match the specified criteria.
+     * Includes create events when new records match the query, update events
+     * when matching records change, and delete events when matching records
+     * are removed.
+     *
+     * @param query - Query object with field-value pairs to filter records.
+     * @param callback - Function called when a matching entity changes.
+     * @param options - Optional configuration for filtering events.
+     * @returns Subscription handle with an unsubscribe method.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all completed tasks
+     * const subscription = base44.entities.Task.subscribe(
+     *   { isCompleted: true },
+     *   (event) => {
+     *     console.log(`Completed task ${event.type}:`, event.data);
+     *   }
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to high-priority active tasks
+     * const subscription = base44.entities.Task.subscribe(
+     *   { priority: "high", status: "active" },
+     *   (event) => console.log("High priority task changed:", event.data)
+     * );
      * ```
      */
-    subscribe(callback: RealtimeCallback): Subscription;
+    subscribe(query: Record<string, any>, callback: RealtimeCallback, options?: SubscribeOptions): Subscription;
 }
 /**
  * Entities module for managing app data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.11-pr.58.0494dbf",
+  "version": "0.8.11-pr.58.a137910",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",