pulse-updates 1.2.5 → 1.3.1

package/lib/commonjs/links.js

@@ -0,0 +1,944 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createDeferredLinkClient = void 0;
+exports.createPulseLinkClient = createPulseLinkClient;
+exports.extractDeferredHandoffToken = extractDeferredHandoffToken;
+exports.isOpaqueDeferredLinkToken = isOpaqueDeferredLinkToken;
+exports.normalizeAndroidInstallReferrerResult = normalizeAndroidInstallReferrerResult;
+exports.normalizeDeferredHandoffToken = normalizeDeferredHandoffToken;
+/**
+ * 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.
+ */
+
+/** Implemented by the separate native `PulseAttribution` module. */
+
+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:'];
+const DEFAULT_QUERY_KEYS = new Set(['encore_handoff', 'encore_deferred', 'pulse_handoff', 'pulse_deferred']);
+const MATCH_BASES = new Set(['direct_token', 'android_install_referrer', 'ios_user_paste', 'account_bound', 'unique_probabilistic', 'unmatched']);
+const CAPTURE_BASES = new Set(['direct_token', 'android_install_referrer', 'ios_user_paste']);
+const STATUSES = new Set(['idle', 'pending', 'resolving', 'waiting_for_account', 'retryable_error', 'applied', 'terminal_error']);
+const INSTALL_REFERRER_STATUSES = new Set(['OK', 'NO_TOKEN', 'FEATURE_NOT_SUPPORTED', 'SERVICE_UNAVAILABLE', 'DEVELOPER_ERROR', 'SERVICE_DISCONNECTED']);
+const DEFAULT_ACTIONS = ['open_home', 'open_premium', 'manage_subscription', 'refresh_entitlement'];
+const DEFAULT_SENSITIVE_ACTIONS = ['manage_subscription', 'refresh_entitlement'];
+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;
+const emptyState = () => ({
+  version: 1,
+  status: 'idle',
+  pending: null,
+  lastAppliedId: null,
+  appliedIds: [],
+  notifiedOutcomes: [],
+  firstOpen: {
+    installAttemptId: null,
+    completed: false,
+    attemptedAt: 0,
+    attempts: 0,
+    nextRetryAt: 0
+  }
+});
+function isOpaqueDeferredLinkToken(value) {
+  return typeof value === 'string' && OPAQUE_TOKEN.test(value);
+}
+function normalizeDeferredHandoffToken(raw, acceptedPrefixes = DEFAULT_PREFIXES) {
+  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. */
+function extractDeferredHandoffToken(url) {
+  if (typeof url !== 'string' || url.length === 0 || url.length > 4_096) return null;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (!parsed.protocol) return null;
+  const queryCandidates = [];
+  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. */
+function normalizeAndroidInstallReferrerResult(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return {
+      status: 'SERVICE_UNAVAILABLE',
+      retryable: true,
+      attempts: 0
+    };
+  }
+  const value = raw;
+  const status = typeof value.status === 'string' && INSTALL_REFERRER_STATUSES.has(value.status) ? value.status : '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) : null;
+  if (status === 'OK' && !token) return {
+    status: 'NO_TOKEN',
+    retryable: false,
+    attempts
+  };
+  return {
+    status,
+    retryable: expectedRetryable,
+    attempts,
+    ...(token ? {
+      token
+    } : {})
+  };
+}
+function createPulseLinkClient(options) {
+  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((options.allowedActions ?? DEFAULT_ACTIONS).filter(Boolean));
+  const sensitiveActions = new Set((options.sensitiveActions ?? DEFAULT_SENSITIVE_ACTIONS).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 => PUBLIC_EXPOSURE.test(token));
+  let state = readState(options.storage, storageKey);
+  let disposed = false;
+  let processing = null;
+  let processRequested = false;
+  let retryTimer = null;
+  let accountRetryAt = 0;
+  let accountAttempts = 0;
+  let lastFirstOpenContext = null;
+  let unsubscribeAccount = null;
+  const listeners = new Set();
+  const reportError = error => {
+    try {
+      options.onError?.(error);
+    } catch {/* diagnostic hooks never break link handling */}
+  };
+  const snapshot = () => ({
+    status: state.status,
+    pending: state.pending ? {
+      ...state.pending
+    } : null,
+    lastAppliedId: state.lastAppliedId,
+    appliedIds: [...state.appliedIds],
+    firstOpen: {
+      ...state.firstOpen
+    }
+  });
+  const persistAndNotify = () => {
+    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 => {
+    state = {
+      ...state,
+      ...patch
+    };
+    persistAndNotify();
+  };
+  const patchFirstOpen = patch => {
+    state = {
+      ...state,
+      firstOpen: {
+        ...state.firstOpen,
+        ...patch
+      }
+    };
+    persistAndNotify();
+  };
+  const isAccountReady = () => {
+    try {
+      return options.isAccountReady?.() ?? false;
+    } catch (error) {
+      reportError(error);
+      return false;
+    }
+  };
+  const schedulePendingRetry = () => {
+    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 = () => {
+    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 = () => {
+    accountAttempts += 1;
+    const delay = Math.min(retryBaseMs * 2 ** Math.min(accountAttempts - 1, 10), retryMaxMs);
+    accountRetryAt = now() + delay;
+    patchState({
+      status: 'retryable_error'
+    });
+  };
+  const clearPendingAsTerminal = () => {
+    patchState({
+      pending: null,
+      status: 'terminal_error'
+    });
+  };
+  const emitOutcome = (link, name) => {
+    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 = {
+        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.catch === 'function') {
+          void result.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, sourceToken) => {
+    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;
+    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, basis) => {
+    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(await response.json(), token, basis, allowedActions, now());
+      return link ? {
+        kind: 'resolved',
+        link
+      } : {
+        kind: 'not_found'
+      };
+    } catch {
+      return {
+        kind: 'retryable'
+      };
+    }
+  };
+  const processOnce = async () => {
+    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(raw, token, 'account_bound', allowedActions, now());
+        const claimed = normalizedClaim ? {
+          ...normalizedClaim,
+          matchBasis: 'account_bound',
+          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(raw, fallbackId, 'account_bound', allowedActions, now());
+      const pendingLink = normalizedPending ? {
+        ...normalizedPending,
+        matchBasis: 'account_bound',
+        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 () => {
+    if (disposed) return;
+    processRequested = true;
+    if (processing) return processing;
+    const run = (async () => {
+      do {
+        processRequested = false;
+        await processOnce();
+      } while (processRequested && !disposed);
+    })();
+    let ownedPromise;
+    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, basis) => {
+    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 => {
+    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',
+      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(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 => {
+    let raw;
+    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() {
+    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;
+    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. */
+const createDeferredLinkClient = exports.createDeferredLinkClient = createPulseLinkClient;
+function normalizeBaseUrl(base) {
+  return `${base.trim().replace(/\/+$/, '')}/`;
+}
+function normalizeAppSlug(value) {
+  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) {
+  return resolverBaseUrl.replace(/\/t\/d\/$/i, '/t/match');
+}
+function boundedDuration(value, fallback, min, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function isAllowedDeepLink(deepLink, prefixes) {
+  const normalized = deepLink.trim().toLowerCase();
+  return normalized.length > 0 && normalized.length <= 2_048 && prefixes.some(prefix => normalized.startsWith(prefix));
+}
+function clampConfidence(value, fallback) {
+  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, name) {
+  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) {
+  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(raw, fallbackId, fallbackBasis, allowedActions, now) {
+  if (!raw || typeof raw !== 'object') return null;
+  const value = raw;
+  const action = typeof value.action === 'string' && allowedActions.has(value.action) ? value.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) ? value.matchBasis : 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, now, maxAgeMs) {
+  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) {
+  return locale.trim().replace(/_/g, '-');
+}
+function makeInstallAttemptId(custom) {
+  try {
+    const candidate = custom?.() ?? globalThis.crypto?.randomUUID?.();
+    if (candidate && INSTALL_ATTEMPT_ID.test(candidate)) return candidate.toLowerCase();
+  } catch {/* use the non-identity fallback below */}
+  const hex = () => 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, input, init, timeoutMs) {
+  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(fetcher, resolverBaseUrl, link, name, timeoutMs) {
+  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, key) {
+  if (!storage) return emptyState();
+  try {
+    const raw = storage.getString(key);
+    if (!raw || raw.length > MAX_PERSISTED_BYTES) return emptyState();
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) return emptyState();
+    const fallback = emptyState();
+    const status = typeof parsed.status === 'string' && STATUSES.has(parsed.status) ? parsed.status : fallback.status;
+    const pendingValue = parsed.pending && typeof parsed.pending === 'object' ? parsed.pending : null;
+    const pendingToken = normalizeDeferredHandoffToken(pendingValue?.token);
+    const pendingBasis = typeof pendingValue?.matchBasis === 'string' && CAPTURE_BASES.has(pendingValue.matchBasis) ? pendingValue.matchBasis : 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);
+    if (lastApplied && !appliedIds.includes(lastApplied)) appliedIds.push(lastApplied);
+    const firstValue = parsed.firstOpen && typeof parsed.firstOpen === 'object' ? parsed.firstOpen : {};
+    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 => 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, key, state) {
+  if (!storage) return;
+  try {
+    void storage.set(key, JSON.stringify(state));
+  } catch {/* in-memory operation continues */}
+}
+function safeTimestamp(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+function safeInteger(value, max) {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(max, Math.trunc(value))) : 0;
+}
+//# sourceMappingURL=links.js.map