(** Matrix client type and lifecycle. *)

(** Client configuration. *)
type config = {
  homeserver : Uri.t;
  (** Homeserver URL (e.g., https://matrix.org) *)
  user_agent : string option;
  (** Optional custom User-Agent header *)
}

(** Session information after login. *)
type session = {
  user_id : Matrix_proto.Id.User_id.t;
  access_token : string;
  device_id : Matrix_proto.Id.Device_id.t;
  refresh_token : string option;
}

(** Matrix client. *)
type t

(** Create a new client.

    The client is not logged in initially. Use {!Auth.login_password} or
    {!with_session} to authenticate.

    The environment must provide network and clock capabilities. *)
val create :
  sw:Eio.Switch.t ->
  config:config ->
  < net : _ Eio.Net.t ; clock : _ Eio.Time.clock ; fs : Eio.Fs.dir_ty Eio.Path.t ; .. > ->
  t

(** Restore a client from a saved session.

    Returns a new client with the session set. The original client is unchanged. *)
val with_session : t -> session -> t

(** Get current session if logged in. *)
val session : t -> session option

(** Get the homeserver URL. *)
val homeserver : t -> Uri.t

(** Check if client is logged in. *)
val is_logged_in : t -> bool

(** Get the access token if logged in. *)
val access_token : t -> string option

(** Get the user ID if logged in. *)
val user_id : t -> Matrix_proto.Id.User_id.t option

(** Get the device ID if logged in. *)
val device_id : t -> Matrix_proto.Id.Device_id.t option

(** {1 Internal HTTP helpers}

    These are used by the API modules. *)

(** Make a GET request. *)
val get :
  t ->
  path:string ->
  ?query:(string * string) list ->
  unit ->
  (string, Error.t) result

(** Make a POST request with JSON body. *)
val post :
  t ->
  path:string ->
  ?query:(string * string) list ->
  body:string ->
  unit ->
  (string, Error.t) result

(** Make a PUT request with JSON body. *)
val put :
  t ->
  path:string ->
  ?query:(string * string) list ->
  body:string ->
  unit ->
  (string, Error.t) result

(** Make a DELETE request. *)
val delete :
  t ->
  path:string ->
  ?query:(string * string) list ->
  ?body:string ->
  unit ->
  (string, Error.t) result

(** Make a POST request without authentication (for login/register). *)
val post_unauthenticated :
  t ->
  path:string ->
  ?query:(string * string) list ->
  body:string ->
  unit ->
  (string, Error.t) result

(** Decode a JSON response using a jsont codec. *)
val decode_response : 'a Jsont.t -> string -> ('a, Error.t) result

(** Encode a value to JSON string using a jsont codec.
    Returns Error if encoding fails. *)
val encode_body : 'a Jsont.t -> 'a -> (string, Error.t) result