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

(** Mailbox type as defined in RFC 8621 Section 2

    @canonical Jmap.Proto.Mailbox *)

(** {1 Mailbox Properties}

    Polymorphic variants for type-safe property selection in Mailbox/get requests.
    These correspond to the properties defined in RFC 8621 Section 2. *)

(** All Mailbox properties that can be requested. *)
type property = [
  | `Id
  | `Name
  | `Parent_id
  | `Role
  | `Sort_order
  | `Total_emails
  | `Unread_emails
  | `Total_threads
  | `Unread_threads
  | `My_rights
  | `Is_subscribed
]

val property_to_string : [< property ] -> string
(** Convert a property to its wire name (e.g., [`Parent_id] -> "parentId"). *)

val property_of_string : string -> property option
(** Parse a property name, case-sensitive. *)

(** {1 Mailbox Rights} *)

(** Rights the user has on a mailbox. *)
module Rights : sig
  type t = {
    may_read_items : bool;
    may_add_items : bool;
    may_remove_items : bool;
    may_set_seen : bool;
    may_set_keywords : bool;
    may_create_child : bool;
    may_rename : bool;
    may_delete : bool;
    may_submit : bool;
  }

  val may_read_items : t -> bool
  val may_add_items : t -> bool
  val may_remove_items : t -> bool
  val may_set_seen : t -> bool
  val may_set_keywords : t -> bool
  val may_create_child : t -> bool
  val may_rename : t -> bool
  val may_delete : t -> bool
  val may_submit : t -> bool

  val jsont : t Jsont.t
end

(** {1 Standard Roles} *)

(** Standard mailbox roles per RFC 8621 Section 2 and draft-ietf-mailmaint. *)
type role = [
  | `All
  | `Archive
  | `Drafts
  | `Flagged
  | `Important
  | `Inbox
  | `Junk
  | `Sent
  | `Subscribed
  | `Trash
  | `Snoozed     (** draft-ietf-mailmaint: Messages snoozed until a later time. *)
  | `Scheduled   (** draft-ietf-mailmaint: Messages scheduled to send. *)
  | `Memos       (** draft-ietf-mailmaint: Messages with the $memo keyword. *)
  | `Other of string
]

val role_to_string : role -> string
val role_of_string : string -> role
val role_jsont : role Jsont.t

(** {2 Conversion to/from mail-flag} *)

val role_of_special_use : Mail_flag.Mailbox_attr.special_use -> role
(** [role_of_special_use su] converts a mail-flag special-use attribute to a JMAP role. *)

val special_use_of_role : role -> Mail_flag.Mailbox_attr.special_use option
(** [special_use_of_role r] converts a JMAP role to a mail-flag special-use attribute.
    Returns [None] for [`Other _] roles that don't correspond to standard special-use values. *)

(** {1 Mailbox} *)

type t = {
  id : Proto_id.t option;
  (** Server-assigned mailbox id. *)
  name : string option;
  (** User-visible name (UTF-8). *)
  parent_id : Proto_id.t option;
  (** Id of parent mailbox, or [None] for root. Note: [None] can mean
      either "not requested" or "top-level mailbox". *)
  role : role option;
  (** Standard role, if any. Note: [None] can mean either "not requested"
      or "no role assigned". *)
  sort_order : int64 option;
  (** Sort order hint (lower = displayed first). *)
  total_emails : int64 option;
  (** Total number of emails in mailbox. *)
  unread_emails : int64 option;
  (** Number of unread emails. *)
  total_threads : int64 option;
  (** Total number of threads. *)
  unread_threads : int64 option;
  (** Number of threads with unread emails. *)
  my_rights : Rights.t option;
  (** User's rights on this mailbox. *)
  is_subscribed : bool option;
  (** Whether user is subscribed to this mailbox. *)
}

val id : t -> Proto_id.t option
val name : t -> string option
val parent_id : t -> Proto_id.t option
val role : t -> role option
val sort_order : t -> int64 option
val total_emails : t -> int64 option
val unread_emails : t -> int64 option
val total_threads : t -> int64 option
val unread_threads : t -> int64 option
val my_rights : t -> Rights.t option
val is_subscribed : t -> bool option

val jsont : t Jsont.t

(** {1 Mailbox Filter Conditions} *)

(** Filter conditions for Mailbox/query. *)
module Filter_condition : sig
  type t = {
    parent_id : Proto_id.t option option;
    (** Filter by parent. [Some None] = top-level only. *)
    name : string option;
    (** Filter by exact name match. *)
    role : role option option;
    (** Filter by role. [Some None] = no role. *)
    has_any_role : bool option;
    (** Filter by whether mailbox has any role. *)
    is_subscribed : bool option;
    (** Filter by subscription status. *)
  }

  val jsont : t Jsont.t
end