// Package email provides the abstraction over outgoing email transport.
//
// ADR-0029 picked Mailpit for local dev and BDD ; production sender is
// deferred. The Sender interface is the swap point : a future production
// adapter (AWS SES, Postmark, SendGrid) implements the same contract
// without touching call sites.
package email

import "context"

// Sender sends email messages. Implementations must be safe for
// concurrent use — multiple goroutines may call Send simultaneously.
type Sender interface {
	Send(ctx context.Context, msg Message) error
}

// Message is the wire-level representation of an outgoing email.
// Headers is for trace correlation (e.g. X-Test-Scenario-ID for BDD)
// and arbitrary application-specific tags. Implementations include
// these as RFC 5322 header fields.
type Message struct {
	// To is the recipient address (single recipient ; we don't currently
	// support multi-recipient broadcasts — keeps the contract simple
	// and matches the magic-link use case which is always 1:1).
	To string

	// From is the sender address. Required.
	From string

	// Subject is the RFC 5322 Subject. Required for non-empty body.
	Subject string

	// BodyText is the plain-text body. At least one of BodyText or
	// BodyHTML must be non-empty.
	BodyText string

	// BodyHTML is the optional HTML body. When both are set, the
	// SMTP-level message is multipart/alternative.
	BodyHTML string

	// Headers are extra RFC 5322 header fields. Keys are case-insensitive ;
	// implementations canonicalise via textproto.CanonicalMIMEHeaderKey.
	// Useful for BDD test correlation (X-BDD-Scenario, etc.).
	Headers map[string]string
}