@flagbearer/node 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flagbearer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @flagbearer/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js SDK for Flagbearer. Downloads an environment's ruleset and evaluates flags
+locally for each user, without making a network request for every flag check.
+Requires Node.js 22 or later.
+
+## Install
+
+```sh
+npm install @flagbearer/node
+```
+
+## Keys
+
+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.
+
+## Development
+
+From the repository root:
+
+```sh
+bun run --filter @flagbearer/node typecheck
+bun run --filter @flagbearer/node build
+```
+
+The build produces a Node-targeted ES module and self-contained TypeScript
+declarations in `dist/`, bundling the internal refresh core, plain SDK validators,
+and evaluator directly from their workspace sources. It does not import the
+application's `shared` package or admin endpoint contracts. Internal packages
+are build dependencies, not extra packages SDK consumers must install. The SDK
+does not include Valibot or another validation library.
+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.

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type SdkOptions = {
+    key: string;
+    url?: string;
+    debug?: boolean;
+    appVersion?: string;
+};
+export type EvaluationUser = {
+    key?: string;
+    email?: string;
+};
+export declare function init({ key, url, debug, appVersion, }: SdkOptions): {
+    sync: () => Promise<void>;
+    isEnabled: (flag: string, user: EvaluationUser, defaultValue?: boolean) => boolean;
+    flush: () => Promise<void>;
+    close: () => void;
+};
+export type Client = ReturnType<typeof init>;

package/dist/index.js

@@ -0,0 +1,738 @@
+// ../evaluator/src/evaluate-flags.ts
+import { createHash } from "node:crypto";
+function bucket(flagKey, userKey) {
+  const hash = createHash("sha256").update(`${flagKey}:${userKey}`, "utf8").digest("hex");
+  return Number(BigInt(`0x${hash}`) % 10000n);
+}
+function evaluateFlag(flag, user, version = null, defaultValue = false) {
+  if (!flag) {
+    return {
+      value: defaultValue,
+      reason: "fallback",
+      configurationVersion: version
+    };
+  }
+  if (!flag.enabled) {
+    return { value: false, reason: "off", configurationVersion: version };
+  }
+  const email = user.email?.trim().toLowerCase();
+  if (email && flag.overrideEmails.some((item) => item.trim().toLowerCase() === email)) {
+    return { value: true, reason: "tester", configurationVersion: version };
+  }
+  if (!user.key && flag.rolloutBps !== 0 && flag.rolloutBps !== 1e4) {
+    return {
+      value: defaultValue,
+      reason: "fallback",
+      configurationVersion: version
+    };
+  }
+  return {
+    value: user.key ? bucket(flag.key, user.key) < flag.rolloutBps : flag.rolloutBps === 1e4,
+    reason: "rollout",
+    configurationVersion: version
+  };
+}
+// ../sdk-core/src/clock.ts
+var realClock = {
+  now: () => Date.now(),
+  setTimeout(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return () => clearTimeout(timer);
+  }
+};
+
+// ../sdk-core/src/debug.ts
+function createDebugLogger(enabled = false) {
+  return (message, details) => {
+    if (!enabled)
+      return;
+    try {
+      if (details)
+        console.debug(`[Flagbearer] ${message}`, details);
+      else
+        console.debug(`[Flagbearer] ${message}`);
+    } catch {}
+  };
+}
+
+// ../sdk-core/src/validation.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVersion(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isFlagRule(value) {
+  if (!isRecord(value) || typeof value.key !== "string" || typeof value.enabled !== "boolean" || typeof value.rolloutBps !== "number" || !Number.isInteger(value.rolloutBps) || value.rolloutBps < 0 || value.rolloutBps > 1e4 || !Array.isArray(value.overrideEmails))
+    return false;
+  for (const email of value.overrideEmails) {
+    if (typeof email !== "string")
+      return false;
+  }
+  return true;
+}
+function isRuleset(value) {
+  if (!isRecord(value) || typeof value.environmentId !== "string" || !isVersion(value.version) || !Array.isArray(value.flags))
+    return false;
+  for (const flag of value.flags) {
+    if (!isFlagRule(flag))
+      return false;
+  }
+  return true;
+}
+function isVersionEvent(value) {
+  return isRecord(value) && isVersion(value.version);
+}
+
+// ../sdk-core/src/refresh.ts
+var REQUEST_TIMEOUT_MS = 5000;
+var POLL_INTERVAL_MS = 30000;
+var MAX_RETRY_MS = 30000;
+var MAX_VERSION_REFRESH_DELAY_MS = 2000;
+
+class RefreshError extends Error {
+  retryable;
+  retryAfterMs;
+  constructor(message, retryable, retryAfterMs = 0) {
+    super(message);
+    this.retryable = retryable;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+function retryAfter(header, now) {
+  if (header === null)
+    return 0;
+  const seconds = Number(header);
+  const delay = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : Date.parse(header) - now;
+  return Number.isFinite(delay) ? Math.max(0, delay) : 0;
+}
+function checkResponse(response, clock = realClock) {
+  if (!response.ok) {
+    throw new RefreshError(`Flagbearer request failed: ${response.status}`, response.status === 408 || response.status === 429 || response.status >= 500, retryAfter(response.headers.get("Retry-After"), clock.now()));
+  }
+}
+async function readJsonResponse(response, signal, clock = realClock) {
+  checkResponse(response, clock);
+  try {
+    return await response.json();
+  } catch (error) {
+    if (signal.aborted)
+      throw signal.reason;
+    if (error instanceof SyntaxError)
+      throw new RefreshError("Invalid snapshot JSON", false);
+    throw error;
+  }
+}
+function wait(ms, signal, clock) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted)
+      return reject(signal.reason);
+    const cancelTimer = clock.setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    function abort() {
+      cancelTimer();
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason);
+    }
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+function createRefreshCoordinator(options) {
+  const clock = options.clock ?? realClock;
+  const debug = createDebugLogger(options.debug);
+  let stopped = false;
+  let automaticBlocked = false;
+  let streaming = false;
+  let version;
+  let wantedVersion;
+  let refreshAgain = false;
+  let inFlight;
+  let activeRequest;
+  let cancelRequestTimeout;
+  let cancelRetry;
+  let cancelPolling;
+  let cancelVersionRefresh;
+  let retryAttempt = 0;
+  let notBefore = 0;
+  function clearRetry() {
+    cancelRetry?.();
+    cancelRetry = undefined;
+  }
+  function clearPolling() {
+    if (cancelPolling)
+      debug("Polling disabled");
+    cancelPolling?.();
+    cancelPolling = undefined;
+  }
+  function ensurePolling() {
+    if (options.background && !stopped && !automaticBlocked && !streaming && cancelPolling === undefined) {
+      const intervalMs = POLL_INTERVAL_MS * (0.9 + Math.random() * 0.2);
+      debug("Polling scheduled", { intervalMs: Math.ceil(intervalMs) });
+      cancelPolling = clock.setTimeout(() => {
+        cancelPolling = undefined;
+        refreshInBackground();
+        ensurePolling();
+      }, intervalMs);
+    }
+  }
+  function isBehindWantedVersion() {
+    return wantedVersion !== undefined && (version === undefined || version < wantedVersion);
+  }
+  function scheduleVersionRefresh() {
+    if (cancelVersionRefresh !== undefined || inFlight !== undefined)
+      return;
+    cancelVersionRefresh = clock.setTimeout(() => {
+      cancelVersionRefresh = undefined;
+      if (isBehindWantedVersion())
+        refreshInBackground();
+    }, Math.random() * MAX_VERSION_REFRESH_DELAY_MS);
+  }
+  function scheduleRetry(error) {
+    if (!options.background || stopped)
+      return;
+    const backoff = Math.min(MAX_RETRY_MS, 1000 * 2 ** Math.min(retryAttempt++, 5));
+    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;
+    clearRetry();
+    debug("Refresh retry scheduled", {
+      delayMs: Math.ceil(delay),
+      attempt: retryAttempt
+    });
+    cancelRetry = clock.setTimeout(() => {
+      cancelRetry = undefined;
+      refreshInBackground();
+    }, Math.min(delay, 2147483647));
+  }
+  async function run() {
+    const controller = new AbortController;
+    activeRequest = controller;
+    try {
+      do {
+        refreshAgain = false;
+        while (clock.now() < notBefore) {
+          await wait(Math.min(notBefore - clock.now(), 2147483647), controller.signal, clock);
+        }
+        if (stopped)
+          return;
+        debug("Refresh started");
+        cancelRequestTimeout = clock.setTimeout(() => {
+          controller.abort(new DOMException("Flagbearer refresh timed out", "TimeoutError"));
+        }, REQUEST_TIMEOUT_MS);
+        const result = await options.fetchSnapshot(controller.signal);
+        if (result !== null && !isVersion(result.version)) {
+          throw new RefreshError("Invalid snapshot version", false);
+        }
+        cancelRequestTimeout?.();
+        cancelRequestTimeout = undefined;
+        if (stopped)
+          return;
+        if (result === null) {
+          debug("Snapshot unchanged", { version });
+          if (isBehindWantedVersion()) {
+            scheduleRetry(undefined);
+            return;
+          }
+          retryAttempt = 0;
+          notBefore = 0;
+          continue;
+        }
+        const previousVersion = version;
+        if (version === undefined || result.version >= version) {
+          version = result.version;
+          options.applySnapshot(result);
+          debug("Snapshot applied", { version, previousVersion });
+        } else {
+          debug("Older snapshot ignored", {
+            version: result.version,
+            currentVersion: version
+          });
+        }
+        if (stopped)
+          return;
+        if (isBehindWantedVersion()) {
+          if (previousVersion !== undefined && result.version <= previousVersion) {
+            scheduleRetry(undefined);
+            return;
+          }
+          refreshAgain = true;
+        } else {
+          retryAttempt = 0;
+          notBefore = 0;
+        }
+      } while (refreshAgain);
+    } catch (error) {
+      if (stopped)
+        return;
+      if (error instanceof RefreshError && !error.retryable) {
+        debug("Automatic refresh stopped after permanent failure");
+        automaticBlocked = true;
+        streaming = false;
+        clearRetry();
+        clearPolling();
+        options.onPermanentFailure();
+      } else {
+        scheduleRetry(error);
+      }
+      throw error;
+    } finally {
+      cancelRequestTimeout?.();
+      cancelRequestTimeout = undefined;
+      activeRequest = undefined;
+    }
+  }
+  function begin() {
+    clearRetry();
+    inFlight = run().finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  }
+  function refreshInBackground() {
+    if (stopped || automaticBlocked || cancelRetry !== undefined || inFlight !== undefined)
+      return;
+    begin().catch((error) => console.error("Flagbearer sync failed", error));
+  }
+  function sync() {
+    if (stopped)
+      return Promise.reject(new Error("Flagbearer client is closed"));
+    if (inFlight) {
+      debug("Joining active refresh");
+      return inFlight;
+    }
+    automaticBlocked = false;
+    ensurePolling();
+    return begin();
+  }
+  function onVersion(nextVersion) {
+    if (stopped)
+      return;
+    debug("Stream version received", {
+      version: nextVersion,
+      currentVersion: version
+    });
+    wantedVersion = Math.max(wantedVersion ?? 0, nextVersion);
+    if (isBehindWantedVersion())
+      scheduleVersionRefresh();
+  }
+  function setStreaming({
+    connected,
+    refresh = true
+  }) {
+    if (stopped)
+      return;
+    if (streaming !== connected) {
+      debug(connected ? "Stream connected" : "Stream disconnected; using polling");
+    }
+    streaming = connected;
+    if (connected) {
+      clearPolling();
+      if (refresh)
+        refreshInBackground();
+    } else {
+      ensurePolling();
+    }
+  }
+  function close() {
+    if (stopped)
+      return;
+    stopped = true;
+    debug("Coordinator closed");
+    clearRetry();
+    clearPolling();
+    cancelVersionRefresh?.();
+    cancelVersionRefresh = undefined;
+    cancelRequestTimeout?.();
+    cancelRequestTimeout = undefined;
+    activeRequest?.abort();
+  }
+  ensurePolling();
+  return { sync, refreshInBackground, onVersion, setStreaming, close };
+}
+// ../sdk-core/src/exposures.ts
+var WINDOW_MS = 30000;
+var MAX_RECORDS = 1000;
+var BATCH_SIZE = 100;
+function createExposureReporter(options) {
+  const reporterId = crypto.randomUUID();
+  const active = new Map;
+  const pending = [];
+  let droppedChecks = 0;
+  let reportedDroppedChecks = 0;
+  let inFlight;
+  let closed = false;
+  let retryAt = 0;
+  let failures = 0;
+  function record(flagKey, user, details) {
+    if (closed)
+      return;
+    try {
+      if (!flagKey || flagKey.length > 256 || user.key && user.key.length > 256) {
+        droppedChecks++;
+        return;
+      }
+      const now = Date.now();
+      const bucket = new Date(Math.floor(now / WINDOW_MS) * WINDOW_MS).toISOString();
+      const email = user.email && user.email.length <= 254 ? user.email.trim().toLowerCase() || undefined : undefined;
+      const userKey = user.key || undefined;
+      const key = JSON.stringify([
+        flagKey,
+        userKey,
+        email,
+        details.value,
+        details.reason,
+        details.configurationVersion,
+        bucket
+      ]);
+      const existing = active.get(key);
+      if (existing && existing.checkCount < 1e9) {
+        existing.checkCount++;
+        existing.lastCheckedAt = new Date(now).toISOString();
+        return;
+      }
+      if (existing || active.size + pending.length >= 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()
+      });
+    } catch {
+      droppedChecks++;
+    }
+  }
+  async function send() {
+    for (const [key, record] of active) {
+      pending.push(record);
+      active.delete(key);
+    }
+    while (pending.length > 0 || droppedChecks > reportedDroppedChecks) {
+      const batch = pending.slice(0, BATCH_SIZE);
+      const dropped = droppedChecks;
+      const response = await fetch(options.url, {
+        method: "POST",
+        credentials: "omit",
+        redirect: "error",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${options.key}`
+        },
+        body: JSON.stringify({
+          reporterId,
+          events: batch,
+          droppedChecks: dropped,
+          sdk: options.sdk,
+          sdkVersion: "0.0.0",
+          appVersion: options.appVersion?.slice(0, 100)
+        }),
+        signal: AbortSignal.timeout(1e4),
+        keepalive: batch.length < 10
+      });
+      if (!response.ok) {
+        const retryAfter = Number(response.headers.get("Retry-After"));
+        if (Number.isFinite(retryAfter) && retryAfter > 0) {
+          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);
+          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)) {
+        throw new Error("Invalid exposure upload receipt");
+      }
+      droppedChecks += receipt.rejectedChecks;
+      pending.splice(0, batch.length);
+      reportedDroppedChecks = Math.max(reportedDroppedChecks, dropped);
+    }
+    failures = 0;
+  }
+  function flush() {
+    if (inFlight)
+      return inFlight.then(() => flush());
+    inFlight = send().catch((error) => {
+      failures++;
+      retryAt = Math.max(retryAt, Date.now() + Math.min(60000, 1000 * 2 ** Math.min(failures, 6)));
+      throw error;
+    }).finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  }
+  const timer = setInterval(() => {
+    if (!closed && Date.now() >= retryAt)
+      flush().catch(() => {});
+  }, 1e4);
+  timer.unref?.();
+  function close() {
+    closed = true;
+    clearInterval(timer);
+    return flush();
+  }
+  return { record, flush, close };
+}
+// src/stream.ts
+var CONNECT_TIMEOUT_MS = 5000;
+var IDLE_TIMEOUT_MS = 45000;
+var MAX_RETRY_MS2 = 30000;
+var MAX_EVENT_LENGTH = 65536;
+function createVersionStream(options) {
+  const debug = createDebugLogger(options.debug);
+  let closed = false;
+  let active;
+  let timeout;
+  let retry;
+  let attempts = 0;
+  function armTimeout(controller, delay) {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => controller.abort(), delay);
+  }
+  function reconnect(error) {
+    const backoff = Math.min(MAX_RETRY_MS2, 1000 * 2 ** Math.min(attempts++, 5));
+    const jittered = Math.min(MAX_RETRY_MS2, backoff * (0.8 + Math.random() * 0.4));
+    const delay = Math.max(jittered, error instanceof RefreshError ? error.retryAfterMs : 0);
+    const notBefore = Date.now() + delay;
+    debug("Stream reconnect scheduled", { delayMs: Math.ceil(delay) });
+    function schedule() {
+      if (closed)
+        return;
+      const remaining = notBefore - Date.now();
+      if (remaining <= 0) {
+        retry = undefined;
+        connect();
+      } else {
+        retry = setTimeout(schedule, Math.min(remaining, 2147483647));
+      }
+    }
+    schedule();
+  }
+  async function connect() {
+    if (closed)
+      return;
+    debug("Stream connecting");
+    const controller = new AbortController;
+    active = controller;
+    let failure;
+    try {
+      let line = function(value) {
+        if (value === "") {
+          if (event === "version" && data !== "") {
+            let parsed;
+            try {
+              parsed = JSON.parse(data);
+            } catch {}
+            if (isVersionEvent(parsed))
+              options.onVersion(parsed.version);
+          }
+          event = "message";
+          data = "";
+          return;
+        }
+        if (value.startsWith(":"))
+          return;
+        const separator = value.indexOf(":");
+        const field = separator === -1 ? value : value.slice(0, separator);
+        let content = separator === -1 ? "" : value.slice(separator + 1);
+        if (content.startsWith(" "))
+          content = content.slice(1);
+        if (field === "event")
+          event = content;
+        if (field === "data")
+          data += `${content}
+`;
+        if (data.length > MAX_EVENT_LENGTH)
+          throw new Error("Flagbearer stream event too large");
+      };
+      armTimeout(controller, CONNECT_TIMEOUT_MS);
+      const response = await fetch(options.url, {
+        headers: { ...options.headers, Accept: "text/event-stream" },
+        signal: controller.signal,
+        credentials: "omit",
+        cache: "no-store",
+        redirect: "error"
+      });
+      checkResponse(response);
+      const contentType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+      if (contentType !== "text/event-stream" || !response.body) {
+        throw new RefreshError("Invalid Flagbearer stream response", false);
+      }
+      if (closed)
+        return;
+      armTimeout(controller, IDLE_TIMEOUT_MS);
+      options.onOpen();
+      const decoder = new TextDecoder;
+      const reader = response.body.getReader();
+      let buffer = "";
+      let event = "message";
+      let data = "";
+      try {
+        while (!closed) {
+          const chunk = await reader.read();
+          if (chunk.done)
+            break;
+          armTimeout(controller, IDLE_TIMEOUT_MS);
+          attempts = 0;
+          buffer += decoder.decode(chunk.value, { stream: true });
+          let start = 0;
+          for (let index = 0;index < buffer.length; index++) {
+            const char = buffer[index];
+            if (char !== "\r" && char !== `
+`)
+              continue;
+            if (char === "\r" && index === buffer.length - 1)
+              break;
+            line(buffer.slice(start, index));
+            if (char === "\r" && buffer[index + 1] === `
+`)
+              index++;
+            start = index + 1;
+          }
+          buffer = buffer.slice(start);
+          if (buffer.length > MAX_EVENT_LENGTH)
+            throw new Error("Flagbearer stream line too large");
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    } catch (error) {
+      failure = error;
+    } finally {
+      clearTimeout(timeout);
+      controller.abort();
+      active = undefined;
+    }
+    if (closed)
+      return;
+    options.onDisconnect();
+    if (failure instanceof RefreshError && !failure.retryable) {
+      console.error("Flagbearer stream stopped; using polling", failure);
+      return;
+    }
+    reconnect(failure);
+  }
+  function close() {
+    if (closed)
+      return;
+    closed = true;
+    debug("Stream closed");
+    clearTimeout(timeout);
+    clearTimeout(retry);
+    active?.abort();
+  }
+  connect();
+  return { close };
+}
+
+// src/index.ts
+var DEFAULT_URL = "https://sdk.flagbearer.dev";
+function init({
+  key,
+  url = DEFAULT_URL,
+  debug = false,
+  appVersion
+}) {
+  if (!key || /\s/.test(key))
+    throw new Error("A nonempty server SDK key is required");
+  const baseUrl = new URL(url);
+  if (baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:") {
+    throw new Error("Flagbearer url must use HTTP or HTTPS");
+  }
+  const rulesetUrl = new URL("/v1/ruleset", baseUrl);
+  const streamUrl = new URL("/v1/stream", baseUrl);
+  const headers = { Authorization: `Bearer ${key}` };
+  const reporter = createExposureReporter({
+    url: new URL("/v1/exposures", baseUrl),
+    key,
+    sdk: "node",
+    appVersion
+  });
+  let configurationVersion = null;
+  let rules = new Map;
+  let environmentId;
+  let stream;
+  let hasConnected = false;
+  let closed = false;
+  const coordinator = createRefreshCoordinator({
+    debug,
+    async fetchSnapshot(signal) {
+      const response = await fetch(rulesetUrl, {
+        method: "GET",
+        headers: configurationVersion === null ? headers : { ...headers, "If-None-Match": `"${configurationVersion}"` },
+        signal,
+        credentials: "omit",
+        cache: "no-store",
+        redirect: "error"
+      });
+      if (response.status === 304)
+        return null;
+      const result = await readJsonResponse(response, signal);
+      if (!isRuleset(result))
+        throw new RefreshError("Invalid ruleset response", false);
+      if (environmentId !== undefined && result.environmentId !== environmentId) {
+        throw new RefreshError("Ruleset environment changed unexpectedly", false);
+      }
+      return result;
+    },
+    applySnapshot(snapshot) {
+      const next = new Map(snapshot.flags.map((rule) => [rule.key, rule]));
+      environmentId = snapshot.environmentId;
+      configurationVersion = snapshot.version;
+      rules = next;
+    },
+    background: true,
+    onPermanentFailure: () => stream?.close()
+  });
+  function isEnabled(flag, user, defaultValue = false) {
+    let details;
+    try {
+      details = evaluateFlag(rules.get(flag), user, configurationVersion, defaultValue);
+    } catch {
+      details = {
+        value: defaultValue,
+        reason: "fallback",
+        configurationVersion
+      };
+    }
+    reporter.record(flag, user, details);
+    return details.value;
+  }
+  function close() {
+    if (closed)
+      return;
+    closed = true;
+    coordinator.close();
+    stream?.close();
+    reporter.close().catch(() => {});
+  }
+  stream = createVersionStream({
+    debug,
+    url: streamUrl,
+    headers,
+    onVersion: coordinator.onVersion,
+    onOpen() {
+      coordinator.setStreaming({ connected: true, refresh: hasConnected });
+      hasConnected = true;
+    },
+    onDisconnect: () => coordinator.setStreaming({ connected: false })
+  });
+  coordinator.refreshInBackground();
+  return { sync: coordinator.sync, isEnabled, flush: reporter.flush, close };
+}
+export {
+  init
+};

package/dist/stream.d.ts

@@ -0,0 +1,12 @@
+type StreamOptions = {
+    url: URL;
+    headers: Record<string, string>;
+    debug?: boolean;
+    onVersion(version: number): void;
+    onOpen(): void;
+    onDisconnect(): void;
+};
+export declare function createVersionStream(options: StreamOptions): {
+    close: () => void;
+};
+export {};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@flagbearer/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "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"
+  },
+  "keywords": [
+    "feature-flags",
+    "flagbearer"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --target node --format esm --outdir ./dist && tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@flagbearer/evaluator": "workspace:*",
+    "@flagbearer/sdk-core": "workspace:*",
+    "@types/node": "^26.6.3"
+  }
+}