@shipeasy/sdk 5.1.0 → 5.3.0

package/dist/client/index.d.mts

@@ -120,6 +120,20 @@ 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:
@@ -162,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;
@@ -207,6 +232,29 @@ 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
@@ -221,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;
@@ -292,6 +343,15 @@ declare class FlagsClientBrowser {
     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
@@ -304,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
@@ -412,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.
@@ -471,7 +552,10 @@ declare const flags: {
     /** 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
@@ -590,4 +674,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-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 };
+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,20 @@ 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:
@@ -162,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;
@@ -207,6 +232,29 @@ 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
@@ -221,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;
@@ -292,6 +343,15 @@ declare class FlagsClientBrowser {
     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
@@ -304,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
@@ -412,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.
@@ -471,7 +552,10 @@ declare const flags: {
     /** 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
@@ -590,4 +674,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-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 };
+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.js

@@ -731,6 +731,40 @@ function writeAnonCookie(id) {
   } catch {
   }
 }
+var STICKY_COOKIE = "__se_sticky";
+var STICKY_MAX_BYTES = 3800;
+function readStickyCookie() {
+  try {
+    const m = ("; " + document.cookie).match(/; __se_sticky=([^;]+)/);
+    if (!m) return {};
+    const parsed = JSON.parse(decodeURIComponent(m[1]));
+    if (!parsed || typeof parsed !== "object") return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (v && typeof v === "object" && typeof v.g === "string") {
+        out[k] = { g: v.g, s: String(v.s ?? "") };
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function writeStickyCookie(map) {
+  try {
+    let json = JSON.stringify(map);
+    if (json.length > STICKY_MAX_BYTES) {
+      const entries = Object.entries(map);
+      while (entries.length > 0 && JSON.stringify(Object.fromEntries(entries)).length > STICKY_MAX_BYTES) {
+        entries.shift();
+      }
+      json = JSON.stringify(Object.fromEntries(entries));
+    }
+    const secure = location.protocol === "https:" ? ";secure" : "";
+    document.cookie = `${STICKY_COOKIE}=${encodeURIComponent(json)};path=/;max-age=31536000;samesite=lax${secure}`;
+  } catch {
+  }
+}
 function getOrCreateAnonId() {
   let id = readAnonCookie();
   if (!id && typeof window !== "undefined") {
@@ -884,6 +918,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   autoGuardrails;
   autoGuardrailGroups;
   autoCollectAlways;
+  disableAutoExposure;
+  privateAttributes;
+  stickyBucketing;
   env;
   evalResult = null;
   anonId;
@@ -918,6 +955,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
     this.testMode = opts.testMode === true;
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
+    this.disableAutoExposure = opts.disableAutoExposure === true;
+    this.privateAttributes = opts.privateAttributes ?? [];
+    this.stickyBucketing = opts.stickyBucketing !== false;
     const g = opts.autoGuardrailGroups ?? {};
     this.autoGuardrailGroups = {
       vitals: g.vitals ?? this.autoGuardrails,
@@ -983,13 +1023,22 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
       body: JSON.stringify({
         user: userPayload,
-        experiment_overrides: readExperimentOverridesFromUrl()
+        experiment_overrides: readExperimentOverridesFromUrl(),
+        // Private attributes still reach the edge for evaluation (unavoidable —
+        // the edge evaluates), but the worker never persists them. See doc 20 §5.
+        ...this.privateAttributes.length > 0 ? { private_attributes: [...this.privateAttributes] } : {},
+        // Sticky state round-trip: send the current cookie map; the worker
+        // applies the sticky short-circuit and returns any new assignments.
+        ...this.stickyBucketing ? { sticky: readStickyCookie() } : {}
       })
     });
     if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
     const data = await res.json();
     if (seq !== this.identifySeq) return;
     this.evalResult = data;
+    if (this.stickyBucketing && data.sticky && Object.keys(data.sticky).length > 0) {
+      writeStickyCookie({ ...readStickyCookie(), ...data.sticky });
+    }
     const anyGroupOn = this.autoGuardrailGroups.vitals || this.autoGuardrailGroups.errors || this.autoGuardrailGroups.engagement;
     if (anyGroupOn && !this.guardrailsInstalled) {
       this.guardrailsInstalled = true;
@@ -1115,7 +1164,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       return void 0;
     }
   }
-  getExperiment(name, defaultParams, decode, variants) {
+  getExperiment(name, defaultParams, decodeOrOpts, variantsArg) {
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts, variants: variantsArg } : decodeOrOpts ?? {};
+    const { decode, variants } = opts;
     this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
@@ -1136,7 +1187,8 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
     }
     const entry = this.evalResult?.experiments[name];
     if (!entry || !entry.inExperiment) return notIn;
-    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    const shouldLog = opts.logExposure ?? !this.disableAutoExposure;
+    if (shouldLog) this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
     if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
     try {
       return { inExperiment: true, group: entry.group, params: decode(entry.params) };
@@ -1145,6 +1197,18 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       return notIn;
     }
   }
+  /**
+   * 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) {
+    const entry = this.evalResult?.experiments[name];
+    if (!entry || !entry.inExperiment) return;
+    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+  }
   /**
    * Subscribe to state changes — fires after identify() completes and on
    * `se:override:change` events from the devtools overlay. Returns an
@@ -1180,7 +1244,16 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   }
   track(eventName, props) {
     if (this.testMode) return;
-    this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
+    this.buffer.pushMetric(eventName, this.userId, this.anonId, this.stripPrivate(props));
+  }
+  /** Drop caller-marked private attributes from an outbound props bag. */
+  stripPrivate(props) {
+    if (!props || this.privateAttributes.length === 0) return props;
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (!this.privateAttributes.includes(k)) out[k] = v;
+    }
+    return out;
   }
   /**
    * Read a killswitch from the server's evaluated state. Without `switchKey`,
@@ -1326,7 +1399,10 @@ function shipeasy(opts) {
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
-    disableTelemetry: opts.disableTelemetry
+    disableTelemetry: opts.disableTelemetry,
+    disableAutoExposure: opts.disableAutoExposure,
+    privateAttributes: opts.privateAttributes,
+    stickyBucketing: opts.stickyBucketing
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
@@ -1434,12 +1510,19 @@ var flags = {
       return void 0;
     }
   },
-  getExperiment(name, defaultParams, decode, variants) {
-    return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
+  getExperiment(name, defaultParams, decodeOrOpts, variants) {
+    const fallback = {
       inExperiment: false,
       group: "control",
       params: defaultParams
     };
+    if (!_client) return fallback;
+    return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
+  },
+  /** Manually log an exposure for an enrolled experiment. See
+   *  {@link FlagsClientBrowser.logExposure}. No-op before configure(). */
+  logExposure(name) {
+    _client?.logExposure(name);
   },
   track(eventName, props) {
     _client?.track(eventName, props);

package/dist/client/index.mjs

@@ -682,6 +682,40 @@ function writeAnonCookie(id) {
   } catch {
   }
 }
+var STICKY_COOKIE = "__se_sticky";
+var STICKY_MAX_BYTES = 3800;
+function readStickyCookie() {
+  try {
+    const m = ("; " + document.cookie).match(/; __se_sticky=([^;]+)/);
+    if (!m) return {};
+    const parsed = JSON.parse(decodeURIComponent(m[1]));
+    if (!parsed || typeof parsed !== "object") return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (v && typeof v === "object" && typeof v.g === "string") {
+        out[k] = { g: v.g, s: String(v.s ?? "") };
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function writeStickyCookie(map) {
+  try {
+    let json = JSON.stringify(map);
+    if (json.length > STICKY_MAX_BYTES) {
+      const entries = Object.entries(map);
+      while (entries.length > 0 && JSON.stringify(Object.fromEntries(entries)).length > STICKY_MAX_BYTES) {
+        entries.shift();
+      }
+      json = JSON.stringify(Object.fromEntries(entries));
+    }
+    const secure = location.protocol === "https:" ? ";secure" : "";
+    document.cookie = `${STICKY_COOKIE}=${encodeURIComponent(json)};path=/;max-age=31536000;samesite=lax${secure}`;
+  } catch {
+  }
+}
 function getOrCreateAnonId() {
   let id = readAnonCookie();
   if (!id && typeof window !== "undefined") {
@@ -835,6 +869,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   autoGuardrails;
   autoGuardrailGroups;
   autoCollectAlways;
+  disableAutoExposure;
+  privateAttributes;
+  stickyBucketing;
   env;
   evalResult = null;
   anonId;
@@ -869,6 +906,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
     this.testMode = opts.testMode === true;
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
+    this.disableAutoExposure = opts.disableAutoExposure === true;
+    this.privateAttributes = opts.privateAttributes ?? [];
+    this.stickyBucketing = opts.stickyBucketing !== false;
     const g = opts.autoGuardrailGroups ?? {};
     this.autoGuardrailGroups = {
       vitals: g.vitals ?? this.autoGuardrails,
@@ -934,13 +974,22 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
       body: JSON.stringify({
         user: userPayload,
-        experiment_overrides: readExperimentOverridesFromUrl()
+        experiment_overrides: readExperimentOverridesFromUrl(),
+        // Private attributes still reach the edge for evaluation (unavoidable —
+        // the edge evaluates), but the worker never persists them. See doc 20 §5.
+        ...this.privateAttributes.length > 0 ? { private_attributes: [...this.privateAttributes] } : {},
+        // Sticky state round-trip: send the current cookie map; the worker
+        // applies the sticky short-circuit and returns any new assignments.
+        ...this.stickyBucketing ? { sticky: readStickyCookie() } : {}
       })
     });
     if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
     const data = await res.json();
     if (seq !== this.identifySeq) return;
     this.evalResult = data;
+    if (this.stickyBucketing && data.sticky && Object.keys(data.sticky).length > 0) {
+      writeStickyCookie({ ...readStickyCookie(), ...data.sticky });
+    }
     const anyGroupOn = this.autoGuardrailGroups.vitals || this.autoGuardrailGroups.errors || this.autoGuardrailGroups.engagement;
     if (anyGroupOn && !this.guardrailsInstalled) {
       this.guardrailsInstalled = true;
@@ -1066,7 +1115,9 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       return void 0;
     }
   }
-  getExperiment(name, defaultParams, decode, variants) {
+  getExperiment(name, defaultParams, decodeOrOpts, variantsArg) {
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts, variants: variantsArg } : decodeOrOpts ?? {};
+    const { decode, variants } = opts;
     this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
@@ -1087,7 +1138,8 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
     }
     const entry = this.evalResult?.experiments[name];
     if (!entry || !entry.inExperiment) return notIn;
-    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    const shouldLog = opts.logExposure ?? !this.disableAutoExposure;
+    if (shouldLog) this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
     if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
     try {
       return { inExperiment: true, group: entry.group, params: decode(entry.params) };
@@ -1096,6 +1148,18 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
       return notIn;
     }
   }
+  /**
+   * 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) {
+    const entry = this.evalResult?.experiments[name];
+    if (!entry || !entry.inExperiment) return;
+    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+  }
   /**
    * Subscribe to state changes — fires after identify() completes and on
    * `se:override:change` events from the devtools overlay. Returns an
@@ -1131,7 +1195,16 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   }
   track(eventName, props) {
     if (this.testMode) return;
-    this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
+    this.buffer.pushMetric(eventName, this.userId, this.anonId, this.stripPrivate(props));
+  }
+  /** Drop caller-marked private attributes from an outbound props bag. */
+  stripPrivate(props) {
+    if (!props || this.privateAttributes.length === 0) return props;
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (!this.privateAttributes.includes(k)) out[k] = v;
+    }
+    return out;
   }
   /**
    * Read a killswitch from the server's evaluated state. Without `switchKey`,
@@ -1277,7 +1350,10 @@ function shipeasy(opts) {
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
-    disableTelemetry: opts.disableTelemetry
+    disableTelemetry: opts.disableTelemetry,
+    disableAutoExposure: opts.disableAutoExposure,
+    privateAttributes: opts.privateAttributes,
+    stickyBucketing: opts.stickyBucketing
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
@@ -1385,12 +1461,19 @@ var flags = {
       return void 0;
     }
   },
-  getExperiment(name, defaultParams, decode, variants) {
-    return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
+  getExperiment(name, defaultParams, decodeOrOpts, variants) {
+    const fallback = {
       inExperiment: false,
       group: "control",
       params: defaultParams
     };
+    if (!_client) return fallback;
+    return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
+  },
+  /** Manually log an exposure for an enrolled experiment. See
+   *  {@link FlagsClientBrowser.logExposure}. No-op before configure(). */
+  logExposure(name) {
+    _client?.logExposure(name);
   },
   track(eventName, props) {
     _client?.track(eventName, props);