flagmint-js-sdk 1.2.26 → 2.2.0

package/README.md

@@ -1,603 +1,347 @@
 # Flagmint JavaScript SDK
 
-**Version: v1.2.25**
+> A framework-agnostic JavaScript SDK for evaluating and streaming feature flags in browsers and Node.js.
 
-This SDK provides a javascript framework-agnostic client for evaluating feature flags, with pluggable caching (sync or async) and transport strategies (WebSocket or long-polling). It's designed for both browser and server-side Node.js environments.
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![Node](https://img.shields.io/badge/Node.js-18%2B-green)
+![License](https://img.shields.io/badge/license-BSD--3--Clause-lightgrey)
 
-## 📋 Release Notes
+## Features
 
-### v1.2.25
-- 🔇 **Controllable debug logging** — SDK logs are now silent by default; opt in with `logger.setup({ debugLog: true })`. In production, only connection/disconnection messages are ever emitted regardless of the setting.
-- 🔌 **Configurable endpoints** — `restEndpoint` and `wsEndpoint` can now be passed directly in `FlagClientOptions`, overriding the environment-derived defaults. Useful for proxies, staging overrides, or self-hosted deployments.
-- 📡 **`subscribe()` delivers current flags immediately** — the callback is now called synchronously with the current flag state at subscription time, so you never miss the initial value.
-- 🧹 **`destroy()` clears all subscribers** — calling `destroy()` now also clears the subscriber set, preventing stale callbacks from holding references after teardown.
-- 🛡️ **WebSocket auth vs rate-limit error discrimination** — close code `1008`/`4001` now inspects the close reason to distinguish `ERR_AUTH` (invalid API key) from `ERR_RATE_LIMITED` errors. Rate-limit errors include a `resetTime` field parsed from the close reason.
-- 🔗 **`initialFlagsReject` on WebSocket transport** — a post-`onopen` close with a terminal code now correctly rejects the `waitForInitialFlags()` promise (and therefore `init()`), so the error surfaces reliably through `client.ready()` even when the connection opened before the server sent the close frame.
-- 🔔 **`onConnectionStateChanged()` exposed** — consumers can now register a callback to observe WebSocket connection state transitions (`connecting`, `connected`, `disconnected`, `reconnecting`, `failed`).
+- Framework agnostic (React, Vue, Angular, vanilla JS, Node.js)
+- Real-time flag updates over Server-Sent Events (SSE)
+- Automatic reconnection with a fresh single-use session token
+- Same-origin iframe/tab connection sharing (one stream per API key)
+- Built-in localStorage cache, with pluggable adapters for Node
+- `getFlag()` is always local — no network on the read path
 
-### v1.2.24
-- ✨ Add `env` parameter to SDK configuration for explicit environment specification
-- Allows users to pass environment as a variable when NODE_ENV or NEXT_PUBLIC_NODE_ENV cannot be reliably detected
-- Improved environment resolution with fallback to auto-detection
+## Release notes
 
-## ✨ Key Features
+### v2.0.0
 
-- 🎯 **Framework-Agnostic**: Works with React, Vue, vanilla JS, Node.js, and more
-- 🔄 **Flexible Transport**: WebSocket for real-time updates or long-polling fallback
-- 💾 **Pluggable Caching**: Use built-in sync cache, async cache (Redis/filesystem), or custom implementations
-- 🚀 **Server & Browser Support**: Compatible with browser environments, Node.js, React Native
-- 🔒 **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- ⚡ **Zero-Config Defaults**: Works out of the box with sensible defaults
+- **SSE instead of WebSockets.** Handshake at `POST /auth/asl-handshake`, stream at `GET /evaluator/v2/flags/stream`, context at `POST /evaluator/v2/flags/context`.
+- **Context updates match the API.** The SDK sends `x-api-key`, treats `202` as queued, and waits for the next `flags` event on the open stream (400ms server debounce). Browser and Node use the same path.
+- **Quota and stream errors.** Listens for `quota_exceeded` and named `error` events. Quota surfaces as `ERR_RATE_LIMITED` (`retryAfter`, `resetTime`) through `onError`. Cached flags keep serving.
+- **Connection sharing.** Same-origin documents (tabs, sibling iframes) with the same API key elect one leader that holds EventSource. Followers skip handshake and the stream. Off in Node so cluster workers each keep their own connection.
+- **Node `EventSourceImpl`.** Node has no native EventSource; pass one (for example `eventsource`).
+- **Session refresh on reconnect.** The stream consumes a single-use `sessionId`; reconnect fetches a new one before opening EventSource again.
+- **`ready()` never throws.** Failures go to `onError`. Cached flags, if any, are used in degraded mode.
 
-## 📦 Installation
+### v1.2.25 / v1.2.24
+
+Historical WebSocket-era releases. See git tags for the full notes. v2.0.0 replaces that transport.
+
+---
+
+# Installation
 
 ```bash
 npm install flagmint-js-sdk
-# or
+```
+
+```bash
 yarn add flagmint-js-sdk
 ```
 
-## Quick Start
+---
+
+# Quick start
+
+## Browser
 
 ```ts
 import { FlagClient } from 'flagmint-js-sdk';
 
-// Create a client instance
 const client = new FlagClient({
-  apiKey: 'ff_your_api_key_here',
+  apiKey: 'ff_your_api_key',
+  enableFlagmint: true,
   context: {
-    kind: "multi | user | organisation",
-    user: { kind: "user", key: '', email: '' },
-    organization: { kind: "organization", key: '', plan: '' }
+    kind: 'user',
+    user: {
+      kind: 'user',
+      key: 'user-123'
+    }
+  },
+  onError: (error) => {
+    console.error(error.message, (error as { code?: string }).code);
   }
 });
 
-// Wait for initial connection and flag synchronization
 await client.ready();
 
-// Get flag values
-const showBanner = client.getFlag('show_banner', false);
-const featureVersion = client.getFlag('feature_version', 'v1');
-
-// Update context and re-evaluate
-await client.updateContext({
-  kind: "user",
-  user: { kind: "user", key: 'user456', email: 'user456@example.com' }
-});
+const enabled = client.getFlag('new_dashboard', false);
 ```
 
-## FlagClientOptions
-
-| Option                | Type                                      | Default            | Description                                                           |
-| --------------------- | ----------------------------------------- | ------------------ | --------------------------------------------------------------------- |
-| `apiKey`              | `string`                                  | **Required**       | Your environment API key.                                             |
-| `context`             | `Record<string, any>`                     | `{}`               | Initial evaluation context (e.g. user attributes).                    |
-| `enableOfflineCache`  | `boolean`                                 | `true`              | Enable caching of flags locally.                                      |
-| `persistContext`      | `boolean`                                 | `false`            | Persist evaluation context across sessions.                           |
-| `cacheAdapter`        | `CacheAdapter<C>`                         | Sync `cacheHelper` | Custom cache implementation (see examples).                           |
-| `transportMode`       | `'auto' \| 'websocket' \| 'long-polling'` | `'auto'`           | How to fetch flags: prefer WebSocket, or use long-polling transport.  |
-| `restEndpoint`        | `string`                                  | env-derived        | Override the REST endpoint (useful for proxies or self-hosted setups).|
-| `wsEndpoint`          | `string`                                  | env-derived        | Override the WebSocket endpoint.                                      |
-| `onError`             | `(error: Error) => void`                  | —                  | Callback for transport or initialization errors. Called when operating in degraded mode with cached flags. |
-| `previewMode`         | `boolean`                                 | `false`            | Evaluate using `rawFlags` only, bypassing remote fetch.               |
-| `rawFlags`            | `Record<string, FlagValue>`               | —                  | Local-only flag definitions used when `previewMode: true`.            |
-| `deferInitialization` | `boolean`                                 | `false`            | If `true`, client initialization is deferred until you call `ready()`. |
-
-## 🪵 Debug Logging
-
-By default the SDK is **silent** — no console output in any environment. To enable verbose logging during development, call `logger.setup()` before creating your client:
-
-```ts
-import { logger } from 'flagmint-js-sdk';
-
-logger.setup({ debugLog: true });
-
-const client = new FlagClient({ apiKey: '...' });
-```
+Same-origin iframes that use this API key share one SSE connection by default **in browsers that provide `BroadcastChannel`**. Without it (older browsers, Node), each client opens its own stream. Set `shareConnection: false` if two clients on the page must keep different evaluation contexts at the same time, or if the origin hosts untrusted documents that should not share that stream.
 
-In **production** (`NODE_ENV=production`), only connection and disconnection messages are emitted regardless of the `debugLog` setting — all other internal logs are suppressed.
+## Node.js
 
-```ts
-// These messages always appear in production:
-// "[WebSocketTransport] Connected"
-// "[WebSocketTransport] Connection closed: 1000"
+Node does not provide `EventSource`. Install a polyfill and inject it. Each cluster worker should construct its own `FlagClient` (sharing is disabled without `window`).
 
-// All other internal logs require debugLog: true in non-production environments
+```bash
+npm install eventsource
 ```
 
-## 🔧 Cache Adapters
-
-### Sync (Browser / In-Memory)
-
-By default, the SDK uses a **sync** `localStorage`-based helper in browsers or a `Map` in Node.js:
-
 ```ts
-import { FlagClient, syncCache } from 'flagmint-js-sdk';
-// No setup needed for browser; for Node you can override:
-syncCache.setCacheStorage({
-  getItem:   key => myMap.get(key) ?? null,
-  setItem:   (key, val) => myMap.set(key, val),
-});
-```
-
-### Async (Redis / File System)
-
-Use the **async** helper for server-side or React Native:
+import { FlagClient } from 'flagmint-js-sdk';
+import EventSource from 'eventsource';
 
-```ts
-import { FlagClient, asyncCache } from 'flagmint-js-sdk';
+const apiKey = process.env.FLAGMINT_API_KEY;
+if (!apiKey) {
+  throw new Error('FLAGMINT_API_KEY is required');
+}
 
 const client = new FlagClient({
-  apiKey: '...',
-  cacheAdapter: {
-    loadFlags:   asyncCache.loadCachedFlags,
-    saveFlags:   asyncCache.saveCachedFlags,
-    loadContext: asyncCache.loadCachedContext,
-    saveContext: asyncCache.saveCachedContext
+  apiKey,
+  enableFlagmint: true,
+  EventSourceImpl: EventSource,
+  env: process.env.FLAGMINT_ENVIRONMENT || 'production',
+  onError: (error) => {
+    console.error('Flagmint error:', error);
   }
 });
-```
 
-## 🌐 Transport Modes
-
-* **`'websocket'`**: Persistent WebSocket connection for live updates.
-* **`'long-polling'`**: HTTP requests held open by server until flags change.
-* **`'auto'`** (default): Try WebSocket, fallback to long-polling.
-
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  transportMode: 'long-polling'
-});
-```
-
-### Custom Endpoints
-
-Override the default environment-derived endpoints — useful for proxies, staging overrides, or self-hosted deployments:
-
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  restEndpoint: 'https://my-proxy.example.com/evaluator/evaluate',
-  wsEndpoint:   'wss://my-proxy.example.com/ws/sdk',
-});
+await client.ready();
 ```
 
-### WebSocket Connection State
-
-Monitor connection state transitions by accessing the underlying WebSocket transport directly:
-
-```ts
-import { WebSocketTransport } from 'flagmint-js-sdk';
-
-const ws = new WebSocketTransport(wsUrl, apiKey);
-ws.onConnectionStateChanged((state) => {
-  // state: 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed'
-  console.log('WS state:', state);
-});
-```
+---
 
-### Transport Performance
+# How it works
 
-| Mode | Latency | Bandwidth | Best For |
-|------|---------|-----------|----------|
-| WebSocket | Lowest (real-time) | Efficient | Real-time dashboards, live updates |
-| Long-Polling | Medium | Higher | Simpler setup, less overhead on server |
-| Auto | Lowest to Medium | Varies | Most applications (recommended) |
+After `ready()`:
 
-## ⚙️ Evaluation Helpers
+1. Optionally joins a same-origin share group (browser). Followers stop here and receive flags from the leader.
+2. `POST /auth/asl-handshake` with `X-API-Key` → single-use `sessionId`.
+3. Opens `GET /evaluator/v2/flags/stream?sessionId&context&sdkVersion&platform&wrapper*`. The server contract requires `sessionId` and a base64 `context` in the query string. Treat those query parameters as sensitive: do not put secrets or PII in `context`, and redact `sessionId` and `context` from access logs, reverse-proxy logs, and telemetry.
+4. Server sends `connected` (connection id) then `flags` (evaluated map). Heartbeats are SSE comments (`: heartbeat`) and are not exposed by EventSource.
+5. Flags are stored in the cache adapter (localStorage in the browser by default).
+6. Later admin publishes are pushed as `flags` events on the same stream.
 
-The SDK includes utilities to evaluate flag targeting rules and rollouts:
+`getFlag()` / `getFlags()` never hit the network. They read the last evaluated snapshot.
 
-### `evaluateFlagValue(flag, context)`
+`updateContext()` `POST`s `/evaluator/v2/flags/context` with `x-api-key` and `{ connectionId, context }`. The HTTP response is `202`; new values arrive as a `flags` event after the server’s 400ms debounce.
 
-```ts
-import { evaluateFlagValue } from 'flagmint-js-sdk';
+---
 
-const result = evaluateFlagValue(flagValue, userContext);
-```
+# Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | string | required | Environment API key |
+| `enableFlagmint` | boolean | `true` | Set `false` in local/dev to skip connecting (no handshake, no stream) |
+| `context` | object | `{}` | Initial evaluation context. Do not put secrets or PII here — the stream URL serializes this object in the query string |
+| `transportMode` | `'auto' \| 'sse' \| 'long-polling'` | `'auto'` | `auto` tries SSE, then long-polling |
+| `EventSourceImpl` | EventSource | browser global | Required in Node |
+| `shareConnection` | boolean | `true` in browsers with `BroadcastChannel`, `false` in Node | One stream per API key across same-origin documents |
+| `enableOfflineCache` | boolean | `true` | Load/save flags via the cache adapter |
+| `persistContext` | boolean | `false` | Persist context in the cache adapter |
+| `cacheAdapter` | CacheAdapter | localStorage helpers | Custom cache (Redis, files, …) |
+| `restEndpoint` | string | env default | Override the long-polling / evaluate URL |
+| `sseEndpoint` | string | env default | Override the SSE stream base URL (`/stream` only). Defaults to `stream.flagmint.com` / `staging-stream…` |
+| `flagsEndpoint` | string | from `restEndpoint` | Override the API base for `POST /context`. Needed when stream and API hosts differ |
+| `handshakeEndpoint` | string | env default | Override the ASL handshake URL. Use with `restEndpoint` / `sseEndpoint` for self-hosted gateways |
+| `restEndpoint` | string | env default | Override REST evaluate URL (also drives events + default context host) |
+| `env` | string | `NODE_ENV` | `development` \| `staging` \| `production` |
+| `wrapperInfo` | `{ name, version }` | native-js | Framework wrapper telemetry on the stream URL |
+| `previewMode` / `rawFlags` | | | Local-only evaluation, no network |
+| `deferInitialization` | boolean | `false` | Wait for `ready()` before connecting |
+| `debugLog` | boolean | `false` | Verbose SDK logs |
+| `onError` | `(error) => void` | | Auth, quota, transport, and context errors. `ready()` still resolves. |
 
-* Applies targeting rules (`segment` or attribute rules).
-* If matched, applies rollout (percentage or variant).
-* Returns flag’s value or `null` if not enabled.
+---
 
-### `evaluateRollout(rollout, context)`
+# Transport modes
 
 ```ts
-import { evaluateRollout } from 'flagmint-js-sdk';
-
-const rolloutValue = evaluateRollout(rolloutConfig, userContext);
+transportMode: 'auto'           // SSE, then long-polling if SSE init fails
+transportMode: 'sse'            // stream only — reports failures through onError; uses cached flags if any (no long-polling fallback)
+transportMode: 'long-polling'   // POST evaluate on an interval
 ```
 
-* Supports **percentage** rollouts using consistent hashing.
-* Supports **variant** distributions (A/B tests).
-
-### `rolloutUtils`
+---
 
-* `hashToPercentage(value: string): number`
-* `pickVariant(value: string, variants: VariantOption[]): string | number | boolean | null`
+# Connection sharing
 
-These helpers underpin reliable, deterministic assignment of users to flag variants.
+Used when the same app is embedded twice on one origin (for example two WeSeeDo iframes in a host page).
 
-### `isInSegment(segment, context)`
+- **Leader** performs handshake and holds EventSource.
+- **Followers** receive flag snapshots over `BroadcastChannel` (`flagmint-share:<apiKey>`). Leadership is a `localStorage` lock (`flagmint_share_lock:<apiKey>`).
+- Follower `updateContext()` is forwarded to the leader, which runs it on the shared stream. Last write wins. Any same-origin document can send that RPC and see the flags that come back — turn sharing off if you host untrusted content on this origin.
+- If the leader iframe unloads, it posts `bye` so another member can take over immediately. If the tab is killed without `pagehide`, followers wait for the lock TTL.
 
 ```ts
-import { isInSegment } from 'flagmint-js-sdk';
+// Default in browsers with BroadcastChannel — one stream for this API key
+shareConnection: true
 
-const inBetaSegment = isInSegment(betaSegment, userContext);
+// Two clients, two contexts, two streams — or no BroadcastChannel
+shareConnection: false
 ```
 
-Evaluates whether a user context matches a segment's criteria.
+Node cluster workers do not share. Each worker process opens its own stream.
 
-## 📖 Framework Integration Examples
-
-### React
-
-```tsx
-import { useEffect, useState } from 'react';
-import { FlagClient } from 'flagmint-js-sdk';
-
-const client = new FlagClient({
-  apiKey: 'ff_...',
-  context: {
-    kind: "multi | user | organisation",
-    user: { kind: "user", key: '', email: '' },
-    organization: { kind: "organization", key: '', plan: '' }
-  }
-});
-
-export function App() {
-  const [flags, setFlags] = useState({});
-
-  useEffect(() => {
-    client.ready().then(() => {
-      setFlags({
-        showBeta: client.getFlag('show_beta', false),
-        theme: client.getFlag('theme', 'light')
-      });
-    });
-
-    // Subscribe to flag updates
-    const unsubscribe = client.subscribe((updatedFlags) => {
-      setFlags({
-        showBeta: client.getFlag('show_beta', false),
-        theme: client.getFlag('theme', 'light')
-      });
-    });
-    
-    return () => unsubscribe();
-  }, []);
-
-  return (
-    <div className={`theme-${flags.theme}`}>
-      {flags.showBeta && <BetaFeature />}
-    </div>
-  );
-}
-```
+---
 
-### Node.js / Express
+# Updating context
 
 ```ts
-import { FlagClient, asyncCache } from 'flagmint-js-sdk';
-
-const client = new FlagClient({
-  apiKey: 'ff_...',
-  cacheAdapter: {
-    loadFlags: asyncCache.loadCachedFlags,
-    saveFlags: asyncCache.saveCachedFlags,
-    loadContext: asyncCache.loadCachedContext,
-    saveContext: asyncCache.saveCachedContext
-  }
-});
-
-// Wait for initialization
-await client.ready();
-
-app.get('/api/feature', async (req, res) => {
-  // Update context with proper structure
-  await client.updateContext({ 
-    kind: "multi",
-    user: {
-      kind: "user",
-      key: req.user.id,
-      email: req.user.email
-    },
-    organization: {
-      kind: "organization",
-      key: req.user.orgId,
-      plan: req.user.plan
-    }
-  });
-  
-  const isEnabled = client.getFlag('new_api', false);
-  
-  res.json({ enabled: isEnabled });
+await client.updateContext({
+  kind: 'multi',
+  user: { kind: 'user', key: '123' },
+  organization: { kind: 'organization', key: 'acme' }
 });
 ```
 
-## 🔄 Context Management
+Await this call. The promise settles when the stream delivers the next `flags` packet (or times out and keeps the previous snapshot). Overlapping calls are serialized.
 
-### Updating Context
+SSE `/context` changes **that connection’s** context. It is the right tool for a browser user logging in. It is the wrong tool for many concurrent Node HTTP requests with different targeting on one singleton client — wait for client-side rule evaluation, or use a dedicated client per distinct context.
 
-```ts
-// Initial context
-const client = new FlagClient({
-  apiKey: '...',
-  context: {
-    kind: "user",
-    user: { kind: "user", key: 'user123' }
-  }
-});
-
-// Update context later (e.g., after user upgrades)
-await client.updateContext({ 
-  kind: "multi",
-  user: {
-    kind: "user",
-    key: 'user123',
-    email: 'user@example.com'
-  },
-  organization: {
-    kind: "organization",
-    key: 'org456',
-    plan: 'premium',
-    country: 'CA'
-  }
-});
-```
+---
 
-### Persisting Context
+# Tracking application errors
 
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  persistContext: true, // Saves to localStorage/AsyncStorage
-  context: {
-    kind: "user",
-    user: { kind: "user", key: 'user123', email: 'user@example.com' }
-  }
-});
-```
+`getFlag()` tells you what was served and, when Analytics Tracking is on for that flag, queues a **debounced call-site evaluation** report (dashboard Evaluations). That report is not a billing meter.
 
-## 🔌 Deferred Initialization
+`trackError()` tells Flagmint whether that variation hurt the user. Errors are attributed to the **currently served value** of the flag, batched, and posted to `POST /evaluator/events`. The call never throws.
 
-For scenarios where you need to set up the client before context is available:
+Analytics must be enabled on the flag in the dashboard. The SDK skips `trackError` / `track` locally once the SSE `flags` packet includes `analytics` for that key. Older servers without the map still accept the POST and drop it at ingest.
 
 ```ts
-const client = new FlagClient({
-  apiKey: '...',
-  deferInitialization: true
-});
-
-// Later, when context is ready:
-await client.updateContext({
-  kind: "user",
-  user: { kind: "user", key: 'user123', email: 'user@example.com' }
-});
-await client.ready(); // Initializes and connects
-```
+const checkoutOn = client.getFlag('checkout_redesign', false);
 
-## 🌍 Advanced Usage
-
-### Error Handling
-
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  onError: (error) => {
-    console.error('Flag client error:', error);
-    // Report to monitoring service
-    sentry.captureException(error);
-  }
-});
+try {
+  await submitPayment();
+} catch (error) {
+  client.trackError('checkout_redesign', error, { step: 'payment' });
+  throw error;
+}
 ```
 
-**Important: Offline Fallback & Cache Behavior**
-
-The SDK gracefully handles connection failures using cached flags as a fallback:
+`track(flagKey, eventName)` uses the same pipe for custom metrics (conversions, etc.). Only `kind: 'error'` is counted in app error rate today.
 
-**When the server is unreachable:**
 
-| Scenario | `ready()` Promise | Behavior |
-|----------|-------------------|----------|
-| ✅ Cached flags available | Resolves | Operates in degraded mode with cached flags; `onError` is called |
-| ❌ No cached flags | Rejects | Initialization fails |
-| ✅ Connected successfully | Resolves | Normal operation with live updates |
-
-**Degraded Mode:** When `ready()` resolves but the connection failed, the `onError` callback is triggered to notify you:
-
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  enableOfflineCache: true,
-  onError: (error) => {
-    // Called when operating in degraded mode with cached flags
-    console.warn('⚠️ Degraded mode - using cached flags:', error.message);
-    // Optionally report to monitoring service
-  }
-});
 
+```tsx
+const enabled = useFlag('checkout_redesign', false);
+const { client } = useFlagmint();
 try {
-  await client.ready();
-  // ✅ Resolves successfully even if server is down (when cached flags exist)
-  console.log('Client ready');
-  const feature = client.getFlag('my_feature', false); // Always works
+  await submitPayment();
 } catch (error) {
-  // ❌ Only throws if NO cached flags AND server is unreachable
-  console.error('Completely offline:', error);
+  client?.trackError?.('checkout_redesign', error);
+  throw error;
 }
 ```
 
-### Preview Mode
+Full notes: `FF-EU/documentation/APPLICATION_ERROR_TRACKING.md`.
 
-For testing or preview environments where you want to bypass remote flag fetching:
+---
 
-```ts
-const client = new FlagClient({
-  apiKey: '...',
-  previewMode: true,
-  rawFlags: {
-    new_checkout: true,
-    discount_percent: 20,
-    ui_variant: 'experimental'
-  }
-});
+# Errors and quota
 
-// All getFlag calls will use rawFlags
-const checkout = client.getFlag('new_checkout', false); // true
-```
+`ready()` always resolves. Failures are reported through `onError`, never thrown from `ready()`. `transportMode: 'sse'` does not fall back to long-polling; it stays on the last cached snapshot (if any). `auto` tries SSE, then long-polling.
 
-### Custom Cache Implementations
+| `error.code` | Meaning |
+|---|---|
+| `ERR_AUTH` | Invalid API key, missing session, inactive subscription |
+| `ERR_RATE_LIMITED` | Evaluation quota exceeded. Check `retryAfter` (seconds) and `resetTime`. Free-tier payloads may include a last snapshot in `data`; the SDK applies it and keeps serving cache. |
+| `ERR_INVALID_CONTEXT` | Stream rejected the context payload |
+| `ERR_INTERNAL` | Named SSE `error` from the server |
 
 ```ts
-import { FlagClient } from 'flagmint-js-sdk';
-import redis from 'redis';
-
-const redisClient = redis.createClient();
-
-const client = new FlagClient({
-  apiKey: '...',
-  cacheAdapter: {
-    loadFlags: async (apiKey) => {
-      const cached = await redisClient.get(`flags:${apiKey}`);
-      return cached ? JSON.parse(cached) : null;
-    },
-    saveFlags: async (apiKey, flags) => {
-      await redisClient.setex(
-        `flags:${apiKey}`, 
-        600, // 10 min TTL
-        JSON.stringify(flags)
-      );
-    },
-    loadContext: async (apiKey) => {
-      const cached = await redisClient.get(`context:${apiKey}`);
-      return cached ? JSON.parse(cached) : null;
-    },
-    saveContext: async (apiKey, context) => {
-      await redisClient.setex(
-        `context:${apiKey}`, 
-        3600, // 1 hour TTL
-        JSON.stringify(context)
-      );
-    }
-  }
-});
+onError: (error) => {
+  const { code, retryAfter, resetTime, message } = error as {
+    code?: string;
+    retryAfter?: number;
+    resetTime?: string;
+    message: string;
+  };
+  console.error(code, message, retryAfter, resetTime);
+}
 ```
 
-## 📋 API Reference
-
-### `FlagClient`
-
-**Methods:**
-- `ready(timeoutMs?: number): Promise<void>` - Wait for initial connection (default timeout: 3000ms)
-- `getFlag<K>(key: K, fallback?: T): T` - Get flag value with optional fallback
-- `getFlags(): FeatureFlags<T>` - Get all flags as an object
-- `updateContext(context: Record<string, any>): Promise<void>` - Update evaluation context (async)
-- `subscribe(callback: (flags) => void): () => void` - Subscribe to flag updates; fires immediately with current flags, returns unsubscribe function
-- `destroy(): void` - Close transport connection, clear all subscribers, and release resources
-
-### Subscribing to Flag Updates
+---
 
-Instead of event listeners, use the `subscribe()` method. The callback is called **immediately** with the current flag state at subscription time, then again on every subsequent update:
+# Subscribing
 
 ```ts
 const unsubscribe = client.subscribe((flags) => {
-  console.log('Flags updated:', flags);
-  // Also fires immediately with current flags — no need to call getFlags() separately
+  const theme = client.getFlag('theme', 'light');
+  console.log(theme, flags);
 });
 
-// Later, to unsubscribe:
 unsubscribe();
 ```
 
-### Cache Adapter Interface
-
-```ts
-interface CacheAdapter {
-  loadFlags(apiKey: string): Promise<Record<string, any>> | Record<string, any>;
-  saveFlags(apiKey: string, flags: Record<string, any>): Promise<void> | void;
-  loadContext(apiKey: string): Promise<Record<string, any> | null> | Record<string, any> | null;
-  saveContext(apiKey: string, context: Record<string, any>): Promise<void> | void;
-}
-```
+The callback runs immediately with the current snapshot, then on every push. `destroy()` clears subscribers.
 
-## 🛠️ Development & Contributing
-
-### Build
+---
 
-```bash
-npm run build
-```
+# Offline cache
 
-### Test
+Enabled by default.
 
-```bash
-npm test
-```
+- **Browser:** loads `flagmint_<apiKey>_flags` from localStorage (24h TTL). With `configSync`, also hydrates/persists `flagmint_<apiKey>_rules` (lease `expiresAt`, not wall-clock TTL).
+- **Node with no adapter:** config-sync rules still work **in memory** for that process (`RulesStore`). Helper persist is a no-op — restart → cold `fullConfig`. Plug in `setCacheStorage` / `setAsyncCacheStorage` or a custom `cacheAdapter` to survive restarts.
+- If the stream fails, the last in-memory snapshot stays and `onError` fires.
 
-### Project Structure
-
-```
-sdk/
-├── core/
-│   ├── client.ts           # Main FlagClient
-│   ├── types.ts            # Type definitions
-│   ├── evaluation/         # Flag evaluation logic
-│   ├── helpers/            # Cache helpers (sync & async)
-│   └── transports/         # Transport implementations
+```ts
+cacheAdapter: {
+  loadFlags(apiKey, ttl) { /* ... */ },
+  saveFlags(apiKey, data) { /* ... */ },
+  loadContext(apiKey) { /* ... */ },
+  saveContext(apiKey, ctx) { /* ... */ },
+  loadRulesSnapshot(apiKey) { /* ... */ },   // configSync
+  saveRulesSnapshot(apiKey, snap) { /* ... */ },
+}
 ```
 
-## 🐛 Troubleshooting
+Use `syncCache` in the browser and `asyncCache` (or your own) in Node / React Native. See `sdk/core/helpers/Readme.md`.
 
-### Client not connecting
+---
 
-- Verify your API key is correct
-- Check network connectivity
-- Review browser console for errors
-- Ensure CORS is properly configured if using from browser
+# Debug logging
 
-### Flags not updating
+```ts
+const client = new FlagClient({
+  apiKey: 'ff_your_api_key',
+  enableFlagmint: true,
+  debugLog: true
+});
+```
 
-- Confirm `enableOfflineCache` setting matches your needs
-- Check transport mode (WebSocket vs long-polling)
-- Verify context is properly set with `await updateContext()`
-- Use `subscribe()` to listen for flag changes instead of polling
+In production, only connection lifecycle messages are emitted.
 
-### Cache behavior when server is down
+---
 
-**Important**: When `enableOfflineCache: true` (default):
-- Cached flags are loaded even if the server is unreachable
-- `ready()` **resolves** (does not throw) if cached flags are available — the `onError` callback is invoked instead to signal degraded mode
-- `ready()` only rejects if **no cached flags exist** and the server is unreachable
-- You can safely call `getFlag()` after `ready()` resolves, regardless of whether the connection succeeded
+# API
 
-### Performance issues
+```ts
+await client.ready()
+client.getFlag(key, fallback)
+client.getFlags()
+await client.updateContext(context)
+client.subscribe(callback) // returns unsubscribe
+client.destroy()
+```
 
-- Consider using long-polling instead of WebSocket for high-traffic scenarios
-- Implement proper cache TTLs
-- Monitor transport connection status
+---
 
-## 📞 Support & Resources
+# Framework support
 
-- **Documentation**: See [Flagmint Docs](https://docs.flagmint.io)
-- **Issues**: Report on [GitHub](https://github.com/flagmint/js-sdk/issues)
-- **Email**: support@flagmint.io
+React, Vue, Angular, Next.js, Nuxt, Express, Fastify, Node.js, vanilla JavaScript.
 
-## 🚀 Releases & Changelog
+Wrappers (`flagmint-vuejs-feature-flags`, `flagmint-react-sdk`) construct `FlagClient` for you. Connection sharing lives in this core SDK, not in the wrappers.
 
-See [GitHub Releases](https://github.com/flagmint/js-sdk/releases) for the complete version history, changelog, and upgrade guides.
+---
 
-## 📖 References
+# License
 
-* Core client: [sdk/core/client.ts](sdk/core/client.ts)
-* Type definitions: [sdk/core/types.ts](sdk/core/types.ts)
-* Cache helpers: [sdk/core/helpers/cacheHelper.ts](sdk/core/helpers/cacheHelper.ts), [cacheHelper.async.ts](sdk/core/helpers/cacheHelper.async.ts)
-* Transports: [WebsocketTransport](sdk/core/transports/WebsocketTransport.ts), [LongPollingTransport](sdk/core/transports/LongPollingTransport.ts)
-* Evaluation: [evaluateFlagValue](sdk/core/evaluation/evaluateFlagValue.ts), [evaluateRollout](sdk/core/evaluation/evaluateRollout.ts), [rolloutUtils](sdk/core/evaluation/rolloutUtils.ts)
+BSD 3-Clause License © Flagmint Team
 
 ---
 
-**License**: BSD 3-Clause License © Flagmint Team
+- **Documentation**: See [Flagmint Docs](https://docs.flagmint.com/sdks/nodejs)
+<!-- - **Issues**: Report on [GitHub](https://github.com/flagmint/js-sdk/issues) -->
+- **Email**: support@flagmint.com
 
 **Maintained with ❤️ by the Flagmint Team**
+