settingsapi

type ChannelInput struct {
	Kind        string   `json:"kind" example:"mattermost"`
	Description string   `json:"description,omitempty" example:"Operations alerts"`
	Enabled     *bool    `json:"enabled,omitempty" example:"true"`
	Connection  string   `json:"connection,omitempty" example:"mattermost-bot"`
	Target      string   `json:"target,omitempty" example:"C0123456789"`
	Recipients  []string `json:"recipients,omitempty"`
	Mode        string   `json:"mode,omitempty" example:"immediate"`
	// RepeatAfter is a duration string ("1h", "30m"). Empty applies the
	// platform default.
	RepeatAfter string `json:"repeat_after,omitempty" example:"1h"`
	MaxPerHour  int    `json:"max_per_hour,omitempty" example:"60"`
	// Format is a webhook channel's payload: "text" (the default) posts
	// {"text": ...}; "json" posts an envelope for a system to receive.
	Format string `json:"format,omitempty" example:"json"`
}

type ChannelListView struct {
	Channels []ChannelView `json:"channels"`
	// Kinds names the kinds this deployment can deliver to, so the admin form
	// offers what will work rather than what compiles.
	Kinds []string `json:"kinds"`
}

type ChannelStatusView struct {
	Name string `json:"name" example:"ops-alerts"`
	// LastDeliveredAt is when a message to the channel was last delivered.
	LastDeliveredAt string `json:"last_delivered_at,omitempty" example:"2026-10-10T09:14:03Z"`
	// LastError is the most recent failure still recorded on one of the
	// channel's messages, and LastErrorAt when that message was queued.
	LastError   string `json:"last_error,omitempty" example:"upstream answered HTTP 403: not_in_channel"`
	LastErrorAt string `json:"last_error_at,omitempty" example:"2026-10-10T08:02:11Z"`
	// SentLastHour counts the sends the hourly cap counts, and MaxPerHour
	// is that cap.
	SentLastHour int `json:"sent_last_hour" example:"12"`
	MaxPerHour   int `json:"max_per_hour" example:"60"`
	// Pending counts messages not yet delivered.
	Pending int `json:"pending" example:"0"`
	// Suppressed counts repeats held back by the channel's keys since each
	// key last went through.
	Suppressed int `json:"suppressed" example:"3"`
}

type ChannelTestResult struct {
	Delivered bool   `json:"delivered"`
	Detail    string `json:"detail"`
}

type ChannelView struct {
	Name        string   `json:"name"`
	Kind        string   `json:"kind"`
	Description string   `json:"description,omitempty"`
	Enabled     bool     `json:"enabled"`
	Connection  string   `json:"connection,omitempty"`
	Target      string   `json:"target,omitempty"`
	Recipients  []string `json:"recipients,omitempty"`
	Mode        string   `json:"mode"`
	RepeatAfter string   `json:"repeat_after"`
	MaxPerHour  int      `json:"max_per_hour"`
	// Format is a webhook channel's payload format, "text" or "json";
	// absent for the other kinds.
	Format    string `json:"format,omitempty"`
	CreatedBy string `json:"created_by,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
	// Warnings report a channel that saves cleanly but cannot deliver -- a
	// connection no live toolkit serves. They are warnings rather than
	// refusals so an operator can create the channel and the connection in
	// either order.
	Warnings []string `json:"warnings,omitempty"`
}

type Config struct {
	// Settings persists the admin SMTP configuration. nil disables every
	// route in this package.
	Settings smtp.SettingsStore
	// SendTest delivers a test email through the stored SMTP settings. nil
	// disables the test route.
	SendTest func(ctx context.Context, to string) error
	// Prefs reads per-address notification preferences so the test-send UI
	// can surface a target's opt-out state (#1022). nil disables the
	// recipient-status route.
	Prefs notification.PrefsStore
	// ReviewAlert persists the knowledge review-queue alert threshold
	// (#803). nil disables the review-queue-alert routes.
	ReviewAlert reviewalert.SettingsStore
	// ConnectionAlert persists the connection-revocation alert's escalation
	// window and recipients (#1694). nil disables the connection-alert
	// routes.
	ConnectionAlert connalert.SettingsStore
	// ScriptRunAlert persists the channels a failed scheduled run is posted
	// to (#1724). nil disables the script-run-alert routes.
	ScriptRunAlert scriptalert.SettingsStore
	// Storage persists the storage capacity settings and the channels its
	// alerts are posted to (#2148). nil disables the storage routes.
	Storage storagecap.SettingsStore
	// WebhookAlert persists the webhook receiver alerts' thresholds and
	// channels (#2149). nil disables the webhook-alert routes.
	WebhookAlert whalert.SettingsStore
	// Channels persists the operator's notification channels (#1720). nil
	// disables the channel routes.
	Channels notification.ChannelStore
	// SendChannelTest delivers a test message through one channel's own
	// transport. nil disables the channel test route.
	SendChannelTest func(ctx context.Context, name string) error
	// ChannelActivity reads what one channel has done recently. nil
	// disables the channel status route.
	ChannelActivity func(ctx context.Context, name string) (notification.ChannelActivity, error)
	// ConnectionExists reports whether a live api toolkit serves a
	// connection, so a channel naming one that is gone is shown as
	// undeliverable rather than as configured. nil omits that warning.
	ConnectionExists func(ctx context.Context, name string) bool
	// Mutable reports database config mode; false swaps the write routes for
	// ReadOnly.
	Mutable bool
	// Author resolves the acting admin for audit columns.
	Author func(*http.Request) string
	// Decode is the parent's strict JSON body decoder (unknown fields
	// rejected, size-capped); its error text is safe to return as the
	// problem detail.
	Decode func(w http.ResponseWriter, r *http.Request, dst any) error
	// ReadOnly is the parent's 405 not-available-in-file-mode responder.
	ReadOnly http.HandlerFunc
}