(** Toplevel printers for JMAP types.

    Printers are automatically installed when the library is loaded:
    {[
      #require "jmap.top";;
    ]}

    After loading, JMAP types will display nicely:
    {[
      # Jmap.Id.of_string_exn "abc123";;
      - : Jmap.Id.t = <id:abc123>

      # Jmap.Keyword.of_string "$seen";;
      - : Jmap.Keyword.t = `Seen

      # Jmap.Role.of_string "inbox";;
      - : Jmap.Role.t = `Inbox
    ]}

    JSON values display as formatted strings, making it easy to see
    how OCaml types map to JMAP JSON. *)

(** {1 JSON Printers} *)

val json_printer : Format.formatter -> Jsont.json -> unit
(** Formats a JSON value as a compact JSON string. *)

val jsont_error_printer : Format.formatter -> Jsont.Error.t -> unit
(** Formats a Jsont parsing error. *)

(** {1 JSON Encoding Helpers}

    These functions encode OCaml types to JSON, useful for understanding
    how the library maps to JMAP wire format. *)

val encode : 'a Jsont.t -> 'a -> Jsont.json
(** [encode codec value] encodes a value to JSON using the given codec.
    Raises [Invalid_argument] on encoding failure. *)

val encode_string : 'a Jsont.t -> 'a -> string
(** [encode_string codec value] encodes a value to a JSON string. *)

val pp_as_json : 'a Jsont.t -> Format.formatter -> 'a -> unit
(** [pp_as_json codec ppf value] pretty-prints a value as JSON. *)

(** {1 Installation} *)

val install : unit -> unit
(** [install ()] installs all printers. This is called automatically when
    the library is loaded, but can be called again if needed. *)