@shipeasy/sdk 5.4.0 → 6.2.0

package/dist/client/index.d.ts

@@ -202,8 +202,8 @@ declare function sameOrigin(rawUrl: string): boolean;
  * pass through unchanged (correlation is optional, never breaks the fetch).
  */
 declare function injectCorrelationHeader(args: Parameters<typeof fetch>, corr: string): Parameters<typeof fetch>;
-type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
-interface FlagsClientBrowserOptions {
+type EngineEnv = "dev" | "staging" | "prod";
+interface EngineOptions {
     sdkKey: string;
     baseUrl?: string;
     autoGuardrails?: boolean;
@@ -222,7 +222,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
@@ -259,11 +259,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;
@@ -288,7 +288,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()
@@ -297,12 +297,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
@@ -411,7 +411,7 @@ interface AttachDevtoolsOptions {
  * each `identify()`/override change. Returns an unsubscribe function for
  * cleanup (e.g. React effect teardown).
  */
-declare function attachDevtools(client: FlagsClientBrowser, opts?: AttachDevtoolsOptions): () => void;
+declare function attachDevtools(client: Engine, opts?: AttachDevtoolsOptions): () => void;
 /** Configure the singleton. Idempotent — re-calling with the same opts is a no-op. */
 interface ShipeasyClientConfig {
     /**
@@ -484,13 +484,13 @@ interface ShipeasyClientConfig {
      * 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}.
+     * {@link EngineOptions.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}.
+     * opt out. See {@link EngineOptions.stickyBucketing}.
      */
     stickyBucketing?: boolean;
 }
@@ -505,9 +505,9 @@ interface ShipeasyClientConfig {
  * A later flags.identify({ user_id }) overrides this in place; anonId stays stable.
  */
 declare function shipeasy(opts: ShipeasyClientConfig): () => void;
-declare function configureShipeasy(opts: FlagsClientBrowserOptions): FlagsClientBrowser;
+declare function configureShipeasy(opts: EngineOptions): Engine;
 /** Returns the configured singleton, or null if configureShipeasy() hasn't run yet. */
-declare function getShipeasyClient(): FlagsClientBrowser | null;
+declare function getShipeasyClient(): Engine | null;
 /**
  * Test helper — drop the singleton so the next configureShipeasy() builds fresh.
  * Not part of the documented surface; production code should never call this.
@@ -539,7 +539,7 @@ interface BootstrapPayload {
  * importing this in a module that loads before app boot is harmless.
  */
 declare const flags: {
-    configure(opts: FlagsClientBrowserOptions): void;
+    configure(opts: EngineOptions): void;
     identify(user: User): Promise<void>;
     /**
      * Read a feature gate.
@@ -554,7 +554,7 @@ declare const flags: {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     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(). */
+     *  {@link Engine.logExposure}. No-op before configure(). */
     logExposure(name: string): void;
     track(eventName: string, props?: Record<string, unknown>): void;
     /**
@@ -583,6 +583,92 @@ declare const flags: {
     /** True once identify() has completed and flags are available. */
     readonly ready: boolean;
 };
+/** Transform YOUR application's user object into Shipeasy targeting attributes. */
+type AttributesFn<U = unknown> = (user: U) => User;
+interface ConfigureOptions<U = unknown> extends Omit<ShipeasyClientConfig, "clientKey"> {
+    /** Public client key — the single key the browser side accepts (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY). */
+    clientKey: 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` + any targeting attrs).
+     */
+    attributes?: AttributesFn<U>;
+}
+/**
+ * Configure the SDK once at app boot, then evaluate per user with
+ * `new Client(user)`. Builds the process-wide {@link Engine} (the
+ * /sdk/evaluate-backed browser client) and registers the `attributes`
+ * transform. The first call wins; later calls reuse the existing engine
+ * (mirrors {@link shipeasy}).
+ *
+ * ```ts
+ * import { configure, Client } from "@shipeasy/sdk/client";
+ *
+ * configure({
+ *   clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY!,
+ *   attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan }),
+ * });
+ *
+ * const flags = new Client(currentUser);
+ * await flags.ready();
+ * if (flags.getFlag("new_checkout")) { ... }
+ * ```
+ *
+ * Returns a cleanup function (same as {@link shipeasy}) that removes the
+ * devtools listeners — call it on teardown.
+ */
+declare function configure<U = unknown>(opts: ConfigureOptions<U>): () => void;
+/** Test seam: reset the registered attribute transform. */
+declare function _resetConfigureForTests(): void;
+/**
+ * A user-bound evaluation handle for the browser. Construct one for the current
+ * visitor — it's cheap (it delegates to the single {@link Engine} built by
+ * {@link configure}); it does NOT open its own connection. The configured
+ * `attributes` transform runs once here and the result is `identify()`-ed into
+ * the engine (fire-and-forget, since identify is async).
+ *
+ * Because the browser is single-user, all bound handles share the engine's
+ * latest eval result. Use {@link Client.ready} to await the first evaluation.
+ *
+ * ```ts
+ * const flags = new Client(currentUser);
+ * await flags.ready();
+ * 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;
+    private readonly _identify;
+    constructor(user: U);
+    /** Resolves once the engine's identify() for this user has completed. */
+    ready(): Promise<void>;
+    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 (identified) user. 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;
+    /**
+     * Log an exposure for `name` at the treatment's render for the bound user.
+     * Delegates to {@link Engine.logExposure} (no-op when the visitor isn't
+     * enrolled). Pair with `getExperiment(name, …, { logExposure: false })` /
+     * `disableAutoExposure` to log exposure exactly when you render.
+     */
+    logExposure(name: string): void;
+}
 interface SeeApi {
     /**
      * Report a handled problem and its product consequence:
@@ -674,4 +760,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 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 };
+export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, 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, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -20,14 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client/index.ts
 var client_exports = {};
 __export(client_exports, {
+  Client: () => Client,
+  Engine: () => Engine,
   FLAG_REASONS: () => FLAG_REASONS,
-  FlagsClientBrowser: () => FlagsClientBrowser,
   LABEL_MARKER_END: () => LABEL_MARKER_END,
   LABEL_MARKER_RE: () => LABEL_MARKER_RE,
   LABEL_MARKER_SEP: () => LABEL_MARKER_SEP,
   LABEL_MARKER_START: () => LABEL_MARKER_START,
+  _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyForTests: () => _resetShipeasyForTests,
   attachDevtools: () => attachDevtools,
+  configure: () => configure,
   configureShipeasy: () => configureShipeasy,
   encodeLabelMarker: () => encodeLabelMarker,
   flags: () => flags,
@@ -912,7 +915,7 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class _FlagsClientBrowser {
+var Engine = class _Engine {
   sdkKey;
   baseUrl;
   autoGuardrails;
@@ -934,7 +937,7 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   // Monotonic counter so a later identify() always wins even if its /sdk/evaluate
   // response races and lands before an earlier in-flight call's response.
   identifySeq = 0;
-  // Test mode: built by `FlagsClientBrowser.forTesting()`. When set, identify()
+  // Test mode: built by `Engine.forTesting()`. When set, identify()
   // never fetches, track() is a no-op, telemetry is off, and the client is
   // already ready with an empty eval result.
   testMode;
@@ -988,13 +991,13 @@ var FlagsClientBrowser = 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) {
-    return new _FlagsClientBrowser({
+    return new _Engine({
       sdkKey: "",
       autoGuardrails: false,
       ...opts,
@@ -1415,7 +1418,7 @@ function shipeasy(opts) {
 }
 function configureShipeasy(opts) {
   if (_client) return _client;
-  _client = new FlagsClientBrowser(opts);
+  _client = new Engine(opts);
   return _client;
 }
 function getShipeasyClient() {
@@ -1554,7 +1557,7 @@ var flags = {
     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(). */
+   *  {@link Engine.logExposure}. No-op before configure(). */
   logExposure(name) {
     _client?.logExposure(name);
   },
@@ -1611,6 +1614,73 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
+var _attributes = _identityAttributes;
+function configure(opts) {
+  const { attributes, ...clientConfig } = opts;
+  _attributes = attributes ?? _identityAttributes;
+  return shipeasy({ autoIdentify: false, ...clientConfig });
+}
+function _resetConfigureForTests() {
+  _attributes = _identityAttributes;
+}
+var Client = class {
+  engine;
+  /** The resolved attribute bag this handle evaluates against. */
+  attributes;
+  _identify;
+  constructor(user) {
+    const engine = getShipeasyClient();
+    if (!engine) {
+      throw new Error(
+        "[shipeasy] new Client(user) called before configure({ clientKey }). Call configure() once at app boot from @shipeasy/sdk/client."
+      );
+    }
+    this.engine = engine;
+    this.attributes = _attributes(user);
+    this._identify = this.engine.identify(this.attributes).catch((err) => {
+      console.warn("[shipeasy] Client identify failed:", String(err));
+    });
+  }
+  /** Resolves once the engine's identify() for this user has completed. */
+  ready() {
+    return this._identify;
+  }
+  getFlag(name, defaultValue = false) {
+    return this.engine.getFlag(name, defaultValue);
+  }
+  getFlagDetail(name) {
+    return this.engine.getFlagDetail(name);
+  }
+  getConfig(name, decodeOrOpts) {
+    return this.engine.getConfig(name, decodeOrOpts);
+  }
+  getExperiment(name, defaultParams, decode) {
+    return this.engine.getExperiment(name, defaultParams, decode);
+  }
+  /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
+  getKillswitch(name, switchKey) {
+    return this.engine.getKillswitch(name, switchKey);
+  }
+  /**
+   * Record a conversion/metric event for the bound (identified) user. 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, props) {
+    this.engine.track(eventName, props);
+  }
+  /**
+   * Log an exposure for `name` at the treatment's render for the bound user.
+   * Delegates to {@link Engine.logExposure} (no-op when the visitor isn't
+   * enrolled). Pair with `getExperiment(name, …, { logExposure: false })` /
+   * `disableAutoExposure` to log exposure exactly when you render.
+   */
+  logExposure(name) {
+    this.engine.logExposure(name);
+  }
+};
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_client) {
     console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
@@ -1859,14 +1929,17 @@ var i18n = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Client,
+  Engine,
   FLAG_REASONS,
-  FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,
   LABEL_MARKER_SEP,
   LABEL_MARKER_START,
+  _resetConfigureForTests,
   _resetShipeasyForTests,
   attachDevtools,
+  configure,
   configureShipeasy,
   encodeLabelMarker,
   flags,

package/dist/client/index.mjs

@@ -863,7 +863,7 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class _FlagsClientBrowser {
+var Engine = class _Engine {
   sdkKey;
   baseUrl;
   autoGuardrails;
@@ -885,7 +885,7 @@ var FlagsClientBrowser = class _FlagsClientBrowser {
   // Monotonic counter so a later identify() always wins even if its /sdk/evaluate
   // response races and lands before an earlier in-flight call's response.
   identifySeq = 0;
-  // Test mode: built by `FlagsClientBrowser.forTesting()`. When set, identify()
+  // Test mode: built by `Engine.forTesting()`. When set, identify()
   // never fetches, track() is a no-op, telemetry is off, and the client is
   // already ready with an empty eval result.
   testMode;
@@ -939,13 +939,13 @@ var FlagsClientBrowser = 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) {
-    return new _FlagsClientBrowser({
+    return new _Engine({
       sdkKey: "",
       autoGuardrails: false,
       ...opts,
@@ -1366,7 +1366,7 @@ function shipeasy(opts) {
 }
 function configureShipeasy(opts) {
   if (_client) return _client;
-  _client = new FlagsClientBrowser(opts);
+  _client = new Engine(opts);
   return _client;
 }
 function getShipeasyClient() {
@@ -1505,7 +1505,7 @@ var flags = {
     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(). */
+   *  {@link Engine.logExposure}. No-op before configure(). */
   logExposure(name) {
     _client?.logExposure(name);
   },
@@ -1562,6 +1562,73 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+var _identityAttributes = (user) => user && typeof user === "object" ? user : {};
+var _attributes = _identityAttributes;
+function configure(opts) {
+  const { attributes, ...clientConfig } = opts;
+  _attributes = attributes ?? _identityAttributes;
+  return shipeasy({ autoIdentify: false, ...clientConfig });
+}
+function _resetConfigureForTests() {
+  _attributes = _identityAttributes;
+}
+var Client = class {
+  engine;
+  /** The resolved attribute bag this handle evaluates against. */
+  attributes;
+  _identify;
+  constructor(user) {
+    const engine = getShipeasyClient();
+    if (!engine) {
+      throw new Error(
+        "[shipeasy] new Client(user) called before configure({ clientKey }). Call configure() once at app boot from @shipeasy/sdk/client."
+      );
+    }
+    this.engine = engine;
+    this.attributes = _attributes(user);
+    this._identify = this.engine.identify(this.attributes).catch((err) => {
+      console.warn("[shipeasy] Client identify failed:", String(err));
+    });
+  }
+  /** Resolves once the engine's identify() for this user has completed. */
+  ready() {
+    return this._identify;
+  }
+  getFlag(name, defaultValue = false) {
+    return this.engine.getFlag(name, defaultValue);
+  }
+  getFlagDetail(name) {
+    return this.engine.getFlagDetail(name);
+  }
+  getConfig(name, decodeOrOpts) {
+    return this.engine.getConfig(name, decodeOrOpts);
+  }
+  getExperiment(name, defaultParams, decode) {
+    return this.engine.getExperiment(name, defaultParams, decode);
+  }
+  /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
+  getKillswitch(name, switchKey) {
+    return this.engine.getKillswitch(name, switchKey);
+  }
+  /**
+   * Record a conversion/metric event for the bound (identified) user. 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, props) {
+    this.engine.track(eventName, props);
+  }
+  /**
+   * Log an exposure for `name` at the treatment's render for the bound user.
+   * Delegates to {@link Engine.logExposure} (no-op when the visitor isn't
+   * enrolled). Pair with `getExperiment(name, …, { logExposure: false })` /
+   * `disableAutoExposure` to log exposure exactly when you render.
+   */
+  logExposure(name) {
+    this.engine.logExposure(name);
+  }
+};
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_client) {
     console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
@@ -1809,14 +1876,17 @@ var i18n = {
   }
 };
 export {
+  Client,
+  Engine,
   FLAG_REASONS,
-  FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,
   LABEL_MARKER_SEP,
   LABEL_MARKER_START,
+  _resetConfigureForTests,
   _resetShipeasyForTests,
   attachDevtools,
+  configure,
   configureShipeasy,
   encodeLabelMarker,
   flags,

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

@@ -78,7 +78,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.
  */
@@ -93,7 +93,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;
@@ -103,7 +103,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>;
@@ -115,12 +115,12 @@ interface BootstrapPayload {
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
 }
-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().
@@ -155,12 +155,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;
@@ -180,7 +180,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
@@ -188,12 +188,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,
@@ -207,14 +207,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. */
@@ -298,32 +298,45 @@ declare class FlagsClient {
  *
  * ```ts
  * import { OpenFeature } from "@openfeature/server-sdk";
- * import { FlagsClient } from "@shipeasy/sdk/server";
+ * import { Engine } from "@shipeasy/sdk/server";
  * import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-server";
  *
- * const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+ * const client = new Engine({ 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`
+ * Pure adapter over `Engine` — 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`;
+ * Shipeasy OpenFeature provider (server paradigm). Wraps an `Engine`;
  * 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);
+    private readonly client;
+    /**
+     * Construct the provider. The **global form** (no argument) resolves the
+     * engine built by `configure({ apiKey })`, so the docs build it after
+     * configuration without ever naming the `Engine`:
+     *
+     * ```ts
+     * configure({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+     * await OpenFeature.setProviderAndWait(new ShipeasyProvider());
+     * ```
+     *
+     * Passing an explicit `Engine` stays supported for advanced/back-compat use.
+     * Throws if no engine is passed and `configure()` has not run.
+     */
+    constructor(client?: Engine);
     /** Fetch the rules blob once. The SDK fires `Ready` when this resolves. */
     initialize(): Promise<void>;
     onClose(): Promise<void>;