@jewel998/config 0.2.0 → 0.2.2

package/README.md

@@ -105,7 +105,7 @@ config.getFlag("feature.checkout_v2"); // Evaluated locally — no round-trip
 │  const flags = initConfig({ clientId, baseUrl })    │
 │  flags.get("feature.dark_mode") → true              │
 └──────────────────────┬──────────────────────────────┘
-                       │ POST /api/getConfig
+                       │ POST /api/v1/config
                        ▼
 ┌──────────────────────────────────────────────────────┐
 │ Your Firebase Hosting (CDN cached)                   │
@@ -137,7 +137,7 @@ config.getFlag("feature.checkout_v2"); // Evaluated locally — no round-trip
 
 ## API Reference
 
-### POST /api/getConfig
+### POST /api/v1/config
 
 The SDK calls this endpoint. Mode is determined by the API key prefix.
 

package/dist/errors/index.d.ts

@@ -4,6 +4,11 @@ export declare class ConfigError extends Error {
     name: string;
     constructor(message: string, code: ConfigErrorCode);
 }
+export declare class RateLimitError extends ConfigError {
+    /** Seconds to wait before retrying (from server Retry-After header) */
+    readonly retryAfterSeconds: number | undefined;
+    constructor(message: string, retryAfterSeconds?: number);
+}
 export declare class InitializationError extends ConfigError {
     readonly cause?: Error | undefined;
     constructor(message: string, cause?: Error | undefined);

package/dist/errors/index.js

@@ -6,6 +6,15 @@ export class ConfigError extends Error {
         this.code = code;
     }
 }
+export class RateLimitError extends ConfigError {
+    /** Seconds to wait before retrying (from server Retry-After header) */
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds) {
+        super(message, "RATE_LIMITED");
+        this.name = "RateLimitError";
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
 export class InitializationError extends ConfigError {
     cause;
     constructor(message, cause) {

package/dist/fetch/batchFetcher.js

@@ -1,15 +1,15 @@
 export const createBatchFetcher = (transport) => ({
     async fetchAll() {
-        const response = await transport.request("getConfig");
+        const response = await transport.request("v1/config");
         return response.data;
     },
     async fetchKeys(_keys) {
         // Batch mode always fetches everything
-        const response = await transport.request("getConfig");
+        const response = await transport.request("v1/config");
         return response.data;
     },
     async checkVersion() {
-        const response = await transport.request("getVersion");
+        const response = await transport.request("v1/version");
         return {
             version: String(response.version),
             changedKeys: response.changedKeys ?? [],

package/dist/fetch/projectedFetcher.js

@@ -3,7 +3,7 @@ export const createProjectedFetcher = (transport) => {
     let batchPromise = null;
     return {
         async fetchAll() {
-            const response = await transport.request("getConfig");
+            const response = await transport.request("v1/config");
             return response.data;
         },
         async fetchKeys(keys) {
@@ -17,7 +17,7 @@ export const createProjectedFetcher = (transport) => {
                         pendingKeys = new Set();
                         batchPromise = null;
                         try {
-                            const response = await transport.request("getConfig", {
+                            const response = await transport.request("v1/config", {
                                 keys: batchedKeys,
                             });
                             resolve(response.data);
@@ -39,7 +39,7 @@ export const createProjectedFetcher = (transport) => {
             return filtered;
         },
         async checkVersion() {
-            const response = await transport.request("getVersion");
+            const response = await transport.request("v1/version");
             return {
                 version: String(response.version),
                 changedKeys: response.changedKeys ?? [],

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export { WEBHOOK_FORMATS, WEBHOOK_FORMAT_INFO, TEMPLATE_VARIABLES, WEBHOOK_EVENT
 export type { WebhookFormat, WebhookEventType, WebhookResourceCategory, } from "./webhook-formats.js";
 export { memoryStorage } from "./cache/memoryStorage.js";
 export { browserStorage } from "./cache/browserStorage.js";
-export { AuthenticationError, ConfigError, InitializationError, TimeoutError, } from "./errors/index.js";
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
 export type { ConfigErrorCode } from "./errors/index.js";

package/dist/index.js

@@ -14,5 +14,5 @@ export { WEBHOOK_FORMATS, WEBHOOK_FORMAT_INFO, TEMPLATE_VARIABLES, WEBHOOK_EVENT
 export { memoryStorage } from "./cache/memoryStorage.js";
 export { browserStorage } from "./cache/browserStorage.js";
 // Errors
-export { AuthenticationError, ConfigError, InitializationError, TimeoutError, } from "./errors/index.js";
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
 //# sourceMappingURL=index.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
@@ -49,7 +50,7 @@ export function initConfig(options) {
     let pollTimer = null;
     async function checkVersion() {
         try {
-            const res = await fetch(`${baseUrl}/getVersion?clientId=${options.clientId}`, {
+            const res = await fetch(`${baseUrl}/v1/version?clientId=${options.clientId}`, {
                 headers: cachedVersion
                     ? { "If-None-Match": `"${cachedVersion}"` }
                     : {},

package/dist/retry/RetryEngine.js

@@ -1,4 +1,4 @@
-import { AuthenticationError, ConfigError } from "../errors/index.js";
+import { AuthenticationError, ConfigError, RateLimitError, } from "../errors/index.js";
 import { DEFAULT_RETRY } from "../types.js";
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const isNonRetryableError = (error) => {
@@ -20,6 +20,20 @@ export const isNonRetryableError = (error) => {
     }
     return false;
 };
+/**
+ * Get the retry delay for an error. If the error is a RateLimitError with
+ * a server-specified Retry-After value, use that instead of calculated backoff.
+ */
+const getRetryDelay = (error, attempt, config) => {
+    // Respect server-specified Retry-After for rate limit errors
+    if (error instanceof RateLimitError && error.retryAfterSeconds != null) {
+        return error.retryAfterSeconds * 1000;
+    }
+    // Default: exponential backoff with jitter
+    const delay = Math.min(config.baseDelay * Math.pow(config.multiplier, attempt), config.maxDelay);
+    // Add jitter (±25%) to prevent thundering herd
+    return delay * (0.75 + Math.random() * 0.5);
+};
 export const withRetry = async (fn, options, onRetry) => {
     const config = { ...DEFAULT_RETRY, ...options };
     let lastError;
@@ -33,11 +47,9 @@ export const withRetry = async (fn, options, onRetry) => {
                 throw error;
             }
             if (attempt < config.maxRetries) {
-                const delay = Math.min(config.baseDelay * Math.pow(config.multiplier, attempt), config.maxDelay);
-                // Add jitter (±25%) to prevent thundering herd
-                const jitter = delay * (0.75 + Math.random() * 0.5);
-                onRetry?.(attempt + 1, lastError, jitter);
-                await sleep(jitter);
+                const delay = getRetryDelay(lastError, attempt, config);
+                onRetry?.(attempt + 1, lastError, delay);
+                await sleep(delay);
             }
         }
     }

package/dist/transport/HttpTransport.js

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { AuthenticationError, ConfigError } from "../errors/index.js";
+import { AuthenticationError, ConfigError, RateLimitError, } from "../errors/index.js";
 import { CircuitBreaker } from "./CircuitBreaker.js";
 /** Errors that should permanently stop retrying (circuit opens) */
 const FATAL_STATUS_CODES = new Set([400, 401, 403]);
@@ -68,9 +68,16 @@ export const createHttpTransport = (config) => {
                     case 413:
                         error = new ConfigError(message, "PAYLOAD_TOO_LARGE");
                         break;
-                    case 429:
-                        error = new ConfigError(message, "RATE_LIMITED");
+                    case 429: {
+                        const retryAfterHeader = response.headers.get("Retry-After");
+                        const retryAfterSeconds = retryAfterHeader
+                            ? parseInt(retryAfterHeader, 10)
+                            : undefined;
+                        error = new RateLimitError(message, Number.isFinite(retryAfterSeconds)
+                            ? retryAfterSeconds
+                            : undefined);
                         break;
+                    }
                     case 500:
                     case 502:
                     case 503:

package/package.json

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