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

(** JMAP JSON codec for Eio

    Low-level encoding and decoding of JMAP messages using jsont and bytesrw. *)

(** {1 Request Encoding} *)

val encode_request :
  ?format:Jsont.format ->
  Jmap.Proto.Request.t ->
  (string, Jsont.Error.t) result
(** [encode_request ?format request] encodes a JMAP request to a JSON string.

    @param format The JSON formatting style. Defaults to {!Jsont.Minify}. *)

val encode_request_exn :
  ?format:Jsont.format ->
  Jmap.Proto.Request.t ->
  string
(** [encode_request_exn ?format request] is like {!encode_request} but raises
    on encoding errors. *)

(** {1 Response Decoding} *)

val decode_response :
  ?locs:bool ->
  string ->
  (Jmap.Proto.Response.t, Jsont.Error.t) result
(** [decode_response ?locs json] decodes a JMAP response from a JSON string.

    @param locs If [true], location information is preserved for error messages.
                Defaults to [false]. *)

val decode_response_exn :
  ?locs:bool ->
  string ->
  Jmap.Proto.Response.t
(** [decode_response_exn ?locs json] is like {!decode_response} but raises
    on decoding errors. *)

(** {1 Session Decoding} *)

val decode_session :
  ?locs:bool ->
  string ->
  (Jmap.Proto.Session.t, Jsont.Error.t) result
(** [decode_session ?locs json] decodes a JMAP session from a JSON string.

    @param locs If [true], location information is preserved for error messages.
                Defaults to [false]. *)

val decode_session_exn :
  ?locs:bool ->
  string ->
  Jmap.Proto.Session.t
(** [decode_session_exn ?locs json] is like {!decode_session} but raises
    on decoding errors. *)

(** {1 Blob Upload Response Decoding} *)

val decode_upload_response :
  ?locs:bool ->
  string ->
  (Jmap.Proto.Blob.upload_response, Jsont.Error.t) result
(** [decode_upload_response ?locs json] decodes a blob upload response. *)

val decode_upload_response_exn :
  ?locs:bool ->
  string ->
  Jmap.Proto.Blob.upload_response
(** [decode_upload_response_exn ?locs json] is like {!decode_upload_response}
    but raises on decoding errors. *)

(** {1 Generic Encoding/Decoding} *)

val encode :
  ?format:Jsont.format ->
  'a Jsont.t ->
  'a ->
  (string, Jsont.Error.t) result
(** [encode ?format jsont value] encodes any value using its jsont codec. *)

val decode :
  ?locs:bool ->
  'a Jsont.t ->
  string ->
  ('a, Jsont.Error.t) result
(** [decode ?locs jsont json] decodes any value using its jsont codec. *)