@shipeasy/sdk 6.2.0 → 7.0.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

@@ -1,3 +1,7 @@
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** All accepted {@link LogLevel} values, in increasing verbosity. */
+declare const LOG_LEVELS: readonly LogLevel[];
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -165,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-
@@ -183,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;
@@ -203,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;
@@ -232,6 +288,22 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — returning a safe default instead of
+     * throwing — and surfaces the swallowed error through this level. Ordering:
+     * `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
@@ -255,6 +327,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
@@ -275,6 +355,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -289,6 +370,13 @@ declare class Engine {
     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()
@@ -342,16 +430,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
@@ -468,12 +561,26 @@ interface ShipeasyClientConfig {
     autoCollect?: boolean | (Partial<AutoCollectGroups> & {
         always?: boolean;
     });
+    /**
+     * How chatty the SDK is on `console` when it swallows an internal error.
+     * `silent` < `error` < `warn` < `info` < `debug`; defaults to `"warn"`. Every
+     * runtime read/track/see call fails silently to a safe default and reports the
+     * cause at this level. See {@link EngineOptions.logLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Disable per-evaluation usage telemetry. Telemetry is ON by default — 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.
      */
     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
@@ -493,6 +600,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.
@@ -552,10 +665,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
@@ -651,7 +773,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;
     /**
@@ -661,13 +793,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 {
     /**
@@ -760,4 +885,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, type LabelAttrs, 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

@@ -1,3 +1,7 @@
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** All accepted {@link LogLevel} values, in increasing verbosity. */
+declare const LOG_LEVELS: readonly LogLevel[];
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -165,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-
@@ -183,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;
@@ -203,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;
@@ -232,6 +288,22 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — returning a safe default instead of
+     * throwing — and surfaces the swallowed error through this level. Ordering:
+     * `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
@@ -255,6 +327,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
@@ -275,6 +355,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -289,6 +370,13 @@ declare class Engine {
     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()
@@ -342,16 +430,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
@@ -468,12 +561,26 @@ interface ShipeasyClientConfig {
     autoCollect?: boolean | (Partial<AutoCollectGroups> & {
         always?: boolean;
     });
+    /**
+     * How chatty the SDK is on `console` when it swallows an internal error.
+     * `silent` < `error` < `warn` < `info` < `debug`; defaults to `"warn"`. Every
+     * runtime read/track/see call fails silently to a safe default and reports the
+     * cause at this level. See {@link EngineOptions.logLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Disable per-evaluation usage telemetry. Telemetry is ON by default — 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.
      */
     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
@@ -493,6 +600,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.
@@ -552,10 +665,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
@@ -651,7 +773,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;
     /**
@@ -661,13 +793,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 {
     /**
@@ -760,4 +885,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, type LabelAttrs, 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 };