@mergedapp/feature-flags 0.1.0

package/dist/react.cjs

@@ -0,0 +1,239 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  FeatureFlagProvider: () => FeatureFlagProvider,
+  createTypedHooks: () => createTypedHooks
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/provider.tsx
+var import_react = require("react");
+var FeatureFlagContext = /* @__PURE__ */ (0, import_react.createContext)(null);
+function createFeatureFlagLoadState(params) {
+  return {
+    status: params.status,
+    isLoading: params.status === "loading",
+    isReady: params.status === "ready",
+    error: params.error ?? params.runtimeStatus.lastError,
+    source: params.runtimeStatus.source,
+    isStale: params.runtimeStatus.isStale,
+    lastSuccessfulRefreshAt: params.runtimeStatus.lastSuccessfulRefreshAt,
+    tokenExpiresAt: params.runtimeStatus.tokenExpiresAt
+  };
+}
+__name(createFeatureFlagLoadState, "createFeatureFlagLoadState");
+function shouldRenderFeatureFlagLoadingFallback(params) {
+  return params.blockUntilReady && params.loadState.isLoading;
+}
+__name(shouldRenderFeatureFlagLoadingFallback, "shouldRenderFeatureFlagLoadingFallback");
+function createSnapshotStore(params) {
+  let cachedFlags = params.initialFlags ?? params.client.getSnapshot();
+  let hasObservedClientUpdate = false;
+  function areSnapshotsEqual(left, right) {
+    if (left.length !== right.length) {
+      return false;
+    }
+    for (let index = 0; index < left.length; index++) {
+      const leftFlag = left[index];
+      const rightFlag = right[index];
+      if (leftFlag?.id !== rightFlag?.id || leftFlag?.name !== rightFlag?.name || leftFlag?.type !== rightFlag?.type || leftFlag?.teamId !== rightFlag?.teamId || leftFlag?.enabled !== rightFlag?.enabled || JSON.stringify(leftFlag?.value) !== JSON.stringify(rightFlag?.value)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  __name(areSnapshotsEqual, "areSnapshotsEqual");
+  return {
+    subscribe(onStoreChange) {
+      return params.client.subscribe(() => {
+        hasObservedClientUpdate = true;
+        onStoreChange();
+      });
+    },
+    getSnapshot() {
+      const current = params.client.getSnapshot();
+      const shouldAdoptClientSnapshot = current.length > 0 || !params.initialFlags || hasObservedClientUpdate;
+      if (shouldAdoptClientSnapshot && !areSnapshotsEqual(current, cachedFlags)) {
+        cachedFlags = current;
+      }
+      return cachedFlags;
+    },
+    getServerSnapshot() {
+      return params.initialFlags ?? [];
+    }
+  };
+}
+__name(createSnapshotStore, "createSnapshotStore");
+function FeatureFlagProvider(props) {
+  const { client, blockUntilReady, loadingFallback, initialFlags, children } = props;
+  const [status, setStatus] = (0, import_react.useState)(initialFlags ? "ready" : "loading");
+  const [error, setError] = (0, import_react.useState)(null);
+  (0, import_react.useEffect)(() => {
+    let isDisposed = false;
+    setStatus(initialFlags ? "ready" : "loading");
+    setError(null);
+    client.initialize().then(() => {
+      if (isDisposed) {
+        return;
+      }
+      setStatus("ready");
+    }).catch((initializationError) => {
+      if (isDisposed) {
+        return;
+      }
+      setStatus("error");
+      setError(initializationError instanceof Error ? initializationError : new Error("Unknown feature flag initialization error."));
+    });
+    return () => {
+      isDisposed = true;
+      client.destroy();
+    };
+  }, [
+    client,
+    initialFlags
+  ]);
+  const snapshotStore = (0, import_react.useMemo)(() => createSnapshotStore({
+    client,
+    initialFlags
+  }), [
+    client,
+    initialFlags
+  ]);
+  const flags = (0, import_react.useSyncExternalStore)(snapshotStore.subscribe, snapshotStore.getSnapshot, snapshotStore.getServerSnapshot);
+  const runtimeStatus = (0, import_react.useSyncExternalStore)(client.subscribe, client.getStatus.bind(client), client.getStatus.bind(client));
+  const loadState = (0, import_react.useMemo)(() => createFeatureFlagLoadState({
+    status,
+    error,
+    runtimeStatus
+  }), [
+    error,
+    runtimeStatus,
+    status
+  ]);
+  const value = (0, import_react.useMemo)(() => ({
+    client,
+    flags,
+    loadState
+  }), [
+    client,
+    flags,
+    loadState
+  ]);
+  if (shouldRenderFeatureFlagLoadingFallback({
+    blockUntilReady,
+    loadState
+  })) {
+    return /* @__PURE__ */ React.createElement(React.Fragment, null, loadingFallback ?? null);
+  }
+  return /* @__PURE__ */ React.createElement(FeatureFlagContext.Provider, {
+    value
+  }, children);
+}
+__name(FeatureFlagProvider, "FeatureFlagProvider");
+
+// src/react/hooks.ts
+var import_react2 = require("react");
+function useFeatureFlagContext() {
+  const context = (0, import_react2.useContext)(FeatureFlagContext);
+  if (!context) {
+    throw new Error("Feature flag hooks and components must be used within a <FeatureFlagProvider>.");
+  }
+  return context;
+}
+__name(useFeatureFlagContext, "useFeatureFlagContext");
+function resolveFlagFromContext(params) {
+  return params.flags.find((flag) => flag.id === params.idOrName || flag.name === params.idOrName) ?? params.client.getFlag(params.idOrName);
+}
+__name(resolveFlagFromContext, "resolveFlagFromContext");
+function useFeatureFlagStatus() {
+  const { loadState } = useFeatureFlagContext();
+  return loadState;
+}
+__name(useFeatureFlagStatus, "useFeatureFlagStatus");
+function createTypedHooks() {
+  function TypedFeatureFlagProvider(props) {
+    return FeatureFlagProvider(props);
+  }
+  __name(TypedFeatureFlagProvider, "TypedFeatureFlagProvider");
+  function typedUseFeatureFlag(name) {
+    const { client, flags } = useFeatureFlagContext();
+    const flag = resolveFlagFromContext({
+      client,
+      flags,
+      idOrName: name
+    });
+    return {
+      enabled: flag?.enabled ?? false,
+      value: flag?.value
+    };
+  }
+  __name(typedUseFeatureFlag, "typedUseFeatureFlag");
+  function typedUseFeatureFlags() {
+    const { flags } = useFeatureFlagContext();
+    return flags;
+  }
+  __name(typedUseFeatureFlags, "typedUseFeatureFlags");
+  function typedUseFeatureFlagClient() {
+    const { client } = useFeatureFlagContext();
+    return client;
+  }
+  __name(typedUseFeatureFlagClient, "typedUseFeatureFlagClient");
+  function typedUseFeatureFlagStatus() {
+    return useFeatureFlagStatus();
+  }
+  __name(typedUseFeatureFlagStatus, "typedUseFeatureFlagStatus");
+  const TypedFeatureFlag = /* @__PURE__ */ __name((props) => {
+    const { children, fallback, loading, matchValue, name } = props;
+    const status = typedUseFeatureFlagStatus();
+    const { enabled, value } = typedUseFeatureFlag(name);
+    if (status.isLoading) {
+      return loading ?? fallback ?? null;
+    }
+    const shouldRenderChildren = typeof matchValue === "undefined" ? enabled : Object.is(value, matchValue);
+    if (!shouldRenderChildren) {
+      return fallback ?? null;
+    }
+    if (typeof children === "function") {
+      return children({
+        enabled,
+        value,
+        status
+      });
+    }
+    return children;
+  }, "TypedFeatureFlag");
+  return {
+    FeatureFlagProvider: TypedFeatureFlagProvider,
+    FeatureFlag: TypedFeatureFlag,
+    useFeatureFlag: typedUseFeatureFlag,
+    useFeatureFlags: typedUseFeatureFlags,
+    useFeatureFlagClient: typedUseFeatureFlagClient,
+    useFeatureFlagStatus: typedUseFeatureFlagStatus
+  };
+}
+__name(createTypedHooks, "createTypedHooks");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeatureFlagProvider,
+  createTypedHooks
+});

package/dist/react.d.cts

@@ -0,0 +1,223 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import * as _repo_types_v2 from '@repo/types-v2';
+import { EvaluatedFlag, FeatureFlagEvaluationContext } from '@repo/types-v2';
+
+/** Base type for a flag registry mapping flag names to their value types. */
+type FlagRegistry = object;
+type FeatureFlagRuntimeSource = "network" | "persisted" | "defaults";
+type FeatureFlagRuntimeStatus = {
+    source: FeatureFlagRuntimeSource;
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+    lastError: Error | null;
+};
+type PersistedFeatureFlagSnapshot = {
+    schemaVersion: number;
+    scopeKey: string;
+    organizationId: string;
+    environmentId: string;
+    teamId: string | null;
+    clientKeyFingerprint: string;
+    contextHash: string;
+    token: string;
+    publicKeyPem: string;
+    fetchedAt: string;
+    tokenExpiresAt: string | null;
+};
+type FeatureFlagSnapshotStore = {
+    load(key: string): Promise<PersistedFeatureFlagSnapshot | null>;
+    save(key: string, snapshot: PersistedFeatureFlagSnapshot): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+type FeatureFlagSnapshotPersistenceConfig = {
+    store?: FeatureFlagSnapshotStore;
+    keyPrefix?: string;
+};
+type FeatureFlagClientConfig<TFlags extends FlagRegistry = FlagRegistry> = {
+    /** API key with `lk_pub_*` or `lk_sec_*` prefix */
+    clientKey: string;
+    /** Base URL for the API (e.g. "https://api.merged.gg") */
+    apiUrl: string;
+    /** Organization scope for signed flag evaluation */
+    organizationId: string;
+    /** Environment scope for signed flag evaluation */
+    environmentId: string;
+    /** Optional team scope for signed flag evaluation */
+    teamId?: string;
+    /** Code-key-to-ID mapping from generated code. Enables type-safe lookups resolved to stable IDs. */
+    flagIds?: {
+        readonly [K in string & keyof TFlags]: string;
+    };
+    /** PEM-format ES256 public key. If omitted, auto-fetched from the public-key endpoint. */
+    publicKey?: string;
+    /** Polling interval in milliseconds. Default: 60_000 (60s). Set to 0 to disable. */
+    refreshInterval?: number;
+    /** Optional caller-provided evaluation context sent to the API when resolving flags. */
+    evaluationContext?: _repo_types_v2.FeatureFlagEvaluationContext;
+    /** Controls automatic persistence of the last successful signed evaluation. */
+    snapshotPersistence?: false | FeatureFlagSnapshotPersistenceConfig;
+    /** Called when an error occurs during refresh or verification */
+    onError?: (error: Error) => void;
+    /** Called when flags change after a refresh */
+    onFlagsChanged?: (flags: _repo_types_v2.EvaluatedFlag[]) => void;
+};
+
+/**
+ * Structural interface for the feature flag client. Using an interface instead of
+ * the concrete MergedFeatureFlags class avoids "separate declarations of a private
+ * property" errors when consumers resolve the class from a different module path
+ * (e.g., dist/ vs src/ in a monorepo workspace).
+ */
+interface FeatureFlagClient {
+    initialize(): Promise<void>;
+    destroy(): void;
+    isEnabled(name: string): boolean;
+    getValue(name: string): unknown;
+    getFlag(name: string): EvaluatedFlag | undefined;
+    getAllFlags(): EvaluatedFlag[];
+    getSnapshot(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    subscribe(onStoreChange: () => void): () => void;
+    refresh(): Promise<void>;
+}
+type FeatureFlagProviderStatus = "idle" | "loading" | "ready" | "error";
+type FeatureFlagLoadState = {
+    status: FeatureFlagProviderStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    error: Error | null;
+    source: FeatureFlagRuntimeStatus["source"];
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+};
+type FeatureFlagProviderProps = {
+    client: FeatureFlagClient;
+    blockUntilReady: boolean;
+    loadingFallback?: ReactNode;
+    /** Pre-evaluated flags for SSR hydration. Skips initial fetch on the server. */
+    initialFlags?: EvaluatedFlag[];
+    children: ReactNode;
+};
+declare function FeatureFlagProvider(props: FeatureFlagProviderProps): react_jsx_runtime.JSX.Element;
+
+type ChangeListener = (flags: EvaluatedFlag[]) => void;
+declare class MergedFeatureFlags<TFlags extends FlagRegistry = FlagRegistry> {
+    private flagsById;
+    private flagsByName;
+    private publicKeyPem;
+    private publicKeyCrypto;
+    private refreshTimer;
+    private backoffMs;
+    private consecutiveFailures;
+    private listeners;
+    private storeListeners;
+    private initialized;
+    private visibilityHandler;
+    private pendingScopeTransition;
+    private runtimeStatus;
+    private snapshotStorePromise;
+    private readonly keyPrefix;
+    private contextSignature;
+    private readonly flagIds;
+    private readonly clientKey;
+    private readonly apiUrl;
+    private readonly organizationId;
+    private readonly environmentId;
+    private readonly teamId;
+    private readonly refreshInterval;
+    private readonly onError;
+    private readonly onFlagsChanged;
+    private readonly snapshotPersistence;
+    private evaluationContext;
+    constructor(config: FeatureFlagClientConfig<TFlags>);
+    initialize(): Promise<void>;
+    /** Returns true if the flag is enabled. Returns false for unknown flags. */
+    isEnabled<K extends string & keyof TFlags>(name: K): boolean;
+    /** Returns the flag's value with the type inferred from the flag registry. */
+    getValue<K extends string & keyof TFlags>(name: K): TFlags[K] | undefined;
+    /** Returns the full evaluated flag entry, or undefined if not found. */
+    getFlag<K extends string & keyof TFlags>(name: K): EvaluatedFlag | undefined;
+    /** Returns all evaluated flags. */
+    getAllFlags(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    getStatusSnapshot(): FeatureFlagRuntimeStatus;
+    /** Manually trigger a refresh from the server. */
+    refresh(): Promise<void>;
+    /** Subscribe to flag changes. Returns an unsubscribe function. */
+    onChange(listener: ChangeListener): () => void;
+    /** Get a snapshot function for useSyncExternalStore. */
+    getSnapshot(): EvaluatedFlag[];
+    /** Replace the caller-provided evaluation context used on subsequent refreshes. */
+    setEvaluationContext(context: FeatureFlagEvaluationContext | null | undefined): void;
+    /** Subscribe function for useSyncExternalStore. */
+    subscribe(onStoreChange: () => void): () => void;
+    /** Clean up timers, listeners, and cached data. */
+    destroy(): void;
+    private resolveFlag;
+    private clearFlags;
+    private emitChange;
+    private updateFlags;
+    private hasFlagsChanged;
+    private setRuntimeStatus;
+    private fetchSignedFlags;
+    private fetchPublicKey;
+    private verifyWithRetry;
+    private ensureVerificationKey;
+    private getTrustedSnapshotVerificationKey;
+    private getSnapshotStore;
+    private getScopeParts;
+    private restorePersistedSnapshot;
+    private persistSnapshot;
+    private startPolling;
+    private scheduleNextPoll;
+    private safeRefresh;
+    private resetBackoff;
+    private incrementBackoff;
+}
+
+type FeatureFlagRenderState<TValue> = {
+    enabled: boolean;
+    value: TValue | undefined;
+    status: FeatureFlagLoadState;
+};
+type FeatureFlagMatchValue<TValue> = Extract<TValue, string | number | boolean>;
+type TypedFeatureFlagProps<TFlags extends FlagRegistry, K extends string & keyof TFlags> = {
+    name: K;
+    children: ReactNode | ((props: FeatureFlagRenderState<TFlags[K]>) => ReactNode);
+    fallback?: ReactNode;
+    loading?: ReactNode;
+    matchValue?: FeatureFlagMatchValue<TFlags[K]>;
+};
+type TypedFeatureFlagComponent<TFlags extends FlagRegistry> = <K extends string & keyof TFlags>(props: TypedFeatureFlagProps<TFlags, K>) => ReactNode;
+/**
+ * Creates type-safe React hooks and provider bound to a specific flag registry.
+ * Call this in your generated code and re-export the result.
+ *
+ * ```typescript
+ * // generated/feature-flags.ts
+ * export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+ *   createTypedHooks<FlagValues>()
+ * ```
+ */
+declare function createTypedHooks<TFlags extends FlagRegistry>(): {
+    FeatureFlagProvider: (props: {
+        client: FeatureFlagClient;
+        blockUntilReady: boolean;
+        loadingFallback?: ReactNode;
+        initialFlags?: EvaluatedFlag[];
+        children: ReactNode;
+    }) => react_jsx_runtime.JSX.Element;
+    FeatureFlag: TypedFeatureFlagComponent<TFlags>;
+    useFeatureFlag: <K extends string & keyof TFlags>(name: K) => {
+        enabled: boolean;
+        value: TFlags[K] | undefined;
+    };
+    useFeatureFlags: () => EvaluatedFlag[];
+    useFeatureFlagClient: () => MergedFeatureFlags<TFlags>;
+    useFeatureFlagStatus: () => FeatureFlagLoadState;
+};
+
+export { type FeatureFlagClient, FeatureFlagProvider, type FeatureFlagProviderProps, createTypedHooks };

package/dist/react.d.ts

@@ -0,0 +1,223 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import * as _repo_types_v2 from '@repo/types-v2';
+import { EvaluatedFlag, FeatureFlagEvaluationContext } from '@repo/types-v2';
+
+/** Base type for a flag registry mapping flag names to their value types. */
+type FlagRegistry = object;
+type FeatureFlagRuntimeSource = "network" | "persisted" | "defaults";
+type FeatureFlagRuntimeStatus = {
+    source: FeatureFlagRuntimeSource;
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+    lastError: Error | null;
+};
+type PersistedFeatureFlagSnapshot = {
+    schemaVersion: number;
+    scopeKey: string;
+    organizationId: string;
+    environmentId: string;
+    teamId: string | null;
+    clientKeyFingerprint: string;
+    contextHash: string;
+    token: string;
+    publicKeyPem: string;
+    fetchedAt: string;
+    tokenExpiresAt: string | null;
+};
+type FeatureFlagSnapshotStore = {
+    load(key: string): Promise<PersistedFeatureFlagSnapshot | null>;
+    save(key: string, snapshot: PersistedFeatureFlagSnapshot): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+type FeatureFlagSnapshotPersistenceConfig = {
+    store?: FeatureFlagSnapshotStore;
+    keyPrefix?: string;
+};
+type FeatureFlagClientConfig<TFlags extends FlagRegistry = FlagRegistry> = {
+    /** API key with `lk_pub_*` or `lk_sec_*` prefix */
+    clientKey: string;
+    /** Base URL for the API (e.g. "https://api.merged.gg") */
+    apiUrl: string;
+    /** Organization scope for signed flag evaluation */
+    organizationId: string;
+    /** Environment scope for signed flag evaluation */
+    environmentId: string;
+    /** Optional team scope for signed flag evaluation */
+    teamId?: string;
+    /** Code-key-to-ID mapping from generated code. Enables type-safe lookups resolved to stable IDs. */
+    flagIds?: {
+        readonly [K in string & keyof TFlags]: string;
+    };
+    /** PEM-format ES256 public key. If omitted, auto-fetched from the public-key endpoint. */
+    publicKey?: string;
+    /** Polling interval in milliseconds. Default: 60_000 (60s). Set to 0 to disable. */
+    refreshInterval?: number;
+    /** Optional caller-provided evaluation context sent to the API when resolving flags. */
+    evaluationContext?: _repo_types_v2.FeatureFlagEvaluationContext;
+    /** Controls automatic persistence of the last successful signed evaluation. */
+    snapshotPersistence?: false | FeatureFlagSnapshotPersistenceConfig;
+    /** Called when an error occurs during refresh or verification */
+    onError?: (error: Error) => void;
+    /** Called when flags change after a refresh */
+    onFlagsChanged?: (flags: _repo_types_v2.EvaluatedFlag[]) => void;
+};
+
+/**
+ * Structural interface for the feature flag client. Using an interface instead of
+ * the concrete MergedFeatureFlags class avoids "separate declarations of a private
+ * property" errors when consumers resolve the class from a different module path
+ * (e.g., dist/ vs src/ in a monorepo workspace).
+ */
+interface FeatureFlagClient {
+    initialize(): Promise<void>;
+    destroy(): void;
+    isEnabled(name: string): boolean;
+    getValue(name: string): unknown;
+    getFlag(name: string): EvaluatedFlag | undefined;
+    getAllFlags(): EvaluatedFlag[];
+    getSnapshot(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    subscribe(onStoreChange: () => void): () => void;
+    refresh(): Promise<void>;
+}
+type FeatureFlagProviderStatus = "idle" | "loading" | "ready" | "error";
+type FeatureFlagLoadState = {
+    status: FeatureFlagProviderStatus;
+    isLoading: boolean;
+    isReady: boolean;
+    error: Error | null;
+    source: FeatureFlagRuntimeStatus["source"];
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+};
+type FeatureFlagProviderProps = {
+    client: FeatureFlagClient;
+    blockUntilReady: boolean;
+    loadingFallback?: ReactNode;
+    /** Pre-evaluated flags for SSR hydration. Skips initial fetch on the server. */
+    initialFlags?: EvaluatedFlag[];
+    children: ReactNode;
+};
+declare function FeatureFlagProvider(props: FeatureFlagProviderProps): react_jsx_runtime.JSX.Element;
+
+type ChangeListener = (flags: EvaluatedFlag[]) => void;
+declare class MergedFeatureFlags<TFlags extends FlagRegistry = FlagRegistry> {
+    private flagsById;
+    private flagsByName;
+    private publicKeyPem;
+    private publicKeyCrypto;
+    private refreshTimer;
+    private backoffMs;
+    private consecutiveFailures;
+    private listeners;
+    private storeListeners;
+    private initialized;
+    private visibilityHandler;
+    private pendingScopeTransition;
+    private runtimeStatus;
+    private snapshotStorePromise;
+    private readonly keyPrefix;
+    private contextSignature;
+    private readonly flagIds;
+    private readonly clientKey;
+    private readonly apiUrl;
+    private readonly organizationId;
+    private readonly environmentId;
+    private readonly teamId;
+    private readonly refreshInterval;
+    private readonly onError;
+    private readonly onFlagsChanged;
+    private readonly snapshotPersistence;
+    private evaluationContext;
+    constructor(config: FeatureFlagClientConfig<TFlags>);
+    initialize(): Promise<void>;
+    /** Returns true if the flag is enabled. Returns false for unknown flags. */
+    isEnabled<K extends string & keyof TFlags>(name: K): boolean;
+    /** Returns the flag's value with the type inferred from the flag registry. */
+    getValue<K extends string & keyof TFlags>(name: K): TFlags[K] | undefined;
+    /** Returns the full evaluated flag entry, or undefined if not found. */
+    getFlag<K extends string & keyof TFlags>(name: K): EvaluatedFlag | undefined;
+    /** Returns all evaluated flags. */
+    getAllFlags(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    getStatusSnapshot(): FeatureFlagRuntimeStatus;
+    /** Manually trigger a refresh from the server. */
+    refresh(): Promise<void>;
+    /** Subscribe to flag changes. Returns an unsubscribe function. */
+    onChange(listener: ChangeListener): () => void;
+    /** Get a snapshot function for useSyncExternalStore. */
+    getSnapshot(): EvaluatedFlag[];
+    /** Replace the caller-provided evaluation context used on subsequent refreshes. */
+    setEvaluationContext(context: FeatureFlagEvaluationContext | null | undefined): void;
+    /** Subscribe function for useSyncExternalStore. */
+    subscribe(onStoreChange: () => void): () => void;
+    /** Clean up timers, listeners, and cached data. */
+    destroy(): void;
+    private resolveFlag;
+    private clearFlags;
+    private emitChange;
+    private updateFlags;
+    private hasFlagsChanged;
+    private setRuntimeStatus;
+    private fetchSignedFlags;
+    private fetchPublicKey;
+    private verifyWithRetry;
+    private ensureVerificationKey;
+    private getTrustedSnapshotVerificationKey;
+    private getSnapshotStore;
+    private getScopeParts;
+    private restorePersistedSnapshot;
+    private persistSnapshot;
+    private startPolling;
+    private scheduleNextPoll;
+    private safeRefresh;
+    private resetBackoff;
+    private incrementBackoff;
+}
+
+type FeatureFlagRenderState<TValue> = {
+    enabled: boolean;
+    value: TValue | undefined;
+    status: FeatureFlagLoadState;
+};
+type FeatureFlagMatchValue<TValue> = Extract<TValue, string | number | boolean>;
+type TypedFeatureFlagProps<TFlags extends FlagRegistry, K extends string & keyof TFlags> = {
+    name: K;
+    children: ReactNode | ((props: FeatureFlagRenderState<TFlags[K]>) => ReactNode);
+    fallback?: ReactNode;
+    loading?: ReactNode;
+    matchValue?: FeatureFlagMatchValue<TFlags[K]>;
+};
+type TypedFeatureFlagComponent<TFlags extends FlagRegistry> = <K extends string & keyof TFlags>(props: TypedFeatureFlagProps<TFlags, K>) => ReactNode;
+/**
+ * Creates type-safe React hooks and provider bound to a specific flag registry.
+ * Call this in your generated code and re-export the result.
+ *
+ * ```typescript
+ * // generated/feature-flags.ts
+ * export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+ *   createTypedHooks<FlagValues>()
+ * ```
+ */
+declare function createTypedHooks<TFlags extends FlagRegistry>(): {
+    FeatureFlagProvider: (props: {
+        client: FeatureFlagClient;
+        blockUntilReady: boolean;
+        loadingFallback?: ReactNode;
+        initialFlags?: EvaluatedFlag[];
+        children: ReactNode;
+    }) => react_jsx_runtime.JSX.Element;
+    FeatureFlag: TypedFeatureFlagComponent<TFlags>;
+    useFeatureFlag: <K extends string & keyof TFlags>(name: K) => {
+        enabled: boolean;
+        value: TFlags[K] | undefined;
+    };
+    useFeatureFlags: () => EvaluatedFlag[];
+    useFeatureFlagClient: () => MergedFeatureFlags<TFlags>;
+    useFeatureFlagStatus: () => FeatureFlagLoadState;
+};
+
+export { type FeatureFlagClient, FeatureFlagProvider, type FeatureFlagProviderProps, createTypedHooks };