@base44-preview/sdk 0.8.48-pr.280.cc2ee4a → 0.8.48-pr.280.cd0dea6

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,9 +14,10 @@ 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 conversions share the injected runtime's visitor ID. When browser
  * storage is blocked, the platform must supply a unique per-page ID; attribution
@@ -24,17 +25,22 @@ export interface ExperimentsSnapshot {
  */
 export interface ExperimentsModule {
     /**
-     * Reads a flag and reports a best-effort exposure for its current assignment.
+     * Reads a flag and queues a best-effort 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. 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`.
@@ -49,7 +55,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.
@@ -61,6 +67,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.
      *
@@ -79,10 +87,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.
@@ -93,4 +101,24 @@ export interface ExperimentsModule {
      * ```
      */
     ready(): Promise<ExperimentsSnapshot>;
+    /**
+     * 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/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.cc2ee4a",
+  "version": "0.8.48-pr.280.cd0dea6",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",