@shipeasy/sdk 4.5.0 → 5.1.0

package/README.md

@@ -69,12 +69,12 @@ try {
 }
 
 // Non-exception problems — the name is a stable identifier (it participates
-// in the issue fingerprint); variable data goes in .message() / .extras():
+// in the issue fingerprint); all variable data goes in .extras():
 if (rows.length > LIMIT) {
   see.Violation("large query")
-    .message(`got ${rows.length} rows`)
     .causes_the("search results")
-    .to("be trimmed");
+    .to("be trimmed")
+    .extras({ rows: rows.length });
 }
 
 // Expected control-flow exceptions: document them, report nothing —
@@ -82,7 +82,7 @@ if (rows.length > LIMIT) {
 try {
   return decodeFoo(blob);
 } catch (e) {
-  see.ControlFlowException(e, "because it wasn't an encoded Foo");
+  see.ControlFlowException(e).because("because it wasn't an encoded Foo");
   return decodeBar(blob);
 }
 ```
@@ -94,16 +94,19 @@ occurrence timeseries. The chain dispatches on the next microtask — no
 `fetch` on the server), spam-guarded by a 30s dedup window and a per-session
 cap.
 
-The client SDK also auto-captures uncaught exceptions, unhandled rejections,
-and network failures (fetch network errors + 5xx) into the same primitive
-(`autoCollect: { errors }`, on by default). Auto-capture is the outer safety
-net — it does not replace `see()` in catch blocks, where you know the
-consequence and it cannot.
+The client SDK also auto-captures **network failures** (fetch network errors +
+5xx) into the same primitive (`autoCollect: { errors }`, on by default) — each
+names a specific endpoint and a specific outcome. It deliberately does **not**
+blanket-report uncaught exceptions or unhandled promise rejections: those carry
+no actionable consequence ("the page hit an error" names the plumbing, not the
+feature). Code that knows the consequence reports it explicitly with `see()` at
+the catch site.
 
-**Rules**: if you don't know the consequence, don't catch the exception. Never
-`see()` then `throw` (double counting — either handle or rethrow). Never use
-`see.Violation()` for a caught exception (you'd drop the stack). No PII or
-high-cardinality data in extras.
+**Rules**: if you don't know the consequence, don't catch the exception. You
+**may** `see()` then re-throw — the re-thrown error links to its inner report
+as a `caused_by` chain instead of double-counting. Never use `see.Violation()`
+for a caught exception (you'd drop the stack). No PII or high-cardinality data
+in extras.
 
 ## Drop-in `<script>` loader (no bundler)
 
@@ -127,6 +130,164 @@ The loader IIFE is published to a public R2 bucket on every release and
 cached for 1y at `loader-vX.Y.Z.js` (immutable) plus a rolling 5-minute
 `loader.js`.
 
+## Testing
+
+For unit tests, build a **no-network** client with `forTesting()` and seed every
+entity with local overrides (Statsig-style). In test mode the client is already
+"initialized"/"ready", `init()`/`initOnce()`/`identify()` are no-ops (they never
+fetch), `track()` is a no-op, telemetry is disabled, and no SDK key is required —
+so your tests never touch the network.
+
+```ts
+// Server (Node / Cloudflare Worker / Deno)
+import { FlagsClient } from "@shipeasy/sdk/server";
+
+const client = FlagsClient.forTesting();
+
+client.overrideFlag("new_checkout", true);
+client.overrideConfig("upload_limits", { max_uploads: 50 });
+client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
+
+client.getFlag("new_checkout", { user_id: "u1" }); // true
+client.getConfig("upload_limits"); // { max_uploads: 50 }
+client.getExperiment("hero_cta", { user_id: "u1" }, { primary_label: "Sign up" });
+// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
+
+client.track("u1", "purchase"); // no-op — never hits the network
+client.clearOverrides(); // reset every override back to default
+```
+
+```ts
+// Browser (vanilla JS — no React required)
+import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+
+const client = FlagsClientBrowser.forTesting();
+
+client.overrideFlag("new_checkout", true);
+client.overrideConfig("upload_limits", { max_uploads: 50 });
+client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
+
+client.getFlag("new_checkout"); // true
+client.getConfig("upload_limits"); // { max_uploads: 50 }
+client.getExperiment("hero_cta", { primary_label: "Sign up" });
+// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
+
+client.track("purchase"); // no-op
+client.clearOverrides();
+```
+
+The `override*` setters also work on a **normal** client (not just `forTesting()`),
+mirroring Statsig — a programmatic override always wins over the fetched values.
+In the browser the precedence is: programmatic override > URL/devtools override
+(`?se_gate_…` / `?se_config_…` / `?se_exp_…`) > the server's evaluation.
+
+**API:**
+
+```ts
+overrideFlag(name: string, value: boolean): void;
+overrideConfig(name: string, value: unknown): void;
+overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+clearOverrides(): void;
+```
+
+## Default values
+
+`getFlag` / `getConfig` take a caller-supplied default that is returned **only
+when the value can't be evaluated** — the client isn't initialized yet, or the
+key isn't in the loaded rules. A flag that legitimately evaluates to `false`
+(disabled, rule denied, rolled out to 0%) still returns `false`, never the
+default.
+
+```ts
+// Server
+flags.get("new_checkout", { user_id: "u1" });        // false for a missing flag
+flags.get("new_checkout", { user_id: "u1" }, true);  // true only if not-ready/not-found
+flags.getConfig("limits", { defaultValue: { max: 50 } }); // default when key absent
+
+// Browser (no user arg)
+client.getFlag("new_checkout");        // false for a missing flag
+client.getFlag("new_checkout", true);  // default when not-ready/not-found
+client.getConfig("limits", { defaultValue: { max: 50 } });
+```
+
+The legacy `getConfig(name, decode)` callback signature still works unchanged;
+the options object (`{ decode?, defaultValue? }`) is the new, additive form.
+
+## Evaluation detail
+
+`getFlagDetail(name[, user])` returns `{ value, reason }` (LaunchDarkly
+`variationDetail` parity) so you can see *why* a flag resolved the way it did:
+
+```ts
+import type { FlagReason } from "@shipeasy/sdk/server"; // or /client
+
+const d = client.getFlagDetail("new_checkout", { user_id: "u1" });
+// → { value: true, reason: "RULE_MATCH" }
+```
+
+`FlagReason` is one of:
+
+| reason             | meaning                                                     |
+| ------------------ | ---------------------------------------------------------- |
+| `CLIENT_NOT_READY` | no rules loaded yet (`init()` / `identify()` pending)      |
+| `FLAG_NOT_FOUND`   | the gate name isn't in the loaded rules                    |
+| `OFF`              | the gate exists but is disabled / killed (server only)     |
+| `OVERRIDE`         | a local override (or `?se_gate_…` URL override) decided it |
+| `RULE_MATCH`       | the gate evaluated `true`                                  |
+| `DEFAULT`          | the gate evaluated `false`                                 |
+
+`getFlag` is implemented on top of `getFlagDetail` (single evaluation, single
+telemetry beacon). On the browser the server pre-evaluates the gate's
+enabled/killed state into a boolean, so `OFF` folds into `DEFAULT` there.
+
+## Change listeners
+
+The server `FlagsClient` fires registered listeners after a **background poll
+returns new data** (HTTP 200, not 304) — handy for invalidating a cache or
+re-rendering when a flag flips. Returns an unsubscribe function. Never fires in
+test/offline mode (no polling happens):
+
+```ts
+const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+await client.init();
+const unsubscribe = client.onChange(() => {
+  console.log("flag rules changed — re-evaluating");
+});
+// later…
+unsubscribe();
+```
+
+The browser `FlagsClientBrowser` already exposes the equivalent `subscribe()`
+(fires after each `identify()` / override change).
+
+## Offline snapshot
+
+Build a fully offline server client from a captured snapshot — zero network.
+Evaluations run the real eval against the snapshot; `init()`/`initOnce()`/
+`track()` are no-ops and overrides still apply on top. The snapshot is just the
+two SDK wire bodies:
+
+```jsonc
+// snapshot.json
+{
+  "flags":       /* body of GET /sdk/flags */,
+  "experiments": /* body of GET /sdk/experiments */
+}
+```
+
+```ts
+import { FlagsClient } from "@shipeasy/sdk/server";
+
+const client = FlagsClient.fromFile("./snapshot.json");
+// or, if you already hold the parsed object:
+const client = FlagsClient.fromSnapshot({ flags, experiments });
+
+client.getFlag("new_checkout", { user_id: "u1" });
+```
+
+`fromFile` is Node-only (it reads the file with `node:fs`); `fromSnapshot` works
+anywhere.
+
 ## Devtools overlay
 
 Press `Shift+Alt+S` on any page running the SDK (or append `?se=1` to the

package/dist/client/index.d.mts

@@ -8,15 +8,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
@@ -84,9 +82,22 @@ 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 global {
@@ -109,6 +120,33 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary:
+ *   - CLIENT_NOT_READY — no eval result yet (identify() hasn't resolved)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the eval result
+ *   - OFF              — folded into DEFAULT here (the server pre-evaluates the
+ *     gate's enabled/killed state into a plain boolean, so the browser can't
+ *     distinguish a disabled gate from one a rule denied)
+ *   - OVERRIDE         — a local override or a ?se_gate_/?se_ks_ URL override
+ *     decided the value
+ *   - RULE_MATCH       — the gate evaluated true
+ *   - DEFAULT          — the gate evaluated false
+ */
+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 eval result). */
+    defaultValue?: T;
+}
 interface EvalExpResult {
     inExperiment: boolean;
     group: string;
@@ -169,6 +207,13 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Test mode — no network at all. identify()/init are no-ops (never call
+     * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
+     * starts "ready" with an empty eval result. Prefer the
+     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -187,8 +232,26 @@ declare class FlagsClientBrowser {
     private listeners;
     private overrideListenerInstalled;
     private identifySeq;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
+    /**
+     * 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?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
     identify(user: User): Promise<void>;
     /**
      * Report a structured error into the errors primitive. Flushes immediately
@@ -199,8 +262,35 @@ declare class FlagsClientBrowser {
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
-    getFlag(name: string): boolean;
+    /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring URL overrides, the eval result, and exposure logging.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
+    /**
+     * 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: string): FlagDetail;
+    /**
+     * 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: string, 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, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     /**
      * Subscribe to state changes — fires after identify() completes and on
@@ -377,7 +467,9 @@ declare const flags: {
      * Everything else gates on _mountedAndReady to prevent hydration mismatches on
      * force-static pages where SSR has no flag data.
      */
-    get(name: string): boolean;
+    get(name: string, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
@@ -430,28 +522,29 @@ 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 (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +590,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -8,15 +8,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
@@ -84,9 +82,22 @@ 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 global {
@@ -109,6 +120,33 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary:
+ *   - CLIENT_NOT_READY — no eval result yet (identify() hasn't resolved)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the eval result
+ *   - OFF              — folded into DEFAULT here (the server pre-evaluates the
+ *     gate's enabled/killed state into a plain boolean, so the browser can't
+ *     distinguish a disabled gate from one a rule denied)
+ *   - OVERRIDE         — a local override or a ?se_gate_/?se_ks_ URL override
+ *     decided the value
+ *   - RULE_MATCH       — the gate evaluated true
+ *   - DEFAULT          — the gate evaluated false
+ */
+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 eval result). */
+    defaultValue?: T;
+}
 interface EvalExpResult {
     inExperiment: boolean;
     group: string;
@@ -169,6 +207,13 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Test mode — no network at all. identify()/init are no-ops (never call
+     * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
+     * starts "ready" with an empty eval result. Prefer the
+     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -187,8 +232,26 @@ declare class FlagsClientBrowser {
     private listeners;
     private overrideListenerInstalled;
     private identifySeq;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
+    /**
+     * 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?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
     identify(user: User): Promise<void>;
     /**
      * Report a structured error into the errors primitive. Flushes immediately
@@ -199,8 +262,35 @@ declare class FlagsClientBrowser {
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
-    getFlag(name: string): boolean;
+    /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring URL overrides, the eval result, and exposure logging.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
+    /**
+     * 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: string): FlagDetail;
+    /**
+     * 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: string, 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, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     /**
      * Subscribe to state changes — fires after identify() completes and on
@@ -377,7 +467,9 @@ declare const flags: {
      * Everything else gates on _mountedAndReady to prevent hydration mismatches on
      * force-static pages where SSR has no flag data.
      */
-    get(name: string): boolean;
+    get(name: string, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
@@ -430,28 +522,29 @@ 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 (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +590,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };