store

type Attachment interface {
	GetID() string
	GetFilename() string
	GetContentType() string
	GetSize() int64
	GetURI() string
	GetCreatedAt() time.Time
}

type AttachmentCreate struct {
	Filename    string
	ContentType string
	Size        int64
	URI         string
	Hash        string
}

type AttachmentFileStore interface {
	// Upload stores content and returns a URI for later retrieval.
	Upload(ctx context.Context, filename, contentType string, content io.Reader) (uri string, err error)

	// Load returns a reader for the attachment content.
	// Caller is responsible for closing the reader.
	Load(ctx context.Context, uri string) (io.ReadCloser, error)

	// Delete removes the attachment file from storage.
	Delete(ctx context.Context, uri string) error
}

type AttachmentManager interface {
	// Upload uploads a file and creates metadata with the given hash.
	// If an attachment with the same hash exists, returns existing metadata
	// without uploading (deduplication).
	Upload(ctx context.Context, filename, contentType, hash string, content io.Reader) (AttachmentMetadata, error)

	// Load returns a reader for the attachment content.
	Load(ctx context.Context, id string) (io.ReadCloser, error)

	// GetMetadata retrieves attachment metadata by ID.
	// Returns ErrNotFound if the attachment doesn't exist.
	GetMetadata(ctx context.Context, id string) (AttachmentMetadata, error)

	// AddRef increments the reference count for an attachment.
	// Called when a message with this attachment is created.
	AddRef(ctx context.Context, id string) error

	// RemoveRef decrements the reference count for an attachment.
	// If the count reaches 0, the file and metadata are deleted.
	// Called when a message is permanently deleted.
	RemoveRef(ctx context.Context, id string) error
}

type AttachmentMetadata interface {
	Attachment

	// GetHash returns the content hash for deduplication.
	GetHash() string

	// GetRefCount returns the number of messages referencing this attachment.
	GetRefCount() int
}

type AttachmentMetadataStore interface {
	// Create stores new attachment metadata with initial ref count of 0.
	// Returns the created metadata with generated ID and timestamps.
	Create(ctx context.Context, data AttachmentCreate) (AttachmentMetadata, error)

	// Get retrieves attachment metadata by ID.
	Get(ctx context.Context, id string) (AttachmentMetadata, error)

	// GetByHash finds attachment by content hash for deduplication.
	// Returns ErrNotFound if no attachment with the hash exists.
	GetByHash(ctx context.Context, hash string) (AttachmentMetadata, error)

	// IncrementRef atomically increments the reference count.
	// Called when a message with this attachment is created.
	IncrementRef(ctx context.Context, id string) error

	// DecrementRefAndDeleteIfZero atomically decrements the reference count
	// and deletes the metadata if the count reaches zero.
	// Returns (true, uri) if deleted, (false, "") if not deleted.
	// This MUST be atomic to prevent race conditions where two concurrent
	// releases both see count=1 and both try to delete.
	//
	// For MongoDB: Use findOneAndUpdate with $inc and return the document,
	//              then delete in same transaction if count <= 0.
	// For PostgreSQL: Use DELETE ... WHERE id = $1 AND ref_count <= 1 RETURNING uri,
	//                 or UPDATE + DELETE in a transaction.
	DecrementRefAndDeleteIfZero(ctx context.Context, id string) (deleted bool, uri string, err error)

	// Delete removes attachment metadata.
	// Should only be called when ref count is 0.
	Delete(ctx context.Context, id string) error
}

type BulkReadMarker interface {
	// MarkAllRead marks all unread non-draft messages in a folder as read.
	// Returns the number of messages that were marked as read.
	MarkAllRead(ctx context.Context, ownerID string, folderID string) (int64, error)
}

type BulkUpdater interface {
	MarkReadByFilter(ctx context.Context, ownerID string, filters []Filter, read bool) (int64, error)
	MoveByFilter(ctx context.Context, ownerID string, filters []Filter, folderID string) (int64, error)
	DeleteByFilter(ctx context.Context, ownerID string, filters []Filter) (int64, error)
	AddTagByFilter(ctx context.Context, ownerID string, filters []Filter, tagID string) (int64, error)
	RemoveTagByFilter(ctx context.Context, ownerID string, filters []Filter, tagID string) (int64, error)
}

type DraftList struct {
	Drafts     []DraftMessage
	Total      int64
	HasMore    bool
	NextCursor string
}

type DraftMessage interface {
	MessageReader

	// Write operations (fluent API)
	SetSubject(subject string) DraftMessage
	SetBody(body string) DraftMessage
	SetRecipients(recipientIDs ...string) DraftMessage
	SetHeader(key, value string) DraftMessage
	SetMetadata(key string, value any) DraftMessage
	AddAttachment(attachment Attachment) DraftMessage

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

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

	// SetThreadID sets the conversation thread ID this draft belongs to.
	// An empty string clears any previously set thread ID.
	SetThreadID(id string) DraftMessage

	// SetReplyToID sets the ID of the message this draft replies to.
	// An empty string clears any previously set reply target.
	SetReplyToID(id string) DraftMessage

	// SetExternalID sets a caller-defined external identifier for correlation
	// with external systems (e.g. an SMTP Message-ID).
	SetExternalID(id string) DraftMessage
}

type DraftStore interface {
	// NewDraft creates a new empty draft for the given owner.
	// This is the only way to create a DraftMessage.
	NewDraft(ownerID string) DraftMessage

	// GetDraft retrieves a draft by ID.
	// Returns ErrNotFound if the draft doesn't exist.
	GetDraft(ctx context.Context, id string) (DraftMessage, error)

	// SaveDraft persists a draft. If the draft has no ID, a new one is assigned.
	// Returns the saved draft (may have updated fields like ID, timestamps).
	SaveDraft(ctx context.Context, draft DraftMessage) (DraftMessage, error)

	// DeleteDraft permanently removes a draft.
	// Returns ErrNotFound if the draft doesn't exist.
	DeleteDraft(ctx context.Context, id string) error

	// ListDrafts returns all drafts for a user.
	ListDrafts(ctx context.Context, ownerID string, opts ListOptions) (*DraftList, error)
}

type EventOutboxProvider interface {
	// EventOutboxStore returns an event.OutboxStore backed by the same database.
	// Returns nil if outbox is not enabled.
	EventOutboxStore() event.OutboxStore
}

type Filter struct {
	// contains filtered or unexported fields
}

type FilterBuilder struct {
	// contains filtered or unexported fields
}

type FilterError struct {
	Key string
	Err error
}

type FindWithCounter interface {
	// FindWithCount retrieves messages matching the filters and returns
	// both the messages and the total count in a single operation.
	FindWithCount(ctx context.Context, filters []Filter, opts ListOptions) (*MessageList, int64, error)
}

type FolderCounter interface {
	// CountByFolders returns message counts and unread counts for the given folders.
	// The returned map is keyed by folder ID. Missing keys indicate zero counts.
	CountByFolders(ctx context.Context, ownerID string, folderIDs []string) (map[string]FolderCounts, error)
}

type FolderCounts struct {
	Total  int64
	Unread int64
}

type FolderLister interface {
	// ListDistinctFolders returns all distinct folder IDs for a user's non-deleted messages.
	// This is used to discover custom folders that are not system folders.
	ListDistinctFolders(ctx context.Context, ownerID string) ([]string, error)
}

type IdempotentCreateEntry struct {
	Data           MessageData
	IdempotencyKey string
}

type IdempotentCreateResult struct {
	Message Message
	Created bool  // true if newly created, false if existing
	Err     error // non-nil if this entry failed
}

type ListOptions struct {
	Limit      int
	Offset     int
	SortBy     string
	SortOrder  SortOrder
	StartAfter string // cursor-based pagination
}

type MailboxStats struct {
	// TotalMessages is the total number of non-draft messages.
	TotalMessages int64
	// UnreadCount is the total number of unread non-draft messages.
	UnreadCount int64
	// DraftCount is the total number of drafts.
	DraftCount int64
	// Folders contains per-folder message counts (non-draft messages only).
	// Keys are folder IDs (e.g., "__inbox", "__sent").
	Folders map[string]FolderCounts
}

type MaintenanceStore interface {
	// DeleteExpiredTrash atomically deletes all messages in trash older than cutoff.
	//
	// This operation is safe to call concurrently from multiple instances.
	// The database handles atomicity - if two instances call this simultaneously,
	// each message is deleted exactly once (one instance succeeds, the other
	// finds no matching documents).
	//
	// Implementation should use atomic bulk delete:
	//   - MongoDB: deleteMany({ folder: "__trash", trashedAt: { $lt: cutoff } })
	//   - PostgreSQL: DELETE FROM messages WHERE folder = '__trash' AND trashed_at < $1
	//
	// Returns the number of messages deleted and any error encountered.
	DeleteExpiredTrash(ctx context.Context, cutoff time.Time) (int64, error)

	// DeleteExpiredMessages atomically deletes all non-draft messages
	// whose created_at is older than cutoff, regardless of folder.
	//
	// This operation is safe to call concurrently from multiple instances.
	// The database handles atomicity.
	//
	// Returns the number of messages deleted and any error encountered.
	DeleteExpiredMessages(ctx context.Context, cutoff time.Time) (int64, error)

	// DeleteMessagesByIDs deletes the specified messages and returns the IDs
	// that were actually deleted. In a multi-instance environment, only the
	// instance that wins the delete for each message will see that ID in the
	// returned slice. This enables safe attachment ref release: only the winner
	// releases refs, preventing double-decrements.
	//
	// Messages that do not exist or were already deleted are silently skipped.
	DeleteMessagesByIDs(ctx context.Context, ids []string) ([]string, error)

	// DeleteTTLExpiredMessages atomically deletes all non-draft messages
	// whose expires_at is non-null and before the given time.
	//
	// This handles per-message TTL cleanup, as opposed to DeleteExpiredMessages
	// which handles global retention based on created_at.
	//
	// Returns the number of messages deleted and any error encountered.
	DeleteTTLExpiredMessages(ctx context.Context, now time.Time) (int64, error)
}

type Message interface {
	MessageReader

	GetStatus() MessageStatus
	GetIsRead() bool
	GetReadAt() *time.Time
	GetFolderID() string
	GetTags() []string
}

type MessageData struct {
	OwnerID      string
	SenderID     string
	RecipientIDs []string
	Subject      string
	Body         string
	Headers      map[string]string
	Metadata     map[string]any
	Status       MessageStatus
	FolderID     string
	Attachments  []Attachment
	Tags         []string
	ThreadID     string
	ReplyToID    string
	ExternalID   string // caller-defined external identifier (e.g. SMTP Message-ID); indexed

	// ExpiresAt is the UTC time after which this message is eligible for
	// automatic deletion via DeleteTTLExpiredMessages. Nil means no expiry.
	ExpiresAt *time.Time

	// AvailableAt is the UTC time before which this message is hidden from
	// queries. Nil means immediately available.
	AvailableAt *time.Time
}

type MessageList struct {
	Messages   []Message
	Total      int64
	HasMore    bool
	NextCursor string
}

type MessageReader interface {
	GetID() string
	GetOwnerID() string
	GetSenderID() string
	GetSubject() string
	GetBody() string
	GetRecipientIDs() []string
	GetHeaders() map[string]string
	GetMetadata() map[string]any
	GetAttachments() []Attachment
	GetCreatedAt() time.Time
	GetUpdatedAt() time.Time

	// GetExpiresAt returns the UTC time after which this message is eligible
	// for automatic deletion. Returns nil if the message has no TTL.
	GetExpiresAt() *time.Time

	// GetAvailableAt returns the UTC time before which this message is hidden
	// from queries. Returns nil if the message is immediately available.
	GetAvailableAt() *time.Time

	// GetThreadID returns the conversation thread ID, or "" if none.
	GetThreadID() string

	// GetReplyToID returns the ID of the message this one replies to, or "".
	GetReplyToID() string

	// GetExternalID returns the caller-defined external identifier, or "".
	GetExternalID() string
}

type MessageStatus string

type MessageStore interface {
	MessageStoreReader
	MessageStoreMutator
	MessageStoreCreator
}

type MessageStoreCreator interface {
	// CreateMessage creates a new message from the given data.
	// Used internally when sending a draft to create sender/recipient copies.
	CreateMessage(ctx context.Context, data MessageData) (Message, error)

	// CreateMessageIdempotent atomically creates a message or returns existing.
	//
	// This operation MUST be atomic at the database level using mechanisms like:
	//   - MongoDB: findOneAndUpdate with upsert
	//   - PostgreSQL: INSERT ... ON CONFLICT DO NOTHING RETURNING ...
	//
	// The idempotency key combined with owner ID forms a unique constraint.
	// If a message with the same (ownerID, idempotencyKey) exists, it is returned
	// without modification and created=false.
	//
	// This design eliminates the need for distributed locks when handling
	// duplicate requests (e.g., network retries, user double-clicks).
	//
	// Returns:
	//   - (message, true, nil): New message was created
	//   - (message, false, nil): Existing message was found and returned
	//   - (nil, false, error): Operation failed
	CreateMessageIdempotent(ctx context.Context, data MessageData, idempotencyKey string) (Message, bool, error)

	// CreateMessagesIdempotent creates multiple messages with idempotency keys.
	//
	// Each entry pairs a MessageData with an idempotency key. Messages whose
	// (ownerID, idempotencyKey) already exist are returned as-is (created=false).
	// New messages are inserted (created=true).
	//
	// Unlike CreateMessages, this is NOT necessarily atomic across the batch —
	// some may succeed while others find existing entries. This matches the
	// semantics needed for multi-recipient delivery with retry support.
	//
	// Returns a result per input entry in the same order.
	CreateMessagesIdempotent(ctx context.Context, entries []IdempotentCreateEntry) ([]IdempotentCreateResult, error)

	// CreateMessages creates multiple messages atomically in a single transaction.
	//
	// This operation MUST be atomic - either all messages are created or none are.
	// Implementations should use:
	//   - MongoDB: insertMany with ordered=true in a session/transaction
	//   - PostgreSQL: Single INSERT with multiple VALUES in a transaction
	//
	// This atomicity guarantee eliminates the need for distributed locks when
	// sending to multiple recipients. If the operation fails, callers know
	// that no partial state exists - they can safely retry the entire batch.
	//
	// Returns:
	//   - (messages, nil): All messages created successfully
	//   - (nil, error): Operation failed, no messages were created
	CreateMessages(ctx context.Context, data []MessageData) ([]Message, error)
}

type MessageStoreMutator interface {
	// MarkRead sets the read status of a message.
	MarkRead(ctx context.Context, id string, read bool) error

	// MoveToFolder moves a message to a different folder.
	//
	// When called without options, the move is unconditional (existing behavior).
	// When called with FromFolder, the move is conditional: it succeeds only if
	// the message is currently in the specified source folder. If the message
	// exists but is in a different folder, ErrFolderMismatch is returned.
	MoveToFolder(ctx context.Context, id string, folderID string, opts ...MoveOption) error

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

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

	// Delete soft-deletes a message (moves to trash).
	Delete(ctx context.Context, id string) error

	// HardDelete permanently removes a message.
	HardDelete(ctx context.Context, id string) error

	// Restore restores a soft-deleted message from trash.
	Restore(ctx context.Context, id string) error
}

type MessageStoreReader interface {
	// Get retrieves a message by ID.
	// Returns ErrNotFound if the message doesn't exist.
	Get(ctx context.Context, id string) (Message, error)

	// Find retrieves messages matching the filters.
	Find(ctx context.Context, filters []Filter, opts ListOptions) (*MessageList, error)

	// Count returns the count of messages matching the filters.
	Count(ctx context.Context, filters []Filter) (int64, error)

	// Search performs full-text search on messages.
	Search(ctx context.Context, query SearchQuery) (*MessageList, error)
}

type MoveOption func(*moveOptions)

type OutboxPersister interface {
	// OutboxEnabled returns whether the outbox is configured.
	OutboxEnabled() bool

	// WithOutboxCtx wraps fn in a database transaction. The context passed
	// to fn has both the store's transaction and event.WithOutboxTx set,
	// so store methods use the same tx and Event.Publish() routes to outbox.
	// If outbox is disabled, calls fn directly with zero overhead.
	WithOutboxCtx(ctx context.Context, fn func(ctx context.Context) error) error
}

type SearchQuery struct {
	OwnerID string      // required: owner of the messages
	Query   string      // text search query
	Fields  []string    // fields to search in (subject, body)
	Tags    []string    // filter by tags (messages must have all specified tags)
	Filters []Filter    // additional filters
	Options ListOptions // pagination and sorting
}

type SortOrder int

type StatsStore interface {
	// MailboxStats returns aggregate statistics for a user's mailbox.
	// This should be implemented as a single efficient query (e.g., MongoDB $facet,
	// PostgreSQL conditional aggregation) rather than multiple round-trips.
	MailboxStats(ctx context.Context, ownerID string) (*MailboxStats, error)
}

type Store interface {
	// Lifecycle
	Connect(ctx context.Context) error
	Close(ctx context.Context) error

	// Draft operations - drafts are mutable messages being composed
	DraftStore

	// Message operations - messages are read-only sent/received items
	MessageStore

	// Maintenance operations - for background cleanup tasks
	MaintenanceStore

	// Stats operations - aggregate mailbox statistics
	StatsStore
}

type ThreadParticipantLister interface {
	// ThreadParticipants returns the distinct owner IDs of all non-deleted,
	// non-draft messages with the given thread_id. The result is unordered.
	// Returns ErrNotFound when no messages exist for the given thread_id.
	ThreadParticipants(ctx context.Context, threadID string) ([]string, error)
}