@shipeasy/sdk 6.3.1 → 7.1.0

package/README.md

@@ -83,7 +83,7 @@ Copy-paste snippets live under [`docs/snippets/`](https://github.com/shipeasy-ai
 
 ## Testing
 
-For unit tests, swap the live `configure()` for **`configureForTesting()`** — a drop-in sibling with **no network, ever** (no SDK key required). It replaces the active configuration with a network-free engine, seeds the values your code should see, and is read through the ordinary `new Client(user)`. In this mode the rules never fetch, `track()` / `logExposure()` are no-ops, and telemetry is off — your tests never touch the network.
+For unit tests, swap the live `configure()` for **`configureForTesting()`** — a drop-in sibling with **no network, ever** (no SDK key required). It replaces the active configuration with a network-free engine, seeds the values your code should see, and is read through the ordinary `new Client(user)`. In this mode the rules never fetch, `track()` is a no-op, `assign()` logs no exposure, and telemetry is off — your tests never touch the network.
 
 ```ts
 import { configureForTesting, Client, clearOverrides } from "@shipeasy/sdk/server"; // or /client
@@ -92,14 +92,11 @@ import { configureForTesting, Client, clearOverrides } from "@shipeasy/sdk/serve
 configureForTesting({
   flags: { new_checkout: true },
   configs: { upload_limits: { max_uploads: 50 } },
-  experiments: { hero_cta: ["treatment", { primary_label: "Buy now" }] },
 });
 
 const flags = new Client({ user_id: "u_1" }); // construct once per callsite
 flags.getFlag("new_checkout");                 // true
 flags.getConfig("upload_limits");              // { max_uploads: 50 }
-flags.getExperiment("hero_cta", { primary_label: "Sign up" });
-// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
 
 clearOverrides(); // reset every seeded override back to the empty-blob default
 ```

package/dist/client/index.d.mts

@@ -169,11 +169,19 @@ interface EvalExpResult {
     inExperiment: boolean;
     group: string;
     params: Record<string, unknown>;
+    /** The universe this experiment belongs to — lets `universe(name).assign()`
+     *  find the enrolled experiment within a universe. */
+    universe?: string;
 }
 interface EvalResponse {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
+    /** Per-universe param defaults (name → default map) so `universe(name).get()`
+     *  resolves to the universe default even when the unit is not enrolled. */
+    universes?: Record<string, {
+        defaults: Record<string, unknown>;
+    }>;
     /**
      * Killswitch state, flattened by the server. A boolean means the killswitch
      * is whole-killed; an object means it's not whole-killed and carries per-
@@ -187,6 +195,23 @@ interface EvalResponse {
      */
     sticky?: Record<string, StickyCookieEntry>;
 }
+/**
+ * The result of `universe(name).assign()` — the visitor's standing in a universe.
+ * A universe is a mutual-exclusion pool, so the visitor lands in **at most one**
+ * experiment. Never throws: an un-enrolled visitor still resolves `get()` to the
+ * universe defaults (or your fallback). `assign()` auto-logs one exposure when
+ * enrolled (subject to `disableAutoExposure`).
+ */
+interface Assignment {
+    /** The experiment the visitor landed in, or `null` when not enrolled. */
+    readonly name: string | null;
+    /** The assigned variant/group name, or `null` when not enrolled. */
+    readonly group: string | null;
+    /** True iff the visitor is enrolled in an experiment in this universe. */
+    readonly enrolled: boolean;
+    /** Read a resolved param: variant override ?? universe default ?? `fallback`. */
+    get<T = unknown>(field: string, fallback?: T): T | undefined;
+}
 /** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
 interface StickyCookieEntry {
     g: string;
@@ -207,6 +232,33 @@ declare function sameOrigin(rawUrl: string): boolean;
  */
 declare function injectCorrelationHeader(args: Parameters<typeof fetch>, corr: string): Parameters<typeof fetch>;
 type EngineEnv = "dev" | "staging" | "prod";
+/**
+ * A pluggable persistence backend for the anonymous id. Primarily for non-DOM
+ * runtimes (React Native / Expo) where there is no cookie or `localStorage`, so
+ * the anon id would otherwise regenerate every app launch and re-bucket the
+ * visitor. Point it at `@react-native-async-storage/async-storage` (or any
+ * store) and the SDK hydrates a stable id before the first `/sdk/evaluate`:
+ *
+ * ```ts
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ * configure({
+ *   clientKey: "...",
+ *   anonymousStore: {
+ *     get: (k) => AsyncStorage.getItem(k),
+ *     set: (k, v) => AsyncStorage.setItem(k, v),
+ *     remove: (k) => AsyncStorage.removeItem(k),
+ *   },
+ * });
+ * ```
+ *
+ * Methods may be sync or async — the SDK awaits either. Any thrown error is
+ * swallowed (the in-memory id is used as a fallback).
+ */
+interface AnonymousStore {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
 interface EngineOptions {
     sdkKey: string;
     baseUrl?: string;
@@ -228,10 +280,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — each getFlag/getConfig/
      * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
-     * usage is counted by Cloudflare's native per-path analytics. Pass `true` to
-     * disable entirely.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -244,6 +312,14 @@ interface EngineOptions {
      * `silent` < `error` < `warn` < `info` < `debug`. Defaults to `"warn"`.
      */
     logLevel?: LogLevel;
+    /**
+     * Opt out of SDK-internal error self-monitoring. When one of the SDK's own
+     * last-resort guards catches an internal failure (an "on our end" bug), the
+     * SDK reports it to Shipeasy's own project so we can track SDK bugs across
+     * apps — never to your project. ON by default; forced off in test mode. Pass
+     * `true` to disable.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Suppress automatic exposure logging in `getExperiment` (Statsig's
      * `disableExposureLogging`). Default false — reading an enrolled variant
@@ -267,6 +343,14 @@ interface EngineOptions {
      * lever. Pass `false` to opt out (pure deterministic eval).
      */
     stickyBucketing?: boolean;
+    /**
+     * Pluggable persistence for the anonymous id (React Native / Expo, or any
+     * runtime without a cookie / `localStorage`). When set, the SDK hydrates the
+     * stored id before the first `/sdk/evaluate` so bucketing stays stable across
+     * app launches; on a fresh device it persists the freshly-minted id. See
+     * {@link AnonymousStore}.
+     */
+    anonymousStore?: AnonymousStore;
     /**
      * Test mode — no network at all. identify()/init are no-ops (never call
      * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
@@ -287,6 +371,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -296,11 +381,20 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: EngineOptions);
+    /**
+     * Consult the caller-supplied {@link AnonymousStore}: adopt a persisted id so
+     * the visitor buckets identically across app launches, or persist the id just
+     * minted by getOrCreateAnonId() on a fresh device. Best-effort — any store
+     * failure leaves the in-memory id in place.
+     */
+    private hydrateAnonFromStore;
     /**
      * Build a no-network, immediately-usable browser client for tests
      * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
@@ -354,16 +448,21 @@ declare class Engine {
     getFlag(name: string, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, opts: GetExperimentOptions<P>): ExperimentResult<P>;
     /**
-     * Manually log an exposure for an enrolled experiment (Statsig's
-     * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
-     * the experiment, pushes the session-deduped exposure. Pair this with the
-     * render of the treatment when reading with `{ logExposure: false }` (or
-     * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
-     */
-    logExposure(name: string): void;
+     * Assign the visitor within a universe: `universe("checkout").assign()`. A
+     * universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+     * and auto-logs one exposure when enrolled (unless `disableAutoExposure` or
+     * `assign({ logExposure: false })`). An un-enrolled visitor still resolves
+     * `get()` to the universe defaults. This is the sole experiment read path —
+     * there is no `getExperiment` (ask a universe, not an experiment).
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
+    private assignUniverse;
     /**
      * Subscribe to state changes — fires after identify() completes and on
      * `se:override:change` events from the devtools overlay. Returns an
@@ -436,6 +535,12 @@ interface ShipeasyClientConfig {
     clientKey: string;
     /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
     baseUrl?: string;
+    /**
+     * Which published env to read values from — also the fallback signal for the
+     * environment-derived egress defaults (see {@link isNetworkEnabled}) when the
+     * browser exposes no native `NODE_ENV`. Defaults to `"prod"`.
+     */
+    env?: EngineEnv;
     /** Override the admin URL for the devtools overlay (dev use). */
     adminUrl?: string;
     /**
@@ -488,11 +593,27 @@ interface ShipeasyClientConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * Master network switch — `false` puts the browser SDK fully offline (no
+     * /sdk/evaluate, no /collect, no telemetry, no error self-monitoring).
+     * Defaults to environment-derived: ON in production, OFF everywhere else
+     * (in the browser, "production" comes from `env`, default `"prod"`). See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. Every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
-     * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
+     * counted by Cloudflare's native per-path analytics. Pass `true` to force off.
      */
     disableTelemetry?: boolean;
+    /**
+     * Opt out of SDK-internal error self-monitoring. Internal SDK failures ("on
+     * our end") are reported to Shipeasy's own project (never yours) so we can
+     * track SDK bugs. ON by default. See
+     * {@link EngineOptions.disableInternalErrorReporting}.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Suppress automatic exposure logging in `flags.getExperiment` (Statsig's
      * `disableExposureLogging`). Default false. When true, call
@@ -512,6 +633,12 @@ interface ShipeasyClientConfig {
      * opt out. See {@link EngineOptions.stickyBucketing}.
      */
     stickyBucketing?: boolean;
+    /**
+     * Pluggable anon-id persistence for non-DOM runtimes (React Native / Expo).
+     * Back it with AsyncStorage so the anonymous id — and thus bucketing — stays
+     * stable across app launches. See {@link AnonymousStore}.
+     */
+    anonymousStore?: AnonymousStore;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.
@@ -571,10 +698,19 @@ declare const flags: {
     /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
     getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decodeOrOpts?: ((raw: unknown) => P) | GetExperimentOptions<P>, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
-    /** Manually log an exposure for an enrolled experiment. See
-     *  {@link Engine.logExposure}. No-op before configure(). */
-    logExposure(name: string): void;
+    /**
+     * Assign the visitor within a universe: `flags.universe("checkout").assign()`.
+     * A universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+     * and auto-logs one exposure when enrolled. Before configure() (or on error)
+     * returns a safe not-enrolled handle. Replaces the removed `getExperiment` —
+     * read experiments by universe, never by name.
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
     track(eventName: string, props?: Record<string, unknown>): void;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -670,7 +806,17 @@ declare class Client<U = unknown> {
     getFlagDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Assign the visitor within a universe: `client.universe("checkout").assign()`.
+     * A universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * returns an {@link Assignment} (`.group` / `.get(field, fallback)`) and
+     * auto-logs one exposure when enrolled. Replaces the removed `getExperiment`.
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
     /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
     getKillswitch(name: string, switchKey?: string): boolean;
     /**
@@ -680,13 +826,6 @@ declare class Client<U = unknown> {
      * test mode.
      */
     track(eventName: string, props?: Record<string, unknown>): void;
-    /**
-     * Log an exposure for `name` at the treatment's render for the bound user.
-     * Delegates to {@link Engine.logExposure} (no-op when the visitor isn't
-     * enrolled). Pair with `getExperiment(name, …, { logExposure: false })` /
-     * `disableAutoExposure` to log exposure exactly when you render.
-     */
-    logExposure(name: string): void;
 }
 interface SeeApi {
     /**
@@ -779,4 +918,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AnonymousStore, type Assignment, type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -169,11 +169,19 @@ interface EvalExpResult {
     inExperiment: boolean;
     group: string;
     params: Record<string, unknown>;
+    /** The universe this experiment belongs to — lets `universe(name).assign()`
+     *  find the enrolled experiment within a universe. */
+    universe?: string;
 }
 interface EvalResponse {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
     experiments: Record<string, EvalExpResult>;
+    /** Per-universe param defaults (name → default map) so `universe(name).get()`
+     *  resolves to the universe default even when the unit is not enrolled. */
+    universes?: Record<string, {
+        defaults: Record<string, unknown>;
+    }>;
     /**
      * Killswitch state, flattened by the server. A boolean means the killswitch
      * is whole-killed; an object means it's not whole-killed and carries per-
@@ -187,6 +195,23 @@ interface EvalResponse {
      */
     sticky?: Record<string, StickyCookieEntry>;
 }
+/**
+ * The result of `universe(name).assign()` — the visitor's standing in a universe.
+ * A universe is a mutual-exclusion pool, so the visitor lands in **at most one**
+ * experiment. Never throws: an un-enrolled visitor still resolves `get()` to the
+ * universe defaults (or your fallback). `assign()` auto-logs one exposure when
+ * enrolled (subject to `disableAutoExposure`).
+ */
+interface Assignment {
+    /** The experiment the visitor landed in, or `null` when not enrolled. */
+    readonly name: string | null;
+    /** The assigned variant/group name, or `null` when not enrolled. */
+    readonly group: string | null;
+    /** True iff the visitor is enrolled in an experiment in this universe. */
+    readonly enrolled: boolean;
+    /** Read a resolved param: variant override ?? universe default ?? `fallback`. */
+    get<T = unknown>(field: string, fallback?: T): T | undefined;
+}
 /** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
 interface StickyCookieEntry {
     g: string;
@@ -207,6 +232,33 @@ declare function sameOrigin(rawUrl: string): boolean;
  */
 declare function injectCorrelationHeader(args: Parameters<typeof fetch>, corr: string): Parameters<typeof fetch>;
 type EngineEnv = "dev" | "staging" | "prod";
+/**
+ * A pluggable persistence backend for the anonymous id. Primarily for non-DOM
+ * runtimes (React Native / Expo) where there is no cookie or `localStorage`, so
+ * the anon id would otherwise regenerate every app launch and re-bucket the
+ * visitor. Point it at `@react-native-async-storage/async-storage` (or any
+ * store) and the SDK hydrates a stable id before the first `/sdk/evaluate`:
+ *
+ * ```ts
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ * configure({
+ *   clientKey: "...",
+ *   anonymousStore: {
+ *     get: (k) => AsyncStorage.getItem(k),
+ *     set: (k, v) => AsyncStorage.setItem(k, v),
+ *     remove: (k) => AsyncStorage.removeItem(k),
+ *   },
+ * });
+ * ```
+ *
+ * Methods may be sync or async — the SDK awaits either. Any thrown error is
+ * swallowed (the in-memory id is used as a fallback).
+ */
+interface AnonymousStore {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
 interface EngineOptions {
     sdkKey: string;
     baseUrl?: string;
@@ -228,10 +280,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — each getFlag/getConfig/
      * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
-     * usage is counted by Cloudflare's native per-path analytics. Pass `true` to
-     * disable entirely.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -244,6 +312,14 @@ interface EngineOptions {
      * `silent` < `error` < `warn` < `info` < `debug`. Defaults to `"warn"`.
      */
     logLevel?: LogLevel;
+    /**
+     * Opt out of SDK-internal error self-monitoring. When one of the SDK's own
+     * last-resort guards catches an internal failure (an "on our end" bug), the
+     * SDK reports it to Shipeasy's own project so we can track SDK bugs across
+     * apps — never to your project. ON by default; forced off in test mode. Pass
+     * `true` to disable.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Suppress automatic exposure logging in `getExperiment` (Statsig's
      * `disableExposureLogging`). Default false — reading an enrolled variant
@@ -267,6 +343,14 @@ interface EngineOptions {
      * lever. Pass `false` to opt out (pure deterministic eval).
      */
     stickyBucketing?: boolean;
+    /**
+     * Pluggable persistence for the anonymous id (React Native / Expo, or any
+     * runtime without a cookie / `localStorage`). When set, the SDK hydrates the
+     * stored id before the first `/sdk/evaluate` so bucketing stays stable across
+     * app launches; on a fresh device it persists the freshly-minted id. See
+     * {@link AnonymousStore}.
+     */
+    anonymousStore?: AnonymousStore;
     /**
      * Test mode — no network at all. identify()/init are no-ops (never call
      * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
@@ -287,6 +371,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -296,11 +381,20 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: EngineOptions);
+    /**
+     * Consult the caller-supplied {@link AnonymousStore}: adopt a persisted id so
+     * the visitor buckets identically across app launches, or persist the id just
+     * minted by getOrCreateAnonId() on a fresh device. Best-effort — any store
+     * failure leaves the in-memory id in place.
+     */
+    private hydrateAnonFromStore;
     /**
      * Build a no-network, immediately-usable browser client for tests
      * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
@@ -354,16 +448,21 @@ declare class Engine {
     getFlag(name: string, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, opts: GetExperimentOptions<P>): ExperimentResult<P>;
     /**
-     * Manually log an exposure for an enrolled experiment (Statsig's
-     * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
-     * the experiment, pushes the session-deduped exposure. Pair this with the
-     * render of the treatment when reading with `{ logExposure: false }` (or
-     * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
-     */
-    logExposure(name: string): void;
+     * Assign the visitor within a universe: `universe("checkout").assign()`. A
+     * universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+     * and auto-logs one exposure when enrolled (unless `disableAutoExposure` or
+     * `assign({ logExposure: false })`). An un-enrolled visitor still resolves
+     * `get()` to the universe defaults. This is the sole experiment read path —
+     * there is no `getExperiment` (ask a universe, not an experiment).
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
+    private assignUniverse;
     /**
      * Subscribe to state changes — fires after identify() completes and on
      * `se:override:change` events from the devtools overlay. Returns an
@@ -436,6 +535,12 @@ interface ShipeasyClientConfig {
     clientKey: string;
     /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
     baseUrl?: string;
+    /**
+     * Which published env to read values from — also the fallback signal for the
+     * environment-derived egress defaults (see {@link isNetworkEnabled}) when the
+     * browser exposes no native `NODE_ENV`. Defaults to `"prod"`.
+     */
+    env?: EngineEnv;
     /** Override the admin URL for the devtools overlay (dev use). */
     adminUrl?: string;
     /**
@@ -488,11 +593,27 @@ interface ShipeasyClientConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * Master network switch — `false` puts the browser SDK fully offline (no
+     * /sdk/evaluate, no /collect, no telemetry, no error self-monitoring).
+     * Defaults to environment-derived: ON in production, OFF everywhere else
+     * (in the browser, "production" comes from `env`, default `"prod"`). See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. Every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
-     * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
+     * counted by Cloudflare's native per-path analytics. Pass `true` to force off.
      */
     disableTelemetry?: boolean;
+    /**
+     * Opt out of SDK-internal error self-monitoring. Internal SDK failures ("on
+     * our end") are reported to Shipeasy's own project (never yours) so we can
+     * track SDK bugs. ON by default. See
+     * {@link EngineOptions.disableInternalErrorReporting}.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Suppress automatic exposure logging in `flags.getExperiment` (Statsig's
      * `disableExposureLogging`). Default false. When true, call
@@ -512,6 +633,12 @@ interface ShipeasyClientConfig {
      * opt out. See {@link EngineOptions.stickyBucketing}.
      */
     stickyBucketing?: boolean;
+    /**
+     * Pluggable anon-id persistence for non-DOM runtimes (React Native / Expo).
+     * Back it with AsyncStorage so the anonymous id — and thus bucketing — stays
+     * stable across app launches. See {@link AnonymousStore}.
+     */
+    anonymousStore?: AnonymousStore;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.
@@ -571,10 +698,19 @@ declare const flags: {
     /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
     getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decodeOrOpts?: ((raw: unknown) => P) | GetExperimentOptions<P>, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
-    /** Manually log an exposure for an enrolled experiment. See
-     *  {@link Engine.logExposure}. No-op before configure(). */
-    logExposure(name: string): void;
+    /**
+     * Assign the visitor within a universe: `flags.universe("checkout").assign()`.
+     * A universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+     * and auto-logs one exposure when enrolled. Before configure() (or on error)
+     * returns a safe not-enrolled handle. Replaces the removed `getExperiment` —
+     * read experiments by universe, never by name.
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
     track(eventName: string, props?: Record<string, unknown>): void;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -670,7 +806,17 @@ declare class Client<U = unknown> {
     getFlagDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Assign the visitor within a universe: `client.universe("checkout").assign()`.
+     * A universe is a mutual-exclusion pool, so the visitor lands in ≤1 experiment;
+     * returns an {@link Assignment} (`.group` / `.get(field, fallback)`) and
+     * auto-logs one exposure when enrolled. Replaces the removed `getExperiment`.
+     */
+    universe(name: string): {
+        assign(opts?: {
+            logExposure?: boolean;
+        }): Assignment;
+    };
     /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
     getKillswitch(name: string, switchKey?: string): boolean;
     /**
@@ -680,13 +826,6 @@ declare class Client<U = unknown> {
      * test mode.
      */
     track(eventName: string, props?: Record<string, unknown>): void;
-    /**
-     * Log an exposure for `name` at the treatment's render for the bound user.
-     * Delegates to {@link Engine.logExposure} (no-op when the visitor isn't
-     * enrolled). Pair with `getExperiment(name, …, { logExposure: false })` /
-     * `disableAutoExposure` to log exposure exactly when you render.
-     */
-    logExposure(name: string): void;
 }
 interface SeeApi {
     /**
@@ -779,4 +918,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AnonymousStore, type Assignment, type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };