@shipeasy/sdk 5.4.0 → 6.2.0

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

@@ -101,8 +101,8 @@ interface AutoCollectGroups {
     errors: boolean;
     engagement: boolean;
 }
-type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
-interface FlagsClientBrowserOptions {
+type EngineEnv = "dev" | "staging" | "prod";
+interface EngineOptions {
     sdkKey: string;
     baseUrl?: string;
     autoGuardrails?: boolean;
@@ -121,7 +121,7 @@ interface FlagsClientBrowserOptions {
      */
     autoCollectAlways?: boolean;
     /** Which published env to read values from. Defaults to "prod". */
-    env?: FlagsClientBrowserEnv;
+    env?: EngineEnv;
     /**
      * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
      * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
@@ -158,11 +158,11 @@ interface FlagsClientBrowserOptions {
      * Test mode — no network at all. identify()/init are no-ops (never call
      * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
      * starts "ready" with an empty eval result. Prefer the
-     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     * {@link Engine.forTesting} factory over passing this directly.
      */
     testMode?: boolean;
 }
-declare class FlagsClientBrowser {
+declare class Engine {
     private readonly sdkKey;
     private readonly baseUrl;
     private readonly autoGuardrails;
@@ -187,7 +187,7 @@ declare class FlagsClientBrowser {
     private readonly configOverrides;
     private readonly experimentOverrides;
     private onOverrideChange;
-    constructor(opts: FlagsClientBrowserOptions);
+    constructor(opts: EngineOptions);
     /**
      * Build a no-network, immediately-usable browser client for tests
      * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
@@ -196,12 +196,12 @@ declare class FlagsClientBrowser {
      * key required.
      *
      * ```ts
-     * const client = FlagsClientBrowser.forTesting();
+     * const client = Engine.forTesting();
      * client.overrideFlag("new_checkout", true);
      * client.getFlag("new_checkout"); // true
      * ```
      */
-    static forTesting(opts?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
+    static forTesting(opts?: Partial<EngineOptions>): Engine;
     identify(user: User): Promise<void>;
     /**
      * Report a structured error into the errors primitive. Flushes immediately
@@ -289,10 +289,10 @@ interface ShipeasySdkBridge {
  *
  * ```ts
  * import { OpenFeature } from "@openfeature/web-sdk";
- * import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+ * import { Engine } from "@shipeasy/sdk/client";
  * import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-web";
  *
- * const client = new FlagsClientBrowser({ sdkKey: NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
+ * const client = new Engine({ sdkKey: NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
  * await OpenFeature.setContext({ targetingKey: "u1", plan: "pro" });
  * await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
  *
@@ -307,7 +307,7 @@ interface ShipeasySdkBridge {
 
 /**
  * Shipeasy OpenFeature provider (client/web paradigm). Wraps a
- * `FlagsClientBrowser`. Context changes are reconciled through `identify()`;
+ * `Engine`. Context changes are reconciled through `identify()`;
  * flag reads come from the cached eval result.
  */
 declare class ShipeasyProvider implements Provider {
@@ -316,7 +316,7 @@ declare class ShipeasyProvider implements Provider {
         readonly name: "shipeasy";
     };
     readonly runsOn: "client";
-    constructor(client: FlagsClientBrowser);
+    constructor(client: Engine);
     /** Identify with the initial static context so the first read is warm. */
     initialize(context?: EvaluationContext): Promise<void>;
     /** Re-identify when the application author changes the static context. */

package/dist/server/index.d.mts

@@ -181,7 +181,7 @@ interface StickyEntry {
 /**
  * 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
+ * from {@link EngineOptions} ⇒ today's deterministic behaviour. Use
  * {@link createInMemoryStickyStore} or a cookie-bridge built from request
  * cookies.
  */
@@ -198,7 +198,7 @@ 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}. */
+/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link Engine.fromSnapshot}. */
 interface FlagsBlob {
     version: string;
     plan: string;
@@ -208,7 +208,7 @@ interface FlagsBlob {
     }>;
     killswitches: Record<string, Killswitch>;
 }
-/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link FlagsClient.fromSnapshot}. */
+/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link Engine.fromSnapshot}. */
 interface ExpsBlob {
     version: string;
     universes: Record<string, Universe>;
@@ -221,12 +221,12 @@ interface BootstrapPayload {
     killswitches: Record<string, boolean | Record<string, boolean>>;
 }
 declare const ANON_ID_COOKIE = "__se_anon_id";
-type FlagsClientEnv = "dev" | "staging" | "prod";
-interface FlagsClientOptions {
+type EngineEnv = "dev" | "staging" | "prod";
+interface EngineOptions {
     apiKey: string;
     baseUrl?: string;
     /** Which published env to read values from. Defaults to "prod". */
-    env?: FlagsClientEnv;
+    env?: EngineEnv;
     /**
      * Preload the flags blob synchronously without a network fetch. Primarily
      * for tests; production callers should rely on init()/initOnce().
@@ -261,12 +261,12 @@ interface FlagsClientOptions {
     /**
      * 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}
+     * "initialized" with an empty blob. Prefer the {@link Engine.forTesting}
      * factory over passing this directly.
      */
     testMode?: boolean;
 }
-declare class FlagsClient {
+declare class Engine {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
@@ -286,7 +286,7 @@ declare class FlagsClient {
     private readonly configOverrides;
     private readonly experimentOverrides;
     private readonly changeListeners;
-    constructor(opts: FlagsClientOptions);
+    constructor(opts: EngineOptions);
     /**
      * Build a no-network, immediately-usable client for tests (Statsig-style).
      * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
@@ -294,12 +294,12 @@ declare class FlagsClient {
      * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
      *
      * ```ts
-     * const client = FlagsClient.forTesting();
+     * const client = Engine.forTesting();
      * client.overrideFlag("new_checkout", true);
      * client.getFlag("new_checkout", { user_id: "u1" }); // true
      * ```
      */
-    static forTesting(opts?: Partial<FlagsClientOptions>): FlagsClient;
+    static forTesting(opts?: Partial<EngineOptions>): Engine;
     /**
      * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
      * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
@@ -313,14 +313,14 @@ declare class FlagsClient {
     static fromSnapshot(snapshot: {
         flags: FlagsBlob;
         experiments: ExpsBlob;
-    }): FlagsClient;
+    }): Engine;
     /**
      * 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}.
+     * See {@link Engine.fromSnapshot}.
      */
-    static fromFile(path: string): FlagsClient;
+    static fromFile(path: string): Engine;
     init(): Promise<void>;
     initOnce(): Promise<void>;
     /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
@@ -440,8 +440,8 @@ interface FetchLabelsOptions {
     timeoutMs?: number;
 }
 declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
-declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
-declare function getShipeasyServerClient(): FlagsClient | null;
+declare function configureShipeasyServer(opts: EngineOptions): Engine;
+declare function getShipeasyServerClient(): Engine | null;
 declare function _resetShipeasyServerForTests(): void;
 interface ShipeasyServerConfig {
     /**
@@ -463,13 +463,13 @@ interface ShipeasyServerConfig {
     /**
      * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
-     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     * that evaluate many flags per request. See {@link EngineOptions.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}.
+     * payload. See {@link EngineOptions.privateAttributes}.
      */
     privateAttributes?: string[];
 }
@@ -547,7 +547,7 @@ declare function getBootstrapData(bootstrap: BootstrapPayload | null, i18nData:
  */
 declare function getBootstrapTags(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapEmitOptions): string;
 declare const flags: {
-    configure(opts: FlagsClientOptions): void;
+    configure(opts: EngineOptions): void;
     /**
      * Long-running server: starts the background poll. Call once at app boot.
      * Throws if the initial fetch fails (caller decides whether to crash or degrade).
@@ -570,7 +570,7 @@ 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(). */
+     *  {@link Engine.logExposure}. No-op before configure(). */
     logExposure(user: string | User, name: string): void;
     /**
      * Evaluate all flags / configs / experiments for a user against the locally
@@ -579,6 +579,165 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+/** Transform YOUR application's user object into Shipeasy targeting attributes. */
+type AttributesFn<U = unknown> = (user: U) => User;
+interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
+    /** Server key — the single key the server side accepts (SHIPEASY_SERVER_KEY). */
+    apiKey: string;
+    /**
+     * Map your own user object into the attribute bag every flag/experiment
+     * evaluation sees. Runs once per `new Client(user)`. Omit when you already
+     * pass a plain attribute object (identity transform — the object is used
+     * verbatim, so it should carry `user_id`/`anonymous_id` + any targeting attrs).
+     */
+    attributes?: AttributesFn<U>;
+    /**
+     * Long-running server: start the **background poll** internally (initial fetch
+     * + periodic refresh) so flags stay fresh without a redeploy. Default `false`.
+     * With `poll: false` (default) a one-shot fetch is kicked off fire-and-forget
+     * (serverless-friendly). You never need to call `engine.init()` yourself —
+     * configuration owns the lifecycle.
+     */
+    poll?: boolean;
+    /**
+     * One-shot fetch on configure (fire-and-forget). Default `true`. Ignored when
+     * `poll: true` (the poll does the initial fetch). Set `false` only if you want
+     * to control the first fetch yourself.
+     */
+    init?: boolean;
+}
+/**
+ * Configure the SDK once at app boot, then evaluate per user with
+ * `new Client(user)`. Builds the process-wide {@link Engine} (polling + blob
+ * cache + HTTP) and registers the `attributes` transform. The first call wins;
+ * later calls return the existing engine (mirrors {@link configureShipeasyServer}).
+ *
+ * ```ts
+ * import { configure, Client } from "@shipeasy/sdk/server";
+ *
+ * configure({
+ *   apiKey: process.env.SHIPEASY_SERVER_KEY!,
+ *   attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan, country: u.geo.country }),
+ * });
+ *
+ * const flags = new Client(currentUser);
+ * if (flags.getFlag("new_checkout")) { ... }
+ * ```
+ */
+declare function configure<U = unknown>(opts: ConfigureOptions<U>): Engine;
+/** Test seam: reset the registered attribute transform. */
+declare function _resetConfigureForTests(): void;
+/** Seed shapes shared by {@link configureForTesting} / {@link configureForOffline}. */
+interface ConfigureTestOptions<U = unknown> {
+    /** Same transform as {@link configure} (default identity). */
+    attributes?: AttributesFn<U>;
+    /** `{ name: bool }` — forced `getFlag` results. */
+    flags?: Record<string, boolean>;
+    /** `{ name: value }` — forced `getConfig` results. */
+    configs?: Record<string, unknown>;
+    /** `{ name: [group, params] }` — forced enrolments. */
+    experiments?: Record<string, [string, Record<string, unknown>]>;
+}
+/**
+ * Configure the SDK in **test mode** — a drop-in sibling of {@link configure}
+ * with no network, ever (no api key needed). Seed what your code under test
+ * should see, then read through the ordinary `new Client(user)`:
+ *
+ * ```ts
+ * configureForTesting({ flags: { new_checkout: true } });
+ * const flags = new Client({ user_id: "u_1" });
+ * flags.getFlag("new_checkout"); // true
+ * ```
+ *
+ * Replaces any previously-configured engine, so tests can reconfigure freely.
+ */
+declare function configureForTesting<U = unknown>(opts?: ConfigureTestOptions<U>): Engine;
+/** Options for {@link configureForOffline} — exactly one of `snapshot` / `path`. */
+interface ConfigureOfflineOptions<U = unknown> extends ConfigureTestOptions<U> {
+    /** In-memory `{ flags: <body of /sdk/flags>, experiments: <body of /sdk/experiments> }`. */
+    snapshot?: {
+        flags: FlagsBlob;
+        experiments: ExpsBlob;
+    };
+    /** Path to a JSON file `{ flags, experiments }`. */
+    path?: string;
+}
+/**
+ * Configure the SDK **offline** — evaluate the REAL rules from an in-memory
+ * snapshot or a JSON file, with no network. A drop-in sibling of
+ * {@link configure} (no api key needed). Optional `flags`/`configs`/`experiments`
+ * overrides are layered on top (same shapes as {@link configureForTesting}).
+ * Replaces any previously-configured engine.
+ */
+declare function configureForOffline<U = unknown>(opts: ConfigureOfflineOptions<U>): Engine;
+/**
+ * Force `getFlag(name)` → `value` on the spot, for the current config. A quick
+ * in-test override layered on top of whatever {@link configureForTesting} /
+ * {@link configureForOffline} (or {@link configure}) set up — wins over the blob
+ * until {@link clearOverrides}.
+ */
+declare function overrideFlag(name: string, value: boolean): void;
+/** Force `getConfig(name)` → `value` on the spot (see {@link overrideFlag}). */
+declare function overrideConfig(name: string, value: unknown): void;
+/**
+ * Force `getExperiment(name)` to report enrolment in `group` with `params` on
+ * the spot (see {@link overrideFlag}).
+ */
+declare function overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+/**
+ * Drop every on-the-spot flag/config/experiment override — INCLUDING the seed
+ * from {@link configureForTesting} (test mode has no blob beneath, so everything
+ * reverts to the empty-blob defaults). Under {@link configureForOffline} the
+ * snapshot remains and evaluations revert to it.
+ */
+declare function clearOverrides(): void;
+/**
+ * Register a listener fired after a background poll fetches NEW data (a 200, not
+ * a 304). Returns an unsubscribe callable. Requires `configure({ poll: true })`
+ * (no poll thread runs otherwise). Configuration owns the engine; you never
+ * touch it.
+ */
+declare function onChange(listener: () => void): () => void;
+/**
+ * A user-bound evaluation handle. Construct one per user/request — it's cheap
+ * (it delegates to the {@link Engine} built by {@link configure}); it does NOT
+ * open its own connection or poll. The configured `attributes` transform runs
+ * once here, so every getFlag/getConfig/getExperiment reads the same bag.
+ *
+ * ```ts
+ * const flags = new Client(req.user);
+ * flags.getFlag("new_checkout");                  // no user arg — bound at construction
+ * flags.getExperiment("price_test", { price: 9 });
+ * ```
+ */
+declare class Client<U = unknown> {
+    private readonly engine;
+    /** The resolved attribute bag this handle evaluates against. */
+    readonly attributes: User;
+    constructor(user: U);
+    getFlag(name: string, defaultValue?: boolean): boolean;
+    getFlagDetail(name: string): FlagDetail;
+    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): ExperimentResult<P>;
+    /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
+    getKillswitch(name: string, switchKey?: string): boolean;
+    /**
+     * Record a conversion/metric event for the bound user. Derives the unit from
+     * the resolved attribute bag (`user_id`, else `anonymous_id`) and delegates to
+     * {@link Engine.track} — so an experiment is end-to-end Client-only (no need to
+     * drop down to the Engine to log a conversion). Fire-and-forget; no-op in test
+     * mode.
+     */
+    track(eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Emit an exposure event for `name` at this server-side decision point for the
+     * bound user. Delegates to {@link Engine.logExposure} with the resolved
+     * attribute bag (re-evaluates enrolment; no-op when the user isn't enrolled or
+     * in test mode).
+     */
+    logExposure(name: string): void;
+}
 interface SeeApi {
     /**
      * Report a handled problem and its product consequence:
@@ -630,4 +789,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapData, type BootstrapEmitOptions, 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 ScriptTagSpec, 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, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, 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, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };