@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/pairing/PairingController.ts

@@ -2,11 +2,17 @@ import {
   DEFAULT_PAIRING_ENDPOINT,
   PairingEngine,
   type PairingEngineState,
+  type PairingPurpose,
   type UserflowCore,
 } from '@userflow-tech/core';
+import { decodePairingJwt, isPairingJwtExpired } from '@userflow-tech/protocol';
 import { AppState, type AppStateStatus, Linking, Platform } from 'react-native';
 
+import { clearFiberAnchorCache } from '../anchors/fiberAnchorCache';
+import { evalJsController } from '../evalJs/evalJsController';
+
 import { inspectPairingDeepLink, isPairingAttempt } from './deepLink';
+import { getOrCreatePairingDeviceId } from './deviceId';
 import {
   defaultPairingLogger,
   pairingAttemptRejectionMessage,
@@ -14,9 +20,11 @@ import {
   pairingLinkDeferredMessage,
   pairingLinkInitFailedMessage,
   pairingListenerSetupFailedMessage,
+  pairingPreviewErrorMessage,
   pairingTokenStoreClearFailedMessage,
   type PairingLogger,
 } from './diagnostics';
+import { bindElementPickerRelay } from './elementPickerRelay';
 import { createPairingTokenStore, type PairingTokenStore } from './tokenStorage';
 
 export type PairingControllerListener = (state: PairingEngineState) => void;
@@ -38,6 +46,13 @@ export interface PairingControllerOptions {
   tokenStore?: PairingTokenStore;
   /** Clear mid-flow session when exiting preview. */
   clearLocalSession?: () => void;
+  /** End the previewed draft on the server when exiting preview. */
+  endDraftSession?: () => Promise<void>;
+  /**
+   * Drop an end that is waiting for a draft identify has not delivered.
+   * A new preview must call this so that draft is not ended when it arrives.
+   */
+  cancelPendingDraftEnd?: () => void;
   LinkingModule?: {
     getInitialURL(): Promise<string | null>;
     addEventListener(type: 'url', handler: (event: { url: string }) => void): { remove(): void };
@@ -47,6 +62,11 @@ export interface PairingControllerOptions {
   };
   /** Sink for pairing diagnostics. Injected in tests. */
   logger?: PairingLogger;
+  /**
+   * Stable pairing device id. Defaults to the persisted install id.
+   * Injected in tests.
+   */
+  deviceIdProvider?: () => Promise<string>;
 }
 
 /**
@@ -64,15 +84,36 @@ export class PairingController {
   private readonly LinkingModule: NonNullable<PairingControllerOptions['LinkingModule']>;
   private readonly AppStateModule: NonNullable<PairingControllerOptions['AppStateModule']>;
   private readonly clearLocalSession: (() => void) | undefined;
+  private readonly endDraftSession: (() => Promise<void>) | undefined;
+  private readonly cancelPendingDraftEnd: (() => void) | undefined;
   private readonly core: UserflowCore;
   private readonly pairingEndpoint: string;
   private readonly logger: PairingLogger;
+  private readonly deviceIdProvider: () => Promise<string>;
+  private pairingDeviceId: string | null = null;
+  /** A link or resume already claimed this launch, so a stored token must not. */
+  private acceptedPairingToken = false;
+  /**
+   * Bumped by exitPreview. An in-flight resume or connect checks it after
+   * every await and does not write the token or leave the socket up.
+   */
+  private launchEpoch = 0;
+  /** Latest enterPreview. An older attempt must not clear a newer token. */
+  private enterAttempt = 0;
+  /**
+   * Orders token and purpose writes. Two scans can overlap on the awaits, and
+   * the slower one's purpose must not land on the token the faster one saved.
+   */
+  private previewSaveQueue: Promise<void> = Promise.resolve();
   private initPhase: InitPhase = 'ready';
   private initFailureReason: string | null = null;
   /** Pairing token captured before init resolved, replayed once it does. */
   private deferredPairingToken: string | null = null;
+  /** Purpose of {@link deferredPairingToken}, so the held banner already honours it. */
+  private deferredPurpose: PairingPurpose | null = null;
   /** Diagnostics already emitted for the current init attempt. */
   private readonly loggedOnce = new Set<string>();
+  private relayUnsub: (() => void) | null = null;
 
   constructor(options: PairingControllerOptions) {
     this.core = options.core;
@@ -81,7 +122,10 @@ export class PairingController {
     this.LinkingModule = options.LinkingModule ?? Linking;
     this.AppStateModule = options.AppStateModule ?? AppState;
     this.clearLocalSession = options.clearLocalSession ?? undefined;
+    this.endDraftSession = options.endDraftSession ?? undefined;
+    this.cancelPendingDraftEnd = options.cancelPendingDraftEnd ?? undefined;
     this.logger = options.logger ?? defaultPairingLogger;
+    this.deviceIdProvider = options.deviceIdProvider ?? getOrCreatePairingDeviceId;
   }
 
   getEngine(): PairingEngine | null {
@@ -96,6 +140,8 @@ export class PairingController {
   getState(): PairingEngineState {
     const blocked = this.blockedState();
     if (blocked) return blocked;
+    const held = this.heldState();
+    if (held) return held;
 
     return (
       this.engine?.getState() ?? {
@@ -106,6 +152,10 @@ export class PairingController {
         lastError: null,
         needsRescan: false,
         awaitingStartCondition: false,
+        canRestartPreview: false,
+        previewRestartGeneration: 0,
+        pairingSessionGeneration: 0,
+        previewStartGeneration: 0,
       }
     );
   }
@@ -127,6 +177,33 @@ export class PairingController {
       }`,
       needsRescan: true,
       awaitingStartCondition: false,
+      canRestartPreview: false,
+      previewRestartGeneration: 0,
+      pairingSessionGeneration: 0,
+      previewStartGeneration: 0,
+    };
+  }
+
+  /**
+   * A link or resumed token is waiting for init. Report connecting so the
+   * banner is visible during credential validation instead of looking idle.
+   */
+  private heldState(): PairingEngineState | null {
+    if (this.initPhase !== 'pending' || this.deferredPairingToken === null) return null;
+
+    return {
+      status: 'connecting',
+      pairingId: null,
+      deviceId: this.pairingDeviceId,
+      previewActive: true,
+      lastError: null,
+      needsRescan: false,
+      awaitingStartCondition: false,
+      canRestartPreview: false,
+      previewRestartGeneration: 0,
+      pairingSessionGeneration: 0,
+      previewStartGeneration: 0,
+      ...(this.deferredPurpose ? { pairingPurpose: this.deferredPurpose } : {}),
     };
   }
 
@@ -154,15 +231,6 @@ export class PairingController {
   }
 
   private async startListening(): Promise<void> {
-    // Exit pairing on app restart: drop any leftover secure token. Guarded so a
-    // storage failure cannot cost us the listeners registered below — losing
-    // those is what makes an inbound QR link vanish without explanation.
-    try {
-      await this.tokenStore.clear();
-    } catch (error) {
-      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
-    }
-
     this.ensureEngine();
 
     this.urlSub = this.LinkingModule.addEventListener('url', ({ url }) => {
@@ -186,6 +254,58 @@ export class PairingController {
     } catch {
       // Linking may throw on some platforms before the native module is ready.
     }
+
+    // A launch URL already claimed this process. Do not also resume storage.
+    if (this.acceptedPairingToken) return;
+    await this.resumeStoredToken();
+  }
+
+  /**
+   * Rejoin the Builder session after a relaunch when no new pairing link won.
+   * An expired or undecodable token is cleared so the next launch stays idle.
+   */
+  private async resumeStoredToken(): Promise<void> {
+    const epoch = this.launchEpoch;
+    let stored: string | null;
+    try {
+      stored = await this.tokenStore.get();
+    } catch (error) {
+      this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+      return;
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken || !stored) return;
+
+    const claims = decodePairingJwt(stored);
+    if (!claims || isPairingJwtExpired(claims)) {
+      // A link that arrived while we were reading storage owns the session.
+      if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+      try {
+        const current = await this.tokenStore.get();
+        if (epoch !== this.launchEpoch || this.acceptedPairingToken || current !== stored) return;
+        await this.tokenStore.clear();
+      } catch (error) {
+        this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+      }
+      return;
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+
+    let purpose: PairingPurpose | null = null;
+    try {
+      purpose = (await this.tokenStore.getPurpose?.()) ?? null;
+    } catch {
+      // Resume without it; the banner falls back to its default reveal.
+    }
+
+    if (epoch !== this.launchEpoch || this.acceptedPairingToken) return;
+
+    try {
+      await this.connectWhenReady(stored, 'resume', purpose);
+    } catch (error) {
+      this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+    }
   }
 
   stop(): void {
@@ -194,6 +314,7 @@ export class PairingController {
     this.appStateSub?.remove();
     this.appStateSub = null;
     this.started = false;
+    this.unbindRelay();
     void this.exitPreview();
   }
 
@@ -217,21 +338,42 @@ export class PairingController {
       return true;
     }
 
+    await this.connectWhenReady(
+      inspected.link.pairingToken,
+      'link',
+      inspected.link.purpose ?? null,
+    );
+    return true;
+  }
+
+  /**
+   * Connect now, or hold the token until init resolves or fails. Links and
+   * resumed sessions share this gate so both are deferred, replayed, and
+   * shown the same way.
+   */
+  private async connectWhenReady(
+    token: string,
+    source: 'link' | 'resume' = 'link',
+    purpose: PairingPurpose | null = null,
+  ): Promise<void> {
+    this.acceptedPairingToken = true;
+
     if (this.initPhase !== 'ready') {
       // Hold the token rather than discarding it. `notifyInitialized` replays it;
       // `notifyInitFailed` turns it into visible state.
-      this.deferredPairingToken = inspected.link.pairingToken;
-      this.warnOnce(
-        this.initPhase === 'failed'
-          ? pairingLinkInitFailedMessage(this.initFailureReason ?? 'unknown error')
-          : pairingLinkDeferredMessage(),
-      );
-      if (this.initPhase === 'failed') this.emit(this.getState());
-      return true;
+      this.deferredPairingToken = token;
+      this.deferredPurpose = purpose;
+      if (this.initPhase === 'failed') {
+        this.warnOnce(pairingLinkInitFailedMessage(this.initFailureReason ?? 'unknown error'));
+      } else if (source === 'link') {
+        // A resume waits on init on every relaunch; only a link needs this note.
+        this.warnOnce(pairingLinkDeferredMessage());
+      }
+      this.emit(this.getState());
+      return;
     }
 
-    await this.enterPreview(inspected.link.pairingToken);
-    return true;
+    await this.enterPreview(token, purpose);
   }
 
   /**
@@ -249,8 +391,9 @@ export class PairingController {
   }
 
   /**
-   * Called when `Userflow.init()` resolves. Connects a link that arrived while
-   * init was still in flight.
+   * Called when `Userflow.init()` resolves. Connects a link or resumed session
+   * that arrived while init was still in flight. `Userflow.init` does not await
+   * this — the pairing socket must not block identify.
    */
   async notifyInitialized(): Promise<void> {
     this.initPhase = 'ready';
@@ -258,14 +401,17 @@ export class PairingController {
 
     const deferred = this.deferredPairingToken;
     if (deferred === null) return;
+    const purpose = this.deferredPurpose;
     this.deferredPairingToken = null;
+    this.deferredPurpose = null;
 
     try {
-      await this.enterPreview(deferred);
+      await this.enterPreview(deferred, purpose);
     } catch (error) {
-      // Preview must not fail host init. `Userflow.init` awaits this, and
-      // PairingEngine.start rethrows on every connect failure, so letting this
-      // escape would let an expired QR token fail the host app's entire init.
+      // Preview must not fail host init. `Userflow.init` does not await this,
+      // and PairingEngine.start rethrows on every connect failure, so letting
+      // this escape would be an unhandled rejection — and, if it were awaited,
+      // an expired QR token would fail the host app's entire init.
       this.warnOnce(pairingConnectFailedMessage(describeError(error)));
     }
   }
@@ -295,21 +441,143 @@ export class PairingController {
   }
 
   /** Explicit entry with a raw pairing JWT (tests / advanced hosts). */
-  async enterPreview(pairingToken: string): Promise<void> {
+  async enterPreview(pairingToken: string, purpose: PairingPurpose | null = null): Promise<void> {
+    const epoch = this.launchEpoch;
+    const attempt = ++this.enterAttempt;
     const engine = this.ensureEngine();
-    await this.tokenStore.set(pairingToken);
-    await engine.start(pairingToken);
+    // Before the first await, so an exit that runs later still arms its own end.
+    if (epoch === this.launchEpoch) this.cancelPendingDraftEnd?.();
+
+    const deviceId = await this.resolveDeviceId();
+    if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) return;
+
+    this.pairingDeviceId = deviceId;
+    const saved = await this.savePreviewCredentials(pairingToken, purpose, attempt, epoch);
+    if (!saved) return;
+
+    try {
+      await (purpose ? engine.start(pairingToken, { purpose }) : engine.start(pairingToken));
+    } catch (error) {
+      // A newer pair owns the engine now. Stopping here would drop it.
+      if (attempt !== this.enterAttempt) return;
+      if (epoch !== this.launchEpoch) {
+        // start() records a connect failure after stop() has already gone idle.
+        await this.discardPreviewToken(pairingToken, attempt);
+        this.engine?.stop();
+        return;
+      }
+      throw error;
+    }
+
+    if (attempt !== this.enterAttempt) return;
+    if (epoch !== this.launchEpoch) {
+      await this.discardPreviewToken(pairingToken, attempt);
+      this.engine?.stop();
+    }
+  }
+
+  /**
+   * Write the token and its purpose as one attempt. Writes are queued so an
+   * older scan cannot finish its purpose after a newer scan has saved its own.
+   * Returns false when this attempt lost the race; storage then still belongs
+   * to whoever connected, or is cleared if this attempt was the last writer.
+   */
+  private async savePreviewCredentials(
+    pairingToken: string,
+    purpose: PairingPurpose | null,
+    attempt: number,
+    epoch: number,
+  ): Promise<boolean> {
+    const previous = this.previewSaveQueue;
+    let release: () => void = () => undefined;
+    this.previewSaveQueue = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    try {
+      await previous;
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) return false;
+
+      await this.tokenStore.set(pairingToken);
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) {
+        await this.revertPreviewCredentials(pairingToken);
+        return false;
+      }
+
+      await this.tokenStore.setPurpose?.(purpose);
+      if (attempt !== this.enterAttempt || epoch !== this.launchEpoch) {
+        await this.revertPreviewCredentials(pairingToken);
+        return false;
+      }
+      return true;
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Drop credentials this attempt wrote, when they are still the ones stored.
+   * A newer scan may already have replaced them; those stay.
+   */
+  private async revertPreviewCredentials(pairingToken: string): Promise<void> {
+    try {
+      const current = await this.tokenStore.get();
+      if (current !== pairingToken) return;
+      await this.tokenStore.clear();
+    } catch (error) {
+      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+    }
+  }
+
+  /**
+   * Remove the token this attempt wrote. A newer pair may already have
+   * replaced it; that token stays.
+   */
+  private async discardPreviewToken(pairingToken: string, attempt: number): Promise<void> {
+    if (attempt !== this.enterAttempt) return;
+    try {
+      const current = await this.tokenStore.get();
+      if (attempt !== this.enterAttempt || current !== pairingToken) return;
+      await this.tokenStore.clear();
+    } catch (error) {
+      this.warnOnce(pairingTokenStoreClearFailedMessage(describeError(error)));
+    }
+  }
+
+  private async resolveDeviceId(): Promise<string> {
+    if (this.pairingDeviceId !== null) return this.pairingDeviceId;
+    return this.deviceIdProvider();
   }
 
   async exitPreview(): Promise<void> {
     // Drop any held link too, so dismissing a blocked banner actually clears it.
+    // Bump before the awaits so a resume still reading storage does not reconnect.
+    this.launchEpoch += 1;
+    evalJsController.reset();
     this.deferredPairingToken = null;
+    this.deferredPurpose = null;
     await this.tokenStore.clear();
     this.engine?.stop();
+    // Not awaited: the local clear is synchronous, and the banner must not wait
+    // on the end-user socket.
+    void this.endDraftSession?.().catch((error: unknown) => {
+      this.warnOnce(pairingPreviewErrorMessage(describeError(error)));
+    });
     this.clearLocalSession?.();
     this.emit(this.getState());
   }
 
+  /**
+   * Replay the last previewed flow from step 1. No-ops when nothing has been
+   * delivered yet (restart control is hidden in that case).
+   */
+  async restartPreview(): Promise<boolean> {
+    if (!this.engine) return false;
+    clearFiberAnchorCache();
+    evalJsController.reset();
+    return this.engine.restartPreview();
+  }
+
   /** Flush queued startFlowWithToken after identify. */
   notifyIdentified(): void {
     this.engine?.notifyIdentified();
@@ -325,19 +593,34 @@ export class PairingController {
       pairingOptions: { pairingEndpoint: this.pairingEndpoint },
       deviceMeta: () => ({
         os: Platform.OS,
+        ...(this.pairingDeviceId !== null ? { device_id: this.pairingDeviceId } : {}),
       }),
+      onBeforePreviewStart: () => {
+        this.clearLocalSession?.();
+      },
     });
 
     this.engine.onStateChange((state) => {
       this.emit(state);
+      if (state.lastError) {
+        this.warnOnce(pairingPreviewErrorMessage(state.lastError));
+      }
       if (state.status === 'token_expired' || state.needsRescan) {
         void this.tokenStore.clear();
       }
     });
 
+    this.unbindRelay();
+    this.relayUnsub = bindElementPickerRelay(this.engine);
+
     return this.engine;
   }
 
+  private unbindRelay(): void {
+    this.relayUnsub?.();
+    this.relayUnsub = null;
+  }
+
   private emit(state: PairingEngineState): void {
     for (const listener of this.listeners) {
       try {