(** Sync operations and long-polling loop. *)

(** {1 Sync API} *)

(** Sync parameters. *)
type params = {
  filter : string option;
  (** Filter ID to use (from {!create_filter}). *)
  since : string option;
  (** Sync token from previous sync. *)
  full_state : bool;
  (** If true, return full state even if since is provided. *)
  set_presence : [ `Online | `Offline | `Unavailable ] option;
  (** Presence state to set. *)
  timeout : int;
  (** Long-poll timeout in milliseconds. 0 for immediate return. *)
}

(** Default sync parameters: 30 second timeout, no filter. *)
val default_params : params

(** Perform a single sync request.

    Returns the sync response from the server. The [next_batch] field
    should be used as [since] for the next sync request. *)
val sync :
  Client.t ->
  ?params:params ->
  unit ->
  (Matrix_proto.Sync.Response.t, Error.t) result

(** {1 Sync Loop} *)

(** Action to take after processing a sync response or error. *)
type action =
  | Continue           (** Continue syncing *)
  | Stop               (** Stop the sync loop *)
  | Retry_after of int (** Retry after N milliseconds *)

(** Callbacks for the sync loop. *)
type callbacks = {
  on_sync : Matrix_proto.Sync.Response.t -> action;
  (** Called for each successful sync response. *)
  on_error : Error.t -> action;
  (** Called when sync fails. *)
}

(** Run a continuous sync loop.

    This function blocks and continuously syncs with the server,
    calling the appropriate callback for each response or error.
    The loop continues until a callback returns [Stop].

    @param clock Eio clock for sleeping on Retry_after.
    @param initial_since Starting sync token (None for initial sync).
    @param params Sync parameters to use (timeout, filter, etc.). *)
val sync_forever :
  Client.t ->
  clock:_ Eio.Time.clock ->
  ?initial_since:string ->
  ?params:params ->
  callbacks:callbacks ->
  unit ->
  unit

(** {1 Filters} *)

(** Event filter for sync. *)
type event_filter = {
  limit : int option;
  not_senders : string list;
  not_types : string list;
  senders : string list;
  types : string list;
}

(** Room event filter. *)
type room_event_filter = {
  limit : int option;
  not_senders : string list;
  not_types : string list;
  senders : string list;
  types : string list;
  lazy_load_members : bool;
  include_redundant_members : bool;
  not_rooms : string list;
  rooms : string list;
  contains_url : bool option;
}

(** Room filter. *)
type room_filter = {
  not_rooms : string list;
  rooms : string list;
  ephemeral : room_event_filter option;
  include_leave : bool;
  state : room_event_filter option;
  timeline : room_event_filter option;
  account_data : room_event_filter option;
}

(** Complete sync filter. *)
type filter = {
  event_fields : string list;
  event_format : [ `Client | `Federation ];
  presence : event_filter option;
  account_data : event_filter option;
  room : room_filter option;
}

(** Default empty event filter. *)
val default_event_filter : event_filter

(** Default room event filter with lazy loading enabled. *)
val default_room_event_filter : room_event_filter

(** Default room filter. *)
val default_room_filter : room_filter

(** Default filter. *)
val default_filter : filter

(** Create a filter on the homeserver.

    Returns the filter ID that can be used in sync requests. *)
val create_filter :
  Client.t ->
  filter:filter ->
  (string, Error.t) result

(** Get an existing filter from the homeserver. *)
val get_filter :
  Client.t ->
  filter_id:string ->
  (filter, Error.t) result