/**
 * @file Unified Error Utilities
 * @description Standardized error creation, classification, normalization,
 * and error handling patterns.
 *
 * @module shared/error-utils
 */
/**
 * Error category for classification and handling decisions.
 */
export type ErrorCategory = 'network' | 'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'timeout' | 'server' | 'client' | 'unknown';
/**
 * Error severity level.
 */
export type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
/**
 * Base application error with category and metadata support.
 */
export declare class AppError extends Error {
    readonly category: ErrorCategory;
    readonly severity: ErrorSeverity;
    readonly code?: string;
    readonly statusCode?: number;
    readonly metadata?: Record<string, unknown>;
    readonly timestamp: number;
    readonly isRetryable: boolean;
    constructor(message: string, options?: {
        category?: ErrorCategory;
        severity?: ErrorSeverity;
        code?: string;
        statusCode?: number;
        metadata?: Record<string, unknown>;
        cause?: Error;
        isRetryable?: boolean;
    });
    /**
     * Convert to plain object for serialization.
     */
    toJSON(): Record<string, unknown>;
    private determineRetryable;
}
/**
 * Network-related error.
 */
export declare class NetworkError extends AppError {
    constructor(message: string, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category'>);
}
/**
 * Validation error with field-level details.
 */
export declare class ValidationError extends AppError {
    readonly fields: Record<string, string[]>;
    constructor(message: string, fields?: Record<string, string[]>, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'isRetryable'>);
    /**
     * Get all error messages as flat array.
     */
    getAllMessages(): string[];
    /**
     * Get error messages for a specific field.
     */
    getFieldErrors(field: string): string[];
}
/**
 * Authentication error.
 */
export declare class AuthenticationError extends AppError {
    constructor(message?: string, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'statusCode' | 'isRetryable'>);
}
/**
 * Authorization error.
 */
export declare class AuthorizationError extends AppError {
    constructor(message?: string, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'statusCode' | 'isRetryable'>);
}
/**
 * Not found error.
 */
export declare class NotFoundError extends AppError {
    readonly resource?: string;
    constructor(message?: string, resource?: string, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'statusCode' | 'isRetryable'>);
}
/**
 * Rate limit error.
 */
export declare class RateLimitError extends AppError {
    readonly retryAfterMs?: number;
    constructor(message?: string, retryAfterMs?: number, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'statusCode'>);
}
/**
 * Timeout error.
 */
export declare class TimeoutError extends AppError {
    readonly timeoutMs: number;
    constructor(message: string, timeoutMs: number, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category'>);
}
/**
 * Conflict error (e.g., resource already exists).
 */
export declare class ConflictError extends AppError {
    constructor(message?: string, options?: Omit<ConstructorParameters<typeof AppError>[1], 'category' | 'statusCode' | 'isRetryable'>);
}
/**
 * Normalize any error into an AppError instance.
 *
 * @param error - Any error value
 * @returns Normalized AppError
 *
 * @example
 * ```ts
 * try {
 *   await fetchData();
 * } catch (error) {
 *   const appError = normalizeError(error);
 *   console.log(appError.category, appError.message);
 * }
 * ```
 */
export declare function normalizeError(error: unknown): AppError;
/**
 * Check if error is retryable based on category and properties.
 */
export declare function isRetryableError(error: unknown): boolean;
/**
 * Check if error is a specific category.
 */
export declare function isErrorCategory(error: unknown, category: ErrorCategory): boolean;
/**
 * Check if error is a network error.
 */
export declare function isNetworkError(error: unknown): error is NetworkError;
/**
 * Check if error is a validation error.
 */
export declare function isValidationError(error: unknown): error is ValidationError;
/**
 * Check if error is an authentication error.
 */
export declare function isAuthenticationError(error: unknown): error is AuthenticationError;
/**
 * Check if error is a timeout error.
 */
export declare function isTimeoutError(error: unknown): error is TimeoutError;
/**
 * Create error from HTTP response.
 *
 * @param response - HTTP response object
 * @param body - Parsed response body
 * @returns Appropriate AppError subclass
 */
export declare function fromHttpResponse(response: {
    status: number;
    statusText: string;
}, body?: {
    message?: string;
    error?: string;
    errors?: Record<string, string[]>;
}): AppError;
/**
 * Result type for operations that can fail.
 */
export type Result<T, E = AppError> = {
    success: true;
    data: T;
} | {
    success: false;
    error: E;
};
/**
 * Create a success result.
 */
export declare function success<T>(data: T): Result<T, never>;
/**
 * Create a failure result.
 */
export declare function failure<E>(error: E): Result<never, E>;
/**
 * Wrap an async function to return Result instead of throwing.
 *
 * @example
 * ```ts
 * const result = await tryCatch(() => fetchData());
 * if (result.success) {
 *   console.log(result.data);
 * } else {
 *   console.error(result.error.message);
 * }
 * ```
 */
export declare function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T>>;
/**
 * Sync version of tryCatch.
 */
export declare function tryCatchSync<T>(fn: () => T): Result<T>;
/**
 * Unwrap a Result, throwing if it's a failure.
 */
export declare function unwrap<T>(result: Result<T>): T;
/**
 * Unwrap a Result with a default value for failures.
 */
export declare function unwrapOr<T>(result: Result<T>, defaultValue: T): T;
/**
 * Map over a successful Result.
 */
export declare function mapResult<T, U>(result: Result<T>, fn: (data: T) => U): Result<U>;
/**
 * Flat map over a successful Result.
 */
export declare function flatMapResult<T, U>(result: Result<T>, fn: (data: T) => Result<U>): Result<U>;