(** Email header field representation.
    
    This module provides types and operations for email header fields as defined in
    RFC 8621 Section 4.1.3. Each header field consists of a field name and its raw,
    unprocessed value as it appears in the original email message.
    
    Header fields follow RFC 5322 syntax and provide access to both standard headers
    (Subject, From, To, etc.) and custom headers that may not be parsed into specific
    Email object properties.
    
    @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.3> RFC 8621, Section 4.1.3 - Email Header Fields
*)

(** Email header field type.
    
    Represents a single email header field as specified in RFC 8621 Section 4.1.3.
    Each header consists of a field name and its raw, unprocessed value as it
    appears in the original email message.
*)
type t

(** JSON serialization interface *)
include Jmap_sigs.JSONABLE with type t := t

(** Pretty-printing interface *)
include Jmap_sigs.PRINTABLE with type t := t

(** Get the header field name.
    @param t The header field
    @return The header field name (e.g., "Subject", "X-Custom-Header") *)
val name : t -> string

(** Get the raw header field value.
    @param t The header field
    @return The unprocessed header value as it appears in the message *)
val value : t -> string

(** Create a new header field.
    
    Creates a header field with validation of the field name according to RFC 5322.
    Header names must contain only printable ASCII characters and cannot contain
    control characters, spaces, or certain special characters.
    
    @param name The header field name
    @param value The raw header field value
    @return Result containing new header field object or validation error *)
val create : 
  name:string -> 
  value:string -> 
  unit -> (t, string) result

(** Create a new header field without validation.
    
    For use when header field names are known to be valid or come from
    trusted sources like server responses.
    
    @param name The header field name
    @param value The raw header field value
    @return New header field object *)
val create_unsafe : 
  name:string -> 
  value:string -> 
  unit -> t

(** Convert a list of header fields to JSON array.
    
    Utility function for converting header field lists to JSON arrays
    as used in Email body parts and other contexts.
    
    @param headers List of header fields to convert
    @return JSON array containing header field objects *)
val list_to_json : t list -> Yojson.Safe.t

(** Parse a list of header fields from JSON array.
    
    Utility function for parsing JSON arrays of header field objects.
    Individual parsing errors are collected and reported.
    
    @param json JSON array containing header field objects
    @return Result containing parsed header field list or parse errors *)
val list_of_json : Yojson.Safe.t -> (t list, string) result

(** Find a header field by name (case-insensitive).
    
    Searches a list of header fields for the first field matching the given
    name using case-insensitive comparison as specified in RFC 5322.
    
    @param headers List of header fields to search
    @param name Header field name to find
    @return The first matching header field, or None if not found *)
val find_by_name : t list -> string -> t option

(** Get all header fields with a given name (case-insensitive).
    
    Returns all header fields matching the given name. This is useful for
    headers that may appear multiple times like "Received" or "X-*" headers.
    
    @param headers List of header fields to search
    @param name Header field name to find
    @return List of all matching header fields *)
val find_all_by_name : t list -> string -> t list

(** Validate a header field name according to RFC 5322.
    
    Checks that a header field name consists only of printable ASCII characters
    and does not contain control characters, spaces, or the colon character.
    
    @param name The header field name to validate
    @return Ok if valid, Error with description if invalid *)
val validate_name : string -> (unit, string) result

(** Structured header parsing support for JMAP access patterns *)
module Value : sig
  (** Header value access patterns as defined in RFC 8621 Section 4.1.2 *)
  type access_form =
    | Raw                (** Raw octets as they appear in the message *)
    | Text               (** Decoded and unfolded text *)
    | Addresses          (** Parsed email addresses *)
    | GroupedAddresses   (** Parsed addresses preserving group information *)
    | MessageIds         (** Parsed message ID list *)
    | Date               (** Parsed date value *)
    | URLs               (** Parsed URL list *)

  (** Structured header value types *)
  type parsed_value =
    | Raw_value of string
    | Text_value of string  
    | Addresses_value of Address.t list
    | GroupedAddresses_value of Address.Group.t list
    | MessageIds_value of string list
    | Date_value of Jmap.Date.t
    | URLs_value of string list

  (** Parse error types *)
  type parse_error =
    | Invalid_encoding of string     (** RFC 2047 encoding error *)
    | Malformed_header of string     (** Malformed header structure *)
    | Unsupported_form of string * access_form (** Unsupported access form for header *)
    | Parse_failure of string        (** General parse failure *)
end

(** Header access pattern functions following RFC 8621 Section 4.1.2 *)

(** Get header value as Raw form.
    
    Returns the raw octets of the header field value as specified in
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.1}RFC 8621 Section 4.1.2.1}.
    This form always succeeds and returns the header value as-is.
    
    @param t The header field
    @return Raw header field value *)
val as_raw : t -> string

(** Get header value as Text form.
    
    Processes the header value according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.2}RFC 8621 Section 4.1.2.2}
    with white space unfolding, RFC 2047 decoding, and normalization.
    Only valid for specific header fields as defined in the RFC.
    
    @param t The header field
    @return Result containing decoded text or parse error *)
val as_text : t -> (string, Value.parse_error) result

(** Get header value as parsed email addresses.
    
    Parses the header as an address-list according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.3}RFC 8621 Section 4.1.2.3}.
    Only valid for address-type header fields (From, To, Cc, etc.).
    
    @param t The header field
    @return Result containing list of email addresses or parse error *)
val as_addresses : t -> (Address.t list, Value.parse_error) result

(** Get header value as grouped addresses.
    
    Similar to addresses but preserves group information according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.4}RFC 8621 Section 4.1.2.4}.
    Only valid for address-type header fields.
    
    @param t The header field
    @return Result containing list of address groups or parse error *)
val as_grouped_addresses : t -> (Address.Group.t list, Value.parse_error) result

(** Get header value as message ID list.
    
    Parses the header as message IDs according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.5}RFC 8621 Section 4.1.2.5}.
    Only valid for message ID header fields (Message-ID, In-Reply-To, References).
    
    @param t The header field
    @return Result containing list of message IDs or parse error *)
val as_message_ids : t -> (string list, Value.parse_error) result

(** Get header value as parsed date.
    
    Parses the header as a date-time according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.6}RFC 8621 Section 4.1.2.6}.
    Only valid for date header fields (Date, Resent-Date).
    
    @param t The header field
    @return Result containing parsed date or parse error *)
val as_date : t -> (Jmap.Date.t, Value.parse_error) result

(** Get header value as URL list.
    
    Parses the header as URLs according to
    {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.7}RFC 8621 Section 4.1.2.7}.
    Only valid for URL-type header fields (List-Archive, List-Post, etc.).
    
    @param t The header field
    @return Result containing list of URLs or parse error *)
val as_urls : t -> (string list, Value.parse_error) result

(** Parse header in the specified access form.
    
    Generic function for parsing a header in any supported access pattern.
    This provides a unified interface for all parsing operations.
    
    @param t The header field
    @param form The desired access form
    @return Result containing parsed value or parse error *)
val parse_as : t -> Value.access_form -> (Value.parsed_value, Value.parse_error) result

(** Utility functions for working with header lists *)

(** Find header by name and parse as Text form.
    @param headers List of header fields to search
    @param name Header field name to find
    @return Parsed text value if found and valid, None otherwise *)
val find_and_parse_as_text : t list -> string -> string option

(** Find header by name and parse as addresses.
    @param headers List of header fields to search
    @param name Header field name to find
    @return List of parsed addresses if found and valid, None otherwise *)
val find_and_parse_as_addresses : t list -> string -> Address.t list option

(** Find header by name and parse as message IDs.
    @param headers List of header fields to search
    @param name Header field name to find
    @return List of parsed message IDs if found and valid, None otherwise *)
val find_and_parse_as_message_ids : t list -> string -> string list option

(** Find header by name and parse as date.
    @param headers List of header fields to search
    @param name Header field name to find
    @return Parsed date if found and valid, None otherwise *)
val find_and_parse_as_date : t list -> string -> Jmap.Date.t option