@webotme/react-native 0.1.1

package/README.md

@@ -0,0 +1,189 @@
+# @webotme/react-native
+
+Drop-in AI chatbot for React Native and Expo. Same bot, same training and same
+AutoFlow as the WebotMe web widget.
+
+## Install
+
+```bash
+npm install @webotme/react-native react-native-webview
+```
+
+`react-native-webview` is a peer dependency — Expo apps can get it with
+`npx expo install react-native-webview`.
+
+> Requires a development build, not Expo Go, because `react-native-webview` is
+> a native module.
+
+## Use
+
+Wrap your app once, then show the widget anywhere.
+
+```tsx
+import { WebotMeProvider, WebotMeLauncher } from "@webotme/react-native";
+
+export default function App() {
+  return (
+    <WebotMeProvider
+      botId="YOUR_BOT_ID"
+      apiBaseUrl="https://your-api.com"
+      chatBaseUrl="https://your-frontend.com"
+    >
+      <RootNavigator />
+    </WebotMeProvider>
+  );
+}
+```
+
+Floating bubble (handles open/close automatically):
+
+```tsx
+import { WebotMeLauncher } from "@webotme/react-native";
+
+<WebotMeLauncher position="bottom-left" icon="💬" />
+```
+
+Inline chat (renders in place, no launcher needed):
+
+```tsx
+import { WebotMeWidget } from "@webotme/react-native";
+
+<WebotMeWidget mode="inline" />
+```
+
+Controlled modal (if you want your own trigger):
+
+```tsx
+import { WebotMeWidget } from "@webotme/react-native";
+import { useState } from "react";
+
+function ChatButton() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Pressable onPress={() => setOpen(true)}>
+        <Text>Open Chat</Text>
+      </Pressable>
+      <WebotMeWidget visible={open} onClose={() => setOpen(false)} />
+    </>
+  );
+}
+```
+
+## Config
+
+| Prop | Required | Description |
+| --- | --- | --- |
+| `botId` | yes | Bot ID from the WebotMe dashboard |
+| `apiBaseUrl` | yes | Backend base URL. Never `localhost` on a device |
+| `chatBaseUrl` | no | Frontend that serves `/chat/{botId}`. Falls back to `apiBaseUrl` |
+| `userId` | no | Stable visitor id. Generated if omitted |
+| `theme` | no | `primary`, `background`, `surface`, `text`, `muted` |
+| `welcome` | no | Message shown before the bot replies |
+| `screenContext` | no | Sent with every message so AutoFlow knows the screen |
+| `timeoutMs` | no | Default `30000` |
+| `resetKey` | no | Change it to start a new session |
+
+## Widget Props
+
+| Prop | Required | Description |
+| --- | --- | --- |
+| `mode` | no | `"modal"` (default) opens full-screen; `"inline"` renders in place |
+| `variant` | no | `"web"` (default) loads the Vercel chat page; `"native"` uses a native RN chat UI |
+| `visible` | no | Modal only — open when `true` (default `false`) |
+| `onClose` | no | Called when modal closes (modal only) |
+| `title` | no | Modal header title (modal/native) |
+| `theme` | no | Override `primary`, `background`, `surface`, `text`, `muted` |
+| `showClose` | no | Show header close button (modal/native, default `true`) |
+
+## AutoFlow
+
+Web AutoFlow reads the page DOM. Native apps have no DOM, so send a
+`screenContext` snapshot and the same engine guides your app.
+
+```tsx
+<WebotMeProvider
+  botId="YOUR_BOT_ID"
+  apiBaseUrl="https://your-api.com"
+  screenContext={{
+    name: "pricing",
+    title: "Plans",
+    visibleText: ["Free", "Pro"],
+    buttons: [{ id: "buy_pro", text: "Buy Pro" }],
+    links: [{ id: "faq", text: "FAQ", route: "/faq" }],
+  }}
+>
+```
+
+The server answers with `text` plus, when it wants the app to act, an `action`:
+
+| Action | Shape |
+| --- | --- |
+| navigate | `{ type: "navigate", route, label }` |
+| click | `{ type: "click", targetId, label }` |
+| fill | `{ type: "fill", fieldId, value, label }` |
+| checkout | `{ type: "checkout", url, label }` |
+
+## Native API instead of the web view
+
+If you want your own UI, skip the WebView and use the client directly.
+
+```tsx
+import { useWebotMeChat } from "@webotme/react-native";
+
+const { messages, send, sending, error } = useWebotMeChat();
+```
+
+Or bypass React entirely:
+
+```ts
+import { WebotMeClient } from "@webotme/react-native";
+
+const client = new WebotMeClient({ botId, apiBaseUrl });
+await client.discover();                       // feature-detect the server
+const { text, action } = await client.send({
+  message: "Hello",
+  sessionId,
+  userId,
+  screenContext,
+});
+```
+
+## Errors
+
+Every failure is a `WebotMeError` with a stable `code`:
+
+`INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `BOT_NOT_FOUND`,
+`RATE_LIMITED`, `PLAN_LIMIT_REACHED`, `AI_UNAVAILABLE`, `INTERNAL_ERROR`,
+`NETWORK_ERROR`.
+
+```tsx
+try {
+  await client.send({ message, sessionId, userId });
+} catch (err) {
+  if (err instanceof WebotMeError && err.code === "PLAN_LIMIT_REACHED") {
+    // show the upgrade screen
+  }
+}
+```
+
+## Security
+
+Never ship an API key in a mobile app — apps can be decompiled. This package
+authenticates with the bot ID only. For server-to-server calls keep the key on
+your own backend and use `POST /api/sdk/chat`.
+
+## Endpoints used
+
+| Purpose | Endpoint |
+| --- | --- |
+| Contract | `GET /api/chatbot/public/{botId}/native-chat/v1` |
+| Chat | `POST /api/chatbot/public/{botId}/native-chat/v1` |
+| Bot config | `GET /api/chatbot/public/{botId}` |
+| Sessions | `GET /api/chatbot/public/{botId}/sessions/{visitorId}` |
+| New session | `POST /api/chatbot/public/{botId}/session/new` |
+| Web chat page | `GET {chatBaseUrl}/chat/{botId}` |
+
+## License
+
+UNLICENSED

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@webotme/react-native",
+  "version": "0.1.1",
+  "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",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "chatbot",
+    "ai",
+    "chat",
+    "react-native",
+    "expo",
+    "webotme",
+    "autoflow"
+  ],
+  "license": "UNLICENSED",
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72",
+    "react-native-webview": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "react-native-webview": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^18.3.1",
+    "react-native": "^0.76.9",
+    "react-native-webview": "^13.17.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "expo-av": "^16.0.8"
+  }
+}

package/src/AutoFlowExecutor.tsx

@@ -0,0 +1,353 @@
+import React, { useCallback, useRef, useState } from "react";
+import {
+  Alert,
+  Keyboard,
+  Linking,
+  Platform,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+  type ViewStyle,
+} from "react-native";
+import type {
+  WebotMeAction,
+  WebotMePendingWorkflow,
+  WebotMeAutoTask,
+  WebotMeScreenContext,
+} from "./types";
+
+/**
+ * Props for the AutoFlowExecutor component.
+ */
+export type AutoFlowExecutorProps = {
+  /** Navigation function - must be provided by the app using React Navigation. */
+  navigate: (routeName: string, params?: Record<string, any>) => void;
+  /** Optional: Go back function. */
+  goBack?: () => void;
+  /** Optional: Push to a specific screen. */
+  push?: (routeName: string, params?: Record<string, any>) => void;
+  /** Optional: Reset navigation stack. */
+  resetRoot?: (routes: Array<{ name: string; params?: Record<string, any> }>) => void;
+  /** Current screen context for form filling context. */
+  screenContext?: WebotMeScreenContext;
+  /** Called when an action is executed. */
+  onActionExecuted?: (action: WebotMeAction, success: boolean, error?: string) => void;
+  /** Called when a multi-step workflow starts/continues. */
+  onWorkflowUpdate?: (workflow: WebotMePendingWorkflow | null) => void;
+  /** Theme colors. */
+  theme?: {
+    primary?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    muted?: string;
+  };
+};
+
+/**
+ * AutoFlowExecutor - Executes AutoFlow actions returned by the server.
+ * 
+ * Handles: navigate, click, fill_input, checkout
+ * Integrates with React Navigation for native navigation.
+ * 
+ * Usage:
+ * ```tsx
+ * <AutoFlowExecutor
+ *   navigate={(name, params) => navigation.navigate(name, params)}
+ *   goBack={() => navigation.goBack()}
+ *   push={(name, params) => navigation.push(name, params)}
+ *   onActionExecuted={(action, success, error) => console.log(action, success)}
+ * />
+ * ```
+ */
+export function AutoFlowExecutor({
+  navigate,
+  goBack,
+  push,
+  resetRoot,
+  screenContext,
+  onActionExecuted,
+  onWorkflowUpdate,
+  theme,
+}: AutoFlowExecutorProps) {
+  const palette = {
+    primary: theme?.primary || "#4f46e5",
+    background: theme?.background || "#0f172a",
+    surface: theme?.surface || "#1e293b",
+    text: theme?.text || "#f8fafc",
+    muted: theme?.muted || "#94a3b8",
+  };
+
+  const [pendingWorkflow, setPendingWorkflow] = useState<WebotMePendingWorkflow | null>(null);
+  const [showFillForm, setShowFillForm] = useState<{
+    action: WebotMeAction & { type: "fill" };
+    fields: Array<{ label: string; placeholder: string; value: string; name: string; required: boolean; type: string }>;
+  } | null>(null);
+  const workflowRef = useRef<WebotMeAutoTask | null>(null);
+
+  const executeAction = useCallback(
+    async (action: WebotMeAction): Promise<{ success: boolean; error?: string }> => {
+      try {
+        switch (action.type) {
+          case "navigate": {
+            const url = action.data?.url;
+            if (!url) throw new Error("Navigate action missing URL");
+            
+            // Try to match with known app routes first
+            const routeMap: Record<string, string> = {
+              "/dashboard": "Dashboard",
+              "/dashboard/create": "CreateChatbot",
+              "/dashboard/inbox": "Inbox",
+              "/dashboard/settings": "Settings",
+              "/dashboard/storage": "Storage",
+              "/dashboard/scripts": "Scripts",
+              "/plans": "Plans",
+              "/login": "Login",
+            };
+            
+            const routeName = routeMap[url] || url.replace(/^\//, "").replace(/\//g, "_") || "Home";
+            
+            if (push) {
+              push(routeName, { fromAutoFlow: true, originalUrl: url });
+            } else {
+              navigate(routeName, { fromAutoFlow: true, originalUrl: url });
+            }
+            
+            return { success: true };
+          }
+
+          case "click": {
+            // For native, click actions typically mean triggering a UI element
+            // The app should handle this via onActionExecuted or refs
+            const selector = action.data?.selector;
+            const text = action.data?.text;
+            const section = action.data?.section;
+            
+            // Notify app to handle the click (e.g., via refs or internal logic)
+            return { success: true };
+          }
+
+          case "fill": {
+            const label = action.data?.label;
+            const selector = action.data?.selector;
+            const text = action.data?.text;
+            const currentValue = action.data?.currentValue;
+            
+            if (!text && text !== "") {
+              throw new Error("Fill action missing text value");
+            }
+            
+            // For native, we show a form modal to confirm/edit the fill
+            // The actual field filling should be handled by the app via onActionExecuted
+            // or by using the screenContext forms
+            return { success: true };
+          }
+
+          case "checkout": {
+            const url = action.data?.url;
+            if (!url) throw new Error("Checkout action missing URL");
+            
+            // Open in browser for secure payment
+            await Linking.openURL(url);
+            return { success: true };
+          }
+
+          default: {
+            return { success: false, error: `Unknown action type: ${(action as any).type}` };
+          }
+        }
+      } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+      }
+    },
+    [navigate, push],
+  );
+
+  const executeActions = useCallback(
+    async (actions: WebotMeAction[]): Promise<void> => {
+      for (const action of actions) {
+        const result = await executeAction(action);
+        onActionExecuted?.(action, result.success, result.error);
+        if (!result.success) {
+          Alert.alert("Action Failed", result.error || "Unknown error");
+          break;
+        }
+        // Small delay between actions for UX
+        await new Promise((r) => setTimeout(r, 300));
+      }
+    },
+    [executeAction, onActionExecuted],
+  );
+
+  const handleServerResponse = useCallback(
+    async (response: {
+      actions?: WebotMeAction[];
+      pendingWorkflow?: WebotMePendingWorkflow;
+      autoTask?: WebotMeAutoTask;
+      reply?: string;
+    }) => {
+      if (response.actions && response.actions.length > 0) {
+        await executeActions(response.actions);
+      }
+
+      if (response.pendingWorkflow) {
+        setPendingWorkflow(response.pendingWorkflow);
+        workflowRef.current = {
+          goal: response.pendingWorkflow.goal,
+          plan: response.pendingWorkflow.plan,
+          done: response.pendingWorkflow.done,
+        };
+        onWorkflowUpdate?.(response.pendingWorkflow);
+      } else if (response.autoTask) {
+        workflowRef.current = response.autoTask;
+        onWorkflowUpdate?.({
+          goal: response.autoTask.goal,
+          plan: response.autoTask.plan,
+          done: response.autoTask.done,
+        });
+      } else {
+        setPendingWorkflow(null);
+        workflowRef.current = null;
+        onWorkflowUpdate?.(null);
+      }
+    },
+    [executeActions, onWorkflowUpdate],
+  );
+
+  // Expose execute methods for parent to call
+  const executorRef = useRef({
+    executeAction,
+    executeActions,
+    handleServerResponse,
+    getPendingWorkflow: () => pendingWorkflow,
+    getAutoTask: () => workflowRef.current,
+  });
+
+  // Render fill form modal if needed
+  if (showFillForm) {
+    const { action, fields } = showFillForm;
+    const [values, setValues] = useState(
+      fields.map((f) => f.value || ""),
+    );
+
+    return (
+      <View style={[styles.modalOverlay, { backgroundColor: "rgba(0,0,0,0.6)" }]}>
+        <View style={[styles.modalContent, { backgroundColor: palette.surface }]}>
+          <Text style={[styles.modalTitle, { color: palette.text }]}>
+            Fill Information
+          </Text>
+          {fields.map((field, index) => (
+            <View key={index} style={styles.formField}>
+              <Text style={[styles.fieldLabel, { color: palette.text }]}>
+                {field.label} {field.required && <Text style={{ color: palette.primary }}>*</Text>}
+              </Text>
+              <TextInput
+                value={values[index]}
+                onChangeText={(v) => {
+                  const newValues = [...values];
+                  newValues[index] = v;
+                  setValues(newValues);
+                }}
+                placeholder={field.placeholder}
+                style={[styles.textInput, { backgroundColor: palette.background, color: palette.text }]}
+                keyboardType={field.type === "number" ? "numeric" : "default"}
+              />
+            </View>
+          ))}
+          <View style={styles.modalButtons}>
+            <TouchableOpacity
+              style={[styles.btnCancel, { backgroundColor: palette.surface }]}
+              onPress={() => setShowFillForm(null)}
+            >
+              <Text style={[styles.btnText, { color: palette.muted }]}>Cancel</Text>
+            </TouchableOpacity>
+            <TouchableOpacity
+              style={[styles.btnConfirm, { backgroundColor: palette.primary }]}
+              onPress={() => {
+                // Execute the fill with confirmed values
+                const fillAction: WebotMeAction = {
+                  type: "fill",
+                  data: {
+                    label: action.data?.label,
+                    selector: action.data?.selector,
+                    text: values[0],
+                    currentValue: action.data?.currentValue,
+                  },
+                  label: action.label,
+                };
+                executeAction(fillAction).then((result) => {
+                  onActionExecuted?.(fillAction, result.success, result.error);
+                  setShowFillForm(null);
+                });
+              }}
+            >
+              <Text style={[styles.btnText, { color: "#fff" }]}>Confirm</Text>
+            </TouchableOpacity>
+          </View>
+        </View>
+      </View>
+    );
+  }
+
+  // This component doesn't render anything visible - it's a headless executor
+  // The actual UI for forms/modals would be in the parent or a separate component
+  return null;
+}
+
+const styles = StyleSheet.create({
+  modalOverlay: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  modalContent: {
+    width: "90%",
+    maxHeight: "80%",
+    borderRadius: 16,
+    padding: 20,
+  },
+  modalTitle: {
+    fontSize: 18,
+    fontWeight: "700",
+    marginBottom: 16,
+    textAlign: "center",
+  },
+  formField: {
+    marginBottom: 16,
+  },
+  fieldLabel: {
+    fontSize: 14,
+    fontWeight: "600",
+    marginBottom: 8,
+  },
+  textInput: {
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: "#334155",
+    fontSize: 16,
+  },
+  modalButtons: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    gap: 12,
+    marginTop: 20,
+  },
+  btnCancel: {
+    paddingHorizontal: 20,
+    paddingVertical: 12,
+    borderRadius: 8,
+  },
+  btnConfirm: {
+    paddingHorizontal: 20,
+    paddingVertical: 12,
+    borderRadius: 8,
+  },
+  btnText: {
+    fontSize: 14,
+    fontWeight: "600",
+  },
+});