@depup/base44__sdk 0.8.22-depup.0

package/dist/modules/analytics.js

@@ -0,0 +1,277 @@
+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 = {
+    // default to enabled //
+    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,
+    wasInitializationTracked: false,
+    sessionContext: null,
+    sessionStartTime: null,
+    config: {
+        ...defaultConfiguration,
+        ...getAnalyticsConfigFromUrlParams(),
+    },
+}));
+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 },
+        });
+    };
+    // currently disabled, until fully tested  //
+    const beaconRequest = (events) => {
+        try {
+            const beaconPayload = JSON.stringify({ events });
+            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, options = {}) => {
+        if (eventsData.length === 0)
+            return;
+        const sessionContext_ = await getSessionContext(userAuthModule);
+        const events = eventsData.map(transformEventDataToApiRequestData(sessionContext_));
+        try {
+            if (!options.isBeacon || !beaconRequest(events)) {
+                await batchRequestFallback(events);
+            }
+        }
+        catch (_a) {
+            // do nothing
+        }
+    };
+    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);
+        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 });
+    };
+    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);
+    // track the referrer event //
+    trackInitializationEvent(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 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(),
+        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 getAnalyticsConfigFromUrlParams() {
+    if (typeof window === "undefined")
+        return undefined;
+    const urlParams = new URLSearchParams(window.location.search);
+    const analyticsEnable = urlParams.get(ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY);
+    // if the url param is not set, return undefined //
+    if (analyticsEnable == null || !analyticsEnable.length)
+        return undefined;
+    // remove the url param from the url //
+    const newUrlParams = new URLSearchParams(window.location.search);
+    newUrlParams.delete(ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY);
+    const newUrl = window.location.pathname +
+        (newUrlParams.toString() ? "?" + newUrlParams.toString() : "");
+    window.history.replaceState({}, "", newUrl);
+    // return the config object //
+    return { enabled: analyticsEnable === "true" };
+}
+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,122 @@
+/**
+ * Properties for analytics events.
+ *
+ * Key-value pairs with additional event data. Values can be strings, numbers, booleans, or null.
+ */
+export type TrackEventProperties = {
+    [key: string]: string | number | boolean | null | undefined;
+};
+/**
+ * Parameters for tracking an analytics event.
+ */
+export type TrackEventParams = {
+    /**
+     * Name of the event to track.
+     *
+     * Use descriptive names like `button_click`, `form_submit`, or `purchase_completed`.
+     */
+    eventName: string;
+    /**
+     * Optional key-value pairs with additional event data.
+     *
+     * Values can be strings, numbers, booleans, or null.
+     *
+     * @example
+     * ```typescript
+     * base44.analytics.track({
+     *   eventName: 'add_to_cart',
+     *   properties: {
+     *     product_id: 'prod_123',
+     *     price: 29.99,
+     *     quantity: 2
+     *   }
+     * });
+     * ```
+     */
+    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;
+};
+/**
+ * Analytics module for tracking custom events in your app.
+ *
+ * Use this module to track specific user actions. Track things like button clicks, form submissions, purchases, and feature usage.
+ *
+ * <Note> Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics).</Note>
+ *
+ * ## Best Practices
+ *
+ * When tracking events:
+ *
+ * - Choose clear, descriptive event names in snake_case like `signup_button_click` or `purchase_completed` rather than generic names like `click`.
+ * - Include relevant context in your properties such as identifiers like `product_id`, measurements like `price`, and flags like `is_first_purchase`.
+ *
+ * ## Authentication Modes
+ *
+ * This module is only available in user authentication mode (`base44.analytics`).
+ */
+export interface AnalyticsModule {
+    /**
+     * Tracks a custom event that appears as a card in your Analytics dashboard.
+     *
+     * Each unique event name becomes its own card showing total count and trends over time. This method returns immediately and events are sent in batches in the background.
+     *
+     * @param params - Event parameters.
+     * @param params.eventName - Name of the event. This becomes the card title in your dashboard. Use descriptive names like `'signup_button_click'` or `'purchase_completed'`.
+     * @param params.properties - Optional data to attach to the event. You can filter and analyze events by these properties in the dashboard.
+     *
+     * @example Track a button click
+     * ```typescript
+     * // Track a button click
+     * base44.analytics.track({
+     *   eventName: 'signup_button_click'
+     * });
+     * ```
+     *
+     * @example Track with properties
+     * ```typescript
+     * // Track with properties
+     * base44.analytics.track({
+     *   eventName: 'add_to_cart',
+     *   properties: {
+     *     product_id: 'prod_123',
+     *     product_name: 'Premium Widget',
+     *     price: 29.99,
+     *     quantity: 2,
+     *     is_first_purchase: true
+     *   }
+     * });
+     * ```
+     */
+    track(params: TrackEventParams): void;
+}

package/dist/modules/analytics.types.js

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

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

@@ -0,0 +1,11 @@
+import { AxiosInstance } from "axios";
+import { AppLogsModule } from "./app-logs.types";
+/**
+ * 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): AppLogsModule;

package/dist/modules/app-logs.js

@@ -0,0 +1,27 @@
+/**
+ * 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
+        async logUserInApp(pageName) {
+            await axios.post(`${baseURL}/log-user-in-app/${pageName}`);
+        },
+        // Fetch app logs with optional parameters
+        async fetchLogs(params = {}) {
+            const response = await axios.get(baseURL, { params });
+            return response;
+        },
+        // 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,46 @@
+/**
+ * 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.
+ *
+ * ## Authentication Modes
+ *
+ * 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

@@ -0,0 +1,142 @@
+/**
+ * @internal
+ */
+export interface AppMessageContent {
+    content?: string;
+    file_urls?: string[];
+    custom_context?: unknown;
+    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;
+    app_id: string;
+    deployment_name_to_info: Record<string, {
+        id: string;
+        code: string;
+    }>;
+}
+/**
+ * @internal
+ */
+export interface AppLike {
+    id?: string;
+    conversation?: AppConversationLike | null;
+    app_stage?: "pending" | "product_flows" | "ready" | string;
+    created_date?: string;
+    updated_date?: string;
+    created_by?: string;
+    organization_id?: string;
+    name?: string;
+    user_description?: string;
+    entities?: Record<string, any>;
+    additional_user_data_schema?: any;
+    pages?: {
+        [key: string]: string;
+    };
+    components: {
+        [key: string]: any;
+    };
+    layout?: string;
+    globals_css?: string;
+    agents?: Record<string, any>;
+    logo_url?: string;
+    slug?: string;
+    public_settings?: "private_with_login" | "public_with_login" | "public_without_login" | "workspace_with_login" | string;
+    is_blocked?: boolean;
+    github_repo_url?: string;
+    main_page?: string;
+    installable_integrations?: any;
+    backend_project?: DenoProjectLike;
+    last_deployed_at?: string;
+    is_remixable?: boolean;
+    remixed_from_app_id?: string;
+    hide_entity_created_by?: boolean;
+    platform_version?: number;
+    enable_username_password?: boolean;
+    auth_config?: AuthConfigLike;
+    status?: {
+        state?: string;
+        details?: any;
+        last_updated_date?: string;
+    };
+    custom_instructions?: any;
+    frozen_files?: string[];
+    deep_coding_mode?: boolean;
+    needs_to_add_diff?: boolean;
+    installed_integration_context_items?: any[];
+    model?: string;
+    is_starred?: boolean;
+    agents_enabled?: boolean;
+    categories?: string[];
+    functions?: any;
+    function_names?: string[];
+    user_entity?: UserEntityLike;
+    app_code_hash?: string;
+    has_backend_functions_enabled?: boolean;
+}
+/**
+ * @internal
+ */
+export interface UserLike {
+    id?: string | null;
+}
+/**
+ * @internal
+ */
+export interface UserEntityLike {
+    type: string;
+    name: string;
+    title?: string;
+    properties?: {
+        role?: {
+            type?: string;
+            description?: string;
+            enum?: ("admin" | "user" | string)[];
+        };
+        email?: {
+            type?: string;
+            description?: string;
+        };
+        full_name?: {
+            type?: string;
+            description?: string;
+        };
+    };
+    required: string[];
+}
+/**
+ * @internal
+ */
+export interface AuthConfigLike {
+    enable_username_password?: boolean;
+    enable_google_login?: boolean;
+    enable_microsoft_login?: boolean;
+    enable_facebook_login?: boolean;
+    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/app.types.js

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

package/dist/modules/auth.d.ts

@@ -0,0 +1,13 @@
+import { AxiosInstance } from "axios";
+import { AuthModule, AuthModuleOptions } from "./auth.types";
+/**
+ * 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: AuthModuleOptions): AuthModule;