@base44-preview/sdk 0.8.6-pr.57.faeb046 → 0.8.7-pr.59.f9ae6aa

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_URL_PARAM_KEY = "analytics-disable";
+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 getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
+export declare function getAnalyticsSessionId(): string;

package/dist/modules/analytics.js

@@ -1,4 +1,15 @@
-import { getSharedInstance, } from "../utils/singleton";
+import { getSharedInstance } from "../utils/sharedInstance";
+import { generateUuid } from "../utils/common";
+export const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export const ANALYTICS_CONFIG_URL_PARAM_KEY = "analytics-disable";
+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     ////
 ///////////////////////////////////////////////
@@ -7,32 +18,25 @@ const ANALYTICS_SHARED_STATE_NAME = "analytics";
 const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () => ({
     requestsQueue: [],
     isProcessing: false,
+    isHeartBeatProcessing: false,
+    sessionContext: null,
+    config: {
+        ...defaultConfiguration,
+        ...getAnalyticsConfigFromUrlParams(),
+    },
 }));
 export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, }) => {
     var _a;
     // prevent overflow of events //
-    const { enabled = true, maxQueueSize = 1000, throttleTime = 1000, batchSize = 30, } = (_a = getAnalyticsModuleOptionsFromUrlParams()) !== null && _a !== void 0 ? _a : {};
-    const trackBatchUrl = `${serverUrl}/api/apps/${appId}/analytics/track/batch`;
-    let sessionContext = null;
-    const getSessionContext = async () => {
-        if (sessionContext)
-            return sessionContext;
-        const user = await userAuthModule.me();
-        sessionContext = {
-            user_id: user.id,
+    const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
+    if (!((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled)) {
+        return {
+            track: () => { },
+            cleanup: () => { },
         };
-        return sessionContext;
-    };
-    const track = (params) => {
-        if (!enabled || analyticsSharedState.requestsQueue.length >= maxQueueSize) {
-            return;
-        }
-        const intrinsicData = getEventIntrinsicData();
-        analyticsSharedState.requestsQueue.push({
-            ...params,
-            ...intrinsicData,
-        });
-    };
+    }
+    let clearHeartBeatProcessor = undefined;
+    const trackBatchUrl = `${serverUrl}/api/apps/${appId}/analytics/track/batch`;
     const batchRequestFallback = async (events) => {
         await axiosClient.request({
             method: "POST",
@@ -40,63 +44,118 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
             data: { events },
         });
     };
+    const beaconRequest = async (events) => {
+        const beaconPayload = JSON.stringify({ events });
+        try {
+            const blob = new Blob([beaconPayload], { type: "application/json" });
+            return (typeof navigator === "undefined" ||
+                beaconPayload.length > 60000 ||
+                !navigator.sendBeacon(trackBatchUrl, blob));
+        }
+        catch (_a) {
+            return false;
+        }
+    };
     const flush = async (eventsData) => {
-        const sessionContext_ = sessionContext !== null && sessionContext !== void 0 ? 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);
+        if (!(await beaconRequest(events))) {
+            return batchRequestFallback(events);
         }
     };
-    if (typeof window !== "undefined" && enabled) {
-        window.addEventListener("visibilitychange", () => {
-            if (document.visibilityState === "hidden") {
-                analyticsSharedState.isProcessing = false;
-                //  flush entire queue on visibility change and hope for the best //
-                const eventsData = analyticsSharedState.requestsQueue.splice(0);
-                flush(eventsData);
-            }
-            else if (document.visibilityState === "visible") {
-                startAnalyticsProcessor(flush, {
-                    throttleTime,
-                    batchSize,
-                });
-            }
+    const startProcessing = () => {
+        startAnalyticsProcessor(flush, {
+            throttleTime,
+            batchSize,
         });
-    }
-    // start analytics processor only if it's the first instance and analytics is enabled //
-    if (enabled) {
+    };
+    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")
+            return;
+        if (document.visibilityState === "hidden") {
+            onDocHidden();
+        }
+        else if (document.visibilityState === "visible") {
+            onDocVisible();
+        }
+    };
+    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);
     }
     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 {
@@ -113,15 +172,51 @@ function transformEventDataToApiRequestData(sessionContext) {
         ...sessionContext,
     });
 }
-export function getAnalyticsModuleOptionsFromUrlParams() {
-    const urlParams = new URLSearchParams(window.location.search);
-    const jsonString = urlParams.get("analytics");
-    if (!jsonString)
+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 getAnalyticsConfigFromUrlParams() {
+    if (typeof window === "undefined")
         return undefined;
+    const urlParams = new URLSearchParams(window.location.search);
+    const analyticsDisable = urlParams.get(ANALYTICS_CONFIG_URL_PARAM_KEY);
+    const newUrlParams = new URLSearchParams(window.location.search);
+    newUrlParams.delete(ANALYTICS_CONFIG_URL_PARAM_KEY);
+    const newUrl = `${window.location.pathname}?${newUrlParams.toString()}`;
+    window.history.replaceState({}, document.title, newUrl);
+    return analyticsDisable === "true" ? { enabled: false } : undefined;
+}
+export function getAnalyticsSessionId() {
+    if (typeof window === "undefined") {
+        return generateUuid();
+    }
     try {
-        return JSON.parse(jsonString);
+        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 undefined;
+        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,4 +35,8 @@ 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/dist/utils/{singleton.d.ts → sharedInstance.d.ts}

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

package/dist/utils/sharedInstance.js

@@ -0,0 +1,15 @@
+const windowObj = typeof window !== "undefined"
+    ? window
+    : { base44SharedInstances: {} };
+// Singleton (shared between sdk instances)//
+export function getSharedInstance(name, factory) {
+    if (!windowObj.base44SharedInstances) {
+        windowObj.base44SharedInstances = {};
+    }
+    if (!windowObj.base44SharedInstances[name]) {
+        windowObj.base44SharedInstances[name] = {
+            instance: factory(),
+        };
+    }
+    return windowObj.base44SharedInstances[name].instance;
+}

package/package.json

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

package/dist/utils/singleton.js

@@ -1,17 +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: 0 };
-    }
-    windowObj.base44[name]._refCount++;
-    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;
-}