@doany-ai/sdk 0.1.0

package/dist/modules/ai-gateway.js

@@ -0,0 +1,13 @@
+import { getAccessToken } from "../utils/auth-utils.js";
+export function createAiGatewayModule({ serverUrl, token, appId, }) {
+    const connection = () => {
+        var _a;
+        return ({
+            baseURL: `${serverUrl}/api/apps/${appId}/ai/openai/v1`,
+            token: (_a = token !== null && token !== void 0 ? token : getAccessToken()) !== null && _a !== void 0 ? _a : "",
+        });
+    };
+    return {
+        connection,
+    };
+}

package/dist/modules/ai-gateway.types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A connection to the Base44 AI Gateway.
+ *
+ * Contains the base URL and bearer token to use with any OpenAI-compatible
+ * client pointed at the Base44 AI Gateway.
+ */
+export interface AiGatewayConnection {
+    /** Base URL of the gateway's OpenAI-compatible endpoint. */
+    baseURL: string;
+    /** Bearer token used to authenticate requests to the gateway. */
+    token: string;
+}
+/**
+ * Configuration for the AI Gateway module.
+ * @internal
+ */
+export interface AiGatewayModuleConfig {
+    /** Server URL */
+    serverUrl?: string;
+    /** Authentication token */
+    token?: string;
+    /** Application ID */
+    appId: string;
+}
+/**
+ * AI Gateway module for calling Base44's managed AI models from your own code.
+ *
+ * The gateway exposes an OpenAI-compatible Chat Completions endpoint, so any
+ * OpenAI-compatible SDK works against it:
+ * - Build custom AI agents or call models directly from your backend code
+ * - Uses your app's models, billing, and credit quota, no API key to manage
+ *
+ * Available in user authentication mode (`base44.aiGateway`) and with the
+ * service-role token via `base44.asServiceRole.aiGateway`.
+ */
+export interface AiGatewayModule {
+    /**
+     * Gets the connection details for the Base44 AI Gateway.
+     *
+     * Returns the `baseURL` and `token` to pass to any OpenAI-compatible client.
+     *
+     * The `token` is the current caller's bearer token: the app user's token for
+     * `base44.aiGateway`, or the service-role token for `base44.asServiceRole.aiGateway`.
+     * When the caller is unauthenticated, `token` is an empty string.
+     *
+     * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`).
+     *
+     * @example
+     * ```typescript
+     * import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai";
+     * import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+     * import { z } from "zod";
+     *
+     * const request = await base44.entities.ReturnRequest.get(returnId);
+     * const { baseURL, token } = base44.aiGateway.connection();
+     * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token`.
+     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
+     *
+     * const agent = new ToolLoopAgent({
+     *   model: models("automatic"),
+     *   instructions:
+     *     "Decide whether this return looks fine or needs the owner's attention. " +
+     *     "Check the customer's past orders, then submit your verdict.",
+     *   tools: {
+     *     searchOrders: tool({
+     *       description: "This customer's past orders, optionally filtered by status",
+     *       inputSchema: z.object({ status: z.string().optional() }),
+     *       execute: ({ status }) => {
+     *         const query = { customer_email: request.customer_email };
+     *         if (status) query.status = status;
+     *         return base44.entities.Order.filter(query, "-created_date", 50);
+     *       },
+     *     }),
+     *     submitVerdict: tool({
+     *       description: "Record the final verdict",
+     *       inputSchema: z.object({ decision: z.enum(["approved", "flagged"]), reason: z.string() }),
+     *       execute: ({ decision, reason }) =>
+     *         base44.entities.ReturnRequest.update(returnId, { status: decision, review_note: reason }),
+     *     }),
+     *   },
+     *   stopWhen: [stepCountIs(8), hasToolCall("submitVerdict")],
+     * });
+     *
+     * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(request)}` });
+     * ```
+     */
+    connection(): AiGatewayConnection;
+}

package/dist/modules/ai-gateway.types.js

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

package/dist/modules/analytics.d.ts

@@ -0,0 +1,20 @@
+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 {
+    axiosClient: AxiosInstance;
+    serverUrl: string;
+    appId: string;
+    userAuthModule: AuthModule;
+}
+export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, }: AnalyticsModuleArgs) => {
+    track: (params: TrackEventParams) => void;
+    cleanup: () => void;
+};
+export declare function getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
+export declare function getAnalyticsSessionId(): string;

package/dist/modules/analytics.js

@@ -0,0 +1,284 @@
+import { getSharedInstance } from "../utils/sharedInstance.js";
+import { generateUuid, isReactNative } 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;
+    // Disable analytics on React Native. It defines `window` but not `document`,
+    // so the per-callsite `typeof window` guards below aren't enough to keep it
+    // from touching `document` (e.g. `document.referrer` on init). Node/SSR is
+    // still handled by those `window` guards, so this doesn't affect it.
+    if (!((_a = analyticsSharedState.config) === null || _a === void 0 ? void 0 : _a.enabled) || isReactNative) {
+        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() {
+    // `window.location` is absent on React Native. This runs at module load (via
+    // the shared-state factory), so an unguarded `window.location.search` would
+    // throw on import there.
+    if (typeof window === "undefined" || !window.location)
+        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 {};