@shipeasy/sdk 4.5.0 → 5.1.0

package/dist/client/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client/index.ts
 var client_exports = {};
 __export(client_exports, {
+  FLAG_REASONS: () => FLAG_REASONS,
   FlagsClientBrowser: () => FlagsClientBrowser,
   LABEL_MARKER_END: () => LABEL_MARKER_END,
   LABEL_MARKER_RE: () => LABEL_MARKER_RE,
@@ -126,25 +127,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -225,7 +230,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -308,19 +313,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -352,6 +359,14 @@ var SeeLimiter = class {
 
 // src/client/index.ts
 var version = "4.0.0";
+var FLAG_REASONS = [
+  "CLIENT_NOT_READY",
+  "FLAG_NOT_FOUND",
+  "OFF",
+  "OVERRIDE",
+  "RULE_MATCH",
+  "DEFAULT"
+];
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -575,39 +590,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     }
   }
   if (groups.errors) {
-    const origOnError = window.onerror;
-    window.onerror = (msg, source, lineno, _colno, err) => {
-      if (!isExpected(err)) {
-        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
-        reportSee(
-          problem,
-          causesThe("page").to("hit an unhandled error"),
-          {
-            source: typeof source === "string" ? source : void 0,
-            line: lineno ?? void 0
-          },
-          "uncaught"
-        );
-      }
-      if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
-      return false;
-    };
-    window.addEventListener("unhandledrejection", (e) => {
-      const reason = e.reason;
-      if (isExpected(reason)) return;
-      reportSee(
-        reason ?? "Unhandled promise rejection",
-        causesThe("page").to("hit an unhandled promise rejection"),
-        void 0,
-        "unhandled_rejection"
-      );
-    });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
       const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
-      const bareUrl = url.split("?")[0].slice(0, 200);
       let corr;
       if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
         corr = crypto.randomUUID();
@@ -619,7 +606,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       } catch (err) {
         if (!ignored && !isExpected(err)) {
           reportSee(
-            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            violation("NetworkError"),
             causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
@@ -630,7 +617,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
-          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          violation("Http5xx"),
           causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
           "network",
@@ -891,7 +878,7 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class {
+var FlagsClientBrowser = class _FlagsClientBrowser {
   sdkKey;
   baseUrl;
   autoGuardrails;
@@ -910,6 +897,16 @@ var FlagsClientBrowser = class {
   // Monotonic counter so a later identify() always wins even if its /sdk/evaluate
   // response races and lands before an earlier in-flight call's response.
   identifySeq = 0;
+  // Test mode: built by `FlagsClientBrowser.forTesting()`. When set, identify()
+  // never fetches, track() is a no-op, telemetry is off, and the client is
+  // already ready with an empty eval result.
+  testMode;
+  // Programmatic overrides (Statsig-style). Set on any client via
+  // overrideFlag/overrideConfig/overrideExperiment; they win over BOTH the URL
+  // overrides and the fetched eval result. Cleared by clearOverrides().
+  flagOverrides = /* @__PURE__ */ new Map();
+  configOverrides = /* @__PURE__ */ new Map();
+  experimentOverrides = /* @__PURE__ */ new Map();
   onOverrideChange = () => {
     this.installBridge();
     this.notify();
@@ -918,6 +915,7 @@ var FlagsClientBrowser = class {
     this.sdkKey = opts.sdkKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.testMode = opts.testMode === true;
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
     const g = opts.autoGuardrailGroups ?? {};
@@ -933,11 +931,42 @@ var FlagsClientBrowser = class {
       sdkKey: this.sdkKey,
       side: "client",
       env: this.env,
-      disabled: opts.disableTelemetry
+      // Test mode never talks to the network — telemetry off regardless of opt.
+      disabled: this.testMode || opts.disableTelemetry
+    });
+    if (this.testMode) {
+      this.evalResult = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
+    } else {
+      void this.buffer.flushPendingAlias();
+    }
+  }
+  /**
+   * Build a no-network, immediately-usable browser client for tests
+   * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+   * is a no-op, telemetry is disabled, and the client is already ready — seed
+   * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+   * key required.
+   *
+   * ```ts
+   * const client = FlagsClientBrowser.forTesting();
+   * client.overrideFlag("new_checkout", true);
+   * client.getFlag("new_checkout"); // true
+   * ```
+   */
+  static forTesting(opts) {
+    return new _FlagsClientBrowser({
+      sdkKey: "",
+      autoGuardrails: false,
+      ...opts,
+      testMode: true
     });
-    void this.buffer.flushPendingAlias();
   }
   async identify(user) {
+    if (this.testMode) {
+      if (user.user_id !== void 0) this.userId = user.user_id;
+      this.notify();
+      return;
+    }
     const seq = ++this.identifySeq;
     const prevUserId = this.userId;
     if (user.user_id !== void 0) this.userId = user.user_id;
@@ -1012,22 +1041,75 @@ var FlagsClientBrowser = class {
   initFromBootstrap(data) {
     this.evalResult = data;
   }
-  getFlag(name) {
+  // ---- Local overrides (Statsig-style) ----
+  //
+  // Precedence (highest first): programmatic override (these methods) > URL
+  // override (?se_gate_/?se_config_/?se_exp_) > fetched eval result. A
+  // programmatic override is an explicit in-code decision, so it wins over the
+  // ad-hoc URL/devtools overrides as well as the server's evaluation.
+  /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideFlag(name, value) {
+    this.flagOverrides.set(name, value);
+  }
+  /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideConfig(name, value) {
+    this.configOverrides.set(name, value);
+  }
+  /**
+   * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+   * ignoring URL overrides, the eval result, and exposure logging.
+   */
+  overrideExperiment(name, group, params) {
+    this.experimentOverrides.set(name, { group, params });
+  }
+  /** Remove every programmatic override set via the override* methods. */
+  clearOverrides() {
+    this.flagOverrides.clear();
+    this.configOverrides.clear();
+    this.experimentOverrides.clear();
+  }
+  /**
+   * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+   * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+   * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+   * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+   * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+   * denied").
+   */
+  getFlagDetail(name) {
+    const pov = this.flagOverrides.get(name);
+    if (pov !== void 0) return { value: pov, reason: "OVERRIDE" };
+    const urlOv = readGateOverride(name);
+    if (urlOv !== null) return { value: urlOv, reason: "OVERRIDE" };
     this.telemetry.emit("gate", name);
-    if (this.evalResult === null) return false;
-    const ov = readGateOverride(name);
-    if (ov !== null) return ov;
-    return this.evalResult.flags[name] ?? false;
+    if (this.evalResult === null) return { value: false, reason: "CLIENT_NOT_READY" };
+    if (!(name in this.evalResult.flags)) return { value: false, reason: "FLAG_NOT_FOUND" };
+    const value = this.evalResult.flags[name] ?? false;
+    return { value, reason: value ? "RULE_MATCH" : "DEFAULT" };
   }
-  getConfig(name, decode) {
+  /**
+   * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+   * evaluated (not ready or flag not found) — never for a gate that legitimately
+   * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+   * missing flag.
+   */
+  getFlag(name, defaultValue = false) {
+    const d = this.getFlagDetail(name);
+    if (d.reason === "CLIENT_NOT_READY" || d.reason === "FLAG_NOT_FOUND") return defaultValue;
+    return d.value;
+  }
+  getConfig(name, decodeOrOpts) {
     this.telemetry.emit("config", name);
-    if (this.evalResult === null) return void 0;
-    const ov = readConfigOverride(name);
-    const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
-    if (raw === void 0) return void 0;
-    if (!decode) return raw;
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts } : decodeOrOpts ?? {};
+    const fallback = "defaultValue" in opts ? opts.defaultValue : void 0;
+    const hasProgrammatic = this.configOverrides.has(name);
+    if (!hasProgrammatic && this.evalResult === null) return fallback;
+    const urlOv = hasProgrammatic ? void 0 : readConfigOverride(name);
+    const raw = hasProgrammatic ? this.configOverrides.get(name) : urlOv !== void 0 ? urlOv : this.evalResult?.configs?.[name];
+    if (raw === void 0) return fallback;
+    if (!opts.decode) return raw;
     try {
-      return decode(raw);
+      return opts.decode(raw);
     } catch (err) {
       console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
       return void 0;
@@ -1040,6 +1122,12 @@ var FlagsClientBrowser = class {
       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 ov = readExpOverride(name);
     if (ov !== null) {
       const variantParams = variants?.[ov];
@@ -1091,6 +1179,7 @@ var FlagsClientBrowser = class {
     return bridge;
   }
   track(eventName, props) {
+    if (this.testMode) return;
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
   /**
@@ -1309,12 +1398,19 @@ var flags = {
    * Everything else gates on _mountedAndReady to prevent hydration mismatches on
    * force-static pages where SSR has no flag data.
    */
-  get(name) {
+  get(name, defaultValue = false) {
     const bs = getBootstrap();
     if (bs !== null && name in bs.flags) return bs.flags[name];
-    if (!_mountedAndReady) return false;
-    if (_client) return _client.getFlag(name);
-    return readGateOverride(name) ?? false;
+    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" };
   },
   getConfig(name, decode) {
     const bs = getBootstrap();
@@ -1409,7 +1505,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 var LABEL_MARKER_START = "\uFFF9";
@@ -1646,6 +1742,7 @@ var i18n = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FLAG_REASONS,
   FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,