Skip to content

feat(dms-mailing): mail DMS notifications through the e-mail channel - #197

Draft
mwesto wants to merge 3 commits into
mainfrom
feat/notification-email-channel
Draft

mwesto wants to merge 3 commits into
mainfrom
feat/notification-email-channel

Conversation

@mwesto

@mwesto mwesto commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Task W05057e83-12.

⚠ draft: CI waits for the stable @antelopejs/interface-dms / @antelopejs/dms release. The second half of AntelopeJS/dms#1126 (W05057e83-9), taken over from @mwesto's version and cut down per review.

Why

A user who turns e-mail on for a notification subject under Settings › Account › Notifications should get the notification by mail. dms#1126 adds the DMS half: a subject offers e-mail (email?: boolean | { defaultOn }) and a mail module registers the channel with NotificationEmailChannel({ deliver }). The DMS cannot depend on the mail module, so the channel lives here and sends through the module's own pipeline.

Summary

  • src/services/notification-email.ts registers the e-mail channel at start-up. deliver starts the e-mail and returns, since the DMS send waits for it; a failure is logged, never thrown.
  • Each notification is sent with sendUnlessSuppressed, so the send log, the suppression list, the sender settings and the webhook apply. Sends are labelled dms-mailing:notification.
  • Skipped, with a debug log: no tenantId, a $ translation key as title or description (a warning), an unknown user, a missing or unvalidated address, a user who left the workspace. A platform owner is always mailed.
  • src/services/notification-template.ts declares one dms-notification template through declareTemplate, in the workspace's fallback locale (French copy for a French locale, else English). declareTemplate keeps a template the workspace already has, so owner edits stay.
  • Dependencies: @antelopejs/interface-dms 0.14.7-next.1002.g39c16f7 (the copy the dms preview ships); @antelopejs/dms 0.21.4-next.1002.g39c16f7 in devDependencies, the test stack (antelope-modules.ts, its module lock), both playgrounds and the e2e playground; zod ^3.25.76, the copy the interface uses. The stable interface-dms/dms release replaces the previews.
  • Docs: Extending § "DMS notifications by e-mail", the introduction, one FAQ entry, the shipped skill and one skill case.

Cut from the first version

  • The claim table mailing_notification_deliveries, its model, the 03:45 prune cron and the release-on-throw logic. The DMS calls deliver only after inserting a new notification row, and the database arbitrates that insert.
  • The feature detection (notification-channel.ts, ChannelRegistrar): dead under the pinned interface range.
  • The services/headers.ts change to every send.
  • The per-workspace locale choice and the notifications category: one declared template, no category.
  • The pending-delivery set awaited on stop().

Proof

CI waits for the stable @antelopejs/interface-dms / @antelopejs/dms release. The test stack also loads @antelopejs/dms-automation, whose range >=0.14.0 <0.15.0 admits no prerelease, so the core refuses the -next interface copy there. The proof below ran locally on @antelopejs/dms@0.21.4-next.1002.g39c16f7 with dms-automation taken out of the test stack (not committed).

ajs module test . -f dist/test/integration/notification-email.test.js. Before = this branch with the channel registration removed from construct; the DMS stores the notification and no e-mail goes out:

    ✔ mails a notification through the workspace's notification template
    ✔ logs a suppressed address without sending to it or throwing
    ✔ sends nothing for a notification that names no workspace
    ✔ sends nothing to a user who left the workspace
    ✔ sends nothing to an address the user never validated
    ✔ sends nothing to an unknown user
    ✔ sends nothing when the title is a key only the dashboard translates
    ✔ keeps the template its owners edited
    1) mails a notification the DMS sends to a user with e-mail on
  8 passing (2s)
  1 failing
  1) [integration] notification e-mail channel
      AssertionError: expected [] to deeply equal [ 'dms-notification' ]
      + expected - actual
      -[]
      +[
      +  "dms-notification"
      +]

After:

    ✔ mails a notification through the workspace's notification template
    ✔ logs a suppressed address without sending to it or throwing
    ✔ sends nothing for a notification that names no workspace
    ✔ sends nothing to a user who left the workspace
    ✔ sends nothing to an address the user never validated
    ✔ sends nothing to an unknown user
    ✔ sends nothing when the title is a key only the dashboard translates
    ✔ keeps the template its owners edited
    ✔ mails a notification the DMS sends to a user with e-mail on
  9 passing

Full backend suite on the preview (ajs module test ., same stack): 613 passing, exit 0.

Typecheck, oxlint and the repo lint scripts (check-module-locks, check-playground-deps-lockfile, check-docs-module-version) pass.

sequenceDiagram
  participant M as Module (toUser with tenantId)
  participant D as DMS notifications
  participant C as dms-mailing e-mail channel
  participant S as sendUnlessSuppressed
  M->>D: send notification
  D->>D: insert notification row
  D->>C: deliver(userId, data, notificationId) if the user has e-mail on
  C-->>D: returns at once
  C->>C: skip checks (tenant, $ key, user, address, membership)
  C->>C: declareTemplate dms-notification (kept if present)
  C->>S: send dms-notification
  S->>S: send log row (sent, suppressed or failed)
Loading

Follow-ups

  • none

@Upd4ting
Upd4ting force-pushed the feat/notification-email-channel branch from 272631f to f0ebf77 Compare November 20, 2026 18:05
@Upd4ting Upd4ting changed the title feat(dms-mailing): mail DMS notifications through the email channel feat(dms-mailing): mail DMS notifications through the e-mail channel Nov 20, 2026
Registers the DMS notifications' e-mail channel and sends each
notification through sendUnlessSuppressed with a declared
dms-notification template. Skips a notification without a workspace,
with a $ translation key, or for a user who is unknown, unvalidated or
no longer a member.
@Upd4ting
Upd4ting force-pushed the feat/notification-email-channel branch from f0ebf77 to 213bf93 Compare November 20, 2026 18:08
…nnel

Pins @antelopejs/dms 0.21.4-next.1002.g39c16f7 in the test stack and the
playgrounds, requires @antelopejs/interface-dms >=0.14.7-next.1002 and
moves zod to the copy the interface uses.
@Upd4ting
Upd4ting marked this pull request as draft November 20, 2026 18:29
The core and the lockfile singleton check need one interface-dms copy:
the one @antelopejs/dms@0.21.4-next.1002.g39c16f7 depends on.
Upd4ting added a commit to emreocell/dms that referenced this pull request Nov 20, 2026
…ntelopeJS#1126)

## 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 AntelopeJS#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

```ts
// 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.

```mermaid
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]
```

⚠ 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

- proposed AntelopeJS/dms-mailing: AntelopeJS#197 registers through
`NotificationChannel("email", { deliver })`, which this PR removes, done
means it calls `NotificationEmailChannel({ deliver })` with
`deliver(userId, data, notificationId)` and its docs show `email: true`
on a subject.

## Checklist

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

---------

Co-authored-by: Antony Rizzitelli <rizzitelli.antony@pm.me>

This branch has not been deployed

No deployments
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