services

type AIService interface {
	// IsEnabled returns true if the AI service is properly configured.
	IsEnabled() bool

	// Reload reinitialises the LLM clients with the given provider and credentials.
	// Passing an empty apiKey (for cloud providers) or empty ollamaBaseURL disables AI features.
	Reload(provider, apiKey, model, ollamaBaseURL string)

	// GenerateSummary generates a concise incident summary using all available context.
	// slackMessages should be the plain-text messages from the incident Slack thread.
	// Pass an empty slice when Slack is not configured or the channel has no messages.
	GenerateSummary(ctx context.Context, incident *models.Incident, timeline []models.TimelineEntry, alerts []models.Alert, slackMessages []string) (string, error)

	// GenerateHandoffDigest generates a structured shift handoff document.
	// Suitable for posting to Slack or displaying in the UI at shift change.
	GenerateHandoffDigest(ctx context.Context, incident *models.Incident, timeline []models.TimelineEntry, alerts []models.Alert) (string, error)

	// GeneratePostMortem generates a full post-mortem document in Markdown.
	// sections is the ordered list of section names from the chosen template.
	// Uses a higher token budget than summary generation.
	GeneratePostMortem(ctx context.Context, incident *models.Incident, timeline []models.TimelineEntry, alerts []models.Alert, sections []string) (string, error)

	// EnhancePostMortem improves an existing post-mortem draft for clarity,
	// structure, and completeness while preserving all factual details.
	EnhancePostMortem(ctx context.Context, content string) (string, error)

	// EnhanceIncidentDraft converts a rough user brief into a polished incident
	// title and summary. Returns structured title + summary strings.
	EnhanceIncidentDraft(ctx context.Context, brief string) (title, summary string, err error)

	// AnswerQuestion answers a natural-language question asked in a Slack channel.
	// postMortems maps "INC-NNN" to the full post-mortem markdown for that incident.
	// Returns a Slack-formatted reply (mrkdwn).
	AnswerQuestion(ctx context.Context, question string, current *models.Incident, similar []models.Incident, postMortems map[string]string) (string, error)
}

type AlertLookupFunc func(id uuid.UUID) (*models.Alert, error)

type AlertService interface {
	// ProcessAlertmanagerPayload processes Prometheus Alertmanager webhooks (legacy method for v0.1 compatibility)
	ProcessAlertmanagerPayload(payload *webhooks.AlertmanagerPayload) (*ProcessingResult, error)

	// ProcessNormalizedAlerts processes alerts from any source after normalization (v0.3+)
	ProcessNormalizedAlerts(alerts []webhooks.NormalizedAlert) (*ProcessingResult, error)

	// SetGroupingEngine sets the grouping engine for alert deduplication and grouping (v0.3+)
	SetGroupingEngine(engine GroupingEngine)

	// SetRoutingEngine sets the routing engine for alert routing decisions (v0.3+)
	SetRoutingEngine(engine RoutingEngine)

	// SetEscalationEngine sets the escalation engine for alert escalation (v0.5+)
	SetEscalationEngine(engine EscalationEngine)

	// SetEscalationRepos provides repos for the severity-rule and global-fallback
	// steps in the escalation policy resolution chain.
	SetEscalationRepos(escalationRepo repository.EscalationPolicyRepository, systemSettingsRepo repository.SystemSettingsRepository)
}

type AuthService interface {
	UpsertFromSAML(ctx context.Context, subject, issuer, email, name string) error
}

type BotAccount struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type BotActivity struct {
	Type         string          `json:"type"`
	ID           string          `json:"id"`
	Text         string          `json:"text"`
	ChannelID    string          `json:"channelId"` // "msteams"
	Conversation BotConversation `json:"conversation"`
	From         BotAccount      `json:"from"`
	Recipient    BotAccount      `json:"recipient"`
	ServiceURL   string          `json:"serviceUrl"`
	ChannelData  json.RawMessage `json:"channelData"`
}

type BotConversation struct {
	ID      string `json:"id"`
	IsGroup bool   `json:"isGroup"`
}

type BuiltInTemplateError struct{ Name string }

type Channel struct {
	// ID is the platform-specific channel identifier
	// Examples: "C01234567" (Slack), "19:xxx@thread.tacv2" (Teams)
	ID string

	// Name is the human-readable channel name
	// Examples: "inc-042-api-gateway-errors"
	Name string

	// URL is the direct link to the channel in the platform's web/app UI
	URL string
}

type ChatService interface {
	// CreateChannel creates a new channel with the given name and description.
	// The channel should be public by default.
	//
	// Parameters:
	//   - name: The channel name (will be sanitized by implementation)
	//   - description: Optional channel description/topic
	//
	// Returns:
	//   - Channel with ID, Name, and URL populated
	//   - Error if creation fails (auth, network, name collision, etc.)
	//
	// Thread-safe: Yes
	CreateChannel(name, description string) (*Channel, error)

	// PostMessage posts a message to the specified channel.
	//
	// Parameters:
	//   - channelID: The platform-specific channel identifier
	//   - message: The message to post (text + optional blocks)
	//
	// Returns:
	//   - Message timestamp/ID for future updates
	//   - Error if posting fails (invalid channel, permissions, rate limits, network, etc.)
	//
	// Thread-safe: Yes
	PostMessage(channelID string, message Message) (string, error)

	// UpdateMessage updates an existing message in a channel.
	//
	// Parameters:
	//   - channelID: The platform-specific channel identifier
	//   - messageTS: The message timestamp/ID returned from PostMessage
	//   - message: The updated message content
	//
	// Returns:
	//   - Error if update fails (message not found, invalid channel, permissions, rate limits, network, etc.)
	//
	// Thread-safe: Yes
	UpdateMessage(channelID, messageTS string, message Message) error

	// ArchiveChannel archives the specified channel.
	// Archived channels are read-only and hidden from active channel lists.
	//
	// Parameters:
	//   - channelID: The platform-specific channel identifier
	//
	// Returns:
	//   - Error if archiving fails (channel not found, permissions, already archived, network, etc.)
	//
	// Thread-safe: Yes
	ArchiveChannel(channelID string) error

	// InviteUsers invites users to a channel.
	// Used for auto-inviting specific users to incident channels.
	//
	// Parameters:
	//   - channelID: Platform-specific channel identifier
	//   - userIDs: List of platform-specific user identifiers
	//
	// Returns:
	//   - Error if invitation fails (permissions, invalid IDs, rate limits, network)
	//
	// Implementation notes:
	//   - Empty userIDs list should return nil (no-op)
	//   - Handle rate limits with exponential backoff
	//   - Partial failures should return descriptive error
	//
	// Thread-safe: Yes
	InviteUsers(channelID string, userIDs []string) error

	// SendDirectMessage sends a direct message to a user by their display name or email.
	// The implementation is responsible for resolving the username to a platform user ID
	// and opening a DM conversation.
	//
	// Parameters:
	//   - username: Display name or email of the recipient (as stored in ScheduleParticipant.UserName)
	//   - message: The message to send
	//
	// Returns:
	//   - Error if lookup, DM open, or send fails
	//   - Graceful no-op (returns nil) if Slack is not configured
	//
	// Thread-safe: Yes
	SendDirectMessage(username string, message Message) error

	// GetThreadMessages fetches the plain-text messages from a channel thread.
	// Used to provide Slack conversation context to the AI summarizer.
	//
	// Parameters:
	//   - channelID: The platform-specific channel identifier
	//   - threadTS: The parent message timestamp identifying the thread
	//
	// Returns:
	//   - Slice of plain-text message strings (author + text, one per message)
	//   - Empty slice (not error) if the thread is empty or has no text messages
	//   - Error only for auth/network failures
	//
	// Thread-safe: Yes
	GetThreadMessages(channelID, threadTS string) ([]string, error)
}

type CreateActionItemParams struct {
	Title   string
	Owner   *string
	DueDate *time.Time
}

type CreateCommentParams struct {
	AuthorID   string
	AuthorName string
	Content    string
}

type CreateIncidentParams struct {
	Title       string
	Severity    models.IncidentSeverity
	Description string
	CreatedBy   string // "user", "system", "api"
	AIEnabled   bool   // Controls whether AI agents process this incident. Defaults to true.
}

type CreatePostMortemTemplateParams struct {
	Name        string
	Description string
	Sections    []string
}

type CreateTimelineEntryParams struct {
	IncidentID uuid.UUID
	Type       string
	Content    models.JSONB
	ActorType  string
	ActorID    string
}

type EscalationEngine interface {
	TriggerEscalation(alert *models.Alert) error
	TriggerIncidentEscalation(incidentID uuid.UUID, policyID uuid.UUID) error
	EvaluateEscalations() error
	AcknowledgeAlert(alertID uuid.UUID, by string, via models.AcknowledgmentVia) error
	MarkAlertCompleted(alertID uuid.UUID) error
}

type EscalationNotifier interface {
	// SendEscalationDM sends a direct message to userID about the given alert
	// at the specified escalation tier.
	SendEscalationDM(userID string, alert *models.Alert, tierIndex int) error
}

type GroupingAction string

type GroupingDecision struct {
	// Action specifies what to do with this alert
	Action GroupingAction

	// IncidentID is the existing incident to link to (only set if Action = GroupActionLinkToExisting)
	IncidentID *uuid.UUID

	// RuleName is the name of the rule that matched (empty for default action)
	RuleName string

	// GroupKey is the derived key for this alert group
	GroupKey string
}

type GroupingEngine interface {
	// EvaluateAlert determines if an alert should create a new incident or link to existing
	EvaluateAlert(alert *models.Alert) (*GroupingDecision, error)

	// RefreshRules reloads grouping rules from the database (called on cache expiry)
	RefreshRules() error
}

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

type IncidentService interface {
	// Alert-triggered incident creation
	CreateIncidentFromAlert(alert *models.Alert, aiEnabled bool) (*models.Incident, error)
	CreateIncidentFromAlertWithGrouping(alert *models.Alert, groupKey string, aiEnabled bool) (*models.Incident, error)
	LinkAlertToExistingIncident(alert *models.Alert, incidentID uuid.UUID) error
	ShouldCreateIncident(severity models.AlertSeverity) bool
	CreateSlackChannelForIncident(incident *models.Incident, alerts []models.Alert) error

	// API operations
	ListIncidents(filters repository.IncidentFilters, pagination repository.Pagination) ([]models.Incident, int64, error)
	GetIncident(id uuid.UUID, number int) (*models.Incident, error)
	GetIncidentBySlackChannelID(channelID string) (*models.Incident, error)
	GetIncidentBySlackMessageTS(messageTS string) (*models.Incident, error)
	CreateIncident(params *CreateIncidentParams) (*models.Incident, error)
	UpdateIncident(id uuid.UUID, params *UpdateIncidentParams) (*models.Incident, error)
	AcknowledgeIncident(id uuid.UUID, actorType, actorID string) error
	ResolveIncident(id uuid.UUID, actorType, actorID string) error
	GetIncidentAlerts(incidentID uuid.UUID) ([]models.Alert, error)
	GetIncidentTimeline(incidentID uuid.UUID, pagination repository.Pagination) ([]models.TimelineEntry, int64, error)
	CreateTimelineEntry(params *CreateTimelineEntryParams) (*models.TimelineEntry, error)

	// Generic status transition used by bots/integrations (e.g. Slack reactions).
	UpdateIncidentStatus(id uuid.UUID, status models.IncidentStatus, actorType, actorID string) error

	// Slack notifications
	PostStatusUpdateToSlack(incident *models.Incident, previousStatus, newStatus models.IncidentStatus) error

	// AI features (v0.6+)
	// GenerateAISummary generates an AI summary for an incident and persists it.
	GenerateAISummary(incident *models.Incident) (string, error)
	// GenerateHandoffDigest generates a shift handoff digest for an incident (not persisted).
	GenerateHandoffDigest(incident *models.Incident) (string, error)
}

type LocalAuthService interface {
	Login(email, password string) (*models.LocalSession, error)
	Logout(token string) error
	GetSessionUser(token string) (*models.User, error)
	CreateUser(email, name, password string, role models.UserRole) (*models.User, string, error)
	UpdateUser(id uuid.UUID, name string, role models.UserRole, newPassword string) error
	ResetPassword(id uuid.UUID) (string, error)
	DeactivateUser(id uuid.UUID) error
	GetUser(id uuid.UUID) (*models.User, error)
	ListUsers() ([]models.User, error)
	CountUsers() (int64, error)
	CountAdmins() (int64, error)
	// GetUserByEmail returns the user with the given email, regardless of auth source.
	// Used by middleware to resolve a SAML JWT session to a DB user record.
	GetUserByEmail(email string) (*models.User, error)
	// LoginByUserID creates a session for the given user ID without a password check.
	// Used by Slack OAuth login after the user's identity is verified by Slack.
	LoginByUserID(id uuid.UUID) (*models.LocalSession, error)
	// UpdateUserSlackID sets or clears the Slack member ID for a user.
	// Pass nil to clear, or a pointer to an ID string like "U0AJLLY3678".
	UpdateUserSlackID(id uuid.UUID, slackUserID *string) error
	// UpdateUserTeamsID sets or clears the Azure AD Object ID for a user.
	// Pass nil to clear, or a pointer to the AAD Object ID string.
	UpdateUserTeamsID(id uuid.UUID, teamsUserID *string) error
}

type Message struct {
	// Text is the plain text fallback content
	// Required for notifications and accessibility
	Text string

	// Blocks contains platform-specific rich content blocks
	// For Slack: []slack.Block
	// For Teams: []teams.MessageBlock
	// Stored as []interface{} to remain platform-agnostic
	Blocks []interface{}

	// ThreadTS is the parent message timestamp for threaded replies
	// Empty string for top-level messages
	ThreadTS string
}

type PostMortemService interface {
	// Templates
	ListTemplates() ([]models.PostMortemTemplate, error)
	GetTemplate(id uuid.UUID) (*models.PostMortemTemplate, error)
	CreateTemplate(params *CreatePostMortemTemplateParams) (*models.PostMortemTemplate, error)
	UpdateTemplate(id uuid.UUID, params *UpdatePostMortemTemplateParams) (*models.PostMortemTemplate, error)
	DeleteTemplate(id uuid.UUID) error

	// Post-mortems
	GetPostMortem(incidentID uuid.UUID) (*models.PostMortem, error)
	GeneratePostMortem(incident *models.Incident, templateID *uuid.UUID, createdByID string) (*models.PostMortem, error)
	UpdatePostMortem(id uuid.UUID, params *UpdatePostMortemParams) (*models.PostMortem, error)

	// Post-mortem manual creation
	CreatePostMortem(incidentID uuid.UUID, createdByID string) (*models.PostMortem, error)

	// AI enhance
	EnhancePostMortem(pm *models.PostMortem, content string) (*models.PostMortem, error)

	// Comments
	ListComments(postMortemID uuid.UUID) ([]models.PostMortemComment, error)
	CreateComment(postMortemID uuid.UUID, params *CreateCommentParams) (*models.PostMortemComment, error)
	DeleteComment(id uuid.UUID) error

	// Action items
	CreateActionItem(postMortemID uuid.UUID, params *CreateActionItemParams) (*models.ActionItem, error)
	UpdateActionItem(id uuid.UUID, params *UpdateActionItemParams) (*models.ActionItem, error)
	DeleteActionItem(id uuid.UUID) error
}

type ProcessingResult struct {
	Received         int // Total alerts received in payload
	Created          int // New alerts created
	Updated          int // Existing alerts updated
	IncidentsCreated int // New incidents created from alerts
}

type RoutingDecision struct {
	// Suppress means: store the alert but do not create an incident
	Suppress bool

	// SeverityOverride replaces the alert's severity for incident creation (empty = no override)
	SeverityOverride string

	// ChannelOverride replaces the auto-generated Slack channel name suffix (empty = no override)
	ChannelOverride string

	// RuleName is the name of the rule that matched (empty if no rule matched)
	RuleName string

	// EscalationPolicyID is the escalation policy to trigger for this alert (nil = no escalation).
	// Set from the "escalation_policy_id" key in the matching rule's actions JSONB.
	EscalationPolicyID *uuid.UUID

	// AIEnabled controls whether AI agents process the resulting incident.
	// Defaults to true; can be set false via the "ai_enabled" key in the rule's actions JSONB.
	AIEnabled bool
}

type RoutingEngine interface {
	// EvaluateAlert returns the routing decision for a given alert
	EvaluateAlert(alert *models.Alert) (*RoutingDecision, error)

	// RefreshRules reloads routing rules from the database
	RefreshRules() error
}

type ScheduleEvaluator interface {
	// WhoIsOnCall returns the username on call for the given schedule at the given time.
	// Returns ("", nil) if the schedule has no layers/participants configured.
	WhoIsOnCall(scheduleID uuid.UUID, at time.Time) (string, error)

	// GetTimeline returns the on-call schedule broken into contiguous segments
	// for the window [from, to). Defaults to next 7 days if from/to are zero.
	GetTimeline(scheduleID uuid.UUID, from, to time.Time) ([]TimelineSegment, error)

	// GetLayerTimelines returns per-layer timelines and the effective merged timeline.
	// layerTimelines is keyed by layer UUID. Each layer is computed independently
	// (no override application). effective is the fully-merged timeline (same as GetTimeline).
	GetLayerTimelines(scheduleID uuid.UUID, from, to time.Time) (layerTimelines map[uuid.UUID][]TimelineSegment, effective []TimelineSegment, err error)
}

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

type SlackMessageBuilder struct{}

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

type TeamMember struct {
	UserID      string // AAD Object ID — stable identifier for proactive DMs (teams_user_id)
	DisplayName string
	Email       string
}

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

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

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

type TimelineSegment struct {
	// Start is the beginning of this segment (inclusive).
	Start time.Time `json:"start"`
	// End is the end of this segment (exclusive).
	End time.Time `json:"end"`
	// UserName is the on-call user for this segment.
	UserName string `json:"user_name"`
	// IsOverride is true when this segment is covered by an explicit override.
	IsOverride bool `json:"is_override"`
	// LayerID is the layer this segment belongs to. nil for effective/merged timeline.
	LayerID *uuid.UUID `json:"layer_id,omitempty"`
}

type UpdateActionItemParams struct {
	Title   *string
	Owner   *string
	DueDate *time.Time
	Status  *models.ActionItemStatus
}

type UpdateIncidentParams struct {
	Status      models.IncidentStatus
	Severity    models.IncidentSeverity
	Summary     string
	UpdatedBy   string
	ClientIP    string     // For audit logging
	AIEnabled   *bool      // Controls whether AI agents process this incident. nil = no change.
	CommanderID *uuid.UUID // nil = no change
}

type UpdatePostMortemParams struct {
	Content *string
	Status  *models.PostMortemStatus
}

type UpdatePostMortemTemplateParams struct {
	Name        *string
	Description *string
	Sections    []string
}