@base44-preview/sdk 0.8.6-pr.57.d5771ed → 0.8.6-pr.58.9363801

package/dist/client.js

@@ -10,7 +10,6 @@ import { createAgentsModule } from "./modules/agents.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
-import { createAnalyticsModule } from "./modules/analytics.js";
 /**
  * Creates a Base44 client.
  *
@@ -100,7 +99,11 @@ export function createClient(config) {
         interceptResponses: false,
     });
     const userModules = {
-        entities: createEntitiesModule(axiosClient, appId),
+        entities: createEntitiesModule({
+            axios: axiosClient,
+            appId,
+            getSocket,
+        }),
         integrations: createIntegrationsModule(axiosClient, appId),
         auth: createAuthModule(axiosClient, functionsAxiosClient, appId, {
             appBaseUrl,
@@ -116,11 +119,6 @@ export function createClient(config) {
         }),
         appLogs: createAppLogsModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
-        analytics: createAnalyticsModule({
-            axiosClient,
-            appId,
-            options: options === null || options === void 0 ? void 0 : options.analytics,
-        }),
         cleanup: () => {
             if (socket) {
                 socket.disconnect();
@@ -128,7 +126,11 @@ export function createClient(config) {
         },
     };
     const serviceRoleModules = {
-        entities: createEntitiesModule(serviceRoleAxiosClient, appId),
+        entities: createEntitiesModule({
+            axios: serviceRoleAxiosClient,
+            appId,
+            getSocket,
+        }),
         integrations: createIntegrationsModule(serviceRoleAxiosClient, appId),
         sso: createSsoModule(serviceRoleAxiosClient, appId, token),
         connectors: createConnectorsModule(serviceRoleAxiosClient, appId),

package/dist/client.types.d.ts

@@ -6,7 +6,6 @@ import type { ConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
-import type { AnalyticsModuleOptions } from "./modules/analytics.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -15,7 +14,6 @@ export interface CreateClientOptions {
      * Optional error handler that will be called whenever an API error occurs.
      */
     onError?: (error: Error) => void;
-    analytics?: AnalyticsModuleOptions;
 }
 /**
  * Configuration for creating a Base44 client.

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, } 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.d.ts

@@ -1,5 +1,23 @@
 import { AxiosInstance } from "axios";
 import { EntitiesModule } from "./entities.types";
+import { RoomsSocket } from "../utils/socket-utils";
+/**
+ * Configuration for the entities module.
+ * @internal
+ */
+export interface EntitiesModuleConfig {
+    axios: AxiosInstance;
+    appId: string;
+    getSocket: () => ReturnType<typeof RoomsSocket>;
+}
+/**
+ * Creates the entities module for the Base44 SDK.
+ *
+ * @param config - Configuration object containing axios, appId, and getSocket
+ * @returns Entities module with dynamic entity access
+ * @internal
+ */
+export declare function createEntitiesModule(config: EntitiesModuleConfig): EntitiesModule;
 /**
  * Creates the entities module for the Base44 SDK.
  *
@@ -7,5 +25,6 @@ import { EntitiesModule } from "./entities.types";
  * @param appId - Application ID
  * @returns Entities module with dynamic entity access
  * @internal
+ * @deprecated Use the config object overload instead
  */
 export declare function createEntitiesModule(axios: AxiosInstance, appId: string): EntitiesModule;

package/dist/modules/entities.js

@@ -1,12 +1,15 @@
-/**
- * Creates the entities module for the Base44 SDK.
- *
- * @param axios - Axios instance
- * @param appId - Application ID
- * @returns Entities module with dynamic entity access
- * @internal
- */
-export function createEntitiesModule(axios, appId) {
+export function createEntitiesModule(configOrAxios, appIdArg) {
+    // Handle both old and new signatures for backwards compatibility
+    const config = "axios" in configOrAxios
+        ? configOrAxios
+        : {
+            axios: configOrAxios,
+            appId: appIdArg,
+            getSocket: () => {
+                throw new Error("Realtime subscriptions are not available. Please update your client configuration.");
+            },
+        };
+    const { axios, appId, getSocket } = config;
     // Using Proxy to dynamically handle entity names
     return new Proxy({}, {
         get(target, entityName) {
@@ -17,20 +20,59 @@ export function createEntitiesModule(axios, appId) {
                 return undefined;
             }
             // Create entity handler
-            return createEntityHandler(axios, appId, entityName);
+            return createEntityHandler(axios, appId, entityName, getSocket);
         },
     });
 }
+/**
+ * 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
+ */
+function parseRealtimeMessage(dataStr) {
+    var _a;
+    try {
+        const parsed = JSON.parse(dataStr);
+        return {
+            type: parsed.type,
+            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) {
+        return null;
+    }
+}
 /**
  * Creates a handler for a specific entity.
  *
  * @param axios - Axios instance
  * @param appId - Application ID
  * @param entityName - Entity name
+ * @param getSocket - Function to get the socket instance
  * @returns Entity handler with CRUD methods
  * @internal
  */
-function createEntityHandler(axios, appId, entityName) {
+function createEntityHandler(axios, appId, entityName, getSocket) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
     return {
         // List entities with optional pagination and sorting
@@ -95,5 +137,52 @@ function createEntityHandler(axios, appId, entityName) {
                 },
             });
         },
+        // Subscribe to realtime updates
+        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)
+                        return;
+                    const event = parseRealtimeMessage(msg.data);
+                    if (!event)
+                        return;
+                    // Apply event type filter if specified
+                    if (eventFilter && !eventFilter.includes(event.type)) {
+                        return;
+                    }
+                    callback(event);
+                },
+            });
+            return {
+                unsubscribe,
+            };
+        },
     };
 }

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

@@ -1,3 +1,40 @@
+/**
+ * Event types for realtime entity updates.
+ */
+export type RealtimeEventType = "create" | "update" | "delete";
+/**
+ * Payload received when a realtime event occurs.
+ */
+export interface RealtimeEvent<T = Record<string, any>> {
+    /** The type of change that occurred */
+    type: RealtimeEventType;
+    /** The entity data (new/updated for create/update, previous for delete) */
+    data: T;
+    /** The unique identifier of the affected entity */
+    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;
+/**
+ * Options for subscribing to realtime updates.
+ */
+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.
  *
@@ -242,6 +279,93 @@ export interface EntityHandler {
      * ```
      */
     importEntities(file: File): Promise<any>;
+    /**
+     * Subscribes to realtime updates for all records of this entity type.
+     *
+     * Receives notifications whenever any record is created, updated, or deleted.
+     *
+     * @param callback - Function called when an entity changes.
+     * @param options - Optional configuration for filtering events.
+     * @returns Subscription handle with an unsubscribe method.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all Task changes
+     * const subscription = base44.entities.Task.subscribe((event) => {
+     *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
+     * });
+     *
+     * // Later, 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(query: Record<string, any>, callback: RealtimeCallback, options?: SubscribeOptions): Subscription;
 }
 /**
  * Entities module for managing app data.

package/dist/modules/types.d.ts

@@ -1,4 +1,3 @@
 export * from "./app.types.js";
 export * from "./agents.types.js";
 export * from "./connectors.types.js";
-export * from "./analytics.types.js";

package/dist/modules/types.js

@@ -1,4 +1,3 @@
 export * from "./app.types.js";
 export * from "./agents.types.js";
 export * from "./connectors.types.js";
-export * from "./analytics.types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.6-pr.57.d5771ed",
+  "version": "0.8.6-pr.58.9363801",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/modules/analytics.d.ts

@@ -1,10 +0,0 @@
-import { AxiosInstance } from "axios";
-import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
-export interface AnalyticsModuleArgs {
-    axiosClient: AxiosInstance;
-    appId: string;
-    options?: AnalyticsModuleOptions;
-}
-export declare const createAnalyticsModule: ({ axiosClient, appId, options, }: AnalyticsModuleArgs) => {
-    track: (params: TrackEventParams) => void;
-};

package/dist/modules/analytics.js

@@ -1,68 +0,0 @@
-import { getSharedInstance, getSharedInstanceRefCount, } from "../utils/singleton";
-const ANALYTICS_SHARED_STATE_NAME = "analytics";
-// shared state//
-const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () => ({
-    requestsQueue: [],
-}));
-export const createAnalyticsModule = ({ axiosClient, appId, options, }) => {
-    // prevent overflow of events //
-    const MAX_QUEUE_SIZE = 1000;
-    const isEnabled = (options === null || options === void 0 ? void 0 : options.enabled) !== false;
-    const track = (params) => {
-        if (!isEnabled ||
-            analyticsSharedState.requestsQueue.length >= MAX_QUEUE_SIZE) {
-            return;
-        }
-        const intrinsicData = getEventIntrinsicData();
-        analyticsSharedState.requestsQueue.push({
-            ...params,
-            ...intrinsicData,
-        });
-    };
-    const flush = async (eventsData) => {
-        const apiEvents = eventsData.map(transformEventDataToApiRequestData);
-        await axiosClient.request({
-            method: "POST",
-            url: `/apps/${appId}/analytics/track/batch`,
-            data: { events: apiEvents },
-        });
-    };
-    // start analytics processor only if it's the first instance and analytics is enabled //
-    if (getSharedInstanceRefCount(ANALYTICS_SHARED_STATE_NAME) <= 1 &&
-        isEnabled) {
-        startAnalyticsProcessor(flush, options === null || options === void 0 ? void 0 : options.trackService);
-    }
-    return {
-        track,
-    };
-};
-async function startAnalyticsProcessor(handleTrack, options) {
-    const { throttleTime = 1000, batchSize = 30 } = options !== null && options !== void 0 ? options : {};
-    while (true) {
-        await new Promise((resolve) => setTimeout(resolve, throttleTime));
-        const requests = analyticsSharedState.requestsQueue.splice(0, batchSize);
-        if (requests.length > 0) {
-            try {
-                await handleTrack(requests);
-            }
-            catch (error) {
-                // TODO: think about retries if needed
-                console.error("Error processing analytics request:", error);
-            }
-        }
-    }
-}
-function getEventIntrinsicData() {
-    return {
-        timestamp: new Date().toISOString(),
-        pageUrl: typeof window !== "undefined" ? window.location.href : null,
-    };
-}
-function transformEventDataToApiRequestData(eventData) {
-    return {
-        event_name: eventData.eventName,
-        properties: eventData.properties,
-        timestamp: eventData.timestamp,
-        page_url: eventData.pageUrl,
-    };
-}

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

@@ -1,35 +0,0 @@
-export type TrackEventProperties = {
-    [key: string]: string | number | boolean | null | undefined;
-};
-export type TrackEventParams = {
-    eventName: string;
-    properties?: TrackEventProperties;
-};
-export type TrackEventIntrinsicData = {
-    timestamp: string;
-    pageUrl?: string | null;
-};
-export type TrackEventData = {
-    properties?: TrackEventProperties;
-    eventName: string;
-} & TrackEventIntrinsicData;
-export type AnalyticsApiRequestData = {
-    event_name: string;
-    properties?: TrackEventProperties;
-    timestamp?: string;
-    page_url?: string | null;
-};
-export type AnalyticsApiBatchRequest = {
-    method: "POST";
-    url: `/apps/${string}/analytics/track/batch`;
-    data: {
-        events: AnalyticsApiRequestData[];
-    };
-};
-export type AnalyticsModuleOptions = {
-    enabled?: boolean;
-    trackService?: {
-        throttleTime: number;
-        batchSize: number;
-    };
-};

package/dist/modules/analytics.types.js

@@ -1 +0,0 @@
-export {};

package/dist/utils/singleton.d.ts

@@ -1,2 +0,0 @@
-export declare function getSharedInstance<T>(name: string, factory: () => T): T;
-export declare function getSharedInstanceRefCount<T>(name: string): number;

package/dist/utils/singleton.js

@@ -1,16 +0,0 @@
-// Singleton (shared between sdk instances)//
-export function getSharedInstance(name, factory) {
-    const windowObj = typeof window !== "undefined" ? window : { base44: {} };
-    if (!windowObj.base44) {
-        windowObj.base44 = {};
-    }
-    if (!windowObj.base44[name]) {
-        windowObj.base44[name] = { instance: factory(), _refCount: 1 };
-    }
-    return windowObj.base44[name].instance;
-}
-export function getSharedInstanceRefCount(name) {
-    var _a, _b, _c;
-    const windowObj = typeof window !== "undefined" ? window : { base44: {} };
-    return (_c = (_b = (_a = windowObj.base44) === null || _a === void 0 ? void 0 : _a[name]) === null || _b === void 0 ? void 0 : _b._refCount) !== null && _c !== void 0 ? _c : 0;
-}