import type { LexErrorCode, LexErrorData, LexValue } from '@atproto/lex-data';
import { LexError } from '@atproto/lex-data';
import { type InferMethodError, type LexValidationError, type Procedure, type Query, type ResultFailure } from '@atproto/lex-schema';
import type { XrpcUnknownResponsePayload } from './types.js';
import type { WWWAuthenticate } from './www-authenticate.js';
export type { XrpcUnknownResponsePayload };
export type DownstreamError<N extends LexErrorCode = LexErrorCode> = {
    status: number;
    headers?: Headers;
    encoding?: 'application/json';
    body: LexErrorData<N>;
};
/**
 * HTTP status codes that indicate a transient error that may succeed on retry.
 *
 * Includes:
 * - 408 Request Timeout
 * - 425 Too Early
 * - 429 Too Many Requests (rate limited)
 * - 500 Internal Server Error
 * - 502 Bad Gateway
 * - 503 Service Unavailable
 * - 504 Gateway Timeout
 * - 522 Connection Timed Out (Cloudflare)
 * - 524 A Timeout Occurred (Cloudflare)
 */
export declare const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number>;
export { LexError };
export type { LexErrorCode, LexErrorData };
/**
 * The payload structure for XRPC error responses.
 *
 * All XRPC errors return JSON with an `error` code and optional `message`.
 *
 * @typeParam N - The specific error code type
 */
export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {
    body: LexErrorData<N>;
    encoding: 'application/json';
};
/**
 * All unsuccessful responses should follow a standard error response
 * schema. The Content-Type should be application/json, and the payload
 * should be a JSON object with the following fields:
 *
 * - `error` (string, required): type name of the error (generic ASCII
 *   constant, no whitespace)
 * - `message` (string, optional): description of the error, appropriate for
 *   display to humans
 *
 * This function checks whether a given payload matches this schema.
 */
export declare function isXrpcErrorPayload(payload: XrpcUnknownResponsePayload | null | undefined): payload is XrpcErrorPayload;
/**
 * Abstract base class for all XRPC errors.
 *
 * Extends {@link LexError} and implements {@link ResultFailure} for use with
 * safe/result-based error handling patterns.
 *
 * @typeParam M - The XRPC method type (Procedure or Query)
 * @typeParam N - The error code type
 * @typeParam TReason - The reason type for ResultFailure
 *
 * @see {@link XrpcResponseError} - For valid XRPC error responses
 * @see {@link XrpcInvalidResponseError} - For invalid/unexpected responses
 * @see {@link XrpcInternalError} - For network/internal errors
 */
export declare abstract class XrpcError<M extends Procedure | Query = Procedure | Query, N extends LexErrorCode = LexErrorCode, TReason = unknown> extends LexError<N> implements ResultFailure<TReason> {
    readonly method: M;
    name: string;
    constructor(method: M, error: N, message?: string, options?: ErrorOptions);
    /**
     * @see {@link ResultFailure.success}
     */
    readonly success: false;
    /**
     * @see {@link ResultFailure.reason}
     */
    abstract readonly reason: TReason;
    /**
     * Indicates whether the error is transient and can be retried.
     */
    abstract shouldRetry(): boolean;
    abstract toDownstreamError(): DownstreamError;
    matchesSchemaErrors(): this is XrpcError<M, InferMethodError<M>>;
}
/**
 * Error class for valid XRPC error responses from the server.
 *
 * This represents a properly formatted XRPC error where the server returned
 * a non-2xx status with a valid JSON error payload containing `error` and
 * optional `message` fields.
 *
 * Use {@link matchesSchemaErrors} to check if the error matches the method's declared
 * error types for type-safe error handling.
 *
 * @typeParam M - The XRPC method type
 * @typeParam N - The error code type (inferred from method or generic)
 *
 * @example Handling specific errors
 * ```typescript
 * try {
 *   await client.xrpc(someMethod, options)
 * } catch (err) {
 *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {
 *     // Handle not found case
 *   }
 * }
 * ```
 */
export declare class XrpcResponseError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, LexErrorCode, XrpcResponseError<M>> {
    readonly response: Response;
    readonly payload?: XrpcUnknownResponsePayload | undefined;
    name: string;
    constructor(method: M, response: Response, payload?: XrpcUnknownResponsePayload | undefined, options?: ErrorOptions);
    get reason(): this;
    shouldRetry(): boolean;
    toJSON(): LexErrorData;
    toDownstreamError(): DownstreamError;
    get status(): number;
    get headers(): Headers;
    get body(): undefined | Uint8Array | LexValue;
}
export type { WWWAuthenticate };
/**
 * Error class for 401 Unauthorized XRPC responses.
 *
 * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header
 * information, useful for implementing authentication flows.
 *
 * Authentication errors are never retryable as they require user intervention
 * (e.g., re-authentication, token refresh).
 *
 * @typeParam M - The XRPC method type
 * @typeParam N - The error code type
 *
 * @example Handling authentication errors
 * ```typescript
 * try {
 *   await client.xrpc(someMethod, options)
 * } catch (err) {
 *   if (err instanceof XrpcAuthenticationError) {
 *     const { DPoP } = err.wwwAuthenticate
 *     if (DPoP?.error === 'use_dpop_nonce') {
 *       // Handle DPoP nonce requirement
 *     }
 *   }
 * }
 * ```
 */
export declare class XrpcAuthenticationError<M extends Procedure | Query = Procedure | Query> extends XrpcResponseError<M> {
    #private;
    name: string;
    shouldRetry(): boolean;
    /**
     * Parsed WWW-Authenticate header from the response.
     * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).
     */
    get wwwAuthenticate(): WWWAuthenticate;
}
/**
 * Error class for invalid or unprocessable XRPC responses from upstream servers.
 *
 * This occurs when the server returns a response that doesn't conform to the
 * XRPC protocol, such as:
 * - Missing or invalid Content-Type header
 * - Response body that doesn't match the method's output schema
 * - Non-JSON error responses
 * - Responses from non-XRPC endpoints
 *
 * The error code is always 'InvalidResponse' and maps to HTTP 502 Bad Gateway
 * when converted to a response. This should allow downstream clients to
 * determine at which boundary the error occurred.
 *
 * @typeParam M - The XRPC method type
 */
export declare class XrpcInvalidResponseError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, 'InvalidResponse', XrpcInvalidResponseError<M>> {
    readonly response: Response;
    readonly payload?: XrpcUnknownResponsePayload | undefined;
    name: string;
    constructor(method: M, response: Response, payload?: XrpcUnknownResponsePayload | undefined, message?: string, options?: ErrorOptions);
    get reason(): this;
    shouldRetry(): boolean;
    toDownstreamError(): DownstreamError;
}
/**
 * Error class for invalid XRPC responses that fail schema validation.
 *
 * This is a specific type of {@link XrpcInvalidResponseError} that indicates the
 * upstream server returned a response that was structurally valid but did not
 * conform to the expected schema for the method. This likely indicates a
 * mismatch between client and server versions or an issue with the server's
 * XRPC implementation.
 *
 * @typeParam M - The XRPC method type
 */
export declare class XrpcResponseValidationError<M extends Procedure | Query = Procedure | Query> extends XrpcInvalidResponseError<M> {
    readonly cause: LexValidationError;
    name: string;
    constructor(method: M, response: Response, payload: XrpcUnknownResponsePayload, cause: LexValidationError);
}
/**
 * Error class for unexpected internal/client-side errors during XRPC requests.
 *
 * The error code is always 'InternalServerError' and these errors not
 * considered retryable as they stem from unforeseen issues in the
 * implementation.
 *
 * @typeParam M - The XRPC method type
 */
export declare class XrpcInternalError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {
    name: string;
    constructor(method: M, message?: string, options?: ErrorOptions);
    get reason(): this;
    shouldRetry(): boolean;
    toJSON(): LexErrorData;
    toDownstreamError(): DownstreamError;
}
/**
 * Special case of XrpcInternalError that specifically represents errors thrown
 * by {@link Agent.fetchHandler} during the XRPC request. This includes:
 * - Network errors (connection refused, DNS failure)
 * - Request timeouts
 * - Request aborted via AbortSignal
 *
 * These errors are optimistically considered retryable, as many fetch errors
 * are transient and may succeed on retry.
 */
export declare class XrpcFetchError<M extends Procedure | Query = Procedure | Query> extends XrpcInternalError<M> {
    name: string;
    constructor(method: M, cause: unknown);
    shouldRetry(): boolean;
    toJSON(): LexErrorData;
    toDownstreamError(): DownstreamError;
}
/**
 * Union type of all possible XRPC failure types.
 *
 * Used as the return type for safe/non-throwing XRPC methods. Check the
 * `success` property to distinguish between success and failure:
 *
 * @typeParam M - The XRPC method type
 *
 * @example
 * ```typescript
 * const result = await client.xrpcSafe(someMethod, options)
 * if (result.success) {
 *   console.log(result.body) // XrpcResponse
 * } else {
 *   // result is XrpcFailure (XrpcResponseError | XrpcInvalidResponseError | XrpcInternalError)
 *   console.error(result.error, result.message)
 * }
 * ```
 */
export type XrpcFailure<M extends Procedure | Query = Procedure | Query> = XrpcResponseError<M> | XrpcInvalidResponseError<M> | XrpcInternalError<M>;
/**
 * Converts an unknown error into an appropriate {@link XrpcFailure} type.
 *
 * If the error is already an XrpcFailure for the given method, returns it as-is.
 * Otherwise, wraps it in an {@link XrpcInternalError}.
 *
 * @param method - The XRPC method that was called
 * @param cause - The error to convert
 * @returns An XrpcFailure instance
 *
 * @example
 * ```typescript
 * try {
 *   const response = await fetch(...)
 *   // ... process response
 * } catch (err) {
 *   return asXrpcFailure(method, err)
 * }
 * ```
 */
export declare function asXrpcFailure<M extends Procedure | Query>(method: M, cause: unknown): XrpcFailure<M>;
//# sourceMappingURL=errors.d.ts.map