Notifications

Two independent subsystems: the in-app bell (@repo/notifications, gated by config.notifications) for per-user alerts, and operator alerts (@repo/admin-notifications, gated by config.adminNotifications) that push business events to your chat tools. This page covers the bell; the alerts have their own page.

The web app and the desktop app both render the bell, the notifications list and the per-notification page, from the same backend and the same config.notifications gate, so a notification reaches a user wherever they are signed in. A notification's link names a web page; the desktop resolves it to its own screen where it has one and opens the web app in the browser where it does not.

Configuration

config.notifications is a discriminated union: { enabled: false } hides the bell entirely - createNotification returns null and writes no rows - or the enabled object tunes these knobs.

Creating notifications

createNotification({ userId, type, title, message, link?, metadata? }) inserts one row and returns its ID, or null when the flag is off. Prefer the eight typed helpers in triggers.ts over raw inserts - each sets the correct type, a deep link, and HTML-escapes interpolated values via escapeHtml.

type must be one of the 18 NotificationType kinds in packages/config/src/types/notifications.ts: payment_success, payment_failed, plan_changed, credits_low, credits_added, subscription_expiring, team_invite_received, team_member_joined, team_member_left, team_role_changed, new_login, password_changed, two_factor_enabled, two_factor_disabled, session_revoked, system_announcement, maintenance_scheduled, feature_update.

Reading the bell

Service functions are all ownership-scoped by userId:

The bell lives in the dashboard - see Data fetching for wiring its data.

Broadcasts

createBroadcast persists an announcement and fans out across the selected channels:

Unsubscribe links

Marketing email carries a signed link from generateUnsubscribeUrl(userId, config.baseUrl): HMAC-SHA-256 with BETTER_AUTH_SECRET, expiring after 30 days, verified in constant time by verifyUnsubscribeToken. It POSTs to /email/preference, which toggles marketingOptIn and emits user/marketing.disabled (cancels the re-engagement ladder) or user/marketing.enabled (resumes a paused onboarding sequence).

Announcement HTML

Titles and messages accept a small allow-list of formatting HTML, sanitized on write and again on render - so a message stored before a rule changed is still safe when it is read.

• Other tags are unwrapped, not deleted: <div>Hi</div> becomes Hi, so pasted rich text keeps its words. script, style, xmp, title and template lose their contents with the tag; comments are removed.
• Text that looks like markup is escaped, and sanitizing is idempotent - re-saving never double-escapes an &.
• Placeholders are substituted after sanitizing and escaped as text, so {userName} can never inject markup.

Cleanup and retention

Two limits bound the table, applied by two different paths - so the per-user cap converges over time rather than instantly.

See Background jobs.

Operator alerts

@repo/admin-notifications pushes signups, purchases, refunds, and deletions to your team chat, gated by config.adminNotifications (default { enabled: true }). notifyAdmins() is a no-op unless the flag is on, a provider is configured, and the event is not opted out.