mail

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

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)
	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)
	// 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)
	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
}