@elqnt/agent-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,446 @@
+import { ChatEvent, ChatMessage, Chat, ChatUser } from '@elqnt/chat';
+export { Chat, ChatEvent, ChatMessage, ChatUser } from '@elqnt/chat';
+import { Tool, Agent, CSATSurvey } from '@elqnt/agents';
+export { Agent, CSATSurvey, SubAgent, Tool } from '@elqnt/agents';
+
+/**
+ * Core types for the Eloquent Agent SDK
+ *
+ * This module provides TypeScript type definitions for the Agent SDK,
+ * including configuration interfaces, return types, and utility types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * WebSocket connection state
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
+/**
+ * Error codes for agent operations
+ */
+type AgentErrorCode = "CONNECTION_FAILED" | "PARSE_ERROR" | "SEND_FAILED" | "TIMEOUT" | "NETWORK_ERROR" | "TOOL_EXECUTION_FAILED" | "AGENT_NOT_FOUND" | "INVALID_CONFIG";
+/**
+ * Agent error interface
+ */
+interface AgentError {
+    code: AgentErrorCode;
+    message: string;
+    retryable: boolean;
+    timestamp: number;
+    details?: any;
+}
+/**
+ * Client-side tool handler function
+ *
+ * @template TParams - The parameters type for the tool
+ * @template TResult - The result type returned by the tool
+ */
+type ToolHandler<TParams = any, TResult = any> = (params: TParams) => Promise<TResult> | TResult;
+/**
+ * Map of tool names to their handler functions
+ */
+type ToolHandlers = Record<string, ToolHandler>;
+/**
+ * Tool execution context
+ */
+interface ToolExecutionContext {
+    toolName: string;
+    params: any;
+    timestamp: number;
+    chatKey?: string;
+    userId?: string;
+}
+/**
+ * Tool execution result
+ */
+interface ToolExecutionResult<TResult = any> {
+    success: boolean;
+    result?: TResult;
+    error?: AgentError;
+    executionTime: number;
+}
+/**
+ * Configurable agent features
+ */
+interface AgentFeatures {
+    /** Enable voice recognition and text-to-speech */
+    voice?: boolean;
+    /** Enable file upload functionality */
+    fileUpload?: boolean;
+    /** Enable CSAT surveys */
+    csat?: boolean;
+    /** Enable analytics tracking */
+    analytics?: boolean;
+    /** Enable human agent handoff */
+    handoff?: boolean;
+    /** Enable client-side tool execution */
+    clientTools?: boolean;
+    /** Enable metadata management */
+    metadata?: boolean;
+}
+/**
+ * Configuration for useAgentChat hook
+ */
+interface UseAgentChatConfig {
+    /** Agent ID */
+    agentId: string;
+    /** Organization ID */
+    orgId: string;
+    /** WebSocket server base URL */
+    serverBaseUrl: string;
+    /** User email or identifier */
+    userEmail: string;
+    /** Optional agent features to enable */
+    features?: AgentFeatures;
+    /** Callback fired when a message is received */
+    onMessage?: (event: ChatEvent) => void;
+    /** Callback fired when connection is established */
+    onConnect?: () => void;
+    /** Callback fired when connection is lost */
+    onDisconnect?: () => void;
+    /** Callback fired when a tool is called */
+    onToolCall?: (toolName: string, params: any) => void;
+    /** Enable auto-reconnection */
+    autoReconnect?: boolean;
+    /** Reconnection delay in milliseconds */
+    reconnectDelay?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Return type for useAgentChat hook
+ */
+interface UseAgentChatReturn {
+    /** Current chat messages */
+    messages: ChatMessage[];
+    /** Current chat object */
+    currentChat: Chat | undefined;
+    /** Current chat users */
+    users: ChatUser[];
+    /** Current user in the chat */
+    currentChatUser: ChatUser | undefined;
+    /** Connection state */
+    connectionState: ConnectionState;
+    /** Is currently connected */
+    isConnected: boolean;
+    /** Is waiting for agent response */
+    isWaiting: boolean;
+    /** Is waiting for human agent */
+    isWaitingForAgent: boolean;
+    /** Chat status */
+    status: string | undefined;
+    /** Current chat key */
+    chatKey: string | undefined;
+    /** Error if any */
+    error: AgentError | undefined;
+    /** Send a text message */
+    sendMessage: (content: string, attachments?: any[]) => Promise<void>;
+    /** Start a new chat session */
+    startNewChat: () => Promise<void>;
+    /** End the current chat */
+    endChat: () => void;
+    /** Reset the chat state */
+    resetChat: () => void;
+    /** Disconnect from WebSocket */
+    disconnect: (intentional?: boolean) => void;
+    /** Clear error state */
+    clearError: () => void;
+}
+/**
+ * Configuration for useAgentTools hook
+ */
+interface UseAgentToolsConfig {
+    /** Map of tool names to handler functions */
+    tools?: ToolHandlers;
+    /** Callback fired after tool execution */
+    onToolExecuted?: (toolName: string, result: ToolExecutionResult) => void;
+    /** Callback fired on tool error */
+    onToolError?: (toolName: string, error: AgentError) => void;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Return type for useAgentTools hook
+ */
+interface UseAgentToolsReturn {
+    /** Available tools */
+    tools: Record<string, Tool>;
+    /** Execute a client-side tool */
+    executeClientTool: <TResult = any>(toolName: string, params: any) => Promise<TResult>;
+    /** Register a new tool handler */
+    registerTool: (toolName: string, handler: ToolHandler) => void;
+    /** Unregister a tool handler */
+    unregisterTool: (toolName: string) => void;
+    /** Check if a tool is registered */
+    hasToolHandler: (toolName: string) => boolean;
+}
+/**
+ * Configuration for useAgent hook (all-in-one)
+ */
+interface UseAgentConfig extends UseAgentChatConfig {
+    /** Tool handlers for client-side execution */
+    tools?: ToolHandlers;
+    /** Initial chat metadata */
+    initialMetadata?: Record<string, any>;
+    /** Callback for CSAT submission */
+    onCSATSubmit?: (response: any) => void;
+}
+/**
+ * Return type for useAgent hook (all-in-one)
+ */
+interface UseAgentReturn extends Omit<UseAgentChatReturn, "sendMessage">, UseAgentToolsReturn {
+    /** Agent configuration */
+    agent: Agent | undefined;
+    /** Chat metadata */
+    metadata: Record<string, any>;
+    /** Update chat metadata */
+    updateMetadata: (updates: Record<string, any>) => void;
+    /** Clear metadata */
+    clearMetadata: () => void;
+    /** CSAT survey if available */
+    csatSurvey: CSATSurvey | undefined;
+    /** Submit CSAT response */
+    submitCSATResponse: (response: {
+        answers: {
+            question: string;
+            rating?: number;
+            comment?: string;
+        }[];
+        overallRating: number;
+    }) => void;
+    /** Dismiss CSAT survey */
+    dismissCSAT: () => void;
+    /** Send a text message */
+    sendMessage: (content: string, attachments?: any[]) => Promise<void>;
+    /** Log analytics event */
+    logEvent: (eventData: any) => Promise<void>;
+}
+/**
+ * Widget styling configuration
+ */
+interface WidgetStyling {
+    /** Primary color */
+    primaryColor?: string;
+    /** Secondary color */
+    secondaryColor?: string;
+    /** Background color */
+    backgroundColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Border radius */
+    borderRadius?: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Custom CSS classes */
+    className?: string;
+}
+/**
+ * Widget theme
+ */
+type WidgetTheme = "light" | "dark" | "auto";
+/**
+ * Widget position
+ */
+type WidgetPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/**
+ * Base widget configuration
+ */
+interface BaseWidgetConfig extends UseAgentConfig {
+    /** Widget theme */
+    theme?: WidgetTheme;
+    /** Widget position */
+    position?: WidgetPosition;
+    /** Widget styling */
+    styling?: WidgetStyling;
+    /** Enable/disable specific features */
+    features?: AgentFeatures;
+}
+/**
+ * Props for AgentChat component
+ */
+interface AgentChatProps {
+    /** Chat messages */
+    messages: ChatMessage[];
+    /** Callback to send a message */
+    onSend: (content: string, attachments?: any[]) => void;
+    /** Is connected to server */
+    isConnected: boolean;
+    /** Is waiting for response */
+    isWaiting?: boolean;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Custom message renderer */
+    renderMessage?: (message: ChatMessage) => React.ReactNode;
+    /** Custom attachment renderer */
+    renderAttachment?: (file: any) => React.ReactNode;
+    /** Enable file upload */
+    enableFileUpload?: boolean;
+    /** Enable voice input */
+    enableVoice?: boolean;
+    /** Theme */
+    theme?: WidgetTheme;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Props for AgentProvider component
+ */
+interface AgentProviderProps {
+    /** Agent configuration or instance */
+    agent: Agent | undefined;
+    /** Child components */
+    children: React.ReactNode;
+}
+/**
+ * Make all properties in T optional recursively
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Extract the params type from a tool handler
+ */
+type ToolParams<T> = T extends ToolHandler<infer P, any> ? P : never;
+/**
+ * Extract the result type from a tool handler
+ */
+type ToolResult<T> = T extends ToolHandler<any, infer R> ? R : never;
+/**
+ * Type-safe tool handlers map
+ */
+type TypedToolHandlers<T extends Record<string, ToolHandler>> = {
+    [K in keyof T]: ToolHandler<ToolParams<T[K]>, ToolResult<T[K]>>;
+};
+
+/**
+ * useAgent Hook
+ *
+ * The all-in-one hook for interacting with AI agents. Combines chat functionality,
+ * tool execution, metadata management, CSAT surveys, and analytics tracking.
+ *
+ * This is the recommended hook for most use cases as it provides the complete
+ * agent interaction experience out of the box.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   sendMessage,
+ *   isConnected,
+ *   executeClientTool,
+ *   metadata,
+ *   updateMetadata,
+ *   csatSurvey,
+ *   submitCSATResponse
+ * } = useAgent({
+ *   agentId: 'my-agent-id',
+ *   orgId: 'my-org-id',
+ *   serverBaseUrl: 'wss://chat.example.com',
+ *   userEmail: 'user@example.com',
+ *   tools: {
+ *     'search_products': async (params) => {
+ *       return await api.search(params.query);
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All-in-one hook for complete agent interaction
+ *
+ * Combines chat, tools, metadata, CSAT, and analytics into a single
+ * convenient hook. This is the recommended starting point for most
+ * agent implementations.
+ *
+ * @param config - Configuration object for the agent
+ * @returns Object containing all agent interaction methods and state
+ *
+ * @public
+ */
+declare function useAgent(config: UseAgentConfig): UseAgentReturn;
+
+/**
+ * useAgentChat Hook
+ *
+ * A developer-friendly hook for connecting to and interacting with an AI agent via WebSocket.
+ * This hook provides a simplified interface for chat functionality while maintaining
+ * full control over the connection and message flow.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   sendMessage,
+ *   isConnected,
+ *   startNewChat
+ * } = useAgentChat({
+ *   agentId: 'my-agent-id',
+ *   orgId: 'my-org-id',
+ *   serverBaseUrl: 'wss://chat.example.com',
+ *   userEmail: 'user@example.com'
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Hook for agent chat functionality
+ *
+ * Provides a simplified interface for interacting with AI agents via WebSocket,
+ * including automatic connection management, message handling, and state management.
+ *
+ * @param config - Configuration object for the agent chat
+ * @returns Object containing chat state and methods
+ *
+ * @public
+ */
+declare function useAgentChat(config: UseAgentChatConfig): UseAgentChatReturn;
+
+/**
+ * useAgentTools Hook
+ *
+ * A hook for executing client-side tools in response to agent tool calls.
+ * Provides a registry for tool handlers and execution management.
+ *
+ * @example
+ * ```tsx
+ * const { executeClientTool, registerTool } = useAgentTools({
+ *   tools: {
+ *     'search_products': async ({ query }) => {
+ *       const results = await api.search(query);
+ *       return { products: results };
+ *     },
+ *     'track_order': async ({ orderId }) => {
+ *       const order = await api.getOrder(orderId);
+ *       return { status: order.status };
+ *     }
+ *   },
+ *   onToolExecuted: (toolName, result) => {
+ *     console.log(`Tool ${toolName} executed:`, result);
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Hook for managing and executing client-side agent tools
+ *
+ * Provides a registry for tool handlers and methods to execute tools
+ * in response to agent requests. Supports dynamic tool registration
+ * and execution tracking.
+ *
+ * @param config - Configuration object for agent tools
+ * @returns Object containing tool management methods
+ *
+ * @public
+ */
+declare function useAgentTools(config?: UseAgentToolsConfig): UseAgentToolsReturn;
+
+export { type AgentChatProps, type AgentError, type AgentErrorCode, type AgentFeatures, type AgentProviderProps, type BaseWidgetConfig, type ConnectionState, type DeepPartial, type ToolExecutionContext, type ToolExecutionResult, type ToolHandler, type ToolHandlers, type ToolParams, type ToolResult, type TypedToolHandlers, type UseAgentChatConfig, type UseAgentChatReturn, type UseAgentConfig, type UseAgentReturn, type UseAgentToolsConfig, type UseAgentToolsReturn, type WidgetPosition, type WidgetStyling, type WidgetTheme, useAgent, useAgentChat, useAgentTools };