@orchard9ai/error-handling/src/types/index.ts

Federated error handling package with go-core-http-toolkit format support and logging integration

/**
 * Error handling types based on go-core-http-toolkit format
 * @module @orchard9ai/error-handling/types
 */

/**
 * Standard API error format from go-core-http-toolkit
 */
export interface ApiError {
  /** Human-readable error message describing what went wrong */
  error: string;
  /** Machine-readable error code like VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED */
  code?: string;
  /** Map of additional context, often used for field-level validation errors */
  details?: Record<string, string>;
  /** Optional trace ID added by observability middleware for distributed tracing */
  trace_id?: string;
}

/**
 * HTTP response interface matching your API format
 */
export interface HttpErrorResponse {
  error: string;
  message: string;
  code: string;
  correlation_id: string;
  details?: {
    field?: string;
    resource?: string;
    value?: string;
    [key: string]: any;
  };
  timestamp: string;
}

/**
 * HTTP client configuration options
 */
export interface HttpClientConfig {
  /** Base URL for all requests */
  baseUrl?: string;
  /** Default headers to include with requests */
  defaultHeaders?: Record<string, string>;
  /** Timeout in milliseconds */
  timeout?: number;
  /** Whether to enable retry on failure (disabled by default) */
  enableRetry?: boolean;
  /** Number of retry attempts if enabled */
  retryAttempts?: number;
  /** Retry delay in milliseconds */
  retryDelay?: number;
  /** Custom error handler callback */
  onError?: (error: any, displayError: DisplayError) => void;
  /** Whether to show toast notifications for errors */
  showToasts?: boolean;
  /** Error handler configuration */
  errorHandlerConfig?: Partial<ErrorHandlerConfig>;
}

/**
 * Enhanced request configuration
 */
export interface HttpRequestConfig extends RequestInit {
  /** Request timeout override */
  timeout?: number;
  /** Skip retry for this request */
  skipRetry?: boolean;
  /** Custom error context */
  errorContext?: Partial<ErrorContext>;
}

/**
 * HTTP client response wrapper
 */
export interface HttpResponse<T = any> {
  data: T;
  status: number;
  statusText: string;
  headers: Headers;
  url: string;
}

/**
 * Global error handler configuration
 */
export interface GlobalErrorHandlerConfig {
  /** Whether to enable global error handling */
  enabled?: boolean;
  /** Whether to show toast notifications for errors */
  showToasts?: boolean;
  /** Whether to log errors to console */
  logToConsole?: boolean;
  /** Custom error handler callback */
  onError?: ((error: Error, displayError: DisplayError, context: ErrorContext) => void) | undefined;
  /** Custom unhandled rejection handler */
  onUnhandledRejection?: ((reason: any, promise: Promise<any>, displayError: DisplayError) => void) | undefined;
  /** Error handler configuration */
  errorHandlerConfig?: Partial<ErrorHandlerConfig>;
  /** Errors to ignore (by message or error type) */
  ignoredErrors?: string[];
  /** Maximum number of errors to handle per minute (rate limiting) */
  maxErrorsPerMinute?: number;
}

/**
 * Error statistics for monitoring
 */
export interface ErrorStats {
  totalErrors: number;
  errorsByType: Record<string, number>;
  errorsByMinute: number[];
  lastError?: {
    message: string;
    timestamp: Date;
    context?: ErrorContext;
  };
}

/**
 * Toast notification configuration
 */
export interface ToastConfig {
  /** Auto-dismiss timeout in milliseconds (0 = no auto-dismiss) */
  autoHideDuration?: number;
  /** Position of the toast */
  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';
  /** Maximum number of toasts to show */
  maxToasts?: number;
  /** Animation duration in milliseconds */
  animationDuration?: number;
}

/**
 * Toast item interface
 */
export interface ToastItem {
  id: string;
  displayError: DisplayError;
  timestamp: number;
  dismissed?: boolean;
}

/**
 * Error context for additional information
 */
export interface ErrorContext {
  /** User ID if authenticated */
  userId?: string;
  /** Session ID */
  sessionId?: string;
  /** Request ID for tracing */
  requestId?: string;
  /** Component or feature where error occurred */
  component?: string;
  /** Action being performed when error occurred */
  action?: string;
  /** Additional metadata */
  metadata?: Record<string, unknown>;
}

/**
 * Display-friendly error for UI components
 */
export interface DisplayError {
  /** Title for error display */
  title: string;
  /** Description for user */
  message: string;
  /** Type of error for styling */
  type: 'error' | 'warning' | 'info';
  /** Whether error can be retried */
  retryable: boolean;
  /** Suggested actions for user */
  actions?: ErrorAction[];
  /** Field-specific errors for forms */
  fieldErrors: Record<string, string>;
}

/**
 * Suggested action for error recovery
 */
export interface ErrorAction {
  /** Action label */
  label: string;
  /** Action handler */
  handler: () => void;
  /** Action type for styling */
  type?: 'primary' | 'secondary' | 'danger';
}

/**
 * Error severity levels
 */
export enum ErrorSeverity {
  /** Low severity - informational */
  Low = 'low',
  /** Medium severity - warning */
  Medium = 'medium', 
  /** High severity - error */
  High = 'high',
  /** Critical severity - system failure */
  Critical = 'critical'
}

/**
 * Error categories for classification
 */
export enum ErrorCategory {
  /** Network/connectivity errors */
  Network = 'network',
  /** Authentication/authorization errors */
  Auth = 'auth',
  /** Input validation errors */
  Validation = 'validation',
  /** Business logic errors */
  Business = 'business',
  /** System/server errors */
  System = 'system',
  /** Unknown errors */
  Unknown = 'unknown'
}

/**
 * Error handler configuration
 */
export interface ErrorHandlerConfig {
  /** Whether to enable logging */
  enableLogging: boolean;
  /** Whether to enable monitoring integration */
  enableMonitoring: boolean;
  /** Default error messages for codes */
  defaultMessages: Record<string, string>;
  /** Custom error transformers */
  transformers: Record<string, (error: ApiError) => DisplayError>;
  /** Logger name for error logs */
  loggerName: string;
}