@featureflare/sdk-js 0.0.26 → 0.0.27

package/dist/index.cjs

@@ -27,12 +27,84 @@ function getSdkKeyFromEnv() {
   }
   return null;
 }
+function monotonicNow() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function isRetriableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function normalizeBoolMap(input) {
+  if (Array.isArray(input.flags)) {
+    return input.flags.filter(
+      (entry) => Boolean(entry) && typeof entry.key === "string" && typeof entry.value === "boolean"
+    ).map((entry) => ({ key: entry.key, value: entry.value }));
+  }
+  const values = input.values ?? {};
+  return Object.entries(values).map(([key, value]) => ({ key, value: Boolean(value) }));
+}
+var InMemoryMetricsCollector = class {
+  buckets = /* @__PURE__ */ new Map();
+  record = (metricName, value, tags) => {
+    const key = `${metricName}:${JSON.stringify(tags ?? {})}`;
+    const list = this.buckets.get(key) ?? [];
+    list.push(value);
+    this.buckets.set(key, list);
+  };
+  get(metricName) {
+    const rows = [];
+    for (const [key, values] of this.buckets.entries()) {
+      if (!key.startsWith(`${metricName}:`)) continue;
+      rows.push({
+        tags: JSON.parse(key.slice(metricName.length + 1)),
+        values: [...values]
+      });
+    }
+    return rows;
+  }
+};
 var FeatureFlareClient = class {
   apiBaseUrl;
   sdkKey;
   projectKey;
   envKey;
   expectedEnvKey;
+  timeoutMs;
+  maxRetries;
+  backoffMs;
+  jitter;
+  cacheTtlMs;
+  staleTtlMs;
+  persistentCache;
+  onMetric;
+  listeners = {
+    update: /* @__PURE__ */ new Set(),
+    circuitOpen: /* @__PURE__ */ new Set(),
+    circuitClose: /* @__PURE__ */ new Set(),
+    connectionState: /* @__PURE__ */ new Set()
+  };
+  cache = /* @__PURE__ */ new Map();
+  diagnostics = /* @__PURE__ */ new Map();
+  killSwitches = /* @__PURE__ */ new Set();
+  revision = 0;
+  circuitOpen = false;
+  persistentLoadPromise = null;
+  inFlightRevalidate = /* @__PURE__ */ new Map();
+  lastUser = null;
+  lastDefaultValue = false;
+  realtimeEnabled = true;
+  realtimePollingMs = 15e3;
+  realtimeSsePath = "/api/v1/sdk/stream";
+  pollTimer = null;
+  reconnectTimer = null;
+  eventSource = null;
   constructor(options = {}) {
     this.apiBaseUrl = getApiBaseUrl(options.apiBaseUrl).replace(/\/$/, "");
     this.sdkKey = options.sdkKey?.trim() || getSdkKeyFromEnv();
@@ -45,6 +117,26 @@ var FeatureFlareClient = class {
         "FeatureFlareClient requires either sdkKey (recommended) or projectKey (legacy). Set FEATUREFLARE_CLIENT_KEY or FEATUREFLARE_SERVER_KEY env var, or pass sdkKey in options."
       );
     }
+    this.timeoutMs = Number.isFinite(options.timeoutMs) && (options.timeoutMs ?? 0) > 0 ? Number(options.timeoutMs) : 3e3;
+    this.maxRetries = Number.isFinite(options.maxRetries) && (options.maxRetries ?? 0) >= 0 ? Number(options.maxRetries) : 2;
+    this.backoffMs = Number.isFinite(options.backoffMs) && (options.backoffMs ?? 0) > 0 ? Number(options.backoffMs) : 200;
+    this.jitter = Number.isFinite(options.jitter) && (options.jitter ?? 0) >= 0 ? Number(options.jitter) : 0.25;
+    this.cacheTtlMs = Number.isFinite(options.cacheTtlMs) && (options.cacheTtlMs ?? 0) > 0 ? Number(options.cacheTtlMs) : 6e4;
+    const configuredStaleTtlMs = Number.isFinite(options.staleTtlMs) && (options.staleTtlMs ?? 0) > 0 ? Number(options.staleTtlMs) : 1e4;
+    this.staleTtlMs = Math.min(configuredStaleTtlMs, this.cacheTtlMs);
+    this.persistentCache = options.persistentCache;
+    this.onMetric = options.onMetric;
+    this.realtimeEnabled = options.realtime?.enabled ?? true;
+    this.realtimePollingMs = Number.isFinite(options.realtime?.pollingIntervalMs) && (options.realtime?.pollingIntervalMs ?? 0) > 0 ? Number(options.realtime?.pollingIntervalMs) : 15e3;
+    this.realtimeSsePath = options.realtime?.ssePath ?? "/api/v1/sdk/stream";
+    this.applyBootstrap(options.bootstrap);
+    this.persistentLoadPromise = this.loadPersistentCache();
+    if (this.realtimeEnabled && this.sdkKey) {
+      this.startRealtime();
+    }
+  }
+  getCacheKey(flagKey) {
+    return `${this.envKey}:${flagKey}`;
   }
   normalizeUser(input) {
     const key = (input.id ?? input.key ?? "").trim();
@@ -57,64 +149,597 @@ var FeatureFlareClient = class {
       custom: input.meta ?? input.custom
     };
   }
-  async bool(flagKey, user, defaultValue = false) {
-    const normalizedUser = this.normalizeUser(user);
-    const res = this.sdkKey ? await fetch(`${this.apiBaseUrl}/api/v1/sdk/eval`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "x-featureflare-sdk-key": this.sdkKey
-      },
-      body: JSON.stringify({
-        flagKey,
-        user: normalizedUser,
-        defaultValue,
-        expectedEnvKey: this.expectedEnvKey ?? void 0
-      })
-    }) : await fetch(`${this.apiBaseUrl}/api/v1/eval`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        projectKey: this.projectKey,
-        envKey: this.envKey,
-        flagKey,
-        user: normalizedUser,
-        defaultValue
-      })
+  emit(event, payload) {
+    for (const listener of this.listeners[event]) {
+      listener(payload);
+    }
+  }
+  on(event, listener) {
+    this.listeners[event].add(listener);
+    return () => {
+      this.listeners[event].delete(listener);
+    };
+  }
+  emitMetric(metricName, value, tags) {
+    this.onMetric?.(metricName, value, tags);
+  }
+  async ensurePersistentLoaded() {
+    if (!this.persistentLoadPromise) return;
+    await this.persistentLoadPromise;
+  }
+  async loadPersistentCache() {
+    if (!this.persistentCache) return;
+    try {
+      const snapshot = await this.persistentCache.load(this.envKey);
+      if (!snapshot) return;
+      this.revision = Math.max(this.revision, snapshot.revision ?? 0);
+      for (const killSwitchKey of snapshot.killSwitches ?? []) {
+        this.killSwitches.add(killSwitchKey);
+      }
+      for (const [flagKey, item] of Object.entries(snapshot.flags ?? {})) {
+        const existing = this.cache.get(this.getCacheKey(flagKey));
+        if (existing && existing.source === "bootstrap") continue;
+        this.cache.set(this.getCacheKey(flagKey), {
+          envKey: this.envKey,
+          flagKey,
+          value: Boolean(item.value),
+          updatedAt: Number(item.updatedAt) || Date.now(),
+          staleAt: Number(item.staleAt) || Date.now(),
+          expiresAt: Number(item.expiresAt) || Date.now(),
+          source: item.source ?? "persistent",
+          revision: item.revision ?? 0
+        });
+      }
+    } catch {
+    }
+  }
+  async persistCache() {
+    if (!this.persistentCache) return;
+    const snapshot = {
+      revision: this.revision,
+      killSwitches: [...this.killSwitches],
+      flags: {}
+    };
+    for (const [key, item] of this.cache.entries()) {
+      if (!key.startsWith(`${this.envKey}:`)) continue;
+      snapshot.flags[item.flagKey] = {
+        value: item.value,
+        updatedAt: item.updatedAt,
+        staleAt: item.staleAt,
+        expiresAt: item.expiresAt,
+        source: item.source,
+        revision: item.revision
+      };
+    }
+    try {
+      await this.persistentCache.save(this.envKey, snapshot);
+    } catch {
+    }
+  }
+  makeCacheWindow(at = Date.now()) {
+    return {
+      updatedAt: at,
+      staleAt: at + this.staleTtlMs,
+      expiresAt: at + this.cacheTtlMs
+    };
+  }
+  setCacheItem(flagKey, value, source, revision = this.revision, at = Date.now()) {
+    this.cache.set(this.getCacheKey(flagKey), {
+      envKey: this.envKey,
+      flagKey,
+      value,
+      source,
+      revision,
+      ...this.makeCacheWindow(at)
     });
-    if (!res.ok) return defaultValue;
-    const json = await res.json();
-    return json.value;
   }
-  async flags(user, defaultValue = false) {
+  applyBootstrap(bootstrap) {
+    if (!bootstrap) return;
+    this.revision = Math.max(this.revision, bootstrap.revision ?? 0);
+    for (const killSwitchKey of bootstrap.killSwitches ?? []) {
+      this.killSwitches.add(killSwitchKey);
+    }
+    const apply = (flagKey, value, revision, updatedAt) => {
+      this.setCacheItem(flagKey, value, "bootstrap", revision ?? this.revision, updatedAt ?? Date.now());
+    };
+    if (Array.isArray(bootstrap.flags)) {
+      for (const item of bootstrap.flags) {
+        if (!item || typeof item.key !== "string") continue;
+        apply(item.key, Boolean(item.value), item.revision, item.updatedAt);
+      }
+      return;
+    }
+    for (const [flagKey, value] of Object.entries(bootstrap.flags ?? {})) {
+      apply(flagKey, Boolean(value));
+    }
+  }
+  getCacheState(item, now = Date.now()) {
+    if (!item) return "missing";
+    if (now <= item.staleAt) return "fresh";
+    if (now <= item.expiresAt) return "stale";
+    return "expired";
+  }
+  setCircuitState(isOpen, reason = "") {
+    if (this.circuitOpen === isOpen) return;
+    this.circuitOpen = isOpen;
+    if (isOpen) {
+      this.emit("circuitOpen", { envKey: this.envKey, reason });
+      return;
+    }
+    this.emit("circuitClose", { envKey: this.envKey });
+  }
+  async fetchWithRetry(url, init, transport) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
+      const timeout = ac !== null ? setTimeout(() => {
+        ac.abort();
+      }, this.timeoutMs) : null;
+      try {
+        const response = await fetch(url, {
+          ...init,
+          signal: ac?.signal
+        });
+        if (timeout) clearTimeout(timeout);
+        if (!response.ok && isRetriableStatus(response.status) && attempt < this.maxRetries) {
+          lastError = new Error(`HTTP ${response.status}`);
+          const jitterOffset = this.backoffMs * this.jitter * Math.random();
+          await sleep(this.backoffMs * (attempt + 1) + jitterOffset);
+          continue;
+        }
+        return response;
+      } catch (error) {
+        if (timeout) clearTimeout(timeout);
+        lastError = error;
+        if (attempt >= this.maxRetries) break;
+        const jitterOffset = this.backoffMs * this.jitter * Math.random();
+        await sleep(this.backoffMs * (attempt + 1) + jitterOffset);
+      }
+    }
+    this.setCircuitState(true, transport);
+    throw lastError;
+  }
+  collectCachedFlags() {
+    const now = Date.now();
+    const flags = [];
+    for (const [cacheKey, item] of this.cache.entries()) {
+      if (!cacheKey.startsWith(`${this.envKey}:`)) continue;
+      if (this.killSwitches.has(item.flagKey)) {
+        flags.push({ key: item.flagKey, value: false });
+        continue;
+      }
+      const state = this.getCacheState(item, now);
+      if (state === "missing" || state === "expired") continue;
+      flags.push({ key: item.flagKey, value: item.value });
+    }
+    return flags.sort((a, b) => a.key.localeCompare(b.key));
+  }
+  getCachedFlags() {
+    const flags = this.collectCachedFlags();
+    return { flags, hasData: flags.length > 0 };
+  }
+  getFlagDiagnostics(flagKey) {
+    return this.diagnostics.get(this.getCacheKey(flagKey)) ?? null;
+  }
+  setKillSwitch(flagKey, enabled) {
+    const started = monotonicNow();
+    if (enabled) {
+      this.killSwitches.add(flagKey);
+    } else {
+      this.killSwitches.delete(flagKey);
+    }
+    const elapsed = monotonicNow() - started;
+    this.emitMetric("ff_killswitch_apply_latency_ms", elapsed, {
+      env: this.envKey,
+      result: enabled ? "enabled" : "disabled"
+    });
+    this.emit("update", { changedKeys: [flagKey], source: "realtime" });
+    void this.persistCache();
+  }
+  async fetchEvalFromNetwork(flagKey, normalizedUser, defaultValue) {
+    const response = this.sdkKey ? await this.fetchWithRetry(
+      `${this.apiBaseUrl}/api/v1/sdk/eval`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-featureflare-sdk-key": this.sdkKey
+        },
+        body: JSON.stringify({
+          flagKey,
+          user: normalizedUser,
+          defaultValue,
+          expectedEnvKey: this.expectedEnvKey ?? void 0
+        })
+      },
+      "network"
+    ) : await this.fetchWithRetry(
+      `${this.apiBaseUrl}/api/v1/eval`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectKey: this.projectKey,
+          envKey: this.envKey,
+          flagKey,
+          user: normalizedUser,
+          defaultValue
+        })
+      },
+      "network"
+    );
+    if (!response.ok) {
+      if (!isRetriableStatus(response.status)) {
+        this.setCircuitState(true, `http_${response.status}`);
+      }
+      return null;
+    }
+    const json = await response.json();
+    const value = typeof json.value === "boolean" ? json.value : defaultValue;
+    if (json.killSwitch === true) {
+      this.killSwitches.add(flagKey);
+    }
+    const revision = json.revision ?? this.revision;
+    this.revision = Math.max(this.revision, revision);
+    this.setCacheItem(flagKey, value, "network", revision);
+    this.setCircuitState(false);
+    void this.persistCache();
+    this.emit("update", { changedKeys: [flagKey], source: "network" });
+    return value;
+  }
+  async fetchFlagsFromNetwork(normalizedUser, defaultValue, transport) {
     if (!this.sdkKey) {
-      throw new Error("FeatureFlareClient.flags requires sdkKey. Legacy projectKey mode does not support listing all flags.");
+      return null;
     }
+    const started = monotonicNow();
+    try {
+      const response = await this.fetchWithRetry(
+        `${this.apiBaseUrl}/api/v1/sdk/flags`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-featureflare-sdk-key": this.sdkKey
+          },
+          body: JSON.stringify({
+            user: normalizedUser,
+            defaultValue,
+            expectedEnvKey: this.expectedEnvKey ?? void 0
+          })
+        },
+        transport
+      );
+      if (!response.ok) {
+        if (!isRetriableStatus(response.status)) {
+          this.setCircuitState(true, `http_${response.status}`);
+        }
+        return null;
+      }
+      const json = await response.json();
+      const list = normalizeBoolMap(json);
+      const revision = json.revision ?? this.revision;
+      this.revision = Math.max(this.revision, revision);
+      if (Array.isArray(json.killSwitches)) {
+        for (const key of json.killSwitches) {
+          this.killSwitches.add(key);
+        }
+      }
+      const changed = /* @__PURE__ */ new Set();
+      for (const entry of list) {
+        const existing = this.cache.get(this.getCacheKey(entry.key));
+        if (!existing || existing.value !== entry.value || existing.revision !== revision) {
+          changed.add(entry.key);
+        }
+        this.setCacheItem(entry.key, entry.value, "network", revision);
+      }
+      if (changed.size > 0) {
+        this.emit("update", { changedKeys: [...changed], source: "network" });
+      }
+      this.setCircuitState(false);
+      void this.persistCache();
+      this.emitMetric("ff_revalidate_latency_ms", monotonicNow() - started, {
+        env: this.envKey,
+        transport
+      });
+      return list;
+    } catch {
+      this.emitMetric("ff_revalidate_latency_ms", monotonicNow() - started, {
+        env: this.envKey,
+        transport,
+        result: "error"
+      });
+      return null;
+    }
+  }
+  revalidate(normalizedUser, defaultValue) {
+    const existing = this.inFlightRevalidate.get(this.envKey);
+    if (existing) return existing;
+    const promise = this.fetchFlagsFromNetwork(normalizedUser, defaultValue, "network").finally(() => {
+      this.inFlightRevalidate.delete(this.envKey);
+    });
+    this.inFlightRevalidate.set(this.envKey, promise);
+    return promise;
+  }
+  async evaluate(flagKey, user, defaultValue = false) {
+    const started = monotonicNow();
+    await this.ensurePersistentLoaded();
     const normalizedUser = this.normalizeUser(user);
-    const res = await fetch(`${this.apiBaseUrl}/api/v1/sdk/flags`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "x-featureflare-sdk-key": this.sdkKey
-      },
-      body: JSON.stringify({
-        user: normalizedUser,
-        defaultValue,
-        expectedEnvKey: this.expectedEnvKey ?? void 0
-      })
+    this.lastUser = normalizedUser;
+    this.lastDefaultValue = defaultValue;
+    if (this.killSwitches.has(flagKey)) {
+      const metadata2 = {
+        reason: "kill_switch",
+        isStale: false,
+        latencyMs: monotonicNow() - started,
+        source: "kill_switch"
+      };
+      this.emitMetric("ff_eval_latency_ms", metadata2.latencyMs, {
+        env: this.envKey,
+        source: metadata2.source,
+        result: "disabled"
+      });
+      this.diagnostics.set(this.getCacheKey(flagKey), metadata2);
+      return { value: false, metadata: metadata2 };
+    }
+    const cacheItem = this.cache.get(this.getCacheKey(flagKey));
+    const cacheState = this.getCacheState(cacheItem);
+    if (cacheItem && cacheState === "fresh") {
+      const metadata2 = {
+        reason: cacheItem.source === "bootstrap" || cacheItem.source === "persistent" ? "bootstrap" : "fresh_cache",
+        isStale: false,
+        latencyMs: monotonicNow() - started,
+        source: cacheItem.source,
+        updatedAt: cacheItem.updatedAt,
+        staleAt: cacheItem.staleAt,
+        expiresAt: cacheItem.expiresAt
+      };
+      this.emitMetric("ff_cache_hit_ratio", 1, { env: this.envKey, source: metadata2.reason });
+      this.emitMetric("ff_eval_latency_ms", metadata2.latencyMs, {
+        env: this.envKey,
+        source: metadata2.source,
+        result: "cache_hit"
+      });
+      this.diagnostics.set(this.getCacheKey(flagKey), metadata2);
+      return { value: cacheItem.value, metadata: metadata2 };
+    }
+    if (cacheItem && cacheState === "stale") {
+      void this.revalidate(normalizedUser, defaultValue);
+      const metadata2 = {
+        reason: "stale_cache",
+        isStale: true,
+        latencyMs: monotonicNow() - started,
+        source: cacheItem.source,
+        updatedAt: cacheItem.updatedAt,
+        staleAt: cacheItem.staleAt,
+        expiresAt: cacheItem.expiresAt
+      };
+      this.emitMetric("ff_cache_hit_ratio", 1, { env: this.envKey, source: metadata2.reason });
+      this.emitMetric("ff_eval_latency_ms", metadata2.latencyMs, {
+        env: this.envKey,
+        source: metadata2.source,
+        result: "stale"
+      });
+      this.diagnostics.set(this.getCacheKey(flagKey), metadata2);
+      return { value: cacheItem.value, metadata: metadata2 };
+    }
+    if (cacheItem && (cacheItem.source === "bootstrap" || cacheItem.source === "persistent")) {
+      void this.revalidate(normalizedUser, defaultValue);
+      const metadata2 = {
+        reason: "bootstrap",
+        isStale: true,
+        latencyMs: monotonicNow() - started,
+        source: cacheItem.source,
+        updatedAt: cacheItem.updatedAt,
+        staleAt: cacheItem.staleAt,
+        expiresAt: cacheItem.expiresAt
+      };
+      this.emitMetric("ff_cache_hit_ratio", 1, { env: this.envKey, source: metadata2.reason });
+      this.emitMetric("ff_eval_latency_ms", metadata2.latencyMs, {
+        env: this.envKey,
+        source: metadata2.source,
+        result: "bootstrap"
+      });
+      this.diagnostics.set(this.getCacheKey(flagKey), metadata2);
+      return { value: cacheItem.value, metadata: metadata2 };
+    }
+    try {
+      const networkValue = await this.fetchEvalFromNetwork(flagKey, normalizedUser, defaultValue);
+      if (networkValue !== null) {
+        const item = this.cache.get(this.getCacheKey(flagKey));
+        const metadata2 = {
+          reason: "network",
+          isStale: false,
+          latencyMs: monotonicNow() - started,
+          source: "network",
+          updatedAt: item?.updatedAt,
+          staleAt: item?.staleAt,
+          expiresAt: item?.expiresAt
+        };
+        this.emitMetric("ff_cache_hit_ratio", 0, { env: this.envKey, source: metadata2.reason });
+        this.emitMetric("ff_eval_latency_ms", metadata2.latencyMs, {
+          env: this.envKey,
+          source: metadata2.source,
+          result: "network"
+        });
+        this.diagnostics.set(this.getCacheKey(flagKey), metadata2);
+        return { value: networkValue, metadata: metadata2 };
+      }
+    } catch {
+    }
+    const metadata = {
+      reason: "default",
+      isStale: false,
+      latencyMs: monotonicNow() - started,
+      source: "default"
+    };
+    this.emitMetric("ff_cache_hit_ratio", 0, { env: this.envKey, source: metadata.reason });
+    this.emitMetric("ff_eval_latency_ms", metadata.latencyMs, {
+      env: this.envKey,
+      source: metadata.source,
+      result: "default"
+    });
+    this.diagnostics.set(this.getCacheKey(flagKey), metadata);
+    return { value: defaultValue, metadata };
+  }
+  async bool(flagKey, user, defaultValue = false) {
+    const result = await this.evaluate(flagKey, user, defaultValue);
+    return result.value;
+  }
+  async flags(user, defaultValue = false) {
+    await this.ensurePersistentLoaded();
+    const normalizedUser = this.normalizeUser(user);
+    this.lastUser = normalizedUser;
+    this.lastDefaultValue = defaultValue;
+    const list = await this.revalidate(normalizedUser, defaultValue);
+    if (list && list.length > 0) {
+      return list.map((entry) => ({
+        key: entry.key,
+        value: this.killSwitches.has(entry.key) ? false : entry.value
+      }));
+    }
+    const cached = this.collectCachedFlags();
+    if (cached.length > 0) return cached;
+    return [];
+  }
+  applyRealtimeMessage(message) {
+    if (typeof message.revision === "number" && message.revision < this.revision) {
+      return;
+    }
+    if (typeof message.revision === "number") {
+      this.revision = message.revision;
+    }
+    const changed = /* @__PURE__ */ new Set();
+    const now = Date.now();
+    if (message.type === "flag.updated") {
+      const flagKey = typeof message.data?.flagKey === "string" ? message.data.flagKey : null;
+      const value = typeof message.data?.value === "boolean" ? message.data.value : null;
+      if (flagKey !== null && value !== null) {
+        this.setCacheItem(flagKey, value, "realtime", message.revision ?? this.revision, now);
+        changed.add(flagKey);
+      }
+    }
+    if (message.type === "flag.deleted") {
+      const flagKey = typeof message.data?.flagKey === "string" ? message.data.flagKey : null;
+      if (flagKey !== null) {
+        this.cache.delete(this.getCacheKey(flagKey));
+        changed.add(flagKey);
+      }
+    }
+    if (message.type === "env.kill_switch.updated") {
+      const started = monotonicNow();
+      const flagKey = typeof message.data?.flagKey === "string" ? message.data.flagKey : null;
+      const enabled = typeof message.data?.enabled === "boolean" ? message.data.enabled : true;
+      if (flagKey !== null) {
+        if (enabled) {
+          this.killSwitches.add(flagKey);
+        } else {
+          this.killSwitches.delete(flagKey);
+        }
+        changed.add(flagKey);
+        this.emitMetric("ff_killswitch_apply_latency_ms", monotonicNow() - started, {
+          env: this.envKey,
+          transport: this.eventSource ? "sse" : "polling",
+          result: enabled ? "enabled" : "disabled"
+        });
+      }
+    }
+    if (message.type === "snapshot.invalidate" && this.lastUser) {
+      void this.revalidate(this.lastUser, this.lastDefaultValue);
+    }
+    const eventLagMs = Math.max(0, Date.now() - (message.timestamp ?? Date.now()));
+    this.emitMetric("ff_realtime_lag_ms", eventLagMs, {
+      env: this.envKey,
+      transport: this.eventSource ? "sse" : "polling"
     });
-    if (!res.ok) return [];
-    const json = await res.json();
-    if (Array.isArray(json.flags)) {
-      return json.flags.filter(
-        (entry) => !!entry && typeof entry.key === "string" && typeof entry.value === "boolean"
-      ).map((entry) => ({ key: entry.key, value: entry.value }));
+    if (changed.size > 0) {
+      this.emit("update", { changedKeys: [...changed], source: "realtime" });
+      void this.persistCache();
     }
-    const values = json.values ?? {};
-    return Object.entries(values).map(([key, value]) => ({ key, value: Boolean(value) }));
+  }
+  startPolling() {
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    const tick = async () => {
+      if (!this.lastUser) {
+        this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+        return;
+      }
+      await this.fetchFlagsFromNetwork(this.lastUser, this.lastDefaultValue, "polling");
+      this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+    };
+    this.pollTimer = setTimeout(tick, this.realtimePollingMs);
+  }
+  connectSse(attempt = 0) {
+    const EventSourceImpl = typeof EventSource !== "undefined" ? EventSource : null;
+    if (!EventSourceImpl || !this.sdkKey) {
+      this.emit("connectionState", { state: "degraded", transport: "polling" });
+      this.startPolling();
+      return;
+    }
+    const url = new URL(this.realtimeSsePath, this.apiBaseUrl);
+    url.searchParams.set("sdkKey", this.sdkKey);
+    url.searchParams.set("envKey", this.envKey);
+    this.eventSource = new EventSourceImpl(url.toString());
+    this.eventSource.onopen = () => {
+      this.emit("connectionState", { state: "connected", transport: "sse" });
+      if (this.pollTimer) {
+        clearTimeout(this.pollTimer);
+        this.pollTimer = null;
+      }
+    };
+    this.eventSource.onmessage = (event) => {
+      try {
+        const payload = JSON.parse(String(event.data));
+        this.applyRealtimeMessage(payload);
+      } catch {
+      }
+    };
+    this.eventSource.onerror = () => {
+      this.emit("connectionState", { state: "degraded", transport: "polling" });
+      this.eventSource?.close();
+      this.eventSource = null;
+      this.startPolling();
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+      }
+      const backoff = Math.min(this.backoffMs * (attempt + 1), 3e4);
+      this.reconnectTimer = setTimeout(() => {
+        this.connectSse(attempt + 1);
+      }, backoff);
+    };
+  }
+  startRealtime() {
+    this.realtimeEnabled = true;
+    this.connectSse(0);
+  }
+  stopRealtime() {
+    this.realtimeEnabled = false;
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.emit("connectionState", { state: "offline", transport: "none" });
+  }
+  dispose() {
+    this.stopRealtime();
+    this.listeners.update.clear();
+    this.listeners.circuitOpen.clear();
+    this.listeners.circuitClose.clear();
+    this.listeners.connectionState.clear();
   }
 };
 
 exports.FeatureFlareClient = FeatureFlareClient;
+exports.InMemoryMetricsCollector = InMemoryMetricsCollector;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map