@jewel998/config 0.2.6 → 0.2.8

package/dist/client/ConfigClient.js

@@ -32,7 +32,7 @@ export const buildConfigClient = (internals) => {
             batchFetchTriggered = true;
             void (async () => {
                 try {
-                    const result = await withRetry(() => fetcher.fetchAll(), retry);
+                    const { data: 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);
@@ -58,7 +58,7 @@ export const buildConfigClient = (internals) => {
             return;
         void (async () => {
             try {
-                const result = await fetcher.fetchKeys([key]);
+                const { data: result } = await fetcher.fetchKeys([key]);
                 for (const [k, v] of Object.entries(result)) {
                     cache.set(k, v, DEFAULT_CACHE_TTL);
                     data[k] = v;

package/dist/client/RefreshManager.js

@@ -59,7 +59,11 @@ export class RefreshManager {
                 catch {
                     // If version check fails, proceed with full fetch as fallback
                 }
-                const result = await withRetry(() => fetcher.fetchAll(), retry);
+                const { data: result, version: responseVersion } = await withRetry(() => fetcher.fetchAll(), retry);
+                // Sync the version from the config response itself — avoids drifting
+                // from the value learned by the earlier checkVersion() probe.
+                if (responseVersion !== null)
+                    this.cachedVersion = responseVersion;
                 cache.set("__all__", result, DEFAULT_CACHE_TTL);
                 for (const [key, value] of Object.entries(result)) {
                     cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/** API paths used by the SDK transport. */
+export declare const API_ENDPOINTS: {
+    readonly config: "v1/config";
+    readonly version: "v1/version";
+};
+/** Shared HTTP values used by browser and server transports. */
+export declare const HTTP_CONSTANTS: {
+    readonly jsonContentType: "application/json";
+    readonly jsonAccept: "application/json";
+    readonly etagHeader: "ETag";
+    readonly ifNoneMatchHeader: "If-None-Match";
+};

package/dist/constants.js

@@ -0,0 +1,13 @@
+/** API paths used by the SDK transport. */
+export const API_ENDPOINTS = {
+    config: "v1/config",
+    version: "v1/version",
+};
+/** Shared HTTP values used by browser and server transports. */
+export const HTTP_CONSTANTS = {
+    jsonContentType: "application/json",
+    jsonAccept: "application/json",
+    etagHeader: "ETag",
+    ifNoneMatchHeader: "If-None-Match",
+};
+//# sourceMappingURL=constants.js.map

package/dist/fetch/TierFetcher.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigFetcher } from "../types.js";
+import type { ConfigFetcher, FetchResult } from "../types.js";
 export type FetchTier = "prefetch" | "page" | "idle";
 /**
  * TierFetcher — wraps a ConfigFetcher with three responsibilities:
@@ -24,12 +24,12 @@ export declare class TierFetcher {
      * Fetch a specific set of keys under a given tier.
      * Keys already tracked under any tier are skipped (deduplication).
      */
-    fetchTier(keys: string[], tier: FetchTier): Promise<Record<string, unknown>>;
+    fetchTier(keys: string[], tier: FetchTier): Promise<FetchResult>;
     /**
      * Fetch all remaining keys (idle tier).
      * Only keys not already tracked are added to the idle set.
      */
-    fetchAll(): Promise<Record<string, unknown>>;
+    fetchAll(): Promise<FetchResult>;
     /** Check the remote version (passthrough). */
     checkVersion(): ReturnType<ConfigFetcher["checkVersion"]>;
     /**
@@ -37,7 +37,7 @@ export declare class TierFetcher {
      * Used by doRefresh() — we're intentionally re-fetching already-fetched keys
      * with a new context, so the allFetched deduplication should be bypassed.
      */
-    refetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+    refetchKeys(keys: string[]): Promise<FetchResult>;
     /**
      * Record keys as fetched under a tier WITHOUT performing a network fetch.
      * Used when values are hydrated from persistent storage (the boot gate),

package/dist/fetch/TierFetcher.js

@@ -36,9 +36,9 @@ export class TierFetcher {
     async fetchTier(keys, tier) {
         const toFetch = keys.filter((k) => !this.allFetched.has(k));
         if (toFetch.length === 0)
-            return {};
+            return { data: {}, version: null };
         const result = await this.fetcher.fetchKeys(toFetch);
-        this.recordKeys(Object.keys(result), tier);
+        this.recordKeys(Object.keys(result.data), tier);
         return result;
     }
     /**
@@ -47,7 +47,7 @@ export class TierFetcher {
      */
     async fetchAll() {
         const result = await this.fetcher.fetchAll();
-        for (const key of Object.keys(result)) {
+        for (const key of Object.keys(result.data)) {
             if (!this.allFetched.has(key)) {
                 this.fetchedKeys.get("idle").add(key);
                 this.allFetched.add(key);

package/dist/fetch/batchFetcher.js

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

package/dist/fetch/projectedFetcher.js

@@ -1,10 +1,11 @@
+import { API_ENDPOINTS } from "../constants.js";
 export const createProjectedFetcher = (transport) => {
     let pendingKeys = new Set();
     let batchPromise = null;
     return {
         async fetchAll() {
-            const response = await transport.request("v1/config");
-            return response.data;
+            const response = await transport.request(API_ENDPOINTS.config);
+            return { data: response.data, version: response.version ?? null };
         },
         async fetchKeys(keys) {
             for (const key of keys) {
@@ -17,10 +18,10 @@ export const createProjectedFetcher = (transport) => {
                         pendingKeys = new Set();
                         batchPromise = null;
                         try {
-                            const response = await transport.request("v1/config", {
+                            const response = await transport.request(API_ENDPOINTS.config, {
                                 keys: batchedKeys,
                             });
-                            resolve(response.data);
+                            resolve({ data: response.data, version: response.version ?? null });
                         }
                         catch (err) {
                             reject(err);
@@ -32,14 +33,14 @@ export const createProjectedFetcher = (transport) => {
             // Return only the keys this caller requested
             const filtered = {};
             for (const key of keys) {
-                if (key in result) {
-                    filtered[key] = result[key];
+                if (key in result.data) {
+                    filtered[key] = result.data[key];
                 }
             }
-            return filtered;
+            return { data: filtered, version: result.version };
         },
         async checkVersion() {
-            const response = await transport.request("v1/version");
+            const response = await transport.request(API_ENDPOINTS.version);
             return {
                 version: String(response.version),
                 changedKeys: response.changedKeys ?? [],

package/dist/initConfig.js

@@ -27,11 +27,13 @@
 //   Re-fetches only already-fetched keys in tier order.
 // ═══════════════════════════════════════════════════════════════
 import { browserStorage } from "./cache/browserStorage.js";
+import { API_ENDPOINTS } from "./constants.js";
 import { SdkError, ConfigError } from "./errors/index.js";
 import { TypedEventEmitter } from "./events/EventEmitter.js";
 import { createProjectedFetcher } from "./fetch/projectedFetcher.js";
 import { TierFetcher } from "./fetch/TierFetcher.js";
 import { withRetry } from "./retry/RetryEngine.js";
+import { warnForFetchFailure, warnIfCspBlocksUrl } from "./transport/browserDiagnostics.js";
 import { createHttpTransport } from "./transport/HttpTransport.js";
 import { DEFAULT_CACHE_TTL, DEFAULT_RETRY } from "./types.js";
 const DEFAULT_BASE_URL = "https://jewel998-config.web.app/api";
@@ -77,6 +79,7 @@ export function initConfig(options) {
     const defaults = options.defaults ?? {};
     const pollInterval = options.pollInterval ?? 300_000;
     const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    warnIfCspBlocksUrl(baseUrl);
     const storage = options.storage ?? browserStorage();
     const retry = { ...DEFAULT_RETRY };
     const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
@@ -130,7 +133,7 @@ export function initConfig(options) {
     // ── Remote version check (shared by boot gate + polling) ─────
     async function fetchRemoteVersion() {
         try {
-            const res = await fetch(`${baseUrl}/v1/version?clientId=${options.clientId}`, {
+            const res = await fetch(`${baseUrl}/${API_ENDPOINTS.version}?clientId=${options.clientId}`, {
                 headers: cachedVersion ? { "If-None-Match": `"${cachedVersion}"` } : {},
             });
             // 304 => unchanged from the version we sent in If-None-Match.
@@ -141,7 +144,8 @@ export function initConfig(options) {
             const { version } = (await res.json());
             return version ?? null;
         }
-        catch {
+        catch (error) {
+            warnForFetchFailure(`${baseUrl}/${API_ENDPOINTS.version}`, error);
             return null;
         }
     }
@@ -180,12 +184,12 @@ export function initConfig(options) {
                         cachedVersion = remote;
                 }
                 const result = await withRetry(() => tierFetcher.fetchTier(initPrefetch, "prefetch"), retry);
-                const fetched = applyResult(result);
-                // Record the version these values correspond to.
-                const v = await fetchRemoteVersion();
-                if (v !== null)
-                    persistVersion(v);
-                tierFetcher.notifyWaiters(result);
+                const fetched = applyResult(result.data);
+                // Persist the version delivered alongside these values — no extra
+                // /version round trip needed; the /config response carries it.
+                if (result.version !== null)
+                    persistVersion(result.version);
+                tierFetcher.notifyWaiters(result.data);
                 emitUpdated(fetched, "prefetch");
             }
             catch (err) {
@@ -214,11 +218,10 @@ export function initConfig(options) {
                         cachedVersion = remote;
                 }
                 const result = await tierFetcher.fetchAll();
-                const fetched = applyResult(result);
-                const v = await fetchRemoteVersion();
-                if (v !== null)
-                    persistVersion(v);
-                tierFetcher.notifyWaiters(result);
+                const fetched = applyResult(result.data);
+                if (result.version !== null)
+                    persistVersion(result.version);
+                tierFetcher.notifyWaiters(result.data);
                 emitUpdated(fetched, "idle");
             }
             catch {
@@ -261,18 +264,22 @@ export function initConfig(options) {
         if (pf.length > 0) {
             refetches.push(withRetry(() => tierFetcher.refetchKeys(pf), retry)
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
         if (page.length > 0) {
             refetches.push(withRetry(() => tierFetcher.refetchKeys(page), retry)
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
@@ -280,9 +287,11 @@ export function initConfig(options) {
             refetches.push(tierFetcher
                 .fetchAll()
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
@@ -300,8 +309,10 @@ export function initConfig(options) {
             void (async () => {
                 try {
                     const result = await withRetry(() => tierFetcher.fetchTier(keys, "page"), retry);
-                    const fetched = applyResult(result);
-                    tierFetcher.notifyWaiters(result);
+                    const fetched = applyResult(result.data);
+                    if (result.version !== null)
+                        persistVersion(result.version);
+                    tierFetcher.notifyWaiters(result.data);
                     emitUpdated(fetched, "page");
                 }
                 catch (err) {

package/dist/loading/optimistic.js

@@ -3,7 +3,7 @@ import { DEFAULT_CACHE_TTL } from "../types.js";
 const scheduleBackgroundFetch = (ctx) => {
     const doFetch = async () => {
         try {
-            const data = await withRetry(() => ctx.fetcher.fetchAll(), ctx.retry);
+            const { data } = await withRetry(() => ctx.fetcher.fetchAll(), ctx.retry);
             ctx.cache.set("__all__", data, DEFAULT_CACHE_TTL);
             for (const [key, value] of Object.entries(data)) {
                 ctx.cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/loading/pessimistic.js

@@ -7,7 +7,7 @@ export const executePessimistic = async (ctx) => {
         setTimeout(() => reject(new TimeoutError(ctx.timeout)), ctx.timeout);
     });
     try {
-        const data = await Promise.race([fetchPromise, timeoutPromise]);
+        const { data } = await Promise.race([fetchPromise, timeoutPromise]);
         ctx.cache.set("__all__", data, DEFAULT_CACHE_TTL);
         for (const [key, value] of Object.entries(data)) {
             ctx.cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/transport/HttpTransport.js

@@ -1,15 +1,19 @@
 /// <reference lib="dom" />
+import { API_ENDPOINTS, HTTP_CONSTANTS } from "../constants.js";
 import { AuthenticationError, ConfigError, RateLimitError } from "../errors/index.js";
+import { warnForFetchFailure, warnIfCspBlocksUrl } from "./browserDiagnostics.js";
 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) => {
+    warnIfCspBlocksUrl(config.baseUrl);
     const circuitBreaker = new CircuitBreaker({
         fatalCodes: FATAL_STATUS_CODES,
         cooldownMs: CIRCUIT_COOLDOWN_MS,
     });
+    let versionCache;
     return {
         async request(endpoint, body) {
             // ── Circuit breaker check ──────────────────────────────
@@ -35,25 +39,50 @@ export const createHttpTransport = (config) => {
             // 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_");
+            const isVersionRequest = endpoint === API_ENDPOINTS.version;
+            const cachedVersion = isVersionRequest ? versionCache : undefined;
+            const conditionalHeaders = cachedVersion
+                ? { [HTTP_CONSTANTS.ifNoneMatchHeader]: cachedVersion.etag }
+                : {};
             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(","));
+            try {
+                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: HTTP_CONSTANTS.jsonAccept, ...conditionalHeaders },
+                    });
+                }
+                else {
+                    // POST request — full body with context
+                    response = await fetch(url, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": HTTP_CONSTANTS.jsonContentType,
+                            ...conditionalHeaders,
+                        },
+                        body: JSON.stringify({ data: requestData }),
+                    });
                 }
-                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 }),
-                });
+            catch (error) {
+                warnForFetchFailure(url, error);
+                throw error;
+            }
+            // A conditional version request has no response body on 304. Reuse the
+            // last successful body so callers never attempt to parse an empty body.
+            if (response.status === 304 && cachedVersion) {
+                circuitBreaker.recordSuccess();
+                return cachedVersion.body;
+            }
+            if (response.status === 304) {
+                const error = new ConfigError("Version endpoint returned 304 but no cached response is available", "NETWORK_ERROR");
+                circuitBreaker.recordFailure(response.status, error);
+                throw error;
             }
             if (!response.ok) {
                 const errorBody = await response.json().catch(() => ({}));
@@ -103,7 +132,13 @@ export const createHttpTransport = (config) => {
             }
             // Success: record in circuit breaker (closes if HALF_OPEN)
             circuitBreaker.recordSuccess();
-            return (await response.json());
+            const responseBody = (await response.json());
+            if (isVersionRequest) {
+                const etag = response.headers.get(HTTP_CONSTANTS.etagHeader);
+                if (etag)
+                    versionCache = { etag, body: responseBody };
+            }
+            return responseBody;
         },
     };
 };

package/dist/transport/browserDiagnostics.d.ts

@@ -0,0 +1,4 @@
+/** Warn when a readable meta CSP blocks the SDK's API connection. */
+export declare function warnIfCspBlocksUrl(baseUrl: string): void;
+/** Fetch failures are intentionally non-fatal; cached/default values can continue. */
+export declare function warnForFetchFailure(url: string, error: unknown): void;

package/dist/transport/browserDiagnostics.js

@@ -0,0 +1,69 @@
+/// <reference lib="dom" />
+const warnedMessages = new Set();
+function warnOnce(message, cause) {
+    if (warnedMessages.has(message))
+        return;
+    warnedMessages.add(message);
+    if (cause === undefined)
+        console.warn(`[config] ${message}`);
+    else
+        console.warn(`[config] ${message}`, cause);
+}
+function sourceAllowsUrl(source, target) {
+    const normalized = source.replace(/^['"]|['"]$/g, "");
+    if (normalized === "*")
+        return true;
+    if (normalized === "none")
+        return false;
+    if (normalized === "self")
+        return target.origin === window.location.origin;
+    if (/^[a-z][a-z\d+.-]*:$/i.test(normalized))
+        return target.protocol === normalized;
+    try {
+        const sourceUrl = new URL(normalized);
+        if (sourceUrl.protocol !== target.protocol)
+            return false;
+        const sourceHost = sourceUrl.hostname.toLowerCase();
+        const targetHost = target.hostname.toLowerCase();
+        const hostMatches = sourceHost.startsWith("*.")
+            ? targetHost.endsWith(sourceHost.slice(1))
+            : sourceHost === targetHost;
+        const portMatches = !sourceUrl.port || sourceUrl.port === target.port;
+        return hostMatches && portMatches;
+    }
+    catch {
+        return false;
+    }
+}
+/** Warn when a readable meta CSP blocks the SDK's API connection. */
+export function warnIfCspBlocksUrl(baseUrl) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    let target;
+    try {
+        target = new URL(baseUrl, window.location.href);
+    }
+    catch {
+        return;
+    }
+    const policies = Array.from(document.querySelectorAll('meta[http-equiv="Content-Security-Policy"]'))
+        .map((meta) => meta.content)
+        .filter(Boolean);
+    for (const policy of policies) {
+        const directives = policy.split(";").map((directive) => directive.trim().split(/\s+/));
+        const connect = directives.find(([name]) => name === "connect-src");
+        const fallback = directives.find(([name]) => name === "default-src");
+        const sources = connect?.slice(1) ?? fallback?.slice(1);
+        if (sources && !sources.some((source) => sourceAllowsUrl(source, target))) {
+            warnOnce(`CSP may block requests to ${target.origin}. Add ${target.origin} to connect-src (or default-src) in your Content-Security-Policy.`);
+        }
+    }
+}
+/** Fetch failures are intentionally non-fatal; cached/default values can continue. */
+export function warnForFetchFailure(url, error) {
+    if (typeof window === "undefined")
+        return;
+    const message = error instanceof Error ? error.message : String(error);
+    warnOnce(`The config request to ${url} failed. This may be a CORS or CSP connect-src restriction; the SDK will continue using cached/default values.`, message);
+}
+//# sourceMappingURL=browserDiagnostics.js.map

package/dist/types.d.ts

@@ -137,11 +137,22 @@ export interface LoadingResult {
 export interface LoadingStrategyHandler {
     execute(context: LoadingContext): LoadingResult | Promise<LoadingResult>;
 }
+/**
+ * Result of a config fetch — the resolved values plus the config version
+ * they correspond to. The version comes from the same `/config` response
+ * that delivered the data, so the SDK can persist it without a second
+ * `/version` round trip.
+ */
+export interface FetchResult {
+    data: Record<string, unknown>;
+    /** Config version from the response, or null if the response omitted it. */
+    version: string | null;
+}
 export interface ConfigFetcher {
     /** Fetch all configs for the bound project+environment */
-    fetchAll(): Promise<Record<string, unknown>>;
+    fetchAll(): Promise<FetchResult>;
     /** Fetch specific keys only */
-    fetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+    fetchKeys(keys: string[]): Promise<FetchResult>;
     /** Check current config version (lightweight — single Firestore read) */
     checkVersion(): Promise<{
         version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jewel998/config",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "private": false,
   "description": "Free, self-hosted feature flags and remote configuration SDK",
   "keywords": [