@userflow-tech/react-native 0.1.0

package/src/navigation/chainCallbacks.ts

@@ -0,0 +1,12 @@
+/** Runs two optional callbacks in sequence, forwarding the same arguments. */
+export function chainCallbacks<A extends unknown[]>(
+  first: ((...args: A) => void) | undefined,
+  second: ((...args: A) => void) | undefined,
+): ((...args: A) => void) | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  return (...args: A) => {
+    first(...args);
+    second(...args);
+  };
+}

package/src/navigation/getActiveRouteName.ts

@@ -0,0 +1,18 @@
+import type { NavigationState, PartialState } from '@react-navigation/native';
+
+type RoutableState = NavigationState | PartialState<NavigationState>;
+
+/** Returns the deepest active route name from a React Navigation state tree. */
+export function getActiveRouteName(state: RoutableState | undefined): string | undefined {
+  if (!state) return undefined;
+
+  const index = state.index ?? 0;
+  const route = state.routes[index];
+  if (!route) return undefined;
+
+  if (route.state) {
+    return getActiveRouteName(route.state);
+  }
+
+  return route.name;
+}

package/src/navigation/index.ts

@@ -0,0 +1,11 @@
+export { WithUserflowReactNavigation } from './WithUserflowReactNavigation';
+export type { WithUserflowReactNavigationProps } from './WithUserflowReactNavigation';
+export {
+  openFlowNavigateUrl,
+  setHostOnNavigate,
+  setReactNavigationRef,
+  setExpoRouterNavigator,
+  isExternalNavigateUrl,
+  isInAppNavigateUrl,
+} from './openFlowNavigateUrl';
+export type { FlowNavigateHandler, ExpoRouterLike } from './openFlowNavigateUrl';

package/src/navigation/openFlowNavigateUrl.ts

@@ -0,0 +1,113 @@
+import type { NavigationContainerRef, ParamListBase } from '@react-navigation/native';
+import { Linking } from 'react-native';
+
+import { isSafeUrl, openSafeUrl } from '../content/openSafeUrl';
+
+export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
+
+export type ExpoRouterLike = {
+  push: (href: string) => void;
+};
+
+let hostOnNavigate: FlowNavigateHandler | null = null;
+let navigationRef: NavigationContainerRef<ParamListBase> | null = null;
+let expoRouter: ExpoRouterLike | null = null;
+
+/** Optional host escape hatch — wins over router / Linking when set. */
+export function setHostOnNavigate(handler: FlowNavigateHandler | null | undefined): void {
+  hostOnNavigate = handler ?? null;
+}
+
+/** Register the React Navigation container used by {@link WithUserflowReactNavigation}. */
+export function setReactNavigationRef(
+  ref: NavigationContainerRef<ParamListBase> | null | undefined,
+): void {
+  navigationRef = ref ?? null;
+}
+
+/** Register Expo Router push for path-like NAVIGATE actions. */
+export function setExpoRouterNavigator(router: ExpoRouterLike | null | undefined): void {
+  expoRouter = router ?? null;
+}
+
+/** True for http(s) / mailto / tel (external). */
+export function isExternalNavigateUrl(url: string): boolean {
+  return isSafeUrl(url);
+}
+
+/** Path-like in-app URL: leading slash, or no scheme. */
+export function isInAppNavigateUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  if (isExternalNavigateUrl(trimmed)) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
+  return true;
+}
+
+function normalizeInAppPath(url: string): string {
+  const trimmed = url.trim();
+  if (trimmed.startsWith('/')) return trimmed;
+  return `/${trimmed}`;
+}
+
+function routeNameFromPath(path: string): string {
+  const normalized = normalizeInAppPath(path).replace(/^\//, '');
+  const [first] = normalized.split(/[/?#]/);
+  return first || normalized;
+}
+
+/**
+ * Open a flow NAVIGATE url.
+ *
+ * Priority:
+ * 1. Host `onNavigate` (custom schemes / exotic routing)
+ * 2. External allowlisted schemes → Linking / `openSafeUrl`
+ * 3. Path-like → Expo Router `push` or React Navigation `navigate`
+ * 4. Fallback → Linking (best-effort)
+ *
+ * Note: screen tracking ≠ action routing. React Navigation hosts must wrap with
+ * `WithUserflowReactNavigation` for in-app NAVIGATE; Expo Router apps get a
+ * navigator handle when the host mounts `UserflowExpoRouterScreenTracker` from
+ * `@userflow-tech/react-native/expo-router` under `UserflowProvider`.
+ */
+export async function openFlowNavigateUrl(url: string): Promise<void> {
+  const trimmed = url.trim();
+  if (!trimmed) return;
+
+  if (hostOnNavigate) {
+    await hostOnNavigate(trimmed);
+    return;
+  }
+
+  if (isExternalNavigateUrl(trimmed)) {
+    await openSafeUrl(trimmed);
+    return;
+  }
+
+  if (isInAppNavigateUrl(trimmed)) {
+    if (expoRouter) {
+      expoRouter.push(normalizeInAppPath(trimmed));
+      return;
+    }
+    if (navigationRef?.isReady()) {
+      const name = routeNameFromPath(trimmed);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
+      (navigationRef as NavigationContainerRef<ParamListBase>).navigate(name as any);
+      return;
+    }
+  }
+
+  // Last resort — may fail for custom schemes; hosts should set onNavigate.
+  try {
+    await Linking.openURL(trimmed);
+  } catch {
+    // Best-effort.
+  }
+}
+
+/** @internal */
+export function resetFlowNavigateRegistryForTests(): void {
+  hostOnNavigate = null;
+  navigationRef = null;
+  expoRouter = null;
+}

package/src/network.ts

@@ -0,0 +1,113 @@
+/**
+ * Network reachability → eager liveness check (optional enhancement).
+ *
+ * When connectivity returns while the app is foregrounded (and the transport is
+ * not suspended), call {@link NetworkControllerDeps.ensureAlive} so we do not
+ * wait for the adaptive heartbeat / foreground probe to notice the drop.
+ * `ensureAlive` probes a still-open (possibly half-dead) socket and reconnects
+ * eagerly when the transport is already dropped — covering both cases.
+ *
+ * This is layered on top of a complete zero-dependency recovery path (socket
+ * close → reconnect ladder, adaptive heartbeat, and the foreground liveness
+ * probe). `@react-native-community/netinfo` is therefore an *optional* peer: when
+ * present it makes offline→online recovery fast; when absent the baseline still
+ * recovers within a few seconds of the next beat / foreground return.
+ */
+
+export interface NetworkStatus {
+  isConnected: boolean | null;
+  /** `null` means unknown — treat as reachable when connected. */
+  isInternetReachable: boolean | null;
+}
+
+export interface NetworkControllerDeps {
+  ensureAlive: () => void;
+  /** Override for tests; defaults to `@react-native-community/netinfo`. */
+  subscribe?: (handler: (status: NetworkStatus) => void) => () => void;
+}
+
+function isOnline(status: NetworkStatus): boolean {
+  return status.isConnected === true && status.isInternetReachable !== false;
+}
+
+function defaultSubscribe(handler: (status: NetworkStatus) => void): () => void {
+  // Lazy require so the SDK works without the optional peer. When installed,
+  // NetInfo makes offline→online reconnect fast; when absent the transport's
+  // adaptive heartbeat + foreground probe still recover the connection.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
+    const NetInfo = require('@react-native-community/netinfo') as {
+      addEventListener: (
+        listener: (state: {
+          isConnected: boolean | null;
+          isInternetReachable: boolean | null;
+        }) => void,
+      ) => () => void;
+    };
+    return NetInfo.addEventListener((state) => {
+      handler({
+        isConnected: state.isConnected,
+        isInternetReachable: state.isInternetReachable,
+      });
+    });
+  } catch {
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+      console.warn(
+        '[Userflow] Optional peer @react-native-community/netinfo is not installed; ' +
+          'skipping instant network-aware reconnect. Connection recovery still works ' +
+          'via the adaptive heartbeat and foreground liveness probe.',
+      );
+    }
+    return () => {};
+  }
+}
+
+/**
+ * Owns the NetInfo subscription. Call {@link start} from `Userflow.init` and
+ * {@link stop} from `Userflow.teardown`.
+ */
+export class NetworkController {
+  private readonly ensureAlive: () => void;
+  private readonly subscribe: (handler: (status: NetworkStatus) => void) => () => void;
+
+  private unsubscribe: (() => void) | null = null;
+  private started = false;
+  private wasOnline: boolean | null = null;
+
+  constructor(deps: NetworkControllerDeps) {
+    this.ensureAlive = deps.ensureAlive;
+    this.subscribe = deps.subscribe ?? defaultSubscribe;
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.unsubscribe = this.subscribe((status) => {
+      this.handleStatus(status);
+    });
+  }
+
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.wasOnline = null;
+  }
+
+  /** Visible for tests. */
+  handleStatus(status: NetworkStatus): void {
+    if (!this.started) return;
+
+    const online = isOnline(status);
+    const previous = this.wasOnline;
+    this.wasOnline = online;
+
+    // First sample only seeds state — do not reconnect on start.
+    if (previous === null) return;
+    if (!previous && online) {
+      this.ensureAlive();
+    }
+  }
+}

package/src/pairing/PairingController.ts

@@ -0,0 +1,356 @@
+import {
+  DEFAULT_PAIRING_ENDPOINT,
+  PairingEngine,
+  type PairingEngineState,
+  type UserflowCore,
+} from '@userflow-tech/core';
+import { AppState, type AppStateStatus, Linking, Platform } from 'react-native';
+
+import { inspectPairingDeepLink, isPairingAttempt } from './deepLink';
+import {
+  defaultPairingLogger,
+  pairingAttemptRejectionMessage,
+  pairingConnectFailedMessage,
+  pairingLinkDeferredMessage,
+  pairingLinkInitFailedMessage,
+  pairingListenerSetupFailedMessage,
+  pairingTokenStoreClearFailedMessage,
+  type PairingLogger,
+} from './diagnostics';
+import { createPairingTokenStore, type PairingTokenStore } from './tokenStorage';
+
+export type PairingControllerListener = (state: PairingEngineState) => void;
+
+/**
+ * Readiness of the end-user session that a preview attaches to.
+ *
+ * Pairing listens independently of `Userflow.init()` so a QR link is never
+ * lost, but it can only connect once init has resolved. `Userflow.init` drives
+ * this via `notifyInitStarted` / `notifyInitialized` / `notifyInitFailed`;
+ * a controller nobody reports init progress for stays usable (`ready`).
+ */
+type InitPhase = 'pending' | 'ready' | 'failed';
+
+export interface PairingControllerOptions {
+  core: UserflowCore;
+  /** Override pairing host (local/staging). Defaults to US-pinned production. */
+  pairingEndpoint?: string;
+  tokenStore?: PairingTokenStore;
+  /** Clear mid-flow session when exiting preview. */
+  clearLocalSession?: () => void;
+  LinkingModule?: {
+    getInitialURL(): Promise<string | null>;
+    addEventListener(type: 'url', handler: (event: { url: string }) => void): { remove(): void };
+  };
+  AppStateModule?: {
+    addEventListener(type: 'change', handler: (state: AppStateStatus) => void): { remove(): void };
+  };
+  /** Sink for pairing diagnostics. Injected in tests. */
+  logger?: PairingLogger;
+}
+
+/**
+ * Inbound deep links → pairing session → preview mode.
+ * Active in all builds (including release); security is the short-lived
+ * signed pairing JWT + Builder ability checks, not `__DEV__`.
+ */
+export class PairingController {
+  private engine: PairingEngine | null = null;
+  private started = false;
+  private urlSub: { remove(): void } | null = null;
+  private appStateSub: { remove(): void } | null = null;
+  private readonly listeners = new Set<PairingControllerListener>();
+  private readonly tokenStore: PairingTokenStore;
+  private readonly LinkingModule: NonNullable<PairingControllerOptions['LinkingModule']>;
+  private readonly AppStateModule: NonNullable<PairingControllerOptions['AppStateModule']>;
+  private readonly clearLocalSession: (() => void) | undefined;
+  private readonly core: UserflowCore;
+  private readonly pairingEndpoint: string;
+  private readonly logger: PairingLogger;
+  private initPhase: InitPhase = 'ready';
+  private initFailureReason: string | null = null;
+  /** Pairing token captured before init resolved, replayed once it does. */
+  private deferredPairingToken: string | null = null;
+  /** Diagnostics already emitted for the current init attempt. */
+  private readonly loggedOnce = new Set<string>();
+
+  constructor(options: PairingControllerOptions) {
+    this.core = options.core;
+    this.pairingEndpoint = options.pairingEndpoint ?? DEFAULT_PAIRING_ENDPOINT;
+    this.tokenStore = options.tokenStore ?? createPairingTokenStore();
+    this.LinkingModule = options.LinkingModule ?? Linking;
+    this.AppStateModule = options.AppStateModule ?? AppState;
+    this.clearLocalSession = options.clearLocalSession ?? undefined;
+    this.logger = options.logger ?? defaultPairingLogger;
+  }
+
+  getEngine(): PairingEngine | null {
+    return this.engine;
+  }
+
+  /** Whether deep-link / AppState listeners have been started. */
+  hasStarted(): boolean {
+    return this.started;
+  }
+
+  getState(): PairingEngineState {
+    const blocked = this.blockedState();
+    if (blocked) return blocked;
+
+    return (
+      this.engine?.getState() ?? {
+        status: 'idle',
+        pairingId: null,
+        deviceId: null,
+        previewActive: false,
+        lastError: null,
+        needsRescan: false,
+        awaitingStartCondition: false,
+      }
+    );
+  }
+
+  /**
+   * State for a link we captured but cannot act on because init failed. Without
+   * this the host app shows no sign that a pairing link was ever received.
+   */
+  private blockedState(): PairingEngineState | null {
+    if (this.initPhase !== 'failed' || this.deferredPairingToken === null) return null;
+
+    return {
+      status: 'error',
+      pairingId: null,
+      deviceId: null,
+      previewActive: false,
+      lastError: `Userflow.init() failed, so preview could not start: ${
+        this.initFailureReason ?? 'unknown error'
+      }`,
+      needsRescan: true,
+      awaitingStartCondition: false,
+    };
+  }
+
+  onStateChange(listener: PairingControllerListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Start deep-link listeners. Safe to call multiple times, and never rejects —
+   * `Userflow.init` fires it without awaiting, so a rejection here would become
+   * an unhandled promise rejection.
+   */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+
+    try {
+      await this.startListening();
+    } catch (error) {
+      this.warnOnce(pairingListenerSetupFailedMessage(describeError(error)));
+    }
+  }
+
+  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 }) => {
+      // handleUrl still rejects for explicit callers (Userflow.handlePairingUrl);
+      // the auto-listener has nowhere to report, so log instead of leaving an
+      // unhandled rejection.
+      void this.handleUrl(url).catch((error: unknown) => {
+        this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+      });
+    });
+
+    this.appStateSub = this.AppStateModule.addEventListener('change', (next) => {
+      if (next === 'active') {
+        this.engine?.ensureAlive();
+      }
+    });
+
+    try {
+      const initial = await this.LinkingModule.getInitialURL();
+      if (initial) await this.handleUrl(initial);
+    } catch {
+      // Linking may throw on some platforms before the native module is ready.
+    }
+  }
+
+  stop(): void {
+    this.urlSub?.remove();
+    this.urlSub = null;
+    this.appStateSub?.remove();
+    this.appStateSub = null;
+    this.started = false;
+    void this.exitPreview();
+  }
+
+  /**
+   * Host apps that intercept deep links themselves can forward them here.
+   */
+  async handleUrl(url: string): Promise<boolean> {
+    const inspected = inspectPairingDeepLink(url);
+
+    if (!inspected.ok) {
+      // Links that are not recognisably ours belong to the host app. Stay silent
+      // so ordinary deep links — and preview links, which accept any
+      // `userflow-*` scheme — are never reported as pairing misconfiguration.
+      if (!isPairingAttempt(inspected.reason)) return false;
+
+      // A deliberate pairing attempt we cannot use. The OS already launched the
+      // app, so a silent return is indistinguishable from a broken deep link.
+      // Still return true — the URL was recognised as pairing, so the host
+      // should stop routing it (see docs/deep-linking.md).
+      this.warnOnce(pairingAttemptRejectionMessage(inspected.reason, url));
+      return 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;
+    }
+
+    await this.enterPreview(inspected.link.pairingToken);
+    return true;
+  }
+
+  /**
+   * Called when `Userflow.init()` begins. Clears a previous failure so a retried
+   * init does not keep reporting the old error.
+   */
+  notifyInitStarted(): void {
+    // A retry is a fresh attempt: allow its diagnostics through again, and drop
+    // a "Preview unavailable" banner that no longer reflects reality.
+    const wasBlocked = this.blockedState() !== null;
+    this.initPhase = 'pending';
+    this.initFailureReason = null;
+    this.loggedOnce.clear();
+    if (wasBlocked) this.emit(this.getState());
+  }
+
+  /**
+   * Called when `Userflow.init()` resolves. Connects a link that arrived while
+   * init was still in flight.
+   */
+  async notifyInitialized(): Promise<void> {
+    this.initPhase = 'ready';
+    this.initFailureReason = null;
+
+    const deferred = this.deferredPairingToken;
+    if (deferred === null) return;
+    this.deferredPairingToken = null;
+
+    try {
+      await this.enterPreview(deferred);
+    } 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.
+      this.warnOnce(pairingConnectFailedMessage(describeError(error)));
+    }
+  }
+
+  /**
+   * Called when `Userflow.init()` rejects. Pairing cannot connect without a
+   * session, so surface why instead of failing silently.
+   */
+  notifyInitFailed(error: unknown): void {
+    this.initPhase = 'failed';
+    this.initFailureReason = describeError(error);
+
+    if (this.deferredPairingToken !== null) {
+      this.warnOnce(pairingLinkInitFailedMessage(this.initFailureReason));
+      this.emit(this.getState());
+    }
+  }
+
+  /**
+   * Log `message` at most once per init attempt. Inbound links can repeat (URL
+   * event plus host forwarding), and these messages are several lines long.
+   */
+  private warnOnce(message: string): void {
+    if (this.loggedOnce.has(message)) return;
+    this.loggedOnce.add(message);
+    this.logger(message);
+  }
+
+  /** Explicit entry with a raw pairing JWT (tests / advanced hosts). */
+  async enterPreview(pairingToken: string): Promise<void> {
+    const engine = this.ensureEngine();
+    await this.tokenStore.set(pairingToken);
+    await engine.start(pairingToken);
+  }
+
+  async exitPreview(): Promise<void> {
+    // Drop any held link too, so dismissing a blocked banner actually clears it.
+    this.deferredPairingToken = null;
+    await this.tokenStore.clear();
+    this.engine?.stop();
+    this.clearLocalSession?.();
+    this.emit(this.getState());
+  }
+
+  /** Flush queued startFlowWithToken after identify. */
+  notifyIdentified(): void {
+    this.engine?.notifyIdentified();
+  }
+
+  private ensureEngine(): PairingEngine {
+    if (this.engine) return this.engine;
+
+    this.engine = new PairingEngine({
+      sendClientMessage: (message) => this.core.send(message),
+      onServerMessage: (handler) => this.core.onServerMessage(handler),
+      isIdentified: () => this.core.getUserId() != null,
+      pairingOptions: { pairingEndpoint: this.pairingEndpoint },
+      deviceMeta: () => ({
+        os: Platform.OS,
+      }),
+    });
+
+    this.engine.onStateChange((state) => {
+      this.emit(state);
+      if (state.status === 'token_expired' || state.needsRescan) {
+        void this.tokenStore.clear();
+      }
+    });
+
+    return this.engine;
+  }
+
+  private emit(state: PairingEngineState): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return String(error);
+}