Skip to content

feat(dms): let a subject offer e-mail and a mail module deliver it - #1126

Merged
Upd4ting merged 5 commits into
mainfrom
feat/notification-email-channel
Nov 20, 2026
Merged

Upd4ting merged 5 commits into
mainfrom
feat/notification-email-channel

Conversation

@mwesto

@mwesto mwesto commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

The account page's notification preferences show an « E-mail » column marked « Bientôt » / "Soon" with nothing behind it. This PR lets a subject offer e-mail and lets a mail module deliver it. Once a module registers the e-mail channel, each subject that offers e-mail gets an Email switch, and every new in-app notification of that subject is handed to the channel for the users who have it on.

Takeover of Maxime's PR, rebased on main. The edit to .agents/skills/verify-dms/features/settings-account.md is dropped, since #1172 deleted that file. Per Antony's review, the generic channel model is collapsed to the one channel that exists: e-mail.

Final contract (@antelopejs/interface-dms/notifications), consumed by AntelopeJS/dms-mailing#197

// A subject offers e-mail. Unset or false: in-app only.
NotificationSubject("invoice", {
  category,
  labelKey: "…",
  email: true,                    // offered, off until the user turns it on
  // email: { defaultOn: true },  // offered, on until the user turns it off
});

// The mail module registers the channel. A RegisteringProxy: released when that module unloads.
NotificationEmailChannel({
  deliver(userId: string, data: NotificationData, notificationId: string): Promise<void> | void,
});

// A send names the workspace it is about; the channel reads it as data.tenantId.
await notification.toUser(userId, { tenantId });
Name Shape
NotificationSubjectInfo.email boolean | { defaultOn?: boolean }, optional
NotificationEmailChannel(channel) registers channel and returns it
NotificationEmailChannelInfo { deliver(userId, data, notificationId) }. notificationId is the stored in-app row's id; a keyed send's row id already derives from its key
internal.RegisterNotificationEmailChannel RegisteringProxy<(info: NotificationEmailChannelInfo) => void>
internal.emailChannelIdentity RegistrationIdentity stamped by NotificationEmailChannel(), so an unload clears the channel only when it is the live one
SendOptions.tenantId, NotificationData.tenantId string, optional. dms-mailing#197 sends nothing without it. toRoles keeps its recipient filter
RoleSendOptions interface RoleSendOptions extends SendOptions {}: its only own field, tenantId, moved to SendOptions; it stays an interface so declaration merging still works

Everything is additive and optional against main. Against Maxime's version, channels, NotificationChannel(id, …), NotificationChannelId, NotificationChannelOffer(s), NotificationChannelInfo and NotificationDeliveryContext (with its unread idempotencyKey) are gone.

What changed in the review

  • channels: { email: … } became email?: boolean | { defaultOn?: boolean }. The one-member NotificationChannelId union and the per-id channel map are deleted.
  • The DMS holds one e-mail channel. A later registration replaces it without a warning, since every hot reload registers the new copy first. Unregistering clears the channel only when the departing registration is the live one, so a hot reload or an unload of a replaced module keeps e-mail working. Maxime's version cleared it on any unregister.
  • The preferences route no longer parses a generic @<channel> suffix. It accepts <category>:<subject>@email only, when the subject offers e-mail and the channel is registered. Any other key gets a 400.
  • GET …/notifications/categories returns emailChannel: boolean in place of channels: string[]. Each subject carries email: { defaultOn } only when it offers e-mail and the channel is registered.
  • A subject turned off in the app now shows its disabled e-mail switch off, as the server sends it. Maxime's version showed a defaultOn subject's switch on.
  • The Vue layer's copy of the channel id type, channelPreferenceKey(subject, channel) and hasChannel(channel) are gone. Every switch reads its value through one read(key): the stored choice, else the e-mail default, else on. The offersEmail prop is gone: the row reads subject.email.
  • notification-channels.ts became notification-email.ts, and the docs page delivery-channels became email.

Behaviour, unchanged from Maxime's version

  • Storage: no migration. The e-mail choice is a second key, "<category>:<subject>@email", in the existing user_notification_preferences.preferences map, read at send time with the subject's defaultOn as fallback.
  • SendToUser, which every send goes through, hands the notification to the channel after the in-app row is stored and published. A subject turned off in the app, a repeat inside the 10-second window and an idempotent retry store no row, so they mail nothing.
  • A locked subject that offers e-mail is mailed whatever is stored, and turning its e-mail off gets a 403.
  • A deliver that throws is logged as [DMS] Notification e-mail channel failed to deliver …, and the send still resolves.
  • Without a registered channel nothing changes: the column keeps its « Bientôt » badge, its — cells and its hint.
flowchart TD
  S[notification.toUser / toUsers / toRoles / broadcast] --> U[SendToUser]
  U --> P{in-app on, or subject locked?}
  P -- no --> X[skip]
  P -- yes --> R[store row, publish realtime]
  R -- row already stored: retry or repeat --> X
  R --> C{e-mail channel registered and subject.email?}
  C -- no --> D[done]
  C -- yes --> E{locked, or stored @email key, else defaultOn}
  E -- off --> D
  E -- on --> M[channel.deliver userId, data, notificationId]
  M -- throws --> L[log, send resolves]
Loading

⚠ sensitive: adds to the interface-dms notifications contract and a new stored preference key format

Related issue

W05057e83-9. Consumed by AntelopeJS/dms-mailing#197.

Verification

The integration test src/test/integration/notification-email.test.ts (12 tests, fake channel) against Maxime's contract, by checking out his interface-dms/src/notifications and typechecking packages/dms:

src/test/integration/notification-email.test.ts(8,3): error TS2724: '"@antelopejs/interface-dms/notifications/types"' has no exported member named 'NotificationEmailChannelInfo'. Did you mean 'NotificationChannelInfo'?
src/test/integration/notification-email.test.ts(34,3): error TS2353: Object literal may only specify known properties, and 'email' does not exist in type 'NotificationSubjectInfo'.
src/test/integration/notification-email.test.ts(40,3): error TS2353: Object literal may only specify known properties, and 'email' does not exist in type 'NotificationSubjectInfo'.
src/test/integration/notification-email.test.ts(52,3): error TS2353: Object literal may only specify known properties, and 'email' does not exist in type 'NotificationSubjectInfo'.

After:

  [integration] notification e-mail, no channel registered
    ✔ lists no channel and no offer (fails when the screen would draw an e-mail switch no module delivers)
    ✔ refuses an e-mail preference (fails when a key for an unregistered channel is stored)
  [integration] notification e-mail, channel registered
    ✔ lists the channel and each subject's offer with its default (fails when the defaults are not read from the subject)
    ✔ does not mail a subject offered off until the user turns it on, then mails it with its tenant (fails when the default is on or the tenant is lost)
    ✔ mails a subject offered on until the user turns it off (fails when defaultOn is ignored or the choice is not read)
    ✔ never mails a subject that offers no e-mail, and refuses its e-mail key (fails when every subject is mailed)
    ✔ does not mail a subject the user turned off in the app (fails when the channel runs without a stored notification)
    ✔ mails a locked subject whatever is stored, and refuses turning its e-mail off (fails when the lock covers only the app)
    ✔ mails an idempotent send once however often it is retried (fails when a retry mails again)
    ✔ mails a repeat dropped by the duplicate window once (fails when a deduplicated send still mails)
    ✔ keeps the in-app notification when the channel throws (fails when a channel error fails the send)
    ✔ keeps mailing when a replaced registration unloads after its replacement, as on a hot reload (fails when any unregister clears the channel)
  12 passing (773ms)

The hot-reload case, keeps mailing when a replaced registration unloads after its replacement, against Maxime's unconditional unregister (mutant) and after:

    1) keeps mailing when a replaced registration unloads after its replacement, as on a hot reload (fails when any unregister clears the channel)
  11 passing (779ms)
  1 failing
      AssertionError: expected false to equal true
    ✔ keeps mailing when a replaced registration unloads after its replacement, as on a hot reload (fails when any unregister clears the channel)
  12 passing (773ms)

notification-preferences-email.test.ts now asserts a subject off in the app shows its e-mail switch off. Against the previous isEmailEnabled: AssertionError: expected 'true' to be 'false', 1 failed | 3 passed. After: 4 passed.

Also run locally:

  • pnpm run checks: 12 passed, 0 failed.
  • pnpm run typecheck: clean.
  • Every integration file about notifications (10 files, 60 tests): passing.
  • frontend-vue vitest on notification (7 files, 33 tests, including notification-preferences-email.test.ts): passing.
  • oxlint and oxfmt on the changed backend files, eslint and prettier on the changed Vue files: no error.

Attention

  • One preference map holds both key kinds, so a subject whose id itself ends in @email would collide with the e-mail key of the subject named without it. No subject id contains @ today; only an odd id triggers it.

Follow-ups

Checklist

  • The pull request title follows Conventional Commits.
  • I added or updated tests when behavior changed.
  • I updated documentation when users or contributors are affected.
  • I documented breaking changes and migration steps.
  • I did not include credentials or unrelated changes.

@Upd4ting
Upd4ting force-pushed the feat/notification-email-channel branch from da606d4 to 4bfbfc8 Compare November 20, 2026 14:48
@Upd4ting Upd4ting changed the title feat(dms): deliver notifications through registered channels and offer e-mail per subject feat(dms): let a subject offer e-mail and a mail module deliver it Nov 20, 2026
mwesto and others added 5 commits November 20, 2026 17:40
A subject now offers e-mail with email?: boolean | { defaultOn?: boolean }
and a mail module registers it with NotificationEmailChannel({ deliver }).
The one-member channel id union, the generic @<channel> key parsing and the
frontend's copy of the channel id type are gone; the frontend reads every
switch default through one function.
An unregister now clears the channel only when it names the live
registration, stamped with a RegistrationIdentity, so a hot reload no
longer turns e-mail off. deliver receives the notification id directly,
SendOptions holds the one tenantId, and a subject off in the app shows its
e-mail switch off.
@Upd4ting
Upd4ting force-pushed the feat/notification-email-channel branch from a8a1823 to 9d35ac4 Compare November 20, 2026 17:45
@Upd4ting
Upd4ting added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit 39c16f7 Nov 20, 2026
24 checks passed
@Upd4ting
Upd4ting deleted the feat/notification-email-channel branch November 20, 2026 17:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants