@shipeasy/sdk 5.0.0 → 5.2.0

package/README.md

@@ -130,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

@@ -120,6 +120,47 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/** Options object form of `getExperiment` — the legacy `decode`/`variants`
+ *  positional args plus per-call exposure control. */
+interface GetExperimentOptions<P> {
+    /** Decode the raw stored params into the typed shape callers want. */
+    decode?: (raw: unknown) => P;
+    /** Variant-specific param overrides merged on top of group params. */
+    variants?: Record<string, Partial<P>>;
+    /**
+     * Override automatic exposure logging for this read. Defaults to the client's
+     * setting (`disableAutoExposure` flips it). `false` reads the variant without
+     * logging an exposure — pair with `logExposure(name)` at render time.
+     */
+    logExposure?: boolean;
+}
+/**
+ * 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;
@@ -135,6 +176,17 @@ interface EvalResponse {
      * switch booleans.
      */
     killswitches?: Record<string, boolean | Record<string, boolean>>;
+    /**
+     * Newly-assigned sticky entries (doc 20 §2). The worker returns these so the
+     * browser can merge them into the `__se_sticky` cookie. Present only when
+     * sticky bucketing is on and at least one assignment was made/refreshed.
+     */
+    sticky?: Record<string, StickyCookieEntry>;
+}
+/** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
+interface StickyCookieEntry {
+    g: string;
+    s: string;
 }
 interface AutoCollectGroups {
     vitals: boolean;
@@ -180,6 +232,36 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Suppress automatic exposure logging in `getExperiment` (Statsig's
+     * `disableExposureLogging`). Default false — reading an enrolled variant
+     * auto-logs a deduped exposure. When true, no exposure fires unless you call
+     * `logExposure(name)` yourself, or pass `{ logExposure: true }` per call.
+     */
+    disableAutoExposure?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). They are sent to `/sdk/evaluate` under
+     * `private_attributes` so the edge can evaluate with them (unavoidable —
+     * the edge evaluates), but the worker never stores them, and the listed keys
+     * are stripped from any `track(props)` payload.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky bucketing (doc 20 §2). ON by default in the browser: a unit's
+     * first-assigned variant is locked in the `__se_sticky` cookie so changing an
+     * experiment's allocation % or group weights never silently re-buckets
+     * enrolled users. Changing the experiment salt is the deliberate reshuffle
+     * lever. Pass `false` to opt out (pure deterministic eval).
+     */
+    stickyBucketing?: boolean;
+    /**
+     * 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,6 +269,9 @@ declare class FlagsClientBrowser {
     private readonly autoGuardrails;
     private readonly autoGuardrailGroups;
     private readonly autoCollectAlways;
+    private readonly disableAutoExposure;
+    private readonly privateAttributes;
+    private readonly stickyBucketing;
     private readonly env;
     private evalResult;
     private anonId;
@@ -198,8 +283,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
@@ -210,9 +313,45 @@ 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>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, opts: GetExperimentOptions<P>): ExperimentResult<P>;
+    /**
+     * Manually log an exposure for an enrolled experiment (Statsig's
+     * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
+     * the experiment, pushes the session-deduped exposure. Pair this with the
+     * render of the treatment when reading with `{ logExposure: false }` (or
+     * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
+     */
+    logExposure(name: string): void;
     /**
      * Subscribe to state changes — fires after identify() completes and on
      * `se:override:change` events from the devtools overlay. Returns an
@@ -225,6 +364,8 @@ declare class FlagsClientBrowser {
      */
     installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /** Drop caller-marked private attributes from an outbound props bag. */
+    private stripPrivate;
     /**
      * Read a killswitch from the server's evaluated state. Without `switchKey`,
      * returns true when the killswitch is whole-killed. With `switchKey`, returns
@@ -333,6 +474,25 @@ interface ShipeasyClientConfig {
      * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
      */
     disableTelemetry?: boolean;
+    /**
+     * Suppress automatic exposure logging in `flags.getExperiment` (Statsig's
+     * `disableExposureLogging`). Default false. When true, call
+     * `flags.logExposure(name)` at the treatment's render to log the exposure.
+     */
+    disableAutoExposure?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). Sent to the edge for evaluation, never
+     * stored, and stripped from `flags.track(props)`. See
+     * {@link FlagsClientBrowserOptions.privateAttributes}.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky bucketing (doc 20 §2). ON by default — locks each enrolled unit to
+     * its first-assigned variant via the `__se_sticky` cookie. Pass `false` to
+     * opt out. See {@link FlagsClientBrowserOptions.stickyBucketing}.
+     */
+    stickyBucketing?: boolean;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.
@@ -388,9 +548,14 @@ 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>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decodeOrOpts?: ((raw: unknown) => P) | GetExperimentOptions<P>, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    /** Manually log an exposure for an enrolled experiment. See
+     *  {@link FlagsClientBrowser.logExposure}. No-op before configure(). */
+    logExposure(name: string): void;
     track(eventName: string, props?: Record<string, unknown>): void;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -509,4 +674,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 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 };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type GetExperimentOptions, 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

@@ -120,6 +120,47 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/** Options object form of `getExperiment` — the legacy `decode`/`variants`
+ *  positional args plus per-call exposure control. */
+interface GetExperimentOptions<P> {
+    /** Decode the raw stored params into the typed shape callers want. */
+    decode?: (raw: unknown) => P;
+    /** Variant-specific param overrides merged on top of group params. */
+    variants?: Record<string, Partial<P>>;
+    /**
+     * Override automatic exposure logging for this read. Defaults to the client's
+     * setting (`disableAutoExposure` flips it). `false` reads the variant without
+     * logging an exposure — pair with `logExposure(name)` at render time.
+     */
+    logExposure?: boolean;
+}
+/**
+ * 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;
@@ -135,6 +176,17 @@ interface EvalResponse {
      * switch booleans.
      */
     killswitches?: Record<string, boolean | Record<string, boolean>>;
+    /**
+     * Newly-assigned sticky entries (doc 20 §2). The worker returns these so the
+     * browser can merge them into the `__se_sticky` cookie. Present only when
+     * sticky bucketing is on and at least one assignment was made/refreshed.
+     */
+    sticky?: Record<string, StickyCookieEntry>;
+}
+/** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
+interface StickyCookieEntry {
+    g: string;
+    s: string;
 }
 interface AutoCollectGroups {
     vitals: boolean;
@@ -180,6 +232,36 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Suppress automatic exposure logging in `getExperiment` (Statsig's
+     * `disableExposureLogging`). Default false — reading an enrolled variant
+     * auto-logs a deduped exposure. When true, no exposure fires unless you call
+     * `logExposure(name)` yourself, or pass `{ logExposure: true }` per call.
+     */
+    disableAutoExposure?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). They are sent to `/sdk/evaluate` under
+     * `private_attributes` so the edge can evaluate with them (unavoidable —
+     * the edge evaluates), but the worker never stores them, and the listed keys
+     * are stripped from any `track(props)` payload.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky bucketing (doc 20 §2). ON by default in the browser: a unit's
+     * first-assigned variant is locked in the `__se_sticky` cookie so changing an
+     * experiment's allocation % or group weights never silently re-buckets
+     * enrolled users. Changing the experiment salt is the deliberate reshuffle
+     * lever. Pass `false` to opt out (pure deterministic eval).
+     */
+    stickyBucketing?: boolean;
+    /**
+     * 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,6 +269,9 @@ declare class FlagsClientBrowser {
     private readonly autoGuardrails;
     private readonly autoGuardrailGroups;
     private readonly autoCollectAlways;
+    private readonly disableAutoExposure;
+    private readonly privateAttributes;
+    private readonly stickyBucketing;
     private readonly env;
     private evalResult;
     private anonId;
@@ -198,8 +283,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
@@ -210,9 +313,45 @@ 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>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, opts: GetExperimentOptions<P>): ExperimentResult<P>;
+    /**
+     * Manually log an exposure for an enrolled experiment (Statsig's
+     * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
+     * the experiment, pushes the session-deduped exposure. Pair this with the
+     * render of the treatment when reading with `{ logExposure: false }` (or
+     * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
+     */
+    logExposure(name: string): void;
     /**
      * Subscribe to state changes — fires after identify() completes and on
      * `se:override:change` events from the devtools overlay. Returns an
@@ -225,6 +364,8 @@ declare class FlagsClientBrowser {
      */
     installBridge(): ShipeasySdkBridge | null;
     track(eventName: string, props?: Record<string, unknown>): void;
+    /** Drop caller-marked private attributes from an outbound props bag. */
+    private stripPrivate;
     /**
      * Read a killswitch from the server's evaluated state. Without `switchKey`,
      * returns true when the killswitch is whole-killed. With `switchKey`, returns
@@ -333,6 +474,25 @@ interface ShipeasyClientConfig {
      * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
      */
     disableTelemetry?: boolean;
+    /**
+     * Suppress automatic exposure logging in `flags.getExperiment` (Statsig's
+     * `disableExposureLogging`). Default false. When true, call
+     * `flags.logExposure(name)` at the treatment's render to log the exposure.
+     */
+    disableAutoExposure?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). Sent to the edge for evaluation, never
+     * stored, and stripped from `flags.track(props)`. See
+     * {@link FlagsClientBrowserOptions.privateAttributes}.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky bucketing (doc 20 §2). ON by default — locks each enrolled unit to
+     * its first-assigned variant via the `__se_sticky` cookie. Pass `false` to
+     * opt out. See {@link FlagsClientBrowserOptions.stickyBucketing}.
+     */
+    stickyBucketing?: boolean;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.
@@ -388,9 +548,14 @@ 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>;
+    getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decodeOrOpts?: ((raw: unknown) => P) | GetExperimentOptions<P>, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
+    /** Manually log an exposure for an enrolled experiment. See
+     *  {@link FlagsClientBrowser.logExposure}. No-op before configure(). */
+    logExposure(name: string): void;
     track(eventName: string, props?: Record<string, unknown>): void;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -509,4 +674,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 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 };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type GetExperimentOptions, 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 };