types

type Alert struct {
	// Timestamp is the time when the alert was created. If the timestamp is empty (or older than 7 days), it will be replaced with the current time.
	Timestamp time.Time `json:"timestamp"`

	// CorrelationID is an optional field used to group related alerts together in issues.
	// If unset, the correlation ID is constructed by hashing [Header, Text, Author, Host, SlackChannelID].
	// It is strongly recommended to set this to an explicit value, which makes sense in your context, rather than relying on the default hash value.
	// With a custom correlation ID, you can update both header and text without creating a new issue.
	CorrelationID string `json:"correlationId"`

	// Type is the type of alert, such as 'compliance', 'security' or 'metrics'.
	// It is primarily used for routing, when the alert RouteKey field is used (rather than SlackChannelID).
	// This field is optional, and case-insensitive.
	Type string `json:"type"`

	// Header is the main header (title) of the alert.
	// It is automatically truncated at MaxHeaderLength characters.
	// Include :status: in the header (or text) to have it replaced with the appropriate emoji for the issue severity.
	// This field is optional, but Header and Text cannot both be empty.
	Header string `json:"header"`

	// HeaderWhenResolved is the main header (title) of the issue when in the *resolved* state.
	// It is automatically truncated at MaxHeaderLength characters.
	// This field is optional. If unset, the Header field is used for all issue states.
	HeaderWhenResolved string `json:"headerWhenResolved"`

	// Text is the main text (body) of the alert.
	// It is automatically truncated at MaxTextLength characters.
	// Include :status: in the text (or header) to have it replaced with the appropriate emoji for the issue severity.
	// This field is optional, but Header and Text cannot both be empty.
	Text string `json:"text"`

	// TextWhenResolved is the main text (body) of the alert when in the *resolved* state.
	// It is automatically truncated at MaxTextLength characters.
	// This field is optional. If unset, the Text field is used for all issue states.
	TextWhenResolved string `json:"textWhenResolved"`

	// FallbackText is the text displayed in Slack notifications.
	// It should be a short, human-readable summary of the alert, without markdown or line breaks.
	// It is automatically truncated at MaxFallbackTextLength characters.
	// This field is optional. If unset, Slack decides what to display in notifications (which may not always be ideal).
	FallbackText string `json:"fallbackText"`

	// Author is the 'author' of the alert (if relevant), displayed as a context block in the Slack post.
	// It is automatically truncated at MaxAuthorLength characters.
	// This field is optional.
	Author string `json:"author"`

	// Host is the 'host' on which the alert originated (if any), displayed as a context block in the Slack post.
	// It is automatically truncated at MaxHostLength characters.
	// This field is optional.
	Host string `json:"host"`

	// Footer is the 'footer' of the alert, displayed as a context block at the bottom of the Slack post.
	// It is automatically truncated at MaxFooterLength characters.
	// This field is optional.
	Footer string `json:"footer"`

	// Link is an optional link (url) to more information about the alert, displayed as a context block in the Slack post.
	// This field is optional, but if set, it must be a valid absolute URL, starting with http:// or https://
	Link string `json:"link"`

	// IssueFollowUpEnabled is a flag that determines if the issue should be automatically resolved after a certain time.
	// If set to true, the issue will be resolved after AutoResolveSeconds seconds.
	// Set to false for fire-and-forget alerts, where no follow-up is needed (i.e. no issue tracking).
	IssueFollowUpEnabled bool `json:"issueFollowUpEnabled"`

	// AutoResolveSeconds is the number of seconds after which the issue should be automatically resolved, if IssueFollowUpEnabled is true.
	// The value must be between MinAutoResolveSeconds and MaxAutoResolveSeconds.
	AutoResolveSeconds int `json:"autoResolveSeconds"`

	// AutoResolveAsInconclusive is a flag that determines if the issue should be automatically resolved as 'inconclusive' instead of 'resolved'.
	// This affects the which emoji is used in the Slack post.
	// The default value is false, which means the issue is resolved with status 'resolved'.
	AutoResolveAsInconclusive bool `json:"autoResolveAsInconclusive"`

	// Severity is the severity of the alert, such as 'panic', 'error', 'warning', 'resolved' or 'info'.
	// This value determines the emoji used in the Slack post (for the :status: placeholder in header or text).
	// The value must be one of the predefined AlertSeverity constants.
	// If unset, the severity is automatically set to 'error'.
	Severity AlertSeverity `json:"severity"`

	// SlackChannelID is the ID of the Slack channel where the alert should be posted.
	// Slack channel names are also accepted, and are automatically converted to channel IDs by the API.
	// The value must be an existing channel ID or name, and the Slack Manager integration must have been added to the channel.
	// This field is optional.
	// If both SlackChannelID and RouteKey are set, SlackChannelID takes precedence.
	// If both SlackChannelID and RouteKey are empty, the API will still accept the alert IF a fallback mapping exists. Otherwise, it will return an error.
	SlackChannelID string `json:"slackChannelId"`

	// RouteKey is the case-insensitive route key of the alert, used for routing to the correct Slack channel by the API.
	// The API will return an error if the route key does not match any configured route.
	// This field is optional.
	// If both SlackChannelID and RouteKey are set, SlackChannelID takes precedence.
	// If both SlackChannelID and RouteKey are empty, the API will still accept the alert IF a fallback mapping exists. Otherwise, it will return an error.
	RouteKey string `json:"routeKey"`

	// Username is the username that the alert should be posted as in Slack.
	// This field is optional. If omitted, the alert is posted as the default bot user.
	Username string `json:"username"`

	// IconEmoji is the emoji that the alert should be posted with in Slack, on the format ':emoji:'.
	IconEmoji string `json:"iconEmoji"`

	// Fields are rendered in a compact format that allows for 2 columns of side-by-side text.
	Fields []*Field `json:"fields"`

	// NotificationDelaySeconds is the number of seconds to wait before creating an actual Slack post.
	// If the issue is resolved before the delay is over, no Slack post is created for the issue.
	// This is useful for issues that may be resolved quickly, to avoid unnecessary notifications.
	NotificationDelaySeconds int `json:"notificationDelaySeconds"`

	// ArchivingDelaySeconds is the number of seconds to wait before archiving the issue, after it is resolved.
	// A non-archived issue is re-opened if a new alert with the same CorrelationID is received, and the same Slack post is updated.
	// An archived issue can never be re-opened, and any new alerts with the same CorrelationID will generate a new issue and new Slack post.
	ArchivingDelaySeconds int `json:"archivingDelaySeconds"`

	// Escalation defines a list of escalation points for this alert's issue.
	// Each escalation can increase severity, add Slack mentions, or move the issue to a different channel after a specified delay.
	// Escalations are sorted by DelaySeconds and triggered in order if the issue remains unresolved.
	// Maximum of MaxEscalationCount escalations allowed.
	Escalation []*Escalation `json:"escalation"`

	// IgnoreIfTextContains is a list of substrings that, if found in the alert text, will cause the alert to be ignored.
	// This is useful for filtering out known noise or false positives.
	// Maximum of MaxIgnoreIfTextContainsCount items, each up to MaxIgnoreIfTextContainsLength characters.
	IgnoreIfTextContains []string `json:"ignoreIfTextContains"`

	// Webhooks defines interactive buttons that appear on the Slack post.
	// Each webhook triggers an HTTP POST to the specified URL when clicked.
	// Webhooks can include confirmation dialogs, input forms, and access level restrictions.
	// Maximum of MaxWebhookCount webhooks allowed.
	Webhooks []*Webhook `json:"webhooks"`

	// Metadata is an arbitrary key-value map for storing custom data with the alert.
	// This data is passed through to webhook payloads and can be used for tracking or correlation purposes.
	// The Slack Manager does not interpret this data.
	Metadata map[string]any `json:"metadata"`

	// Deprecated: FailOnRateLimitError is no longer in use.
	FailOnRateLimitError bool `json:"failOnRateLimitError"`
}

type AlertSeverity string

type ChannelProcessingState struct {
	ChannelID           string    `json:"channelId"`
	Created             time.Time `json:"created"`
	LastChannelActivity time.Time `json:"lastChannelActivity"`
	LastProcessed       time.Time `json:"lastProcessed"`
	OpenIssues          int       `json:"openIssues"`
}

type DB interface {
	// Init initializes the database, for example by creating necessary tables or collections.
	// Set skipSchemaValidation to true to skip schema validation.
	Init(ctx context.Context, skipSchemaValidation bool) error

	// SaveAlert saves an alert to the database (for auditing purposes).
	// The same alert may be saved multiple times, in case of errors and retries.
	//
	// A database implementation can choose to skip saving the alerts, since they are never read by the manager.
	SaveAlert(ctx context.Context, alert *Alert) error

	// SaveIssue creates or updates a single issue in the database.
	SaveIssue(ctx context.Context, issue Issue) error

	// SaveIssues creates or updates multiple issues in the database.
	SaveIssues(ctx context.Context, issues ...Issue) error

	// MoveIssue moves an issue from one channel to another.
	// This channel ID in the issue must match the targetChannelID.
	// The sourceChannelID is used to find the existing issue in the database.
	MoveIssue(ctx context.Context, issue Issue, sourceChannelID, targetChannelID string) error

	// FindOpenIssueByCorrelationID finds a single open issue in the database, based on the provided channel ID and correlation ID.
	//
	// The database implementation should return an error if the query matches multiple issues, and [nil, nil] if no issue is found.
	FindOpenIssueByCorrelationID(ctx context.Context, channelID, correlationID string) (string, json.RawMessage, error)

	// FindIssueBySlackPostID finds a single issue in the database, based on the provided channel ID and Slack post ID.
	//
	// The database implementation should return an error if the query matches multiple issues, and [nil, nil] if no issue is found.
	FindIssueBySlackPostID(ctx context.Context, channelID, postID string) (string, json.RawMessage, error)

	// FindActiveChannels returns a list of all active channels in the database.
	// An active channel is one that has at least one open issue.
	// The returned list may be empty if no active channels are found.
	FindActiveChannels(ctx context.Context) ([]string, error)

	// LoadOpenIssuesInChannel loads all open (non-archived) issues from the database, for the specified channel ID.
	// The returned list may be empty if no open issues are found in the channel.
	LoadOpenIssuesInChannel(ctx context.Context, channelID string) (map[string]json.RawMessage, error)

	// SaveMoveMapping creates or updates a single move mapping in the database.
	SaveMoveMapping(ctx context.Context, moveMapping MoveMapping) error

	// FindMoveMapping finds a single move mapping in the database, for the specified channel ID and correlation ID.
	//
	// The database implementation should return an error if the query matches multiple mappings, and [nil, nil] if no mapping is found.
	FindMoveMapping(ctx context.Context, channelID, correlationID string) (json.RawMessage, error)

	// DeleteMoveMapping deletes a single move mapping from the database, for the specified channel ID and correlation ID.
	DeleteMoveMapping(ctx context.Context, channelID, correlationID string) error

	// SaveChannelProcessingState creates or updates a single channel processing state in the database.
	SaveChannelProcessingState(ctx context.Context, state *ChannelProcessingState) error

	// FindChannelProcessingState finds a single channel processing state in the database, for the specified channel ID.
	//
	// The database implementation should return an error if the query matches multiple states, and [nil, nil] if no state is found.
	FindChannelProcessingState(ctx context.Context, channelID string) (*ChannelProcessingState, error)

	// DropAllData drops *all* data from the database.
	// This is useful for testing purposes, to reset the database state.
	// It should be used with caution, as it will remove all alerts, issues, move mappings, and processing states.
	DropAllData(ctx context.Context) error
}

type Escalation struct {
	// Severity is the new severity of the issue, when the escalation is triggered.
	Severity AlertSeverity `json:"severity"`

	// DelaySeconds is the number of seconds since the issue was created (first alert received),
	// before the escalation is triggered.
	DelaySeconds int `json:"delaySeconds"`

	// SlackMentions is a list of Slack mentions that should be added to the Slack post when the escalation is triggered.
	SlackMentions []string `json:"slackMentions"`

	// MoveToChannel is the ID or name of the Slack channel where the alert should be moved when the escalation is triggered.
	MoveToChannel string `json:"moveToChannel"`
}

type Field struct {
	// Title is the title of the field. It is automatically truncated at MaxFieldTitleLength characters.
	Title string `json:"title"`

	// Value is the value of the field. It is automatically truncated at MaxFieldValueLength characters.
	Value string `json:"value"`
}

type FifoQueueItem struct {
	// MessageID is the unique identifier of the message (as defined by the queue implementation).
	MessageID string

	// SlackChannelID is the ID of the Slack channel to which the message is related.
	SlackChannelID string

	// ReceiveTimestamp is the time when the message was received from the queue.
	ReceiveTimestamp time.Time

	// Body is the body of the message.
	Body string

	// Ack acknowledges the successful processing of the message, effectively removing it from the queue.
	// This function cannot be nil.
	//
	// Ack does not accept a context parameter because acknowledgment is a commitment that must complete
	// regardless of the caller's context state. Each queue implementation is responsible for managing
	// its own timeouts and retry logic internally.
	Ack func()

	// Nack negatively acknowledges the processing of the message, thus making it available for reprocessing.
	// This function cannot be nil.
	//
	// Nack does not accept a context parameter because negative acknowledgment is a commitment that must
	// complete regardless of the caller's context state. Each queue implementation is responsible for
	// managing its own timeouts and retry logic internally.
	Nack func()
}

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

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

type Issue interface {
	json.Marshaler

	// ChannelID returns the Slack channel ID that this issue belongs to.
	ChannelID() string

	// UniqueID returns a unique and deterministic ID for this issue, for database/storage purposes.
	// The ID is based on certain issue fields, and is base64 encoded to ensure it is safe for use in URLs and as a database key.
	UniqueID() string

	// GetCorrelationID returns the correlation ID for this issue.
	// The correlation ID is used to group related alerts together, and may or may not be client defined.
	// It is not guaranteed to be unique across all issues, even in the same channel, and *cannot* be used as a unique issue identifier.
	// It is not URL safe, and should thus be encoded before being used in URLs or as part of a database key.
	GetCorrelationID() string

	// IsOpen returns true if this issue is currently open (i.e. not archived).
	// A resolved issue is still considered open until it is archived.
	IsOpen() bool

	// CurrentPostID returns the current Slack post ID associated with this issue.
	// The value may change over time as the issue is updated.
	// If the issue has no current post, it returns an empty string.
	CurrentPostID() string
}

type Logger interface {
	Debug(msg string)
	Debugf(format string, args ...any)
	Info(msg string)
	Infof(format string, args ...any)
	Error(msg string)
	Errorf(format string, args ...any)
	WithField(key string, value any) Logger
	WithFields(fields map[string]any) Logger
}

type Metrics interface {
	// RegisterCounter registers a counter metric with the given name, help text, and optional labels.
	RegisterCounter(name, help string, labels ...string)

	// RegisterGauge registers a gauge metric with the given name, help text, and optional labels.
	RegisterGauge(name, help string, labels ...string)

	// RegisterHistogram registers a histogram metric with the given name, help text, buckets, and optional labels.
	RegisterHistogram(name, help string, buckets []float64, labels ...string)

	// Add adds the given value to the specified counter metric, with optional label values.
	Add(name string, value float64, labelValues ...string)

	// Inc increments the specified counter metric by 1, with optional label values.
	Inc(name string, labelValues ...string)

	// Set sets the specified gauge metric to the given value, with optional label values.
	Set(name string, value float64, labelValues ...string)

	// Observe records an observation for the specified histogram metric, with optional label values.
	Observe(name string, value float64, labelValues ...string)
}

type MoveMapping interface {
	json.Marshaler

	// ChannelID returns the Slack channel ID that this move mapping belongs to (i.e. the channel where the move was initiated).
	ChannelID() string

	// UniqueID returns a unique and deterministic ID for this move mapping, for database/storage purposes.
	// The ID is based on the original channel and the correlation ID, and is base64 encoded to ensure it is safe for use in URLs and as a database key.
	UniqueID() string

	// GetCorrelationID returns the correlation ID that this move mapping is associated with, for the given channel.
	// It is not URL safe, and should thus be encoded before being used in URLs or as part of a database key.
	GetCorrelationID() string
}

type NoopLogger struct{}

type NoopMetrics struct{}

type Webhook struct {
	// ID is the unique identifier for this webhook within the alert.
	// It must be unique among all webhooks in the same alert.
	// Maximum length: MaxWebhookIDLength characters.
	ID string `json:"id"`

	// URL specifies the target for the webhook when the button is clicked.
	// For HTTP webhooks, this must be a valid absolute URL starting with http:// or https://.
	// For custom webhook handlers registered in the Slack Manager app, this can be an arbitrary
	// ASCII string identifier that the handler recognizes.
	// The field name "URL" is retained for backwards compatibility.
	// Maximum length: MaxWebhookURLLength characters.
	URL string `json:"url"`

	// ConfirmationText is the text displayed in a confirmation dialog before triggering the webhook.
	// If empty, no confirmation dialog is shown and the webhook is triggered immediately.
	// Maximum length: MaxWebhookConfirmationTextLength characters.
	ConfirmationText string `json:"confirmationText"`

	// ButtonText is the label displayed on the button in Slack.
	// This field is required.
	// Maximum length: MaxWebhookButtonTextLength characters.
	ButtonText string `json:"buttonText"`

	// ButtonStyle determines the visual appearance of the button in Slack.
	// Valid values are defined by WebhookButtonStyle constants.
	// If empty, the default Slack button style is used.
	ButtonStyle WebhookButtonStyle `json:"buttonStyle"`

	// AccessLevel controls who can click this webhook button.
	// Valid values are defined by WebhookAccessLevel constants.
	// If empty, anyone in the channel can trigger the webhook.
	AccessLevel WebhookAccessLevel `json:"accessLevel"`

	// DisplayMode controls when the webhook button is visible.
	// Valid values are defined by WebhookDisplayMode constants.
	// If empty, the button is always visible.
	DisplayMode WebhookDisplayMode `json:"displayMode"`

	// Payload is a map of key-value pairs sent in the HTTP POST body when the webhook is triggered.
	// Alert metadata and input values are merged into this payload.
	// Maximum of MaxWebhookPayloadCount items.
	Payload map[string]any `json:"payload"`

	// PlainTextInput defines text input fields shown in the webhook's modal dialog.
	// User-entered values are included in the webhook payload.
	// Maximum of MaxWebhookPlainTextInputCount inputs.
	PlainTextInput []*WebhookPlainTextInput `json:"plainTextInput"`

	// CheckboxInput defines checkbox groups shown in the webhook's modal dialog.
	// Selected values are included in the webhook payload.
	// Maximum of MaxWebhookCheckboxInputCount inputs.
	CheckboxInput []*WebhookCheckboxInput `json:"checkboxInput"`
}

type WebhookAccessLevel string

type WebhookButtonStyle string

type WebhookCallback struct {
	ID            string              `json:"id"`
	UserID        string              `json:"userId"`
	UserRealName  string              `json:"userRealName"`
	ChannelID     string              `json:"channelId"`
	MessageID     string              `json:"messageId"`
	Timestamp     time.Time           `json:"timestamp"`
	Input         map[string]string   `json:"input"`
	CheckboxInput map[string][]string `json:"checkboxInput"`
	Payload       map[string]any      `json:"payload"`
}

type WebhookCheckboxInput struct {
	// ID is the unique identifier for this checkbox group.
	// It must be unique among all inputs (both text and checkbox) in the same webhook.
	// The ID is used as the key in the webhook payload.
	// Maximum length: MaxWebhookInputIDLength characters.
	ID string `json:"id"`

	// Label is the text displayed above the checkbox group.
	// Maximum length: MaxWebhookInputLabelLength characters.
	Label string `json:"label"`

	// Options is the list of checkbox options available in this group.
	// Maximum of MaxWebhookCheckboxOptionCount options.
	Options []*WebhookCheckboxOption `json:"options"`
}

type WebhookCheckboxOption struct {
	// Value is the value included in the webhook payload when this option is selected.
	// Must be unique among all options in the same checkbox group.
	// Maximum length: MaxCheckboxOptionValueLength characters.
	Value string `json:"value"`

	// Text is the label displayed next to the checkbox.
	// Maximum length: MaxWebhookCheckboxOptionTextLength characters.
	Text string `json:"text"`

	// Selected determines whether this checkbox is pre-selected when the modal opens.
	Selected bool `json:"selected"`
}

type WebhookDisplayMode string

type WebhookPlainTextInput struct {
	// ID is the unique identifier for this input field.
	// It must be unique among all inputs (both text and checkbox) in the same webhook.
	// The ID is used as the key in the webhook payload.
	// Maximum length: MaxWebhookInputIDLength characters.
	ID string `json:"id"`

	// Description is the placeholder text shown in the input field before the user types.
	// Maximum length: MaxWebhookInputDescriptionLength characters.
	Description string `json:"description"`

	// MinLength is the minimum number of characters required for the input.
	// Must be >= 0 and <= MaxLength.
	MinLength int `json:"minLength"`

	// MaxLength is the maximum number of characters allowed for the input.
	// Must be >= MinLength and <= MaxWebhookInputTextLength.
	MaxLength int `json:"maxLength"`

	// Multiline determines whether the input field allows multiple lines of text.
	// If true, a larger textarea is shown instead of a single-line input.
	Multiline bool `json:"multiline"`

	// InitialValue is the default text pre-filled in the input field.
	// Must satisfy the MinLength and MaxLength constraints.
	InitialValue string `json:"initialValue"`
}