pulse-updates 1.3.1 → 1.3.2

package/src/links.ts

@@ -190,6 +190,7 @@ export interface DeferredLinkClient {
 const OPAQUE_TOKEN = /^[A-Za-z0-9_-]{16,512}$/;
 const PUBLIC_EXPOSURE = /^[a-f0-9]{32}$/i;
 const INSTALL_ATTEMPT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const APP_IDENTITY = /^[A-Za-z0-9.-]+$/;
 const LOCALE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 const DEFAULT_PREFIXES = ['encore_handoff:', 'pulse_handoff:'] as const;
@@ -244,7 +245,22 @@ const DEFAULT_TOKEN_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1_000;
 const DEFAULT_RECENT_INSTALL_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const MAX_APPLIED_IDS = 32;
 const MAX_NOTIFIED_OUTCOMES = MAX_APPLIED_IDS * 3;
-const MAX_PERSISTED_BYTES = 16_384;
+const MAX_RESOLVER_OUTCOMES = MAX_NOTIFIED_OUTCOMES;
+const MAX_PERSISTED_BYTES = 131_072;
+
+interface QueuedResolverOutcome {
+  /** Non-reversible local transition key; never sent over the network. */
+  transitionKey: string;
+  /** Kept only in app storage and the Encore request path. Never added to analytics/body. */
+  token: string;
+  name: DeferredLinkOutcomeName;
+  eventId: string;
+  occurredAt: string;
+  matchBasis: DeferredLinkMatchBasis;
+  confidence: number;
+  attempts: number;
+  nextRetryAt: number;
+}
 
 interface PersistedDeferredLinkState {
   version: 1;
@@ -254,6 +270,8 @@ interface PersistedDeferredLinkState {
   appliedIds: string[];
   /** Internal transition-once ledger of non-reversible bounded hashes. */
   notifiedOutcomes: string[];
+  /** Durable Encore delivery queue. Exposure tokens stay local and are used only in URL paths. */
+  outcomeQueue: QueuedResolverOutcome[];
   firstOpen: DeferredLinkFirstOpenState;
 }
 
@@ -269,6 +287,7 @@ const emptyState = (): PersistedDeferredLinkState => ({
   lastAppliedId: null,
   appliedIds: [],
   notifiedOutcomes: [],
+  outcomeQueue: [],
   firstOpen: {
     installAttemptId: null,
     completed: false,
@@ -395,6 +414,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   let processing: Promise<void> | null = null;
   let processRequested = false;
   let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let outcomeSending: Promise<number> | null = null;
   let accountRetryAt = 0;
   let accountAttempts = 0;
   let lastFirstOpenContext: AnonymousFirstOpenContext | null = null;
@@ -475,44 +495,164 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     patchState({ pending: null, status: 'terminal_error' });
   };
 
+  const persistOutcomeState = (): void => {
+    writeState(options.storage, storageKey, state);
+    scheduleWake();
+  };
+
+  const flushResolverOutcomes = async (): Promise<number> => {
+    if (disposed) return 0;
+    if (outcomeSending) return outcomeSending;
+
+    const run = async (): Promise<number> => {
+      let delivered = 0;
+      while (!disposed) {
+        const queued = state.outcomeQueue[0];
+        if (!queued || queued.nextRetryAt > now()) break;
+
+        let response: Response;
+        try {
+          response = await postResolverOutcome(
+            fetcher,
+            resolverBaseUrl,
+            queued,
+            requestTimeoutMs,
+          );
+        } catch (error) {
+          if (disposed) break;
+          const index = state.outcomeQueue.findIndex((item) => item === queued);
+          if (index < 0) continue;
+          const current = state.outcomeQueue[index]!;
+          const attempts = Math.min(current.attempts + 1, 100_000);
+          const next = {
+            ...current,
+            attempts,
+            nextRetryAt: now() + resolverOutcomeRetryDelay(
+              current.eventId,
+              attempts,
+              retryBaseMs,
+              retryMaxMs,
+            ),
+          };
+          state = {
+            ...state,
+            outcomeQueue: state.outcomeQueue.map((item, itemIndex) => itemIndex === index ? next : item),
+          };
+          persistOutcomeState();
+          reportError(error);
+          break;
+        }
+
+        if (disposed) break;
+        const index = state.outcomeQueue.findIndex((item) => item === queued);
+        if (index < 0) continue;
+        const status = response.status;
+        if ((status >= 200 && status < 300) || status === 409 || status === 404 || status === 410) {
+          state = {
+            ...state,
+            outcomeQueue: state.outcomeQueue.filter((item) => item !== queued),
+          };
+          persistOutcomeState();
+          if ((status >= 200 && status < 300) || status === 409) delivered += 1;
+          continue;
+        }
+
+        if (status === 429 || status >= 500) {
+          const current = state.outcomeQueue[index]!;
+          const attempts = Math.min(current.attempts + 1, 100_000);
+          const next = {
+            ...current,
+            attempts,
+            nextRetryAt: now() + resolverOutcomeRetryDelay(
+              current.eventId,
+              attempts,
+              retryBaseMs,
+              retryMaxMs,
+            ),
+          };
+          state = {
+            ...state,
+            outcomeQueue: state.outcomeQueue.map((item, itemIndex) => itemIndex === index ? next : item),
+          };
+          persistOutcomeState();
+          reportError(new Error(`Pulse Links: Encore outcome HTTP ${status}`));
+          break;
+        }
+
+        // Other client/protocol errors cannot become valid by retrying the same payload.
+        state = {
+          ...state,
+          outcomeQueue: state.outcomeQueue.filter((item) => item !== queued),
+        };
+        persistOutcomeState();
+        reportError(new Error(`Pulse Links: terminal Encore outcome HTTP ${status}`));
+      }
+      return delivered;
+    };
+
+    let owned: Promise<number>;
+    owned = run().finally(() => {
+      if (outcomeSending === owned) outcomeSending = null;
+      const nextOutcome = state.outcomeQueue[0];
+      if (!disposed && nextOutcome && nextOutcome.nextRetryAt <= now()) {
+        void flushResolverOutcomes();
+      }
+    });
+    outcomeSending = owned;
+    return owned;
+  };
+
   const emitOutcome = (link: ResolvedDeferredLink<Action>, name: DeferredLinkOutcomeName): void => {
     const transitionKey = stableOutcomeKey(link.id, name);
-    if (!state.notifiedOutcomes.includes(transitionKey)) {
-      // Persist before handing off to the general Pulse outbox. A process death after the callback
-      // queues an event must not queue the same product transition again on restart.
-      state = {
-        ...state,
-        notifiedOutcomes: [...state.notifiedOutcomes, transitionKey].slice(-MAX_NOTIFIED_OUTCOMES),
-      };
-      writeState(options.storage, storageKey, state);
-      const event: DeferredLinkOutcomeEvent = {
-        name,
-        matchBasis: link.matchBasis,
-        confidence: link.confidence,
-        ...(link.campaignId !== undefined ? { campaignId: link.campaignId } : {}),
-        ...(link.experimentId !== undefined ? { experimentId: link.experimentId } : {}),
-        ...(link.variantId !== undefined ? { variantId: link.variantId } : {}),
-        occurredAt: new Date(now()).toISOString(),
-      };
-      try {
-        const result = options.onOutcome?.(event);
-        if (result && typeof (result as Promise<void>).catch === 'function') {
-          void (result as Promise<void>).catch(reportError);
-        }
-      } catch (error) {
-        reportError(error);
+    if (state.notifiedOutcomes.includes(transitionKey)) return;
+
+    const occurredAt = new Date(now()).toISOString();
+    const shouldReportToResolver = (options.reportResolverOutcomes ?? true) && isPublicToken(link.id);
+    const queued: QueuedResolverOutcome | null = shouldReportToResolver ? {
+      transitionKey,
+      token: link.id,
+      name,
+      eventId: makeOutcomeEventId(
+        options.randomUUID,
+        new Set(state.outcomeQueue.map((outcome) => outcome.eventId)),
+      ),
+      occurredAt,
+      matchBasis: link.matchBasis,
+      confidence: link.confidence,
+      attempts: 0,
+      nextRetryAt: 0,
+    } : null;
+
+    // Persist the logical transition and complete Encore payload before either delivery path.
+    // The token remains only in this local record and in Encore's URL path.
+    state = {
+      ...state,
+      notifiedOutcomes: [...state.notifiedOutcomes, transitionKey].slice(-MAX_NOTIFIED_OUTCOMES),
+      outcomeQueue: queued
+        ? [...state.outcomeQueue, queued].slice(-MAX_RESOLVER_OUTCOMES)
+        : state.outcomeQueue,
+    };
+    persistOutcomeState();
+
+    const event: DeferredLinkOutcomeEvent = {
+      name,
+      matchBasis: link.matchBasis,
+      confidence: link.confidence,
+      ...(link.campaignId !== undefined ? { campaignId: link.campaignId } : {}),
+      ...(link.experimentId !== undefined ? { experimentId: link.experimentId } : {}),
+      ...(link.variantId !== undefined ? { variantId: link.variantId } : {}),
+      occurredAt,
+    };
+    try {
+      const result = options.onOutcome?.(event);
+      if (result && typeof (result as Promise<void>).catch === 'function') {
+        void (result as Promise<void>).catch(reportError);
       }
+    } catch (error) {
+      reportError(error);
     }
 
-    if ((options.reportResolverOutcomes ?? true) && isPublicToken(link.id)) {
-      void postResolverOutcome(
-        fetcher,
-        resolverBaseUrl,
-        link,
-        name,
-        requestTimeoutMs,
-      ).catch(reportError);
-    }
+    if (queued) void flushResolverOutcomes();
   };
 
   const applyResolved = async (
@@ -911,12 +1051,14 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       state.pending?.nextRetryAt ?? 0,
       lastFirstOpenContext ? state.firstOpen.nextRetryAt : 0,
       accountRetryAt,
+      state.outcomeQueue[0]?.nextRetryAt ?? 0,
     ].filter((value) => value > now());
     if (candidates.length === 0) return;
     const next = Math.min(...candidates);
     retryTimer = setTimeout(() => {
       retryTimer = null;
       void process();
+      void flushResolverOutcomes();
       if (lastFirstOpenContext && state.firstOpen.nextRetryAt <= now()) {
         void matchFirstOpen(lastFirstOpenContext);
       }
@@ -934,6 +1076,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   }
   scheduleWake();
   void process();
+  void flushResolverOutcomes();
 
   return {
     capture,
@@ -1106,10 +1249,45 @@ function makeInstallAttemptId(custom?: () => string): string {
       ?? (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID?.();
     if (candidate && INSTALL_ATTEMPT_ID.test(candidate)) return candidate.toLowerCase();
   } catch { /* use the non-identity fallback below */ }
+  return fallbackUuidV4();
+}
+
+function makeOutcomeEventId(custom?: () => string, existing: ReadonlySet<string> = new Set()): string {
+  try {
+    const candidate = custom?.()
+      ?? (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID?.();
+    if (candidate && UUID_V4.test(candidate) && !existing.has(candidate.toLowerCase())) {
+      return candidate.toLowerCase();
+    }
+  } catch { /* use the UUIDv4 fallback below */ }
+  let fallback = fallbackUuidV4();
+  while (existing.has(fallback)) fallback = fallbackUuidV4();
+  return fallback;
+}
+
+function fallbackUuidV4(): string {
   const hex = (): string => Math.floor(Math.random() * 0x10000).toString(16).padStart(4, '0');
   return `${hex()}${hex()}-${hex()}-4${hex().slice(1)}-${(8 + Math.floor(Math.random() * 4)).toString(16)}${hex().slice(1)}-${hex()}${hex()}${hex()}`;
 }
 
+/** Deterministic equal jitter keeps a persisted retry stable while spreading different events. */
+function resolverOutcomeRetryDelay(
+  eventId: string,
+  attempts: number,
+  retryBaseMs: number,
+  retryMaxMs: number,
+): number {
+  const exponent = Math.min(Math.max(attempts - 1, 0), 10);
+  const ceiling = Math.min(retryMaxMs, retryBaseMs * 2 ** exponent);
+  let hash = 0x811c9dc5;
+  const seed = `${eventId}:${attempts}`;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash = Math.imul(hash ^ seed.charCodeAt(index), 0x01000193) >>> 0;
+  }
+  const jitter = 0.5 + (hash / 0xffffffff) * 0.5;
+  return Math.max(1, Math.floor(ceiling * jitter));
+}
+
 async function withTimeout(
   fetcher: typeof fetch,
   input: string,
@@ -1125,27 +1303,90 @@ async function withTimeout(
   }
 }
 
-async function postResolverOutcome<Action extends string>(
+async function postResolverOutcome(
   fetcher: typeof fetch,
   resolverBaseUrl: string,
-  link: ResolvedDeferredLink<Action>,
-  name: DeferredLinkOutcomeName,
+  outcome: QueuedResolverOutcome,
   timeoutMs: number,
-): Promise<void> {
-  await withTimeout(
+): Promise<Response> {
+  return withTimeout(
     fetcher,
-    `${resolverBaseUrl}${encodeURIComponent(link.id)}/event/${name}`,
+    `${resolverBaseUrl}${encodeURIComponent(outcome.token)}/event/${outcome.name}`,
     {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({ matchBasis: link.matchBasis, confidence: link.confidence }),
+      body: JSON.stringify({
+        eventId: outcome.eventId,
+        occurredAt: outcome.occurredAt,
+        matchBasis: outcome.matchBasis,
+        confidence: outcome.confidence,
+      }),
     },
     timeoutMs,
   );
 }
 
+function readResolverOutcomeQueue(raw: unknown): QueuedResolverOutcome[] {
+  if (!Array.isArray(raw)) return [];
+  const queue: QueuedResolverOutcome[] = [];
+  const seenTransitions = new Set<string>();
+  const seenEvents = new Set<string>();
+  const candidates = [...raw].reverse();
+  for (const candidate of candidates) {
+    if (queue.length >= MAX_RESOLVER_OUTCOMES) break;
+    if (!candidate || typeof candidate !== 'object') continue;
+    const value = candidate as Record<string, unknown>;
+    const token = normalizeDeferredHandoffToken(value.token as string | undefined);
+    const name = isDeferredLinkOutcomeName(value.name) ? value.name : null;
+    const eventId = typeof value.eventId === 'string' && UUID_V4.test(value.eventId)
+      ? value.eventId.toLowerCase()
+      : null;
+    const occurredAt = normalizeOccurredAt(value.occurredAt);
+    const matchBasis = typeof value.matchBasis === 'string'
+      && MATCH_BASES.has(value.matchBasis as DeferredLinkMatchBasis)
+      ? value.matchBasis as DeferredLinkMatchBasis
+      : null;
+    if (!token || !name || !eventId || !occurredAt || !matchBasis) continue;
+    const transitionKey = stableOutcomeKey(token, name);
+    if (value.transitionKey !== transitionKey
+      || seenTransitions.has(transitionKey)
+      || seenEvents.has(eventId)) continue;
+    const confidence = typeof value.confidence === 'number' && Number.isFinite(value.confidence)
+      ? clampConfidence(value.confidence, 0)
+      : null;
+    if (confidence === null) continue;
+    seenTransitions.add(transitionKey);
+    seenEvents.add(eventId);
+    queue.unshift({
+      transitionKey,
+      token,
+      name,
+      eventId,
+      occurredAt,
+      matchBasis,
+      confidence,
+      attempts: safeInteger(value.attempts, 100_000),
+      nextRetryAt: safeTimestamp(value.nextRetryAt),
+    });
+  }
+  return queue;
+}
+
+function isDeferredLinkOutcomeName(value: unknown): value is DeferredLinkOutcomeName {
+  return value === 'app_open_confirmed'
+    || value === 'deferred_link_resolved'
+    || value === 'action_applied';
+}
+
+function normalizeOccurredAt(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length > 40) return null;
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return null;
+  return new Date(timestamp).toISOString() === value ? value : null;
+}
+
 function readState(storage: ConfigStorage | undefined, key: string): PersistedDeferredLinkState {
   if (!storage) return emptyState();
   try {
@@ -1192,13 +1433,18 @@ function readState(storage: ConfigStorage | undefined, key: string): PersistedDe
           && /^[a-f0-9]{16}\|(app_open_confirmed|deferred_link_resolved|action_applied)$/.test(value))
         .slice(-MAX_NOTIFIED_OUTCOMES)
       : [];
+    const outcomeQueue = readResolverOutcomeQueue(parsed.outcomeQueue);
     return {
       version: 1,
       status: status === 'resolving' ? (pending ? 'pending' : 'idle') : status,
       pending,
       lastAppliedId: lastApplied,
       appliedIds: [...new Set(appliedIds)].slice(-MAX_APPLIED_IDS),
-      notifiedOutcomes: [...new Set(notifiedOutcomes)].slice(-MAX_NOTIFIED_OUTCOMES),
+      notifiedOutcomes: [...new Set([
+        ...notifiedOutcomes,
+        ...outcomeQueue.map((outcome) => outcome.transitionKey),
+      ])].slice(-MAX_NOTIFIED_OUTCOMES),
+      outcomeQueue,
       firstOpen: {
         installAttemptId: attemptId,
         completed: firstValue.completed === true,