@shipeasy/sdk 6.3.1 → 7.0.0

package/dist/server/index.mjs

@@ -67,53 +67,6 @@ function send(url) {
   }
 }
 
-// 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));
-    return fallback;
-  }
-}
-
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -231,7 +184,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;
@@ -259,8 +212,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);
@@ -269,10 +222,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;
 }
@@ -365,6 +318,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;
@@ -501,6 +546,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) {
@@ -571,6 +688,9 @@ 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();
@@ -582,6 +702,11 @@ var Engine = class _Engine {
     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,
@@ -792,68 +917,77 @@ var Engine = class _Engine {
       return "defaultValue" in opts ? opts.defaultValue : void 0;
     }
   }
-  getExperiment(name, user, defaultParams, decode) {
-    this.telemetry.emit("experiment", name);
-    const notIn = {
-      inExperiment: false,
-      group: "control",
-      params: defaultParams
+  /**
+   * 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) {
-        logger.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) {
-        logger.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) {
@@ -885,26 +1019,26 @@ var Engine = class _Engine {
     }).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()
         }
       ]
@@ -913,7 +1047,7 @@ var Engine = class _Engine {
       method: "POST",
       headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
       body
-    }).catch((err) => logger.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 —
@@ -959,8 +1093,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);
@@ -977,10 +1120,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);
@@ -1128,6 +1272,7 @@ async function shipeasy(opts) {
   flags.configure({
     apiKey: serverKey,
     disableTelemetry: opts.disableTelemetry,
+    disableInternalErrorReporting: opts.disableInternalErrorReporting,
     privateAttributes: opts.privateAttributes,
     logLevel: opts.logLevel
   });
@@ -1272,13 +1417,22 @@ var flags = {
       () => _server?.getConfig(name, decodeOrOpts)
     );
   },
-  getExperiment(name, user, defaultParams, decode) {
-    const notIn = { inExperiment: false, group: "control", params: defaultParams };
-    return safeRun(
-      "flags.getExperiment",
-      notIn,
-      () => _server?.getExperiment(name, user, defaultParams, decode) ?? notIn
-    );
+  /**
+   * 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, {})
+      )
+    };
   },
   /**
    * Read a killswitch. Without `switchKey`, returns true when the whole
@@ -1291,11 +1445,6 @@ var flags = {
   track(userId, eventName, props) {
     safeRun("flags.track", void 0, () => _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) {
-    safeRun("flags.logExposure", void 0, () => _server?.logExposure(user, name));
-  },
   /**
    * Evaluate all flags / configs / experiments for a user against the locally
    * cached blob. Pass the request URL to apply ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -1412,13 +1561,20 @@ var Client = class {
       () => this.engine.getConfig(name, decodeOrOpts)
     );
   }
-  getExperiment(name, defaultParams, decode) {
-    const notIn = { inExperiment: false, group: "control", params: defaultParams };
-    return safeRun(
-      "Client.getExperiment",
-      notIn,
-      () => 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) {
@@ -1438,15 +1594,6 @@ var Client = class {
       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) {
-    safeRun("Client.logExposure", void 0, () => this.engine.logExposure(this.attributes, name));
-  }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {

package/docs/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shipeasy-typescript
-description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from TypeScript / JavaScript. Covers configure() + Client(user), getFlag/getConfig/getKillswitch/getExperiment, track, testing, OpenFeature, and the see() error reporter — server (@shipeasy/sdk/server) and browser (@shipeasy/sdk/client).
+description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from TypeScript / JavaScript. Covers configure() + Client(user), getFlag/getConfig/getKillswitch/universe().assign(), track, testing, OpenFeature, and the see() error reporter — server (@shipeasy/sdk/server) and browser (@shipeasy/sdk/client).
 ---
 
 # Shipeasy TypeScript SDK
@@ -52,17 +52,21 @@ snippets <https://shipeasy-ai.github.io/sdk-ts/snippets/release/flags.md> ·
 
 ```ts
 const flags = new Client(currentUser); // construct once per callsite
-const { inExperiment, group, params } = flags.getExperiment("hero_cta", {
-  primary_label: "Sign up", // default params (control / not-enrolled)
-});
-render(params.primary_label);
 
-flags.logExposure("hero_cta");          // record the exposure where you present it
+// Read experiments by UNIVERSE (a mutual-exclusion pool — the unit lands in ≤1
+// experiment). assign() auto-logs one deduped exposure when enrolled.
+const exp = flags.universe("hero_cta").assign();
+render(exp.get("primary_label", "Sign up")); // variant ?? universe default ?? fallback
+
+if (exp.enrolled) {
+  // exp.group is the variant, exp.name is the experiment
+}
 flags.track("purchase", { value: 42 }); // record a conversion for the bound user
 ```
 
-`ExperimentResult = { inExperiment: boolean; group: string; params: P }`. Full
-reference: <https://shipeasy-ai.github.io/sdk-ts/pages/experiments.md> · track snippet
+`Assignment = { name: string | null; group: string | null; enrolled: boolean;
+get(field, fallback) }`. Full reference:
+<https://shipeasy-ai.github.io/sdk-ts/pages/experiments.md> · track snippet
 <https://shipeasy-ai.github.io/sdk-ts/snippets/metrics/track.md>
 
 ## i18n
@@ -138,8 +142,8 @@ Full reference: <https://shipeasy-ai.github.io/sdk-ts/pages/openfeature.md>
 ## Advanced
 
 `privateAttributes`, `bucketBy` (custom bucketing unit), `stickyBucketing`
-(browser: on by default, `__se_sticky` cookie), manual exposure
-(`getExperiment(..., { logExposure: false })` + `flags.logExposure(name)`),
+(browser: on by default, `__se_sticky` cookie), exposure control (browser:
+`universe(name).assign({ logExposure: false })` + `disableAutoExposure`),
 `onChange(cb)` (requires `configure({ poll: true })`) / browser `subscribe()`.
 Devtools overlay: `Shift+Alt+S` or `?se=1`. Full reference:
 <https://shipeasy-ai.github.io/sdk-ts/pages/advanced.md>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "6.3.1",
+  "version": "7.0.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -14,6 +14,7 @@
   "main": "./dist/server/index.js",
   "module": "./dist/server/index.mjs",
   "browser": "./dist/client/index.js",
+  "react-native": "./dist/client/index.js",
   "typesVersions": {
     "*": {
       "client": [
@@ -29,6 +30,7 @@
   },
   "exports": {
     ".": {
+      "react-native": "./dist/client/index.js",
       "node": "./dist/server/index.js",
       "browser": "./dist/client/index.js",
       "default": "./dist/server/index.js"