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

package/dist/client.js

@@ -16,6 +16,7 @@ import { RoomsSocket } from "./utils/socket-utils.js";
 import { createAnalyticsModule } from "./modules/analytics.js";
 import { createExperimentsModule } from "./modules/experiments.js";
 import { createExposureTracker } from "./modules/experiment-exposures.js";
+import { EXPERIMENTS_CONTEXT_HEADER, getBrowserExperimentsContext, readExperimentsContext } from "./modules/experiments-context.js";
 import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
 /**
  * Creates a Base44 client.
@@ -55,10 +56,11 @@ import { createActorsModule, resolveActorsHost, } from "./modules/actors.js";
  * ```
  */
 export function createClient(config) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     const { serverUrl = "https://base44.app", appId, analytics, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
     // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
     const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
+    const experimentsContext = (_a = config.experiments) !== null && _a !== void 0 ? _a : getBrowserExperimentsContext(appId);
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -75,9 +77,14 @@ export function createClient(config) {
         }
         return socket;
     };
+    const { [EXPERIMENTS_CONTEXT_HEADER]: inheritedExperimentsContext, ...requestHeaders } = optionalHeaders !== null && optionalHeaders !== void 0 ? optionalHeaders : {};
     const headers = {
-        ...optionalHeaders,
+        ...requestHeaders,
         "X-App-Id": String(appId),
+        ...(experimentsContext ? {
+            "Base44-Visitor-Id": experimentsContext.identity.visitorId,
+            "Base44-Experiment-Preview": JSON.stringify((_b = experimentsContext.preview) !== null && _b !== void 0 ? _b : {}),
+        } : {}),
     };
     const functionHeaders = functionsVersion
         ? {
@@ -123,13 +130,18 @@ export function createClient(config) {
         baseURL: `${serverUrl}/api`,
         headers,
     });
+    const exposureTracker = createExposureTracker({
+        axiosClient,
+        appId,
+        enabled: (_c = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _c !== void 0 ? _c : true,
+        source: typeof window === "undefined" ? "backend" : "browser",
+        pageUrl: experimentsContext === null || experimentsContext === void 0 ? void 0 : experimentsContext.pageUrl,
+    });
     const experiments = createExperimentsModule({
         getAuth: () => userAuthModule,
-        trackExposure: createExposureTracker({
-            axiosClient,
-            appId,
-            enabled: (_a = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _a !== void 0 ? _a : true,
-        }).track,
+        trackExposure: exposureTracker.track,
+        flushExposures: exposureTracker.flush,
+        context: experimentsContext,
     });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
         appBaseUrl: normalizedAppBaseUrl,
@@ -147,11 +159,19 @@ export function createClient(config) {
             userAuthModule.setToken(accessToken);
         }
     }
+    if (experimentsContext) {
+        const { userId, status } = experimentsContext.identity;
+        // The document's cookie identity may differ from this client's localStorage token.
+        const needsClientIdentity = typeof window !== "undefined" && userAuthModule.hasToken() &&
+            experimentsContext.config.experiments.some((experiment) => experiment.assign_by === "user");
+        experiments.onAuthStateChange(status === "pending" || needsClientIdentity ? { status: "pending" } :
+            userId ? { status: "authenticated", userId } : { status: "anonymous" });
+    }
     const actorsModule = createActorsModule({
         appId,
         // serverUrl is often relative/empty (same-origin app); the proxy-fallback
         // URL needs an absolute host, so fall back to the page origin.
-        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_b = window.location) === null || _b === void 0 ? void 0 : _b.origin : undefined),
+        host: resolveActorsHost(serverUrl, typeof window !== "undefined" ? (_d = window.location) === null || _d === void 0 ? void 0 : _d.origin : undefined),
         functionsVersion,
         getAuthToken: () => token || getAccessToken(),
         mintConnectionToken: async (actorName, room, connectionId) => {
@@ -190,7 +210,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_c = functionsAxiosClient.defaults) === null || _c === void 0 ? void 0 : _c.baseURL,
+            baseURL: (_e = functionsAxiosClient.defaults) === null || _e === void 0 ? void 0 : _e.baseURL,
         }),
         agents: createAgentsModule({
             axios: axiosClient,
@@ -208,7 +228,8 @@ export function createClient(config) {
             serverUrl,
             appId,
             userAuthModule,
-            enabled: (_d = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _d !== void 0 ? _d : true,
+            enabled: (_f = analytics === null || analytics === void 0 ? void 0 : analytics.enabled) !== null && _f !== void 0 ? _f : true,
+            getVisitorId: experiments.visitorId,
         }),
         actors: actorsModule.module,
         cleanup: () => {
@@ -238,7 +259,7 @@ export function createClient(config) {
                 }
                 return headers;
             },
-            baseURL: (_e = serviceRoleFunctionsAxiosClient.defaults) === null || _e === void 0 ? void 0 : _e.baseURL,
+            baseURL: (_g = serviceRoleFunctionsAxiosClient.defaults) === null || _g === void 0 ? void 0 : _g.baseURL,
         }),
         agents: createAgentsModule({
             axios: serviceRoleAxiosClient,
@@ -281,7 +302,10 @@ export function createClient(config) {
             appId: String(appId),
             serverUrl,
             functionsVersion,
-            platformHeaders: optionalHeaders,
+            platformHeaders: {
+                ...headers,
+                ...(inheritedExperimentsContext ? { [EXPERIMENTS_CONTEXT_HEADER]: inheritedExperimentsContext } : {}),
+            },
         }),
         /**
          * Sets a new authentication token for all subsequent requests.
@@ -433,6 +457,10 @@ export function createClientFromRequest(request) {
     }
     // Prepare additional headers to propagate
     const additionalHeaders = {};
+    const encodedExperiments = request.headers.get(EXPERIMENTS_CONTEXT_HEADER);
+    const experimentsContext = readExperimentsContext(encodedExperiments, appId);
+    if (experimentsContext && encodedExperiments)
+        additionalHeaders[EXPERIMENTS_CONTEXT_HEADER] = encodedExperiments;
     if (stateHeader) {
         additionalHeaders["Base44-State"] = stateHeader;
     }
@@ -453,5 +481,6 @@ export function createClientFromRequest(request) {
         serviceToken: serviceRoleToken,
         functionsVersion: functionsVersion !== null && functionsVersion !== void 0 ? functionsVersion : undefined,
         headers: additionalHeaders,
+        experiments: experimentsContext ? { ...experimentsContext, pageUrl: request.url ? new URL(request.url).pathname : "/" } : undefined,
     });
 }

package/dist/client.types.d.ts

@@ -10,6 +10,7 @@ import type { AppLogsModule } from "./modules/app-logs.types.js";
 import type { AppModule } from "./modules/app.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
 import type { ExperimentsModule } from "./modules/experiments.types.js";
+import type { ExperimentsContext } from "./modules/experiments-config.types.js";
 import type { ActorsModule } from "./modules/actors.types.js";
 import type { FetchWithAuthInit } from "./utils/fetch-with-auth.js";
 /**
@@ -80,6 +81,12 @@ export interface CreateClientConfig {
      * Omit this option to preserve the default analytics behavior.
      */
     analytics?: CreateClientAnalyticsConfig;
+    /**
+     * Platform-validated context for local flag evaluation. Request-scoped on servers.
+     * Automatically read from the platform bootstrap in browsers and trusted headers
+     * by createClientFromRequest(). Not an authorization credential.
+     */
+    experiments?: ExperimentsContext;
     /**
      * User authentication token. Used to authenticate as a specific user.
      *
@@ -135,7 +142,7 @@ export interface Base44Client {
     connectors: UserConnectorsModule;
     /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
     entities: EntitiesModule;
-    /** {@link ExperimentsModule | Experiments module} for browser feature flags and exposures. */
+    /** {@link ExperimentsModule | Experiments module} for local feature flags and exposures. */
     experiments: ExperimentsModule;
     /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
     functions: FunctionsModule;

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientAnalyticsConfig, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
+export { evaluateExperiments } from "./modules/experiments-evaluator.js";
+export type { ExperimentsConfig, ExperimentsContext, ExperimentsIdentity } from "./modules/experiments-config.types.js";
 export type { ExperimentsModule, ExperimentsSnapshot, } from "./modules/experiments.types.js";
 export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";

package/dist/index.js

@@ -3,4 +3,5 @@ import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export * from "./types.js";
+export { evaluateExperiments } from "./modules/experiments-evaluator.js";
 export { Actor } from "./actor.js";

package/dist/modules/analytics.d.ts

@@ -12,10 +12,11 @@ export interface AnalyticsModuleArgs {
     appId: string;
     userAuthModule: InternalAuthModule;
     enabled: boolean;
+    getVisitorId?: () => string | undefined;
 }
 /** @internal */
 export declare function isAnalyticsEnabled(enabled: boolean): boolean;
-export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }: AnalyticsModuleArgs) => {
+export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, }: AnalyticsModuleArgs) => {
     track: (params: TrackEventParams) => void;
     cleanup: () => void;
 };

package/dist/modules/analytics.js

@@ -1,5 +1,6 @@
 import { getSharedInstance } from "../utils/sharedInstance.js";
 import { generateUuid, isReactNative } from "../utils/common.js";
+import { getExperimentsRuntime } from "./experiments-runtime.types.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__";
@@ -37,7 +38,7 @@ const analyticsSharedState = getSharedInstance(ANALYTICS_SHARED_STATE_NAME, () =
 export function isAnalyticsEnabled(enabled) {
     return enabled && analyticsSharedState.config.enabled && !isReactNative;
 }
-export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, enabled, }) => {
+export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthModule, enabled, getVisitorId, }) => {
     // prevent overflow of events //
     const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
     // Disable analytics on React Native. It defines `window` but not `document`,
@@ -73,16 +74,17 @@ export const createAnalyticsModule = ({ axiosClient, serverUrl, appId, userAuthM
         }
     };
     const flush = async (eventsData, options = {}) => {
+        var _a;
         if (eventsData.length === 0)
             return;
         const sessionContext_ = await getSessionContext(userAuthModule);
-        const events = eventsData.map(transformEventDataToApiRequestData(sessionContext_));
+        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 (_a) {
+        catch (_b) {
             // do nothing
         }
     };
@@ -317,6 +319,10 @@ function getFallbackSessionId() {
     return ((_a = analyticsSharedState.fallbackSessionId) !== null && _a !== void 0 ? _a : (analyticsSharedState.fallbackSessionId = generateUuid()));
 }
 export function getAnalyticsSessionId() {
+    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();
     }
@@ -329,7 +335,7 @@ export function getAnalyticsSessionId() {
         }
         return sessionId;
     }
-    catch (_a) {
+    catch (_b) {
         return getFallbackSessionId();
     }
 }

package/dist/modules/auth.js

@@ -239,6 +239,8 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 const { access_token, user } = response;
                 if (access_token) {
                     this.setToken(access_token);
+                    if (typeof (user === null || user === void 0 ? void 0 : user.id) === "string")
+                        notifyAuthState({ status: "authenticated", userId: user.id });
                 }
                 return {
                     access_token,

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

@@ -1,9 +1,11 @@
 import type { AxiosInstance } from "axios";
 /** @internal */
-export declare function createExposureTracker({ axiosClient, appId, enabled, }: {
+export declare function createExposureTracker({ axiosClient, appId, enabled, source, pageUrl, }: {
     axiosClient: AxiosInstance;
     appId: string;
     enabled: boolean;
+    source?: "browser" | "backend";
+    pageUrl?: string;
 }): {
     track(assignment: {
         experiment_id: string;
@@ -13,4 +15,5 @@ export declare function createExposureTracker({ axiosClient, appId, enabled, }:
         visitorId: string;
         userId: string | null;
     }): void;
+    flush(): Promise<void>;
 };

package/dist/modules/experiment-exposures.js

@@ -1,45 +1,65 @@
+import { v4 as uuid } from "uuid";
 import { isAnalyticsEnabled } from "./analytics.js";
 /** @internal */
-export function createExposureTracker({ axiosClient, appId, enabled, }) {
-    const exposed = new Set();
+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;
+    }
     return {
         track(assignment, identity) {
-            var _a;
-            if (typeof window === "undefined" || !isAnalyticsEnabled(enabled))
+            if ((source === "browser" && typeof window === "undefined") || !isAnalyticsEnabled(enabled))
                 return;
             const { experiment_id, run_version, variant_key } = assignment;
-            const key = JSON.stringify([
-                experiment_id,
-                run_version,
-                variant_key,
-                identity.userId,
-                identity.visitorId,
-            ]);
-            if (exposed.has(key))
-                return;
-            exposed.add(key);
-            // Pin the event's auth before an account change can alter Axios defaults.
-            const authorization = identity.userId
-                ? ((_a = axiosClient.defaults.headers.common.Authorization) !== null && _a !== void 0 ? _a : null)
-                : null;
-            void axiosClient
-                .request({
-                method: "POST",
-                url: `/apps/${appId}/analytics/track/batch`,
-                headers: { Authorization: authorization },
-                data: {
-                    events: [
-                        {
-                            event_name: "__experiment_exposure__",
-                            timestamp: new Date().toISOString(),
-                            session_id: identity.visitorId,
-                            page_url: window.location.pathname,
-                            properties: { experiment_id, run_version, variant_key },
-                        },
-                    ],
-                },
-            })
-                .catch(() => exposed.delete(key));
+            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));
         },
     };
 }

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

@@ -0,0 +1,39 @@
+import type { ExperimentsSnapshot } from "./experiments.types.js";
+/** Shared versioned configuration published by the platform, never visitor-specific. */
+export interface ExperimentsConfig {
+    v: 1;
+    app_id: string;
+    revision?: number;
+    flags: {
+        key: string;
+        rollout_percentage: number;
+    }[];
+    experiments: {
+        id: string;
+        flag_key: string;
+        run_version: number;
+        assign_by: "visitor" | "user";
+        traffic_allocation: number;
+        variants: {
+            key: string;
+            value: boolean;
+            weight: number;
+        }[];
+    }[];
+}
+/** Identity supplied by the platform's normal authenticated request/bootstrap path. */
+export interface ExperimentsIdentity {
+    visitorId: string;
+    userId: string | null;
+    status?: "authenticated" | "anonymous" | "pending";
+}
+/** One request's or browser page's context. Never share it between server requests. */
+export interface ExperimentsContext {
+    config: ExperimentsConfig;
+    identity: ExperimentsIdentity;
+    preview?: Readonly<Record<string, boolean>>;
+    /** Request pathname used for server-side exposure events. */
+    pageUrl?: string;
+    /** Exact server-rendered flags, retained for the browser's first hydration render. */
+    serverSnapshot?: ExperimentsSnapshot;
+}

package/dist/modules/experiments-config.types.js

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

package/dist/modules/experiments-context.d.ts

@@ -0,0 +1,10 @@
+import type { ExperimentsContext } from "./experiments-config.types.js";
+import type { ExperimentsRuntime } from "./experiments-runtime.types.js";
+/** @internal Platform ingress overwrites this header; it is not authentication. */
+export declare const EXPERIMENTS_CONTEXT_HEADER = "Base44-Experiments-Context";
+/** @internal */
+export declare function readExperimentsContext(encoded: string | null, appId: string): ExperimentsContext | undefined;
+/** @internal */
+export declare function getBrowserExperimentsContext(appId: string): ExperimentsContext | undefined;
+/** One independent evaluator instance for one client/request. @internal */
+export declare function createExperimentsRuntime(context: ExperimentsContext): ExperimentsRuntime;

package/dist/modules/experiments-context.js

@@ -0,0 +1,44 @@
+import { evaluateExperiments } from "./experiments-evaluator.js";
+/** @internal Platform ingress overwrites this header; it is not authentication. */
+export const EXPERIMENTS_CONTEXT_HEADER = "Base44-Experiments-Context";
+/** @internal */
+export function readExperimentsContext(encoded, appId) {
+    if (!encoded || encoded.length > 96 * 1024)
+        return;
+    try {
+        const bytes = Uint8Array.from(atob(encoded.replace(/-/g, "+").replace(/_/g, "/")), (character) => character.charCodeAt(0));
+        return matchingContext(JSON.parse(new TextDecoder().decode(bytes)), appId);
+    }
+    catch (_a) {
+        return;
+    }
+}
+function matchingContext(value, appId) {
+    var _a, _b;
+    return ((_a = value === null || value === void 0 ? void 0 : value.config) === null || _a === void 0 ? void 0 : _a.v) === 1 && value.config.app_id === appId &&
+        typeof ((_b = value.identity) === null || _b === void 0 ? void 0 : _b.visitorId) === "string" && value.identity.visitorId &&
+        (value.identity.userId === null || typeof value.identity.userId === "string")
+        ? value : undefined;
+}
+/** @internal */
+export function getBrowserExperimentsContext(appId) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    return matchingContext(window.__B44_EXPERIMENTS_BOOTSTRAP__, appId);
+}
+/** One independent evaluator instance for one client/request. @internal */
+export function createExperimentsRuntime(context) {
+    const identity = { ...context.identity };
+    const evaluate = () => evaluateExperiments(context.config, identity, context.preview);
+    const runtime = {
+        ...evaluate(),
+        visitorId: identity.visitorId,
+        userId: identity.userId,
+        pendingUser: identity.status === "pending",
+        setUser(userId) {
+            identity.userId = userId;
+            Object.assign(runtime, evaluate(), { userId, pendingUser: false });
+        },
+    };
+    return runtime;
+}

package/dist/modules/experiments-evaluator.d.ts

@@ -0,0 +1,11 @@
+import type { ExperimentAssignment } from "./experiments-runtime.types.js";
+import type { ExperimentsConfig, ExperimentsIdentity } from "./experiments-config.types.js";
+/**
+ * Evaluates flags locally without storage, network, clock, or browser globals.
+ * The same config and identity always produce the same assignments.
+ * This controls presentation, never authorization or access to data.
+ */
+export declare function evaluateExperiments(config: ExperimentsConfig, identity: ExperimentsIdentity, preview?: Readonly<Record<string, boolean>>): {
+    flags: Record<string, boolean>;
+    assignments: ExperimentAssignment[];
+};

package/dist/modules/experiments-evaluator.js

@@ -0,0 +1,45 @@
+function bucket(parts) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(parts.join(":"))) {
+        hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
+    }
+    return hash % 100;
+}
+/**
+ * Evaluates flags locally without storage, network, clock, or browser globals.
+ * The same config and identity always produce the same assignments.
+ * This controls presentation, never authorization or access to data.
+ */
+export function evaluateExperiments(config, identity, preview = {}) {
+    const flags = Object.fromEntries(config.flags.map((flag) => [
+        flag.key,
+        bucket(["rollout", config.app_id, flag.key, identity.visitorId]) < flag.rollout_percentage,
+    ]));
+    const assignments = [];
+    for (const experiment of config.experiments) {
+        if (Object.prototype.hasOwnProperty.call(preview, experiment.flag_key))
+            continue;
+        const key = experiment.assign_by === "user" ? identity.userId : identity.visitorId;
+        if (!key || bucket(["enroll", config.app_id, experiment.id, experiment.run_version, key]) >= experiment.traffic_allocation)
+            continue;
+        const value = bucket(["variant", config.app_id, experiment.id, experiment.run_version, key]);
+        let total = 0;
+        let variant = experiment.variants[experiment.variants.length - 1];
+        for (const candidate of experiment.variants) {
+            total += candidate.weight;
+            if (value < total) {
+                variant = candidate;
+                break;
+            }
+        }
+        flags[experiment.flag_key] = variant.value;
+        assignments.push({
+            experiment_id: experiment.id,
+            flag_key: experiment.flag_key,
+            run_version: experiment.run_version,
+            variant_key: variant.key,
+            preview: false,
+        });
+    }
+    return { flags: { ...flags, ...preview }, assignments };
+}

package/dist/modules/experiments.d.ts

@@ -1,12 +1,16 @@
 import type { AuthState, InternalAuthModule } from "./auth.types.js";
 import type { ExperimentsModule } from "./experiments.types.js";
 import type { createExposureTracker } from "./experiment-exposures.js";
+import type { ExperimentsContext } from "./experiments-config.types.js";
 /** @internal */
-export declare function createExperimentsModule({ getAuth, trackExposure, }: {
+export declare function createExperimentsModule({ getAuth, trackExposure, flushExposures, context, }: {
     getAuth: () => InternalAuthModule;
     trackExposure: ReturnType<typeof createExposureTracker>["track"];
+    flushExposures?: () => Promise<void>;
+    context?: ExperimentsContext;
 }): {
     module: ExperimentsModule;
     onAuthStateChange: (next: AuthState) => void;
+    visitorId: () => string | undefined;
     cleanup(): void;
 };

package/dist/modules/experiments.js

@@ -1,19 +1,28 @@
 import { getExperimentsRuntime, } from "./experiments-runtime.types.js";
+import { createExperimentsRuntime } from "./experiments-context.js";
 const EMPTY = Object.freeze({
     flags: Object.freeze({}),
     isLoading: false,
 });
 /** @internal */
-export function createExperimentsModule({ getAuth, trackExposure, }) {
-    let runtime;
-    let state;
+export function createExperimentsModule({ getAuth, trackExposure, flushExposures = async () => { }, context, }) {
+    var _a;
+    let runtime = context ? createExperimentsRuntime(context) : undefined;
+    let state = context
+        ? context.identity.status === "pending" ? { status: "pending" }
+            : context.identity.userId ? { status: "authenticated", userId: context.identity.userId }
+                : { status: "anonymous" }
+        : undefined;
     let snapshot = EMPTY;
     let active = false;
     let disposed = false;
-    let generation = 0;
-    let pending;
     const listeners = new Set();
     const readyWaiters = new Set();
+    const initial = (_a = context === null || context === void 0 ? void 0 : context.serverSnapshot) !== null && _a !== void 0 ? _a : (context ? {
+        flags: context.identity.status === "pending" ? {} : runtime.flags,
+        isLoading: context.identity.status === "pending",
+    } : EMPTY);
+    const serverSnapshot = Object.freeze({ ...initial, flags: Object.freeze({ ...initial.flags }) });
     function settleReady() {
         if (snapshot.isLoading)
             return;
@@ -53,25 +62,12 @@ export function createExperimentsModule({ getAuth, trackExposure, }) {
         }
         publish();
     }
-    function resolveIdentity() {
-        if (!runtime || pending || disposed)
-            return;
-        state = { status: "pending" };
-        applyIdentity();
-        const currentGeneration = generation;
-        pending = getAuth()
-            .me()
-            .then(() => { }, () => { })
-            .finally(() => {
-            if (currentGeneration === generation)
-                pending = undefined;
-        });
-    }
     function activate() {
         if (disposed)
             return;
         active = true;
-        runtime = getExperimentsRuntime();
+        if (!context)
+            runtime = getExperimentsRuntime();
         if (!runtime) {
             publish();
             return;
@@ -81,23 +77,16 @@ export function createExperimentsModule({ getAuth, trackExposure, }) {
                 ? { status: "pending" }
                 : { status: "anonymous" };
         applyIdentity();
-        if (state.status === "pending")
-            resolveIdentity();
     }
     function onAuthStateChange(next) {
         if (disposed)
             return;
         state = next;
-        if (next.status === "pending" || next.status === "anonymous") {
-            generation++;
-            pending = undefined;
-        }
         if (!active)
             return;
-        runtime = getExperimentsRuntime();
+        if (!context)
+            runtime = getExperimentsRuntime();
         applyIdentity();
-        if (next.status === "pending")
-            resolveIdentity();
     }
     const module = {
         isEnabled(flagKey, fallback = false) {
@@ -113,6 +102,7 @@ export function createExperimentsModule({ getAuth, trackExposure, }) {
             activate();
             return snapshot;
         },
+        getServerSnapshot: () => serverSnapshot,
         subscribe(listener) {
             activate();
             if (!disposed)
@@ -123,24 +113,18 @@ export function createExperimentsModule({ getAuth, trackExposure, }) {
         },
         async ready() {
             activate();
-            if ((state === null || state === void 0 ? void 0 : state.status) === "error") {
-                // Wait for auth.me() to release its shared, failed request before retrying.
-                await pending;
-                if ((state === null || state === void 0 ? void 0 : state.status) === "error")
-                    resolveIdentity();
-            }
             if (snapshot.isLoading)
                 return new Promise((resolve) => readyWaiters.add(resolve));
             return snapshot;
         },
+        flush: flushExposures,
     };
     return {
         module,
         onAuthStateChange,
+        visitorId: () => runtime === null || runtime === void 0 ? void 0 : runtime.visitorId,
         cleanup() {
             disposed = true;
-            generation++;
-            pending = undefined;
             runtime = undefined;
             snapshot = EMPTY;
             settleReady();

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

@@ -6,7 +6,7 @@ export interface ExperimentsSnapshot {
     readonly isLoading: boolean;
 }
 /**
- * Reads feature flags evaluated by the Base44 browser runtime.
+ * Evaluates feature flags locally from platform-provided configuration and identity.
  *
  * - Reads flags and reports experiment exposures when a flag is used.
  * - Synchronizes assignments with this client's SDK login, token changes, and logout.
@@ -14,26 +14,28 @@ export interface ExperimentsSnapshot {
  *
  * Available as `base44.experiments` for anonymous and signed-in app visitors,
  * not in service role mode. Use one client for the app whose runtime is on the page.
- * The platform must inject the Experiments runtime before this module can evaluate
- * flags. Without it, including on servers and Workers, reads return their fallback;
- * this module does not provide server-side evaluation or hydration guarantees.
+ * Browsers read the platform bootstrap. Servers and Workers use the request-scoped
+ * context passed by createClientFromRequest(), or explicit createClient options.
+ * Missing context returns fallbacks. For authenticated first render, the platform's
+ * common auth bootstrap must supply a resolved identity before mounting the app.
  * Goal conversions use the existing {@link AnalyticsModule | analytics module}.
- * Visitor-keyed conversion attribution requires matching runtime and analytics
- * visitor IDs; blocked browser storage is not currently supported for attribution.
+ * Visitor-keyed conversions share the injected runtime's visitor ID. When browser
+ * storage is blocked, the platform must supply a unique per-page ID; attribution
+ * then lasts for that page only, not across reloads or tabs.
  */
 export interface ExperimentsModule {
     /**
-     * Reads a flag and reports a best-effort exposure for its current assignment.
+     * Reads a flag and queues an acknowledged exposure for its current assignment.
      *
-     * The first use resolves identity through {@link AuthModule.me | auth.me()}
-     * when the client has a token. Reads return the fallback while identity is
-     * pending or could not be resolved. Await {@link ExperimentsModule.ready | ready()}
-     * or subscribe to updates before displaying authenticated variants.
+     * Never starts an authentication request. Reads return the fallback while the
+     * app's normal auth initialization is pending or failed. Supply trusted bootstrap
+     * identity or let the app's existing auth.me()/login flow resolve it.
      *
      * 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, and retry only on a later read after failure.
+     * experiment run, variant and identity. Failed sends retry up to three attempts
+     * with the same event ID, timestamp and credentials. Await flush() on servers.
      *
      * @param flagKey - Feature flag key defined in your app.
      * @param fallback - Value for an unavailable flag or unresolved identity. Defaults to `false`.
@@ -48,7 +50,7 @@ export interface ExperimentsModule {
     /**
      * Returns the current flags and identity-loading state without tracking exposures.
      *
-     * Starts lazy identity resolution if needed. The returned object retains its
+     * Observes identity resolution without starting it. The returned object retains its
      * reference until its values change, for use with external-store subscriptions.
      * Use {@link ExperimentsModule.isEnabled | isEnabled()} at the feature boundary
      * to record exposure rather than displaying a variant directly from this snapshot.
@@ -60,6 +62,8 @@ export interface ExperimentsModule {
      * ```
      */
     getSnapshot(): ExperimentsSnapshot;
+    /** Immutable initial platform snapshot for matching server render and hydration. */
+    getServerSnapshot(): ExperimentsSnapshot;
     /**
      * Listens for flag or loading-state changes caused by this client's SDK auth flows.
      *
@@ -78,10 +82,10 @@ export interface ExperimentsModule {
      */
     subscribe(listener: () => void): () => void;
     /**
-     * Waits for the current identity lookup, including a token change during that lookup.
+     * Waits for the app's common auth initialization, including a token change.
      *
-     * Resolves with empty flags after an identity lookup failure; calling again retries
-     * the lookup. Missing runtimes resolve immediately. This does not wait for a future
+     * Resolves with empty flags after an identity lookup failure. Retrying authentication
+     * belongs to the normal auth flow. Missing runtimes resolve immediately. This does not wait for a future
      * runtime injection or for exposure delivery, and never records an exposure itself.
      *
      * @returns A snapshot after the current identity lookup settles.
@@ -92,4 +96,11 @@ 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.
+     */
+    flush(): Promise<void>;
 }

package/dist/utils/fetch-with-auth.js

@@ -29,6 +29,7 @@ export function createFetchWithAuth({ axios, serviceRoleAxios, appId, serverUrl,
             ? header
             : null;
     };
+    const contextAuthorization = bearer(axios);
     return async function fetchWithAuth(path, init = {}) {
         assertOwnOriginPath(path);
         const { fetch: transport = fetch, ...requestInit } = init;
@@ -49,6 +50,11 @@ export function createFetchWithAuth({ axios, serviceRoleAxios, appId, serverUrl,
         inherit("Base44-Functions-Version", functionsVersion);
         inherit("Base44-State", inherited.get("Base44-State"));
         inherit("X-Data-Env", inherited.get("X-Data-Env"));
+        inherit("Base44-Visitor-Id", inherited.get("Base44-Visitor-Id"));
+        inherit("Base44-Experiment-Preview", inherited.get("Base44-Experiment-Preview"));
+        if (headers.get("Authorization") === contextAuthorization) {
+            inherit("Base44-Experiments-Context", inherited.get("Base44-Experiments-Context"));
+        }
         // The path is passed through untouched: resolving it here would need a
         // document, and a root-relative path is already what a runtime that
         // dispatches in-process (Nitro's `fetch`) expects. `host` is deliberately

package/package.json

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