email

type Attachment struct {
	// Filename is the name of the file as it will appear in the email
	Filename string

	// Content is the file content as bytes
	Content []byte

	// MimeType is the MIME type of the file (optional).
	// If empty, it will be automatically detected based on the filename.
	MimeType string
}

type AttachmentMeta struct {
	// ID is the provider attachment identifier (used to fetch content).
	ID string

	// Filename is the attachment's file name.
	Filename string

	// MimeType is the attachment's content type.
	MimeType string

	// Size is the attachment size in bytes (0 if unknown).
	Size int64
}

type CalendarProvider interface {
	// ListEvents returns events in the option's date range, soonest first.
	ListEvents(ctx context.Context, opts EventListOptions) ([]Event, error)

	// ReadEvent returns one event by id, including body and attendees.
	ReadEvent(ctx context.Context, id string) (*Event, error)

	// CreateEvent creates an event and returns it with its assigned id.
	CreateEvent(ctx context.Context, e Event) (*Event, error)

	// UpdateEvent applies the non-zero fields of e to the event with the given
	// id and returns the updated event. Categories, when non-nil, REPLACE the
	// event's category list wholesale (Graph PATCH semantics).
	UpdateEvent(ctx context.Context, id string, e Event) (*Event, error)

	// DeleteEvent removes an event by id.
	DeleteEvent(ctx context.Context, id string) error
}

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

type Config struct {
	// Provider specifies which email provider to use.
	// Supported values: "outlook365", "gmail"
	Provider string

	// Outlook contains Outlook 365 specific configuration.
	// Required when Provider is "outlook365".
	Outlook *OutlookConfig

	// Gmail contains Gmail specific configuration.
	// Required when Provider is "gmail".
	Gmail *GmailConfig

	// Custom is reserved for future provider extensions
	Custom map[string]interface{}
}

type DraftInfo struct {
	// ID is the provider message id of the created draft (Graph message id for
	// Outlook). Treat it as opaque; it can be passed to Read/Delete/Move.
	ID string

	// WebLink is the Outlook-on-the-web URL to open the draft, if the provider
	// returns one (empty otherwise).
	WebLink string
}

type Event struct {
	// ID is the provider event identifier. Treat it as opaque. Empty when an
	// Event is passed to Create (the provider assigns it).
	ID string

	// Subject is the event title.
	Subject string

	// Start, End are the event's wall-clock start/end in TimeZone.
	Start time.Time
	End   time.Time

	// TimeZone is the IANA zone the Start/End are expressed in (e.g.
	// "Australia/Perth"). Empty on input means the provider's default zone.
	TimeZone string

	// AllDay reports an all-day event (Start/End are dates).
	AllDay bool

	// Location is the free-text venue, if any.
	Location string

	// BodyText is the plain-text event description.
	BodyText string

	// Organizer is the organiser's email address (output only).
	Organizer string

	// Attendees holds attendee email addresses.
	Attendees []string

	// Categories holds the event's Outlook category tags.
	Categories []string
}

type EventListOptions struct {
	// Start, End bound the query (inclusive of events overlapping the range).
	// Zero Start means "now"; zero End means "no upper bound" for the
	// upcoming-events list.
	Start time.Time
	End   time.Time

	// Limit caps the number of events returned (0 = provider default).
	Limit int
}

type Folder struct {
	// ID is the provider identifier, suitable for ListOptions.Folder and Move.
	ID string

	// Name is the human-readable display name.
	Name string

	// Unread is the count of unread items, where the provider reports it
	// (Outlook); 0 if unknown.
	Unread int
}

type FullMessage struct {
	Summary

	// To, Cc are the recipient addresses.
	To []string
	Cc []string

	// BodyText is the plain-text body, if available.
	BodyText string

	// BodyHTML is the HTML body, if the message was HTML.
	BodyHTML string
}

type GmailAuthHelper struct {
	// CredentialsJSON contains the OAuth2 client credentials from Google Cloud Console
	CredentialsJSON []byte

	// Scopes overrides the OAuth2 scopes requested during the consent flow.
	// If empty, the helper requests gmail.send + gmail.modify so the resulting
	// token works for both sending and the MailboxProvider read/move/label
	// operations. Set this (e.g. add gmail.MailGoogleComScope) before calling
	// Authenticate to widen or narrow the grant.
	Scopes []string
}

type GmailConfig struct {
	// CredentialsJSON contains the OAuth2 credentials downloaded from Google Cloud Console
	CredentialsJSON []byte

	// TokenJSON contains the stored OAuth2 token.
	// If not provided, authentication will be required on first use.
	TokenJSON []byte

	// Scopes overrides the OAuth2 scopes requested. If empty, the provider
	// requests gmail.send + gmail.modify, which covers sending plus the
	// MailboxProvider read/move/label/trash operations. Add
	// gmail.MailGoogleComScope (full access) here if you need permanent
	// deletion. Widening scopes requires re-running the consent flow and
	// replacing the stored token.
	Scopes []string
}

type ListOptions struct {
	// Folder is the folder/label to list. Empty means "inbox". For Outlook
	// this is a well-known folder name or folder id (e.g. "inbox",
	// "sentitems", "archive"); for Gmail it is a label name or system label
	// id (e.g. "INBOX", "SENT"). Ignored by Search.
	Folder string

	// UnreadOnly restricts results to unread messages.
	UnreadOnly bool

	// Since restricts results to messages received at or after this time.
	// The zero value means no lower bound.
	Since time.Time

	// Limit caps the number of messages returned (0 means provider default,
	// no explicit cap). Acts as a ceiling across pages.
	Limit int
}

type MailboxProvider interface {
	Provider

	// List returns message headers from a folder per opts (default inbox),
	// newest first.
	List(ctx context.Context, opts ListOptions) ([]Summary, error)

	// Read returns one message including its body.
	Read(ctx context.Context, id string) (*FullMessage, error)

	// Search runs a provider-native full-text search. The query uses the
	// provider's own syntax (Graph $search KQL / Gmail search operators).
	// opts bounds the results (Folder is ignored).
	Search(ctx context.Context, query string, opts ListOptions) ([]Summary, error)

	// Move relocates a message to the destination folder/label. For Outlook
	// the message is moved; for Gmail the destination label is added and
	// INBOX removed (archive-style move). dest is a folder/label name or id.
	Move(ctx context.Context, id, dest string) error

	// ListAttachments returns metadata for a message's file attachments.
	ListAttachments(ctx context.Context, id string) ([]AttachmentMeta, error)

	// SaveAttachments writes a message's file attachments into destDir and
	// returns the paths written. destDir is created if it does not exist.
	SaveAttachments(ctx context.Context, id, destDir string) ([]string, error)

	// SaveMessageRaw writes the message's raw RFC822 MIME (.eml) into destDir
	// under a collision-free name derived from baseName (".eml" is appended if
	// absent; reserved/control chars in baseName are sanitized), and returns the
	// path written. destDir is created if it does not exist. The raw MIME is the
	// provider's verbatim wire form (Graph $value / Gmail raw), suitable for an
	// .eml->PDF converter. Providers that cannot export raw MIME return
	// ErrUnsupported.
	SaveMessageRaw(ctx context.Context, id, destDir, baseName string) (string, error)

	// CreateReplyDraft creates a DRAFT reply to the message identified by id and
	// returns the new draft's id and web link. It never sends. The server
	// (Graph createReply / createReplyAll) seeds the draft with the correct
	// recipients and the quoted original message, preserving thread context;
	// htmlBody is then PREPENDED to that quoted content as the reply text, so the
	// caller's content appears above the quoted original. htmlBody is always
	// treated as HTML (so formatted tables render); pass "" to create a draft
	// containing only the quoted original. If replyAll is true the draft replies
	// to all recipients (To + Cc of the original), preserving the CCs; otherwise
	// it replies to the sender only. Providers that cannot create draft replies
	// return ErrUnsupported.
	CreateReplyDraft(ctx context.Context, id, htmlBody string, replyAll bool) (*DraftInfo, error)

	// AddAttachment adds a single file attachment to an EXISTING message (typically
	// a draft, e.g. one from CreateReplyDraft) identified by id. att.Filename names
	// the file and att.Content carries its raw bytes; att.MimeType is used verbatim
	// when set, otherwise it is detected from the filename extension. This is a
	// DIRECT attachment upload (a single POST of the whole content), so it is
	// bounded to small files: content larger than MaxDirectAttachmentBytes is
	// rejected with an error rather than attempted, because Graph requires an upload
	// session for larger attachments (which is out of scope). It never sends the
	// message. Providers that cannot add attachments to a stored message return
	// ErrUnsupported.
	AddAttachment(ctx context.Context, id string, att Attachment) error

	// ListMasterCategories returns the mailbox's master category list — the named,
	// colored categories Outlook renders as chips (outlook/masterCategories). A
	// caller ensuring a category exists should fetch this once and match
	// case-insensitively (master categories are unique case-insensitively).
	// Providers without a master-category concept (Gmail) return ErrUnsupported.
	ListMasterCategories(ctx context.Context) ([]MasterCategory, error)

	// CreateMasterCategory adds a category to the mailbox's master list so Outlook
	// renders it in color. name is the display name; color is an Outlook preset
	// token ("preset0".."preset24"); an empty/invalid color falls back to a default
	// preset. The caller is responsible for the case-insensitive existence check —
	// creating a name that already exists (in any case) fails with a Graph 409.
	// Providers without a master-category concept (Gmail) return ErrUnsupported.
	CreateMasterCategory(ctx context.Context, name, color string) error

	// MarkRead sets a message's read state.
	MarkRead(ctx context.Context, id string, read bool) error

	// SetLabels replaces a message's labels (Gmail) or categories (Outlook)
	// with the given set. Names are used; for Gmail, missing user labels are
	// created on demand.
	SetLabels(ctx context.Context, id string, labels []string) error

	// Delete removes a message. If permanent is false the message is moved to
	// the trash/deleted-items and is recoverable; if true it is permanently
	// deleted where the provider supports it (Gmail requires the full-access
	// scope for permanent deletion).
	Delete(ctx context.Context, id string, permanent bool) error

	// ListFolders returns the mailbox's folders (Outlook) or labels (Gmail).
	ListFolders(ctx context.Context) ([]Folder, error)
}

type MasterCategory struct {
	// DisplayName is the category name (e.g. "e-Filed"). Master categories are
	// unique case-insensitively within a mailbox.
	DisplayName string

	// Color is the Outlook preset color token ("preset0".."preset24", or "none").
	// preset0 is red and preset4 is green in the standard Outlook palette.
	Color string
}

type Message struct {
	// From is the sender's email address (required)
	From string

	// To contains the primary recipient email addresses (at least one required)
	To []string

	// Cc contains carbon copy recipient email addresses (optional)
	Cc []string

	// Bcc contains blind carbon copy recipient email addresses (optional)
	Bcc []string

	// Subject is the email subject line (required)
	Subject string

	// Body is the email content (required)
	Body string

	// HTML indicates whether the body should be treated as HTML.
	// If false, the body is treated as plain text.
	HTML bool

	// Attachments contains file attachments (optional)
	Attachments []Attachment
}

type OutlookConfig struct {
	// TenantID is the Azure AD tenant ID
	TenantID string

	// ClientID is the Azure AD application client ID
	ClientID string

	// ClientSecret is the Azure AD application client secret
	ClientSecret string

	// UserID is the mailbox (user principal name or object id) that the read
	// and management operations of MailboxProvider act on, e.g.
	// "info@deltalegal.com.au". It is not required for sending — Send keys off
	// the message's From address — but the mailbox operations (List, Read,
	// Move, ...) need a concrete target and return an error if it is empty.
	UserID string
}

type Provider interface {
	// Send sends an email message using the provider's implementation.
	// The context can be used for timeout and cancellation.
	Send(ctx context.Context, msg *Message) error
}

type Summary struct {
	// ID is the provider-specific message identifier. For Outlook it is the
	// Graph message id; for Gmail the Gmail message id. Treat it as opaque.
	ID string

	// ThreadID groups a conversation. Populated for Gmail; empty for Outlook
	// (Outlook exposes conversationId, which is not currently surfaced).
	ThreadID string

	// From is the sender's email address.
	From string

	// Subject is the message subject (UTF-8, may be non-ASCII).
	Subject string

	// Received is the time the message was received.
	Received time.Time

	// HasAttachments reports whether the message carries file attachments.
	HasAttachments bool

	// Unread reports whether the message is unread.
	Unread bool

	// Labels holds the message's labels (Gmail) or categories (Outlook).
	Labels []string
}

type VersionInfo struct {
	Version    string `json:"version"`
	Major      int    `json:"major"`
	Minor      int    `json:"minor"`
	Patch      int    `json:"patch"`
	PreRelease string `json:"preRelease,omitempty"`
	BuildDate  string `json:"buildDate,omitempty"`
	GitCommit  string `json:"gitCommit,omitempty"`
}