mailbox

type AttachmentLoader interface {
	LoadAttachment(ctx context.Context, messageID, attachmentID string) (io.ReadCloser, error)
}

type AttachmentRefError struct {
	// Operation is either "add" or "release"
	Operation string
	// Failed maps attachment IDs to their errors
	Failed map[string]error
	// RollbackFailed maps attachment IDs to rollback errors (only for "add" operations)
	RollbackFailed map[string]error
}

type AttachmentResolver interface {
	ResolveAttachments(ctx context.Context, attachmentIDs []string) ([]store.Attachment, error)
}

type AttachmentStore = store.AttachmentFileStore

type BulkOperationError struct {
	Result *BulkResult
}

type BulkOperator interface {
	BulkUpdateFlags(ctx context.Context, messageIDs []string, flags Flags) (*BulkResult, error)
	BulkMove(ctx context.Context, messageIDs []string, folderID string, opts ...store.MoveOption) (*BulkResult, error)
	BulkDelete(ctx context.Context, messageIDs []string) (*BulkResult, error)
	BulkPermanentlyDelete(ctx context.Context, messageIDs []string) (*BulkResult, error)
	BulkAddTag(ctx context.Context, messageIDs []string, tagID string) (*BulkResult, error)
	BulkRemoveTag(ctx context.Context, messageIDs []string, tagID string) (*BulkResult, error)
}

type BulkResult struct {
	// Results contains the outcome of each operation in input order.
	Results []OperationResult
}

type CleanupExpiredMessagesResult struct {
	// DeletedCount is the number of messages permanently deleted.
	DeletedCount int
	// Interrupted indicates if the cleanup was interrupted (e.g., context cancelled).
	Interrupted bool
}

type CleanupTrashResult struct {
	// DeletedCount is the number of messages permanently deleted.
	DeletedCount int
	// Interrupted indicates if the cleanup was interrupted (e.g., context cancelled).
	Interrupted bool
}

type Config struct {

	// TrashCleanupInterval is how often to run automatic trash cleanup.
	// Zero disables automatic trash cleanup (caller must invoke CleanupTrash manually).
	TrashCleanupInterval time.Duration

	// ExpiredMessageCleanupInterval is how often to run automatic expired message cleanup.
	// This covers both global retention (MessageRetention) and per-message TTL expiry.
	// Zero disables automatic cleanup (caller must invoke CleanupExpiredMessages manually).
	ExpiredMessageCleanupInterval time.Duration

	// QuotaEnforcementInterval is how often to run automatic quota enforcement.
	// Requires QuotaUserLister to be set; ignored if nil.
	// Zero disables automatic quota enforcement (caller must invoke EnforceQuotas manually).
	QuotaEnforcementInterval time.Duration

	// QuotaUserLister provides the list of user IDs for background quota enforcement.
	// Required when QuotaEnforcementInterval > 0. If nil, quota enforcement is skipped
	// even when the interval is set.
	QuotaUserLister QuotaUserLister

	// TrashRetention is how long messages stay in trash before cleanup.
	// Default is 30 days. Minimum is 1 day; shorter values are ignored.
	TrashRetention time.Duration

	// MessageRetention is the global message TTL based on creation time.
	// Messages older than this are permanently deleted by CleanupExpiredMessages.
	// Default is 0 (disabled). Minimum is 1 day when enabled.
	MessageRetention time.Duration

	// MaxSubjectLength is the maximum subject length in characters.
	// Default is 998 (RFC 5322).
	MaxSubjectLength int

	// MaxBodySize is the maximum body size in bytes.
	// Default is 10 MB.
	MaxBodySize int

	// MaxAttachmentSize is the maximum size per attachment in bytes.
	// Default is 25 MB.
	MaxAttachmentSize int64

	// MaxAttachmentCount is the maximum number of attachments per message.
	// Default is 20.
	MaxAttachmentCount int

	// MaxRecipientCount is the maximum number of recipients per message.
	// Default is 100.
	MaxRecipientCount int

	// MaxMetadataSize is the maximum total metadata size in bytes.
	// Default is 64 KB.
	MaxMetadataSize int

	// MaxMetadataKeys is the maximum number of metadata keys per message.
	// Default is 100.
	MaxMetadataKeys int

	// MaxHeaderCount is the maximum number of headers per message.
	// Default is 50.
	MaxHeaderCount int

	// MaxHeaderKeyLength is the maximum length of a single header key.
	// Default is 128 bytes.
	MaxHeaderKeyLength int

	// MaxHeaderValueLength is the maximum length of a single header value.
	// Default is 8 KB.
	MaxHeaderValueLength int

	// MaxHeadersTotalSize is the maximum total size of all headers combined.
	// Default is 64 KB.
	MaxHeadersTotalSize int

	// MaxQueryLimit is the maximum number of messages per query.
	// Any query requesting more than this limit will be capped.
	// Default is 100.
	MaxQueryLimit int

	// DefaultQueryLimit is the default number of messages per query
	// when no limit is specified. Capped to MaxQueryLimit.
	// Default is 20.
	DefaultQueryLimit int

	// MaxConcurrentSends is the maximum number of concurrent send operations.
	// Default is 10.
	MaxConcurrentSends int

	// ShutdownTimeout is the maximum time to wait for in-flight operations
	// during graceful shutdown. Minimum is 1 second.
	// Default is 30 seconds.
	ShutdownTimeout time.Duration

	// DefaultTTL is the default per-message time-to-live. When a message is
	// sent without an explicit TTL, this default is applied.
	// Default is 0 (disabled — messages do not expire unless explicitly set).
	DefaultTTL time.Duration

	// MinTTL is the minimum allowed TTL. Messages with a shorter TTL are rejected.
	// Default is 1 minute.
	MinTTL time.Duration

	// MaxTTL is the maximum allowed TTL. Messages with a longer TTL are rejected.
	// Default is 0 (unlimited).
	MaxTTL time.Duration

	// MinScheduleDelay is the minimum allowed schedule delay from now.
	// Default is 0 (no minimum).
	MinScheduleDelay time.Duration

	// MaxScheduleDelay is the maximum allowed schedule delay from now.
	// Default is 0 (unlimited).
	MaxScheduleDelay time.Duration

	// StatsRefreshInterval is the TTL for cached mailbox stats.
	// Default is 30 seconds.
	StatsRefreshInterval time.Duration

	// ClaimInterval is how often the background goroutine scans for orphaned
	// messages in Redis consumer groups. Default is 30 seconds.
	ClaimInterval time.Duration

	// ClaimMinIdle is the minimum idle time before a message is eligible
	// for claiming from dead consumers. Default is 60 seconds.
	ClaimMinIdle time.Duration

	// ClaimBatchSize is the maximum number of orphaned messages to claim per cycle.
	// Default is 100.
	ClaimBatchSize int64

	// EventStreamMaxLen is the approximate maximum number of entries per
	// Redis event stream. Older entries are trimmed automatically on each publish.
	// Default is 10,000 (see DefaultEventStreamMaxLen).
	// Set to -1 to disable trimming (not recommended for production — streams grow without bound).
	EventStreamMaxLen int64
}

type Draft interface {
	DraftReader
	DraftComposer
	DraftPreparer
	DraftPublisher
	DraftMutator
}

type DraftClient interface {
	DraftLister
	MessageComposer
}

type DraftComposer interface {
	SetRecipients(recipientIDs ...string) DraftComposer
	SetDeliverTo(recipientIDs ...string) DraftComposer
	SetSubject(subject string) DraftComposer
	SetBody(body string) DraftComposer
	SetHeader(key, value string) DraftComposer
	SetMetadata(key string, value any) DraftComposer

	// SetTTL sets the message time-to-live. The message will be eligible for
	// automatic deletion after this duration from send time. A zero duration
	// clears any previously set TTL.
	SetTTL(d time.Duration) DraftComposer

	// SetScheduleAt sets the time at which the message becomes visible to
	// recipients. Before this time, the message is hidden from queries.
	// A zero time clears any previously set schedule.
	SetScheduleAt(t time.Time) DraftComposer

	// SetExternalID sets a caller-defined external identifier for correlation
	// with external systems (e.g. SMTP Message-ID). Stored indexed; use
	// store.ExternalIDIs to look up messages by this value.
	SetExternalID(id string) DraftComposer
}

type DraftList interface {
	DraftListReader
	DraftListMutator
}

type DraftListMutator interface {
	// Delete deletes all drafts in this list.
	Delete(ctx context.Context) (*BulkResult, error)
	// Send sends all drafts in this list.
	// Returns results for each draft (success or failure).
	// Use result.SentMessages() to access the sent messages.
	Send(ctx context.Context) (*DraftSendResult, error)
}

type DraftListReader interface {
	// All returns all drafts in this list.
	All() []Draft
	// Total returns the total count of drafts matching the query (not just this page).
	Total() int64
	// HasMore returns true if there are more drafts after this page.
	HasMore() bool
	// NextCursor returns the cursor for fetching the next page.
	NextCursor() string
}

type DraftLister interface {
	Drafts(ctx context.Context, opts store.ListOptions) (DraftList, error)
	GetDraft(ctx context.Context, id string) (Draft, error)
}

type DraftMutator interface {
	// Delete deletes the draft.
	// If the draft was saved, it's permanently deleted from storage.
	// If the draft was not saved, this is a no-op.
	Delete(ctx context.Context) error
}

type DraftPreparer interface {
	// AddAttachment adds an attachment after validating it.
	// Returns an error if the attachment is invalid or limits are exceeded.
	AddAttachment(attachment store.Attachment) error

	// ReplyTo sets this draft as a reply to another message.
	// It looks up the parent message to inherit the thread ID.
	// Returns an error if the parent message cannot be found or accessed.
	ReplyTo(ctx context.Context, messageID string) error

	// Forward prepares this draft as a forward of another message.
	// Copies subject (with "Fwd:" prefix), body, and attachments from the original.
	// Returns an error if the original message cannot be found or accessed.
	Forward(ctx context.Context, messageID string) error
}

type DraftPublisher interface {
	// Send validates fully and sends the draft.
	// Requires: at least one recipient and a non-empty subject.
	// Creates recipient copies and moves sender's copy to sent folder.
	// Returns ErrEmptyRecipients if no recipients, ErrEmptySubject if no subject.
	Send(ctx context.Context) (Message, error)

	// Save saves the draft without sending.
	// Allows incomplete drafts (empty recipients, empty subject) for later editing.
	// Validates: body size, metadata size, attachment limits.
	// The draft can be retrieved later via Drafts() and completed.
	Save(ctx context.Context) (Draft, error)
}

type DraftReader interface {
	ID() string
	OwnerID() string
	Subject() string
	Body() string
	RecipientIDs() []string
	DeliverTo() []string
	Headers() map[string]string
	Metadata() map[string]any
	Attachments() []store.Attachment
	ThreadID() string
	ReplyToID() string
	ExternalID() string
}

type DraftSendResult struct {
	*BulkResult
	// contains filtered or unexported fields
}

type EnforceQuotasResult struct {
	// UsersChecked is the number of users whose quotas were evaluated.
	UsersChecked int
	// UsersOverQuota is the number of users found over their quota limit.
	UsersOverQuota int
	// MessagesDeleted is the total number of messages deleted across all users.
	MessagesDeleted int
	// Interrupted indicates if the enforcement was stopped early (e.g., context cancelled).
	Interrupted bool
}

type EventPublishError struct {
	Event     string // The event name (e.g., "MessageSent", "MessageRead")
	MessageID string // The message ID the event was for
	Err       error  // The underlying publish error
}

type EventPublishFailureFunc func(eventName string, err error)

type Flags struct {
	Read     *bool // nil = no change, true = mark read, false = mark unread
	Archived *bool // nil = no change, true = archive, false = unarchive
}

type FolderInfo struct {
	// ID is the folder identifier (e.g., "__inbox", "custom-folder").
	ID string
	// Name is the display name for the folder.
	Name string
	// IsSystem indicates if this is a system folder (starts with "__").
	IsSystem bool
	// MessageCount is the total number of messages in the folder.
	MessageCount int64
	// UnreadCount is the number of unread messages in the folder.
	UnreadCount int64
}

type FolderReader interface {
	ListFolders(ctx context.Context) ([]FolderInfo, error)
}

type ListOptions = store.ListOptions

type Mailbox interface {
	UserID() string
	MessageClient
	DraftClient
	StorageClient
	MailboxMutator
	MessageSender
	BulkOperator
	AttachmentResolver
	StatsReader
}

type MailboxMutator interface {
	UpdateFlags(ctx context.Context, messageID string, flags Flags) error
	MoveToFolder(ctx context.Context, messageID string, folderID string, opts ...store.MoveOption) error
	Delete(ctx context.Context, messageID string) error
	Restore(ctx context.Context, messageID string) error
	PermanentlyDelete(ctx context.Context, messageID string) error
	AddTag(ctx context.Context, messageID string, tagID string) error
	RemoveTag(ctx context.Context, messageID string, tagID string) error
	// MarkAllRead marks all unread messages in a folder as read.
	// Uses store.BulkReadMarker for a single database operation when available,
	// falling back to individual MarkRead calls otherwise.
	// Returns the number of messages that were marked as read.
	MarkAllRead(ctx context.Context, folderID string) (int64, error)

	// UpdateByFilter marks messages matching filters as read/unread.
	UpdateByFilter(ctx context.Context, filters []store.Filter, flags Flags) (int64, error)
	// MoveByFilter moves messages matching filters to the given folder.
	MoveByFilter(ctx context.Context, filters []store.Filter, folderID string) (int64, error)
	// DeleteByFilter soft-deletes messages matching filters (moves to trash).
	DeleteByFilter(ctx context.Context, filters []store.Filter) (int64, error)
	// TagByFilter adds a tag to messages matching filters.
	TagByFilter(ctx context.Context, filters []store.Filter, tagID string) (int64, error)
	// UntagByFilter removes a tag from messages matching filters.
	UntagByFilter(ctx context.Context, filters []store.Filter, tagID string) (int64, error)
}

type MarkAllReadEvent struct {
	UserID   string    `json:"user_id"`
	FolderID string    `json:"folder_id"`
	Count    int64     `json:"count"`
	MarkedAt time.Time `json:"marked_at"`
}

type Message interface {
	store.Message
	MessageMutator
}

type MessageClient interface {
	MessageReader
	MessageLister
	MessageSearcher
	MessageStreamer
	ThreadReader
}

type MessageComposer interface {
	Compose() (Draft, error)
}

type MessageDeletedEvent struct {
	MessageID string    `json:"message_id"`
	UserID    string    `json:"user_id"`
	FolderID  string    `json:"folder_id"`
	WasUnread bool      `json:"was_unread"`
	DeletedAt time.Time `json:"deleted_at"`
}

type MessageIterator interface {
	// Next advances to the next message.
	// Returns (true, nil) if there is a message available.
	// Returns (false, nil) if iteration is done (no more messages).
	// Returns (false, error) if an error occurred (e.g., service disconnected, context cancelled).
	// Must be called before accessing Message().
	Next(ctx context.Context) (bool, error)

	// Message returns the current message with full mutation capabilities.
	// Must be called after a successful Next() call that returned (true, nil).
	// Returns ErrIteratorOutOfBounds if called before Next() or after iteration ends.
	Message() (Message, error)
}

type MessageLimits struct {
	MaxSubjectLength     int
	MaxBodySize          int
	MaxAttachmentSize    int64
	MaxAttachmentCount   int
	MaxRecipientCount    int
	MaxMetadataSize      int
	MaxMetadataKeys      int
	MaxHeaderCount       int
	MaxHeaderKeyLength   int
	MaxHeaderValueLength int
	MaxHeadersTotalSize  int
}

type MessageList interface {
	MessageListReader
	MessageListMutator
}

type MessageListMutator interface {
	// MarkRead marks all messages in this list as read.
	MarkRead(ctx context.Context) (*BulkResult, error)
	// MarkUnread marks all messages in this list as unread.
	MarkUnread(ctx context.Context) (*BulkResult, error)
	// Move moves all messages in this list to the specified folder.
	Move(ctx context.Context, folderID string, opts ...store.MoveOption) (*BulkResult, error)
	// Delete moves all messages in this list to trash.
	Delete(ctx context.Context) (*BulkResult, error)
	// AddTag adds a tag to all messages in this list.
	AddTag(ctx context.Context, tagID string) (*BulkResult, error)
	// RemoveTag removes a tag from all messages in this list.
	RemoveTag(ctx context.Context, tagID string) (*BulkResult, error)
}

type MessageListReader interface {
	// All returns all messages in this list.
	All() []Message
	// Total returns the total count of messages matching the query (not just this page).
	Total() int64
	// HasMore returns true if there are more messages after this page.
	HasMore() bool
	// NextCursor returns the cursor for fetching the next page.
	NextCursor() string
}

type MessageLister interface {
	Folder(ctx context.Context, folderID string, opts store.ListOptions) (MessageList, error)
}

type MessageMovedEvent struct {
	MessageID    string    `json:"message_id"`
	UserID       string    `json:"user_id"`
	FromFolderID string    `json:"from_folder_id"`
	ToFolderID   string    `json:"to_folder_id"`
	WasUnread    bool      `json:"was_unread"`
	MovedAt      time.Time `json:"moved_at"`
}

type MessageMutator interface {
	// Update updates the message flags (read, archived status).
	// Use MarkRead(), MarkUnread(), MarkArchived(), MarkUnarchived() helpers.
	Update(ctx context.Context, flags Flags) error

	// Move moves the message to a folder.
	// When called with store.FromFolder, the move is conditional.
	Move(ctx context.Context, folderID string, opts ...store.MoveOption) error

	// Delete moves the message to trash.
	Delete(ctx context.Context) error

	// Restore restores the message from trash.
	Restore(ctx context.Context) error

	// PermanentlyDelete permanently deletes the message from trash.
	PermanentlyDelete(ctx context.Context) error

	// AddTag adds a tag to the message.
	AddTag(ctx context.Context, tagID string) error

	// RemoveTag removes a tag from the message.
	RemoveTag(ctx context.Context, tagID string) error
}

type MessageReadEvent struct {
	MessageID string    `json:"message_id"`
	UserID    string    `json:"user_id"`
	FolderID  string    `json:"folder_id"`
	ReadAt    time.Time `json:"read_at"`
}

type MessageReader interface {
	Get(ctx context.Context, messageID string) (Message, error)
}

type MessageReceivedEvent struct {
	MessageID   string    `json:"message_id"`
	RecipientID string    `json:"recipient_id"`
	SenderID    string    `json:"sender_id"`
	Subject     string    `json:"subject"`
	ReceivedAt  time.Time `json:"received_at"`
}

type MessageSearcher interface {
	Search(ctx context.Context, query SearchQuery) (MessageList, error)
}

type MessageSender interface {
	SendMessage(ctx context.Context, req SendRequest) (Message, error)
}

type MessageSentEvent struct {
	MessageID    string    `json:"message_id"`
	SenderID     string    `json:"sender_id"`
	RecipientIDs []string  `json:"recipient_ids"`
	Subject      string    `json:"subject"`
	SentAt       time.Time `json:"sent_at"`
}

type MessageStreamer interface {
	// Stream returns an iterator for messages matching the given filters.
	// The owner filter and not-deleted filter are automatically added.
	Stream(ctx context.Context, filters []store.Filter, opts StreamOptions) (MessageIterator, error)
	// StreamSearch returns an iterator for search results.
	StreamSearch(ctx context.Context, query SearchQuery, opts StreamOptions) (MessageIterator, error)
}

type OperationResult struct {
	// ID is the identifier of the item that was processed.
	ID string
	// Success indicates whether the operation succeeded.
	Success bool
	// Error contains the error if the operation failed (nil if successful).
	Error error
}

type Option func(*options)

type PartialDeliveryError struct {
	// MessageID is the sender's message ID.
	MessageID string
	// DeliveredTo contains recipient IDs that received the message.
	DeliveredTo []string
	// FailedRecipients maps recipient IDs to their delivery errors.
	FailedRecipients map[string]error
}

type Plugin interface {
	// Name returns the plugin identifier.
	Name() string
	// Init initializes the plugin. Called when service connects.
	Init(ctx context.Context) error
	// Close cleans up plugin resources. Called when service closes.
	Close(ctx context.Context) error
}

type PluginError struct {
	Plugin string
	Op     string
	Err    error
}

type QuotaAction int

type QuotaExceededError struct {
	UserID       string
	CurrentCount int64
	MaxMessages  int64
}

type QuotaPolicy struct {
	// MaxMessages is the maximum number of messages allowed in a user's mailbox.
	// Set to 0 for unlimited (no quota enforcement).
	MaxMessages int64

	// ExceedAction determines what happens when the quota is exceeded.
	// Default is QuotaActionReject.
	ExceedAction QuotaAction

	// DeleteOlderThan is the minimum age of messages eligible for deletion
	// when ExceedAction is QuotaActionDeleteOldest. Messages younger than
	// this duration are never deleted by quota enforcement.
	// Must be positive when ExceedAction is QuotaActionDeleteOldest;
	// enforcement is skipped if zero to prevent accidental deletion of recent messages.
	DeleteOlderThan time.Duration
}

type QuotaProvider interface {
	// GetQuota returns the quota policy for the given user.
	// Return a nil policy or a policy with MaxMessages=0 for unlimited quota.
	GetQuota(ctx context.Context, userID string) (*QuotaPolicy, error)
}

type QuotaUserLister interface {
	// ListUsers returns user IDs that should be checked for quota enforcement.
	ListUsers(ctx context.Context) ([]string, error)
}

type Recipient struct {
	// UserID is the unique user identifier.
	UserID string
	// Name is the display name of the user.
	Name string
	// Email is the user's email address (optional).
	Email string
}

type RecipientResolver interface {
	// Resolve returns recipient information for a single user ID.
	// Returns ErrRecipientNotFound if the user ID is unknown.
	Resolve(ctx context.Context, userID string) (*Recipient, error)

	// ResolveBatch returns recipient information for multiple user IDs.
	// Returns results in the same order as input. Unknown IDs have nil entries.
	ResolveBatch(ctx context.Context, userIDs []string) ([]*Recipient, error)
}

type Registrar interface {
	// Register announces this mailbox instance and returns the mailbox ID
	// assigned by the registrar. Returning an error aborts Connect.
	Register(ctx context.Context) (mailboxID string, err error)
}

type Router interface {
	// Route returns the Mailbox that holds messages for the given user.
	// Returns an error if the user is unknown or the lookup fails.
	Route(ctx context.Context, userID string) (Mailbox, error)
}

type SearchQuery = store.SearchQuery

type SendHook interface {
	Plugin
	// BeforeSend is called before a draft is sent. Return an error to abort.
	// Use this for spam filtering, rate limiting, or content validation.
	BeforeSend(ctx context.Context, userID string, draft store.DraftMessage) error
	// AfterSend is called after a message is successfully sent.
	// Return an error to signal post-send failures (e.g., notification errors).
	// Note: The message is already sent and cannot be rolled back.
	AfterSend(ctx context.Context, userID string, msg store.Message) error
}

type SendRequest struct {
	RecipientIDs  []string
	Subject       string
	Body          string
	Headers       map[string]string
	Metadata      map[string]any
	Attachments   []store.Attachment
	AttachmentIDs []string
	ThreadID      string
	ReplyToID     string
	ExternalID    string // caller-defined external identifier (e.g. SMTP Message-ID); stored indexed

	// DeliverTo optionally restricts which recipients receive inbox copies
	// on this instance. The message's RecipientIDs stores the full recipient
	// list for display. When empty, delivery targets default to RecipientIDs.
	DeliverTo []string

	// TTL is an optional message time-to-live. When set, the message will be
	// eligible for automatic deletion after this duration from send time.
	// Zero means no per-message TTL (the service default TTL may still apply).
	TTL time.Duration

	// ScheduleAt is an optional delivery schedule. When set, the message is
	// hidden from recipient queries until this UTC time.
	// Nil means the message is immediately available.
	ScheduleAt *time.Time
}

type Service interface {
	// IsConnected returns true if the service is connected and ready.
	IsConnected() bool

	// Connect establishes connections to storage backends and starts
	// background maintenance goroutines (if configured via Config).
	Connect(ctx context.Context) error
	// Close stops background goroutines, waits for in-flight operations,
	// and closes all connections.
	Close(ctx context.Context) error
	// Client returns a mailbox client for the given user.
	// The returned client shares the service's connections.
	// Connection state is checked lazily on each operation; if the service
	// is not connected, operations will return ErrNotConnected.
	Client(userID string) Mailbox
	// CleanupTrash permanently deletes messages that have been in trash
	// longer than the configured retention period. Called automatically
	// when Config.TrashCleanupInterval is set; can also be called manually.
	CleanupTrash(ctx context.Context) (*CleanupTrashResult, error)
	// CleanupExpiredMessages permanently deletes messages older than the
	// configured message retention period (based on created_at).
	// Returns a zero result if message retention is not configured.
	// Called automatically when Config.ExpiredMessageCleanupInterval is set.
	CleanupExpiredMessages(ctx context.Context) (*CleanupExpiredMessagesResult, error)
	// EnforceQuotas evaluates quotas for the given users and applies enforcement
	// actions. Only users with QuotaActionDeleteOldest policies are processed;
	// QuotaActionReject is enforced at delivery time. Called automatically when
	// Config.QuotaEnforcementInterval and Config.QuotaUserLister are set.
	EnforceQuotas(ctx context.Context, userIDs []string) (*EnforceQuotasResult, error)
	// RunQuotaEnforcement lists all users via the configured QuotaUserLister and
	// calls EnforceQuotas for them. Returns ErrQuotaUserListerNotConfigured when no
	// lister is set. Prefer this over EnforceQuotas in admin/on-demand contexts
	// because it does not accept user IDs from external callers.
	RunQuotaEnforcement(ctx context.Context) (*EnforceQuotasResult, error)

	// Events returns per-service event instances for subscribing and publishing.
	// Each service has its own events bound to its own event bus, enabling
	// independent event routing and parallel testing.
	Events() *ServiceEvents

	// Notifications returns a real-time notification stream for the given user.
	// Requires WithNotifier to be configured. Returns ErrNotifierNotConfigured otherwise.
	// lastEventID enables backfill of missed events ("" for new events only).
	// The caller must close the returned Stream when done.
	Notifications(ctx context.Context, userID string, lastEventID string) (notify.Stream, error)

	// MailboxID returns the mailbox ID assigned by the Registrar during Connect.
	// Returns an empty string when no registrar was configured or Connect has not
	// completed successfully.
	MailboxID() string

	// ThreadParticipants returns the distinct user IDs of all non-deleted participants
	// in the given thread. A participant is any user who has a non-trash copy of a
	// message with that thread_id (sender or recipient).
	//
	// This is a cross-owner query used by external delivery systems (e.g., SMTP gateways)
	// that know the thread_id but not the individual recipient IDs:
	//
	//	participants, err := svc.ThreadParticipants(ctx, threadID)
	//	if err != nil { ... }
	//	_, err = svc.Client(senderID).SendMessage(ctx, mailbox.SendRequest{
	//	    RecipientIDs: participants,
	//	    ThreadID:     threadID,
	//	    Subject:      subject,
	//	    Body:         body,
	//	})
	//
	// Returns store.ErrNotFound when no messages exist for the given thread_id.
	ThreadParticipants(ctx context.Context, threadID string) ([]string, error)
}

type ServiceEvents struct {
	// MessageSent is published when a message is sent.
	MessageSent event.Event[MessageSentEvent]

	// MessageReceived is published when a message is delivered to a recipient.
	MessageReceived event.Event[MessageReceivedEvent]

	// MessageRead is published when a message is marked as read.
	MessageRead event.Event[MessageReadEvent]

	// MessageDeleted is published when a message is permanently deleted.
	MessageDeleted event.Event[MessageDeletedEvent]

	// MessageMoved is published when a message is moved between folders.
	MessageMoved event.Event[MessageMovedEvent]

	// MarkAllRead is published when all messages in a folder are marked as read.
	MarkAllRead event.Event[MarkAllReadEvent]
}

type SortOrder = store.SortOrder

type StaticQuotaProvider struct {
	Policy QuotaPolicy
}

type StatsCache interface {
	// Get retrieves cached stats for a user. Returns nil, nil when not found.
	Get(ctx context.Context, ownerID string) (*store.MailboxStats, error)

	// Set stores stats for a user with the given TTL.
	Set(ctx context.Context, ownerID string, stats *store.MailboxStats, ttl time.Duration) error

	// IncrBy atomically increments a named counter for a user.
	// field is one of the well-known keys defined in the statscache package.
	IncrBy(ctx context.Context, ownerID string, field string, delta int64) error

	// Invalidate removes cached stats for a user, forcing the next read
	// to fall through to the store.
	Invalidate(ctx context.Context, ownerID string) error
}

type StatsReader interface {
	// Stats returns aggregate statistics for this user's mailbox.
	// Results are cached with event-driven incremental updates and periodic TTL refresh.
	Stats(ctx context.Context) (*store.MailboxStats, error)
	// UnreadCount returns the total unread message count for this user.
	// This is a convenience method equivalent to calling Stats() and reading UnreadCount.
	UnreadCount(ctx context.Context) (int64, error)
}

type StorageClient interface {
	FolderReader
	AttachmentLoader
}

type StreamOptions struct {
	// BatchSize is the number of messages fetched per batch.
	// Larger batches reduce round-trips but use more memory.
	// Default: 100
	BatchSize int
}

type ThreadReader interface {
	// GetThread returns all messages in a thread, ordered by creation time.
	GetThread(ctx context.Context, threadID string, opts store.ListOptions) (MessageList, error)
	// GetReplies returns all direct replies to a message.
	GetReplies(ctx context.Context, messageID string, opts store.ListOptions) (MessageList, error)
}

type User interface {
	// ID returns the unique identifier for this principal (typically their email address).
	ID() string
	FirstName() string
	LastName() string
	Email() string
	// Type classifies the principal: "human", "agent", "service", or "" (unset).
	Type() string
	// PublicKey returns the principal's Ed25519 public key, base64-encoded.
	// Empty for human users; set for agents and services that sign their payloads.
	PublicKey() string
	// Capabilities returns routing and capability metadata: skills, endpoint, region, model, etc.
	// Callers must not mutate the returned map.
	Capabilities() map[string]string
}

type UserResolver interface {
	ResolveUser(ctx context.Context, userID string) (User, error)
}

type ValidationError struct {
	Field   string // The field that failed validation
	Message string // Human-readable error message
}