notification

type Channel interface {
	// Name returns the unique identifier for this channel, e.g. ChannelMail, ChannelDatabase.
	Name() string

	Send(notifiable Notifiable, notification Notification) error
}

type DatabaseNotification interface {
	Notification
	// ToDatabase returns the map that will be JSON-encoded into the data column.
	ToDatabase(notifiable Notifiable) map[string]any
}

type DatabaseRoutable interface {
	RouteNotificationForDatabase() string
}

type MailMessage struct {
	// Subject is the email subject line. Defaults to the notification type name.
	Subject string
	// To overrides the recipient address(es). Leave empty to use
	// RouteNotificationFor(ChannelMail) / MailRoutable.
	To []string
	// From overrides the sender address. Leave empty to use the global mail.from config.
	From string
	// ReplyTo sets the Reply-To header.
	ReplyTo string
	// Content holds the plain-text and/or Html bodies — the same type
	// facades.Mail() itself uses, so nothing is lost or re-mapped between
	// a notification's mail representation and a plain Mailable's.
	Content contractsmail.Content
	// Attachments is a list of absolute file paths to attach.
	Attachments []string
	// Headers are arbitrary additional email headers.
	Headers map[string]string
}

type MailRoutable interface {
	RouteNotificationForMail(notification Notification) map[string]string
}

type MailableNotification interface {
	Notification
	// ToMail returns the MailMessage used to build the outgoing email.
	ToMail(notifiable Notifiable) MailMessage
}

type Manager interface {
	Send(notifiable Notifiable, notification Notification) error

	SendNow(notifiable Notifiable, notification Notification) error

	Extend(channel Channel)

	Channel(name string) Channel

	Route(channel string, route any) OnDemandNotifiable
}

type Notifiable interface {
	// RouteNotificationFor returns the delivery address for specified channel.
	// Concrete address types vary by channel implementation:
	// mail:
	//   string        single recipient address
	//   []string      multiple recipient addresses
	//   map[string]string address-name recipient mapping
	// database:
	//   string        model primary key (numeric IDs auto converted via cast.ToString)
	// Custom channels support arbitrary custom types. Unrecognized types for a channel are treated as no valid route.
	//
	// Prefer the typed alternatives for the built-in channels instead of
	// matching on the channel name constants (ChannelMail / ChannelDatabase)
	// here: implement MailRoutable (mail) or DatabaseRoutable (database)
	// and the channel uses them directly, so a typo can't silently drop a
	// route.
	RouteNotificationFor(channel string) any
}

type Notification interface {
	Via(notifiable Notifiable) []string
}

type NotificationWithAfterSending interface {
	Notification
	AfterSending(notifiable Notifiable, channel string) error
}

type NotificationWithBackoff interface {
	Notification
	// Backoff returns the delay before each retry attempt on channel,
	// in order; the last value repeats for subsequent attempts.
	Backoff(channel string) []time.Duration
}

type NotificationWithDatabaseConnection interface {
	Notification
	// DatabaseConnection returns the connection name to use. Return ""
	// for the default connection.
	DatabaseConnection() string
}

type NotificationWithID interface {
	Notification
	ID() string
}

type NotificationWithShouldSend interface {
	Notification
	ShouldSend(notifiable Notifiable, channel string) bool
}

type NotificationWithTries interface {
	Notification
	// Tries returns the maximum number of attempts for the given
	// channel. 0 / not implementing this interface means no retry policy
	// is declared and the queue worker's Tries config applies.
	Tries(channel string) int
}

type OnDemandNotifiable interface {
	Notifiable

	Route(channel string, route any) OnDemandNotifiable

	Notify(notification Notification) error

	NotifyNow(notification Notification) error
}

type ResolvableChannel interface {
	Channel

	// Resolve computes what Deliver will need. route is whatever
	// RouteNotificationFor returned for this channel; payload is this
	// channel's message type, JSON-marshaled.
	Resolve(notifiable Notifiable, notification Notification) (route string, payload []byte, err error)

	// Deliver sends using only the plain data Resolve produced.
	Deliver(route string, payload []byte) error
}

type ShouldQueue interface {
	// OnQueue returns the queue name to use. Return "" for the default queue.
	OnQueue() string
	// OnConnection returns the connection name to use. Return "" for the default.
	OnConnection() string
}