pulse-updates 1.2.3 → 1.2.5

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,29 @@ 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;
+  outcomeDeliveryInfo(): OutcomeDeliveryInfo;
+  dispose(): Promise<void>;
 }
 
+export interface OutcomeDeliveryInfo {
+  queueDepth: number;
+  sending: boolean;
+  nextAttemptAt: number;
+}
+
+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 +95,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 +219,50 @@ 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,
+    outcomeDeliveryInfo: () => ({
+      queueDepth: outcomeQueue.length,
+      sending: outcomeSending,
+      nextAttemptAt: outcomeNextAttemptAt,
+    }),
+    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 +306,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));