@cmnd-ai/chatbot-react 1.9.2 → 1.13.0

package/dist/type.d.ts

@@ -1,46 +1,58 @@
 import { CSSProperties } from "react";
 import { ConversationProps } from "./components/Conversation.js";
+/**
+ * Context interface for the CMND Chat system.
+ * This is used primarily by the internal provider but can be accessed via useCMNDChatContext.
+ */
 export interface CmndChatContext {
+    /** Internal props passed to the conversation view. */
     props: Partial<ConversationProps>;
-    /**
-     * Create a new conversation (resets state, starts a new chat thread)
-     */
+    /** Create a new conversation (resets state, starts a new chat thread). */
     createNewConversation: () => void;
-    /**
-     * Toggle the sidebar open/collapsed state
-     */
+    /** Toggle the sidebar open/collapsed state. */
     toggleSidebar: () => void;
-    /**
-     * Open the sidebar (set collapsed to false)
-     */
+    /** Open the sidebar (set collapsed to false). */
     openSidePanel: () => void;
-    /**
-     * Close the sidebar (set collapsed to true)
-     */
+    /** Close the sidebar (set collapsed to true). */
     closeSidePanel: () => void;
-    /**
-     * Set the message text in the input box
-     */
+    /** Set the message text in the input box. */
     setMessageText: (text: string) => void;
-    /**
-     * Send the current message, or set and send if text is provided
-     */
+    /** Send the current message, or set and send if text is provided. */
     sendMessage: (text?: string) => void;
 }
+/**
+ * Props for a custom input field component.
+ */
 export interface InputFieldProps {
+    /** The current input text. */
     input: string;
+    /** Setter for the input text. */
     setInput: (input: string) => void;
+    /** Whether the send button should be enabled. */
     canSendMessage: boolean;
+    /** Callback to trigger the send action. */
     handleSendClick: () => void;
-    inputRef?: React.RefObject<HTMLInputElement> | React.RefObject<HTMLTextAreaElement> | React.RefObject<HTMLTextAreaElement>;
+    /** Ref for the input element. */
+    inputRef?: React.RefObject<HTMLInputElement> | React.RefObject<HTMLTextAreaElement>;
 }
+/**
+ * Props for a custom send button component.
+ */
 export interface SendButtonProps {
+    /** Callback to trigger the send action. */
     handleSendClick: () => void;
+    /** Whether the button should be enabled. */
     canSendMessage: boolean;
 }
+/**
+ * Utility type for wrapping API responses that might contain an error.
+ */
 export type ErrorOrData<T> = {
     error: unknown;
 } | T;
+/**
+ * Represents a conversation object from the server.
+ */
 export interface Conversation {
     conversationId: number;
     conversationTitle: string;
@@ -50,36 +62,54 @@ export interface Conversation {
     costLimit: number;
     systemPrompt: string;
     enabledTools: any[];
-    /** Date string format */
+    /** Date string format (UTC). */
     createdAt: string;
-    /** Date string format */
+    /** Date string format (UTC). */
     updatedAt: string;
 }
+/**
+ * Data object received via streaming or finalized responses.
+ */
 export interface ConversationDataObject {
+    /** Indicates if the AI has finished generating the response text. */
     completionFinished: boolean;
+    /** Indicates if this is the final message containing usage metadata. */
     finalResponseWithUsageData: boolean;
+    /** The message text (full or chunk). */
     message?: string;
-    conversationId?: string;
-    chatbotConversationId?: number;
+    /** The conversation reference ID. */
+    chatbotConversationRef?: string;
+    /** Alias for chatbotConversationRef used in some stream responses. */
+    conversationRef?: string;
+    /** Total tokens used in the conversation so far. */
     totalTokens?: number;
+    /** Total cost of the conversation so far. */
     totalCost?: number;
+    /** Updated list of all messages in the conversation. */
     messages?: Message[];
+    /** Indicates if an error occurred during streaming. */
+    hasError?: boolean;
+    /** Path associated with the error if available. */
+    errorPath?: string[] | string;
+    /** Indicates if a function call is currently being streamed. */
+    streamingFunctionCall?: boolean;
+    /** Name of the function being called. */
+    functionName?: string;
+    /** Result of a function execution. */
+    functionResult?: any;
 }
-interface ToolArgument {
-    type: string;
-    description: string;
-    default?: any;
-}
-interface ToolArguments {
-    type: string;
-    default?: any;
-    properties: Record<string, ToolArgument>;
-    required?: string[];
-}
+/**
+ * Defines the type of tool function.
+ */
 export declare enum FunctionType {
+    /** Tool that renders a React component in the chat. */
     UI = "ui",
+    /** Tool that runs on the backend. */
     BACKEND = "backend"
 }
+/**
+ * Metadata for a tool.
+ */
 export type ToolData = {
     name: string;
     description: string;
@@ -88,62 +118,105 @@ export type ToolData = {
     subsubcategory?: string;
     functionType: FunctionType;
     dangerous: boolean;
-    arguments: ToolArguments;
-};
-export type UIFunctionArguments<AIProvidedParams> = {
-    functionArgs: AIProvidedParams;
-    previousRunResults?: string;
-    captureResults: (result: string) => void;
+    arguments: any;
 };
+/**
+ * Represents a tool that can be used within the chatbot.
+ */
 export interface CMNDChatbotUITool {
+    /** Unique name of the tool. */
     name: string;
+    /** Description of what the tool does. */
     description: string;
+    /** Category for organizational purposes. */
     category: string;
+    /** Subcategory for finer organization. */
     subcategory?: string;
+    /** Indicates if the tool should be treated as dangerous (e.g., requires confirmation). */
     dangerous?: boolean;
+    /** Command aliases that might trigger this tool. */
     associatedCommands?: string[];
+    /** Prerequisites required before this tool can run. */
     prerequisites?: string[];
+    /** JSON Schema for the tool's arguments. */
     argumentSchema: any;
+    /** Whether the tool can be re-run after finishing. */
     rerun?: boolean;
+    /** Whether the tool can be re-run with different parameters. */
     rerunWithDifferentParameters?: boolean;
+    /** Whether the tool requires further user input. */
     capturesUserInput?: boolean;
+    /** Explicitly set to 'ui' for UI-based tools. */
     functionType?: "ui";
+    /** The function implementation to run when the tool is called. */
     runCmd: (args: {
         functionArgs?: Record<string, any>;
         captureResults?: (result: any) => Promise<any>;
         previousRunResults?: any;
     }, ref?: React.RefObject<HTMLElement>) => void;
 }
+/**
+ * Roles for different message types.
+ */
 export declare enum MessageRole {
+    /** A tool call or result. */
     FUNCTION = "function",
+    /** A message from the user. */
     USER = "user",
+    /** A message from the AI assistant. */
     ASSISTANT = "assistant",
+    /** A system instruction. */
     SYSTEM = "system"
 }
 type MessageRoleExceptFunctions = Exclude<MessageRole, MessageRole.FUNCTION>;
+/**
+ * Base message structure.
+ */
 interface GenericMessage {
     id: string;
+    /** Whether the message should be hidden or ignored in some contexts. */
     unuseful: boolean;
+    /** Whether the message is visible to the end user. */
     hiddenFromUser: boolean;
+    /** The text content of the message. */
     message?: string;
+    /** The role of the sender. */
     role: MessageRoleExceptFunctions;
 }
+/**
+ * Details of a tool call or its execution result.
+ */
 export interface ToolDetails {
+    /** Arguments passed by the AI. */
     args: any;
+    /** Name of the tool called. */
     name: string;
+    /** Whether the tool run has been confirmed. */
     confirmed?: boolean;
+    /** Timestamp of when the tool was run. */
     runAt?: string;
+    /** The result/output of the tool execution. */
     output?: string;
 }
+/**
+ * A message representing a tool call.
+ */
 interface ToolMessage {
     id: string;
     unuseful: boolean;
     hiddenFromUser: boolean;
     message?: string;
     role: MessageRole.FUNCTION;
+    /** Details about the tool call. */
     tool: ToolDetails;
 }
+/**
+ * Union type for all possible message types in a conversation.
+ */
 export type Message = GenericMessage | ToolMessage;
+/**
+ * CSS properties for customizing various parts of the chatbot UI.
+ */
 export interface CustomStyles {
     chatAvatarStyle?: CSSProperties;
     inputStyle?: CSSProperties;
@@ -164,9 +237,15 @@ export interface CustomStyles {
     dateStyle?: CSSProperties;
     deleteButtonStyle?: CSSProperties;
 }
+/**
+ * KV store for conversation memory/context.
+ */
 export interface CMNDChatMemory {
     [key: string]: any;
 }
+/**
+ * Simple message structure used in the ChatbotConversation summary.
+ */
 export interface ChatbotConversationMessage {
     id?: string;
     role: "user" | "assistant";
@@ -174,16 +253,30 @@ export interface ChatbotConversationMessage {
     unuseful: boolean;
     hiddenFromUser: boolean;
 }
+/**
+ * Full conversation metadata and history.
+ */
 export interface ChatbotConversation {
-    chatbotConversationId: number;
+    /** Unique reference for the conversation. */
+    chatbotConversationRef: string;
+    /** Snapshot of message history. */
     messages: ChatbotConversationMessage[];
+    /** ID of the parent chatbot. */
     chatbotId: number;
+    /** Human-readable title for the conversation. */
     chatbotConversationTitle: string;
+    /** Creation timestamp. */
     createdAt: string;
+    /** Last update timestamp. */
     updatedAt: string;
+    /** Cumulative cost of this thread. */
     totalCostSoFar: number;
+    /** Cumulative token count for this thread. */
     totalTokensSoFar: number;
 }
+/**
+ * Response structure when listing conversations.
+ */
 export interface ChatbotConversationsResponse {
     chatbotConversations: ChatbotConversation[];
 }

package/dist/type.js

@@ -1,12 +1,24 @@
+/**
+ * Defines the type of tool function.
+ */
 export var FunctionType;
 (function (FunctionType) {
+    /** Tool that renders a React component in the chat. */
     FunctionType["UI"] = "ui";
+    /** Tool that runs on the backend. */
     FunctionType["BACKEND"] = "backend";
 })(FunctionType = FunctionType || (FunctionType = {}));
+/**
+ * Roles for different message types.
+ */
 export var MessageRole;
 (function (MessageRole) {
+    /** A tool call or result. */
     MessageRole["FUNCTION"] = "function";
+    /** A message from the user. */
     MessageRole["USER"] = "user";
+    /** A message from the AI assistant. */
     MessageRole["ASSISTANT"] = "assistant";
+    /** A system instruction. */
     MessageRole["SYSTEM"] = "system";
 })(MessageRole = MessageRole || (MessageRole = {}));

package/dist/utils/cleanMarkdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cleans markdown characters from a string to return plaintext.
+ * This is a simple regex-based cleaner that handles common markdown patterns.
+ *
+ * @param markdown The markdown string to clean.
+ * @returns The cleaned plaintext string.
+ */
+export declare const cleanMarkdown: (markdown: string) => string;

package/dist/utils/cleanMarkdown.js

@@ -0,0 +1,31 @@
+/**
+ * Cleans markdown characters from a string to return plaintext.
+ * This is a simple regex-based cleaner that handles common markdown patterns.
+ *
+ * @param markdown The markdown string to clean.
+ * @returns The cleaned plaintext string.
+ */
+export const cleanMarkdown = (markdown) => {
+    if (!markdown)
+        return "";
+    return (markdown
+        // Handle bold/italic
+        .replace(/(\*\*|__)(.*?)\1/g, "$2")
+        .replace(/(\*|_)(.*?)\1/g, "$2")
+        // Handle links: [text](url) -> text
+        .replace(/\[(.*?)\]\(.*?\)/g, "$1")
+        // Handle code blocks
+        .replace(/```[\s\S]*?```/g, (match) => {
+        return match.replace(/```(\w+)?\n?|```/g, "").trim();
+    })
+        // Handle inline code
+        .replace(/`(.*?)`/g, "$1")
+        // Handle headers: # Header -> Header
+        .replace(/^#+\s+/gm, "")
+        // Handle blockquotes: > quote -> quote
+        .replace(/^>\s+/gm, "")
+        // Handle horizontal rules
+        .replace(/^-{3,}|^\*{3,}|^\_{3,}/gm, "")
+        // Handle images: ![alt](url) -> alt
+        .replace(/!\[(.*?)\]\(.*?\)/g, "$1"));
+};

package/dist/utils/saveConversationIdToLocalStorage/index.d.ts

@@ -1,5 +1,5 @@
-declare const saveConversationIdToLocalStorage: ({ chatbotConversationId, chatbotId, organizationId, chatHistoryStorageKey }: {
-    chatbotConversationId: number;
+declare const saveConversationIdToLocalStorage: ({ chatbotConversationRef, chatbotId, organizationId, chatHistoryStorageKey, }: {
+    chatbotConversationRef: string;
     chatbotId: number;
     organizationId: number;
     chatHistoryStorageKey?: string | undefined;

package/dist/utils/saveConversationIdToLocalStorage/index.js

@@ -1,14 +1,15 @@
 import getConversationLocalStorageKey from "../getConversationLocalStorageKey/index.js";
-const saveConversationIdToLocalStorage = async ({ chatbotConversationId, chatbotId, organizationId, chatHistoryStorageKey }) => {
+const saveConversationIdToLocalStorage = async ({ chatbotConversationRef, chatbotId, organizationId, chatHistoryStorageKey, }) => {
     try {
-        const key = chatHistoryStorageKey || getConversationLocalStorageKey({
-            organizationId,
-            chatbotId: Number(chatbotId),
-        });
+        const key = chatHistoryStorageKey ||
+            getConversationLocalStorageKey({
+                organizationId,
+                chatbotId: Number(chatbotId),
+            });
         //get the conversation ids from local storage
         const conversations = JSON.parse(localStorage.getItem(key) || "[]") ?? [];
-        if (!conversations.includes(chatbotConversationId)) {
-            conversations.push(chatbotConversationId);
+        if (!conversations.includes(chatbotConversationRef)) {
+            conversations.push(chatbotConversationRef);
             localStorage.setItem(key, JSON.stringify(conversations));
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmnd-ai/chatbot-react",
-  "version": "1.9.2",
+  "version": "1.13.0",
   "main": "dist/index.js",
   "description": "",
   "type": "module",
@@ -31,11 +31,12 @@
     "access": "public"
   },
   "dependencies": {
-    "axios": "^1.7.5",
+    "axios": "^1.13.1",
     "react-error-boundary": "^4.0.13",
     "react-icons": "^5.3.0",
     "react-markdown": "^8.0.6",
     "react-syntax-highlighter": "^15.5.0",
-    "remark-gfm": "^3.0.1"
+    "remark-gfm": "^3.0.1",
+    "uuid": "^13.0.0"
   }
 }

package/readme.dev.md

@@ -28,3 +28,52 @@
    ```
 
 This will allow you to test your local changes in another project without publishing to npm.
+
+## Core Hook Implementation (`useCMNDChat`)
+
+The `useCMNDChat` hook is designed to be the logic engine of the chatbot. Key implementation details:
+
+- **State Management**: Uses native React `useState` for messages, input, and loading states.
+- **Real-time Streaming**: Utilizes `postUserConversation` with a stream reader to process response chunks.
+- **Tool Orchestration**:
+  - **Backend Tools**: Automatically confirms tool call by setting `confirmed: true`. This triggers the server to execute the tool and return the actual data.
+  - **UI Tools**: Fires the `onToolCall` callback. The developer must execute the tool logic and call `submitToolResult(output)`.
+- **Message Cleaning**: When `cleanResponse: true` is enabled, assistant messages are passed through a `cleanMarkdown` utility to return plaintext.
+- **Persistence**: Automatically saves and loads conversation IDs from `localStorage` based on the `organizationId` and `chatbotId`.
+
+### Tool Call Flow
+
+1. AI generates a `function_call`.
+2. Hook receives the call and adds a message with `role: "function"` to the state (internally).
+3. **Internal Behavior:**
+   - **Backend Tools**: The hook automatically calls `confirmBackendTool()`. This sends a confirmed message back to the server.
+   - **UI Tools**: The hook notifies the developer via `onToolCall`.
+4. **Execution:**
+   - **Backend Tools**: The server receives the confirmation, executes the tool, and returns the real data in the next stream update.
+   - **UI Tools**: The developer manually calls `submitToolResult(data)` with the result of the frontend execution.
+5. The conversation resumes with the tool results included in the history.
+
+### Backend Tool Data Flow
+
+```
+User: "Show my playlists"
+  ↓
+AI calls: get_playlists() (role: function)
+  ↓
+Hook auto-confirms: internal confirmBackendTool() (sets confirmed: true)
+  ↓
+Server executes and returns: { playlists: [...] } (Actual data)
+  ↓
+AI receives data and responds: "Here are your playlists: ..."
+```
+
+**Note**: `FUNCTION` role messages are filtered out from the `messages` array returned by the hook to keep the UI clean. Only `USER` and `ASSISTANT` messages are exposed.
+
+## Building and Releasing
+
+1. **Build the package:**
+   ```sh
+   npm run build
+   ```
+2. **Release:**
+   This project uses `semantic-release` for automated versioning and npm publishing. Ensure your commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.