notification

type Attachment struct {
	// AssetID names a portal asset.
	AssetID string `json:"asset_id,omitempty"`
	// ResourceID names a managed resource.
	ResourceID string `json:"resource_id,omitempty"`
	// Version is the asset version the attachment was made from, recorded
	// at enqueue so a later edit of the asset does not change what a
	// queued message sends. Zero for a resource, which has no versions.
	Version int `json:"version,omitempty"`
	// Preview, with AssetID, sends the asset's light tile image instead of
	// its content: what a chat reader sees of a report before opening it.
	Preview bool `json:"preview,omitempty"`
	// Name is the file name the reader sees.
	Name string `json:"name,omitempty"`
	// Link is where a reader opens the asset or resource, used in place of
	// the file by a kind that carries none or when the file is over the
	// attachment cap.
	Link string `json:"link,omitempty"`
}

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"`
	// Format is the webhook kind's payload: ChannelFormatText (the default
	// when empty) or ChannelFormatJSON. Empty for every other kind.
	Format string `json:"format,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 ChannelActivity struct {
	// LastDeliveredAt is when a row to the channel was last sent.
	LastDeliveredAt *time.Time
	// LastError is the most recent failure recorded on one of the channel's
	// rows still holding one, and LastErrorAt when that row was queued. A
	// delivery clears its row's error, so a channel that recovered reads
	// clean.
	LastError   string
	LastErrorAt *time.Time
	// SentLastHour counts the sends the hourly cap counts.
	SentLastHour int
	// Pending counts rows not yet delivered: waiting, retrying, or in a
	// digest window.
	Pending int
	// Suppressed counts repeats held back across the channel's keys since
	// each key last went through.
	Suppressed int
}

type ChannelGate struct {
	// Channel is the channel's name.
	Channel string
	// MaxPerHour is the channel's hourly cap, counted in sends.
	MaxPerHour int
	// Key is the document's suppression key. Empty skips suppression.
	Key string
	// Window is the repeat window the key is measured against.
	Window time.Duration
}

type ChannelOutcome struct {
	// Suppressed reports a send the key absorbed: no row was written.
	Suppressed bool
}

type ChannelResult struct {
	// Queued is how many queue rows were written: one for a chat or webhook
	// channel, one per deliverable recipient for an email channel.
	Queued int
	// Suppressed reports a send absorbed by its key's repeat window: counted
	// on the key, and stated by the next send that goes through.
	Suppressed bool
}

type ChannelSend struct {
	Channel  Channel
	Document Document
	// Actor is who the send is charged to: the person or script sending.
	// Empty for an alert the platform raised.
	Actor string
	// RepeatAfter lengthens the channel's repeat window for the document's
	// key. A value shorter than the channel's own window is ignored: a
	// sender may make an alert quieter, never louder.
	RepeatAfter time.Duration
}

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 Delivery struct {
	// ID is the delivery's stable id: "ntf_<row id>" for a queued row.
	ID string
	// OccurredAt is when the document was queued.
	OccurredAt time.Time
	// Files are the document's attachments that were read for this
	// delivery, in the document's order.
	Files []File
	// Linked are the attachments that travel as a link instead: over
	// MaxAttachmentBytes, unreadable, or on a kind that carries no files.
	Linked []Attachment
	Document
}

type Document struct {
	// Title is the message's subject line: the email subject, 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"`
	// Attachments name the portal assets and managed resources that travel
	// with the document as files. They are references, never bytes: the
	// queue row stays small and the worker reads each one at the version
	// recorded here when it delivers.
	Attachments []Attachment `json:"attachments,omitempty"`
	// Key identifies "the same alert again" on its channel. A second send
	// with the same key inside the channel's repeat window is counted and
	// not delivered. Empty means every send is delivered.
	Key string `json:"key,omitempty"`
	// Suppressed is how many sends with this document's key were absorbed
	// since SuppressedSince, written by the queue when this send went
	// through after them. Every kind states it on the message's first line.
	Suppressed      int        `json:"suppressed,omitempty"`
	SuppressedSince *time.Time `json:"suppressed_since,omitempty"`
	// Type is one of the Document* types: what produced the document.
	// Empty on a document queued before types existed.
	Type string `json:"type,omitempty"`
	// Source is who produced it.
	Source *DocumentSource `json:"source,omitempty"`
	// Data is the sender's structured payload, JSON, delivered verbatim by a
	// JSON webhook channel and ignored by every other kind.
	Data json.RawMessage `json:"data,omitempty"`
}

type DocumentSource struct {
	// Kind is DocumentSourceScript, DocumentSourceUser or DocumentSourceAdmin.
	Kind string `json:"kind"`
	// Script is the producing script's reference, mcp:script:<id>.
	Script string `json:"script,omitempty"`
	// RunID is the producing run.
	RunID string `json:"run_id,omitempty"`
}

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

type File struct {
	Name        string
	ContentType string
	Data        []byte
}

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
	// Channel scopes the listing to rows sent to one notification channel.
	// Empty means any row.
	Channel 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"`
	// Cause is why a KindScriptRun run failed, one of the script.Cause*
	// values (#1859), which decides whether the alert tells the owner to fix
	// the script or that the next run should succeed. Empty for every other
	// kind, and on a row enqueued before the cause was recorded.
	Cause string `json:"cause,omitempty"`
	// Repeats is how many finished runs of a KindScriptRun alert's script
	// have now failed in a row ending on the same error, this one included
	// (#1935). A failure that repeats is one the next run is not getting past
	// on its own; a single one may be a bad moment outside the script. Zero
	// where it was not read, which renders as a first failure.
	Repeats int `json:"repeats,omitempty"`
	// Recovery is set on a KindScriptRun alert that a failing automation ran
	// successfully again (#2041), and is nil on a failure alert and every
	// other kind.
	Recovery *ScriptRecovery `json:"recovery,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
	// EnqueueChannel writes the rows of one channel send in one transaction
	// behind gate: it returns an error wrapping ErrChannelOverCap when the
	// channel has been sent gate.MaxPerHour sends in the last hour, and
	// Suppressed when gate.Key was sent inside gate.Window. A send that goes
	// through after suppressed ones carries their count and start on its
	// document.
	EnqueueChannel(ctx context.Context, rows []Notification, gate ChannelGate) (ChannelOutcome, 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)
	// PurgeChannelKeys deletes suppression keys whose window ended more than
	// retention ago, returning how many were deleted.
	PurgeChannelKeys(ctx context.Context, retention 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 RunPost struct {
	Channel  string
	Title    string
	QueuedAt time.Time
	// Deliveries counts the queue rows the post became; Sent and Failed how
	// many of them were delivered and how many gave up. The rest are waiting.
	Deliveries int
	Sent       int
	Failed     int
	// LastSentAt is when the last of them was delivered.
	LastSentAt *time.Time
	// LastError is a failure recorded on one of them.
	LastError string
}

type ScriptRecovery struct {
	FailedRuns   int       `json:"failed_runs"`
	FailingSince time.Time `json:"failing_since"`
	RecoveredAt  time.Time `json:"recovered_at"`
	OpeningRunID string    `json:"opening_run_id"`
	OpeningCause string    `json:"opening_cause,omitempty"`
	// OpeningError is the line of the opening run's error that names the
	// failure: its last, as a traceback ends with what was raised.
	OpeningError string `json:"opening_error,omitempty"`
	// OpeningLink is the opening run's page, empty when the deployment does
	// not know its own public address.
	OpeningLink string `json:"opening_link,omitempty"`
}

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
}