@restnfeel/agentc-starter-kit/src/components/chatbot/customer/types.ts

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

// ================================================================
// AgentC Customer Chat Library - TypeScript Type Definitions
// ================================================================

import { ReactNode, ComponentType, CSSProperties } from 'react';

// ================================================================
// Core Chat Types
// ================================================================

export interface Message {
  id: string;
  content: string;
  sender: 'user' | 'ai' | 'system';
  timestamp: Date;
  type: 'text' | 'image' | 'file' | 'action';
  metadata?: Record<string, any>;
  status?: 'sending' | 'sent' | 'delivered' | 'read' | 'error';
}

export interface ChatSession {
  id: string;
  userId?: string;
  startTime: Date;
  lastActivity: Date;
  messages: Message[];
  context: Record<string, any>;
  status: 'active' | 'ended' | 'paused';
}

export interface ChatError {
  code: string;
  message: string;
  details?: any;
  timestamp: Date;
  recoverable: boolean;
}

// ================================================================
// Device & Responsive Types
// ================================================================

export enum DeviceType {
  DESKTOP = 'desktop',
  TABLET = 'tablet',
  MOBILE = 'mobile'
}

export enum ChatMode {
  DESKTOP = 'desktop',
  MOBILE = 'mobile',
  AUTO = 'auto'
}

export interface DeviceInfo {
  type: DeviceType;
  screenWidth: number;
  screenHeight: number;
  orientation: 'portrait' | 'landscape';
  isTouchDevice: boolean;
  isKeyboardVisible: boolean;
  userAgent: string;
  pixelRatio: number;
  viewport: {
    width: number;
    height: number;
  };
}

export interface DeviceBreakpoints {
  mobile: number;
  tablet: number;
  desktop: number;
}

// ================================================================
// Theme & Styling Types
// ================================================================

export interface ChatbotTheme {
  primary: string;
  secondary: string;
  background: string;
  surface: string;
  text: {
    primary: string;
    secondary: string;
    inverse: string;
  };
  border: string;
  shadow: string;
  success: string;
  warning: string;
  error: string;
  radius: {
    sm: string;
    md: string;
    lg: string;
    full: string;
  };
  spacing: {
    xs: string;
    sm: string;
    md: string;
    lg: string;
    xl: string;
  };
  typography: {
    fontFamily: string;
    fontSize: {
      xs: string;
      sm: string;
      md: string;
      lg: string;
      xl: string;
    };
    fontWeight: {
      normal: string;
      medium: string;
      semibold: string;
      bold: string;
    };
  };
}

export type ThemeName = 'default' | 'dark' | 'compact' | string;

export interface ThemeConfig {
  name: ThemeName;
  theme: ChatbotTheme;
  variables?: Record<string, string>;
}

// ================================================================
// Internationalization Types
// ================================================================

export interface ChatbotTranslations {
  chatbot: string;
  placeholder: string;
  send: string;
  typing: string;
  retry: string;
  error: string;
  close: string;
  minimize: string;
  maximize: string;
  welcome: string;
  goodbye: string;
  // 추가 번역 키들
  [key: string]: string;
}

export type SupportedLanguage = 'ko' | 'en' | 'ja' | 'zh' | 'es' | 'fr' | 'de';

export interface LanguageInfo {
  code: SupportedLanguage;
  name: string;
  nativeName: string;
  isRTL: boolean;
}

export interface I18nConfig {
  defaultLanguage: SupportedLanguage;
  fallbackLanguage: SupportedLanguage;
  translations: Record<SupportedLanguage, ChatbotTranslations>;
  languages: Record<SupportedLanguage, LanguageInfo>;
}

// ================================================================
// Configuration Types
// ================================================================

export interface ApiConfig {
  baseUrl?: string;
  apiKey?: string;
  timeout?: number;
  retryAttempts?: number;
  headers?: Record<string, string>;
}

export interface PerformanceConfig {
  enableOptimization: boolean;
  enableMemoryManagement: boolean;
  enableGarbageCollection: boolean;
  memoryThreshold: number;
  maxCacheSize: number;
  debounceMs: number;
  throttleMs: number;
}

export interface AccessibilityConfig {
  enableScreenReader: boolean;
  enableKeyboardNavigation: boolean;
  enableHighContrast: boolean;
  enableFocusVisible: boolean;
  ariaLabels: Record<string, string>;
}

export interface AnalyticsConfig {
  enabled: boolean;
  trackPageViews: boolean;
  trackInteractions: boolean;
  trackErrors: boolean;
  customEvents: boolean;
  provider?: 'ga' | 'gtm' | 'custom';
  trackingId?: string;
}

// ================================================================
// Component Props Types
// ================================================================

export interface BaseComponentProps {
  className?: string;
  style?: CSSProperties;
  children?: ReactNode;
  'data-testid'?: string;
}

export interface FloatingButtonProps extends BaseComponentProps {
  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  size: 'small' | 'medium' | 'large';
  color?: string;
  icon?: ReactNode;
  label?: string;
  disabled?: boolean;
  onClick?: () => void;
  onHover?: () => void;
  animationDuration?: number;
}

export interface ChatWidgetProps extends BaseComponentProps {
  apiConfig?: ApiConfig;
  theme?: ThemeName | ChatbotTheme;
  language?: SupportedLanguage;
  title?: string;
  placeholder?: string;
  welcomeMessage?: string;
  enableTypingIndicator?: boolean;
  enableSuggestedQuestions?: boolean;
  enableFileUpload?: boolean;
  maxFileSize?: number;
  allowedFileTypes?: string[];
  onMessage?: (message: Message) => void;
  onError?: (error: ChatError) => void;
  onClose?: () => void;
  onMinimize?: () => void;
}

export interface ResponsiveChatSystemProps extends BaseComponentProps {
  config: ResponsiveChatSystemConfig;
  deviceBreakpoints?: DeviceBreakpoints;
  enableDebug?: boolean;
  onDeviceChange?: (deviceInfo: DeviceInfo) => void;
  onModeChange?: (mode: ChatMode) => void;
  onError?: (error: ChatError) => void;
}

// ================================================================
// Library Configuration Types
// ================================================================

export interface ResponsiveChatSystemConfig {
  // Device detection
  mobileBreakpoint: number;
  tabletBreakpoint: number;
  desktopBreakpoint: number;
  
  // Chat behavior
  defaultChatMode: ChatMode;
  enableTransitions: boolean;
  animationDuration: number;
  
  // Performance
  performance: PerformanceConfig;
  
  // Accessibility
  accessibility: AccessibilityConfig;
  
  // Analytics
  analytics?: AnalyticsConfig;
  
  // Debug
  enableDebug: boolean;
  debugLevel: 'error' | 'warn' | 'info' | 'debug';
}

export interface UnifiedCustomerChatLibraryConfig extends ResponsiveChatSystemConfig {
  // API 설정
  api: ApiConfig;
  
  // UI 설정
  ui: {
    theme: ThemeName | ChatbotTheme;
    brandName: string;
    logo?: string;
    primaryColor?: string;
    enableThemeToggle: boolean;
  };
  
  // 언어 설정
  i18n: {
    defaultLanguage: SupportedLanguage;
    enableLanguageSelector: boolean;
    autoDetectLanguage: boolean;
  };
  
  // 기능 설정
  features: {
    enableSuggestedQuestions: boolean;
    enableTypingIndicator: boolean;
    enableFileUpload: boolean;
    enableChatHistory: boolean;
    enableRealTimeSync: boolean;
    enableNotifications: boolean;
  };
  
  // 플로팅 버튼 설정
  floatingButton: {
    enabled: boolean;
    position: FloatingButtonProps['position'];
    size: FloatingButtonProps['size'];
    customIcon?: ReactNode;
    showBadge: boolean;
  };
  
  // 보안 설정
  security: {
    enableCSP: boolean;
    allowedOrigins?: string[];
    enableEncryption: boolean;
    sessionTimeout: number;
  };
}

// ================================================================
// Event Types
// ================================================================

export interface ChatEvent {
  type: string;
  timestamp: Date;
  data: any;
  sessionId?: string;
  messageId?: string;
}

export interface ChatEventHandlers {
  onMessageSent?: (message: Message) => void;
  onMessageReceived?: (message: Message) => void;
  onTypingStart?: () => void;
  onTypingStop?: () => void;
  onChatOpen?: () => void;
  onChatClose?: () => void;
  onError?: (error: ChatError) => void;
  onSessionStart?: (session: ChatSession) => void;
  onSessionEnd?: (session: ChatSession) => void;
  onDeviceChange?: (deviceInfo: DeviceInfo) => void;
  onThemeChange?: (theme: ThemeName) => void;
  onLanguageChange?: (language: SupportedLanguage) => void;
}

// ================================================================
// Hook Return Types
// ================================================================

export interface UseChatReturn {
  // 상태
  isOpen: boolean;
  isConnected: boolean;
  isTyping: boolean;
  messages: Message[];
  session: ChatSession | null;
  
  // 액션
  sendMessage: (content: string) => Promise<void>;
  openChat: () => void;
  closeChat: () => void;
  toggleChat: () => void;
  clearHistory: () => void;
  
  // 설정
  changeTheme: (theme: ThemeName) => void;
  changeLanguage: (language: SupportedLanguage) => void;
}

export interface UseDeviceDetectionReturn {
  deviceInfo: DeviceInfo;
  isDesktop: boolean;
  isTablet: boolean;
  isMobile: boolean;
  orientation: 'portrait' | 'landscape';
  breakpoint: 'mobile' | 'tablet' | 'desktop';
}

export interface UseResponsiveChatReturn extends UseChatReturn, UseDeviceDetectionReturn {
  chatMode: ChatMode;
  setChatMode: (mode: ChatMode) => void;
  config: ResponsiveChatSystemConfig;
}

// ================================================================
// Plugin & Extension Types
// ================================================================

export interface ChatPlugin {
  name: string;
  version: string;
  enabled: boolean;
  config?: Record<string, any>;
  initialize?: (context: ChatPluginContext) => void;
  destroy?: () => void;
}

export interface ChatPluginContext {
  api: any;
  ui: any;
  events: any;
  utils: any;
}

export interface CustomComponent {
  name: string;
  component: ComponentType<any>;
  props?: Record<string, any>;
  position?: 'header' | 'footer' | 'sidebar' | 'overlay';
}

// ================================================================
// Utility Types
// ================================================================

export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

export type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;

export type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

export type EventCallback<T = any> = (data: T) => void | Promise<void>;

export type AsyncFunction<T = any> = (...args: any[]) => Promise<T>;

// ================================================================
// Constants Types
// ================================================================

export const CHAT_EVENTS = {
  MESSAGE_SENT: 'message_sent',
  MESSAGE_RECEIVED: 'message_received',
  TYPING_START: 'typing_start',
  TYPING_STOP: 'typing_stop',
  CHAT_OPEN: 'chat_open',
  CHAT_CLOSE: 'chat_close',
  ERROR: 'error',
  SESSION_START: 'session_start',
  SESSION_END: 'session_end',
  DEVICE_CHANGE: 'device_change',
  THEME_CHANGE: 'theme_change',
  LANGUAGE_CHANGE: 'language_change'
} as const;

export type ChatEventType = typeof CHAT_EVENTS[keyof typeof CHAT_EVENTS];

export const DEFAULT_CONFIG: DeepPartial<UnifiedCustomerChatLibraryConfig> = {
  mobileBreakpoint: 768,
  tabletBreakpoint: 1024,
  desktopBreakpoint: 1200,
  defaultChatMode: ChatMode.AUTO,
  enableTransitions: true,
  animationDuration: 300,
  enableDebug: false,
  debugLevel: 'warn',
  
  api: {
    timeout: 10000,
    retryAttempts: 3
  },
  
  ui: {
    theme: 'default',
    brandName: 'AgentC',
    enableThemeToggle: false
  },
  
  i18n: {
    defaultLanguage: 'ko',
    enableLanguageSelector: false,
    autoDetectLanguage: true
  },
  
  features: {
    enableSuggestedQuestions: true,
    enableTypingIndicator: true,
    enableFileUpload: false,
    enableChatHistory: true,
    enableRealTimeSync: false,
    enableNotifications: false
  },
  
  floatingButton: {
    enabled: true,
    position: 'bottom-right',
    size: 'medium',
    showBadge: true
  },
  
  performance: {
    enableOptimization: true,
    enableMemoryManagement: true,
    enableGarbageCollection: true,
    memoryThreshold: 0.8,
    maxCacheSize: 100,
    debounceMs: 300,
    throttleMs: 100
  },
  
  accessibility: {
    enableScreenReader: true,
    enableKeyboardNavigation: true,
    enableHighContrast: false,
    enableFocusVisible: true,
    ariaLabels: {}
  },
  
  security: {
    enableCSP: true,
    enableEncryption: false,
    sessionTimeout: 3600000 // 1시간
  }
} as const;