@shipeasy/sdk 6.3.1 → 7.0.0

package/dist/client/index.mjs

@@ -57,53 +57,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;
@@ -221,7 +174,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;
@@ -249,8 +202,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);
@@ -259,10 +212,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;
 }
@@ -355,6 +308,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 = [
@@ -365,6 +410,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";
@@ -376,8 +455,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 {
@@ -922,6 +1001,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;
@@ -949,9 +1032,14 @@ var Engine = class _Engine {
   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;
@@ -964,6 +1052,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,
@@ -979,6 +1070,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()
@@ -1006,6 +1114,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;
@@ -1163,50 +1275,37 @@ var Engine = class _Engine {
       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) {
-      logger.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
@@ -1215,7 +1314,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);
     }
@@ -1231,9 +1330,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)
     };
@@ -1356,7 +1457,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("+");
@@ -1400,9 +1501,11 @@ function shipeasy(opts) {
     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();
@@ -1484,7 +1587,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();
@@ -1550,21 +1653,22 @@ var flags = {
       }
     });
   },
-  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, {})
+      )
     };
-    return safeRun("flags.getExperiment", fallback, () => {
-      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) {
-    safeRun("flags.logExposure", void 0, () => _client?.logExposure(name));
   },
   track(eventName, props) {
     safeRun("flags.track", void 0, () => _client?.track(eventName, props));
@@ -1670,13 +1774,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, 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) {
@@ -1691,15 +1802,6 @@ var Client = class {
   track(eventName, props) {
     safeRun("Client.track", void 0, () => 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) {
-    safeRun("Client.logExposure", void 0, () => this.engine.logExposure(name));
-  }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_client) {
@@ -1925,6 +2027,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 });
@@ -1935,6 +2038,8 @@ var i18n = {
     if (typeof window === "undefined") return () => {
     };
     if (window.i18n) return window.i18n.on("update", cb);
+    if (!hasDomEvents()) return () => {
+    };
     let unsub = () => {
     };
     const handler = () => {