@base44/sdk 0.8.12 → 0.8.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 base44
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.js

@@ -104,7 +104,11 @@ export function createClient(config) {
         serverUrl,
     });
     const userModules = {
-        entities: createEntitiesModule(axiosClient, appId),
+        entities: createEntitiesModule({
+            axios: axiosClient,
+            appId,
+            getSocket,
+        }),
         integrations: createIntegrationsModule(axiosClient, appId),
         auth: userAuthModule,
         functions: createFunctionsModule(functionsAxiosClient, appId),
@@ -131,7 +135,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/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, 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/analytics.d.ts

@@ -2,6 +2,8 @@ import { AxiosInstance } from "axios";
 import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
 import type { AuthModule } from "./auth.types";
 export declare const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export declare const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_event__";
+export declare const ANALYTICS_SESSION_DURATION_EVENT_NAME = "__session_duration_event__";
 export declare const ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY = "analytics-enable";
 export declare const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
 export interface AnalyticsModuleArgs {

package/dist/modules/analytics.js

@@ -1,6 +1,8 @@
 import { getSharedInstance } from "../utils/sharedInstance.js";
 import { generateUuid } from "../utils/common.js";
 export const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_event__";
+export const ANALYTICS_SESSION_DURATION_EVENT_NAME = "__session_duration_event__";
 export const ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY = "analytics-enable";
 export const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
 const defaultConfiguration = {
@@ -20,7 +22,9 @@ const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () =
     requestsQueue: [],
     isProcessing: false,
     isHeartBeatProcessing: false,
+    wasInitializationTracked: false,
     sessionContext: null,
+    sessionStartTime: null,
     config: {
         ...defaultConfiguration,
         ...getAnalyticsConfigFromUrlParams(),
@@ -95,10 +99,12 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             batchSize,
         });
         clearHeartBeatProcessor = startHeartBeatProcessor(track);
+        setSessionDurationTimerStart();
     };
     const onDocHidden = () => {
         stopAnalyticsProcessor();
         clearHeartBeatProcessor === null || clearHeartBeatProcessor === void 0 ? void 0 : clearHeartBeatProcessor();
+        trackSessionDurationEvent(track);
         //  flush entire queue on visibility change and hope for the best //
         const eventsData = analyticsSharedState.requestsQueue.splice(0);
         flush(eventsData, { isBeacon: true });
@@ -124,6 +130,8 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
     startProcessing();
     // start the heart beat processor //
     clearHeartBeatProcessor = startHeartBeatProcessor(track);
+    // track the referrer event //
+    trackInitializationEvent(track);
     // start the visibility change listener //
     if (typeof window !== "undefined") {
         window.addEventListener("visibilitychange", onVisibilityChange);
@@ -166,6 +174,38 @@ function startHeartBeatProcessor(track) {
         analyticsSharedState.isHeartBeatProcessing = false;
     };
 }
+function trackInitializationEvent(track) {
+    if (typeof window === "undefined" ||
+        analyticsSharedState.wasInitializationTracked) {
+        return;
+    }
+    analyticsSharedState.wasInitializationTracked = true;
+    track({
+        eventName: ANALYTICS_INITIALIZATION_EVENT_NAME,
+        properties: {
+            referrer: document === null || document === void 0 ? void 0 : document.referrer,
+        },
+    });
+}
+function setSessionDurationTimerStart() {
+    if (typeof window === "undefined" ||
+        analyticsSharedState.sessionStartTime !== null) {
+        return;
+    }
+    analyticsSharedState.sessionStartTime = new Date().toISOString();
+}
+function trackSessionDurationEvent(track) {
+    if (typeof window === "undefined" ||
+        analyticsSharedState.sessionStartTime === null)
+        return;
+    const sessionDuration = new Date().getTime() -
+        new Date(analyticsSharedState.sessionStartTime).getTime();
+    analyticsSharedState.sessionStartTime = null;
+    track({
+        eventName: ANALYTICS_SESSION_DURATION_EVENT_NAME,
+        properties: { sessionDuration },
+    });
+}
 function getEventIntrinsicData() {
     return {
         timestamp: new Date().toISOString(),

package/dist/modules/entities.d.ts

@@ -1,11 +1,20 @@
 import { AxiosInstance } from "axios";
 import { EntitiesModule } from "./entities.types";
+import { RoomsSocket } from "../utils/socket-utils.js";
+/**
+ * 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 axios - Axios instance
- * @param appId - Application ID
+ * @param config - Configuration object containing axios, appId, and getSocket
  * @returns Entities module with dynamic entity access
  * @internal
  */
-export declare function createEntitiesModule(axios: AxiosInstance, appId: string): EntitiesModule;
+export declare function createEntitiesModule(config: EntitiesModuleConfig): EntitiesModule;

package/dist/modules/entities.js

@@ -1,12 +1,12 @@
 /**
  * Creates the entities module for the Base44 SDK.
  *
- * @param axios - Axios instance
- * @param appId - Application ID
+ * @param config - Configuration object containing axios, appId, and getSocket
  * @returns Entities module with dynamic entity access
  * @internal
  */
-export function createEntitiesModule(axios, appId) {
+export function createEntitiesModule(config) {
+    const { axios, appId, getSocket } = config;
     // Using Proxy to dynamically handle entity names
     return new Proxy({}, {
         get(target, entityName) {
@@ -17,20 +17,41 @@ export function createEntitiesModule(axios, appId) {
                 return undefined;
             }
             // Create entity handler
-            return createEntityHandler(axios, appId, entityName);
+            return createEntityHandler(axios, appId, entityName, getSocket);
         },
     });
 }
+/**
+ * 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(),
+        };
+    }
+    catch (error) {
+        console.warn("[Base44 SDK] Failed to parse realtime message:", error);
+        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 +116,26 @@ function createEntityHandler(axios, appId, entityName) {
                 },
             });
         },
+        // 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) => {
+                    const event = parseRealtimeMessage(msg.data);
+                    if (!event) {
+                        return;
+                    }
+                    try {
+                        callback(event);
+                    }
+                    catch (error) {
+                        console.error("[Base44 SDK] Subscription callback error:", error);
+                    }
+                },
+            });
+            return unsubscribe;
+        },
     };
 }

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

@@ -1,3 +1,28 @@
+/**
+ * Event types for realtime entity updates.
+ */
+export type RealtimeEventType = "create" | "update" | "delete";
+/**
+ * Payload received when a realtime event occurs.
+ */
+export interface RealtimeEvent {
+    /** The type of change that occurred */
+    type: RealtimeEventType;
+    /** The entity data */
+    data: any;
+    /** The unique identifier of the affected entity */
+    id: string;
+    /** ISO 8601 timestamp of when the event occurred */
+    timestamp: string;
+}
+/**
+ * Callback function invoked when a realtime event occurs.
+ */
+export type RealtimeCallback = (event: RealtimeEvent) => void;
+/**
+ * Function returned from subscribe, call it to unsubscribe.
+ */
+export type Subscription = () => void;
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -242,6 +267,26 @@ 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.
+     * @returns Unsubscribe function to stop listening.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all Task changes
+     * const unsubscribe = base44.entities.Task.subscribe((event) => {
+     *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
+     * });
+     *
+     * // Later, unsubscribe
+     * unsubscribe();
+     * ```
+     */
+    subscribe(callback: RealtimeCallback): Subscription;
 }
 /**
  * Entities module for managing app data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/sdk",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,10 +55,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/base44/sdk.git"
+    "url": "git+https://github.com/base44/javascript-sdk.git"
   },
   "bugs": {
-    "url": "https://github.com/base44/sdk/issues"
+    "url": "https://github.com/base44/javascript-sdk/issues"
   },
-  "homepage": "https://github.com/base44/sdk#readme"
+  "homepage": "https://github.com/base44/javascript-sdk#readme"
 }