@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/evalJs/getWebView.ts

@@ -0,0 +1,124 @@
+import type { ComponentType, Ref } from 'react';
+import { NativeModules, TurboModuleRegistry } from 'react-native';
+
+/**
+ * Minimal surface of `react-native-webview` this spike uses.
+ * Defined locally so the package root never statically imports the optional peer.
+ */
+export interface EvalJsWebViewHandle {
+  injectJavaScript(script: string): void;
+}
+
+export interface EvalJsShouldStartRequest {
+  url: string;
+}
+
+export interface EvalJsWebViewProps {
+  source: { html: string; baseUrl?: string };
+  style?: object;
+  pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+  originWhitelist?: string[];
+  javaScriptEnabled?: boolean;
+  domStorageEnabled?: boolean;
+  scrollEnabled?: boolean;
+  bounces?: boolean;
+  showsHorizontalScrollIndicator?: boolean;
+  showsVerticalScrollIndicator?: boolean;
+  mediaPlaybackRequiresUserAction?: boolean;
+  allowsInlineMediaPlayback?: boolean;
+  setSupportMultipleWindows?: boolean;
+  webviewDebuggingEnabled?: boolean;
+  androidLayerType?: 'none' | 'software' | 'hardware';
+  onMessage?: (event: { nativeEvent: { data?: string } }) => void;
+  onLoadEnd?: () => void;
+  onShouldStartLoadWithRequest?: (request: EvalJsShouldStartRequest) => boolean;
+  onOpenWindow?: (event: { nativeEvent: { targetUrl?: string } }) => void;
+  onError?: (event: { nativeEvent: { description?: string } }) => void;
+  ref?: Ref<EvalJsWebViewHandle>;
+}
+
+export type EvalJsWebViewComponent = ComponentType<EvalJsWebViewProps>;
+
+let cached: EvalJsWebViewComponent | null | undefined;
+let warnedMissing = false;
+
+/**
+ * True when the native `react-native-webview` binary is linked. Do not
+ * `require('react-native-webview')` before this passes — the JS entry calls
+ * `TurboModuleRegistry.getEnforcing('RNCWebViewModule')` and can red-screen.
+ */
+export function isEvalJsWebViewNativeLinked(): boolean {
+  try {
+    if (typeof TurboModuleRegistry?.get === 'function') {
+      if (TurboModuleRegistry.get('RNCWebViewModule') != null) {
+        return true;
+      }
+    }
+    const legacy = NativeModules.RNCWebViewModule as unknown;
+    return legacy != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lazy `require('react-native-webview')`, cached. Returns null when the package
+ * or native module is missing so Evaluate JavaScript can no-op instead of crashing.
+ */
+export function getEvalJsWebView(): EvalJsWebViewComponent | null {
+  if (cached !== undefined) return cached;
+
+  if (typeof require !== 'function') {
+    cached = null;
+    warnMissing('unavailable');
+    return cached;
+  }
+
+  if (!isEvalJsWebViewNativeLinked()) {
+    cached = null;
+    warnMissing('native');
+    return cached;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- peer probe
+    const mod = require('react-native-webview') as {
+      WebView?: EvalJsWebViewComponent;
+      default?: EvalJsWebViewComponent;
+    };
+    const component = mod?.WebView ?? mod?.default;
+    cached = component != null ? component : null;
+  } catch {
+    cached = null;
+  }
+
+  if (cached == null) {
+    warnMissing('js');
+  }
+  return cached;
+}
+
+function warnMissing(reason: 'native' | 'js' | 'unavailable'): void {
+  if (warnedMissing) return;
+  warnedMissing = true;
+  if (reason === 'native') {
+    console.warn(
+      'Userflow: react-native-webview is listed in package.json but RNCWebViewModule is not in ' +
+        'this native build. Run npx expo install react-native-webview (or npm install), then ' +
+        'rebuild the dev client (expo prebuild + run:ios / run:android — not Expo Go). ' +
+        'Evaluate JavaScript and WebView banners will not run until then.',
+    );
+    return;
+  }
+  console.warn(
+    'Userflow: Evaluate JavaScript requires react-native-webview. Install it in your app ' +
+      '(e.g. npx expo install react-native-webview), rebuild the native app, then retry. ' +
+      'The action was skipped.',
+  );
+}
+
+/** @internal */
+export function resetEvalJsWebViewCacheForTests(): void {
+  cached = undefined;
+  warnedMissing = false;
+}

package/src/evalJs/injectEvalPending.ts

@@ -0,0 +1,14 @@
+import { wrapCode } from './bootstrap';
+import { evalJsController } from './evalJsController';
+import type { EvalJsWebViewHandle } from './getWebView';
+
+/** Inject queued Evaluate JavaScript into a WebView (same document as the banner). */
+export function injectEvalPendingIntoWebView(view: EvalJsWebViewHandle | null | undefined): void {
+  if (!view) {
+    return;
+  }
+  const codes = evalJsController.consumePending();
+  for (const code of codes) {
+    view.injectJavaScript(wrapCode(code));
+  }
+}

package/src/evalJs/types.ts

@@ -0,0 +1,56 @@
+/** Layout the customer script asks the SDK overlay to use. */
+export type EvalJsLayoutMode = 'hidden' | 'fullscreen' | 'fitted';
+
+export interface EvalJsRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface EvalJsLayout {
+  mode: EvalJsLayoutMode;
+  rect?: EvalJsRect;
+}
+
+/** Mirrors the core `onEvalJs` request. Kept local so this package does not import engine internals. */
+export interface EvalJsEnqueueRequest {
+  code: string;
+  sessionId: string;
+  flowId: string;
+  draftMode: boolean;
+}
+
+export interface EvalJsScreen {
+  name?: string;
+  path?: string;
+}
+
+export interface EvalJsSafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** Snapshot injected as `window.userflowContext`. */
+export interface EvalJsContext {
+  platform: string;
+  colorScheme: 'light' | 'dark';
+  safeAreaInsets: EvalJsSafeAreaInsets;
+  viewport: { width: number; height: number };
+  screen: EvalJsScreen;
+  host: Record<string, unknown>;
+}
+
+export interface EvalJsSnapshot {
+  /** When false the WebView is unmounted. */
+  active: boolean;
+  /** Bumped on reset so a late message from a torn-down page is ignored. */
+  generation: number;
+  pendingCount: number;
+  layout: EvalJsLayout;
+  host: Record<string, unknown>;
+  /** Custom banner WebView owns eval injection; overlay EvalJsHost stays unmounted. */
+  bannerOwnsWebView: boolean;
+}

package/src/evalJs/useEvalJsWebViewInjection.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+
+import { contextUpdateScript, wrapCode } from './bootstrap';
+import { evalJsController } from './evalJsController';
+import type { EvalJsWebViewHandle } from './getWebView';
+import type { EvalJsContext } from './types';
+
+/**
+ * Keeps `userflowContext` fresh and drains the eval-js queue into one WebView.
+ */
+export function useEvalJsWebViewInjection(
+  webRef: React.RefObject<EvalJsWebViewHandle | null>,
+  options: { pageReady: boolean; context: EvalJsContext; pendingCount: number },
+): void {
+  const { pageReady, context, pendingCount } = options;
+
+  React.useEffect(() => {
+    if (!pageReady) {
+      return;
+    }
+    webRef.current?.injectJavaScript(contextUpdateScript(context));
+  }, [context, pageReady, webRef]);
+
+  React.useEffect(() => {
+    if (!pageReady) {
+      return;
+    }
+    const view = webRef.current;
+    if (!view) {
+      return;
+    }
+    const codes = evalJsController.consumePending();
+    for (const code of codes) {
+      view.injectJavaScript(wrapCode(code));
+    }
+  }, [pageReady, pendingCount, webRef]);
+}

package/src/expo-router/index.ts

@@ -1,2 +1,10 @@
 export { useUserflowExpoRouter } from './useUserflowExpoRouter';
 export { UserflowExpoRouterScreenTracker } from './UserflowExpoRouterScreenTracker';
+export {
+  createRedirectSystemPath,
+  isUserflowLinkPath,
+  redirectSystemPath,
+  type CreateRedirectSystemPathOptions,
+  type RedirectSystemPath,
+  type RedirectSystemPathOptions,
+} from './redirectSystemPath';

package/src/expo-router/redirectSystemPath.ts

@@ -0,0 +1,86 @@
+import { parsePreviewDeepLink } from '../deepLinking';
+import { inspectPairingDeepLink, isPairingAttempt } from '../pairing/deepLink';
+
+/**
+ * Arguments Expo Router passes to `redirectSystemPath` from `+native-intent`.
+ * @see https://docs.expo.dev/router/advanced/native-intent/
+ */
+export interface RedirectSystemPathOptions {
+  path: string;
+  initial: boolean;
+}
+
+export type RedirectSystemPath = (
+  event: RedirectSystemPathOptions,
+) => Promise<string | null> | string | null;
+
+export interface CreateRedirectSystemPathOptions {
+  /**
+   * Optional host handler invoked when the path is not a Userflow deep link.
+   * Receives the same event Expo passed in; its return value is forwarded.
+   */
+  next?: RedirectSystemPath;
+}
+
+/**
+ * True when `path` is a full Userflow pairing or preview URL that Expo Router
+ * should not navigate to.
+ *
+ * Only full URLs are claimed. Expo Router passes the raw URL to
+ * `redirectSystemPath` for both the initial URL and later URL events, so a
+ * bare `?token=` or `?pairing_token=` must be left alone — it may belong to
+ * the host.
+ */
+export function isUserflowLinkPath(path: string): boolean {
+  if (typeof path !== 'string' || path.length === 0) return false;
+  if (!/^[a-z][a-z0-9+.-]*:/i.test(path)) return false;
+
+  const pairing = inspectPairingDeepLink(path);
+  if (pairing.ok || isPairingAttempt(pairing.reason)) return true;
+  return parsePreviewDeepLink(path) != null;
+}
+
+/**
+ * Build a `redirectSystemPath` that yields Userflow links and otherwise
+ * forwards to `next` (or returns the path unchanged).
+ */
+export function createRedirectSystemPath(
+  options: CreateRedirectSystemPathOptions = {},
+): RedirectSystemPath {
+  const { next } = options;
+
+  return (event) => {
+    try {
+      if (isUserflowLinkPath(event.path)) {
+        return null;
+      }
+    } catch {
+      // Expo warns that throwing here can crash the app. Fall through and let
+      // the router handle the original path.
+    }
+
+    if (next) {
+      return next(event);
+    }
+    return event.path;
+  };
+}
+
+/**
+ * Expo Router `redirectSystemPath` that swallows Userflow deep links.
+ *
+ * Returning `null` tells Expo Router to stay on the current path. The original
+ * URL remains available to React Native `Linking`, which the SDK already
+ * listens on.
+ *
+ * Mount from the host app:
+ *
+ * ```ts
+ * // app/+native-intent.ts
+ * export { redirectSystemPath } from '@userflow-tech/react-native/expo-router';
+ * ```
+ *
+ * Hosts that already export `redirectSystemPath` should wrap it with
+ * {@link createRedirectSystemPath}.
+ */
+export const redirectSystemPath: RedirectSystemPath = createRedirectSystemPath();

package/src/expo-router/useUserflowExpoRouter.ts

@@ -1,6 +1,11 @@
-import { usePathname, useRouter } from 'expo-router';
-import { useEffect } from 'react';
+import { useNavigationContainerRef, usePathname, useRouter } from 'expo-router';
+import { useCallback, useEffect, useRef } from 'react';
 
+import {
+  isOverlayPresentation,
+  readNavigationPresentation,
+  subscribeNavigationState,
+} from '../navigation/isOverlayPresentation';
 import { setExpoRouterNavigator } from '../navigation/openFlowNavigateUrl';
 import { handleScreenChange } from '../screenTracker';
 
@@ -13,8 +18,8 @@ import { handleScreenChange } from '../screenTracker';
  * import this hook from the package root — that would force every host app to
  * install the `expo-router` peer.
  *
- * Pathnames are reported as `{ path }` and mapped to wire `screenPath`
- * (not `screenName`).
+ * Pathnames are reported as `{ path }` and sent as wire `screenName` (the
+ * backend has no separate path field).
  *
  * Screen tracking ≠ action routing: NAVIGATE for in-app paths uses the router
  * handle registered here; http(s)/mailto/tel still go through Linking.
@@ -22,10 +27,48 @@ import { handleScreenChange } from '../screenTracker';
 export function useUserflowExpoRouter(): void {
   const pathname = usePathname();
   const router = useRouter();
+  // Root container ref — `useNavigation()` is the route prop and has no getCurrentOptions.
+  const navigationRef = useNavigationContainerRef();
+  const overlayWasFocusedRef = useRef(false);
+  const pathnameRef = useRef(pathname);
+  pathnameRef.current = pathname;
+  const subscribedToStateRef = useRef(false);
+
+  const reportPath = useCallback(() => {
+    if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
+      overlayWasFocusedRef.current = true;
+      return;
+    }
+    handleScreenChange(
+      pathnameRef.current ? { path: pathnameRef.current } : undefined,
+      overlayWasFocusedRef.current ? { force: true } : undefined,
+    );
+    overlayWasFocusedRef.current = false;
+  }, [navigationRef]);
+
+  useEffect(() => {
+    // Pathname is the fallback when the container ref has no `state` listener
+    // (tests, or before the root container mounts). Once subscribed, navigation
+    // state is the source of truth so overlay options are read on the same tick
+    // as the transition — a pathname-only update can still see the previous
+    // route's options.
+    if (!subscribedToStateRef.current) {
+      reportPath();
+    }
+  }, [pathname, reportPath]);
 
   useEffect(() => {
-    handleScreenChange(pathname ? { path: pathname } : undefined);
-  }, [pathname]);
+    const unsubscribe = subscribeNavigationState(navigationRef, () => {
+      queueMicrotask(() => {
+        reportPath();
+      });
+    });
+    subscribedToStateRef.current = typeof unsubscribe === 'function';
+    return () => {
+      subscribedToStateRef.current = false;
+      unsubscribe?.();
+    };
+  }, [navigationRef, reportPath]);
 
   useEffect(() => {
     setExpoRouterNavigator({

package/src/hostAppVersion.ts

@@ -0,0 +1,258 @@
+/**
+ * Read the host app's native marketing version (store version), not the
+ * SDK package version. React Native does not expose the store version on
+ * `Platform`; Expo hosts may use optional expo modules; bare RN reads
+ * `NativeModules.RNDeviceInfo` constants from the bundled device-info native
+ * module (after autolink + rebuild). The OS name is `Platform.OS`.
+ *
+ * Do not `require('react-native-device-info')` — that package throws at import
+ * when the native module is missing, and Metro/Hermes may surface it as uncaught
+ * even inside try/catch.
+ */
+
+export type HostAppVersionSource =
+  | 'expo-application'
+  | 'expo-constants'
+  | 'react-native-device-info'
+  | 'init-override';
+
+export interface HostAppVersion {
+  version: string;
+  build?: string;
+  source: HostAppVersionSource;
+}
+
+export interface RNDeviceInfoConstants {
+  appVersion?: string;
+  buildNumber?: string;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function unwrapModule(mod: unknown): Record<string, unknown> | null {
+  if (typeof mod !== 'object' || mod === null) return null;
+  const record = mod as Record<string, unknown>;
+  const nested = record['default'];
+  if (typeof nested === 'object' && nested !== null) {
+    return { ...record, ...(nested as Record<string, unknown>) };
+  }
+  return record;
+}
+
+function tryRequireExpoApplication(): unknown {
+  try {
+    // Optional on bare RN — Metro requires a string literal.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('expo-application');
+  } catch {
+    return undefined;
+  }
+}
+
+function tryRequireExpoConstants(): unknown {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('expo-constants');
+  } catch {
+    return undefined;
+  }
+}
+
+function loadLinkedDeviceInfoNativeModule(): RNDeviceInfoConstants | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const { NativeModules } = require('react-native') as {
+      NativeModules: { RNDeviceInfo?: RNDeviceInfoConstants };
+    };
+    return NativeModules.RNDeviceInfo ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Visible for tests: map an `expo-application` module shape to a version. */
+export function readExpoApplication(mod: unknown): HostAppVersion | null {
+  const record = unwrapModule(mod);
+  if (!record) return null;
+  const version = nonEmptyString(record['nativeApplicationVersion']);
+  if (!version) return null;
+  const build = nonEmptyString(record['nativeBuildVersion']);
+  return { version, source: 'expo-application', ...(build ? { build } : {}) };
+}
+
+/** Visible for tests: map an `expo-constants` module shape to a version. */
+export function readExpoConstants(mod: unknown): HostAppVersion | null {
+  const record = unwrapModule(mod);
+  if (!record) return null;
+  const expoConfig = record['expoConfig'];
+  const configVersion =
+    typeof expoConfig === 'object' && expoConfig !== null
+      ? nonEmptyString((expoConfig as Record<string, unknown>)['version'])
+      : undefined;
+  const version = nonEmptyString(record['nativeAppVersion']) ?? configVersion;
+  if (!version) return null;
+  const build = nonEmptyString(record['nativeBuildVersion']);
+  return { version, source: 'expo-constants', ...(build ? { build } : {}) };
+}
+
+/** Visible for tests: map linked RNDeviceInfo native constants to a version. */
+export function readDeviceInfoFromNativeModule(
+  module: RNDeviceInfoConstants | null | undefined,
+): HostAppVersion | null {
+  if (!module) return null;
+  const version = nonEmptyString(module.appVersion);
+  if (!version || version === 'unknown') return null;
+  const build = nonEmptyString(module.buildNumber);
+  return {
+    version,
+    source: 'react-native-device-info',
+    ...(build && build !== 'unknown' ? { build } : {}),
+  };
+}
+
+/** Visible for tests: first non-null reader wins (Expo modules, then RNDeviceInfo). */
+export function resolveHostAppVersionFromSources(sources: {
+  expoApplication?: unknown;
+  expoConstants?: unknown;
+  deviceInfoNative?: RNDeviceInfoConstants | null;
+}): HostAppVersion | null {
+  return (
+    readExpoApplication(sources.expoApplication) ??
+    readExpoConstants(sources.expoConstants) ??
+    readDeviceInfoFromNativeModule(sources.deviceInfoNative)
+  );
+}
+
+export function resolveHostAppVersion(): HostAppVersion | null {
+  return resolveHostAppVersionFromSources({
+    expoApplication: tryRequireExpoApplication(),
+    expoConstants: tryRequireExpoConstants(),
+    deviceInfoNative: loadLinkedDeviceInfoNativeModule(),
+  });
+}
+
+export interface HostAppVersionInitOptions {
+  /** When set, overrides auto-detection for the lifetime of this init. */
+  appVersion?: string;
+  appBuild?: string;
+}
+
+/** Visible for tests: resolve version for init, honoring an optional client override. */
+export function resolveHostAppVersionForInit(
+  options: HostAppVersionInitOptions = {},
+): HostAppVersion | null {
+  const overrideVersion = nonEmptyString(options.appVersion);
+  if (overrideVersion) {
+    const build = nonEmptyString(options.appBuild);
+    return {
+      version: overrideVersion,
+      source: 'init-override',
+      ...(build ? { build } : {}),
+    };
+  }
+  return resolveHostAppVersion();
+}
+
+/** `undefined` until the first {@link cacheHostAppVersionAtInit}; then resolved or null. */
+let cachedHostAppVersion: HostAppVersion | null | undefined;
+
+/**
+ * Resolve and cache the host app version during {@link Userflow.init}.
+ * Re-running init replaces the cache.
+ */
+export function cacheHostAppVersionAtInit(
+  options: HostAppVersionInitOptions = {},
+): HostAppVersion | null {
+  cachedHostAppVersion = resolveHostAppVersionForInit(options);
+  return cachedHostAppVersion;
+}
+
+/** Returns the version cached at init, or `null` before init or when unavailable. */
+export function getCachedHostAppVersion(): HostAppVersion | null {
+  return cachedHostAppVersion ?? null;
+}
+
+/** User attribute keys for the host app's native store version. */
+export const HOST_APP_VERSION_USER_ATTRIBUTE = 'app_version';
+export const HOST_APP_BUILD_USER_ATTRIBUTE = 'app_build';
+
+/** Returns cached host version fields for UpsertUser, or `{}` when unavailable. */
+export function hostAppVersionUserAttributes(): Record<string, string> {
+  const cached = getCachedHostAppVersion();
+  if (!cached) return {};
+  return {
+    [HOST_APP_VERSION_USER_ATTRIBUTE]: cached.version,
+    ...(cached.build ? { [HOST_APP_BUILD_USER_ATTRIBUTE]: cached.build } : {}),
+  };
+}
+
+/** Optional user-attribute keys added by {@link mergeHostAppVersionUserAttributes}. */
+export type HostAppVersionUserAttributeMap = Partial<{
+  [HOST_APP_VERSION_USER_ATTRIBUTE]: string;
+  [HOST_APP_BUILD_USER_ATTRIBUTE]: string;
+}>;
+
+/** Merges cached host version attrs into identify attributes; caller values win on key conflicts. */
+export function mergeHostAppVersionUserAttributes<T extends Record<string, unknown>>(
+  attributes?: T,
+): (T & HostAppVersionUserAttributeMap) | undefined {
+  const system = hostAppVersionUserAttributes();
+  if (Object.keys(system).length === 0) {
+    return attributes as (T & HostAppVersionUserAttributeMap) | undefined;
+  }
+  return { ...system, ...(attributes ?? {}) } as T & HostAppVersionUserAttributeMap;
+}
+
+/** @internal Resets init cache between tests. */
+export function resetCachedHostAppVersionForTests(): void {
+  cachedHostAppVersion = undefined;
+}
+
+function readPlatformOS(): string {
+  try {
+    // Lazy require so Node unit tests can format messages without loading RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const os = (require('react-native') as { Platform?: { OS?: string } }).Platform?.OS;
+    return typeof os === 'string' && os.length > 0 ? os : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+export function formatHostAppVersionLog(
+  resolved: HostAppVersion | null,
+  os: string,
+): {
+  level: 'log' | 'warn';
+  message: string;
+} {
+  if (!resolved) {
+    return {
+      level: 'warn',
+      message:
+        `[Userflow] host app version is unavailable on ${os}. Rebuild the native app ` +
+        '(for example `cd ios && pod install`) so the bundled version module is linked.',
+    };
+  }
+  const build = resolved.build ? ` (build ${resolved.build})` : '';
+  return {
+    level: 'log',
+    message: `[Userflow] host app version ${resolved.version}${build} on ${os}`,
+  };
+}
+
+/** Log the host app's native version and platform OS to the console. */
+export function logHostAppVersion(): void {
+  const resolved =
+    cachedHostAppVersion !== undefined ? cachedHostAppVersion : resolveHostAppVersion();
+  const { level, message } = formatHostAppVersionLog(resolved, readPlatformOS());
+  if (level === 'warn') {
+    // eslint-disable-next-line no-console -- public logHostAppVersion()
+    console.warn(message);
+    return;
+  }
+  // eslint-disable-next-line no-console -- public logHostAppVersion()
+  console.log(message);
+}