@shipeasy/sdk 5.3.0 → 6.0.0

package/README.md

@@ -17,42 +17,121 @@ pnpm add @shipeasy/sdk
 For React projects use [`@shipeasy/sdk-react`](https://github.com/shipeasy-ai/sdk-react)
 which wraps this package with a `<ShipeasyProvider>` and hooks.
 
-## Quickstart — browser
+## Quickstart — `configure()` once, then `new Client(user)`
+
+The ergonomic front door: **configure once** with your key and an optional
+`attributes` transform from *your own user object* to Shipeasy targeting
+attributes, then evaluate per user with `new Client(user)`. The bound
+`Client` takes **no user argument** on its methods — the user is bound at
+construction.
+
+### Browser
 
 ```ts
-import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+import { configure, Client } from "@shipeasy/sdk/client";
 
-const client = new FlagsClientBrowser({
-  sdkKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY!,
+// Once, at app startup:
+configure({
+  clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY!,
+  // Optional — omit when you already pass a plain attribute object.
+  attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan }),
 });
 
-await client.identify({ user_id: "user-123", plan: "pro" });
+// Per visitor:
+const flags = new Client(currentUser);
+await flags.ready(); // optional — await the first /sdk/evaluate round-trip
 
-if (client.getFlag("new_checkout")) {
+if (flags.getFlag("new_checkout")) {
   // ship it
 }
 
-const cfg = client.getConfig<{ max_uploads: number }>("upload_limits");
-const { params } = client.getExperiment("hero_cta", {
-  primary_label: "Sign up",
+const cfg = flags.getConfig<{ max_uploads: number }>("upload_limits");
+const { params } = flags.getExperiment("hero_cta", { primary_label: "Sign up" });
+```
+
+The browser is single-user: `new Client(user)` runs the transform and
+`identify()`s the result under the hood (merging browser context — `locale`,
+`timezone`, `path`, `referrer`, `screen_*`, `user_agent` — and a persisted
+`anonymous_id`). `getFlag` reflects the latest identify; `await client.ready()`
+when you need the first evaluation to have resolved.
+
+### Server (Node, Cloudflare Worker, Deno)
+
+```ts
+import { configure, Client } from "@shipeasy/sdk/server";
+
+// Once, at app boot:
+configure({
+  apiKey: process.env.SHIPEASY_SERVER_KEY!,
+  attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan, country: u.geo.country }),
 });
+
+// Per request:
+const flags = new Client(req.user);
+if (flags.getFlag("new_checkout")) { /* ... */ }
+const cfg = flags.getConfig("plan_limits");
 ```
 
-`identify()` automatically merges browser context (`locale`, `timezone`,
-`path`, `referrer`, `screen_*`, `user_agent`) and a persisted
-`anonymous_id` into the payload — so gate rules can target by locale or
-holdouts can hash anonymous visitors out of the box.
+When you don't pass `attributes`, the transform is the **identity** function —
+the user object you pass is used verbatim, so it should already be the
+attribute bag (`{ user_id, anonymous_id, ...targeting }`).
 
-## Quickstart — server (Node, Cloudflare Worker, Deno)
+### Low-level: the `Engine` directly
+
+`Client` is a cheap, user-bound handle over a single shared `Engine` (the
+heavyweight class that owns the key, HTTP, the blob cache, and the poll timer —
+**renamed from `FlagsClient` / `FlagsClientBrowser` in 6.0.0**). You can still
+construct and drive an `Engine` yourself:
 
 ```ts
-import { FlagsClient } from "@shipeasy/sdk/server";
+import { Engine } from "@shipeasy/sdk/server";
 
-const client = new FlagsClient({ sdkKey: process.env.SHIPEASY_SERVER_KEY! });
+const engine = new Engine({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+await engine.initOnce();
+const on = engine.getFlag("new_checkout", { user_id: "u-1", plan: "pro" });
+```
 
-const cfg = await client.getConfig("plan_limits", { user_id: "u-1" });
+## SSR bootstrap (flags on first paint)
+
+Server-render the evaluated flags / configs / experiments into the page so the
+browser SDK reads them **synchronously on first paint** — no flash, no extra
+round-trip. The `shipeasy()` server handle emits two declarative `<script>`
+tags. **No SDK key is embedded** in the bootstrap tag (the server key never
+reaches the browser).
+
+```tsx
+// app/layout.tsx — Next.js root layout (React Server Component)
+import { shipeasy } from "@shipeasy/sdk/server";
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const se = await shipeasy({ serverKey: process.env.SHIPEASY_SERVER_KEY ?? "" });
+  const boot = se.getBootstrapData({
+    // public client key — lets the i18n loader revalidate strings at runtime
+    clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY,
+  });
+  return (
+    <html>
+      <body>
+        {/* Render REAL <script> elements — scripts set via
+            dangerouslySetInnerHTML do NOT execute. */}
+        <script src={boot.bootstrap.src} {...boot.bootstrap.attrs} />
+        {boot.i18nLoader && <script src={boot.i18nLoader.src} {...boot.i18nLoader.attrs} />}
+        {children}
+      </body>
+    </html>
+  );
+}
 ```
 
+`bootstrap.src` is `https://cdn.shipeasy.ai/sdk/bootstrap.js` — a static loader
+that reads its own `data-*` attributes, hydrates `window.__SE_BOOTSTRAP`, and
+persists the `__se_anon_id` cookie so the browser buckets **identically** to the
+server. The i18n loader tag carries the SSR strings (`data-strings`) for a
+no-flash first paint plus the public client key for runtime revalidation.
+
+For non-React SSR (Express, raw templates), `se.getBootstrapTags()` returns the
+same two tags as an HTML string you can drop straight into the served markup.
+
 ## Error tracking — `see()`
 
 `see` (shipeasy error) is the structured error reporter — opes-style: every
@@ -140,9 +219,9 @@ so your tests never touch the network.
 
 ```ts
 // Server (Node / Cloudflare Worker / Deno)
-import { FlagsClient } from "@shipeasy/sdk/server";
+import { Engine } from "@shipeasy/sdk/server";
 
-const client = FlagsClient.forTesting();
+const client = Engine.forTesting();
 
 client.overrideFlag("new_checkout", true);
 client.overrideConfig("upload_limits", { max_uploads: 50 });
@@ -159,9 +238,9 @@ client.clearOverrides(); // reset every override back to default
 
 ```ts
 // Browser (vanilla JS — no React required)
-import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+import { Engine } from "@shipeasy/sdk/client";
 
-const client = FlagsClientBrowser.forTesting();
+const client = Engine.forTesting();
 
 client.overrideFlag("new_checkout", true);
 client.overrideConfig("upload_limits", { max_uploads: 50 });
@@ -242,13 +321,13 @@ enabled/killed state into a boolean, so `OFF` folds into `DEFAULT` there.
 
 ## Change listeners
 
-The server `FlagsClient` fires registered listeners after a **background poll
+The server `Engine` fires registered listeners after a **background poll
 returns new data** (HTTP 200, not 304) — handy for invalidating a cache or
 re-rendering when a flag flips. Returns an unsubscribe function. Never fires in
 test/offline mode (no polling happens):
 
 ```ts
-const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+const client = new Engine({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
 await client.init();
 const unsubscribe = client.onChange(() => {
   console.log("flag rules changed — re-evaluating");
@@ -257,7 +336,7 @@ const unsubscribe = client.onChange(() => {
 unsubscribe();
 ```
 
-The browser `FlagsClientBrowser` already exposes the equivalent `subscribe()`
+The browser `Engine` already exposes the equivalent `subscribe()`
 (fires after each `identify()` / override change).
 
 ## Offline snapshot
@@ -276,11 +355,11 @@ two SDK wire bodies:
 ```
 
 ```ts
-import { FlagsClient } from "@shipeasy/sdk/server";
+import { Engine } from "@shipeasy/sdk/server";
 
-const client = FlagsClient.fromFile("./snapshot.json");
+const client = Engine.fromFile("./snapshot.json");
 // or, if you already hold the parsed object:
-const client = FlagsClient.fromSnapshot({ flags, experiments });
+const client = Engine.fromSnapshot({ flags, experiments });
 
 client.getFlag("new_checkout", { user_id: "u1" });
 ```

package/dist/client/index.d.mts

@@ -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.
@@ -530,8 +530,8 @@ interface BootstrapPayload {
     /** i18n profile the server rendered with, so the client loader matches. No key is embedded. */
     i18nProfile?: string;
     apiUrl?: string;
-    /** When true, tEl() returns marker-wrapped strings for devtools label editing. */
-    editLabels?: boolean;
+    /** Stable anonymous bucketing id the server evaluated against (cross-SDK contract). */
+    anonId?: string;
 }
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
@@ -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,78 @@ 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;
+}
 interface SeeApi {
     /**
      * Report a handled problem and its product consequence:
@@ -674,4 +746,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.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.
@@ -530,8 +530,8 @@ interface BootstrapPayload {
     /** i18n profile the server rendered with, so the client loader matches. No key is embedded. */
     i18nProfile?: string;
     apiUrl?: string;
-    /** When true, tEl() returns marker-wrapped strings for devtools label editing. */
-    editLabels?: boolean;
+    /** Stable anonymous bucketing id the server evaluated against (cross-SDK contract). */
+    anonId?: string;
 }
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
@@ -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,78 @@ 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;
+}
 interface SeeApi {
     /**
      * Report a handled problem and its product consequence:
@@ -674,4 +746,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 };