Status: ✅ Implemented | Extensible notification system with Discord, ntfy, and Pushover support
Sends notifications for audiobook request events (pending approval, approved, available, error) to configured backends. Non-blocking, atomic per-backend failure handling. Proper notification timing for all request flows including interactive search.
- Backends: Apprise (API), Discord (webhooks), ntfy (API), Pushover (API)
- Events: request_pending_approval, request_approved, request_grabbed, request_available, request_error, issue_reported
- Encryption: AES-256-GCM for sensitive config (webhook URLs, API keys, notification URLs)
- Delivery: Async via Bull job queue (priority 5)
- Failure Handling: Non-blocking, Promise.allSettled (one backend fails, others succeed)
model NotificationBackend {
id String @id @default(uuid())
type String // 'apprise' | 'discord' | 'ntfy' | 'pushover'
name String // User-friendly label
config Json // Encrypted sensitive values
events Json // Array of subscribed events
enabled Boolean @default(true)
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}| Event | Trigger | Notification Sent When |
|---|---|---|
| request_pending_approval | User creates request | Request needs admin approval |
| request_approved | Admin approves OR auto-approval | Request approved (manual or auto) |
| request_grabbed | Torrent/NZB added to download client | Download handed off to configured download client (title resolves by type) — opt-in: existing backends do not auto-subscribe; enable in Settings |
| request_available | Plex/ABS scan or ebook download completes | Request available (title resolves by type) |
| request_error | Download/import fails | Request failed at any stage |
| issue_reported | User reports issue | User reports problem with available audiobook |
Dynamic Titles: Events can define titleByRequestType in notification-events.ts for type-specific titles.
request_grabbed+requestType: 'audiobook'→ "Audiobook Grabbed"request_grabbed+requestType: 'ebook'→ "Ebook Grabbed"request_available+requestType: 'audiobook'→ "Audiobook Available"request_available+requestType: 'ebook'→ "Ebook Available"request_available+ no requestType → "Request Available" (fallback)- Use
getEventTitle(event, requestType?)to resolve titles in providers
Request Creation (POST /api/requests)
- Automatic search, approval needed:
status === 'awaiting_approval'→ request_pending_approval - Automatic search, auto-approved:
status === 'pending'→ request_approved - Interactive search: NO notification yet (deferred until torrent selection)
BookDate Swipe (POST /api/bookdate/swipe)
- Right swipe, approval needed:
status === 'awaiting_approval'→ request_pending_approval - Right swipe, auto-approved:
status === 'pending'→ request_approved
Request with Pre-Selected Torrent (POST /api/audiobooks/request-with-torrent)
- Approval needed:
status === 'awaiting_approval'→ request_pending_approval - Auto-approved:
status === 'downloading'→ request_approved
Torrent Selection for Existing Request (POST /api/requests/[id]/select-torrent)
- Approval needed:
status === 'awaiting_approval'→ request_pending_approval - Auto-approved:
status === 'downloading'→ request_approved
Admin Approval (POST /api/admin/requests/[id]/approve)
- Approve (with or without pre-selected torrent): After job triggered → request_approved
- Deny: No notification
Download Grabbed (processor: download-torrent)
- After
client.addDownload()succeeds andDownloadHistoryrecord created → request_grabbed messagefield:"${torrent.title} via ${indexer} (${clientType})"requestType: fromrequest.type(audiobook/ebook)
Audiobook Available (processors: scan-plex, plex-recently-added)
- After
status: 'available'update → request_available (requestType: 'audiobook') - Includes user info in query (plexUsername)
Ebook Available (processor: organize-files)
- After ebook
status: 'downloaded'(terminal) → request_available (requestType: 'ebook') - Ebooks don't transition to 'available' via Plex matching
Request Error (processors: monitor-download, organize-files)
- After
status: 'failed'orstatus: 'warn'update → request_error - Includes error message in payload
Issue Reported (reported-issue.service.ts)
- After user reports issue with available audiobook → issue_reported
- Payload: issue ID (as requestId), book title/author, reporter username, reason (as message)
Encrypted Values:
- Apprise:
urls,authToken,basicAuthPassword - Discord:
webhookUrl - ntfy:
accessToken - Pushover:
userKey,appToken
Pattern: iv:authTag:encryptedData (base64)
Masking: Sensitive values returned as •••••••• in API responses
Preservation: NotificationService.mergeMaskedSecrets(type, existing, updated) on update: a masked value (MASKED_CONFIG_VALUE = ••••••••) keeps the existing encrypted value
- Providers with
secretBoundUrl(Apprise:serverUrl, no default; ntfy:serverUrl, defaulthttps://ntfy.sh): a kept secret requires the same server URL (isSameServiceUrl; ntfy: empty =https://ntfy.shon both sides) → elsePUTreturns 400{ error: 'ValidationError', message }naming the fields to re-enter, nothing saved - Apprise: an empty or scheme-less
serverUrlwith masked secrets → 400 asking for the fullhttp(s)://URL - Discord, Pushover: no server URL binding
Apprise Basic auth (credentials never in serverUrl): src/lib/services/notification/providers/apprise-credentials.ts
- Fields:
serverUrl(plain, shown),basicAuthUser(plain),basicAuthPassword(sensitive) - On every admin write (POST, PUT, test with
type+config):prepareSubmittedConfig()→ providernormalizeSubmittedConfig()movesuser:pass@out ofserverUrl. Userinfo is %-decoded run by run (decodeUserinfo: a stray%stays as typed, other escapes still decode; a run that is not valid UTF-8 is decoded escape by escape, longest valid sequence first, e.g.^%E2→^%E2, invalid escapes kept as typed). When the URL's password fillsbasicAuthPassword(field empty/missing/mask), the URL's username replacesbasicAuthUsertoo; a typed password wins and the username is then only filled if blank. Then every non-empty, non-mask sensitive value is encrypted (even if it looks like ciphertext: a client-supplied ciphertext is stored as text, never decrypted); a non-text sensitive value → 400"<Label> must be text." serverUrlthat is not an http(s) URL and contains@→ 400 (credentials could not be removed). Notealice:pw@hostparses with schemealice:, so it counts as not http(s)- PUT order: saved config in migrated form (
migrateStoredConfig) → submitted prepared →mergeMaskedSecrets(password is URL-bound like the other secrets) →encryptConfig - Display:
maskConfig()shows a not-yet-migrated row in migrated form (URL without credentials,basicAuthUser,basicAuthPassword: ••••••••); the mask is never placed inside a URL. A stored server URL that is not a valid http(s) URL but contains@(e.g. legacyalice:pw@apprise:8000, which never sent) is shown as the part after the last@only; such rows are not migrated - Startup migration
migrateStoredSecrets()(scheduler init, afterreEncryptUnprotectedBackends(), serially): rows whoseserverUrlhas userinfo → URL stripped, userinfo wins over existing fields, password encrypted (an empty password is never stored); compare-and-swap onupdatedAt; per-row errors logged and skipped; idempotent.reEncryptUnprotectedBackends()is per-row too: a failing row or a non-text sensitive value (skipped, value never logged) doesn't stop the others send(): validatesserverUrlfirst (invalid → generic "The Apprise Server URL is not a valid URL", never echoing it); request URL never carries userinfo; Basic: userinfo still in a not-yet-migrated URL wins over the fields, per part (username, password), the same rule as the migration andmaskConfig, so a send before and after the migration uses the same credentials;authToken(Bearer) wins over Basic- Rollback: older versions read Basic auth only from
serverUrl, so after a downgrade Apprise Basic auth fails until the credentials are re-entered in the URL. Change the Apprise password if DB backups or logs from before the upgrade are kept (they hold it in plaintext)
Apprise (JSON via Apprise API):
- Type: info (pending), success (approved/available), failure (error)
- Modes: Stateless (send URLs directly) or Stateful (use persistent configKey, optional tag filter)
- Endpoint:
{serverUrl}/notify/(stateless) or{serverUrl}/notify/{configKey}(stateful) - Auth: optional Bearer token (
authToken), else optional Basic auth (basicAuthUser/basicAuthPassword) - Format: Event title + book details + user + error (if applicable)
Discord (Rich Embeds):
- Color-coded by event (yellow=pending, green=approved, blue=available, red=error, orange=issue)
- Fields: Title, Author, Requested/Reported By, Error/Reason (if applicable)
- Footer: Request/Issue ID
- Timestamp: Event time
ntfy (JSON Publishing to Base URL):
- Endpoint: POST to base
serverUrl(default: https://ntfy.sh), topic in JSON body - Tags: mailbox_with_mail, white_check_mark, tada, x, triangular_flag_on_post (rendered as emojis by ntfy)
- Priority: Default (3) for pending/approved, High (4) for available/error
- Format: Event title + book details + user + error (if applicable)
- Auth: Optional Bearer token via
accessTokenconfig field - Server: Configurable
serverUrl(default: https://ntfy.sh)
Pushover (Plain Text with Emojis):
- Emojis: 📬 📬 🎉 ❌
- Priority: Normal (0) for pending/approved, High (1) for available/error
- Format: Event title + book details + user + error (if applicable)
GET /api/admin/notifications
- Returns all backends (sensitive values masked)
POST /api/admin/notifications
- Create backend (encrypts sensitive values)
- Body:
{type, name, config, events, enabled}
GET /api/admin/notifications/[id]
- Get single backend (sensitive values masked)
PUT /api/admin/notifications/[id]
- Update backend (masked values kept via
mergeMaskedSecrets, URL-bound for Apprise/ntfy; new values encrypted)
DELETE /api/admin/notifications/[id]
- Delete backend
POST /api/admin/notifications/test
- Test notification (synchronous, not via job queue)
- Body:
{backendId}(stored config) or{type, config}(prepared like a save: normalised, secrets encrypted as text) - Sends test payload: "The Hitchhiker's Guide to the Galaxy" by Douglas Adams
NotificationsTab (src/app/admin/settings/tabs/NotificationsTab)
- Type selector cards (Discord: indigo "D", Pushover: blue "P")
- Configured backends grid (3 columns)
- Backend cards: type icon, name, enabled status, event count, edit/delete actions
- Modal: type-specific forms, event checkboxes, enable toggle, test button
Modal Features:
- Type-first selection (user clicks "Add Discord" or "Add Pushover")
- Password inputs for sensitive values
- Event subscription checkboxes (5 events, default: available + error)
- Test button (sends synchronous test notification)
- Save button (validates and creates/updates backend)
Job Type: send_notification (priority 5, concurrency 5)
Payload:
{
jobId?: string,
event: string,
requestId: string,
title: string,
author: string,
userName: string,
message?: string,
requestType?: string, // 'audiobook' | 'ebook' — drives type-specific titles
timestamp: Date
}Processor: src/lib/processors/send-notification.processor.ts
- Calls NotificationService.sendNotification()
- Non-blocking error handling (logs but doesn't throw)
Queue Method: addNotificationJob(event, requestId, title, author, userName, message?, requestType?)
Provider Pattern: INotificationProvider interface + registry (matches IAuthProvider pattern)
src/lib/services/notification/
INotificationProvider.ts # Interface + shared types
notification.service.ts # Core service with registry
index.ts # Re-exports
providers/
apprise.provider.ts # Apprise API (100+ services)
apprise-credentials.ts # Credentials out of serverUrl (normalise, lift, split)
discord.provider.ts # Discord webhook
ntfy.provider.ts # ntfy API
pushover.provider.ts # Pushover API
Registry: Module-level Map<string, INotificationProvider> with registerProvider() / getProvider()
INotificationProvider interface:
type: string— provider identifier (registry key)sensitiveFields: string[]— fields needing encryption/maskingsecretBoundUrl?: { field, defaultUrl?, credentialKind }— config field holding the server URL the sensitive fields are sent to (Apprise, ntfy)normalizeSubmittedConfig?(config)— normalise an admin-submitted config before merge/encrypt (Apprise: credentials out of the URL); may refuse with an errorliftStoredSecrets?(config)— migrated form of a stored config + plaintext password to encrypt (Apprise legacy URL userinfo), or nullmetadata: ProviderMetadata— self-describing UI/validation metadatasend(config, payload): Promise<void>— receives decrypted config
ProviderMetadata: { type, displayName, description, iconLabel, iconColor, configFields[] }
ProviderConfigField: { name, label, type, required, placeholder?, helpText?, defaultValue?, options? } (helpText shown under the field)
Helper functions (notification.service.ts):
getRegisteredProviderTypes(): string[]— all registered type keysgetAllProviderMetadata(): ProviderMetadata[]— metadata for all providers
Helper functions (notification-events.ts):
getEventMeta(event)— raw event metadata (label, title, emoji, severity, priority)getEventTitle(event, requestType?)— resolved title (checkstitleByRequestTypefirst, falls back totitle)getEventLabel(event)— human-readable label for UI
API Endpoint: GET /api/admin/notifications/providers — returns all provider metadata (admin-only)
Adding New Backend (2 steps):
- Create
providers/email.provider.tsimplementingINotificationProvider:- Set
type = 'email',sensitiveFields = ['smtpPassword'] - Set
metadatawith displayName, description, iconLabel, iconColor, configFields - Implement
send()with email-specific logic
- Set
- Register in
notification.service.ts:registerProvider(new EmailProvider())+ re-export fromindex.ts
No UI changes, no API route changes, no Zod schema changes needed — the UI renders dynamically from provider metadata.
Adding New Event (e.g., download_complete):
- Add entry to
NOTIFICATION_EVENTSinnotification-events.ts(label, title, emoji, severity, priority) - Optionally add
titleByRequestTypefor type-specific titles - Add trigger point in processor, passing
requestTypeif relevant - Providers auto-resolve titles via
getEventTitle()— no per-provider changes needed
- Bull (job queue)
- Node.js crypto (AES-256-GCM encryption)
- Apprise API, Discord webhooks, ntfy API, Pushover API
- React (UI), Tailwind CSS (styling)
Apprise server URL credentials stored and shown in plaintext
- Cause: Basic auth for an Apprise server behind auth was only possible as
https://user:pass@hostinserverUrl, a plain (unencrypted, unmasked) field - Fix: separate
basicAuthUser/basicAuthPassword(encrypted) fields; credentials typed into the URL are moved on save; existing rows migrated at startup; the API returns neither the password nor URL userinfo. Exception: a legacy row whose URL was never a valid http(s) URL is not migrated (its credentials stay in the stored value until the admin re-saves it) but is displayed without the part before the last@