@shipeasy/sdk 6.3.1 → 7.1.0

package/dist/openfeature-server/index.mjs

@@ -4,43 +4,12 @@ import { ErrorCode } from "@openfeature/server-sdk";
 // src/server/index.ts
 import { AsyncLocalStorage } from "async_hooks";
 
-// src/logger.ts
-var RANK = {
-  silent: 0,
-  error: 1,
-  warn: 2,
-  info: 3,
-  debug: 4
-};
-var currentLevel = "warn";
-function write(method, args) {
-  try {
-    const c = globalThis.console;
-    if (!c) return;
-    const fn = c[method] ?? c.log;
-    if (typeof fn === "function") fn.call(c, ...args);
-  } catch {
-  }
-}
-var logger = {
-  error(...args) {
-    if (RANK[currentLevel] >= RANK.error) write("error", args);
-  },
-  warn(...args) {
-    if (RANK[currentLevel] >= RANK.warn) write("warn", args);
-  },
-  info(...args) {
-    if (RANK[currentLevel] >= RANK.info) write("info", args);
-  },
-  debug(...args) {
-    if (RANK[currentLevel] >= RANK.debug) write("debug", args);
-  }
-};
-
 // src/see/core.ts
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_DEDUP_WINDOW_MS = 3e4;
+var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
   return {
     to(outcome) {
@@ -151,6 +120,69 @@ function startControlFlowChain(err) {
     }
   };
 }
+function topStackLine(stack) {
+  if (!stack) return "";
+  for (const line of stack.split("\n")) {
+    if (/^\s*at |@|:\d+:\d+/.test(line)) return line.trim().slice(0, 200);
+  }
+  return "";
+}
+var SeeLimiter = class {
+  constructor(maxPerSession = SEE_MAX_PER_SESSION, dedupWindowMs = SEE_DEDUP_WINDOW_MS) {
+    this.maxPerSession = maxPerSession;
+    this.dedupWindowMs = dedupWindowMs;
+  }
+  maxPerSession;
+  dedupWindowMs;
+  lastSent = /* @__PURE__ */ new Map();
+  sent = 0;
+  shouldSend(ev) {
+    if (this.sent >= this.maxPerSession) return false;
+    const key = `${ev.kind}|${ev.error_type}|${ev.message.slice(0, 200)}|${topStackLine(ev.stack)}`;
+    const now = Date.now();
+    const prev = this.lastSent.get(key);
+    if (prev !== void 0 && now - prev < this.dedupWindowMs) return false;
+    this.lastSent.set(key, now);
+    this.sent += 1;
+    return true;
+  }
+};
+
+// src/internal-report.ts
+var limiter = new SeeLimiter();
+
+// src/logger.ts
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var currentLevel = "warn";
+function write(method, args) {
+  try {
+    const c = globalThis.console;
+    if (!c) return;
+    const fn = c[method] ?? c.log;
+    if (typeof fn === "function") fn.call(c, ...args);
+  } catch {
+  }
+}
+var logger = {
+  error(...args) {
+    if (RANK[currentLevel] >= RANK.error) write("error", args);
+  },
+  warn(...args) {
+    if (RANK[currentLevel] >= RANK.warn) write("warn", args);
+  },
+  info(...args) {
+    if (RANK[currentLevel] >= RANK.info) write("info", args);
+  },
+  debug(...args) {
+    if (RANK[currentLevel] >= RANK.debug) write("debug", args);
+  }
+};
 
 // src/server/index.ts
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");

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

@@ -25,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:
@@ -75,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-
@@ -93,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;
@@ -104,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;
@@ -125,10 +158,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}. */
@@ -141,6 +190,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
@@ -164,6 +221,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
@@ -184,6 +249,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -193,11 +259,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()
@@ -251,16 +326,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

@@ -25,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:
@@ -75,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-
@@ -93,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;
@@ -104,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;
@@ -125,10 +158,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}. */
@@ -141,6 +190,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
@@ -164,6 +221,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
@@ -184,6 +249,7 @@ declare class Engine {
     private readonly env;
     private evalResult;
     private anonId;
+    private anonReady;
     private userId;
     private buffer;
     private telemetry;
@@ -193,11 +259,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()
@@ -251,16 +326,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