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

package/dist/client.js

@@ -230,6 +230,7 @@ export function createClient(config) {
             userAuthModule,
             enabled: (_f = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _f !== void 0 ? _f : true,
             getVisitorId: experiments.visitorId,
+            experimentsContext,
         }),
         actors: actorsModule.module,
         cleanup: () => {

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,11 +1,24 @@
 import { AxiosInstance } from "axios";
-import { TrackEventParams, AnalyticsModuleOptions } 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__";
 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";
+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;
@@ -13,10 +26,19 @@ export interface AnalyticsModuleArgs {
     userAuthModule: InternalAuthModule;
     enabled: boolean;
     getVisitorId?: () => string | undefined;
+    experimentsContext?: ExperimentsContext;
 }
 /** @internal */
-export declare function isAnalyticsEnabled(enabled: boolean): boolean;
-export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, }: AnalyticsModuleArgs) => {
+export declare function isAnalyticsEnabled(enabled: boolean, state?: {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    fallbackSessionId: string | null;
+    config: Required<AnalyticsModuleOptions>;
+}): boolean;
+export declare const createAnalyticsModule: ({ axiosClient, appId, userAuthModule, enabled, getVisitorId, experimentsContext, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
     cleanup: () => void;
 };
@@ -30,6 +52,15 @@ export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, us
  *
  * @internal
  */
-export declare function resetAnalyticsSessionContext(): void;
+export declare function resetAnalyticsSessionContext(axiosClient?: AxiosInstance): void;
 export declare function getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
-export declare function getAnalyticsSessionId(): string;
+export declare function getAnalyticsSessionId(state?: {
+    isHeartBeatProcessing: boolean;
+    wasInitializationTracked: boolean;
+    sessionContext: SessionContext | null;
+    sessionContextPromise: Promise<SessionContext> | null;
+    sessionStartTime: string | null;
+    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,112 +15,85 @@ const defaultConfiguration = {
     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,
-    // Memoized session id for when `localStorage` can't persist one — see
-    // getAnalyticsSessionId.
-    fallbackSessionId: null,
-    config: {
-        ...defaultConfiguration,
-        ...getAnalyticsConfigFromUrlParams(),
-    },
-}));
+function createAnalyticsState() {
+    return {
+        isHeartBeatProcessing: false,
+        wasInitializationTracked: false,
+        sessionContext: null,
+        sessionContextPromise: null,
+        sessionStartTime: null,
+        // Memoized session id for when `localStorage` can't persist one — see
+        // getAnalyticsSessionId.
+        fallbackSessionId: null,
+        config: {
+            ...defaultConfiguration,
+            ...getAnalyticsConfigFromUrlParams(),
+        },
+    };
+}
+const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, createAnalyticsState);
+const clientAnalyticsStates = new WeakMap();
 /** @internal */
-export function isAnalyticsEnabled(enabled) {
-    return enabled && analyticsSharedState.config.enabled && !isReactNative;
+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;
 }
-export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, }) => {
-    // prevent overflow of events //
-    const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
+/** @internal */
+export function isAnalyticsEnabled(enabled, state = analyticsSharedState) {
+    return enabled && state.config.enabled && !isReactNative;
+}
+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
     // still handled by those `window` guards, so this doesn't affect it.
-    if (!isAnalyticsEnabled(enabled)) {
+    if (!isAnalyticsEnabled(enabled, state)) {
         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 = {}) => {
-        var _a;
-        if (eventsData.length === 0)
-            return;
-        const sessionContext_ = await getSessionContext(userAuthModule);
-        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,
-        });
-    };
     const track = (params) => {
-        if (analyticsSharedState.requestsQueue.length >= maxQueueSize) {
-            return;
-        }
+        var _a, _b;
         const intrinsicData = getEventIntrinsicData();
-        analyticsSharedState.requestsQueue.push({
-            ...params,
-            ...intrinsicData,
-        });
-        startProcessing();
+        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);
+        }
+        const event = {
+            event_name: params.eventName,
+            timestamp: intrinsicData.timestamp,
+            page_url: intrinsicData.pageUrl,
+            properties: params.properties || Object.keys(properties).length ? properties : undefined,
+        };
+        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,
-        });
-        clearHeartBeatProcessor = startHeartBeatProcessor(track);
-        setSessionDurationTimerStart();
+        clearHeartBeatProcessor = startHeartBeatProcessor(track, automaticState);
+        setSessionDurationTimerStart(automaticState);
     };
     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 });
+        trackSessionDurationEvent(track, automaticState);
+        void queue.flush();
     };
     const onVisibilityChange = () => {
         if (typeof window === "undefined")
@@ -132,18 +106,16 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         }
     };
     const cleanup = () => {
-        stopAnalyticsProcessor();
+        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);
+    clearHeartBeatProcessor = startHeartBeatProcessor(track, automaticState);
     // track the referrer event //
-    trackInitializationEvent(track);
+    trackInitializationEvent(track, automaticState);
     // start the visibility change listener //
     if (typeof window !== "undefined") {
         window.addEventListener("visibilitychange", onVisibilityChange);
@@ -153,50 +125,32 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         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) {
+function startHeartBeatProcessor(track, state) {
     var _a;
     // Browser-only, like the other automatic events here (initialization, session
     // duration, visibility). Outside a browser this timer fired a `me()` every
     // interval for the lifetime of a long-lived server-side client, and kept the
     // Node event loop alive. Explicit `analytics.track()` calls still work.
     if (typeof window === "undefined" ||
-        analyticsSharedState.isHeartBeatProcessing ||
-        ((_a = analyticsSharedState.config.heartBeatInterval) !== null && _a !== void 0 ? _a : 0) < 10) {
+        state.isHeartBeatProcessing ||
+        ((_a = state.config.heartBeatInterval) !== null && _a !== void 0 ? _a : 0) < 10) {
         return () => { };
     }
-    analyticsSharedState.isHeartBeatProcessing = true;
+    state.isHeartBeatProcessing = true;
     const interval = setInterval(() => {
         track({ eventName: USER_HEARTBEAT_EVENT_NAME });
-    }, analyticsSharedState.config.heartBeatInterval);
+    }, state.config.heartBeatInterval);
     return () => {
         clearInterval(interval);
-        analyticsSharedState.isHeartBeatProcessing = false;
+        state.isHeartBeatProcessing = false;
     };
 }
-function trackInitializationEvent(track) {
+function trackInitializationEvent(track, state) {
     if (typeof window === "undefined" ||
-        analyticsSharedState.wasInitializationTracked) {
+        state.wasInitializationTracked) {
         return;
     }
-    analyticsSharedState.wasInitializationTracked = true;
+    state.wasInitializationTracked = true;
     track({
         eventName: ANALYTICS_INITIALIZATION_EVENT_NAME,
         properties: {
@@ -204,20 +158,20 @@ function trackInitializationEvent(track) {
         },
     });
 }
-function setSessionDurationTimerStart() {
+function setSessionDurationTimerStart(state) {
     if (typeof window === "undefined" ||
-        analyticsSharedState.sessionStartTime !== null) {
+        state.sessionStartTime !== null) {
         return;
     }
-    analyticsSharedState.sessionStartTime = new Date().toISOString();
+    state.sessionStartTime = new Date().toISOString();
 }
-function trackSessionDurationEvent(track) {
+function trackSessionDurationEvent(track, state) {
     if (typeof window === "undefined" ||
-        analyticsSharedState.sessionStartTime === null)
+        state.sessionStartTime === null)
         return;
     const sessionDuration = new Date().getTime() -
-        new Date(analyticsSharedState.sessionStartTime).getTime();
-    analyticsSharedState.sessionStartTime = null;
+        new Date(state.sessionStartTime).getTime();
+    state.sessionStartTime = null;
     track({
         eventName: ANALYTICS_SESSION_DURATION_EVENT_NAME,
         properties: { sessionDuration },
@@ -231,16 +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,
-    });
-}
-let sessionContextPromise = null;
 /**
  * Clears the memoized analytics session context.
  *
@@ -251,22 +195,23 @@ let sessionContextPromise = null;
  *
  * @internal
  */
-export function resetAnalyticsSessionContext() {
-    analyticsSharedState.sessionContext = null;
-    sessionContextPromise = null;
+export function resetAnalyticsSessionContext(axiosClient) {
+    const state = axiosClient ? getAnalyticsState(axiosClient) : analyticsSharedState;
+    state.sessionContext = null;
+    state.sessionContextPromise = null;
 }
-async function getSessionContext(userAuthModule) {
-    if (!analyticsSharedState.sessionContext) {
+async function getSessionContext(userAuthModule, state) {
+    if (!state.sessionContext) {
         // With no token there is no identity to resolve: `me()` can only answer 401,
         // which the browser logs to the console before any handler here sees it. On
         // a public page that request is the sole reason an error appears, so skip
         // it. This is not memoized — a visitor who logs in later must still resolve.
         if (!userAuthModule.hasToken()) {
-            return { user_id: null, session_id: getAnalyticsSessionId() };
+            return { user_id: null, session_id: getAnalyticsSessionId(state) };
         }
-        if (!sessionContextPromise) {
-            const sessionId = getAnalyticsSessionId();
-            sessionContextPromise = userAuthModule
+        if (!state.sessionContextPromise) {
+            const sessionId = getAnalyticsSessionId(state);
+            state.sessionContextPromise = userAuthModule
                 .me()
                 .then((user) => ({
                 user_id: user.id,
@@ -277,7 +222,7 @@ async function getSessionContext(userAuthModule) {
                 session_id: sessionId,
             }));
         }
-        const pending = sessionContextPromise;
+        const pending = state.sessionContextPromise;
         const context = await pending;
         // Publish only if this lookup is still the current one. A reset that lands
         // while the request is in flight nulls `sessionContextPromise`, and an
@@ -285,12 +230,12 @@ async function getSessionContext(userAuthModule) {
         // for the rest of the session. The awaited value is still returned: these
         // events were queued before the identity changed, so that is who they
         // belong to.
-        if (sessionContextPromise === pending) {
-            analyticsSharedState.sessionContext = context;
+        if (state.sessionContextPromise === pending) {
+            state.sessionContext = context;
         }
         return context;
     }
-    return analyticsSharedState.sessionContext;
+    return state.sessionContext;
 }
 export function getAnalyticsConfigFromUrlParams() {
     // `window.location` is absent on React Native. This runs at module load (via
@@ -312,19 +257,18 @@ export function getAnalyticsConfigFromUrlParams() {
     // return the config object //
     return { enabled: analyticsEnable === "true" };
 }
-// When the id can't be persisted (React Native has no `localStorage`), keep
-// it stable for the process instead of minting a fresh one per call.
-function getFallbackSessionId() {
+// Without persistent storage, keep the id stable within this analytics state.
+function getFallbackSessionId(state) {
     var _a;
-    return ((_a = analyticsSharedState.fallbackSessionId) !== null && _a !== void 0 ? _a : (analyticsSharedState.fallbackSessionId = generateUuid()));
+    return ((_a = state.fallbackSessionId) !== null && _a !== void 0 ? _a : (state.fallbackSessionId = generateUuid()));
 }
-export function getAnalyticsSessionId() {
+export function getAnalyticsSessionId(state = analyticsSharedState) {
     var _a;
     const visitorId = (_a = getExperimentsRuntime()) === null || _a === void 0 ? void 0 : _a.visitorId;
     if (visitorId && visitorId !== "anon")
         return visitorId;
     if (typeof window === "undefined") {
-        return getFallbackSessionId();
+        return getFallbackSessionId(state);
     }
     try {
         const sessionId = localStorage.getItem(ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY);
@@ -336,6 +280,6 @@ export function getAnalyticsSessionId() {
         return sessionId;
     }
     catch (_b) {
-        return getFallbackSessionId();
+        return getFallbackSessionId(state);
     }
 }

package/dist/modules/auth.js

@@ -177,7 +177,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // Drop identity resolved under the previous session: a `me()` already in
             // flight would otherwise resolve into callers that run after the logout.
             clearPendingMe();
-            resetAnalyticsSessionContext();
+            resetAnalyticsSessionContext(axios);
             hasAccessToken = false;
             notifyAuthState({ status: "anonymous" });
             // Only do the rest if in a browser environment
@@ -207,7 +207,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // Same reasoning as in `logout`: the identity changes here, so anything
             // resolved for the previous one must not be handed to later callers.
             clearPendingMe();
-            resetAnalyticsSessionContext();
+            resetAnalyticsSessionContext(axios);
             hasAccessToken = true;
             // handle token change for axios clients
             axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;

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.b5c6133",
+  "version": "0.8.48-pr.280.b620aa9",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",