@shipeasy/sdk 5.0.0 → 5.2.0

package/dist/openfeature-server/index.d.mts

@@ -0,0 +1,338 @@
+import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/server-sdk';
+
+type SeeExtras = Record<string, string | number | boolean | null | undefined>;
+type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
+/** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+
+interface User {
+    user_id?: string;
+    anonymous_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    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";
+    value: unknown;
+}
+interface Gate {
+    rules: GateRule[];
+    rolloutPct: number;
+    salt: string;
+    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;
+}
+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;
+    gates: Record<string, Gate>;
+    configs: Record<string, {
+        value: unknown;
+    }>;
+    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>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    killswitches: Record<string, boolean | Record<string, boolean>>;
+}
+type FlagsClientEnv = "dev" | "staging" | "prod";
+interface FlagsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientEnv;
+    /**
+     * Preload the flags blob synchronously without a network fetch. Primarily
+     * for tests; production callers should rely on init()/initOnce().
+     */
+    initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    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;
+    private expsBlob;
+    private flagsEtag;
+    private expsEtag;
+    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;
+    /**
+     * 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
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
+    /**
+     * Evaluate all flags, configs, and experiments for a user against the locally
+     * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+     * overrides from the request URL when provided.
+     *
+     * Intended for SSR: call on the server, inject the result as
+     * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+     * synchronously without waiting for identify() to resolve.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
+    getKillswitch(name: string, switchKey?: string): boolean;
+}
+
+/**
+ * OpenFeature **server** provider for Shipeasy.
+ *
+ * Lets apps standardized on the CNCF OpenFeature API plug Shipeasy in as the
+ * backing provider:
+ *
+ * ```ts
+ * import { OpenFeature } from "@openfeature/server-sdk";
+ * import { FlagsClient } from "@shipeasy/sdk/server";
+ * import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-server";
+ *
+ * const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+ * await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
+ *
+ * const ofClient = OpenFeature.getClient();
+ * const on = await ofClient.getBooleanValue("new_checkout", false, { targetingKey: "u1" });
+ * ```
+ *
+ * Pure adapter over `FlagsClient` — no change to evaluation. `@openfeature/server-sdk`
+ * is an optional peer dependency; install it in the consuming app.
+ */
+
+/**
+ * Shipeasy OpenFeature provider (server paradigm). Wraps a `FlagsClient`;
+ * evaluation is local against the cached blob, so resolution is effectively
+ * synchronous (the methods are `async` only to satisfy the server contract).
+ */
+declare class ShipeasyProvider implements Provider {
+    private readonly client;
+    readonly metadata: {
+        readonly name: "shipeasy";
+    };
+    readonly runsOn: "server";
+    constructor(client: FlagsClient);
+    /** Fetch the rules blob once. The SDK fires `Ready` when this resolves. */
+    initialize(): Promise<void>;
+    onClose(): Promise<void>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<boolean>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<string>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<number>>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<T>>;
+    /** OpenFeature `track()` → Shipeasy `track()`. No-ops without a targeting key. */
+    track(trackingEventName: string, context: EvaluationContext, details?: Record<string, unknown>): void;
+}
+
+export { ShipeasyProvider };

package/dist/openfeature-server/index.d.ts

@@ -0,0 +1,338 @@
+import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/server-sdk';
+
+type SeeExtras = Record<string, string | number | boolean | null | undefined>;
+type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
+/** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+
+interface User {
+    user_id?: string;
+    anonymous_id?: string;
+    [attr: string]: unknown;
+}
+interface ExperimentResult<P> {
+    inExperiment: boolean;
+    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";
+    value: unknown;
+}
+interface Gate {
+    rules: GateRule[];
+    rolloutPct: number;
+    salt: string;
+    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;
+}
+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;
+    gates: Record<string, Gate>;
+    configs: Record<string, {
+        value: unknown;
+    }>;
+    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>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    killswitches: Record<string, boolean | Record<string, boolean>>;
+}
+type FlagsClientEnv = "dev" | "staging" | "prod";
+interface FlagsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Which published env to read values from. Defaults to "prod". */
+    env?: FlagsClientEnv;
+    /**
+     * Preload the flags blob synchronously without a network fetch. Primarily
+     * for tests; production callers should rely on init()/initOnce().
+     */
+    initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    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;
+    private expsBlob;
+    private flagsEtag;
+    private expsEtag;
+    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;
+    /**
+     * 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
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
+    /**
+     * Evaluate all flags, configs, and experiments for a user against the locally
+     * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+     * overrides from the request URL when provided.
+     *
+     * Intended for SSR: call on the server, inject the result as
+     * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+     * synchronously without waiting for identify() to resolve.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
+    getKillswitch(name: string, switchKey?: string): boolean;
+}
+
+/**
+ * OpenFeature **server** provider for Shipeasy.
+ *
+ * Lets apps standardized on the CNCF OpenFeature API plug Shipeasy in as the
+ * backing provider:
+ *
+ * ```ts
+ * import { OpenFeature } from "@openfeature/server-sdk";
+ * import { FlagsClient } from "@shipeasy/sdk/server";
+ * import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-server";
+ *
+ * const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+ * await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
+ *
+ * const ofClient = OpenFeature.getClient();
+ * const on = await ofClient.getBooleanValue("new_checkout", false, { targetingKey: "u1" });
+ * ```
+ *
+ * Pure adapter over `FlagsClient` — no change to evaluation. `@openfeature/server-sdk`
+ * is an optional peer dependency; install it in the consuming app.
+ */
+
+/**
+ * Shipeasy OpenFeature provider (server paradigm). Wraps a `FlagsClient`;
+ * evaluation is local against the cached blob, so resolution is effectively
+ * synchronous (the methods are `async` only to satisfy the server contract).
+ */
+declare class ShipeasyProvider implements Provider {
+    private readonly client;
+    readonly metadata: {
+        readonly name: "shipeasy";
+    };
+    readonly runsOn: "server";
+    constructor(client: FlagsClient);
+    /** Fetch the rules blob once. The SDK fires `Ready` when this resolves. */
+    initialize(): Promise<void>;
+    onClose(): Promise<void>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<boolean>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<string>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<number>>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, _context: EvaluationContext, _logger?: Logger): Promise<ResolutionDetails<T>>;
+    /** OpenFeature `track()` → Shipeasy `track()`. No-ops without a targeting key. */
+    track(trackingEventName: string, context: EvaluationContext, details?: Record<string, unknown>): void;
+}
+
+export { ShipeasyProvider };