Repository navigation
Conversation
5 tasks done
Upd4ting
force-pushed
the
feat/notification-email-channel
branch
from
November 20, 2026 18:05
272631f to
f0ebf77
Compare
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
force-pushed
the
feat/notification-email-channel
branch
from
November 20, 2026 18:08
f0ebf77 to
213bf93
Compare
…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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Task W05057e83-12.
⚠ draft: CI waits for the stable
@antelopejs/interface-dms/@antelopejs/dmsrelease. 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 withNotificationEmailChannel({ 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.tsregisters the e-mail channel at start-up.deliverstarts the e-mail and returns, since the DMS send waits for it; a failure is logged, never thrown.sendUnlessSuppressed, so the send log, the suppression list, the sender settings and the webhook apply. Sends are labelleddms-mailing:notification.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.tsdeclares onedms-notificationtemplate throughdeclareTemplate, in the workspace's fallback locale (French copy for a French locale, else English).declareTemplatekeeps a template the workspace already has, so owner edits stay.@antelopejs/interface-dms0.14.7-next.1002.g39c16f7(the copy the dms preview ships);@antelopejs/dms0.21.4-next.1002.g39c16f7in 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.Cut from the first version
mailing_notification_deliveries, its model, the 03:45 prune cron and the release-on-throw logic. The DMS callsdeliveronly after inserting a new notification row, and the database arbitrates that insert.notification-channel.ts,ChannelRegistrar): dead under the pinned interface range.services/headers.tschange to every send.notificationscategory: one declared template, no category.stop().Proof
CI waits for the stable
@antelopejs/interface-dms/@antelopejs/dmsrelease. The test stack also loads@antelopejs/dms-automation, whose range>=0.14.0 <0.15.0admits no prerelease, so the core refuses the-nextinterface copy there. The proof below ran locally on@antelopejs/dms@0.21.4-next.1002.g39c16f7withdms-automationtaken 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 fromconstruct; the DMS stores the notification and no e-mail goes out:After:
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.Follow-ups