@feathq/web-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,4 +1,12 @@
-# @feathq/web-sdk
+<p align="center">
+  <a href="https://feat.so">
+    <img src="https://feat.so/logo/wordmark.png" alt="feat.so" width="320" />
+  </a>
+</p>
+
+---
+
+# feat Web SDK
 
 Browser / client-side SDK for [feat](https://feat.so) feature flags. Polls a per-environment datafile to the browser and evaluates flags locally with a synchronous cache.
 
@@ -19,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
 });
@@ -54,7 +62,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" });
 
@@ -66,7 +74,7 @@ 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
@@ -75,7 +83,7 @@ new FeatWebClient({ apiKey, dataPlaneUrl, bootstrap: serverProvidedDatafile });
 - Polls every 30 s by default; pauses while the tab is hidden and force-refreshes on visibility restore. Floored at 5 s.
 - 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,11 +267,15 @@ function hasLocalStorage2() {
   }
 }
 
+// src/version.ts
+var SDK_VERSION = "0.2.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;
@@ -184,17 +294,29 @@ var FeatWebClient = class {
         `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.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;
@@ -224,6 +346,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() {
@@ -290,6 +413,7 @@ var FeatWebClient = class {
     }
     this.broadcast?.close();
     this.broadcast = null;
+    this.summarizer?.close();
     this.emitter.removeAll();
   }
   async bootstrap() {
@@ -299,6 +423,7 @@ var FeatWebClient = class {
       if (this.closed) return;
       this.startPolling();
       this.attachVisibilityHandler();
+      this.summarizer?.start();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -331,9 +456,11 @@ 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}`
+      Authorization: `Bearer ${this.config.apiKey}`,
+      // Custom header because browsers forbid setting User-Agent on fetch.
+      "X-Feat-Sdk": `web/${SDK_VERSION}`
     };
     if (this.etag) headers["If-None-Match"] = this.etag;
     const res = await this.fetchImpl(url, { method: "GET", headers });
@@ -431,11 +558,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_VERSION = "0.1.0";
+var SDK_VERSION2 = "0.2.0";
 
 exports.FeatWebClient = FeatWebClient;
-exports.SDK_VERSION = SDK_VERSION;
+exports.SDK_VERSION = SDK_VERSION2;

package/dist/index.d.cts

@@ -15,13 +15,15 @@ interface DatafileCacheConfig {
 
 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;
 }
 interface ChangeEvent {
@@ -49,8 +51,10 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private readonly summarizer;
     private readonly fetchImpl;
     private readonly pollIntervalMs;
+    private readonly url;
     private closed;
     constructor(config: FeatWebClientConfig);
     ready(): Promise<void>;
@@ -76,6 +80,6 @@ declare class FeatWebClient {
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.2.0";
 
 export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.d.ts

@@ -15,13 +15,15 @@ interface DatafileCacheConfig {
 
 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;
 }
 interface ChangeEvent {
@@ -49,8 +51,10 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private readonly summarizer;
     private readonly fetchImpl;
     private readonly pollIntervalMs;
+    private readonly url;
     private closed;
     constructor(config: FeatWebClientConfig);
     ready(): Promise<void>;
@@ -76,6 +80,6 @@ declare class FeatWebClient {
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.2.0";
 
 export { type ChangeEvent, 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,11 +265,15 @@ function hasLocalStorage2() {
   }
 }
 
+// src/version.ts
+var SDK_VERSION = "0.2.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;
@@ -182,17 +292,29 @@ var FeatWebClient = class {
         `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.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;
@@ -222,6 +344,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() {
@@ -288,6 +411,7 @@ var FeatWebClient = class {
     }
     this.broadcast?.close();
     this.broadcast = null;
+    this.summarizer?.close();
     this.emitter.removeAll();
   }
   async bootstrap() {
@@ -297,6 +421,7 @@ var FeatWebClient = class {
       if (this.closed) return;
       this.startPolling();
       this.attachVisibilityHandler();
+      this.summarizer?.start();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -329,9 +454,11 @@ 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}`
+      Authorization: `Bearer ${this.config.apiKey}`,
+      // Custom header because browsers forbid setting User-Agent on fetch.
+      "X-Feat-Sdk": `web/${SDK_VERSION}`
     };
     if (this.etag) headers["If-None-Match"] = this.etag;
     const res = await this.fetchImpl(url, { method: "GET", headers });
@@ -429,10 +556,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_VERSION = "0.1.0";
+var SDK_VERSION2 = "0.2.0";
 
-export { FeatWebClient, SDK_VERSION };
+export { FeatWebClient, SDK_VERSION2 as SDK_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feathq/web-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "feat feature-flag SDK for browsers. Polling client + sync evaluation cache. Pair with @feathq/openfeature-web for OpenFeature.",
   "keywords": [
     "feature-flags",
@@ -11,7 +11,7 @@
     "client-side"
   ],
   "license": "MIT",
-  "author": "feat HQ <engineering@feat.so>",
+  "author": "feat HQ <support@feat.so>",
   "homepage": "https://feat.so",
   "repository": {
     "type": "git",
@@ -48,11 +48,6 @@
     "@feathq/datafile-schema": "^0.1.0",
     "@feathq/feat-eval": "^0.1.0"
   },
-  "resolutions": {
-    "@feathq/datafile-schema": "portal:../../packages/datafile-schema",
-    "@feathq/datafile-schema@workspace:*": "portal:../../packages/datafile-schema",
-    "@feathq/feat-eval": "portal:../../packages/feat-eval"
-  },
   "devDependencies": {
     "@types/node": "^25.6.2",
     "happy-dom": "^15.11.7",
@@ -60,4 +55,4 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   }
-}
+}