pulse-updates 1.3.8 → 1.3.10

package/src/links.ts

@@ -122,6 +122,14 @@ export interface AnonymousFirstOpenContext {
   /** JavaScript Date#getTimezoneOffset semantics, bounded to real-world UTC offsets. */
   timezoneOffsetMinutes?: number;
   isEmulator?: boolean;
+  /**
+   * The address the person is signed in with, when the host app has one. An install that arrives
+   * with an account does not need to be guessed at: the resolver binds it to the message sent to
+   * that address and skips probabilistic matching entirely. Omitted for signed-out first opens,
+   * and never read from the clipboard or any other ambient source — the app passes what it
+   * already knows, or nothing.
+   */
+  accountEmail?: string;
 }
 
 export type AnonymousFirstOpenResult =
@@ -261,6 +269,17 @@ export interface DeferredLinkClientOptions<Action extends string = DeferredLinkA
   randomUUID?: () => string;
   /** Phase-one public campaign exposures are 128-bit hex; account tokens use the wider grammar. */
   isPublicToken?: (token: string) => boolean;
+  /**
+   * Whether a first open may name the signed-in account.
+   *
+   * Off by default, and deliberately a second switch rather than "the host passed one, so send
+   * it": an address is the only piece of the first-open request that identifies a person, and an
+   * integrator adopting Pulse must choose to send it rather than discover later that reading their
+   * own auth state started forwarding addresses. With it on, an install that arrives signed in is
+   * bound to the message sent to that address instead of being inferred from device shape and
+   * timing — the only deterministic signal left where no store referrer survives.
+   */
+  sendAccountEmailOnFirstOpen?: boolean;
 }
 
 export interface DeferredLinkClient {
@@ -574,6 +593,11 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   let accountRetryAt = 0;
   let accountAttempts = 0;
   let deterministicEpoch = 0;
+  // Invalidates every host callback that crossed an await when this client is reset/disposed.
+  // This is deliberately separate from deterministicEpoch: captures during a committed callback
+  // have intentional last-touch semantics, whereas a lifecycle boundary must forbid every stale
+  // state write, retry and outcome from the old instance.
+  let lifecycleGeneration = 0;
   // Host navigation is irreversible once any routing callback has started: it may perform its
   // side effect synchronously before returning a Promise. Serialize captures against that commit
   // boundary and keep the newer accepted token durable for the next client lifecycle instead of
@@ -796,6 +820,11 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     status: DeferredLinkStatus,
     outcome: Omit<AnonymousFirstOpenTerminalOutcome, 'eventId' | 'occurredAt' | 'retryable'>,
   ): void => {
+    const completionLifecycleGeneration = lifecycleGeneration;
+    const completionDeterministicEpoch = deterministicEpoch;
+    const completionIsCurrent = (): boolean => !disposed
+      && lifecycleGeneration === completionLifecycleGeneration
+      && deterministicEpoch === completionDeterministicEpoch;
     let shouldQueue = Boolean(options.onFirstOpenResult);
     if (shouldQueue && options.shouldQueueFirstOpenResult) {
       try {
@@ -804,6 +833,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         shouldQueue = false;
         reportError(error);
       }
+      // Privacy/diagnostic hooks are host code and may synchronously reset, dispose, or capture a
+      // deterministic destination. Never resurrect the terminal first-open state they invalidated.
+      if (!completionIsCurrent()) return;
     }
     if (!shouldQueue) {
       state = {
@@ -852,21 +884,36 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     void flushTerminalDelivery();
   };
 
-  const blockFirstOpenForDeterministic = (): void => {
+  const blockFirstOpenForDeterministic = (): boolean => {
+    const blockingLifecycleGeneration = lifecycleGeneration;
     deterministicEpoch += 1;
-    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return;
+    const blockingDeterministicEpoch = deterministicEpoch;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return true;
     state = {
       ...state,
       firstOpen: { ...state.firstOpen, completed: true, nextRetryAt: 0 },
     };
     persistAndNotify();
+    return !disposed
+      && lifecycleGeneration === blockingLifecycleGeneration
+      && deterministicEpoch === blockingDeterministicEpoch;
   };
 
-  const isAccountReady = (): boolean => {
-    try { return options.isAccountReady?.() ?? false; } catch (error) {
+  const readAccountReadiness = (): { ready: boolean; current: boolean } => {
+    const readinessLifecycleGeneration = lifecycleGeneration;
+    const readinessDeterministicEpoch = deterministicEpoch;
+    let ready = false;
+    try { ready = options.isAccountReady?.() ?? false; } catch (error) {
       reportError(error);
-      return false;
     }
+    return {
+      ready,
+      // Readiness is host code, not a pure getter. A reset/dispose/capture inside it invalidates
+      // the caller's snapshot and must be observed before any waiting/retry/application write.
+      current: !disposed
+        && lifecycleGeneration === readinessLifecycleGeneration
+        && deterministicEpoch === readinessDeterministicEpoch,
+    };
   };
 
   const schedulePendingRetry = (): void => {
@@ -1101,7 +1148,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
         return false;
       }
-      if (!isAccountReady()) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) return false;
+      if (!accountReadiness.ready) {
         patchState({ status: 'waiting_for_account' });
         return false;
       }
@@ -1122,6 +1171,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     let applicationFailed = false;
     let applicationError: unknown;
     const applicationEpoch = deterministicEpoch;
+    const applicationLifecycleGeneration = lifecycleGeneration;
+    const lifecycleIsCurrent = (): boolean => !disposed
+      && lifecycleGeneration === applicationLifecycleGeneration;
     const hasNewerPendingIntent = (): boolean => deterministicEpoch !== applicationEpoch
       && state.pending !== null
       // A provenance upgrade or rejected lower-priority capture for the token already being
@@ -1129,7 +1181,15 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       && (sourceToken === null || state.pending.token !== sourceToken);
     routingApplicationInFlight = true;
     emitOutcome(link, 'app_open_confirmed');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     emitOutcome(link, 'deferred_link_resolved');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     // `emitOutcome` invokes host diagnostics synchronously. If those hooks re-enter capture with
     // a newer accepted destination, it still arrived before the routing callback and must win.
     if (hasNewerPendingIntent()) {
@@ -1153,10 +1213,19 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       routingApplicationInFlight = false;
     }
 
+    // The callback may resolve after reset/dispose and after another client has already committed
+    // a newer journey into the same storage. The old instance must not schedule a retry, rewrite
+    // state, or emit action_applied regardless of whether the callback returned true/false/threw.
+    if (!lifecycleIsCurrent()) return false;
+
     const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
     if (applicationFailed) {
       reportError(applicationError);
-      if (newerIntentArrivedDuringApplication) {
+      if (!lifecycleIsCurrent()) return false;
+      // onError is host code too: it may capture a newer deterministic destination while reporting
+      // this failure. Re-evaluate after the callback instead of arming a stale retry from the value
+      // observed before diagnostics ran.
+      if (hasNewerPendingIntent()) {
         // The current action did not commit. Resume the newer accepted intent that was captured
         // while its callback was suspended, without scheduling a retry for the superseded one.
         void process();
@@ -1200,11 +1269,13 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       appliedIds,
     };
     persistAndNotify();
+    if (!lifecycleIsCurrent()) return false;
     if (link.matchBasis === 'account_bound') {
       accountAttempts = 0;
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
+    if (!lifecycleIsCurrent()) return false;
     if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
       void process();
     }
@@ -1258,9 +1329,15 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return;
       }
       const token = pending.token;
+      const pendingLifecycleGeneration = lifecycleGeneration;
       patchState({ status: 'resolving' });
+      if (disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
       const publicResult = await resolvePublic(token, pending.matchBasis);
-      if (disposed || state.pending?.token !== token) return;
+      if (disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
       if (publicResult.kind === 'resolved') {
         await applyResolved(publicResult.link, token);
         return;
@@ -1270,7 +1347,16 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         return;
       }
 
-      if (!options.accountBridge || !isAccountReady()) {
+      if (!options.accountBridge) {
+        patchState({ status: 'waiting_for_account' });
+        return;
+      }
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current
+        || disposed
+        || lifecycleGeneration !== pendingLifecycleGeneration
+        || state.pending?.token !== token) return;
+      if (!accountReadiness.ready) {
         patchState({ status: 'waiting_for_account' });
         return;
       }
@@ -1280,7 +1366,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
           requestTimeoutMs,
           'account claim',
         );
-        if (disposed || state.pending?.token !== token) return;
+        if (disposed
+          || lifecycleGeneration !== pendingLifecycleGeneration
+          || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved<Action>(
           raw,
           token,
@@ -1295,19 +1383,28 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
           confidence: 1,
         } : null;
         if (claimed) {
-          blockFirstOpenForDeterministic();
+          if (!blockFirstOpenForDeterministic()) return;
           await applyResolved(claimed, token);
         }
         else clearPendingAsTerminal();
       } catch (error) {
+        if (disposed
+          || lifecycleGeneration !== pendingLifecycleGeneration
+          || state.pending?.token !== token) return;
         reportError(error);
-        if (state.pending?.token === token) schedulePendingRetry();
+        if (!disposed
+          && lifecycleGeneration === pendingLifecycleGeneration
+          && state.pending?.token === token) schedulePendingRetry();
       }
       return;
     }
 
-    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    if (!options.accountBridge) return;
+    const accountReadiness = readAccountReadiness();
+    if (!accountReadiness.current || state.pending) return;
+    if (!accountReadiness.ready || accountRetryAt > now()) return;
     const accountPendingEpoch = deterministicEpoch;
+    const accountPendingLifecycleGeneration = lifecycleGeneration;
     try {
       const raw = await withPromiseTimeout(
         () => options.accountBridge!.pending(),
@@ -1317,7 +1414,10 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       // A URL/paste/referrer captured while the account lookup was in flight is newer explicit
       // user intent. Ignore the stale bridge response and let the requested drain resolve the
       // captured token; otherwise both deterministic destinations could be applied.
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -1346,7 +1446,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         // Reserve the first-open journey for deterministic recovery before invoking any host
         // callback. This also covers an already-applied account item restored from older SDK
         // state, which must still prevent a second probabilistic destination.
-        blockFirstOpenForDeterministic();
+        if (!blockFirstOpenForDeterministic()) return;
         if (!state.appliedIds.includes(pendingLink.id)) {
           await applyResolved(pendingLink, null);
         } else if (state.status !== 'applied') {
@@ -1354,8 +1454,15 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         }
       }
     } catch (error) {
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       reportError(error);
+      if (disposed
+        || lifecycleGeneration !== accountPendingLifecycleGeneration
+        || deterministicEpoch !== accountPendingEpoch
+        || state.pending) return;
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
     }
@@ -1451,7 +1558,14 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     lastFirstOpenContext = context;
     if (state.pending) return 'deterministic_pending';
     if (state.firstOpen.completed) return 'already_completed';
-    if (state.firstOpen.nextRetryAt > now()) return 'backoff';
+    if (state.firstOpen.nextRetryAt > now()) {
+      // On a fresh client lifecycle scheduleWake() ran before the host supplied this ephemeral
+      // context, so the persisted first-open deadline could not be part of its candidates. Re-arm
+      // now that retrying is possible; otherwise a 503 followed by process death remains asleep
+      // until some unrelated foreground/manual call invokes matchFirstOpen again.
+      scheduleWake();
+      return 'backoff';
+    }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
 
     // The client starts account recovery at construction. Join that deterministic rail before
@@ -1460,15 +1574,22 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     await process();
     if (disposed) return 'ineligible';
     if (state.pending || state.firstOpen.completed) return 'deterministic_pending';
-    if (options.accountBridge && isAccountReady() && accountRetryAt > now()) {
-      if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
-      return 'retry_scheduled';
+    if (options.accountBridge) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) {
+        return disposed ? 'ineligible' : 'deterministic_pending';
+      }
+      if (accountReadiness.ready && accountRetryAt > now()) {
+        if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+        return 'retry_scheduled';
+      }
     }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
 
     const installAttemptId = state.firstOpen.installAttemptId
       ?? makeInstallAttemptId(options.randomUUID);
     const startingDeterministicEpoch = deterministicEpoch;
+    const startingLifecycleGeneration = lifecycleGeneration;
     state = {
       ...state,
       status: 'resolving',
@@ -1478,8 +1599,37 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
         attemptedAt: now(),
       },
     };
-    persistAndNotify();
+    const firstOpenReservationPersisted = persistAndNotify();
+    // Persistence notifies host state hooks synchronously. They may reset/dispose this client or
+    // capture a deterministic destination. In all three cases the reserved id no longer belongs to
+    // the current lifecycle and must never cross the network boundary.
+    if (disposed) return 'ineligible';
+    if (lifecycleGeneration !== startingLifecycleGeneration
+      || deterministicEpoch !== startingDeterministicEpoch
+      || state.pending
+      || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.storage && !firstOpenReservationPersisted) {
+      // An unpersisted id must never leave the process: after a crash the retry would mint a new
+      // id and the server could count/route the same install twice. Keep the exact nonce in memory,
+      // arm a persistence retry without incrementing matcher attempts, and send nothing until a
+      // synchronous durable write succeeds. Memory-only clients have no restart contract and may
+      // continue normally.
+      state = {
+        ...state,
+        status: 'retryable_error',
+        firstOpen: {
+          ...state.firstOpen,
+          nextRetryAt: now() + retryBaseMs,
+        },
+      };
+      reportError(new Error('Pulse Links: first-open install attempt id was not durably persisted'));
+      notifyState();
+      return 'retry_scheduled';
+    }
 
+    const accountEmail = options.sendAccountEmailOnFirstOpen === true
+      ? normalizeAccountEmail(context.accountEmail)
+      : null;
     const body = {
       appBundleId: context.appBundleId.trim(),
       platform: 'ios' as const,
@@ -1487,6 +1637,10 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       firstOpen: true,
       installAttemptId,
       ...normalizeAnonymousFirstOpenSignals(context),
+      // Sent only when the app already knows it. The resolver treats an address that matches
+      // exactly one recent message as proof of origin; anything else falls back to the
+      // probabilistic path, so a shared or unknown address costs nothing.
+      ...(accountEmail ? { accountEmail } : {}),
     };
     try {
       const response = await withTimeout(
@@ -1637,6 +1791,8 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
   const captureAndroidInstallReferrer = async (
     bridge: AndroidInstallReferrerBridge,
   ): Promise<AndroidInstallReferrerResult> => {
+    const referrerLifecycleGeneration = lifecycleGeneration;
+    const referrerDeterministicEpoch = deterministicEpoch;
     let raw: unknown;
     try {
       raw = await bridge.getDeferredHandoff();
@@ -1645,6 +1801,9 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
       return { status: 'SERVICE_UNAVAILABLE', retryable: true, attempts: 0 };
     }
     const result = normalizeAndroidInstallReferrerResult(raw);
+    if (disposed
+      || lifecycleGeneration !== referrerLifecycleGeneration
+      || deterministicEpoch !== referrerDeterministicEpoch) return result;
     if (result.status === 'OK' && result.token) {
       capture(result.token, 'android_install_referrer');
     }
@@ -1708,6 +1867,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
@@ -1719,6 +1879,7 @@ export function createPulseLinkClient<Action extends string = DeferredLinkAction
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       terminalDeliverySending = null;
@@ -1967,6 +2128,20 @@ function resolverOutcomeRetryDelay(
   return Math.max(1, Math.floor(ceiling * jitter));
 }
 
+/**
+ * An address is only useful to the resolver if it is the same shape the send was recorded with.
+ * Anything that is not plausibly an address is dropped rather than sent: a malformed value can
+ * only ever fail to match, and not sending it keeps the payload free of stray user input.
+ */
+export function normalizeAccountEmail(raw: string | undefined | null): string | null {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value.length < 3 || value.length > 255) return null;
+  const at = value.indexOf('@');
+  if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null;
+  if (/\s/.test(value)) return null;
+  return value;
+}
+
 async function withTimeout(
   fetcher: typeof fetch,
   input: string,