@userflow-tech/react-native 0.1.0

package/src/pairing/PreviewModeBanner.tsx

@@ -0,0 +1,130 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+import * as React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+export interface PreviewModeBannerProps {
+  state: PairingEngineState;
+  onExit: () => void;
+}
+
+/**
+ * Overlay chrome for Builder pairing preview mode.
+ */
+export function PreviewModeBanner({
+  state,
+  onExit,
+}: PreviewModeBannerProps): React.ReactElement | null {
+  if (!state.previewActive && state.status === 'idle') return null;
+  if (
+    !state.previewActive &&
+    state.status !== 'token_expired' &&
+    state.status !== 'device_already_paired' &&
+    state.status !== 'error'
+  ) {
+    return null;
+  }
+
+  const needsRescan = state.needsRescan;
+  // No pairing id means the session never started (e.g. init failed), so
+  // "Pairing ended" would misdescribe it.
+  const neverPaired = state.status === 'error' && !state.previewActive && state.pairingId === null;
+  const title = neverPaired
+    ? 'Preview unavailable'
+    : needsRescan
+      ? 'Pairing ended'
+      : 'Preview mode';
+  const detail =
+    state.lastError ??
+    (state.status === 'reconnecting'
+      ? 'Reconnecting…'
+      : state.status === 'connecting'
+        ? 'Connecting to Builder…'
+        : // Mirrors the Builder's own wording. Without this the banner reads
+          // "Paired" while the flow is absent, which looks like a broken preview
+          // rather than a condition that has not matched yet.
+          state.awaitingStartCondition
+          ? 'Waiting for auto-start condition to trigger…'
+          : 'Paired with Userflow Builder');
+
+  return (
+    <View style={styles.wrap} pointerEvents="box-none">
+      <View style={[styles.banner, needsRescan ? styles.bannerWarn : styles.bannerActive]}>
+        <View style={styles.textCol}>
+          <Text style={styles.title}>{title}</Text>
+          <Text style={styles.detail} numberOfLines={2}>
+            {needsRescan ? `${detail} Re-scan the QR code to continue.` : detail}
+          </Text>
+        </View>
+        {!needsRescan ? (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Exit preview"
+            onPress={onExit}
+            style={styles.button}
+          >
+            <Text style={styles.buttonLabel}>Exit preview</Text>
+          </Pressable>
+        ) : (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Dismiss pairing message"
+            onPress={onExit}
+            style={styles.button}
+          >
+            <Text style={styles.buttonLabel}>Dismiss</Text>
+          </Pressable>
+        )}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 1000,
+  },
+  banner: {
+    marginTop: 48,
+    marginHorizontal: 12,
+    borderRadius: 10,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 10,
+  },
+  bannerActive: {
+    backgroundColor: 'rgba(17, 24, 39, 0.92)',
+  },
+  bannerWarn: {
+    backgroundColor: 'rgba(127, 29, 29, 0.94)',
+  },
+  textCol: {
+    flex: 1,
+  },
+  title: {
+    color: '#ffffff',
+    fontSize: 13,
+    fontWeight: '700',
+  },
+  detail: {
+    color: 'rgba(255,255,255,0.85)',
+    fontSize: 12,
+    marginTop: 2,
+  },
+  button: {
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    borderRadius: 8,
+    backgroundColor: 'rgba(255,255,255,0.14)',
+  },
+  buttonLabel: {
+    color: '#ffffff',
+    fontSize: 12,
+    fontWeight: '600',
+  },
+});

package/src/pairing/deepLink.ts

@@ -0,0 +1,128 @@
+/**
+ * Parse Builder pairing deep links:
+ *   {scheme_id}://?pairing_token=<jwt>
+ *
+ * `scheme_id` is typically `userflow-<digits>`.
+ */
+
+export interface PairingDeepLink {
+  scheme: string;
+  pairingToken: string;
+}
+
+/** Scheme prefix shared by preview and pairing links. */
+const USERFLOW_SCHEME_PREFIX = 'userflow-';
+const USERFLOW_SCHEME = /^userflow-\d+$/i;
+
+/**
+ * Why a URL was not treated as a pairing link.
+ *
+ * `bad-scheme-shape` and `missing-token` are only reported for URLs that
+ * actually target pairing (root with a `pairing_token` query), so callers can
+ * tell a misconfigured pairing attempt apart from an unrelated link. See
+ * {@link isPairingAttempt}.
+ */
+export type PairingDeepLinkRejection =
+  | 'not-userflow'
+  | 'foreign-scheme'
+  | 'bad-scheme-shape'
+  | 'unparseable'
+  | 'not-pair-path'
+  | 'missing-token';
+
+/**
+ * Rejections where the URL was a recognisable pairing attempt that could not be
+ * used. These are worth reporting; everything else belongs to the host app.
+ */
+export type PairingAttemptRejection = 'foreign-scheme' | 'bad-scheme-shape' | 'missing-token';
+
+export type PairingDeepLinkResult =
+  | { ok: true; link: PairingDeepLink }
+  | { ok: false; reason: PairingDeepLinkRejection };
+
+/**
+ * True when a rejected URL was nonetheless a recognisable pairing attempt rather
+ * than someone else's deep link.
+ *
+ * Callers use this to decide whether a rejection is worth reporting. Preview
+ * links accept any `userflow-*` scheme, so scheme shape alone cannot be the
+ * signal — reporting on it would flag valid preview links as broken pairing.
+ */
+export function isPairingAttempt(
+  reason: PairingDeepLinkRejection,
+): reason is PairingAttemptRejection {
+  return reason === 'foreign-scheme' || reason === 'bad-scheme-shape' || reason === 'missing-token';
+}
+
+/**
+ * Parse `url` as a pairing deep link, reporting why it was rejected.
+ * Prefer this over {@link parsePairingDeepLink} when the reason matters.
+ */
+export function inspectPairingDeepLink(url: string | null | undefined): PairingDeepLinkResult {
+  if (typeof url !== 'string' || url.length === 0) {
+    return { ok: false, reason: 'not-userflow' };
+  }
+
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(url);
+  if (!schemeMatch?.[1]) return { ok: false, reason: 'not-userflow' };
+  const scheme = schemeMatch[1];
+  const isUserflowScheme = scheme.toLowerCase().startsWith(USERFLOW_SCHEME_PREFIX);
+
+  // Parse before judging the scheme: a pairing link opened with the host app's
+  // own scheme still needs to be recognisable so it can be reported.
+  //
+  // Custom schemes are not valid WHATWG URLs on their own. Strip the scheme
+  // and re-parse as https. Root forms (`://?…`, `://`) use a placeholder base
+  // so the query survives — a bare `https://?…` is an invalid URL.
+  const remainder = url.slice(scheme.length + 1).replace(/^\/\//, '');
+  let parsed: URL;
+  try {
+    if (remainder === '' || remainder.startsWith('?') || remainder.startsWith('/')) {
+      parsed = new URL(remainder === '' ? '/' : remainder, 'https://userflow.local');
+    } else {
+      parsed = new URL(`https://${remainder}`);
+    }
+  } catch {
+    return { ok: false, reason: isUserflowScheme ? 'unparseable' : 'not-userflow' };
+  }
+
+  const pairingToken = parsed.searchParams.get('pairing_token');
+  const hasPairingTokenParam = parsed.searchParams.has('pairing_token');
+  const isRoot =
+    (parsed.hostname === '' || parsed.hostname === 'userflow.local') &&
+    (parsed.pathname === '' || parsed.pathname === '/');
+  // Only the root query form is pairing. A host `/pair` route (or any other
+  // path) is left alone even when it carries `pairing_token`.
+  const isPair = isRoot && hasPairingTokenParam;
+
+  if (!isUserflowScheme) {
+    // Claim a scheme we do not own only when the URL is unmistakably ours: root
+    // form *and* our query parameter. That combination means someone swapped
+    // the environment's scheme_id for the app's own scheme.
+    return isPair ? { ok: false, reason: 'foreign-scheme' } : { ok: false, reason: 'not-userflow' };
+  }
+
+  if (!isPair) return { ok: false, reason: 'not-pair-path' };
+
+  // Only once the URL is known to target pairing does the scheme shape matter.
+  // Checking it earlier would misreport preview links on non-numeric schemes.
+  if (!USERFLOW_SCHEME.test(scheme)) return { ok: false, reason: 'bad-scheme-shape' };
+
+  if (!pairingToken) return { ok: false, reason: 'missing-token' };
+
+  return { ok: true, link: { scheme, pairingToken } };
+}
+
+/**
+ * Returns pairing token details when `url` is a Userflow pairing deep link.
+ * Accepts only `userflow-*` schemes.
+ */
+export function parsePairingDeepLink(url: string | null | undefined): PairingDeepLink | null {
+  const result = inspectPairingDeepLink(url);
+  return result.ok ? result.link : null;
+}
+
+/** True when the URL looks like a Userflow pairing deep link. */
+export function isUserflowPairingUrl(url: string | null | undefined): boolean {
+  return parsePairingDeepLink(url) != null;
+}

package/src/pairing/diagnostics.ts

@@ -0,0 +1,135 @@
+/**
+ * Diagnostics for Builder pairing deep links.
+ *
+ * Pairing failures are unusually easy to miss. The URL scheme is registered in
+ * the native project at build time, so the OS launches the host app from a
+ * Builder QR code whether or not the SDK is listening. When the SDK then drops
+ * the link, the app looks like it simply "opened and did nothing".
+ *
+ * Every drop path routes through a message below so the reason is visible.
+ */
+
+import type { PairingAttemptRejection } from './deepLink';
+
+const PREFIX = '[Userflow]';
+
+/**
+ * Hide the pairing token before a URL reaches the console. It is a bearer
+ * credential for the pairing session, and these messages are printed verbatim.
+ */
+function redactPairingToken(url: string): string {
+  return url.replace(/(pairing_token=)[^&]+/i, '$1<redacted>');
+}
+
+/** Sink for pairing diagnostics. Injected in tests. */
+export type PairingLogger = (message: string) => void;
+
+/**
+ * Default logger. Pairing links only ever arrive from a deliberate developer
+ * action (scanning or opening a Builder QR code), so these warn unconditionally
+ * rather than behind `__DEV__` — a swallowed pairing link is otherwise
+ * undiagnosable, and this cannot fire for real end users.
+ */
+export const defaultPairingLogger: PairingLogger = (message) => {
+  // eslint-disable-next-line no-console -- intentional pairing diagnostic
+  console.warn(message);
+};
+
+/** A pairing link arrived while `Userflow.init()` was still in flight. */
+export function pairingLinkDeferredMessage(): string {
+  return (
+    `${PREFIX} Builder pairing link received before Userflow.init() finished. ` +
+    `Holding it and will connect as soon as init resolves.`
+  );
+}
+
+/**
+ * A pairing link arrived but `Userflow.init()` rejected, so there is no session
+ * to attach the preview to.
+ */
+export function pairingLinkInitFailedMessage(reason: string): string {
+  return (
+    `${PREFIX} Builder pairing link received, but Userflow.init() failed so pairing ` +
+    `cannot start: ${reason}. Fix the init error — most often an invalid clientToken ` +
+    `or an unreachable serverEndpoint — then re-open the pairing link.`
+  );
+}
+
+/**
+ * Pairing was reachable but the connection itself failed (expired token, device
+ * already paired, backend unreachable). Never fatal to the host app.
+ */
+export function pairingConnectFailedMessage(reason: string): string {
+  return (
+    `${PREFIX} Builder pairing could not connect: ${reason}. The app is unaffected — ` +
+    `re-open the pairing link from the Builder to try again.`
+  );
+}
+
+/** A pairing link arrived without the `pairing_token` query parameter. */
+export function pairingMissingTokenMessage(url: string): string {
+  return (
+    `${PREFIX} Ignoring Builder pairing link "${redactPairingToken(url)}": no ` +
+    `"pairing_token" query parameter. Open the link straight from the Builder QR ` +
+    `code rather than reconstructing it by hand.`
+  );
+}
+
+/**
+ * A pairing link arrived on a scheme Userflow does not own — almost always the
+ * host app's own scheme substituted for the environment's `scheme_id`.
+ */
+export function pairingForeignSchemeMessage(url: string): string {
+  return (
+    `${PREFIX} Ignoring "${redactPairingToken(url)}": this is a Builder pairing ` +
+    `link, but it was opened with a scheme Userflow does not own. Use your ` +
+    `environment's scheme_id ("userflow-" followed by digits) exactly as the ` +
+    `pairing QR code provides it — do not substitute your app's own scheme. ` +
+    `Register it via the @userflow-tech/expo plugin ({ schemeId: 'userflow-…' }) and ` +
+    `rebuild the native app; a Metro reload is not enough.`
+  );
+}
+
+/** Message for a pairing attempt that could not be used. */
+export function pairingAttemptRejectionMessage(
+  reason: PairingAttemptRejection,
+  url: string,
+): string {
+  switch (reason) {
+    case 'foreign-scheme':
+      return pairingForeignSchemeMessage(url);
+    case 'bad-scheme-shape':
+      return pairingSchemeShapeMessage(url);
+    case 'missing-token':
+      return pairingMissingTokenMessage(url);
+  }
+}
+
+/** Clearing the persisted pairing token failed. Best-effort, never fatal. */
+export function pairingTokenStoreClearFailedMessage(reason: string): string {
+  return (
+    `${PREFIX} Could not clear the stored pairing token: ${reason}. Continuing — ` +
+    `a stale preview may survive an app restart until you exit preview manually.`
+  );
+}
+
+/** Attaching the deep-link listeners failed, which disables pairing entirely. */
+export function pairingListenerSetupFailedMessage(reason: string): string {
+  return (
+    `${PREFIX} Could not start Builder pairing listeners: ${reason}. Pairing deep ` +
+    `links will be ignored for this session; the rest of the SDK is unaffected.`
+  );
+}
+
+/**
+ * The URL used a `userflow-` scheme that is not a valid `scheme_id`. Pairing
+ * requires `userflow-` followed by digits, so an arbitrary `userflow-*` scheme
+ * can match preview links but not pairing ones.
+ */
+export function pairingSchemeShapeMessage(url: string): string {
+  return (
+    `${PREFIX} Ignoring Builder pairing link "${redactPairingToken(url)}": the scheme must be your ` +
+    `environment's scheme_id — "userflow-" followed by digits (e.g. userflow-257587). ` +
+    `Check the schemeId passed to the @userflow-tech/expo plugin.`
+  );
+}

package/src/pairing/index.ts

@@ -0,0 +1,19 @@
+export {
+  inspectPairingDeepLink,
+  isPairingAttempt,
+  parsePairingDeepLink,
+  isUserflowPairingUrl,
+} from './deepLink';
+export type {
+  PairingAttemptRejection,
+  PairingDeepLink,
+  PairingDeepLinkRejection,
+  PairingDeepLinkResult,
+} from './deepLink';
+export type { PairingLogger } from './diagnostics';
+export { PairingController } from './PairingController';
+export type { PairingControllerOptions, PairingControllerListener } from './PairingController';
+export { PreviewModeBanner } from './PreviewModeBanner';
+export type { PreviewModeBannerProps } from './PreviewModeBanner';
+export { createMemoryPairingTokenStore, createPairingTokenStore } from './tokenStorage';
+export type { PairingTokenStore } from './tokenStorage';

package/src/pairing/pairingRuntime.ts

@@ -0,0 +1,76 @@
+import type { UserflowCore } from '@userflow-tech/core';
+
+import { PairingController, type PairingControllerOptions } from './PairingController';
+
+let controller: PairingController | null = null;
+const installListeners = new Set<(controller: PairingController) => void>();
+
+/** Return the singleton if it already exists — never creates one. */
+export function peekPairingController(): PairingController | null {
+  return controller;
+}
+
+export function getPairingController(core: UserflowCore): PairingController {
+  if (!controller) {
+    controller = new PairingController({ core });
+    notifyInstall(controller);
+  }
+  return controller;
+}
+
+/**
+ * Ensure the singleton exists with init-time options. Idempotent once the
+ * controller has started listening — subsequent {@link Userflow.init} calls
+ * reuse it so AppState/Linking listeners are not stacked.
+ *
+ * If a bare controller was created early (e.g. a hook peek race that used
+ * {@link getPairingController}) but has not started yet, it is replaced so
+ * init-time options such as `pairingEndpoint` / `clearLocalSession` apply.
+ */
+export function installPairingController(
+  core: UserflowCore,
+  options?: Omit<PairingControllerOptions, 'core'>,
+): PairingController {
+  if (!controller) {
+    controller = new PairingController({ core, ...options });
+    notifyInstall(controller);
+    return controller;
+  }
+
+  if (!controller.hasStarted()) {
+    controller.stop();
+    controller = new PairingController({ core, ...options });
+    notifyInstall(controller);
+  }
+
+  return controller;
+}
+
+/**
+ * Subscribe to singleton install/replace. Immediately invokes `listener` when
+ * a controller already exists. Used by hooks that must not create the
+ * singleton before {@link Userflow.init}.
+ */
+export function onPairingController(listener: (controller: PairingController) => void): () => void {
+  if (controller) listener(controller);
+  installListeners.add(listener);
+  return () => {
+    installListeners.delete(listener);
+  };
+}
+
+function notifyInstall(next: PairingController): void {
+  for (const listener of installListeners) {
+    try {
+      listener(next);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/** Test helper: drop the singleton. */
+export function __resetPairingControllerForTests(): void {
+  controller?.stop();
+  controller = null;
+}

package/src/pairing/tokenStorage.ts

@@ -0,0 +1,76 @@
+/**
+ * Persist the pairing JWT for reconnect within the current app session.
+ * Cleared on SDK init / exit preview / app restart (pairing exits on restart).
+ */
+
+const STORAGE_KEY = 'userflow:pairingToken';
+
+export interface PairingTokenStore {
+  get(): Promise<string | null>;
+  set(token: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+type SecureStoreModule = {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+  deleteItemAsync(key: string): Promise<void>;
+};
+
+function tryLoadExpoSecureStore(): SecureStoreModule | null {
+  try {
+    // Optional peer — absent in bare RN without expo-secure-store.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
+    return require('expo-secure-store') as SecureStoreModule;
+  } catch {
+    return null;
+  }
+}
+
+/** In-memory store used when SecureStore is unavailable (and in tests). */
+export function createMemoryPairingTokenStore(): PairingTokenStore {
+  let value: string | null = null;
+  return {
+    async get() {
+      return value;
+    },
+    async set(token: string) {
+      value = token;
+    },
+    async clear() {
+      value = null;
+    },
+  };
+}
+
+/**
+ * Prefer expo-secure-store (Keychain / Keystore); fall back to memory.
+ */
+export function createPairingTokenStore(): PairingTokenStore {
+  const secure = tryLoadExpoSecureStore();
+  if (!secure) return createMemoryPairingTokenStore();
+
+  return {
+    async get() {
+      try {
+        return await secure.getItemAsync(STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    },
+    async set(token: string) {
+      try {
+        await secure.setItemAsync(STORAGE_KEY, token);
+      } catch {
+        // Best-effort; reconnect still works from in-memory PairingEngine token.
+      }
+    },
+    async clear() {
+      try {
+        await secure.deleteItemAsync(STORAGE_KEY);
+      } catch {
+        // ignore
+      }
+    },
+  };
+}

package/src/pairing/usePairingState.ts

@@ -0,0 +1,43 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+import * as React from 'react';
+
+import type { PairingController } from './PairingController';
+import { onPairingController, peekPairingController } from './pairingRuntime';
+
+const IDLE: PairingEngineState = {
+  status: 'idle',
+  pairingId: null,
+  deviceId: null,
+  previewActive: false,
+  lastError: null,
+  needsRescan: false,
+  awaitingStartCondition: false,
+};
+
+/** Subscribe to Builder pairing / preview-mode state (dev builds only). */
+export function usePairingState(): PairingEngineState {
+  const [state, setState] = React.useState<PairingEngineState>(
+    () => peekPairingController()?.getState() ?? IDLE,
+  );
+
+  React.useEffect(() => {
+    let unsubState: (() => void) | undefined;
+
+    const bind = (controller: PairingController) => {
+      unsubState?.();
+      setState(controller.getState());
+      unsubState = controller.onStateChange(setState);
+    };
+
+    const existing = peekPairingController();
+    if (existing) bind(existing);
+    const unsubInstall = onPairingController(bind);
+
+    return () => {
+      unsubInstall();
+      unsubState?.();
+    };
+  }, []);
+
+  return state;
+}

package/src/runtime/FlowRenderer.tsx

@@ -0,0 +1,60 @@
+import { genSessionDataLookup } from '@userflow-tech/core';
+import type { FlowSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+
+import { ModalSurface } from '../surfaces/ModalSurface';
+import { TooltipSurface } from '../surfaces/TooltipSurface';
+
+import { FlowSurfaceFade } from './FlowSurfaceFade';
+import { useFlowSessionState } from './useFlowSessionState';
+
+export interface FlowRendererProps {
+  engine: FlowSessionEngine;
+}
+
+function appearanceOf(step: { appearance: unknown }): string {
+  return String(step.appearance).toUpperCase();
+}
+
+/**
+ * Renders the active flow step.
+ *
+ * TOOLTIP → {@link TooltipSurface}; everything else → {@link ModalSurface}
+ * (BUBBLE/HIDDEN remain centered-card fallbacks until dedicated surfaces).
+ */
+export function FlowRenderer({ engine }: FlowRendererProps): React.ReactElement | null {
+  const { session, currentStep } = useFlowSessionState(engine);
+  const lookupAttribute = React.useMemo(
+    () => genSessionDataLookup(session?.data ?? []),
+    [session?.data],
+  );
+
+  if (!session || !currentStep) {
+    return null;
+  }
+
+  const theme = currentStep.theme ?? session.version.theme;
+  const appearance = appearanceOf(currentStep);
+  const animationKey = `${session.id}:${currentStep.id}:${appearance}`;
+
+  const surface =
+    appearance === 'TOOLTIP' ? (
+      <TooltipSurface
+        engine={engine}
+        session={session}
+        currentStep={currentStep}
+        theme={theme}
+        lookupAttribute={lookupAttribute}
+      />
+    ) : (
+      <ModalSurface
+        engine={engine}
+        session={session}
+        currentStep={currentStep}
+        theme={theme}
+        lookupAttribute={lookupAttribute}
+      />
+    );
+
+  return <FlowSurfaceFade animationKey={animationKey}>{surface}</FlowSurfaceFade>;
+}