@avsbhq/node 1.6.1 → 1.7.0

package/README.md

@@ -1,8 +1,8 @@
 # @avsbhq/node
 
-Node.js server-side SDK for the [A vs B](https://app.avsb.cloud) platform.
+Node.js server SDK for [A vs B](https://app.avsb.cloud).
 
-Evaluate feature flags, bucket users consistently, and track conversion events on the server. Includes Express and Fastify middleware, real-time datafile streaming over SSE, pluggable sticky bucketing (in-memory and Redis), multi-context evaluation, and per-request decision logs.
+Evaluate feature flags, bucket users consistently, and track conversions on the server. Includes Express and Fastify middleware, real-time datafile streaming over SSE (on by default), pluggable sticky bucketing (in-memory and Redis), multi-context evaluation, and per-request decision logs.
 
 ---
 
@@ -12,62 +12,124 @@ Evaluate feature flags, bucket users consistently, and track conversion events o
 npm install @avsbhq/node
 ```
 
-Requires Node.js 18 or later.
+Requires Node.js 18 or later. No mandatory peer dependencies.
 
-No mandatory peer dependencies. Express and Fastify middleware are included but only activated when the corresponding framework is present. Install `@avsbhq/utils` for additional middleware (Hono, Koa, Lambda, Cloudflare Workers), OpenFeature integration, and warehouse-native decision sinks.
+Install `@avsbhq/utils` as well for the other framework adapters (Hono, Koa, Next, Lambda, Cloudflare Workers), the OpenFeature provider, and the warehouse decision sinks.
 
 ---
 
 ## 2. Quickstart
 
 ```ts
-import { AvsbServer } from '@avsbhq/node'
+import { AvsbServer } from '@avsbhq/node';
 
-const server = new AvsbServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-})
+const server = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! });
 
-const result = await server.onReady()
+const result = await server.onReady();
 if (!result.success) {
-  process.exit(1)  // or degrade gracefully: result.degraded === true means defaults are safe
+  // Flags serve the defaults you pass until a datafile arrives, and polling
+  // continues in the background. Survivable, not fatal.
+  console.error('AvsB init failed', result.error);
 }
 
-// Evaluate per-request via forUser()
-const user = server.forUser({ kind: 'user', key: 'u_123', plan: 'pro' })
+// Bind the context once per request.
+const user = server.forUser({ kind: 'user', key: 'u_123', plan: 'pro' });
 
-const flag = user.getBoolFlag('new-checkout-flow', false)
-if (flag.isEnabled()) {
-  renderNewCheckout()
-}
+const flag = user.getBoolFlag('new-checkout-flow', false);
+const checkoutTemplate = flag.isEnabled() ? 'checkout-v2' : 'checkout-v1';
 
-user.track('checkout_started', { value: 99.0 })
+user.track('checkout_started', { revenue: 99.0 });
 ```
 
-Instantiate `AvsbServer` once at app boot. The server holds the datafile in memory and refreshes it on a polling interval (or via SSE when `streaming: true`).
+Construct `AvsbServer` once at boot. It holds the datafile in memory, refreshes over SSE when the environment publishes, and falls back to polling when streaming is unavailable.
 
 ---
 
-## 3. SDK keys
+## 3. Constructor options
+
+Every type named on this page is exported by the package, so the shapes below (and your own declarations) can import them:
+
+```ts
+import type {
+  DecideOption,
+  DecisionLog,
+  EvalContext,
+  EvaluationSource,
+  Flag,
+  FlagDatafile,
+  GetAllFlagsOptions,
+  Logger,
+  ServerGetFlagOptions,
+  StickyBucketService,
+} from '@avsbhq/node';
+```
 
-Get the SDK key for the environment you want to target from your A vs B project's Environments page. The key format is `sdk_<environment>_<id>` (e.g. `sdk_production_clp1a2b3c4d5e6`).
+```ts
+interface AvsbServerOptions {
+  /** `sdk_<environment>_<id>`, e.g. sdk_production_ttqm0eaj4vth1krcb2xn. */
+  sdkKey: string;
+  /** Polling interval in ms. Default 60_000. Clamped to a 5_000 minimum, jittered. */
+  pollingInterval?: number;
+  /** Datafile CDN host. Default 'https://cdn.avsb.cloud'. */
+  cdnHost?: string;
+  /** Max ms onReady() waits for the first datafile. Default 10_000. */
+  initTimeout?: number;
+  /** A datafile you already have, so onReady() resolves with no network call. */
+  bootstrap?: FlagDatafile;
+  /** SSE datafile updates. Default TRUE on the server. */
+  streaming?: boolean;
+  /** Stream ticket endpoint. Overrides the datafile's own `streamEndpoint`. */
+  streamingEndpoint?: string;
+  /** Event tracker tuning. */
+  events?: EventOptions;
+  /** Sticky bucketing store. */
+  stickyBucketService?: StickyBucketService;
+  /** Your logger. Default: console at warn level outside production. */
+  logger?: Logger;
+  /** Shorthand for the default logger's level. 'silent' restores no output. */
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+
+interface EventOptions {
+  /** Ms between automatic flushes. Default 2000. */
+  flushInterval?: number;
+  /** Max events per request. Default 10. */
+  batchSize?: number;
+  /** Queue cap; oldest dropped with a warning. Default 10_000. */
+  maxQueueSize?: number;
+  /** Retry attempts per failed flush. Default 3. */
+  retryAttempts?: number;
+}
+```
+
+### SDK keys
+
+Copy the key for the environment you want from app.avsb.cloud, then Settings, then Environments. The format is `sdk_<environment>_<id>`.
 
 ```bash
-AVSB_SDK_KEY=sdk_production_...
+AVSB_SDK_KEY=sdk_production_ttqm0eaj4vth1krcb2xn
 ```
 
-When used server-side, the SDK key only ever needs to leave the server to hit the datafile CDN; it should never end up in client-rendered HTML, browser bundles, or browser-accessible config. Store it in environment variables only.
+The shape is checked at construction. A key that does not look like one is logged with what looked wrong and where the real key lives; the SDK carries on with the value you passed, because the datafile request is the real arbiter.
 
-Server SDK keys cannot be rotated without a process restart; the new key must be set in the environment before the server boots (or trigger a rolling restart in your orchestrator).
+Keep the key in environment variables. The SDK reads it once, at construction, so moving an environment to a new key means setting the new value and restarting the process (or constructing a new client and closing the old one).
 
 ---
 
 ## 4. Identity
 
-The server SDK is stateless per request; it does not hold a persistent context. Pass the user context on each call using `forUser()` or as a `context` option on individual calls.
+The server holds no context of its own: you supply it per request. The examples below read a request object shaped like this, whatever your framework calls it:
 
-### `forUser(context)` / `createUserContext(context)`
+```ts
+interface AppRequest {
+  user: { id: string; plan: string; country: string };
+  org: { id: string; tier: string };
+}
+
+declare const req: AppRequest;
+```
 
-Creates a `UserBoundClient` scoped to the given context. All flag and track calls on the returned client use that context automatically. Carries its own per-request decision log.
+### `forUser(context)`, the primary pattern
 
 ```ts
 const user = server.forUser({
@@ -75,184 +137,269 @@ const user = server.forUser({
   key: req.user.id,
   plan: req.user.plan,
   country: req.user.country,
-})
+});
 
-const flag = user.getBoolFlag('checkout-v2', false)
-user.track('page_viewed', { properties: { page: '/checkout' } })
+const flag = user.getBoolFlag('checkout-v2', false);
+user.track('page_viewed');
 ```
 
-`createUserContext` is an ergonomic alias for `forUser`.
+`createUserContext(context)` is an alias for the same thing. The returned `UserBoundClient` carries its own decision log and its own forced decisions.
 
 ### Per-call context
 
-Pass `context` in the options object when not using `forUser()`:
+Context is the THIRD POSITIONAL argument on every evaluation call, matching `@avsbhq/edge`:
 
 ```ts
 const flag = server.getBoolFlag('checkout-v2', false, {
-  context: { kind: 'user', key: 'u_123', plan: 'pro' },
-})
+  kind: 'user',
+  key: 'u_123',
+  plan: 'pro',
+});
+```
+
+Calling without a context returns your default with `source: 'not_ready'` and warns once, naming `forUser`. There is nobody to evaluate for.
+
+### Multi-context
+
+```ts
+const user = server.forUser({
+  kind: 'multi',
+  user: { kind: 'user', key: req.user.id, plan: req.user.plan },
+  organization: { kind: 'organization', key: req.org.id, tier: req.org.tier },
+});
+// A rule can target organization.tier while bucketing on user.key.
 ```
 
 ### Commerce targeting attributes
 
-Audiences built with the commerce condition types (cart value, products viewed, purchase history) evaluate from attributes you supply on the context. The attribute names are fixed:
+Audiences built with the commerce condition types (cart value, products viewed, purchase history) read fixed attribute names off the context:
 
 ```ts
 const flag = server.getBoolFlag('big-cart-banner', false, {
-  context: {
-    kind: 'user',
-    key: 'u_123',
-    cartValue: 120.5, // decimal MAJOR units of the project currency
-    viewedSkus: ['SKU-1', 'SKU-2'], // for "products viewed" matching on SKU
-    viewedCategories: ['trainers'], // for "products viewed" matching on category
-    purchaseHistory: {
-      // PurchaseHistoryAttribute, exported for your own declarations
-      hasPurchased: true,
-      lastPurchaseAt: 1765500000000, // epoch milliseconds (optional)
-      lifetimeSpend: 540.0, // decimal MAJOR units (optional)
-      orderCount: 7, // optional
-    },
+  kind: 'user',
+  key: 'u_123',
+  cartValue: 120.5, // decimal MAJOR units of the project currency
+  viewedSkus: ['SKU-1', 'SKU-2'], // "products viewed" matching on SKU
+  viewedCategories: ['trainers'], // "products viewed" matching on category
+  purchaseHistory: {
+    // PurchaseHistoryAttribute, exported for you
+    hasPurchased: true,
+    lastPurchaseAt: 1765500000000, // epoch milliseconds (optional)
+    lifetimeSpend: 540.0, // decimal MAJOR units (optional)
+    orderCount: 7, // optional
   },
-})
+});
 ```
 
-Server-side semantics to be aware of:
-
-- **All money is decimal major units.** Condition values are stored in minor units and converted using the project currency exponent from the datafile (default 2); you never pass minor units.
-- **Missing or mistyped attributes evaluate the condition to `false`.** A completely absent `purchaseHistory` makes ALL purchase-history operators false, including `has_not_purchased`. On the server, absence means "not provided", not "never purchased" (this deliberately diverges from the browser snippet, where a profile miss is authoritative).
-- **Dataset-backed "products viewed" conditions evaluate `false` on the server.** Dataset view windows live in the browser; server callers use literal SKU/category lists. The session/30-day window distinction is also browser-only; supply whatever view list you consider current.
+- **All money is decimal major units.** Condition values are stored in minor units and converted with the project currency exponent from the datafile (default 2); you never pass minor units.
+- **Missing or mistyped attributes evaluate to `false`.** A completely absent `purchaseHistory` makes every purchase-history operator false, including `has_not_purchased`. On the server, absence means "not provided", not "never purchased". This deliberately differs from the browser snippet, where a profile miss is authoritative.
+- **Dataset-backed "products viewed" conditions evaluate `false` on the server.** Dataset view windows live in the browser; server callers pass literal SKU or category lists.
 
-### `alias(previousContext, newContext)`
+### `alias(previousContext, newContext): void`
 
-Send an alias event linking two identities in the analytics pipeline. Typically called server-side when a user signs up or links an anonymous session to an account:
+Marks the moment a signup or login claimed an anonymous session. Synchronous.
 
 ```ts
-await server.alias(
-  { kind: 'user', key: anonymousId },
-  { kind: 'user', key: user.id }
-)
+const anonymousId = 'anon_7f3c9d2b'; // the key you evaluated with before login
+const signedInId = 'u_123'; // the key you evaluate with from now on
+
+server.alias({ kind: 'user', key: anonymousId }, { kind: 'user', key: signedInId });
 ```
 
+What it does: queues one `avsb_alias` event for the new identity.
+
+What it does NOT do, precisely: it does not rewrite sticky assignments, move past exposures, or store the previous key (the conversion wire carries no properties column, so a retroactive session join is not available yet). To keep one visitor's bucketing across a login, evaluate with the SAME context key on both sides.
+
 ### Sharing identity with the web snippet
 
-To measure one metric across both the A vs B web snippet and this SDK (the setup behind cross-project metrics), the context `key` must equal the browser snippet's visitor id: the `_avsb_visitor` cookie UUID returned by `avsb.getVisitorId()`. Results join on raw id equality, so a different key means the two surfaces never line up. Forward the snippet id from the browser and use it as the key here, or link an internal account id to it with `alias()`. Full guide: [Shared Visitor Identity](https://avsb.cloud/docs/developer-reference/shared-visitor-identity).
+To measure one metric across the A vs B web snippet and this SDK, the context `key` must equal the snippet's visitor id: the `_avsb_visitor` cookie UUID that `avsb.getVisitorId()` returns. Results join on raw id equality, so a different key means the two surfaces never line up. Forward the snippet id from the browser and use it as the key here. Full guide: [Shared Visitor Identity](https://avsb.cloud/docs/developer-reference/shared-visitor-identity).
 
 ---
 
-## 5. Multi-context
+## 5. Reading flags
 
-Pass a multi-context to evaluate flags against multiple context kinds simultaneously:
+### Signatures
 
 ```ts
-const user = server.forUser({
-  kind: 'multi',
-  user: { kind: 'user', key: req.user.id, plan: req.user.plan },
-  organization: { kind: 'organization', key: req.org.id, tier: req.org.tier },
-})
+getFlag<T>(flagKey: string, defaultValue: T, context?: EvalContext, options?: ServerGetFlagOptions): Flag<T>
+getBoolFlag(flagKey: string, defaultValue: boolean, context?: EvalContext, options?: ServerGetFlagOptions): Flag<boolean>
+getStringFlag(flagKey: string, defaultValue: string, context?: EvalContext, options?: ServerGetFlagOptions): Flag<string>
+getNumberFlag(flagKey: string, defaultValue: number, context?: EvalContext, options?: ServerGetFlagOptions): Flag<number>
+getJsonFlag<T>(flagKey: string, defaultValue: T, context?: EvalContext, options?: ServerGetFlagOptions): Flag<T>
+getAllFlags(context?: EvalContext, options?: GetAllFlagsOptions): Record<string, Flag>
+```
+
+The two options bags those signatures name:
+
+```ts
+interface ServerGetFlagOptions {
+  decideOptions?: DecideOption[];
+  decisionLog?: DecisionLog;
+}
 
-const flag = user.getBoolFlag('enterprise-dashboard', false)
-// The rule may target organization.tier and bucket on user.key simultaneously
+interface GetAllFlagsOptions {
+  /** Record an exposure per flag. Default FALSE. */
+  fireExposures?: boolean;
+  decideOptions?: DecideOption[];
+  decisionLog?: DecisionLog;
+}
 ```
 
----
+On a `UserBoundClient` the context is already bound, so the same calls read `getBoolFlag(key, default, options?)`.
 
-## 6. Reading flags
+One deliberate difference from `@avsbhq/browser`: there, `getAllFlags` takes an options bag (`getAllFlags({ context })`) because the browser client is context-bound and the bag disambiguates its optional arguments; here the context is the first positional argument, matching every other server evaluation call.
 
-### Typed variants (recommended)
+Typed getters check the value against the flag's declared type in the datafile. On a mismatch they log a warning naming both types and return YOUR default; they never throw and never coerce.
+
+### The `Flag<T>` object
 
 ```ts
-const darkMode    = user.getBoolFlag('dark-mode', false)
-const theme       = user.getStringFlag('theme', 'light')
-const maxItems    = user.getNumberFlag('max-results', 25)
-const config      = user.getJsonFlag<{ timeout: number }>('api-config', { timeout: 5000 })
+interface Flag<T = unknown> {
+  readonly value: T;
+  readonly variationKey: string | null;
+  readonly source: EvaluationSource;
+  readonly ruleId: string | null;
+  readonly ruleType: 'targeted_delivery' | 'ab_test' | 'holdout' | 'bandit' | null;
+  readonly reasons: string[];
+  readonly evaluatedAt: number;
+  readonly durationMicros: number;
+  isEnabled(): boolean;
+  exists(): boolean;
+}
 ```
 
-Each typed variant performs a runtime type check against the datafile's declared flag type. A mismatch logs a warning and returns the default.
+`isEnabled()` is true only when a REAL decision produced a truthy value: sources `rule`, `holdout`, `bandit`, `runtimeOverride`, `datafileOverride`, `sticky`. It is always false for `default`, `not_found`, `disabled`, and `not_ready`.
 
-### Generic `getFlag<T>`
+`exists()` answers "is this key in the datafile": false for `not_found`, and false for `not_ready` because with no datafile the question is unanswerable.
 
-```ts
-const flag = server.getFlag<boolean>('checkout-v2', false, {
-  context: { kind: 'user', key: 'u_123' },
-})
-```
+| `source`           | Meaning                                                                        |
+| ------------------ | ------------------------------------------------------------------------------ |
+| `datafileOverride` | A per-user override configured in the dashboard matched.                       |
+| `runtimeOverride`  | `setOverrideForUser`, `setGlobalOverride`, or a forced decision matched.       |
+| `sticky`           | A stored assignment was reused.                                                |
+| `rule`             | A targeting or A/B rule matched.                                               |
+| `holdout`          | The context is held out; the holdout variation was served.                     |
+| `bandit`           | A bandit rule picked the variation.                                            |
+| `default`          | The flag exists, nothing matched, its default variation was served.            |
+| `disabled`         | The flag exists but is off in this environment.                                |
+| `not_found`        | The datafile loaded and has no such key. Check the key name.                   |
+| `not_ready`        | No datafile yet, or no context passed. Await `onReady()`, or pass `bootstrap`. |
 
-### The `Flag<T>` object
+### `DecideOption`
 
 ```ts
-flag.value          // T, the variation value
-flag.isEnabled()    // true if source === 'rule' && value is truthy
-flag.variationKey   // 'on' | 'off' | 'control' | null (null = default served)
-flag.exists()       // false when source === 'not_found'
-flag.source         // 'rule' | 'sticky' | 'holdout' | 'datafileOverride' | 'default' | ...
-flag.ruleId         // which rule matched
-flag.reasons        // string[], evaluation path
+import { DecideOption } from '@avsbhq/node';
+
+user.getBoolFlag('checkout-v2', false, {
+  decideOptions: [DecideOption.DISABLE_EXPOSURE],
+});
 ```
 
-### `getAllFlags(context, options?)`
+Two members, both accepted:
+
+- `DISABLE_EXPOSURE` evaluates without recording an exposure. Use it for admin panels, previews, and bulk reads.
+- `INCLUDE_REASONS` asks for reason strings. This SDK collects reasons unconditionally, so passing it changes nothing here; it is real in the per-language SDKs that gate reason collection behind it.
+
+Anything else warns once with the accepted list. `EXCLUDE_VARIABLES`, `IGNORE_STICKY_BUCKET`, and `ENABLED_FLAGS_ONLY` were deleted: no evaluator in any language implemented them.
+
+### `getAllFlags`
 
 ```ts
-const all = server.getAllFlags({ kind: 'user', key: 'u_123' })
-// Exposures are suppressed by default. Pass { fireExposures: true } to enable.
+const all = server.getAllFlags({ kind: 'user', key: 'u_123' });
+// Exposures are suppressed by default. Pass { fireExposures: true } to record them.
 ```
 
-### Forced decisions (QA / testing)
+Called without a context, or before the datafile loads, it returns `{}` AND warns, because an empty map is otherwise indistinguishable from a project with no flags.
 
-```ts
-// Override for a specific user context key
-server.setOverrideForUser('checkout-v2', 'u_qa', 'on')
-server.setOverrideForUser('checkout-v2', 'u_qa', 'on', 'user')  // explicit kind
+### Overrides, for QA and testing
 
-// Global override (all contexts)
-server.setGlobalOverride('checkout-v2', 'on')
+```ts
+server.setOverrideForUser('checkout-v2', 'u_qa', 'on');
+server.setOverrideForUser('checkout-v2', 'acme', 'on', 'organization'); // explicit kind
+server.setGlobalOverride('checkout-v2', 'on');
 
-// Clear
-server.clearOverrideForUser('checkout-v2', 'u_qa')
-server.clearGlobalOverride('checkout-v2')
-server.clearAllOverrides()
+server.clearOverrideForUser('checkout-v2', 'u_qa');
+server.clearGlobalOverride('checkout-v2');
+server.clearAllOverrides();
 ```
 
-Per-request forced decisions (bound to a `UserBoundClient`):
+Per-request forced decisions, which never touch the shared state above:
 
 ```ts
-const user = server.forUser(ctx)
-user.setForcedDecision('checkout-v2', { variationKey: 'on' })
-user.clearForcedDecision('checkout-v2')
+const user = server.forUser({ kind: 'user', key: 'u_qa' });
+user.setForcedDecision('checkout-v2', { variationKey: 'on' });
+user.clearForcedDecision('checkout-v2');
 ```
 
 ---
 
-## 7. Tracking events
+## 6. Tracking
 
 ```ts
-user.track('purchase_completed', {
-  value: 199.0,
-  properties: { plan: 'annual', sku: 'PRO_ANNUAL' },
-})
+// Bound client: context implied.
+user.track('purchase_completed', { revenue: 199.0 }); // money
+user.track('items_added', { value: 3 }); // a quantity
+user.track('signup_completed'); // a count
+
+// Server directly: context in the payload.
+server.track('purchase_completed', {
+  revenue: 199.0,
+  context: { kind: 'user', key: 'u_123' },
+});
 ```
 
-When called directly on `server` (not via `forUser`), include `context`:
+`TrackPayload` carries two numbers, and they are two columns end to end:
+
+| Field     | Meaning                                                                 | Storage column          |
+| --------- | ----------------------------------------------------------------------- | ----------------------- |
+| `revenue` | Money in decimal MAJOR units of the project currency (49.99, not 4999). | `metric_events.revenue` |
+| `value`   | Numeric metric value for average-value metrics: items, seats, seconds.  | `metric_events.value`   |
+
+One conversion can carry money, a quantity, or both. Earlier releases mapped `value` into the revenue column and could never write the value column, so a quantity was recorded as money and every average-value metric read empty.
+
+`track` is synchronous: it queues the event and the tracker batches it. Events tracked before the datafile arrives are QUEUED (bounded by `events.maxQueueSize`) and sent once it does.
+
+`payload.properties` is accepted by the shared type but NOT stored for conversions: the ingestion contract for a metric event keeps the event name, the two numbers, the timestamp, and the visitor id. The SDK warns once and drops them rather than pretending. Exposure events do carry properties.
+
+### Purchases
 
 ```ts
-server.track('purchase_completed', {
-  value: 199.0,
-  context: { kind: 'user', key: 'u_123' },
-  properties: { plan: 'annual' },
-})
+await server.trackPurchase('u_123', {
+  orderId: 'order_1001',
+  total: 199.0,
+  currency: 'USD',
+  items: [{ sku: 'PRO_ANNUAL', price: 199.0, quantity: 1 }],
+});
+
+// Or from a bound client, attributed to its context key:
+await user.trackPurchase({ orderId: 'order_1001', total: 199.0 });
 ```
 
-Events are synchronous calls that queue the event for batch flushing. There is no `await` on `track`.
+Purchases are queued before ready exactly like `track`. They used to be dropped with a warning while `track` queued.
+
+### Manual exposure
+
+```ts
+const flag = user.getBoolFlag('checkout-v2', false, {
+  decideOptions: [DecideOption.DISABLE_EXPOSURE],
+});
+
+// Later, at the point the visitor actually sees the variation:
+user.manualExposure('checkout-v2');
+```
 
 ---
 
-## 8. Error handling
+## 7. Errors, logging, and events
+
+### Logger
 
-### `logger` option
+The default is a console logger at WARN level when `NODE_ENV` is neither `production` nor `test`, and a noop otherwise. A wrong SDK key is loud in development and silent in production logs.
 
 ```ts
-import { AvsbServer, createLogger } from '@avsbhq/node'
-import pino from 'pino'
-import { createPinoTransport } from '@avsbhq/utils/log/pino'
+import { AvsbServer, createLogger } from '@avsbhq/node';
+import pino from 'pino';
+import { createPinoTransport } from '@avsbhq/utils/log/pino';
 
 const server = new AvsbServer({
   sdkKey: process.env.AVSB_SDK_KEY!,
@@ -260,242 +407,399 @@ const server = new AvsbServer({
     level: 'info',
     transports: [createPinoTransport({ logger: pino(), level: 'info' })],
   }),
-})
+});
+
+// Or just turn the volume down:
+new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY!, logLevel: 'silent' });
 ```
 
-### `onReady()` error handling
+### `onReady()`
 
 ```ts
-const result = await server.onReady()
-// result.success: boolean
-// result.source: 'network' | 'bootstrap' | 'timeout' | 'error'
-// result.degraded: true means init failed but defaults are served; polling continues
-if (!result.success && !result.degraded) {
-  throw result.error
+interface InitResult {
+  success: boolean;
+  source: 'network' | 'bootstrap' | 'timeout' | 'error';
+  error?: Error;
+  /** Serving stale-but-real values after a failed refresh. Not set by this SDK today. */
+  degraded?: boolean;
+}
+
+const result = await server.onReady();
+if (!result.success) {
+  // result.source is 'timeout' or 'error'; result.error says which.
 }
 ```
 
-`onReady()` never rejects; it always resolves. Check `result.success` to decide whether to proceed.
+`onReady()` never rejects and returns the same promise on repeated calls. `isReady()` answers "are flags readable right now" synchronously.
 
-### Event bus
+### Events
 
 ```ts
-const unsubscribe = server.on('error', (err) => {
-  myLogger.error('SDK error', { error: err.message })
-})
-
+server.on('ready', () => {});
 server.on('configUpdate', ({ publishedAt, reason }) => {
-  myLogger.info('datafile refreshed', { publishedAt, reason })
-})
+  // reason: 'poll' | 'stream' | 'manual'
+});
+server.on('evaluation', ({ flagKey, flag, contextKeys }) => {});
+server.on('exposure', (event) => {
+  // Same eventId the ingestion pipeline receives, so your own analytics rows
+  // reconcile with A vs B results.
+});
+server.on('error', (error) => {});
+server.on('stickyOrphan', ({ flagKey, userId, assignment }) => {});
+
+// on() returns the unsubscribe:
+const unsubscribe = server.on('error', (error) => console.error(error));
+unsubscribe();
 ```
 
+The payloads are the shared `ClientEventMap` shapes, so a listener written against `@avsbhq/browser` reads the same fields here. The server does not emit `flagChange`: it holds one datafile for the process and does not diff individual flags. Subscribing to it through `client.utils` warns and hands back a no-op disposer.
+
 ---
 
-## 9. SSR / hydration
+## 8. Heartbeat and SDK health
+
+The SDK reports liveness to the endpoint the datafile publishes
+(`heartbeatEndpoint`), so the dashboard can show whether an environment is
+actually being served.
+
+- **What it posts**: `{ sdkKey, sdkType, sdkVersion }`, nothing else. No flag
+  values, no context, no counts.
+- **When**: on every successful datafile REQUEST (init, poll, stream-triggered
+  refresh, and `refreshDatafile()`), throttled to at most one every 2 minutes.
+  A `304 Not Modified` counts: the SDK sends a conditional request once it has
+  an ETag, so an unchanged datafile answers 304 on every poll, and that is
+  exactly the steady state of a healthy process.
+- **Fire and forget**: a failed heartbeat is dropped, never retried, and never
+  affects evaluation.
+- **Where it shows up**: Settings, then Environments, in the dashboard. Each
+  environment shows Connected, Stale, or Not connected, plus the `sdkType` and
+  `sdkVersion` that last reported, which is how you see "production is running
+  @avsbhq/node 1.6.2". An environment goes Stale after five minutes without a
+  heartbeat.
+- **Turning it off**: publish a datafile with no `heartbeatEndpoint`. The SDK
+  never guesses a host, so an absent field simply means no heartbeats.
+
+---
 
-Not applicable to server-side Node.js usage. For Next.js App Router SSR, see `@avsbhq/next` which provides `getDatafile`, `evaluateFlagServer`, and `AvsbHydrator` for the server-to-client bootstrap handoff.
+## 9. Streaming
 
-For server-side rendering outside of Next.js, fetch the datafile via `bootstrap` to avoid an extra round-trip:
+Streaming is ON by default. The endpoint comes from the datafile's `streamEndpoint` field, which the publisher controls, so a self-hosted or proxied deployment needs no client-side configuration.
 
 ```ts
-const server = new AvsbServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  bootstrap: cachedDatafile,  // pre-fetched FlagDatafile object
-})
-// onReady() resolves immediately with source: 'bootstrap'
+const sdkKey = process.env.AVSB_SDK_KEY!;
+const streamingEndpoint = 'https://stream.avsb.cloud/v1/ticket';
+
+new AvsbServer({ sdkKey }); // streaming on, endpoint from the datafile
+new AvsbServer({ sdkKey, streaming: false }); // polling only
+new AvsbServer({ sdkKey, streamingEndpoint }); // explicit endpoint wins
 ```
 
----
+If no endpoint is available, or the stream drops, the SDK keeps polling and logs the reason at debug level. Nothing is guessed from another host: pointing a reconnect loop at DNS that does not resolve is the failure mode this design exists to prevent.
 
-## 10. Graceful shutdown
+---
 
-### SIGTERM handler
+## 10. Bootstrap and serverless cold starts
 
 ```ts
-process.on('SIGTERM', async () => {
-  await server.close()  // abort in-flight fetches, drain events
-  process.exit(0)
-})
+import type { BootstrapBlob } from '@avsbhq/utils';
+
+// You already have the datafile (KV, a file, a cache), and a blob from a
+// server that called serializeBootstrap.
+declare const cachedDatafile: FlagDatafile;
+declare const blob: BootstrapBlob;
+
+const server = new AvsbServer({ sdkKey, bootstrap: cachedDatafile });
+// onReady() resolves immediately with source: 'bootstrap'.
+
+// Or hand it over after construction:
+server.applyDatafileBootstrap(cachedDatafile);
+
+// Same thing through the bootstrap blob helpers:
+server.utils.hydrateBootstrap(blob); // blob must carry `datafile`
 ```
 
-`close()` calls `server.flush()` internally, then aborts any open streaming connections and stops polling.
+`hydrateBootstrap` THROWS on a blob that carries only a pre-evaluated snapshot: a snapshot belongs to one context, and a server evaluates a different context per request, so adopting one process-wide would serve one user's values to another. Serialize with `{ includeDatafile: true }`, or pass `bootstrap: blob.datafile`.
+
+For Next.js SSR see `@avsbhq/next`.
+
+---
 
-### Manual flush
+## 11. Shutdown
 
 ```ts
-await server.flush()  // drain queued events without teardown
+process.on('SIGTERM', async () => {
+  await server.close();
+  process.exit(0);
+});
+
+await server.flush(); // drain queued events without tearing down
 ```
 
+`close()` aborts in-flight fetches, disconnects the stream, stops polling, and drains the event queue.
+
 ---
 
-## 11. Testing
+## 12. Verifying inbound webhooks
+
+AvsB signs every outbound webhook delivery with HMAC-SHA256 over `deliveryId + "." + timestamp + "." + rawBody` (the Standard Webhooks scheme). `verifyWebhookSignature` checks it against the **raw** body bytes, enforces a replay window, and compares digests in constant time.
 
 ```ts
-import { createMockClient, TestData } from '@avsbhq/test'
+// docs-example: not typechecked here, because express is not a dependency of the A vs B repository, so its Request and Response types cannot be resolved for the route handler
+
+import express from 'express';
+import { verifyWebhookSignature } from '@avsbhq/node';
 
-const td = TestData.flag('checkout-v2')
-  .booleanFlag()
-  .variationForUser('u_test', true)
-  .fallthroughVariation(false)
+const app = express();
 
-const mock = createMockClient({ flags: [td.build()] })
-// mock has the same interface as AvsbServer; inject it in tests
+async function handleEvent(deliveryId: string, event: unknown): Promise<void> {
+  // your own idempotent processing, keyed on deliveryId
+}
+
+// express.raw(), NOT express.json(): parsing and re-serialising the body changes
+// its bytes, and the signature is over the bytes we sent.
+app.post('/avsb-webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const result = verifyWebhookSignature(req.body, req.headers, process.env.AVSB_WEBHOOK_SECRET!);
+  if (!result.ok) {
+    // 'missing_headers' | 'malformed_signature' | 'malformed_timestamp'
+    // | 'timestamp_out_of_tolerance' | 'signature_mismatch'
+    return res.status(401).send(result.reason);
+  }
+
+  const event = JSON.parse(req.body.toString('utf8'));
+  void handleEvent(result.deliveryId, event); // retries reuse the id: dedupe on it
+  res.sendStatus(200);
+});
 ```
 
-For assertion helpers:
+| Option             | Default    | Notes                                                                                                             |
+| ------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------- |
+| `toleranceSeconds` | `300`      | Reject deliveries signed more than this long ago (or ahead, so clock skew is caught). `0` disables the age check. |
+| `now`              | `Date.now` | Injectable clock, for tests.                                                                                      |
 
-```ts
-import { recordEvaluations } from '@avsbhq/test'
+Works with Node's `req.headers`, a plain object with any casing, or anything exposing `get(name)` (a `Headers` instance, a Next.js `Request`).
+
+---
 
-const recorder = recordEvaluations(mock)
-callCodeUnderTest(mock)
-expect(recorder).toHaveEvaluated('checkout-v2')
-  .withContext({ kind: 'user', key: 'u_test' })
-  .withValue(true)
+## 13. Testing
+
+```ts
+import { createMockServer, flagsFromTestData, TestData } from '@avsbhq/test';
+
+const server = createMockServer(
+  flagsFromTestData([
+    TestData.flag('checkout-v2')
+      .booleanFlag()
+      .variationForUser('u_paying', true)
+      .fallthroughVariation(false)
+      .build(),
+  ]),
+);
+
+const user = server.forUser({ kind: 'user', key: 'u_paying' });
+expect(user.getBoolFlag('checkout-v2', false).value).toBe(true);
+expect(server._evaluations()).toHaveLength(1);
 ```
 
+`createMockServer` mirrors this SDK's surface, `forUser` included. `createMockClient` mirrors the browser client. Both read the same fixture through `flagsFromTestData`.
+
 ---
 
-## 12. Framework integrations
+## 14. Framework integrations
 
 ### Express
 
 ```ts
-import express from 'express'
-import { AvsbServer, expressMiddleware } from '@avsbhq/node'
+import express from 'express';
+import { AvsbServer, expressMiddleware } from '@avsbhq/node';
+import { getRequestClient } from '@avsbhq/utils';
+
+const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! });
+await avsb.onReady();
+
+const app = express();
+app.use(
+  expressMiddleware(avsb, {
+    // The middleware reads the request structurally, so narrow it to whatever
+    // your auth layer put there.
+    contextFrom: (req) => {
+      const authed = req.user as { id?: string; plan?: string } | undefined;
+      return { kind: 'user', key: authed?.id ?? 'anon', plan: authed?.plan };
+    },
+  }),
+);
 
-const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! })
-await avsb.onReady()
+// Deep inside a service, with no `req` in scope:
+function pricingService() {
+  return getRequestClient()?.getBoolFlag('new-pricing', false).value ?? false;
+}
+```
 
-const app = express()
-app.use(expressMiddleware(avsb, {
-  contextFrom: (req) => ({
-    kind: 'user',
-    key: req.user?.id ?? 'anon',
-    plan: req.user?.plan,
-  }),
-}))
+Every route then reads flags off `req.avsb`:
+
+```ts
+// docs-example: not typechecked here, because express is not a dependency of the A vs B repository, so a route handler's Request and Response types cannot be resolved
 
 app.get('/checkout', (req, res) => {
-  const flag = req.avsb.getBoolFlag('new-checkout-flow', false)
-  res.render(flag.isEnabled() ? 'checkout-v2' : 'checkout-v1')
-})
+  const flag = req.avsb.getBoolFlag('new-checkout-flow', false);
+  res.render(flag.isEnabled() ? 'checkout-v2' : 'checkout-v1');
+});
 ```
 
-`expressMiddleware` decorates each request with `req.avsb`: a `UserBoundClient` scoped to the context returned by `contextFrom`. It also opens an `AsyncLocalStorage` scope so `getRequestClient()` from `@avsbhq/utils` works anywhere in the call chain.
+Return `undefined` from `contextFrom` to skip AvsB for that request.
+
+`expressMiddleware` and `fastifyPlugin` ARE the implementations from `@avsbhq/utils/middleware/*`, re-exported here so one dependency is enough. There is exactly one signature for each; this package used to ship a second, incompatible `expressMiddleware(client, { userIdFrom })`.
+
+Type `req.avsb` in your own project (four lines, once):
+
+```ts
+// src/types/express.d.ts
+import type { UserBoundClient } from '@avsbhq/node';
+
+declare global {
+  namespace Express {
+    interface Request {
+      avsb: UserBoundClient;
+    }
+  }
+}
+```
 
 ### Fastify
 
 ```ts
-import Fastify from 'fastify'
-import { AvsbServer, fastifyPlugin } from '@avsbhq/node'
+// docs-example: not typechecked here, because fastify is not a dependency of the A vs B repository, so neither the instance nor its route handler types can be resolved
+
+import Fastify from 'fastify';
+import { AvsbServer, fastifyPlugin } from '@avsbhq/node';
 
-const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! })
-await avsb.onReady()
+const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! });
+await avsb.onReady();
 
-const app = Fastify()
+const app = Fastify();
 await app.register(fastifyPlugin, {
   server: avsb,
-  contextFrom: (req) => ({
-    kind: 'user',
-    key: req.headers['x-user-id'] as string,
-  }),
-})
+  contextFrom: (req) => ({ kind: 'user', key: req.headers['x-user-id'] as string }),
+});
 
 app.get('/features', (req, reply) => {
-  const flag = req.avsb.getBoolFlag('new-feature', false)
-  reply.send({ enabled: flag.isEnabled() })
-})
+  reply.send({ enabled: req.avsb.getBoolFlag('new-feature', false).isEnabled() });
+});
 ```
 
+### Other frameworks
+
+Hono, Koa, Next (app and pages), Lambda, and Cloudflare Workers adapters live in `@avsbhq/utils/middleware/*`: `honoMiddleware`, `koaMiddleware`, `nextAppHandler`, `nextPagesApi`, `lambdaHandler`, `workersHandler`. All open the same AsyncLocalStorage scope, so `getRequestClient()` works under every one of them.
+
 ### Sticky bucketing
 
-Keep users in the same variation across rule changes. In-memory is suitable for single-process deployments:
+Keep users in the same variation across rule changes. Sticky lookup runs BEFORE the engine, so a stored assignment survives a rollout edit.
 
 ```ts
-import { InMemoryStickyBucketService } from '@avsbhq/node'
-
-const server = new AvsbServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  stickyBucketService: new InMemoryStickyBucketService(),
-})
+import { createClient } from 'redis';
+import { InMemoryStickyBucketService, RedisStickyBucketService } from '@avsbhq/node';
+
+// Single process:
+new AvsbServer({ sdkKey, stickyBucketService: new InMemoryStickyBucketService() });
+
+// Multi-process, multi-region:
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+new AvsbServer({
+  sdkKey,
+  stickyBucketService: new RedisStickyBucketService({ redis, prefix: 'avsb:sticky:' }),
+});
 ```
 
-Redis for multi-process and multi-region deployments:
+The Redis service keeps evaluation synchronous: a lookup is a cache hit or null, with a background fill, so the first lookup per process misses by design. DynamoDB, Postgres, and Durable Object services live in `@avsbhq/utils`.
 
-```ts
-import { createClient } from 'redis'
-import { RedisStickyBucketService } from '@avsbhq/node'
+### Decision logs
 
-const redis = createClient({ url: process.env.REDIS_URL })
-await redis.connect()
+```ts
+const user = server.forUser({ kind: 'user', key: 'u_123' });
+user.getBoolFlag('checkout-v2', false);
 
-const server = new AvsbServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  stickyBucketService: new RedisStickyBucketService({
-    redis,
-    prefix: 'avsb:sticky:',
-  }),
-})
+const entries = user.getDecisionLog().entries;
+// [{ flagKey, value, variationKey, source, ruleId, ruleType, reasons,
+//    evaluatedAt, durationMicros, contextSummary }]
 ```
 
-DynamoDB and PostgreSQL adapters are available in `@avsbhq/utils`.
-
-### Real-time streaming
-
-Enable SSE streaming to receive datafile updates the instant a flag changes, with no polling delay:
+Redaction is real: any attribute named in `_meta.privateAttributes` has its VALUE replaced with `[REDACTED]` wherever it appears in a logged value or a reason string. Values shorter than two characters are matched exactly rather than as substrings, because a one-character value cannot be told apart from ordinary text.
 
 ```ts
-const server = new AvsbServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  streaming: true,
-})
+server.forUser({
+  kind: 'user',
+  key: 'u_123',
+  email: 'ada@example.com',
+  _meta: { privateAttributes: ['email'] },
+});
 ```
 
-### Decision logs
+---
 
-Capture full evaluation reasons per request for debugging or audit:
+## 15. Migration
 
-```ts
-import { createDecisionLog } from '@avsbhq/node'
+### From LaunchDarkly Node
 
-const log = createDecisionLog()
-const user = server.forUser({ kind: 'user', key: 'u_123' })
-const flag = user.getBoolFlag('checkout-v2', false)
-// The bound client's decision log captures all evaluations automatically:
-const entries = user.getDecisionLog().entries
-// [{ flagKey, value, variationKey, source, ruleId, ruleType, reasons, evaluatedAt }]
-```
+| LaunchDarkly Node                                 | `@avsbhq/node`                                               |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| `init(sdkKey, options)`                           | `new AvsbServer({ sdkKey })`                                 |
+| `client.waitForInitialization()`                  | `await server.onReady()`                                     |
+| `client.variation('key', context, default)`       | `server.forUser(ctx).getBoolFlag('key', default).value`      |
+| `client.variationDetail('key', context, default)` | `server.forUser(ctx).getFlag('key', default)`                |
+| `client.track('event', context, { metricValue })` | `server.forUser(ctx).track('event', { value })`              |
+| `client.identify(context)`                        | not applicable (the server is stateless); use `forUser(ctx)` |
+| `client.allFlagsState(context)`                   | `server.getAllFlags(ctx)`                                    |
+| `client.close()`                                  | `await server.close()`                                       |
+
+Key differences: `getFlag` returns `Flag<T>`, not a raw value (`.value` for the primitive); `track` uses `value`, not `metricValue`; all evaluation is per-request via `forUser()`; multi-context is native.
+
+### From Statsig Node
+
+| Statsig Node                                               | `@avsbhq/node`                                               |
+| ---------------------------------------------------------- | ------------------------------------------------------------ |
+| `Statsig.initialize(serverSecret)`                         | `new AvsbServer({ sdkKey })`                                 |
+| `Statsig.checkGate(user, 'gate')`                          | `server.forUser(ctx).getBoolFlag('gate', false).isEnabled()` |
+| `Statsig.getExperiment(user, 'exp').get('param', default)` | `server.forUser(ctx).getFlag('exp', default).value`          |
+| `Statsig.logEvent(user, 'event', value, metadata)`         | `server.forUser(ctx).track('event', { value })`              |
+| `Statsig.flush()`                                          | `await server.flush()`                                       |
+
+### From an earlier @avsbhq/node
+
+| Was                                                                    | Now                                                                           |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `getFlag(key, default, { context })`                                   | `getFlag(key, default, context)`                                              |
+| `getAllFlags(context, opts)`                                           | same call; `context` is now optional and warns when omitted                   |
+| `expressMiddleware(client, { userIdFrom })`                            | `expressMiddleware(server, { contextFrom })`                                  |
+| Pre-ready reads reported `not_found`                                   | they report `not_ready`                                                       |
+| `evaluation` event `{ flagKey, value, userId, source }`                | `{ flagKey, flag, contextKeys }`                                              |
+| `DecideOption` members beyond `DISABLE_EXPOSURE` and `INCLUDE_REASONS` | deleted; they were never implemented                                          |
+| `streaming` defaulted to false                                         | defaults to true, with silent fallback to polling                             |
+| `track(key, { value: 199.0 })` for money                               | `track(key, { revenue: 199.0 })`; `value` now means an average-value quantity |
+| `server.alias(...)` documented but absent                              | implemented, synchronous, and documented for what it really does              |
 
 ---
 
-## 13. Migration
+## 16. Set this up with your AI assistant
 
-### From LaunchDarkly Node
+Paste this into Claude Code, Cursor, or any coding assistant:
 
-| LaunchDarkly Node | `@avsbhq/node` |
-|---|---|
-| `init(sdkKey, options)` | `new AvsbServer({ sdkKey })` |
-| `client.waitForInitialization()` | `await server.onReady()` |
-| `client.variation('key', context, default)` | `server.forUser(ctx).getBoolFlag('key', default).value` |
-| `client.variationDetail('key', context, default)` | `server.forUser(ctx).getFlag('key', default)` |
-| `client.track('event', context, { metricValue })` | `server.forUser(ctx).track('event', { value })` |
-| `client.identify(context)` | not applicable (server is stateless); use `forUser(ctx)` |
-| `client.allFlagsState(context)` | `server.getAllFlags(ctx)` |
-| `client.close()` | `await server.close()` |
-
-Key differences:
-- `getFlag` returns `Flag<T>` not a raw value. Access `.value` for the primitive.
-- `track` uses `value` (not `metricValue`) for the numeric metric.
-- The server is context-free at construction; all evaluation is per-request via `forUser()`.
-- Multi-context is native, with no `ldUser` adapter needed.
+```text
+Set up A vs B feature flags in this Node.js project.
 
-### From Statsig Node
+1. Run: npx @avsbhq/cli init
+   Use my saved CLI login: do not ask me for a token and do not put one in any file.
+   It writes the SDK key into .env as AVSB_SDK_KEY and writes an example file.
+2. Install @avsbhq/node with this project's package manager.
+3. Construct AvsbServer once at boot with that key, await server.onReady(), and
+   bind a context per request with server.forUser({ kind: 'user', key: userId }).
+4. Every getter returns a Flag object, so read .value or call .isEnabled(), and
+   always pass a fallback. Before the datafile arrives, reads return your fallback
+   and flag.source is 'not_ready'.
+5. Then run: npx @avsbhq/cli codegen
+
+Done looks like: the process starts, the flag reads without throwing, and avsb
+init prints the line confirming it saw the first check-in.
+```
 
-| Statsig Node | `@avsbhq/node` |
-|---|---|
-| `Statsig.initialize(serverSecret)` | `new AvsbServer({ sdkKey })` |
-| `Statsig.checkGate(user, 'gate')` | `server.forUser(ctx).getBoolFlag('gate', false).isEnabled()` |
-| `Statsig.getExperiment(user, 'exp').get('param', default)` | `server.forUser(ctx).getFlag('exp', default).value` |
-| `Statsig.logEvent(user, 'event', value, metadata)` | `server.forUser(ctx).track('event', { value, properties: metadata })` |
-| `Statsig.flush()` | `await server.flush()` |
+`avsb init` ends by waiting for your app's first check-in and printing what it
+saw, so the terminal tells you it works rather than the dashboard.