@flagbearer/node 0.1.4 → 0.1.5

package/README.md

@@ -10,83 +10,10 @@ Requires Node.js 22 or later.
 npm install @flagbearer/node
 ```
 
-## Keys
+## Docs
 
-Use a server key, which starts with `fbs_`. Server keys are secret, so load them
-from your environment and never include them in browser code. Browsers use client
-keys, which start with `fbc_`, through `@flagbearer/web`.
-
-## Usage
-
-```ts
-import { init } from "@flagbearer/node";
-
-const flags = init({
-  key: process.env.FLAGBEARER_SERVER_KEY!,
-});
-
-try {
-  await flags.sync(); // Optional: wait for fresh rules before accepting requests.
-} catch (error) {
-  console.error("Initial Flagbearer sync failed", error);
-  // Continue using defaults; the SDK retries transient failures in the background.
-}
-
-const enabled = flags.isEnabled(
-  "advanced-search",
-  { key: "123", email: "jane@example.com" },
-  false, // Application default when the rule is unknown or can't be evaluated.
-);
-
-// Keep one client per process, pass each request's user explicitly, and close it
-// during application shutdown rather than after each request.
-flags.close();
-```
-
-`url` is optional and defaults to `https://sdk.flagbearer.dev`, the SDK API
-origin. Override it with the SDK URL printed by `bun run dev` (by default
-`http://127.0.0.1:8081`) for local development, or with a self-hosted
-deployment's SDK origin; use HTTPS for remote production servers. Secret server keys are sent in
-`Authorization: Bearer ...` headers for both HTTP requests and streaming, never
-in URLs. Do not include server keys in browser code. Requests reject redirects
-rather than following a changed API location.
-
-## Refreshing and outages
-
-Pass `debug: true` to `init` to log stream connections, received versions, refresh
-attempts, retries, and applied snapshot versions using `console.debug`. Debugging
-is off by default; existing error logs are independent of this option. Logs never
-include SDK keys, user identities, flag names, or ruleset contents.
-
-For a change delivered over SSE, look for both `Stream version received` and
-`Snapshot applied` with the same version. A notification alone doesn't mean the
-SDK has downloaded the new rules yet. `Snapshot applied` also appears for initial,
-manual, and polling refreshes; it doesn't imply flag values actually changed.
-
-- Initialization opens an authenticated SSE stream and starts fetching rules.
-- The internal `@flagbearer/sdk-core` coordinator handles version tracking,
-  request coalescing, five-second request timeouts, retries, and fallback polling.
-- Valid rules are indexed by flag key and replaced together. `isEnabled` is
-  synchronous and uses only the current in-memory rules.
-- A newer streamed version triggers a ruleset refresh within two seconds. Older responses cannot
-  replace a newer ruleset. Reconnecting also triggers a refresh.
-- The Node stream uses `fetch`, supports chunked SSE data and heartbeats, and
-  reconnects with jittered backoff capped at 30 seconds. Connection setup times
-  out after five seconds; 45 seconds without stream data triggers reconnection.
-- While streaming is disconnected, rules are polled about every 30 seconds. HTTP 408,
-  429, and server errors are retried, honoring longer `Retry-After` delays.
-- Invalid rules or permanent ruleset errors stop automatic refreshes and close
-  the stream. Existing rules remain usable. An explicit `sync()` can retry;
-  successful recovery resumes polling, not the closed stream.
-- A permanent stream error stops stream reconnects but leaves polling available.
-- Explicit `sync()` failures reject; background refresh failures are logged.
-- `close()` aborts requests and streaming and clears timers. It is idempotent;
-  later `sync()` calls reject. Existing in-memory rules can still be evaluated.
-
-Until the first valid ruleset arrives, checks use the supplied default. During an
-outage, the last valid ruleset stays in memory. There is **no disk cache yet**:
-restarting the application during an outage means using defaults until a fetch
-succeeds. This SDK requires a Node runtime with built-in `fetch` and web streams.
+Keys, syncing at startup, per-request checks, shutdown and exposures are covered
+at [docs.flagbearer.dev/sdks/node](https://docs.flagbearer.dev/sdks/node).
 
 ## Development
 
@@ -107,42 +34,5 @@ Bun is used as the build tool; the output targets Node.js.
 
 ## Integration tests
 
-The integration suite runs this SDK in a separate Node HTTP server alongside
-the browser SDK and an isolated backend:
-
-```sh
-bun run test:integration
-```
-
-See [the integration README](../../tests/integration/README.md) for setup and coverage.
-
-## Exposure reporting
-
-Flag checks automatically report the boolean actually returned, its evaluation
-reason (`off`, `tester`, `rollout`, or `fallback`), the configuration version, and
-optional user key/email. Reporting runs in every environment and never waits for
-network activity in `isEnabled`. Pass `appVersion` to `init` to identify your
-application deployment in the stored records.
-
-Repeated checks are counted in fixed 30-second buckets by user, flag, result,
-reason, and configuration version. Uploads run every 10 seconds in batches of up
-to 100 aggregates. The memory buffer holds up to 1,000 aggregates. Overflow and
-rejected checks are reported as environment-level reporting loss when delivery
-recovers. Records keep their IDs and contents across retries; HTTP retries do not
-increase stored counts. The server currently accepts up to 6,000 batches per
-minute per environment and returns `429` beyond that limit.
-
-For shutdown or serverless invocations, explicitly await delivery before closing:
-
-```ts
-try {
-  await flags.flush();
-} finally {
-  flags.close();
-}
-```
-
-`flush()` rejects on upload failure so callers can choose their shutdown policy.
-`close()` also starts a best-effort flush and stops recurring reporting. Delivery
-is best effort: abrupt process exits can lose in-memory checks. Old SDK versions
-do not report exposure; no observed activity does not prove a path is unused.
+Flagbearer's integration tests run this SDK against the real backend through
+[`testing/servers/node-server.ts`](../../testing/servers/node-server.ts).

package/dist/index.js

@@ -32,7 +32,7 @@ function evaluateFlag(flag, user, version = null, defaultValue = false) {
     configurationVersion: version
   };
 }
-// ../sdk-core/src/clock.ts
+// ../core/src/clock.ts
 var realClock = {
   now: () => Date.now(),
   setTimeout(callback, delayMs) {
@@ -41,7 +41,7 @@ var realClock = {
   }
 };
 
-// ../sdk-core/src/debug.ts
+// ../core/src/debug.ts
 function createDebugLogger(enabled = false) {
   return (message, details) => {
     if (!enabled)
@@ -55,7 +55,7 @@ function createDebugLogger(enabled = false) {
   };
 }
 
-// ../sdk-core/src/validation.ts
+// ../core/src/validation.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -84,7 +84,7 @@ function isVersionEvent(value) {
   return isRecord(value) && isVersion(value.version);
 }
 
-// ../sdk-core/src/refresh.ts
+// ../core/src/refresh.ts
 var REQUEST_TIMEOUT_MS = 5000;
 var POLL_INTERVAL_MS = 30000;
 var MAX_RETRY_MS = 30000;
@@ -156,6 +156,8 @@ function createRefreshCoordinator(options) {
   let cancelVersionRefresh;
   let retryAttempt = 0;
   let notBefore = 0;
+  let serverNotBefore = 0;
+  let lastCheckedAt = Number.NEGATIVE_INFINITY;
   function clearRetry() {
     cancelRetry?.();
     cancelRetry = undefined;
@@ -196,6 +198,9 @@ function createRefreshCoordinator(options) {
     const jittered = Math.min(MAX_RETRY_MS, backoff * (0.8 + Math.random() * 0.4));
     const delay = Math.max(jittered, error instanceof RefreshError ? error.retryAfterMs : 0);
     notBefore = clock.now() + delay;
+    if (error instanceof RefreshError && error.retryAfterMs > 0) {
+      serverNotBefore = Math.max(serverNotBefore, clock.now() + error.retryAfterMs);
+    }
     clearRetry();
     debug("Refresh retry scheduled", {
       delayMs: Math.ceil(delay),
@@ -229,6 +234,7 @@ function createRefreshCoordinator(options) {
         cancelRequestTimeout = undefined;
         if (stopped)
           return;
+        lastCheckedAt = clock.now();
         if (result === null) {
           debug("Snapshot unchanged", { version });
           if (isBehindWantedVersion()) {
@@ -266,6 +272,7 @@ function createRefreshCoordinator(options) {
     } catch (error) {
       if (stopped)
         return;
+      options.onRefreshFailed?.(error);
       if (error instanceof RefreshError && !error.retryable) {
         debug("Automatic refresh stopped after permanent failure");
         automaticBlocked = true;
@@ -335,6 +342,28 @@ function createRefreshCoordinator(options) {
       ensurePolling();
     }
   }
+  function resume() {
+    if (stopped || automaticBlocked)
+      return;
+    if (clock.now() - lastCheckedAt < (options.resumeStaleMs ?? 15000)) {
+      ensurePolling();
+      return;
+    }
+    if (clock.now() >= serverNotBefore) {
+      clearRetry();
+      notBefore = 0;
+      retryAttempt = 0;
+    }
+    clearPolling();
+    refreshInBackground();
+    ensurePolling();
+  }
+  function pause() {
+    if (stopped)
+      return;
+    streaming = false;
+    clearPolling();
+  }
   function close() {
     if (stopped)
       return;
@@ -349,16 +378,26 @@ function createRefreshCoordinator(options) {
     activeRequest?.abort();
   }
   ensurePolling();
-  return { sync, refreshInBackground, onVersion, setStreaming, close };
+  return {
+    sync,
+    refreshInBackground,
+    onVersion,
+    setStreaming,
+    resume,
+    pause,
+    close
+  };
 }
-// ../sdk-core/src/exposures.ts
+// ../core/src/exposures.ts
 var WINDOW_MS = 30000;
+var FLUSH_MS = 30000;
 var MAX_RECORDS = 1000;
 var BATCH_SIZE = 100;
 function createExposureReporter(options) {
   const reporterId = crypto.randomUUID();
   const active = new Map;
-  const pending = [];
+  const sealed = [];
+  let sealedEvents = 0;
   let droppedChecks = 0;
   let reportedDroppedChecks = 0;
   let inFlight;
@@ -387,39 +426,62 @@ function createExposureReporter(options) {
         bucket
       ]);
       const existing = active.get(key);
-      if (existing && existing.checkCount < 1e9) {
-        existing.checkCount++;
-        existing.lastCheckedAt = new Date(now).toISOString();
+      if (existing && existing.event.checkCount < 1e9) {
+        existing.event.checkCount++;
+        existing.event.lastCheckedAt = new Date(now).toISOString();
         return;
       }
-      if (existing || active.size + pending.length >= MAX_RECORDS) {
+      if (existing || active.size + sealedEvents >= MAX_RECORDS) {
         droppedChecks++;
         return;
       }
       active.set(key, {
-        eventId: crypto.randomUUID(),
-        flagKey,
-        userKey,
-        userEmail: email,
-        result: details.value,
-        reason: details.reason,
-        configurationVersion: details.configurationVersion,
-        bucket,
-        checkCount: 1,
-        firstCheckedAt: new Date(now).toISOString(),
-        lastCheckedAt: new Date(now).toISOString()
+        user: { key: userKey, email },
+        event: {
+          flagKey,
+          result: details.value,
+          reason: details.reason,
+          configurationVersion: details.configurationVersion,
+          bucket,
+          checkCount: 1,
+          firstCheckedAt: new Date(now).toISOString(),
+          lastCheckedAt: new Date(now).toISOString()
+        }
       });
     } catch {
       droppedChecks++;
     }
   }
-  async function send() {
-    for (const [key, record] of active) {
-      pending.push(record);
+  function seal() {
+    const open = new Map;
+    for (const [key, { user, event }] of active) {
+      const userId = JSON.stringify([user.key, user.email]);
+      let batch = open.get(userId);
+      if (!batch || batch.events.length >= BATCH_SIZE) {
+        batch = { batchId: crypto.randomUUID(), user, events: [] };
+        open.set(userId, batch);
+        sealed.push(batch);
+      }
+      batch.events.push(event);
+      sealedEvents++;
       active.delete(key);
     }
-    while (pending.length > 0 || droppedChecks > reportedDroppedChecks) {
-      const batch = pending.slice(0, BATCH_SIZE);
+  }
+  function settle(batch) {
+    if (sealed[0] !== batch)
+      return;
+    sealed.shift();
+    sealedEvents -= batch.events.length;
+  }
+  async function send() {
+    seal();
+    while (sealed.length > 0 || droppedChecks > reportedDroppedChecks) {
+      const batch = sealed[0] ?? {
+        batchId: crypto.randomUUID(),
+        user: {},
+        events: []
+      };
+      const checks = batch.events.reduce((sum, item) => sum + item.checkCount, 0);
       const dropped = droppedChecks;
       const response = await fetch(options.url, {
         method: "POST",
@@ -430,15 +492,17 @@ function createExposureReporter(options) {
           Authorization: `Bearer ${options.key}`
         },
         body: JSON.stringify({
+          batchId: batch.batchId,
           reporterId,
-          events: batch,
+          user: batch.user,
+          events: batch.events,
           droppedChecks: dropped,
           sdk: options.sdk,
-          sdkVersion: "0.0.0",
+          sdkVersion: options.sdkVersion,
           appVersion: options.appVersion?.slice(0, 100)
         }),
         signal: AbortSignal.timeout(1e4),
-        keepalive: batch.length < 10
+        keepalive: batch.events.length < 10
       });
       if (!response.ok) {
         const retryAfter = Number(response.headers.get("Retry-After"));
@@ -446,18 +510,18 @@ function createExposureReporter(options) {
           retryAt = Math.max(retryAt, Date.now() + Math.min(retryAfter, 3600) * 1000);
         }
         if (response.status >= 400 && response.status < 500 && response.status !== 429) {
-          droppedChecks += batch.reduce((sum, item) => sum + item.checkCount, 0);
-          pending.splice(0, batch.length);
+          droppedChecks += checks;
+          settle(batch);
           retryAt = Date.now() + 60000;
         }
         throw new Error(`Exposure upload failed (${response.status})`);
       }
       const receipt = await response.json();
-      if (typeof receipt !== "object" || receipt === null || !("accepted" in receipt) || typeof receipt.accepted !== "number" || !Number.isSafeInteger(receipt.accepted) || receipt.accepted < 0 || receipt.accepted > batch.length || !("rejectedChecks" in receipt) || typeof receipt.rejectedChecks !== "number" || !Number.isSafeInteger(receipt.rejectedChecks) || receipt.rejectedChecks < 0 || receipt.rejectedChecks > batch.reduce((sum, item) => sum + item.checkCount, 0)) {
+      if (typeof receipt !== "object" || receipt === null || !("accepted" in receipt) || typeof receipt.accepted !== "number" || !Number.isSafeInteger(receipt.accepted) || receipt.accepted < 0 || receipt.accepted > batch.events.length || !("rejectedChecks" in receipt) || typeof receipt.rejectedChecks !== "number" || !Number.isSafeInteger(receipt.rejectedChecks) || receipt.rejectedChecks < 0 || receipt.rejectedChecks > checks) {
         throw new Error("Invalid exposure upload receipt");
       }
       droppedChecks += receipt.rejectedChecks;
-      pending.splice(0, batch.length);
+      settle(batch);
       reportedDroppedChecks = Math.max(reportedDroppedChecks, dropped);
     }
     failures = 0;
@@ -477,7 +541,7 @@ function createExposureReporter(options) {
   const timer = setInterval(() => {
     if (!closed && Date.now() >= retryAt)
       flush().catch(() => {});
-  }, 1e4);
+  }, FLUSH_MS);
   timer.unref?.();
   function close() {
     closed = true;
@@ -638,6 +702,9 @@ function createVersionStream(options) {
   return { close };
 }
 
+// src/version.ts
+var SDK_VERSION = "0.1.5";
+
 // src/index.ts
 var DEFAULT_URL = "https://sdk.flagbearer.dev";
 function init({
@@ -659,6 +726,7 @@ function init({
     url: new URL("/v1/exposures", baseUrl),
     key,
     sdk: "node",
+    sdkVersion: SDK_VERSION,
     appVersion
   });
   let configurationVersion = null;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION: string;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@flagbearer/node",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Flagbearer Node.js SDK",
   "license": "MIT",
   "homepage": "https://flagbearer.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ajsmth/flagbearer.git",
-    "directory": "packages/sdk-node"
+    "url": "git+https://github.com/flagbearer-dev/sdks.git",
+    "directory": "js/node"
   },
   "keywords": [
     "feature-flags",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --target node --format esm --outdir ./dist && tsc -p tsconfig.json --emitDeclarationOnly",
+    "build": "bun build ./src/index.ts --target node --format esm --outdir ./dist --define __FLAGBEARER_SDK_VERSION__=\\\"$npm_package_version\\\" && tsc -p tsconfig.json --emitDeclarationOnly",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepack": "bun run build"
   },