@ozwell/react 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,282 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * TypeScript type definitions for @ozwell/react
+ *
+ * This file defines types for both:
+ * 1. Currently implemented features (from vanilla widget)
+ * 2. Planned future features (documented but not yet implemented)
+ */
+/**
+ * MCP tool function parameter definition
+ */
+interface OzwellToolParameter {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: OzwellToolParameter;
+    properties?: Record<string, OzwellToolParameter>;
+    required?: string[];
+}
+/**
+ * MCP tool function definition
+ */
+interface OzwellToolFunction {
+    name: string;
+    description: string;
+    parameters: OzwellToolParameter;
+}
+/**
+ * MCP tool definition (OpenAI-compatible)
+ */
+interface OzwellTool {
+    type: 'function';
+    function: OzwellToolFunction;
+}
+/**
+ * Ozwell chat widget configuration
+ * Maps to window.OzwellChatConfig in vanilla implementation
+ */
+interface OzwellConfig {
+    /** API endpoint URL */
+    endpoint?: string;
+    /** Model name (e.g., 'llama3', 'gpt-4') */
+    model?: string;
+    /** System prompt for the assistant */
+    system?: string;
+    /** Welcome message shown when chat opens */
+    welcomeMessage?: string;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Chat widget title */
+    title?: string;
+    /** MCP tools available to the assistant */
+    tools?: OzwellTool[];
+    /** Enable debug mode (shows tool execution details) */
+    debug?: boolean;
+    /** OpenAI API key (for direct OpenAI endpoint usage) */
+    openaiApiKey?: string;
+    /** Custom HTTP headers */
+    headers?: Record<string, string>;
+    /** Widget frame URL (defaults to https://ozwellapi.os.mieweb.org/widget/frame/) */
+    widgetUrl?: string;
+    /** Auto-mount widget on load (default: true) */
+    autoMount?: boolean;
+    /** Enable default floating button UI (default: true) */
+    defaultUI?: boolean;
+    /** Container element ID for custom mounting */
+    containerId?: string;
+    /** Auto-open chat window when AI replies (default: false) */
+    autoOpenOnReply?: boolean;
+    /** Agent key (agnt_key-...) for authentication and server-side agent configuration */
+    apiKey?: string;
+    /** Agent ID for agent-specific configuration */
+    agentId?: string;
+}
+/**
+ * Props for the OzwellChat component
+ */
+interface OzwellChatProps extends Omit<OzwellConfig, 'autoMount'> {
+    /** Widget width (CSS value or number in pixels) */
+    width?: number | string;
+    /** Widget height (CSS value or number in pixels) */
+    height?: number | string;
+    /** Called when widget is ready */
+    onReady?: () => void;
+    /** Called when chat is opened */
+    onOpen?: () => void;
+    /** Called when chat is closed */
+    onClose?: () => void;
+    /**
+     * Called when the AI requests a tool call.
+     * The callback receives the tool name, arguments, and a sendResult function.
+     * Call sendResult(result) to send the tool result back to the widget.
+     *
+     * @example
+     * ```tsx
+     * onToolCall={(tool, args, sendResult) => {
+     *   const result = toolHandlers[tool](args);
+     *   sendResult(result);
+     * }}
+     * ```
+     */
+    onToolCall?: (tool: string, args: Record<string, unknown>, sendResult: (result: unknown) => void) => void;
+    /** Called when user explicitly shares data (privacy-preserving) */
+    onUserShare?: (data: unknown) => void;
+    /** Called on errors */
+    onError?: (error: OzwellError) => void;
+    /** Theme mode */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Widget position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Primary accent color */
+    primaryColor?: string;
+    /** Auto-open chat on mount */
+    autoOpen?: boolean;
+    /** React children (for context provider pattern) */
+    children?: React.ReactNode;
+}
+/**
+ * Return type for useOzwell hook
+ */
+interface UseOzwellReturn {
+    /** Whether the widget is ready */
+    isReady: boolean;
+    /** Whether the chat is currently open */
+    isOpen: boolean;
+    /** Whether there are unread messages */
+    hasUnread: boolean;
+    /** Open the chat */
+    open: () => void;
+    /** Close the chat */
+    close: () => void;
+    /** Toggle chat open/closed */
+    toggle: () => void;
+    /** Send a message programmatically */
+    sendMessage: (content: string) => void;
+    /** Access the underlying iframe element */
+    iframe: HTMLIFrameElement | null;
+}
+/**
+ * Error object for onError callback
+ */
+interface OzwellError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * Vanilla widget API exposed on window object
+ */
+interface OzwellChatAPI {
+    mount: (options?: {
+        containerId?: string;
+        src?: string;
+        width?: number;
+        height?: number;
+    }) => HTMLIFrameElement;
+    configure: (config: Partial<OzwellConfig>) => void;
+    ready: () => Promise<void>;
+    /** Programmatically open the chat window */
+    open: () => void;
+    /** Programmatically close the chat window */
+    close: () => void;
+    /** Current iframe element */
+    iframe: HTMLIFrameElement | null;
+    /** Whether the chat window is currently open */
+    isOpen: boolean;
+    /** Whether there are unread messages */
+    hasUnread: boolean;
+}
+/**
+ * Extend Window interface for TypeScript
+ */
+declare global {
+    interface Window {
+        OzwellChat?: OzwellChatAPI;
+        OzwellChatConfig?: Partial<OzwellConfig>;
+    }
+}
+/**
+ * Script load status
+ */
+type ScriptLoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * PostMessage event data from widget
+ */
+interface OzwellWidgetMessage {
+    source: 'ozwell-chat-widget';
+    type: 'ready' | 'request-config' | 'closed' | 'opened' | 'tool_call' | 'assistant_response' | 'user-share' | 'error';
+    payload?: unknown;
+}
+/**
+ * Assistant response notification from widget (signal only, no message content)
+ */
+interface OzwellAssistantResponseMessage {
+    source: 'ozwell-chat-widget';
+    type: 'assistant_response';
+    /** Whether the response included tool calls */
+    hadToolCalls: boolean;
+}
+/**
+ * Tool call message from widget to parent
+ * Properties are at the root level (not nested in payload)
+ */
+interface OzwellToolCallMessage {
+    source: 'ozwell-chat-widget';
+    type: 'tool_call';
+    /** Tool function name */
+    tool: string;
+    /** Unique ID for this tool call */
+    tool_call_id: string;
+    /** Tool arguments (parsed from function.arguments) */
+    payload: Record<string, unknown>;
+}
+/**
+ * PostMessage event data to widget
+ */
+interface OzwellParentMessage {
+    source: 'ozwell-chat-parent';
+    type: 'config' | 'tool_result';
+    payload?: unknown;
+}
+/**
+ * Tool result message from parent to widget
+ * Properties are at the root level (not nested in payload)
+ */
+interface OzwellToolResultMessage {
+    source: 'ozwell-chat-parent';
+    type: 'tool_result';
+    /** Must match the tool_call_id from the tool_call message */
+    tool_call_id: string;
+    /** Result data to send back to the LLM */
+    result: unknown;
+}
+
+/**
+ * OzwellChat - React component wrapper for Ozwell chat widget
+ *
+ * This component loads the vanilla Ozwell widget and provides a React-friendly API.
+ * It wraps the existing ozwell-loader.js implementation rather than reimplementing it.
+ *
+ * IMPORTANT: Only render one OzwellChat component per page. Multiple instances
+ * will share global configuration (window.OzwellChatConfig) and may cause
+ * unexpected behavior. Use conditional rendering for different configurations.
+ *
+ * @example
+ * ```tsx
+ * <OzwellChat
+ *   endpoint="/v1/chat/completions"
+ *   tools={[...]}
+ *   onReady={() => console.log('Ready!')}
+ * />
+ * ```
+ */
+declare function OzwellChat(props: OzwellChatProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useOzwell - React hook for programmatic control of Ozwell widget
+ *
+ * Provides methods to control the widget and access its state.
+ * Must be used within a component tree that has OzwellChat mounted.
+ *
+ * @example
+ * ```tsx
+ * function ChatControls() {
+ *   const ozwell = useOzwell();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => ozwell.open()}>Open Chat</button>
+ *       <button onClick={() => ozwell.sendMessage('Hello!')}>Send Hello</button>
+ *       {ozwell.isReady ? 'Ready' : 'Loading...'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns {UseOzwellReturn} Widget control methods and state
+ */
+declare function useOzwell(): UseOzwellReturn;
+
+export { type OzwellAssistantResponseMessage, OzwellChat, type OzwellChatAPI, type OzwellChatProps, type OzwellConfig, type OzwellError, type OzwellParentMessage, type OzwellTool, type OzwellToolCallMessage, type OzwellToolFunction, type OzwellToolParameter, type OzwellToolResultMessage, type OzwellWidgetMessage, type ScriptLoadStatus, type UseOzwellReturn, OzwellChat as default, useOzwell };

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * TypeScript type definitions for @ozwell/react
+ *
+ * This file defines types for both:
+ * 1. Currently implemented features (from vanilla widget)
+ * 2. Planned future features (documented but not yet implemented)
+ */
+/**
+ * MCP tool function parameter definition
+ */
+interface OzwellToolParameter {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: OzwellToolParameter;
+    properties?: Record<string, OzwellToolParameter>;
+    required?: string[];
+}
+/**
+ * MCP tool function definition
+ */
+interface OzwellToolFunction {
+    name: string;
+    description: string;
+    parameters: OzwellToolParameter;
+}
+/**
+ * MCP tool definition (OpenAI-compatible)
+ */
+interface OzwellTool {
+    type: 'function';
+    function: OzwellToolFunction;
+}
+/**
+ * Ozwell chat widget configuration
+ * Maps to window.OzwellChatConfig in vanilla implementation
+ */
+interface OzwellConfig {
+    /** API endpoint URL */
+    endpoint?: string;
+    /** Model name (e.g., 'llama3', 'gpt-4') */
+    model?: string;
+    /** System prompt for the assistant */
+    system?: string;
+    /** Welcome message shown when chat opens */
+    welcomeMessage?: string;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Chat widget title */
+    title?: string;
+    /** MCP tools available to the assistant */
+    tools?: OzwellTool[];
+    /** Enable debug mode (shows tool execution details) */
+    debug?: boolean;
+    /** OpenAI API key (for direct OpenAI endpoint usage) */
+    openaiApiKey?: string;
+    /** Custom HTTP headers */
+    headers?: Record<string, string>;
+    /** Widget frame URL (defaults to https://ozwellapi.os.mieweb.org/widget/frame/) */
+    widgetUrl?: string;
+    /** Auto-mount widget on load (default: true) */
+    autoMount?: boolean;
+    /** Enable default floating button UI (default: true) */
+    defaultUI?: boolean;
+    /** Container element ID for custom mounting */
+    containerId?: string;
+    /** Auto-open chat window when AI replies (default: false) */
+    autoOpenOnReply?: boolean;
+    /** Agent key (agnt_key-...) for authentication and server-side agent configuration */
+    apiKey?: string;
+    /** Agent ID for agent-specific configuration */
+    agentId?: string;
+}
+/**
+ * Props for the OzwellChat component
+ */
+interface OzwellChatProps extends Omit<OzwellConfig, 'autoMount'> {
+    /** Widget width (CSS value or number in pixels) */
+    width?: number | string;
+    /** Widget height (CSS value or number in pixels) */
+    height?: number | string;
+    /** Called when widget is ready */
+    onReady?: () => void;
+    /** Called when chat is opened */
+    onOpen?: () => void;
+    /** Called when chat is closed */
+    onClose?: () => void;
+    /**
+     * Called when the AI requests a tool call.
+     * The callback receives the tool name, arguments, and a sendResult function.
+     * Call sendResult(result) to send the tool result back to the widget.
+     *
+     * @example
+     * ```tsx
+     * onToolCall={(tool, args, sendResult) => {
+     *   const result = toolHandlers[tool](args);
+     *   sendResult(result);
+     * }}
+     * ```
+     */
+    onToolCall?: (tool: string, args: Record<string, unknown>, sendResult: (result: unknown) => void) => void;
+    /** Called when user explicitly shares data (privacy-preserving) */
+    onUserShare?: (data: unknown) => void;
+    /** Called on errors */
+    onError?: (error: OzwellError) => void;
+    /** Theme mode */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Widget position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Primary accent color */
+    primaryColor?: string;
+    /** Auto-open chat on mount */
+    autoOpen?: boolean;
+    /** React children (for context provider pattern) */
+    children?: React.ReactNode;
+}
+/**
+ * Return type for useOzwell hook
+ */
+interface UseOzwellReturn {
+    /** Whether the widget is ready */
+    isReady: boolean;
+    /** Whether the chat is currently open */
+    isOpen: boolean;
+    /** Whether there are unread messages */
+    hasUnread: boolean;
+    /** Open the chat */
+    open: () => void;
+    /** Close the chat */
+    close: () => void;
+    /** Toggle chat open/closed */
+    toggle: () => void;
+    /** Send a message programmatically */
+    sendMessage: (content: string) => void;
+    /** Access the underlying iframe element */
+    iframe: HTMLIFrameElement | null;
+}
+/**
+ * Error object for onError callback
+ */
+interface OzwellError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * Vanilla widget API exposed on window object
+ */
+interface OzwellChatAPI {
+    mount: (options?: {
+        containerId?: string;
+        src?: string;
+        width?: number;
+        height?: number;
+    }) => HTMLIFrameElement;
+    configure: (config: Partial<OzwellConfig>) => void;
+    ready: () => Promise<void>;
+    /** Programmatically open the chat window */
+    open: () => void;
+    /** Programmatically close the chat window */
+    close: () => void;
+    /** Current iframe element */
+    iframe: HTMLIFrameElement | null;
+    /** Whether the chat window is currently open */
+    isOpen: boolean;
+    /** Whether there are unread messages */
+    hasUnread: boolean;
+}
+/**
+ * Extend Window interface for TypeScript
+ */
+declare global {
+    interface Window {
+        OzwellChat?: OzwellChatAPI;
+        OzwellChatConfig?: Partial<OzwellConfig>;
+    }
+}
+/**
+ * Script load status
+ */
+type ScriptLoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * PostMessage event data from widget
+ */
+interface OzwellWidgetMessage {
+    source: 'ozwell-chat-widget';
+    type: 'ready' | 'request-config' | 'closed' | 'opened' | 'tool_call' | 'assistant_response' | 'user-share' | 'error';
+    payload?: unknown;
+}
+/**
+ * Assistant response notification from widget (signal only, no message content)
+ */
+interface OzwellAssistantResponseMessage {
+    source: 'ozwell-chat-widget';
+    type: 'assistant_response';
+    /** Whether the response included tool calls */
+    hadToolCalls: boolean;
+}
+/**
+ * Tool call message from widget to parent
+ * Properties are at the root level (not nested in payload)
+ */
+interface OzwellToolCallMessage {
+    source: 'ozwell-chat-widget';
+    type: 'tool_call';
+    /** Tool function name */
+    tool: string;
+    /** Unique ID for this tool call */
+    tool_call_id: string;
+    /** Tool arguments (parsed from function.arguments) */
+    payload: Record<string, unknown>;
+}
+/**
+ * PostMessage event data to widget
+ */
+interface OzwellParentMessage {
+    source: 'ozwell-chat-parent';
+    type: 'config' | 'tool_result';
+    payload?: unknown;
+}
+/**
+ * Tool result message from parent to widget
+ * Properties are at the root level (not nested in payload)
+ */
+interface OzwellToolResultMessage {
+    source: 'ozwell-chat-parent';
+    type: 'tool_result';
+    /** Must match the tool_call_id from the tool_call message */
+    tool_call_id: string;
+    /** Result data to send back to the LLM */
+    result: unknown;
+}
+
+/**
+ * OzwellChat - React component wrapper for Ozwell chat widget
+ *
+ * This component loads the vanilla Ozwell widget and provides a React-friendly API.
+ * It wraps the existing ozwell-loader.js implementation rather than reimplementing it.
+ *
+ * IMPORTANT: Only render one OzwellChat component per page. Multiple instances
+ * will share global configuration (window.OzwellChatConfig) and may cause
+ * unexpected behavior. Use conditional rendering for different configurations.
+ *
+ * @example
+ * ```tsx
+ * <OzwellChat
+ *   endpoint="/v1/chat/completions"
+ *   tools={[...]}
+ *   onReady={() => console.log('Ready!')}
+ * />
+ * ```
+ */
+declare function OzwellChat(props: OzwellChatProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useOzwell - React hook for programmatic control of Ozwell widget
+ *
+ * Provides methods to control the widget and access its state.
+ * Must be used within a component tree that has OzwellChat mounted.
+ *
+ * @example
+ * ```tsx
+ * function ChatControls() {
+ *   const ozwell = useOzwell();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => ozwell.open()}>Open Chat</button>
+ *       <button onClick={() => ozwell.sendMessage('Hello!')}>Send Hello</button>
+ *       {ozwell.isReady ? 'Ready' : 'Loading...'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns {UseOzwellReturn} Widget control methods and state
+ */
+declare function useOzwell(): UseOzwellReturn;
+
+export { type OzwellAssistantResponseMessage, OzwellChat, type OzwellChatAPI, type OzwellChatProps, type OzwellConfig, type OzwellError, type OzwellParentMessage, type OzwellTool, type OzwellToolCallMessage, type OzwellToolFunction, type OzwellToolParameter, type OzwellToolResultMessage, type OzwellWidgetMessage, type ScriptLoadStatus, type UseOzwellReturn, OzwellChat as default, useOzwell };