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

(** JMAP client for browsers using Brr.

    This module provides a JMAP client that runs in web browsers using
    the Fetch API. It can be used with js_of_ocaml to build browser-based
    email clients.

    {2 Example}

    {[
      open Fut.Syntax

      let main () =
        let* session = Jmap_brr.get_session
          ~url:(Jstr.v "https://api.fastmail.com/jmap/session")
          ~token:(Jstr.v "your-api-token")
        in
        match session with
        | Error e -> Brr.Console.(error [str "Session error:"; e]); Fut.return ()
        | Ok session ->
            Brr.Console.(log [str "Connected as:"; str (Jmap.Session.username session)]);
            Fut.return ()

      let () = ignore (main ())
    ]} *)

(** {1 Connection} *)

type connection
(** A JMAP connection to a server. *)

val session : connection -> Jmap.Proto.Session.t
(** [session conn] returns the session information. *)

val api_url : connection -> Jstr.t
(** [api_url conn] returns the API URL for requests. *)

(** {1 Session Establishment} *)

val get_session :
  url:Jstr.t ->
  token:Jstr.t ->
  (connection, Jv.Error.t) result Fut.t
(** [get_session ~url ~token] establishes a JMAP session.

    [url] is the session URL (e.g., ["https://api.fastmail.com/jmap/session"]).
    [token] is the Bearer authentication token. *)

(** {1 Making Requests} *)

val request :
  connection ->
  Jmap.Proto.Request.t ->
  (Jmap.Proto.Response.t, Jv.Error.t) result Fut.t
(** [request conn req] sends a JMAP request and returns the response. *)

val request_json :
  connection ->
  Jsont.json ->
  (Jsont.json, Jv.Error.t) result Fut.t
(** [request_json conn json] sends a raw JSON request and returns the
    JSON response. Useful for debugging or custom requests. *)

(** {1 JSON Encoding Utilities}

    These functions help visualize how OCaml types map to JMAP JSON,
    useful for the tutorial and debugging. *)

val encode_request : Jmap.Proto.Request.t -> (Jstr.t, Jv.Error.t) result
(** [encode_request req] encodes a request to JSON string. *)

val encode_response : Jmap.Proto.Response.t -> (Jstr.t, Jv.Error.t) result
(** [encode_response resp] encodes a response to JSON string. *)

val encode_session : Jmap.Proto.Session.t -> (Jstr.t, Jv.Error.t) result
(** [encode_session session] encodes a session to JSON string. *)

val decode_json : Jstr.t -> (Jsont.json, Jv.Error.t) result
(** [decode_json s] parses a JSON string to a Jsont.json value. *)

val encode_json : Jsont.json -> (Jstr.t, Jv.Error.t) result
(** [encode_json json] encodes a Jsont.json value to a string. *)

val pp_json : Format.formatter -> Jsont.json -> unit
(** [pp_json ppf json] pretty-prints JSON. For toplevel use. *)

(** {1 Protocol Logging} *)

val set_request_logger : (string -> string -> unit) -> unit
(** [set_request_logger f] registers a callback [f label json] that will be
    called with each outgoing JMAP request. Useful for debugging and
    educational displays. *)

val set_response_logger : (string -> string -> unit) -> unit
(** [set_response_logger f] registers a callback [f label json] that will be
    called with each incoming JMAP response. Useful for debugging and
    educational displays. *)

(** {1 Toplevel Support} *)

val install_printers : unit -> unit
(** [install_printers ()] installs toplevel pretty printers for JMAP types.
    This is useful when using the OCaml console in the browser. *)