@base44-preview/sdk 0.8.27-pr.171.bb56537 → 0.8.28-pr.173.186369a

package/dist/client.js

@@ -122,11 +122,19 @@ export function createClient(config) {
             userAuthModule.setToken(accessToken);
         }
     }
+    const userAnalyticsModule = createAnalyticsModule({
+        axiosClient,
+        serverUrl,
+        appId,
+        userAuthModule,
+    });
     const userModules = {
         entities: createEntitiesModule({
             axios: axiosClient,
             appId,
             getSocket,
+            subscriptionOptions: options === null || options === void 0 ? void 0 : options.entitySubscriptions,
+            trackSubscriptionEvent: userAnalyticsModule.track,
         }),
         integrations: createIntegrationsModule(axiosClient, appId),
         connectors: createUserConnectorsModule(axiosClient, appId),
@@ -152,12 +160,7 @@ export function createClient(config) {
         }),
         appLogs: createAppLogsModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
-        analytics: createAnalyticsModule({
-            axiosClient,
-            serverUrl,
-            appId,
-            userAuthModule,
-        }),
+        analytics: userAnalyticsModule,
         cleanup: () => {
             userModules.analytics.cleanup();
             if (socket) {
@@ -170,6 +173,7 @@ export function createClient(config) {
             axios: serviceRoleAxiosClient,
             appId,
             getSocket,
+            subscriptionOptions: options === null || options === void 0 ? void 0 : options.entitySubscriptions,
         }),
         integrations: createIntegrationsModule(serviceRoleAxiosClient, appId),
         sso: createSsoModule(serviceRoleAxiosClient, appId),

package/dist/client.types.d.ts

@@ -1,4 +1,4 @@
-import type { EntitiesModule } from "./modules/entities.types.js";
+import type { EntitiesModule, EntitySubscriptionOptions } from "./modules/entities.types.js";
 import type { IntegrationsModule } from "./modules/integrations.types.js";
 import type { AuthModule } from "./modules/auth.types.js";
 import type { SsoModule } from "./modules/sso.types.js";
@@ -15,6 +15,10 @@ export interface CreateClientOptions {
      * Optional error handler that will be called whenever an API error occurs.
      */
     onError?: (error: Error) => void;
+    /**
+     * Client-side controls for realtime entity subscriptions.
+     */
+    entitySubscriptions?: EntitySubscriptionOptions;
 }
 /**
  * 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 { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
+export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntitySubscriptionOptions, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";

package/dist/modules/entities.d.ts

@@ -1,5 +1,6 @@
 import { AxiosInstance } from "axios";
-import { EntitiesModule } from "./entities.types";
+import { EntitiesModule, EntitySubscriptionOptions } from "./entities.types";
+import type { TrackEventParams } from "./analytics.types";
 import { RoomsSocket } from "../utils/socket-utils.js";
 /**
  * Configuration for the entities module.
@@ -9,6 +10,8 @@ export interface EntitiesModuleConfig {
     axios: AxiosInstance;
     appId: string;
     getSocket: () => ReturnType<typeof RoomsSocket>;
+    subscriptionOptions?: EntitySubscriptionOptions;
+    trackSubscriptionEvent?: (params: TrackEventParams) => void;
 }
 /**
  * Creates the entities module for the Base44 SDK.

package/dist/modules/entities.js

@@ -1,3 +1,8 @@
+const DEFAULT_MAX_ACTIVE_ENTITY_SUBSCRIPTIONS = 100;
+const DEFAULT_SUBSCRIPTION_CHURN_WARNING_THRESHOLD = 20;
+const DEFAULT_SUBSCRIPTION_CHURN_WINDOW_MS = 60000;
+const DEFAULT_EMPTY_ROOM_GRACE_MS = 1000;
+const ENTITY_SUBSCRIPTION_WARNING_EVENT_NAME = "__entity_subscription_warning__";
 /**
  * Creates the entities module for the Base44 SDK.
  *
@@ -7,6 +12,13 @@
  */
 export function createEntitiesModule(config) {
     const { axios, appId, getSocket } = config;
+    const entityHandlers = new Map();
+    const subscriptionManager = createEntitySubscriptionManager({
+        appId,
+        getSocket,
+        options: config.subscriptionOptions,
+        trackSubscriptionEvent: config.trackSubscriptionEvent,
+    });
     // Using Proxy to dynamically handle entity names
     return new Proxy({}, {
         get(target, entityName) {
@@ -16,8 +28,14 @@ export function createEntitiesModule(config) {
                 entityName.startsWith("_")) {
                 return undefined;
             }
+            const cachedHandler = entityHandlers.get(entityName);
+            if (cachedHandler) {
+                return cachedHandler;
+            }
             // Create entity handler
-            return createEntityHandler(axios, appId, entityName, getSocket);
+            const handler = createEntityHandler(axios, appId, entityName, subscriptionManager);
+            entityHandlers.set(entityName, handler);
+            return handler;
         },
     });
 }
@@ -41,17 +59,226 @@ function parseRealtimeMessage(dataStr) {
         return null;
     }
 }
+function normalizeEntitySubscriptionOptions(options) {
+    return {
+        maxActiveSubscriptions: normalizePositiveInteger(options === null || options === void 0 ? void 0 : options.maxActiveSubscriptions, DEFAULT_MAX_ACTIVE_ENTITY_SUBSCRIPTIONS),
+        churnWarningThreshold: normalizePositiveInteger(options === null || options === void 0 ? void 0 : options.churnWarningThreshold, DEFAULT_SUBSCRIPTION_CHURN_WARNING_THRESHOLD),
+        churnWindowMs: normalizePositiveInteger(options === null || options === void 0 ? void 0 : options.churnWindowMs, DEFAULT_SUBSCRIPTION_CHURN_WINDOW_MS),
+        emptyRoomGraceMs: normalizeNonNegativeInteger(options === null || options === void 0 ? void 0 : options.emptyRoomGraceMs, DEFAULT_EMPTY_ROOM_GRACE_MS),
+    };
+}
+function normalizePositiveInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function createEntitySubscriptionManager({ appId, getSocket, options, trackSubscriptionEvent, }) {
+    const normalizedOptions = normalizeEntitySubscriptionOptions(options);
+    const activeSubscriptions = new Map();
+    const churnByRoom = new Map();
+    const roomsWarnedForCap = new Set();
+    let nextCallbackId = 1;
+    function makeRoom(entityName) {
+        return `entities:${appId}:${entityName}`;
+    }
+    function emitWarning(message, properties) {
+        console.warn(message);
+        try {
+            trackSubscriptionEvent === null || trackSubscriptionEvent === void 0 ? void 0 : trackSubscriptionEvent({
+                eventName: ENTITY_SUBSCRIPTION_WARNING_EVENT_NAME,
+                properties,
+            });
+        }
+        catch (_a) {
+            // Diagnostics should never break application code.
+        }
+    }
+    function recordSubscriptionActivity(room, entityName, action) {
+        var _a;
+        const now = Date.now();
+        const churnState = (_a = churnByRoom.get(room)) !== null && _a !== void 0 ? _a : {
+            events: [],
+            lastWarningAt: null,
+        };
+        churnState.events = churnState.events.filter((event) => now - event.timestamp <= normalizedOptions.churnWindowMs);
+        churnState.events.push({ action, timestamp: now });
+        churnByRoom.set(room, churnState);
+        const subscribeCount = churnState.events.filter((event) => event.action === "subscribe").length;
+        const unsubscribeCount = churnState.events.length - subscribeCount;
+        if (churnState.events.length < normalizedOptions.churnWarningThreshold ||
+            subscribeCount === 0 ||
+            unsubscribeCount === 0 ||
+            (churnState.lastWarningAt !== null &&
+                now - churnState.lastWarningAt < normalizedOptions.churnWindowMs)) {
+            return;
+        }
+        churnState.lastWarningAt = now;
+        emitWarning(`[Base44 SDK] entities.${entityName}.subscribe() is being created and cleaned up repeatedly ` +
+            `(${churnState.events.length} subscribe/unsubscribe operations in ` +
+            `${normalizedOptions.churnWindowMs}ms). Keep realtime subscriptions in a stable lifecycle to avoid socket churn.`, {
+            reason: "subscription_churn",
+            app_id: appId,
+            entity: entityName,
+            room,
+            action,
+            activity_count: churnState.events.length,
+            subscribe_count: subscribeCount,
+            unsubscribe_count: unsubscribeCount,
+            churn_window_ms: normalizedOptions.churnWindowMs,
+            empty_room_grace_ms: normalizedOptions.emptyRoomGraceMs,
+            churn_warning_threshold: normalizedOptions.churnWarningThreshold,
+        });
+    }
+    function warnForSubscriptionCap(room, entityName) {
+        if (roomsWarnedForCap.has(room)) {
+            return;
+        }
+        roomsWarnedForCap.add(room);
+        emitWarning(`[Base44 SDK] Realtime entity subscription cap reached ` +
+            `(${normalizedOptions.maxActiveSubscriptions} active entities per SDK client/tab). ` +
+            `Skipping entities.${entityName}.subscribe(). Unsubscribe from unused entity subscriptions before subscribing to more entities.`, {
+            reason: "active_subscription_cap",
+            app_id: appId,
+            entity: entityName,
+            room,
+            active_subscription_count: activeSubscriptions.size,
+            max_active_subscriptions: normalizedOptions.maxActiveSubscriptions,
+        });
+    }
+    function closeRoomSubscription(state) {
+        clearPendingClose(state);
+        state.unsubscribeFromRoom();
+        activeSubscriptions.delete(state.room);
+        if (activeSubscriptions.size < normalizedOptions.maxActiveSubscriptions) {
+            roomsWarnedForCap.clear();
+        }
+    }
+    function clearPendingClose(state) {
+        if (!state.closeTimer) {
+            return;
+        }
+        clearTimeout(state.closeTimer);
+        state.closeTimer = null;
+    }
+    function scheduleRoomClose(state) {
+        var _a;
+        if (state.closeTimer) {
+            return;
+        }
+        if (normalizedOptions.emptyRoomGraceMs === 0) {
+            closeRoomSubscription(state);
+            return;
+        }
+        const closeTimer = setTimeout(() => {
+            state.closeTimer = null;
+            if (state.callbacks.size === 0 &&
+                activeSubscriptions.get(state.room) === state) {
+                closeRoomSubscription(state);
+            }
+        }, normalizedOptions.emptyRoomGraceMs);
+        (_a = closeTimer.unref) === null || _a === void 0 ? void 0 : _a.call(closeTimer);
+        state.closeTimer = closeTimer;
+    }
+    function dispatchRealtimeMessage(state, dataStr) {
+        var _a;
+        if (state.callbacks.size === 0) {
+            return;
+        }
+        const event = parseRealtimeMessage(dataStr);
+        if (!event) {
+            return;
+        }
+        // Server signals oversize broadcasts with `_oversize: true` on
+        // `data`. The wire payload was slimmed to fit under the realtime
+        // transport cap, so big string fields arrive as empty strings (or
+        // the whole record collapses to a stub). Surface this to the
+        // developer console so they know to fetch the full record on
+        // demand (e.g. a follow-up entities.X.get(id) call) instead of
+        // rendering the slimmed payload directly. Skip on delete events
+        // — the record no longer exists.
+        if (event.type !== "delete" && ((_a = event.data) === null || _a === void 0 ? void 0 : _a._oversize)) {
+            console.error(`[Base44 SDK] Realtime broadcast for ${state.entityName}#${event.id} was oversize and got slimmed for transport. ` +
+                `Fields >10 KB are empty and the rest of the record may be a stub. ` +
+                `Call \`entities.${state.entityName}.get("${event.id}")\` to fetch the full record.`);
+        }
+        Array.from(state.callbacks.values()).forEach((callback) => {
+            try {
+                callback(event);
+            }
+            catch (error) {
+                console.error("[Base44 SDK] Subscription callback error:", error);
+            }
+        });
+    }
+    function openRoomSubscription(entityName, room) {
+        const state = {
+            room,
+            entityName,
+            callbacks: new Map(),
+            unsubscribeFromRoom: () => { },
+            closeTimer: null,
+        };
+        const socket = getSocket();
+        state.unsubscribeFromRoom = socket.subscribeToRoom(room, {
+            update_model: (msg) => {
+                dispatchRealtimeMessage(state, msg.data);
+            },
+        });
+        activeSubscriptions.set(room, state);
+        return state;
+    }
+    return {
+        subscribe(entityName, callback) {
+            const room = makeRoom(entityName);
+            recordSubscriptionActivity(room, entityName, "subscribe");
+            let state = activeSubscriptions.get(room);
+            if (!state) {
+                if (activeSubscriptions.size >=
+                    normalizedOptions.maxActiveSubscriptions) {
+                    warnForSubscriptionCap(room, entityName);
+                    return () => { };
+                }
+                state = openRoomSubscription(entityName, room);
+            }
+            else {
+                clearPendingClose(state);
+            }
+            const callbackId = nextCallbackId++;
+            state.callbacks.set(callbackId, callback);
+            let unsubscribed = false;
+            return () => {
+                if (unsubscribed) {
+                    return;
+                }
+                unsubscribed = true;
+                recordSubscriptionActivity(room, entityName, "unsubscribe");
+                state.callbacks.delete(callbackId);
+                if (state.callbacks.size === 0 &&
+                    activeSubscriptions.get(room) === state) {
+                    scheduleRoomClose(state);
+                }
+            };
+        },
+    };
+}
 /**
  * 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
+ * @param subscriptionManager - Shared realtime subscription manager
  * @returns Entity handler with CRUD methods
  * @internal
  */
-function createEntityHandler(axios, appId, entityName, getSocket) {
+function createEntityHandler(axios, appId, entityName, subscriptionManager) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
     return {
         // List entities with optional pagination and sorting
@@ -126,38 +353,7 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
         },
         // Subscribe to realtime updates
         subscribe(callback) {
-            const room = `entities:${appId}:${entityName}`;
-            // Get the socket and subscribe to the room
-            const socket = getSocket();
-            const unsubscribe = socket.subscribeToRoom(room, {
-                update_model: (msg) => {
-                    var _a;
-                    const event = parseRealtimeMessage(msg.data);
-                    if (!event) {
-                        return;
-                    }
-                    // Server signals oversize broadcasts with `_oversize: true` on
-                    // `data`. The wire payload was slimmed to fit under the realtime
-                    // transport cap, so big string fields arrive as empty strings (or
-                    // the whole record collapses to a stub). Surface this to the
-                    // developer console so they know to fetch the full record on
-                    // demand (e.g. a follow-up entities.X.get(id) call) instead of
-                    // rendering the slimmed payload directly. Skip on delete events
-                    // — the record no longer exists.
-                    if (event.type !== "delete" && ((_a = event.data) === null || _a === void 0 ? void 0 : _a._oversize)) {
-                        console.error(`[Base44 SDK] Realtime broadcast for ${entityName}#${event.id} was oversize and got slimmed for transport. ` +
-                            `Fields >10 KB are empty and the rest of the record may be a stub. ` +
-                            `Call \`entities.${entityName}.get("${event.id}")\` to fetch the full record.`);
-                    }
-                    try {
-                        callback(event);
-                    }
-                    catch (error) {
-                        console.error("[Base44 SDK] Subscription callback error:", error);
-                    }
-                },
-            });
-            return unsubscribe;
+            return subscriptionManager.subscribe(entityName, callback);
         },
     };
 }

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

@@ -23,6 +23,42 @@ export interface RealtimeEvent<T = any> {
  * @typeParam T - The entity type for the event data. Defaults to `any`.
  */
 export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
+/**
+ * Client-side controls for realtime entity subscriptions.
+ */
+export interface EntitySubscriptionOptions {
+    /**
+     * Maximum number of distinct active entity realtime subscriptions allowed
+     * for one SDK client instance. Repeated subscriptions to the same entity
+     * share one active entity subscription and do not count again.
+     *
+     * @defaultValue `100`
+     */
+    maxActiveSubscriptions?: number;
+    /**
+     * Number of subscribe/unsubscribe operations for the same entity within
+     * `churnWindowMs` before the SDK logs a warning and emits diagnostic
+     * telemetry.
+     *
+     * @defaultValue `20`
+     */
+    churnWarningThreshold?: number;
+    /**
+     * Time window, in milliseconds, used to detect repeated subscribe/unsubscribe
+     * churn for one entity.
+     *
+     * @defaultValue `60000`
+     */
+    churnWindowMs?: number;
+    /**
+     * Grace period, in milliseconds, before the SDK leaves an entity realtime
+     * room after its last local callback unsubscribes. A new subscription to
+     * the same entity during this window reuses the existing room membership.
+     *
+     * @defaultValue `1000`
+     */
+    emptyRoomGraceMs?: number;
+}
 /**
  * Result returned when deleting a single entity.
  */

package/dist/utils/socket-utils.js

@@ -88,7 +88,8 @@ export function RoomsSocket({ config }) {
         return (_a = handlers.update_model) === null || _a === void 0 ? void 0 : _a.call(handlers, { room, data: dataStr });
     }
     function getListeners(room) {
-        return roomsToListeners[room];
+        var _a;
+        return (_a = roomsToListeners[room]) !== null && _a !== void 0 ? _a : [];
     }
     const subscribeToRoom = (room, handlers) => {
         if (!roomsToListeners[room]) {
@@ -102,6 +103,7 @@ export function RoomsSocket({ config }) {
                 (_b = (_a = roomsToListeners[room]) === null || _a === void 0 ? void 0 : _a.filter((listener) => listener !== handlers)) !== null && _b !== void 0 ? _b : [];
             if (roomsToListeners[room].length === 0) {
                 leaveRoom(room);
+                delete roomsToListeners[room];
             }
         };
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.27-pr.171.bb56537",
+  "version": "0.8.28-pr.173.186369a",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",