pulse-updates 1.0.14 → 1.0.16

package/src/config.ts

@@ -0,0 +1,410 @@
+/**
+ * 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;
+  /**
+   * Skip a fetch that lands within this window of the last successful one. 0 (the
+   * default) means never skip: unlike Firebase there is no per-request price, so the
+   * throttle exists only for callers who want it.
+   */
+  minimumFetchIntervalMs?: number;
+  /**
+   * When false, a fetch stores the payload without applying it — call activateConfig()
+   * to swap it in. Mirrors Firebase's fetch/activate split, and matters here because
+   * the foreground poll would otherwise flip a flag under a user mid-session: an ad
+   * gate or a playback engine changing while a track plays is worse than being a few
+   * minutes stale. Default true, matching fetchAndActivate.
+   */
+  activateOnFetch?: boolean;
+  /** 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 pending: Record<string, ConfigValue> | null = null;
+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;
+
+  const minInterval = options.minimumFetchIntervalMs ?? 0;
+  if (minInterval > 0 && fetchedAt > 0 && Date.now() - fetchedAt < minInterval) {
+    return false;
+  }
+
+  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;
+      // A payload without a values object is a broken response, not "no keys": adopting
+      // it would blank every flag at once.
+      if (!nextValues || typeof nextValues !== 'object' || Array.isArray(nextValues)) {
+        throw new Error('Pulse config: malformed payload');
+      }
+
+      etag = response.headers?.get?.('etag') ?? null;
+      fetchedAt = Date.now();
+
+      if (opts.activateOnFetch === false) {
+        pending = nextValues as Record<string, ConfigValue>;
+        return false;
+      }
+
+      return applyValues(nextValues as Record<string, ConfigValue>, opts);
+    } 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;
+}
+
+/**
+ * Swap in the values from the last fetch made with activateOnFetch: false.
+ * Returns true when something actually changed.
+ */
+export function activateConfig(): boolean {
+  if (!pending || !options) return false;
+  const next = pending;
+  pending = null;
+  return applyValues(next, options);
+}
+
+/** Whether a fetched-but-not-yet-applied payload is waiting. */
+export function hasPendingConfig(): boolean {
+  return pending !== null;
+}
+
+/**
+ * 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 applyValues(next: Record<string, ConfigValue>, opts: ConfigOptions): boolean {
+  const changed = !shallowEqual(values, next);
+
+  values = next;
+  source = 'remote';
+  writeCache(opts.storage, { values, etag, fetchedAt });
+
+  // Listeners drive re-renders and gate re-evaluation: firing them for an identical
+  // payload is pure churn, and the 200-with-same-content case is common enough
+  // (a proxy that drops the ETag) to be worth checking.
+  if (changed) notify();
+  return changed;
+}
+
+function shallowEqual(a: Record<string, ConfigValue>, b: Record<string, ConfigValue>): boolean {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((k) => {
+    const av = a[k];
+    const bv = b[k];
+    if (av !== null && bv !== null && typeof av === 'object' && typeof bv === 'object') {
+      return JSON.stringify(av) === JSON.stringify(bv);
+    }
+    return av === bv;
+  });
+}
+
+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 };
+}
+
+/** Parsed object/array value, or the default. Null when neither is usable. */
+export function getConfigJson<T = unknown>(key: string): T | null {
+  const value = getConfigValue(key);
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'object') return value as T;
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** Where this key's value came from — the answer to "why is this flag off?". */
+export function getConfigSource(key: string): 'remote' | 'default' | 'missing' {
+  if (Object.prototype.hasOwnProperty.call(values, key) && values[key] !== null) return 'remote';
+  if (Object.prototype.hasOwnProperty.call(defaults, key)) return 'default';
+  return 'missing';
+}
+
+export function getConfigKeys(): string[] {
+  return Object.keys(getAllConfig()).sort();
+}
+
+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;
+  pending = 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';