@userflow-tech/react-native 0.2.0 → 0.3.1

package/src/evalJs/evalJsBridge.ts

@@ -0,0 +1,42 @@
+/** Calls into the public SDK without importing the facade (that would cycle). */
+export interface EvalJsBridgeHandlers {
+  track(name: string, attributes?: Record<string, unknown>): void;
+  updateUser(attributes: Record<string, unknown>): void;
+  updateGroup(
+    attributes: Record<string, unknown>,
+    options?: { membership?: Record<string, unknown> },
+  ): void;
+  openUrl(url: string): void;
+  /** End the current flow session if it is one of `sessionIds` (the scripts in this WebView). */
+  endFlow(sessionIds: ReadonlySet<string>): void;
+  warn(message: string): void;
+}
+
+const noopHandlers: EvalJsBridgeHandlers = {
+  track: () => undefined,
+  updateUser: () => undefined,
+  updateGroup: () => undefined,
+  openUrl: () => undefined,
+  endFlow: () => undefined,
+  warn: (message) => {
+    console.warn(message);
+  },
+};
+
+let handlers: EvalJsBridgeHandlers = noopHandlers;
+
+export function setEvalJsBridgeHandlers(next: EvalJsBridgeHandlers | null): void {
+  handlers = next ?? noopHandlers;
+}
+
+export function getEvalJsBridgeHandlers(): EvalJsBridgeHandlers {
+  return handlers;
+}
+
+export function formatEvalJsError(message: string, code?: string): string {
+  return (
+    `Userflow: Evaluate JavaScript action failed.\n\n` +
+    `Error:\n${message}\n\n` +
+    `Code:\n${code ?? ''}`
+  );
+}

package/src/evalJs/evalJsController.ts

@@ -0,0 +1,127 @@
+import type { EvalJsEnqueueRequest, EvalJsLayout, EvalJsSnapshot } from './types';
+
+const HIDDEN: EvalJsLayout = { mode: 'hidden' };
+
+type Listener = () => void;
+
+let generation = 0;
+let active = false;
+let pending: string[] = [];
+/** Sessions whose scripts ran in the current WebView; `endFlow` may only end one of these. */
+let sessionIds = new Set<string>();
+let layout: EvalJsLayout = HIDDEN;
+let host: Record<string, unknown> = {};
+let bannerOwnsWebView = false;
+const listeners = new Set<Listener>();
+
+/**
+ * Cached for `useSyncExternalStore`: React re-renders forever if getSnapshot
+ * returns a new object while nothing changed.
+ */
+let currentSnapshot: EvalJsSnapshot = {
+  active,
+  generation,
+  pendingCount: 0,
+  layout,
+  host,
+  bannerOwnsWebView,
+};
+
+function emit(): void {
+  currentSnapshot = {
+    active,
+    generation,
+    pendingCount: pending.length,
+    layout,
+    host,
+    bannerOwnsWebView,
+  };
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+export const evalJsController = {
+  subscribe(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+
+  getSnapshot(): EvalJsSnapshot {
+    return currentSnapshot;
+  },
+
+  enqueue(request: EvalJsEnqueueRequest): void {
+    if (!request.code) return;
+    pending = [...pending, request.code];
+    sessionIds.add(request.sessionId);
+    active = true;
+    emit();
+  },
+
+  sessionIds(): ReadonlySet<string> {
+    return new Set(sessionIds);
+  },
+
+  /** Codes waiting to be injected. Clears the queue. */
+  consumePending(): string[] {
+    if (pending.length === 0) return [];
+    const codes = pending;
+    pending = [];
+    emit();
+    return codes;
+  },
+
+  setLayout(next: EvalJsLayout): void {
+    layout = next;
+    emit();
+  },
+
+  /** App-supplied values exposed as `userflowContext.host`. Survives reset. */
+  setHostContext(values: Record<string, unknown>): void {
+    host = { ...values };
+    emit();
+  },
+
+  /** Custom banner WebView is the sole eval page (no overlay EvalJsHost). */
+  setBannerOwnsWebView(owns: boolean): void {
+    bannerOwnsWebView = owns;
+    emit();
+  },
+
+  /**
+   * Destroy the shared WebView and drop queued code. Host context stays so the
+   * next script still sees language / tab-bar height the app provided.
+   */
+  reset(): void {
+    generation += 1;
+    active = false;
+    pending = [];
+    sessionIds = new Set();
+    layout = HIDDEN;
+    bannerOwnsWebView = false;
+    emit();
+  },
+};
+
+/** @internal */
+export function resetEvalJsControllerForTests(): void {
+  generation = 0;
+  active = false;
+  pending = [];
+  sessionIds = new Set();
+  layout = HIDDEN;
+  host = {};
+  bannerOwnsWebView = false;
+  listeners.clear();
+  currentSnapshot = {
+    active,
+    generation,
+    pendingCount: 0,
+    layout,
+    host,
+    bannerOwnsWebView,
+  };
+}

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

@@ -18,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.