@shipeasy/sdk 4.5.0 → 5.1.0

package/dist/client/index.mjs

@@ -78,25 +78,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
     });
@@ -177,7 +181,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) {
@@ -260,19 +264,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 "";
@@ -304,6 +310,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";
@@ -527,39 +541,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();
@@ -571,7 +557,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"
@@ -582,7 +568,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",
@@ -843,7 +829,7 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class {
+var FlagsClientBrowser = class _FlagsClientBrowser {
   sdkKey;
   baseUrl;
   autoGuardrails;
@@ -862,6 +848,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();
@@ -870,6 +866,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 ?? {};
@@ -885,11 +882,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;
@@ -964,22 +992,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;
@@ -992,6 +1073,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];
@@ -1043,6 +1130,7 @@ var FlagsClientBrowser = class {
     return bridge;
   }
   track(eventName, props) {
+    if (this.testMode) return;
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
   /**
@@ -1261,12 +1349,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();
@@ -1361,7 +1456,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";
@@ -1597,6 +1692,7 @@ var i18n = {
   }
 };
 export {
+  FLAG_REASONS,
   FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,

package/dist/server/index.d.mts

@@ -10,15 +10,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -87,12 +85,33 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare const version = "4.0.0";
+/**
+ * @internal Exported ONLY so the cross-language eval-parity golden-vector test
+ * (src/__tests__/eval-vectors.test.ts) can assert the raw unsigned-32-bit hash
+ * against the canonical fixture. Not part of the public SDK surface — do not
+ * rely on it in product code; the bucketing contract lives behind getFlag /
+ * getExperiment. Name-prefixed with `_` to signal "test seam, not API".
+ */
+declare function _murmur3ForTests(key: string): number;
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -103,6 +122,30 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary, never inside the canonical eval:
+ *   - CLIENT_NOT_READY — no rules blob loaded yet (init()/initOnce() pending)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the loaded blob
+ *   - OFF              — the gate exists but is disabled / killed
+ *   - OVERRIDE         — a local override (overrideFlag) decided the value
+ *   - RULE_MATCH       — the gate evaluated true (rules + rollout passed)
+ *   - DEFAULT          — the gate evaluated false (a rule or the rollout denied)
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the blob). */
+    defaultValue?: T;
+}
 interface GateRule {
     attr: string;
     op: "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "regex";
@@ -115,10 +158,27 @@ interface Gate {
     enabled: 0 | 1 | boolean;
     killswitch?: 0 | 1 | boolean;
 }
+interface ExperimentGroup {
+    name: string;
+    weight: number;
+    params: Record<string, unknown>;
+}
+interface Experiment {
+    universe: string;
+    targetingGate?: string | null;
+    allocationPct: number;
+    salt: string;
+    groups: ExperimentGroup[];
+    status: "draft" | "running" | "stopped" | "archived";
+}
+interface Universe {
+    holdout_range: [number, number] | null;
+}
 interface Killswitch {
     killed: 0 | 1 | boolean;
     switches?: Record<string, 0 | 1 | boolean>;
 }
+/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link FlagsClient.fromSnapshot}. */
 interface FlagsBlob {
     version: string;
     plan: string;
@@ -128,6 +188,12 @@ interface FlagsBlob {
     }>;
     killswitches: Record<string, Killswitch>;
 }
+/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link FlagsClient.fromSnapshot}. */
+interface ExpsBlob {
+    version: string;
+    universes: Record<string, Universe>;
+    experiments: Record<string, Experiment>;
+}
 interface BootstrapPayload {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
@@ -157,6 +223,13 @@ interface FlagsClientOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Test mode — no network at all. init()/initOnce() are no-ops (never fetch),
+     * track() is a no-op, telemetry is forced off, and the client starts
+     * "initialized" with an empty blob. Prefer the {@link FlagsClient.forTesting}
+     * factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClient {
     private readonly apiKey;
@@ -171,16 +244,89 @@ declare class FlagsClient {
     private pollInterval;
     private timer;
     private initialized;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
+    private readonly changeListeners;
     constructor(opts: FlagsClientOptions);
+    /**
+     * 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?: Partial<FlagsClientOptions>): FlagsClient;
+    /**
+     * 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: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    }): FlagsClient;
+    /**
+     * 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: string): FlagsClient;
     init(): Promise<void>;
     initOnce(): Promise<void>;
+    /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring the fetched config. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring allocation, holdouts, and targeting.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
     destroy(): void;
+    /**
+     * 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: () => void): () => void;
+    private notifyChange;
     private startPoll;
     private fetchAll;
     private fetchFlags;
     private fetchExps;
-    getFlag(name: string, user: User): boolean;
+    /**
+     * 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: string, user: User): FlagDetail;
+    /**
+     * 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: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
@@ -327,8 +473,10 @@ declare const flags: {
     initOnce(): Promise<void>;
     /** Stop background timers. Safe to call repeatedly. */
     destroy(): void;
-    get(name: string, user: User): boolean;
-    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    get(name: string, user: User, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string, user: User): FlagDetail;
+    getConfig<T = unknown>(name: string, decodeOrOpts?: ((raw: unknown) => T) | GetConfigOptions<T>): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the whole
@@ -367,20 +515,26 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (results.length > LIMIT) {
-     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: results.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — documents the expectation and
-     * reports nothing. The reason must start with "because".
+     * reports nothing. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
+     *
+     * ```ts
+     * see.ControlFlowException(e).because("because the metric may not exist yet");
+     * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -389,4 +543,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type GetConfigOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _murmur3ForTests, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };