@userflow-tech/react-native 0.1.0

package/src/content/types.ts

@@ -0,0 +1,189 @@
+/** Slate-shaped TreeDoc types (web `rich2` / `plaintext2`) — MVP subset for RN. */
+
+export type LookupAttribute = (fqn: string) => string | null;
+
+export type BlockAlign = 'left' | 'center' | 'right';
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+export type JustifyContent =
+  | 'start'
+  | 'end'
+  | 'center'
+  | 'space-between'
+  | 'space-evenly'
+  | 'space-around';
+export type LinkTarget = 'same' | 'new';
+export type BlockWidthMode = 'fill' | 'percent' | 'px';
+
+export interface RichContentDoc {
+  type: 'rich2';
+  children: RichContentBlockElement[];
+}
+
+export type RichContentDescendant = RichContentElement | RichContentText;
+
+export type RichContentElement =
+  | RichContentBlockElement
+  | RichContentInlineElement
+  | ListItemElement
+  | ButtonElement
+  | ColumnElement;
+
+export type RichContentBlockElement =
+  | ButtonGroupElement
+  | CodeBlockElement
+  | ColumnGroupElement
+  | ContainerElement
+  | Heading1Element
+  | Heading2Element
+  | ImageElement
+  | OrderedListElement
+  | ParagraphElement
+  | QuoteElement
+  | UnorderedListElement
+  | VideoElement
+  | QuestionElement;
+
+export type RichContentInlineElement = AttributeElement | LinkElement;
+export type RichContentInlineNode = RichContentInlineElement | RichContentText;
+
+export interface AbstractRichContentTextFormatting {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikeThrough?: boolean;
+  code?: boolean;
+  small?: boolean;
+  sup?: boolean;
+  color?: string;
+  silent?: boolean;
+}
+
+export interface RichContentText extends AbstractRichContentTextFormatting {
+  text: string;
+}
+
+export interface AttributeElement extends AbstractRichContentTextFormatting {
+  type: 'attribute';
+  attributeName?: string | null;
+  fallback?: string | null;
+  children: [{ text: '' }];
+}
+
+export interface ButtonElement {
+  type: 'button';
+  cvid: string;
+  clipboardData?: string;
+  children: [{ text: '' }];
+}
+
+export interface ButtonGroupElement {
+  type: 'button-group';
+  align?: JustifyContent;
+  children: ButtonElement[];
+}
+
+export interface QuestionElement {
+  type: 'question';
+  cvid: string;
+  clipboardData?: string;
+  children: [{ text: '' }];
+}
+
+export interface ColumnElement {
+  type: 'column';
+  children: RichContentBlockElement[];
+}
+
+export interface ColumnGroupElement {
+  type: 'column-group';
+  children: ColumnElement[];
+}
+
+export interface ContainerElement {
+  type: 'container';
+  children: RichContentBlockElement[];
+}
+
+export interface ImageElement {
+  type: 'image';
+  src?: string | PlaintextDoc | null;
+  widthMode?: BlockWidthMode | null;
+  displayWidth?: number | null;
+  width?: number | null;
+  height?: number | null;
+  align?: BlockAlign | null;
+  hasLink?: boolean;
+  href?: PlaintextDoc | null;
+  target?: LinkTarget;
+  children: [{ text: '' }];
+}
+
+export interface LinkElement {
+  type: 'link';
+  href?: PlaintextDoc | null;
+  target?: LinkTarget;
+  children: RichContentInlineNode[];
+}
+
+export interface AbstractTextBlockElement {
+  align?: TextAlign | null;
+  children: RichContentInlineNode[];
+}
+
+export interface ParagraphElement extends AbstractTextBlockElement {
+  type: 'paragraph';
+}
+
+export interface Heading1Element extends AbstractTextBlockElement {
+  type: 'heading1';
+}
+
+export interface Heading2Element extends AbstractTextBlockElement {
+  type: 'heading2';
+}
+
+export interface QuoteElement extends AbstractTextBlockElement {
+  type: 'quote';
+}
+
+export interface CodeBlockElement {
+  type: 'code-block';
+  children: RichContentInlineNode[];
+}
+
+export interface OrderedListElement {
+  type: 'ordered-list';
+  children: ListItemElement[];
+}
+
+export interface UnorderedListElement {
+  type: 'unordered-list';
+  children: ListItemElement[];
+}
+
+export interface ListItemElement {
+  type: 'list-item';
+  children: RichContentInlineNode[];
+}
+
+export interface VideoElement {
+  type: 'video';
+  children: [{ text: '' }];
+}
+
+export interface PlaintextDoc {
+  type: 'plaintext2';
+  children: [PlaintextRootElement];
+}
+
+export type PlaintextElement = PlaintextRootElement | AttributeElement;
+export type PlaintextInlineNode = AttributeElement | PlaintextText;
+
+export interface PlaintextRootElement {
+  type: 'plaintext';
+  children: PlaintextInlineNode[];
+}
+
+export interface PlaintextText {
+  text: string;
+}

package/src/deepLinking.ts

@@ -0,0 +1,182 @@
+/**
+ * Inbound deep-link handling for builder preview.
+ *
+ * Host apps register their environment's `scheme_id` (e.g. `userflow-257587`) as
+ * a URL scheme at build time. The SDK matches inbound URLs by prefix + root
+ * query (no init config) and starts a draft flow via `StartFlowWithToken` once
+ * a user is identified.
+ */
+
+import { Linking } from 'react-native';
+
+/** Scheme prefix required for Userflow deep links (build-time registration). */
+export const USERFLOW_URL_SCHEME_PREFIX = 'userflow-';
+
+export interface ParsedPreviewDeepLink {
+  token: string;
+}
+
+export interface DeepLinkStartFlowWithToken {
+  (token: string): Promise<void>;
+}
+
+export interface DeepLinkingDeps {
+  /** Whether a user is currently identified (channel ready to send). */
+  isIdentified: () => boolean;
+  /** Send StartFlowWithToken once identified. */
+  startFlowWithToken: DeepLinkStartFlowWithToken;
+  /** Optional Linking overrides for tests. */
+  linking?: {
+    getInitialURL: () => Promise<string | null>;
+    addEventListener: (
+      type: 'url',
+      handler: (event: { url: string }) => void,
+    ) => { remove: () => void };
+  };
+}
+
+let deps: DeepLinkingDeps | null = null;
+let pendingToken: string | null = null;
+let lastHandledToken: string | null = null;
+let urlSubscription: { remove: () => void } | null = null;
+let started = false;
+
+function getLinking(): NonNullable<DeepLinkingDeps['linking']> {
+  return (
+    deps?.linking ?? {
+      getInitialURL: () => Linking.getInitialURL(),
+      addEventListener: (type, handler) => Linking.addEventListener(type, handler),
+    }
+  );
+}
+
+/**
+ * Parse a Userflow preview deep link.
+ * Accepts `userflow-*://?token=...` (root form).
+ *
+ * A root URL carrying `pairing_token` instead of `token` is a pairing link —
+ * leave it for {@link inspectPairingDeepLink}.
+ */
+export function parsePreviewDeepLink(url: string): ParsedPreviewDeepLink | null {
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (!schemeMatch?.[1]) return null;
+  const scheme = schemeMatch[1];
+  if (!scheme.toLowerCase().startsWith(USERFLOW_URL_SCHEME_PREFIX)) {
+    return null;
+  }
+
+  // Custom schemes need a rewrite so root forms (`://?token=…`) parse.
+  const remainder = trimmed.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 null;
+  }
+
+  // Pairing wins at the root when both query shapes could apply.
+  if (parsed.searchParams.has('pairing_token')) {
+    return null;
+  }
+
+  const host = parsed.hostname.toLowerCase();
+  const path = parsed.pathname.replace(/\/+$/, '') || '/';
+  const isRoot = (host === '' || host === 'userflow.local') && (path === '' || path === '/');
+  if (!isRoot) {
+    return null;
+  }
+
+  const token = parsed.searchParams.get('token')?.trim() ?? '';
+  if (!token) {
+    return null;
+  }
+
+  return { token };
+}
+
+async function applyToken(token: string): Promise<void> {
+  if (!deps) return;
+
+  if (lastHandledToken === token) {
+    return;
+  }
+
+  if (!deps.isIdentified()) {
+    pendingToken = token;
+    return;
+  }
+
+  pendingToken = null;
+  lastHandledToken = token;
+  await deps.startFlowWithToken(token);
+}
+
+/**
+ * Handle an inbound URL. Returns true when it was a Userflow preview deep link.
+ */
+export async function didHandleURL(url: string): Promise<boolean> {
+  const parsed = parsePreviewDeepLink(url);
+  if (!parsed) {
+    return false;
+  }
+  await applyToken(parsed.token);
+  return true;
+}
+
+/** Flush a buffered preview token after identify (no-op if none / not identified). */
+export async function flushPendingPreviewToken(): Promise<void> {
+  if (!deps || !pendingToken || !deps.isIdentified()) {
+    return;
+  }
+  const token = pendingToken;
+  pendingToken = null;
+  lastHandledToken = token;
+  await deps.startFlowWithToken(token);
+}
+
+/** Wire dependencies and start Listening for inbound URLs. Idempotent. */
+export function startDeepLinking(nextDeps: DeepLinkingDeps): void {
+  deps = nextDeps;
+  if (started) {
+    return;
+  }
+  started = true;
+
+  const linking = getLinking();
+  void linking.getInitialURL().then((url) => {
+    if (url) {
+      void didHandleURL(url);
+    }
+  });
+
+  urlSubscription = linking.addEventListener('url', ({ url }) => {
+    void didHandleURL(url);
+  });
+}
+
+/** Stop Listening and clear buffered preview state. */
+export function stopDeepLinking(): void {
+  urlSubscription?.remove();
+  urlSubscription = null;
+  started = false;
+  pendingToken = null;
+  lastHandledToken = null;
+  deps = null;
+}
+
+/** Test helper: inspect buffered token without flushing. */
+export function __getPendingPreviewTokenForTests(): string | null {
+  return pendingToken;
+}
+
+/** Test helper: reset module state between suites. */
+export function __resetDeepLinkingForTests(): void {
+  stopDeepLinking();
+}

package/src/expo-router/UserflowExpoRouterScreenTracker.tsx

@@ -0,0 +1,7 @@
+import { useUserflowExpoRouter } from './useUserflowExpoRouter';
+
+/** Invisible component that wires Expo Router pathname tracking into the SDK. */
+export function UserflowExpoRouterScreenTracker(): null {
+  useUserflowExpoRouter();
+  return null;
+}

package/src/expo-router/getExpoRouterScreenTracker.ts

@@ -0,0 +1,49 @@
+import type { ComponentType } from 'react';
+
+let cached: ComponentType | null | undefined;
+
+/**
+ * Returns the Expo Router screen tracker when a real `expo-router` peer is
+ * installed (both `usePathname` and `useRouter`), otherwise `null`.
+ *
+ * Not part of the public API — hosts mount {@link UserflowExpoRouterScreenTracker}
+ * from `@userflow-tech/react-native/expo-router`. Kept for unit tests that probe
+ * partial / absent `expo-router` stubs.
+ */
+export function getExpoRouterScreenTracker(): ComponentType | null {
+  if (cached !== undefined) return cached;
+
+  if (typeof require !== 'function') {
+    cached = null;
+    return cached;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer probe
+    const expoRouter = require('expo-router') as {
+      usePathname?: unknown;
+      useRouter?: unknown;
+    };
+    if (
+      typeof expoRouter?.usePathname !== 'function' ||
+      typeof expoRouter?.useRouter !== 'function'
+    ) {
+      cached = null;
+      return cached;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('./UserflowExpoRouterScreenTracker') as {
+      UserflowExpoRouterScreenTracker: ComponentType;
+    };
+    cached = mod.UserflowExpoRouterScreenTracker;
+  } catch {
+    cached = null;
+  }
+
+  return cached;
+}
+
+/** @internal Resets module cache between tests. */
+export function resetExpoRouterScreenTrackerCacheForTests(): void {
+  cached = undefined;
+}

package/src/expo-router/index.ts

@@ -0,0 +1,2 @@
+export { useUserflowExpoRouter } from './useUserflowExpoRouter';
+export { UserflowExpoRouterScreenTracker } from './UserflowExpoRouterScreenTracker';

package/src/expo-router/useUserflowExpoRouter.ts

@@ -0,0 +1,40 @@
+import { usePathname, useRouter } from 'expo-router';
+import { useEffect } from 'react';
+
+import { setExpoRouterNavigator } from '../navigation/openFlowNavigateUrl';
+import { handleScreenChange } from '../screenTracker';
+
+/**
+ * Tracks Expo Router pathname changes for Userflow screen detection and
+ * registers `router.push` for path-like flow NAVIGATE actions.
+ *
+ * Mount via {@link UserflowExpoRouterScreenTracker} from
+ * `@userflow-tech/react-native/expo-router` under {@link UserflowProvider}. Do not
+ * 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`).
+ *
+ * Screen tracking ≠ action routing: NAVIGATE for in-app paths uses the router
+ * handle registered here; http(s)/mailto/tel still go through Linking.
+ */
+export function useUserflowExpoRouter(): void {
+  const pathname = usePathname();
+  const router = useRouter();
+
+  useEffect(() => {
+    handleScreenChange(pathname ? { path: pathname } : undefined);
+  }, [pathname]);
+
+  useEffect(() => {
+    setExpoRouterNavigator({
+      push: (href) => {
+        router.push(href as never);
+      },
+    });
+    return () => {
+      setExpoRouterNavigator(null);
+    };
+  }, [router]);
+}