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

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

/**
 * @fileoverview Event type definitions for the RAG chatbot system
 * @module types/events
 */

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

/**
 * Base event interface
 */
export interface BaseEvent {
  /** Event type */
  type: string;
  /** Event timestamp */
  timestamp: Date;
  /** Event source */
  source: string;
  /** Event metadata */
  metadata?: Record<string, any>;
}

/**
 * Chatbot lifecycle events
 */
export interface ChatbotInitializedEvent extends BaseEvent {
  type: "chatbot:initialized";
  data: {
    config: any;
    initTime: number;
  };
}

export interface ChatbotResetEvent extends BaseEvent {
  type: "chatbot:reset";
  data: {
    reason?: string;
  };
}

export interface ChatbotErrorEvent extends BaseEvent {
  type: "chatbot:error";
  data: {
    error: ChatbotError;
    context?: string;
  };
}

/**
 * Conversation events
 */
export interface ConversationStartedEvent extends BaseEvent {
  type: "conversation:started";
  data: {
    conversationId: string;
    initiatedBy: "user" | "system";
  };
}

export interface ConversationEndedEvent extends BaseEvent {
  type: "conversation:ended";
  data: {
    conversationId: string;
    duration: number;
    messageCount: number;
    reason: "user" | "timeout" | "error";
  };
}

export interface ConversationSwitchedEvent extends BaseEvent {
  type: "conversation:switched";
  data: {
    fromConversationId: string | null;
    toConversationId: string;
  };
}

/**
 * Message events
 */
export interface MessageSentEvent extends BaseEvent {
  type: "message:sent";
  data: {
    message: ConversationMessage;
    conversationId: string;
    processingTime?: number;
  };
}

export interface MessageReceivedEvent extends BaseEvent {
  type: "message:received";
  data: {
    message: ConversationMessage;
    conversationId: string;
    sources?: any[];
    processingTime: number;
  };
}

export interface MessageErrorEvent extends BaseEvent {
  type: "message:error";
  data: {
    messageId: string;
    error: ChatbotError;
    conversationId: string;
    retryCount?: number;
  };
}

/**
 * Document events
 */
export interface DocumentUploadStartedEvent extends BaseEvent {
  type: "document:upload:started";
  data: {
    files: Array<{
      name: string;
      size: number;
      type: string;
    }>;
    totalSize: number;
  };
}

export interface DocumentUploadProgressEvent extends BaseEvent {
  type: "document:upload:progress";
  data: {
    fileName: string;
    progress: number;
    uploaded: number;
    total: number;
    stage: string;
  };
}

export interface DocumentUploadCompletedEvent extends BaseEvent {
  type: "document:upload:completed";
  data: {
    documents: Document[];
    totalTime: number;
    successCount: number;
    failureCount: number;
  };
}

export interface DocumentUploadErrorEvent extends BaseEvent {
  type: "document:upload:error";
  data: {
    fileName: string;
    error: Error;
    stage: string;
  };
}

export interface DocumentDeletedEvent extends BaseEvent {
  type: "document:deleted";
  data: {
    documentIds: string[];
    deletedCount: number;
  };
}

/**
 * Search events
 */
export interface SearchStartedEvent extends BaseEvent {
  type: "search:started";
  data: {
    query: string;
    method: "vector" | "keyword" | "hybrid";
    filters?: Record<string, any>;
  };
}

export interface SearchCompletedEvent extends BaseEvent {
  type: "search:completed";
  data: {
    query: string;
    results: Document[];
    resultCount: number;
    searchTime: number;
    method: string;
  };
}

export interface SearchErrorEvent extends BaseEvent {
  type: "search:error";
  data: {
    query: string;
    error: ChatbotError;
  };
}

/**
 * System events
 */
export interface SystemHealthCheckEvent extends BaseEvent {
  type: "system:health:check";
  data: {
    healthy: boolean;
    components: {
      vectorStore: boolean;
      llm: boolean;
      storage: boolean;
    };
    responseTime: number;
  };
}

export interface ComponentConnectedEvent extends BaseEvent {
  type: "component:connected";
  data: {
    component: "vectorStore" | "llm" | "storage";
    config: any;
    connectionTime: number;
  };
}

export interface ComponentDisconnectedEvent extends BaseEvent {
  type: "component:disconnected";
  data: {
    component: "vectorStore" | "llm" | "storage";
    reason: string;
  };
}

export interface ComponentErrorEvent extends BaseEvent {
  type: "component:error";
  data: {
    component: "vectorStore" | "llm" | "storage";
    error: ChatbotError;
    operation?: string;
  };
}

/**
 * User interaction events
 */
export interface UserEngagementEvent extends BaseEvent {
  type: "user:engagement";
  data: {
    action:
      | "widget:opened"
      | "widget:closed"
      | "message:sent"
      | "question:clicked";
    duration?: number;
    context?: string;
  };
}

export interface UserFeedbackEvent extends BaseEvent {
  type: "user:feedback";
  data: {
    messageId: string;
    rating: number;
    feedback?: string;
    helpful: boolean;
  };
}

/**
 * Performance events
 */
export interface PerformanceMetricEvent extends BaseEvent {
  type: "performance:metric";
  data: {
    metric: string;
    value: number;
    unit: string;
    context?: string;
  };
}

/**
 * Union type of all events
 */
export type ChatbotEvent =
  | ChatbotInitializedEvent
  | ChatbotResetEvent
  | ChatbotErrorEvent
  | ConversationStartedEvent
  | ConversationEndedEvent
  | ConversationSwitchedEvent
  | MessageSentEvent
  | MessageReceivedEvent
  | MessageErrorEvent
  | DocumentUploadStartedEvent
  | DocumentUploadProgressEvent
  | DocumentUploadCompletedEvent
  | DocumentUploadErrorEvent
  | DocumentDeletedEvent
  | SearchStartedEvent
  | SearchCompletedEvent
  | SearchErrorEvent
  | SystemHealthCheckEvent
  | ComponentConnectedEvent
  | ComponentDisconnectedEvent
  | ComponentErrorEvent
  | UserEngagementEvent
  | UserFeedbackEvent
  | PerformanceMetricEvent;

/**
 * Event listener function type
 */
export type EventListener<T extends ChatbotEvent = ChatbotEvent> = (
  event: T
) => void;

/**
 * Event emitter interface
 */
export interface EventEmitter {
  /** Add event listener */
  on<T extends ChatbotEvent>(type: T["type"], listener: EventListener<T>): void;
  /** Remove event listener */
  off<T extends ChatbotEvent>(
    type: T["type"],
    listener: EventListener<T>
  ): void;
  /** Emit event */
  emit<T extends ChatbotEvent>(event: T): void;
  /** Remove all listeners */
  removeAllListeners(type?: string): void;
}