@restnfeel/agentc-starter-kit/src/lib/chatbot/types/hooks.ts

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

/**
 * @fileoverview Hook type definitions for the RAG chatbot system
 * @module types/hooks
 */

import type { Document, ConversationMessage, ChatbotError } from "./index";

/**
 * Return type for useChatbot hook
 */
export interface UseChatbotReturn {
  // State
  /** Whether the chatbot is initialized */
  isInitialized: boolean;
  /** Whether any operation is in progress */
  isLoading: boolean;
  /** Current error state */
  error: ChatbotError | null;
  /** Current conversation ID */
  conversationId: string | null;
  /** List of all conversations */
  conversations: any[];
  /** Current conversation messages */
  messages: ConversationMessage[];
  /** Vector store connection status */
  vectorStoreConnected: boolean;
  /** LLM connection status */
  llmConnected: boolean;
  /** Storage connection status */
  storageConnected: boolean;

  // Actions
  /** Initialize the chatbot system */
  initialize: () => Promise<void>;
  /** Reset/disconnect the chatbot system */
  reset: () => Promise<void>;
  /** Send a message and get response */
  sendMessage: (content: string) => Promise<ConversationMessage>;
  /** Start a new conversation */
  startConversation: () => Promise<string>;
  /** Switch to a different conversation */
  switchConversation: (conversationId: string) => Promise<void>;
  /** Delete a conversation */
  deleteConversation: (conversationId: string) => Promise<void>;
  /** Upload documents to knowledge base */
  uploadDocuments: (files: File[]) => Promise<Document[]>;
  /** Remove documents from knowledge base */
  removeDocuments: (documentIds: string[]) => Promise<void>;
  /** Search for similar documents */
  searchDocuments: (query: string, limit?: number) => Promise<Document[]>;
  /** Get system health status */
  getHealthStatus: () => Promise<any>;
}

/**
 * Configuration options for useChatbot hook
 */
export interface UseChatbotOptions {
  /** Auto-initialize on mount */
  autoInit?: boolean;
  /** Configuration override */
  config?: {
    vectorStore?: any;
    llm?: any;
    storage?: any;
  };
  /** Error callback */
  onError?: (error: ChatbotError) => void;
  /** Initialization callback */
  onInitialized?: () => void;
}

/**
 * Return type for useDocuments hook
 */
export interface UseDocumentsReturn {
  // State
  /** List of documents */
  documents: Document[];
  /** Whether documents are loading */
  loading: boolean;
  /** Current error */
  error: ChatbotError | null;
  /** Upload progress for each file */
  uploadProgress: Record<string, number>;
  /** Total number of documents */
  totalCount: number;

  // Actions
  /** Upload new documents */
  upload: (files: File[]) => Promise<Document[]>;
  /** Delete documents */
  remove: (documentIds: string[]) => Promise<void>;
  /** Search documents */
  search: (query: string) => Promise<Document[]>;
  /** Refresh document list */
  refresh: () => Promise<void>;
  /** Get document by ID */
  getDocument: (id: string) => Document | undefined;
}

/**
 * Options for useDocuments hook
 */
export interface UseDocumentsOptions {
  /** Auto-fetch on mount */
  autoFetch?: boolean;
  /** Search debounce delay in milliseconds */
  searchDebounce?: number;
  /** Maximum file size for uploads */
  maxFileSize?: number;
  /** Accepted file types */
  acceptedTypes?: string[];
  /** Pagination options */
  pagination?: {
    page?: number;
    limit?: number;
  };
}

/**
 * Return type for useConversations hook
 */
export interface UseConversationsReturn {
  // State
  /** List of conversations */
  conversations: any[];
  /** Current active conversation */
  currentConversation: any | null;
  /** Whether conversations are loading */
  loading: boolean;
  /** Current error */
  error: ChatbotError | null;

  // Actions
  /** Create a new conversation */
  create: (title?: string) => Promise<string>;
  /** Select a conversation */
  select: (conversationId: string) => Promise<void>;
  /** Delete a conversation */
  remove: (conversationId: string) => Promise<void>;
  /** Update conversation metadata */
  update: (conversationId: string, updates: any) => Promise<void>;
  /** Refresh conversation list */
  refresh: () => Promise<void>;
}

/**
 * Return type for useMessages hook
 */
export interface UseMessagesReturn {
  // State
  /** Messages in current conversation */
  messages: ConversationMessage[];
  /** Whether messages are loading */
  loading: boolean;
  /** Whether currently sending a message */
  sending: boolean;
  /** Current error */
  error: ChatbotError | null;

  // Actions
  /** Send a new message */
  send: (content: string) => Promise<ConversationMessage>;
  /** Resend a failed message */
  resend: (messageId: string) => Promise<ConversationMessage>;
  /** Delete a message */
  remove: (messageId: string) => Promise<void>;
  /** Clear all messages */
  clear: () => Promise<void>;
}

/**
 * Return type for useTheme hook
 */
export interface UseThemeReturn {
  // State
  /** Current theme name */
  theme: string;
  /** Resolved theme colors */
  colors: Record<string, string>;
  /** Whether dark mode is active */
  isDark: boolean;
  /** Available themes */
  availableThemes: string[];

  // Actions
  /** Set theme */
  setTheme: (theme: string) => void;
  /** Toggle dark mode */
  toggleDark: () => void;
  /** Apply custom colors */
  setColors: (colors: Record<string, string>) => void;
  /** Reset to default theme */
  reset: () => void;
}

/**
 * Return type for useI18n hook
 */
export interface UseI18nReturn {
  // State
  /** Current language code */
  language: string;
  /** Available languages */
  languages: Array<{ code: string; name: string; flag?: string }>;
  /** Text direction */
  direction: "ltr" | "rtl";
  /** Whether translations are loading */
  loading: boolean;

  // Actions
  /** Translate a key */
  t: (key: string, params?: Record<string, any>) => string;
  /** Set language */
  setLanguage: (language: string) => void;
  /** Check if language is RTL */
  isRTL: (language?: string) => boolean;
}

/**
 * Return type for useSearch hook
 */
export interface UseSearchReturn {
  // State
  /** Search query */
  query: string;
  /** Search results */
  results: Document[];
  /** Whether search is in progress */
  searching: boolean;
  /** Search metadata */
  metadata: {
    totalResults: number;
    searchTime: number;
    method: string;
  } | null;
  /** Current error */
  error: ChatbotError | null;

  // Actions
  /** Set search query */
  setQuery: (query: string) => void;
  /** Perform search */
  search: (query?: string) => Promise<Document[]>;
  /** Clear search results */
  clear: () => void;
  /** Load more results */
  loadMore: () => Promise<Document[]>;
}

/**
 * Return type for useUpload hook
 */
export interface UseUploadReturn {
  // State
  /** Upload progress for each file */
  progress: Record<string, number>;
  /** Whether any upload is in progress */
  uploading: boolean;
  /** Completed uploads */
  completed: Document[];
  /** Failed uploads */
  failed: Array<{ file: File; error: Error }>;
  /** Current error */
  error: ChatbotError | null;

  // Actions
  /** Start upload */
  upload: (files: File[]) => Promise<Document[]>;
  /** Cancel upload */
  cancel: (fileId?: string) => void;
  /** Clear completed/failed uploads */
  clear: () => void;
  /** Retry failed upload */
  retry: (file: File) => Promise<Document>;
}