@base44/sdk 0.8.5 → 0.8.7

package/dist/modules/analytics.js

@@ -0,0 +1,213 @@
+import { getSharedInstance } from "../utils/sharedInstance";
+import { generateUuid } from "../utils/common";
+export const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export const ANALYTICS_CONFIG_WINDOW_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     ////
+///////////////////////////////////////////////
+const ANALYTICS_SHARED_STATE_NAME = "analytics";
+// shared state//
+const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () => ({
+    requestsQueue: [],
+    isProcessing: false,
+    isHeartBeatProcessing: false,
+    sessionContext: null,
+    config: {
+        ...defaultConfiguration,
+        ...getAnalyticsModuleOptionsFromWindow(),
+    },
+}));
+export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, }) => {
+    var _a;
+    // prevent overflow of events //
+    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 batchRequestFallback = async (events) => {
+        await axiosClient.request({
+            method: "POST",
+            url: `/apps/${appId}/analytics/track/batch`,
+            data: { events },
+        });
+    };
+    const flush = async (eventsData) => {
+        const sessionContext_ = await getSessionContext(userAuthModule);
+        const events = eventsData.map(transformEventDataToApiRequestData(sessionContext_));
+        const beaconPayload = JSON.stringify({ 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 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")
+            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 &&
+        analyticsSharedState.requestsQueue.length > 0) {
+        const requests = analyticsSharedState.requestsQueue.splice(0, batchSize);
+        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 {
+        timestamp: new Date().toISOString(),
+        pageUrl: typeof window !== "undefined" ? window.location.pathname : null,
+    };
+}
+function transformEventDataToApiRequestData(sessionContext) {
+    return (eventData) => ({
+        event_name: eventData.eventName,
+        properties: eventData.properties,
+        timestamp: eventData.timestamp,
+        page_url: eventData.pageUrl,
+        ...sessionContext,
+    });
+}
+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 getAnalyticsModuleOptionsFromWindow() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window[ANALYTICS_CONFIG_WINDOW_KEY];
+}
+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

@@ -0,0 +1,42 @@
+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 SessionContext = {
+    user_id?: string | null;
+    session_id?: string | null;
+};
+export type AnalyticsApiRequestData = {
+    event_name: string;
+    properties?: TrackEventProperties;
+    timestamp?: string;
+    page_url?: string | null;
+} & SessionContext;
+export type AnalyticsApiBatchRequest = {
+    method: "POST";
+    url: `/apps/${string}/analytics/track/batch`;
+    data: {
+        events: AnalyticsApiRequestData[];
+    };
+};
+export type AnalyticsModuleOptions = {
+    enabled?: boolean;
+    maxQueueSize?: number;
+    throttleTime?: number;
+    batchSize?: number;
+    heartBeatInterval?: number;
+};
+export type AnalyticsModule = {
+    track: (params: TrackEventParams) => void;
+};

package/dist/modules/analytics.types.js

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

package/dist/modules/app-logs.d.ts

@@ -1,27 +1,11 @@
 import { AxiosInstance } from "axios";
+import { AppLogsModule } from "./app-logs.types";
 /**
- * Creates the app logs module for the Base44 SDK
- * @param {AxiosInstance} axios - Axios instance
- * @param {string} appId - Application ID
- * @returns {Object} App logs module
+ * Creates the app logs module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns App logs module with methods for tracking and analyzing app usage
+ * @internal
  */
-export declare function createAppLogsModule(axios: AxiosInstance, appId: string): {
-    /**
-     * Log user activity in the app
-     * @param {string} pageName - Name of the page being visited
-     * @returns {Promise<void>}
-     */
-    logUserInApp(pageName: string): Promise<void>;
-    /**
-     * Fetch app logs with optional parameters
-     * @param {Object} params - Query parameters for filtering logs
-     * @returns {Promise<any>} App logs data
-     */
-    fetchLogs(params?: Record<string, any>): Promise<any>;
-    /**
-     * Get app statistics
-     * @param {Object} params - Query parameters for filtering stats
-     * @returns {Promise<any>} App statistics
-     */
-    getStats(params?: Record<string, any>): Promise<any>;
-};
+export declare function createAppLogsModule(axios: AxiosInstance, appId: string): AppLogsModule;

package/dist/modules/app-logs.js

@@ -1,34 +1,24 @@
 /**
- * Creates the app logs module for the Base44 SDK
- * @param {AxiosInstance} axios - Axios instance
- * @param {string} appId - Application ID
- * @returns {Object} App logs module
+ * Creates the app logs module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns App logs module with methods for tracking and analyzing app usage
+ * @internal
  */
 export function createAppLogsModule(axios, appId) {
     const baseURL = `/app-logs/${appId}`;
     return {
-        /**
-         * Log user activity in the app
-         * @param {string} pageName - Name of the page being visited
-         * @returns {Promise<void>}
-         */
+        // Log user activity in the app
         async logUserInApp(pageName) {
             await axios.post(`${baseURL}/log-user-in-app/${pageName}`);
         },
-        /**
-         * Fetch app logs with optional parameters
-         * @param {Object} params - Query parameters for filtering logs
-         * @returns {Promise<any>} App logs data
-         */
+        // Fetch app logs with optional parameters
         async fetchLogs(params = {}) {
             const response = await axios.get(baseURL, { params });
             return response;
         },
-        /**
-         * Get app statistics
-         * @param {Object} params - Query parameters for filtering stats
-         * @returns {Promise<any>} App statistics
-         */
+        // Get app statistics
         async getStats(params = {}) {
             const response = await axios.get(`${baseURL}/stats`, { params });
             return response;

package/dist/modules/app-logs.types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * App Logs module for tracking and analyzing app usage.
+ *
+ * This module provides a method to log user activity. The logs are reflected in the Analytics page in the app dashboard.
+ *
+ * This module is available to use with a client in all authentication modes.
+ */
+export interface AppLogsModule {
+    /**
+     * Log user activity in the app.
+     *
+     * Records when a user visits a specific page or section of the app. Useful for tracking user navigation patterns and popular features. The logs are reflected in the Analytics page in the app dashboard.
+     *
+     * The specified page name doesn't have to be the name of an actual page in the app, it can be any string you want to use to track the activity.
+     *
+     * @param pageName - Name of the page or section being visited.
+     * @returns Promise that resolves when the log is recorded.
+     *
+     * @example
+     * ```typescript
+     * // Log page visit or feature usage
+     * await base44.appLogs.logUserInApp('home');
+     * await base44.appLogs.logUserInApp('features-section');
+     * await base44.appLogs.logUserInApp('button-click');
+     * ```
+     */
+    logUserInApp(pageName: string): Promise<void>;
+    /**
+     * Fetch app logs with optional parameters.
+     *
+     * @param params - Optional query parameters for filtering logs.
+     * @returns Promise resolving to the logs data.
+     * @internal
+     */
+    fetchLogs(params?: Record<string, any>): Promise<any>;
+    /**
+     * Get app statistics.
+     *
+     * @param params - Optional query parameters for filtering stats.
+     * @returns Promise resolving to the stats data.
+     * @internal
+     */
+    getStats(params?: Record<string, any>): Promise<any>;
+}

package/dist/modules/app-logs.types.js

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

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

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export interface AppMessageContent {
     content?: string;
     file_urls?: string[];
@@ -5,16 +8,25 @@ export interface AppMessageContent {
     additional_message_params?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * @internal
+ */
 export interface AppConversationMessage extends AppMessageContent {
     id?: string | null;
     role?: "user" | "assistant" | string;
 }
+/**
+ * @internal
+ */
 export interface AppConversationLike {
     id?: string | null;
     messages?: AppMessageContent[] | null;
     model?: string;
     functions_fail_silently?: boolean;
 }
+/**
+ * @internal
+ */
 export interface DenoProjectLike {
     project_id: string;
     project_name: string;
@@ -24,6 +36,9 @@ export interface DenoProjectLike {
         code: string;
     }>;
 }
+/**
+ * @internal
+ */
 export interface AppLike {
     id?: string;
     conversation?: AppConversationLike | null;
@@ -80,9 +95,15 @@ export interface AppLike {
     app_code_hash?: string;
     has_backend_functions_enabled?: boolean;
 }
+/**
+ * @internal
+ */
 export interface UserLike {
     id?: string | null;
 }
+/**
+ * @internal
+ */
 export interface UserEntityLike {
     type: string;
     name: string;
@@ -104,6 +125,9 @@ export interface UserEntityLike {
     };
     required: string[];
 }
+/**
+ * @internal
+ */
 export interface AuthConfigLike {
     enable_username_password?: boolean;
     enable_google_login?: boolean;
@@ -112,4 +136,7 @@ export interface AuthConfigLike {
     sso_provider_name?: string;
     enable_sso_login?: boolean;
 }
+/**
+ * @internal
+ */
 export type LoginInfoResponse = Pick<AppLike, "id" | "name" | "slug" | "logo_url" | "user_description" | "updated_date" | "created_date" | "auth_config" | "platform_version">;

package/dist/modules/auth.d.ts

@@ -1,81 +1,13 @@
 import { AxiosInstance } from "axios";
+import { AuthModule, AuthModuleOptions } from "./auth.types";
 /**
- * Creates the auth module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @param {string} serverUrl - Server URL
- * @returns {Object} Auth module with authentication methods
+ * Creates the auth module for the Base44 SDK.
+ *
+ * @param axios - Axios instance for API requests
+ * @param functionsAxiosClient - Axios instance for functions API requests
+ * @param appId - Application ID
+ * @param options - Configuration options including server URLs
+ * @returns Auth module with authentication and user management methods
+ * @internal
  */
-export declare function createAuthModule(axios: AxiosInstance, functionsAxiosClient: AxiosInstance, appId: string, options: {
-    serverUrl: string;
-    appBaseUrl?: string;
-}): {
-    /**
-     * Get current user information
-     * @returns {Promise<Object>} Current user data
-     */
-    me(): Promise<import("axios").AxiosResponse<any, any>>;
-    /**
-     * Update current user data
-     * @param {Object} data - Updated user data
-     * @returns {Promise<Object>} Updated user
-     */
-    updateMe(data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
-    /**
-     * Redirects the user to the app's login page
-     * @param {string} nextUrl - URL to redirect to after successful login
-     * @throws {Error} When not in a browser environment
-     */
-    redirectToLogin(nextUrl: string): void;
-    /**
-     * Logout the current user
-     * Removes the token from localStorage and optionally redirects to a URL or reloads the page
-     * @param redirectUrl - Optional URL to redirect to after logout. Reloads the page if not provided
-     * @returns {Promise<void>}
-     */
-    logout(redirectUrl?: string): void;
-    /**
-     * Set authentication token
-     * @param {string} token - Auth token
-     * @param {boolean} [saveToStorage=true] - Whether to save the token to localStorage
-     */
-    setToken(token: string, saveToStorage?: boolean): void;
-    /**
-     * Login via username and password
-     * @param email - User email
-     * @param password - User password
-     * @param turnstileToken - Optional Turnstile captcha token
-     * @returns Login response with access_token and user
-     */
-    loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<{
-        access_token: string;
-        user: any;
-    }>;
-    /**
-     * Verify if the current token is valid
-     * @returns {Promise<boolean>} True if token is valid
-     */
-    isAuthenticated(): Promise<boolean>;
-    inviteUser(userEmail: string, role: string): Promise<import("axios").AxiosResponse<any, any>>;
-    register(payload: {
-        email: string;
-        password: string;
-        turnstile_token?: string | null;
-        referral_code?: string | null;
-    }): Promise<import("axios").AxiosResponse<any, any>>;
-    verifyOtp({ email, otpCode }: {
-        email: string;
-        otpCode: string;
-    }): Promise<import("axios").AxiosResponse<any, any>>;
-    resendOtp(email: string): Promise<import("axios").AxiosResponse<any, any>>;
-    resetPasswordRequest(email: string): Promise<import("axios").AxiosResponse<any, any>>;
-    resetPassword({ resetToken, newPassword, }: {
-        resetToken: string;
-        newPassword: string;
-    }): Promise<import("axios").AxiosResponse<any, any>>;
-    changePassword({ userId, currentPassword, newPassword, }: {
-        userId: string;
-        currentPassword: string;
-        newPassword: string;
-    }): Promise<import("axios").AxiosResponse<any, any>>;
-};
+export declare function createAuthModule(axios: AxiosInstance, functionsAxiosClient: AxiosInstance, appId: string, options: AuthModuleOptions): AuthModule;