mail

type Caps struct {
	Move       bool
	UIDPlus    bool
	SpecialUse bool
	Idle       bool
	All        []string // every advertised capability, sorted; stored in accounts.capabilities
}

type Cert struct {
	// Fingerprint is the SHA-256 of the certificate (its DER bytes) as upper-case hex pairs
	// separated by colons, the form browsers and `openssl x509 -fingerprint -sha256` show.
	Fingerprint string
	Subject     string
	Issuer      string
	NotBefore   time.Time
	NotAfter    time.Time
}

type CertError struct {
	Host   string
	Cert   Cert   // what the server presented
	Pinned string // the fingerprint accepted for the account; empty when none was
	Reason string // why the system does not trust Cert; empty when Pinned is set
}

type Folder struct {
	Name       string
	Delimiter  string // empty when the server has a flat namespace
	SpecialUse string // one of the Role constants, or empty
}

type FolderStatus struct {
	UIDValidity uint32
	UIDNext     uint32
}

type Mailbox interface {
	Capabilities() Caps
	// Folders lists selectable folders with their special-use role.
	Folders(ctx context.Context) ([]Folder, error)
	// EnsureFolder creates the folder, and any missing parents, if it does not exist.
	EnsureFolder(ctx context.Context, name string) error
	// Status returns the folder's UIDVALIDITY and UIDNEXT. Callers compare UIDValidity with
	// the stored one and, when it differs (or on first connect), baseline lastUID to
	// UIDNext-1 so a whole mailbox is never re-sorted.
	Status(ctx context.Context, folder string) (FolderStatus, error)
	// Watch blocks until ctx is done. It sends every message newer than lastUID,
	// first as catch-up, then as arrivals are reported, in UID order. It reconnects on
	// its own and returns early only for errors that retrying cannot fix (ErrAuth, ErrTLS).
	Watch(ctx context.Context, folder string, lastUID uint32, out chan<- NewMail) error
	// Fetch reads headers and at most maxBody bytes of body without marking the message read.
	Fetch(ctx context.Context, ref MsgRef, maxBody int) (*message.Raw, error)
	// FetchMany reads several messages of one folder in one request, each like Fetch. The
	// result lines up with refs; a message that is gone is nil. refs must all name the same
	// folder and UIDVALIDITY.
	FetchMany(ctx context.Context, refs []MsgRef, maxBody int) ([]*message.Raw, error)
	// FetchSince lists messages received on or after since's date, oldest first.
	// A positive limit keeps only the newest limit messages. matched is how many messages
	// the folder holds in that range before the limit was applied, so a caller can say
	// "the newest 2,000 of 4,310"; the search that finds them already knows it.
	FetchSince(ctx context.Context, folder string, since time.Time, limit int) (refs []MsgRef, matched int, err error)
	// Move moves one message and returns where it now lives.
	Move(ctx context.Context, ref MsgRef, dest string) (MsgRef, error)
	// MoveMany moves several messages of one folder to dest with as few commands as the
	// server allows, and returns where each now lives, lined up with refs. A message it did
	// not move is a zero MsgRef: it is not there, the folder's UIDVALIDITY changed, or (on a
	// server without UIDPLUS) it could not be found in dest afterwards; Move on its own says
	// which. refs must all name the same folder and UIDVALIDITY.
	MoveMany(ctx context.Context, refs []MsgRef, dest string) ([]MsgRef, error)
	SetFlags(ctx context.Context, ref MsgRef, add, remove []string) error
	Flags(ctx context.Context, ref MsgRef) ([]string, error)
	// FindByMessageID returns the newest message in folder with that Message-ID, or ErrNotFound.
	FindByMessageID(ctx context.Context, folder, messageID string) (MsgRef, error)
	// Present reports which of uids are still in folder, with one search that reads nothing
	// of the messages and changes nothing. A message marked \Deleted counts as gone. When
	// the folder's UIDVALIDITY is no longer uidValidity the UIDs name other messages or
	// none, and it fails with ErrNotFound.
	Present(ctx context.Context, folder string, uidValidity uint32, uids []uint32) ([]uint32, error)
	// SentRecipients reads the To and Cc addresses of the newest limit messages in folder
	// (headers only), one entry per address with the latest time it was written to.
	SentRecipients(ctx context.Context, folder string, limit int) ([]Recipient, error)
	// Append adds raw, a whole RFC 5322 message, to folder with flags and date as its
	// internal date, and returns where it now is: from the server's APPENDUID (UIDPLUS), or
	// else by a search for raw's Message-ID, which it must then have. It is how MailRules
	// saves a draft reply; nothing else is ever added to a mailbox.
	Append(ctx context.Context, folder string, raw []byte, flags []string, date time.Time) (MsgRef, error)
	// Delete removes the one message at ref for good: UID STORE +FLAGS (\Deleted), then UID
	// EXPUNGE of that UID alone, never a bare EXPUNGE, which would also remove mail other
	// clients had marked deleted. A server without UIDPLUS gets ErrUnsupported and nothing
	// is changed. Only the undo of a draft MailRules appended calls it, on exactly that UID.
	Delete(ctx context.Context, ref MsgRef) error
	Close() error
}

type MsgRef struct {
	AccountID   int64
	Folder      string
	UIDValidity uint32
	UID         uint32
}

type NewMail struct{ Ref MsgRef }

type Recipient struct {
	Address string // lower-cased
	SentAt  time.Time
}