@avsbhq/node 0.3.0 → 1.2.0

package/README.md

@@ -2,267 +2,467 @@
 
 Node.js server-side SDK for the [A vs B](https://app.avsb.cloud) platform.
 
-Evaluate feature flags, bucket users consistently, and track conversion events on the server. Includes optional Express and Fastify middleware, real-time datafile streaming over SSE, pluggable sticky bucketing (in-memory and Redis), and decision logs for debugging.
+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.
 
-## Install
+---
+
+## 1. Install
 
 ```bash
 npm install @avsbhq/node
 ```
 
-## Authentication
-
-You'll need a server SDK key from your A vs B project's environments page.
+Requires Node.js 18 or later.
 
-1. Log in to the [A vs B platform](https://app.avsb.cloud)
-2. Open your project, go to **Environments**
-3. Copy the **server** SDK key for the environment you want to use
+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.
 
-Server SDK keys grant full flag-read access. Store them in environment variables, never check them into source control.
+---
 
-## Quick start
+## 2. Quickstart
 
 ```ts
-import { AvsBServer } from '@avsbhq/node'
+import { AvsbServer } from '@avsbhq/node'
 
-const server = new AvsBServer({
+const server = new AvsbServer({
   sdkKey: process.env.AVSB_SDK_KEY!,
 })
 
-await server.onReady()
+const result = await server.onReady()
+if (!result.success) {
+  process.exit(1)  // or degrade gracefully: result.degraded === true means defaults are safe
+}
 
-const showNewCheckout = server.evaluateFlag('new-checkout-flow', {
-  userId: 'user_123',
-  attributes: { plan: 'pro', country: 'US' },
-})
+// Evaluate per-request via forUser()
+const user = server.forUser({ kind: 'user', key: 'u_123', plan: 'pro' })
 
-await server.track('checkout_completed', {
-  userId: 'user_123',
-  revenue: 49.99,
-})
+const flag = user.getBoolFlag('new-checkout-flow', false)
+if (flag.isEnabled()) {
+  renderNewCheckout()
+}
+
+user.track('checkout_started', { value: 99.0 })
 ```
 
-Initialize once at app boot. The server holds an in-memory datafile and refreshes it on a polling interval (or via SSE if streaming is enabled).
+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`).
 
-## API reference
+---
 
-### `new AvsBServer(options)`
+## 3. SDK keys
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `sdkKey` | `string` | — | **Required.** Server SDK key for the environment. |
-| `pollingInterval` | `number` | `60_000` | How often (ms) to refresh the datafile. Min `5_000`. |
-| `cdnHost` | `string` | `'https://cdn.avsb.cloud'` | CDN host for datafile fetches. |
-| `initTimeout` | `number` | `10_000` | Max ms to wait for initial datafile fetch. |
-| `bootstrap` | `FlagDatafile` | — | Pre-fetched datafile to skip the initial network request. |
-| `streaming` | `boolean` | `false` | Enable SSE streaming for real-time datafile updates. |
-| `streamingEndpoint` | `string` | derived | Custom SSE endpoint URL. |
-| `events` | `EventOptions` | defaults | Event tracking config (`flushInterval`, `batchSize`, `maxQueueSize`, `retryAttempts`). |
-| `stickyBucketService` | `StickyBucketService` | none | Pluggable sticky bucketing backend. |
-| `logger` | `Logger` | `noopLogger` | Custom logger (`debug` / `info` / `warn` / `error`). |
+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`).
 
-### `server.onReady(): Promise<InitResult>`
+```bash
+AVSB_SDK_KEY=sdk_production_...
+```
+
+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.
+
+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).
+
+---
 
-Resolves when the SDK has loaded its datafile.
+## 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.
+
+### `forUser(context)` / `createUserContext(context)`
+
+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.
 
 ```ts
-const result = await server.onReady()
-if (!result.success) {
-  console.error('SDK failed to initialize:', result.error)
-}
+const user = server.forUser({
+  kind: 'user',
+  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' } })
 ```
 
-`InitResult.source` is one of `'network'`, `'bootstrap'`, `'cache'`, `'timeout'`, `'error'`.
+`createUserContext` is an ergonomic alias for `forUser`.
 
-### `server.evaluateFlag(key, userContext): unknown`
+### Per-call context
 
-Evaluate a flag for a specific user. The user context must include a `userId`.
+Pass `context` in the options object when not using `forUser()`:
 
 ```ts
-const value = server.evaluateFlag('new-checkout-flow', {
-  userId: 'user_123',
-  attributes: { plan: 'pro' },
+const flag = server.getBoolFlag('checkout-v2', false, {
+  context: { kind: 'user', key: 'u_123', plan: 'pro' },
 })
 ```
 
-`UserContext` fields:
-| Field | Type | Description |
-|---|---|---|
-| `userId` | `string` | **Required.** Bucketing identifier. |
-| `attributes` | `Record<string, unknown>` | Targeting attributes. |
-| `suppressExposure` | `boolean` | When `true`, don't fire an exposure event. |
-| `decisionLog` | `DecisionLog` | Collect detailed evaluation reasons into a log. |
-| `privateAttributes` | `string[]` | Attribute keys to strip from event payloads. |
+### `alias(previousContext, newContext)`
+
+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:
+
+```ts
+await server.alias(
+  { kind: 'user', key: anonymousId },
+  { kind: 'user', key: user.id }
+)
+```
+
+---
 
-### `server.track(eventKey, trackContext): Promise<void>`
+## 5. Multi-context
 
-Send a conversion event.
+Pass a multi-context to evaluate flags against multiple context kinds simultaneously:
 
 ```ts
-await server.track('purchase_completed', {
-  userId: 'user_123',
-  revenue: 99.99,
-  properties: { plan: 'annual' },
+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 },
 })
+
+const flag = user.getBoolFlag('enterprise-dashboard', false)
+// The rule may target organization.tier and bucket on user.key simultaneously
 ```
 
-### `SDK_VERSION`
+---
 
-The version of this SDK. Useful for telemetry and bug reports.
+## 6. Reading flags
+
+### Typed variants (recommended)
 
 ```ts
-import { SDK_VERSION } from '@avsbhq/node'
-console.log(SDK_VERSION)
+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 })
 ```
 
-## Framework integrations
+Each typed variant performs a runtime type check against the datafile's declared flag type. A mismatch logs a warning and returns the default.
 
-### Express
+### Generic `getFlag<T>`
 
 ```ts
-import express from 'express'
-import { AvsBServer, expressMiddleware } from '@avsbhq/node'
+const flag = server.getFlag<boolean>('checkout-v2', false, {
+  context: { kind: 'user', key: 'u_123' },
+})
+```
 
-const server = new AvsBServer({ sdkKey: process.env.AVSB_SDK_KEY! })
-await server.onReady()
+### The `Flag<T>` object
 
-const app = express()
-app.use(expressMiddleware(server, {
-  userIdFrom: (req) => req.user?.id,
-  attributesFrom: (req) => ({ plan: req.user?.plan }),
-}))
+```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
+```
 
-app.get('/checkout', (req, res) => {
-  const showNew = req.avsb.getFlag('new-checkout-flow', false)
-  res.render(showNew ? 'checkout-v2' : 'checkout-v1')
-})
+### `getAllFlags(context, options?)`
+
+```ts
+const all = server.getAllFlags({ kind: 'user', key: 'u_123' })
+// Exposures are suppressed by default. Pass { fireExposures: true } to enable.
 ```
 
-The middleware decorates each request with `req.avsb`, which exposes per-request `getFlag`, `getFlagDetails`, `getAllFlags`, and `track` methods scoped to the current user.
+### Forced decisions (QA / testing)
 
-### Fastify
+```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
+
+// Global override (all contexts)
+server.setGlobalOverride('checkout-v2', 'on')
+
+// Clear
+server.clearOverrideForUser('checkout-v2', 'u_qa')
+server.clearGlobalOverride('checkout-v2')
+server.clearAllOverrides()
+```
+
+Per-request forced decisions (bound to a `UserBoundClient`):
 
 ```ts
-import Fastify from 'fastify'
-import { AvsBServer, fastifyPlugin } from '@avsbhq/node'
+const user = server.forUser(ctx)
+user.setForcedDecision('checkout-v2', { variationKey: 'on' })
+user.clearForcedDecision('checkout-v2')
+```
 
-const server = new AvsBServer({ sdkKey: process.env.AVSB_SDK_KEY! })
-await server.onReady()
+---
 
-const app = Fastify()
-await app.register(fastifyPlugin, {
-  server,
-  userIdFrom: (req) => req.headers['x-user-id'] as string,
+## 7. Tracking events
+
+```ts
+user.track('purchase_completed', {
+  value: 199.0,
+  properties: { plan: 'annual', sku: 'PRO_ANNUAL' },
 })
 ```
 
-## Sticky bucketing
+When called directly on `server` (not via `forUser`), include `context`:
 
-Sticky bucketing keeps a user in the same variation across evaluations, even if rules or rollout percentages change.
+```ts
+server.track('purchase_completed', {
+  value: 199.0,
+  context: { kind: 'user', key: 'u_123' },
+  properties: { plan: 'annual' },
+})
+```
 
-### In-memory (single process)
+Events are synchronous calls that queue the event for batch flushing. There is no `await` on `track`.
+
+---
+
+## 8. Error handling
+
+### `logger` option
 
 ```ts
-import { AvsBServer, InMemoryStickyBucketService } from '@avsbhq/node'
+import { AvsbServer, createLogger } from '@avsbhq/node'
+import pino from 'pino'
+import { createPinoTransport } from '@avsbhq/utils/log/pino'
 
-const server = new AvsBServer({
+const server = new AvsbServer({
   sdkKey: process.env.AVSB_SDK_KEY!,
-  stickyBucketService: new InMemoryStickyBucketService(),
+  logger: createLogger({
+    level: 'info',
+    transports: [createPinoTransport({ logger: pino(), level: 'info' })],
+  }),
 })
 ```
 
-### Redis (multi-process / multi-region)
+### `onReady()` error handling
 
 ```ts
-import { createClient } from 'redis'
-import { AvsBServer, RedisStickyBucketService } from '@avsbhq/node'
+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
+}
+```
 
-const redis = createClient({ url: process.env.REDIS_URL })
-await redis.connect()
+`onReady()` never rejects — it always resolves. Check `result.success` to decide whether to proceed.
 
-const server = new AvsBServer({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  stickyBucketService: new RedisStickyBucketService({ redis, keyPrefix: 'avsb' }),
+### Event bus
+
+```ts
+const unsubscribe = server.on('error', (err) => {
+  myLogger.error('SDK error', { error: err.message })
+})
+
+server.on('configUpdate', ({ publishedAt, reason }) => {
+  myLogger.info('datafile refreshed', { publishedAt, reason })
 })
 ```
 
-`RedisStickyBucketService` accepts any Redis client matching the `RedisLike` interface (just needs `get` and `set`).
+---
 
-## Real-time updates
+## 9. SSR / hydration
 
-Enable SSE streaming to receive datafile updates the instant a flag changes on the platform — no polling delay.
+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.
+
+For server-side rendering outside of Next.js, fetch the datafile via `bootstrap` to avoid an extra round-trip:
 
 ```ts
-const server = new AvsBServer({
+const server = new AvsbServer({
   sdkKey: process.env.AVSB_SDK_KEY!,
-  streaming: true,
+  bootstrap: cachedDatafile,  // pre-fetched FlagDatafile object
+})
+// onReady() resolves immediately with source: 'bootstrap'
+```
+
+---
+
+## 10. Graceful shutdown
+
+### SIGTERM handler
+
+```ts
+process.on('SIGTERM', async () => {
+  await server.close()  // abort in-flight fetches, drain events
+  process.exit(0)
 })
 ```
 
-Or use the streaming client directly:
+`close()` calls `server.flush()` internally, then aborts any open streaming connections and stops polling.
+
+### Manual flush
 
 ```ts
-import { createStreamingClient } from '@avsbhq/node'
+await server.flush()  // drain queued events without teardown
+```
 
-const stream = createStreamingClient({
-  sdkKey: process.env.AVSB_SDK_KEY!,
-  onUpdate: (datafile) => { /* refresh in-memory datafile */ },
+---
+
+## 11. Testing
+
+```ts
+import { createMockClient, TestData } from '@avsbhq/test'
+
+const td = TestData.flag('checkout-v2')
+  .booleanFlag()
+  .variationForUser('u_test', true)
+  .fallthroughVariation(false)
+
+const mock = createMockClient({ flags: [td.build()] })
+// mock has the same interface as AvsbServer; inject it in tests
+```
+
+For assertion helpers:
+
+```ts
+import { recordEvaluations } from '@avsbhq/test'
+
+const recorder = recordEvaluations(mock)
+callCodeUnderTest(mock)
+expect(recorder).toHaveEvaluated('checkout-v2')
+  .withContext({ kind: 'user', key: 'u_test' })
+  .withValue(true)
+```
+
+---
+
+## 12. Framework integrations
+
+### Express
+
+```ts
+import express from 'express'
+import { AvsbServer, expressMiddleware } from '@avsbhq/node'
+
+const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! })
+await avsb.onReady()
+
+const app = express()
+app.use(expressMiddleware(avsb, {
+  contextFrom: (req) => ({
+    kind: 'user',
+    key: req.user?.id ?? 'anon',
+    plan: req.user?.plan,
+  }),
+}))
+
+app.get('/checkout', (req, res) => {
+  const flag = req.avsb.getBoolFlag('new-checkout-flow', false)
+  res.render(flag.isEnabled() ? 'checkout-v2' : 'checkout-v1')
 })
 ```
 
-## Decision logs
+`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.
 
-Capture full evaluation reasons for debugging or audit trails.
+### Fastify
 
 ```ts
-import { createDecisionLog } from '@avsbhq/node'
+import Fastify from 'fastify'
+import { AvsbServer, fastifyPlugin } from '@avsbhq/node'
 
-const log = createDecisionLog()
-const value = server.evaluateFlag('new-checkout-flow', {
-  userId: 'user_123',
-  decisionLog: log,
+const avsb = new AvsbServer({ sdkKey: process.env.AVSB_SDK_KEY! })
+await avsb.onReady()
+
+const app = Fastify()
+await app.register(fastifyPlugin, {
+  server: avsb,
+  contextFrom: (req) => ({
+    kind: 'user',
+    key: req.headers['x-user-id'] as string,
+  }),
 })
 
-console.log(log.entries)
-// [{ flagKey, value, variationKey, source, ruleId, ruleType, reasons, evaluatedAt, durationMs }]
+app.get('/features', (req, reply) => {
+  const flag = req.avsb.getBoolFlag('new-feature', false)
+  reply.send({ enabled: flag.isEnabled() })
+})
 ```
 
-## Common patterns
+### Sticky bucketing
 
-### Bootstrap once, evaluate per-request
+Keep users in the same variation across rule changes. In-memory is suitable for single-process deployments:
 
 ```ts
-// startup.ts
-import { AvsBServer } from '@avsbhq/node'
+import { InMemoryStickyBucketService } from '@avsbhq/node'
 
-export const avsb = new AvsBServer({ sdkKey: process.env.AVSB_SDK_KEY! })
-await avsb.onReady()
+const server = new AvsbServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  stickyBucketService: new InMemoryStickyBucketService(),
+})
 ```
 
+Redis for multi-process and multi-region deployments:
+
 ```ts
-// route handler
-import { avsb } from './startup'
+import { createClient } from 'redis'
+import { RedisStickyBucketService } from '@avsbhq/node'
 
-const value = avsb.evaluateFlag('flag-key', { userId: req.user.id })
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+
+const server = new AvsbServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  stickyBucketService: new RedisStickyBucketService({
+    redis,
+    prefix: 'avsb:sticky:',
+  }),
+})
 ```
 
-### Suppress exposure for backend-only checks
+DynamoDB and PostgreSQL adapters are available in `@avsbhq/utils`.
+
+### Real-time streaming
+
+Enable SSE streaming to receive datafile updates the instant a flag changes — no polling delay:
 
 ```ts
-const value = server.evaluateFlag('feature-flag', {
-  userId: 'user_123',
-  suppressExposure: true,
+const server = new AvsbServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  streaming: true,
 })
 ```
 
-## Requirements
+### Decision logs
+
+Capture full evaluation reasons per request for debugging or audit:
 
-- Node.js >= 18
-- No required peer dependencies. Express and Fastify are optional — only needed if you use the corresponding middleware.
+```ts
+import { createDecisionLog } from '@avsbhq/node'
 
-## Links
+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 }]
+```
 
-- [Platform docs](https://app.avsb.cloud/docs)
-- [Client SDK (`@avsbhq/js`)](https://www.npmjs.com/package/@avsbhq/js)
-- [React SDK (`@avsbhq/react`)](https://www.npmjs.com/package/@avsbhq/react)
-- [CLI (`@avsbhq/cli`)](https://www.npmjs.com/package/@avsbhq/cli)
+---
+
+## 13. Migration
+
+### From LaunchDarkly Node
+
+| 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 — no `ldUser` adapter needed.
+
+### 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, properties: metadata })` |
+| `Statsig.flush()` | `await server.flush()` |