@optilogic/chat 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import * as React from 'react';
+
+/**
+ * Agent Response Component Types
+ *
+ * Type definitions for the library-ready agent response component
+ */
+/**
+ * Status of the agent response cycle
+ */
+type AgentResponseStatus = "idle" | "processing" | "complete";
+/**
+ * Feedback value for the response
+ */
+type FeedbackValue = "up" | "down" | null;
+/**
+ * Tool call information from the agent
+ */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Knowledge retrieval information
+ */
+interface KnowledgeItem {
+    id: string;
+    source: string;
+    content: string;
+    timestamp: number;
+}
+/**
+ * Memory access information
+ */
+interface MemoryItem {
+    id: string;
+    type: string;
+    content: string;
+    timestamp: number;
+}
+/**
+ * State shape for the agent response component
+ */
+interface AgentResponseState {
+    /** Current status of the response cycle */
+    status: AgentResponseStatus;
+    /** Accumulated thinking/reasoning text */
+    thinking: string;
+    /** Tool calls made during processing */
+    toolCalls: ToolCall[];
+    /** Knowledge items retrieved */
+    knowledge: KnowledgeItem[];
+    /** Memory items accessed */
+    memory: MemoryItem[];
+    /** Final response text */
+    response: string;
+    /** Timestamp when first thinking message was received (for timer) */
+    thinkingStartTime: number | null;
+    /** Timestamp when response was completed (for final timer display) */
+    responseCompleteTime: number | null;
+    /** Timestamp when first message of any type was received (for total time) */
+    firstMessageTime: number | null;
+}
+/**
+ * WebSocket message payload for agent responses
+ */
+interface AgentMessage {
+    type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response";
+    /** Message content - for simple string payloads */
+    message?: string;
+    /** Alternative content field */
+    content?: string;
+    /** For status messages */
+    status?: string;
+    /** For tool_call messages */
+    tool?: {
+        id: string;
+        name: string;
+        arguments?: Record<string, unknown>;
+    };
+    /** For knowledge messages */
+    knowledge?: {
+        id: string;
+        source: string;
+        content: string;
+    };
+    /** For memory messages */
+    memory?: {
+        id: string;
+        type: string;
+        content: string;
+    };
+}
+/**
+ * Generic websocket message wrapper type
+ */
+interface GenericWebSocketMessage {
+    topic: string;
+    message: AgentMessage;
+    accountId?: string;
+}
+/**
+ * Initial state for the agent response component
+ */
+declare const initialAgentResponseState: AgentResponseState;
+
+/**
+ * AgentResponse Component
+ *
+ * A library-ready presentational component for displaying AI agent responses.
+ * Displays thinking, tool calls, knowledge retrieval, memory access, and final response.
+ */
+
+interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The response state to render */
+    state: AgentResponseState;
+    /** Optional unique ID (for list keys) */
+    id?: string;
+    /** Optional timestamp to display */
+    timestamp?: Date;
+    /** Feedback state (controlled) */
+    feedback?: FeedbackValue;
+    onFeedbackChange?: (feedback: FeedbackValue) => void;
+    /** Callback when the response is copied via the action bar */
+    onResponseCopy?: (response: string) => void;
+    /** Thinking section expansion (controlled or uncontrolled) */
+    defaultThinkingExpanded?: boolean;
+    thinkingExpanded?: boolean;
+    onThinkingExpandedChange?: (expanded: boolean) => void;
+    /** Action bar visibility mode */
+    actionsVisible?: boolean | "hover";
+    /**
+     * Custom markdown renderer for the response content.
+     * If not provided, the response will be rendered as plain text.
+     *
+     * @example
+     * <AgentResponse
+     *   state={state}
+     *   renderMarkdown={(content) => <MyMarkdownRenderer content={content} />}
+     * />
+     */
+    renderMarkdown?: (content: string) => React.ReactNode;
+}
+/**
+ * AgentResponse Component
+ *
+ * A complete component for displaying AI agent responses including:
+ * - Thinking/reasoning content (collapsible)
+ * - Tool calls, knowledge retrieval, and memory access indicators
+ * - Final response with optional markdown rendering
+ * - Action bar with copy and feedback buttons
+ *
+ * @example
+ * // Basic usage with useAgentResponseAccumulator hook
+ * const { state, handleMessage } = useAgentResponseAccumulator();
+ *
+ * <AgentResponse state={state} />
+ *
+ * @example
+ * // With markdown rendering and feedback
+ * <AgentResponse
+ *   state={state}
+ *   renderMarkdown={(content) => <ReactMarkdown>{content}</ReactMarkdown>}
+ *   feedback={feedback}
+ *   onFeedbackChange={setFeedback}
+ * />
+ *
+ * @example
+ * // Controlled thinking expansion
+ * <AgentResponse
+ *   state={state}
+ *   thinkingExpanded={isExpanded}
+ *   onThinkingExpandedChange={setIsExpanded}
+ * />
+ */
+declare const AgentResponse: React.ForwardRefExoticComponent<AgentResponseProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Activity Indicators Component
+ *
+ * Displays tool, knowledge, memory icons with counts and popovers
+ */
+
+interface ActivityIndicatorsProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Tool calls to display */
+    toolCalls: ToolCall[];
+    /** Knowledge items to display */
+    knowledge: KnowledgeItem[];
+    /** Memory items to display */
+    memory: MemoryItem[];
+}
+/**
+ * ActivityIndicators Component
+ *
+ * Displays icons with counts for tool calls, knowledge retrieval, and memory access.
+ * Each icon has a popover showing details when clicked.
+ *
+ * @example
+ * <ActivityIndicators
+ *   toolCalls={state.toolCalls}
+ *   knowledge={state.knowledge}
+ *   memory={state.memory}
+ * />
+ */
+declare const ActivityIndicators: React.ForwardRefExoticComponent<ActivityIndicatorsProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Metadata Row Component
+ *
+ * Displays thinking toggle, timer, and activity indicators
+ */
+
+interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Whether there is thinking content */
+    hasThinking: boolean;
+    /** Whether the thinking section is expanded */
+    isExpanded: boolean;
+    /** Toggle callback for thinking expansion */
+    onToggle: () => void;
+    /** Tool calls to display */
+    toolCalls: ToolCall[];
+    /** Knowledge items to display */
+    knowledge: KnowledgeItem[];
+    /** Memory items to display */
+    memory: MemoryItem[];
+    /** Current response status */
+    status: AgentResponseStatus;
+    /** Elapsed time in seconds */
+    elapsedTime: number;
+}
+/**
+ * MetadataRow Component
+ *
+ * Displays the metadata row with thinking toggle, timer, and activity indicators.
+ * When thinking content is present, the row is clickable to toggle expansion.
+ *
+ * @example
+ * <MetadataRow
+ *   hasThinking={!!state.thinking}
+ *   isExpanded={thinkingExpanded}
+ *   onToggle={toggleThinking}
+ *   toolCalls={state.toolCalls}
+ *   knowledge={state.knowledge}
+ *   memory={state.memory}
+ *   status={state.status}
+ *   elapsedTime={elapsedTime}
+ * />
+ */
+declare const MetadataRow: React.ForwardRefExoticComponent<MetadataRowProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Thinking Section Component
+ *
+ * Collapsible section for displaying agent thinking/reasoning content
+ */
+
+interface ThinkingSectionProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The thinking content to display */
+    content: string;
+    /** Whether the section is expanded */
+    isExpanded: boolean;
+}
+/**
+ * ThinkingSection Component
+ *
+ * Displays the agent's thinking/reasoning content in a collapsible panel.
+ *
+ * @example
+ * <ThinkingSection content={state.thinking} isExpanded={isExpanded} />
+ */
+declare const ThinkingSection: React.ForwardRefExoticComponent<ThinkingSectionProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Action Bar Component
+ *
+ * Displays copy, feedback, and timing actions for the response
+ */
+
+interface ActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The response text (for copying) */
+    response: string;
+    /** Whether the action bar is visible */
+    isVisible: boolean;
+    /** Total time in seconds */
+    totalTimeSeconds: number;
+    /** Current feedback value */
+    feedback?: FeedbackValue;
+    /** Callback when feedback changes */
+    onFeedbackChange?: (feedback: FeedbackValue) => void;
+    /** Callback when response is copied */
+    onResponseCopy?: (response: string) => void;
+}
+/**
+ * ActionBar Component
+ *
+ * Displays action buttons for copying the response, providing feedback,
+ * and showing total response time.
+ *
+ * @example
+ * <ActionBar
+ *   response={state.response}
+ *   isVisible={isHovered}
+ *   totalTimeSeconds={totalTime}
+ *   feedback={feedback}
+ *   onFeedbackChange={setFeedback}
+ *   onCopy={handleCopy}
+ * />
+ */
+declare const ActionBar: React.ForwardRefExoticComponent<ActionBarProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * useThinkingTimer Hook
+ *
+ * Tracks elapsed time during agent thinking/processing
+ */
+
+interface UseThinkingTimerOptions {
+    startTime: number | null;
+    endTime: number | null;
+    status: AgentResponseStatus;
+}
+/**
+ * Custom hook for thinking timer
+ * Returns elapsed time in seconds
+ */
+declare function useThinkingTimer({ startTime, endTime, status, }: UseThinkingTimerOptions): number;
+
+/**
+ * useAgentResponseAccumulator Hook
+ *
+ * Accumulates agent response messages into a unified state
+ */
+
+interface UseAgentResponseAccumulatorOptions {
+    /** WebSocket topic to filter messages (optional, for convenience) */
+    topic?: string;
+}
+interface UseAgentResponseAccumulatorReturn {
+    /** Current accumulated state */
+    state: AgentResponseState;
+    /** Handler to process incoming messages */
+    handleMessage: (message: unknown) => void;
+    /** Reset state to initial */
+    reset: () => void;
+}
+/**
+ * Hook for accumulating agent response messages into a unified state
+ *
+ * @example
+ * const { state, handleMessage, reset } = useAgentResponseAccumulator({ topic: "agent" });
+ *
+ * // In your WebSocket handler:
+ * websocket.onmessage = (event) => {
+ *   handleMessage(JSON.parse(event.data));
+ * };
+ */
+declare function useAgentResponseAccumulator(options?: UseAgentResponseAccumulatorOptions): UseAgentResponseAccumulatorReturn;
+
+/**
+ * Agent Response Utility Functions
+ */
+/**
+ * Format elapsed time for display
+ * - Under 60s: "Xs" (e.g., "23s")
+ * - 60+ seconds while active: "M:SS" (e.g., "1:23")
+ * - Complete under 60s: "Xs" (e.g., "45s")
+ * - Complete 60-119s: "1.X min" (e.g., "1.2 min")
+ * - Complete 120+ s: "X.X min" (e.g., "2.5 min")
+ */
+declare function formatTime(seconds: number, isComplete: boolean): string;
+/**
+ * Format total time for action bar display
+ */
+declare function formatTotalTime(seconds: number): string;
+
+export { ActionBar, type ActionBarProps, ActivityIndicators, type ActivityIndicatorsProps, type AgentMessage, AgentResponse, type AgentResponseProps, type AgentResponseState, type AgentResponseStatus, type FeedbackValue, type GenericWebSocketMessage, type KnowledgeItem, type MemoryItem, MetadataRow, type MetadataRowProps, ThinkingSection, type ThinkingSectionProps, type ToolCall, type UseAgentResponseAccumulatorOptions, type UseAgentResponseAccumulatorReturn, type UseThinkingTimerOptions, formatTime, formatTotalTime, initialAgentResponseState, useAgentResponseAccumulator, useThinkingTimer };