pulse-updates 1.2.5 → 1.3.0

package/src/links.ts

@@ -0,0 +1,1232 @@
+/**
+ * Pulse Links - a headless, app-neutral deferred-link client.
+ *
+ * Encore owns the phase-one HTTP resolver and attribution ledger. Pulse owns the reusable
+ * client boundary: capture, durable pending state, retry/idempotence, safe application and the
+ * privacy-preserving first-open request. Billing/account SDKs integrate only through the narrow
+ * optional account bridge below.
+ */
+
+import type { ConfigStorage } from './config';
+
+export type DeferredLinkAction =
+  | 'open_home'
+  | 'open_premium'
+  | 'manage_subscription'
+  | 'refresh_entitlement';
+
+export type DeferredLinkMatchBasis =
+  | 'direct_token'
+  | 'android_install_referrer'
+  | 'ios_user_paste'
+  | 'account_bound'
+  | 'unique_probabilistic'
+  | 'unmatched';
+
+export type DeferredLinkCaptureBasis = Extract<
+  DeferredLinkMatchBasis,
+  'direct_token' | 'android_install_referrer' | 'ios_user_paste'
+>;
+
+export type DeferredLinkStatus =
+  | 'idle'
+  | 'pending'
+  | 'resolving'
+  | 'waiting_for_account'
+  | 'retryable_error'
+  | 'applied'
+  | 'terminal_error';
+
+export type DeferredLinkOutcomeName =
+  | 'app_open_confirmed'
+  | 'deferred_link_resolved'
+  | 'action_applied';
+
+export interface ResolvedDeferredLink<Action extends string = DeferredLinkAction> {
+  id: string;
+  action?: Action;
+  deepLink?: string;
+  expiresAt?: string;
+  source?: string | null;
+  campaignId?: string | null;
+  experimentId?: string | null;
+  variantId?: string | null;
+  matchBasis: DeferredLinkMatchBasis;
+  matchGuaranteed: boolean;
+  confidence: number;
+}
+
+export interface DeferredLinkPendingState {
+  /** Opaque bearer-by-entropy handoff. It is never logged or sent to Pulse event properties. */
+  token: string;
+  receivedAt: number;
+  matchBasis: DeferredLinkCaptureBasis;
+  attempts: number;
+  nextRetryAt: number;
+}
+
+export interface DeferredLinkFirstOpenState {
+  /** Random retry nonce scoped to one install attempt; it is not a device or account identity. */
+  installAttemptId: string | null;
+  completed: boolean;
+  attemptedAt: number;
+  attempts: number;
+  nextRetryAt: number;
+}
+
+export interface DeferredLinkState {
+  status: DeferredLinkStatus;
+  pending: DeferredLinkPendingState | null;
+  lastAppliedId: string | null;
+  /** Bounded persisted idempotence window. */
+  appliedIds: readonly string[];
+  firstOpen: DeferredLinkFirstOpenState;
+}
+
+export interface DeferredLinkAccountBridge<Action extends string = DeferredLinkAction> {
+  claim(token?: string): Promise<ResolvedDeferredLink<Action> | null>;
+  pending(): Promise<ResolvedDeferredLink<Action> | null>;
+}
+
+export interface DeferredLinkOutcomeEvent {
+  name: DeferredLinkOutcomeName;
+  matchBasis: DeferredLinkMatchBasis;
+  confidence: number;
+  campaignId?: string | null;
+  experimentId?: string | null;
+  variantId?: string | null;
+  occurredAt: string;
+}
+
+export interface AnonymousFirstOpenContext {
+  appBundleId: string;
+  locale: string;
+  platform: 'ios';
+  /** Native first-install timestamp. Matching is refused when recency cannot be proven. */
+  installedAt: number;
+}
+
+export type AnonymousFirstOpenResult =
+  | 'matched'
+  | 'no_match'
+  | 'ineligible'
+  | 'deterministic_pending'
+  | 'already_completed'
+  | 'backoff'
+  | 'retry_scheduled'
+  | 'terminal_error';
+
+export type AndroidInstallReferrerStatus =
+  | 'OK'
+  | 'NO_TOKEN'
+  | 'FEATURE_NOT_SUPPORTED'
+  | 'SERVICE_UNAVAILABLE'
+  | 'DEVELOPER_ERROR'
+  | 'SERVICE_DISCONNECTED';
+
+export interface AndroidInstallReferrerResult {
+  status: AndroidInstallReferrerStatus;
+  retryable: boolean;
+  attempts: number;
+  token?: string;
+}
+
+/** Implemented by the separate native `PulseAttribution` module. */
+export interface AndroidInstallReferrerBridge {
+  getDeferredHandoff(): Promise<unknown>;
+}
+
+export interface DeferredLinkClientOptions<Action extends string = DeferredLinkAction> {
+  /** Public Encore resolver prefix for phase one, e.g. https://encore.example/t/d/. */
+  resolverBaseUrl: string;
+  /** App-owned schemes/universal-link prefixes accepted from the resolver. */
+  allowedDeepLinkPrefixes: readonly string[];
+  /** Closed action vocabulary. Unknown server actions are ignored. */
+  allowedActions?: readonly Action[];
+  /** Actions that require both a deterministic match and a stable signed-in account. */
+  sensitiveActions?: readonly Action[];
+  onDeepLink: (deepLink: string, link: ResolvedDeferredLink<Action>) => boolean | void | Promise<boolean | void>;
+  onAction?: (link: ResolvedDeferredLink<Action>) => boolean | void | Promise<boolean | void>;
+  accountBridge?: DeferredLinkAccountBridge<Action>;
+  isAccountReady?: () => boolean;
+  /** Lets the client retry an account-bound handoff immediately after login/logout changes. */
+  subscribeAccountState?: (listener: () => void) => (() => void);
+  /** Same synchronous storage adapter used by initPulse/MMKV. */
+  storage?: ConfigStorage;
+  /** Used to derive `pulse.{appSlug}.links.v1`; required with storage unless storageKey is explicit. */
+  appSlug?: string;
+  /** Must be app-scoped when storage is shared by more than one app. */
+  storageKey?: string;
+  fetch?: typeof fetch;
+  requestTimeoutMs?: number;
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+  tokenMaxAgeMs?: number;
+  recentInstallMaxAgeMs?: number;
+  autoRetry?: boolean;
+  reportResolverOutcomes?: boolean;
+  onOutcome?: (event: DeferredLinkOutcomeEvent) => void | Promise<void>;
+  onStateChange?: (state: DeferredLinkState) => void;
+  onError?: (error: unknown) => void;
+  now?: () => number;
+  randomUUID?: () => string;
+  /** Phase-one public campaign exposures are 128-bit hex; account tokens use the wider grammar. */
+  isPublicToken?: (token: string) => boolean;
+}
+
+export interface DeferredLinkClient {
+  capture(token: string, basis: DeferredLinkCaptureBasis): boolean;
+  captureUrl(url: string): boolean;
+  process(): Promise<void>;
+  matchFirstOpen(context: AnonymousFirstOpenContext): Promise<AnonymousFirstOpenResult>;
+  captureAndroidInstallReferrer(bridge: AndroidInstallReferrerBridge): Promise<AndroidInstallReferrerResult>;
+  getState(): DeferredLinkState;
+  subscribe(listener: (state: DeferredLinkState) => void): () => void;
+  dispose(): void;
+  /** Clears only install-attribution state. It never touches Pulse config/events or account data. */
+  reset(): void;
+}
+
+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 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;
+const DEFAULT_QUERY_KEYS = new Set([
+  'encore_handoff',
+  'encore_deferred',
+  'pulse_handoff',
+  'pulse_deferred',
+]);
+const MATCH_BASES = new Set<DeferredLinkMatchBasis>([
+  'direct_token',
+  'android_install_referrer',
+  'ios_user_paste',
+  'account_bound',
+  'unique_probabilistic',
+  'unmatched',
+]);
+const CAPTURE_BASES = new Set<DeferredLinkCaptureBasis>([
+  'direct_token',
+  'android_install_referrer',
+  'ios_user_paste',
+]);
+const STATUSES = new Set<DeferredLinkStatus>([
+  'idle',
+  'pending',
+  'resolving',
+  'waiting_for_account',
+  'retryable_error',
+  'applied',
+  'terminal_error',
+]);
+const INSTALL_REFERRER_STATUSES = new Set<AndroidInstallReferrerStatus>([
+  'OK',
+  'NO_TOKEN',
+  'FEATURE_NOT_SUPPORTED',
+  'SERVICE_UNAVAILABLE',
+  'DEVELOPER_ERROR',
+  'SERVICE_DISCONNECTED',
+]);
+const DEFAULT_ACTIONS = [
+  'open_home',
+  'open_premium',
+  'manage_subscription',
+  'refresh_entitlement',
+] as const;
+const DEFAULT_SENSITIVE_ACTIONS = ['manage_subscription', 'refresh_entitlement'] as const;
+const DEFAULT_STORAGE_KEY = 'pulse.links.v1';
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_BASE_MS = 15_000;
+const DEFAULT_RETRY_MAX_MS = 6 * 60 * 60 * 1_000;
+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;
+
+interface PersistedDeferredLinkState {
+  version: 1;
+  status: DeferredLinkStatus;
+  pending: DeferredLinkPendingState | null;
+  lastAppliedId: string | null;
+  appliedIds: string[];
+  /** Internal transition-once ledger of non-reversible bounded hashes. */
+  notifiedOutcomes: string[];
+  firstOpen: DeferredLinkFirstOpenState;
+}
+
+type ResolveResult<Action extends string> =
+  | { kind: 'resolved'; link: ResolvedDeferredLink<Action> }
+  | { kind: 'not_found' }
+  | { kind: 'retryable' };
+
+const emptyState = (): PersistedDeferredLinkState => ({
+  version: 1,
+  status: 'idle',
+  pending: null,
+  lastAppliedId: null,
+  appliedIds: [],
+  notifiedOutcomes: [],
+  firstOpen: {
+    installAttemptId: null,
+    completed: false,
+    attemptedAt: 0,
+    attempts: 0,
+    nextRetryAt: 0,
+  },
+});
+
+export function isOpaqueDeferredLinkToken(value: unknown): value is string {
+  return typeof value === 'string' && OPAQUE_TOKEN.test(value);
+}
+
+export function normalizeDeferredHandoffToken(
+  raw: string | null | undefined,
+  acceptedPrefixes: readonly string[] = DEFAULT_PREFIXES,
+): string | null {
+  if (typeof raw !== 'string') return null;
+  let candidate = raw.trim();
+  const lower = candidate.toLowerCase();
+  const prefix = acceptedPrefixes.find((value) => {
+    const normalized = value.trim().toLowerCase();
+    return normalized.length > 1 && lower.startsWith(normalized);
+  });
+  if (prefix) candidate = candidate.slice(prefix.trim().length);
+  return isOpaqueDeferredLinkToken(candidate) ? candidate : null;
+}
+
+/** Extracts only explicit handoff query keys or /handoff|d/{token} path segments. */
+export function extractDeferredHandoffToken(url: string): string | null {
+  if (typeof url !== 'string' || url.length === 0 || url.length > 4_096) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (!parsed.protocol) return null;
+
+  const queryCandidates: string[] = [];
+  for (const [key, value] of parsed.searchParams.entries()) {
+    if (DEFAULT_QUERY_KEYS.has(key.toLowerCase())) queryCandidates.push(value);
+  }
+  if (queryCandidates.length > 1) return null;
+  if (queryCandidates.length === 1) return normalizeDeferredHandoffToken(queryCandidates[0]);
+
+  const segments = [parsed.hostname, ...parsed.pathname.split('/')].filter(Boolean);
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    const marker = segments[index]?.toLowerCase();
+    if (marker !== 'handoff' && marker !== 'd') continue;
+    try {
+      return normalizeDeferredHandoffToken(decodeURIComponent(segments[index + 1] ?? ''));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** Runtime-validates the native result so raw bridge data can never leak into app state. */
+export function normalizeAndroidInstallReferrerResult(raw: unknown): AndroidInstallReferrerResult {
+  if (!raw || typeof raw !== 'object') {
+    return { status: 'SERVICE_UNAVAILABLE', retryable: true, attempts: 0 };
+  }
+  const value = raw as Record<string, unknown>;
+  const status = typeof value.status === 'string'
+    && INSTALL_REFERRER_STATUSES.has(value.status as AndroidInstallReferrerStatus)
+    ? value.status as AndroidInstallReferrerStatus
+    : 'DEVELOPER_ERROR';
+  const attempts = typeof value.attempts === 'number' && Number.isFinite(value.attempts)
+    ? Math.max(0, Math.min(3, Math.trunc(value.attempts)))
+    : 0;
+  const expectedRetryable = status === 'SERVICE_UNAVAILABLE' || status === 'SERVICE_DISCONNECTED';
+  const token = status === 'OK' ? normalizeDeferredHandoffToken(value.token as string | undefined) : null;
+  if (status === 'OK' && !token) return { status: 'NO_TOKEN', retryable: false, attempts };
+  return {
+    status,
+    retryable: expectedRetryable,
+    attempts,
+    ...(token ? { token } : {}),
+  };
+}
+
+export function createPulseLinkClient<Action extends string = DeferredLinkAction>(
+  options: DeferredLinkClientOptions<Action>,
+): DeferredLinkClient {
+  const resolverBaseUrl = normalizeBaseUrl(options.resolverBaseUrl);
+  if (!/^https:\/\//i.test(resolverBaseUrl)) {
+    throw new Error('Pulse Links: resolverBaseUrl must use HTTPS');
+  }
+  const allowedDeepLinkPrefixes = options.allowedDeepLinkPrefixes
+    .map((prefix) => prefix.trim().toLowerCase())
+    .filter((prefix) => prefix.length > 0 && prefix.length <= 256);
+  if (allowedDeepLinkPrefixes.length === 0) {
+    throw new Error('Pulse Links: at least one app-owned deep-link prefix is required');
+  }
+  const allowedActions = new Set<Action>(
+    (options.allowedActions ?? DEFAULT_ACTIONS as unknown as readonly Action[]).filter(Boolean),
+  );
+  const sensitiveActions = new Set<Action>(
+    (options.sensitiveActions ?? DEFAULT_SENSITIVE_ACTIONS as unknown as readonly Action[]).filter(Boolean),
+  );
+  const now = options.now ?? Date.now;
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const appSlug = normalizeAppSlug(options.appSlug);
+  const explicitStorageKey = options.storageKey?.trim();
+  if (options.storage && !explicitStorageKey && !appSlug) {
+    throw new Error('Pulse Links: appSlug or an app-scoped storageKey is required when storage is used');
+  }
+  const storageKey = explicitStorageKey || (appSlug ? `pulse.${appSlug}.links.v1` : DEFAULT_STORAGE_KEY);
+  const requestTimeoutMs = boundedDuration(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, 500, 60_000);
+  const retryBaseMs = boundedDuration(options.retryBaseMs, DEFAULT_RETRY_BASE_MS, 100, 60 * 60 * 1_000);
+  const retryMaxMs = boundedDuration(options.retryMaxMs, DEFAULT_RETRY_MAX_MS, retryBaseMs, 24 * 60 * 60 * 1_000);
+  const tokenMaxAgeMs = boundedDuration(options.tokenMaxAgeMs, DEFAULT_TOKEN_MAX_AGE_MS, 60_000, 365 * 24 * 60 * 60 * 1_000);
+  const recentInstallMaxAgeMs = boundedDuration(
+    options.recentInstallMaxAgeMs,
+    DEFAULT_RECENT_INSTALL_MAX_AGE_MS,
+    60_000,
+    7 * 24 * 60 * 60 * 1_000,
+  );
+  const isPublicToken = options.isPublicToken ?? ((token: string) => PUBLIC_EXPOSURE.test(token));
+  let state = readState(options.storage, storageKey);
+  let disposed = false;
+  let processing: Promise<void> | null = null;
+  let processRequested = false;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let accountRetryAt = 0;
+  let accountAttempts = 0;
+  let lastFirstOpenContext: AnonymousFirstOpenContext | null = null;
+  let unsubscribeAccount: (() => void) | null = null;
+  const listeners = new Set<(value: DeferredLinkState) => void>();
+
+  const reportError = (error: unknown): void => {
+    try { options.onError?.(error); } catch { /* diagnostic hooks never break link handling */ }
+  };
+
+  const snapshot = (): DeferredLinkState => ({
+    status: state.status,
+    pending: state.pending ? { ...state.pending } : null,
+    lastAppliedId: state.lastAppliedId,
+    appliedIds: [...state.appliedIds],
+    firstOpen: { ...state.firstOpen },
+  });
+
+  const persistAndNotify = (): void => {
+    writeState(options.storage, storageKey, state);
+    const value = snapshot();
+    for (const listener of listeners) {
+      try { listener(value); } catch (error) { reportError(error); }
+    }
+    try { options.onStateChange?.(value); } catch (error) { reportError(error); }
+    scheduleWake();
+  };
+
+  const patchState = (patch: Partial<PersistedDeferredLinkState>): void => {
+    state = { ...state, ...patch };
+    persistAndNotify();
+  };
+
+  const patchFirstOpen = (patch: Partial<DeferredLinkFirstOpenState>): void => {
+    state = { ...state, firstOpen: { ...state.firstOpen, ...patch } };
+    persistAndNotify();
+  };
+
+  const isAccountReady = (): boolean => {
+    try { return options.isAccountReady?.() ?? false; } catch (error) {
+      reportError(error);
+      return false;
+    }
+  };
+
+  const schedulePendingRetry = (): void => {
+    const pending = state.pending;
+    if (!pending) return;
+    const attempts = pending.attempts + 1;
+    const delay = Math.min(retryBaseMs * 2 ** Math.min(attempts - 1, 10), retryMaxMs);
+    state = {
+      ...state,
+      status: 'retryable_error',
+      pending: { ...pending, attempts, nextRetryAt: now() + delay },
+    };
+    persistAndNotify();
+  };
+
+  const scheduleFirstOpenRetry = (): void => {
+    const attempts = state.firstOpen.attempts + 1;
+    const delay = Math.min(retryBaseMs * 2 ** Math.min(attempts - 1, 10), retryMaxMs);
+    state = {
+      ...state,
+      status: 'retryable_error',
+      firstOpen: { ...state.firstOpen, attempts, nextRetryAt: now() + delay },
+    };
+    persistAndNotify();
+  };
+
+  const scheduleAccountRetry = (): void => {
+    accountAttempts += 1;
+    const delay = Math.min(retryBaseMs * 2 ** Math.min(accountAttempts - 1, 10), retryMaxMs);
+    accountRetryAt = now() + delay;
+    patchState({ status: 'retryable_error' });
+  };
+
+  const clearPendingAsTerminal = (): void => {
+    patchState({ pending: null, status: 'terminal_error' });
+  };
+
+  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 ((options.reportResolverOutcomes ?? true) && isPublicToken(link.id)) {
+      void postResolverOutcome(
+        fetcher,
+        resolverBaseUrl,
+        link,
+        name,
+        requestTimeoutMs,
+      ).catch(reportError);
+    }
+  };
+
+  const applyResolved = async (
+    link: ResolvedDeferredLink<Action>,
+    sourceToken: string | null,
+  ): Promise<boolean> => {
+    if (disposed) return false;
+    if (state.appliedIds.includes(link.id)) {
+      if (sourceToken && state.pending?.token === sourceToken) {
+        state = {
+          ...state,
+          status: 'applied',
+          pending: null,
+          appliedIds: [...state.appliedIds.filter((id) => id !== sourceToken), sourceToken]
+            .slice(-MAX_APPLIED_IDS),
+        };
+        persistAndNotify();
+      }
+      return true;
+    }
+    if (sourceToken && state.pending?.token !== sourceToken) return false;
+    if (link.matchBasis === 'unmatched') return false;
+
+    if (link.action && sensitiveActions.has(link.action)) {
+      if (!link.matchGuaranteed) {
+        if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
+        return false;
+      }
+      if (!isAccountReady()) {
+        patchState({ status: 'waiting_for_account' });
+        return false;
+      }
+    }
+
+    // Validate the whole product surface before measuring a successful resolution. Otherwise a
+    // malicious/out-of-contract URL would inflate the resolver funnel despite never being usable.
+    if (link.deepLink && !isAllowedDeepLink(link.deepLink, allowedDeepLinkPrefixes)) {
+      if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
+      return false;
+    }
+    if (!link.deepLink && (!link.action || !options.onAction)) {
+      if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
+      return false;
+    }
+
+    emitOutcome(link, 'app_open_confirmed');
+    emitOutcome(link, 'deferred_link_resolved');
+    let applied: boolean | void;
+    try {
+      if (link.deepLink) {
+        applied = await options.onDeepLink(link.deepLink, link);
+      } else if (link.action && options.onAction) {
+        applied = await options.onAction(link);
+      } else {
+        if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
+        return false;
+      }
+    } catch (error) {
+      reportError(error);
+      if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();
+      else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();
+      else scheduleAccountRetry();
+      return false;
+    }
+    if (applied === false) {
+      if (sourceToken && state.pending?.token === sourceToken) schedulePendingRetry();
+      else if (link.matchBasis === 'unique_probabilistic') scheduleFirstOpenRetry();
+      else scheduleAccountRetry();
+      return false;
+    }
+
+    const newlyApplied = sourceToken && sourceToken !== link.id ? [link.id, sourceToken] : [link.id];
+    const newlyAppliedSet = new Set(newlyApplied);
+    const appliedIds = [...state.appliedIds.filter((id) => !newlyAppliedSet.has(id)), ...newlyApplied]
+      .slice(-MAX_APPLIED_IDS);
+    const stillPending = sourceToken !== null && state.pending?.token !== sourceToken;
+    state = {
+      ...state,
+      status: stillPending ? 'pending' : 'applied',
+      pending: sourceToken && state.pending?.token === sourceToken ? null : state.pending,
+      lastAppliedId: link.id,
+      appliedIds,
+    };
+    persistAndNotify();
+    if (link.matchBasis === 'account_bound') {
+      accountAttempts = 0;
+      accountRetryAt = 0;
+    }
+    emitOutcome(link, 'action_applied');
+    if (stillPending) void process();
+    return true;
+  };
+
+  const resolvePublic = async (
+    token: string,
+    basis: DeferredLinkMatchBasis,
+  ): Promise<ResolveResult<Action>> => {
+    if (!isPublicToken(token)) return { kind: 'not_found' };
+    try {
+      const response = await withTimeout(
+        fetcher,
+        `${resolverBaseUrl}${encodeURIComponent(token)}`,
+        {
+          method: 'GET',
+          headers: { Accept: 'application/json' },
+        },
+        requestTimeoutMs,
+      );
+      if (response.status === 404 || response.status === 410) return { kind: 'not_found' };
+      if (!response.ok) {
+        return { kind: response.status === 429 || response.status >= 500 ? 'retryable' : 'not_found' };
+      }
+      const link = normalizeResolved<Action>(
+        await response.json(),
+        token,
+        basis,
+        allowedActions,
+        now(),
+      );
+      return link ? { kind: 'resolved', link } : { kind: 'not_found' };
+    } catch {
+      return { kind: 'retryable' };
+    }
+  };
+
+  const processOnce = async (): Promise<void> => {
+    if (disposed) return;
+    const pending = state.pending;
+    if (pending) {
+      if (pending.nextRetryAt > now()) return;
+      if (now() - pending.receivedAt > tokenMaxAgeMs) {
+        clearPendingAsTerminal();
+        return;
+      }
+      const token = pending.token;
+      patchState({ status: 'resolving' });
+      const publicResult = await resolvePublic(token, pending.matchBasis);
+      if (disposed || state.pending?.token !== token) return;
+      if (publicResult.kind === 'resolved') {
+        await applyResolved(publicResult.link, token);
+        return;
+      }
+      if (publicResult.kind === 'retryable') {
+        schedulePendingRetry();
+        return;
+      }
+
+      if (!options.accountBridge || !isAccountReady()) {
+        patchState({ status: 'waiting_for_account' });
+        return;
+      }
+      try {
+        const raw = await options.accountBridge.claim(token);
+        if (disposed || state.pending?.token !== token) return;
+        const normalizedClaim = normalizeResolved<Action>(
+          raw,
+          token,
+          'account_bound',
+          allowedActions,
+          now(),
+        );
+        const claimed = normalizedClaim ? {
+          ...normalizedClaim,
+          matchBasis: 'account_bound' as const,
+          matchGuaranteed: true,
+          confidence: 1,
+        } : null;
+        if (claimed) await applyResolved(claimed, token);
+        else clearPendingAsTerminal();
+      } catch (error) {
+        reportError(error);
+        if (state.pending?.token === token) schedulePendingRetry();
+      }
+      return;
+    }
+
+    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    try {
+      const raw = await options.accountBridge.pending();
+      if (!raw) {
+        accountAttempts = 0;
+        accountRetryAt = 0;
+        if (state.status === 'waiting_for_account' || state.status === 'retryable_error') {
+          patchState({ status: 'idle' });
+        }
+        return;
+      }
+      const fallbackId = raw && typeof raw === 'object' && typeof raw.id === 'string'
+        ? raw.id
+        : 'account-bound-pending';
+      const normalizedPending = normalizeResolved<Action>(
+        raw,
+        fallbackId,
+        'account_bound',
+        allowedActions,
+        now(),
+      );
+      const pendingLink = normalizedPending ? {
+        ...normalizedPending,
+        matchBasis: 'account_bound' as const,
+        matchGuaranteed: true,
+        confidence: 1,
+      } : null;
+      if (pendingLink && !state.appliedIds.includes(pendingLink.id)) {
+        await applyResolved(pendingLink, null);
+      } else if (pendingLink && state.status !== 'applied') {
+        patchState({ status: 'applied' });
+      }
+    } catch (error) {
+      reportError(error);
+      // No token was consumed; the authenticated server outbox remains authoritative.
+      scheduleAccountRetry();
+    }
+  };
+
+  const process = async (): Promise<void> => {
+    if (disposed) return;
+    processRequested = true;
+    if (processing) return processing;
+    const run = (async () => {
+      do {
+        processRequested = false;
+        await processOnce();
+      } while (processRequested && !disposed);
+    })();
+    let ownedPromise: Promise<void>;
+    ownedPromise = run
+      .catch(reportError)
+      .then(async () => {
+        if (processing === ownedPromise) processing = null;
+        // A capture can arrive after the drain's last condition check but before its promise
+        // continuation runs. Chain that late request instead of losing the wakeup.
+        if (processRequested && !disposed) await process();
+      });
+    processing = ownedPromise;
+    return ownedPromise;
+  };
+
+  const capture = (rawToken: string, basis: DeferredLinkCaptureBasis): boolean => {
+    if (disposed || !CAPTURE_BASES.has(basis)) return false;
+    const token = normalizeDeferredHandoffToken(rawToken);
+    if (!token) return false;
+    if (state.appliedIds.includes(token)) {
+      if (!state.firstOpen.completed) patchFirstOpen({ completed: true, nextRetryAt: 0 });
+      return true;
+    }
+    if (state.pending?.token === token) {
+      if (state.pending.matchBasis === 'direct_token' && basis !== 'direct_token') {
+        state = {
+          ...state,
+          pending: { ...state.pending, matchBasis: basis },
+          firstOpen: { ...state.firstOpen, completed: true, nextRetryAt: 0 },
+        };
+        persistAndNotify();
+      } else if (!state.firstOpen.completed) {
+        patchFirstOpen({ completed: true, nextRetryAt: 0 });
+      }
+      void process();
+      return true;
+    }
+    state = {
+      ...state,
+      status: 'pending',
+      pending: {
+        token,
+        receivedAt: now(),
+        matchBasis: basis,
+        attempts: 0,
+        nextRetryAt: 0,
+      },
+      firstOpen: {
+        ...state.firstOpen,
+        completed: true,
+        nextRetryAt: 0,
+      },
+    };
+    persistAndNotify();
+    void process();
+    return true;
+  };
+
+  const matchFirstOpen = async (
+    context: AnonymousFirstOpenContext,
+  ): Promise<AnonymousFirstOpenResult> => {
+    if (disposed) return 'ineligible';
+    lastFirstOpenContext = context;
+    if (state.pending) return 'deterministic_pending';
+    if (state.firstOpen.completed) return 'already_completed';
+    if (state.firstOpen.nextRetryAt > now()) return 'backoff';
+    if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
+
+    const installAttemptId = state.firstOpen.installAttemptId
+      ?? makeInstallAttemptId(options.randomUUID);
+    state = {
+      ...state,
+      status: 'resolving',
+      firstOpen: {
+        ...state.firstOpen,
+        installAttemptId,
+        attemptedAt: now(),
+      },
+    };
+    persistAndNotify();
+
+    const body = {
+      appBundleId: context.appBundleId.trim(),
+      platform: 'ios' as const,
+      locale: normalizeLocale(context.locale),
+      firstOpen: true,
+      installAttemptId,
+    };
+    try {
+      const response = await withTimeout(
+        fetcher,
+        matchUrlOf(resolverBaseUrl),
+        {
+          method: 'POST',
+          headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        },
+        requestTimeoutMs,
+      );
+      if (state.pending) return 'deterministic_pending';
+      if (state.firstOpen.completed) return 'deterministic_pending';
+      if (response.status === 204) {
+        patchFirstOpen({ completed: true, attempts: 0, nextRetryAt: 0 });
+        patchState({ status: 'idle' });
+        return 'no_match';
+      }
+      if (response.status === 400 || response.status === 404 || response.status === 410) {
+        patchFirstOpen({ completed: true, nextRetryAt: 0 });
+        patchState({ status: 'terminal_error' });
+        return 'terminal_error';
+      }
+      if (!response.ok) {
+        if (response.status === 429 || response.status >= 500) {
+          scheduleFirstOpenRetry();
+          return 'retry_scheduled';
+        }
+        patchFirstOpen({ completed: true, nextRetryAt: 0 });
+        patchState({ status: 'terminal_error' });
+        return 'terminal_error';
+      }
+      const link = normalizeResolved<Action>(
+        await response.json(),
+        installAttemptId.replace(/-/g, ''),
+        'unique_probabilistic',
+        allowedActions,
+        now(),
+      );
+      // The probabilistic endpoint can personalize harmless UX only. It can never upgrade its own
+      // evidence to guaranteed or return a deterministic/account basis.
+      if (!link || link.matchBasis !== 'unique_probabilistic' || link.matchGuaranteed
+        || (link.action && sensitiveActions.has(link.action))) {
+        patchFirstOpen({ completed: true, nextRetryAt: 0 });
+        patchState({ status: 'terminal_error' });
+        return 'terminal_error';
+      }
+      if (await applyResolved(link, null)) {
+        patchFirstOpen({ completed: true, attempts: 0, nextRetryAt: 0 });
+        return 'matched';
+      }
+      if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+      return 'retry_scheduled';
+    } catch (error) {
+      reportError(error);
+      scheduleFirstOpenRetry();
+      return 'retry_scheduled';
+    }
+  };
+
+  const captureAndroidInstallReferrer = async (
+    bridge: AndroidInstallReferrerBridge,
+  ): Promise<AndroidInstallReferrerResult> => {
+    let raw: unknown;
+    try {
+      raw = await bridge.getDeferredHandoff();
+    } catch (error) {
+      reportError(error);
+      return { status: 'SERVICE_UNAVAILABLE', retryable: true, attempts: 0 };
+    }
+    const result = normalizeAndroidInstallReferrerResult(raw);
+    if (result.status === 'OK' && result.token) {
+      capture(result.token, 'android_install_referrer');
+    }
+    return result;
+  };
+
+  function scheduleWake(): void {
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    if (disposed || options.autoRetry === false) return;
+    const candidates = [
+      state.pending?.nextRetryAt ?? 0,
+      lastFirstOpenContext ? state.firstOpen.nextRetryAt : 0,
+      accountRetryAt,
+    ].filter((value) => value > now());
+    if (candidates.length === 0) return;
+    const next = Math.min(...candidates);
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void process();
+      if (lastFirstOpenContext && state.firstOpen.nextRetryAt <= now()) {
+        void matchFirstOpen(lastFirstOpenContext);
+      }
+    }, Math.max(0, next - now()));
+    const maybeTimer = retryTimer as unknown as { unref?: () => void };
+    maybeTimer.unref?.();
+  }
+
+  if (options.subscribeAccountState) {
+    try {
+      unsubscribeAccount = options.subscribeAccountState(() => { void process(); });
+    } catch (error) {
+      reportError(error);
+    }
+  }
+  scheduleWake();
+  void process();
+
+  return {
+    capture,
+    captureUrl: (url) => {
+      const token = extractDeferredHandoffToken(url);
+      return token ? capture(token, 'direct_token') : false;
+    },
+    process,
+    matchFirstOpen,
+    captureAndroidInstallReferrer,
+    getState: snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      if (retryTimer) clearTimeout(retryTimer);
+      retryTimer = null;
+      unsubscribeAccount?.();
+      unsubscribeAccount = null;
+      listeners.clear();
+    },
+    reset: () => {
+      accountRetryAt = 0;
+      accountAttempts = 0;
+      state = emptyState();
+      persistAndNotify();
+    },
+  };
+}
+
+/** @deprecated Prefer the product-facing `createPulseLinkClient` name. */
+export const createDeferredLinkClient = createPulseLinkClient;
+
+function normalizeBaseUrl(base: string): string {
+  return `${base.trim().replace(/\/+$/, '')}/`;
+}
+
+function normalizeAppSlug(value: string | undefined): string | null {
+  if (typeof value !== 'string') return null;
+  const slug = value.trim().toLowerCase();
+  return /^[a-z0-9][a-z0-9_-]{0,79}$/.test(slug) ? slug : null;
+}
+
+function matchUrlOf(resolverBaseUrl: string): string {
+  return resolverBaseUrl.replace(/\/t\/d\/$/i, '/t/match');
+}
+
+function boundedDuration(value: number | undefined, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+function isAllowedDeepLink(deepLink: string, prefixes: readonly string[]): boolean {
+  const normalized = deepLink.trim().toLowerCase();
+  return normalized.length > 0
+    && normalized.length <= 2_048
+    && prefixes.some((prefix) => normalized.startsWith(prefix));
+}
+
+function clampConfidence(value: unknown, fallback: number): number {
+  const number = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.max(0, Math.min(1, number));
+}
+
+/** Non-cryptographic local dedupe key. It is never authorization evidence or sent to analytics. */
+function stableOutcomeKey(linkId: string, name: DeferredLinkOutcomeName): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  for (let index = 0; index < linkId.length; index += 1) {
+    const code = linkId.charCodeAt(index);
+    first = Math.imul(first ^ code, 0x01000193) >>> 0;
+    second = Math.imul(second ^ (code + index), 0x85ebca6b) >>> 0;
+  }
+  return `${first.toString(16).padStart(8, '0')}${second.toString(16).padStart(8, '0')}|${name}`;
+}
+
+function boundedMetadata(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== 'string' && typeof value !== 'number') return undefined;
+  const result = String(value).trim();
+  return result.length > 0 && result.length <= 256 ? result : undefined;
+}
+
+function normalizeResolved<Action extends string>(
+  raw: unknown,
+  fallbackId: string,
+  fallbackBasis: DeferredLinkMatchBasis,
+  allowedActions: ReadonlySet<Action>,
+  now: number,
+): ResolvedDeferredLink<Action> | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const value = raw as Record<string, unknown>;
+  const action = typeof value.action === 'string' && allowedActions.has(value.action as Action)
+    ? value.action as Action
+    : undefined;
+  const deepLink = typeof value.deepLink === 'string' && value.deepLink.length <= 2_048
+    ? value.deepLink.trim()
+    : undefined;
+  if (!action && !deepLink) return null;
+
+  const rawBasis = typeof value.matchBasis === 'string'
+    && MATCH_BASES.has(value.matchBasis as DeferredLinkMatchBasis)
+    ? value.matchBasis as DeferredLinkMatchBasis
+    : fallbackBasis;
+  const matchBasis = rawBasis === 'direct_token'
+    && (fallbackBasis === 'android_install_referrer' || fallbackBasis === 'ios_user_paste')
+    ? fallbackBasis
+    : rawBasis;
+  const guaranteedDefault = matchBasis !== 'unique_probabilistic' && matchBasis !== 'unmatched';
+  const matchGuaranteed = matchBasis === 'unique_probabilistic' || matchBasis === 'unmatched'
+    ? false
+    : typeof value.matchGuaranteed === 'boolean' ? value.matchGuaranteed : guaranteedDefault;
+  const confidence = clampConfidence(value.confidence, matchGuaranteed ? 1 : 0);
+  const rawId = typeof value.id === 'string' ? value.id : fallbackId;
+  const id = normalizeDeferredHandoffToken(rawId) ?? normalizeDeferredHandoffToken(fallbackId);
+  if (!id) return null;
+
+  const expiresAt = typeof value.expiresAt === 'string' ? value.expiresAt : undefined;
+  if (expiresAt) {
+    const expiry = new Date(expiresAt).getTime();
+    if (!Number.isFinite(expiry) || expiry <= now) return null;
+  }
+  const source = boundedMetadata(value.source);
+  const campaignId = boundedMetadata(value.campaignId);
+  const experimentId = boundedMetadata(value.experimentId);
+  const variantId = boundedMetadata(value.variantId);
+  return {
+    id,
+    ...(action ? { action } : {}),
+    ...(deepLink ? { deepLink } : {}),
+    ...(expiresAt ? { expiresAt } : {}),
+    ...(source !== undefined ? { source } : {}),
+    ...(campaignId !== undefined ? { campaignId } : {}),
+    ...(experimentId !== undefined ? { experimentId } : {}),
+    ...(variantId !== undefined ? { variantId } : {}),
+    matchBasis,
+    matchGuaranteed,
+    confidence,
+  };
+}
+
+function isEligibleFirstOpen(
+  context: AnonymousFirstOpenContext,
+  now: number,
+  maxAgeMs: number,
+): boolean {
+  const appBundleId = context.appBundleId.trim();
+  const locale = normalizeLocale(context.locale);
+  return context.platform === 'ios'
+    && APP_IDENTITY.test(appBundleId)
+    && appBundleId.length <= 200
+    && LOCALE.test(locale)
+    && locale.length <= 35
+    && Number.isFinite(context.installedAt)
+    && context.installedAt > 0
+    && context.installedAt <= now
+    && now - context.installedAt <= maxAgeMs;
+}
+
+function normalizeLocale(locale: string): string {
+  return locale.trim().replace(/_/g, '-');
+}
+
+function makeInstallAttemptId(custom?: () => string): string {
+  try {
+    const candidate = custom?.()
+      ?? (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID?.();
+    if (candidate && INSTALL_ATTEMPT_ID.test(candidate)) return candidate.toLowerCase();
+  } catch { /* use the non-identity fallback below */ }
+  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()}`;
+}
+
+async function withTimeout(
+  fetcher: typeof fetch,
+  input: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetcher(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function postResolverOutcome<Action extends string>(
+  fetcher: typeof fetch,
+  resolverBaseUrl: string,
+  link: ResolvedDeferredLink<Action>,
+  name: DeferredLinkOutcomeName,
+  timeoutMs: number,
+): Promise<void> {
+  await withTimeout(
+    fetcher,
+    `${resolverBaseUrl}${encodeURIComponent(link.id)}/event/${name}`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ matchBasis: link.matchBasis, confidence: link.confidence }),
+    },
+    timeoutMs,
+  );
+}
+
+function readState(storage: ConfigStorage | undefined, key: string): PersistedDeferredLinkState {
+  if (!storage) return emptyState();
+  try {
+    const raw = storage.getString(key);
+    if (!raw || raw.length > MAX_PERSISTED_BYTES) return emptyState();
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (parsed.version !== 1) return emptyState();
+    const fallback = emptyState();
+    const status = typeof parsed.status === 'string' && STATUSES.has(parsed.status as DeferredLinkStatus)
+      ? parsed.status as DeferredLinkStatus
+      : fallback.status;
+    const pendingValue = parsed.pending && typeof parsed.pending === 'object'
+      ? parsed.pending as Record<string, unknown>
+      : null;
+    const pendingToken = normalizeDeferredHandoffToken(pendingValue?.token as string | undefined);
+    const pendingBasis = typeof pendingValue?.matchBasis === 'string'
+      && CAPTURE_BASES.has(pendingValue.matchBasis as DeferredLinkCaptureBasis)
+      ? pendingValue.matchBasis as DeferredLinkCaptureBasis
+      : null;
+    const pending = pendingToken && pendingBasis
+      ? {
+        token: pendingToken,
+        receivedAt: safeTimestamp(pendingValue?.receivedAt),
+        matchBasis: pendingBasis,
+        attempts: safeInteger(pendingValue?.attempts, 100_000),
+        nextRetryAt: safeTimestamp(pendingValue?.nextRetryAt),
+      }
+      : null;
+    const appliedIds = Array.isArray(parsed.appliedIds)
+      ? parsed.appliedIds.filter(isOpaqueDeferredLinkToken).slice(-MAX_APPLIED_IDS)
+      : [];
+    const lastApplied = normalizeDeferredHandoffToken(parsed.lastAppliedId as string | undefined);
+    if (lastApplied && !appliedIds.includes(lastApplied)) appliedIds.push(lastApplied);
+    const firstValue = parsed.firstOpen && typeof parsed.firstOpen === 'object'
+      ? parsed.firstOpen as Record<string, unknown>
+      : {};
+    const attemptId = typeof firstValue.installAttemptId === 'string'
+      && INSTALL_ATTEMPT_ID.test(firstValue.installAttemptId)
+      ? firstValue.installAttemptId.toLowerCase()
+      : null;
+    const notifiedOutcomes = Array.isArray(parsed.notifiedOutcomes)
+      ? parsed.notifiedOutcomes
+        .filter((value): value is string => typeof value === 'string'
+          && /^[a-f0-9]{16}\|(app_open_confirmed|deferred_link_resolved|action_applied)$/.test(value))
+        .slice(-MAX_NOTIFIED_OUTCOMES)
+      : [];
+    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),
+      firstOpen: {
+        installAttemptId: attemptId,
+        completed: firstValue.completed === true,
+        attemptedAt: safeTimestamp(firstValue.attemptedAt),
+        attempts: safeInteger(firstValue.attempts, 100_000),
+        nextRetryAt: safeTimestamp(firstValue.nextRetryAt),
+      },
+    };
+  } catch {
+    return emptyState();
+  }
+}
+
+function writeState(
+  storage: ConfigStorage | undefined,
+  key: string,
+  state: PersistedDeferredLinkState,
+): void {
+  if (!storage) return;
+  try { void storage.set(key, JSON.stringify(state)); } catch { /* in-memory operation continues */ }
+}
+
+function safeTimestamp(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+
+function safeInteger(value: unknown, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.min(max, Math.trunc(value)))
+    : 0;
+}