@webotme/react-native 0.1.1

package/src/client.ts

@@ -0,0 +1,265 @@
+import {
+  WebotMeError,
+  type WebotMeAction,
+  type WebotMeConfig,
+  type WebotMeContract,
+  type WebotMeErrorCode,
+  type WebotMeScreenContext,
+  type WebotMePendingWorkflow,
+  type WebotMeAutoTask,
+} from "./types";
+
+export type SendResult = {
+  text: string;
+  reply?: string;
+  type: string;
+  version?: string;
+  provider?: string;
+  action?: WebotMeAction;
+  actions?: WebotMeAction[];
+  pendingWorkflow?: WebotMePendingWorkflow;
+  autoTask?: WebotMeAutoTask;
+  raw: Record<string, unknown>;
+};
+
+/**
+ * Thin client for the versioned native contract.
+ *
+ * Auth is the bot ID only — never ship an API key in a mobile app, because
+ * apps can be decompiled. Server-to-server callers should use /api/sdk/chat
+ * with a key held on their own backend.
+ */
+export class WebotMeClient {
+  private apiBaseUrl: string;
+  private botId: string;
+  private timeoutMs: number;
+
+  constructor(config: Pick<WebotMeConfig, "botId" | "apiBaseUrl" | "timeoutMs">) {
+    if (!config.botId) throw new WebotMeError("INVALID_REQUEST", "botId is required");
+    if (!config.apiBaseUrl)
+      throw new WebotMeError("INVALID_REQUEST", "apiBaseUrl is required");
+
+    this.botId = config.botId;
+    this.apiBaseUrl = config.apiBaseUrl.replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs ?? 30000;
+  }
+
+  private url(path: string) {
+    return `${this.apiBaseUrl}/api/chatbot/public/${this.botId}${path}`;
+  }
+
+  private async request<T>(
+    path: string,
+    init: RequestInit & { method: "GET" | "POST" },
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetch(this.url(path), {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          ...(init.headers || {}),
+        },
+      });
+    } catch (err) {
+      const aborted = (err as Error)?.name === "AbortError";
+      throw new WebotMeError(
+        "NETWORK_ERROR",
+        aborted
+          ? `Request timed out after ${this.timeoutMs}ms`
+          : `Cannot reach ${this.apiBaseUrl}. Check the server URL and your network.`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const text = await response.text();
+    let body: any = null;
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = null;
+      }
+    }
+
+    if (!response.ok) {
+      const code = (body?.code as WebotMeErrorCode) || "INTERNAL_ERROR";
+      const message =
+        body?.message || `Request failed with status ${response.status}`;
+      throw new WebotMeError(code, message, response.status);
+    }
+
+    return body as T;
+  }
+
+  /** Feature-detect the server before sending anything. */
+  discover(): Promise<WebotMeContract> {
+    return this.request<WebotMeContract>("/native-chat/v1", { method: "GET" });
+  }
+
+  /** Public bot config: name, theme, welcome message. */
+  settings(): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>("", { method: "GET" });
+  }
+
+  async send(params: {
+    message: string;
+    sessionId: string;
+    userId: string;
+    screenContext?: WebotMeScreenContext;
+  }): Promise<SendResult> {
+    const body = await this.request<Record<string, unknown>>("/native-chat/v1", {
+      method: "POST",
+      body: JSON.stringify({
+        message: params.message,
+        sessionId: params.sessionId,
+        userId: params.userId,
+        ...(params.screenContext ? { screenContext: params.screenContext } : {}),
+      }),
+    });
+
+    // v1 always returns `text`; `reply` is kept as an alias by the server.
+    const text =
+      (typeof body.text === "string" && body.text) ||
+      (typeof body.reply === "string" && body.reply) ||
+      "";
+
+    return {
+      text,
+      reply: typeof body.reply === "string" ? body.reply : undefined,
+      type: typeof body.type === "string" ? body.type : "message",
+      version: typeof body.version === "string" ? body.version : undefined,
+      provider:
+        typeof body.provider === "string" ? body.provider : undefined,
+      action: normalizeAction(body),
+      actions: (body.actions as any[]) || (body.action ? [normalizeAction(body)].filter(Boolean) : undefined),
+      pendingWorkflow: (body.pendingWorkflow as any) || undefined,
+      autoTask: (body.autoTask as any) || undefined,
+      raw: body,
+    };
+  }
+
+  /** Past sessions for this visitor, newest first. */
+  async sessions(visitorId: string): Promise<unknown[]> {
+    const body = await this.request<{ sessions?: unknown[] } | unknown[]>(
+      `/sessions/${encodeURIComponent(visitorId)}`,
+      { method: "GET" },
+    );
+    return Array.isArray(body) ? body : (body?.sessions ?? []);
+  }
+
+  startSession(): Promise<{ sessionId: string }> {
+    return this.request<{ sessionId: string }>("/session/new", {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  }
+
+  /**
+   * Speech-to-Text: send audio blob, get transcribed text.
+   * @param audioBlob - Audio recording (webm, wav, mp4, etc.)
+   * @param mimeType - MIME type of the audio (e.g., "audio/webm", "audio/wav")
+   * @returns Transcribed text
+   */
+  async speechToText(audioBlob: Blob, mimeType = "audio/webm"): Promise<{ text: string }> {
+    const formData = new FormData();
+    formData.append("audio", audioBlob, `recording.${mimeType.split("/")[1] || "webm"}`);
+    
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(this.url("/native-chat/v1/stt"), {
+        method: "POST",
+        body: formData,
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+
+      const text = await response.text();
+      let body: any = null;
+      if (text) {
+        try { body = JSON.parse(text); } catch { body = null; }
+      }
+
+      if (!response.ok) {
+        const code = (body?.code as WebotMeErrorCode) || "INTERNAL_ERROR";
+        const message = body?.message || `STT failed with status ${response.status}`;
+        throw new WebotMeError(code, message, response.status);
+      }
+
+      return { text: body?.text || body?.transcript || "" };
+    } catch (err) {
+      clearTimeout(timer);
+      const aborted = (err as Error)?.name === "AbortError";
+      throw new WebotMeError(
+        "NETWORK_ERROR",
+        aborted
+          ? `STT request timed out after ${this.timeoutMs}ms`
+          : `Cannot reach STT endpoint. Check the server URL and your network.`,
+      );
+    }
+  }
+
+  /**
+   * Text-to-Speech: send text, get audio blob.
+   * @param text - Text to synthesize
+   * @param voice - Optional voice identifier (provider-specific)
+   * @returns Audio blob (mp3, wav, etc.)
+   */
+  async textToSpeech(text: string, voice?: string): Promise<Blob> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(this.url("/native-chat/v1/tts"), {
+        method: "POST",
+        signal: controller.signal,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text, voice }),
+      });
+      clearTimeout(timer);
+
+      if (!response.ok) {
+        const text = await response.text();
+        let body: any = null;
+        if (text) { try { body = JSON.parse(text); } catch { body = null; } }
+        const code = (body?.code as WebotMeErrorCode) || "INTERNAL_ERROR";
+        const message = body?.message || `TTS failed with status ${response.status}`;
+        throw new WebotMeError(code, message, response.status);
+      }
+
+      return await response.blob();
+    } catch (err) {
+      clearTimeout(timer);
+      const aborted = (err as Error)?.name === "AbortError";
+      throw new WebotMeError(
+        "NETWORK_ERROR",
+        aborted
+          ? `TTS request timed out after ${this.timeoutMs}ms`
+          : `Cannot reach TTS endpoint. Check the server URL and your network.`,
+      );
+    }
+  }
+}
+
+/**
+ * The server may express the next AutoFlow action under any of a few keys
+ * depending on the flow, so pick the first one that looks actionable.
+ */
+function normalizeAction(
+  body: Record<string, unknown>,
+): WebotMeAction | undefined {
+  const candidates = [body.action, body.nextAction, body.flowAction];
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === "object") {
+      return candidate as WebotMeAction;
+    }
+  }
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { WebotMeProvider, useWebotMe, useWebotMeChat } from "./provider";
+export type { WebotMeProviderProps } from "./provider";
+
+export { WebotMeWidget } from "./widget";
+export type { WebotMeWidgetProps, WidgetMode } from "./widget";
+
+export { WebotMeLauncher } from "./launcher";
+export type { WebotMeLauncherProps, LauncherPosition } from "./launcher";
+
+export { WebotMeClient } from "./client";
+export type { SendResult } from "./client";
+
+export { WebotMeError } from "./types";
+export type {
+  WebotMeAction,
+  WebotMeButton,
+  WebotMeCapabilities,
+  WebotMeConfig,
+  WebotMeContract,
+  WebotMeErrorCode,
+  WebotMeField,
+  WebotMeLink,
+  WebotMeList,
+  WebotMeMessage,
+  WebotMeScreenContext,
+  WebotMeTheme,
+} from "./types";

package/src/launcher.tsx

@@ -0,0 +1,93 @@
+import React, { useState } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { WebotMeWidget } from "./widget";
+import { useWebotMe } from "./provider";
+import type { WebotMeTheme } from "./types";
+
+export type LauncherPosition = "bottom-left" | "bottom-right";
+
+export type WebotMeLauncherProps = {
+  position?: LauncherPosition;
+  bottom?: number;
+  side?: number;
+  label?: string;
+  icon?: string;
+  theme?: WebotMeTheme;
+  /** Hide the dot after the first screen view. */
+  showBadge?: boolean;
+  widgetProps?: React.ComponentProps<typeof WebotMeWidget>;
+};
+
+export function WebotMeLauncher({
+  position = "bottom-right",
+  bottom = 24,
+  side = 24,
+  label = "Chat",
+  icon = "💬",
+  theme,
+  showBadge = true,
+  widgetProps,
+}: WebotMeLauncherProps) {
+  const { messages } = useWebotMe();
+  const [open, setOpen] = useState(false);
+
+  const primary = theme?.primary || "#4f46e5";
+  const unread = showBadge && messages.some((m) => m.from === "bot" && m.text);
+
+  return (
+    <>
+      <View
+        pointerEvents="box-none"
+        style={[
+          styles.wrap,
+          position === "bottom-left" ? { left: side } : { right: side },
+          { bottom },
+        ]}
+      >
+        <Pressable
+          onPress={() => setOpen(true)}
+          accessibilityLabel={label}
+          style={({ pressed }) => [
+            styles.bubble,
+            { backgroundColor: primary, opacity: pressed ? 0.85 : 1 },
+          ]}
+        >
+          <Text style={styles.icon}>{icon}</Text>
+          {unread ? <View style={styles.badge} /> : null}
+        </Pressable>
+      </View>
+
+      <WebotMeWidget
+        {...widgetProps}
+        visible={open}
+        onClose={() => setOpen(false)}
+      />
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: { position: "absolute", zIndex: 100 },
+  bubble: {
+    width: 56,
+    height: 56,
+    borderRadius: 28,
+    alignItems: "center",
+    justifyContent: "center",
+    elevation: 6,
+    shadowColor: "#000",
+    shadowOpacity: 0.25,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 4 },
+  },
+  icon: { fontSize: 24 },
+  badge: {
+    position: "absolute",
+    top: 4,
+    right: 4,
+    width: 12,
+    height: 12,
+    borderRadius: 6,
+    backgroundColor: "#ef4444",
+  },
+});

package/src/provider.tsx

@@ -0,0 +1,238 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { WebotMeClient } from "./client";
+import type {
+  WebotMeConfig,
+  WebotMeContract,
+  WebotMeMessage,
+  WebotMeAction,
+  WebotMePendingWorkflow,
+  WebotMeAutoTask,
+} from "./types";
+
+type WebotMeContextValue = {
+  client: WebotMeClient;
+  botId: string;
+  apiBaseUrl: string;
+  /** Shareable page that renders the bot inside a WebView. */
+  chatUrl: string;
+  userId: string;
+  sessionId: string;
+  messages: WebotMeMessage[];
+  sending: boolean;
+  error: string | null;
+  contract: WebotMeContract | null;
+  send: (text: string) => Promise<void>;
+  retry: () => void;
+  reset: () => void;
+  /** Current pending multi-step workflow from AutoFlow. */
+  pendingWorkflow: WebotMePendingWorkflow | null;
+  /** Current autonomous task from AutoFlow. */
+  autoTask: WebotMeAutoTask | null;
+  /** Callback when an action is executed. */
+  onActionExecuted?: (action: WebotMeAction, success: boolean, error?: string) => void;
+  /** Callback when workflow state changes. */
+  onWorkflowUpdate?: (workflow: WebotMePendingWorkflow | null) => void;
+};
+
+const WebotMeContext = createContext<WebotMeContextValue | null>(null);
+
+export function useWebotMe() {
+  const ctx = useContext(WebotMeContext);
+  if (!ctx) {
+    throw new Error(
+      "useWebotMe must be used inside <WebotMeProvider>. Wrap your app root first.",
+    );
+  }
+  return ctx;
+}
+
+/** Optional hook for screens that only need to send or read messages. */
+export function useWebotMeChat() {
+  const { messages, send, sending, error, retry } = useWebotMe();
+  return { messages, send, sending, error, retry };
+}
+
+const makeId = (prefix: string) =>
+  `${prefix}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+
+export type WebotMeProviderProps = WebotMeConfig & {
+  children: React.ReactNode;
+  /** Change this to wipe the local conversation and start a new session. */
+  resetKey?: string | number;
+};
+
+export function WebotMeProvider({
+  children,
+  botId,
+  apiBaseUrl,
+  chatBaseUrl: chatBaseUrlProp,
+  userId,
+  theme,
+  welcome,
+  screenContext,
+  timeoutMs,
+  resetKey,
+}: WebotMeProviderProps) {
+  const client = useMemo(
+    () => new WebotMeClient({ botId, apiBaseUrl, timeoutMs }),
+    [botId, apiBaseUrl, timeoutMs],
+  );
+
+  // 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);
+
+  const chatBaseUrl = useMemo(
+    () => (chatBaseUrlProp || apiBaseUrl).replace(/\/+$/, ""),
+    [chatBaseUrlProp, apiBaseUrl],
+  );
+
+  const chatUrl = `${chatBaseUrl}/chat/${botId}`;
+
+  // Feature-detect once so the app can show a clear message on an old server.
+  useEffect(() => {
+    let active = true;
+    client
+      .discover()
+      .then((c) => {
+        if (active) setContract(c);
+      })
+      .catch(() => {
+        if (active) setContract(null);
+      });
+    return () => {
+      active = false;
+    };
+  }, [client, attempt]);
+
+  // 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);
+  }, [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 retry = () => setAttempt((n) => n + 1);
+  const reset = () => setSessionId(makeId("s"));
+
+  const value = useMemo<WebotMeContextValue>(
+    () => ({
+      client,
+      botId,
+      apiBaseUrl,
+      chatUrl,
+      userId: visitorRef.current,
+      sessionId,
+      messages,
+      sending,
+      error,
+      contract,
+      send,
+      retry,
+      reset,
+      pendingWorkflow,
+      autoTask,
+    }),
+    [
+      client,
+      botId,
+      apiBaseUrl,
+      chatUrl,
+      sessionId,
+      messages,
+      sending,
+      error,
+      contract,
+      pendingWorkflow,
+      autoTask,
+    ],
+  );
+
+  return (
+    <WebotMeContext.Provider value={value}>{children}</WebotMeContext.Provider>
+  );
+}
+
+function botMessage(text: string): WebotMeMessage {
+  return { id: makeId("m"), from: "bot", text, createdAt: Date.now() };
+}
+
+export type { WebotMeTheme } from "./types";