@base44-preview/sdk 0.8.6-pr.57.346f67a → 0.8.6-pr.57.5bc7e40

package/dist/client.js

@@ -124,6 +124,7 @@ export function createClient(config) {
             userAuthModule,
         }),
         cleanup: () => {
+            userModules.analytics.cleanup();
             if (socket) {
                 socket.disconnect();
             }

package/dist/client.types.d.ts

@@ -6,6 +6,7 @@ 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 { AnalyticsModule } from "./modules/analytics.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -82,6 +83,8 @@ export interface Base44Client {
     agents: AgentsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
+    /** {@link AnalyticsModule | Analytics module} for tracking app usage. */
+    analytics: AnalyticsModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
     /**

package/dist/modules/analytics.d.ts

@@ -1,6 +1,9 @@
 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_CONFIG_LOCAL_STORAGE_KEY = "base44_analytics_config";
+export declare const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
 export interface AnalyticsModuleArgs {
     axiosClient: AxiosInstance;
     serverUrl: string;
@@ -9,5 +12,7 @@ export interface AnalyticsModuleArgs {
 }
 export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
+    cleanup: () => void;
 };
-export declare function getAnalyticsModuleOptionsFromUrlParams(): AnalyticsModuleOptions | undefined;
+export declare function getAnalyticsModuleOptionsFromLocalStorage(): AnalyticsModuleOptions | undefined;
+export declare function getAnalyticsSessionId(): string;

package/dist/modules/analytics.js

@@ -1,9 +1,14 @@
 import { getSharedInstance } from "../utils/sharedInstance";
+import { generateUuid } from "../utils/common";
+export const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export const ANALYTICS_CONFIG_LOCAL_STORAGE_KEY = "base44_analytics_config";
+export const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
 const defaultConfiguration = {
     enabled: true,
     maxQueueSize: 1000,
     throttleTime: 1000,
     batchSize: 30,
+    heartBeatInterval: 60 * 1000,
 };
 ///////////////////////////////////////////////
 //// shared queue for analytics events     ////
@@ -13,35 +18,25 @@ const ANALYTICS_SHARED_STATE_NAME = "analytics";
 const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () => ({
     requestsQueue: [],
     isProcessing: false,
+    isHeartBeatProcessing: false,
     sessionContext: null,
     config: {
         ...defaultConfiguration,
-        ...getAnalyticsModuleOptionsFromUrlParams(),
+        ...getAnalyticsModuleOptionsFromLocalStorage(),
     },
 }));
 export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, }) => {
+    var _a;
     // prevent overflow of events //
-    const { enabled, maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
+    const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
+    if (!((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled)) {
+        return {
+            track: () => { },
+            cleanup: () => { },
+        };
+    }
+    let clearHeartBeatProcessor = undefined;
     const trackBatchUrl = `${serverUrl}/api/apps/${appId}/analytics/track/batch`;
-    const getSessionContext = async () => {
-        if (!analyticsSharedState.sessionContext) {
-            const user = await userAuthModule.me();
-            analyticsSharedState.sessionContext = {
-                user_id: user.id,
-            };
-        }
-        return analyticsSharedState.sessionContext;
-    };
-    const track = (params) => {
-        if (!enabled || analyticsSharedState.requestsQueue.length >= maxQueueSize) {
-            return;
-        }
-        const intrinsicData = getEventIntrinsicData();
-        analyticsSharedState.requestsQueue.push({
-            ...params,
-            ...intrinsicData,
-        });
-    };
     const batchRequestFallback = async (events) => {
         await axiosClient.request({
             method: "POST",
@@ -50,27 +45,51 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         });
     };
     const flush = async (eventsData) => {
-        const sessionContext_ = await getSessionContext();
+        const sessionContext_ = await getSessionContext(userAuthModule);
         const events = eventsData.map(transformEventDataToApiRequestData(sessionContext_));
         const beaconPayload = JSON.stringify({ events });
-        if (typeof navigator === "undefined" ||
-            beaconPayload.length > 60000 ||
-            !navigator.sendBeacon(trackBatchUrl, beaconPayload)) {
-            // beacon didn't work, fallback to axios
-            await batchRequestFallback(events);
+        try {
+            if (typeof navigator === "undefined" ||
+                beaconPayload.length > 60000 ||
+                !navigator.sendBeacon(trackBatchUrl, beaconPayload)) {
+                // beacon didn't work, fallback to axios
+                await batchRequestFallback(events);
+            }
+        }
+        catch (_a) {
+            // TODO: think about retries if needed
         }
     };
-    const onDocHidden = () => {
-        analyticsSharedState.isProcessing = false;
-        //  flush entire queue on visibility change and hope for the best //
-        const eventsData = analyticsSharedState.requestsQueue.splice(0);
-        flush(eventsData);
+    const startProcessing = () => {
+        startAnalyticsProcessor(flush, {
+            throttleTime,
+            batchSize,
+        });
+    };
+    const track = (params) => {
+        if (analyticsSharedState.requestsQueue.length >= maxQueueSize) {
+            return;
+        }
+        const intrinsicData = getEventIntrinsicData();
+        analyticsSharedState.requestsQueue.push({
+            ...params,
+            ...intrinsicData,
+        });
+        startProcessing();
     };
     const onDocVisible = () => {
         startAnalyticsProcessor(flush, {
             throttleTime,
             batchSize,
         });
+        clearHeartBeatProcessor = startHeartBeatProcessor(track);
+    };
+    const onDocHidden = () => {
+        stopAnalyticsProcessor();
+        //  flush entire queue on visibility change and hope for the best //
+        const eventsData = analyticsSharedState.requestsQueue.splice(0);
+        flush(eventsData);
+        clearHeartBeatProcessor === null || clearHeartBeatProcessor === void 0 ? void 0 : clearHeartBeatProcessor();
     };
     const onVisibilityChange = () => {
         if (typeof window === "undefined")
@@ -82,39 +101,58 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             onDocVisible();
         }
     };
-    if (typeof window !== "undefined" && enabled) {
+    const cleanup = () => {
+        stopAnalyticsProcessor();
+        clearHeartBeatProcessor === null || clearHeartBeatProcessor === void 0 ? void 0 : clearHeartBeatProcessor();
+        if (typeof window !== "undefined") {
+            window.removeEventListener("visibilitychange", onVisibilityChange);
+        }
+    };
+    // start the flusing process ///
+    startProcessing();
+    // start the heart beat processor //
+    clearHeartBeatProcessor = startHeartBeatProcessor(track);
+    // start the visibility change listener //
+    if (typeof window !== "undefined") {
         window.addEventListener("visibilitychange", onVisibilityChange);
     }
-    // start analytics processor only if it's the first instance and analytics is enabled //
-    if (enabled) {
-        startAnalyticsProcessor(flush, {
-            throttleTime,
-            batchSize,
-        });
-    }
     return {
         track,
+        cleanup,
     };
 };
+function stopAnalyticsProcessor() {
+    analyticsSharedState.isProcessing = false;
+}
 async function startAnalyticsProcessor(handleTrack, options) {
     if (analyticsSharedState.isProcessing) {
+        // only one instance of the analytics processor can be running at a time //
         return;
     }
     analyticsSharedState.isProcessing = true;
     const { throttleTime = 1000, batchSize = 30 } = options !== null && options !== void 0 ? options : {};
-    while (analyticsSharedState.isProcessing) {
+    while (analyticsSharedState.isProcessing &&
+        analyticsSharedState.requestsQueue.length > 0) {
         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);
-            }
-        }
+        requests.length && (await handleTrack(requests));
         await new Promise((resolve) => setTimeout(resolve, throttleTime));
     }
+    analyticsSharedState.isProcessing = false;
+}
+function startHeartBeatProcessor(track) {
+    var _a;
+    if (analyticsSharedState.isHeartBeatProcessing ||
+        ((_a = analyticsSharedState.config.heartBeatInterval) !== null && _a !== void 0 ? _a : 0) < 10) {
+        return () => { };
+    }
+    analyticsSharedState.isHeartBeatProcessing = true;
+    const interval = setInterval(() => {
+        track({ eventName: USER_HEARTBEAT_EVENT_NAME });
+    }, analyticsSharedState.config.heartBeatInterval);
+    return () => {
+        clearInterval(interval);
+        analyticsSharedState.isHeartBeatProcessing = false;
+    };
 }
 function getEventIntrinsicData() {
     return {
@@ -131,17 +169,53 @@ function transformEventDataToApiRequestData(sessionContext) {
         ...sessionContext,
     });
 }
-export function getAnalyticsModuleOptionsFromUrlParams() {
+let sessionContextPromise = null;
+async function getSessionContext(userAuthModule) {
+    if (!analyticsSharedState.sessionContext) {
+        if (!sessionContextPromise) {
+            const sessionId = getAnalyticsSessionId();
+            sessionContextPromise = userAuthModule
+                .me()
+                .then((user) => ({
+                user_id: user.id,
+                session_id: sessionId,
+            }))
+                .catch(() => ({
+                user_id: null,
+                session_id: sessionId,
+            }));
+        }
+        analyticsSharedState.sessionContext = await sessionContextPromise;
+    }
+    return analyticsSharedState.sessionContext;
+}
+export function getAnalyticsModuleOptionsFromLocalStorage() {
     if (typeof window === "undefined")
         return undefined;
-    const urlParams = new URLSearchParams(window.location.search);
-    const jsonString = urlParams.get("analytics");
-    if (!jsonString)
-        return undefined;
     try {
+        const jsonString = localStorage.getItem(ANALYTICS_CONFIG_LOCAL_STORAGE_KEY);
+        if (!jsonString)
+            return undefined;
         return JSON.parse(jsonString);
     }
     catch (_a) {
         return undefined;
     }
 }
+export function getAnalyticsSessionId() {
+    if (typeof window === "undefined") {
+        return generateUuid();
+    }
+    try {
+        const sessionId = localStorage.getItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY);
+        if (!sessionId) {
+            const newSessionId = generateUuid();
+            localStorage.setItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY, newSessionId);
+            return newSessionId;
+        }
+        return sessionId;
+    }
+    catch (_a) {
+        return generateUuid();
+    }
+}

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

@@ -15,6 +15,7 @@ export type TrackEventData = {
 } & TrackEventIntrinsicData;
 export type SessionContext = {
     user_id?: string | null;
+    session_id?: string | null;
 };
 export type AnalyticsApiRequestData = {
     event_name: string;
@@ -34,6 +35,7 @@ export type AnalyticsModuleOptions = {
     maxQueueSize?: number;
     throttleTime?: number;
     batchSize?: number;
+    heartBeatInterval?: number;
 };
 export type AnalyticsModule = {
     track: (params: TrackEventParams) => void;

package/dist/utils/common.d.ts

@@ -1,2 +1,3 @@
 export declare const isNode: boolean;
 export declare const isInIFrame: boolean;
+export declare const generateUuid: () => string;

package/dist/utils/common.js

@@ -1,2 +1,6 @@
 export const isNode = typeof window === "undefined";
 export const isInIFrame = !isNode && window.self !== window.top;
+export const generateUuid = () => {
+    return (Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15));
+};

package/package.json

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