@shipeasy/sdk 6.2.0 → 7.0.0

package/dist/client/index.js

@@ -27,6 +27,7 @@ __export(client_exports, {
   LABEL_MARKER_RE: () => LABEL_MARKER_RE,
   LABEL_MARKER_SEP: () => LABEL_MARKER_SEP,
   LABEL_MARKER_START: () => LABEL_MARKER_START,
+  LOG_LEVELS: () => LOG_LEVELS,
   _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyForTests: () => _resetShipeasyForTests,
   attachDevtools: () => attachDevtools,
@@ -226,7 +227,7 @@ function captureCallsiteStack() {
   const kept = lines.slice(1).filter((l) => !/@shipeasy[\\/]sdk|see[\\/]core|captureCallsiteStack|\bsee\b\s*\(/.test(l));
   return kept.length ? kept.join("\n") : void 0;
 }
-function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlationId) {
+function buildSeeEvent(problem, consequence, extras, ctx2, kindOverride, correlationId) {
   let errorType;
   let message;
   let stack;
@@ -254,8 +255,8 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
     message: truncate(message, SEE_MAX_MESSAGE),
     subject: consequence.subject,
     outcome: consequence.outcome,
-    side: ctx.side,
-    sdk_version: ctx.sdkVersion,
+    side: ctx2.side,
+    sdk_version: ctx2.sdkVersion,
     ts: Date.now()
   };
   if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
@@ -264,10 +265,10 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   if (causedBy) ev.caused_by = causedBy;
   const cleanExtras = sanitizeExtras(extras);
   if (cleanExtras) ev.extras = cleanExtras;
-  if (ctx.url) ev.url = truncate(ctx.url, SEE_MAX_SUBJECT);
-  if (ctx.userId) ev.user_id = ctx.userId;
-  if (ctx.anonId) ev.anonymous_id = ctx.anonId;
-  if (ctx.env) ev.env = ctx.env;
+  if (ctx2.url) ev.url = truncate(ctx2.url, SEE_MAX_SUBJECT);
+  if (ctx2.userId) ev.user_id = ctx2.userId;
+  if (ctx2.anonId) ev.anonymous_id = ctx2.anonId;
+  if (ctx2.env) ev.env = ctx2.env;
   markReported(problem, ev);
   return ev;
 }
@@ -360,6 +361,98 @@ var SeeLimiter = class {
   }
 };
 
+// src/internal-report.ts
+var INGEST_URL = "https://api.shipeasy.ai/collect";
+var PLACEHOLDER_KEY = "sdk_client_REPLACE_WITH_SHIPEASY_INTERNAL_ERROR_KEY";
+var INGEST_KEY = "sdk_client_00bd4608a03e4084922978f9522614d5";
+function keyConfigured() {
+  return !!INGEST_KEY && INGEST_KEY !== PLACEHOLDER_KEY;
+}
+var OUTCOME = "returned a safe default";
+var SDK_ID = "ts";
+var ctx = null;
+var limiter = new SeeLimiter();
+function setInternalReportContext(c) {
+  ctx = { side: c.side, sdkVersion: c.sdkVersion, enabled: c.enabled !== false };
+}
+function reportInternalError(label, err) {
+  try {
+    if (!ctx || !ctx.enabled || !keyConfigured()) return;
+    const ev = buildSeeEvent(
+      err,
+      causesThe(label).to(OUTCOME),
+      { sdk: SDK_ID },
+      { side: ctx.side, sdkVersion: ctx.sdkVersion },
+      "caught"
+    );
+    if (!limiter.shouldSend(ev)) return;
+    send2(INGEST_URL, INGEST_KEY, JSON.stringify({ events: [ev] }));
+  } catch {
+  }
+}
+function send2(url, key, body) {
+  try {
+    const f = globalThis.fetch;
+    if (typeof f !== "function") return;
+    void f(url, {
+      method: "POST",
+      headers: { "X-SDK-Key": key, "Content-Type": "text/plain" },
+      body,
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+
+// src/logger.ts
+var LOG_LEVELS = ["silent", "error", "warn", "info", "debug"];
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var currentLevel = "warn";
+function setLogLevel(level) {
+  if (typeof level === "string" && Object.prototype.hasOwnProperty.call(RANK, level)) {
+    currentLevel = level;
+  }
+}
+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);
+  }
+};
+function safeRun(label, fallback, fn) {
+  try {
+    return fn();
+  } catch (err) {
+    logger.error(`[shipeasy] ${label} failed \u2014 returning safe default:`, String(err));
+    reportInternalError(label, err);
+    return fallback;
+  }
+}
+
 // src/client/index.ts
 var version = "4.0.0";
 var FLAG_REASONS = [
@@ -370,6 +463,40 @@ var FLAG_REASONS = [
   "RULE_MATCH",
   "DEFAULT"
 ];
+var AssignmentImpl = class {
+  constructor(name, group, params) {
+    this.name = name;
+    this.group = group;
+    this.params = params;
+  }
+  name;
+  group;
+  params;
+  get enrolled() {
+    return this.group !== null;
+  }
+  get(field, fallback) {
+    const v = this.params[field];
+    return v === void 0 ? fallback : v;
+  }
+};
+function hasDomEvents() {
+  return typeof window !== "undefined" && typeof window.addEventListener === "function";
+}
+function onWindow(type, handler, opts) {
+  try {
+    if (hasDomEvents()) window.addEventListener(type, handler, opts);
+  } catch {
+  }
+}
+function onDocument(type, handler, opts) {
+  try {
+    if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+      document.addEventListener(type, handler, opts);
+    }
+  } catch {
+  }
+}
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -381,8 +508,8 @@ var EventBuffer = class {
     this.sdkKey = sdkKey;
     if (typeof window !== "undefined") {
       this.timer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
-      window.addEventListener("beforeunload", () => this.flush());
-      document.addEventListener("visibilitychange", () => {
+      onWindow("beforeunload", () => this.flush());
+      onDocument("visibilitychange", () => {
         if (document.visibilityState === "hidden") this.flush(true);
       });
       try {
@@ -927,6 +1054,10 @@ var Engine = class _Engine {
   env;
   evalResult = null;
   anonId;
+  // Resolves once a caller-supplied anonymousStore has been consulted (persisted
+  // id adopted, or the minted id written back). identify() awaits it so the
+  // stable id is settled before the first /sdk/evaluate. null when no store.
+  anonReady = null;
   userId = "";
   buffer;
   telemetry;
@@ -952,10 +1083,16 @@ var Engine = class _Engine {
     this.notify();
   };
   constructor(opts) {
+    setLogLevel(opts.logLevel);
     this.sdkKey = opts.sdkKey;
-    this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
+    this.baseUrl = (opts.baseUrl ?? "https://api.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.testMode = opts.testMode === true;
+    setInternalReportContext({
+      side: "client",
+      sdkVersion: version,
+      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+    });
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
     this.disableAutoExposure = opts.disableAutoExposure === true;
@@ -968,6 +1105,9 @@ var Engine = class _Engine {
       engagement: g.engagement ?? this.autoGuardrails
     };
     this.anonId = getOrCreateAnonId();
+    if (opts.anonymousStore && !this.testMode) {
+      this.anonReady = this.hydrateAnonFromStore(opts.anonymousStore);
+    }
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
@@ -983,6 +1123,23 @@ var Engine = class _Engine {
       void this.buffer.flushPendingAlias();
     }
   }
+  /**
+   * 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.
+   */
+  async hydrateAnonFromStore(store) {
+    try {
+      const stored = await store.get(ANON_ID_KEY);
+      if (typeof stored === "string" && stored) {
+        this.anonId = stored;
+      } else {
+        await store.set(ANON_ID_KEY, this.anonId);
+      }
+    } catch {
+    }
+  }
   /**
    * Build a no-network, immediately-usable browser client for tests
    * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
@@ -1010,6 +1167,10 @@ var Engine = class _Engine {
       this.notify();
       return;
     }
+    if (this.anonReady) {
+      await this.anonReady;
+      this.anonReady = null;
+    }
     const seq = ++this.identifySeq;
     const prevUserId = this.userId;
     if (user.user_id !== void 0) this.userId = user.user_id;
@@ -1086,7 +1247,7 @@ var Engine = class _Engine {
       try {
         l();
       } catch (err) {
-        console.warn("[shipeasy] subscriber threw:", String(err));
+        logger.warn("[shipeasy] subscriber threw:", String(err));
       }
     }
   }
@@ -1163,54 +1324,41 @@ var Engine = class _Engine {
     try {
       return opts.decode(raw);
     } catch (err) {
-      console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
+      logger.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
       return void 0;
     }
   }
-  getExperiment(name, defaultParams, decodeOrOpts, variantsArg) {
-    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts, variants: variantsArg } : decodeOrOpts ?? {};
-    const { decode, variants } = opts;
+  /**
+   * 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) {
+    return { assign: (opts) => this.assignUniverse(name, opts) };
+  }
+  assignUniverse(name, opts) {
     this.telemetry.emit("experiment", name);
-    const notIn = {
-      inExperiment: false,
-      group: "control",
-      params: defaultParams
-    };
-    const pov = this.experimentOverrides.get(name);
-    if (pov) {
-      const variantParams = variants?.[pov.group];
-      const params = { ...defaultParams, ...pov.params, ...variantParams ?? {} };
-      return { inExperiment: true, group: pov.group, params };
+    const defaults = this.evalResult?.universes?.[name]?.defaults ?? {};
+    for (const [expName, pov] of this.experimentOverrides) {
+      if (this.evalResult?.experiments[expName]?.universe !== name) continue;
+      return new AssignmentImpl(expName, pov.group, { ...defaults, ...pov.params });
     }
-    const ov = readExpOverride(name);
-    if (ov !== null) {
-      const variantParams = variants?.[ov];
-      const params = variantParams ? { ...defaultParams, ...variantParams } : defaultParams;
-      return { inExperiment: true, group: ov, params };
+    for (const [expName, entry] of Object.entries(this.evalResult?.experiments ?? {})) {
+      if (entry.universe !== name) continue;
+      const ov = readExpOverride(expName);
+      if (ov !== null) return new AssignmentImpl(expName, ov, { ...defaults, ...entry.params });
     }
-    const entry = this.evalResult?.experiments[name];
-    if (!entry || !entry.inExperiment) return notIn;
-    const shouldLog = opts.logExposure ?? !this.disableAutoExposure;
-    if (shouldLog) this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
-    if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
-    try {
-      return { inExperiment: true, group: entry.group, params: decode(entry.params) };
-    } catch (err) {
-      console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
-      return notIn;
+    for (const [expName, entry] of Object.entries(this.evalResult?.experiments ?? {})) {
+      if (entry.universe !== name || !entry.inExperiment) continue;
+      const shouldLog = opts?.logExposure ?? !this.disableAutoExposure;
+      if (shouldLog) this.buffer.pushExposure(expName, entry.group, this.userId, this.anonId);
+      return new AssignmentImpl(expName, entry.group, entry.params);
     }
-  }
-  /**
-   * 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) {
-    const entry = this.evalResult?.experiments[name];
-    if (!entry || !entry.inExperiment) return;
-    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    return new AssignmentImpl(null, null, defaults);
   }
   /**
    * Subscribe to state changes — fires after identify() completes and on
@@ -1219,7 +1367,7 @@ var Engine = class _Engine {
    */
   subscribe(listener) {
     this.listeners.add(listener);
-    if (!this.overrideListenerInstalled && typeof window !== "undefined") {
+    if (!this.overrideListenerInstalled && hasDomEvents()) {
       this.overrideListenerInstalled = true;
       window.addEventListener("se:override:change", this.onOverrideChange);
     }
@@ -1235,9 +1383,11 @@ var Engine = class _Engine {
     if (typeof window === "undefined") return null;
     const bridge = {
       getFlag: (n) => this.getFlag(n),
+      // Devtools reads assignments by experiment name straight off the eval
+      // result (the public read path is universe-first; this is display-only).
       getExperiment: (n) => {
-        const r = this.getExperiment(n, {});
-        return { inExperiment: r.inExperiment, group: r.group };
+        const entry = this.evalResult?.experiments[n];
+        return { inExperiment: entry?.inExperiment ?? false, group: entry?.group ?? "control" };
       },
       getConfig: (n) => this.getConfig(n)
     };
@@ -1360,7 +1510,7 @@ function loadDevtools(opts = {}) {
   }
 }
 function attachDevtools(client, opts = {}) {
-  if (typeof window === "undefined") return () => {
+  if (!hasDomEvents()) return () => {
   };
   const hotkey = opts.hotkey ?? "Shift+Alt+S";
   const parts = hotkey.split("+");
@@ -1399,19 +1549,22 @@ function shipeasy(opts) {
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
+    logLevel: opts.logLevel,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
     disableTelemetry: opts.disableTelemetry,
+    disableInternalErrorReporting: opts.disableInternalErrorReporting,
     disableAutoExposure: opts.disableAutoExposure,
     privateAttributes: opts.privateAttributes,
-    stickyBucketing: opts.stickyBucketing
+    stickyBucketing: opts.stickyBucketing,
+    anonymousStore: opts.anonymousStore
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
   if (opts.autoIdentify !== false) {
     void client.identify({}).catch((err) => {
-      console.warn("[shipeasy] auto-identify failed:", String(err));
+      logger.warn("[shipeasy] auto-identify failed:", String(err));
     });
   }
   return attachDevtools(client, { adminUrl: opts.adminUrl });
@@ -1487,7 +1640,7 @@ var _mountedAndReady = false;
 var _standaloneListeners = /* @__PURE__ */ new Set();
 var _standaloneOverrideWired = false;
 function wireStandaloneOverride() {
-  if (_standaloneOverrideWired || typeof window === "undefined") return;
+  if (_standaloneOverrideWired || !hasDomEvents()) return;
   _standaloneOverrideWired = true;
   window.addEventListener("se:override:change", () => {
     for (const cb of _standaloneListeners) cb();
@@ -1499,7 +1652,7 @@ var flags = {
   },
   identify(user) {
     if (!_client) {
-      console.warn("[shipeasy] flags.identify called before configureShipeasy()");
+      logger.warn("[shipeasy] flags.identify called before configureShipeasy()");
       return Promise.resolve();
     }
     return _client.identify(user);
@@ -1512,57 +1665,66 @@ var flags = {
    * force-static pages where SSR has no flag data.
    */
   get(name, defaultValue = false) {
-    const bs = getBootstrap();
-    if (bs !== null && name in bs.flags) return bs.flags[name];
-    if (!_mountedAndReady) return defaultValue;
-    if (_client) return _client.getFlag(name, defaultValue);
-    return readGateOverride(name) ?? defaultValue;
+    return safeRun("flags.get", defaultValue, () => {
+      const bs = getBootstrap();
+      if (bs !== null && name in bs.flags) return bs.flags[name];
+      if (!_mountedAndReady) return defaultValue;
+      if (_client) return _client.getFlag(name, defaultValue);
+      return readGateOverride(name) ?? defaultValue;
+    });
   },
   /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
   getDetail(name) {
-    if (_client) return _client.getFlagDetail(name);
-    const ov = readGateOverride(name);
-    if (ov !== null) return { value: ov, reason: "OVERRIDE" };
-    return { value: false, reason: "CLIENT_NOT_READY" };
+    return safeRun("flags.getDetail", { value: false, reason: "CLIENT_NOT_READY" }, () => {
+      if (_client) return _client.getFlagDetail(name);
+      const ov = readGateOverride(name);
+      if (ov !== null) return { value: ov, reason: "OVERRIDE" };
+      return { value: false, reason: "CLIENT_NOT_READY" };
+    });
   },
   getConfig(name, decode) {
-    const bs = getBootstrap();
-    if (bs !== null && name in bs.configs) {
-      const raw = bs.configs[name];
-      if (!decode) return raw;
+    return safeRun("flags.getConfig", void 0, () => {
+      const bs = getBootstrap();
+      if (bs !== null && name in bs.configs) {
+        const raw = bs.configs[name];
+        if (!decode) return raw;
+        try {
+          return decode(raw);
+        } catch {
+          return void 0;
+        }
+      }
+      if (!_mountedAndReady) return void 0;
+      if (_client) return _client.getConfig(name, decode);
+      const ov = readConfigOverride(name);
+      if (ov === void 0) return void 0;
+      if (!decode) return ov;
       try {
-        return decode(raw);
+        return decode(ov);
       } catch {
         return void 0;
       }
-    }
-    if (!_mountedAndReady) return void 0;
-    if (_client) return _client.getConfig(name, decode);
-    const ov = readConfigOverride(name);
-    if (ov === void 0) return void 0;
-    if (!decode) return ov;
-    try {
-      return decode(ov);
-    } catch {
-      return void 0;
-    }
+    });
   },
-  getExperiment(name, defaultParams, decodeOrOpts, variants) {
-    const fallback = {
-      inExperiment: false,
-      group: "control",
-      params: defaultParams
+  /**
+   * 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) {
+    return {
+      assign: (opts) => safeRun(
+        "flags.universe.assign",
+        new AssignmentImpl(null, null, {}),
+        () => _client ? _client.universe(name).assign(opts) : new AssignmentImpl(null, null, {})
+      )
     };
-    if (!_client) return fallback;
-    return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
-  },
-  /** Manually log an exposure for an enrolled experiment. See
-   *  {@link Engine.logExposure}. No-op before configure(). */
-  logExposure(name) {
-    _client?.logExposure(name);
   },
   track(eventName, props) {
-    _client?.track(eventName, props);
+    safeRun("flags.track", void 0, () => _client?.track(eventName, props));
   },
   /**
    * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -1574,15 +1736,17 @@ var flags = {
    * available synchronously on first render.
    */
   ks(name, switchKey) {
-    const bs = getBootstrap();
-    if (bs !== null && bs.killswitches && name in bs.killswitches) {
-      const ks = bs.killswitches[name];
-      if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
-      if (switchKey === void 0) return false;
-      return ks[switchKey] === true;
-    }
-    if (!_mountedAndReady) return false;
-    return _client?.getKillswitch(name, switchKey) ?? false;
+    return safeRun("flags.ks", false, () => {
+      const bs = getBootstrap();
+      if (bs !== null && bs.killswitches && name in bs.killswitches) {
+        const ks = bs.killswitches[name];
+        if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+        if (switchKey === void 0) return false;
+        return ks[switchKey] === true;
+      }
+      if (!_mountedAndReady) return false;
+      return _client?.getKillswitch(name, switchKey) ?? false;
+    });
   },
   flush() {
     return _client?.flush() ?? Promise.resolve();
@@ -1639,7 +1803,7 @@ var Client = class {
     this.engine = engine;
     this.attributes = _attributes(user);
     this._identify = this.engine.identify(this.attributes).catch((err) => {
-      console.warn("[shipeasy] Client identify failed:", String(err));
+      logger.warn("[shipeasy] Client identify failed:", String(err));
     });
   }
   /** Resolves once the engine's identify() for this user has completed. */
@@ -1647,20 +1811,40 @@ var Client = class {
     return this._identify;
   }
   getFlag(name, defaultValue = false) {
-    return this.engine.getFlag(name, defaultValue);
+    return safeRun("Client.getFlag", defaultValue, () => this.engine.getFlag(name, defaultValue));
   }
   getFlagDetail(name) {
-    return this.engine.getFlagDetail(name);
+    return safeRun(
+      "Client.getFlagDetail",
+      { value: false, reason: "CLIENT_NOT_READY" },
+      () => this.engine.getFlagDetail(name)
+    );
   }
   getConfig(name, decodeOrOpts) {
-    return this.engine.getConfig(name, decodeOrOpts);
+    return safeRun(
+      "Client.getConfig",
+      void 0,
+      () => this.engine.getConfig(name, decodeOrOpts)
+    );
   }
-  getExperiment(name, defaultParams, decode) {
-    return this.engine.getExperiment(name, defaultParams, decode);
+  /**
+   * 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) {
+    return {
+      assign: (opts) => safeRun(
+        "Client.universe.assign",
+        new AssignmentImpl(null, null, {}),
+        () => this.engine.universe(name).assign(opts)
+      )
+    };
   }
   /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
   getKillswitch(name, switchKey) {
-    return this.engine.getKillswitch(name, switchKey);
+    return safeRun("Client.getKillswitch", false, () => this.engine.getKillswitch(name, switchKey));
   }
   /**
    * Record a conversion/metric event for the bound (identified) user. Delegates
@@ -1669,21 +1853,12 @@ var Client = class {
    * test mode.
    */
   track(eventName, props) {
-    this.engine.track(eventName, props);
-  }
-  /**
-   * 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) {
-    this.engine.logExposure(name);
+    safeRun("Client.track", void 0, () => this.engine.track(eventName, props));
   }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_client) {
-    console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
+    logger.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
     return;
   }
   _client.reportError(problem, consequence, extras, kind);
@@ -1905,6 +2080,7 @@ var i18n = {
   whenReady() {
     if (typeof window === "undefined") return Promise.resolve();
     if (window.i18n?.locale) return Promise.resolve();
+    if (!hasDomEvents()) return Promise.resolve();
     return new Promise((resolve) => {
       const handler = () => resolve();
       window.addEventListener("se:i18n:ready", handler, { once: true });
@@ -1915,6 +2091,8 @@ var i18n = {
     if (typeof window === "undefined") return () => {
     };
     if (window.i18n) return window.i18n.on("update", cb);
+    if (!hasDomEvents()) return () => {
+    };
     let unsub = () => {
     };
     const handler = () => {
@@ -1936,6 +2114,7 @@ var i18n = {
   LABEL_MARKER_RE,
   LABEL_MARKER_SEP,
   LABEL_MARKER_START,
+  LOG_LEVELS,
   _resetConfigureForTests,
   _resetShipeasyForTests,
   attachDevtools,