@shipeasy/sdk 5.0.0 → 5.2.0

package/dist/server/index.d.mts

@@ -104,6 +104,14 @@ interface SeeControlFlowChain {
 }
 
 declare const version = "4.0.0";
+/**
+ * @internal Exported ONLY so the cross-language eval-parity golden-vector test
+ * (src/__tests__/eval-vectors.test.ts) can assert the raw unsigned-32-bit hash
+ * against the canonical fixture. Not part of the public SDK surface — do not
+ * rely on it in product code; the bucketing contract lives behind getFlag /
+ * getExperiment. Name-prefixed with `_` to signal "test seam, not API".
+ */
+declare function _murmur3ForTests(key: string): number;
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -114,6 +122,30 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary, never inside the canonical eval:
+ *   - CLIENT_NOT_READY — no rules blob loaded yet (init()/initOnce() pending)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the loaded blob
+ *   - OFF              — the gate exists but is disabled / killed
+ *   - OVERRIDE         — a local override (overrideFlag) decided the value
+ *   - RULE_MATCH       — the gate evaluated true (rules + rollout passed)
+ *   - DEFAULT          — the gate evaluated false (a rule or the rollout denied)
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the blob). */
+    defaultValue?: T;
+}
 interface GateRule {
     attr: string;
     op: "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "regex";
@@ -126,10 +158,47 @@ interface Gate {
     enabled: 0 | 1 | boolean;
     killswitch?: 0 | 1 | boolean;
 }
+interface ExperimentGroup {
+    name: string;
+    weight: number;
+    params: Record<string, unknown>;
+}
+interface Experiment {
+    universe: string;
+    targetingGate?: string | null;
+    allocationPct: number;
+    salt: string;
+    groups: ExperimentGroup[];
+    status: "draft" | "running" | "stopped" | "archived";
+    /** Attribute to bucket on (e.g. company_id); defaults to user_id/anonymous_id. */
+    bucketBy?: string | null;
+}
+/** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
+interface StickyEntry {
+    g: string;
+    s: string;
+}
+/**
+ * Pluggable sticky-bucketing store for the server (doc 20 §2). Keyed by the
+ * bucketing unit; the value is that unit's per-experiment assignments. Absent
+ * from {@link FlagsClientOptions} ⇒ today's deterministic behaviour. Use
+ * {@link createInMemoryStickyStore} or a cookie-bridge built from request
+ * cookies.
+ */
+interface StickyBucketStore {
+    get(unit: string): Record<string, StickyEntry> | undefined;
+    set(unit: string, exp: string, entry: StickyEntry): void;
+}
+/** A process-local sticky store (Map-backed). Handy for tests + single-process servers. */
+declare function createInMemoryStickyStore(seed?: Record<string, Record<string, StickyEntry>>): StickyBucketStore;
+interface Universe {
+    holdout_range: [number, number] | null;
+}
 interface Killswitch {
     killed: 0 | 1 | boolean;
     switches?: Record<string, 0 | 1 | boolean>;
 }
+/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link FlagsClient.fromSnapshot}. */
 interface FlagsBlob {
     version: string;
     plan: string;
@@ -139,6 +208,12 @@ interface FlagsBlob {
     }>;
     killswitches: Record<string, Killswitch>;
 }
+/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link FlagsClient.fromSnapshot}. */
+interface ExpsBlob {
+    version: string;
+    universes: Record<string, Universe>;
+    experiments: Record<string, Experiment>;
+}
 interface BootstrapPayload {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
@@ -168,11 +243,35 @@ interface FlagsClientOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). The server evaluates locally so private
+     * attrs never leave for evaluation at all; the only egress is `/collect`, and
+     * the listed keys are stripped from every outbound `track()` payload.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky-bucketing store (doc 20 §2). When provided, `getExperiment` locks a
+     * unit to its first-assigned variant — changing allocation % or weights won't
+     * re-bucket enrolled units (changing the experiment salt is the reshuffle
+     * lever). Absent ⇒ deterministic (fully backward compatible). Built-ins:
+     * {@link createInMemoryStickyStore}, or a cookie-bridge over `__se_sticky`.
+     */
+    stickyStore?: StickyBucketStore;
+    /**
+     * Test mode — no network at all. init()/initOnce() are no-ops (never fetch),
+     * track() is a no-op, telemetry is forced off, and the client starts
+     * "initialized" with an empty blob. Prefer the {@link FlagsClient.forTesting}
+     * factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly privateAttributes;
+    private readonly stickyStore;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -182,18 +281,102 @@ declare class FlagsClient {
     private pollInterval;
     private timer;
     private initialized;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
+    private readonly changeListeners;
     constructor(opts: FlagsClientOptions);
+    /**
+     * Build a no-network, immediately-usable client for tests (Statsig-style).
+     * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
+     * is disabled, and the client is already "initialized" — seed every entity
+     * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
+     *
+     * ```ts
+     * const client = FlagsClient.forTesting();
+     * client.overrideFlag("new_checkout", true);
+     * client.getFlag("new_checkout", { user_id: "u1" }); // true
+     * ```
+     */
+    static forTesting(opts?: Partial<FlagsClientOptions>): FlagsClient;
+    /**
+     * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
+     * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
+     * telemetry off) but, unlike forTesting(), seeds the REAL flags + experiments
+     * blobs so evaluations run the canonical eval against the snapshot. Local
+     * overrides still apply on top.
+     *
+     * Snapshot shape mirrors the wire bodies:
+     * `{ flags: <GET /sdk/flags body>, experiments: <GET /sdk/experiments body> }`.
+     */
+    static fromSnapshot(snapshot: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    }): FlagsClient;
+    /**
+     * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
+     * not available in the browser entrypoint). The file must contain
+     * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
+     * See {@link FlagsClient.fromSnapshot}.
+     */
+    static fromFile(path: string): FlagsClient;
     init(): Promise<void>;
     initOnce(): Promise<void>;
+    /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring the fetched config. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring allocation, holdouts, and targeting.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
     destroy(): void;
+    /**
+     * Subscribe to data-change notifications. The listener fires after a
+     * background poll fetch returns NEW data (200, not 304) — i.e. after the
+     * cached blob is updated. Never fires in testMode/offline (no polling).
+     * Returns an unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+    private notifyChange;
     private startPoll;
     private fetchAll;
     private fetchFlags;
     private fetchExps;
-    getFlag(name: string, user: User): boolean;
+    /**
+     * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). The
+     * reason is computed entirely at this boundary — the canonical eval
+     * (evalGateInternal) is untouched. A local override short-circuits BEFORE
+     * telemetry, exactly like getFlag's override path; otherwise exactly one
+     * "gate" beacon is emitted.
+     */
+    getFlagDetail(name: string, user: User): FlagDetail;
+    /**
+     * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+     * evaluated (client not initialized or flag not found) — never for a gate that
+     * legitimately evaluates to false. Plain `getFlag(name, user)` keeps returning
+     * false for a missing flag.
+     */
+    getFlag(name: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /** Drop caller-marked private attributes from an outbound props bag. */
+    private stripPrivate;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Emit an exposure event for an experiment at the server-side decision point
+     * (parity with the browser's auto-exposure). The server is stateless and
+     * never auto-logs, so call this when you actually present the treatment.
+     * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
+     * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
+     * `/collect`. No-op in test mode or when the user isn't enrolled.
+     */
+    logExposure(user: string | User, name: string): void;
     /**
      * Report a structured error into the errors primitive. Fire-and-forget —
      * never blocks or throws into the request path. Spam-guarded by a 30s
@@ -283,6 +466,12 @@ interface ShipeasyServerConfig {
      * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
      */
     disableTelemetry?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). Stripped from every outbound `track()`
+     * payload. See {@link FlagsClientOptions.privateAttributes}.
+     */
+    privateAttributes?: string[];
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;
@@ -338,8 +527,10 @@ declare const flags: {
     initOnce(): Promise<void>;
     /** Stop background timers. Safe to call repeatedly. */
     destroy(): void;
-    get(name: string, user: User): boolean;
-    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    get(name: string, user: User, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string, user: User): FlagDetail;
+    getConfig<T = unknown>(name: string, decodeOrOpts?: ((raw: unknown) => T) | GetConfigOptions<T>): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the whole
@@ -348,6 +539,9 @@ declare const flags: {
      */
     ks(name: string, switchKey?: string): boolean;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /** Emit an exposure for an enrolled experiment at the decision point. See
+     *  {@link FlagsClient.logExposure}. No-op before configure(). */
+    logExposure(user: string | User, name: string): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally
      * cached blob. Pass the request URL to apply ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -406,4 +600,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type GetConfigOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetShipeasyServerForTests, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -104,6 +104,14 @@ interface SeeControlFlowChain {
 }
 
 declare const version = "4.0.0";
+/**
+ * @internal Exported ONLY so the cross-language eval-parity golden-vector test
+ * (src/__tests__/eval-vectors.test.ts) can assert the raw unsigned-32-bit hash
+ * against the canonical fixture. Not part of the public SDK surface — do not
+ * rely on it in product code; the bucketing contract lives behind getFlag /
+ * getExperiment. Name-prefixed with `_` to signal "test seam, not API".
+ */
+declare function _murmur3ForTests(key: string): number;
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -114,6 +122,30 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary, never inside the canonical eval:
+ *   - CLIENT_NOT_READY — no rules blob loaded yet (init()/initOnce() pending)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the loaded blob
+ *   - OFF              — the gate exists but is disabled / killed
+ *   - OVERRIDE         — a local override (overrideFlag) decided the value
+ *   - RULE_MATCH       — the gate evaluated true (rules + rollout passed)
+ *   - DEFAULT          — the gate evaluated false (a rule or the rollout denied)
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the blob). */
+    defaultValue?: T;
+}
 interface GateRule {
     attr: string;
     op: "eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "regex";
@@ -126,10 +158,47 @@ interface Gate {
     enabled: 0 | 1 | boolean;
     killswitch?: 0 | 1 | boolean;
 }
+interface ExperimentGroup {
+    name: string;
+    weight: number;
+    params: Record<string, unknown>;
+}
+interface Experiment {
+    universe: string;
+    targetingGate?: string | null;
+    allocationPct: number;
+    salt: string;
+    groups: ExperimentGroup[];
+    status: "draft" | "running" | "stopped" | "archived";
+    /** Attribute to bucket on (e.g. company_id); defaults to user_id/anonymous_id. */
+    bucketBy?: string | null;
+}
+/** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
+interface StickyEntry {
+    g: string;
+    s: string;
+}
+/**
+ * Pluggable sticky-bucketing store for the server (doc 20 §2). Keyed by the
+ * bucketing unit; the value is that unit's per-experiment assignments. Absent
+ * from {@link FlagsClientOptions} ⇒ today's deterministic behaviour. Use
+ * {@link createInMemoryStickyStore} or a cookie-bridge built from request
+ * cookies.
+ */
+interface StickyBucketStore {
+    get(unit: string): Record<string, StickyEntry> | undefined;
+    set(unit: string, exp: string, entry: StickyEntry): void;
+}
+/** A process-local sticky store (Map-backed). Handy for tests + single-process servers. */
+declare function createInMemoryStickyStore(seed?: Record<string, Record<string, StickyEntry>>): StickyBucketStore;
+interface Universe {
+    holdout_range: [number, number] | null;
+}
 interface Killswitch {
     killed: 0 | 1 | boolean;
     switches?: Record<string, 0 | 1 | boolean>;
 }
+/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link FlagsClient.fromSnapshot}. */
 interface FlagsBlob {
     version: string;
     plan: string;
@@ -139,6 +208,12 @@ interface FlagsBlob {
     }>;
     killswitches: Record<string, Killswitch>;
 }
+/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link FlagsClient.fromSnapshot}. */
+interface ExpsBlob {
+    version: string;
+    universes: Record<string, Universe>;
+    experiments: Record<string, Experiment>;
+}
 interface BootstrapPayload {
     flags: Record<string, boolean>;
     configs: Record<string, unknown>;
@@ -168,11 +243,35 @@ interface FlagsClientOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). The server evaluates locally so private
+     * attrs never leave for evaluation at all; the only egress is `/collect`, and
+     * the listed keys are stripped from every outbound `track()` payload.
+     */
+    privateAttributes?: string[];
+    /**
+     * Sticky-bucketing store (doc 20 §2). When provided, `getExperiment` locks a
+     * unit to its first-assigned variant — changing allocation % or weights won't
+     * re-bucket enrolled units (changing the experiment salt is the reshuffle
+     * lever). Absent ⇒ deterministic (fully backward compatible). Built-ins:
+     * {@link createInMemoryStickyStore}, or a cookie-bridge over `__se_sticky`.
+     */
+    stickyStore?: StickyBucketStore;
+    /**
+     * Test mode — no network at all. init()/initOnce() are no-ops (never fetch),
+     * track() is a no-op, telemetry is forced off, and the client starts
+     * "initialized" with an empty blob. Prefer the {@link FlagsClient.forTesting}
+     * factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly privateAttributes;
+    private readonly stickyStore;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -182,18 +281,102 @@ declare class FlagsClient {
     private pollInterval;
     private timer;
     private initialized;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
+    private readonly changeListeners;
     constructor(opts: FlagsClientOptions);
+    /**
+     * Build a no-network, immediately-usable client for tests (Statsig-style).
+     * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
+     * is disabled, and the client is already "initialized" — seed every entity
+     * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
+     *
+     * ```ts
+     * const client = FlagsClient.forTesting();
+     * client.overrideFlag("new_checkout", true);
+     * client.getFlag("new_checkout", { user_id: "u1" }); // true
+     * ```
+     */
+    static forTesting(opts?: Partial<FlagsClientOptions>): FlagsClient;
+    /**
+     * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
+     * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
+     * telemetry off) but, unlike forTesting(), seeds the REAL flags + experiments
+     * blobs so evaluations run the canonical eval against the snapshot. Local
+     * overrides still apply on top.
+     *
+     * Snapshot shape mirrors the wire bodies:
+     * `{ flags: <GET /sdk/flags body>, experiments: <GET /sdk/experiments body> }`.
+     */
+    static fromSnapshot(snapshot: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    }): FlagsClient;
+    /**
+     * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
+     * not available in the browser entrypoint). The file must contain
+     * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
+     * See {@link FlagsClient.fromSnapshot}.
+     */
+    static fromFile(path: string): FlagsClient;
     init(): Promise<void>;
     initOnce(): Promise<void>;
+    /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring the fetched config. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring allocation, holdouts, and targeting.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
     destroy(): void;
+    /**
+     * Subscribe to data-change notifications. The listener fires after a
+     * background poll fetch returns NEW data (200, not 304) — i.e. after the
+     * cached blob is updated. Never fires in testMode/offline (no polling).
+     * Returns an unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+    private notifyChange;
     private startPoll;
     private fetchAll;
     private fetchFlags;
     private fetchExps;
-    getFlag(name: string, user: User): boolean;
+    /**
+     * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). The
+     * reason is computed entirely at this boundary — the canonical eval
+     * (evalGateInternal) is untouched. A local override short-circuits BEFORE
+     * telemetry, exactly like getFlag's override path; otherwise exactly one
+     * "gate" beacon is emitted.
+     */
+    getFlagDetail(name: string, user: User): FlagDetail;
+    /**
+     * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+     * evaluated (client not initialized or flag not found) — never for a gate that
+     * legitimately evaluates to false. Plain `getFlag(name, user)` keeps returning
+     * false for a missing flag.
+     */
+    getFlag(name: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /** Drop caller-marked private attributes from an outbound props bag. */
+    private stripPrivate;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Emit an exposure event for an experiment at the server-side decision point
+     * (parity with the browser's auto-exposure). The server is stateless and
+     * never auto-logs, so call this when you actually present the treatment.
+     * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
+     * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
+     * `/collect`. No-op in test mode or when the user isn't enrolled.
+     */
+    logExposure(user: string | User, name: string): void;
     /**
      * Report a structured error into the errors primitive. Fire-and-forget —
      * never blocks or throws into the request path. Spam-guarded by a 30s
@@ -283,6 +466,12 @@ interface ShipeasyServerConfig {
      * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
      */
     disableTelemetry?: boolean;
+    /**
+     * Attribute names usable for targeting but never persisted in analytics
+     * (LD/Statsig `privateAttributes`). Stripped from every outbound `track()`
+     * payload. See {@link FlagsClientOptions.privateAttributes}.
+     */
+    privateAttributes?: string[];
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;
@@ -338,8 +527,10 @@ declare const flags: {
     initOnce(): Promise<void>;
     /** Stop background timers. Safe to call repeatedly. */
     destroy(): void;
-    get(name: string, user: User): boolean;
-    getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    get(name: string, user: User, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string, user: User): FlagDetail;
+    getConfig<T = unknown>(name: string, decodeOrOpts?: ((raw: unknown) => T) | GetConfigOptions<T>): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     /**
      * Read a killswitch. Without `switchKey`, returns true when the whole
@@ -348,6 +539,9 @@ declare const flags: {
      */
     ks(name: string, switchKey?: string): boolean;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /** Emit an exposure for an enrolled experiment at the decision point. See
+     *  {@link FlagsClient.logExposure}. No-op before configure(). */
+    logExposure(user: string | User, name: string): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally
      * cached blob. Pass the request URL to apply ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -406,4 +600,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type GetConfigOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetShipeasyServerForTests, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };