(** JMAP Email Validation Rules.
    
    This module implements comprehensive validation rules for JMAP email objects
    and related entities as specified in RFC 8621. Provides validation functions
    for ensuring data integrity and RFC compliance.
    
    @see <https://www.rfc-editor.org/rfc/rfc8621.html> RFC 8621: JMAP for Mail
*)

(** {1 Email Object Validation} *)

(** Validation error types *)
type validation_error = [
  | `InvalidKeyword of string * string  (** Invalid keyword format with keyword and reason *)
  | `InvalidEmailAddress of string      (** Invalid email address format *)
  | `InvalidSize of int * int           (** Size exceeds limit (actual, max) *)
  | `InvalidMailboxId of string         (** Invalid mailbox ID format *)
  | `InvalidMessageId of string         (** Invalid Message-ID format *)
  | `InvalidHeader of string * string   (** Invalid header name/value *)
  | `InvalidDate of string              (** Invalid date format *)
  | `DuplicateRole of string            (** Duplicate mailbox role *)
  | `InvalidRole of string              (** Invalid mailbox role *)
  | `MailboxHierarchyCycle of string list  (** Circular mailbox hierarchy *)
  | `InvalidIdentityPermission of string   (** Invalid identity permission *)
  | `InvalidSubmissionTime of string       (** Invalid email submission time *)
]

(** Format validation error for display *)
val string_of_validation_error : validation_error -> string

(** {1 Keywords Validation} *)

(** Validate email keywords according to RFC 8621 Section 4.1.1.
    
    Keywords must be:
    - Lowercase ASCII characters only
    - No whitespace or control characters  
    - Maximum length of 255 characters
    - Valid UTF-8 encoding
    
    @param keywords Keywords to validate
    @return Ok () if valid, Error with invalid keywords *)
val validate_keywords : Jmap_email.Keywords.t -> (unit, validation_error list) result

(** Validate a single keyword string format.
    
    @param keyword Keyword string to validate
    @return Ok () if valid, Error with reason *)
val validate_keyword_format : string -> (unit, validation_error) result

(** Check if a keyword is a standard system keyword.
    
    @param keyword Keyword to check
    @return true if it's a standard system keyword *)
val is_system_keyword : string -> bool

(** Get list of all standard system keywords.
    
    @return List of standard JMAP keywords *)
val standard_keywords : string list

(** {1 Email Address Validation} *)

(** Validate email address format according to RFC 5322.
    
    @param address Email address to validate
    @return Ok () if valid, Error with reason *)
val validate_email_address : Jmap_email.Address.t -> (unit, validation_error) result

(** Validate email address string format.
    
    @param addr_str Email address string to validate  
    @return Ok () if valid, Error with reason *)
val validate_email_address_string : string -> (unit, validation_error) result

(** {1 Size Constraints Validation} *)

(** Validate email object size constraints.
    
    Checks various size limits according to RFC 8621:
    - Maximum email size
    - Maximum header size
    - Maximum attachment count
    
    @param email Email object to validate
    @return Ok () if valid, Error with constraint violations *)
val validate_size_constraints : Jmap_email.Email.Email.t -> (unit, validation_error list) result

(** Validate mailbox name size constraints.
    
    @param name Mailbox name to validate
    @return Ok () if valid, Error with reason *)
val validate_mailbox_name_size : string -> (unit, validation_error) result

(** {1 Mailbox Validation} *)

(** Validate mailbox role uniqueness within an account.
    
    Each account should have at most one mailbox of each standard role.
    
    @param mailboxes List of mailboxes in the account
    @return Ok () if valid, Error with duplicate roles *)
val validate_mailbox_role_uniqueness : Jmap_email.Mailbox.Mailbox.t list -> (unit, validation_error list) result

(** Validate mailbox hierarchy for cycles.
    
    Ensures parent-child relationships don't create circular references.
    
    @param mailboxes List of mailboxes to check
    @return Ok () if valid, Error with cycle information *)
val validate_mailbox_hierarchy : Jmap_email.Mailbox.Mailbox.t list -> (unit, validation_error list) result

(** Validate mailbox name collision rules.
    
    @param mailboxes List of mailboxes to check
    @return Ok () if valid, Error with name collisions *)
val validate_mailbox_name_collisions : Jmap_email.Mailbox.Mailbox.t list -> (unit, validation_error list) result

(** {1 Email Submission Validation} *)

(** Validate SMTP envelope format.
    
    @param envelope SMTP envelope to validate
    @return Ok () if valid, Error with validation issues *)
val validate_smtp_envelope : Jmap_email.Submission.Envelope.t -> (unit, validation_error list) result

(** Validate email send-time constraints.
    
    @param send_at Optional send time to validate
    @return Ok () if valid, Error with constraint violation *)
val validate_send_time_constraints : Jmap.Date.t option -> (unit, validation_error) result

(** Validate identity permission for sending.
    
    @param identity Identity to validate
    @param sender_email Sender email address
    @return Ok () if valid, Error with permission issue *)
val validate_identity_permission : Jmap_email.Identity.Identity.t -> string -> (unit, validation_error) result

(** {1 Header Validation} *)

(** Validate email header format and content.
    
    @param header Header to validate
    @return Ok () if valid, Error with validation issue *)
val validate_header : Jmap_email.Header.t -> (unit, validation_error) result

(** Validate Message-ID header format.
    
    @param message_id Message-ID value to validate
    @return Ok () if valid, Error with format issue *)
val validate_message_id : string -> (unit, validation_error) result

(** Validate References header format.
    
    @param references References header value to validate
    @return Ok () if valid, Error with format issue *)
val validate_references : string -> (unit, validation_error) result

(** {1 Date Validation} *)

(** Validate date format and constraints.
    
    @param date Date to validate
    @return Ok () if valid, Error with validation issue *)
val validate_date : Jmap.Date.t -> (unit, validation_error) result

(** Validate date string format.
    
    @param date_str Date string to validate
    @return Ok () if valid, Error with format issue *)
val validate_date_string : string -> (unit, validation_error) result

(** {1 Comprehensive Validation} *)

(** Validate complete email object with all constraints.
    
    Performs comprehensive validation including:
    - Keywords format
    - Email addresses
    - Size constraints  
    - Headers
    - Dates
    
    @param email Email object to validate
    @return Ok () if valid, Error with all validation issues *)
val validate_email_complete : Jmap_email.Email.Email.t -> (unit, validation_error list) result

(** Validate complete mailbox object with all constraints.
    
    @param mailbox Mailbox object to validate
    @return Ok () if valid, Error with validation issues *)
val validate_mailbox_complete : Jmap_email.Mailbox.Mailbox.t -> (unit, validation_error list) result

(** Validate complete email submission with all constraints.
    
    @param submission Email submission to validate
    @return Ok () if valid, Error with validation issues *)
val validate_submission_complete : Jmap_email.Submission.EmailSubmission.t -> (unit, validation_error list) result