@mergedapp/feature-flags 0.1.0

package/dist/index.cjs

@@ -0,0 +1,897 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  FeatureFlagError: () => FeatureFlagError,
+  FeatureFlagNetworkError: () => FeatureFlagNetworkError,
+  FeatureFlagVerificationError: () => FeatureFlagVerificationError,
+  MergedFeatureFlags: () => MergedFeatureFlags,
+  createDefaultFeatureFlagRuntimeStatus: () => createDefaultFeatureFlagRuntimeStatus,
+  createFileFeatureFlagSnapshotStore: () => createFileFeatureFlagSnapshotStore,
+  createLocalStorageFeatureFlagSnapshotStore: () => createLocalStorageFeatureFlagSnapshotStore
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+var FeatureFlagError = class extends Error {
+  static {
+    __name(this, "FeatureFlagError");
+  }
+  constructor(message, options) {
+    super(message, options);
+    this.name = "FeatureFlagError";
+  }
+};
+var FeatureFlagNetworkError = class extends FeatureFlagError {
+  static {
+    __name(this, "FeatureFlagNetworkError");
+  }
+  constructor(message, options) {
+    super(message, options);
+    this.name = "FeatureFlagNetworkError";
+  }
+};
+var FeatureFlagVerificationError = class extends FeatureFlagError {
+  static {
+    __name(this, "FeatureFlagVerificationError");
+  }
+  constructor(message, options) {
+    super(message, options);
+    this.name = "FeatureFlagVerificationError";
+  }
+};
+
+// src/persistence.ts
+var DEFAULT_SNAPSHOT_KEY_PREFIX = "merged-feature-flags";
+var SNAPSHOT_SCHEMA_VERSION = 1;
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+var nodeModulePromise = null;
+async function getNodeModules() {
+  if (!nodeModulePromise) {
+    nodeModulePromise = Promise.all([
+      import("crypto"),
+      import("fs/promises"),
+      import("os"),
+      import("path")
+    ]).then(([crypto, fs, os, path]) => ({
+      crypto,
+      fs,
+      os,
+      path
+    }));
+  }
+  return nodeModulePromise;
+}
+__name(getNodeModules, "getNodeModules");
+function normalizeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue(item));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entryValue]) => [
+      key,
+      normalizeValue(entryValue)
+    ]);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+__name(normalizeValue, "normalizeValue");
+function serializeCanonicalValue(value) {
+  return JSON.stringify(normalizeValue(value));
+}
+__name(serializeCanonicalValue, "serializeCanonicalValue");
+function createDefaultFeatureFlagRuntimeStatus() {
+  return {
+    source: "defaults",
+    isStale: false,
+    lastSuccessfulRefreshAt: null,
+    tokenExpiresAt: null,
+    lastError: null
+  };
+}
+__name(createDefaultFeatureFlagRuntimeStatus, "createDefaultFeatureFlagRuntimeStatus");
+async function sha256Hex(value) {
+  if (globalThis.crypto?.subtle) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", textEncoder.encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  const { crypto } = await getNodeModules();
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+__name(sha256Hex, "sha256Hex");
+async function buildSnapshotScopeParts(params) {
+  const contextHash = await sha256Hex(serializeCanonicalValue(params.config.evaluationContext ?? null));
+  const clientKeyFingerprint = await sha256Hex(params.config.clientKey);
+  const prefix = params.keyPrefix?.trim() || DEFAULT_SNAPSHOT_KEY_PREFIX;
+  const scopeMaterial = serializeCanonicalValue({
+    apiUrl: params.config.apiUrl.replace(/\/$/, ""),
+    organizationId: params.config.organizationId.trim(),
+    environmentId: params.config.environmentId.trim(),
+    teamId: params.config.teamId?.trim() || null,
+    clientKeyFingerprint,
+    contextHash
+  });
+  return {
+    scopeKey: `${prefix}:${await sha256Hex(scopeMaterial)}`,
+    organizationId: params.config.organizationId.trim(),
+    environmentId: params.config.environmentId.trim(),
+    teamId: params.config.teamId?.trim() || null,
+    clientKeyFingerprint,
+    contextHash
+  };
+}
+__name(buildSnapshotScopeParts, "buildSnapshotScopeParts");
+function buildSnapshotRecord(params) {
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    scopeKey: params.scope.scopeKey,
+    organizationId: params.scope.organizationId,
+    environmentId: params.scope.environmentId,
+    teamId: params.scope.teamId,
+    clientKeyFingerprint: params.scope.clientKeyFingerprint,
+    contextHash: params.scope.contextHash,
+    token: params.token,
+    publicKeyPem: params.publicKeyPem,
+    fetchedAt: params.fetchedAt,
+    tokenExpiresAt: params.tokenExpiresAt
+  };
+}
+__name(buildSnapshotRecord, "buildSnapshotRecord");
+function createPersistedFeatureFlagSnapshot(params) {
+  return buildSnapshotRecord(params);
+}
+__name(createPersistedFeatureFlagSnapshot, "createPersistedFeatureFlagSnapshot");
+function doesSnapshotMatchScope(params) {
+  return params.snapshot.schemaVersion === SNAPSHOT_SCHEMA_VERSION && params.snapshot.scopeKey === params.scope.scopeKey && params.snapshot.organizationId === params.scope.organizationId && params.snapshot.environmentId === params.scope.environmentId && params.snapshot.teamId === params.scope.teamId && params.snapshot.clientKeyFingerprint === params.scope.clientKeyFingerprint && params.snapshot.contextHash === params.scope.contextHash;
+}
+__name(doesSnapshotMatchScope, "doesSnapshotMatchScope");
+function isBrowserPersistenceAvailable() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+__name(isBrowserPersistenceAvailable, "isBrowserPersistenceAvailable");
+function createLocalStorageFeatureFlagSnapshotStore() {
+  return {
+    async load(key) {
+      if (!isBrowserPersistenceAvailable()) {
+        return null;
+      }
+      try {
+        const raw = window.localStorage.getItem(key);
+        return raw ? JSON.parse(raw) : null;
+      } catch {
+        return null;
+      }
+    },
+    async save(key, snapshot) {
+      if (!isBrowserPersistenceAvailable()) {
+        return;
+      }
+      try {
+        window.localStorage.setItem(key, JSON.stringify(snapshot));
+      } catch {
+      }
+    },
+    async remove(key) {
+      if (!isBrowserPersistenceAvailable()) {
+        return;
+      }
+      try {
+        window.localStorage.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+__name(createLocalStorageFeatureFlagSnapshotStore, "createLocalStorageFeatureFlagSnapshotStore");
+function sanitizeKeyForFilename(key) {
+  return encodeURIComponent(key);
+}
+__name(sanitizeKeyForFilename, "sanitizeKeyForFilename");
+function createFileFeatureFlagSnapshotStore(params) {
+  return {
+    async load(key) {
+      const { fs, os, path } = await getNodeModules();
+      const rootDirectory = params?.rootDirectory ?? path.join(os.tmpdir(), DEFAULT_SNAPSHOT_KEY_PREFIX);
+      const filePath = path.join(rootDirectory, `${sanitizeKeyForFilename(key)}.json`);
+      try {
+        const raw = await fs.readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async save(key, snapshot) {
+      const { fs, os, path } = await getNodeModules();
+      const rootDirectory = params?.rootDirectory ?? path.join(os.tmpdir(), DEFAULT_SNAPSHOT_KEY_PREFIX);
+      const filePath = path.join(rootDirectory, `${sanitizeKeyForFilename(key)}.json`);
+      const tempFilePath = path.join(rootDirectory, `${sanitizeKeyForFilename(key)}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+      await fs.mkdir(rootDirectory, {
+        recursive: true
+      });
+      await fs.writeFile(tempFilePath, JSON.stringify(snapshot), "utf-8");
+      await fs.rename(tempFilePath, filePath);
+    },
+    async remove(key) {
+      const { fs, os, path } = await getNodeModules();
+      const rootDirectory = params?.rootDirectory ?? path.join(os.tmpdir(), DEFAULT_SNAPSHOT_KEY_PREFIX);
+      const filePath = path.join(rootDirectory, `${sanitizeKeyForFilename(key)}.json`);
+      try {
+        await fs.rm(filePath, {
+          force: true
+        });
+      } catch {
+      }
+    }
+  };
+}
+__name(createFileFeatureFlagSnapshotStore, "createFileFeatureFlagSnapshotStore");
+async function resolveSnapshotStore(params) {
+  const persistence = params.config.snapshotPersistence;
+  if (persistence === false) {
+    return null;
+  }
+  if (persistence?.store) {
+    return persistence.store;
+  }
+  if (isBrowserPersistenceAvailable()) {
+    return createLocalStorageFeatureFlagSnapshotStore();
+  }
+  return createFileFeatureFlagSnapshotStore();
+}
+__name(resolveSnapshotStore, "resolveSnapshotStore");
+function getSnapshotKeyPrefix(params) {
+  const persistence = params.config.snapshotPersistence;
+  return persistence?.keyPrefix?.trim() || DEFAULT_SNAPSHOT_KEY_PREFIX;
+}
+__name(getSnapshotKeyPrefix, "getSnapshotKeyPrefix");
+
+// src/jwt.ts
+var import_jose = require("jose");
+var JWT_ALGORITHM = "ES256";
+var JWT_ISSUER = "merged";
+var JWT_TYPE = "feature_flag_values";
+var cachedKey = null;
+var cachedPem = null;
+async function importPublicKey(pem) {
+  if (cachedPem === pem && cachedKey) {
+    return cachedKey;
+  }
+  try {
+    cachedKey = await (0, import_jose.importSPKI)(pem, JWT_ALGORITHM);
+    cachedPem = pem;
+    return cachedKey;
+  } catch (error) {
+    cachedKey = null;
+    cachedPem = null;
+    throw new FeatureFlagVerificationError("Failed to import public key.", {
+      cause: error
+    });
+  }
+}
+__name(importPublicKey, "importPublicKey");
+function resetPublicKeyCache() {
+  cachedKey = null;
+  cachedPem = null;
+}
+__name(resetPublicKeyCache, "resetPublicKeyCache");
+async function verifyFeatureFlagTokenDetailed(params) {
+  try {
+    if (!params.allowExpired) {
+      const { payload: payload2 } = await (0, import_jose.jwtVerify)(params.token, params.publicKey, {
+        algorithms: [
+          JWT_ALGORITHM
+        ],
+        issuer: JWT_ISSUER
+      });
+      return extractVerifiedTokenPayload(payload2);
+    }
+    const { payload } = await (0, import_jose.compactVerify)(params.token, params.publicKey, {
+      algorithms: [
+        JWT_ALGORITHM
+      ]
+    });
+    const rawPayload = JSON.parse(new TextDecoder().decode(payload));
+    const notBefore = rawPayload.nbf;
+    if (typeof notBefore === "number" && Number.isFinite(notBefore) && Math.floor(Date.now() / 1e3) < notBefore) {
+      throw new FeatureFlagVerificationError("JWT payload is not yet valid.");
+    }
+    return extractVerifiedTokenPayload(rawPayload);
+  } catch (error) {
+    if (error instanceof FeatureFlagVerificationError) {
+      throw error;
+    }
+    throw new FeatureFlagVerificationError("JWT verification failed.", {
+      cause: error
+    });
+  }
+}
+__name(verifyFeatureFlagTokenDetailed, "verifyFeatureFlagTokenDetailed");
+function extractVerifiedTokenPayload(payload) {
+  if (payload.iss !== JWT_ISSUER) {
+    throw new FeatureFlagVerificationError("JWT payload has an unexpected issuer.");
+  }
+  if (payload.type !== JWT_TYPE) {
+    throw new FeatureFlagVerificationError("JWT payload has an unexpected token type.");
+  }
+  const flags = payload.flags;
+  if (!Array.isArray(flags)) {
+    throw new FeatureFlagVerificationError("JWT payload does not contain a flags array.");
+  }
+  const expiresAt = typeof payload.exp === "number" && Number.isFinite(payload.exp) ? new Date(payload.exp * 1e3).toISOString() : null;
+  return {
+    flags,
+    expiresAt
+  };
+}
+__name(extractVerifiedTokenPayload, "extractVerifiedTokenPayload");
+
+// src/client.ts
+var DEFAULT_REFRESH_INTERVAL_MS = 6e4;
+var BACKOFF_BASE_MS = 5e3;
+var BACKOFF_CAP_MS = 3e5;
+var MergedFeatureFlags = class {
+  static {
+    __name(this, "MergedFeatureFlags");
+  }
+  flagsById = /* @__PURE__ */ new Map();
+  flagsByName = /* @__PURE__ */ new Map();
+  publicKeyPem;
+  publicKeyCrypto = null;
+  refreshTimer = null;
+  backoffMs = 0;
+  consecutiveFailures = 0;
+  listeners = /* @__PURE__ */ new Set();
+  storeListeners = /* @__PURE__ */ new Set();
+  initialized = false;
+  visibilityHandler = null;
+  pendingScopeTransition = false;
+  runtimeStatus = createDefaultFeatureFlagRuntimeStatus();
+  snapshotStorePromise = null;
+  keyPrefix;
+  contextSignature;
+  flagIds;
+  clientKey;
+  apiUrl;
+  organizationId;
+  environmentId;
+  teamId;
+  refreshInterval;
+  onError;
+  onFlagsChanged;
+  snapshotPersistence;
+  evaluationContext;
+  constructor(config) {
+    this.flagIds = config.flagIds ?? null;
+    this.clientKey = config.clientKey;
+    this.apiUrl = config.apiUrl.replace(/\/$/, "");
+    this.organizationId = config.organizationId.trim();
+    this.environmentId = config.environmentId.trim();
+    this.teamId = config.teamId?.trim() || null;
+    this.publicKeyPem = config.publicKey ?? null;
+    this.refreshInterval = config.refreshInterval ?? DEFAULT_REFRESH_INTERVAL_MS;
+    this.onError = config.onError ?? null;
+    this.onFlagsChanged = config.onFlagsChanged ?? null;
+    this.snapshotPersistence = config.snapshotPersistence;
+    this.evaluationContext = config.evaluationContext ?? null;
+    this.contextSignature = serializeCanonicalValue(this.evaluationContext ?? null);
+    this.keyPrefix = getSnapshotKeyPrefix({
+      config
+    });
+    if (!this.organizationId) {
+      throw new TypeError("organizationId is required.");
+    }
+    if (!this.environmentId) {
+      throw new TypeError("environmentId is required.");
+    }
+  }
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    try {
+      const restored = await this.restorePersistedSnapshot().catch(() => false);
+      try {
+        await this.refresh();
+      } catch {
+        if (!restored) {
+          this.clearFlags();
+          this.setRuntimeStatus({
+            source: "defaults",
+            tokenExpiresAt: null
+          });
+          this.emitChange({
+            flagsChanged: true,
+            storeChanged: true
+          });
+        }
+      }
+    } finally {
+      if (this.refreshInterval > 0) {
+        this.startPolling();
+      }
+    }
+  }
+  /** Returns true if the flag is enabled. Returns false for unknown flags. */
+  isEnabled(name) {
+    return this.resolveFlag(name)?.enabled ?? false;
+  }
+  /** Returns the flag's value with the type inferred from the flag registry. */
+  getValue(name) {
+    const flag = this.resolveFlag(name);
+    return flag?.value;
+  }
+  /** Returns the full evaluated flag entry, or undefined if not found. */
+  getFlag(name) {
+    return this.resolveFlag(name);
+  }
+  /** Returns all evaluated flags. */
+  getAllFlags() {
+    return Array.from(this.flagsById.values());
+  }
+  getStatus() {
+    const tokenExpiresAt = this.runtimeStatus.tokenExpiresAt;
+    const isStale = tokenExpiresAt != null && Number.isFinite(new Date(tokenExpiresAt).getTime()) && new Date(tokenExpiresAt).getTime() <= Date.now();
+    return {
+      ...this.runtimeStatus,
+      isStale
+    };
+  }
+  getStatusSnapshot() {
+    return this.getStatus();
+  }
+  /** Manually trigger a refresh from the server. */
+  async refresh() {
+    const restoredForCurrentScope = this.pendingScopeTransition ? await this.restorePersistedSnapshot().catch(() => false) : false;
+    try {
+      await this.ensureVerificationKey();
+      const response = await this.fetchSignedFlags();
+      const verifiedFlags = await this.verifyWithRetry(response.token);
+      const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const flagsChanged = this.updateFlags(verifiedFlags.flags);
+      this.resetBackoff();
+      this.pendingScopeTransition = false;
+      this.setRuntimeStatus({
+        source: "network",
+        tokenExpiresAt: verifiedFlags.expiresAt,
+        lastSuccessfulRefreshAt: fetchedAt,
+        lastError: null
+      });
+      await this.persistSnapshot({
+        fetchedAt,
+        token: response.token,
+        tokenExpiresAt: verifiedFlags.expiresAt
+      });
+      this.emitChange({
+        flagsChanged,
+        storeChanged: true
+      });
+    } catch (error) {
+      this.incrementBackoff();
+      const wrappedError = error instanceof Error ? error : new FeatureFlagNetworkError("Unknown error during refresh.");
+      if (this.pendingScopeTransition && !restoredForCurrentScope) {
+        const hadFlags = this.flagsById.size > 0;
+        this.clearFlags();
+        this.pendingScopeTransition = false;
+        this.setRuntimeStatus({
+          source: "defaults",
+          tokenExpiresAt: null,
+          lastSuccessfulRefreshAt: null,
+          lastError: wrappedError
+        });
+        this.emitChange({
+          flagsChanged: hadFlags,
+          storeChanged: true
+        });
+      } else {
+        this.setRuntimeStatus({
+          lastError: wrappedError
+        });
+        this.emitChange({
+          flagsChanged: false,
+          storeChanged: true
+        });
+      }
+      this.onError?.(wrappedError);
+      throw wrappedError;
+    }
+  }
+  /** Subscribe to flag changes. Returns an unsubscribe function. */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Get a snapshot function for useSyncExternalStore. */
+  getSnapshot() {
+    return this.getAllFlags();
+  }
+  /** Replace the caller-provided evaluation context used on subsequent refreshes. */
+  setEvaluationContext(context) {
+    const nextContext = context ?? null;
+    const nextSignature = serializeCanonicalValue(nextContext ?? null);
+    if (nextSignature === this.contextSignature) {
+      this.evaluationContext = nextContext;
+      return;
+    }
+    this.evaluationContext = nextContext;
+    this.contextSignature = nextSignature;
+    this.pendingScopeTransition = true;
+  }
+  /** Subscribe function for useSyncExternalStore. */
+  subscribe(onStoreChange) {
+    this.storeListeners.add(onStoreChange);
+    return () => {
+      this.storeListeners.delete(onStoreChange);
+    };
+  }
+  /** Clean up timers, listeners, and cached data. */
+  destroy() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    this.listeners.clear();
+    this.storeListeners.clear();
+    this.clearFlags();
+    this.pendingScopeTransition = false;
+    this.runtimeStatus = createDefaultFeatureFlagRuntimeStatus();
+    this.initialized = false;
+  }
+  resolveFlag(name) {
+    if (this.flagIds && name in this.flagIds) {
+      const id = this.flagIds[name];
+      return this.flagsById.get(id);
+    }
+    return this.flagsById.get(name) ?? this.flagsByName.get(name);
+  }
+  clearFlags() {
+    this.flagsById.clear();
+    this.flagsByName.clear();
+  }
+  emitChange(params) {
+    const allFlags = this.getAllFlags();
+    if (params.flagsChanged) {
+      this.onFlagsChanged?.(allFlags);
+      for (const listener of this.listeners) {
+        listener(allFlags);
+      }
+    }
+    if (params.storeChanged) {
+      for (const listener of this.storeListeners) {
+        listener();
+      }
+    }
+  }
+  updateFlags(flags) {
+    const oldFlags = new Map(this.flagsById);
+    this.clearFlags();
+    for (const flag of flags) {
+      this.flagsById.set(flag.id, flag);
+      this.flagsByName.set(flag.name, flag);
+    }
+    return this.hasFlagsChanged(oldFlags, this.flagsById);
+  }
+  hasFlagsChanged(oldFlags, newFlags) {
+    if (oldFlags.size !== newFlags.size) {
+      return true;
+    }
+    for (const [id, newFlag] of newFlags) {
+      const oldFlag = oldFlags.get(id);
+      if (!oldFlag) {
+        return true;
+      }
+      if (oldFlag.enabled !== newFlag.enabled || oldFlag.name !== newFlag.name || JSON.stringify(oldFlag.value) !== JSON.stringify(newFlag.value)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  setRuntimeStatus(patch) {
+    this.runtimeStatus = {
+      ...this.runtimeStatus,
+      ...patch
+    };
+  }
+  async fetchSignedFlags() {
+    const url = new URL("/api/feature-flags/evaluate/signed", this.apiUrl);
+    const payload = {
+      organizationId: this.organizationId,
+      environmentId: this.environmentId,
+      ...this.teamId ? {
+        teamId: this.teamId
+      } : {},
+      ...this.evaluationContext ? {
+        context: this.evaluationContext
+      } : {}
+    };
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.clientKey}`,
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        },
+        body: JSON.stringify(payload)
+      });
+    } catch (error) {
+      throw new FeatureFlagNetworkError("Failed to fetch feature flags.", {
+        cause: error
+      });
+    }
+    if (!response.ok) {
+      throw new FeatureFlagNetworkError(`Feature flag API returned ${response.status}: ${response.statusText}`);
+    }
+    return await response.json();
+  }
+  async fetchPublicKey() {
+    const url = `${this.apiUrl}/api/feature-flags/public-key`;
+    let response;
+    try {
+      response = await fetch(url);
+    } catch (error) {
+      throw new FeatureFlagNetworkError("Failed to fetch public key.", {
+        cause: error
+      });
+    }
+    if (!response.ok) {
+      throw new FeatureFlagNetworkError(`Public key endpoint returned ${response.status}: ${response.statusText}`);
+    }
+    const body = await response.json();
+    return body.publicKey;
+  }
+  async verifyWithRetry(token) {
+    try {
+      return await verifyFeatureFlagTokenDetailed({
+        token,
+        publicKey: this.publicKeyCrypto
+      });
+    } catch (error) {
+      if (!(error instanceof FeatureFlagVerificationError)) {
+        throw error;
+      }
+      resetPublicKeyCache();
+      this.publicKeyPem = await this.fetchPublicKey();
+      this.publicKeyCrypto = await importPublicKey(this.publicKeyPem);
+      return verifyFeatureFlagTokenDetailed({
+        token,
+        publicKey: this.publicKeyCrypto
+      });
+    }
+  }
+  async ensureVerificationKey() {
+    if (!this.publicKeyPem) {
+      this.publicKeyPem = await this.fetchPublicKey();
+    }
+    if (!this.publicKeyCrypto) {
+      this.publicKeyCrypto = await importPublicKey(this.publicKeyPem);
+    }
+  }
+  async getTrustedSnapshotVerificationKey() {
+    if (this.publicKeyPem) {
+      if (!this.publicKeyCrypto) {
+        this.publicKeyCrypto = await importPublicKey(this.publicKeyPem);
+      }
+      return {
+        publicKeyCrypto: this.publicKeyCrypto,
+        publicKeyPem: this.publicKeyPem
+      };
+    }
+    try {
+      await this.ensureVerificationKey();
+    } catch (error) {
+      if (error instanceof FeatureFlagNetworkError) {
+        return null;
+      }
+      throw error;
+    }
+    if (!this.publicKeyPem || !this.publicKeyCrypto) {
+      return null;
+    }
+    return {
+      publicKeyCrypto: this.publicKeyCrypto,
+      publicKeyPem: this.publicKeyPem
+    };
+  }
+  async getSnapshotStore() {
+    if (!this.snapshotStorePromise) {
+      let snapshotPersistence;
+      if (this.snapshotPersistence === void 0) {
+        snapshotPersistence = {
+          keyPrefix: this.keyPrefix
+        };
+      } else if (this.snapshotPersistence === false) {
+        snapshotPersistence = false;
+      } else {
+        snapshotPersistence = {
+          ...this.snapshotPersistence,
+          keyPrefix: this.snapshotPersistence.keyPrefix ?? this.keyPrefix
+        };
+      }
+      this.snapshotStorePromise = resolveSnapshotStore({
+        config: {
+          apiUrl: this.apiUrl,
+          clientKey: this.clientKey,
+          environmentId: this.environmentId,
+          organizationId: this.organizationId,
+          teamId: this.teamId ?? void 0,
+          evaluationContext: this.evaluationContext ?? void 0,
+          snapshotPersistence
+        }
+      });
+    }
+    return this.snapshotStorePromise;
+  }
+  async getScopeParts() {
+    return buildSnapshotScopeParts({
+      config: {
+        apiUrl: this.apiUrl,
+        clientKey: this.clientKey,
+        environmentId: this.environmentId,
+        organizationId: this.organizationId,
+        teamId: this.teamId ?? void 0,
+        evaluationContext: this.evaluationContext ?? void 0
+      },
+      keyPrefix: this.keyPrefix
+    });
+  }
+  async restorePersistedSnapshot() {
+    const store = await this.getSnapshotStore();
+    if (!store) {
+      return false;
+    }
+    const scope = await this.getScopeParts();
+    const snapshot = await store.load(scope.scopeKey);
+    if (!snapshot) {
+      return false;
+    }
+    if (!doesSnapshotMatchScope({
+      snapshot,
+      scope
+    })) {
+      await store.remove(scope.scopeKey);
+      return false;
+    }
+    const trustedKey = await this.getTrustedSnapshotVerificationKey();
+    if (!trustedKey) {
+      return false;
+    }
+    try {
+      const verified = await verifyFeatureFlagTokenDetailed({
+        token: snapshot.token,
+        publicKey: trustedKey.publicKeyCrypto,
+        allowExpired: true
+      });
+      this.publicKeyPem = trustedKey.publicKeyPem;
+      this.publicKeyCrypto = trustedKey.publicKeyCrypto;
+      this.pendingScopeTransition = false;
+      const flagsChanged = this.updateFlags(verified.flags);
+      this.setRuntimeStatus({
+        source: "persisted",
+        tokenExpiresAt: verified.expiresAt,
+        lastSuccessfulRefreshAt: snapshot.fetchedAt,
+        lastError: null
+      });
+      this.emitChange({
+        flagsChanged,
+        storeChanged: true
+      });
+      return true;
+    } catch {
+      await store.remove(scope.scopeKey);
+      return false;
+    }
+  }
+  async persistSnapshot(params) {
+    const store = await this.getSnapshotStore();
+    if (!store || !this.publicKeyPem) {
+      return;
+    }
+    const scope = await this.getScopeParts();
+    const snapshot = createPersistedFeatureFlagSnapshot({
+      scope,
+      token: params.token,
+      publicKeyPem: this.publicKeyPem,
+      fetchedAt: params.fetchedAt,
+      tokenExpiresAt: params.tokenExpiresAt
+    });
+    try {
+      await store.save(scope.scopeKey, snapshot);
+    } catch (error) {
+      const wrappedError = error instanceof Error ? error : new Error("Failed to persist feature flag snapshot.");
+      this.onError?.(wrappedError);
+    }
+  }
+  startPolling() {
+    this.scheduleNextPoll();
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+          if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+          }
+        } else if (document.visibilityState === "visible") {
+          void this.safeRefresh();
+        }
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+  scheduleNextPoll() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+    const delay = this.backoffMs > 0 ? this.backoffMs : this.refreshInterval;
+    this.refreshTimer = setTimeout(() => {
+      void this.safeRefresh();
+    }, delay);
+  }
+  async safeRefresh() {
+    try {
+      await this.refresh();
+    } catch {
+    } finally {
+      const isPageVisible = typeof document === "undefined" || document.visibilityState !== "hidden";
+      if (this.initialized && this.refreshInterval > 0 && isPageVisible) {
+        this.scheduleNextPoll();
+      }
+    }
+  }
+  resetBackoff() {
+    this.backoffMs = 0;
+    this.consecutiveFailures = 0;
+  }
+  incrementBackoff() {
+    this.consecutiveFailures++;
+    this.backoffMs = Math.min(BACKOFF_BASE_MS * 2 ** (this.consecutiveFailures - 1), BACKOFF_CAP_MS);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeatureFlagError,
+  FeatureFlagNetworkError,
+  FeatureFlagVerificationError,
+  MergedFeatureFlags,
+  createDefaultFeatureFlagRuntimeStatus,
+  createFileFeatureFlagSnapshotStore,
+  createLocalStorageFeatureFlagSnapshotStore
+});