@shipeasy/sdk 6.2.0 → 7.0.0

package/dist/openfeature-web/index.d.mts

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/web-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 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. */
@@ -23,25 +25,6 @@ interface User {
     user_id?: string;
     [attr: string]: unknown;
 }
-interface ExperimentResult<P> {
-    inExperiment: boolean;
-    group: string;
-    params: P;
-}
-/** Options object form of `getExperiment` — the legacy `decode`/`variants`
- *  positional args plus per-call exposure control. */
-interface GetExperimentOptions<P> {
-    /** Decode the raw stored params into the typed shape callers want. */
-    decode?: (raw: unknown) => P;
-    /** Variant-specific param overrides merged on top of group params. */
-    variants?: Record<string, Partial<P>>;
-    /**
-     * Override automatic exposure logging for this read. Defaults to the client's
-     * setting (`disableAutoExposure` flips it). `false` reads the variant without
-     * logging an exposure — pair with `logExposure(name)` at render time.
-     */
-    logExposure?: boolean;
-}
 /**
  * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
  * Computed at the client boundary:
@@ -73,11 +56,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-
@@ -91,6 +82,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;
@@ -102,6 +110,33 @@ interface AutoCollectGroups {
     engagement: boolean;
 }
 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;
@@ -131,6 +166,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
@@ -154,6 +205,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
@@ -174,6 +233,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -188,6 +248,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()
@@ -241,16 +308,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.
+     * 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).
      */
-    logExposure(name: string): void;
+    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

package/dist/openfeature-web/index.d.ts

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/web-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 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. */
@@ -23,25 +25,6 @@ interface User {
     user_id?: string;
     [attr: string]: unknown;
 }
-interface ExperimentResult<P> {
-    inExperiment: boolean;
-    group: string;
-    params: P;
-}
-/** Options object form of `getExperiment` — the legacy `decode`/`variants`
- *  positional args plus per-call exposure control. */
-interface GetExperimentOptions<P> {
-    /** Decode the raw stored params into the typed shape callers want. */
-    decode?: (raw: unknown) => P;
-    /** Variant-specific param overrides merged on top of group params. */
-    variants?: Record<string, Partial<P>>;
-    /**
-     * Override automatic exposure logging for this read. Defaults to the client's
-     * setting (`disableAutoExposure` flips it). `false` reads the variant without
-     * logging an exposure — pair with `logExposure(name)` at render time.
-     */
-    logExposure?: boolean;
-}
 /**
  * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
  * Computed at the client boundary:
@@ -73,11 +56,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-
@@ -91,6 +82,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;
@@ -102,6 +110,33 @@ interface AutoCollectGroups {
     engagement: boolean;
 }
 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;
@@ -131,6 +166,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
@@ -154,6 +205,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
@@ -174,6 +233,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -188,6 +248,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()
@@ -241,16 +308,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.
+     * 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).
      */
-    logExposure(name: string): void;
+    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