(** Email changes operations using core JMAP Changes_args.
    
    This module provides type-safe Email/changes operations for tracking
    modifications to emails since a given state, enabling efficient
    incremental synchronization.
    
    @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.6> RFC 8621 Section 4.6 *)

open Jmap.Methods

(** {1 Changes Arguments} *)

(** Build Email/changes arguments using core Changes_args.
    @param account_id The account to check for changes
    @param since_state The state to get changes since
    @param ?max_changes Optional maximum number of changes to return
    @return Changes_args for Email/changes method *)
val build_changes_args :
  account_id:Jmap.Id.t ->
  since_state:string ->
  ?max_changes:Jmap.UInt.t ->
  unit ->
  Changes_args.t

(** Convert Email/changes arguments to JSON.
    @param args The Changes_args to convert
    @return JSON representation for Email/changes method *)
val changes_args_to_json : Changes_args.t -> Yojson.Safe.t

(** {1 Change Tracking} *)

(** Change tracker for accumulating changes over time *)
type change_tracker

(** Create a new change tracker.
    @param account_id The account ID to track
    @param initial_state The starting state
    @return A new change tracker *)
val create_tracker :
  account_id:Jmap.Id.t ->
  initial_state:string ->
  change_tracker

(** Update tracker with a Changes_response.
    @param tracker The tracker to update
    @param response The changes response to process
    @return Updated tracker with accumulated changes *)
val update_tracker :
  change_tracker ->
  Changes_response.t ->
  change_tracker

(** Get all accumulated changes.
    @param tracker The change tracker
    @return Tuple of (created_ids, updated_ids, destroyed_ids) *)
val get_all_changes :
  change_tracker ->
  (Jmap.Id.t list * Jmap.Id.t list * Jmap.Id.t list)

(** {1 Incremental Sync} *)

(** Get next batch of changes.
    @param account_id The account ID
    @param since_state State to get changes since
    @param ?max_changes Maximum changes per batch (default 500)
    @return Changes_args for fetching next batch *)
val get_next_changes :
  account_id:Jmap.Id.t ->
  since_state:string ->
  ?max_changes:int ->
  unit ->
  Changes_args.t

(** Check if there are more changes pending.
    @param response The changes response to check
    @return True if has_more_changes flag is set *)
val has_pending_changes : Changes_response.t -> bool

(** Module for managing incremental sync state *)
module Sync : sig
  (** Sync state tracking *)
  type sync_state
  
  (** Initialize sync state.
      @param account_id The account to sync
      @param initial_state The starting state
      @return New sync state *)
  val init :
    account_id:Jmap.Id.t ->
    initial_state:string ->
    sync_state
  
  (** Add a changes response to sync state.
      @param sync Current sync state
      @param response Changes response to add
      @return Updated sync state *)
  val add_response :
    sync_state ->
    Changes_response.t ->
    sync_state
  
  (** Clear pending changes from sync state.
      @param sync Sync state to clear
      @return Sync state with empty pending lists *)
  val clear_pending : sync_state -> sync_state
  
  (** Get pending changes.
      @param sync Sync state
      @return Tuple of (created, updated, destroyed) ID lists *)
  val get_pending :
    sync_state ->
    (Jmap.Id.t list * Jmap.Id.t list * Jmap.Id.t list)
  
  (** Check if sync is needed.
      @param sync Current sync state
      @param response Last changes response
      @return True if more changes or pending items exist *)
  val needs_sync :
    sync_state ->
    Changes_response.t ->
    bool
end

(** {1 Utilities} *)

(** Merge multiple change responses.
    @param responses List of changes responses
    @return Combined (created, updated, destroyed) ID lists *)
val merge_changes :
  Changes_response.t list ->
  (Jmap.Id.t list * Jmap.Id.t list * Jmap.Id.t list)

(** Get updated properties if available.
    @param response Changes response
    @return Optional list of properties that were updated *)
val get_updated_properties :
  Changes_response.t ->
  string list option