@base44-preview/sdk 0.8.48-pr.280.7eec9ba → 0.8.48-pr.280.b620aa9

package/dist/modules/analytics-queue.d.ts

@@ -0,0 +1,12 @@
+import type { AxiosInstance } from "axios";
+import type { AnalyticsApiRequestData, AnalyticsModuleOptions } from "./analytics.types.js";
+type Event = AnalyticsApiRequestData & {
+    event_id?: string;
+};
+/** @internal One transport queue per client, shared by goals and exposures. */
+export declare function getAnalyticsQueue(axiosClient: AxiosInstance, appId: string, config: AnalyticsModuleOptions): {
+    enqueue(event: Event | Promise<Event>, authorization: string | null, userId: string | null | Promise<string | null>): void;
+    flush(): Promise<void>;
+    cleanup(): void;
+};
+export {};

package/dist/modules/analytics-queue.js

@@ -0,0 +1,128 @@
+const DELIVERY_BUDGET_MS = 5000;
+const queues = new WeakMap();
+/** @internal One transport queue per client, shared by goals and exposures. */
+export function getAnalyticsQueue(axiosClient, appId, config) {
+    let queue = queues.get(axiosClient);
+    if (!queue) {
+        queue = createAnalyticsQueue(axiosClient, appId, config);
+        queues.set(axiosClient, queue);
+    }
+    return queue;
+}
+function createAnalyticsQueue(axiosClient, appId, config) {
+    const entries = [];
+    const pending = new Set();
+    let timer;
+    function deliver(batch) {
+        const controller = new AbortController();
+        const deadlineAt = Date.now() + DELIVERY_BUDGET_MS;
+        const deadline = new Promise((resolve) => {
+            controller.signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        const timeout = setTimeout(() => controller.abort(), DELIVERY_BUDGET_MS);
+        function send(prepared) {
+            var _a;
+            const groups = new Map();
+            for (const entry of prepared) {
+                const key = JSON.stringify([entry.authorization, entry.userId, entry.event.session_id]);
+                const group = (_a = groups.get(key)) !== null && _a !== void 0 ? _a : [];
+                group.push(entry);
+                groups.set(key, group);
+            }
+            return Promise.all([...groups.values()].map(async (group) => {
+                var _a, _b;
+                const events = group.map(({ event }) => event);
+                const exposures = events.filter((event) => event.event_name === "__experiment_exposure__");
+                const attempts = exposures.length ? 3 : 1;
+                for (let attempt = 0; attempt < attempts; attempt++) {
+                    try {
+                        if (controller.signal.aborted)
+                            return;
+                        await axiosClient.request({
+                            method: "POST", url: `/apps/${appId}/analytics/track/batch`,
+                            headers: { Authorization: group[0].authorization },
+                            // Ordinary goals have no backend deduplication and remain single-attempt.
+                            data: { events: attempt === 0 ? events : exposures },
+                            timeout: Math.max(1, deadlineAt - Date.now()), signal: controller.signal,
+                        });
+                        return;
+                    }
+                    catch (error) {
+                        const status = (_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status) !== null && _b !== void 0 ? _b : error.status;
+                        if (controller.signal.aborted || attempt === attempts - 1 ||
+                            (status !== undefined && (status < 500 || status >= 600)))
+                            return;
+                        await new Promise((resolve) => setTimeout(resolve, attempt === 0 ? 100 : 500));
+                    }
+                }
+            }));
+        }
+        const delivery = (async () => {
+            const ready = [];
+            const requests = [];
+            let wake = () => { };
+            let preparedAll = false;
+            const preparation = Promise.all(batch.map(async (entry) => {
+                const [event, userId] = await Promise.all([entry.event, entry.userId]);
+                if (event && !controller.signal.aborted)
+                    ready.push({ event, userId, authorization: entry.authorization });
+                wake();
+            })).then(() => { preparedAll = true; wake(); });
+            while (!preparedAll || ready.length) {
+                if (!ready.length && !preparedAll)
+                    await Promise.race([
+                        new Promise((resolve) => { wake = resolve; }), deadline,
+                    ]);
+                if (controller.signal.aborted)
+                    return;
+                // Coalesce this turn's resolved identities without waiting for unrelated auth I/O.
+                let turnTimer;
+                await Promise.race([preparation, new Promise((resolve) => { turnTimer = setTimeout(resolve, 0); })]);
+                clearTimeout(turnTimer);
+                if (ready.length)
+                    requests.push(send(ready.splice(0)));
+            }
+            await Promise.all(requests);
+        })();
+        // Identity lookup and transports that ignore cancellation must also be bounded.
+        const settlement = Promise.race([delivery, deadline]).catch(() => { }).finally(() => {
+            clearTimeout(timeout);
+            controller.abort();
+            pending.delete(settlement);
+        });
+        pending.add(settlement);
+    }
+    function schedule() {
+        var _a;
+        if (timer || entries.length === 0)
+            return;
+        timer = setTimeout(() => {
+            var _a;
+            timer = undefined;
+            deliver(entries.splice(0, (_a = config.batchSize) !== null && _a !== void 0 ? _a : 30));
+            schedule();
+        }, (_a = config.throttleTime) !== null && _a !== void 0 ? _a : 1000);
+    }
+    return {
+        enqueue(event, authorization, userId) {
+            var _a;
+            if (entries.length >= ((_a = config.maxQueueSize) !== null && _a !== void 0 ? _a : 1000))
+                return;
+            entries.push({ event: Promise.resolve(event).catch(() => undefined), authorization,
+                userId: Promise.resolve(userId).catch(() => null) });
+            schedule();
+        },
+        async flush() {
+            var _a;
+            clearTimeout(timer);
+            timer = undefined;
+            while (entries.length)
+                deliver(entries.splice(0, (_a = config.batchSize) !== null && _a !== void 0 ? _a : 30));
+            await Promise.all([...pending]);
+        },
+        cleanup() {
+            clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/modules/analytics.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { TrackEventParams, TrackEventData, AnalyticsModuleOptions, SessionContext } from "./analytics.types";
+import { TrackEventParams, AnalyticsModuleOptions, SessionContext } from "./analytics.types";
 import type { InternalAuthModule } from "./auth.types";
 import type { ExperimentsContext } from "./experiments-config.types.js";
 export declare const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
@@ -7,6 +7,18 @@ export declare const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_eve
 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";
+declare function createAnalyticsState(): {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    fallbackSessionId: string | null;
+    config: Required<AnalyticsModuleOptions>;
+};
+type AnalyticsState = ReturnType<typeof createAnalyticsState>;
+/** @internal */
+export declare function getAnalyticsState(axiosClient: AxiosInstance): AnalyticsState;
 export interface AnalyticsModuleArgs {
     axiosClient: AxiosInstance;
     serverUrl: string;
@@ -18,8 +30,6 @@ export interface AnalyticsModuleArgs {
 }
 /** @internal */
 export declare function isAnalyticsEnabled(enabled: boolean, state?: {
-    requestsQueue: TrackEventData[];
-    isProcessing: boolean;
     isHeartBeatProcessing: boolean;
     wasInitializationTracked: boolean;
     sessionContext: SessionContext | null;
@@ -28,7 +38,7 @@ export declare function isAnalyticsEnabled(enabled: boolean, state?: {
     fallbackSessionId: string | null;
     config: Required<AnalyticsModuleOptions>;
 }): boolean;
-export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }: AnalyticsModuleArgs) => {
+export declare const createAnalyticsModule: ({ axiosClient, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
     cleanup: () => void;
 };
@@ -45,8 +55,6 @@ export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, us
 export declare function resetAnalyticsSessionContext(axiosClient?: AxiosInstance): void;
 export declare function getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
 export declare function getAnalyticsSessionId(state?: {
-    requestsQueue: TrackEventData[];
-    isProcessing: boolean;
     isHeartBeatProcessing: boolean;
     wasInitializationTracked: boolean;
     sessionContext: SessionContext | null;
@@ -55,3 +63,4 @@ export declare function getAnalyticsSessionId(state?: {
     fallbackSessionId: string | null;
     config: Required<AnalyticsModuleOptions>;
 }): string;
+export {};

package/dist/modules/analytics.js

@@ -1,6 +1,7 @@
 import { getSharedInstance } from "../utils/sharedInstance.js";
 import { generateUuid, isReactNative } from "../utils/common.js";
 import { getExperimentsRuntime } from "./experiments-runtime.types.js";
+import { getAnalyticsQueue } from "./analytics-queue.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__";
@@ -14,14 +15,9 @@ const defaultConfiguration = {
     batchSize: 30,
     heartBeatInterval: 60 * 1000,
 };
-///////////////////////////////////////////////
-//// shared queue for analytics events     ////
-///////////////////////////////////////////////
 const ANALYTICS_SHARED_STATE_NAME = "analytics";
 function createAnalyticsState() {
     return {
-        requestsQueue: [],
-        isProcessing: false,
         isHeartBeatProcessing: false,
         wasInitializationTracked: false,
         sessionContext: null,
@@ -37,17 +33,27 @@ function createAnalyticsState() {
     };
 }
 const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, createAnalyticsState);
-const serverAnalyticsStates = new WeakMap();
+const clientAnalyticsStates = new WeakMap();
+/** @internal */
+export function getAnalyticsState(axiosClient) {
+    let state = clientAnalyticsStates.get(axiosClient);
+    if (!state) {
+        state = createAnalyticsState();
+        if (typeof window !== "undefined") {
+            state.config = analyticsSharedState.config;
+        }
+        clientAnalyticsStates.set(axiosClient, state);
+    }
+    return state;
+}
 /** @internal */
 export function isAnalyticsEnabled(enabled, state = analyticsSharedState) {
     return enabled && state.config.enabled && !isReactNative;
 }
-export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }) => {
-    const state = typeof window === "undefined" ? createAnalyticsState() : analyticsSharedState;
-    if (typeof window === "undefined")
-        serverAnalyticsStates.set(axiosClient, state);
-    // prevent overflow of events //
-    const { maxQueueSize, throttleTime, batchSize } = state.config;
+export const createAnalyticsModule = ({ axiosClient, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }) => {
+    const state = getAnalyticsState(axiosClient);
+    const automaticState = typeof window === "undefined" ? state : analyticsSharedState;
+    const queue = getAnalyticsQueue(axiosClient, appId, state.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
@@ -59,83 +65,35 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         };
     }
     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 = {}) => {
-        var _a;
-        if (eventsData.length === 0)
-            return;
-        const sessionContext_ = await getSessionContext(userAuthModule, state);
-        const events = eventsData.map(transformEventDataToApiRequestData({ ...sessionContext_, session_id: (_a = getVisitorId === null || getVisitorId === void 0 ? void 0 : getVisitorId()) !== null && _a !== void 0 ? _a : sessionContext_.session_id }));
-        try {
-            if (!options.isBeacon || !beaconRequest(events)) {
-                await batchRequestFallback(events);
-            }
-        }
-        catch (_b) {
-            // do nothing
-        }
-    };
-    const startProcessing = () => {
-        startAnalyticsProcessor(flush, {
-            throttleTime,
-            batchSize,
-        }, state);
-    };
     const track = (params) => {
-        var _a;
-        if (state.requestsQueue.length >= maxQueueSize) {
-            return;
-        }
+        var _a, _b;
         const intrinsicData = getEventIntrinsicData();
-        const preview = Object.fromEntries(Object.entries((_a = experimentsContext === null || experimentsContext === void 0 ? void 0 : experimentsContext.preview) !== null && _a !== void 0 ? _a : {}).filter(([, value]) => typeof value === "boolean"));
+        const visitorId = (_a = getVisitorId === null || getVisitorId === void 0 ? void 0 : getVisitorId()) !== null && _a !== void 0 ? _a : getAnalyticsSessionId(state);
+        const authorization = userAuthModule.hasToken() ? axiosClient.defaults.headers.common.Authorization : null;
+        const context = getSessionContext(userAuthModule, state);
+        const preview = Object.fromEntries(Object.entries((_b = experimentsContext === null || experimentsContext === void 0 ? void 0 : experimentsContext.preview) !== null && _b !== void 0 ? _b : {}).filter(([, value]) => typeof value === "boolean"));
         const properties = { ...params.properties };
         delete properties.__b44_experiment_preview;
         if (Object.keys(preview).length) {
             // Capture now: a queued event must retain its occurrence-time preview.
             properties.__b44_experiment_preview = JSON.stringify(preview);
         }
-        state.requestsQueue.push({
-            ...params,
-            ...intrinsicData,
+        const event = {
+            event_name: params.eventName,
+            timestamp: intrinsicData.timestamp,
+            page_url: intrinsicData.pageUrl,
             properties: params.properties || Object.keys(properties).length ? properties : undefined,
-        });
-        startProcessing();
+        };
+        queue.enqueue(context.then((identity) => ({ ...event, ...identity, session_id: visitorId })), typeof authorization === "string" ? authorization : null, context.then((identity) => { var _a; return (_a = identity.user_id) !== null && _a !== void 0 ? _a : null; }));
     };
     const onDocVisible = () => {
-        startAnalyticsProcessor(flush, {
-            throttleTime,
-            batchSize,
-        }, state);
-        clearHeartBeatProcessor = startHeartBeatProcessor(track, state);
-        setSessionDurationTimerStart(state);
+        clearHeartBeatProcessor = startHeartBeatProcessor(track, automaticState);
+        setSessionDurationTimerStart(automaticState);
     };
     const onDocHidden = () => {
-        stopAnalyticsProcessor(state);
         clearHeartBeatProcessor === null || clearHeartBeatProcessor === void 0 ? void 0 : clearHeartBeatProcessor();
-        trackSessionDurationEvent(track, state);
-        //  flush entire queue on visibility change and hope for the best //
-        const eventsData = state.requestsQueue.splice(0);
-        flush(eventsData, { isBeacon: true });
+        trackSessionDurationEvent(track, automaticState);
+        void queue.flush();
     };
     const onVisibilityChange = () => {
         if (typeof window === "undefined")
@@ -148,18 +106,16 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         }
     };
     const cleanup = () => {
-        stopAnalyticsProcessor(state);
+        queue.cleanup();
         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, state);
+    clearHeartBeatProcessor = startHeartBeatProcessor(track, automaticState);
     // track the referrer event //
-    trackInitializationEvent(track, state);
+    trackInitializationEvent(track, automaticState);
     // start the visibility change listener //
     if (typeof window !== "undefined") {
         window.addEventListener("visibilitychange", onVisibilityChange);
@@ -169,24 +125,6 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         cleanup,
     };
 };
-function stopAnalyticsProcessor(state) {
-    state.isProcessing = false;
-}
-async function startAnalyticsProcessor(handleTrack, options, state) {
-    if (state.isProcessing) {
-        // only one instance of the analytics processor can be running at a time //
-        return;
-    }
-    state.isProcessing = true;
-    const { throttleTime = 1000, batchSize = 30 } = options !== null && options !== void 0 ? options : {};
-    while (state.isProcessing &&
-        state.requestsQueue.length > 0) {
-        const requests = state.requestsQueue.splice(0, batchSize);
-        requests.length && (await handleTrack(requests));
-        await new Promise((resolve) => setTimeout(resolve, throttleTime));
-    }
-    state.isProcessing = false;
-}
 function startHeartBeatProcessor(track, state) {
     var _a;
     // Browser-only, like the other automatic events here (initialization, session
@@ -247,15 +185,6 @@ function getEventIntrinsicData() {
         pageUrl: typeof window !== "undefined" ? (_b = (_a = window.location) === null || _a === void 0 ? void 0 : _a.pathname) !== null && _b !== void 0 ? _b : null : null,
     };
 }
-function transformEventDataToApiRequestData(sessionContext) {
-    return (eventData) => ({
-        event_name: eventData.eventName,
-        properties: eventData.properties,
-        timestamp: eventData.timestamp,
-        page_url: eventData.pageUrl,
-        ...sessionContext,
-    });
-}
 /**
  * Clears the memoized analytics session context.
  *
@@ -267,8 +196,7 @@ function transformEventDataToApiRequestData(sessionContext) {
  * @internal
  */
 export function resetAnalyticsSessionContext(axiosClient) {
-    var _a;
-    const state = axiosClient ? (_a = serverAnalyticsStates.get(axiosClient)) !== null && _a !== void 0 ? _a : analyticsSharedState : analyticsSharedState;
+    const state = axiosClient ? getAnalyticsState(axiosClient) : analyticsSharedState;
     state.sessionContext = null;
     state.sessionContextPromise = null;
 }

package/dist/modules/experiment-exposures.d.ts

@@ -15,5 +15,5 @@ export declare function createExposureTracker({ axiosClient, appId, enabled, sou
         visitorId: string;
         userId: string | null;
     }): void;
-    flush(): Promise<void>;
+    flush: () => Promise<void>;
 };

package/dist/modules/experiment-exposures.js

@@ -1,65 +1,30 @@
 import { v4 as uuid } from "uuid";
-import { isAnalyticsEnabled } from "./analytics.js";
+import { getAnalyticsState, isAnalyticsEnabled } from "./analytics.js";
+import { getAnalyticsQueue } from "./analytics-queue.js";
 /** @internal */
 export function createExposureTracker({ axiosClient, appId, enabled, source = "browser", pageUrl, }) {
-    const entries = new Map();
-    function send(entry) {
-        if (entry.pending)
-            return entry.pending;
-        const pending = (async () => {
-            for (let attempt = 0;; attempt++) {
-                try {
-                    const response = await axiosClient.request({
-                        method: "POST",
-                        url: `/apps/${appId}/analytics/track/batch`,
-                        headers: { Authorization: entry.authorization },
-                        data: entry.data,
-                    });
-                    if (response.accepted !== 1)
-                        throw new Error("Experiment exposure was not accepted");
-                    entry.acknowledged = true;
-                    return;
-                }
-                catch (error) {
-                    if (attempt === 2)
-                        throw error;
-                    await new Promise((resolve) => setTimeout(resolve, attempt === 0 ? 100 : 500));
-                }
-            }
-        })().finally(() => { entry.pending = undefined; });
-        entry.pending = pending;
-        // Reads stay synchronous; flush() lets request handlers observe delivery failures.
-        void pending.catch(() => { });
-        return pending;
-    }
+    const state = getAnalyticsState(axiosClient);
+    const queue = getAnalyticsQueue(axiosClient, appId, state.config);
+    const tracked = new Set();
     return {
         track(assignment, identity) {
-            if ((source === "browser" && typeof window === "undefined") || !isAnalyticsEnabled(enabled))
+            if ((source === "browser" && typeof window === "undefined") || !isAnalyticsEnabled(enabled, state))
                 return;
             const { experiment_id, run_version, variant_key } = assignment;
             const key = JSON.stringify([experiment_id, run_version, variant_key, identity.userId, identity.visitorId]);
-            let entry = entries.get(key);
-            if (!entry) {
-                const authorization = identity.userId ? axiosClient.defaults.headers.common.Authorization : null;
-                entry = {
-                    acknowledged: false,
-                    authorization: typeof authorization === "string" ? authorization : null,
-                    data: { events: [{
-                                event_id: uuid(),
-                                event_name: "__experiment_exposure__",
-                                timestamp: new Date().toISOString(),
-                                session_id: identity.visitorId,
-                                page_url: pageUrl !== null && pageUrl !== void 0 ? pageUrl : (typeof window === "undefined" ? "/" : window.location.pathname),
-                                properties: { experiment_id, run_version, variant_key, source },
-                            }] },
-                };
-                entries.set(key, entry);
-            }
-            if (!entry.acknowledged)
-                void send(entry);
-        },
-        async flush() {
-            await Promise.all([...entries.values()].filter((entry) => !entry.acknowledged).map(send));
+            if (tracked.has(key))
+                return;
+            tracked.add(key);
+            const authorization = identity.userId ? axiosClient.defaults.headers.common.Authorization : null;
+            queue.enqueue({
+                event_id: uuid(),
+                event_name: "__experiment_exposure__",
+                timestamp: new Date().toISOString(),
+                session_id: identity.visitorId,
+                page_url: pageUrl !== null && pageUrl !== void 0 ? pageUrl : (typeof window === "undefined" ? "/" : window.location.pathname),
+                properties: { experiment_id, run_version, variant_key, source },
+            }, typeof authorization === "string" ? authorization : null, identity.userId);
         },
+        flush: queue.flush,
     };
 }

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

@@ -25,7 +25,7 @@ export interface ExperimentsSnapshot {
  */
 export interface ExperimentsModule {
     /**
-     * Reads a flag and queues an acknowledged exposure for its current assignment.
+     * Reads a flag and queues a best-effort exposure for its current assignment.
      *
      * Never starts an authentication request. Reads return the fallback while the
      * app's normal auth initialization is pending or failed. Supply trusted bootstrap
@@ -34,8 +34,13 @@ export interface ExperimentsModule {
      * Call only where the feature is used: a read counts as exposure, not proof of
      * visibility. Preview overrides and flags without an assignment are not tracked.
      * Exposures respect the client's analytics setting, are deduplicated per client,
-     * experiment run, variant and identity. Failed sends retry up to three attempts
-     * with the same event ID, timestamp and credentials. Await flush() on servers.
+     * experiment run, variant and identity. Network and server failures retry up to
+     * three attempts within five seconds of batch delivery, preserving the event ID,
+     * timestamp and credentials. HTTP successes (including rejected measurements) and client errors
+     * are terminal. Exposures share the Analytics batch with compatible ordinary
+     * events; credentials and user/visitor identities are captured when tracking.
+     * Only exposures are retried; ordinary goals retain single-attempt delivery.
+     * On servers, use the runtime's background lifetime mechanism.
      *
      * @param flagKey - Feature flag key defined in your app.
      * @param fallback - Value for an unavailable flag or unresolved identity. Defaults to `false`.
@@ -97,10 +102,23 @@ export interface ExperimentsModule {
      */
     ready(): Promise<ExperimentsSnapshot>;
     /**
-     * Waits until queued exposures are acknowledged; rejects after bounded retries.
-     * Server/Worker handlers must await this before ending the request (or use waitUntil).
-     * Retries preserve event IDs but raw storage is not exactly-once. Calling again
-     * retries unacknowledged events with the same IDs. No new exposures are created.
+     * Flushes this client's queued Analytics goals and exposures without rejecting.
+     * Each delivery has a five-second total budget; exhausted or rejected events are
+     * dropped and are not retried by later reads or flushes. Settlement is not proof
+     * of ingestion, and raw storage is not exactly-once. No new exposures are created.
+     * Worker handlers should use `ctx.waitUntil(client.experiments.flush())` instead
+     * of awaiting Analytics on the application response path. Other runtimes must use
+     * their supported background lifetime mechanism; fire-and-forget alone may be cut off.
+     * Base44's legacy Cloudflare runtime exposes `globalThis.Base44.waitUntil(...)`;
+     * the newer runtime exports `waitUntil` from `base44:runtime`. Use the API provided
+     * by your deployed runtime. Deno without a background lifetime API must await flush.
+     *
+     * @returns A promise that resolves when the current batch deliveries settle.
+     * @example
+     * ```typescript
+     * // In a Worker handler with an execution context:
+     * ctx.waitUntil(base44.experiments.flush());
+     * ```
      */
     flush(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.280.7eec9ba",
+  "version": "0.8.48-pr.280.b620aa9",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",