@jewel998/config 0.2.2 → 0.2.4

package/dist/server/initServerConfig.d.ts

@@ -0,0 +1,110 @@
+import type { EvaluationContext, EvaluationPlugin } from "../plugins/types.js";
+import type { CacheStorage, ConfigClient, FetchGranularity, RetryConfig } from "../types.js";
+export interface InitServerConfigOptions {
+    /**
+     * Required. Server API key from the portal (must start with `svr_`).
+     *
+     * Server keys return full flag data (targeting rules, rollouts, segments)
+     * for local evaluation. The Cloud Function does NOT validate the
+     * request origin for server keys — no domain allowlist is enforced.
+     */
+    clientId: string;
+    /**
+     * Your self-hosted API URL. Points to your Firebase deployment.
+     * Default: https://jewel998-config.web.app/api (demo instance)
+     *
+     * @example "https://your-project.web.app/api"
+     */
+    baseUrl?: string;
+    /**
+     * Evaluation context for targeting rules and rollouts.
+     * Use `serverContext()` helper to build this from request/session data.
+     *
+     * Can be updated post-init via `setContext()` for per-request evaluation.
+     */
+    context?: EvaluationContext;
+    /**
+     * Evaluation plugins to register (tree-shakeable pipeline steps).
+     *
+     * @example
+     * ```ts
+     * import { targetingPlugin } from "@jewel998/config/targeting";
+     * import { rolloutPlugin } from "@jewel998/config/rollout";
+     *
+     * const config = await initServerConfig({
+     *   clientId: "svr_xxx",
+     *   plugins: [targetingPlugin(), rolloutPlugin()],
+     * });
+     * ```
+     */
+    plugins?: EvaluationPlugin[];
+    /**
+     * Fetch granularity.
+     * - "batch" (default): Fetch all flags in one request (recommended for servers)
+     * - "projected": Fetch only specific keys on demand
+     */
+    fetchGranularity?: FetchGranularity;
+    /** Cache storage adapter. Default: memoryStorage() (in-process Map) */
+    storage?: CacheStorage;
+    /** Retry configuration for failed fetches */
+    retry?: RetryConfig;
+    /** Timeout for initial fetch (ms). Default: 10000 */
+    timeout?: number;
+    /**
+     * Background refresh interval in milliseconds.
+     * The SDK will periodically re-fetch flags to keep them current.
+     *
+     * Default: 0 (disabled). Set to e.g. 60_000 for 1-minute refresh.
+     *
+     * For most server apps, calling `refresh()` after receiving a webhook
+     * notification is more efficient than background polling.
+     */
+    refreshInterval?: number;
+}
+export interface ServerFlags extends ConfigClient {
+    /**
+     * Gracefully shut down the SDK.
+     * Stops background refresh timers and cleans up listeners.
+     * Call this on server shutdown (SIGTERM handler, etc.)
+     */
+    close(): void;
+}
+/**
+ * Initialize the server-side feature flags SDK.
+ *
+ * Returns a Promise that resolves once flags are fetched from the API.
+ * This is a pessimistic strategy — your server won't serve requests
+ * with stale/empty flags.
+ *
+ * @example
+ * ```ts
+ * import { initServerConfig, serverContext } from "@jewel998/config/server";
+ * import { targetingPlugin } from "@jewel998/config/targeting";
+ * import { rolloutPlugin } from "@jewel998/config/rollout";
+ *
+ * // Initialize once at server startup
+ * const flags = await initServerConfig({
+ *   clientId: "svr_xxx",
+ *   baseUrl: "https://your-project.web.app/api",
+ *   plugins: [targetingPlugin(), rolloutPlugin()],
+ *   refreshInterval: 60_000, // re-fetch every minute
+ * });
+ *
+ * // In request handlers:
+ * app.get("/api/feature", (req, res) => {
+ *   flags.setContext(serverContext({
+ *     userId: req.user.id,
+ *     plan: req.user.plan,
+ *   }));
+ *
+ *   res.json({
+ *     newCheckout: flags.getFlag("feature.checkout_v2"),
+ *     uploadLimit: flags.getValue("app.upload_limit", 50),
+ *   });
+ * });
+ *
+ * // Graceful shutdown
+ * process.on("SIGTERM", () => flags.close());
+ * ```
+ */
+export declare function initServerConfig(options: InitServerConfigOptions): Promise<ServerFlags>;

package/dist/server/initServerConfig.js

@@ -0,0 +1,159 @@
+// ═══════════════════════════════════════════════════════════════
+// initServerConfig — Server-side SDK entry point
+//
+// Designed for Node.js, Deno, Bun, and server-side runtimes.
+// Does NOT use window, document, navigator, localStorage,
+// or any browser-specific APIs.
+//
+// Key differences from initConfig (browser):
+//   - Always uses pessimistic strategy (await flags before serving)
+//   - No polling (server processes are long-lived; use refresh())
+//   - No visibility change detection
+//   - Plugins always run locally (svr_ keys provide full flag data)
+//   - Optional background refresh via configurable interval
+// ═══════════════════════════════════════════════════════════════
+import { memoryStorage } from "../cache/memoryStorage.js";
+import { buildConfigClient } from "../client/ConfigClient.js";
+import { ConfigError } from "../errors/index.js";
+import { TypedEventEmitter } from "../events/EventEmitter.js";
+import { createBatchFetcher } from "../fetch/batchFetcher.js";
+import { createProjectedFetcher } from "../fetch/projectedFetcher.js";
+import { executePessimistic } from "../loading/pessimistic.js";
+import { createHttpTransport } from "../transport/HttpTransport.js";
+import { DEFAULT_RETRY, DEFAULT_TIMEOUT } from "../types.js";
+/**
+ * Initialize the server-side feature flags SDK.
+ *
+ * Returns a Promise that resolves once flags are fetched from the API.
+ * This is a pessimistic strategy — your server won't serve requests
+ * with stale/empty flags.
+ *
+ * @example
+ * ```ts
+ * import { initServerConfig, serverContext } from "@jewel998/config/server";
+ * import { targetingPlugin } from "@jewel998/config/targeting";
+ * import { rolloutPlugin } from "@jewel998/config/rollout";
+ *
+ * // Initialize once at server startup
+ * const flags = await initServerConfig({
+ *   clientId: "svr_xxx",
+ *   baseUrl: "https://your-project.web.app/api",
+ *   plugins: [targetingPlugin(), rolloutPlugin()],
+ *   refreshInterval: 60_000, // re-fetch every minute
+ * });
+ *
+ * // In request handlers:
+ * app.get("/api/feature", (req, res) => {
+ *   flags.setContext(serverContext({
+ *     userId: req.user.id,
+ *     plan: req.user.plan,
+ *   }));
+ *
+ *   res.json({
+ *     newCheckout: flags.getFlag("feature.checkout_v2"),
+ *     uploadLimit: flags.getValue("app.upload_limit", 50),
+ *   });
+ * });
+ *
+ * // Graceful shutdown
+ * process.on("SIGTERM", () => flags.close());
+ * ```
+ */
+export async function initServerConfig(options) {
+    // ── Validation ─────────────────────────────────────────────
+    if (!options.clientId) {
+        throw new ConfigError("clientId is required", "MISSING_CLIENT_ID");
+    }
+    if (!options.clientId.startsWith("svr_")) {
+        throw new ConfigError("Server SDK requires a server key (svr_ prefix). " +
+            "Client keys (cid_) are for the browser SDK — they don't return " +
+            "full flag data needed for local evaluation.", "INITIALIZATION_FAILED");
+    }
+    // ── Resolve defaults ───────────────────────────────────────
+    const baseUrl = options.baseUrl ?? "https://jewel998-config.web.app/api";
+    const granularity = options.fetchGranularity ?? "batch";
+    const storage = options.storage ?? memoryStorage();
+    const retry = { ...DEFAULT_RETRY, ...options.retry };
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const refreshInterval = options.refreshInterval ?? 0;
+    const plugins = options.plugins ?? [];
+    // Server keys always evaluate locally (client mode)
+    const evaluationMode = "client";
+    // Mutable context reference
+    let currentContext = options.context ?? {};
+    // ── Create internal modules ────────────────────────────────
+    const transport = createHttpTransport({
+        baseUrl,
+        clientId: options.clientId,
+        evaluationMode,
+        getContext: () => currentContext,
+    });
+    const events = new TypedEventEmitter();
+    const fetcher = granularity === "batch" ? createBatchFetcher(transport) : createProjectedFetcher(transport);
+    // ── Pessimistic load — await flags before returning ────────
+    const loadResult = await executePessimistic({
+        clientId: options.clientId,
+        fetcher,
+        cache: storage,
+        events,
+        retry,
+        timeout,
+        granularity,
+    });
+    // ── Build the config client ────────────────────────────────
+    const client = buildConfigClient({
+        data: loadResult.initialData,
+        cache: storage,
+        fetcher,
+        events,
+        retry,
+        granularity,
+        isDeferred: false,
+        plugins,
+        context: options.context,
+        evaluationMode,
+        onContextChange: (ctx) => {
+            currentContext = ctx;
+        },
+    });
+    events.emit("ready", {
+        loadingStrategy: "pessimistic",
+        cachedKeys: Object.keys(loadResult.initialData).length,
+    });
+    // ── Background refresh (optional) ─────────────────────────
+    let refreshTimer = null;
+    if (refreshInterval > 0) {
+        refreshTimer = setInterval(() => {
+            void client.refresh();
+        }, refreshInterval);
+        // Ensure the timer doesn't prevent Node.js process from exiting.
+        // In Node.js, setInterval returns an object with .unref().
+        // We use a safe dynamic check to avoid depending on @types/node.
+        const timer = refreshTimer;
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+    }
+    // ── Return ServerFlags (extends ConfigClient + close()) ────
+    const serverFlags = {
+        getValue: client.getValue,
+        getFlag: client.getFlag,
+        getAll: client.getAll,
+        refresh: client.refresh,
+        setContext: client.setContext,
+        on: client.on,
+        off: client.off,
+        destroy() {
+            if (refreshTimer) {
+                clearInterval(refreshTimer);
+                refreshTimer = null;
+            }
+            client.destroy();
+        },
+        close() {
+            serverFlags.destroy();
+        },
+    };
+    return serverFlags;
+}
+//# sourceMappingURL=initServerConfig.js.map

package/dist/server/serverContext.d.ts

@@ -0,0 +1,63 @@
+import type { EvaluationContext } from "../plugins/types.js";
+export interface ServerContextOptions {
+    /** The authenticated user's ID. Should be stable (database ID, not session). */
+    userId?: string;
+    /**
+     * Custom attributes for targeting rules.
+     * Typically derived from the authenticated user, request headers, or environment.
+     *
+     * @example
+     * ```ts
+     * serverContext({
+     *   userId: req.user.id,
+     *   plan: req.user.plan,
+     *   country: req.headers["cf-ipcountry"],
+     *   locale: req.headers["accept-language"]?.split(",")[0],
+     * })
+     * ```
+     */
+    [key: string]: string | number | boolean | string[] | undefined;
+}
+/**
+ * Build an evaluation context from server-side data.
+ *
+ * Unlike `autoContext()` (browser-side), this does NOT auto-detect anything.
+ * In server environments, context comes from your request/session/database
+ * — not from `navigator` or `window`.
+ *
+ * @example
+ * ```ts
+ * import { initServerConfig, serverContext } from "@jewel998/config/server";
+ *
+ * // In an Express route handler:
+ * app.get("/dashboard", (req, res) => {
+ *   const flags = initServerConfig({
+ *     clientId: "svr_xxx",
+ *     context: serverContext({
+ *       userId: req.user.id,
+ *       plan: req.user.plan,
+ *       country: req.headers["cf-ipcountry"],
+ *       role: req.user.role,
+ *     }),
+ *   });
+ *
+ *   if (flags.getFlag("feature.new_dashboard")) {
+ *     // serve new dashboard
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // For per-request context updates (shared instance):
+ * const config = await initServerConfig({ clientId: "svr_xxx" });
+ *
+ * // On each request:
+ * config.setContext(serverContext({
+ *   userId: req.user.id,
+ *   plan: req.user.plan,
+ * }));
+ * config.getFlag("feature.checkout_v2");
+ * ```
+ */
+export declare function serverContext(options?: ServerContextOptions): EvaluationContext;

package/dist/server/serverContext.js

@@ -0,0 +1,64 @@
+// ═══════════════════════════════════════════════════════════════
+// Server Context Helper
+//
+// The server-side equivalent of autoContext(). Provides a clean
+// way to build evaluation context from server-side data sources
+// (HTTP requests, environment variables, session objects, etc.)
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Build an evaluation context from server-side data.
+ *
+ * Unlike `autoContext()` (browser-side), this does NOT auto-detect anything.
+ * In server environments, context comes from your request/session/database
+ * — not from `navigator` or `window`.
+ *
+ * @example
+ * ```ts
+ * import { initServerConfig, serverContext } from "@jewel998/config/server";
+ *
+ * // In an Express route handler:
+ * app.get("/dashboard", (req, res) => {
+ *   const flags = initServerConfig({
+ *     clientId: "svr_xxx",
+ *     context: serverContext({
+ *       userId: req.user.id,
+ *       plan: req.user.plan,
+ *       country: req.headers["cf-ipcountry"],
+ *       role: req.user.role,
+ *     }),
+ *   });
+ *
+ *   if (flags.getFlag("feature.new_dashboard")) {
+ *     // serve new dashboard
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // For per-request context updates (shared instance):
+ * const config = await initServerConfig({ clientId: "svr_xxx" });
+ *
+ * // On each request:
+ * config.setContext(serverContext({
+ *   userId: req.user.id,
+ *   plan: req.user.plan,
+ * }));
+ * config.getFlag("feature.checkout_v2");
+ * ```
+ */
+export function serverContext(options) {
+    if (!options)
+        return {};
+    const { userId, ...attrs } = options;
+    const attributes = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v !== undefined)
+            attributes[k] = v;
+    }
+    return {
+        userId,
+        attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
+    };
+}
+//# sourceMappingURL=serverContext.js.map

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+export { initServerConfig } from "./server/initServerConfig.js";
+export type { InitServerConfigOptions, ServerFlags } from "./server/initServerConfig.js";
+export { serverContext } from "./server/serverContext.js";
+export type { ServerContextOptions } from "./server/serverContext.js";
+export type { CacheStorage, ConfigClient, ConfigEventCallback, ConfigEventPayloads, ConfigEventType, ConfigRecord, CreateConfigOptions, EvaluationWarning, FetchGranularity, LoadingStrategy, RetryConfig, } from "./types.js";
+export type { EvaluationContext, EvaluationPlugin, PipelineStepId, PipelineStepResult, PipelineHelpers, } from "./plugins/types.js";
+export { PIPELINE_ORDER } from "./plugins/types.js";
+export { memoryStorage } from "./cache/memoryStorage.js";
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
+export type { ConfigErrorCode } from "./errors/index.js";

package/dist/server.js

@@ -0,0 +1,20 @@
+// ═══════════════════════════════════════════════════════════════
+// @jewel998/config — Server (Node.js) Entry Point
+//
+// This module provides the backend SDK that runs in Node.js,
+// Deno, Bun, or any server-side JavaScript runtime.
+//
+// It does NOT import any browser-specific code (localStorage,
+// navigator, document, window). Tree-shaking ensures that
+// frontend-only modules are never bundled into server builds.
+// ═══════════════════════════════════════════════════════════════
+// Server-specific entry point
+export { initServerConfig } from "./server/initServerConfig.js";
+// Server context helper (equivalent of autoContext for Node.js)
+export { serverContext } from "./server/serverContext.js";
+export { PIPELINE_ORDER } from "./plugins/types.js";
+// Cache adapters (memory only — no browser storage)
+export { memoryStorage } from "./cache/memoryStorage.js";
+// Errors
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
+//# sourceMappingURL=server.js.map

package/dist/transport/HttpTransport.js

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { AuthenticationError, ConfigError, RateLimitError, } 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]);
@@ -32,15 +32,29 @@ export const createHttpTransport = (config) => {
                     };
                 }
             }
-            const response = await fetch(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({
-                    data: requestData,
-                }),
-            });
+            // Client keys (cid_) use POST with body (server-side evaluation needs context).
+            // Server keys (svr_) use GET with query params (fetches full flag data).
+            const isServerKey = config.clientId.startsWith("svr_");
+            let response;
+            if (isServerKey) {
+                // GET request — clientId as query param
+                const params = new URLSearchParams({ clientId: config.clientId });
+                if (body?.keys && Array.isArray(body.keys)) {
+                    params.set("keys", body.keys.join(","));
+                }
+                response = await fetch(`${url}?${params.toString()}`, {
+                    method: "GET",
+                    headers: { Accept: "application/json" },
+                });
+            }
+            else {
+                // POST request — full body with context
+                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;
@@ -70,12 +84,8 @@ export const createHttpTransport = (config) => {
                         break;
                     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);
+                        const retryAfterSeconds = retryAfterHeader ? parseInt(retryAfterHeader, 10) : undefined;
+                        error = new RateLimitError(message, Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined);
                         break;
                     }
                     case 500:

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import type { EvaluationContext, EvaluationPlugin } from "./plugins/types.js";
 /** Loading strategy for SDK initialization */
 export type LoadingStrategy = "optimistic" | "pessimistic" | "deferred";
+/** Fetch tier for priority-based key fetching */
+export type FetchTier = "critical" | "page" | "prefetch";
 /** Evaluation mode for the SDK */
 export type EvaluationMode = "server" | "client";
 /** Fetch granularity for remote config retrieval */
@@ -106,7 +108,7 @@ export interface ConfigEventPayloads {
     };
     updated: {
         keys: string[];
-        source: "background" | "refresh" | "version-check";
+        source: "background" | "refresh" | "version-check" | "prefetch" | "page" | "idle";
     };
     fetchError: {
         error: Error;

package/dist/webhook-formats.js

@@ -105,12 +105,7 @@ export const TEMPLATE_VARIABLES = [
 /**
  * Event types that can trigger webhooks.
  */
-export const WEBHOOK_EVENT_TYPES = [
-    "create",
-    "update",
-    "delete",
-    "state_change",
-];
+export const WEBHOOK_EVENT_TYPES = ["create", "update", "delete", "state_change"];
 /**
  * Resource categories for webhook filtering.
  */

package/package.json

@@ -1,33 +1,46 @@
 {
   "name": "@jewel998/config",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
-  "type": "module",
-  "sideEffects": false,
   "description": "Free, self-hosted feature flags and remote configuration SDK",
-  "author": "Jyotirmoy Barman",
-  "homepage": "https://github.com/jewel998/config#readme",
-  "bugs": {
-    "url": "https://github.com/jewel998/config/issues"
-  },
   "keywords": [
+    "a-b-testing",
+    "configuration",
     "feature-flags",
-    "remote-config",
+    "feature-management",
     "feature-toggles",
-    "self-hosted",
     "firebase",
-    "sdk",
-    "configuration",
-    "targeting",
+    "free",
+    "launchdarkly-alternative",
+    "open-source",
+    "percentage-rollout",
+    "remote-config",
     "rollout",
-    "a-b-testing"
+    "sdk",
+    "segments",
+    "self-hosted",
+    "server-side-evaluation",
+    "targeting"
   ],
+  "homepage": "https://github.com/jewel998/config#readme",
+  "bugs": {
+    "url": "https://github.com/jewel998/config/issues"
+  },
+  "license": "Elastic-2.0",
+  "author": "Jyotirmoy Barman",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jewel998/config.git",
     "directory": "packages/config"
   },
-  "license": "Elastic-2.0",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -35,6 +48,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
     "./storage": {
       "types": "./dist/cache/memoryStorage.d.ts",
       "import": "./dist/cache/memoryStorage.js"
@@ -68,15 +85,6 @@
       "import": "./dist/plugins/overrides/index.js"
     }
   },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22.0.0"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch",
@@ -86,6 +94,9 @@
   },
   "devDependencies": {
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
   }
 }