query

type AccountInfo struct {
	ID          int64
	SourceType  string
	Identifier  string // email address
	DisplayName string
}

type Address struct {
	Email string
	Name  string
}

type AggregateOptions struct {
	// Account filter
	SourceID *int64 // nil means all accounts

	// Date range
	After  *time.Time
	Before *time.Time

	// Sorting
	SortField     SortField
	SortDirection SortDirection

	// Limit results (0 means default, typically 100)
	Limit int

	// Time-specific options
	TimeGranularity TimeGranularity

	// Filter options
	WithAttachmentsOnly bool

	// Text search filter (filters aggregates to only include messages matching search)
	SearchQuery string
}

type AggregateRow struct {
	Key             string // email, domain, label name, or time period
	Count           int64  // number of messages
	TotalSize       int64  // sum of size_estimate in bytes
	AttachmentSize  int64  // sum of attachment sizes in bytes
	AttachmentCount int64  // number of attachments
	TotalUnique     int64  // total unique keys (same for all rows, computed via COUNT(*) OVER())
}

type AttachmentInfo struct {
	ID          int64
	Filename    string
	MimeType    string
	Size        int64
	ContentHash string
}

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

type DuckDBOptions struct {
	// DisableSQLiteScanner prevents loading the sqlite_scanner extension even
	// on platforms where it would normally be available. This forces all SQLite
	// queries to route through sqliteEngine, matching the Windows code path.
	// Useful for testing the non-scanner code path on Linux/macOS.
	DisableSQLiteScanner bool
}

type Engine interface {
	// Aggregate performs grouping based on the provided ViewType (Sender, Domain, etc.)
	Aggregate(ctx context.Context, groupBy ViewType, opts AggregateOptions) ([]AggregateRow, error)

	// SubAggregate performs aggregation on a filtered subset of messages.
	// This is used for sub-grouping after drill-down, e.g., drilling into
	// "Sender: foo@example.com" and then sub-grouping by Recipients or Labels.
	// The filter specifies the parent context (sender, domain, etc.) and
	// groupBy specifies what dimension to aggregate by.
	SubAggregate(ctx context.Context, filter MessageFilter, groupBy ViewType, opts AggregateOptions) ([]AggregateRow, error)

	// Message queries
	ListMessages(ctx context.Context, filter MessageFilter) ([]MessageSummary, error)
	GetMessage(ctx context.Context, id int64) (*MessageDetail, error)
	GetMessageBySourceID(ctx context.Context, sourceMessageID string) (*MessageDetail, error)
	GetAttachment(ctx context.Context, id int64) (*AttachmentInfo, error)

	// Search - full-text search using FTS5 (includes message body)
	Search(ctx context.Context, query *search.Query, limit, offset int) ([]MessageSummary, error)

	// SearchFast searches message metadata only (no body text).
	// This is much faster for large archives as it queries Parquet files directly.
	// Searches: subject, sender email/name (case-insensitive).
	// The filter parameter allows contextual search within a drill-down.
	SearchFast(ctx context.Context, query *search.Query, filter MessageFilter, limit, offset int) ([]MessageSummary, error)

	// SearchFastCount returns the total count of messages matching a search query.
	// This is used for pagination UI to show "N of M results".
	SearchFastCount(ctx context.Context, query *search.Query, filter MessageFilter) (int64, error)

	// SearchFastWithStats performs a fast metadata search and returns paginated
	// results, total count, and aggregate stats in a single operation. The DuckDB
	// implementation materializes matching IDs into a temp table with one Parquet
	// scan, then reuses it for count, pagination, and stats — replacing 3-4
	// separate scans with one.
	//
	// queryStr is the raw search string (needed for stats; search.Query doesn't store it).
	// statsGroupBy controls which view's key columns are used for stats search filtering.
	SearchFastWithStats(ctx context.Context, query *search.Query, queryStr string,
		filter MessageFilter, statsGroupBy ViewType, limit, offset int) (*SearchFastResult, error)

	// GetGmailIDsByFilter returns Gmail message IDs (source_message_id) matching a filter.
	// This is useful for batch operations like staging messages for deletion.
	GetGmailIDsByFilter(ctx context.Context, filter MessageFilter) ([]string, error)

	// Account queries
	ListAccounts(ctx context.Context) ([]AccountInfo, error)

	// Stats
	GetTotalStats(ctx context.Context, opts StatsOptions) (*TotalStats, error)

	// Close releases any resources held by the engine.
	Close() error
}

type MessageDetail struct {
	ID              int64
	SourceMessageID string
	ConversationID  int64
	Subject         string
	Snippet         string
	SentAt          time.Time
	ReceivedAt      *time.Time
	SizeEstimate    int64
	HasAttachments  bool

	// Participants
	From []Address
	To   []Address
	Cc   []Address
	Bcc  []Address

	// Content
	BodyText string
	BodyHTML string

	// Metadata
	Labels      []string
	Attachments []AttachmentInfo
}

type MessageFilter struct {
	// Filter by aggregate key
	Sender        string // filter by sender email
	SenderName    string // filter by sender display name (COALESCE(display_name, email))
	Recipient     string // filter by recipient email
	RecipientName string // filter by recipient display name (COALESCE(display_name, email))
	Domain        string // filter by sender domain
	Label         string // filter by label name

	// Filter by conversation (thread)
	ConversationID *int64 // filter by conversation/thread ID

	// EmptyValueTargets specifies which dimensions to filter for NULL/empty values.
	// When empty (default): empty filter strings mean "no filter" (return all).
	// When a ViewType is present in the map: that dimension filters for NULL/empty values,
	// enabling drilldown into empty-bucket aggregates (e.g., messages with no sender).
	// Multiple dimensions can be set when drilling from one empty bucket into another.
	EmptyValueTargets map[ViewType]bool

	// Time range
	TimeRange TimeRange

	// Account filter
	SourceID *int64 // nil means all accounts

	// Date range
	After  *time.Time
	Before *time.Time

	// Content filter
	WithAttachmentsOnly bool // only return messages with attachments

	// Pagination
	Pagination Pagination

	// Sorting
	Sorting MessageSorting
}

type MessageSortField int

type MessageSorting struct {
	Field     MessageSortField
	Direction SortDirection
}

type MessageSummary struct {
	ID              int64
	SourceMessageID string
	ConversationID  int64
	Subject         string
	Snippet         string
	FromEmail       string
	FromName        string
	SentAt          time.Time
	SizeEstimate    int64
	HasAttachments  bool
	AttachmentCount int
	Labels          []string
	DeletedAt       *time.Time // When message was deleted from server (nil if not deleted)
}

type Pagination struct {
	Limit  int
	Offset int
}

type ParquetSyncState struct {
	LastMessageID int64     `json:"last_message_id"`
	LastSyncAt    time.Time `json:"last_sync_at,omitempty"`
}

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

type SearchFastResult struct {
	Messages   []MessageSummary
	TotalCount int64
	Stats      *TotalStats
}

type SortDirection int

type SortField int

type StatsOptions struct {
	SourceID            *int64   // nil means all accounts
	WithAttachmentsOnly bool     // only count messages with attachments
	SearchQuery         string   // when set, stats reflect only messages matching this search
	GroupBy             ViewType // when set, search filters on this view's key columns instead of subject+sender
}

type TimeGranularity int

type TimeRange struct {
	Period      string // e.g., "2024", "2024-01", "2024-01-15"
	Granularity TimeGranularity
}

type TotalStats struct {
	MessageCount    int64
	TotalSize       int64
	AttachmentCount int64
	AttachmentSize  int64
	LabelCount      int64
	AccountCount    int64
}

type ViewType int