(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** JSON Feed format parser and serializer.

    @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)

type t
(** The type representing a complete JSON Feed. *)

(** {1 Jsont Type} *)

val jsont : t Jsont.t
(** Declarative JSON type for JSON feeds.

    Maps the complete JSON Feed 1.1 specification including all required and
    optional fields. *)

module Unknown : sig
  type t = (string * Jsont.json) list
  (** Unknown/unrecognized JSON object members. Useful for preserving fields
      from custom extensions or future spec versions. *)

  val empty : t
  (** [empty] is the empty list of unknown fields. *)

  val is_empty : t -> bool
  (** [is_empty u] returns [true] if there are no unknown fields. *)
end

val create :
  title:string ->
  ?home_page_url:string ->
  ?feed_url:string ->
  ?description:string ->
  ?user_comment:string ->
  ?next_url:string ->
  ?icon:string ->
  ?favicon:string ->
  ?authors:Author.t list ->
  ?language:string ->
  ?expired:bool ->
  ?hubs:Hub.t list ->
  items:Item.t list ->
  ?unknown:Unknown.t ->
  unit ->
  t

val version : t -> string
val title : t -> string
val home_page_url : t -> string option
val feed_url : t -> string option
val description : t -> string option
val user_comment : t -> string option
val next_url : t -> string option
val icon : t -> string option
val favicon : t -> string option
val authors : t -> Author.t list option
val language : t -> string option
val expired : t -> bool option
val hubs : t -> Hub.t list option
val items : t -> Item.t list
val unknown : t -> Unknown.t

(** {1 Encoding and Decoding} *)

val decode :
  ?layout:bool ->
  ?locs:bool ->
  ?file:string ->
  Bytesrw.Bytes.Reader.t ->
  (t, Jsont.Error.t) result
(** [decode r] decodes a JSON Feed from bytesrw reader [r].

    @param layout Preserve whitespace for round-tripping (default: false)
    @param locs Track locations for better error messages (default: false)
    @param file Source file name for error reporting *)

val decode_string :
  ?layout:bool ->
  ?locs:bool ->
  ?file:string ->
  string ->
  (t, Jsont.Error.t) result
(** [decode_string s] decodes a JSON Feed from string [s]. *)

val encode :
  ?format:Jsont.format ->
  ?number_format:Jsont.number_format ->
  t ->
  eod:bool ->
  Bytesrw.Bytes.Writer.t ->
  (unit, Jsont.Error.t) result
(** [encode feed w] encodes [feed] to bytesrw writer [w].

    @param format
      Output formatting: [Jsont.Minify] or [Jsont.Indent] (default: Minify)
    @param number_format Printf format for numbers (default: "%.16g")
    @param eod Write end-of-data marker *)

val encode_string :
  ?format:Jsont.format ->
  ?number_format:Jsont.number_format ->
  t ->
  (string, Jsont.Error.t) result
(** [encode_string feed] encodes [feed] to a string. *)

val of_string : string -> (t, Jsont.Error.t) result
(** Alias for [decode_string] with default options. *)

val to_string : ?minify:bool -> t -> (string, Jsont.Error.t) result
(** [to_string feed] encodes [feed] to string.
    @param minify Use compact format (true) or indented (false, default) *)

(** {1 Validation} *)

val validate : t -> (unit, string list) result
(** [validate feed] validates the feed structure. Checks for unique item IDs,
    valid content, etc. *)

(** {1 Comparison} *)

val equal : t -> t -> bool
(** [equal a b] tests equality between two feeds. *)

(** {1 Pretty Printing} *)

val pp : Format.formatter -> t -> unit
val pp_summary : Format.formatter -> t -> unit

(** {1 Submodules} *)

module Rfc3339 = Rfc3339
module Cito = Cito
module Author = Author
module Attachment = Attachment
module Hub = Hub
module Reference = Reference
module Item = Item