mail

type Attachment struct {
	// Filename is the name the recipient sees. It is sanitised on
	// emission: a caller's filename ends up as a name on someone's disk
	// and inside a header, so it is input, not decoration.
	Filename string
	// ContentType defaults to application/octet-stream.
	ContentType string
	// Content is the raw file, encoded base64 on emission.
	Content []byte
	// Inline marks an attachment meant to be rendered inside the HTML
	// body (Content-Disposition: inline) rather than offered as a file.
	Inline bool
	// ContentID is the identifier the HTML refers to as cid:<ContentID>.
	// It only means anything for an inline attachment.
	ContentID string
}

type CircuitBreakerConfig struct {
	// Enabled turns on circuit-breaker wrapping around Send.
	Enabled bool `koanf:"enabled"`

	// FailureThreshold is the number of consecutive Send failures
	// required to trip the breaker open. Non-positive falls back to
	// pkg/circuit's default (1).
	FailureThreshold int `koanf:"failure_threshold"`

	// Cooldown is the duration the breaker stays open before admitting
	// half-open probes. Non-positive falls back to pkg/circuit's
	// default (30s).
	Cooldown time.Duration `koanf:"cooldown"`

	// HalfOpenMaxConcurrent caps in-flight probes in the half-open
	// state. Non-positive falls back to pkg/circuit's default (1).
	HalfOpenMaxConcurrent int `koanf:"half_open_max_concurrent"`
}

type Config struct {
	Driver  string
	Timeout time.Duration

	// SMTP
	SMTPHost string
	SMTPPort int
	SMTPUser string
	SMTPPass string

	// CircuitBreaker, when Enabled, wraps the returned Sender.Send
	// with a pkg/circuit breaker. Healthy (if the underlying provider
	// implements HealthChecker) bypasses the breaker so /healthz
	// observes a recovering dependency.
	CircuitBreaker CircuitBreakerConfig

	// Logger receives the circuit breaker's state-transition lines
	// (NF-9: the breaker used to open and close in silence). Nil falls
	// back to slog.Default().
	Logger *slog.Logger
}

type HealthChecker interface {
	Healthy(ctx context.Context) error
}

type Message struct {
	From    string
	To      []string
	Subject string
	Body    string

	// Headers holds optional custom headers appended after the
	// framework-generated ones (From, To, Subject, MIME-Version,
	// Content-Type). The built-in senders (SMTP and external
	// plugins) validate the map on Send: a key must be non-empty
	// and neither key nor value may contain CR or LF, so
	// caller-supplied input cannot inject additional headers (e.g.
	// an extra Bcc). Values are trimmed; a header whose value is
	// empty after trimming is omitted. Custom providers registered
	// via RegisterProvider are responsible for their own emission.
	Headers map[string]string

	// HTML is the alternative representation of Body. When it is set the
	// message goes out as multipart/alternative with the plain text
	// first, so a reader that cannot render HTML still gets the message
	// rather than an encoded wall. Body is NOT optional when HTML is
	// present: a message with no text alternative is what spam filters
	// score against, and a text-only client would receive nothing.
	HTML string

	// Attachments are files carried with the message. Any attachment
	// wraps the body in a multipart/mixed. An attachment whose Inline is
	// set and whose ContentID is referenced from the HTML (cid:<id>) is
	// rendered in place instead of listed.
	Attachments []Attachment
}

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

type ProviderFactory func(cfg Config) (Sender, error)

type Sender interface {
	Send(ctx context.Context, message Message) error
}

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