notify

package
v0.0.0-...-bdfed93 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package notify dispatches user notifications across multiple channels (Web Push, Mail/SMTP, ntfy) and schedules daily application summaries (#38).

Index

Constants

This section is empty.

Variables

View Source
var ActivityStates = []string{"needs_input", "submitted", "confirmed", "interview", "offer", "rejected", "parked",
	"failed", "submit_unknown"}

ActivityStates are the application states the activity feed reports: the ones a user wants to hear about.

View Source
var ErrInvalidPreferences = errors.New("invalid notification preferences")

ErrInvalidPreferences reports validation failure in notification preferences.

View Source
var ErrNotFound = errors.New("notification preferences not found")

ErrNotFound indicates notification preferences were not found.

Functions

This section is empty.

Types

type Activity

type Activity struct {
	Items  []ActivityItem
	Unread int
	More   bool // older entries exist
}

Activity is a page of the feed and how many entries are unread.

type ActivityItem

type ActivityItem struct {
	ID            string // unique within its kind
	Kind          ActivityKind
	State         string // the new state, or the suggested one
	ApplicationID uuid.UUID
	Title         string
	Company       string
	At            time.Time
	Unread        bool
}

ActivityItem is one entry of the feed.

func (a ActivityItem) Link() string

Link is where the entry leads: the inbox for a run that waits, the application otherwise.

type ActivityKind

type ActivityKind string

ActivityKind tells a state change from a status suggestion read from the mailbox.

const (
	KindState      ActivityKind = "state"
	KindSuggestion ActivityKind = "suggestion"
)

type DailyStats

type DailyStats struct {
	UserID             uuid.UUID
	PeriodStart        time.Time
	PeriodEnd          time.Time
	SubmittedCount     int64
	NeedsInputCount    int64
	PendingSuggestions int64
	PendingApprovals   int64
	Confirmations      int64
	Invitations        int64
	Rejections         int64
}

DailyStats represents aggregated statistics for a user's 24h summary.

func (DailyStats) FormatSummary

func (s DailyStats) FormatSummary(l i18n.Locale) (title, body string)

FormatSummary formats the daily summary in the given language for email or push notifications.

type EmailClient

type EmailClient interface {
	SendEmail(ctx context.Context, to, subject, body string) error
}

EmailClient sends email notifications.

type Event

type Event string

Event classifies the trigger for a notification.

const (
	EventHandoffClosing   Event = "handoff_closing"
	EventNeedsInput       Event = "needs_input"
	EventStatusSuggestion Event = "status_suggestion"
	EventApprovalQueued   Event = "approval_queued"
	EventDailySummary     Event = "daily_summary"
	EventSearchAlert      Event = "search_alert"
	EventTest             Event = "test"
)

type Notification

type Notification struct {
	UserID    uuid.UUID
	Event     Event
	Key       string
	Params    map[string]any
	Title     string
	Body      string
	URL       string // relative or absolute click link
	Priority  Priority
	Tags      []string
	CreatedAt time.Time
}

Notification is an outbound message to a user. With Key set, Title and Body come from the catalog ("notify.<key>.title", "notify.<key>.body") in the user's language, filled with Params.

type NtfyClient

type NtfyClient interface {
	SendNtfy(ctx context.Context, serverURL, topic, token string, n Notification) error
}

NtfyClient posts notifications to an ntfy topic.

type Preferences

type Preferences struct {
	UserID              uuid.UUID
	EmailEnabled        bool
	EmailAddress        string // unused: mail goes to the verified account address only
	WebPushEnabled      bool
	NtfyEnabled         bool
	NtfyURL             string
	NtfyTopic           string
	NtfyToken           string
	DailySummaryEnabled bool
	DailySummaryTime    string // "HH:MM", defaults to "18:00"
	LastSummaryAt       *time.Time
	QuietHoursEnabled   bool
	QuietHoursStart     string // "HH:MM", defaults to "22:00"
	QuietHoursEnd       string // "HH:MM", defaults to "08:00"
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

Preferences holds user notification settings.

func DefaultPreferences

func DefaultPreferences(userID uuid.UUID, fallbackEmail string) Preferences

DefaultPreferences returns standard preferences for a user.

func (Preferences) InQuietHours

func (p Preferences) InQuietHours(t time.Time) bool

InQuietHours returns true if the given time falls within the configured quiet hours.

func (Preferences) Invalid

func (p Preferences) Invalid() []string

Invalid lists the fields that cannot be saved: an enabled ntfy channel needs a topic of letters, digits, - and _, and the summary and quiet hour times are HH:MM.

func (Preferences) IsSummaryDue

func (p Preferences) IsSummaryDue(now time.Time) bool

IsSummaryDue returns true if daily summary is enabled and due at current time.

type Priority

type Priority int

Priority levels for notifications.

const (
	PriorityLow    Priority = 2
	PriorityNormal Priority = 3
	PriorityHigh   Priority = 4
	PriorityUrgent Priority = 5
)

type Service

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

Service dispatches notifications and generates daily summaries.

func NewService

func NewService(store Store, ntfy NtfyClient, email EmailClient, webpush WebPushClient, baseURL string, logger *slog.Logger) *Service

NewService returns a notification service.

func (*Service) Activity

func (s *Service) Activity(ctx context.Context, userID uuid.UUID, before time.Time, limit int) (Activity, error)

Activity returns the newest entries before the given time (zero: now), at most limit.

func (*Service) CheckAndSendDailySummaries

func (s *Service) CheckAndSendDailySummaries(ctx context.Context) (int, error)

CheckAndSendDailySummaries checks all users and delivers summaries that are due.

func (*Service) GetPreferences

func (s *Service) GetPreferences(ctx context.Context, userID uuid.UUID) (Preferences, error)

GetPreferences returns user notification preferences, falling back to defaults if not set.

func (*Service) MarkRead

func (s *Service) MarkRead(ctx context.Context, userID uuid.UUID) error

MarkRead marks every entry up to now as read.

func (*Service) Notify

func (s *Service) Notify(ctx context.Context, n Notification) error

Notify delivers a notification across all enabled channels for the recipient.

func (*Service) SavePreferences

func (s *Service) SavePreferences(ctx context.Context, prefs Preferences) error

SavePreferences persists user notification preferences.

func (*Service) SendDailySummary

func (s *Service) SendDailySummary(ctx context.Context, userID uuid.UUID) error

SendDailySummary aggregates stats and sends the 24h summary notification to a user.

func (*Service) SendTestNotification

func (s *Service) SendTestNotification(ctx context.Context, userID uuid.UUID) error

SendTestNotification sends an immediate test notification to verify all channels.

func (*Service) SetLocation

func (s *Service) SetLocation(loc *time.Location)

SetLocation makes daily summaries and quiet hours follow the clock of loc instead of the server's.

func (*Service) SetNow

func (s *Service) SetNow(now func() time.Time)

SetNow overrides the time source (used in tests).

type Store

type Store interface {
	GetPreferences(ctx context.Context, userID uuid.UUID) (Preferences, error)
	SavePreferences(ctx context.Context, prefs Preferences) error
	ListDailySummaryCandidates(ctx context.Context) ([]Preferences, error)
	UpdateLastSummaryAt(ctx context.Context, userID uuid.UUID, at time.Time) error
	GetUserEmail(ctx context.Context, userID uuid.UUID) (string, error)
	UserLocale(ctx context.Context, userID uuid.UUID) (i18n.Locale, error)
	// Activity returns the newest feed entries before a time; CountActivitySince counts the entries after one.
	Activity(ctx context.Context, userID uuid.UUID, before time.Time, limit int) ([]ActivityItem, error)
	CountActivitySince(ctx context.Context, userID uuid.UUID, since time.Time) (int, error)
	// SeenAt is when the user last marked the feed read (zero: never); MarkSeen moves it forward only.
	SeenAt(ctx context.Context, userID uuid.UUID) (time.Time, error)
	MarkSeen(ctx context.Context, userID uuid.UUID, at time.Time) error
	DailyStats(ctx context.Context, userID uuid.UUID, since time.Time) (DailyStats, error)
}

Store persists user notification preferences and reads daily summary statistics.

type WebPushClient

type WebPushClient interface {
	SendWebPush(ctx context.Context, userID uuid.UUID, title, body, url string) error
}

WebPushClient sends Web Push notifications.

Directories

Path Synopsis
adapters
mail
Package mail adapts platform/mail to notify.EmailClient.
Package mail adapts platform/mail to notify.EmailClient.
ntfy
Package ntfy publishes notifications to an ntfy.sh instance or self-hosted ntfy server.
Package ntfy publishes notifications to an ntfy.sh instance or self-hosted ntfy server.
pgstore
Package pgstore implements notify.Store on PostgreSQL.
Package pgstore implements notify.Store on PostgreSQL.
webpush
Package webpush adapts platform/webpush to notify.WebPushClient.
Package webpush adapts platform/webpush to notify.WebPushClient.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址