pulse-updates 1.2.2 → 1.2.4

package/src/config.ts

@@ -113,6 +113,8 @@ export interface ConfigOptions {
    * the mistake that announces itself.
    */
   reportExposure?: boolean;
+  /** Durable exposure outbox key. initPulse supplies an app-scoped value. */
+  exposureStorageKey?: string;
   /** Network timeout per request. */
   timeoutMs?: number;
   /** Ed25519 public key, as raw 32-byte base64. Enables built-in verification. */
@@ -150,9 +152,21 @@ interface ConfigSnapshot {
   experiments: ConfigExperiment[];
 }
 
+interface QueuedExposure {
+  reportId: string;
+  signature: string;
+  platform?: string;
+  appVersion?: string;
+  assignments: Record<string, string>;
+  attempts: number;
+}
+
 const STORAGE_KEY = 'pulse.config.v1';
 const DEFAULT_POLL_MS = 5 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_EXPOSURE_RETRY_MS = 10_000;
+const DEFAULT_EXPOSURE_STORAGE_KEY = 'pulse.exposures.v1';
+const MAX_EXPOSURE_QUEUE = 50;
 
 let options: ConfigOptions | null = null;
 let defaults: Record<string, ConfigValue> = {};
@@ -177,6 +191,11 @@ let signatureKeyId: string | null = null;
 let pending: ConfigSnapshot | null = null;
 /** The arm set already reported this session, so a poll does not re-report it. */
 let reportedExposure: string | null = null;
+let exposureQueue: QueuedExposure[] = [];
+let deliveredExposureSignatures = new Set<string>();
+let exposureSending = false;
+let exposureNextAttemptAt = 0;
+let exposureTimer: ReturnType<typeof setInterval> | null = null;
 let inFlight: Promise<boolean> | null = null;
 let pollTimer: ReturnType<typeof setInterval> | null = null;
 let configGeneration = 0;
@@ -193,6 +212,7 @@ export function configureConfig(opts: ConfigOptions): void {
   // may cross that boundary.
   configGeneration += 1;
   stopPolling();
+  stopExposureDelivery();
   options = opts;
   defaults = { ...(opts.defaults ?? {}) };
   values = {};
@@ -205,6 +225,10 @@ export function configureConfig(opts: ConfigOptions): void {
   signatureKeyId = null;
   pending = null;
   reportedExposure = null;
+  exposureQueue = readExposureQueue(opts);
+  deliveredExposureSignatures = readDeliveredExposureSignatures(opts);
+  exposureSending = false;
+  exposureNextAttemptAt = 0;
   inFlight = null;
 
   applyCachedPayload(readCache(opts.storage, opts.storageKey), opts);
@@ -322,6 +346,8 @@ export function startConfigAutoRefresh(appState?: {
   addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void };
 }): () => void {
   void fetchConfig();
+  startExposureDelivery();
+  void flushExposures();
 
   const subscription = appState?.addEventListener('change', (state) => {
     if (state === 'active') void fetchConfig();
@@ -339,6 +365,7 @@ export function startConfigAutoRefresh(appState?: {
   return () => {
     subscription?.remove();
     stopPolling();
+    stopExposureDelivery();
   };
 }
 
@@ -360,7 +387,7 @@ function applySnapshot(next: ConfigSnapshot, opts: ConfigOptions): boolean {
   // Reported on apply, never on fetch: with activateOnFetch false a payload can sit
   // unapplied for the rest of a session, and an arm the app is not actually serving
   // is not an exposure.
-  void reportExposure(opts);
+  queueExposure(opts);
 
   // 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
@@ -386,34 +413,100 @@ function applySnapshot(next: ConfigSnapshot, opts: ConfigOptions): boolean {
  * Failure is swallowed on purpose. This is a diagnostic, and no diagnostic is worth
  * a rejected promise on the path that delivers config to the app.
  */
-async function reportExposure(opts: ConfigOptions): Promise<void> {
+function queueExposure(opts: ConfigOptions): void {
   if (opts.reportExposure !== true) return;
   if (experiments.length === 0) return;
 
   const signature = experiments.map((e) => `${e.key}=${e.variant}`).join(',');
-  if (signature === reportedExposure) return;
-  reportedExposure = signature;
+  if (signature === reportedExposure || deliveredExposureSignatures.has(signature) ||
+      exposureQueue.some((item) => item.signature === signature)) return;
 
   const context = opts.getContext?.() ?? {};
   const assignments: Record<string, string> = {};
   for (const entry of experiments) assignments[entry.key] = entry.variant;
 
+  exposureQueue.push({
+    reportId: randomDeliveryId('exp'),
+    signature,
+    platform: context.platform,
+    appVersion: context.appVersion,
+    assignments,
+    attempts: 0,
+  });
+  if (exposureQueue.length > MAX_EXPOSURE_QUEUE) {
+    exposureQueue = exposureQueue.slice(-MAX_EXPOSURE_QUEUE);
+  }
+  persistExposureQueue(opts, exposureQueue);
+  void flushExposures();
+}
+
+/** Flushes the durable exposure outbox. Safe to call on launch, resume or manually. */
+export async function flushExposures(): Promise<number> {
+  if (!options || exposureSending || exposureQueue.length === 0 || Date.now() < exposureNextAttemptAt) return 0;
+
+  const opts = options;
+  const requestGeneration = configGeneration;
+  const item = exposureQueue[0]!;
+  exposureSending = true;
+
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timeout = controller
+    ? setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+    : null;
+
   try {
-    await fetch(`${opts.url.replace(/\/+$/, '')}/exposure`, {
+    const response = await fetch(`${opts.url.replace(/\/+$/, '')}/exposure`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        platform: context.platform,
-        appVersion: context.appVersion,
-        assignments,
+        reportId: item.reportId,
+        platform: item.platform,
+        appVersion: item.appVersion,
+        assignments: item.assignments,
       }),
+      signal: controller?.signal,
     });
-  } catch {
-    // A device that cannot report its arm still has the right arm.
-    if (options === opts) reportedExposure = signature;
+    if (!response.ok) throw new Error(`Pulse exposure HTTP ${response.status}`);
+
+    if (requestGeneration === configGeneration && options === opts) {
+      exposureQueue = exposureQueue.filter((queued) => queued.reportId !== item.reportId);
+      reportedExposure = item.signature;
+      deliveredExposureSignatures.add(item.signature);
+      persistDeliveredExposureSignatures(opts);
+      exposureNextAttemptAt = 0;
+      persistExposureQueue(opts, exposureQueue);
+      if (exposureQueue.length > 0) void flushExposures();
+    } else {
+      removeExposureFromStoredQueue(opts, item.reportId);
+      markStoredExposureDelivered(opts, item.signature);
+    }
+    return 1;
+  } catch (error) {
+    if (requestGeneration === configGeneration && options === opts) {
+      exposureQueue = exposureQueue.map((queued) => queued.reportId === item.reportId
+        ? { ...queued, attempts: queued.attempts + 1 }
+        : queued);
+      const attempts = Math.min(item.attempts + 1, 6);
+      const base = Math.min(60_000, 1_000 * 2 ** Math.max(0, attempts - 1));
+      exposureNextAttemptAt = Date.now() + base;
+      persistExposureQueue(opts, exposureQueue);
+    }
+    opts.onError?.(error);
+    return 0;
+  } finally {
+    if (timeout) clearTimeout(timeout);
+    if (requestGeneration === configGeneration) exposureSending = false;
   }
 }
 
+export function pendingExposureCount(): number {
+  return exposureQueue.length;
+}
+
+export function getExposureDeliveryInfo(): { queueDepth: number; sending: boolean; nextAttemptAt: number } {
+  return { queueDepth: exposureQueue.length, sending: exposureSending, nextAttemptAt: exposureNextAttemptAt };
+}
+
 /**
  * Verifies the exact unsigned JSON object the server signs. A configured verifier
  * also rejects a bad optional signature: accepting a payload that claims to be
@@ -587,6 +680,102 @@ function stopPolling(): void {
   }
 }
 
+function startExposureDelivery(): void {
+  stopExposureDelivery();
+  if (options?.reportExposure !== true) return;
+  exposureTimer = setInterval(() => void flushExposures(), DEFAULT_EXPOSURE_RETRY_MS);
+  (exposureTimer as unknown as { unref?: () => void }).unref?.();
+}
+
+function stopExposureDelivery(): void {
+  if (exposureTimer) clearInterval(exposureTimer);
+  exposureTimer = null;
+}
+
+function exposureStorageKey(opts: ConfigOptions): string {
+  if (opts.exposureStorageKey?.trim()) return opts.exposureStorageKey.trim();
+  if (opts.storageKey?.trim()) return `${opts.storageKey.trim()}.exposures`;
+  return DEFAULT_EXPOSURE_STORAGE_KEY;
+}
+
+function deliveredExposureStorageKey(opts: ConfigOptions): string {
+  return `${exposureStorageKey(opts)}.delivered`;
+}
+
+function readExposureQueue(opts: ConfigOptions): QueuedExposure[] {
+  if (!opts.storage) return [];
+  try {
+    const raw = opts.storage.getString(exposureStorageKey(opts));
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((item): item is QueuedExposure => Boolean(
+      item && typeof item === 'object' &&
+      typeof (item as QueuedExposure).reportId === 'string' &&
+      typeof (item as QueuedExposure).signature === 'string' &&
+      typeof (item as QueuedExposure).assignments === 'object' &&
+      typeof (item as QueuedExposure).attempts === 'number',
+    )).slice(-MAX_EXPOSURE_QUEUE);
+  } catch {
+    return [];
+  }
+}
+
+function persistExposureQueue(opts: ConfigOptions, queued: QueuedExposure[]): void {
+  if (!opts.storage) return;
+  try {
+    opts.storage.set(exposureStorageKey(opts), JSON.stringify(queued));
+  } catch {
+    // Exposure delivery is diagnostic and may never make config adoption fail.
+  }
+}
+
+function readDeliveredExposureSignatures(opts: ConfigOptions): Set<string> {
+  if (!opts.storage) return new Set();
+  try {
+    const raw = opts.storage.getString(deliveredExposureStorageKey(opts));
+    if (!raw) return new Set();
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((value): value is string => typeof value === 'string').slice(-100));
+  } catch {
+    return new Set();
+  }
+}
+
+function persistDeliveredExposureSignatures(opts: ConfigOptions): void {
+  if (!opts.storage) return;
+  try {
+    const values = [...deliveredExposureSignatures].slice(-100);
+    opts.storage.set(deliveredExposureStorageKey(opts), JSON.stringify(values));
+  } catch {
+    // The server-side reportId still protects retries in this process.
+  }
+}
+
+function markStoredExposureDelivered(opts: ConfigOptions, signature: string): void {
+  if (!opts.storage) return;
+  try {
+    const stored = readDeliveredExposureSignatures(opts);
+    stored.add(signature);
+    opts.storage.set(deliveredExposureStorageKey(opts), JSON.stringify([...stored].slice(-100)));
+  } catch {
+    // A later server retry remains idempotent through its reportId.
+  }
+}
+
+function removeExposureFromStoredQueue(opts: ConfigOptions, reportId: string): void {
+  if (!opts.storage) return;
+  const queued = readExposureQueue(opts).filter((item) => item.reportId !== reportId);
+  persistExposureQueue(opts, queued);
+}
+
+function randomDeliveryId(prefix: string): string {
+  const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return `${prefix}-${cryptoLike.randomUUID()}`;
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
+}
+
 // ─── Reads ────────────────────────────────────────────────────────────────────
 
 /** The served value, or the registered default. Never a type's zero value. */
@@ -714,8 +903,13 @@ export function resetConfigForTests(): void {
   inFlight = null;
   pending = null;
   reportedExposure = null;
+  exposureQueue = [];
+  deliveredExposureSignatures = new Set();
+  exposureSending = false;
+  exposureNextAttemptAt = 0;
   listeners.clear();
   stopPolling();
+  stopExposureDelivery();
 }
 
 // ─── Internals ────────────────────────────────────────────────────────────────

package/src/decisions.ts

@@ -45,6 +45,14 @@ export interface PulseDecisionClientOptions {
   /** Safe default. User-facing execution needs an explicit per-app opt-in. */
   executionMode?: 'shadow-only' | 'allow-live';
   handlers?: Record<string, DecisionHandler>;
+  /** Persists terminal outcomes across process death and offline periods. */
+  storage?: ConfigStorage;
+  /** App-scoped outcome outbox key. Defaults to one derived from appSlug. */
+  storageKey?: string;
+  /** Retry tick for pending outcomes. Default 10s. */
+  flushIntervalMs?: number;
+  /** Bound on decisions awaiting delivery. Default 100. */
+  maxQueue?: number;
   onError?: (error: unknown) => void;
 }
 
@@ -57,8 +65,22 @@ export interface DecideOptions {
 export interface PulseDecisionClient {
   decide(trigger: string, options?: DecideOptions): Promise<PulseDecision | null>;
   reportOutcome(decisionId: string, outcome: DecisionOutcome, metadata?: Record<string, unknown>): Promise<boolean>;
+  flushOutcomes(): Promise<number>;
+  pendingOutcomeCount(): number;
+  dispose(): Promise<void>;
 }
 
+interface QueuedOutcome {
+  decisionId: string;
+  outcome: DecisionOutcome;
+  metadata?: Record<string, unknown>;
+  revision: string;
+  attempts: number;
+}
+
+const DEFAULT_OUTCOME_FLUSH_MS = 10_000;
+const DEFAULT_OUTCOME_MAX_QUEUE = 100;
+
 /** Generic decision protocol. Product-specific action handlers remain in each app. */
 export function createPulseDecisionClient(options: PulseDecisionClientOptions): PulseDecisionClient {
   const fetcher = options.fetch ?? globalThis.fetch;
@@ -66,26 +88,83 @@ export function createPulseDecisionClient(options: PulseDecisionClientOptions):
   const slug = encodeURIComponent(options.appSlug);
   const timeoutMs = Math.max(250, options.timeoutMs ?? 3_000);
   const executionMode = options.executionMode ?? 'shadow-only';
+  const storageKey = options.storageKey?.trim() || `pulse.${options.appSlug.trim()}.outcomes.v1`;
+  const maxQueue = Math.max(1, options.maxQueue ?? DEFAULT_OUTCOME_MAX_QUEUE);
+  let outcomeQueue = readOutcomeQueue(options.storage, storageKey, maxQueue);
+  let outcomeSending = false;
+  let outcomeNextAttemptAt = 0;
+  let disposed = false;
 
-  const reportOutcome = async (
-    decisionId: string,
-    outcome: DecisionOutcome,
-    metadata?: Record<string, unknown>,
-  ): Promise<boolean> => {
+  const persistOutcomes = (): void => {
+    if (!options.storage) return;
+    try { options.storage.set(storageKey, JSON.stringify(outcomeQueue)); }
+    catch {
+      // A storage failure may reduce durability, but decision execution itself must
+      // remain available and the caller still receives the delivery result.
+    }
+  };
+
+  const flushOutcomes = async (): Promise<number> => {
+    if (disposed || outcomeSending || outcomeQueue.length === 0 || Date.now() < outcomeNextAttemptAt) return 0;
+    outcomeSending = true;
+    const queued = outcomeQueue[0]!;
     try {
       const response = await timedFetch(fetcher,
-        `${base}/pulse/decisions/${slug}/${encodeURIComponent(decisionId)}/outcome`, {
+        `${base}/pulse/decisions/${slug}/${encodeURIComponent(queued.decisionId)}/outcome`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ outcome, ...(metadata ? { metadata } : {}) }),
+          body: JSON.stringify({
+            outcome: queued.outcome,
+            ...(queued.metadata ? { metadata: queued.metadata } : {}),
+          }),
         }, timeoutMs);
-      return response.ok;
+      if (!response.ok) throw new Error(`Pulse outcome HTTP ${response.status}`);
+
+      // A newer terminal state may have replaced this one while the request was in
+      // flight (accepted -> converted). Remove only the exact revision delivered.
+      outcomeQueue = outcomeQueue.filter((item) =>
+        item.decisionId !== queued.decisionId || item.revision !== queued.revision);
+      outcomeNextAttemptAt = 0;
+      persistOutcomes();
+      return 1;
     } catch (error) {
+      const current = outcomeQueue.find((item) => item.decisionId === queued.decisionId);
+      if (current?.revision === queued.revision) current.attempts += 1;
+      const attempts = Math.min((current?.attempts ?? queued.attempts + 1), 6);
+      const baseDelay = Math.min(60_000, 1_000 * 2 ** Math.max(0, attempts - 1));
+      outcomeNextAttemptAt = Date.now() + baseDelay;
+      persistOutcomes();
       options.onError?.(error);
-      return false;
+      return 0;
+    } finally {
+      outcomeSending = false;
+      if (!disposed && outcomeNextAttemptAt === 0 && outcomeQueue.length > 0) void flushOutcomes();
     }
   };
 
+  const reportOutcome = async (
+    decisionId: string,
+    outcome: DecisionOutcome,
+    metadata?: Record<string, unknown>,
+  ): Promise<boolean> => {
+    if (!decisionId.trim() || disposed) return false;
+    const next: QueuedOutcome = {
+      decisionId,
+      outcome,
+      metadata,
+      revision: randomKey(),
+      attempts: 0,
+    };
+    const existing = outcomeQueue.findIndex((item) => item.decisionId === decisionId);
+    if (existing >= 0) outcomeQueue[existing] = next;
+    else outcomeQueue.push(next);
+    outcomeQueue = outcomeQueue.slice(-maxQueue);
+    outcomeNextAttemptAt = 0;
+    persistOutcomes();
+    await flushOutcomes();
+    return !outcomeQueue.some((item) => item.decisionId === decisionId && item.revision === next.revision);
+  };
+
   const decide = async (trigger: string, request: DecideOptions = {}): Promise<PulseDecision | null> => {
     try {
       const context = await options.getContext();
@@ -133,7 +212,45 @@ export function createPulseDecisionClient(options: PulseDecisionClientOptions):
     }
   };
 
-  return { decide, reportOutcome };
+  const timer = setInterval(() => void flushOutcomes(), options.flushIntervalMs ?? DEFAULT_OUTCOME_FLUSH_MS);
+  (timer as unknown as { unref?: () => void }).unref?.();
+  void flushOutcomes();
+
+  return {
+    decide,
+    reportOutcome,
+    flushOutcomes,
+    pendingOutcomeCount: () => outcomeQueue.length,
+    dispose: async () => {
+      clearInterval(timer);
+      await flushOutcomes();
+      disposed = true;
+      persistOutcomes();
+    },
+  };
+}
+
+function readOutcomeQueue(
+  storage: ConfigStorage | undefined,
+  key: string,
+  maxQueue: number,
+): QueuedOutcome[] {
+  if (!storage) return [];
+  try {
+    const raw = storage.getString(key);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((item): item is QueuedOutcome => Boolean(
+      item && typeof item === 'object' &&
+      typeof (item as QueuedOutcome).decisionId === 'string' &&
+      typeof (item as QueuedOutcome).outcome === 'string' &&
+      typeof (item as QueuedOutcome).revision === 'string' &&
+      typeof (item as QueuedOutcome).attempts === 'number',
+    )).slice(-maxQueue);
+  } catch {
+    return [];
+  }
 }
 
 function parseDecision(raw: unknown): PulseDecision {
@@ -177,3 +294,4 @@ function randomKey(): string {
   if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
   return `moment-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
 }
+import type { ConfigStorage } from './config';

package/src/init.ts

@@ -36,6 +36,7 @@ import {
   getConfigNumber,
   getConfigString,
   getConfigJson,
+  getExposureDeliveryInfo,
 } from './config';
 import {
   configureTracking,
@@ -100,6 +101,9 @@ export interface InitPulseOptions {
   /** Foreground poll interval for the config. 0 disables it; launch and resume still fetch. */
   pollIntervalMs?: number;
 
+  /** Report experiment assignments through the durable outbox. Defaults to true. */
+  reportExposure?: boolean;
+
   /** How often queued events are sent. Default 10s. */
   flushIntervalMs?: number;
 
@@ -119,6 +123,7 @@ export interface PulseHealth {
   deviceId: string;
   config: ReturnType<typeof getConfigInfo>;
   events: ReturnType<typeof getTrackingInfo>;
+  exposures: ReturnType<typeof getExposureDeliveryInfo>;
   analyticsConsent: boolean;
 }
 
@@ -196,6 +201,8 @@ export function initPulse(opts: InitPulseOptions): PulseClient {
     defaults: opts.defaults,
     storage: opts.storage,
     storageKey: `pulse.${slug}.config.v1`,
+    exposureStorageKey: `pulse.${slug}.exposures.v1`,
+    reportExposure: opts.reportExposure ?? true,
     getContext,
     pollIntervalMs: opts.pollIntervalMs,
     onError: opts.onError,
@@ -260,7 +267,14 @@ export function initPulse(opts: InitPulseOptions): PulseClient {
       try { opts.storage?.set(deviceStorageKey, deviceId); } catch { /* memory-only fallback */ }
       return deviceId;
     },
-    health: () => ({ appSlug: slug, deviceId, config: getConfigInfo(), events: getTrackingInfo(), analyticsConsent: hasConsent() }),
+    health: () => ({
+      appSlug: slug,
+      deviceId,
+      config: getConfigInfo(),
+      events: getTrackingInfo(),
+      exposures: getExposureDeliveryInfo(),
+      analyticsConsent: hasConsent(),
+    }),
     config: {
       boolean: getConfigBoolean,
       number: getConfigNumber,
@@ -297,6 +311,7 @@ export async function initPulseAsync(
     `pulse.${slug}.device-id`,
     `pulse.${slug}.config.v1`,
     `pulse.${slug}.events.v1`,
+    `pulse.${slug}.exposures.v1`,
     DEVICE_ID_KEY,
   ];
   const loaded = await Promise.all(keys.map(async (key) => [key, await opts.storage.getItem(key)] as const));