(** Centralized error handling for the Requests library *)

(** Log source for error reporting *)
val src : Logs.Src.t

(** {1 Exception Types} *)

(** Raised when a request times out *)
exception Timeout

(** Raised when too many redirects are encountered *)
exception TooManyRedirects of { url: string; count: int; max: int }

(** Raised when a connection error occurs *)
exception ConnectionError of string

(** Raised when an HTTP error response is received *)
exception HTTPError of {
  url: string;
  status: int;
  reason: string;
  body: string option;
  headers: Headers.t
}

(** Raised when authentication fails *)
exception AuthenticationError of string

(** Raised when there's an SSL/TLS error *)
exception SSLError of string

(** Raised when proxy connection fails *)
exception ProxyError of string

(** Raised when content encoding/decoding fails *)
exception EncodingError of string

(** Raised when an invalid URL is provided *)
exception InvalidURL of string

(** Raised when request is invalid *)
exception InvalidRequest of string

(** {1 Error Type} *)

(** Unified error type for result-based error handling *)
type t = [
  | `Timeout
  | `TooManyRedirects of string * int * int  (* url, count, max *)
  | `ConnectionError of string
  | `HTTPError of string * int * string * string option * Headers.t  (* url, status, reason, body, headers *)
  | `AuthenticationError of string
  | `SSLError of string
  | `ProxyError of string
  | `EncodingError of string
  | `InvalidURL of string
  | `InvalidRequest of string
  | `UnknownError of string
]

(** {1 Conversion Functions} *)

(** Convert an exception to an error type *)
val of_exn : exn -> t option

(** Convert an error type to an exception *)
val to_exn : t -> exn

(** Raise an error as an exception *)
val raise : t -> 'a

(** {1 Combinators} *)

(** Wrap a function that may raise exceptions into a result type *)
val catch : (unit -> 'a) -> ('a, t) result

(** Wrap an async function that may raise exceptions *)
val catch_async : (unit -> 'a) -> ('a, t) result

(** Map over the success case of a result *)
val map : ('a -> 'b) -> ('a, t) result -> ('b, t) result

(** Bind for result types with error *)
val bind : ('a -> ('b, t) result) -> ('a, t) result -> ('b, t) result

(** Applicative operator for combining results *)
val both : ('a, t) result -> ('b, t) result -> ('a * 'b, t) result

(** Get value or raise the error *)
val get_exn : ('a, t) result -> 'a

(** Get value or use default *)
val get_or : default:'a -> ('a, t) result -> 'a

(** Check if error is retryable *)
val is_retryable : t -> bool

(** Check if error is a client error (4xx) *)
val is_client_error : t -> bool

(** Check if error is a server error (5xx) *)
val is_server_error : t -> bool

(** {1 Pretty Printing} *)

(** Pretty printer for errors *)
val pp : Format.formatter -> t -> unit

(** Pretty printer for exceptions (falls back to Printexc if not a known exception) *)
val pp_exn : Format.formatter -> exn -> unit

(** Convert error to string *)
val to_string : t -> string

(** {1 Syntax Module} *)

(** Syntax module for let-operators *)
module Syntax : sig
  (** Bind operator for result types *)
  val ( let* ) : ('a, t) result -> ('a -> ('b, t) result) -> ('b, t) result

  (** Map operator for result types *)
  val ( let+ ) : ('a, t) result -> ('a -> 'b) -> ('b, t) result

  (** Both operator for combining results *)
  val ( and* ) : ('a, t) result -> ('b, t) result -> ('a * 'b, t) result
end