@feathq/web-sdk 0.1.1 → 0.3.0

package/README.md

@@ -27,7 +27,7 @@ import { FeatWebClient } from "@feathq/web-sdk";
 
 const client = new FeatWebClient({
   apiKey: "feat_cs_…",                       // client-side ID key
-  dataPlaneUrl: "https://data.feat.so",
+  url: "https://data-01.feat.so",            // optional; this is the default
   anonymous: { storage: "localStorage" },    // optional: auto-mint a stable anonymous user
   cache: { storage: "localStorage" },        // optional: warm cache across page loads
 });
@@ -55,6 +55,19 @@ await client.setContext({
 
 `change` events fire per flag whose evaluated value flipped, after either a context change or a datafile refresh.
 
+## Live streaming
+
+The SDK can hold a Server-Sent Events connection so datafile changes land near-instantly instead of waiting for the next poll. On each update the server pushes the full datafile; the SDK adopts it in version order (no extra HTTP request) and fires `change` events.
+
+By default streaming **follows your subscription**: the stream opens when the first `change` listener is added and closes when the last one is removed, so a page that never listens pays nothing. Override with the `streaming` option:
+
+```ts
+new FeatWebClient({ apiKey, streaming: true });  // always stream, opens on ready
+new FeatWebClient({ apiKey, streaming: false }); // never stream
+```
+
+Polling stays on as a safety net in every mode, so a dropped stream still self-heals.
+
 ## OpenFeature
 
 ```ts
@@ -62,7 +75,7 @@ import { OpenFeature } from "@openfeature/web-sdk";
 import { FeatWebClient } from "@feathq/web-sdk";
 import { FeatWebProvider } from "@feathq/openfeature-web";
 
-const featClient = new FeatWebClient({ apiKey, dataPlaneUrl });
+const featClient = new FeatWebClient({ apiKey });
 await OpenFeature.setProviderAndWait(new FeatWebProvider(featClient));
 await OpenFeature.setContext({ targetingKey: "user-123" });
 
@@ -74,16 +87,17 @@ const enabled = OpenFeature.getClient().getBooleanValue("checkout-v2", false);
 Fetch the datafile on the server and pass it through to the client to skip the first round trip:
 
 ```ts
-new FeatWebClient({ apiKey, dataPlaneUrl, bootstrap: serverProvidedDatafile });
+new FeatWebClient({ apiKey, bootstrap: serverProvidedDatafile });
 ```
 
 ## How it works
 
 - Pre-evaluates every flag against the current context into a `Map` so `getValue` is synchronous.
 - Polls every 30 s by default; pauses while the tab is hidden and force-refreshes on visibility restore. Floored at 5 s.
+- Optional Server-Sent Events stream for near-instant updates (see [Live streaming](#live-streaming)); polling remains the fallback.
 - Cross-tab `BroadcastChannel` sync: when one tab fetches a new datafile, sibling tabs adopt it without their own network call.
 - 304-aware via `ETag` / `If-None-Match`.
-- `dataPlaneUrl` must use `https://` (the constructor rejects plaintext URLs except `http://localhost` for tests).
+- `url` must use `https://` if you override it (the constructor rejects plaintext URLs except `http://localhost` for tests).
 
 ## Security notes
 

package/dist/index.cjs

@@ -130,6 +130,112 @@ var Emitter = class {
   }
 };
 
+// src/events.ts
+var DEFAULT_EVENTS_FLUSH_INTERVAL_MS = 6e4;
+var MIN_EVENTS_FLUSH_INTERVAL_MS = 5e3;
+var MAX_BATCH = 2e3;
+var MAX_BUFFERED_PAIRS = 1e5;
+function extractContextPairs(context) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (kind, key) => {
+    const id = `${kind} ${key}`;
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push({ kind, key });
+  };
+  const userObj = context.user;
+  if (userObj && typeof userObj === "object" && typeof userObj.key === "string") {
+    push("user", userObj.key);
+  } else if (typeof context.targetingKey === "string") {
+    push("user", context.targetingKey);
+  }
+  for (const [kind, value] of Object.entries(context)) {
+    if (kind === "targetingKey" || kind === "user") continue;
+    if (value && typeof value === "object" && typeof value.key === "string") {
+      push(kind, value.key);
+    }
+  }
+  return out;
+}
+var EventSummarizer = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.pending = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.inFlight = false;
+    this.visibilityHandler = null;
+    this.endpoint = `${opts.url.replace(/\/$/, "")}/sdk/v1/events`;
+  }
+  // Synchronous, never throws: safe to call inline from setContext().
+  record(context) {
+    for (const pair of extractContextPairs(context)) {
+      const id = `${pair.kind} ${pair.key}`;
+      if (this.pending.has(id)) continue;
+      if (this.pending.size >= MAX_BUFFERED_PAIRS) return;
+      this.pending.set(id, pair);
+    }
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.opts.flushIntervalMs);
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") void this.flush(true);
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+  async flush(keepalive = false) {
+    if (this.inFlight || this.pending.size === 0) return;
+    const batch = [...this.pending.values()].slice(0, MAX_BATCH);
+    for (const c of batch) this.pending.delete(`${c.kind} ${c.key}`);
+    this.inFlight = true;
+    try {
+      const res = await this.opts.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.opts.apiKey}`,
+          "Content-Type": "application/json",
+          "X-Feat-Sdk": this.opts.sdkHeader
+        },
+        body: JSON.stringify({ contexts: batch }),
+        keepalive
+      });
+      if (!res.ok && (res.status >= 500 || res.status === 429)) {
+        this.requeue(batch);
+      }
+    } catch {
+      this.requeue(batch);
+    } finally {
+      this.inFlight = false;
+    }
+  }
+  // Detach the page-hide hook, stop the timer, and make a best-effort final
+  // flush. Fire-and-forget: the flush is not awaited so close() stays sync.
+  close() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    void this.flush(true);
+  }
+  requeue(batch) {
+    for (const c of batch) {
+      const id = `${c.kind} ${c.key}`;
+      if (this.pending.has(id)) continue;
+      if (this.pending.size >= MAX_BUFFERED_PAIRS) return;
+      this.pending.set(id, c);
+    }
+  }
+};
+
 // src/persistence.ts
 var STORAGE_KEY2 = "feat:datafile";
 function loadCachedDatafile(config) {
@@ -161,14 +267,62 @@ function hasLocalStorage2() {
   }
 }
 
+// src/streaming.ts
+var EVENT_SOURCE_CLOSED = 2;
+var DatafileStream = class {
+  constructor(options) {
+    this.source = null;
+    this.warned = false;
+    this.options = options;
+  }
+  open() {
+    if (this.source) return;
+    const base = this.options.url.replace(/\/$/, "");
+    const streamUrl = `${base}/sdk/v1/datafile/stream?key=${encodeURIComponent(
+      this.options.apiKey
+    )}`;
+    const source = new this.options.eventSourceCtor(streamUrl);
+    this.source = source;
+    source.addEventListener("put", (ev) => {
+      const datafile = parsePut(ev.data);
+      if (datafile) this.options.onPut(datafile);
+    });
+    source.addEventListener("error", () => {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("feat: datafile stream error; falling back to polling");
+      }
+      if (this.source && this.source.readyState === EVENT_SOURCE_CLOSED) {
+        this.close();
+      }
+    });
+  }
+  close() {
+    this.source?.close();
+    this.source = null;
+  }
+};
+function parsePut(data) {
+  if (typeof data !== "string") return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && typeof parsed.version === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+
 // src/version.ts
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var CLIENT_SIDE_PREFIX = "feat_cs_";
 var MIN_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
 var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_URL = "https://data-01.feat.so";
 var FeatWebClient = class {
   constructor(config) {
     this.config = config;
@@ -181,23 +335,44 @@ var FeatWebClient = class {
     this.visibilityHandler = null;
     this.emitter = new Emitter();
     this.broadcast = null;
+    this.stream = null;
+    // The set of live `change` listeners. The streaming-follows-subscription
+    // policy keys off whether this is non-empty; tracking the listeners (rather
+    // than a counter) keeps the refcount correct whether the caller unsubscribes
+    // via the returned disposer or via off().
+    this.changeListeners = /* @__PURE__ */ new Set();
+    this.started = false;
+    this.warnedNoEventSource = false;
     this.closed = false;
     if (!config.apiKey.startsWith(CLIENT_SIDE_PREFIX)) {
       throw new Error(
         `FeatWebClient requires a client_side_id key (prefix "${CLIENT_SIDE_PREFIX}"). Server and mobile keys must never ship in browser code.`
       );
     }
-    assertHttpsUrl(config.dataPlaneUrl);
+    this.url = config.url ?? DEFAULT_URL;
+    assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.eventSourceCtor = config.eventSource ?? (typeof globalThis.EventSource !== "undefined" ? globalThis.EventSource : void 0);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
     );
+    this.summarizer = config.events === false ? null : new EventSummarizer({
+      url: this.url,
+      apiKey: config.apiKey,
+      fetchImpl: this.fetchImpl,
+      sdkHeader: `web/${SDK_VERSION}`,
+      flushIntervalMs: Math.max(
+        config.eventsFlushIntervalMs ?? DEFAULT_EVENTS_FLUSH_INTERVAL_MS,
+        MIN_EVENTS_FLUSH_INTERVAL_MS
+      )
+    });
     if (config.context) {
       this.context = config.context;
     } else if (config.anonymous) {
       this.context = buildAnonymousContext(config.anonymous);
     }
+    if (this.context) this.summarizer?.record(this.context);
     if (config.bootstrap) {
       this.datafile = config.bootstrap;
       this.etag = config.bootstrap.etag;
@@ -227,6 +402,7 @@ var FeatWebClient = class {
   // OpenFeature's `onContextChange` lifecycle hook bridges to this.
   async setContext(context) {
     this.context = context;
+    this.summarizer?.record(context);
     await this.recomputeCache();
   }
   currentContext() {
@@ -269,10 +445,17 @@ var FeatWebClient = class {
     return new Map(this.cache);
   }
   on(event, listener) {
-    return this.emitter.on(event, listener);
+    if (event !== "change") return this.emitter.on(event, listener);
+    this.emitter.on(event, listener);
+    this.changeListeners.add(listener);
+    this.maybeUpdateStream();
+    return () => this.off(event, listener);
   }
   off(event, listener) {
     this.emitter.off(event, listener);
+    if (event === "change" && this.changeListeners.delete(listener)) {
+      this.maybeUpdateStream();
+    }
   }
   // Force a one-shot fetch. Returns true if the in-memory datafile changed.
   async refresh() {
@@ -287,12 +470,16 @@ var FeatWebClient = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.stream?.close();
+    this.stream = null;
+    this.changeListeners.clear();
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
     }
     this.broadcast?.close();
     this.broadcast = null;
+    this.summarizer?.close();
     this.emitter.removeAll();
   }
   async bootstrap() {
@@ -302,6 +489,9 @@ var FeatWebClient = class {
       if (this.closed) return;
       this.startPolling();
       this.attachVisibilityHandler();
+      this.summarizer?.start();
+      this.started = true;
+      this.maybeUpdateStream();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -334,7 +524,7 @@ var FeatWebClient = class {
     document.addEventListener("visibilitychange", this.visibilityHandler);
   }
   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}`,
       // Custom header because browsers forbid setting User-Agent on fetch.
@@ -362,18 +552,73 @@ var FeatWebClient = class {
     await this.recomputeCache();
     return true;
   }
-  // Sibling-tab handler. Only adopt if the broadcast carries a newer
-  // version (or we have nothing); old broadcasts can race with our own
-  // fresh fetches and we don't want to regress.
+  // Sibling-tab handler. Adopt without republishing: this is the receive end
+  // of a BroadcastChannel message, so echoing it back would loop.
   async adoptFromBroadcast(datafile, etag) {
+    await this.adoptDatafile(datafile, etag, false);
+  }
+  // Version-guarded adopt for datafiles that arrive outside the fetch path
+  // (sibling-tab broadcast, SSE `put`). Only adopt a strictly newer version so
+  // an old broadcast or out-of-order frame can't regress us; the same guard
+  // stops a republished put from looping back through a sibling tab. When
+  // `publish` is set we mirror the fetch path and rebroadcast so sibling tabs
+  // stay fresh without their own network call.
+  async adoptDatafile(datafile, etag, publish) {
+    if (this.closed) return;
     if (this.datafile && datafile.version <= this.datafile.version) return;
     this.datafile = datafile;
     this.etag = etag;
     if (this.config.cache) {
       saveCachedDatafile(this.config.cache, { datafile, etag });
     }
+    if (publish) this.broadcast?.publish(datafile, etag);
     await this.recomputeCache();
   }
+  // Reconcile the SSE connection with the current streaming policy. Called
+  // whenever an input to that policy changes: ready, a `change` (un)subscribe,
+  // or close.
+  maybeUpdateStream() {
+    if (this.closed) return;
+    const want = this.wantsStream();
+    if (want) {
+      this.openStream();
+    } else if (this.stream) {
+      this.stream.close();
+      this.stream = null;
+    }
+  }
+  wantsStream() {
+    if (this.config.streaming === false) return false;
+    if (this.config.streaming === true) return this.started;
+    return this.changeListeners.size > 0;
+  }
+  openStream() {
+    if (!this.eventSourceCtor) {
+      if (!this.warnedNoEventSource) {
+        this.warnedNoEventSource = true;
+        console.warn("feat: streaming requested but EventSource is unavailable; using polling");
+      }
+      return;
+    }
+    if (!this.stream) {
+      this.stream = new DatafileStream({
+        url: this.url,
+        apiKey: this.config.apiKey,
+        eventSourceCtor: this.eventSourceCtor,
+        // A `put` carries the full datafile; reuse the version-ordered adopt
+        // path so a duplicate or out-of-order frame is ignored and the cache
+        // recomputes (firing `change`) only on a strictly newer version. Like
+        // the fetch path, a stream-adopted put republishes on the
+        // BroadcastChannel so sibling tabs stay fresh without their own fetch.
+        onPut: (datafile) => {
+          void this.adoptDatafile(datafile, datafile.etag, true).catch((err) => {
+            console.warn("feat: streamed datafile update failed:", messageOf(err));
+          });
+        }
+      });
+    }
+    this.stream.open();
+  }
   // Pre-evaluate every flag in the datafile against the current context
   // and diff against the previous cache. Skips silently if datafile or
   // context is missing; the caller will recompute as soon as both land.
@@ -436,11 +681,11 @@ 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)");
 }
 
 // src/index.ts
-var SDK_VERSION2 = "0.1.0";
+var SDK_VERSION2 = "0.3.0";
 
 exports.FeatWebClient = FeatWebClient;
 exports.SDK_VERSION = SDK_VERSION2;

package/dist/index.d.cts

@@ -13,16 +13,27 @@ interface DatafileCacheConfig {
     storage: DatafileCacheStorage;
 }
 
+interface EventSourceLike {
+    readyState: number;
+    addEventListener(type: string, listener: (ev: MessageEvent) => void): void;
+    close(): void;
+}
+type EventSourceConstructor = new (url: string, init?: EventSourceInit) => EventSourceLike;
+
 interface FeatWebClientConfig {
     apiKey: string;
-    dataPlaneUrl: string;
+    url?: string;
     context?: EvalContext;
     anonymous?: AnonymousConfig;
     bootstrap?: Datafile;
     cache?: DatafileCacheConfig;
     pollIntervalMs?: number;
     crossTabSync?: boolean;
+    events?: boolean;
+    eventsFlushIntervalMs?: number;
     fetch?: typeof fetch;
+    streaming?: boolean;
+    eventSource?: EventSourceConstructor;
 }
 interface ChangeEvent {
     flagKey: string;
@@ -49,8 +60,15 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private stream;
+    private changeListeners;
+    private started;
+    private warnedNoEventSource;
+    private readonly summarizer;
     private readonly fetchImpl;
+    private readonly eventSourceCtor;
     private readonly pollIntervalMs;
+    private readonly url;
     private closed;
     constructor(config: FeatWebClientConfig);
     ready(): Promise<void>;
@@ -73,9 +91,13 @@ declare class FeatWebClient {
     private attachVisibilityHandler;
     private fetchDatafile;
     private adoptFromBroadcast;
+    private adoptDatafile;
+    private maybeUpdateStream;
+    private wantsStream;
+    private openStream;
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.3.0";
 
-export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };
+export { type ChangeEvent, type EventSourceConstructor, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.d.ts

@@ -13,16 +13,27 @@ interface DatafileCacheConfig {
     storage: DatafileCacheStorage;
 }
 
+interface EventSourceLike {
+    readyState: number;
+    addEventListener(type: string, listener: (ev: MessageEvent) => void): void;
+    close(): void;
+}
+type EventSourceConstructor = new (url: string, init?: EventSourceInit) => EventSourceLike;
+
 interface FeatWebClientConfig {
     apiKey: string;
-    dataPlaneUrl: string;
+    url?: string;
     context?: EvalContext;
     anonymous?: AnonymousConfig;
     bootstrap?: Datafile;
     cache?: DatafileCacheConfig;
     pollIntervalMs?: number;
     crossTabSync?: boolean;
+    events?: boolean;
+    eventsFlushIntervalMs?: number;
     fetch?: typeof fetch;
+    streaming?: boolean;
+    eventSource?: EventSourceConstructor;
 }
 interface ChangeEvent {
     flagKey: string;
@@ -49,8 +60,15 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private stream;
+    private changeListeners;
+    private started;
+    private warnedNoEventSource;
+    private readonly summarizer;
     private readonly fetchImpl;
+    private readonly eventSourceCtor;
     private readonly pollIntervalMs;
+    private readonly url;
     private closed;
     constructor(config: FeatWebClientConfig);
     ready(): Promise<void>;
@@ -73,9 +91,13 @@ declare class FeatWebClient {
     private attachVisibilityHandler;
     private fetchDatafile;
     private adoptFromBroadcast;
+    private adoptDatafile;
+    private maybeUpdateStream;
+    private wantsStream;
+    private openStream;
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.3.0";
 
-export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };
+export { type ChangeEvent, type EventSourceConstructor, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.js

@@ -128,6 +128,112 @@ var Emitter = class {
   }
 };
 
+// src/events.ts
+var DEFAULT_EVENTS_FLUSH_INTERVAL_MS = 6e4;
+var MIN_EVENTS_FLUSH_INTERVAL_MS = 5e3;
+var MAX_BATCH = 2e3;
+var MAX_BUFFERED_PAIRS = 1e5;
+function extractContextPairs(context) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (kind, key) => {
+    const id = `${kind} ${key}`;
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push({ kind, key });
+  };
+  const userObj = context.user;
+  if (userObj && typeof userObj === "object" && typeof userObj.key === "string") {
+    push("user", userObj.key);
+  } else if (typeof context.targetingKey === "string") {
+    push("user", context.targetingKey);
+  }
+  for (const [kind, value] of Object.entries(context)) {
+    if (kind === "targetingKey" || kind === "user") continue;
+    if (value && typeof value === "object" && typeof value.key === "string") {
+      push(kind, value.key);
+    }
+  }
+  return out;
+}
+var EventSummarizer = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.pending = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.inFlight = false;
+    this.visibilityHandler = null;
+    this.endpoint = `${opts.url.replace(/\/$/, "")}/sdk/v1/events`;
+  }
+  // Synchronous, never throws: safe to call inline from setContext().
+  record(context) {
+    for (const pair of extractContextPairs(context)) {
+      const id = `${pair.kind} ${pair.key}`;
+      if (this.pending.has(id)) continue;
+      if (this.pending.size >= MAX_BUFFERED_PAIRS) return;
+      this.pending.set(id, pair);
+    }
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.opts.flushIntervalMs);
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") void this.flush(true);
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+  async flush(keepalive = false) {
+    if (this.inFlight || this.pending.size === 0) return;
+    const batch = [...this.pending.values()].slice(0, MAX_BATCH);
+    for (const c of batch) this.pending.delete(`${c.kind} ${c.key}`);
+    this.inFlight = true;
+    try {
+      const res = await this.opts.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.opts.apiKey}`,
+          "Content-Type": "application/json",
+          "X-Feat-Sdk": this.opts.sdkHeader
+        },
+        body: JSON.stringify({ contexts: batch }),
+        keepalive
+      });
+      if (!res.ok && (res.status >= 500 || res.status === 429)) {
+        this.requeue(batch);
+      }
+    } catch {
+      this.requeue(batch);
+    } finally {
+      this.inFlight = false;
+    }
+  }
+  // Detach the page-hide hook, stop the timer, and make a best-effort final
+  // flush. Fire-and-forget: the flush is not awaited so close() stays sync.
+  close() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    void this.flush(true);
+  }
+  requeue(batch) {
+    for (const c of batch) {
+      const id = `${c.kind} ${c.key}`;
+      if (this.pending.has(id)) continue;
+      if (this.pending.size >= MAX_BUFFERED_PAIRS) return;
+      this.pending.set(id, c);
+    }
+  }
+};
+
 // src/persistence.ts
 var STORAGE_KEY2 = "feat:datafile";
 function loadCachedDatafile(config) {
@@ -159,14 +265,62 @@ function hasLocalStorage2() {
   }
 }
 
+// src/streaming.ts
+var EVENT_SOURCE_CLOSED = 2;
+var DatafileStream = class {
+  constructor(options) {
+    this.source = null;
+    this.warned = false;
+    this.options = options;
+  }
+  open() {
+    if (this.source) return;
+    const base = this.options.url.replace(/\/$/, "");
+    const streamUrl = `${base}/sdk/v1/datafile/stream?key=${encodeURIComponent(
+      this.options.apiKey
+    )}`;
+    const source = new this.options.eventSourceCtor(streamUrl);
+    this.source = source;
+    source.addEventListener("put", (ev) => {
+      const datafile = parsePut(ev.data);
+      if (datafile) this.options.onPut(datafile);
+    });
+    source.addEventListener("error", () => {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("feat: datafile stream error; falling back to polling");
+      }
+      if (this.source && this.source.readyState === EVENT_SOURCE_CLOSED) {
+        this.close();
+      }
+    });
+  }
+  close() {
+    this.source?.close();
+    this.source = null;
+  }
+};
+function parsePut(data) {
+  if (typeof data !== "string") return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && typeof parsed.version === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+
 // src/version.ts
-var SDK_VERSION = "0.1.1";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var CLIENT_SIDE_PREFIX = "feat_cs_";
 var MIN_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_INTERVAL_MS = 3e4;
 var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_URL = "https://data-01.feat.so";
 var FeatWebClient = class {
   constructor(config) {
     this.config = config;
@@ -179,23 +333,44 @@ var FeatWebClient = class {
     this.visibilityHandler = null;
     this.emitter = new Emitter();
     this.broadcast = null;
+    this.stream = null;
+    // The set of live `change` listeners. The streaming-follows-subscription
+    // policy keys off whether this is non-empty; tracking the listeners (rather
+    // than a counter) keeps the refcount correct whether the caller unsubscribes
+    // via the returned disposer or via off().
+    this.changeListeners = /* @__PURE__ */ new Set();
+    this.started = false;
+    this.warnedNoEventSource = false;
     this.closed = false;
     if (!config.apiKey.startsWith(CLIENT_SIDE_PREFIX)) {
       throw new Error(
         `FeatWebClient requires a client_side_id key (prefix "${CLIENT_SIDE_PREFIX}"). Server and mobile keys must never ship in browser code.`
       );
     }
-    assertHttpsUrl(config.dataPlaneUrl);
+    this.url = config.url ?? DEFAULT_URL;
+    assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.eventSourceCtor = config.eventSource ?? (typeof globalThis.EventSource !== "undefined" ? globalThis.EventSource : void 0);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
     );
+    this.summarizer = config.events === false ? null : new EventSummarizer({
+      url: this.url,
+      apiKey: config.apiKey,
+      fetchImpl: this.fetchImpl,
+      sdkHeader: `web/${SDK_VERSION}`,
+      flushIntervalMs: Math.max(
+        config.eventsFlushIntervalMs ?? DEFAULT_EVENTS_FLUSH_INTERVAL_MS,
+        MIN_EVENTS_FLUSH_INTERVAL_MS
+      )
+    });
     if (config.context) {
       this.context = config.context;
     } else if (config.anonymous) {
       this.context = buildAnonymousContext(config.anonymous);
     }
+    if (this.context) this.summarizer?.record(this.context);
     if (config.bootstrap) {
       this.datafile = config.bootstrap;
       this.etag = config.bootstrap.etag;
@@ -225,6 +400,7 @@ var FeatWebClient = class {
   // OpenFeature's `onContextChange` lifecycle hook bridges to this.
   async setContext(context) {
     this.context = context;
+    this.summarizer?.record(context);
     await this.recomputeCache();
   }
   currentContext() {
@@ -267,10 +443,17 @@ var FeatWebClient = class {
     return new Map(this.cache);
   }
   on(event, listener) {
-    return this.emitter.on(event, listener);
+    if (event !== "change") return this.emitter.on(event, listener);
+    this.emitter.on(event, listener);
+    this.changeListeners.add(listener);
+    this.maybeUpdateStream();
+    return () => this.off(event, listener);
   }
   off(event, listener) {
     this.emitter.off(event, listener);
+    if (event === "change" && this.changeListeners.delete(listener)) {
+      this.maybeUpdateStream();
+    }
   }
   // Force a one-shot fetch. Returns true if the in-memory datafile changed.
   async refresh() {
@@ -285,12 +468,16 @@ var FeatWebClient = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.stream?.close();
+    this.stream = null;
+    this.changeListeners.clear();
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
     }
     this.broadcast?.close();
     this.broadcast = null;
+    this.summarizer?.close();
     this.emitter.removeAll();
   }
   async bootstrap() {
@@ -300,6 +487,9 @@ var FeatWebClient = class {
       if (this.closed) return;
       this.startPolling();
       this.attachVisibilityHandler();
+      this.summarizer?.start();
+      this.started = true;
+      this.maybeUpdateStream();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -332,7 +522,7 @@ var FeatWebClient = class {
     document.addEventListener("visibilitychange", this.visibilityHandler);
   }
   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}`,
       // Custom header because browsers forbid setting User-Agent on fetch.
@@ -360,18 +550,73 @@ var FeatWebClient = class {
     await this.recomputeCache();
     return true;
   }
-  // Sibling-tab handler. Only adopt if the broadcast carries a newer
-  // version (or we have nothing); old broadcasts can race with our own
-  // fresh fetches and we don't want to regress.
+  // Sibling-tab handler. Adopt without republishing: this is the receive end
+  // of a BroadcastChannel message, so echoing it back would loop.
   async adoptFromBroadcast(datafile, etag) {
+    await this.adoptDatafile(datafile, etag, false);
+  }
+  // Version-guarded adopt for datafiles that arrive outside the fetch path
+  // (sibling-tab broadcast, SSE `put`). Only adopt a strictly newer version so
+  // an old broadcast or out-of-order frame can't regress us; the same guard
+  // stops a republished put from looping back through a sibling tab. When
+  // `publish` is set we mirror the fetch path and rebroadcast so sibling tabs
+  // stay fresh without their own network call.
+  async adoptDatafile(datafile, etag, publish) {
+    if (this.closed) return;
     if (this.datafile && datafile.version <= this.datafile.version) return;
     this.datafile = datafile;
     this.etag = etag;
     if (this.config.cache) {
       saveCachedDatafile(this.config.cache, { datafile, etag });
     }
+    if (publish) this.broadcast?.publish(datafile, etag);
     await this.recomputeCache();
   }
+  // Reconcile the SSE connection with the current streaming policy. Called
+  // whenever an input to that policy changes: ready, a `change` (un)subscribe,
+  // or close.
+  maybeUpdateStream() {
+    if (this.closed) return;
+    const want = this.wantsStream();
+    if (want) {
+      this.openStream();
+    } else if (this.stream) {
+      this.stream.close();
+      this.stream = null;
+    }
+  }
+  wantsStream() {
+    if (this.config.streaming === false) return false;
+    if (this.config.streaming === true) return this.started;
+    return this.changeListeners.size > 0;
+  }
+  openStream() {
+    if (!this.eventSourceCtor) {
+      if (!this.warnedNoEventSource) {
+        this.warnedNoEventSource = true;
+        console.warn("feat: streaming requested but EventSource is unavailable; using polling");
+      }
+      return;
+    }
+    if (!this.stream) {
+      this.stream = new DatafileStream({
+        url: this.url,
+        apiKey: this.config.apiKey,
+        eventSourceCtor: this.eventSourceCtor,
+        // A `put` carries the full datafile; reuse the version-ordered adopt
+        // path so a duplicate or out-of-order frame is ignored and the cache
+        // recomputes (firing `change`) only on a strictly newer version. Like
+        // the fetch path, a stream-adopted put republishes on the
+        // BroadcastChannel so sibling tabs stay fresh without their own fetch.
+        onPut: (datafile) => {
+          void this.adoptDatafile(datafile, datafile.etag, true).catch((err) => {
+            console.warn("feat: streamed datafile update failed:", messageOf(err));
+          });
+        }
+      });
+    }
+    this.stream.open();
+  }
   // Pre-evaluate every flag in the datafile against the current context
   // and diff against the previous cache. Skips silently if datafile or
   // context is missing; the caller will recompute as soon as both land.
@@ -434,10 +679,10 @@ 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)");
 }
 
 // src/index.ts
-var SDK_VERSION2 = "0.1.0";
+var SDK_VERSION2 = "0.3.0";
 
 export { FeatWebClient, SDK_VERSION2 as SDK_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feathq/web-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "feat feature-flag SDK for browsers. Polling client + sync evaluation cache. Pair with @feathq/openfeature-web for OpenFeature.",
   "keywords": [
     "feature-flags",