(*---------------------------------------------------------------------------
   Copyright (c) 2026 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** High-level query interface for changes.

    This module provides convenient functions for querying changes since a
    specific timestamp and formatting them for broadcast. *)

(** {1 Querying Changes} *)

val changes_since :
  fs:_ Eio.Path.t ->
  changes_dir:Fpath.t ->
  since:Ptime.t ->
  now:Ptime.t ->
  (Changes_aggregated.entry list, string) result
(** Get all change entries from aggregated files created after [since]. Returns
    entries from all days after the timestamp.
    @param now Current time for determining the date range end. *)

val has_new_changes :
  fs:_ Eio.Path.t -> changes_dir:Fpath.t -> since:Ptime.t -> now:Ptime.t -> bool
(** Check if there are any new changes since the given timestamp.
    @param now Current time for determining the date range end. *)

(** {1 Formatting} *)

val format_for_zulip :
  entries:Changes_aggregated.entry list ->
  include_date:bool ->
  date:string option ->
  string
(** Format entries as markdown suitable for Zulip. If [include_date] is true,
    includes a date header. [date] is used for the header if provided. *)

val format_summary : entries:Changes_aggregated.entry list -> string
(** Format a brief summary of the changes. *)

(** {1 Daily Changes (Real-time)} *)

val daily_changes_since :
  fs:_ Eio.Path.t ->
  changes_dir:Fpath.t ->
  since:Ptime.t ->
  Changes_daily.entry list
(** Get all daily change entries created after [since] timestamp. Uses the
    per-day-per-repo files for real-time access. *)

val has_new_daily_changes :
  fs:_ Eio.Path.t -> changes_dir:Fpath.t -> since:Ptime.t -> bool
(** Check if there are any new daily changes since the given timestamp. *)

val format_daily_for_zulip :
  entries:Changes_daily.entry list ->
  include_date:bool ->
  date:string option ->
  string
(** Format daily entries as markdown suitable for Zulip. Groups entries by
    repository. *)

val format_daily_summary : entries:Changes_daily.entry list -> string
(** Format a brief summary of daily changes. *)