@userflow-tech/react-native 0.2.0 → 0.3.1

package/src/runtime/flowEngine.ts

@@ -1,8 +1,15 @@
 import { FlowSessionEngine, type UserflowCore } from '@userflow-tech/core';
+import type { EndFlowReasonInput } from '@userflow-tech/protocol';
 
+import { evalJsController } from '../evalJs/evalJsController';
 import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
 
+import { isolateAsync } from './isolateCall';
+
 let flowEngine: FlowSessionEngine | null = null;
+/** Exit asked to end a draft that identify has not delivered yet. */
+let endDraftOnArrival = false;
+let unsubscribeDraftArrival: (() => void) | null = null;
 
 /** Build (once) the module-level flow session engine over a {@link UserflowCore} transport. */
 export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
@@ -14,11 +21,17 @@ export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
         setFlowSessionId: (id) => core.setFlowSessionId(id),
       },
       onOpenExternalUrl: (url) => {
-        void openFlowNavigateUrl(url);
+        void isolateAsync('navigate', () => openFlowNavigateUrl(url), {
+          rethrowHostContract: false,
+        });
+      },
+      onEvalJs: (request) => {
+        evalJsController.enqueue(request);
       },
       updateUser: (attributes) => core.updateUser(attributes),
       updateGroup: (attributes, options) => core.updateGroup(attributes, options),
     });
+    if (endDraftOnArrival) watchForRestoredDraft();
   }
   return flowEngine;
 }
@@ -43,13 +56,73 @@ export function clearFlowSessionEngineLocalSession(): void {
   flowEngine?.clearLocalSession();
 }
 
-/** Whether any mid-flow session (live or draft/preview) is currently on screen. */
+/**
+ * Whether a mid-flow session is held (live, draft, or suppressed by Temporarily
+ * Hide). Foreground idle uses this so a hidden session keeps the socket that
+ * can deliver the attribute update which shows it again.
+ */
 export function hasActiveFlowSession(): boolean {
-  return flowEngine?.getFlowSession() != null;
+  return flowEngine?.hasHeldFlowSession() === true;
+}
+
+/**
+ * End the current flow on the server if it is a Builder preview draft. The
+ * server restores every active draft on identify, so clearing it locally is
+ * not enough to keep it from returning on the next launch.
+ *
+ * A draft Temporarily Hide is suppressing is still ended. `getFlowSession()`
+ * hides it, but the server will send it again. When exit runs before identify
+ * has delivered the draft, the next draft session is ended when it arrives.
+ * {@link cancelPendingDraftEnd} drops that wait; a new preview must call it
+ * so the preview's own draft is not ended.
+ */
+export async function endDraftFlowSession(): Promise<void> {
+  const session = flowEngine?.getHeldFlowSession();
+  if (flowEngine && session?.draftMode) {
+    cancelPendingDraftEnd();
+    await flowEngine.endFlow('USER_CLOSED' as EndFlowReasonInput);
+    return;
+  }
+  watchForRestoredDraft();
+}
+
+/** Drop a pending end from {@link endDraftFlowSession}. A new preview calls this. */
+export function cancelPendingDraftEnd(): void {
+  endDraftOnArrival = false;
+  unsubscribeDraftArrival?.();
+  unsubscribeDraftArrival = null;
+}
+
+function watchForRestoredDraft(): void {
+  endDraftOnArrival = true;
+  if (!flowEngine || unsubscribeDraftArrival) return;
+
+  const engine = flowEngine;
+  unsubscribeDraftArrival = engine.on((event) => {
+    if (event.type !== 'sessionChange' || !endDraftOnArrival) return;
+    const session = engine.getHeldFlowSession();
+    if (!session?.draftMode) return;
+    cancelPendingDraftEnd();
+    void engine.endFlow('USER_CLOSED' as EndFlowReasonInput).catch(() => {
+      // The session can disappear before EndFlow is built. Nothing to send.
+    });
+  });
+}
+
+/**
+ * `userflow.endFlow()` from an Evaluate JavaScript page. Ends the current
+ * session only if one of the page's scripts came from it, so a stale page
+ * cannot end a flow that started later.
+ */
+export async function endEvalJsFlowSession(sessionIds: ReadonlySet<string>): Promise<void> {
+  const session = flowEngine?.getFlowSession();
+  if (!flowEngine || !session || !sessionIds.has(session.id)) return;
+  await flowEngine.endFlow('USERFLOWJS' as EndFlowReasonInput);
 }
 
 /** Test helper: drop the singleton so the next get recreates it. */
 export function __resetFlowSessionEngineForTests(): void {
+  cancelPendingDraftEnd();
   flowEngine?.reset();
   flowEngine = null;
 }

package/src/runtime/isolateCall.ts

@@ -0,0 +1,53 @@
+import { reportSdkError } from './reportSdkError';
+
+/**
+ * True for missing `init` / `identify`, invalid event or attribute names — not
+ * for transport `UserflowAuthError`s. The flag is set at the throw site on
+ * `UserflowAuthError.isHostContract`; message text is not consulted.
+ * Matched by `error.name` plus the flag so mocked test doubles with the same
+ * name are treated like the real class.
+ */
+export function isHostContractError(error: unknown): boolean {
+  if (!(error instanceof Error) || error.name !== 'UserflowAuthError') {
+    return false;
+  }
+  return (error as { isHostContract?: boolean }).isHostContract === true;
+}
+
+export interface IsolateAsyncOptions {
+  /**
+   * When true (default), host-contract `UserflowAuthError`s are rethrown so the
+   * host sees integration misuse. Internal fire-and-forget paths pass false.
+   */
+  rethrowHostContract?: boolean;
+}
+
+/** Run synchronous SDK work; swallow and report anything except host-contract errors. */
+export function isolateSync<T>(scope: string, work: () => T): T | undefined {
+  try {
+    return work();
+  } catch (error) {
+    if (isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}
+
+/** Run async SDK work; swallow and report anything except host-contract errors. */
+export async function isolateAsync<T>(
+  scope: string,
+  work: () => Promise<T>,
+  options?: IsolateAsyncOptions,
+): Promise<T | undefined> {
+  try {
+    return await work();
+  } catch (error) {
+    if ((options?.rethrowHostContract ?? true) && isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}

package/src/runtime/reportSdkError.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal reporter for SDK failures that must not reach the host app.
+ * Always logs (not `__DEV__`-only) so a swallowed error is still diagnosable.
+ *
+ * Uses `console.warn`, not `console.error`: React Native release builds forward
+ * `console.error` to the native exception manager (Crashlytics / Sentry), which
+ * would report an isolated tooltip failure as a host crash.
+ */
+export function reportSdkError(scope: string, error: unknown, extra?: unknown): void {
+  // eslint-disable-next-line no-console -- isolation diagnostics must reach host logs
+  console.warn('[Userflow] isolated error', scope, error, extra ?? '');
+}

package/src/runtime/useBannerSession.ts

@@ -0,0 +1,35 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { isolateSync } from './isolateCall';
+
+/** Subscribe to the active banner. A throw while reading the session stays off the host tree. */
+export function useBannerSession(engine: BannerSessionEngine | null): BannerSessionFragment | null {
+  const [session, setSession] = React.useState<BannerSessionFragment | null>(() => {
+    if (!engine) return null;
+    try {
+      return engine.getBannerSession();
+    } catch {
+      return null;
+    }
+  });
+
+  React.useEffect(() => {
+    if (!engine) {
+      setSession(null);
+      return;
+    }
+    const read = () => {
+      isolateSync('banner-session', () => {
+        setSession(engine.getBannerSession());
+      });
+    };
+    read();
+    return engine.on(() => {
+      read();
+    });
+  }, [engine]);
+
+  return session;
+}

package/src/screenTracker.ts

@@ -18,6 +18,7 @@ let currentLocation: ClientLocationUpdate | null = null;
 /** Latest location seen while tracking was disabled; flushed on enable. */
 let pendingLocation: ClientLocationUpdate | null = null;
 let reporter: ScreenChangeReporter | null = null;
+const screenListeners = new Set<ScreenChangeReporter>();
 
 function locationKey(location: ClientLocationUpdate): string {
   return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
@@ -26,13 +27,10 @@ function locationKey(location: ClientLocationUpdate): string {
 /** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
 export function screenViewedAttributes(
   location: ClientLocationUpdate,
-): { screen_path: string } | { screen_name: string } | null {
-  if ('path' in location) {
-    if (!location.path) return null;
-    return { screen_path: location.path };
-  }
-  if (!location.screen) return null;
-  return { screen_name: location.screen };
+): { screen_name: string } | null {
+  const screenName = 'path' in location ? location.path : location.screen;
+  if (!screenName) return null;
+  return { screen_name: screenName };
 }
 
 /**
@@ -43,10 +41,37 @@ export function setScreenChangeReporter(next: ScreenChangeReporter | null): void
   reporter = next;
 }
 
+/**
+ * Observe accepted screen changes (Evaluate JavaScript context, and similar).
+ * Fires immediately with the latest known location when one exists.
+ * A throwing listener does not block the reporter or the other listeners.
+ */
+export function subscribeScreenLocation(listener: ScreenChangeReporter): () => void {
+  screenListeners.add(listener);
+  const current = getCurrentScreenLocation();
+  if (current) {
+    try {
+      listener(current);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
+  return () => {
+    screenListeners.delete(listener);
+  };
+}
+
 function report(location: ClientLocationUpdate): void {
   currentKey = locationKey(location);
   currentLocation = location;
   reporter?.(location);
+  for (const listener of screenListeners) {
+    try {
+      listener(location);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
 }
 
 /** Latest screen/path the SDK has recorded, or `null` before the first report. */
@@ -85,7 +110,7 @@ export function disableScreenTracking(): void {
  * flushed when tracking is enabled (so init-after-mount still picks up the
  * active route).
  *
- * - Expo Router: `{ path: "/settings/billing" }` → wire `screenPath`
+ * - Expo Router: `{ path: "/settings/billing" }` → wire `screenName`
  * - React Navigation / manual: `{ screen: "BillingSettings" }` → wire `screenName`
  */
 export function handleScreenChange(
@@ -122,4 +147,5 @@ export function resetScreenTrackerForTests(): void {
   currentLocation = null;
   currentKey = null;
   pendingLocation = null;
+  screenListeners.clear();
 }

package/src/storage/asyncStorage.ts

@@ -0,0 +1,88 @@
+interface ReactNativeNativeLookup {
+  NativeModules?: Record<string, unknown>;
+  TurboModuleRegistry?: { get?: (name: string) => unknown };
+}
+const ASYNC_STORAGE_NATIVE_MODULES = [
+  'RNAsyncStorage',
+  'RNCAsyncStorage',
+  'RNC_AsyncSQLiteDBStorage',
+  'PlatformLocalStorage',
+  'AsyncSQLiteDBStorage',
+  'AsyncLocalStorage',
+] as const;
+
+export interface AsyncStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+let cached: AsyncStorageLike | null | undefined;
+
+function loadReactNative(): ReactNativeNativeLookup | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('react-native') as ReactNativeNativeLookup;
+  } catch {
+    return null;
+  }
+}
+
+function nativeModuleRegistered(name: string, reactNative: ReactNativeNativeLookup): boolean {
+  try {
+    const turbo = reactNative.TurboModuleRegistry;
+    if (typeof turbo?.get === 'function' && turbo.get(name) != null) {
+      return true;
+    }
+  } catch {
+    // A missing turbo registry is not a failed link check.
+  }
+  try {
+    return reactNative.NativeModules?.[name] != null;
+  } catch {
+    return false;
+  }
+}
+
+/** True when some AsyncStorage native binary is in this build. */
+export function isAsyncStorageLinked(): boolean {
+  const reactNative = loadReactNative();
+  if (!reactNative) return false;
+  return ASYNC_STORAGE_NATIVE_MODULES.some((name) => nativeModuleRegistered(name, reactNative));
+}
+
+/**
+ * The AsyncStorage JS API, or `null` when the package or its native module is
+ * missing. Never requires the package until the native module is registered.
+ */
+export function getAsyncStorage(): AsyncStorageLike | null {
+  if (cached !== undefined) return cached;
+
+  if (typeof require !== 'function' || !isAsyncStorageLinked()) {
+    cached = null;
+    return cached;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('@react-native-async-storage/async-storage') as {
+      default?: Partial<AsyncStorageLike>;
+    } & Partial<AsyncStorageLike>;
+    const storage = mod?.default ?? mod;
+    cached =
+      typeof storage?.getItem === 'function' &&
+      typeof storage.setItem === 'function' &&
+      typeof storage.removeItem === 'function'
+        ? (storage as AsyncStorageLike)
+        : null;
+  } catch {
+    cached = null;
+  }
+
+  return cached;
+}
+
+/** @internal */
+export function resetAsyncStorageCacheForTests(): void {
+  cached = undefined;
+}

package/src/surfaces/BannerBar.tsx

@@ -0,0 +1,176 @@
+import { genSessionDataLookup } from '@userflow-tech/core';
+import type { FlowActionFragment } from '@userflow-tech/protocol';
+import {
+  BannerEmbedMode,
+  EndFlowReasonInput,
+  type BannerSessionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+import { Animated, Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { BannerStepButton } from '../content/BannerStepButton';
+import { RichContentRenderer } from '../content/RichContentRenderer';
+import { mixThemeColors } from '../content/themeColor';
+
+import {
+  BANNER_CLOSE_SLOT_SIZE,
+  BANNER_ROOT_PADDING,
+  bannerFrameStyle,
+  bannerInnerStyle,
+  resolveBannerBarBorderRadius,
+} from './bannerBarLayout';
+import {
+  BANNER_BUTTON_GAP,
+  BANNER_CLOSE_BORDER_RADIUS,
+  bannerOverlayShadowStyle,
+} from './bannerBarTokens';
+import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from './resolveBannerTheme';
+
+export interface BannerBarProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+/**
+ * Banner chrome. An overlay parent floats this over the host. A flow parent
+ * keeps it in layout so the app is pushed instead of covered.
+ */
+export function BannerBar({
+  session,
+  onActions,
+  onDismiss,
+}: BannerBarProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const backgroundColor = resolveBannerBackgroundColor(theme);
+  const foregroundColor = resolveBannerForegroundColor(theme);
+  const bannerTheme = React.useMemo(
+    () => ({ ...theme, backgroundColor, fontColor: foregroundColor }),
+    [theme, backgroundColor, foregroundColor],
+  );
+  const lookupAttribute = React.useMemo(() => genSessionDataLookup(session.data), [session.data]);
+  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+
+  React.useEffect(() => {
+    if (!banner?.animate) {
+      opacity.setValue(1);
+      return;
+    }
+    opacity.setValue(0);
+    const animation = Animated.timing(opacity, {
+      toValue: 1,
+      duration: 200,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => {
+      animation.stop();
+    };
+  }, [banner?.animate, opacity, session.id]);
+
+  if (!banner) return null;
+
+  const overlay = banner.overlay !== false;
+  const frameStyle = bannerFrameStyle(banner);
+  const innerStyle = bannerInnerStyle(banner);
+  const closePressedBackground = mixThemeColors(backgroundColor, foregroundColor, 0.12);
+  const overlayEdge = banner.embedMode === BannerEmbedMode.BODY_LAST ? 'bottom' : 'top';
+  const barRadius = resolveBannerBarBorderRadius(banner);
+
+  return (
+    <View testID="userflow-banner-frame" style={frameStyle}>
+      <Animated.View style={[{ opacity }, overlay ? bannerOverlayShadowStyle(overlayEdge) : null]}>
+        <View
+          testID="userflow-banner"
+          style={[
+            styles.root,
+            { backgroundColor },
+            barRadius != null ? { borderRadius: barRadius, overflow: 'hidden' as const } : null,
+          ]}
+        >
+          <View style={styles.startSpacer} />
+          <View style={innerStyle}>
+            <View style={styles.content}>
+              <RichContentRenderer
+                content={banner.content}
+                buttons={[]}
+                theme={bannerTheme}
+                sessionData={session.data}
+                lookupAttribute={lookupAttribute}
+                onActions={onActions}
+              />
+            </View>
+            {banner.buttons.length > 0 ? (
+              <View style={styles.buttons}>
+                {banner.buttons.map((button) => (
+                  <BannerStepButton
+                    key={button.id}
+                    button={button}
+                    theme={bannerTheme}
+                    sessionData={session.data}
+                    onActions={onActions}
+                  />
+                ))}
+              </View>
+            ) : null}
+          </View>
+          {session.version.closeDisabled ? (
+            <View style={styles.startSpacer} />
+          ) : (
+            <Pressable
+              testID="userflow-banner-dismiss"
+              accessibilityRole="button"
+              accessibilityLabel="Dismiss"
+              hitSlop={8}
+              onPress={() => onDismiss(EndFlowReasonInput.USER_CLOSED)}
+              style={({ pressed }) => [
+                styles.close,
+                pressed ? { backgroundColor: closePressedBackground } : null,
+              ]}
+            >
+              <Text style={[styles.dismissIcon, { color: foregroundColor }]}>×</Text>
+            </Pressable>
+          )}
+        </View>
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: BANNER_ROOT_PADDING,
+  },
+  startSpacer: {
+    flexGrow: 1,
+    flexShrink: 1,
+    maxWidth: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+  },
+  content: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
+  buttons: {
+    flexDirection: 'row',
+    flexWrap: 'nowrap',
+    alignItems: 'center',
+    gap: BANNER_BUTTON_GAP,
+  },
+  close: {
+    width: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    borderRadius: BANNER_CLOSE_BORDER_RADIUS,
+  },
+  dismissIcon: {
+    fontSize: 18,
+    lineHeight: 22,
+    fontWeight: '300',
+  },
+});

package/src/surfaces/BannerSurface.tsx

@@ -0,0 +1,82 @@
+import type {
+  BannerSessionFragment,
+  EndFlowReasonInput,
+  FlowActionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { evalJsController } from '../evalJs/evalJsController';
+import { getEvalJsWebView } from '../evalJs/getWebView';
+
+import { BannerBar } from './BannerBar';
+import { BannerWebViewBar } from './bannerWebView/BannerWebViewBar';
+import { clearBannerAutoRunEvalSession } from './bannerWebView/bannerAutoRunSession';
+import { bannerNeedsWebView } from './bannerWebView/bannerNeedsWebView';
+
+export interface BannerSurfaceProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+let warnedMissingWebView = false;
+
+/**
+ * Native banner bar, or a WebView when a button runs Evaluate JavaScript or the
+ * theme has published custom CSS (same CDN stylesheet as userflow.js iframes).
+ */
+export function BannerSurface({
+  session,
+  onActions,
+  onDismiss,
+}: BannerSurfaceProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
+  const webView = needsWebView ? getEvalJsWebView() : null;
+
+  React.useLayoutEffect(() => {
+    if (!needsWebView || !webView) {
+      return;
+    }
+    evalJsController.setBannerOwnsWebView(true);
+    return () => {
+      evalJsController.setBannerOwnsWebView(false);
+    };
+  }, [needsWebView, webView, session.id]);
+
+  const dismissWebViewBanner = React.useCallback(
+    (endReason: EndFlowReasonInput) => {
+      clearBannerAutoRunEvalSession(session.id);
+      evalJsController.reset();
+      onDismiss(endReason);
+    },
+    [onDismiss, session.id],
+  );
+
+  if (!banner) {
+    return null;
+  }
+  if (needsWebView) {
+    if (!webView) {
+      if (!warnedMissingWebView) {
+        warnedMissingWebView = true;
+        console.warn(
+          'Userflow: WebView banner requires react-native-webview in the native binary. ' +
+            'Add it to your app (e.g. npx expo install react-native-webview), run pod install under ios/, ' +
+            'then rebuild with expo run:ios (not Expo Go). Falling back to the native banner bar.',
+        );
+      }
+      return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+    }
+    return (
+      <BannerWebViewBar session={session} onActions={onActions} onDismiss={dismissWebViewBanner} />
+    );
+  }
+  return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+}
+
+/** @internal */
+export function resetBannerSurfaceWarningsForTests(): void {
+  warnedMissingWebView = false;
+}