@hsafa/ui-sdk 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import * as React from 'react';
-import React__default, { ComponentType } from 'react';
+import * as react from 'react';
+import react__default, { ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Props for the Button component
  */
-interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
+interface ButtonProps extends react__default.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Visual style variant of the button */
     variant?: "primary" | "secondary" | "outline" | "ghost";
     /** Size of the button */
@@ -13,7 +13,7 @@ interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElem
     /** Whether the button is in a loading state */
     loading?: boolean;
     /** Content to be displayed inside the button */
-    children: React__default.ReactNode;
+    children: react__default.ReactNode;
 }
 /**
  * A versatile button component with multiple variants, sizes, and states.
@@ -33,7 +33,268 @@ interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElem
  * <Button onClick={() => console.log('Clicked!')}>Click me</Button>
  * ```
  */
-declare const Button: React__default.FC<ButtonProps>;
+declare const Button: react__default.FC<ButtonProps>;
+
+/**
+ * Vercel AI SDK compatible message types
+ * Based on https://sdk.vercel.ai/docs/ai-sdk-core/messages
+ */
+type TextPart = {
+    type: 'text';
+    text: string;
+};
+type ImagePart = {
+    type: 'image';
+    image: string | URL;
+    mediaType?: string;
+};
+type FilePart = {
+    type: 'file';
+    data: string | URL;
+    mediaType: string;
+    name?: string;
+};
+type UserContentPart = TextPart | ImagePart | FilePart;
+type AssistantTextPart = {
+    type: 'text';
+    text: string;
+};
+type ReasoningPart = {
+    type: 'reasoning';
+    text: string;
+};
+type AssistantFilePart = {
+    type: 'file';
+    data: string | URL;
+    mediaType: string;
+    filename?: string;
+};
+type ToolCallPart = {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    input: any;
+};
+type AssistantContentPart = AssistantTextPart | ReasoningPart | AssistantFilePart | ToolCallPart;
+interface Attachment {
+    id: string;
+    name: string;
+    url: string;
+    mimeType: string;
+    size: number;
+}
+
+/**
+ * Type definitions for the HsafaChat component
+ */
+
+type MainAgentAction$1 = {
+    type: 'reasoning';
+    reasoning: string;
+    status: 'streaming' | 'finished';
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'tool-call';
+    toolCallId?: string;
+    toolName?: string;
+    input?: any;
+    inputText?: string;
+    output?: any;
+    status: 'input_streaming' | 'running' | 'finished' | 'error';
+    error?: string;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'step';
+    stepNumber?: number;
+    finishReason?: string;
+    usage?: any;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'text';
+    text: string;
+    status: 'streaming' | 'finished';
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'source';
+    source: any;
+    durationMs?: number;
+} | {
+    type: 'file';
+    file: any;
+    durationMs?: number;
+} | {
+    type: 'response';
+    items: any[];
+    [key: string]: any;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+};
+type ChatMessage = {
+    id: string;
+    role: 'user';
+    content: string | UserContentPart[];
+    createdAt?: number;
+    text?: string;
+    attachments?: Attachment[];
+} | {
+    id: string;
+    role: 'assistant';
+    content?: string | AssistantContentPart[];
+    items: any[];
+    reasoning?: string;
+    reasoningOpen?: boolean;
+    reasoningTokens?: number;
+    createdAt?: number;
+    requestParams?: any;
+    mcpToolCalls?: Array<{
+        toolName: string;
+        args: any;
+        timestamp: number;
+        status?: 'pending' | 'running' | 'completed' | 'failed';
+    }>;
+    mcpToolResults?: Record<string, any>;
+    mainAgentActions?: MainAgentAction$1[];
+    firstAgentMessage?: string;
+    firstAgentContinue?: boolean;
+    autoGenerated?: boolean;
+    hidden?: boolean;
+    turnIndex?: number;
+    controlDecision?: 'continue' | 'done';
+    followUpPrompt?: string;
+};
+interface HsafaChatProps {
+    agentId: string;
+    children?: React.ReactNode;
+    theme?: 'dark' | 'light';
+    primaryColor?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    accentColor?: string;
+    width?: number | string;
+    maxWidth?: number | string;
+    height?: string;
+    expandable?: boolean;
+    alwaysOpen?: boolean;
+    defaultOpen?: boolean;
+    floatingButtonPosition?: {
+        bottom?: number | string;
+        right?: number | string;
+        top?: number | string;
+        left?: number | string;
+    };
+    enableBorderAnimation?: boolean;
+    enableContentPadding?: boolean;
+    borderRadius?: number | string;
+    enableContentBorder?: boolean;
+    placeholder?: string;
+    title?: string;
+    className?: string;
+    chatContainerClassName?: string;
+    dir?: 'rtl' | 'ltr';
+    language?: 'en' | 'ar';
+    defaultReasoningOpen?: boolean;
+    hideReasoningContent?: boolean;
+}
+
+declare const themeColors: {
+    dark: {
+        primaryColor: string;
+        backgroundColor: string;
+        borderColor: string;
+        textColor: string;
+        accentColor: string;
+        mutedTextColor: string;
+        inputBackground: string;
+        cardBackground: string;
+        hoverBackground: string;
+    };
+    light: {
+        primaryColor: string;
+        backgroundColor: string;
+        borderColor: string;
+        textColor: string;
+        accentColor: string;
+        mutedTextColor: string;
+        inputBackground: string;
+        cardBackground: string;
+        hoverBackground: string;
+    };
+};
+type ThemeColors = typeof themeColors.dark;
+
+type TranslationKeys = {
+    'header.maximize': string;
+    'header.minimize': string;
+    'header.new': string;
+    'header.history': string;
+    'header.close': string;
+    'input.placeholder': string;
+    'input.attachFiles': string;
+    'input.insertLink': string;
+    'input.send': string;
+    'input.stop': string;
+    'input.uploadingFiles': string;
+    'input.previewImage': string;
+    'input.removeFile': string;
+    'editor.cancel': string;
+    'editor.saveAndRegenerate': string;
+    'editor.clickToEdit': string;
+    'messages.empty': string;
+    'messages.error': string;
+    'history.search': string;
+    'history.noChatsFound': string;
+    'history.untitledChat': string;
+    'history.deleteChat': string;
+    'general.agent': string;
+};
+
+interface MessageListProps {
+    messages: ChatMessage[];
+    streaming: boolean;
+    editingMessageId: string | null;
+    editingMessageText: string;
+    editingAttachments?: Attachment[];
+    error: string | null;
+    actionStatuses: Map<string, 'executing' | 'executed'>;
+    components: Map<string, react__default.ComponentType<any>>;
+    theme: 'light' | 'dark';
+    resolvedColors: ThemeColors;
+    onEditingTextChange: (text: string) => void;
+    onRemoveAttachment?: (id: string) => void;
+    onAddAttachments?: (files: FileList) => void;
+    uploading?: boolean;
+    onStartEdit: (messageId: string, text: string) => void;
+    onCancelEdit: () => void;
+    onSaveEdit: (messageId: string, text: string) => void;
+    onToggleReasoning: (messageId: string) => void;
+    scrollAnchorRef: react__default.RefObject<HTMLDivElement>;
+    hideReasoningContent?: boolean;
+    t: (key: keyof TranslationKeys) => string;
+}
+declare function MessageList({ messages, streaming, editingMessageId, editingMessageText, editingAttachments, error, actionStatuses, components, theme, resolvedColors, onEditingTextChange, onRemoveAttachment, onAddAttachments, uploading, onStartEdit, onCancelEdit, onSaveEdit, onToggleReasoning, scrollAnchorRef, hideReasoningContent, t }: MessageListProps): react_jsx_runtime.JSX.Element;
+
+interface FloatingChatButtonProps {
+    show: boolean;
+    onClick: () => void;
+    resolvedColors: ThemeColors;
+    floatingButtonPosition: {
+        bottom?: number | string;
+        right?: number | string;
+        top?: number | string;
+        left?: number | string;
+    };
+}
+declare function FloatingChatButton({ show, onClick, resolvedColors, floatingButtonPosition }: FloatingChatButtonProps): react_jsx_runtime.JSX.Element | null;
 
 interface UseToggleReturn {
     /** Current toggle state */
@@ -54,7 +315,7 @@ interface UseToggleReturn {
  */
 declare function useToggle(initial?: boolean): UseToggleReturn;
 
-declare function useAutoScroll<T extends HTMLElement>(): React.MutableRefObject<T | null>;
+declare function useAutoScroll<T extends HTMLElement>(): react.MutableRefObject<T | null>;
 
 /**
  * Handler function for custom actions that can be triggered by the AI agent
@@ -85,22 +346,22 @@ interface HsafaContextValue extends HsafaConfig {
     /** Registered custom actions */
     actions: Map<string, HsafaActionHandler>;
     /** Registered custom components */
-    components: Map<string, React__default.ComponentType<any>>;
+    components: Map<string, react__default.ComponentType<any>>;
     /** Register a custom action handler */
     registerAction: (name: string, handler: HsafaActionHandler) => () => void;
     /** Unregister a custom action handler */
     unregisterAction: (name: string, handler?: HsafaActionHandler) => void;
     /** Register a custom component */
-    registerComponent: (name: string, component: React__default.ComponentType<any>) => () => void;
+    registerComponent: (name: string, component: react__default.ComponentType<any>) => () => void;
     /** Unregister a custom component */
-    unregisterComponent: (name: string, component?: React__default.ComponentType<any>) => void;
+    unregisterComponent: (name: string, component?: react__default.ComponentType<any>) => void;
 }
 /**
  * Props for the HsafaProvider component
  */
 interface HsafaProviderProps extends HsafaConfig {
     /** Child components that will have access to the Hsafa context */
-    children: React__default.ReactNode;
+    children: react__default.ReactNode;
 }
 /**
  * Provider component that sets up the Hsafa context for the SDK.
@@ -143,46 +404,180 @@ declare function useHsafa(): HsafaContextValue;
 /**
  * Register an action handler by name within the nearest HsafaProvider.
  * The handler will be automatically unregistered on unmount.
+ *
+ * @param name - Unique name for the action
+ * @param handler - Function to execute when action is triggered
+ *
+ * @example
+ * ```tsx
+ * useHsafaAction('submitForm', async (params, meta) => {
+ *   console.log('Form submitted:', params);
+ *   return { success: true };
+ * });
+ * ```
  */
 declare function useHsafaAction(name: string, handler: HsafaActionHandler): void;
 
 /**
  * Register a UI component by name within the nearest HsafaProvider.
  * The component will be automatically unregistered on unmount.
+ *
+ * @param name - Unique name for the component (matches agent's component field)
+ * @param component - React component to render when agent requests this component
+ *
+ * @example
+ * ```tsx
+ * function ProductCard({ name, price }: { name: string; price: number }) {
+ *   return <div>{name}: ${price}</div>;
+ * }
+ *
+ * useHsafaComponent('ProductCard', ProductCard);
+ * ```
  */
-declare function useHsafaComponent(name: string, component: ComponentType<any>): void;
+declare function useHsafaComponent<T = any>(name: string, component: ComponentType<T>): void;
 
-interface HsafaChatProps {
-    agentId: string;
-    children?: React__default.ReactNode;
-    theme?: 'dark' | 'light';
-    primaryColor?: string;
-    backgroundColor?: string;
-    borderColor?: string;
-    textColor?: string;
-    accentColor?: string;
-    width?: number | string;
-    maxWidth?: number | string;
-    height?: string;
-    expandable?: boolean;
-    alwaysOpen?: boolean;
-    defaultOpen?: boolean;
-    floatingButtonPosition?: {
-        bottom?: number | string;
-        right?: number | string;
-        top?: number | string;
-        left?: number | string;
-    };
-    enableBorderAnimation?: boolean;
-    enableContentPadding?: boolean;
-    borderRadius?: number | string;
-    enableContentBorder?: boolean;
-    placeholder?: string;
-    title?: string;
-    className?: string;
-    chatContainerClassName?: string;
-    dir?: 'rtl' | 'ltr';
+interface ChatMeta {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
 }
-declare function HsafaChat({ agentId, children, theme, primaryColor, backgroundColor, borderColor, textColor, accentColor, width, maxWidth, height, expandable, alwaysOpen, defaultOpen, dir, floatingButtonPosition, enableBorderAnimation, enableContentPadding, borderRadius, enableContentBorder, placeholder, title, className, chatContainerClassName }: HsafaChatProps): react_jsx_runtime.JSX.Element;
+interface ChatData {
+    id: string;
+    messages: ChatMessage[];
+    agentId?: string;
+}
+declare function useChatStorage(agentId: string): {
+    currentChatId: string | null;
+    setCurrentChatId: react.Dispatch<react.SetStateAction<string | null>>;
+    hasChatRecordRef: react.MutableRefObject<boolean>;
+    pendingFirstTitleRef: react.MutableRefObject<string | null>;
+    loadChatsIndex: () => ChatMeta[];
+    loadChat: (id: string) => ChatData | null;
+    saveChat: (data: ChatData) => void;
+    deleteChat: (id: string, onChatDeleted?: (wasCurrentChat: boolean) => void) => void;
+    loadChatPreferences: () => ChatMessage[];
+    persistChatData: (messages: ChatMessage[]) => void;
+    createNewChat: (firstMessage?: string) => string;
+    upsertChatMeta: (meta: ChatMeta) => void;
+    showChatKey: string;
+};
+
+declare function useStreaming(): {
+    streaming: boolean;
+    setStreaming: react.Dispatch<react.SetStateAction<boolean>>;
+    error: string | null;
+    setError: react.Dispatch<react.SetStateAction<string | null>>;
+    actionStatuses: Map<string, "executing" | "executed">;
+    setActionStatuses: react.Dispatch<react.SetStateAction<Map<string, "executing" | "executed">>>;
+    abortControllerRef: react.MutableRefObject<AbortController | null>;
+    actionExecMapRef: react.MutableRefObject<Record<string, boolean>>;
+    assistantMsgIdRef: react.MutableRefObject<string | undefined>;
+    calledFinalActionsRef: react.MutableRefObject<Set<string>>;
+    actionParamsHistoryRef: react.MutableRefObject<Map<string, any[]>>;
+    actionExecutionStatusRef: react.MutableRefObject<Map<string, "executing" | "executed">>;
+    processActions: (items: any[] | undefined, trigger: "partial" | "final", actions: Map<string, any>, currentChatId: string | null) => void;
+    handleStop: () => void;
+    resetActionTracking: () => void;
+    cleanupTimeouts: () => void;
+    hasActionParamsStabilized: (actionKey: string, currentParams: any) => boolean;
+};
+
+declare function useFileUpload(baseUrl: string): {
+    attachments: Attachment[];
+    uploading: boolean;
+    fileInputRef: react.MutableRefObject<HTMLInputElement | null>;
+    formatBytes: (bytes: number) => string;
+    handleRemoveAttachment: (id: string) => void;
+    handleFileSelection: (fileList: FileList | File[] | null, setError: (error: string | null) => void) => Promise<void>;
+    buildUserContent: (text: string, attachments: Attachment[]) => any[];
+    clearAttachments: () => void;
+    MAX_UPLOAD_SIZE: number;
+};
+
+/**
+ * Types matching the structure from getAgentStreamingResponse
+ */
+type FirstAgentData = {
+    message: string;
+    continue: boolean;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+};
+type MainAgentAction = {
+    type: 'reasoning';
+    reasoning: string;
+    status: 'streaming' | 'finished';
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'tool-call';
+    toolCallId?: string;
+    toolName?: string;
+    input?: any;
+    inputText?: string;
+    output?: any;
+    status: 'input_streaming' | 'running' | 'finished' | 'error';
+    error?: string;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'step';
+    stepNumber?: number;
+    finishReason?: string;
+    usage?: any;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'text';
+    text: string;
+    status: 'streaming' | 'finished';
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+} | {
+    type: 'source';
+    source: any;
+    durationMs?: number;
+} | {
+    type: 'file';
+    file: any;
+    durationMs?: number;
+} | {
+    type: 'response';
+    items: any[];
+    [key: string]: any;
+    startDate?: number;
+    endDate?: number;
+    durationMs?: number;
+};
+type AgentStreamData = {
+    first_agent: FirstAgentData;
+    main_agent: MainAgentAction[];
+};
+/**
+ * Hook to handle agent streaming responses
+ * Returns streaming state and a function to start streaming
+ */
+declare function useAgentStreaming(): {
+    streaming: boolean;
+    error: string | null;
+    streamData: AgentStreamData | null;
+    startStreaming: ({ agentId, body, baseUrl, onUpdate, signal, }: {
+        agentId: string;
+        body: any;
+        baseUrl?: string;
+        onUpdate?: (data: AgentStreamData) => void;
+        signal?: AbortSignal;
+    }) => Promise<AgentStreamData | null>;
+    stopStreaming: () => void;
+    reset: () => void;
+};
+
+declare function HsafaChat(props: HsafaChatProps): react_jsx_runtime.JSX.Element;
 
-export { Button, type ButtonProps, HsafaChat, HsafaProvider, type UseToggleReturn, useAutoScroll, useHsafa, useHsafaAction, useHsafaComponent, useToggle };
+export { type AgentStreamData, Button, type ButtonProps, type ChatData, type ChatMeta, type FirstAgentData, FloatingChatButton, HsafaChat, HsafaProvider, type MainAgentAction, MessageList, type UseToggleReturn, useAgentStreaming, useAutoScroll, useChatStorage, useFileUpload, useHsafa, useHsafaAction, useHsafaComponent, useStreaming, useToggle };