@avsbhq/node 0.1.0

package/README.md

@@ -0,0 +1,268 @@
+# @avsbhq/node
+
+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.
+
+## Install
+
+```bash
+npm install @avsbhq/node
+```
+
+## Authentication
+
+You'll need a server SDK key from your A vs B project's environments page.
+
+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
+
+Server SDK keys grant full flag-read access. Store them in environment variables, never check them into source control.
+
+## Quick start
+
+```ts
+import { AvsBServer } from '@avsbhq/node'
+
+const server = new AvsBServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+})
+
+await server.onReady()
+
+const showNewCheckout = server.evaluateFlag('new-checkout-flow', {
+  userId: 'user_123',
+  attributes: { plan: 'pro', country: 'US' },
+})
+
+await server.track('checkout_completed', {
+  userId: 'user_123',
+  revenue: 49.99,
+})
+```
+
+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).
+
+## API reference
+
+### `new AvsBServer(options)`
+
+| 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.app'` | 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`). |
+
+### `server.onReady(): Promise<InitResult>`
+
+Resolves when the SDK has loaded its datafile.
+
+```ts
+const result = await server.onReady()
+if (!result.success) {
+  console.error('SDK failed to initialize:', result.error)
+}
+```
+
+`InitResult.source` is one of `'network'`, `'bootstrap'`, `'cache'`, `'timeout'`, `'error'`.
+
+### `server.evaluateFlag(key, userContext): unknown`
+
+Evaluate a flag for a specific user. The user context must include a `userId`.
+
+```ts
+const value = server.evaluateFlag('new-checkout-flow', {
+  userId: 'user_123',
+  attributes: { 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. |
+
+### `server.track(eventKey, trackContext): Promise<void>`
+
+Send a conversion event.
+
+```ts
+await server.track('purchase_completed', {
+  userId: 'user_123',
+  revenue: 99.99,
+  properties: { plan: 'annual' },
+})
+```
+
+### `SDK_VERSION`
+
+The version of this SDK. Useful for telemetry and bug reports.
+
+```ts
+import { SDK_VERSION } from '@avsbhq/node'
+console.log(SDK_VERSION)
+```
+
+## Framework integrations
+
+### Express
+
+```ts
+import express from 'express'
+import { AvsBServer, expressMiddleware } from '@avsbhq/node'
+
+const server = new AvsBServer({ sdkKey: process.env.AVSB_SDK_KEY! })
+await server.onReady()
+
+const app = express()
+app.use(expressMiddleware(server, {
+  userIdFrom: (req) => req.user?.id,
+  attributesFrom: (req) => ({ plan: req.user?.plan }),
+}))
+
+app.get('/checkout', (req, res) => {
+  const showNew = req.avsb.getFlag('new-checkout-flow', false)
+  res.render(showNew ? 'checkout-v2' : 'checkout-v1')
+})
+```
+
+The middleware decorates each request with `req.avsb`, which exposes per-request `getFlag`, `getFlagDetails`, `getAllFlags`, and `track` methods scoped to the current user.
+
+### Fastify
+
+```ts
+import Fastify from 'fastify'
+import { AvsBServer, fastifyPlugin } from '@avsbhq/node'
+
+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,
+})
+```
+
+## Sticky bucketing
+
+Sticky bucketing keeps a user in the same variation across evaluations, even if rules or rollout percentages change.
+
+### In-memory (single process)
+
+```ts
+import { AvsBServer, InMemoryStickyBucketService } from '@avsbhq/node'
+
+const server = new AvsBServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  stickyBucketService: new InMemoryStickyBucketService(),
+})
+```
+
+### Redis (multi-process / multi-region)
+
+```ts
+import { createClient } from 'redis'
+import { AvsBServer, RedisStickyBucketService } from '@avsbhq/node'
+
+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, keyPrefix: 'avsb' }),
+})
+```
+
+`RedisStickyBucketService` accepts any Redis client matching the `RedisLike` interface (just needs `get` and `set`).
+
+## Real-time updates
+
+Enable SSE streaming to receive datafile updates the instant a flag changes on the platform — no polling delay.
+
+```ts
+const server = new AvsBServer({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  streaming: true,
+})
+```
+
+Or use the streaming client directly:
+
+```ts
+import { createStreamingClient } from '@avsbhq/node'
+
+const stream = createStreamingClient({
+  sdkKey: process.env.AVSB_SDK_KEY!,
+  onUpdate: (datafile) => { /* refresh in-memory datafile */ },
+})
+```
+
+## Decision logs
+
+Capture full evaluation reasons for debugging or audit trails.
+
+```ts
+import { createDecisionLog } from '@avsbhq/node'
+
+const log = createDecisionLog()
+const value = server.evaluateFlag('new-checkout-flow', {
+  userId: 'user_123',
+  decisionLog: log,
+})
+
+console.log(log.entries)
+// [{ flagKey, value, variationKey, source, ruleId, ruleType, reasons, evaluatedAt, durationMs }]
+```
+
+## Common patterns
+
+### Bootstrap once, evaluate per-request
+
+```ts
+// startup.ts
+import { AvsBServer } from '@avsbhq/node'
+
+export const avsb = new AvsBServer({ sdkKey: process.env.AVSB_SDK_KEY! })
+await avsb.onReady()
+```
+
+```ts
+// route handler
+import { avsb } from './startup'
+
+const value = avsb.evaluateFlag('flag-key', { userId: req.user.id })
+```
+
+### Suppress exposure for backend-only checks
+
+```ts
+const value = server.evaluateFlag('feature-flag', {
+  userId: 'user_123',
+  suppressExposure: true,
+})
+```
+
+## Requirements
+
+- Node.js >= 18
+- No required peer dependencies. Express and Fastify are optional — only needed if you use the corresponding middleware.
+
+## Links
+
+- [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)