react-ai-agent 1.5.6

package/index.d.ts

@@ -0,0 +1,633 @@
+import * as React from 'react';
+import { ReactNode, ComponentType, RefObject, ReactElement } from 'react';
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export interface SessionData {
+  sessionId: string;
+  token?: string;
+  refreshToken?: string;
+  [key: string]: any;
+}
+
+export interface AuthConfig {
+  sessionId: string;
+  accessToken: string;
+  refreshToken?: string;
+}
+
+export interface WelcomeConfig {
+  title?: string;
+  description?: string;
+  component?: React.ReactNode;
+}
+
+export interface TypingAnimationConfig {
+  mode?: 'char' | 'word' | 'batch' | 'instant';
+  speed?: number; // Units per second
+  batchSize?: number; // Characters per batch (for 'batch' mode)
+}
+
+export interface ForwardingMetadata {
+  action: string;
+  isLive: boolean;
+  event: 'chunk' | 'end';
+}
+
+export type ForwardingHandler = (
+  incrementalText: string,
+  fullText: string,
+  metadata: ForwardingMetadata
+) => void;
+
+export interface ForwardingHandlerConfig {
+  handler: ForwardingHandler;
+  mode?: 'dual' | 'replace' | 'raw';
+  animated?: boolean;
+  subscriptionMode?: 'delta' | 'full';
+}
+
+export interface ForwardingHandlers {
+  [action: string]: ForwardingHandlerConfig;
+}
+
+export interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp?: number;
+  isLive?: boolean;
+  thinking?: string;
+  tools?: any[];
+  files?: AttachedFile[];
+  [key: string]: any;
+}
+
+export interface AttachedFile {
+  id: string;
+  name: string;
+  size: number;
+  type: string;
+  url?: string;
+  preview?: string;
+  [key: string]: any;
+}
+
+export interface SessionMetrics {
+  usedTokens?: number;
+  contextLimit?: number;
+  [key: string]: any;
+}
+
+export interface StreamError {
+  message: string;
+  code?: string;
+  [key: string]: any;
+}
+
+// ============================================================================
+// Chat Context
+// ============================================================================
+
+export interface SendMessageParams {
+  messageId?: string;
+  message?: string;
+  attachedFiles?: AttachedFile[];
+  uploadId?: string | null;
+}
+
+export interface StatusRegistry {
+  register: (action: string, handler: (statusData: any) => void) => () => void;
+  registerGlobal: (handler: (statusData: any) => void) => () => void;
+}
+
+export interface ChatContextValue {
+  // Message operations
+  sendMsg: (params?: SendMessageParams) => Promise<void>;
+  messages: any[];
+  messageManager: {
+    addMessage: (msg: any) => any;
+    updateMessage: (id: string, updates: any, options?: { silent?: boolean }) => any;
+    removeMessage: (id: string) => boolean;
+    getMessage: (id: string) => any;
+    clear: () => void;
+  };
+
+  // Loading states
+  isLoading: boolean;
+  isStreaming: boolean;
+  isResponseStarted: boolean;
+  isInitialLoading: boolean;
+  isLoadingMore: boolean;
+
+  // Error handling
+  error: any;
+  streamError: any;
+  clearStreamError: () => void;
+
+  // Message history
+  getHistory: () => Promise<void>;
+  loadMoreMessages: () => Promise<void>;
+  hasMoreMessages: boolean;
+  enableHistory: boolean;
+
+  // Retry & Control
+  retryLastMessage: () => Promise<void>;
+  abort: () => any;
+
+  // Session management
+  sessionId: string | undefined;
+  setSessionId: (id: string | undefined) => void;
+
+  // Instance identification
+  instanceId: string;
+
+  // File management
+  currentSelectedFile: any;
+  setCurrentSelectedFile: (file: any) => void;
+
+  // Welcome message
+  welcome: any;
+
+  // Status handling
+  statusRegistry: StatusRegistry;
+
+  // Markdown components
+  markdownComponents: any;
+
+  // Typing animation config
+  typingAnimation: TypingAnimationConfig;
+
+  // Status components
+  statusComponents?: any;
+
+  // Loading component
+  loadingComponent?: ComponentType<any>;
+
+  // Header component
+  headerComponent?: React.ReactNode;
+
+  // Debug
+  debug?: boolean;
+}
+
+export function useChatContext(): ChatContextValue;
+
+// ============================================================================
+// Chat Provider
+// ============================================================================
+
+export interface ChatProviderProps {
+  children: ReactNode;
+  debug?: boolean;
+  initialWelcome?: any;
+  authConfig?: AuthConfig;
+  markdownComponents?: any;
+  typingAnimation?: TypingAnimationConfig;
+  statusComponents?: any;
+  forwardingHandlers?: ForwardingHandlers;
+  enableHistory?: boolean;
+  loadingComponent?: ComponentType<any>;
+  headerComponent?: ComponentType<any>;
+  allowThinking?: boolean;
+  config?: any;
+  agentId?: string; // Unique identifier for multi-instance support
+  refreshTokenCallback?: (refreshToken: string) => Promise<any>;
+  onError?: (error: any) => void; // Error handler callback
+  // Legacy support (deprecated)
+  sessionData?: SessionData | null;
+}
+
+export function ChatProvider(props: ChatProviderProps): ReactElement;
+
+// ============================================================================
+// Components
+// ============================================================================
+
+export interface DefaultPanelProps {
+  onCreateSession?: () => void;
+  isDark?: boolean;
+  allowEditMessage?: boolean;
+  config?: {
+    chatUrl?: string;
+    uploadUrl?: string;
+    historyUrl?: string;
+    prepareSessionUrl?: string;
+  };
+}
+
+export const DefaultPanel: ComponentType<DefaultPanelProps>;
+
+// ============================================================================
+// ChatCore - Standalone Message Rendering Component
+// ============================================================================
+
+/**
+ * Ref handle for ChatCore component
+ * Provides imperative access to scroll, messages, and stream control
+ */
+export interface ChatCoreRef {
+  /** Scroll the message container to bottom */
+  scrollToBottom: () => void;
+  /** Check if scroll is at bottom */
+  isAtBottom: () => boolean;
+  /** Direct access to scroll container element */
+  scrollContainer: HTMLDivElement | null;
+  /** TanStack virtualizer instance */
+  virtualizer: any;
+  /** Send a message (wraps context sendMsg with auto-scroll) */
+  sendMessage: (messageData?: SendMessageParams) => Promise<void>;
+  /** Abort current streaming response */
+  abort: () => any;
+  /** Current streaming state */
+  isStreaming: boolean;
+  /** Current loading state */
+  isLoading: boolean;
+  /** Current messages array */
+  messages: any[];
+  /** Message manager instance */
+  messageManager: ChatContextValue['messageManager'];
+}
+
+export interface ChatCoreProps {
+  /** Enable dark theme */
+  isDark?: boolean;
+  /** Additional CSS classes for the container */
+  className?: string;
+  /** Allow editing messages */
+  allowEditMessage?: boolean;
+  /** Show welcome screen when no messages */
+  showWelcome?: boolean;
+  /** Show load more button for history */
+  showLoadMore?: boolean;
+  /** Show loading indicator during response */
+  showLoadingIndicator?: boolean;
+  /** Custom welcome component */
+  welcomeComponent?: ComponentType<{ error?: any }>;
+  /** Custom loading component (overrides context loadingComponent) */
+  loadingComponent?: ComponentType<any>;
+  /** Additional inline styles for container */
+  containerStyle?: React.CSSProperties;
+  /** Enable gradient mask on scroll */
+  useGradientMask?: boolean;
+  /** Custom gradient mask CSS value */
+  gradientMaskStyle?: string;
+}
+
+/**
+ * ChatCore - Standalone message rendering component
+ * 
+ * Renders messages with virtualization and scroll handling.
+ * Must be used within a ChatProvider context.
+ * 
+ * @example Basic usage
+ * ```tsx
+ * <ChatProvider authConfig={authConfig}>
+ *   <ChatCore isDark={true} className="h-full" />
+ * </ChatProvider>
+ * ```
+ * 
+ * @example With ref for imperative access
+ * ```tsx
+ * const coreRef = useRef<ChatCoreRef>(null);
+ * 
+ * <ChatProvider authConfig={authConfig}>
+ *   <ChatCore ref={coreRef} />
+ *   <button onClick={() => coreRef.current?.scrollToBottom()}>
+ *     Scroll to bottom
+ *   </button>
+ * </ChatProvider>
+ * ```
+ * 
+ * @example Custom layout with ChatInput
+ * ```tsx
+ * <ChatProvider authConfig={authConfig}>
+ *   <div className="flex flex-col h-screen">
+ *     <ChatCore className="flex-1" isDark={true} />
+ *     <ChatInput onSend={handleSend} />
+ *   </div>
+ * </ChatProvider>
+ * ```
+ */
+export const ChatCore: React.ForwardRefExoticComponent<
+  ChatCoreProps & React.RefAttributes<ChatCoreRef>
+>;
+
+export interface MessageItemProps {
+  message: Message;
+  isLast?: boolean;
+  theme?: string;
+  [key: string]: any;
+}
+
+export const MessageItem: ComponentType<MessageItemProps>;
+
+export interface ChatInputProps {
+  onSend?: (message: string, files?: AttachedFile[]) => void;
+  disabled?: boolean;
+  placeholder?: string;
+  [key: string]: any;
+}
+
+export const ChatInput: ComponentType<ChatInputProps>;
+
+export interface ChatHeaderProps {
+  title?: string;
+  subtitle?: string;
+  onClose?: () => void;
+  [key: string]: any;
+}
+
+export const ChatHeader: ComponentType<ChatHeaderProps>;
+
+export interface ModeToggleProps {
+  currentMode: 'sse' | 'websocket';
+  onModeChange: (mode: 'sse' | 'websocket') => void;
+  [key: string]: any;
+}
+
+export const ModeToggle: ComponentType<ModeToggleProps>;
+
+export interface StatusBlockProps {
+  status?: any;
+  message?: any;
+  [key: string]: any;
+}
+
+export const StatusBlock: ComponentType<StatusBlockProps>;
+
+export interface ShimmerTextProps {
+  text?: string;
+  [key: string]: any;
+}
+
+export const ShimmerText: ComponentType<ShimmerTextProps>;
+
+export interface StartChatProps {
+  error?: any;
+  miniMode?: boolean;
+  [key: string]: any;
+}
+
+export const StartChat: ComponentType<StartChatProps>;
+
+export interface LoadingResponseProps {
+  type?: 'text' | 'dots';
+  [key: string]: any;
+}
+
+export const LoadingResponse: ComponentType<LoadingResponseProps>;
+
+export interface ChatLoadingMockProps {
+  [key: string]: any;
+}
+
+export const ChatLoadingMock: ComponentType<ChatLoadingMockProps>;
+
+// ============================================================================
+// Services & Managers
+// ============================================================================
+
+export declare class TokenManager {
+  setTokens: (tokens: SessionData) => void;
+  setAuth: (auth: AuthConfig) => Promise<void>;
+  getAccessToken: () => string | null;
+  getRefreshToken: () => string | null;
+  clearTokens: () => void;
+  setRefreshCallback: (callback: (refreshToken: string) => Promise<any>) => void;
+  [key: string]: any;
+  
+  constructor();
+}
+
+export declare class SessionManager {
+  getSessionId: () => string | null;
+  setSessionId: (id: string) => void;
+  clearSession: () => void;
+  [key: string]: any;
+  
+  constructor();
+}
+
+export declare class ChatApi {
+  sendMessage: (message: string, sessionId?: string, files?: AttachedFile[]) => Promise<any>;
+  getHistory: (sessionId: string, limit?: number, offset?: number) => Promise<any>;
+  abort: () => void;
+  [key: string]: any;
+  
+  constructor(tokenManager: TokenManager, config?: any);
+}
+
+export declare class StreamService {
+  setMode: (mode: 'sse' | 'websocket', websocketService?: any) => void;
+  connect: (sessionId: string, onMessage: (data: any) => void, onError?: (error: Error) => void) => void;
+  disconnect: () => void;
+  isConnected: () => boolean;
+  on: (event: string, handler: (data: any) => void) => void;
+  off: (event: string, handler: (data: any) => void) => void;
+  startStream: (params: any, feedbackClient?: any, rawFeedback?: boolean) => Promise<any>;
+  abort: () => void;
+  [key: string]: any;
+  
+  constructor(chatApi: ChatApi);
+}
+
+export default class WebSocketService {
+  connect: (sessionId: string, onMessage: (data: any) => void, onError?: (error: Error) => void) => void;
+  disconnect: () => void;
+  send: (data: any) => void;
+  isConnected: () => boolean;
+  [key: string]: any;
+  
+  constructor();
+}
+
+// ============================================================================
+// Forwarding Hook
+// ============================================================================
+
+export interface UseForwardingReturn {
+  register: (action: string, handler: ForwardingHandler, options?: Partial<ForwardingHandlerConfig>) => () => void;
+  unregister: (action: string) => void;
+  getActiveSessions: () => string[];
+  getHandler: (action: string) => ForwardingHandlerConfig | undefined;
+  getAllHandlers: () => Array<{ action: string } & ForwardingHandlerConfig>;
+}
+
+export function useForwarding(
+  action: string,
+  handler: ForwardingHandler,
+  options?: Partial<ForwardingHandlerConfig>
+): UseForwardingReturn;
+
+export function useForwarding(
+  handlers: ForwardingHandlers
+): UseForwardingReturn;
+
+export function useForwarding(): UseForwardingReturn;
+
+// ============================================================================
+// Status Subscription Hook
+// ============================================================================
+
+export interface UseStatusSubscriptionOptions {
+  instanceId?: string;
+}
+
+export type StatusHandler = (statusData: any) => void;
+
+export type StatusHandlers = {
+  [action: string]: StatusHandler;
+};
+
+/**
+ * Hook to subscribe to status notifications from ChatProvider
+ * 
+ * @example Single action (inside ChatProvider)
+ * useStatusSubscription('tool_call', (statusData) => {
+ *   console.log('Tool call status:', statusData);
+ * });
+ * 
+ * @example Multiple actions
+ * useStatusSubscription({
+ *   tool_call: (data) => console.log('Tool:', data),
+ *   edit_file: (data) => console.log('Edit:', data)
+ * });
+ * 
+ * @example Listen to specific instance (outside ChatProvider)
+ * useStatusSubscription('tool_call', handler, { instanceId: 'agent-123' });
+ * 
+ * @example Global listener (all instances)
+ * useStatusSubscription('*', (data) => console.log('All statuses:', data));
+ */
+export function useStatusSubscription(
+  action: string,
+  handler: StatusHandler,
+  options?: UseStatusSubscriptionOptions
+): void;
+
+export function useStatusSubscription(
+  handlers: StatusHandlers,
+  handler?: never,
+  options?: UseStatusSubscriptionOptions
+): void;
+
+/**
+ * Context to provide instanceId for multi-instance support
+ * Used internally by ChatProvider
+ */
+export const ChatInstanceContext: React.Context<string | null>;
+
+// ============================================================================
+// Forwarding Manager
+// ============================================================================
+
+export declare class ForwardingManager {
+  handlers: ForwardingHandlers;
+  register(action: string, handler: ForwardingHandler, options?: Partial<ForwardingHandlerConfig>): () => void;
+  startSession(statusId: string, action: string): boolean;
+  endSession(statusId: string): void;
+  isActive(statusId: string): boolean;
+  getSession(statusId: string): any;
+  forwardChunk(statusId: string, newText: string, isLive?: boolean): boolean;
+  shouldReplace(statusId: string): boolean;
+  isAnimated(statusId: string): boolean;
+  getActiveSessions(): string[];
+  clearAll(): void;
+  constructor(forwardingHandlers?: ForwardingHandlers);
+}
+
+export function getGlobalForwardingManager(initialHandlers?: ForwardingHandlers): ForwardingManager;
+export function setGlobalForwardingManager(instance: ForwardingManager): void;
+export function resetGlobalForwardingManager(): void;
+
+// ============================================================================
+// Status Handler Registry
+// ============================================================================
+
+export interface StatusFilter {
+  instanceId?: string;
+}
+
+export declare class StatusHandlerRegistry {
+  handlers: Map<string, Array<{ handler: StatusHandler; filter: StatusFilter }>>;
+  globalHandlers: Array<{ handler: StatusHandler; filter: StatusFilter }>;
+  streamForwarders: Map<string, any>;
+  
+  /**
+   * Register a handler for a specific status type
+   * @param statusType - The status type to handle (e.g., 'tool_call', 'prompt_create')
+   * @param handler - Handler function (statusData) => void
+   * @param filter - Optional filter { instanceId: string }
+   */
+  register(statusType: string, handler: StatusHandler, filter?: StatusFilter): () => void;
+  
+  /**
+   * Register a global handler that receives all status messages
+   * @param handler - Handler function (statusData) => void
+   * @param filter - Optional filter { instanceId: string }
+   */
+  registerGlobal(handler: StatusHandler, filter?: StatusFilter): () => void;
+  
+  /**
+   * Execute handlers for a status message
+   * @param statusData - Status data from the stream
+   */
+  handle(statusData: any): Promise<void>;
+  
+  /**
+   * Register a stream forwarder
+   */
+  registerStreamForwarder(forwarder: any): { id: string; stop: () => void };
+  
+  /**
+   * Forward stream data to registered forwarders
+   */
+  forwardStream(messageId: string, data: any): void;
+  
+  /**
+   * Clear all handlers
+   */
+  clear(): void;
+  
+  constructor();
+}
+
+/**
+ * Get the global status registry (single instance - event bus pattern)
+ * This is the single source of truth for all status events
+ */
+export function getGlobalStatusRegistry(): StatusHandlerRegistry;
+
+// ============================================================================
+// Message Manager
+// ============================================================================
+
+export declare class MessageManager {
+  messages: any[];
+  subscribers: Set<(messages: any[]) => void>;
+  
+  addMessage(msg: any): any;
+  updateMessage(id: string, updates: any, options?: { silent?: boolean }): any;
+  removeMessage(id: string): boolean;
+  getMessage(id: string): any;
+  insertMessages(messages: any[], position?: 'start' | 'end'): void;
+  subscribe(callback: (messages: any[]) => void): () => void;
+  clear(): void;
+  
+  get count(): number;
+  
+  constructor();
+}
+
+// ============================================================================
+// CSS Import
+// ============================================================================
+
+declare module 'react-chat-agent/ui.css' {
+  const content: string;
+  export default content;
+}
+