@jewel998/config 0.1.8 → 0.2.1

package/dist/client/ConfigClient.js

@@ -1,6 +1,9 @@
 import { withRetry } from "../retry/RetryEngine.js";
-import { evaluatePipeline } from "../plugins/evaluatePipeline.js";
 import { DEFAULT_CACHE_TTL } from "../types.js";
+import { RefreshManager } from "./RefreshManager.js";
+import { ValueResolver } from "./ValueResolver.js";
+const MIN_FETCH_INTERVAL = 30_000; // Don't re-fetch within 30s
+const CONTEXT_DEBOUNCE_MS = 100; // Batch rapid setContext calls
 export const buildConfigClient = (internals) => {
     const { cache, fetcher, events, retry, granularity, isDeferred } = internals;
     const plugins = internals.plugins ?? [];
@@ -10,16 +13,21 @@ export const buildConfigClient = (internals) => {
     const onContextChange = internals.onContextChange;
     let data = { ...internals.data };
     let batchFetchTriggered = false;
-    // ── Request deduplication & debouncing ──
-    let inflightRefresh = null;
-    let lastFetchTime = 0;
+    // ── Debouncing ──
     let contextDebounceTimer = null;
-    const MIN_FETCH_INTERVAL = 30_000; // Don't re-fetch within 30s
-    const CONTEXT_DEBOUNCE_MS = 100; // Batch rapid setContext calls
+    // ── Extracted components ──
+    const refreshManager = new RefreshManager({
+        fetcher,
+        cache,
+        events,
+        retry,
+        minFetchInterval: MIN_FETCH_INTERVAL,
+    });
+    const valueResolver = new ValueResolver(plugins, data, cache, events);
+    // ── Deferred fetch helpers ──
     const triggerDeferredFetch = () => {
-        if (!isDeferred || batchFetchTriggered) {
+        if (!isDeferred || batchFetchTriggered)
             return;
-        }
         if (granularity === "batch") {
             batchFetchTriggered = true;
             void (async () => {
@@ -29,7 +37,7 @@ export const buildConfigClient = (internals) => {
                     for (const [key, value] of Object.entries(result)) {
                         cache.set(key, value, DEFAULT_CACHE_TTL);
                     }
-                    data = { ...data, ...result };
+                    Object.assign(data, result);
                     events.emit("updated", {
                         keys: Object.keys(result),
                         source: "background",
@@ -46,9 +54,8 @@ export const buildConfigClient = (internals) => {
         }
     };
     const triggerProjectedFetch = (key) => {
-        if (!isDeferred || granularity !== "projected") {
+        if (!isDeferred || granularity !== "projected")
             return;
-        }
         void (async () => {
             try {
                 const result = await fetcher.fetchKeys([key]);
@@ -72,75 +79,20 @@ export const buildConfigClient = (internals) => {
     };
     const client = {
         getValue(key, defaultValue) {
-            // If plugins are registered, use the evaluation pipeline
+            // Delegate to ValueResolver for plugin-based or simple resolution
             if (plugins.length > 0) {
-                // Consent-aware mode: if enabled and consent not granted, return default immediately
-                if (consentAware && evalContext.consentGranted !== true) {
-                    return defaultValue;
-                }
-                // Get raw flag data from cache/data store
-                const rawValue = data[key] ?? cache.get(key);
-                // If we have no data at all for this key, trigger deferred fetch and return default
-                if (rawValue === undefined) {
-                    if (isDeferred) {
-                        triggerDeferredFetch();
-                        triggerProjectedFetch(key);
-                    }
+                // Check if data is missing and trigger deferred fetch
+                if (valueResolver.isMissing(key) && isDeferred) {
+                    triggerDeferredFetch();
+                    triggerProjectedFetch(key);
                     return defaultValue;
                 }
-                // Build a ConfigFlagData object from the raw data
-                // If the data is already a full ConfigFlagData object (has 'key' and 'value' fields), use it
-                // Otherwise, wrap the raw value as a simple flag
-                const flag = isConfigFlagData(rawValue)
-                    ? rawValue
-                    : {
-                        key,
-                        value: rawValue,
-                        valueType: inferValueType(rawValue),
-                        version: "0",
-                        lifecycleState: "active",
-                    };
-                // Build pipeline helpers
-                const helpers = {
-                    evaluateFlag: (flagKey, ctx) => {
-                        // Recursive evaluation for prerequisites
-                        const flagData = data[flagKey] ?? cache.get(flagKey);
-                        if (flagData === undefined)
-                            return undefined;
-                        const innerFlag = isConfigFlagData(flagData)
-                            ? flagData
-                            : {
-                                key: flagKey,
-                                value: flagData,
-                                valueType: inferValueType(flagData),
-                                version: "0",
-                                lifecycleState: "active",
-                            };
-                        return evaluatePipeline(plugins, innerFlag, ctx, helpers);
-                    },
-                    emitError: (message) => {
-                        events.emit("fetchError", {
-                            error: new Error(message),
-                            retryCount: 0,
-                            willRetry: false,
-                        });
-                    },
-                    now: () => Date.now(),
-                };
-                const result = evaluatePipeline(plugins, flag, evalContext, helpers);
-                return (result !== undefined ? result : defaultValue);
-            }
-            // No plugins — use existing behavior (backward compat)
-            // Check live data first
-            if (key in data) {
-                return data[key];
-            }
-            // Check cache
-            const cached = cache.get(key);
-            if (cached !== undefined) {
-                data[key] = cached;
-                return cached;
+                return valueResolver.resolve(key, evalContext, defaultValue, consentAware);
             }
+            // No plugins — use simple resolution via ValueResolver
+            const result = valueResolver.resolveSimple(key, defaultValue);
+            if (result !== undefined)
+                return result;
             // Trigger deferred fetch if applicable
             if (isDeferred) {
                 triggerDeferredFetch();
@@ -153,48 +105,18 @@ export const buildConfigClient = (internals) => {
             return value === true;
         },
         getAll() {
-            // Check cache for full batch
             const cached = cache.get("__all__");
             if (cached) {
-                data = { ...data, ...cached };
+                Object.assign(data, cached);
                 return { ...data };
             }
-            // Trigger deferred fetch if applicable
             if (isDeferred) {
                 triggerDeferredFetch();
             }
             return { ...data };
         },
         async refresh() {
-            // Deduplication: if a refresh is already in-flight, reuse it
-            if (inflightRefresh)
-                return inflightRefresh;
-            inflightRefresh = (async () => {
-                try {
-                    const result = await withRetry(() => fetcher.fetchAll(), retry);
-                    cache.set("__all__", result, DEFAULT_CACHE_TTL);
-                    for (const [key, value] of Object.entries(result)) {
-                        cache.set(key, value, DEFAULT_CACHE_TTL);
-                    }
-                    data = { ...data, ...result };
-                    lastFetchTime = Date.now();
-                    events.emit("updated", {
-                        keys: Object.keys(result),
-                        source: "refresh",
-                    });
-                }
-                catch (error) {
-                    events.emit("fetchError", {
-                        error: error,
-                        retryCount: retry.maxRetries,
-                        willRetry: false,
-                    });
-                }
-                finally {
-                    inflightRefresh = null;
-                }
-            })();
-            return inflightRefresh;
+            await refreshManager.refresh(data);
         },
         on(event, callback) {
             events.on(event, callback);
@@ -204,7 +126,6 @@ export const buildConfigClient = (internals) => {
         },
         setContext(newContext) {
             evalContext = { ...newContext };
-            // Notify the transport layer of the context change
             if (onContextChange) {
                 onContextChange(evalContext);
             }
@@ -215,35 +136,20 @@ export const buildConfigClient = (internals) => {
                     clearTimeout(contextDebounceTimer);
                 contextDebounceTimer = setTimeout(() => {
                     contextDebounceTimer = null;
-                    // Skip if we fetched very recently (stale check)
-                    if (Date.now() - lastFetchTime < MIN_FETCH_INTERVAL)
+                    if (refreshManager.isRecent)
                         return;
                     void client.refresh();
                 }, CONTEXT_DEBOUNCE_MS);
             }
         },
+        destroy() {
+            if (contextDebounceTimer) {
+                clearTimeout(contextDebounceTimer);
+                contextDebounceTimer = null;
+            }
+            events.removeAllListeners();
+        },
     };
     return client;
 };
-// ═══════════════════════════════════════════════════════════════
-// Helpers
-// ═══════════════════════════════════════════════════════════════
-/** Type guard: checks if a value looks like a full ConfigFlagData object */
-function isConfigFlagData(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "key" in value &&
-        "value" in value &&
-        "lifecycleState" in value);
-}
-/** Infer a valueType string from a raw value */
-function inferValueType(value) {
-    if (typeof value === "boolean")
-        return "boolean";
-    if (typeof value === "number")
-        return "number";
-    if (typeof value === "string")
-        return "string";
-    return "json";
-}
 //# sourceMappingURL=ConfigClient.js.map

package/dist/client/RefreshManager.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RefreshManager — handles version-gated, deduplicated config refreshes.
+ *
+ * Responsibilities:
+ * - Version checking before full fetch (skip if unchanged)
+ * - In-flight request deduplication (only one refresh at a time)
+ * - Tracking time since last fetch (for stale-check gating)
+ * - Updating cache and data store on successful refresh
+ */
+import type { CacheStorage, ConfigFetcher, EventEmitterInterface, RetryConfig } from "../types.js";
+export interface RefreshManagerConfig {
+    /** Fetcher for remote config data */
+    fetcher: ConfigFetcher;
+    /** Cache storage adapter */
+    cache: CacheStorage;
+    /** Event emitter for lifecycle notifications */
+    events: EventEmitterInterface;
+    /** Retry configuration */
+    retry: Required<RetryConfig>;
+    /** Minimum interval between fetches in ms */
+    minFetchInterval: number;
+}
+export declare class RefreshManager {
+    private config;
+    private inflightRefresh;
+    private lastFetchTime;
+    private cachedVersion;
+    constructor(config: RefreshManagerConfig);
+    /** Time in ms since the last successful fetch */
+    get timeSinceLastFetch(): number;
+    /** Whether a fetch has happened recently (within minFetchInterval) */
+    get isRecent(): boolean;
+    /**
+     * Perform a version-gated refresh with deduplication.
+     *
+     * 1. If a refresh is already in-flight, returns the existing promise.
+     * 2. Checks the remote version first (lightweight call).
+     * 3. If version is unchanged, emits an update event and skips full fetch.
+     * 4. Otherwise performs a full fetch with retry, updates cache & data.
+     *
+     * @param data - Mutable data record to update with fetched values
+     * @returns The updated data record
+     */
+    refresh(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/dist/client/RefreshManager.js

@@ -0,0 +1,89 @@
+/**
+ * RefreshManager — handles version-gated, deduplicated config refreshes.
+ *
+ * Responsibilities:
+ * - Version checking before full fetch (skip if unchanged)
+ * - In-flight request deduplication (only one refresh at a time)
+ * - Tracking time since last fetch (for stale-check gating)
+ * - Updating cache and data store on successful refresh
+ */
+import { withRetry } from "../retry/RetryEngine.js";
+import { DEFAULT_CACHE_TTL } from "../types.js";
+export class RefreshManager {
+    config;
+    inflightRefresh = null;
+    lastFetchTime = 0;
+    cachedVersion = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Time in ms since the last successful fetch */
+    get timeSinceLastFetch() {
+        return Date.now() - this.lastFetchTime;
+    }
+    /** Whether a fetch has happened recently (within minFetchInterval) */
+    get isRecent() {
+        return this.timeSinceLastFetch < this.config.minFetchInterval;
+    }
+    /**
+     * Perform a version-gated refresh with deduplication.
+     *
+     * 1. If a refresh is already in-flight, returns the existing promise.
+     * 2. Checks the remote version first (lightweight call).
+     * 3. If version is unchanged, emits an update event and skips full fetch.
+     * 4. Otherwise performs a full fetch with retry, updates cache & data.
+     *
+     * @param data - Mutable data record to update with fetched values
+     * @returns The updated data record
+     */
+    async refresh(data) {
+        // Deduplication: if a refresh is already in-flight, reuse it
+        if (this.inflightRefresh) {
+            await this.inflightRefresh;
+            return data;
+        }
+        const { fetcher, cache, events, retry } = this.config;
+        this.inflightRefresh = (async () => {
+            try {
+                // Version-gated refresh: check version first (lightweight call)
+                try {
+                    const { version } = await fetcher.checkVersion();
+                    if (this.cachedVersion !== null && version === this.cachedVersion) {
+                        // Version unchanged — skip full fetch
+                        events.emit("updated", { keys: [], source: "version-check" });
+                        this.lastFetchTime = Date.now();
+                        return;
+                    }
+                    this.cachedVersion = version;
+                }
+                catch {
+                    // If version check fails, proceed with full fetch as fallback
+                }
+                const result = await withRetry(() => fetcher.fetchAll(), retry);
+                cache.set("__all__", result, DEFAULT_CACHE_TTL);
+                for (const [key, value] of Object.entries(result)) {
+                    cache.set(key, value, DEFAULT_CACHE_TTL);
+                }
+                Object.assign(data, result);
+                this.lastFetchTime = Date.now();
+                events.emit("updated", {
+                    keys: Object.keys(result),
+                    source: "refresh",
+                });
+            }
+            catch (error) {
+                events.emit("fetchError", {
+                    error: error,
+                    retryCount: retry.maxRetries,
+                    willRetry: false,
+                });
+            }
+            finally {
+                this.inflightRefresh = null;
+            }
+        })();
+        await this.inflightRefresh;
+        return data;
+    }
+}
+//# sourceMappingURL=RefreshManager.js.map

package/dist/client/ValueResolver.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ValueResolver — resolves config values through the plugin evaluation pipeline.
+ *
+ * Responsibilities:
+ * - Looking up raw flag data from in-memory data or cache
+ * - Running the evaluation pipeline when plugins are registered
+ * - Handling consent-aware mode (GDPR compliance)
+ * - Providing backward-compatible behavior when no plugins are present
+ */
+import type { EvaluationContext, EvaluationPlugin } from "../plugins/types.js";
+import type { CacheStorage, EventEmitterInterface } from "../types.js";
+export declare class ValueResolver {
+    private plugins;
+    private data;
+    private cache;
+    private events;
+    constructor(plugins: EvaluationPlugin[], data: Record<string, unknown>, cache: CacheStorage, events: EventEmitterInterface);
+    /**
+     * Resolve a value through the plugin pipeline or via direct lookup.
+     *
+     * @param key - Config key to resolve
+     * @param context - Current evaluation context
+     * @param defaultValue - Fallback value if key is not found or no plugin resolves
+     * @param consentAware - If true, blocks evaluation unless consentGranted is true
+     * @returns The resolved value, or defaultValue if unresolved
+     */
+    resolve<T>(key: string, context: EvaluationContext, defaultValue?: T, consentAware?: boolean): T | undefined;
+    /**
+     * Simple resolution without plugins — checks data then cache.
+     * Returns undefined (or defaultValue) if the key is missing entirely.
+     */
+    resolveSimple<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Resolution with plugin pipeline — evaluates flag data through registered plugins.
+     */
+    private resolveWithPlugins;
+    /** Whether data is missing for a given key (triggers deferred fetch) */
+    isMissing(key: string): boolean;
+}

package/dist/client/ValueResolver.js

@@ -0,0 +1,131 @@
+/**
+ * ValueResolver — resolves config values through the plugin evaluation pipeline.
+ *
+ * Responsibilities:
+ * - Looking up raw flag data from in-memory data or cache
+ * - Running the evaluation pipeline when plugins are registered
+ * - Handling consent-aware mode (GDPR compliance)
+ * - Providing backward-compatible behavior when no plugins are present
+ */
+import { evaluatePipeline } from "../plugins/evaluatePipeline.js";
+export class ValueResolver {
+    plugins;
+    data;
+    cache;
+    events;
+    constructor(plugins, data, cache, events) {
+        this.plugins = plugins;
+        this.data = data;
+        this.cache = cache;
+        this.events = events;
+    }
+    /**
+     * Resolve a value through the plugin pipeline or via direct lookup.
+     *
+     * @param key - Config key to resolve
+     * @param context - Current evaluation context
+     * @param defaultValue - Fallback value if key is not found or no plugin resolves
+     * @param consentAware - If true, blocks evaluation unless consentGranted is true
+     * @returns The resolved value, or defaultValue if unresolved
+     */
+    resolve(key, context, defaultValue, consentAware = false) {
+        if (this.plugins.length > 0) {
+            return this.resolveWithPlugins(key, context, defaultValue, consentAware);
+        }
+        // No plugins — use existing behavior (backward compat)
+        return this.resolveSimple(key, defaultValue);
+    }
+    /**
+     * Simple resolution without plugins — checks data then cache.
+     * Returns undefined (or defaultValue) if the key is missing entirely.
+     */
+    resolveSimple(key, defaultValue) {
+        if (key in this.data) {
+            return this.data[key];
+        }
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            this.data[key] = cached;
+            return cached;
+        }
+        return defaultValue;
+    }
+    /**
+     * Resolution with plugin pipeline — evaluates flag data through registered plugins.
+     */
+    resolveWithPlugins(key, context, defaultValue, consentAware = false) {
+        // Consent-aware mode: if enabled and consent not granted, return default
+        if (consentAware && context.consentGranted !== true) {
+            return defaultValue;
+        }
+        // Get raw flag data from data store or cache
+        const rawValue = this.data[key] ?? this.cache.get(key);
+        if (rawValue === undefined) {
+            return defaultValue;
+        }
+        // Build a ConfigFlagData object from the raw data
+        const flag = isConfigFlagData(rawValue)
+            ? rawValue
+            : {
+                key,
+                value: rawValue,
+                valueType: inferValueType(rawValue),
+                version: "0",
+                lifecycleState: "active",
+            };
+        // Build pipeline helpers
+        const helpers = {
+            evaluateFlag: (flagKey, ctx) => {
+                const flagData = this.data[flagKey] ?? this.cache.get(flagKey);
+                if (flagData === undefined)
+                    return undefined;
+                const innerFlag = isConfigFlagData(flagData)
+                    ? flagData
+                    : {
+                        key: flagKey,
+                        value: flagData,
+                        valueType: inferValueType(flagData),
+                        version: "0",
+                        lifecycleState: "active",
+                    };
+                return evaluatePipeline(this.plugins, innerFlag, ctx, helpers);
+            },
+            emitError: (message) => {
+                this.events.emit("fetchError", {
+                    error: new Error(message),
+                    retryCount: 0,
+                    willRetry: false,
+                });
+            },
+            now: () => Date.now(),
+        };
+        const result = evaluatePipeline(this.plugins, flag, context, helpers);
+        return (result !== undefined ? result : defaultValue);
+    }
+    /** Whether data is missing for a given key (triggers deferred fetch) */
+    isMissing(key) {
+        return !(key in this.data) && this.cache.get(key) === undefined;
+    }
+}
+// ═══════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════
+/** Type guard: checks if a value looks like a full ConfigFlagData object */
+function isConfigFlagData(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "key" in value &&
+        "value" in value &&
+        "lifecycleState" in value);
+}
+/** Infer a valueType string from a raw value */
+function inferValueType(value) {
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "string")
+        return "string";
+    return "json";
+}
+//# sourceMappingURL=ValueResolver.js.map

package/dist/createConfig.js

@@ -9,7 +9,7 @@ import { executeOptimistic } from "./loading/optimistic.js";
 import { executePessimistic } from "./loading/pessimistic.js";
 import { createHttpTransport } from "./transport/HttpTransport.js";
 import { DEFAULT_RETRY, DEFAULT_TIMEOUT } from "./types.js";
-const DEFAULT_BASE_URL = "https://us-central1-jewel998-config.cloudfunctions.net";
+const DEFAULT_BASE_URL = "https://jewel998-config.web.app/api";
 export function createConfig(options) {
     // 1. Validate clientId
     if (!options.clientId) {

package/dist/errors/index.d.ts

@@ -1,4 +1,4 @@
-export type ConfigErrorCode = "MISSING_CLIENT_ID" | "AUTHENTICATION_FAILED" | "INITIALIZATION_FAILED" | "TIMEOUT" | "RATE_LIMITED" | "REVOKED" | "NETWORK_ERROR";
+export type ConfigErrorCode = "MISSING_CLIENT_ID" | "AUTHENTICATION_FAILED" | "INITIALIZATION_FAILED" | "TIMEOUT" | "RATE_LIMITED" | "REVOKED" | "NETWORK_ERROR" | "BAD_REQUEST" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "PAYLOAD_TOO_LARGE" | "CONFLICT" | "SERVER_ERROR";
 export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
     name: string;

package/dist/fetch/batchFetcher.js

@@ -8,5 +8,12 @@ export const createBatchFetcher = (transport) => ({
         const response = await transport.request("getConfig");
         return response.data;
     },
+    async checkVersion() {
+        const response = await transport.request("getVersion");
+        return {
+            version: String(response.version),
+            changedKeys: response.changedKeys ?? [],
+        };
+    },
 });
 //# sourceMappingURL=batchFetcher.js.map

package/dist/fetch/projectedFetcher.js

@@ -38,6 +38,13 @@ export const createProjectedFetcher = (transport) => {
             }
             return filtered;
         },
+        async checkVersion() {
+            const response = await transport.request("getVersion");
+            return {
+                version: String(response.version),
+                changedKeys: response.changedKeys ?? [],
+            };
+        },
     };
 };
 //# sourceMappingURL=projectedFetcher.js.map

package/dist/initConfig.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigEventCallback, ConfigEventType } from "./types.js";
+import type { CacheStorage, ConfigEventCallback, ConfigEventType } from "./types.js";
 import type { EvaluationContext } from "./plugins/types.js";
 export interface InitConfigOptions {
     /** Required. API key from the portal (cid_ for client, svr_ for server). */
@@ -17,6 +17,19 @@ export interface InitConfigOptions {
      * @example "https://your-project.web.app/api"
      */
     baseUrl?: string;
+    /**
+     * Cache storage adapter. Controls where resolved config values are persisted.
+     *
+     * - `memoryStorage()` (default) — In-memory, lost on page reload
+     * - `browserStorage()` — localStorage, persists across page reloads and sessions
+     *
+     * @example
+     * ```ts
+     * import { browserStorage } from "@jewel998/config";
+     * initConfig({ storage: browserStorage({ prefix: "myapp" }) })
+     * ```
+     */
+    storage?: CacheStorage;
     /**
      * Polling interval in milliseconds for version checks.
      * The SDK periodically calls /api/version (lightweight ~100 bytes)

package/dist/initConfig.js

@@ -42,6 +42,7 @@ export function initConfig(options) {
         clientId: options.clientId,
         loadingStrategy: "optimistic",
         context: options.context,
+        storage: options.storage,
         baseUrl,
     });
     // Version-based polling: check /api/version periodically, delta-fetch on change

package/dist/retry/RetryEngine.js

@@ -5,8 +5,18 @@ export const isNonRetryableError = (error) => {
     if (error instanceof AuthenticationError) {
         return true;
     }
-    if (error instanceof ConfigError && error.code === "REVOKED") {
-        return true;
+    if (error instanceof ConfigError) {
+        // Client errors — retrying won't help
+        switch (error.code) {
+            case "REVOKED":
+            case "BAD_REQUEST":
+            case "FORBIDDEN":
+            case "NOT_FOUND":
+            case "METHOD_NOT_ALLOWED":
+            case "PAYLOAD_TOO_LARGE":
+            case "CONFLICT":
+                return true;
+        }
     }
     return false;
 };

package/dist/transport/CircuitBreaker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Circuit Breaker — prevents repeated requests to a failing endpoint.
+ *
+ * States:
+ * - CLOSED: Normal operation, all requests flow through.
+ * - OPEN: A fatal error occurred; requests are blocked until cooldown expires.
+ * - HALF_OPEN: Cooldown expired; one probe request is allowed through.
+ *
+ * On success in HALF_OPEN, the circuit transitions back to CLOSED.
+ * On a fatal failure (status code in the fatalCodes set), the circuit opens.
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+export interface CircuitBreakerConfig {
+    /** HTTP status codes that trigger the circuit to open */
+    fatalCodes: Set<number>;
+    /** Cooldown in ms before transitioning from OPEN to HALF_OPEN */
+    cooldownMs: number;
+}
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private openedAt;
+    private lastError;
+    constructor(config: CircuitBreakerConfig);
+    /** Current circuit state */
+    get currentState(): CircuitState;
+    /**
+     * Check if a request should be allowed through.
+     * If the circuit is OPEN and the cooldown has passed, transitions to HALF_OPEN.
+     *
+     * @returns true if the request can proceed, false if blocked
+     */
+    canExecute(): boolean;
+    /**
+     * Record a successful response.
+     * Closes the circuit if currently in HALF_OPEN state.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed response.
+     * Opens the circuit if the status code is in the fatal set.
+     *
+     * @param statusCode - HTTP status code of the failed response
+     * @param error - The error to cache for re-throwing while the circuit is open
+     */
+    recordFailure(statusCode: number, error: Error): void;
+    /**
+     * Get the cached fatal error (for throwing without making a network call).
+     * Returns null if no fatal error has been recorded.
+     */
+    getCachedError(): Error | null;
+    /** Reset the circuit breaker to CLOSED state, clearing any cached error. */
+    reset(): void;
+}

package/dist/transport/CircuitBreaker.js

@@ -0,0 +1,79 @@
+/**
+ * Circuit Breaker — prevents repeated requests to a failing endpoint.
+ *
+ * States:
+ * - CLOSED: Normal operation, all requests flow through.
+ * - OPEN: A fatal error occurred; requests are blocked until cooldown expires.
+ * - HALF_OPEN: Cooldown expired; one probe request is allowed through.
+ *
+ * On success in HALF_OPEN, the circuit transitions back to CLOSED.
+ * On a fatal failure (status code in the fatalCodes set), the circuit opens.
+ */
+export class CircuitBreaker {
+    config;
+    state = "CLOSED";
+    openedAt = 0;
+    lastError = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Current circuit state */
+    get currentState() {
+        return this.state;
+    }
+    /**
+     * Check if a request should be allowed through.
+     * If the circuit is OPEN and the cooldown has passed, transitions to HALF_OPEN.
+     *
+     * @returns true if the request can proceed, false if blocked
+     */
+    canExecute() {
+        if (this.state === "CLOSED" || this.state === "HALF_OPEN") {
+            return true;
+        }
+        // OPEN state — check cooldown
+        if (Date.now() - this.openedAt >= this.config.cooldownMs) {
+            this.state = "HALF_OPEN";
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Record a successful response.
+     * Closes the circuit if currently in HALF_OPEN state.
+     */
+    recordSuccess() {
+        if (this.state === "HALF_OPEN") {
+            this.state = "CLOSED";
+            this.lastError = null;
+        }
+    }
+    /**
+     * Record a failed response.
+     * Opens the circuit if the status code is in the fatal set.
+     *
+     * @param statusCode - HTTP status code of the failed response
+     * @param error - The error to cache for re-throwing while the circuit is open
+     */
+    recordFailure(statusCode, error) {
+        if (this.config.fatalCodes.has(statusCode)) {
+            this.state = "OPEN";
+            this.openedAt = Date.now();
+            this.lastError = error;
+        }
+    }
+    /**
+     * Get the cached fatal error (for throwing without making a network call).
+     * Returns null if no fatal error has been recorded.
+     */
+    getCachedError() {
+        return this.lastError;
+    }
+    /** Reset the circuit breaker to CLOSED state, clearing any cached error. */
+    reset() {
+        this.state = "CLOSED";
+        this.openedAt = 0;
+        this.lastError = null;
+    }
+}
+//# sourceMappingURL=CircuitBreaker.js.map

package/dist/transport/HttpTransport.js

@@ -1,45 +1,93 @@
 /// <reference lib="dom" />
 import { AuthenticationError, ConfigError } from "../errors/index.js";
-export const createHttpTransport = (config) => ({
-    async request(endpoint, body) {
-        const url = `${config.baseUrl}/${endpoint}`;
-        const requestData = {
-            clientId: config.clientId,
-            ...body,
-        };
-        // In server mode (cid_ key), include the current context for server-side evaluation
-        if (config.evaluationMode === "server" && config.getContext) {
-            const ctx = config.getContext();
-            if (ctx && (ctx.userId || ctx.attributes)) {
-                requestData.context = {
-                    ...(ctx.userId && { userId: ctx.userId }),
-                    ...(ctx.attributes && { attributes: ctx.attributes }),
-                };
+import { CircuitBreaker } from "./CircuitBreaker.js";
+/** Errors that should permanently stop retrying (circuit opens) */
+const FATAL_STATUS_CODES = new Set([400, 401, 403]);
+/** Cooldown before trying again after a fatal error (5 minutes) */
+const CIRCUIT_COOLDOWN_MS = 5 * 60 * 1000;
+export const createHttpTransport = (config) => {
+    const circuitBreaker = new CircuitBreaker({
+        fatalCodes: FATAL_STATUS_CODES,
+        cooldownMs: CIRCUIT_COOLDOWN_MS,
+    });
+    return {
+        async request(endpoint, body) {
+            // ── Circuit breaker check ──────────────────────────────
+            if (!circuitBreaker.canExecute()) {
+                throw (circuitBreaker.getCachedError() ??
+                    new ConfigError("API circuit breaker is open — requests are blocked due to a previous fatal error", "FORBIDDEN"));
             }
-        }
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                data: requestData,
-            }),
-        });
-        if (!response.ok) {
-            const errorBody = await response.json().catch(() => ({}));
-            const errorData = errorBody;
-            const code = errorData.error?.code ?? "NETWORK_ERROR";
-            const message = errorData.error?.message ?? `HTTP ${response.status}`;
-            if (response.status === 401) {
-                throw new AuthenticationError(message);
+            const url = `${config.baseUrl}/${endpoint}`;
+            const requestData = {
+                clientId: config.clientId,
+                ...body,
+            };
+            // In server mode (cid_ key), include the current context for server-side evaluation
+            if (config.evaluationMode === "server" && config.getContext) {
+                const ctx = config.getContext();
+                if (ctx && (ctx.userId || ctx.attributes)) {
+                    requestData.context = {
+                        ...(ctx.userId && { userId: ctx.userId }),
+                        ...(ctx.attributes && { attributes: ctx.attributes }),
+                    };
+                }
             }
-            if (response.status === 429) {
-                throw new ConfigError(message, "RATE_LIMITED");
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    data: requestData,
+                }),
+            });
+            if (!response.ok) {
+                const errorBody = await response.json().catch(() => ({}));
+                const errorData = errorBody;
+                const message = errorData.error?.message ?? `HTTP ${response.status}`;
+                let error;
+                switch (response.status) {
+                    case 400:
+                        error = new ConfigError(message, "BAD_REQUEST");
+                        break;
+                    case 401:
+                        error = new AuthenticationError(message);
+                        break;
+                    case 403:
+                        error = new ConfigError(message, "FORBIDDEN");
+                        break;
+                    case 404:
+                        error = new ConfigError(message, "NOT_FOUND");
+                        break;
+                    case 405:
+                        error = new ConfigError(message, "METHOD_NOT_ALLOWED");
+                        break;
+                    case 409:
+                        error = new ConfigError(message, "CONFLICT");
+                        break;
+                    case 413:
+                        error = new ConfigError(message, "PAYLOAD_TOO_LARGE");
+                        break;
+                    case 429:
+                        error = new ConfigError(message, "RATE_LIMITED");
+                        break;
+                    case 500:
+                    case 502:
+                    case 503:
+                    case 504:
+                        error = new ConfigError(message, "SERVER_ERROR");
+                        break;
+                    default:
+                        error = new ConfigError(message, "NETWORK_ERROR");
+                }
+                // Record failure in circuit breaker
+                circuitBreaker.recordFailure(response.status, error);
+                throw error;
             }
-            throw new ConfigError(message, code);
-        }
-        return (await response.json());
-    },
-});
+            // Success: record in circuit breaker (closes if HALF_OPEN)
+            circuitBreaker.recordSuccess();
+            return (await response.json());
+        },
+    };
+};
 //# sourceMappingURL=HttpTransport.js.map

package/dist/types.d.ts

@@ -64,6 +64,8 @@ export interface ConfigClient {
     on<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
     /** Unsubscribe from a lifecycle event. */
     off<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+    /** Clean up timers, listeners, and in-flight requests. */
+    destroy(): void;
 }
 export interface RetryConfig {
     /** Maximum number of retry attempts. Default: 3 */
@@ -104,7 +106,7 @@ export interface ConfigEventPayloads {
     };
     updated: {
         keys: string[];
-        source: "background" | "refresh";
+        source: "background" | "refresh" | "version-check";
     };
     fetchError: {
         error: Error;
@@ -138,6 +140,11 @@ export interface ConfigFetcher {
     fetchAll(): Promise<Record<string, unknown>>;
     /** Fetch specific keys only */
     fetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+    /** Check current config version (lightweight — single Firestore read) */
+    checkVersion(): Promise<{
+        version: string;
+        changedKeys: string[];
+    }>;
 }
 export interface HttpTransport {
     request<T>(endpoint: string, body?: Record<string, unknown>): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jewel998/config",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "sideEffects": false,