/**
 * Error handler utilities for Discord connector
 *
 * Provides:
 * - User-friendly error messages for Discord users
 * - Detailed logging for debugging
 * - Retry logic for transient failures
 * - Error classification and handling
 */
import type { DiscordConnectorLogger } from "./types.js";
/**
 * Standard user-friendly error messages for Discord responses
 */
export declare const USER_ERROR_MESSAGES: {
    /** Generic processing error */
    readonly PROCESSING_ERROR: "Sorry, I encountered an error processing your request. Please try again.";
    /** Connection/network error */
    readonly CONNECTION_ERROR: "I'm having trouble connecting right now. Please try again in a moment.";
    /** Rate limit error */
    readonly RATE_LIMITED: "I'm receiving too many requests right now. Please wait a moment and try again.";
    /** Command execution error */
    readonly COMMAND_ERROR: "Sorry, I couldn't complete that command. Please try again.";
    /** Session error */
    readonly SESSION_ERROR: "I'm having trouble with your conversation session. Please try again.";
    /** Timeout error */
    readonly TIMEOUT_ERROR: "The request took too long to complete. Please try again.";
    /** Permission error */
    readonly PERMISSION_ERROR: "I don't have permission to do that in this channel.";
};
/**
 * Categories of errors for handling purposes
 */
export declare enum ErrorCategory {
    /** Transient errors that may succeed on retry */
    TRANSIENT = "transient",
    /** Permanent errors that won't succeed on retry */
    PERMANENT = "permanent",
    /** Rate limit errors that need backoff */
    RATE_LIMIT = "rate_limit",
    /** Configuration/setup errors */
    CONFIGURATION = "configuration",
    /** Unknown/unexpected errors */
    UNKNOWN = "unknown"
}
/**
 * Classified error with category and user-friendly message
 */
interface ClassifiedError {
    /** Original error */
    error: Error;
    /** Error category for handling */
    category: ErrorCategory;
    /** User-friendly message to display */
    userMessage: string;
    /** Whether this error should be retried */
    shouldRetry: boolean;
    /** Suggested retry delay in milliseconds (if shouldRetry is true) */
    retryDelayMs?: number;
}
/**
 * Classify an error for appropriate handling
 *
 * @param error - The error to classify
 * @returns Classified error with category and handling info
 */
export declare function classifyError(error: unknown): ClassifiedError;
/**
 * Options for retry operations
 */
interface RetryOptions {
    /** Maximum number of retry attempts (default: 3) */
    maxAttempts?: number;
    /** Base delay between retries in ms (default: 1000) */
    baseDelayMs?: number;
    /** Maximum delay between retries in ms (default: 30000) */
    maxDelayMs?: number;
    /** Exponential backoff multiplier (default: 2) */
    backoffMultiplier?: number;
    /** Logger for retry attempts */
    logger?: DiscordConnectorLogger;
    /** Operation name for logging */
    operationName?: string;
    /** Predicate to determine if error should be retried */
    shouldRetry?: (error: unknown, attempt: number) => boolean;
}
/**
 * Result of a retry operation
 */
export interface RetryResult<T> {
    /** Whether the operation succeeded */
    success: boolean;
    /** The result value (if success is true) */
    value?: T;
    /** The last error encountered (if success is false) */
    error?: Error;
    /** Number of attempts made */
    attempts: number;
}
/**
 * Execute an async operation with retry logic
 *
 * Uses exponential backoff for transient failures.
 * Only retries errors that are classified as retryable.
 *
 * @param operation - Async function to execute
 * @param options - Retry configuration
 * @returns Result with success status, value, or error
 *
 * @example
 * ```typescript
 * const result = await withRetry(
 *   async () => {
 *     const response = await fetch(url);
 *     if (!response.ok) throw new Error('Request failed');
 *     return response.json();
 *   },
 *   {
 *     maxAttempts: 3,
 *     operationName: 'fetchData',
 *     logger: myLogger,
 *   }
 * );
 *
 * if (result.success) {
 *   console.log('Data:', result.value);
 * } else {
 *   console.error('Failed after', result.attempts, 'attempts:', result.error);
 * }
 * ```
 */
export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
/**
 * Options for the ErrorHandler
 */
export interface ErrorHandlerOptions {
    /** Logger for error logging */
    logger: DiscordConnectorLogger;
    /** Agent name for context in logs */
    agentName: string;
}
/**
 * Error handler that provides user-friendly messages and detailed logging
 *
 * Handles:
 * - Converting errors to user-friendly messages
 * - Logging detailed error information for debugging
 * - Tracking error statistics
 *
 * @example
 * ```typescript
 * const errorHandler = new ErrorHandler({
 *   logger: myLogger,
 *   agentName: 'my-agent',
 * });
 *
 * try {
 *   await someOperation();
 * } catch (error) {
 *   const userMessage = errorHandler.handleError(error, 'processing message');
 *   await message.reply(userMessage);
 * }
 * ```
 */
export declare class ErrorHandler {
    private readonly logger;
    private readonly agentName;
    private errorCounts;
    constructor(options: ErrorHandlerOptions);
    /**
     * Handle an error and return a user-friendly message
     *
     * Logs detailed error information and returns a safe message for users.
     *
     * @param error - The error to handle
     * @param context - Description of what operation was being performed
     * @returns User-friendly error message
     */
    handleError(error: unknown, context: string): string;
    /**
     * Handle an error with custom user message
     *
     * @param error - The error to handle
     * @param context - Description of what operation was being performed
     * @param userMessage - Custom message to return to user
     * @returns The provided user message
     */
    handleErrorWithMessage(error: unknown, context: string, userMessage: string): string;
    /**
     * Get error statistics
     *
     * @returns Map of error categories to counts
     */
    getErrorStats(): ReadonlyMap<ErrorCategory, number>;
    /**
     * Reset error statistics
     */
    resetStats(): void;
    /**
     * Check if an error is retryable
     *
     * @param error - The error to check
     * @returns true if the error should be retried
     */
    isRetryable(error: unknown): boolean;
    /**
     * Get the appropriate user message for an error
     *
     * @param error - The error to get message for
     * @returns User-friendly error message
     */
    getUserMessage(error: unknown): string;
}
/**
 * Execute an async function and handle errors safely
 *
 * Returns the result or undefined if an error occurs.
 * Always logs errors for debugging.
 *
 * @param operation - Async function to execute
 * @param errorHandler - Error handler for logging
 * @param context - Description of the operation
 * @returns Result or undefined on error
 */
export declare function safeExecute<T>(operation: () => Promise<T>, errorHandler: ErrorHandler, context: string): Promise<T | undefined>;
/**
 * Execute an async function that returns a reply to the user
 *
 * On error, returns a user-friendly error message instead.
 *
 * @param operation - Async function to execute that returns a message
 * @param errorHandler - Error handler for logging
 * @param context - Description of the operation
 * @returns Result message or error message
 */
export declare function safeExecuteWithReply(operation: () => Promise<string>, errorHandler: ErrorHandler, context: string): Promise<string>;
export {};
//# sourceMappingURL=error-handler.d.ts.map