// Package notifications owns the Phase 6 push pipeline: typed Notification
// shape, per-channel delivery (dashboard, web push, Discord webhook, ntfy),
// and the dispatcher that fans out to operator-configured channels.
package notifications

import (
	"context"
	"time"
)

// Severity is one of the standard four. Channels may render differently per
// severity (Discord colors, ntfy priority headers, push notification urgency).
type Severity string

const (
	SeverityInfo     Severity = "info"
	SeverityWarning  Severity = "warning"
	SeverityCritical Severity = "critical"
	SeverityDebug    Severity = "debug"
)

// Notification is the typed envelope a Trigger emits and the Dispatcher
// delivers. RuleID may be zero (e.g. the operator-fired test notification).
type Notification struct {
	RuleID    int64    // 0 = ad-hoc, e.g. operator test
	RuleName  string   // operator-readable; included in audit log + Discord embeds
	Title     string
	Body      string
	Severity  Severity
	URL       string   // deep-link the operator can tap (e.g. /trackers/mam)
	Data      map[string]any // structured payload available in service worker
	Timestamp time.Time
}

// Channel is the contract every delivery target implements. Channels are
// stateless: configuration arrives via the dispatcher's per-rule channel
// config map.
type Channel interface {
	// Name returns the channel identifier matching `channels:` in YAML.
	Name() string

	// Send delivers n. cfg is the per-rule channel configuration (e.g. a
	// Discord webhook URL or an ntfy topic). Returns (count_delivered, err).
	// An error from one channel must not stop other channels in the same
	// dispatch — the Dispatcher fans out per-channel.
	Send(ctx context.Context, n Notification, cfg map[string]any) (int, error)
}