@hastekit/hastekit-converse 0.0.4

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import { ReactNode, ReactElement } from 'react';
+import { AxiosInstance } from 'axios';
+
+interface Agent {
+    id: string;
+    agent_id: string;
+    name: string;
+    version: number;
+}
+declare enum Role {
+    User = "user",
+    Developer = "developer",
+    System = "system",
+    Assistant = "assistant"
+}
+declare enum MessageType {
+    Message = "message",
+    FunctionCall = "function_call",
+    FunctionCallOutput = "function_call_output",
+    Reasoning = "reasoning",
+    ImageGenerationCall = "image_generation_call",
+    FunctionCallApprovalResponse = "function_call_approval_response"
+}
+declare enum ContentType {
+    InputText = "input_text",
+    OutputText = "output_text",
+    SummaryText = "summary_text",
+    InputImage = "input_image"
+}
+declare enum ChunkType {
+    ChunkTypeRunCreated = "run.created",
+    ChunkTypeRunInProgress = "run.in_progress",
+    ChunkTypeRunPaused = "run.paused",
+    ChunkTypeRunCompleted = "run.completed",
+    ChunkTypeResponseCreated = "response.created",
+    ChunkTypeResponseInProgress = "response.in_progress",
+    ChunkTypeResponseCompleted = "response.completed",
+    ChunkTypeOutputItemAdded = "response.output_item.added",
+    ChunkTypeOutputItemDone = "response.output_item.done",
+    ChunkTypeContentPartAdded = "response.content_part.added",
+    ChunkTypeContentPartDone = "response.content_part.done",
+    ChunkTypeOutputTextDelta = "response.output_text.delta",
+    ChunkTypeOutputTextDone = "response.output_text.done",
+    ChunkTypeFunctionCallArgumentsDelta = "response.function_call_arguments.delta",
+    ChunkTypeFunctionCallArgumentsDone = "response.function_call_arguments.done",
+    ChunkTypeReasoningSummaryPartAdded = "response.reasoning_summary_part.added",
+    ChunkTypeReasoningSummaryPartDone = "response.reasoning_summary_part.done",
+    ChunkTypeReasoningSummaryTextDelta = "response.reasoning_summary_text.delta",
+    ChunkTypeReasoningSummaryTextDone = "response.reasoning_summary_text.done",
+    ChunkTypeImageGenerationCallInProgress = "response.image_generation_call.in_progress",
+    ChunkTypeImageGenerationCallGenerating = "response.image_generation_call.generating",
+    ChunkTypeImageGenerationCallPartialImage = "response.image_generation_call.partial_image",
+    ChunkTypeFunctionCallOutput = "function_call_output"
+}
+/**
+ * Represents a conversation container
+ */
+interface Conversation {
+    namespace_id: string;
+    conversation_id: string;
+    name: string;
+    created_at: string;
+    last_updated: string;
+}
+/**
+ * Represents a thread within a conversation
+ */
+interface Thread {
+    conversation_id: string;
+    origin_message_id: string;
+    thread_id: string;
+    meta: Record<string, any>;
+    created_at: string;
+    last_updated: string;
+}
+/**
+ * Represents a message within a conversation thread
+ */
+interface ConversationMessage {
+    conversation_id: string;
+    thread_id: string;
+    message_id: string;
+    messages: MessageUnion[];
+    meta: Record<string, any>;
+    isStreaming?: boolean;
+}
+type MessageUnion = EasyMessage | InputMessage | OutputMessage | FunctionCallMessage | FunctionCallApprovalResponseMessage | FunctionCallOutputMessage | ReasoningMessage | ImageGenerationCallMessage;
+interface EasyMessage {
+    type: MessageType.Message;
+    id: string;
+    role?: Role;
+    content: EasyInputContentUnion;
+}
+interface InputMessage {
+    type: MessageType.Message;
+    id?: string;
+    role?: Role;
+    content?: InputContentUnion[];
+}
+interface OutputMessage {
+    id: string;
+    type?: MessageType.Message;
+    role?: Role;
+    content?: OutputContentUnion[];
+}
+interface FunctionCallMessage {
+    type: MessageType.FunctionCall;
+    id: string;
+    call_id?: string;
+    name: string;
+    arguments: string;
+}
+interface FunctionCallApprovalResponseMessage {
+    type: MessageType.FunctionCallApprovalResponse;
+    id: string;
+    approved_call_ids: string[];
+    rejected_call_ids: string[];
+}
+interface FunctionCallOutputMessage {
+    type: MessageType.FunctionCallOutput;
+    id: string;
+    call_id: string;
+    output: FunctionCallOutputContentUnion;
+}
+interface ReasoningMessage {
+    type: MessageType.Reasoning;
+    id: string;
+    summary?: SummaryTextContent[];
+    encrypted_content?: string;
+}
+interface ImageGenerationCallMessage {
+    type: MessageType.ImageGenerationCall;
+    id: string;
+    status: string;
+    background: string;
+    output_format: string;
+    quality: string;
+    size: string;
+    result: string;
+}
+type EasyInputContentUnion = string | InputContentUnion;
+type InputContentUnion = InputTextContent | OutputTextContent | InputImageContent;
+type FunctionCallOutputContentUnion = string | InputContentUnion;
+type OutputContentUnion = OutputTextContent | FunctionCallMessage | SummaryTextContent;
+interface InputTextContent {
+    type: ContentType.InputText;
+    text: string;
+}
+interface OutputTextContent {
+    type: ContentType.OutputText;
+    text: string;
+}
+interface SummaryTextContent {
+    type: ContentType.SummaryText;
+    text: string;
+}
+interface InputImageContent {
+    type: ContentType.InputImage;
+    image_url: string;
+    detail: string;
+}
+/**
+ * Configuration for the converse API endpoint
+ */
+interface ConverseConfig {
+    namespace: string;
+    agentId: string;
+    baseUrl?: string;
+    context?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+interface ResponseChunk {
+    type: ChunkType;
+    sequence_number: number;
+    run_state?: ChunkRunData;
+    response?: ChunkResponseData;
+    output_index?: number;
+    item?: ChunkOutputItemData;
+    item_id?: string;
+    content_index?: number;
+    part?: OutputContentUnion;
+    delta?: string;
+    text?: string;
+    arguments?: string;
+    summary_index?: number;
+    output: string;
+    partial_image_index?: number;
+    partial_image_b64?: string;
+    background?: string;
+    output_format?: string;
+    quality?: string;
+    size?: string;
+    status?: string;
+}
+interface ChunkRunData {
+    id: string;
+    object: "run";
+    status: "created" | "in_progress" | "paused" | "resumed" | "completed" | "aborted";
+    pending_tool_calls: FunctionCallMessage[];
+    usage: ChunkResponseUsage;
+    traceid: string;
+}
+interface ChunkResponseData {
+    id: string;
+    object: string;
+    created_at: number;
+    status: string;
+    background: boolean;
+    error: unknown;
+    incomplete_details: unknown;
+    output: OutputMessageUnion[];
+    usage: ChunkResponseUsage;
+}
+interface ChunkOutputItemData {
+    type: string;
+    id: string;
+    status: string;
+    content: OutputContentUnion[];
+    role: Role;
+    call_id?: string;
+    name?: string;
+    arguments?: string;
+    encrypted_content?: string;
+    summary?: OutputContentUnion[];
+    background?: string;
+    output_format?: string;
+    quality?: string;
+    result?: string;
+    size?: string;
+}
+type OutputMessageUnion = (OutputMessage & {
+    id: string;
+}) | (FunctionCallMessage & {
+    id: string;
+}) | (ReasoningMessage & {
+    id: string;
+}) | (ImageGenerationCallMessage & {
+    id: string;
+});
+interface ChunkResponseUsage {
+    input_tokens: number;
+    input_tokens_details: {
+        cached_tokens: number;
+    };
+    output_tokens: number;
+    output_tokens_details: {
+        reasoning_tokens: number;
+    };
+    total_tokens: number;
+}
+interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    input_tokens_details: {
+        cached_tokens: number;
+    };
+    output_tokens_details: {
+        reasoning_tokens: number;
+    };
+}
+declare function isEasyMessage(msg: MessageUnion): msg is EasyMessage;
+declare function isInputMessage(msg: MessageUnion): msg is InputMessage;
+declare function isFunctionCallMessage(msg: MessageUnion): msg is FunctionCallMessage;
+declare function isFunctionCallOutputMessage(msg: MessageUnion): msg is FunctionCallOutputMessage;
+declare function isReasoningMessage(msg: MessageUnion): msg is ReasoningMessage;
+declare function isImageGenerationCallMessage(msg: MessageUnion): msg is ImageGenerationCallMessage;
+
+/**
+ * Function type for providing custom headers.
+ * Called before each request to get headers (useful for dynamic auth tokens).
+ *
+ * @example
+ * ```ts
+ * const getHeaders: GetHeadersFn = () => ({
+ *   'Authorization': `Bearer ${getToken()}`,
+ *   'X-Custom-Header': 'value',
+ * });
+ * ```
+ */
+type GetHeadersFn = () => Record<string, string> | Promise<Record<string, string>>;
+/**
+ * Options for the useConversation hook
+ */
+interface UseConversationOptions {
+    /** The namespace for conversations */
+    namespace: string;
+    /** Auto-load conversations on mount (default: true) */
+    autoLoad?: boolean;
+}
+/**
+ * Return type for the useConversation hook
+ */
+interface UseConversationReturn {
+    /** List of all conversations */
+    conversations: Conversation[];
+    /** Whether conversations are being loaded */
+    conversationsLoading: boolean;
+    /** List of threads in the current conversation */
+    threads: Thread[];
+    /** Whether threads are being loaded */
+    threadsLoading: boolean;
+    /** Currently selected thread */
+    currentThread: Thread | null;
+    /** List of messages in the current thread */
+    messages: ConversationMessage[];
+    /** Message currently being streamed */
+    streamingMessage: ConversationMessage | null;
+    /** Whether messages are being loaded */
+    messagesLoading: boolean;
+    /** Whether a response is currently streaming */
+    isStreaming: boolean;
+    /** Whether waiting for a response */
+    isThinking: boolean;
+    /** ID of the currently selected conversation */
+    currentConversationId: string | null;
+    /** ID of the currently selected thread */
+    currentThreadId: string | null;
+    /** Load all conversations */
+    loadConversations: () => Promise<void>;
+    /** Select a conversation by ID */
+    selectConversation: (conversationId: string) => void;
+    /** Load threads for a conversation */
+    loadThreads: (conversationId: string) => Promise<void>;
+    /** Select a thread by ID */
+    selectThread: (threadId: string) => void;
+    /** Send a message and stream the response */
+    sendMessage: (userMessages: MessageUnion[], config: ConverseConfig) => Promise<void>;
+    /** Start a new chat (clears current state) */
+    startNewChat: () => void;
+    /** All messages including the currently streaming one */
+    allMessages: ConversationMessage[];
+}
+/**
+ * A comprehensive hook for managing conversations, threads, messages, and streaming
+ * with Uno Agent Server.
+ *
+ * @example
+ * ```tsx
+ * import { useConversation } from '@praveen001/uno-converse';
+ *
+ * function ChatComponent() {
+ *   const {
+ *     allMessages,
+ *     isStreaming,
+ *     sendMessage,
+ *     startNewChat,
+ *   } = useConversation({
+ *     namespace: 'my-app',
+ *   });
+ *
+ *   const handleSend = async (text: string) => {
+ *     await sendMessage(
+ *       [{ type: 'message', id: '1', content: text }],
+ *       {
+ *         namespace: 'my-app',
+ *         agentName: 'my-agent',
+ *       }
+ *     );
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {allMessages.map(msg => (
+ *         <MessageComponent key={msg.message_id} message={msg} />
+ *       ))}
+ *       {isStreaming && <LoadingIndicator />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useConversation(options: UseConversationOptions): UseConversationReturn;
+
+/**
+ * Options for the useAgent hook
+ */
+interface UseAgentOptions {
+    /** The name of the agent */
+    name: string;
+}
+/**
+ * Return type for the useAgent hook
+ */
+interface UseAgentReturn {
+    agent: Agent | null;
+    /** Whether the agent is being loaded */
+    agentLoading: boolean;
+}
+declare function useAgent(options: UseAgentOptions): UseAgentReturn;
+
+/**
+ * Options for the useProject hook
+ */
+interface UseProjectOptions {
+    /** Base URL of the Uno Agent Server (e.g., 'https://api.example.com/api/agent-server') */
+    baseUrl: string;
+    /** Project Name used to fetch the project ID */
+    projectName: string;
+    /** Optional function to get custom headers for requests (e.g., for authentication) */
+    getHeaders?: GetHeadersFn;
+    /** Auto-load conversations on mount (default: true) */
+    autoLoad?: boolean;
+}
+/**
+ * Return type for the useProject hook
+ */
+interface UseProjectReturn {
+    /** The fetched project ID */
+    projectId: string;
+    /** Whether the project ID is being fetched */
+    projectLoading: boolean;
+    /** Axios instance configured with baseUrl and custom headers */
+    axiosInstance: AxiosInstance;
+    /** Function to build query params with project_id automatically added */
+    buildParams: (params?: Record<string, string>) => Record<string, string>;
+    /** Function to get request headers (combines default + custom headers) */
+    getRequestHeaders: () => Promise<Record<string, string>>;
+    /** Base URL used for the axios instance */
+    baseUrl: string;
+}
+
+/**
+ * Context value for ProjectProvider
+ */
+interface ProjectContextValue extends UseProjectReturn {
+}
+/**
+ * Props for ProjectProvider component
+ */
+interface ProjectProviderProps {
+    /** Base URL of the Uno Agent Server (e.g., 'https://api.example.com/api/agent-server') */
+    baseUrl: string;
+    /** Project Name used to fetch the project ID */
+    projectName: string;
+    /** Optional function to get custom headers for requests (e.g., for authentication) */
+    getHeaders?: UseProjectOptions['getHeaders'];
+    /** Auto-load project on mount (default: true) */
+    autoLoad?: boolean;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * ProjectProvider component that manages project state using React Context.
+ *
+ * This provider wraps the useProject hook and makes the project state available
+ * to all child components through context.
+ *
+ * @example
+ * ```tsx
+ * import { ProjectProvider, useProjectContext } from '@praveen001/uno-converse';
+ *
+ * function App() {
+ *   return (
+ *     <ProjectProvider
+ *       baseUrl="https://api.example.com/api/agent-server"
+ *       projectName="my-project"
+ *       getHeaders={() => ({
+ *         'Authorization': `Bearer ${getToken()}`,
+ *       })}
+ *     >
+ *       <YourApp />
+ *     </ProjectProvider>
+ *   );
+ * }
+ *
+ * function YourApp() {
+ *   const { projectId, projectLoading } = useProjectContext();
+ *
+ *   if (projectLoading) {
+ *     return <div>Loading project...</div>;
+ *   }
+ *
+ *   return <div>Project ID: {projectId}</div>;
+ * }
+ * ```
+ */
+declare const ProjectProvider: ({ baseUrl, projectName, getHeaders, autoLoad, children, }: ProjectProviderProps) => ReactElement;
+/**
+ * Hook to access the project context.
+ *
+ * Must be used within a ProjectProvider component.
+ *
+ * @throws {Error} If used outside of ProjectProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { projectId, projectLoading } = useProjectContext();
+ *
+ *   return (
+ *     <div>
+ *       {projectLoading ? 'Loading...' : `Project ID: ${projectId}`}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useProjectContext: () => ProjectContextValue;
+
+/**
+ * Callback invoked when the conversation state changes
+ */
+type OnChangeCallback = (conversation: ConversationMessage) => void;
+/**
+ * Processes streaming chunks from the LLM response.
+ * Builds up messages incrementally as chunks arrive.
+ *
+ * @example
+ * ```ts
+ * const processor = new ChunkProcessor(
+ *   'conv-123',
+ *   'thread-456',
+ *   (conversation) => {
+ *     // Update UI with new conversation state
+ *     setConversation(conversation);
+ *   }
+ * );
+ *
+ * // Process incoming chunks
+ * processor.processChunk(jsonData);
+ *
+ * // Get final conversation when done
+ * const finalConversation = processor.getConversation();
+ * ```
+ */
+declare class ChunkProcessor {
+    private messages;
+    private currentOutputItem;
+    private _onChange;
+    private conversation;
+    constructor(conversationId: string, threadId: string, onChange: OnChangeCallback);
+    /**
+     * Get all processed messages
+     */
+    getMessages(): MessageUnion[];
+    /**
+     * Get the current conversation state
+     */
+    getConversation(): ConversationMessage;
+    private emitChange;
+    /**
+     * Process a raw JSON chunk from the SSE stream
+     */
+    processChunk(data: string): void;
+    private handleChunk;
+    private handleOutputItemAdded;
+    private handleContentPartAdded;
+    private handleOutputTextDelta;
+    private handleReasoningSummaryPartAdded;
+    private handleReasoningSummaryTextDelta;
+    private handleFunctionCallArgumentsDelta;
+    private handleFunctionCallOutput;
+    private handleImageGenerationCallPartialImage;
+}
+
+/**
+ * Options for the SSE stream callbacks
+ */
+interface SSEStreamOptions {
+    /** Called for each data chunk received */
+    onChunk: (data: string) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when the stream completes */
+    onComplete?: () => void;
+}
+/**
+ * Streams Server-Sent Events (SSE) from a URL.
+ * Parses SSE frames and calls onChunk for each data payload.
+ *
+ * @param url - The URL to stream from
+ * @param requestOptions - Fetch request options
+ * @param callbacks - SSE event callbacks
+ * @param abortSignal - Optional signal to abort the stream
+ *
+ * @example
+ * ```ts
+ * await streamSSE(
+ *   'https://api.example.com/stream',
+ *   { method: 'POST', body: JSON.stringify({ message: 'Hello' }) },
+ *   {
+ *     onChunk: (data) => console.log('Received:', data),
+ *     onComplete: () => console.log('Done'),
+ *     onError: (err) => console.error('Error:', err),
+ *   }
+ * );
+ * ```
+ */
+declare function streamSSE(url: string, requestOptions: RequestInit, callbacks: SSEStreamOptions, abortSignal?: AbortSignal): Promise<void>;
+
+export { ChunkProcessor, ChunkType, ContentType, MessageType, ProjectProvider, Role, isEasyMessage, isFunctionCallMessage, isFunctionCallOutputMessage, isImageGenerationCallMessage, isInputMessage, isReasoningMessage, streamSSE, useAgent, useConversation, useProjectContext };
+export type { ChunkOutputItemData, ChunkResponseData, ChunkResponseUsage, ChunkRunData, Conversation, ConversationMessage, ConverseConfig, EasyInputContentUnion, EasyMessage, FunctionCallApprovalResponseMessage, FunctionCallMessage, FunctionCallOutputContentUnion, FunctionCallOutputMessage, GetHeadersFn, ImageGenerationCallMessage, InputContentUnion, InputImageContent, InputMessage, InputTextContent, MessageUnion, OnChangeCallback, OutputContentUnion, OutputMessage, OutputMessageUnion, OutputTextContent, ProjectContextValue, ProjectProviderProps, ReasoningMessage, ResponseChunk, SSEStreamOptions, SummaryTextContent, Thread, Usage, UseAgentOptions, UseAgentReturn, UseConversationOptions, UseConversationReturn };