@shipeasy/sdk 5.4.0 → 6.2.0

package/README.md

@@ -1,348 +1,113 @@
-# @shipeasy/sdk
+<!--
+  This file is GENERATED by scripts/gen-readme.mjs from docs/.
+  Do NOT edit by hand — edit the docs, then run: npm run gen:readme
+-->
 
-Feature gates, runtime configs, experiments, and metrics for the
-[Shipeasy](https://shipeasy.ai) hosted service.
+# @shipeasy/sdk (TypeScript)
 
-> Source-available under the [Shipeasy-SAL 1.0](./LICENSE). Use it freely
-> as a client of Shipeasy. Don't use it to build a competing service.
+[![Tests](https://github.com/shipeasy-ai/sdk/actions/workflows/test.yml/badge.svg)](https://github.com/shipeasy-ai/sdk/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@shipeasy/sdk.svg)](https://www.npmjs.com/package/@shipeasy/sdk)
+[![node](https://img.shields.io/node/v/@shipeasy/sdk.svg)](https://www.npmjs.com/package/@shipeasy/sdk)
 
-## Install
-
-```bash
-npm install @shipeasy/sdk
-# or
-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
-
-```ts
-import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+The Shipeasy SDK for **feature flags, dynamic configs, kill switches, A/B
+experiments, metric tracking, and SSR/i18n** — for Node, Next.js, and Cloudflare
+Workers. Server-key only on the server; the browser uses its own client key.
 
-const client = new FlagsClientBrowser({
-  sdkKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY!,
-});
-
-await client.identify({ user_id: "user-123", plan: "pro" });
-
-if (client.getFlag("new_checkout")) {
-  // ship it
-}
-
-const cfg = client.getConfig<{ max_uploads: number }>("upload_limits");
-const { params } = client.getExperiment("hero_cta", {
-  primary_label: "Sign up",
-});
-```
+> 📚 **Full documentation:** **<https://shipeasy-ai.github.io/sdk/>** — also browsable under
+> [`docs/`](https://github.com/shipeasy-ai/sdk/blob/main/docs). This README is generated from those docs.
 
-`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.
+## 🤖 Using an AI agent?
 
-## Quickstart — server (Node, Cloudflare Worker, Deno)
-
-```ts
-import { FlagsClient } from "@shipeasy/sdk/server";
-
-const client = new FlagsClient({ sdkKey: process.env.SHIPEASY_SERVER_KEY! });
-
-const cfg = await client.getConfig("plan_limits", { user_id: "u-1" });
-```
+This SDK ships an installable **agent skill** — a copy-paste-ready guide to
+`configure()` + `new Client(user)`, testing, experiments, error reporting, and
+more, with links the agent can pull for deeper docs:
 
-## SSR bootstrap (flags on first paint)
+- **Skill:** [`docs/skill/SKILL.md`](https://github.com/shipeasy-ai/sdk/blob/main/docs/skill/SKILL.md) · raw:
+  `https://shipeasy-ai.github.io/sdk/skill/SKILL.md`
+- **Install it** (ships with the package — no network):
+  `npx shipeasy-skill install` → `.claude/skills/shipeasy-typescript/SKILL.md`
+  (or via the Shipeasy CLI: `shipeasy docs skill --sdk typescript --install`)
 
-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).
+**Humans:** you can copy that skill straight into your own project's agent skills
+directory (e.g. `.claude/skills/shipeasy-typescript/SKILL.md`) so your coding agent
+always uses the correct Shipeasy patterns. Every doc page and snippet is also
+fetchable by URL — start from the manifest at `https://shipeasy-ai.github.io/sdk/manifest.json`.
 
-```tsx
-// app/layout.tsx — Next.js root layout (React Server Component)
-import { shipeasy } from "@shipeasy/sdk/server";
+## Install
 
-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>
-  );
-}
+```bash
+npm install @shipeasy/sdk
+# or
+pnpm add @shipeasy/sdk
+# or
+yarn add @shipeasy/sdk
 ```
 
-`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.
+Per-framework setup (Next.js / Express / Cloudflare Workers) and the anon-id
+middleware are on the [Installation](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/installation.md) page.
 
-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
-handled exception documents its **product consequence**, not just its stack.
-Works in vanilla JS on both sides; the whole grammar hangs off one import:
+## Quickstart — `configure()` once, then `new Client(user)` per request
 
 ```ts
-import { see } from "@shipeasy/sdk/client"; // or "@shipeasy/sdk/server"
-
-try {
-  await submitOrder(order);
-} catch (e) {
-  see(e).causes_the("checkout").to("use cached prices").extras({ order_id: order.id });
-}
+import { configure, Client } from "@shipeasy/sdk/server"; // or /client
 
-// Non-exception problems — the name is a stable identifier (it participates
-// in the issue fingerprint); all variable data goes in .extras():
-if (rows.length > LIMIT) {
-  see.Violation("large query")
-    .causes_the("search results")
-    .to("be trimmed")
-    .extras({ rows: rows.length });
-}
+configure({ apiKey: process.env.SHIPEASY_SERVER_KEY!,
+            attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan }) });
 
-// Expected control-flow exceptions: document them, report nothing —
-// auto-capture skips marked errors. The reason must start with "because".
-try {
-  return decodeFoo(blob);
-} catch (e) {
-  see.ControlFlowException(e).because("because it wasn't an encoded Foo");
-  return decodeBar(blob);
-}
+const flags = new Client(currentUser);
+if (flags.getFlag("new_checkout")) { /* ship it */ }
 ```
 
-Reports land in the Shipeasy **errors** primitive: fingerprint-grouped issues
-(open / resolved / ignored, regression auto-reopens) with a near-real-time
-occurrence timeseries. The chain dispatches on the next microtask — no
-`.send()` — and ships immediately (`sendBeacon` in the browser, fire-and-forget
-`fetch` on the server), spam-guarded by a 30s dedup window and a per-session
-cap.
-
-The client SDK also auto-captures **network failures** (fetch network errors +
-5xx) into the same primitive (`autoCollect: { errors }`, on by default) — each
-names a specific endpoint and a specific outcome. It deliberately does **not**
-blanket-report uncaught exceptions or unhandled promise rejections: those carry
-no actionable consequence ("the page hit an error" names the plumbing, not the
-feature). Code that knows the consequence reports it explicitly with `see()` at
-the catch site.
-
-**Rules**: if you don't know the consequence, don't catch the exception. You
-**may** `see()` then re-throw — the re-thrown error links to its inner report
-as a `caused_by` chain instead of double-counting. Never use `see.Violation()`
-for a caught exception (you'd drop the stack). No PII or high-cardinality data
-in extras.
+Constructing `new Client(user)` before `configure()` throws.
 
-## Drop-in `<script>` loader (no bundler)
-
-```html
-<script
-  src="https://cdn.shipeasy.ai/sdk/loader.js"
-  data-sdk-key="sdk_client_..."
-  data-user-id="user-123"
-  data-user-email="u@x.com"
-  data-user-plan="pro"
-  data-attrs='{"country":"US"}'
-  defer
-></script>
-<script>
-  await window.shipeasy.ready;
-  if (window.shipeasy.getFlag("new_checkout")) { /* … */ }
-</script>
-```
+## Documentation
 
-The loader IIFE is published to a public R2 bucket on every release and
-cached for 1y at `loader-vX.Y.Z.js` (immutable) plus a rolling 5-minute
-`loader.js`.
+| Page | What |
+| --- | --- |
+| [Overview](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/overview.md) | The `configure()` + `new Client(user)` model. |
+| [Installation](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/installation.md) | Install, frameworks (Next / Express / Workers), `configure()` wiring. |
+| [Configuration](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/configuration.md) | Keys, `attributes`, one-shot vs poll, every option. |
+| [Feature flags](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/flags.md) | `getFlag`, `getFlagDetail`, defaults. |
+| [Dynamic configs](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/configs.md) | `getConfig`, typed decode, defaults. |
+| [Kill switches](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/killswitches.md) | `getKillswitch`, named switches. |
+| [Experiments](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/experiments.md) | `getExperiment`, `logExposure`, `track`. |
+| [Internationalization](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/i18n.md) | SSR bootstrap + i18n loader tags. |
+| [Error reporting](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/error-reporting.md) | `see()` structured error reporting. |
+| [Testing](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/testing.md) | `configureForTesting` / `configureForOffline`, overrides. |
+| [OpenFeature](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/openfeature.md) | `ShipeasyProvider` (OpenFeature server provider). |
+| [Advanced](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/advanced.md) | Anon-id middleware, private attributes, sticky bucketing, SSR. |
+
+Copy-paste snippets live under [`docs/snippets/`](https://github.com/shipeasy-ai/sdk/blob/main/docs/snippets)
+(release · metrics · i18n · ops); an installable agent skill is at
+[`docs/skill/SKILL.md`](https://github.com/shipeasy-ai/sdk/blob/main/docs/skill/SKILL.md).
 
 ## Testing
 
-For unit tests, build a **no-network** client with `forTesting()` and seed every
-entity with local overrides (Statsig-style). In test mode the client is already
-"initialized"/"ready", `init()`/`initOnce()`/`identify()` are no-ops (they never
-fetch), `track()` is a no-op, telemetry is disabled, and no SDK key is required —
-so your tests never touch the network.
-
-```ts
-// Server (Node / Cloudflare Worker / Deno)
-import { FlagsClient } from "@shipeasy/sdk/server";
-
-const client = FlagsClient.forTesting();
-
-client.overrideFlag("new_checkout", true);
-client.overrideConfig("upload_limits", { max_uploads: 50 });
-client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
-
-client.getFlag("new_checkout", { user_id: "u1" }); // true
-client.getConfig("upload_limits"); // { max_uploads: 50 }
-client.getExperiment("hero_cta", { user_id: "u1" }, { primary_label: "Sign up" });
-// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
-
-client.track("u1", "purchase"); // no-op — never hits the network
-client.clearOverrides(); // reset every override back to default
-```
-
-```ts
-// Browser (vanilla JS — no React required)
-import { FlagsClientBrowser } from "@shipeasy/sdk/client";
-
-const client = FlagsClientBrowser.forTesting();
-
-client.overrideFlag("new_checkout", true);
-client.overrideConfig("upload_limits", { max_uploads: 50 });
-client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
-
-client.getFlag("new_checkout"); // true
-client.getConfig("upload_limits"); // { max_uploads: 50 }
-client.getExperiment("hero_cta", { primary_label: "Sign up" });
-// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
-
-client.track("purchase"); // no-op
-client.clearOverrides();
-```
-
-The `override*` setters also work on a **normal** client (not just `forTesting()`),
-mirroring Statsig — a programmatic override always wins over the fetched values.
-In the browser the precedence is: programmatic override > URL/devtools override
-(`?se_gate_…` / `?se_config_…` / `?se_exp_…`) > the server's evaluation.
-
-**API:**
-
-```ts
-overrideFlag(name: string, value: boolean): void;
-overrideConfig(name: string, value: unknown): void;
-overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
-clearOverrides(): void;
-```
-
-## Default values
-
-`getFlag` / `getConfig` take a caller-supplied default that is returned **only
-when the value can't be evaluated** — the client isn't initialized yet, or the
-key isn't in the loaded rules. A flag that legitimately evaluates to `false`
-(disabled, rule denied, rolled out to 0%) still returns `false`, never the
-default.
-
-```ts
-// Server
-flags.get("new_checkout", { user_id: "u1" });        // false for a missing flag
-flags.get("new_checkout", { user_id: "u1" }, true);  // true only if not-ready/not-found
-flags.getConfig("limits", { defaultValue: { max: 50 } }); // default when key absent
-
-// Browser (no user arg)
-client.getFlag("new_checkout");        // false for a missing flag
-client.getFlag("new_checkout", true);  // default when not-ready/not-found
-client.getConfig("limits", { defaultValue: { max: 50 } });
-```
-
-The legacy `getConfig(name, decode)` callback signature still works unchanged;
-the options object (`{ decode?, defaultValue? }`) is the new, additive form.
-
-## Evaluation detail
-
-`getFlagDetail(name[, user])` returns `{ value, reason }` (LaunchDarkly
-`variationDetail` parity) so you can see *why* a flag resolved the way it did:
+For unit tests, swap the live `configure()` for **`configureForTesting()`** — a drop-in sibling with **no network, ever** (no SDK key required). It replaces the active configuration with a network-free engine, seeds the values your code should see, and is read through the ordinary `new Client(user)`. In this mode the rules never fetch, `track()` / `logExposure()` are no-ops, and telemetry is off — your tests never touch the network.
 
 ```ts
-import type { FlagReason } from "@shipeasy/sdk/server"; // or /client
+import { configureForTesting, Client, clearOverrides } from "@shipeasy/sdk/server"; // or /client
 
-const d = client.getFlagDetail("new_checkout", { user_id: "u1" });
-// → { value: true, reason: "RULE_MATCH" }
-```
-
-`FlagReason` is one of:
-
-| reason             | meaning                                                     |
-| ------------------ | ---------------------------------------------------------- |
-| `CLIENT_NOT_READY` | no rules loaded yet (`init()` / `identify()` pending)      |
-| `FLAG_NOT_FOUND`   | the gate name isn't in the loaded rules                    |
-| `OFF`              | the gate exists but is disabled / killed (server only)     |
-| `OVERRIDE`         | a local override (or `?se_gate_…` URL override) decided it |
-| `RULE_MATCH`       | the gate evaluated `true`                                  |
-| `DEFAULT`          | the gate evaluated `false`                                 |
-
-`getFlag` is implemented on top of `getFlagDetail` (single evaluation, single
-telemetry beacon). On the browser the server pre-evaluates the gate's
-enabled/killed state into a boolean, so `OFF` folds into `DEFAULT` there.
-
-## Change listeners
-
-The server `FlagsClient` 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! });
-await client.init();
-const unsubscribe = client.onChange(() => {
-  console.log("flag rules changed — re-evaluating");
+// Seed everything the code under test should see (no key, no network):
+configureForTesting({
+  flags: { new_checkout: true },
+  configs: { upload_limits: { max_uploads: 50 } },
+  experiments: { hero_cta: ["treatment", { primary_label: "Buy now" }] },
 });
-// later…
-unsubscribe();
-```
-
-The browser `FlagsClientBrowser` already exposes the equivalent `subscribe()`
-(fires after each `identify()` / override change).
-
-## Offline snapshot
 
-Build a fully offline server client from a captured snapshot — zero network.
-Evaluations run the real eval against the snapshot; `init()`/`initOnce()`/
-`track()` are no-ops and overrides still apply on top. The snapshot is just the
-two SDK wire bodies:
-
-```jsonc
-// snapshot.json
-{
-  "flags":       /* body of GET /sdk/flags */,
-  "experiments": /* body of GET /sdk/experiments */
-}
-```
-
-```ts
-import { FlagsClient } from "@shipeasy/sdk/server";
-
-const client = FlagsClient.fromFile("./snapshot.json");
-// or, if you already hold the parsed object:
-const client = FlagsClient.fromSnapshot({ flags, experiments });
+const flags = new Client({ user_id: "u_1" }); // construct once per callsite
+flags.getFlag("new_checkout");                 // true
+flags.getConfig("upload_limits");              // { max_uploads: 50 }
+flags.getExperiment("hero_cta", { primary_label: "Sign up" });
+// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
 
-client.getFlag("new_checkout", { user_id: "u1" });
+clearOverrides(); // reset every seeded override back to the empty-blob default
 ```
 
-`fromFile` is Node-only (it reads the file with `node:fs`); `fromSnapshot` works
-anywhere.
-
-## Devtools overlay
-
-Press `Shift+Alt+S` on any page running the SDK (or append `?se=1` to the
-URL). The Shipeasy devtools panel mounts in a Shadow DOM overlay and lets
-you flip every gate / config / experiment / translation **for the current
-session only** — handy for QA, demos, and bug repro.
-
-## Documentation
-
-Full docs at [docs.shipeasy.ai](https://docs.shipeasy.ai). API surfaces
-covered there: targeting rules, holdouts, sequential stats, custom
-metrics, Slack digests, OAuth/SSO, Claude/MCP integration.
+More — the on-the-spot override helpers and a working example snapshot file — on
+the [Testing](https://github.com/shipeasy-ai/sdk/blob/main/docs/pages/testing.md) page.
 
 ## License
 
-[Shipeasy-SAL 1.0](./LICENSE) — source-available, non-commercial-use,
-permitted for use as a Shipeasy client.
+See [LICENSE](https://github.com/shipeasy-ai/sdk/blob/main/LICENSE). Evaluation is tested against the cross-language
+MurmurHash3 vectors in `experiment-platform/04-evaluation.md`.

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.
@@ -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 };