@shipeasy/sdk 6.2.0 → 7.0.0

package/dist/server/index.js

@@ -34,6 +34,7 @@ __export(server_exports, {
   Client: () => Client,
   Engine: () => Engine,
   FLAG_REASONS: () => FLAG_REASONS,
+  LOG_LEVELS: () => LOG_LEVELS,
   _murmur3ForTests: () => _murmur3ForTests,
   _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
@@ -238,7 +239,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;
@@ -266,8 +267,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);
@@ -276,10 +277,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;
 }
@@ -372,6 +373,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/server/index.ts
 var version = "4.0.0";
 var C1 = 3432918353;
@@ -508,6 +601,78 @@ function evalGateInternal(gate, user) {
   if (!uid) return gate.rolloutPct >= 1e4;
   return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
 }
+function paramDefaultsFromSchema(schema) {
+  if (!schema || schema.length === 0) return null;
+  const out = {};
+  for (const p of schema) out[p.name] = p.default;
+  return out;
+}
+function mergeParams(paramDefaults, groupParams) {
+  return paramDefaults ? { ...paramDefaults, ...groupParams } : { ...groupParams };
+}
+function classifyExperimentLocal(exp, user, holdoutRange, paramDefaults, evalGate, sticky) {
+  const asGroup = (g) => ({
+    state: "group",
+    group: g.name,
+    params: mergeParams(paramDefaults, g.params)
+  });
+  if (exp.targetingGate && !evalGate(exp.targetingGate)) return { state: "out" };
+  const uid = pickIdentifier(user, exp.bucketBy);
+  if (!uid) return { state: "out" };
+  const universeSeg = murmur3(`${exp.universe}:${uid}`) % 1e4;
+  if (holdoutRange) {
+    const [lo, hi] = holdoutRange;
+    if (universeSeg >= lo && universeSeg <= hi) return { state: "holdout" };
+  }
+  if (exp.holdoutGate && evalGate(exp.holdoutGate)) return { state: "holdout" };
+  const salt8 = exp.salt.slice(0, 8);
+  if (sticky) {
+    const entry = sticky.get();
+    if (entry && entry.s === salt8) {
+      const g = exp.groups.find((x) => x.name === entry.g);
+      if (g) return asGroup(g);
+    }
+  }
+  const pooled = (exp.hashVersion ?? 1) >= 2 && exp.poolOffsetBp != null && exp.poolSizeBp != null && exp.poolSizeBp > 0;
+  if (pooled) {
+    const lo = exp.poolOffsetBp;
+    const hi = lo + exp.poolSizeBp;
+    if (universeSeg < lo || universeSeg >= hi) return { state: "out" };
+  } else {
+    if (murmur3(`${exp.salt}:alloc:${uid}`) % 1e4 >= exp.allocationPct) return { state: "out" };
+  }
+  const reserved = Math.max(0, Math.min(1e4, exp.reservedHeadroomBp ?? 0));
+  const usable = 1e4 - reserved;
+  const groupHash = murmur3(`${exp.salt}:group:${uid}`) % 1e4;
+  if (groupHash >= usable) return { state: "out" };
+  let cumulative = 0;
+  for (let i = 0; i < exp.groups.length; i++) {
+    const g = exp.groups[i];
+    cumulative += g.weight;
+    if (groupHash < cumulative || i === exp.groups.length - 1) {
+      sticky?.set({ g: g.name, s: salt8 });
+      return asGroup(g);
+    }
+  }
+  return { state: "out" };
+}
+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;
+  }
+};
 var TRUE_RX = /^(true|on|1|yes)$/i;
 var FALSE_RX = /^(false|off|0|no)$/i;
 function parseOverrideBool(raw) {
@@ -578,16 +743,25 @@ var Engine = class _Engine {
   flagOverrides = /* @__PURE__ */ new Map();
   configOverrides = /* @__PURE__ */ new Map();
   experimentOverrides = /* @__PURE__ */ new Map();
+  // Bounded per-process exposure dedup (`uid:exp:group`) so auto-exposure from
+  // repeated assign() calls doesn't spam /collect. Cleared past a soft cap.
+  exposureSeen = /* @__PURE__ */ new Set();
   // Change listeners fired after a background poll returns NEW data (200, not
   // 304). Never fired in testMode/offline (no polling happens there).
   changeListeners = /* @__PURE__ */ new Set();
   constructor(opts) {
+    setLogLevel(opts.logLevel);
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.privateAttributes = opts.privateAttributes ?? [];
     this.stickyStore = opts.stickyStore;
     this.testMode = opts.testMode === true;
+    setInternalReportContext({
+      side: "server",
+      sdkVersion: version,
+      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+    });
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
       sdkKey: this.apiKey,
@@ -705,14 +879,14 @@ var Engine = class _Engine {
       try {
         l();
       } catch (err) {
-        console.warn("[shipeasy] onChange listener threw:", String(err));
+        logger.warn("[shipeasy] onChange listener threw:", String(err));
       }
     }
   }
   startPoll() {
     this.timer = setInterval(() => {
       this.fetchAll(true).catch(
-        (err) => console.warn("[shipeasy] background poll failed:", String(err))
+        (err) => logger.warn("[shipeasy] background poll failed:", String(err))
       );
     }, this.pollInterval * 1e3);
   }
@@ -791,70 +965,84 @@ var Engine = class _Engine {
       return "defaultValue" in opts ? opts.defaultValue : void 0;
     }
     if (!opts.decode) return raw;
-    return opts.decode(raw);
-  }
-  getExperiment(name, user, defaultParams, decode) {
-    this.telemetry.emit("experiment", name);
-    const notIn = {
-      inExperiment: false,
-      group: "control",
-      params: defaultParams
+    try {
+      return opts.decode(raw);
+    } catch (err) {
+      logger.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
+      return "defaultValue" in opts ? opts.defaultValue : void 0;
+    }
+  }
+  /**
+   * Bind the per-experiment sticky seam over the configured {@link StickyBucketStore}
+   * for one (unit, experiment). Absent store ⇒ deterministic (no sticky).
+   */
+  bindSticky(name, uid) {
+    const store = this.stickyStore;
+    if (!store) return void 0;
+    return {
+      get: () => store.get(uid)?.[name],
+      set: (entry) => store.set(uid, name, entry)
     };
+  }
+  /**
+   * Evaluate one experiment by name for `user` — override → full classify
+   * pipeline (targeting → universe holdout → holdout gate → sticky → allocation
+   * → group), merging the universe defaults under the assigned variant (§B2).
+   * Internal: the public surface is `universe(name).assign(user)`. Reused by the
+   * SSR `evaluate()` bootstrap (keyed by experiment name) and by `assignUniverse`.
+   */
+  evalExperiment(name, exp, user) {
+    const paramDefaults = paramDefaultsFromSchema(
+      this.expsBlob?.universes[exp.universe]?.param_schema
+    );
     const ov = this.experimentOverrides.get(name);
-    if (ov) {
-      if (!decode) return { inExperiment: true, group: ov.group, params: ov.params };
-      try {
-        return { inExperiment: true, group: ov.group, params: decode(ov.params) };
-      } catch (err) {
-        console.warn(`[shipeasy] getExperiment('${name}') override decode failed:`, String(err));
-        return notIn;
-      }
-    }
-    if (!this.flagsBlob || !this.expsBlob) return notIn;
-    const exp = this.expsBlob.experiments[name];
-    if (!exp || exp.status !== "running") return notIn;
-    if (exp.targetingGate) {
-      const gate = this.flagsBlob.gates[exp.targetingGate];
-      if (!gate || !evalGateInternal(gate, user)) return notIn;
-    }
-    const uid = pickIdentifier(user, exp.bucketBy);
-    if (!uid) return notIn;
-    const universe = this.expsBlob.universes[exp.universe];
-    const holdoutRange = universe?.holdout_range ?? null;
-    if (holdoutRange) {
-      const seg = murmur3(`${exp.universe}:${uid}`) % 1e4;
-      const [lo, hi] = holdoutRange;
-      if (seg >= lo && seg <= hi) return notIn;
-    }
-    const asResult = (g) => {
-      if (!decode) return { inExperiment: true, group: g.name, params: g.params };
-      try {
-        return { inExperiment: true, group: g.name, params: decode(g.params) };
-      } catch (err) {
-        console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
-        return notIn;
-      }
+    if (ov) return { state: "group", group: ov.group, params: mergeParams(paramDefaults, ov.params) };
+    if (!this.flagsBlob || !this.expsBlob) return { state: "out" };
+    if (exp.status !== "running") return { state: "out" };
+    const holdoutRange = this.expsBlob.universes[exp.universe]?.holdout_range ?? null;
+    const evalGate = (gname) => {
+      const gate = this.flagsBlob?.gates[gname];
+      return gate ? evalGateInternal(gate, user) : false;
     };
-    const salt8 = exp.salt.slice(0, 8);
-    if (this.stickyStore) {
-      const entry = this.stickyStore.get(uid)?.[name];
-      if (entry && entry.s === salt8) {
-        const g = exp.groups.find((x) => x.name === entry.g);
-        if (g) return asResult(g);
-      }
-    }
-    if (murmur3(`${exp.salt}:alloc:${uid}`) % 1e4 >= exp.allocationPct) return notIn;
-    const groupHash = murmur3(`${exp.salt}:group:${uid}`) % 1e4;
-    let cumulative = 0;
-    for (let i = 0; i < exp.groups.length; i++) {
-      const g = exp.groups[i];
-      cumulative += g.weight;
-      if (groupHash < cumulative || i === exp.groups.length - 1) {
-        this.stickyStore?.set(uid, name, { g: g.name, s: salt8 });
-        return asResult(g);
+    const uid = pickIdentifier(user, exp.bucketBy);
+    const sticky = uid ? this.bindSticky(name, uid) : void 0;
+    return classifyExperimentLocal(exp, user, holdoutRange, paramDefaults, evalGate, sticky);
+  }
+  /**
+   * Assign `user` within `universeName`. A universe is a mutual-exclusion pool,
+   * so a unit lands in **at most one** experiment; the returned {@link Assignment}
+   * exposes the variant + resolved params and auto-logs a single exposure when
+   * enrolled. An un-enrolled unit still resolves `get()` to the universe defaults.
+   * Never throws. This is the sole experiment read path (there is no
+   * `getExperiment` — a caller asks a universe, not an experiment).
+   */
+  assignUniverse(universeName, user) {
+    this.telemetry.emit("experiment", universeName);
+    const paramDefaults = paramDefaultsFromSchema(
+      this.expsBlob?.universes[universeName]?.param_schema
+    );
+    const notEnrolled = () => new AssignmentImpl(null, null, paramDefaults ?? {});
+    if (!this.expsBlob) return notEnrolled();
+    const candidates = Object.entries(this.expsBlob.experiments).filter(([, e]) => e.universe === universeName && e.status === "running").sort(
+      (a, b) => (a[1].poolOffsetBp ?? 0) - (b[1].poolOffsetBp ?? 0) || a[0].localeCompare(b[0])
+    );
+    for (const [name, exp] of candidates) {
+      const c = this.evalExperiment(name, exp, user);
+      if (c.state === "group") {
+        this.postExposure(user, name, c.group);
+        return new AssignmentImpl(name, c.group, c.params ?? {});
       }
     }
-    return notIn;
+    return notEnrolled();
+  }
+  /**
+   * The universe-first experiment read entry point:
+   * `engine.universe("checkout").assign(user)`. Returns a reusable handle bound
+   * to one universe; `assign(user)` picks the ≤1 experiment the unit is pooled
+   * into and auto-logs a single exposure. See {@link assignUniverse}.
+   */
+  universe(name) {
+    return { assign: (user) => this.assignUniverse(name, user) };
   }
   /** Drop caller-marked private attributes from an outbound props bag. */
   stripPrivate(props) {
@@ -883,29 +1071,29 @@ var Engine = class _Engine {
       method: "POST",
       headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
       body
-    }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
+    }).catch((err) => logger.warn("[shipeasy] track failed:", String(err)));
   }
   /**
-   * Emit an exposure event for an experiment at the server-side decision point
-   * (parity with the browser's auto-exposure). The server is stateless and
-   * never auto-logs, so call this when you actually present the treatment.
-   * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
-   * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
-   * `/collect`. No-op in test mode or when the user isn't enrolled.
+   * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
+   * per process (bounded set) so repeated `assign()` calls in one server don't
+   * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
+   * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
    */
-  logExposure(user, name) {
+  postExposure(user, experiment, group) {
     if (this.testMode) return;
-    const u = typeof user === "string" ? { user_id: user } : user;
-    const result = this.getExperiment(name, u, {});
-    if (!result.inExperiment) return;
+    const uid = user.user_id ?? user.anonymous_id;
+    const dedupKey = `${uid ?? ""}:${experiment}:${group}`;
+    if (this.exposureSeen.has(dedupKey)) return;
+    if (this.exposureSeen.size > 5e3) this.exposureSeen.clear();
+    this.exposureSeen.add(dedupKey);
     const body = JSON.stringify({
       events: [
         {
           type: "exposure",
-          experiment: name,
-          group: result.group,
-          ...u.user_id !== void 0 ? { user_id: u.user_id } : {},
-          ...u.anonymous_id !== void 0 ? { anonymous_id: u.anonymous_id } : {},
+          experiment,
+          group,
+          ...user.user_id !== void 0 ? { user_id: user.user_id } : {},
+          ...user.anonymous_id !== void 0 ? { anonymous_id: user.anonymous_id } : {},
           ts: Date.now()
         }
       ]
@@ -914,7 +1102,7 @@ var Engine = class _Engine {
       method: "POST",
       headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
       body
-    }).catch((err) => console.warn("[shipeasy] logExposure failed:", String(err)));
+    }).catch((err) => logger.warn("[shipeasy] exposure send failed:", String(err)));
   }
   /**
    * Report a structured error into the errors primitive. Fire-and-forget —
@@ -934,7 +1122,7 @@ var Engine = class _Engine {
         method: "POST",
         headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
         body: JSON.stringify({ events: [ev] })
-      }).catch((err) => console.warn("[shipeasy] see() send failed:", String(err)));
+      }).catch((err) => logger.warn("[shipeasy] see() send failed:", String(err)));
     } catch {
     }
   }
@@ -960,8 +1148,17 @@ var Engine = class _Engine {
       this.telemetry.emit("config", name);
       configs[name] = entry.value;
     }
-    for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
-      experiments[name] = this.getExperiment(name, user, {});
+    const universes = {};
+    for (const [name, exp] of Object.entries(this.expsBlob?.experiments ?? {})) {
+      this.telemetry.emit("experiment", exp.universe);
+      const uniName = exp.universe;
+      if (!(uniName in universes)) {
+        universes[uniName] = {
+          defaults: paramDefaultsFromSchema(this.expsBlob?.universes[uniName]?.param_schema) ?? {}
+        };
+      }
+      const c = this.evalExperiment(name, exp, user);
+      experiments[name] = c.state === "group" ? { inExperiment: true, group: c.group, params: c.params ?? {}, universe: uniName } : { inExperiment: false, group: "control", params: {}, universe: uniName };
     }
     for (const [name, ks] of Object.entries(this.flagsBlob?.killswitches ?? {})) {
       this.telemetry.emit("ks", name);
@@ -978,10 +1175,11 @@ var Engine = class _Engine {
       Object.assign(flags2, ov.gates);
       Object.assign(configs, ov.configs);
       for (const [name, group] of Object.entries(ov.experiments)) {
-        experiments[name] = { inExperiment: true, group, params: {} };
+        const uni = this.expsBlob?.experiments[name]?.universe;
+        experiments[name] = { inExperiment: true, group, params: {}, ...uni ? { universe: uni } : {} };
       }
     }
-    return { flags: flags2, configs, experiments, killswitches };
+    return { flags: flags2, configs, experiments, killswitches, universes };
   }
   getKillswitch(name, switchKey) {
     this.telemetry.emit("ks", name);
@@ -1121,7 +1319,7 @@ function _resetShipeasyServerForTests() {
 async function shipeasy(opts) {
   const serverKey = opts.serverKey ?? "";
   if (!serverKey) {
-    console.error(
+    logger.error(
       "[shipeasy] No server key \u2014 flags, experiments and SSR i18n skipped. Pass `serverKey` to shipeasy() from @shipeasy/sdk/server with your server key (SHIPEASY_SERVER_KEY). Set it as a Worker secret with `wrangler secret put SHIPEASY_SERVER_KEY` (or add it to .env for local dev). Do not pass a client key here \u2014 the server entrypoint only accepts the server key."
     );
   }
@@ -1129,7 +1327,9 @@ async function shipeasy(opts) {
   flags.configure({
     apiKey: serverKey,
     disableTelemetry: opts.disableTelemetry,
-    privateAttributes: opts.privateAttributes
+    disableInternalErrorReporting: opts.disableInternalErrorReporting,
+    privateAttributes: opts.privateAttributes,
+    logLevel: opts.logLevel
   });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
@@ -1255,20 +1455,38 @@ var flags = {
     _server?.destroy();
   },
   get(name, user, defaultValue = false) {
-    return _server?.getFlag(name, user, defaultValue) ?? defaultValue;
+    return safeRun("flags.get", defaultValue, () => _server?.getFlag(name, user, defaultValue) ?? defaultValue);
   },
   /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
   getDetail(name, user) {
-    return _server?.getFlagDetail(name, user) ?? { value: false, reason: "CLIENT_NOT_READY" };
+    return safeRun(
+      "flags.getDetail",
+      { value: false, reason: "CLIENT_NOT_READY" },
+      () => _server?.getFlagDetail(name, user) ?? { value: false, reason: "CLIENT_NOT_READY" }
+    );
   },
   getConfig(name, decodeOrOpts) {
-    return _server?.getConfig(name, decodeOrOpts);
+    return safeRun(
+      "flags.getConfig",
+      void 0,
+      () => _server?.getConfig(name, decodeOrOpts)
+    );
   },
-  getExperiment(name, user, defaultParams, decode) {
-    return _server?.getExperiment(name, user, defaultParams, decode) ?? {
-      inExperiment: false,
-      group: "control",
-      params: defaultParams
+  /**
+   * Assign `user` within a universe: `flags.universe("checkout").assign(user)`.
+   * A universe is a mutual-exclusion pool, so the unit lands in ≤1 experiment;
+   * the returned {@link Assignment} exposes `.group` / `.get(field, fallback)`
+   * and auto-logs one exposure when enrolled. Before configure() (or on any
+   * error) it returns a safe not-enrolled handle. This replaces the removed
+   * `getExperiment` — read experiments by universe, never by name.
+   */
+  universe(name) {
+    return {
+      assign: (user) => safeRun(
+        "flags.universe.assign",
+        new AssignmentImpl(null, null, {}),
+        () => _server?.assignUniverse(name, user) ?? new AssignmentImpl(null, null, {})
+      )
     };
   },
   /**
@@ -1277,15 +1495,10 @@ var flags = {
    * switch is on. Unknown killswitches / switches return false.
    */
   ks(name, switchKey) {
-    return _server?.getKillswitch(name, switchKey) ?? false;
+    return safeRun("flags.ks", false, () => _server?.getKillswitch(name, switchKey) ?? false);
   },
   track(userId, eventName, props) {
-    _server?.track(userId, eventName, props);
-  },
-  /** Emit an exposure for an enrolled experiment at the decision point. See
-   *  {@link Engine.logExposure}. No-op before configure(). */
-  logExposure(user, name) {
-    _server?.logExposure(user, name);
+    safeRun("flags.track", void 0, () => _server?.track(userId, eventName, props));
   },
   /**
    * Evaluate all flags / configs / experiments for a user against the locally
@@ -1293,12 +1506,8 @@ var flags = {
    * overrides. Returns an empty payload when the blob hasn't been fetched yet.
    */
   evaluate(user, rawUrl) {
-    return _server?.evaluate(user, rawUrl) ?? {
-      flags: {},
-      configs: {},
-      experiments: {},
-      killswitches: {}
-    };
+    const empty = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
+    return safeRun("flags.evaluate", empty, () => _server?.evaluate(user, rawUrl) ?? empty);
   }
 };
 var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
@@ -1387,20 +1596,44 @@ var Client = class {
     this.attributes = _attributes(user);
   }
   getFlag(name, defaultValue = false) {
-    return this.engine.getFlag(name, this.attributes, defaultValue);
+    return safeRun(
+      "Client.getFlag",
+      defaultValue,
+      () => this.engine.getFlag(name, this.attributes, defaultValue)
+    );
   }
   getFlagDetail(name) {
-    return this.engine.getFlagDetail(name, this.attributes);
+    return safeRun(
+      "Client.getFlagDetail",
+      { value: false, reason: "CLIENT_NOT_READY" },
+      () => this.engine.getFlagDetail(name, this.attributes)
+    );
   }
   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, this.attributes, defaultParams, decode);
+  /**
+   * Assign the bound user within a universe: `client.universe("checkout").assign()`.
+   * The user is already bound at construction, so `assign()` takes no arg. Returns
+   * an {@link Assignment} (`.group` / `.get(field, fallback)`) and auto-logs one
+   * exposure when enrolled. Replaces the removed `getExperiment`.
+   */
+  universe(name) {
+    return {
+      assign: () => safeRun(
+        "Client.universe.assign",
+        new AssignmentImpl(null, null, {}),
+        () => this.engine.assignUniverse(name, this.attributes)
+      )
+    };
   }
   /** 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 user. Derives the unit from
@@ -1410,23 +1643,16 @@ var Client = class {
    * mode.
    */
   track(eventName, props) {
-    const id = this.attributes.user_id ?? this.attributes.anonymous_id;
-    if (id === void 0) return;
-    this.engine.track(String(id), eventName, props);
-  }
-  /**
-   * Emit an exposure event for `name` at this server-side decision point for the
-   * bound user. Delegates to {@link Engine.logExposure} with the resolved
-   * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
-   * in test mode).
-   */
-  logExposure(name) {
-    this.engine.logExposure(this.attributes, name);
+    safeRun("Client.track", void 0, () => {
+      const id = this.attributes.user_id ?? this.attributes.anonymous_id;
+      if (id === void 0) return;
+      this.engine.track(String(id), eventName, props);
+    });
   }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
-    console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
+    logger.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
     return;
   }
   _server.reportError(problem, consequence, extras, kind);
@@ -1444,6 +1670,7 @@ var see = Object.assign(
   Client,
   Engine,
   FLAG_REASONS,
+  LOG_LEVELS,
   _murmur3ForTests,
   _resetConfigureForTests,
   _resetShipeasyServerForTests,