/**
 * Robust Error Handling Utilities for NeuroLink
 * Provides structured error management for tool execution and system operations
 */
import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
import type { StructuredError } from "../types/index.js";
export declare const ERROR_CODES: {
    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
    readonly TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED";
    readonly TOOL_TIMEOUT: "TOOL_TIMEOUT";
    readonly TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED";
    readonly INVALID_PARAMETERS: "INVALID_PARAMETERS";
    readonly MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM";
    readonly MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED";
    readonly NETWORK_ERROR: "NETWORK_ERROR";
    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
    readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
    readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
    readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
    readonly OPERATION_ABORTED: "OPERATION_ABORTED";
    readonly INVALID_CONFIGURATION: "INVALID_CONFIGURATION";
    readonly MISSING_CONFIGURATION: "MISSING_CONFIGURATION";
    readonly INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION";
    readonly INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH";
    readonly INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO";
    readonly INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO";
    readonly INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE";
    readonly MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE";
    readonly EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT";
    readonly VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG";
    readonly EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH";
    readonly INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE";
    readonly IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
    readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
    readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
    readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
    readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
    readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
    readonly RATE_LIMITER_RESET: "RATE_LIMITER_RESET";
    readonly SCORER_NOT_FOUND: "SCORER_NOT_FOUND";
    readonly EVALUATION_VALIDATION_FAILED: "EVALUATION_VALIDATION_FAILED";
    readonly EVALUATION_TIMEOUT: "EVALUATION_TIMEOUT";
    readonly EVALUATION_EXECUTION_FAILED: "EVALUATION_EXECUTION_FAILED";
    readonly MISSING_PPT_PROPERTIES: "MISSING_PPT_PROPERTIES";
    readonly INVALID_PPT_PAGES: "INVALID_PPT_PAGES";
    readonly INVALID_PPT_FORMAT: "INVALID_PPT_FORMAT";
    readonly INVALID_PPT_PROVIDER: "INVALID_PPT_PROVIDER";
    readonly INVALID_PPT_OUTPUT_OPTIONS: "INVALID_PPT_OUTPUT_OPTIONS";
    readonly INVALID_PPT_OUTPUT_PATH: "INVALID_PPT_OUTPUT_PATH";
    readonly INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH";
    readonly INVALID_PPT_MODE: "INVALID_PPT_MODE";
    readonly INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT";
};
/**
 * Enhanced error class with structured information
 */
export declare class NeuroLinkError extends Error {
    readonly code: string;
    readonly category: ErrorCategory;
    readonly severity: ErrorSeverity;
    readonly retriable: boolean;
    readonly context: Record<string, unknown>;
    readonly timestamp: Date;
    readonly toolName?: string;
    readonly serverId?: string;
    constructor(options: {
        code: string;
        message: string;
        category: ErrorCategory;
        severity: ErrorSeverity;
        retriable: boolean;
        context?: Record<string, unknown>;
        originalError?: Error;
        toolName?: string;
        serverId?: string;
    });
    /**
     * Convert to JSON for logging and serialization
     */
    toJSON(): StructuredError;
}
/**
 * Error factory for common error scenarios
 */
export declare class ErrorFactory {
    /**
     * Create a tool not found error
     */
    static toolNotFound(toolName: string, availableTools?: string[]): NeuroLinkError;
    /**
     * Create a tool execution failed error
     */
    static toolExecutionFailed(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
    /**
     * Create a tool timeout error
     */
    static toolTimeout(toolName: string, timeoutMs: number, serverId?: string): NeuroLinkError;
    /**
     * Create a parameter validation error
     */
    static invalidParameters(toolName: string, validationError: Error, providedParams?: unknown): NeuroLinkError;
    /**
     * Create a network error
     */
    static networkError(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
    /**
     * Create a memory exhaustion error
     */
    static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
    /**
     * Create a typed abort error preserving the originating exception. Callers
     * can switch on `error.category === ErrorCategory.ABORT` and
     * `error.code === ERROR_CODES.OPERATION_ABORTED` instead of message-string
     * matching DOMException / AI SDK error wrappers.
     *
     * `error.name` is intentionally set to "AbortError" (overriding the default
     * "NeuroLinkError") so existing callers that branch on
     * `err.name === "AbortError"` keep working without code changes — the new
     * structured fields (category, code, retriable) are additive.
     */
    static aborted(originalError?: Error): NeuroLinkError;
    /**
     * Create a missing configuration error (e.g., missing API key)
     */
    static missingConfiguration(configName: string, context?: Record<string, unknown>): NeuroLinkError;
    /**
     * Create an invalid configuration error (e.g., NaN for numeric values)
     */
    static invalidConfiguration(configName: string, reason: string, context?: Record<string, unknown>): NeuroLinkError;
    /**
     * Create an invalid video resolution error
     */
    static invalidVideoResolution(resolution: string): NeuroLinkError;
    /**
     * Create an invalid video length error
     */
    static invalidVideoLength(length: number): NeuroLinkError;
    /**
     * Create an invalid video aspect ratio error
     */
    static invalidVideoAspectRatio(aspectRatio: string): NeuroLinkError;
    /**
     * Create an invalid video audio option error
     */
    static invalidVideoAudio(audio: unknown): NeuroLinkError;
    /**
     * Create an invalid video mode error
     */
    static invalidVideoMode(): NeuroLinkError;
    /**
     * Create a missing video image error
     */
    static missingVideoImage(): NeuroLinkError;
    /**
     * Create an empty video prompt error
     */
    static emptyVideoPrompt(): NeuroLinkError;
    /**
     * Create a video prompt too long error
     */
    static videoPromptTooLong(length: number, maxLength: number): NeuroLinkError;
    /**
     * Create an empty image path error
     */
    static emptyImagePath(): NeuroLinkError;
    /**
     * Create an invalid image type error
     */
    static invalidImageType(): NeuroLinkError;
    /**
     * Create a PDF page limit exceeded error
     */
    static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
    /**
     * Create an image too large error
     */
    static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
    /**
     * Create an image too small error
     */
    static imageTooSmall(): NeuroLinkError;
    /**
     * Create an invalid image format error
     */
    static invalidImageFormat(): NeuroLinkError;
    /**
     * Create a rate limiter queue full error
     */
    static rateLimiterQueueFull(maxQueueSize: number): NeuroLinkError;
    /**
     * Create a rate limiter queue timeout error
     */
    static rateLimiterQueueTimeout(timeoutMs: number): NeuroLinkError;
    /**
     * Create a rate limiter reset error
     */
    static rateLimiterReset(): NeuroLinkError;
    /**
     * Create a generic missing PPT property error
     */
    static missingPPTProperty(field: string, suggestions?: string[]): NeuroLinkError;
    /**
     * Create an invalid PPT pages error
     */
    static invalidPPTPages(pages: unknown, reason: string): NeuroLinkError;
    /**
     * Create an invalid PPT format error
     */
    static invalidPPTFormat(format: string): NeuroLinkError;
    /**
     * Create a generic invalid PPT output options error
     */
    static invalidPPTOutputOptions(field: string, value: unknown, validOptions?: string[]): NeuroLinkError;
    /**
     * Create an invalid PPT output path error
     */
    static invalidPPTOutputPath(path: unknown, reason: string): NeuroLinkError;
    /**
     * Create an invalid PPT mode error
     */
    static invalidPPTMode(): NeuroLinkError;
    /**
     * Create an invalid PPT prompt error
     */
    static invalidPPTPrompt(reason: string): NeuroLinkError;
    /**
     * Create an invalid PPT logo path error
     */
    static invalidPPTLogoPath(path: unknown, reason: string): NeuroLinkError;
    /**
     * Create an invalid PPT provider error
     */
    static invalidPPTProvider(provider: unknown): NeuroLinkError;
    /**
     * Create a scorer not found error
     */
    static scorerNotFound(scorerId: string, availableScorers?: string[]): NeuroLinkError;
    /**
     * Create an evaluation validation error
     */
    static evaluationValidationFailed(scorerId: string, errors: string[]): NeuroLinkError;
    /**
     * Create an evaluation timeout error
     */
    static evaluationTimeout(operation: string, timeoutMs: number): NeuroLinkError;
    /**
     * Create an evaluation execution failed error
     */
    static evaluationExecutionFailed(operation: string, originalError: Error): NeuroLinkError;
}
/**
 * Timeout wrapper for async operations
 */
export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutError?: Error): Promise<T>;
/**
 * Retry mechanism for retriable operations
 */
export declare function withRetry<T>(operation: () => Promise<T>, options: {
    maxAttempts: number;
    delayMs: number;
    isRetriable?: (error: Error) => boolean;
    onRetry?: (attempt: number, error: Error) => void;
}): Promise<T>;
/**
 * Circuit breaker for preventing cascading failures
 */
export declare class CircuitBreaker {
    private readonly failureThreshold;
    private readonly resetTimeoutMs;
    private failures;
    private lastFailureTime;
    private state;
    private name;
    constructor(failureThreshold?: number, resetTimeoutMs?: number, name?: string);
    execute<T>(operation: () => Promise<T>): Promise<T>;
    private onSuccess;
    private onFailure;
    getState(): "closed" | "open" | "half-open";
    getFailureCount(): number;
}
/**
 * Detect AbortError from any source (DOMException, plain Error, or message-based).
 * Used to short-circuit retry/fallback loops when an abort signal fires.
 *
 * Uses `includes()` for message checks because provider error handlers
 * (e.g., googleVertex.formatProviderError) wrap the original AbortError
 * in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
 * which destroys the exact message match.
 */
export declare function isAbortError(error: unknown): boolean;
/**
 * Error handler that decides whether to retry based on error type
 */
export declare function isRetriableError(error: Error): boolean;
/**
 * Determines if an error is likely recoverable (rate limit, timeout, network issues).
 * Useful for deciding whether to retry or fail fast.
 */
export declare function isRecoverableError(error: Error): boolean;
/**
 * Enhanced error logger that provides structured logging
 */
export declare function logStructuredError(error: NeuroLinkError, context?: Record<string, unknown>): void;