(** JMAP Error Types.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6> RFC 8620, Section 3.6 *)

open Jmap_types

(** Standard Method-level error types.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)
type method_error_type = [
  | `ServerUnavailable
  | `ServerFail
  | `ServerPartialFail
  | `UnknownMethod
  | `InvalidArguments
  | `InvalidResultReference
  | `Forbidden
  | `AccountNotFound
  | `AccountNotSupportedByMethod
  | `AccountReadOnly
  | `RequestTooLarge
  | `CannotCalculateChanges
  | `StateMismatch
  | `AnchorNotFound
  | `UnsupportedSort
  | `UnsupportedFilter
  | `TooManyChanges
  | `FromAccountNotFound
  | `FromAccountNotSupportedByMethod
  | `Other_method_error of string
]

(** Standard SetError types.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)
type set_error_type = [
  | `Forbidden
  | `OverQuota
  | `TooLarge
  | `RateLimit
  | `NotFound
  | `InvalidPatch
  | `WillDestroy
  | `InvalidProperties
  | `Singleton
  | `AlreadyExists (* From /copy *)
  | `MailboxHasChild (* RFC 8621 *)
  | `MailboxHasEmail (* RFC 8621 *)
  | `BlobNotFound (* RFC 8621 *)
  | `TooManyKeywords (* RFC 8621 *)
  | `TooManyMailboxes (* RFC 8621 *)
  | `InvalidEmail (* RFC 8621 *)
  | `TooManyRecipients (* RFC 8621 *)
  | `NoRecipients (* RFC 8621 *)
  | `InvalidRecipients (* RFC 8621 *)
  | `ForbiddenMailFrom (* RFC 8621 *)
  | `ForbiddenFrom (* RFC 8621 *)
  | `ForbiddenToSend (* RFC 8621 *)
  | `CannotUnsend (* RFC 8621 *)
  | `Other_set_error of string (* For future or custom errors *)
]

(** Primary error type that can represent all JMAP errors *)
type error =
  | Transport of string     (** Network/HTTP-level error *)
  | Parse of string         (** JSON parsing error *)
  | Protocol of string      (** JMAP protocol error *)
  | Problem of string       (** Problem Details object error *)
  | Method of method_error_type * string option (** Method error with optional description *)
  | SetItem of id * set_error_type * string option (** Error for a specific item in a /set operation *)
  | Auth of string          (** Authentication error *)
  | ServerError of string   (** Server reported an error *)

(** Standard Result type for JMAP operations *)
type 'a result = ('a, error) Result.t

(** Problem details object for HTTP-level errors.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.1> RFC 8620, Section 3.6.1
    @see <https://www.rfc-editor.org/rfc/rfc7807.html> RFC 7807 *)
module Problem_details : sig
  type t

  val problem_type : t -> string
  val status : t -> int option
  val detail : t -> string option
  val limit : t -> string option
  val other_fields : t -> Yojson.Safe.t string_map
  
  val v : 
    ?status:int ->
    ?detail:string ->
    ?limit:string ->
    ?other_fields:Yojson.Safe.t string_map ->
    string ->
    t
end

(** Description for method errors. May contain additional details.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)
module Method_error_description : sig
  type t
  
  val description : t -> string option
  
  val v : ?description:string -> unit -> t
end

(** Represents a method-level error response invocation part.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)
module Method_error : sig
  type t
  
  val type_ : t -> method_error_type
  val description : t -> Method_error_description.t option
  
  val v : 
    ?description:Method_error_description.t ->
    method_error_type ->
    t
end

(** SetError object.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)
module Set_error : sig
  type t
  
  val type_ : t -> set_error_type
  val description : t -> string option
  val properties : t -> string list option
  val existing_id : t -> id option
  val max_recipients : t -> uint option
  val invalid_recipients : t -> string list option
  val max_size : t -> uint option
  val not_found_blob_ids : t -> id list option
  
  val v :
    ?description:string ->
    ?properties:string list ->
    ?existing_id:id ->
    ?max_recipients:uint ->
    ?invalid_recipients:string list ->
    ?max_size:uint ->
    ?not_found_blob_ids:id list ->
    set_error_type ->
    t
end

(** {2 Error Handling Functions} *)

(** Create a transport error *)
val transport_error : string -> error

(** Create a parse error *)
val parse_error : string -> error

(** Create a protocol error *)
val protocol_error : string -> error 

(** Create a problem details error *)
val problem_error : Problem_details.t -> error

(** Create a method error *)
val method_error : ?description:string -> method_error_type -> error

(** Create a SetItem error *)
val set_item_error : id -> ?description:string -> set_error_type -> error

(** Create an auth error *)
val auth_error : string -> error

(** Create a server error *)
val server_error : string -> error

(** Convert a Method_error.t to error *)
val of_method_error : Method_error.t -> error

(** Convert a Set_error.t to error for a specific ID *)
val of_set_error : id -> Set_error.t -> error

(** Get a human-readable description of an error *)
val error_to_string : error -> string

(** {2 Result Handling} *)

(** Map an error with additional context *)
val map_error : 'a result -> (error -> error) -> 'a result

(** Add context to an error *)
val with_context : 'a result -> string -> 'a result

(** Convert an option to a result with an error for None *)
val of_option : 'a option -> error -> 'a result