/**
 * @unbrowser/core - Error Types
 *
 * Structured error types with clear codes, messages, and recovery guidance.
 * Every error includes actionable suggestions for resolution.
 *
 * @module errors
 * @packageDocumentation
 */
/**
 * Error codes used by the Unbrowser SDK.
 *
 * @description
 * Each code represents a specific error category with a defined recovery path.
 * Use these codes in switch statements or error handling logic.
 *
 * @example
 * ```typescript
 * try {
 *   await client.browse(url);
 * } catch (error) {
 *   if (error instanceof UnbrowserError) {
 *     switch (error.code) {
 *       case 'RATE_LIMITED':
 *         await delay(error.retryAfter || 60000);
 *         break;
 *       case 'INVALID_URL':
 *         console.error('URL validation failed');
 *         break;
 *     }
 *   }
 * }
 * ```
 */
export type ErrorCode = 'MISSING_API_KEY' | 'INVALID_API_KEY' | 'EXPIRED_API_KEY' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'INVALID_REQUEST' | 'INVALID_URL' | 'URL_BLOCKED' | 'TIMEOUT' | 'REQUEST_ABORTED' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'CONTENT_NOT_FOUND' | 'CONTENT_BLOCKED' | 'CAPTCHA_DETECTED' | 'BOT_DETECTED' | 'NETWORK_ERROR' | 'DNS_ERROR' | 'SSL_ERROR' | 'CONNECTION_REFUSED' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE' | 'SSE_ERROR' | 'HEALTH_CHECK_FAILED' | 'VERIFICATION_FAILED' | 'CONTENT_MISMATCH' | 'UNKNOWN_ERROR';
/**
 * Detailed guidance for recovering from an error.
 *
 * @description
 * Every error includes recovery guidance to help LLMs understand
 * how to resolve the issue without human intervention.
 */
export interface ErrorRecovery {
    /**
     * Whether the request can be retried.
     */
    canRetry: boolean;
    /**
     * Suggested delay before retrying (milliseconds).
     */
    retryAfter?: number;
    /**
     * Alternative approaches to try.
     */
    alternatives?: string[];
    /**
     * Human-readable suggestion for resolution.
     */
    suggestion: string;
}
/**
 * Error recovery guidance for each error code.
 *
 * @description
 * This mapping provides structured recovery guidance for every error type.
 * LLMs can use this to automatically determine recovery strategies.
 */
export declare const ERROR_RECOVERY: Record<ErrorCode, ErrorRecovery>;
/**
 * Structured error class for the Unbrowser SDK.
 *
 * @description
 * All SDK errors are instances of this class. Each error includes:
 * - A unique error code for programmatic handling
 * - A human-readable message
 * - Recovery guidance with retry information
 *
 * @example
 * ```typescript
 * try {
 *   await client.browse(url);
 * } catch (error) {
 *   if (error instanceof UnbrowserError) {
 *     console.log(`Error: ${error.code} - ${error.message}`);
 *
 *     // Check if we can retry
 *     if (error.recovery.canRetry) {
 *       console.log(`Retry in ${error.recovery.retryAfter}ms`);
 *       console.log(`Suggestion: ${error.recovery.suggestion}`);
 *     }
 *
 *     // Try alternatives
 *     for (const alt of error.recovery.alternatives || []) {
 *       console.log(`Alternative: ${alt}`);
 *     }
 *   }
 * }
 * ```
 */
export declare class UnbrowserError extends Error {
    /**
     * Unique error code for this error type.
     * Use this for programmatic error handling.
     */
    readonly code: ErrorCode;
    /**
     * Recovery guidance including retry information and suggestions.
     * LLMs should use this to determine next steps.
     */
    readonly recovery: ErrorRecovery;
    /**
     * HTTP status code if this error came from an HTTP response.
     */
    readonly statusCode?: number;
    /**
     * Original error if this wraps another error.
     */
    readonly cause?: Error;
    /**
     * Additional context about the error.
     */
    readonly context?: Record<string, unknown>;
    constructor(code: ErrorCode, message: string, options?: {
        statusCode?: number;
        cause?: Error;
        context?: Record<string, unknown>;
        customRecovery?: Partial<ErrorRecovery>;
    });
    /**
     * Create an error from an HTTP response.
     *
     * @example
     * ```typescript
     * const error = UnbrowserError.fromResponse(response, await response.json());
     * throw error;
     * ```
     */
    static fromResponse(response: {
        status: number;
        statusText: string;
    }, body?: {
        error?: {
            code?: string;
            message?: string;
        };
    }): UnbrowserError;
    /**
     * Check if this error is retryable.
     *
     * @example
     * ```typescript
     * if (error.isRetryable()) {
     *   await delay(error.getRetryDelay());
     *   // retry request
     * }
     * ```
     */
    isRetryable(): boolean;
    /**
     * Get the suggested retry delay in milliseconds.
     *
     * @returns Retry delay or 0 if not retryable.
     */
    getRetryDelay(): number;
    /**
     * Get a formatted error string suitable for logging.
     *
     * @example
     * ```typescript
     * console.error(error.toDetailedString());
     * // Output:
     * // UnbrowserError [RATE_LIMITED]: Too many requests (429)
     * // Suggestion: Too many requests. Wait before retrying.
     * // Alternatives:
     * //   - Use batch() for multiple URLs
     * //   - Implement request queuing
     * // Retry after: 60000ms
     * ```
     */
    toDetailedString(): string;
    /**
     * Convert error to a plain object for serialization.
     */
    toJSON(): Record<string, unknown>;
}
/**
 * Type guard to check if an error is an UnbrowserError.
 *
 * @example
 * ```typescript
 * try {
 *   await client.browse(url);
 * } catch (error) {
 *   if (isUnbrowserError(error)) {
 *     console.log(error.code); // TypeScript knows this is ErrorCode
 *   }
 * }
 * ```
 */
export declare function isUnbrowserError(error: unknown): error is UnbrowserError;
/**
 * Type guard to check if an error is retryable.
 *
 * @example
 * ```typescript
 * if (isRetryableError(error)) {
 *   await delay(error.getRetryDelay());
 *   // retry
 * }
 * ```
 */
export declare function isRetryableError(error: unknown): error is UnbrowserError;
/**
 * Create a rate limit error with custom retry delay.
 */
export declare function rateLimitError(retryAfter: number): UnbrowserError;
/**
 * Create a timeout error with custom message.
 */
export declare function timeoutError(timeoutMs: number, url?: string): UnbrowserError;
//# sourceMappingURL=errors.d.ts.map