@ozwell/react 1.0.0

package/README.md

@@ -0,0 +1,207 @@
+# @ozwell/react
+
+React components for Ozwell chat widget.
+
+## Installation
+
+```bash
+npm install @ozwell/react
+# or
+yarn add @ozwell/react
+# or
+pnpm add @ozwell/react
+```
+
+## Quick Start
+
+```tsx
+import { OzwellChat } from '@ozwell/react';
+
+function App() {
+  return (
+    <OzwellChat
+      apiKey="agnt_key-your-agent-key"
+      tools={[
+        {
+          type: 'function',
+          function: {
+            name: 'get_user_info',
+            description: 'Get current user information',
+            parameters: {
+              type: 'object',
+              properties: {},
+              required: []
+            }
+          }
+        }
+      ]}
+    />
+  );
+}
+```
+
+This package loads the hosted iframe widget and authenticates with an agent key.
+Sign in to [Ozwell Manager](https://ozwellconsole.os.mieweb.org) to create an agent.
+For another deployment, set `widgetUrl` to its `/widget/frame/` URL.
+See the [React integration guide](https://docs.ozwell.ai/frontend/react) for credential
+safety, a complete Vite + MIE UI Hello World example, and troubleshooting.
+
+## Feature Support
+
+### Currently Available
+- Agent-key authentication (`apiKey` prop)
+- Custom endpoints (`endpoint` prop)
+- Model selection (`model` prop)
+- MCP tool/function calling (`tools` prop, `onToolCall` callback)
+- System prompts (`system` prop)
+- Welcome messages (`welcomeMessage` prop)
+- Debug mode (`debug` prop)
+- OpenAI API compatibility (`openaiApiKey` prop)
+- Custom headers (`headers` prop)
+- Auto-open on AI reply (`autoOpenOnReply` prop)
+- Lifecycle callbacks (`onReady`, `onOpen`, `onClose`)
+- Error callback for loader and mount errors (`onError` - partial)
+
+### Coming Soon
+- Agent management (`agentId` prop)
+- Theme customization (`theme`, `primaryColor` props)
+- Position control (`position` prop)
+- Auto-open behavior (`autoOpen` prop)
+- User share callbacks (`onUserShare` - requires widget support)
+- Full error callback support (`onError` - additional error types)
+
+## Using Tools (MCP Function Calling)
+
+The React package supports MCP (Model Context Protocol) tools for function calling. Here's how to define and handle tools:
+
+### Defining Tools
+
+Tools are defined using the OpenAI-compatible format and passed via the `tools` prop:
+
+```tsx
+import { OzwellChat } from '@ozwell/react';
+import type { OzwellTool } from '@ozwell/react';
+
+const tools: OzwellTool[] = [
+  {
+    type: 'function',
+    function: {
+      name: 'get_form_data',
+      description: 'Retrieves current user information including name, address, and zip code',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    }
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'update_form_data',
+      description: 'Updates user profile information',
+      parameters: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'The new name value' },
+          address: { type: 'string', description: 'The new address value' },
+          zipCode: { type: 'string', description: 'The new zip code value' }
+        },
+        required: []
+      }
+    }
+  }
+];
+
+function App() {
+  return (
+    <OzwellChat
+      endpoint="http://localhost:3000/v1/chat/completions"
+      tools={tools}
+      debug={true}
+      system="You are a helpful assistant for managing user profile information."
+    />
+  );
+}
+```
+
+### Handling Tool Calls
+
+Use the `onToolCall` prop to handle tool calls with a simple callback:
+
+```tsx
+import React, { useState } from 'react';
+import { OzwellChat } from '@ozwell/react';
+
+function App() {
+  const [formData, setFormData] = useState({
+    name: '',
+    address: '',
+    zipCode: ''
+  });
+
+  // Define your tool handlers
+  const toolHandlers: Record<string, (args: Record<string, unknown>) => unknown> = {
+    get_form_data: () => formData,
+
+    update_form_data: (args) => {
+      setFormData(prev => ({
+        name: (args.name as string) ?? prev.name,
+        address: (args.address as string) ?? prev.address,
+        zipCode: (args.zipCode as string) ?? prev.zipCode
+      }));
+      return { success: true, updated: args };
+    }
+  };
+
+  return (
+    <OzwellChat
+      endpoint="/v1/chat/completions"
+      tools={tools}
+      onToolCall={(tool, args, sendResult) => {
+        const handler = toolHandlers[tool];
+        if (handler) {
+          const result = handler(args);
+          sendResult(result);
+        } else {
+          sendResult({ error: `Unknown tool: ${tool}` });
+        }
+      }}
+    />
+  );
+}
+```
+
+The `onToolCall` callback receives:
+
+- `tool` - The name of the tool being called
+- `args` - The arguments passed to the tool
+- `sendResult` - A function to send the result back to the AI
+
+This handles all the postMessage complexity internally, so you just focus on your tool logic.
+
+## Documentation
+
+For full documentation, see [React Integration Guide](../../docs/frontend/react.md).
+
+> **Note:** The documentation describes the planned API including `apiKey` and `agentId` props. The current implementation supports `endpoint` and `tools` configuration matching the vanilla JS widget.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Development mode (watch)
+npm run dev
+
+# Type checking
+npm run lint
+```
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,394 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  OzwellChat: () => OzwellChat,
+  default: () => OzwellChat_default,
+  useOzwell: () => useOzwell
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/OzwellChat.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function OzwellChat(props) {
+  const {
+    // Layout
+    width = 360,
+    height = 420,
+    containerId,
+    defaultUI = true,
+    // Configuration
+    endpoint,
+    model,
+    system,
+    welcomeMessage,
+    placeholder,
+    title,
+    tools,
+    debug,
+    openaiApiKey,
+    headers,
+    widgetUrl,
+    autoOpenOnReply,
+    apiKey,
+    // Future props (not yet implemented in vanilla widget)
+    // These are accepted but ignored until backend support is added
+    agentId,
+    theme: _theme,
+    // Prefix with _ to indicate intentionally unused
+    position: _position,
+    primaryColor: _primaryColor,
+    autoOpen: _autoOpen,
+    // Callbacks
+    onReady,
+    onOpen,
+    onClose,
+    onToolCall,
+    onUserShare,
+    onError,
+    // React-specific
+    children
+  } = props;
+  const [scriptStatus, setScriptStatus] = (0, import_react.useState)("idle");
+  const [isWidgetReady, setIsWidgetReady] = (0, import_react.useState)(false);
+  const instanceContainerId = (0, import_react.useRef)(
+    containerId || `ozwell-container-${Math.random().toString(36).slice(2, 11)}`
+  );
+  (0, import_react.useEffect)(() => {
+    if (window.OzwellChat) {
+      setScriptStatus("ready");
+      return;
+    }
+    const handleLoad = () => setScriptStatus("ready");
+    const handleError = () => {
+      setScriptStatus("error");
+      console.error("[OzwellChat] Failed to load ozwell-loader.js");
+      onError?.({
+        code: "SCRIPT_LOAD_ERROR",
+        message: "Failed to load Ozwell widget. Check the widget host URL and network access."
+      });
+    };
+    const existingScript = document.querySelector(
+      'script[data-ozwell-loader], script[src*="ozwell-loader.js"]'
+    );
+    if (existingScript) {
+      setScriptStatus("loading");
+      existingScript.addEventListener("load", handleLoad);
+      existingScript.addEventListener("error", handleError);
+      return () => {
+        existingScript.removeEventListener("load", handleLoad);
+        existingScript.removeEventListener("error", handleError);
+      };
+    }
+    window.OzwellChatConfig = {
+      ...window.OzwellChatConfig,
+      autoMount: false
+    };
+    setScriptStatus("loading");
+    const scriptSrc = new URL(
+      "/widget",
+      widgetUrl ? new URL(widgetUrl, window.location.href) : "https://ozwellapi.os.mieweb.org"
+    ).href;
+    const script = document.createElement("script");
+    script.dataset.ozwellLoader = "true";
+    script.src = scriptSrc;
+    script.async = true;
+    script.addEventListener("load", handleLoad);
+    script.addEventListener("error", handleError);
+    document.head.appendChild(script);
+    return () => {
+      script.removeEventListener("load", handleLoad);
+      script.removeEventListener("error", handleError);
+    };
+  }, [widgetUrl]);
+  (0, import_react.useEffect)(() => {
+    if (scriptStatus !== "ready" || !window.OzwellChat) {
+      return;
+    }
+    const config = {
+      // Core config
+      endpoint,
+      model,
+      system,
+      welcomeMessage,
+      placeholder,
+      title,
+      tools,
+      debug,
+      openaiApiKey,
+      headers,
+      widgetUrl,
+      apiKey,
+      // Layout config
+      defaultUI,
+      autoMount: false,
+      // Prevent auto-mount, we'll mount manually
+      autoOpenOnReply,
+      agentId
+    };
+    if (!defaultUI) {
+      config.containerId = instanceContainerId.current;
+    }
+    const cleanConfig = Object.fromEntries(
+      Object.entries(config).filter(([, value]) => value !== void 0)
+    );
+    window.OzwellChatConfig = cleanConfig;
+    try {
+      const mountOptions = {};
+      if (!defaultUI) {
+        mountOptions.containerId = instanceContainerId.current;
+      }
+      if (width) {
+        mountOptions.width = typeof width === "string" ? parseInt(width) : width;
+      }
+      if (height) {
+        mountOptions.height = typeof height === "string" ? parseInt(height) : height;
+      }
+      if (window.OzwellChat.iframe) {
+        window.OzwellChat.configure(cleanConfig);
+      } else {
+        window.OzwellChat.mount(mountOptions);
+      }
+      window.OzwellChat.ready().then(() => {
+        setIsWidgetReady(true);
+        onReady?.();
+      });
+    } catch (error) {
+      console.error("[OzwellChat] Failed to mount widget:", error);
+      onError?.({
+        code: "MOUNT_ERROR",
+        message: "Failed to mount Ozwell widget",
+        details: error
+      });
+    }
+  }, [
+    scriptStatus,
+    endpoint,
+    model,
+    system,
+    welcomeMessage,
+    placeholder,
+    title,
+    tools,
+    debug,
+    openaiApiKey,
+    headers,
+    widgetUrl,
+    defaultUI,
+    autoOpenOnReply,
+    width,
+    height,
+    apiKey,
+    agentId,
+    onReady,
+    onError
+  ]);
+  (0, import_react.useEffect)(() => {
+    if (!isWidgetReady) {
+      return;
+    }
+    const handleMessage = (event) => {
+      const iframe = window.OzwellChat?.iframe;
+      if (!iframe || event.source !== iframe.contentWindow || event.origin !== new URL(iframe.src, window.location.href).origin) {
+        return;
+      }
+      const data = event.data;
+      if (!data || typeof data !== "object" || data.source !== "ozwell-chat-widget") {
+        return;
+      }
+      switch (data.type) {
+        case "closed":
+          onClose?.();
+          break;
+        case "opened":
+          onOpen?.();
+          break;
+        case "user-share":
+          onUserShare?.(data.payload);
+          break;
+        case "error":
+          onError?.(data.payload);
+          break;
+        case "tool_call":
+          if (onToolCall) {
+            const { tool, tool_call_id, payload: args } = data;
+            const sendResult = (result) => {
+              const iframe2 = window.OzwellChat?.iframe;
+              if (iframe2?.contentWindow) {
+                const targetOrigin = iframe2.src ? new URL(iframe2.src).origin : "*";
+                iframe2.contentWindow.postMessage(
+                  {
+                    source: "ozwell-chat-parent",
+                    type: "tool_result",
+                    tool_call_id,
+                    result
+                  },
+                  targetOrigin
+                );
+              } else {
+                console.error("[OzwellChat] Could not find widget iframe to send tool result");
+              }
+            };
+            onToolCall(tool, args || {}, sendResult);
+          }
+          break;
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+    };
+  }, [isWidgetReady, onClose, onOpen, onUserShare, onError, onToolCall]);
+  (0, import_react.useEffect)(() => {
+    const handleToolCall = (event) => {
+      const { name, arguments: args, respond, error } = event.detail;
+      if (!onToolCall) {
+        error(`No handler configured for tool "${name}".`);
+        return;
+      }
+      try {
+        const outcome = onToolCall(name, args || {}, respond);
+        Promise.resolve(outcome).catch(() => error(`Tool "${name}" failed.`));
+      } catch {
+        error(`Tool "${name}" failed.`);
+      }
+    };
+    document.addEventListener("ozwell-tool-call", handleToolCall);
+    return () => document.removeEventListener("ozwell-tool-call", handleToolCall);
+  }, [onToolCall]);
+  if (defaultUI) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      id: instanceContainerId.current,
+      style: {
+        width: typeof width === "number" ? `${width}px` : width,
+        height: typeof height === "number" ? `${height}px` : height
+      },
+      children
+    }
+  );
+}
+var OzwellChat_default = OzwellChat;
+
+// src/useOzwell.ts
+var import_react2 = require("react");
+function useOzwell() {
+  const [isReady, setIsReady] = (0, import_react2.useState)(false);
+  const [isOpen, setIsOpen] = (0, import_react2.useState)(false);
+  const [hasUnread, setHasUnread] = (0, import_react2.useState)(false);
+  const [iframe, setIframe] = (0, import_react2.useState)(null);
+  (0, import_react2.useEffect)(() => {
+    if (window.OzwellChat) {
+      setIsReady(true);
+      setIframe(window.OzwellChat.iframe);
+      return;
+    }
+    const handleReady = () => {
+      setIsReady(true);
+      setIframe(window.OzwellChat?.iframe || null);
+    };
+    document.addEventListener("ozwell-chat-ready", handleReady);
+    return () => {
+      document.removeEventListener("ozwell-chat-ready", handleReady);
+    };
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    if (!isReady) {
+      return;
+    }
+    const handleMessage = (event) => {
+      const widgetIframe = window.OzwellChat?.iframe;
+      if (widgetIframe && event.source !== widgetIframe.contentWindow) {
+        return;
+      }
+      const data = event.data;
+      if (!data || typeof data !== "object" || data.source !== "ozwell-chat-widget") {
+        return;
+      }
+      if (data.type === "opened") {
+        setIsOpen(true);
+        setHasUnread(false);
+      } else if (data.type === "closed") {
+        setIsOpen(false);
+      }
+    };
+    const handleUnread = () => {
+      setHasUnread(true);
+    };
+    window.addEventListener("message", handleMessage);
+    document.addEventListener("ozwell-chat-unread", handleUnread);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      document.removeEventListener("ozwell-chat-unread", handleUnread);
+    };
+  }, [isReady]);
+  const open = (0, import_react2.useCallback)(() => {
+    if (!isReady) {
+      console.warn("[useOzwell] Widget not ready yet");
+      return;
+    }
+    window.OzwellChat?.open?.();
+  }, [isReady]);
+  const close = (0, import_react2.useCallback)(() => {
+    if (!isReady) {
+      console.warn("[useOzwell] Widget not ready yet");
+      return;
+    }
+    window.OzwellChat?.close?.();
+  }, [isReady]);
+  const toggle = (0, import_react2.useCallback)(() => {
+    if (isOpen) {
+      close();
+    } else {
+      open();
+    }
+  }, [isOpen, open, close]);
+  const sendMessage = (0, import_react2.useCallback)((content) => {
+    if (!isReady) {
+      console.warn("[useOzwell] Widget not ready yet");
+      return;
+    }
+    if (!content || typeof content !== "string") {
+      console.warn("[useOzwell] sendMessage requires a non-empty string");
+      return;
+    }
+    console.warn("[useOzwell] sendMessage() not yet implemented in vanilla widget");
+  }, [isReady]);
+  return {
+    isReady,
+    isOpen,
+    hasUnread,
+    open,
+    close,
+    toggle,
+    sendMessage,
+    iframe
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OzwellChat,
+  useOzwell
+});