(*---------------------------------------------------------------------------
  Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
  SPDX-License-Identifier: ISC
 ---------------------------------------------------------------------------*)

(** IMAP Client Errors

    Error types for IMAP client operations, integrated with Eio's exception
    handling. *)

(** {1 Error Types} *)

type t =
  | Connection_error of { reason : string }
  | Protocol_error of { code : Code.t option; text : string }
  | Parse_error of { reason : string; data : string option }
  | State_error of { expected : string; actual : string }
  | Timeout of { operation : string }
  | Capability_missing of { capability : string }
  | Authentication_error of { mechanism : string; reason : string }

(** {1 Pretty Printing} *)

val pp : Format.formatter -> t -> unit
val to_string : t -> string

(** {1 Eio Integration} *)

type Eio.Exn.err += E of t
(** Exception type for IMAP errors. *)

val err : t -> exn
(** [err e] wraps error [e] in an Eio exception. *)

val raise : t -> 'a
(** [raise e] raises error [e] as an Eio exception. *)

val of_eio_exn : exn -> t option
(** [of_eio_exn exn] extracts an IMAP error from an Eio exception. *)

(** {1 Error Classification} *)

val is_retryable : t -> bool
(** [is_retryable e] returns [true] if the error may succeed on retry. *)

val is_auth_error : t -> bool
(** [is_auth_error e] returns [true] if this is an authentication error. *)

val is_state_error : t -> bool
(** [is_state_error e] returns [true] if this is a state error. *)