Documentation
¶
Overview ¶
Package notify dispatches user notifications across multiple channels (Web Push, Mail/SMTP, ntfy) and schedules daily application summaries (#38).
Index ¶
- Variables
- type Activity
- type ActivityItem
- type ActivityKind
- type DailyStats
- type EmailClient
- type Event
- type Notification
- type NtfyClient
- type Preferences
- type Priority
- type Service
- func (s *Service) Activity(ctx context.Context, userID uuid.UUID, before time.Time, limit int) (Activity, error)
- func (s *Service) CheckAndSendDailySummaries(ctx context.Context) (int, error)
- func (s *Service) GetPreferences(ctx context.Context, userID uuid.UUID) (Preferences, error)
- func (s *Service) MarkRead(ctx context.Context, userID uuid.UUID) error
- func (s *Service) Notify(ctx context.Context, n Notification) error
- func (s *Service) SavePreferences(ctx context.Context, prefs Preferences) error
- func (s *Service) SendDailySummary(ctx context.Context, userID uuid.UUID) error
- func (s *Service) SendTestNotification(ctx context.Context, userID uuid.UUID) error
- func (s *Service) SetLocation(loc *time.Location)
- func (s *Service) SetNow(now func() time.Time)
- type Store
- type WebPushClient
Constants ¶
This section is empty.
Variables ¶
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.
var ErrInvalidPreferences = errors.New("invalid notification preferences")
ErrInvalidPreferences reports validation failure in notification preferences.
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 (ActivityItem) Link ¶
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 ¶
EmailClient sends email notifications.
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 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 ¶
CheckAndSendDailySummaries checks all users and delivers summaries that are due.
func (*Service) GetPreferences ¶
GetPreferences returns user notification preferences, falling back to defaults if not set.
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 ¶
SendDailySummary aggregates stats and sends the 24h summary notification to a user.
func (*Service) SendTestNotification ¶
SendTestNotification sends an immediate test notification to verify all channels.
func (*Service) SetLocation ¶
SetLocation makes daily summaries and quiet hours follow the clock of loc instead of the server's.
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.
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. |