(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** JMAP error types as defined in RFC 8620 Section 3.6.1-3.6.2 

    @canonical Jmap.Proto.Error *)

(** {1 Request-Level Errors}

    These errors are returned with an HTTP error status code and a JSON
    Problem Details body (RFC 7807). *)

(** Request-level error URNs *)
module Request_error : sig
  type urn = [
    | `Unknown_capability
    (** urn:ietf:params:jmap:error:unknownCapability
        The client included a capability in "using" that the server does not support. *)
    | `Not_json
    (** urn:ietf:params:jmap:error:notJSON
        The content type was not application/json or the request was not valid JSON. *)
    | `Not_request
    (** urn:ietf:params:jmap:error:notRequest
        The request was valid JSON but not a valid JMAP Request object. *)
    | `Limit
    (** urn:ietf:params:jmap:error:limit
        A server-defined limit was reached. *)
    | `Other of string
    (** Other URN not in the standard set. *)
  ]

  val urn_to_string : urn -> string
  (** [urn_to_string urn] returns the URN string. *)

  val urn_of_string : string -> urn
  (** [urn_of_string s] parses a URN string. *)

  type t = {
    type_ : urn;
    (** The error type URN. *)
    status : int;
    (** HTTP status code. *)
    title : string option;
    (** Short human-readable summary. *)
    detail : string option;
    (** Longer human-readable explanation. *)
    limit : string option;
    (** For "limit" errors, the name of the limit that was exceeded. *)
  }
  (** A request-level error per RFC 7807 Problem Details. *)

  val jsont : t Jsont.t
  (** JSON codec for request-level errors. *)
end

(** {1 Method-Level Errors}

    These are returned as the second element of an Invocation tuple
    when a method call fails. *)

(** Standard method error types per RFC 8620 Section 3.6.2 *)
type method_error_type = [
  | `Server_unavailable
  (** The server is temporarily unavailable. *)
  | `Server_fail
  (** An unexpected error occurred. *)
  | `Server_partial_fail
  (** Some, but not all, changes were successfully made. *)
  | `Unknown_method
  (** The method name is not recognized. *)
  | `Invalid_arguments
  (** One or more arguments are invalid. *)
  | `Invalid_result_reference
  (** A result reference could not be resolved. *)
  | `Forbidden
  (** The method/arguments are valid but forbidden. *)
  | `Account_not_found
  (** The accountId does not correspond to a valid account. *)
  | `Account_not_supported_by_method
  (** The account does not support this method. *)
  | `Account_read_only
  (** The account is read-only. *)
  | `Other of string
  (** Other error type not in the standard set. *)
]

val method_error_type_to_string : method_error_type -> string
(** [method_error_type_to_string t] returns the type string. *)

val method_error_type_of_string : string -> method_error_type
(** [method_error_type_of_string s] parses a type string. *)

(** A method-level error response. *)
type method_error = {
  type_ : method_error_type;
  (** The error type. *)
  description : string option;
  (** Human-readable description of the error. *)
}

val method_error_jsont : method_error Jsont.t
(** JSON codec for method errors. *)

(** {1 SetError}

    Errors returned in notCreated/notUpdated/notDestroyed responses. *)

(** Standard SetError types per RFC 8620 Section 5.3 and RFC 8621 Section 7 *)
type set_error_type = [
  | `Forbidden
  (** The operation is not permitted. *)
  | `Over_quota
  (** The maximum server quota has been reached. *)
  | `Too_large
  (** The object is too large. *)
  | `Rate_limit
  (** Too many objects of this type have been created recently. *)
  | `Not_found
  (** The id does not exist (for update/destroy). *)
  | `Invalid_patch
  (** The PatchObject is invalid. *)
  | `Will_destroy
  (** The object will be destroyed by another operation in the request. *)
  | `Invalid_properties
  (** Some properties were invalid. *)
  | `Singleton
  (** Only one object of this type can exist (for create). *)
  | `Forbidden_mail_from
  (** RFC 8621: The server does not permit the user to send from the address. *)
  | `Forbidden_from
  (** RFC 8621: The server does not permit the user to send a message with
      the From header of the message to be sent. *)
  | `Forbidden_to_send
  (** RFC 8621: The user does not have permission to send at all. *)
  | `Other of string
  (** Other error type. *)
]

val set_error_type_to_string : set_error_type -> string
val set_error_type_of_string : string -> set_error_type

(** A SetError object. *)
type set_error = {
  type_ : set_error_type;
  (** The error type. *)
  description : string option;
  (** Human-readable description. *)
  properties : string list option;
  (** For invalidProperties errors, the list of invalid property names. *)
}

val set_error : ?description:string -> ?properties:string list -> set_error_type -> set_error
(** [set_error ?description ?properties type_] creates a SetError. *)

val set_error_jsont : set_error Jsont.t
(** JSON codec for SetError. *)