@shipeasy/sdk 4.5.0 → 5.1.0

package/dist/server/index.js

@@ -31,7 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  FLAG_REASONS: () => FLAG_REASONS,
   FlagsClient: () => FlagsClient,
+  _murmur3ForTests: () => _murmur3ForTests,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
   configureShipeasyServer: () => configureShipeasyServer,
   fetchLabelsForSSR: () => fetchLabelsForSSR,
@@ -128,25 +130,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
     });
@@ -227,7 +233,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) {
@@ -310,19 +316,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 "";
@@ -356,6 +364,9 @@ var SeeLimiter = class {
 var version = "4.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
+function _murmur3ForTests(key) {
+  return murmur3(key);
+}
 function murmur3(key) {
   const bytes = new TextEncoder().encode(key);
   const len = bytes.length;
@@ -396,6 +407,14 @@ function murmur3(key) {
   h1 ^= h1 >>> 16;
   return h1 >>> 0;
 }
+var FLAG_REASONS = [
+  "CLIENT_NOT_READY",
+  "FLAG_NOT_FOUND",
+  "OFF",
+  "OVERRIDE",
+  "RULE_MATCH",
+  "DEFAULT"
+];
 function isEnabled(v) {
   return v === 1 || v === true;
 }
@@ -503,7 +522,7 @@ function parseOverrides(rawUrl) {
   }
   return { gates, configs, experiments };
 }
-var FlagsClient = class {
+var FlagsClient = class _FlagsClient {
   apiKey;
   baseUrl;
   env;
@@ -516,47 +535,155 @@ var FlagsClient = class {
   pollInterval = 30;
   timer = null;
   initialized = false;
+  // Test mode: built by `FlagsClient.forTesting()`. When set, init()/initOnce()
+  // never fetch, track() is a no-op, and telemetry is off — the client is a
+  // fully self-contained, network-free seam for unit tests.
+  testMode;
+  // Programmatic overrides (Statsig-style). Set on any client via
+  // overrideFlag/overrideConfig/overrideExperiment; they win over the fetched
+  // blob in getFlag/getConfig/getExperiment. Cleared by clearOverrides().
+  flagOverrides = /* @__PURE__ */ new Map();
+  configOverrides = /* @__PURE__ */ new Map();
+  experimentOverrides = /* @__PURE__ */ new Map();
+  // 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) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.testMode = opts.testMode === true;
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
       sdkKey: this.apiKey,
       side: "server",
       env: this.env,
-      disabled: opts.disableTelemetry
+      // Test mode never talks to the network — telemetry off regardless of opt.
+      disabled: this.testMode || opts.disableTelemetry
     });
-    if (opts.initialBlob) {
-      this.flagsBlob = opts.initialBlob;
+    if (opts.initialBlob || this.testMode) {
+      this.flagsBlob = opts.initialBlob ?? { version: "test", plan: "free", gates: {}, configs: {}, killswitches: {} };
+      this.expsBlob = this.expsBlob ?? { version: "test", universes: {}, experiments: {} };
       this.initialized = true;
     }
   }
+  /**
+   * Build a no-network, immediately-usable client for tests (Statsig-style).
+   * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
+   * is disabled, and the client is already "initialized" — seed every entity
+   * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
+   *
+   * ```ts
+   * const client = FlagsClient.forTesting();
+   * client.overrideFlag("new_checkout", true);
+   * client.getFlag("new_checkout", { user_id: "u1" }); // true
+   * ```
+   */
+  static forTesting(opts) {
+    return new _FlagsClient({ apiKey: "", ...opts, testMode: true });
+  }
+  /**
+   * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
+   * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
+   * telemetry off) but, unlike forTesting(), seeds the REAL flags + experiments
+   * blobs so evaluations run the canonical eval against the snapshot. Local
+   * overrides still apply on top.
+   *
+   * Snapshot shape mirrors the wire bodies:
+   * `{ flags: <GET /sdk/flags body>, experiments: <GET /sdk/experiments body> }`.
+   */
+  static fromSnapshot(snapshot) {
+    const client = new _FlagsClient({ apiKey: "", testMode: true });
+    client.flagsBlob = snapshot.flags;
+    client.expsBlob = snapshot.experiments;
+    client.initialized = true;
+    return client;
+  }
+  /**
+   * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
+   * not available in the browser entrypoint). The file must contain
+   * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
+   * See {@link FlagsClient.fromSnapshot}.
+   */
+  static fromFile(path) {
+    const fs = require("fs");
+    const raw = fs.readFileSync(path, "utf8");
+    const snapshot = JSON.parse(raw);
+    return _FlagsClient.fromSnapshot(snapshot);
+  }
   async init() {
+    if (this.testMode) {
+      this.initialized = true;
+      return;
+    }
     await this.fetchAll();
     this.initialized = true;
     this.startPoll();
   }
   async initOnce() {
-    if (this.initialized) return;
+    if (this.testMode || this.initialized) return;
     await this.fetchAll();
     this.initialized = true;
   }
+  // ---- Local overrides (Statsig-style) ----
+  /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
+  overrideFlag(name, value) {
+    this.flagOverrides.set(name, value);
+  }
+  /** Force `getConfig(name)` to return `value`, ignoring the fetched config. */
+  overrideConfig(name, value) {
+    this.configOverrides.set(name, value);
+  }
+  /**
+   * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+   * ignoring allocation, holdouts, and targeting.
+   */
+  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();
+  }
   destroy() {
     if (this.timer !== null) {
       clearInterval(this.timer);
       this.timer = null;
     }
   }
+  /**
+   * Subscribe to data-change notifications. The listener fires after a
+   * background poll fetch returns NEW data (200, not 304) — i.e. after the
+   * cached blob is updated. Never fires in testMode/offline (no polling).
+   * Returns an unsubscribe function.
+   */
+  onChange(listener) {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+  notifyChange() {
+    for (const l of this.changeListeners) {
+      try {
+        l();
+      } catch (err) {
+        console.warn("[shipeasy] onChange listener threw:", String(err));
+      }
+    }
+  }
   startPoll() {
     this.timer = setInterval(() => {
-      this.fetchAll().catch(
+      this.fetchAll(true).catch(
         (err) => console.warn("[shipeasy] background poll failed:", String(err))
       );
     }, this.pollInterval * 1e3);
   }
-  async fetchAll() {
-    const [interval] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+  async fetchAll(fromPoll = false) {
+    const [flagsRes, expsChanged] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+    const { interval, changed: flagsChanged } = flagsRes;
     if (interval !== null && interval !== this.pollInterval) {
       this.pollInterval = interval;
       if (this.timer !== null) {
@@ -564,41 +691,72 @@ var FlagsClient = class {
         this.startPoll();
       }
     }
+    if (fromPoll && (flagsChanged || expsChanged)) this.notifyChange();
   }
   async fetchFlags() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
     const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags?env=${this.env}`, { headers });
     const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
-    if (res.status === 304) return interval;
+    if (res.status === 304) return { interval, changed: false };
     if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
     const etag = res.headers.get("ETag");
     if (etag) this.flagsEtag = etag;
     this.flagsBlob = await res.json();
-    return interval;
+    return { interval, changed: true };
   }
   async fetchExps() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.expsEtag) headers["If-None-Match"] = this.expsEtag;
     const res = await globalThis.fetch(`${this.baseUrl}/sdk/experiments`, { headers });
-    if (res.status === 304) return;
+    if (res.status === 304) return false;
     if (!res.ok) throw new Error(`/sdk/experiments returned ${res.status}`);
     const etag = res.headers.get("ETag");
     if (etag) this.expsEtag = etag;
     this.expsBlob = await res.json();
+    return true;
   }
-  getFlag(name, user) {
+  /**
+   * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). The
+   * reason is computed entirely at this boundary — the canonical eval
+   * (evalGateInternal) is untouched. A local override short-circuits BEFORE
+   * telemetry, exactly like getFlag's override path; otherwise exactly one
+   * "gate" beacon is emitted.
+   */
+  getFlagDetail(name, user) {
+    const ov = this.flagOverrides.get(name);
+    if (ov !== void 0) return { value: ov, reason: "OVERRIDE" };
     this.telemetry.emit("gate", name);
-    const gate = this.flagsBlob?.gates[name];
-    if (!gate) return false;
-    return evalGateInternal(gate, user);
+    if (!this.flagsBlob) return { value: false, reason: "CLIENT_NOT_READY" };
+    const gate = this.flagsBlob.gates[name];
+    if (!gate) return { value: false, reason: "FLAG_NOT_FOUND" };
+    if (isEnabled(gate.killswitch) || !isEnabled(gate.enabled)) {
+      return { value: false, reason: "OFF" };
+    }
+    const value = evalGateInternal(gate, user);
+    return { value, reason: value ? "RULE_MATCH" : "DEFAULT" };
   }
-  getConfig(name, decode) {
+  /**
+   * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+   * evaluated (client not initialized or flag not found) — never for a gate that
+   * legitimately evaluates to false. Plain `getFlag(name, user)` keeps returning
+   * false for a missing flag.
+   */
+  getFlag(name, user, defaultValue = false) {
+    const d = this.getFlagDetail(name, user);
+    if (d.reason === "CLIENT_NOT_READY" || d.reason === "FLAG_NOT_FOUND") return defaultValue;
+    return d.value;
+  }
+  getConfig(name, decodeOrOpts) {
     this.telemetry.emit("config", name);
-    const entry = this.flagsBlob?.configs[name];
-    if (!entry) return void 0;
-    if (!decode) return entry.value;
-    return decode(entry.value);
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts } : decodeOrOpts ?? {};
+    const has = this.configOverrides.has(name);
+    const raw = has ? this.configOverrides.get(name) : this.flagsBlob?.configs[name]?.value;
+    if (raw === void 0 && !has) {
+      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);
@@ -607,6 +765,16 @@ var FlagsClient = class {
       group: "control",
       params: defaultParams
     };
+    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;
@@ -644,6 +812,7 @@ var FlagsClient = class {
     return notIn;
   }
   track(userId, eventName, props) {
+    if (this.testMode) return;
     const body = JSON.stringify({
       events: [
         {
@@ -978,11 +1147,15 @@ var flags = {
   destroy() {
     _server?.destroy();
   },
-  get(name, user) {
-    return _server?.getFlag(name, user) ?? false;
+  get(name, user, defaultValue = false) {
+    return _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" };
   },
-  getConfig(name, decode) {
-    return _server?.getConfig(name, decode);
+  getConfig(name, decodeOrOpts) {
+    return _server?.getConfig(name, decodeOrOpts);
   },
   getExperiment(name, user, defaultParams, decode) {
     return _server?.getExperiment(name, user, defaultParams, decode) ?? {
@@ -1027,13 +1200,15 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ANON_ID_COOKIE,
+  FLAG_REASONS,
   FlagsClient,
+  _murmur3ForTests,
   _resetShipeasyServerForTests,
   configureShipeasyServer,
   fetchLabelsForSSR,