@feathq/js-sdk 0.1.1 → 0.2.0

package/README.md

@@ -29,7 +29,7 @@ import { FeatClient } from "@feathq/js-sdk";
 
 const client = new FeatClient({
   apiKey: process.env.FEAT_SERVER_KEY!,    // feat_sdk_…
-  dataPlaneUrl: "https://data.feat.so",
+  url: "https://data-01.feat.so",          // optional; this is the default
 });
 
 await client.ready();
@@ -52,7 +52,7 @@ Use a **server** API key (`feat_sdk_…`). Mobile and client-side keys are for t
 import { OpenFeature } from "@openfeature/server-sdk";
 import { FeatClient, FeatProvider } from "@feathq/js-sdk";
 
-const featClient = new FeatClient({ apiKey, dataPlaneUrl });
+const featClient = new FeatClient({ apiKey });
 await OpenFeature.setProviderAndWait(new FeatProvider(featClient));
 
 const client = OpenFeature.getClient();
@@ -64,9 +64,12 @@ const enabled = await client.getBooleanValue("checkout-v2", false, {
 ## How it works
 
 - The SDK fetches a per-environment **datafile** and keeps it in memory.
-- Polls every 30 s by default (configurable down to 5 s). ETag-aware: unchanged polls are 304s.
+- **Live streaming is on by default.** After the initial fetch the SDK opens a Server-Sent Events stream and applies each pushed datafile the moment it changes. Updates are applied in version order: a push is adopted only when its `version` is strictly newer than the one in memory.
+- A background poll keeps running as a safety net (slow while the stream is healthy). If the stream cannot establish or drops, the SDK falls back to polling at the normal interval and keeps retrying the stream with backoff.
+- Set `streaming: false` to rely on polling alone. Poll cadence is `pollIntervalMs` (default 30 s, floored at 5 s). ETag-aware: unchanged polls are 304s.
 - Evaluation is local; no per-flag network call.
-- `dataPlaneUrl` must use `https://` (the constructor rejects plaintext URLs except `http://localhost` for tests).
+- Call `client.close()` to tear down the stream and poll loop.
+- `url` must use `https://` if you override it (the constructor rejects plaintext URLs except `http://localhost` for tests).
 
 ## License
 

package/dist/index.cjs

@@ -5,31 +5,189 @@ var core = require('@openfeature/core');
 
 // src/client.ts
 
+// src/streaming.ts
+var STREAM_MAX_BYTES = 10 * 1024 * 1024;
+var SseHttpError = class extends Error {
+  constructor(status) {
+    super(`datafile stream failed: ${status}`);
+    this.status = status;
+    this.name = "SseHttpError";
+  }
+  status;
+};
+var fetchSseTransport = async (options) => {
+  const { url, headers, fetch: fetchImpl, signal, onOpen, onFrame, maxBytes } = options;
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: { Accept: "text/event-stream", ...headers },
+    signal
+  });
+  if (!res.ok) {
+    throw new SseHttpError(res.status);
+  }
+  if (!res.body) {
+    throw new Error("datafile stream returned no body");
+  }
+  onOpen?.();
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new SseParser(onFrame, maxBytes ?? STREAM_MAX_BYTES);
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parser.push(decoder.decode(value, { stream: true }));
+    }
+    parser.push(decoder.decode());
+    parser.flush();
+  } finally {
+    reader.releaseLock();
+  }
+};
+var SseParser = class {
+  constructor(onFrame, maxBytes = STREAM_MAX_BYTES) {
+    this.onFrame = onFrame;
+    this.maxBytes = maxBytes;
+  }
+  onFrame;
+  maxBytes;
+  buffer = "";
+  eventType = "";
+  dataLines = [];
+  dataBytes = 0;
+  lastId = null;
+  push(chunk) {
+    this.buffer += chunk;
+    if (this.buffer.length > this.maxBytes) {
+      throw new Error(`datafile stream line exceeds ${this.maxBytes} bytes`);
+    }
+    let newlineIndex;
+    while ((newlineIndex = this.indexOfLineBreak(this.buffer)) !== -1) {
+      if (this.buffer[newlineIndex] === "\r" && newlineIndex === this.buffer.length - 1) {
+        break;
+      }
+      const line = this.buffer.slice(0, newlineIndex);
+      this.buffer = this.buffer.slice(newlineIndex + this.lineBreakLength(newlineIndex));
+      this.handleLine(line);
+    }
+  }
+  // Leftover bytes are passed to handleLine but dispatch() is never called, so
+  // a frame missing its terminating blank line is discarded. That is
+  // spec-correct: an unterminated final frame is not delivered.
+  flush() {
+    if (this.buffer.endsWith("\r")) this.buffer = this.buffer.slice(0, -1);
+    if (this.buffer.length > 0) {
+      this.handleLine(this.buffer);
+      this.buffer = "";
+    }
+  }
+  indexOfLineBreak(s) {
+    const lf = s.indexOf("\n");
+    const cr = s.indexOf("\r");
+    if (lf === -1) return cr;
+    if (cr === -1) return lf;
+    return Math.min(lf, cr);
+  }
+  lineBreakLength(index) {
+    if (this.buffer[index] === "\r" && this.buffer[index + 1] === "\n") return 2;
+    return 1;
+  }
+  handleLine(line) {
+    if (line === "") {
+      this.dispatch();
+      return;
+    }
+    if (line.startsWith(":")) {
+      return;
+    }
+    const colon = line.indexOf(":");
+    let field;
+    let value;
+    if (colon === -1) {
+      field = line;
+      value = "";
+    } else {
+      field = line.slice(0, colon);
+      value = line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+    }
+    switch (field) {
+      case "event":
+        this.eventType = value;
+        break;
+      case "data":
+        this.dataBytes += value.length;
+        if (this.dataBytes > this.maxBytes) {
+          throw new Error(`datafile stream frame exceeds ${this.maxBytes} bytes`);
+        }
+        this.dataLines.push(value);
+        break;
+      case "id":
+        if (!value.includes("\0")) this.lastId = value;
+        break;
+    }
+  }
+  dispatch() {
+    if (this.dataLines.length === 0) {
+      this.eventType = "";
+      return;
+    }
+    const frame = {
+      event: this.eventType === "" ? "message" : this.eventType,
+      id: this.lastId,
+      data: this.dataLines.join("\n")
+    };
+    this.eventType = "";
+    this.dataLines = [];
+    this.dataBytes = 0;
+    this.onFrame(frame);
+  }
+};
+
 // src/version.ts
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.2.0";
 
 // src/client.ts
 var MIN_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var DEFAULT_SAFETY_NET_POLL_INTERVAL_MS = 15 * 60 * 1e3;
+var STREAM_BACKOFF_INITIAL_MS = 1e3;
+var STREAM_BACKOFF_MAX_MS = 3e4;
+var STREAM_HEALTHY_RESET_MS = 5e3;
 var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_URL = "https://data-01.feat.so";
 var USER_AGENT = `feat-sdk-js/${SDK_VERSION}`;
 var FeatClient = class {
   constructor(config) {
     this.config = config;
-    assertHttpsUrl(config.dataPlaneUrl);
+    this.url = config.url ?? DEFAULT_URL;
+    assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
     );
+    this.safetyNetPollIntervalMs = Math.max(
+      DEFAULT_SAFETY_NET_POLL_INTERVAL_MS,
+      this.pollIntervalMs
+    );
+    this.streamingEnabled = config.streaming ?? true;
+    this.streamTransport = config.streamTransport ?? fetchSseTransport;
   }
   config;
   datafile = null;
   etag = null;
-  timer = null;
+  pollTimer = null;
   readyPromise = null;
+  closed = false;
+  streamAbort = null;
+  streamConnected = false;
   fetchImpl;
   pollIntervalMs;
+  safetyNetPollIntervalMs;
+  url;
+  streamingEnabled;
+  streamTransport;
   async ready() {
     if (!this.readyPromise) {
       this.readyPromise = this.bootstrap();
@@ -53,26 +211,111 @@ var FeatClient = class {
     return result;
   }
   close() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
+    this.closed = true;
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.streamAbort) {
+      this.streamAbort.abort();
+      this.streamAbort = null;
     }
   }
   async bootstrap() {
     await this.fetchDatafile();
-    this.timer = setInterval(() => {
+    if (this.closed) return;
+    if (this.streamingEnabled) {
+      void this.runStreamLoop();
+    }
+    this.scheduleNextPoll();
+  }
+  // Self-scheduling poll. The interval depends on stream health: slow while
+  // streaming is healthy, normal otherwise (the fallback path).
+  scheduleNextPoll() {
+    if (this.closed) return;
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    const interval = this.streamingEnabled && this.streamConnected ? this.safetyNetPollIntervalMs : this.pollIntervalMs;
+    this.pollTimer = setTimeout(() => {
       void this.fetchDatafile().catch((err) => {
-        console.warn(
-          "feat: background poll failed:",
-          err instanceof Error ? err.message : String(err)
-        );
-      });
-    }, this.pollIntervalMs);
-    const t = this.timer;
-    t.unref?.();
+        warn("background poll failed:", err);
+      }).finally(() => this.scheduleNextPoll());
+    }, interval);
+    unref(this.pollTimer);
+  }
+  async runStreamLoop() {
+    const streamUrl = `${this.url.replace(/\/$/, "")}/sdk/v1/datafile/stream`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      "User-Agent": USER_AGENT
+    };
+    let backoff = STREAM_BACKOFF_INITIAL_MS;
+    while (!this.closed) {
+      const abort = new AbortController();
+      this.streamAbort = abort;
+      let connectedAt = null;
+      try {
+        await this.streamTransport({
+          url: streamUrl,
+          headers,
+          fetch: this.fetchImpl,
+          signal: abort.signal,
+          onOpen: () => {
+            connectedAt = Date.now();
+            this.setStreamConnected(true);
+          },
+          onFrame: (frame) => this.handleFrame(frame)
+        });
+        this.setStreamConnected(false);
+        if (connectedAt !== null && Date.now() - connectedAt >= STREAM_HEALTHY_RESET_MS) {
+          backoff = STREAM_BACKOFF_INITIAL_MS;
+        } else {
+          backoff = Math.min(backoff * 2, STREAM_BACKOFF_MAX_MS);
+        }
+      } catch (err) {
+        this.setStreamConnected(false);
+        if (this.closed || isAbortError(err)) break;
+        if (isTerminalStreamStatus(err)) {
+          warn("datafile stream rejected (auth); falling back to polling:", err);
+          break;
+        }
+        warn("datafile stream error:", err);
+        backoff = Math.min(backoff * 2, STREAM_BACKOFF_MAX_MS);
+      }
+      if (this.closed) break;
+      await abortableDelay(jitter(backoff), abort.signal);
+    }
+    this.setStreamConnected(false);
+  }
+  setStreamConnected(connected) {
+    if (this.streamConnected === connected) return;
+    this.streamConnected = connected;
+    this.scheduleNextPoll();
+  }
+  handleFrame(frame) {
+    if (frame.event !== "put") return;
+    let next;
+    try {
+      next = JSON.parse(frame.data);
+    } catch {
+      warn("ignoring stream frame with invalid datafile JSON");
+      return;
+    }
+    this.adoptDatafile(next);
+  }
+  // Adopt a datafile only if its version is strictly newer than what we
+  // hold. Equal or older versions are ignored so out-of-order pushes or a
+  // stale poll can never roll the datafile backwards. Returns true if
+  // adopted.
+  adoptDatafile(next) {
+    if (typeof next?.version !== "number") return false;
+    const current = this.datafile?.version ?? Number.NEGATIVE_INFINITY;
+    if (next.version <= current) return false;
+    this.datafile = next;
+    if (typeof next.etag === "string") this.etag = next.etag;
+    return true;
   }
   async fetchDatafile() {
-    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const url = `${this.url.replace(/\/$/, "")}/sdk/v1/datafile`;
     const headers = {
       Authorization: `Bearer ${this.config.apiKey}`,
       "User-Agent": USER_AGENT
@@ -89,11 +332,51 @@ var FeatClient = class {
       throw new Error("datafile exceeds maximum allowed size");
     }
     const next = await res.json();
-    this.datafile = next;
-    this.etag = res.headers.get("etag");
-    return true;
+    const adopted = this.adoptDatafile(next);
+    if (adopted) {
+      const headerEtag = res.headers.get("etag");
+      if (headerEtag) this.etag = headerEtag;
+    }
+    return adopted;
   }
 };
+function warn(message, err) {
+  if (err === void 0) {
+    console.warn(`feat: ${message}`);
+    return;
+  }
+  console.warn(`feat: ${message}`, err instanceof Error ? err.message : String(err));
+}
+function isAbortError(err) {
+  return err instanceof Error && err.name === "AbortError";
+}
+function isTerminalStreamStatus(err) {
+  return err instanceof SseHttpError && (err.status === 401 || err.status === 403);
+}
+function jitter(ms) {
+  return ms * (0.5 + Math.random() * 0.5);
+}
+function unref(timer) {
+  timer.unref?.();
+}
+function abortableDelay(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    unref(timer);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function assertHttpsUrl(url) {
   try {
     const u = new URL(url);
@@ -103,7 +386,7 @@ function assertHttpsUrl(url) {
     }
   } catch {
   }
-  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+  throw new Error("url must use https:// (http://localhost allowed for tests)");
 }
 var FeatProvider = class {
   constructor(client) {
@@ -200,3 +483,4 @@ Object.defineProperty(exports, "evaluate", {
 });
 exports.FeatClient = FeatClient;
 exports.FeatProvider = FeatProvider;
+exports.fetchSseTransport = fetchSseTransport;

package/dist/index.d.cts

@@ -4,26 +4,57 @@ import { ProviderMetadata, EvaluationContext, Logger, ResolutionDetails, JsonVal
 import { Provider, Hook, ProviderStatus } from '@openfeature/server-sdk';
 export { Datafile, Operator } from '@feathq/datafile-schema';
 
+interface SseFrame {
+    event: string;
+    id: string | null;
+    data: string;
+}
+interface SseTransportOptions {
+    url: string;
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+    signal: AbortSignal;
+    maxBytes?: number;
+    onOpen?: () => void;
+    onFrame: (frame: SseFrame) => void;
+}
+type SseTransport = (options: SseTransportOptions) => Promise<void>;
+declare const fetchSseTransport: SseTransport;
+
 interface FeatClientConfig {
     apiKey: string;
-    dataPlaneUrl: string;
+    url?: string;
     pollIntervalMs?: number;
+    streaming?: boolean;
+    streamTransport?: SseTransport;
     fetch?: typeof fetch;
 }
 declare class FeatClient {
     private readonly config;
     private datafile;
     private etag;
-    private timer;
+    private pollTimer;
     private readyPromise;
+    private closed;
+    private streamAbort;
+    private streamConnected;
     private readonly fetchImpl;
     private readonly pollIntervalMs;
+    private readonly safetyNetPollIntervalMs;
+    private readonly url;
+    private readonly streamingEnabled;
+    private readonly streamTransport;
     constructor(config: FeatClientConfig);
     ready(): Promise<void>;
     refresh(): Promise<boolean>;
     evaluate<T = unknown>(flagKey: string, defaultValue: T, context: EvalContext): Promise<EvaluationResult<T>>;
     close(): void;
     private bootstrap;
+    private scheduleNextPoll;
+    private runStreamLoop;
+    private setStreamConnected;
+    private handleFrame;
+    private adoptDatafile;
     private fetchDatafile;
 }
 
@@ -42,4 +73,4 @@ declare class FeatProvider implements Provider {
     resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<T>>;
 }
 
-export { FeatClient, type FeatClientConfig, FeatProvider };
+export { FeatClient, type FeatClientConfig, FeatProvider, type SseFrame, type SseTransport, type SseTransportOptions, fetchSseTransport };

package/dist/index.d.ts

@@ -4,26 +4,57 @@ import { ProviderMetadata, EvaluationContext, Logger, ResolutionDetails, JsonVal
 import { Provider, Hook, ProviderStatus } from '@openfeature/server-sdk';
 export { Datafile, Operator } from '@feathq/datafile-schema';
 
+interface SseFrame {
+    event: string;
+    id: string | null;
+    data: string;
+}
+interface SseTransportOptions {
+    url: string;
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+    signal: AbortSignal;
+    maxBytes?: number;
+    onOpen?: () => void;
+    onFrame: (frame: SseFrame) => void;
+}
+type SseTransport = (options: SseTransportOptions) => Promise<void>;
+declare const fetchSseTransport: SseTransport;
+
 interface FeatClientConfig {
     apiKey: string;
-    dataPlaneUrl: string;
+    url?: string;
     pollIntervalMs?: number;
+    streaming?: boolean;
+    streamTransport?: SseTransport;
     fetch?: typeof fetch;
 }
 declare class FeatClient {
     private readonly config;
     private datafile;
     private etag;
-    private timer;
+    private pollTimer;
     private readyPromise;
+    private closed;
+    private streamAbort;
+    private streamConnected;
     private readonly fetchImpl;
     private readonly pollIntervalMs;
+    private readonly safetyNetPollIntervalMs;
+    private readonly url;
+    private readonly streamingEnabled;
+    private readonly streamTransport;
     constructor(config: FeatClientConfig);
     ready(): Promise<void>;
     refresh(): Promise<boolean>;
     evaluate<T = unknown>(flagKey: string, defaultValue: T, context: EvalContext): Promise<EvaluationResult<T>>;
     close(): void;
     private bootstrap;
+    private scheduleNextPoll;
+    private runStreamLoop;
+    private setStreamConnected;
+    private handleFrame;
+    private adoptDatafile;
     private fetchDatafile;
 }
 
@@ -42,4 +73,4 @@ declare class FeatProvider implements Provider {
     resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<T>>;
 }
 
-export { FeatClient, type FeatClientConfig, FeatProvider };
+export { FeatClient, type FeatClientConfig, FeatProvider, type SseFrame, type SseTransport, type SseTransportOptions, fetchSseTransport };

package/dist/index.js

@@ -4,31 +4,189 @@ import { ErrorCode } from '@openfeature/core';
 
 // src/client.ts
 
+// src/streaming.ts
+var STREAM_MAX_BYTES = 10 * 1024 * 1024;
+var SseHttpError = class extends Error {
+  constructor(status) {
+    super(`datafile stream failed: ${status}`);
+    this.status = status;
+    this.name = "SseHttpError";
+  }
+  status;
+};
+var fetchSseTransport = async (options) => {
+  const { url, headers, fetch: fetchImpl, signal, onOpen, onFrame, maxBytes } = options;
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: { Accept: "text/event-stream", ...headers },
+    signal
+  });
+  if (!res.ok) {
+    throw new SseHttpError(res.status);
+  }
+  if (!res.body) {
+    throw new Error("datafile stream returned no body");
+  }
+  onOpen?.();
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new SseParser(onFrame, maxBytes ?? STREAM_MAX_BYTES);
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parser.push(decoder.decode(value, { stream: true }));
+    }
+    parser.push(decoder.decode());
+    parser.flush();
+  } finally {
+    reader.releaseLock();
+  }
+};
+var SseParser = class {
+  constructor(onFrame, maxBytes = STREAM_MAX_BYTES) {
+    this.onFrame = onFrame;
+    this.maxBytes = maxBytes;
+  }
+  onFrame;
+  maxBytes;
+  buffer = "";
+  eventType = "";
+  dataLines = [];
+  dataBytes = 0;
+  lastId = null;
+  push(chunk) {
+    this.buffer += chunk;
+    if (this.buffer.length > this.maxBytes) {
+      throw new Error(`datafile stream line exceeds ${this.maxBytes} bytes`);
+    }
+    let newlineIndex;
+    while ((newlineIndex = this.indexOfLineBreak(this.buffer)) !== -1) {
+      if (this.buffer[newlineIndex] === "\r" && newlineIndex === this.buffer.length - 1) {
+        break;
+      }
+      const line = this.buffer.slice(0, newlineIndex);
+      this.buffer = this.buffer.slice(newlineIndex + this.lineBreakLength(newlineIndex));
+      this.handleLine(line);
+    }
+  }
+  // Leftover bytes are passed to handleLine but dispatch() is never called, so
+  // a frame missing its terminating blank line is discarded. That is
+  // spec-correct: an unterminated final frame is not delivered.
+  flush() {
+    if (this.buffer.endsWith("\r")) this.buffer = this.buffer.slice(0, -1);
+    if (this.buffer.length > 0) {
+      this.handleLine(this.buffer);
+      this.buffer = "";
+    }
+  }
+  indexOfLineBreak(s) {
+    const lf = s.indexOf("\n");
+    const cr = s.indexOf("\r");
+    if (lf === -1) return cr;
+    if (cr === -1) return lf;
+    return Math.min(lf, cr);
+  }
+  lineBreakLength(index) {
+    if (this.buffer[index] === "\r" && this.buffer[index + 1] === "\n") return 2;
+    return 1;
+  }
+  handleLine(line) {
+    if (line === "") {
+      this.dispatch();
+      return;
+    }
+    if (line.startsWith(":")) {
+      return;
+    }
+    const colon = line.indexOf(":");
+    let field;
+    let value;
+    if (colon === -1) {
+      field = line;
+      value = "";
+    } else {
+      field = line.slice(0, colon);
+      value = line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+    }
+    switch (field) {
+      case "event":
+        this.eventType = value;
+        break;
+      case "data":
+        this.dataBytes += value.length;
+        if (this.dataBytes > this.maxBytes) {
+          throw new Error(`datafile stream frame exceeds ${this.maxBytes} bytes`);
+        }
+        this.dataLines.push(value);
+        break;
+      case "id":
+        if (!value.includes("\0")) this.lastId = value;
+        break;
+    }
+  }
+  dispatch() {
+    if (this.dataLines.length === 0) {
+      this.eventType = "";
+      return;
+    }
+    const frame = {
+      event: this.eventType === "" ? "message" : this.eventType,
+      id: this.lastId,
+      data: this.dataLines.join("\n")
+    };
+    this.eventType = "";
+    this.dataLines = [];
+    this.dataBytes = 0;
+    this.onFrame(frame);
+  }
+};
+
 // src/version.ts
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.2.0";
 
 // src/client.ts
 var MIN_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var DEFAULT_SAFETY_NET_POLL_INTERVAL_MS = 15 * 60 * 1e3;
+var STREAM_BACKOFF_INITIAL_MS = 1e3;
+var STREAM_BACKOFF_MAX_MS = 3e4;
+var STREAM_HEALTHY_RESET_MS = 5e3;
 var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_URL = "https://data-01.feat.so";
 var USER_AGENT = `feat-sdk-js/${SDK_VERSION}`;
 var FeatClient = class {
   constructor(config) {
     this.config = config;
-    assertHttpsUrl(config.dataPlaneUrl);
+    this.url = config.url ?? DEFAULT_URL;
+    assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
     );
+    this.safetyNetPollIntervalMs = Math.max(
+      DEFAULT_SAFETY_NET_POLL_INTERVAL_MS,
+      this.pollIntervalMs
+    );
+    this.streamingEnabled = config.streaming ?? true;
+    this.streamTransport = config.streamTransport ?? fetchSseTransport;
   }
   config;
   datafile = null;
   etag = null;
-  timer = null;
+  pollTimer = null;
   readyPromise = null;
+  closed = false;
+  streamAbort = null;
+  streamConnected = false;
   fetchImpl;
   pollIntervalMs;
+  safetyNetPollIntervalMs;
+  url;
+  streamingEnabled;
+  streamTransport;
   async ready() {
     if (!this.readyPromise) {
       this.readyPromise = this.bootstrap();
@@ -52,26 +210,111 @@ var FeatClient = class {
     return result;
   }
   close() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
+    this.closed = true;
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.streamAbort) {
+      this.streamAbort.abort();
+      this.streamAbort = null;
     }
   }
   async bootstrap() {
     await this.fetchDatafile();
-    this.timer = setInterval(() => {
+    if (this.closed) return;
+    if (this.streamingEnabled) {
+      void this.runStreamLoop();
+    }
+    this.scheduleNextPoll();
+  }
+  // Self-scheduling poll. The interval depends on stream health: slow while
+  // streaming is healthy, normal otherwise (the fallback path).
+  scheduleNextPoll() {
+    if (this.closed) return;
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    const interval = this.streamingEnabled && this.streamConnected ? this.safetyNetPollIntervalMs : this.pollIntervalMs;
+    this.pollTimer = setTimeout(() => {
       void this.fetchDatafile().catch((err) => {
-        console.warn(
-          "feat: background poll failed:",
-          err instanceof Error ? err.message : String(err)
-        );
-      });
-    }, this.pollIntervalMs);
-    const t = this.timer;
-    t.unref?.();
+        warn("background poll failed:", err);
+      }).finally(() => this.scheduleNextPoll());
+    }, interval);
+    unref(this.pollTimer);
+  }
+  async runStreamLoop() {
+    const streamUrl = `${this.url.replace(/\/$/, "")}/sdk/v1/datafile/stream`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      "User-Agent": USER_AGENT
+    };
+    let backoff = STREAM_BACKOFF_INITIAL_MS;
+    while (!this.closed) {
+      const abort = new AbortController();
+      this.streamAbort = abort;
+      let connectedAt = null;
+      try {
+        await this.streamTransport({
+          url: streamUrl,
+          headers,
+          fetch: this.fetchImpl,
+          signal: abort.signal,
+          onOpen: () => {
+            connectedAt = Date.now();
+            this.setStreamConnected(true);
+          },
+          onFrame: (frame) => this.handleFrame(frame)
+        });
+        this.setStreamConnected(false);
+        if (connectedAt !== null && Date.now() - connectedAt >= STREAM_HEALTHY_RESET_MS) {
+          backoff = STREAM_BACKOFF_INITIAL_MS;
+        } else {
+          backoff = Math.min(backoff * 2, STREAM_BACKOFF_MAX_MS);
+        }
+      } catch (err) {
+        this.setStreamConnected(false);
+        if (this.closed || isAbortError(err)) break;
+        if (isTerminalStreamStatus(err)) {
+          warn("datafile stream rejected (auth); falling back to polling:", err);
+          break;
+        }
+        warn("datafile stream error:", err);
+        backoff = Math.min(backoff * 2, STREAM_BACKOFF_MAX_MS);
+      }
+      if (this.closed) break;
+      await abortableDelay(jitter(backoff), abort.signal);
+    }
+    this.setStreamConnected(false);
+  }
+  setStreamConnected(connected) {
+    if (this.streamConnected === connected) return;
+    this.streamConnected = connected;
+    this.scheduleNextPoll();
+  }
+  handleFrame(frame) {
+    if (frame.event !== "put") return;
+    let next;
+    try {
+      next = JSON.parse(frame.data);
+    } catch {
+      warn("ignoring stream frame with invalid datafile JSON");
+      return;
+    }
+    this.adoptDatafile(next);
+  }
+  // Adopt a datafile only if its version is strictly newer than what we
+  // hold. Equal or older versions are ignored so out-of-order pushes or a
+  // stale poll can never roll the datafile backwards. Returns true if
+  // adopted.
+  adoptDatafile(next) {
+    if (typeof next?.version !== "number") return false;
+    const current = this.datafile?.version ?? Number.NEGATIVE_INFINITY;
+    if (next.version <= current) return false;
+    this.datafile = next;
+    if (typeof next.etag === "string") this.etag = next.etag;
+    return true;
   }
   async fetchDatafile() {
-    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const url = `${this.url.replace(/\/$/, "")}/sdk/v1/datafile`;
     const headers = {
       Authorization: `Bearer ${this.config.apiKey}`,
       "User-Agent": USER_AGENT
@@ -88,11 +331,51 @@ var FeatClient = class {
       throw new Error("datafile exceeds maximum allowed size");
     }
     const next = await res.json();
-    this.datafile = next;
-    this.etag = res.headers.get("etag");
-    return true;
+    const adopted = this.adoptDatafile(next);
+    if (adopted) {
+      const headerEtag = res.headers.get("etag");
+      if (headerEtag) this.etag = headerEtag;
+    }
+    return adopted;
   }
 };
+function warn(message, err) {
+  if (err === void 0) {
+    console.warn(`feat: ${message}`);
+    return;
+  }
+  console.warn(`feat: ${message}`, err instanceof Error ? err.message : String(err));
+}
+function isAbortError(err) {
+  return err instanceof Error && err.name === "AbortError";
+}
+function isTerminalStreamStatus(err) {
+  return err instanceof SseHttpError && (err.status === 401 || err.status === 403);
+}
+function jitter(ms) {
+  return ms * (0.5 + Math.random() * 0.5);
+}
+function unref(timer) {
+  timer.unref?.();
+}
+function abortableDelay(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    unref(timer);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function assertHttpsUrl(url) {
   try {
     const u = new URL(url);
@@ -102,7 +385,7 @@ function assertHttpsUrl(url) {
     }
   } catch {
   }
-  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+  throw new Error("url must use https:// (http://localhost allowed for tests)");
 }
 var FeatProvider = class {
   constructor(client) {
@@ -193,4 +476,4 @@ function toEvalContext(ctx) {
   return out;
 }
 
-export { FeatClient, FeatProvider };
+export { FeatClient, FeatProvider, fetchSseTransport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feathq/js-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "feat feature-flag SDK for JavaScript and TypeScript (server-side, OpenFeature provider)",
   "keywords": [
     "feature-flags",
@@ -48,6 +48,7 @@
     "@feathq/feat-eval": "^0.1.0"
   },
   "peerDependencies": {
+    "@openfeature/core": "^1.0.0",
     "@openfeature/server-sdk": "^1.0.0"
   },
   "devDependencies": {