@feathq/web-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 feat HQ
+
+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

@@ -0,0 +1,88 @@
+# @feathq/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.
+
+For server code, use [`@feathq/js-sdk`](../js-sdk). For an OpenFeature web Provider, install [`@feathq/openfeature-web`](../openfeature-web) alongside this package.
+
+## Install
+
+```bash
+npm install @feathq/web-sdk
+# or
+yarn add @feathq/web-sdk
+```
+
+## Usage
+
+```ts
+import { FeatWebClient } from "@feathq/web-sdk";
+
+const client = new FeatWebClient({
+  apiKey: "feat_cs_…",                       // client-side ID key
+  dataPlaneUrl: "https://data.feat.so",
+  anonymous: { storage: "localStorage" },    // optional: auto-mint a stable anonymous user
+  cache: { storage: "localStorage" },        // optional: warm cache across page loads
+});
+
+await client.ready();
+
+const enabled = client.getBooleanValue("checkout-v2", false);   // sync
+const greeting = client.getStringValue("hero-greeting", "Hi");
+```
+
+Use a **client-side ID** key (`feat_cs_…`). The key is non-secret and safe to ship in your bundle. Add your site's origin to the key's Authorized URLs in the feat console.
+
+## Reacting to flag changes
+
+```ts
+client.on("change", ({ flagKey, newValue }) => {
+  console.log(`${flagKey} → ${newValue}`);
+});
+
+await client.setContext({
+  targetingKey: "user-123",
+  user: { plan: "pro" },
+});
+```
+
+`change` events fire per flag whose evaluated value flipped, after either a context change or a datafile refresh.
+
+## OpenFeature
+
+```ts
+import { OpenFeature } from "@openfeature/web-sdk";
+import { FeatWebClient } from "@feathq/web-sdk";
+import { FeatWebProvider } from "@feathq/openfeature-web";
+
+const featClient = new FeatWebClient({ apiKey, dataPlaneUrl });
+await OpenFeature.setProviderAndWait(new FeatWebProvider(featClient));
+await OpenFeature.setContext({ targetingKey: "user-123" });
+
+const enabled = OpenFeature.getClient().getBooleanValue("checkout-v2", false);
+```
+
+## SSR / hydration
+
+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 });
+```
+
+## 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.
+- 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).
+
+## Security notes
+
+- `cache: { storage: "localStorage" }` persists the full datafile (including flag rules and segment definitions) under `feat:datafile`. Use only on browsers where you're comfortable with that footprint; default is off.
+- `anonymous: { storage: "localStorage" }` writes a stable UUID to `feat:anonymousKey`. Use `storage: "memory"` if you don't want it persisted.
+- `BroadcastChannel("feat:datafile")` broadcasts to all same-origin tabs. Any script on the same origin can subscribe; treat the datafile as same-origin-readable.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,441 @@
+'use strict';
+
+var featEval = require('@feathq/feat-eval');
+
+// src/client.ts
+
+// src/anonymous.ts
+var STORAGE_KEY = "feat:anonymousKey";
+function buildAnonymousContext(config) {
+  const key = resolveOrMintAnonymousKey(config.storage);
+  return {
+    targetingKey: key,
+    user: { key, anonymous: true }
+  };
+}
+var memoryKey = null;
+function resolveOrMintAnonymousKey(storage) {
+  if (storage === "localStorage" && hasLocalStorage()) {
+    try {
+      const existing = window.localStorage.getItem(STORAGE_KEY);
+      if (existing) return existing;
+      const fresh = randomKey();
+      window.localStorage.setItem(STORAGE_KEY, fresh);
+      return fresh;
+    } catch {
+    }
+  }
+  if (memoryKey) return memoryKey;
+  memoryKey = randomKey();
+  return memoryKey;
+}
+function hasLocalStorage() {
+  try {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  } catch {
+    return false;
+  }
+}
+function randomKey() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    const buf = new Uint8Array(16);
+    crypto.getRandomValues(buf);
+    buf[6] = (buf[6] ?? 0) & 15 | 64;
+    buf[8] = (buf[8] ?? 0) & 63 | 128;
+    return formatUuid(buf);
+  }
+  let s = "";
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+}
+function formatUuid(bytes) {
+  const hex = [];
+  for (let i = 0; i < 16; i++) {
+    hex.push(((bytes[i] ?? 0) & 255).toString(16).padStart(2, "0"));
+  }
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+
+// src/broadcast.ts
+var CHANNEL_NAME = "feat:datafile";
+var DatafileBroadcast = class {
+  constructor(handler) {
+    this.channel = null;
+    this.handler = null;
+    this.listener = null;
+    if (typeof BroadcastChannel === "undefined") return;
+    this.handler = handler;
+    this.channel = new BroadcastChannel(CHANNEL_NAME);
+    this.listener = (ev) => {
+      const data = ev.data;
+      if (!data || data.type !== "datafile-update" || !this.handler) return;
+      this.handler(data);
+    };
+    this.channel.addEventListener("message", this.listener);
+  }
+  publish(datafile, etag) {
+    if (!this.channel) return;
+    const msg = { type: "datafile-update", datafile, etag };
+    try {
+      this.channel.postMessage(msg);
+    } catch {
+    }
+  }
+  close() {
+    if (this.channel && this.listener) {
+      this.channel.removeEventListener("message", this.listener);
+    }
+    this.channel?.close();
+    this.channel = null;
+    this.handler = null;
+    this.listener = null;
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = {};
+  }
+  on(event, listener) {
+    let set = this.listeners[event];
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners[event] = set;
+    }
+    set.add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) {
+    this.listeners[event]?.delete(listener);
+  }
+  emit(event, arg) {
+    const set = this.listeners[event];
+    if (!set) return;
+    for (const listener of [...set]) {
+      try {
+        listener(arg);
+      } catch (err) {
+        console.error("feat-web-sdk: emitter listener threw", err);
+      }
+    }
+  }
+  removeAll() {
+    this.listeners = {};
+  }
+};
+
+// src/persistence.ts
+var STORAGE_KEY2 = "feat:datafile";
+function loadCachedDatafile(config) {
+  if (config.storage !== "localStorage" || !hasLocalStorage2()) return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY2);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed.datafile || typeof parsed.datafile !== "object") return null;
+    const df = parsed.datafile;
+    if (typeof df.envId !== "string" || typeof df.version !== "number") return null;
+    return { datafile: df, etag: parsed.etag ?? null };
+  } catch {
+    return null;
+  }
+}
+function saveCachedDatafile(config, payload) {
+  if (config.storage !== "localStorage" || !hasLocalStorage2()) return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY2, JSON.stringify(payload));
+  } catch {
+  }
+}
+function hasLocalStorage2() {
+  try {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  } catch {
+    return false;
+  }
+}
+
+// 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 FeatWebClient = class {
+  constructor(config) {
+    this.config = config;
+    this.datafile = null;
+    this.etag = null;
+    this.context = null;
+    this.cache = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.readyPromise = null;
+    this.visibilityHandler = null;
+    this.emitter = new Emitter();
+    this.broadcast = null;
+    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.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.pollIntervalMs = Math.max(
+      config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      MIN_POLL_INTERVAL_MS
+    );
+    if (config.context) {
+      this.context = config.context;
+    } else if (config.anonymous) {
+      this.context = buildAnonymousContext(config.anonymous);
+    }
+    if (config.bootstrap) {
+      this.datafile = config.bootstrap;
+      this.etag = config.bootstrap.etag;
+    } else if (config.cache) {
+      const cached = loadCachedDatafile(config.cache);
+      if (cached) {
+        this.datafile = cached.datafile;
+        this.etag = cached.etag;
+      }
+    }
+    if (config.crossTabSync !== false) {
+      this.broadcast = new DatafileBroadcast((msg) => {
+        void this.adoptFromBroadcast(msg.datafile, msg.etag);
+      });
+    }
+  }
+  // Resolves once the first datafile is in memory AND (if context was
+  // supplied) the cache has been pre-evaluated.
+  async ready() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.bootstrap();
+    }
+    return this.readyPromise;
+  }
+  // Swap the evaluation context. Re-evaluates every flag, diffs against
+  // the previous cache, and fires a `change` event per flipped flag.
+  // OpenFeature's `onContextChange` lifecycle hook bridges to this.
+  async setContext(context) {
+    this.context = context;
+    await this.recomputeCache();
+  }
+  currentContext() {
+    return this.context;
+  }
+  // Sync flag access. Returns defaultValue with reason ERROR if the
+  // client isn't ready or the flag is missing. Sync because the cache
+  // is pre-computed; no async work happens in this path.
+  getDetail(flagKey, defaultValue) {
+    const cached = this.cache.get(flagKey);
+    if (cached !== void 0) return cached;
+    return {
+      value: defaultValue,
+      variationId: null,
+      reason: "ERROR",
+      errorMessage: this.context ? "flag could not be evaluated" : "client not ready: call setContext() and await ready()"
+    };
+  }
+  getValue(flagKey, defaultValue) {
+    return this.getDetail(flagKey, defaultValue).value;
+  }
+  getBooleanValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "boolean" ? v : defaultValue;
+  }
+  getStringValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "string" ? v : defaultValue;
+  }
+  getNumberValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "number" ? v : defaultValue;
+  }
+  getObjectValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "object" && v !== null ? v : defaultValue;
+  }
+  // Snapshot of the current sync cache. Useful for devtools and debug panels.
+  allFlags() {
+    return new Map(this.cache);
+  }
+  on(event, listener) {
+    return this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  // Force a one-shot fetch. Returns true if the in-memory datafile changed.
+  async refresh() {
+    return this.fetchDatafile();
+  }
+  currentDatafile() {
+    return this.datafile;
+  }
+  close() {
+    this.closed = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    this.broadcast?.close();
+    this.broadcast = null;
+    this.emitter.removeAll();
+  }
+  async bootstrap() {
+    try {
+      if (this.datafile) await this.recomputeCache();
+      await this.fetchDatafile();
+      if (this.closed) return;
+      this.startPolling();
+      this.attachVisibilityHandler();
+      this.emitter.emit("ready", void 0);
+    } catch (err) {
+      this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    }
+  }
+  startPolling() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = setInterval(() => {
+      void this.fetchDatafile().catch((err) => {
+        console.warn("feat: background poll failed:", messageOf(err));
+      });
+    }, this.pollIntervalMs);
+  }
+  attachVisibilityHandler() {
+    if (typeof document === "undefined") return;
+    this.visibilityHandler = () => {
+      if (document.hidden) {
+        if (this.timer) {
+          clearInterval(this.timer);
+          this.timer = null;
+        }
+        return;
+      }
+      void this.fetchDatafile().catch((err) => {
+        console.warn("feat: visibility refresh failed:", messageOf(err));
+      });
+      if (!this.timer) this.startPolling();
+    };
+    document.addEventListener("visibilitychange", this.visibilityHandler);
+  }
+  async fetchDatafile() {
+    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`
+    };
+    if (this.etag) headers["If-None-Match"] = this.etag;
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (res.status === 304) return false;
+    if (res.status === 404) return false;
+    if (res.status === 429) return false;
+    if (!res.ok) {
+      throw new Error(`fetchDatafile failed: ${res.status}`);
+    }
+    const lengthHeader = res.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_DATAFILE_BYTES) {
+      throw new Error("datafile exceeds maximum allowed size");
+    }
+    const next = await res.json();
+    this.datafile = next;
+    this.etag = res.headers.get("etag");
+    if (this.config.cache) {
+      saveCachedDatafile(this.config.cache, { datafile: next, etag: this.etag });
+    }
+    this.broadcast?.publish(next, this.etag);
+    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.
+  async adoptFromBroadcast(datafile, etag) {
+    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 });
+    }
+    await this.recomputeCache();
+  }
+  // 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.
+  async recomputeCache() {
+    if (!this.datafile || !this.context) return;
+    const prev = this.cache;
+    const next = /* @__PURE__ */ new Map();
+    const datafile = this.datafile;
+    const context = this.context;
+    for (const flagKey of Object.keys(datafile.flags)) {
+      const flag = datafile.flags[flagKey];
+      if (!flag) continue;
+      const result = await featEval.evaluate(flagKey, null, context, datafile);
+      next.set(flagKey, result);
+    }
+    this.cache = next;
+    for (const [flagKey, newResult] of next) {
+      const oldResult = prev.get(flagKey);
+      if (!oldResult || !sameValue(oldResult.value, newResult.value)) {
+        this.emitter.emit("change", {
+          flagKey,
+          oldValue: oldResult?.value ?? null,
+          newValue: newResult.value,
+          oldVariation: oldResult?.variationId ?? null,
+          newVariation: newResult.variationId
+        });
+      }
+    }
+    for (const [flagKey, oldResult] of prev) {
+      if (!next.has(flagKey)) {
+        this.emitter.emit("change", {
+          flagKey,
+          oldValue: oldResult.value,
+          newValue: null,
+          oldVariation: oldResult.variationId,
+          newVariation: null
+        });
+      }
+    }
+    this.emitter.emit("update", void 0);
+  }
+};
+function sameValue(a, b) {
+  if (a === b) return true;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function assertHttpsUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol === "https:") return;
+    if (u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1")) {
+      return;
+    }
+  } catch {
+  }
+  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+}
+
+// src/index.ts
+var SDK_VERSION = "0.1.0";
+
+exports.FeatWebClient = FeatWebClient;
+exports.SDK_VERSION = SDK_VERSION;

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+import { Datafile } from '@feathq/datafile-schema';
+export { Datafile } from '@feathq/datafile-schema';
+import { EvalContext, EvaluationResult } from '@feathq/feat-eval';
+export { ContextKindObject, EvalContext, EvaluationResult, Reason } from '@feathq/feat-eval';
+
+type AnonymousStorage = "localStorage" | "memory";
+interface AnonymousConfig {
+    storage: AnonymousStorage;
+}
+
+type DatafileCacheStorage = "localStorage";
+interface DatafileCacheConfig {
+    storage: DatafileCacheStorage;
+}
+
+interface FeatWebClientConfig {
+    apiKey: string;
+    dataPlaneUrl: string;
+    context?: EvalContext;
+    anonymous?: AnonymousConfig;
+    bootstrap?: Datafile;
+    cache?: DatafileCacheConfig;
+    pollIntervalMs?: number;
+    crossTabSync?: boolean;
+    fetch?: typeof fetch;
+}
+interface ChangeEvent {
+    flagKey: string;
+    oldValue: unknown;
+    newValue: unknown;
+    oldVariation: string | null;
+    newVariation: string | null;
+}
+interface FlagEventMap {
+    ready: undefined;
+    update: undefined;
+    change: ChangeEvent;
+    failed: Error;
+}
+
+declare class FeatWebClient {
+    private readonly config;
+    private datafile;
+    private etag;
+    private context;
+    private cache;
+    private timer;
+    private readyPromise;
+    private visibilityHandler;
+    private emitter;
+    private broadcast;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    private closed;
+    constructor(config: FeatWebClientConfig);
+    ready(): Promise<void>;
+    setContext(context: EvalContext): Promise<void>;
+    currentContext(): EvalContext | null;
+    getDetail<T = unknown>(flagKey: string, defaultValue: T): EvaluationResult<T>;
+    getValue<T = unknown>(flagKey: string, defaultValue: T): T;
+    getBooleanValue(flagKey: string, defaultValue: boolean): boolean;
+    getStringValue(flagKey: string, defaultValue: string): string;
+    getNumberValue(flagKey: string, defaultValue: number): number;
+    getObjectValue<T = unknown>(flagKey: string, defaultValue: T): T;
+    allFlags(): ReadonlyMap<string, EvaluationResult>;
+    on<K extends keyof FlagEventMap>(event: K, listener: (arg: FlagEventMap[K]) => void): () => void;
+    off<K extends keyof FlagEventMap>(event: K, listener: (arg: FlagEventMap[K]) => void): void;
+    refresh(): Promise<boolean>;
+    currentDatafile(): Datafile | null;
+    close(): void;
+    private bootstrap;
+    private startPolling;
+    private attachVisibilityHandler;
+    private fetchDatafile;
+    private adoptFromBroadcast;
+    private recomputeCache;
+}
+
+declare const SDK_VERSION = "0.1.0";
+
+export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { Datafile } from '@feathq/datafile-schema';
+export { Datafile } from '@feathq/datafile-schema';
+import { EvalContext, EvaluationResult } from '@feathq/feat-eval';
+export { ContextKindObject, EvalContext, EvaluationResult, Reason } from '@feathq/feat-eval';
+
+type AnonymousStorage = "localStorage" | "memory";
+interface AnonymousConfig {
+    storage: AnonymousStorage;
+}
+
+type DatafileCacheStorage = "localStorage";
+interface DatafileCacheConfig {
+    storage: DatafileCacheStorage;
+}
+
+interface FeatWebClientConfig {
+    apiKey: string;
+    dataPlaneUrl: string;
+    context?: EvalContext;
+    anonymous?: AnonymousConfig;
+    bootstrap?: Datafile;
+    cache?: DatafileCacheConfig;
+    pollIntervalMs?: number;
+    crossTabSync?: boolean;
+    fetch?: typeof fetch;
+}
+interface ChangeEvent {
+    flagKey: string;
+    oldValue: unknown;
+    newValue: unknown;
+    oldVariation: string | null;
+    newVariation: string | null;
+}
+interface FlagEventMap {
+    ready: undefined;
+    update: undefined;
+    change: ChangeEvent;
+    failed: Error;
+}
+
+declare class FeatWebClient {
+    private readonly config;
+    private datafile;
+    private etag;
+    private context;
+    private cache;
+    private timer;
+    private readyPromise;
+    private visibilityHandler;
+    private emitter;
+    private broadcast;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    private closed;
+    constructor(config: FeatWebClientConfig);
+    ready(): Promise<void>;
+    setContext(context: EvalContext): Promise<void>;
+    currentContext(): EvalContext | null;
+    getDetail<T = unknown>(flagKey: string, defaultValue: T): EvaluationResult<T>;
+    getValue<T = unknown>(flagKey: string, defaultValue: T): T;
+    getBooleanValue(flagKey: string, defaultValue: boolean): boolean;
+    getStringValue(flagKey: string, defaultValue: string): string;
+    getNumberValue(flagKey: string, defaultValue: number): number;
+    getObjectValue<T = unknown>(flagKey: string, defaultValue: T): T;
+    allFlags(): ReadonlyMap<string, EvaluationResult>;
+    on<K extends keyof FlagEventMap>(event: K, listener: (arg: FlagEventMap[K]) => void): () => void;
+    off<K extends keyof FlagEventMap>(event: K, listener: (arg: FlagEventMap[K]) => void): void;
+    refresh(): Promise<boolean>;
+    currentDatafile(): Datafile | null;
+    close(): void;
+    private bootstrap;
+    private startPolling;
+    private attachVisibilityHandler;
+    private fetchDatafile;
+    private adoptFromBroadcast;
+    private recomputeCache;
+}
+
+declare const SDK_VERSION = "0.1.0";
+
+export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.js

@@ -0,0 +1,438 @@
+import { evaluate } from '@feathq/feat-eval';
+
+// src/client.ts
+
+// src/anonymous.ts
+var STORAGE_KEY = "feat:anonymousKey";
+function buildAnonymousContext(config) {
+  const key = resolveOrMintAnonymousKey(config.storage);
+  return {
+    targetingKey: key,
+    user: { key, anonymous: true }
+  };
+}
+var memoryKey = null;
+function resolveOrMintAnonymousKey(storage) {
+  if (storage === "localStorage" && hasLocalStorage()) {
+    try {
+      const existing = window.localStorage.getItem(STORAGE_KEY);
+      if (existing) return existing;
+      const fresh = randomKey();
+      window.localStorage.setItem(STORAGE_KEY, fresh);
+      return fresh;
+    } catch {
+    }
+  }
+  if (memoryKey) return memoryKey;
+  memoryKey = randomKey();
+  return memoryKey;
+}
+function hasLocalStorage() {
+  try {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  } catch {
+    return false;
+  }
+}
+function randomKey() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    const buf = new Uint8Array(16);
+    crypto.getRandomValues(buf);
+    buf[6] = (buf[6] ?? 0) & 15 | 64;
+    buf[8] = (buf[8] ?? 0) & 63 | 128;
+    return formatUuid(buf);
+  }
+  let s = "";
+  for (let i = 0; i < 32; i++) {
+    s += Math.floor(Math.random() * 16).toString(16);
+  }
+  return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+}
+function formatUuid(bytes) {
+  const hex = [];
+  for (let i = 0; i < 16; i++) {
+    hex.push(((bytes[i] ?? 0) & 255).toString(16).padStart(2, "0"));
+  }
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+
+// src/broadcast.ts
+var CHANNEL_NAME = "feat:datafile";
+var DatafileBroadcast = class {
+  constructor(handler) {
+    this.channel = null;
+    this.handler = null;
+    this.listener = null;
+    if (typeof BroadcastChannel === "undefined") return;
+    this.handler = handler;
+    this.channel = new BroadcastChannel(CHANNEL_NAME);
+    this.listener = (ev) => {
+      const data = ev.data;
+      if (!data || data.type !== "datafile-update" || !this.handler) return;
+      this.handler(data);
+    };
+    this.channel.addEventListener("message", this.listener);
+  }
+  publish(datafile, etag) {
+    if (!this.channel) return;
+    const msg = { type: "datafile-update", datafile, etag };
+    try {
+      this.channel.postMessage(msg);
+    } catch {
+    }
+  }
+  close() {
+    if (this.channel && this.listener) {
+      this.channel.removeEventListener("message", this.listener);
+    }
+    this.channel?.close();
+    this.channel = null;
+    this.handler = null;
+    this.listener = null;
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = {};
+  }
+  on(event, listener) {
+    let set = this.listeners[event];
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners[event] = set;
+    }
+    set.add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) {
+    this.listeners[event]?.delete(listener);
+  }
+  emit(event, arg) {
+    const set = this.listeners[event];
+    if (!set) return;
+    for (const listener of [...set]) {
+      try {
+        listener(arg);
+      } catch (err) {
+        console.error("feat-web-sdk: emitter listener threw", err);
+      }
+    }
+  }
+  removeAll() {
+    this.listeners = {};
+  }
+};
+
+// src/persistence.ts
+var STORAGE_KEY2 = "feat:datafile";
+function loadCachedDatafile(config) {
+  if (config.storage !== "localStorage" || !hasLocalStorage2()) return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY2);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed.datafile || typeof parsed.datafile !== "object") return null;
+    const df = parsed.datafile;
+    if (typeof df.envId !== "string" || typeof df.version !== "number") return null;
+    return { datafile: df, etag: parsed.etag ?? null };
+  } catch {
+    return null;
+  }
+}
+function saveCachedDatafile(config, payload) {
+  if (config.storage !== "localStorage" || !hasLocalStorage2()) return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY2, JSON.stringify(payload));
+  } catch {
+  }
+}
+function hasLocalStorage2() {
+  try {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  } catch {
+    return false;
+  }
+}
+
+// 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 FeatWebClient = class {
+  constructor(config) {
+    this.config = config;
+    this.datafile = null;
+    this.etag = null;
+    this.context = null;
+    this.cache = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.readyPromise = null;
+    this.visibilityHandler = null;
+    this.emitter = new Emitter();
+    this.broadcast = null;
+    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.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.pollIntervalMs = Math.max(
+      config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      MIN_POLL_INTERVAL_MS
+    );
+    if (config.context) {
+      this.context = config.context;
+    } else if (config.anonymous) {
+      this.context = buildAnonymousContext(config.anonymous);
+    }
+    if (config.bootstrap) {
+      this.datafile = config.bootstrap;
+      this.etag = config.bootstrap.etag;
+    } else if (config.cache) {
+      const cached = loadCachedDatafile(config.cache);
+      if (cached) {
+        this.datafile = cached.datafile;
+        this.etag = cached.etag;
+      }
+    }
+    if (config.crossTabSync !== false) {
+      this.broadcast = new DatafileBroadcast((msg) => {
+        void this.adoptFromBroadcast(msg.datafile, msg.etag);
+      });
+    }
+  }
+  // Resolves once the first datafile is in memory AND (if context was
+  // supplied) the cache has been pre-evaluated.
+  async ready() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.bootstrap();
+    }
+    return this.readyPromise;
+  }
+  // Swap the evaluation context. Re-evaluates every flag, diffs against
+  // the previous cache, and fires a `change` event per flipped flag.
+  // OpenFeature's `onContextChange` lifecycle hook bridges to this.
+  async setContext(context) {
+    this.context = context;
+    await this.recomputeCache();
+  }
+  currentContext() {
+    return this.context;
+  }
+  // Sync flag access. Returns defaultValue with reason ERROR if the
+  // client isn't ready or the flag is missing. Sync because the cache
+  // is pre-computed; no async work happens in this path.
+  getDetail(flagKey, defaultValue) {
+    const cached = this.cache.get(flagKey);
+    if (cached !== void 0) return cached;
+    return {
+      value: defaultValue,
+      variationId: null,
+      reason: "ERROR",
+      errorMessage: this.context ? "flag could not be evaluated" : "client not ready: call setContext() and await ready()"
+    };
+  }
+  getValue(flagKey, defaultValue) {
+    return this.getDetail(flagKey, defaultValue).value;
+  }
+  getBooleanValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "boolean" ? v : defaultValue;
+  }
+  getStringValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "string" ? v : defaultValue;
+  }
+  getNumberValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "number" ? v : defaultValue;
+  }
+  getObjectValue(flagKey, defaultValue) {
+    const v = this.getDetail(flagKey, defaultValue).value;
+    return typeof v === "object" && v !== null ? v : defaultValue;
+  }
+  // Snapshot of the current sync cache. Useful for devtools and debug panels.
+  allFlags() {
+    return new Map(this.cache);
+  }
+  on(event, listener) {
+    return this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  // Force a one-shot fetch. Returns true if the in-memory datafile changed.
+  async refresh() {
+    return this.fetchDatafile();
+  }
+  currentDatafile() {
+    return this.datafile;
+  }
+  close() {
+    this.closed = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    this.broadcast?.close();
+    this.broadcast = null;
+    this.emitter.removeAll();
+  }
+  async bootstrap() {
+    try {
+      if (this.datafile) await this.recomputeCache();
+      await this.fetchDatafile();
+      if (this.closed) return;
+      this.startPolling();
+      this.attachVisibilityHandler();
+      this.emitter.emit("ready", void 0);
+    } catch (err) {
+      this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    }
+  }
+  startPolling() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = setInterval(() => {
+      void this.fetchDatafile().catch((err) => {
+        console.warn("feat: background poll failed:", messageOf(err));
+      });
+    }, this.pollIntervalMs);
+  }
+  attachVisibilityHandler() {
+    if (typeof document === "undefined") return;
+    this.visibilityHandler = () => {
+      if (document.hidden) {
+        if (this.timer) {
+          clearInterval(this.timer);
+          this.timer = null;
+        }
+        return;
+      }
+      void this.fetchDatafile().catch((err) => {
+        console.warn("feat: visibility refresh failed:", messageOf(err));
+      });
+      if (!this.timer) this.startPolling();
+    };
+    document.addEventListener("visibilitychange", this.visibilityHandler);
+  }
+  async fetchDatafile() {
+    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`
+    };
+    if (this.etag) headers["If-None-Match"] = this.etag;
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (res.status === 304) return false;
+    if (res.status === 404) return false;
+    if (res.status === 429) return false;
+    if (!res.ok) {
+      throw new Error(`fetchDatafile failed: ${res.status}`);
+    }
+    const lengthHeader = res.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_DATAFILE_BYTES) {
+      throw new Error("datafile exceeds maximum allowed size");
+    }
+    const next = await res.json();
+    this.datafile = next;
+    this.etag = res.headers.get("etag");
+    if (this.config.cache) {
+      saveCachedDatafile(this.config.cache, { datafile: next, etag: this.etag });
+    }
+    this.broadcast?.publish(next, this.etag);
+    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.
+  async adoptFromBroadcast(datafile, etag) {
+    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 });
+    }
+    await this.recomputeCache();
+  }
+  // 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.
+  async recomputeCache() {
+    if (!this.datafile || !this.context) return;
+    const prev = this.cache;
+    const next = /* @__PURE__ */ new Map();
+    const datafile = this.datafile;
+    const context = this.context;
+    for (const flagKey of Object.keys(datafile.flags)) {
+      const flag = datafile.flags[flagKey];
+      if (!flag) continue;
+      const result = await evaluate(flagKey, null, context, datafile);
+      next.set(flagKey, result);
+    }
+    this.cache = next;
+    for (const [flagKey, newResult] of next) {
+      const oldResult = prev.get(flagKey);
+      if (!oldResult || !sameValue(oldResult.value, newResult.value)) {
+        this.emitter.emit("change", {
+          flagKey,
+          oldValue: oldResult?.value ?? null,
+          newValue: newResult.value,
+          oldVariation: oldResult?.variationId ?? null,
+          newVariation: newResult.variationId
+        });
+      }
+    }
+    for (const [flagKey, oldResult] of prev) {
+      if (!next.has(flagKey)) {
+        this.emitter.emit("change", {
+          flagKey,
+          oldValue: oldResult.value,
+          newValue: null,
+          oldVariation: oldResult.variationId,
+          newVariation: null
+        });
+      }
+    }
+    this.emitter.emit("update", void 0);
+  }
+};
+function sameValue(a, b) {
+  if (a === b) return true;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function assertHttpsUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol === "https:") return;
+    if (u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1")) {
+      return;
+    }
+  } catch {
+  }
+  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+}
+
+// src/index.ts
+var SDK_VERSION = "0.1.0";
+
+export { FeatWebClient, SDK_VERSION };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@feathq/web-sdk",
+  "version": "0.1.0",
+  "description": "feat feature-flag SDK for browsers. Polling client + sync evaluation cache. Pair with @feathq/openfeature-web for OpenFeature.",
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "openfeature",
+    "feat",
+    "browser",
+    "client-side"
+  ],
+  "license": "MIT",
+  "author": "feat HQ <engineering@feat.so>",
+  "homepage": "https://feat.so",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/feathq/web-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/feathq/web-sdk/issues"
+  },
+  "type": "module",
+  "packageManager": "yarn@4.14.1",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@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",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}