/**
 * @license
 * Copyright 2025 Vybestack LLC
 * SPDX-License-Identifier: Apache-2.0
 */
/**
 * OAuth Error Handling System
 *
 * Provides comprehensive error classification, user-friendly messaging,
 * and recovery mechanisms for OAuth providers.
 */
/**
 * OAuth error categories for classification and handling
 */
export declare enum OAuthErrorCategory {
    /** User must take action (re-authenticate, grant permissions) */
    USER_ACTION_REQUIRED = "user_action_required",
    /** Network or temporary service issues that can be retried */
    TRANSIENT = "transient",
    /** System issues (file permissions, storage problems) */
    SYSTEM = "system",
    /** Critical security or data corruption issues */
    CRITICAL = "critical",
    /** Configuration or setup problems */
    CONFIGURATION = "configuration"
}
/**
 * Specific OAuth error types with detailed classification
 */
export declare enum OAuthErrorType {
    AUTHENTICATION_REQUIRED = "authentication_required",
    AUTHORIZATION_EXPIRED = "authorization_expired",
    INSUFFICIENT_PERMISSIONS = "insufficient_permissions",
    USER_CANCELLED = "user_cancelled",
    INVALID_CREDENTIALS = "invalid_credentials",
    NETWORK_ERROR = "network_error",
    SERVICE_UNAVAILABLE = "service_unavailable",
    RATE_LIMITED = "rate_limited",
    TIMEOUT = "timeout",
    STORAGE_ERROR = "storage_error",
    FILE_PERMISSIONS = "file_permissions",
    CORRUPTED_DATA = "corrupted_data",
    SECURITY_VIOLATION = "security_violation",
    MALFORMED_TOKEN = "malformed_token",
    INVALID_CLIENT_ID = "invalid_client_id",
    INVALID_ENDPOINT = "invalid_endpoint",
    MISSING_CONFIGURATION = "missing_configuration",
    UNKNOWN = "unknown"
}
/**
 * Retry strategy configuration
 */
export interface RetryConfig {
    /** Maximum number of retry attempts */
    maxAttempts: number;
    /** Base delay between retries in milliseconds */
    baseDelayMs: number;
    /** Multiplier for exponential backoff */
    backoffMultiplier: number;
    /** Maximum delay between retries in milliseconds */
    maxDelayMs: number;
    /** Whether to add random jitter to delays */
    jitter: boolean;
}
/**
 * Default retry configuration for transient errors
 */
export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
/**
 * Comprehensive OAuth error with classification and user guidance
 */
export declare class OAuthError extends Error {
    readonly category: OAuthErrorCategory;
    readonly type: OAuthErrorType;
    readonly provider: string;
    readonly userMessage: string;
    readonly actionRequired: string | null;
    readonly isRetryable: boolean;
    readonly retryAfterMs: number | null;
    readonly technicalDetails: Record<string, unknown>;
    readonly originalError: Error | null;
    constructor(type: OAuthErrorType, provider: string, message: string, options?: {
        userMessage?: string;
        actionRequired?: string;
        retryAfterMs?: number;
        technicalDetails?: Record<string, unknown>;
        originalError?: Error;
        cause?: Error;
    });
    /**
     * Categorizes error type into handling categories
     */
    private categorizeError;
    /**
     * Determines if error type is retryable
     */
    private determineRetryability;
    /**
     * Generates user-friendly error message
     */
    private generateUserMessage;
    /**
     * Generates actionable guidance for users
     */
    private generateActionRequired;
    /**
     * Creates a sanitized version of the error for logging
     */
    toLogEntry(): Record<string, unknown>;
}
/**
 * Error factory for common OAuth error scenarios
 */
export declare class OAuthErrorFactory {
    /**
     * Creates an authentication required error
     */
    static authenticationRequired(provider: string, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates an expired authorization error
     */
    static authorizationExpired(provider: string, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates a network error with retry capability
     */
    static networkError(provider: string, originalError?: Error, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates a rate limited error with specific retry delay
     */
    static rateLimited(provider: string, retryAfterSeconds?: number, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates a storage error
     */
    static storageError(provider: string, originalError?: Error, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates a corrupted data error
     */
    static corruptedData(provider: string, details?: Record<string, unknown>): OAuthError;
    /**
     * Creates an error from an unknown error, attempting classification
     */
    static fromUnknown(provider: string, error: unknown, context?: string): OAuthError;
}
/**
 * Retry handler with exponential backoff and jitter
 */
export declare class RetryHandler {
    private config;
    constructor(config?: RetryConfig);
    /**
     * Executes operation with retry logic for transient errors
     */
    executeWithRetry<T>(operation: () => Promise<T>, provider: string, context?: string): Promise<T>;
    /**
     * Sleep utility
     */
    private sleep;
}
/**
 * Graceful error handler for OAuth operations
 */
export declare class GracefulErrorHandler {
    private retryHandler;
    constructor(retryHandler?: RetryHandler);
    /**
     * Handles errors gracefully, providing fallback behavior when possible
     */
    handleGracefully<T>(operation: () => Promise<T>, fallback: T | (() => T | Promise<T>), provider: string, context?: string): Promise<T>;
    /**
     * Wraps a method to handle errors gracefully with logging
     */
    wrapMethod<TArgs extends unknown[], TReturn>(method: (...args: TArgs) => Promise<TReturn>, provider: string, methodName: string, fallback?: TReturn | ((...args: TArgs) => TReturn | Promise<TReturn>)): (...args: TArgs) => Promise<TReturn>;
}