/**
 * @fileoverview Main ErrorHandler implementation with logging and telemetry integration.
 * Provides error classification, formatting, and consistent error handling patterns.
 * @module src/utils/internal/error-handler/errorHandler
 */
import { JsonRpcErrorCode } from '../../../types-global/errors.js';
import type { ErrorHandlerOptions, ErrorMapping } from './types.js';
/** Eagerly creates the error classification counter so the series exists from startup. */
export declare function initErrorMetrics(): void;
/**
 * A utility class providing static methods for comprehensive error handling.
 */
export declare class ErrorHandler {
    /**
     * Determines an appropriate `JsonRpcErrorCode` for a given error.
     *
     * Resolution order:
     * 1. `McpError` instances — returns `error.code` directly.
     * 2. Standard JS error constructor names via `ERROR_TYPE_MAPPINGS` (e.g. `TypeError` → `ValidationError`).
     * 3. Provider-specific patterns (AWS, HTTP status codes, Supabase, OpenRouter) — checked before common patterns for specificity.
     * 4. Common message/name patterns (auth, not-found, rate-limit, etc.).
     * 5. `AbortError` name — mapped to `Timeout`.
     * 6. Falls back to `JsonRpcErrorCode.InternalError`.
     *
     * @param error - The error instance or value to classify.
     * @returns The most specific `JsonRpcErrorCode` that fits the error.
     *
     * @example
     * ```ts
     * ErrorHandler.determineErrorCode(new McpError(JsonRpcErrorCode.NotFound, 'missing'));
     * // → JsonRpcErrorCode.NotFound
     *
     * ErrorHandler.determineErrorCode(new TypeError('Cannot read properties of undefined'));
     * // → JsonRpcErrorCode.InternalError (falls through to default)
     *
     * ErrorHandler.determineErrorCode(new Error('status code 429'));
     * // → JsonRpcErrorCode.RateLimited
     * ```
     */
    static determineErrorCode(error: unknown): JsonRpcErrorCode;
    /**
     * Handles an error with consistent logging, OpenTelemetry integration, and optional transformation.
     *
     * Steps performed:
     * 1. Records the exception on the active OTel span and sets span status to ERROR.
     * 2. Sanitizes `options.input` via `sanitizeInputForLogging` before including in logs.
     * 3. Extracts and consolidates error data, original stack, and the full cause chain.
     * 4. Wraps non-`McpError` errors in a new `McpError` (or delegates to `options.errorMapper`).
     * 5. Logs the result at `error` level via the global logger with full structured context.
     * 6. Returns the processed error, or rethrows it if `options.rethrow` is `true`.
     *
     * @param error - The error instance or value that occurred.
     * @param options - Configuration controlling transformation, logging, and rethrow behavior.
     * @returns The processed `Error` instance (a `McpError` unless `errorMapper` returns something else).
     *
     * @example
     * ```ts
     * // Log and return without rethrowing
     * const handled = ErrorHandler.handleError(err, { operation: 'fetchUser', context: { requestId } });
     *
     * // Log and rethrow
     * ErrorHandler.handleError(err, { operation: 'fetchUser', rethrow: true });
     *
     * // Custom error transformation
     * ErrorHandler.handleError(err, {
     *   operation: 'fetchUser',
     *   errorMapper: (e) => new MyDomainError(getErrorMessage(e)),
     * });
     * ```
     */
    static handleError(error: unknown, options: ErrorHandlerOptions): Error;
    /**
     * Classifies an error and returns its JSON-RPC error code and message without
     * logging, OTel side effects, or error wrapping. Use this when you need error
     * classification but the caller handles logging/rethrowing (e.g., resource
     * handler factory where the SDK logs the re-thrown error).
     *
     * @param error - The error instance or value to classify.
     * @returns `{ code, message, data? }` — the classified error code, a human-readable
     *          message, and optional structured data (populated for `ZodError` with
     *          the full `issues` array so clients can render field-level errors).
     */
    static classifyOnly(error: unknown): {
        code: JsonRpcErrorCode;
        message: string;
        data?: Record<string, unknown>;
    };
    /**
     * Maps an error to a specific error type `T` by testing it against an ordered list of `ErrorMapping` rules.
     *
     * Each mapping's `pattern` is tested (case-insensitively) against both the error message and error name.
     * The first matching rule's `factory` is called with the original error and the mapping's `additionalContext`.
     * If no rule matches and `defaultFactory` is provided, it is called instead.
     * If neither matches, returns the original `Error` or wraps non-Error values in a plain `Error`.
     *
     * @template T The target error type, extending `Error`.
     * @param error - The error instance or value to map.
     * @param mappings - An ordered array of mapping rules; first match wins.
     * @param defaultFactory - Optional factory invoked when no mapping rule matches.
     * @returns The mapped error of type `T`, or the original/wrapped error if no rule matched.
     *
     * @example
     * ```ts
     * const mapped = ErrorHandler.mapError(err, [
     *   {
     *     pattern: /not found/i,
     *     errorCode: JsonRpcErrorCode.NotFound,
     *     factory: (e) => new McpError(JsonRpcErrorCode.NotFound, getErrorMessage(e)),
     *   },
     * ]);
     * ```
     */
    static mapError<T extends Error>(error: unknown, mappings: ReadonlyArray<ErrorMapping<T>>, defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
    /**
     * Formats an error into a consistent `{ code, message, data }` structure for API responses or structured logging.
     *
     * - `McpError` → `{ code: error.code, message: error.message, data: error.data ?? {} }`
     * - `Error` → `{ code: determineErrorCode(error), message: error.message, data: { errorType: error.name } }`
     * - Other values → `{ code: JsonRpcErrorCode.UnknownError, message: getErrorMessage(value), data: { errorType: getErrorName(value) } }`
     *
     * @param error - The error instance or value to format.
     * @returns A plain object with `code` (numeric `JsonRpcErrorCode`), `message` (string), and `data` (object).
     *
     * @example
     * ```ts
     * const formatted = ErrorHandler.formatError(new McpError(JsonRpcErrorCode.NotFound, 'Item missing'));
     * // → { code: -32001, message: 'Item missing', data: {} }
     *
     * const formatted2 = ErrorHandler.formatError(new TypeError('bad arg'));
     * // → { code: -32007, message: 'bad arg', data: { errorType: 'TypeError' } }
     * ```
     */
    static formatError(error: unknown): Record<string, unknown>;
    /**
     * Safely executes a synchronous or asynchronous function, logging and rethrowing any error.
     *
     * Equivalent to wrapping `fn` in a try/catch that calls `ErrorHandler.handleError` with `rethrow: true`.
     * The processed `McpError` (or custom-mapped error) is always thrown — this method never swallows errors.
     * Use this in service code where you want structured logging and OTel integration without duplicating
     * error-handling boilerplate.
     *
     * @template T The expected return type of `fn`.
     * @param fn - The function to execute. May be synchronous or return a `Promise`.
     * @param options - Error handling options passed to `handleError` (`rethrow` is always `true` and cannot be overridden).
     * @returns A promise that resolves with the return value of `fn` on success.
     * @throws {McpError | Error} The processed error from `ErrorHandler.handleError` on failure.
     *
     * @example
     * ```ts
     * const user = await ErrorHandler.tryCatch(
     *   () => db.findUser(id),
     *   { operation: 'findUser', context: { requestId, userId: id } },
     * );
     * ```
     */
    static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, 'rethrow'>): Promise<T>;
}
//# sourceMappingURL=errorHandler.d.ts.map