pulse-updates 1.0.13 → 1.0.15

package/lib/commonjs/config.js

@@ -0,0 +1,282 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.configureConfig = configureConfig;
+exports.fetchConfig = fetchConfig;
+exports.getAllConfig = getAllConfig;
+exports.getConfigBoolean = getConfigBoolean;
+exports.getConfigInfo = getConfigInfo;
+exports.getConfigNumber = getConfigNumber;
+exports.getConfigString = getConfigString;
+exports.getConfigValue = getConfigValue;
+exports.onConfigChange = onConfigChange;
+exports.resetConfigForTests = resetConfigForTests;
+exports.setConfigDefaults = setConfigDefaults;
+exports.startConfigAutoRefresh = startConfigAutoRefresh;
+/**
+ * Pulse Config — the client half of the Firebase Remote Config replacement.
+ *
+ * Why this exists: from 2026-09-01 Firebase bills every Remote Config fetch above
+ * 100k/day and throttles projects that stay on the free plan. Worse than the bill is
+ * the failure mode — the Firebase SDK yields the type's zero value for a key it does
+ * not hold, so a throttled fetch reads as "every flag is false" and, for an ads
+ * config, quietly turns the revenue off.
+ *
+ * The shape here deliberately mirrors what the apps already do with Remote Config —
+ * defaults, fetch, activate, typed getters — so swapping the source is a change of
+ * adapter, not of every call site. Three things are different on purpose:
+ *
+ *  1. A missing key falls back to the registered default, never to false/0. That is
+ *     the exact bug this replaces.
+ *  2. The last good values are persisted and reloaded at boot, so a failed fetch
+ *     degrades to yesterday's config rather than to nothing.
+ *  3. Fetching is cheap (our server, no per-request price), so it happens on launch,
+ *     on every return from foreground, and on a timer — with ETag, so an unchanged
+ *     config costs a 304 with no body.
+ */
+
+/**
+ * Everything the server may ever want to target on. Sent on every request even when
+ * no rule uses it yet: the client can only start sending a new field with a store
+ * build, so a contract that is incomplete today cannot be completed for months.
+ */
+
+const STORAGE_KEY = 'pulse.config.v1';
+const DEFAULT_POLL_MS = 5 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+let options = null;
+let defaults = {};
+let values = {};
+let etag = null;
+let fetchedAt = 0;
+let source = 'defaults';
+let inFlight = null;
+let pollTimer = null;
+const listeners = new Set();
+
+/**
+ * Registers defaults and reloads the last good payload from storage, synchronously,
+ * so the very first read at boot already has real values instead of a blank config
+ * while the network call is in flight.
+ */
+function configureConfig(opts) {
+  options = opts;
+  defaults = {
+    ...(opts.defaults ?? {})
+  };
+  const cached = readCache(opts.storage);
+  if (cached) {
+    values = cached.values;
+    etag = cached.etag;
+    fetchedAt = cached.fetchedAt;
+    source = 'cache';
+  }
+}
+
+/** Merge more defaults after configure (a late-loading module registering its own). */
+function setConfigDefaults(more) {
+  defaults = {
+    ...defaults,
+    ...more
+  };
+}
+
+/**
+ * Fetch, and adopt the payload if it changed. Returns true when new values were
+ * applied — false for "nothing changed" (304) and false for a failure, which are
+ * deliberately indistinguishable to callers: in both cases the current values stand.
+ * Errors surface through onError instead of rejecting, because no caller should have
+ * to wrap a config refresh in a try/catch to keep the app running.
+ */
+async function fetchConfig() {
+  if (!options) return false;
+  // Collapse concurrent calls (launch + resume can land together) onto one request.
+  if (inFlight) return inFlight;
+  inFlight = (async () => {
+    const opts = options;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) : null;
+    try {
+      const response = await fetch(opts.url, {
+        method: 'GET',
+        headers: buildHeaders(opts, etag),
+        signal: controller?.signal
+      });
+      if (response.status === 304) return false;
+      if (!response.ok) throw new Error(`Pulse config HTTP ${response.status}`);
+      const payload = await response.json();
+      const nextValues = payload?.values ?? {};
+      values = nextValues;
+      etag = response.headers?.get?.('etag') ?? null;
+      fetchedAt = Date.now();
+      source = 'remote';
+      writeCache(opts.storage, {
+        values,
+        etag,
+        fetchedAt
+      });
+      notify();
+      return true;
+    } catch (error) {
+      // A failed refresh must never clear what we have: the whole point of the cache
+      // is that an unreachable server degrades to the last good config.
+      opts.onError?.(error);
+      return false;
+    } finally {
+      if (timer) clearTimeout(timer);
+      inFlight = null;
+    }
+  })();
+  return inFlight;
+}
+
+/**
+ * Fetch on launch, on every return to the foreground, and on a timer.
+ * Returns a function that stops both.
+ */
+function startConfigAutoRefresh(appState) {
+  void fetchConfig();
+  const subscription = appState?.addEventListener('change', state => {
+    if (state === 'active') void fetchConfig();
+  });
+  const interval = options?.pollIntervalMs ?? DEFAULT_POLL_MS;
+  if (interval > 0) {
+    stopPolling();
+    pollTimer = setInterval(() => void fetchConfig(), interval);
+  }
+  return () => {
+    subscription?.remove();
+    stopPolling();
+  };
+}
+function stopPolling() {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}
+
+// ─── Reads ────────────────────────────────────────────────────────────────────
+
+/** The served value, or the registered default. Never a type's zero value. */
+function getConfigValue(key) {
+  if (Object.prototype.hasOwnProperty.call(values, key) && values[key] !== null) {
+    return values[key];
+  }
+  const fallback = defaults[key];
+  return fallback === undefined ? null : fallback;
+}
+function getConfigBoolean(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'boolean') return value;
+  // A server that sends "true" as a string must not read as false.
+  if (typeof value === 'string') return value.toLowerCase() === 'true';
+  if (typeof value === 'number') return value !== 0;
+  return false;
+}
+function getConfigNumber(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  return 0;
+}
+function getConfigString(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/** Defaults first, then everything the server sent — what a caller would see key by key. */
+function getAllConfig() {
+  return {
+    ...defaults,
+    ...values
+  };
+}
+function onConfigChange(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** For diagnostics: where the current values came from and how old they are. */
+function getConfigInfo() {
+  return {
+    source,
+    fetchedAt,
+    etag,
+    keyCount: Object.keys(getAllConfig()).length
+  };
+}
+
+/** Test seam: drops every piece of module state. */
+function resetConfigForTests() {
+  options = null;
+  defaults = {};
+  values = {};
+  etag = null;
+  fetchedAt = 0;
+  source = 'defaults';
+  inFlight = null;
+  listeners.clear();
+  stopPolling();
+}
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+function buildHeaders(opts, currentEtag) {
+  const ctx = opts.getContext?.() ?? {};
+  const headers = {
+    Accept: 'application/json'
+  };
+  if (ctx.platform) headers['X-Pulse-Platform'] = ctx.platform;
+  if (ctx.appVersion) headers['X-Pulse-App-Version'] = ctx.appVersion;
+  if (ctx.osVersion) headers['X-Pulse-Os-Version'] = ctx.osVersion;
+  if (ctx.language) headers['X-Pulse-Language'] = ctx.language;
+  if (ctx.deviceId) headers['Pulse-Device-Id'] = ctx.deviceId;
+  if (ctx.userAttributes && Object.keys(ctx.userAttributes).length > 0) {
+    headers['X-Pulse-User-Attributes'] = JSON.stringify(ctx.userAttributes);
+  }
+  // Country is deliberately absent: the server reads it from the edge, which a client
+  // header cannot spoof to opt into a targeted rollout.
+
+  if (currentEtag) headers['If-None-Match'] = currentEtag;
+  return headers;
+}
+function readCache(storage) {
+  if (!storage) return null;
+  try {
+    const raw = storage.getString(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.values) return null;
+    return parsed;
+  } catch {
+    // A corrupt cache is not worth a crash at boot: fall back to defaults.
+    return null;
+  }
+}
+function writeCache(storage, payload) {
+  if (!storage) return;
+  try {
+    storage.set(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Persistence is an optimisation; failing to write must not fail the fetch.
+  }
+}
+function notify() {
+  const snapshot = getAllConfig();
+  listeners.forEach(listener => {
+    try {
+      listener(snapshot);
+    } catch {
+      // One bad listener must not stop the others from being told.
+    }
+  });
+}
+//# sourceMappingURL=config.js.map

package/lib/commonjs/config.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["STORAGE_KEY","DEFAULT_POLL_MS","DEFAULT_TIMEOUT_MS","options","defaults","values","etag","fetchedAt","source","inFlight","pollTimer","listeners","Set","configureConfig","opts","cached","readCache","storage","setConfigDefaults","more","fetchConfig","controller","AbortController","timer","setTimeout","abort","timeoutMs","response","fetch","url","method","headers","buildHeaders","signal","status","ok","Error","payload","json","nextValues","get","Date","now","writeCache","notify","error","onError","clearTimeout","startConfigAutoRefresh","appState","subscription","addEventListener","state","interval","pollIntervalMs","stopPolling","setInterval","remove","clearInterval","getConfigValue","key","Object","prototype","hasOwnProperty","call","fallback","undefined","getConfigBoolean","value","toLowerCase","getConfigNumber","parsed","Number","isNaN","getConfigString","String","getAllConfig","onConfigChange","listener","add","delete","getConfigInfo","keyCount","keys","length","resetConfigForTests","clear","currentEtag","ctx","getContext","Accept","platform","appVersion","osVersion","language","deviceId","userAttributes","JSON","stringify","raw","getString","parse","set","snapshot","forEach"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/index.js

@@ -52,4 +52,16 @@ Object.keys(_types).forEach(function (key) {
 });
 var _usePulseUpdates = require("./usePulseUpdates");
 var _assetResolver = require("./assetResolver");
+var _config = require("./config");
+Object.keys(_config).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _config[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _config[key];
+    }
+  });
+});
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_PulseUpdates","require","Object","keys","forEach","key","prototype","hasOwnProperty","call","_exportNames","exports","defineProperty","enumerable","get","_types","_usePulseUpdates","_assetResolver"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,aAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,aAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAL,aAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAb,aAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAS,MAAA,GAAAb,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAW,MAAA,EAAAV,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAS,MAAA,CAAAT,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAC,MAAA,CAAAT,GAAA;IAAA;EAAA;AAAA;AACA,IAAAU,gBAAA,GAAAd,OAAA;AACA,IAAAe,cAAA,GAAAf,OAAA","ignoreList":[]}
+{"version":3,"names":["_PulseUpdates","require","Object","keys","forEach","key","prototype","hasOwnProperty","call","_exportNames","exports","defineProperty","enumerable","get","_types","_usePulseUpdates","_assetResolver","_config"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,aAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,aAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAL,aAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAb,aAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAS,MAAA,GAAAb,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAW,MAAA,EAAAV,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAS,MAAA,CAAAT,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAC,MAAA,CAAAT,GAAA;IAAA;EAAA;AAAA;AACA,IAAAU,gBAAA,GAAAd,OAAA;AACA,IAAAe,cAAA,GAAAf,OAAA;AACA,IAAAgB,OAAA,GAAAhB,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAc,OAAA,EAAAb,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAY,OAAA,CAAAZ,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAI,OAAA,CAAAZ,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}

package/lib/module/config.js

@@ -0,0 +1,265 @@
+/**
+ * Pulse Config — the client half of the Firebase Remote Config replacement.
+ *
+ * Why this exists: from 2026-09-01 Firebase bills every Remote Config fetch above
+ * 100k/day and throttles projects that stay on the free plan. Worse than the bill is
+ * the failure mode — the Firebase SDK yields the type's zero value for a key it does
+ * not hold, so a throttled fetch reads as "every flag is false" and, for an ads
+ * config, quietly turns the revenue off.
+ *
+ * The shape here deliberately mirrors what the apps already do with Remote Config —
+ * defaults, fetch, activate, typed getters — so swapping the source is a change of
+ * adapter, not of every call site. Three things are different on purpose:
+ *
+ *  1. A missing key falls back to the registered default, never to false/0. That is
+ *     the exact bug this replaces.
+ *  2. The last good values are persisted and reloaded at boot, so a failed fetch
+ *     degrades to yesterday's config rather than to nothing.
+ *  3. Fetching is cheap (our server, no per-request price), so it happens on launch,
+ *     on every return from foreground, and on a timer — with ETag, so an unchanged
+ *     config costs a 304 with no body.
+ */
+
+/**
+ * Everything the server may ever want to target on. Sent on every request even when
+ * no rule uses it yet: the client can only start sending a new field with a store
+ * build, so a contract that is incomplete today cannot be completed for months.
+ */
+
+const STORAGE_KEY = 'pulse.config.v1';
+const DEFAULT_POLL_MS = 5 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+let options = null;
+let defaults = {};
+let values = {};
+let etag = null;
+let fetchedAt = 0;
+let source = 'defaults';
+let inFlight = null;
+let pollTimer = null;
+const listeners = new Set();
+
+/**
+ * Registers defaults and reloads the last good payload from storage, synchronously,
+ * so the very first read at boot already has real values instead of a blank config
+ * while the network call is in flight.
+ */
+export function configureConfig(opts) {
+  options = opts;
+  defaults = {
+    ...(opts.defaults ?? {})
+  };
+  const cached = readCache(opts.storage);
+  if (cached) {
+    values = cached.values;
+    etag = cached.etag;
+    fetchedAt = cached.fetchedAt;
+    source = 'cache';
+  }
+}
+
+/** Merge more defaults after configure (a late-loading module registering its own). */
+export function setConfigDefaults(more) {
+  defaults = {
+    ...defaults,
+    ...more
+  };
+}
+
+/**
+ * Fetch, and adopt the payload if it changed. Returns true when new values were
+ * applied — false for "nothing changed" (304) and false for a failure, which are
+ * deliberately indistinguishable to callers: in both cases the current values stand.
+ * Errors surface through onError instead of rejecting, because no caller should have
+ * to wrap a config refresh in a try/catch to keep the app running.
+ */
+export async function fetchConfig() {
+  if (!options) return false;
+  // Collapse concurrent calls (launch + resume can land together) onto one request.
+  if (inFlight) return inFlight;
+  inFlight = (async () => {
+    const opts = options;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) : null;
+    try {
+      const response = await fetch(opts.url, {
+        method: 'GET',
+        headers: buildHeaders(opts, etag),
+        signal: controller?.signal
+      });
+      if (response.status === 304) return false;
+      if (!response.ok) throw new Error(`Pulse config HTTP ${response.status}`);
+      const payload = await response.json();
+      const nextValues = payload?.values ?? {};
+      values = nextValues;
+      etag = response.headers?.get?.('etag') ?? null;
+      fetchedAt = Date.now();
+      source = 'remote';
+      writeCache(opts.storage, {
+        values,
+        etag,
+        fetchedAt
+      });
+      notify();
+      return true;
+    } catch (error) {
+      // A failed refresh must never clear what we have: the whole point of the cache
+      // is that an unreachable server degrades to the last good config.
+      opts.onError?.(error);
+      return false;
+    } finally {
+      if (timer) clearTimeout(timer);
+      inFlight = null;
+    }
+  })();
+  return inFlight;
+}
+
+/**
+ * Fetch on launch, on every return to the foreground, and on a timer.
+ * Returns a function that stops both.
+ */
+export function startConfigAutoRefresh(appState) {
+  void fetchConfig();
+  const subscription = appState?.addEventListener('change', state => {
+    if (state === 'active') void fetchConfig();
+  });
+  const interval = options?.pollIntervalMs ?? DEFAULT_POLL_MS;
+  if (interval > 0) {
+    stopPolling();
+    pollTimer = setInterval(() => void fetchConfig(), interval);
+  }
+  return () => {
+    subscription?.remove();
+    stopPolling();
+  };
+}
+function stopPolling() {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}
+
+// ─── Reads ────────────────────────────────────────────────────────────────────
+
+/** The served value, or the registered default. Never a type's zero value. */
+export function getConfigValue(key) {
+  if (Object.prototype.hasOwnProperty.call(values, key) && values[key] !== null) {
+    return values[key];
+  }
+  const fallback = defaults[key];
+  return fallback === undefined ? null : fallback;
+}
+export function getConfigBoolean(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'boolean') return value;
+  // A server that sends "true" as a string must not read as false.
+  if (typeof value === 'string') return value.toLowerCase() === 'true';
+  if (typeof value === 'number') return value !== 0;
+  return false;
+}
+export function getConfigNumber(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  return 0;
+}
+export function getConfigString(key) {
+  const value = getConfigValue(key);
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/** Defaults first, then everything the server sent — what a caller would see key by key. */
+export function getAllConfig() {
+  return {
+    ...defaults,
+    ...values
+  };
+}
+export function onConfigChange(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** For diagnostics: where the current values came from and how old they are. */
+export function getConfigInfo() {
+  return {
+    source,
+    fetchedAt,
+    etag,
+    keyCount: Object.keys(getAllConfig()).length
+  };
+}
+
+/** Test seam: drops every piece of module state. */
+export function resetConfigForTests() {
+  options = null;
+  defaults = {};
+  values = {};
+  etag = null;
+  fetchedAt = 0;
+  source = 'defaults';
+  inFlight = null;
+  listeners.clear();
+  stopPolling();
+}
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+function buildHeaders(opts, currentEtag) {
+  const ctx = opts.getContext?.() ?? {};
+  const headers = {
+    Accept: 'application/json'
+  };
+  if (ctx.platform) headers['X-Pulse-Platform'] = ctx.platform;
+  if (ctx.appVersion) headers['X-Pulse-App-Version'] = ctx.appVersion;
+  if (ctx.osVersion) headers['X-Pulse-Os-Version'] = ctx.osVersion;
+  if (ctx.language) headers['X-Pulse-Language'] = ctx.language;
+  if (ctx.deviceId) headers['Pulse-Device-Id'] = ctx.deviceId;
+  if (ctx.userAttributes && Object.keys(ctx.userAttributes).length > 0) {
+    headers['X-Pulse-User-Attributes'] = JSON.stringify(ctx.userAttributes);
+  }
+  // Country is deliberately absent: the server reads it from the edge, which a client
+  // header cannot spoof to opt into a targeted rollout.
+
+  if (currentEtag) headers['If-None-Match'] = currentEtag;
+  return headers;
+}
+function readCache(storage) {
+  if (!storage) return null;
+  try {
+    const raw = storage.getString(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.values) return null;
+    return parsed;
+  } catch {
+    // A corrupt cache is not worth a crash at boot: fall back to defaults.
+    return null;
+  }
+}
+function writeCache(storage, payload) {
+  if (!storage) return;
+  try {
+    storage.set(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Persistence is an optimisation; failing to write must not fail the fetch.
+  }
+}
+function notify() {
+  const snapshot = getAllConfig();
+  listeners.forEach(listener => {
+    try {
+      listener(snapshot);
+    } catch {
+      // One bad listener must not stop the others from being told.
+    }
+  });
+}
+//# sourceMappingURL=config.js.map

package/lib/module/config.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["STORAGE_KEY","DEFAULT_POLL_MS","DEFAULT_TIMEOUT_MS","options","defaults","values","etag","fetchedAt","source","inFlight","pollTimer","listeners","Set","configureConfig","opts","cached","readCache","storage","setConfigDefaults","more","fetchConfig","controller","AbortController","timer","setTimeout","abort","timeoutMs","response","fetch","url","method","headers","buildHeaders","signal","status","ok","Error","payload","json","nextValues","get","Date","now","writeCache","notify","error","onError","clearTimeout","startConfigAutoRefresh","appState","subscription","addEventListener","state","interval","pollIntervalMs","stopPolling","setInterval","remove","clearInterval","getConfigValue","key","Object","prototype","hasOwnProperty","call","fallback","undefined","getConfigBoolean","value","toLowerCase","getConfigNumber","parsed","Number","isNaN","getConfigString","String","getAllConfig","onConfigChange","listener","add","delete","getConfigInfo","keyCount","keys","length","resetConfigForTests","clear","currentEtag","ctx","getContext","Accept","platform","appVersion","osVersion","language","deviceId","userAttributes","JSON","stringify","raw","getString","parse","set","snapshot","forEach"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/index.js

@@ -2,4 +2,5 @@ export * from './PulseUpdates';
 export * from './types';
 export { usePulseUpdates } from './usePulseUpdates';
 export { initializeAssetResolver, updateLocalAssets } from './assetResolver';
+export * from './config';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["usePulseUpdates","initializeAssetResolver","updateLocalAssets"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA,cAAc,gBAAgB;AAC9B,cAAc,SAAS;AACvB,SAASA,eAAe,QAAQ,mBAAmB;AACnD,SAASC,uBAAuB,EAAEC,iBAAiB,QAAQ,iBAAiB","ignoreList":[]}
+{"version":3,"names":["usePulseUpdates","initializeAssetResolver","updateLocalAssets"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA,cAAc,gBAAgB;AAC9B,cAAc,SAAS;AACvB,SAASA,eAAe,QAAQ,mBAAmB;AACnD,SAASC,uBAAuB,EAAEC,iBAAiB,QAAQ,iBAAiB;AAC5E,cAAc,UAAU","ignoreList":[]}

package/lib/typescript/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pulse Config — the client half of the Firebase Remote Config replacement.
+ *
+ * Why this exists: from 2026-09-01 Firebase bills every Remote Config fetch above
+ * 100k/day and throttles projects that stay on the free plan. Worse than the bill is
+ * the failure mode — the Firebase SDK yields the type's zero value for a key it does
+ * not hold, so a throttled fetch reads as "every flag is false" and, for an ads
+ * config, quietly turns the revenue off.
+ *
+ * The shape here deliberately mirrors what the apps already do with Remote Config —
+ * defaults, fetch, activate, typed getters — so swapping the source is a change of
+ * adapter, not of every call site. Three things are different on purpose:
+ *
+ *  1. A missing key falls back to the registered default, never to false/0. That is
+ *     the exact bug this replaces.
+ *  2. The last good values are persisted and reloaded at boot, so a failed fetch
+ *     degrades to yesterday's config rather than to nothing.
+ *  3. Fetching is cheap (our server, no per-request price), so it happens on launch,
+ *     on every return from foreground, and on a timer — with ETag, so an unchanged
+ *     config costs a 304 with no body.
+ */
+export type ConfigValue = boolean | number | string | null | object;
+export interface ConfigStorage {
+    getString(key: string): string | null | undefined;
+    set(key: string, value: string): void;
+}
+/**
+ * Everything the server may ever want to target on. Sent on every request even when
+ * no rule uses it yet: the client can only start sending a new field with a store
+ * build, so a contract that is incomplete today cannot be completed for months.
+ */
+export interface ConfigContext {
+    platform?: string;
+    appVersion?: string;
+    osVersion?: string;
+    language?: string;
+    deviceId?: string;
+    /** Free-form user attributes a rule can compare (registration date, plan, counters). */
+    userAttributes?: Record<string, string>;
+}
+export interface ConfigOptions {
+    /** Full manifest-style URL, e.g. https://pulse.example.com/pulse/config/esound */
+    url: string;
+    /** Values used when the server has never been reached, or has no such key. */
+    defaults?: Record<string, ConfigValue>;
+    /** Persistence for the last good payload. Without it the cache is memory-only. */
+    storage?: ConfigStorage;
+    /** Read fresh on every request: the country or plan can change between launches. */
+    getContext?: () => ConfigContext;
+    /** Foreground poll interval. 0 disables polling (launch + resume still fetch). */
+    pollIntervalMs?: number;
+    /** Network timeout per request. */
+    timeoutMs?: number;
+    onError?: (error: unknown) => void;
+}
+/**
+ * Registers defaults and reloads the last good payload from storage, synchronously,
+ * so the very first read at boot already has real values instead of a blank config
+ * while the network call is in flight.
+ */
+export declare function configureConfig(opts: ConfigOptions): void;
+/** Merge more defaults after configure (a late-loading module registering its own). */
+export declare function setConfigDefaults(more: Record<string, ConfigValue>): void;
+/**
+ * Fetch, and adopt the payload if it changed. Returns true when new values were
+ * applied — false for "nothing changed" (304) and false for a failure, which are
+ * deliberately indistinguishable to callers: in both cases the current values stand.
+ * Errors surface through onError instead of rejecting, because no caller should have
+ * to wrap a config refresh in a try/catch to keep the app running.
+ */
+export declare function fetchConfig(): Promise<boolean>;
+/**
+ * Fetch on launch, on every return to the foreground, and on a timer.
+ * Returns a function that stops both.
+ */
+export declare function startConfigAutoRefresh(appState?: {
+    addEventListener: (type: 'change', handler: (state: string) => void) => {
+        remove: () => void;
+    };
+}): () => void;
+/** The served value, or the registered default. Never a type's zero value. */
+export declare function getConfigValue(key: string): ConfigValue;
+export declare function getConfigBoolean(key: string): boolean;
+export declare function getConfigNumber(key: string): number;
+export declare function getConfigString(key: string): string;
+/** Defaults first, then everything the server sent — what a caller would see key by key. */
+export declare function getAllConfig(): Record<string, ConfigValue>;
+export declare function onConfigChange(listener: (values: Record<string, ConfigValue>) => void): () => void;
+/** For diagnostics: where the current values came from and how old they are. */
+export declare function getConfigInfo(): {
+    source: 'defaults' | 'cache' | 'remote';
+    fetchedAt: number;
+    etag: string | null;
+    keyCount: number;
+};
+/** Test seam: drops every piece of module state. */
+export declare function resetConfigForTests(): void;
+//# sourceMappingURL=config.d.ts.map

package/lib/typescript/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,kFAAkF;IAClF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,aAAa,CAAC;IACjC,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAsBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAWzD;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAEzE;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CA6CpD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE;IAChD,gBAAgB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK;QAAE,MAAM,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CAChG,GAAG,MAAM,IAAI,CAiBb;AAWD,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAMvD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAE1D;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAGlG;AAED,gFAAgF;AAChF,wBAAgB,aAAa,IAAI;IAC/B,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAEA;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,IAAI,IAAI,CAU1C"}

package/lib/typescript/index.d.ts

@@ -2,4 +2,5 @@ export * from './PulseUpdates';
 export * from './types';
 export { usePulseUpdates } from './usePulseUpdates';
 export { initializeAssetResolver, updateLocalAssets } from './assetResolver';
+export * from './config';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,cAAc,UAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-updates",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "OTA updates for React Native - lightweight alternative to expo-updates",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/scripts/publish.mjs

@@ -777,8 +777,9 @@ async function publish(options) {
   }
   logSuccess(`Created release: ${release.id}`);
 
-  // Crash-prediction preflight: warn (and abort unless --force) if this release references native
-  // modules that weren't in the previous good release for this runtime version.
+  // Crash-prediction preflight: REFUSE the publish (fail-closed) if this release references native
+  // modules that weren't in the previous good release for this runtime version — native code can't ship
+  // over the air, so it would crash the installed cohort. Override with --allow-native-change.
   let preflight = null;
   try {
     const pfRes = await fetch(`${config.apiUrl}/api/releases/${release.id}/preflight`, {
@@ -790,17 +791,24 @@ async function publish(options) {
   }
   if (preflight) {
     for (const w of preflight.warnings || []) log(`⚠  ${w}`);
-    // Only NEW NATIVE modules are risky for OTA (native code can't ship over the air); JS changes
-    // are always fine. Warn by default; only block when the publisher opts into --strict.
-    if (!preflight.ok) {
-      if (options.strict) {
+    // Only NEW NATIVE modules are risky for OTA (native code can't ship over the air); JS changes are
+    // always fine. FAIL-CLOSED by default: a new native module referenced by this JS bundle that isn't
+    // in the previous good build for this runtime-version would CRASH the whole installed cohort on load,
+    // so we refuse the publish. Override only with --allow-native-change (you certify the native module
+    // is already in the installed binary). `--no-native-check` skips the gate entirely.
+    if (!preflight.ok && !options['no-native-check']) {
+      const allow = options['allow-native-change'] || options.force;
+      if (!allow) {
         throw new Error(
-          'Aborting (--strict): this release references native modules new to it — they cannot ship ' +
-          'over the air. Ship them in a new native binary first.'
+          `Refusing to publish: this release references native module(s) NOT in the previous good build ` +
+          `for runtime-version ${config.runtimeVersion}/${config.platform}. Native code cannot ship over ` +
+          `the air — this OTA would crash the installed cohort on load. Ship a NEW native binary (and bump ` +
+          `the runtime-version) first. If you are certain the native module is already in the installed ` +
+          `binary, re-run with --allow-native-change.`
         );
       }
-      log('⚠  Continuing: native-module changes detected (above). Only matters if those native modules ' +
-        'are not already in the installed binary. Re-run with --strict to block on this.');
+      logWarning('--allow-native-change: publishing despite detected native-module changes. If those ' +
+        'native modules are NOT already in the installed binary, this OTA will crash the cohort.');
     }
   }
 
@@ -989,7 +997,11 @@ ${colors.cyan}Options:${colors.reset}
   --entry-file <file>     Entry file (default: index.ts)
   --skip-bundle           Skip bundle creation (use existing)
   --dry-run               Build + validate locally without creating a release on the server
-  --strict                Abort publish if new native modules are detected (default: warn only)
+  --allow-native-change   Publish even though new native modules were detected (you certify they're
+                          already in the installed binary). Default is FAIL-CLOSED: a new native module
+                          not in the shipped build is refused (it would crash the cohort over the air).
+  --no-native-check       Skip the native-mismatch gate entirely (not recommended)
+  --strict                (deprecated — blocking on native changes is now the default)
   --build <number>        Build number (shown in version, e.g., 1.0.0.42)
   --message <msg>         Release message/notes
   --key-id <id>           Key id for keygen (default: auto-generated)

package/src/config.ts

@@ -0,0 +1,313 @@
+/**
+ * Pulse Config — the client half of the Firebase Remote Config replacement.
+ *
+ * Why this exists: from 2026-09-01 Firebase bills every Remote Config fetch above
+ * 100k/day and throttles projects that stay on the free plan. Worse than the bill is
+ * the failure mode — the Firebase SDK yields the type's zero value for a key it does
+ * not hold, so a throttled fetch reads as "every flag is false" and, for an ads
+ * config, quietly turns the revenue off.
+ *
+ * The shape here deliberately mirrors what the apps already do with Remote Config —
+ * defaults, fetch, activate, typed getters — so swapping the source is a change of
+ * adapter, not of every call site. Three things are different on purpose:
+ *
+ *  1. A missing key falls back to the registered default, never to false/0. That is
+ *     the exact bug this replaces.
+ *  2. The last good values are persisted and reloaded at boot, so a failed fetch
+ *     degrades to yesterday's config rather than to nothing.
+ *  3. Fetching is cheap (our server, no per-request price), so it happens on launch,
+ *     on every return from foreground, and on a timer — with ETag, so an unchanged
+ *     config costs a 304 with no body.
+ */
+
+export type ConfigValue = boolean | number | string | null | object;
+
+export interface ConfigStorage {
+  getString(key: string): string | null | undefined;
+  set(key: string, value: string): void;
+}
+
+/**
+ * Everything the server may ever want to target on. Sent on every request even when
+ * no rule uses it yet: the client can only start sending a new field with a store
+ * build, so a contract that is incomplete today cannot be completed for months.
+ */
+export interface ConfigContext {
+  platform?: string;
+  appVersion?: string;
+  osVersion?: string;
+  language?: string;
+  deviceId?: string;
+  /** Free-form user attributes a rule can compare (registration date, plan, counters). */
+  userAttributes?: Record<string, string>;
+}
+
+export interface ConfigOptions {
+  /** Full manifest-style URL, e.g. https://pulse.example.com/pulse/config/esound */
+  url: string;
+  /** Values used when the server has never been reached, or has no such key. */
+  defaults?: Record<string, ConfigValue>;
+  /** Persistence for the last good payload. Without it the cache is memory-only. */
+  storage?: ConfigStorage;
+  /** Read fresh on every request: the country or plan can change between launches. */
+  getContext?: () => ConfigContext;
+  /** Foreground poll interval. 0 disables polling (launch + resume still fetch). */
+  pollIntervalMs?: number;
+  /** Network timeout per request. */
+  timeoutMs?: number;
+  onError?: (error: unknown) => void;
+}
+
+interface CachedPayload {
+  values: Record<string, ConfigValue>;
+  etag: string | null;
+  fetchedAt: number;
+}
+
+const STORAGE_KEY = 'pulse.config.v1';
+const DEFAULT_POLL_MS = 5 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+let options: ConfigOptions | null = null;
+let defaults: Record<string, ConfigValue> = {};
+let values: Record<string, ConfigValue> = {};
+let etag: string | null = null;
+let fetchedAt = 0;
+let source: 'defaults' | 'cache' | 'remote' = 'defaults';
+let inFlight: Promise<boolean> | null = null;
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+const listeners = new Set<(values: Record<string, ConfigValue>) => void>();
+
+/**
+ * Registers defaults and reloads the last good payload from storage, synchronously,
+ * so the very first read at boot already has real values instead of a blank config
+ * while the network call is in flight.
+ */
+export function configureConfig(opts: ConfigOptions): void {
+  options = opts;
+  defaults = { ...(opts.defaults ?? {}) };
+
+  const cached = readCache(opts.storage);
+  if (cached) {
+    values = cached.values;
+    etag = cached.etag;
+    fetchedAt = cached.fetchedAt;
+    source = 'cache';
+  }
+}
+
+/** Merge more defaults after configure (a late-loading module registering its own). */
+export function setConfigDefaults(more: Record<string, ConfigValue>): void {
+  defaults = { ...defaults, ...more };
+}
+
+/**
+ * Fetch, and adopt the payload if it changed. Returns true when new values were
+ * applied — false for "nothing changed" (304) and false for a failure, which are
+ * deliberately indistinguishable to callers: in both cases the current values stand.
+ * Errors surface through onError instead of rejecting, because no caller should have
+ * to wrap a config refresh in a try/catch to keep the app running.
+ */
+export async function fetchConfig(): Promise<boolean> {
+  if (!options) return false;
+  // Collapse concurrent calls (launch + resume can land together) onto one request.
+  if (inFlight) return inFlight;
+
+  inFlight = (async () => {
+    const opts = options!;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const timer = controller
+      ? setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+      : null;
+
+    try {
+      const response = await fetch(opts.url, {
+        method: 'GET',
+        headers: buildHeaders(opts, etag),
+        signal: controller?.signal,
+      });
+
+      if (response.status === 304) return false;
+      if (!response.ok) throw new Error(`Pulse config HTTP ${response.status}`);
+
+      const payload = await response.json();
+      const nextValues = (payload?.values ?? {}) as Record<string, ConfigValue>;
+
+      values = nextValues;
+      etag = response.headers?.get?.('etag') ?? null;
+      fetchedAt = Date.now();
+      source = 'remote';
+
+      writeCache(opts.storage, { values, etag, fetchedAt });
+      notify();
+      return true;
+    } catch (error) {
+      // A failed refresh must never clear what we have: the whole point of the cache
+      // is that an unreachable server degrades to the last good config.
+      opts.onError?.(error);
+      return false;
+    } finally {
+      if (timer) clearTimeout(timer);
+      inFlight = null;
+    }
+  })();
+
+  return inFlight;
+}
+
+/**
+ * Fetch on launch, on every return to the foreground, and on a timer.
+ * Returns a function that stops both.
+ */
+export function startConfigAutoRefresh(appState?: {
+  addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void };
+}): () => void {
+  void fetchConfig();
+
+  const subscription = appState?.addEventListener('change', (state) => {
+    if (state === 'active') void fetchConfig();
+  });
+
+  const interval = options?.pollIntervalMs ?? DEFAULT_POLL_MS;
+  if (interval > 0) {
+    stopPolling();
+    pollTimer = setInterval(() => void fetchConfig(), interval);
+  }
+
+  return () => {
+    subscription?.remove();
+    stopPolling();
+  };
+}
+
+function stopPolling(): void {
+  if (pollTimer) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}
+
+// ─── Reads ────────────────────────────────────────────────────────────────────
+
+/** The served value, or the registered default. Never a type's zero value. */
+export function getConfigValue(key: string): ConfigValue {
+  if (Object.prototype.hasOwnProperty.call(values, key) && values[key] !== null) {
+    return values[key] as ConfigValue;
+  }
+  const fallback = defaults[key];
+  return fallback === undefined ? null : fallback;
+}
+
+export function getConfigBoolean(key: string): boolean {
+  const value = getConfigValue(key);
+  if (typeof value === 'boolean') return value;
+  // A server that sends "true" as a string must not read as false.
+  if (typeof value === 'string') return value.toLowerCase() === 'true';
+  if (typeof value === 'number') return value !== 0;
+  return false;
+}
+
+export function getConfigNumber(key: string): number {
+  const value = getConfigValue(key);
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    if (!Number.isNaN(parsed)) return parsed;
+  }
+  return 0;
+}
+
+export function getConfigString(key: string): string {
+  const value = getConfigValue(key);
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/** Defaults first, then everything the server sent — what a caller would see key by key. */
+export function getAllConfig(): Record<string, ConfigValue> {
+  return { ...defaults, ...values };
+}
+
+export function onConfigChange(listener: (values: Record<string, ConfigValue>) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** For diagnostics: where the current values came from and how old they are. */
+export function getConfigInfo(): {
+  source: 'defaults' | 'cache' | 'remote';
+  fetchedAt: number;
+  etag: string | null;
+  keyCount: number;
+} {
+  return { source, fetchedAt, etag, keyCount: Object.keys(getAllConfig()).length };
+}
+
+/** Test seam: drops every piece of module state. */
+export function resetConfigForTests(): void {
+  options = null;
+  defaults = {};
+  values = {};
+  etag = null;
+  fetchedAt = 0;
+  source = 'defaults';
+  inFlight = null;
+  listeners.clear();
+  stopPolling();
+}
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+function buildHeaders(opts: ConfigOptions, currentEtag: string | null): Record<string, string> {
+  const ctx = opts.getContext?.() ?? {};
+  const headers: Record<string, string> = { Accept: 'application/json' };
+
+  if (ctx.platform) headers['X-Pulse-Platform'] = ctx.platform;
+  if (ctx.appVersion) headers['X-Pulse-App-Version'] = ctx.appVersion;
+  if (ctx.osVersion) headers['X-Pulse-Os-Version'] = ctx.osVersion;
+  if (ctx.language) headers['X-Pulse-Language'] = ctx.language;
+  if (ctx.deviceId) headers['Pulse-Device-Id'] = ctx.deviceId;
+  if (ctx.userAttributes && Object.keys(ctx.userAttributes).length > 0) {
+    headers['X-Pulse-User-Attributes'] = JSON.stringify(ctx.userAttributes);
+  }
+  // Country is deliberately absent: the server reads it from the edge, which a client
+  // header cannot spoof to opt into a targeted rollout.
+
+  if (currentEtag) headers['If-None-Match'] = currentEtag;
+  return headers;
+}
+
+function readCache(storage?: ConfigStorage): CachedPayload | null {
+  if (!storage) return null;
+  try {
+    const raw = storage.getString(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as CachedPayload;
+    if (!parsed || typeof parsed !== 'object' || !parsed.values) return null;
+    return parsed;
+  } catch {
+    // A corrupt cache is not worth a crash at boot: fall back to defaults.
+    return null;
+  }
+}
+
+function writeCache(storage: ConfigStorage | undefined, payload: CachedPayload): void {
+  if (!storage) return;
+  try {
+    storage.set(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Persistence is an optimisation; failing to write must not fail the fetch.
+  }
+}
+
+function notify(): void {
+  const snapshot = getAllConfig();
+  listeners.forEach((listener) => {
+    try {
+      listener(snapshot);
+    } catch {
+      // One bad listener must not stop the others from being told.
+    }
+  });
+}

package/src/index.ts

@@ -2,3 +2,4 @@ export * from './PulseUpdates';
 export * from './types';
 export { usePulseUpdates } from './usePulseUpdates';
 export { initializeAssetResolver, updateLocalAssets } from './assetResolver';
+export * from './config';