@webotme/react-native 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webotme/react-native",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Drop-in AI chatbot for React Native and Expo apps. Same bot, training and AutoFlow as the WebotMe web widget.",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/AutoFlowExecutor.tsx

@@ -11,6 +11,7 @@ import {
   View,
   type ViewStyle,
 } from "react-native";
+import { routeTargetFromUrl } from "./navigationAdapter";
 import type {
   WebotMeAction,
   WebotMePendingWorkflow,
@@ -94,8 +95,12 @@ export function AutoFlowExecutor({
           case "navigate": {
             const url = action.data?.url;
             if (!url) throw new Error("Navigate action missing URL");
-            
-            // Try to match with known app routes first
+
+            // Resolve the raw URL/path into a real expo-router path + a
+            // friendly PascalCase name for React Navigation named screens.
+            const target = routeTargetFromUrl(url);
+
+            // Try to match known app routes first (named screens).
             const routeMap: Record<string, string> = {
               "/dashboard": "Dashboard",
               "/dashboard/create": "CreateChatbot",
@@ -106,15 +111,21 @@ export function AutoFlowExecutor({
               "/plans": "Plans",
               "/login": "Login",
             };
-            
-            const routeName = routeMap[url] || url.replace(/^\//, "").replace(/\//g, "_") || "Home";
-            
+
+            const routeName = routeMap[url] || target.name;
+            const params = {
+              fromAutoFlow: true,
+              originalUrl: url,
+              screenName: routeName,
+              route: target.route,
+            };
+
             if (push) {
-              push(routeName, { fromAutoFlow: true, originalUrl: url });
+              push(target.route, params);
             } else {
-              navigate(routeName, { fromAutoFlow: true, originalUrl: url });
+              navigate(target.route, params);
             }
-            
+
             return { success: true };
           }
 

package/src/chat.ts

@@ -6,6 +6,7 @@
  */
 import { useEffect, useState } from "react";
 import { WebotMeClient } from "./client";
+import { ensureRuntime } from "./runtime";
 import {
   WebotMeError,
   type WebotMeAction,
@@ -66,6 +67,7 @@ class ChatEngine {
   }
 
   configure(config: WebotMeConfig) {
+    ensureRuntime();
     const nextClient = new WebotMeClient({
       botId: config.botId,
       apiBaseUrl: config.apiBaseUrl,

package/src/executor.ts

@@ -2,6 +2,7 @@ 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 = {
@@ -14,27 +15,13 @@ export type ExecutorOptions = {
 };
 
 let handlers: ExecutorOptions | null = null;
+let currentUnsub: (() => void) | null = null;
 const executedMessageIds = new Set<string>();
 
-function routeNameFromUrl(url: string): string {
-  const match = /^([^?#]+)/.exec(url)?.[1] ?? url;
-  const trimmed = match.replace(/^\/+|\/+$/g, "");
-  if (!trimmed) return "Home";
-  const parts = trimmed.split("/").map((part) =>
-    part.charAt(0).toUpperCase() + part.slice(1),
-  );
-  return parts.join(":");
-}
-
-function defaultNavigate(routeName: string, params?: Record<string, any>) {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const router = require("expo-router").default ?? require("expo-router").router;
-    router?.push?.(routeName as any);
-    return true;
-  } catch {
-    return false;
-  }
+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. */
@@ -49,17 +36,55 @@ export async function executeAction(action: WebotMeAction): Promise<{ success: b
       case "navigate": {
         const url = (action.data as any)?.url;
         if (!url) throw new Error("Navigate action missing URL");
-        const name = routeNameFromUrl(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(name, { fromAutoFlow: true, originalUrl: url });
+          doNavigate(target.route, params);
           return { success: true };
         }
         if (handlers?.push) {
-          handlers.push(name, { fromAutoFlow: true, originalUrl: url });
+          handlers.push(target.route, params);
           return { success: true };
         }
-        const ok = defaultNavigate(url);
-        if (!ok) throw new Error(`No navigation handler for "${url}"`);
+        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": {
@@ -124,6 +149,7 @@ export async function executeActions(actions: WebotMeAction[]): Promise<void> {
  */
 export function setupExecutor(options?: ExecutorOptions): () => void {
   handlers = options ?? handlers ?? {};
+  if (currentUnsub) return currentUnsub;
   const unsubscribe = subscribeChat(() => {
     const { messages } = getChatState();
     for (const message of messages) {
@@ -147,10 +173,18 @@ export function setupExecutor(options?: ExecutorOptions): () => void {
       });
     }
   });
-  return () => unsubscribe();
+  currentUnsub = () => {
+    unsubscribe();
+    currentUnsub = null;
+  };
+  return currentUnsub;
 }
 
 export function resetExecutorState() {
   executedMessageIds.clear();
   handlers = null;
+  if (currentUnsub) {
+    currentUnsub();
+    currentUnsub = null;
+  }
 }

package/src/index.ts

@@ -35,6 +35,7 @@ export {
 export type { VoiceOptions, VoiceResult, VoiceState } from "./voice";
 
 export { WebotMeError } from "./types";
+export { ensureRuntime } from "./runtime";
 export {
   executeAction,
   executeActions,
@@ -46,6 +47,8 @@ export {
   getCurrentRoute,
   goBack,
   navigateTo,
+  pushRoute,
+  routeTargetFromUrl,
   setCurrentRoute,
   useNavigationAdapter,
 } from "./navigationAdapter";

package/src/navigationAdapter.ts

@@ -11,15 +11,74 @@ 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;
-    if (params) (router as any)?.push?.({ pathname: route as any, params } as any);
-    else (router as any)?.push?.(route as any);
+    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 {
-    /* no router available */
+    return false;
   }
 }
 

package/src/provider.tsx

@@ -19,6 +19,7 @@ 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,
@@ -165,6 +166,36 @@ 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;

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;
+  }
+}

package/src/screenScanner.tsx

@@ -344,8 +344,14 @@ export function setupFiberScanner(options?: {
   intervalMs?: number;
   onScan?: (ctx: WebotMeScreenContext) => void;
 }): () => void {
-  stopFiberScanner();
   const interval = options?.intervalMs ?? 2000;
+  // Idempotent: if a scanner is already running, just refresh the snapshot and
+  // keep the single timer (avoids duplicate intervals when the provider arms
+  // after an app already called chatWithUs/configureChat).
+  if (scanTimer) {
+    scanScreen();
+    return stopFiberScanner;
+  }
   scanScreen();
   scanTimer = setInterval(() => {
     const ctx = scanScreen();

package/src/voice.ts

@@ -33,23 +33,22 @@ export type VoiceState =
 export type VoiceOptions = {
   /** BCP-47 language for both recognition and speech. Default "en-US". */
   lang?: string;
-  /** Speaking speed, 0.5–2. Default 0.9 (same pace the web widget uses). */
   rate?: number;
-  /** Speaking pitch, 0.5–2. Default 1. */
   pitch?: number;
-  /**
-   * Speak every bot reply, including ones the user typed. Default false, so
-   * only answers to spoken questions are read out.
-   */
   speakAllReplies?: boolean;
-  /** Silence in ms that finalises the spoken query. Default 2200. */
   silenceTimeout?: number;
   onStateChange?: (state: VoiceState) => void;
-  /** Interim transcript, updated live while the user speaks. */
   onPartial?: (text: string) => void;
-  /** Final transcript once the user stops talking. */
   onUserQuery?: (text: string) => void;
   onError?: (message: string) => void;
+  /** Wake words that enable the bot once recognised (e.g. ["hello botName"]). */
+  activateCommands?: string[];
+  /** Shuts down voice once recognised (e.g. ["off botName"]). */
+  shutdownCommands?: string[];
+  /** Name used to substitute {botName} in the activation/shutdown phrases. */
+  botName?: string;
+  onActivated?: (transcript: string) => void;
+  onDeactivated?: (transcript: string) => void;
 };
 
 /** What `voiceWithUs` hands back, mirroring `ChatResult`. */
@@ -76,6 +75,14 @@ type SpeechLike = {
 
 type SpeechEvent = { results?: Array<{ transcript?: string } | string> };
 
+function normalizeTranscript(v: unknown): string {
+  return String(v ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
 type SpeechRecognitionLike = {
   start: (options?: Record<string, unknown>) => Promise<void> | void;
   stop: () => Promise<void> | void;
@@ -191,6 +198,8 @@ class VoiceEngine {
   private speaking = false;
   private continuous = false;
   private loopStopped = false;
+  private activated = true;
+  private commandsConfigured = false;
 
   constructor() {
     this.state = {
@@ -227,6 +236,16 @@ class VoiceEngine {
     if (typeof options.speakAllReplies === "boolean") {
       this.patch({ voiceReplies: options.speakAllReplies });
     }
+    if (Array.isArray(options.activateCommands) && options.activateCommands.length > 0) {
+      // Lock voice until an activation phrase is heard, but only the first time
+      // the commands are applied so re-configuring never re-locks a live bot.
+      if (!this.commandsConfigured) this.activated = false;
+      this.commandsConfigured = true;
+    } else if (options.activateCommands !== undefined) {
+      // Commands were explicitly cleared -> fall back to always-available voice.
+      this.commandsConfigured = false;
+      this.activated = true;
+    }
     this.patch({ supported: this.isSupported() });
   }
 
@@ -363,10 +382,110 @@ class VoiceEngine {
     }
   }
 
+  /** [a-z0-9] tokens that make up the bot's name (used for phrase matching). */
+  private static botNameTokens(botName: string): string[] {
+    return String(botName || "assistant")
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean);
+  }
+
+  /** Remove every mention of the bot's name from a lowercase phrase. */
+  private static stripName(text: string, botName: string): string {
+    const tokens = VoiceEngine.botNameTokens(botName);
+    if (tokens.length === 0) return text;
+    let clean = " " + (text || "").toLowerCase() + " ";
+    for (const token of tokens) {
+      if (!token) continue;
+      clean = clean.replace(
+        new RegExp(`(^|[^a-z0-9])${token}(?=$|[^a-z0-9])`, "g"),
+        "$1 ",
+      );
+    }
+    return clean.replace(/\s+/g, " ").trim();
+  }
+
+  /**
+   * True when the spoken phrase matches one of the commands. The bot name is
+   * matched both inside the phrase and without it, so "hello rover", "hello",
+   * and "hey rover" all activate when the command is "hello {botName}".
+   */
+  private static matchesAny(
+    normalized: string,
+    commands: string[] | undefined,
+    botName: string,
+  ): boolean {
+    if (!Array.isArray(commands) || commands.length === 0) return false;
+    const stripped = VoiceEngine.stripName(normalized, botName);
+    return commands.some((cmd) => {
+      const raw = cmd
+        .toLowerCase()
+        .replace(/{botname}/g, botName.toLowerCase())
+        .replace(/\s+/g, " ")
+        .trim();
+      if (!raw) return false;
+      if (normalized.includes(raw)) return true;
+      const rawNoName = VoiceEngine.stripName(raw, botName);
+      if (!rawNoName) return false;
+      return stripped.includes(rawNoName) || stripped === rawNoName;
+    });
+  }
+
   private async askBot(transcript: string) {
+    const normalized = transcript.toLowerCase().replace(/[^a-z0-9\s]/gi, "").trim();
+    const botName = this.options.botName || "assistant";
+    const wantsActivation = VoiceEngine.matchesAny(normalized, this.options.activateCommands, botName);
+    const wantsShutdown = VoiceEngine.matchesAny(normalized, this.options.shutdownCommands, botName);
+
+    if (wantsShutdown) {
+      this.activated = false;
+      this.options.onDeactivated?.(transcript);
+      this.continuous = false;
+      this.loopStopped = true;
+      this.stop();
+      this.finishSession({
+        ok: true,
+        transcript,
+        reply: "",
+        userMessage: null,
+        botMessage: null,
+        spoken: false,
+      });
+      return;
+    }
+
+    if (this.options.activateCommands && this.options.activateCommands.length > 0) {
+      if (!this.activated) {
+        if (wantsActivation) {
+          this.activated = true;
+          this.options.onActivated?.(transcript);
+        } else {
+          // Ignore everything before activation; start loop again if continuous.
+          if (this.continuous && !this.loopStopped) {
+            this.continueLoop();
+          } else {
+            this.finishSession({
+              ok: true,
+              transcript,
+              reply: "",
+              userMessage: null,
+              botMessage: null,
+              spoken: false,
+            });
+          }
+          return;
+        }
+      }
+    }
+
+    // Send the phrase without the bare bot-name mention (like the web engine),
+    // so "hello rover" reaches the bot as just "hello".
+    const forwardText = VoiceEngine.stripName(transcript, botName) || transcript;
+
     let result: ChatResult;
     try {
-      result = await chatWithUs(transcript);
+      result = await chatWithUs(forwardText);
     } catch (err) {
       // chatWithUs already reports its own failures, so this is a real crash.
       this.fail(
@@ -460,7 +579,7 @@ class VoiceEngine {
     if (this.state.state === "speaking") this.patch({ state: "idle" });
   }
 
-  /** Stop listening and speaking without settling the promise. */
+  /** Stop listening and speaking; a pending `voiceWithUs()` promise resolves. */
   stop() {
     if (this.settleTimer) {
       clearTimeout(this.settleTimer);
@@ -475,6 +594,17 @@ class VoiceEngine {
     if (this.state.state === "listening" || this.state.state === "thinking" || this.state.state === "speaking") {
       this.patch({ state: "idle" });
     }
+    // Never leave a caller hanging on `await voiceWithUs()`.
+    if (this.resolveSession) {
+      this.finishSession({
+        ok: true,
+        transcript: this.transcript.trim(),
+        reply: "",
+        userMessage: null,
+        botMessage: null,
+        spoken: false,
+      });
+    }
   }
 
   /** A recogniser failure mid-session: report it and go back to idle. */