@webotme/react-native 0.1.1 → 0.1.3

package/src/executor.ts

@@ -0,0 +1,190 @@
+import { Alert, Linking } from "react-native";
+import { getChatState, nextAutoFlowStep, subscribeChat } from "./chat";
+import { isActionAllowed } from "./safety";
+import { findClickHandler, findFillHandler } from "./screenScanner";
+import { routeTargetFromUrl, pushRoute, getCurrentRoute } from "./navigationAdapter";
+import type { WebotMeAction, WebotMeMessage } from "./types";
+
+export type ExecutorOptions = {
+  /** Called to navigate; defaults to expo-router when available. */
+  navigate?: (routeName: string, params?: Record<string, any>) => void;
+  goBack?: () => void;
+  push?: (routeName: string, params?: Record<string, any>) => void;
+  /** Called after every action attempt. */
+  onActionExecuted?: (action: WebotMeAction, success: boolean, error?: string) => void;
+};
+
+let handlers: ExecutorOptions | null = null;
+let currentUnsub: (() => void) | null = null;
+const executedMessageIds = new Set<string>();
+
+function defaultNavigate(routeName: string, fallbackName?: string, params?: Record<string, any>) {
+  if (pushRoute(routeName, params)) return true;
+  if (fallbackName && pushRoute(fallbackName, params)) return true;
+  return false;
+}
+
+/** Run a single server action on the device. */
+export async function executeAction(action: WebotMeAction): Promise<{ success: boolean; error?: string }> {
+  const doNavigate = handlers?.navigate;
+  try {
+    // Block/confirm at the gate before doing anything on the device.
+    const allowed = await isActionAllowed(action);
+    if (!allowed) return { success: false, error: "Blocked or declined by safety layer" };
+
+    switch (action.type) {
+      case "navigate": {
+        const url = (action.data as any)?.url;
+        if (!url) throw new Error("Navigate action missing URL");
+        // Resolve the raw URL (full URL, path, or native://screen) into a real
+        // route path so router.push actually moves the app — the friendly name
+        // is only used as a fallback for React Navigation named screens.
+        const target = routeTargetFromUrl(url);
+        const params = {
+          fromAutoFlow: true,
+          originalUrl: url,
+          screenName: target.name,
+          route: target.route,
+        };
+        if (doNavigate) {
+          doNavigate(target.route, params);
+          return { success: true };
+        }
+        if (handlers?.push) {
+          handlers.push(target.route, params);
+          return { success: true };
+        }
+        const before = getCurrentRoute();
+        const ok = defaultNavigate(target.route, target.name, params);
+        if (!ok) {
+          // No expo-router stack is available — the app may use tabs or a
+          // custom layout. Fall back to tapping a matching control on-screen
+          // (e.g. the "Settings" tab) so the bot's promise still lands.
+          const tapper =
+            findClickHandler(target.name) ||
+            findClickHandler((action.data as any)?.label) ||
+            findClickHandler((action.data as any)?.text);
+          if (tapper) {
+            tapper();
+            return { success: true };
+          }
+          throw new Error(`No navigation handler for "${url}"`);
+        }
+        // Give expo-router a beat to move; if nothing changed, the route likely
+        // doesn't exist, so tap a same-named tab/button instead of reporting a
+        // success that never happened.
+        await new Promise((resolve) => setTimeout(resolve, 800));
+        const after = getCurrentRoute();
+        if (after === before && after !== target.route) {
+          const tapper =
+            findClickHandler(target.name) ||
+            findClickHandler((action.data as any)?.label) ||
+            findClickHandler((action.data as any)?.text);
+          if (tapper) {
+            tapper();
+            return { success: true };
+          }
+        }
+        return { success: true };
+      }
+      case "click": {
+        const label =
+          (action.data as any)?.text ??
+          (action.data as any)?.selector ??
+          (action.data as any)?.label;
+        const h = findClickHandler(label);
+        if (h) {
+          h();
+          return { success: true };
+        }
+        console.warn("[WebotMe executor] click action has no ref binding:", action.data);
+        return { success: true };
+      }
+      case "fill": {
+        const label =
+          (action.data as any)?.label ??
+          (action.data as any)?.selector ??
+          (action.data as any)?.name;
+        const value = (action.data as any)?.text;
+        const setter = findFillHandler(label);
+        if (setter) {
+          setter(typeof value === "string" ? value : String(value ?? ""));
+          return { success: true };
+        }
+        console.log(
+          `[WebotMe executor] fill "${label}" -> "${value}" -- no matching input found.`,
+        );
+        return { success: true };
+      }
+      case "checkout": {
+        const url = (action.data as any)?.url;
+        if (!url) throw new Error("Checkout action missing URL");
+        await Linking.openURL(url);
+        return { success: true };
+      }
+      default:
+        return { success: false, error: `Unknown action type: ${(action as any).type}` };
+    }
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : "Unknown error" };
+  }
+}
+
+/** Run the actions a bot returns on its message, in order. */
+export async function executeActions(actions: WebotMeAction[]): Promise<void> {
+  for (const action of actions.slice(0, 20)) {
+    const result = await executeAction(action);
+    handlers?.onActionExecuted?.(action, result.success, result.error);
+    if (!result.success) {
+      Alert.alert("Action Failed", result.error || "Unknown error");
+      break;
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+}
+
+/**
+ * Arm the executor: it watches the shared chat engine and runs each bot action
+ * exactly once. Returns a disposer.
+ */
+export function setupExecutor(options?: ExecutorOptions): () => void {
+  handlers = options ?? handlers ?? {};
+  if (currentUnsub) return currentUnsub;
+  const unsubscribe = subscribeChat(() => {
+    const { messages } = getChatState();
+    for (const message of messages) {
+      if (!message || message.from !== "bot" || executedMessageIds.has(message.id)) continue;
+      const actions = message.actions && message.actions.length > 0
+        ? message.actions
+        : message.action
+          ? [message.action]
+          : [];
+      if (actions.length === 0) continue;
+      executedMessageIds.add(message.id);
+      void executeActions(actions).then(() => {
+        // If we're inside an AutoFlow task, let the server decide the next step.
+        const state = getChatState();
+        if (state.autoTask && state.autoTask.goal) {
+          // Wait for the screen to settle so the next step sees fresh screenContext.
+          setTimeout(() => {
+            void nextAutoFlowStep();
+          }, 2500);
+        }
+      });
+    }
+  });
+  currentUnsub = () => {
+    unsubscribe();
+    currentUnsub = null;
+  };
+  return currentUnsub;
+}
+
+export function resetExecutorState() {
+  executedMessageIds.clear();
+  handlers = null;
+  if (currentUnsub) {
+    currentUnsub();
+    currentUnsub = null;
+  }
+}

package/src/index.ts

@@ -10,7 +10,64 @@ export type { WebotMeLauncherProps, LauncherPosition } from "./launcher";
 export { WebotMeClient } from "./client";
 export type { SendResult } from "./client";
 
+export {
+  chatWithUs,
+  configureChat,
+  resetChat,
+  updateChatScreenContext,
+  useChat,
+  subscribeChat,
+  getChatState,
+  getChatSessionId,
+} from "./chat";
+export type { ChatResult } from "./chat";
+
+export {
+  configureVoice,
+  isVoiceSupported,
+  setVoiceReplies,
+  speakReplyIfEnabled,
+  speakWithUs,
+  stopVoice,
+  useVoiceChat,
+  voiceWithUs,
+} from "./voice";
+export type { VoiceOptions, VoiceResult, VoiceState } from "./voice";
+
 export { WebotMeError } from "./types";
+export { ensureRuntime } from "./runtime";
+export {
+  executeAction,
+  executeActions,
+  resetExecutorState,
+  setupExecutor,
+  type ExecutorOptions,
+} from "./executor";
+export {
+  getCurrentRoute,
+  goBack,
+  navigateTo,
+  pushRoute,
+  routeTargetFromUrl,
+  setCurrentRoute,
+  useNavigationAdapter,
+} from "./navigationAdapter";
+export {
+  isActionAllowed,
+  isBlocked,
+  needsConfirmation,
+  requireConfirmation,
+  setupSafetyLayer,
+} from "./safety";
+export {
+  registerScreenTree,
+  scanScreen,
+  setupFiberScanner,
+  stopFiberScanner,
+  useFiberScanner,
+  findClickHandler,
+  findFillHandler,
+} from "./screenScanner";
 export type {
   WebotMeAction,
   WebotMeButton,

package/src/lazy-webview.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import { StyleSheet, Text, View } from "react-native";
+
+/**
+ * `react-native-webview` is a native module, so importing it at the top of a
+ * file breaks any app that runs in Expo Go or a plain JS bundle. The web
+ * variant is the only thing that needs it, so it is resolved on first render
+ * instead — apps that only use `chatWithUs` never touch it.
+ */
+
+type AnyProps = Record<string, unknown>;
+
+function MissingWebView() {
+  return (
+    <View style={styles.wrap}>
+      <Text style={styles.title}>Web chat needs a development build</Text>
+      <Text style={styles.body}>
+        react-native-webview is a native module, so it is not available in Expo Go.
+      </Text>
+      <Text style={styles.body}>
+        Run "npx expo run:android" / "npx expo run:ios", or use an EAS build. If you
+        only need text chat, use variant="native" or the chatWithUs function.
+      </Text>
+    </View>
+  );
+}
+
+let resolved: React.ComponentType<AnyProps> | null = null;
+
+export function loadWebView(): React.ComponentType<AnyProps> {
+  if (resolved) return resolved;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require("react-native-webview");
+    const candidate = mod?.WebView ?? mod?.default ?? mod;
+    resolved =
+      candidate && (typeof candidate === "function" || typeof candidate === "object")
+        ? (candidate as React.ComponentType<AnyProps>)
+        : MissingWebView;
+  } catch {
+    resolved = MissingWebView;
+  }
+
+  return resolved;
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+    padding: 24,
+    backgroundColor: "#0f172a",
+  },
+  title: { color: "#f8fafc", fontSize: 15, fontWeight: "700", textAlign: "center" },
+  body: { color: "#94a3b8", fontSize: 13, textAlign: "center", lineHeight: 19 },
+});

package/src/navigationAdapter.ts

@@ -0,0 +1,117 @@
+import { useEffect } from "react";
+
+let lastRoute = "";
+
+/** Last route seen by the app. */
+export function getCurrentRoute(): string {
+  return lastRoute;
+}
+
+export function setCurrentRoute(route: string): void {
+  lastRoute = route;
+}
+
+function toPascalName(route: string): string {
+  const trimmed = route.replace(/^\/+|\/+$/g, "");
+  if (!trimmed) return "Home";
+  const parts = trimmed.split("/").map((part) =>
+    part.charAt(0).toUpperCase() + part.slice(1),
+  );
+  return parts.join(":");
+}
+
+/**
+ * Turn any URL a server/AI returns into a navigation target that works with
+ * Expo Router (path-first) while keeping a friendly PascalCase name for apps
+ * using React Navigation named screens.
+ *
+ *  - "https://host/book"        -> { route: "/book", name: "Book" }
+ *  - "/dashboard/settings"      -> { route: "/dashboard/settings", name: "Dashboard:Settings" }
+ *  - "native://Select Doctor"   -> { route: "/select-doctor", name: "Select Doctor" }
+ *  - "checkout"                 -> { route: "/checkout", name: "Checkout" }
+ */
+export function routeTargetFromUrl(input?: string | null): { route: string; name: string } {
+  let url = String(input ?? "").trim();
+  if (!url || url === "/") return { route: "/", name: "Home" };
+
+  // Native screen snapshots come in as native://<screen name>.
+  if (/^native:\/\//i.test(url)) {
+    const screenName = decodeURIComponent(url.slice("native://".length)) || "Home";
+    const slug = screenName
+      .toLowerCase()
+      .replace(/\s+/g, "-")
+      .replace(/[^a-z0-9\-_/]/g, "");
+    return { route: "/" + slug, name: screenName };
+  }
+
+  // A full URL (from web scans) must become a bare path for expo-router.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith("//")) {
+    try {
+      url = new URL(url).pathname || "/";
+    } catch {
+      url = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, "") || "/";
+    }
+  }
+
+  // Strip query string and hash.
+  url = url.replace(/[?#].*$/, "");
+  url = "/" + url.replace(/^\/+/, "");
+  url = url.replace(/\/{2,}/g, "/");
+
+  return { route: url, name: toPascalName(url) };
+}
+
+/** Navigate imperatively using Expo Router's router. */
+export function navigateTo(route: string, params?: Record<string, any>): void {
+  pushRoute(route, params);
+}
+
+/** Internal helper that reports whether a push actually happened. */
+export function pushRoute(route: string, params?: Record<string, any>): boolean {
+  try {
+    const { route: target } = routeTargetFromUrl(route);
+    const router =
+      require("expo-router").default ?? require("expo-router").router;
+    const push = (router as any)?.push;
+    if (typeof push !== "function") return false;
+    if (params) push({ pathname: target as any, params } as any);
+    else push(target as any);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function goBack(): void {
+  try {
+    const router =
+      require("expo-router").default ?? require("expo-router").router;
+    (router as any)?.back?.();
+  } catch {
+    /* noop */
+  }
+}
+
+/**
+ * Bridge the live Expo Router pathname into the scanner's screen map. Call
+ * this once from a component that sits inside the router context.
+ */
+export function useNavigationAdapter(): { route: string | undefined; back: () => void } {
+  let pathname: string | undefined;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const usePathname = require("expo-router").usePathname as () => string | undefined;
+    // Expo Router provides this hook inside the app root; if it is missing the
+    // scanner/scanner route just stays blank.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    pathname = usePathname();
+  } catch {
+    pathname = undefined;
+  }
+
+  useEffect(() => {
+    if (pathname) setCurrentRoute(pathname);
+  }, [pathname]);
+
+  return { route: pathname, back: goBack };
+}

package/src/provider.tsx

@@ -1,5 +1,6 @@
 import React, {
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -7,6 +8,18 @@ import React, {
   useState,
 } from "react";
 import { WebotMeClient } from "./client";
+import {
+  chatWithUs,
+  configureChat,
+  resetChat,
+  updateChatScreenContext,
+  useChat,
+} from "./chat";
+import { registerScreenTree, setupFiberScanner } from "./screenScanner";
+import { setupExecutor } from "./executor";
+import { setupSafetyLayer } from "./safety";
+import { useNavigationAdapter } from "./navigationAdapter";
+import { configureVoice } from "./voice";
 import type {
   WebotMeConfig,
   WebotMeContract,
@@ -85,16 +98,50 @@ export function WebotMeProvider({
     [botId, apiBaseUrl, timeoutMs],
   );
 
+  // Feed the same bot into the one-function chat engine so `chatWithUs` works
+  // in apps that only mounted the provider and nothing else.
+  useEffect(() => {
+    configureChat({ botId, apiBaseUrl, userId, theme, welcome, screenContext, timeoutMs });
+    // Only re-run when the bot itself changes; message sends must not reset it.
+  }, [botId, apiBaseUrl, userId, welcome, timeoutMs]);
+
+  // Keep the element tree snapshot fresh for the screen scanner.
+  useEffect(() => {
+    registerScreenTree(children);
+  }, [children]);
+
+  // Auto-start the screen scanner so it can feed live screen context.
+  useEffect(() => {
+    const stop = setupFiberScanner({ intervalMs: 2500 });
+    return stop;
+  }, []);
+
+  // Arm the action executor so server-returned actions run on their own.
+  useEffect(() => {
+    const unsubscribe = setupExecutor();
+    return unsubscribe;
+  }, []);
+
+  // Default safety gate: confirm sensitive actions, block configured keywords.
+  useEffect(() => {
+    const reset = setupSafetyLayer();
+    return reset;
+  }, []);
+
+  useEffect(() => {
+    updateChatScreenContext(screenContext);
+  }, [screenContext]);
+
   // Stable visitor id for the lifetime of the app install.
   const visitorRef = useRef<string>(userId || makeId("v"));
-  const [sessionId, setSessionId] = useState(() => makeId("s"));
-  const [messages, setMessages] = useState<WebotMeMessage[]>([]);
-  const [sending, setSending] = useState(false);
-  const [error, setError] = useState<string | null>(null);
   const [contract, setContract] = useState<WebotMeContract | null>(null);
   const [attempt, setAttempt] = useState(0);
-  const [pendingWorkflow, setPendingWorkflow] = useState<WebotMePendingWorkflow | null>(null);
-  const [autoTask, setAutoTask] = useState<WebotMeAutoTask | null>(null);
+
+  // The engine owns the conversation so `chatWithUs` and `useWebotMeChat`
+  // always share one session and one transcript.
+  const engineState = useChat();
+  // Track the live route so the scanner + executor act on the current screen.
+  useNavigationAdapter();
 
   const chatBaseUrl = useMemo(
     () => (chatBaseUrlProp || apiBaseUrl).replace(/\/+$/, ""),
@@ -119,79 +166,60 @@ export function WebotMeProvider({
     };
   }, [client, attempt]);
 
+  // Pull the bot's activation/shutdown voice phrases from the server and arm
+  // the native voice engine with them ("hello {botName}" wakes it up, the
+  // shutdown phrase turns voice off). Mirrors the web widget exactly.
+  useEffect(() => {
+    let active = true;
+    client
+      .settings()
+      .then((raw: any) => {
+        if (!active) return;
+        const bot = raw?.chatbot ?? raw;
+        const botName = typeof bot?.name === "string" && bot.name.trim() ? bot.name.trim() : "Assistant";
+        const commands: string[] = Array.isArray(bot?.activation?.commands)
+          ? bot.activation.commands
+              .filter((c: unknown): c is string => typeof c === "string" && c.trim().length > 0)
+              .map((c: string) => c.replace(/{botName}/gi, botName).trim())
+          : [];
+        const activateCommands = commands.filter((c) => !/shutdown|bye|stop|off/i.test(c));
+        const shutdownCommands = commands.filter((c) => /shutdown|bye|stop|off/i.test(c));
+        if (activateCommands.length > 0 || shutdownCommands.length > 0) {
+          configureVoice({ botName, activateCommands, shutdownCommands });
+        }
+      })
+      .catch(() => {
+        // Settings unavailable -> voice stays always-on, matching the fallback.
+      });
+    return () => {
+      active = false;
+    };
+  }, [client]);
+
   // New session when the caller bumps resetKey.
   useEffect(() => {
     if (resetKey === undefined) return;
-    setSessionId(makeId("s"));
-    setMessages(welcome ? [botMessage(welcome)] : []);
-    setError(null);
-    setPendingWorkflow(null);
-    setAutoTask(null);
+    resetChat();
   }, [resetKey, welcome]);
 
-  const send = async (text: string) => {
-    const trimmed = text.trim();
-    if (!trimmed || sending) return;
-
-    const userMsg: WebotMeMessage = {
-      id: makeId("m"),
-      from: "user",
-      text: trimmed,
-      createdAt: Date.now(),
-    };
-    const pendingId = makeId("m");
-    setMessages((prev) => [
-      ...prev,
-      userMsg,
-      { id: pendingId, from: "bot", text: "", createdAt: Date.now(), pending: true },
-    ]);
-    setSending(true);
-    setError(null);
-
-    try {
-      const result = await client.send({
-        message: trimmed,
-        sessionId,
-        userId: visitorRef.current,
-        screenContext,
-      });
-      
-      // Handle new response format with actions, pendingWorkflow, autoTask
-      const botMsg: WebotMeMessage = {
-        id: pendingId,
-        from: "bot",
-        text: result.text || result.reply || "",
-        createdAt: Date.now(),
-        action: result.action ? result.actions?.[0] : undefined,
-      };
-      
-      setMessages((prev) =>
-        prev.map((m) =>
-          m.id === pendingId ? botMsg : m,
-        ),
-      );
-      
-      // Update workflow state
-      if (result.pendingWorkflow) {
-        setPendingWorkflow(result.pendingWorkflow);
-      } else if (result.autoTask) {
-        setAutoTask(result.autoTask);
-      } else if (!result.pendingWorkflow && !result.autoTask) {
-        // Only clear if server explicitly says no workflow
-        setPendingWorkflow(null);
-        setAutoTask(null);
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : "Something went wrong";
-      setError(message);
-      setMessages((prev) => prev.filter((m) => m.id !== pendingId));
-    } finally {
-      setSending(false);
-    }
-  };
+  const send = useCallback(
+    async (text: string) => {
+      await chatWithUs(text);
+    },
+    [],
+  );
 
   const retry = () => setAttempt((n) => n + 1);
-  const reset = () => setSessionId(makeId("s"));
+  const reset = () => resetChat();
+
+  const {
+    sessionId,
+    messages,
+    sending,
+    error,
+    pendingWorkflow,
+    autoTask,
+  } = engineState;
 
   const value = useMemo<WebotMeContextValue>(
     () => ({
@@ -221,6 +249,9 @@ export function WebotMeProvider({
       sending,
       error,
       contract,
+      send,
+      retry,
+      reset,
       pendingWorkflow,
       autoTask,
     ],
@@ -231,8 +262,4 @@ export function WebotMeProvider({
   );
 }
 
-function botMessage(text: string): WebotMeMessage {
-  return { id: makeId("m"), from: "bot", text, createdAt: Date.now() };
-}
-
 export type { WebotMeTheme } from "./types";

package/src/runtime.ts

@@ -0,0 +1,35 @@
+/**
+ * Self-healing runtime: apps that chat through `chatWithUs` without mounting
+ * `<WebotMeProvider>` should still get screen scanning, action execution and
+ * the safety gate. Everything here is idempotent, so double-arming (provider +
+ * manual call) is harmless.
+ *
+ * Modules are required lazily on purpose — `runtime` is imported by `chat`,
+ * and `executor`/`scanner` import `chat`, so top-level imports would form a
+ * cycle at module load time.
+ */
+
+let executorArmed = false;
+let scannerArmed = false;
+let safetyArmed = false;
+
+export function ensureRuntime(): void {
+  if (!executorArmed) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { setupExecutor } = require("./executor");
+    setupExecutor();
+    executorArmed = true;
+  }
+  if (!scannerArmed) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { setupFiberScanner } = require("./screenScanner");
+    setupFiberScanner({ intervalMs: 2500 });
+    scannerArmed = true;
+  }
+  if (!safetyArmed) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { setupSafetyLayer } = require("./safety");
+    setupSafetyLayer();
+    safetyArmed = true;
+  }
+}