notification

type Channel struct {
	// Name identifies the channel and is its primary key.
	Name string `json:"name"`
	// Kind is one of the ChannelKind* constants.
	Kind string `json:"kind"`
	// Description is the operator's sentence about what this channel is for.
	Description string `json:"description,omitempty"`
	// Enabled gates delivery. A disabled channel refuses an enqueue rather
	// than silently collecting rows nobody will send.
	Enabled bool `json:"enabled"`
	// Connection names the api connection the three HTTP kinds deliver
	// through. Empty for the email kind.
	Connection string `json:"connection,omitempty"`
	// Target is the chat channel id a post is addressed to: Slack's C… id or
	// Mattermost's channel id. Empty for the webhook and email kinds.
	Target string `json:"target,omitempty"`
	// Recipients is the email kind's distribution list. Empty for the three
	// HTTP kinds.
	Recipients []string `json:"recipients,omitempty"`
	// Mode is ChannelModeImmediate or ChannelModeDaily.
	Mode string `json:"mode"`
	// RepeatAfter is how long a repeated key is suppressed for. Zero means
	// DefaultChannelRepeatAfter.
	RepeatAfter time.Duration `json:"repeat_after,omitempty"`
	// MaxPerHour bounds the channel's outbound rate across replicas. Zero
	// means DefaultChannelMaxPerHour.
	MaxPerHour int `json:"max_per_hour,omitempty"`
	// CreatedBy is the administrator who created the channel.
	CreatedBy string `json:"created_by,omitempty"`
	// UpdatedAt is when the record was last written.
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

type ChannelStore interface {
	// List returns every channel in name order.
	List(ctx context.Context) ([]Channel, error)
	// Get returns one channel by name, or ErrChannelNotFound.
	Get(ctx context.Context, name string) (*Channel, error)
	// Set creates or replaces a channel.
	Set(ctx context.Context, ch Channel) error
	// Delete removes a channel. Deleting an absent channel is not an error.
	Delete(ctx context.Context, name string) error
}

type ConnectionAuth struct {
	// Kind is the connection kind (mcp, api, graphql). With Name it is how a
	// recipient finds the connection, and the two are rendered together rather
	// than as one joined string so the email can link to it.
	Kind string `json:"kind"`
	// Name is the connection name within the kind.
	Name string `json:"name"`
	// IDPHost is the host of the upstream token endpoint that rejected the
	// refresh. Empty when the platform decided locally (see Reason).
	IDPHost string `json:"idp_host,omitempty"`
	// Reason is what the upstream returned, in the stable short form the auth
	// event history records: an RFC 6749 error code such as invalid_grant or
	// invalid_client when the upstream answered, and no_refresh_token or
	// refresh_expired when the platform reached the verdict without calling
	// it. The email states which of those two it was, because they ask the
	// recipient for different things.
	Reason string `json:"reason,omitempty"`
	// Description is the upstream's error_description, bounded by the
	// platform. Carried for a refused jwt_bearer assertion, where it is
	// usually the only statement of which upstream approval is missing.
	Description string `json:"description,omitempty"`
	// SignedAssertion marks a refused jwt_bearer assertion rather than a
	// revoked authorization (#1734). The email then says there is nothing to
	// reconnect and sends the reader to the upstream: the key, the integration
	// user or the clocks, and it says the alert clears itself when an exchange
	// is next accepted.
	SignedAssertion bool `json:"signed_assertion,omitempty"`
	// AuthorizedBy is the identity that authorized the connection, and the
	// address the first alert is sent to. It is carried in the payload as well
	// so the escalation to the operator's chosen recipients can say whose
	// authorization lapsed.
	AuthorizedBy string `json:"authorized_by,omitempty"`
	// RevokedAt is when the credential was discarded.
	RevokedAt time.Time `json:"revoked_at,omitzero"`
	// Escalated marks the second alert: the connection was still unauthorized
	// after the operator's escalation window, so it went to the addresses the
	// operator named rather than to the person who authorized it. The two
	// alerts carry the same revocation and differ only in who is being asked
	// to act, which is what this field lets the email say.
	Escalated bool `json:"escalated,omitempty"`
	// EscalatedAfterHours is the window that elapsed before the escalation was
	// raised. Zero on the first alert.
	EscalatedAfterHours int `json:"escalated_after_hours,omitempty"`
}

type Document struct {
	// Title is the message's subject line: the email subject, the Slack
	// header block, the Mattermost first-line heading.
	Title string `json:"title"`
	// Body is markdown. What a reader sees of it depends on the kind.
	Body string `json:"body,omitempty"`
	// Link is the absolute URL a reader follows to the asset, the run, or
	// whatever else produced the message.
	Link string `json:"link,omitempty"`
}

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

type HistoryFilter struct {
	// Recipient scopes the listing to one address. Empty means every
	// recipient, which only an admin-gated caller may ask for.
	Recipient string
	// Status is one of the Status* constants. Empty means any status.
	Status string
	// Category is one of the Category* constants. Empty means any category.
	Category string
	// Limit bounds the page; zero or negative means DefaultHistoryLimit.
	// Values above MaxHistoryLimit are clamped.
	Limit int
	// Offset is the page start.
	Offset int
}

type HistoryStore interface {
	// List returns one page of notifications, newest first.
	List(ctx context.Context, filter HistoryFilter) ([]Notification, error)
	// Count returns how many rows match the filter, ignoring its paging
	// fields.
	Count(ctx context.Context, filter HistoryFilter) (int, error)
	// CountsByStatus returns the per-status row counts for the filter,
	// keyed by the Status* constants. It honors every field of the filter,
	// so a caller wanting the whole breakdown of a status-filtered view
	// clears Status first.
	CountsByStatus(ctx context.Context, filter HistoryFilter) (map[string]int, error)
}

type Notification struct {
	ID        int64  `json:"id"`
	Recipient string `json:"recipient"`
	Category  string `json:"category"`
	// Channel names the destination a KindChannel row was sent to, and is
	// empty for every row addressed to a person alone. It is a column rather
	// than a payload field because the worker claims on it (a chat row is
	// deliverable with no mail server configured) and the admin history
	// filters on it.
	Channel      string     `json:"channel,omitempty"`
	Payload      Payload    `json:"payload"`
	Digest       bool       `json:"digest"`
	Status       string     `json:"status"`
	Attempts     int        `json:"attempts"`
	LastError    string     `json:"last_error,omitempty"`
	ScheduledFor time.Time  `json:"scheduled_for"`
	SentAt       *time.Time `json:"sent_at,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
}

type Payload struct {
	// Kind is one of the Kind* constants.
	Kind string `json:"kind"`
	// ItemID identifies the shared or commented item.
	ItemID string `json:"item_id"`
	// ItemTitle is the human-readable name of the item.
	ItemTitle string `json:"item_title"`
	// Actor is the email of the person who shared or commented.
	Actor string `json:"actor"`
	// Message is an optional comment/feedback snippet.
	Message string `json:"message,omitempty"`
	// Link is the absolute portal deep link for the item.
	Link string `json:"link,omitempty"`
	// Review carries the review-queue rollup of a KindReviewQueue alert and
	// is nil for every other kind.
	Review *ReviewQueue `json:"review,omitempty"`
	// Connection carries the revocation a KindConnectionAuth alert reports and
	// is nil for every other kind.
	Connection *ConnectionAuth `json:"connection,omitempty"`
	// Document carries what a KindChannel row delivers and is nil for every
	// other kind. It holds the message rather than a reference to one
	// because a channel document has no platform record behind it to re-read
	// at send time: the sender composed it, and what was composed is what
	// must arrive.
	Document *Document `json:"document,omitempty"`
}

type Prefs struct {
	Email           string    `json:"email"`
	Mode            string    `json:"mode"`
	SharesEnabled   bool      `json:"shares_enabled"`
	CommentsEnabled bool      `json:"comments_enabled"`
	MentionsEnabled bool      `json:"mentions_enabled"`
	UpdatedAt       time.Time `json:"updated_at"`
}

type PrefsStore interface {
	// Get returns the user's preferences, falling back to DefaultPrefs when
	// no row exists. It never returns an error for an unknown user.
	Get(ctx context.Context, email string) (Prefs, error)
	// Set upserts the user's preferences, applying u over the current values.
	Set(ctx context.Context, email string, u PrefsUpdate) (Prefs, error)
}

type PrefsUpdate struct {
	Mode            *string `json:"mode,omitempty"`
	SharesEnabled   *bool   `json:"shares_enabled,omitempty"`
	CommentsEnabled *bool   `json:"comments_enabled,omitempty"`
	MentionsEnabled *bool   `json:"mentions_enabled,omitempty"`
}

type QueueStore interface {
	// Enqueue inserts a pending row and nudges the send worker.
	Enqueue(ctx context.Context, n Notification) error
	// ClaimImmediate claims the next due non-digest row deliverable under
	// filter, returning ErrNoWork when none is due.
	ClaimImmediate(ctx context.Context, lease time.Duration, filter TransportFilter) (*Notification, error)
	// ClaimDigest claims every due digest row for one recipient under a
	// lease, returning ErrNoWork when none is due.
	ClaimDigest(ctx context.Context, lease time.Duration, filter TransportFilter) ([]Notification, error)
	// MarkSent transitions claimed rows to sent.
	MarkSent(ctx context.Context, ids []int64) error
	// Retry returns claimed rows to pending after backoff, recording the error.
	Retry(ctx context.Context, ids []int64, sendErr string, backoff time.Duration) error
	// Fail marks claimed rows permanently failed, recording the error.
	Fail(ctx context.Context, ids []int64, sendErr string) error
	// PurgeOld bounds table growth: it deletes resolved (sent/failed) rows
	// older than resolvedRetention and unresolved rows older than
	// pendingTTL. The latter also guarantees that enabling SMTP on a
	// deployment that queued for months does not deliver an ancient
	// backlog. Returns the number of rows deleted.
	PurgeOld(ctx context.Context, resolvedRetention, pendingTTL time.Duration) (int64, error)
}

type ReviewQueue struct {
	// Pending is the total number of insights awaiting review.
	Pending int `json:"pending"`
	// OldestAgeDays is the age in days of the oldest pending insight.
	OldestAgeDays int `json:"oldest_age_days"`
	// StaleCount is how many pending insights are at least StaleAfterDays
	// old -- the accumulating review debt.
	StaleCount int `json:"stale_count"`
	// StaleAfterDays is the age at which a pending insight counts toward
	// StaleCount. The email states it rather than assuming the reader knows
	// the platform's staleness window.
	StaleAfterDays int `json:"stale_after_days"`
}

type TransportFilter struct {
	// Email includes every row delivered over SMTP: rows addressed to a
	// person, whether or not an email channel put them there.
	Email bool
	// Channel includes rows addressed to a channel destination, delivered
	// over the channel kind's HTTP transport.
	Channel bool
}