@nxgt/janus-mail 0.5.1 → 0.6.0

package/README.md

@@ -47,7 +47,7 @@ bun add -d typescript
 
 Three peers, all required: `@nxgt/mail` (0.1 or later, below 2 — 1.0 and
 its transports included), which defines the `Mailer` port and the errors;
-`@nxgt/janus` (0.11), whose flows' answers the methods take — types only,
+`@nxgt/janus` (0.14), whose flows' answers the methods take — types only,
 nothing of it is loaded; and `typescript` (6). **No Maizzle, no Vue, no
 Tailwind**: they run at this package's build, not in yours.
 
@@ -144,21 +144,35 @@ if (issued !== null) {
 await mail.verifyEmail(issued, { name: user.name, locale: 'fr' }, { expiresIn: '24 heures' });
 ```
 
-### Telling a user their password changed
+### Telling a user their password or e-mail changed
 
-```ts
-const changed = await auth.changePassword(user, { current, next });
-await mail.passwordChanged({ name: changed.name, locale: changed.locale, email: changed.email });
-```
-
-### Telling a user their e-mail changed
+`@nxgt/janus` 0.14 sends `user.passwordChanged` once `changePassword` or
+`setPassword` wrote the password, and `user.emailChanged` once `update`
+changed the e-mail. The e-mail change is told to the **former** address — the
+new one belongs to whoever changed it — which the event carries as
+`formerEmail`, `null` for a user who had none:
 
 ```ts
-const before = user.email;
-const updated = await auth.update(user, { email: next });
-await mail.emailChanged({ name: updated.name, locale: updated.locale, formerEmail: before, newEmail: updated.email });
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type === 'user.passwordChanged') {
+			const user = await auth.get(event.userId);
+			await mail.passwordChanged({ name: user.name, locale: user.locale, email: user.email });
+		}
+		if (event.type === 'user.emailChanged' && event.formerEmail != null) {
+			const user = await auth.get(event.userId);
+			await mail.emailChanged({ name: user.name, locale: user.locale, formerEmail: event.formerEmail, newEmail: user.email });
+		}
+	},
+});
 ```
 
+A reset sends `user.passwordReset`, not `user.passwordChanged`: add that type
+to the first test to tell a reset too. The examples assume a required e-mail;
+with an optional one, an update that removes it has no `newEmail` to name —
+see [Sending](docs/guide/sending.md#emailchangedto).
+
 ### Telling a user their second factor was turned on or off
 
 `@nxgt/janus` sends `user.secondFactorEnabled` once `secondFactor.activate`
@@ -380,8 +394,8 @@ The symptoms and fixes are in [troubleshooting](docs/troubleshooting.md).
 
 ## Type safety, counted
 
-**Thirty-four plausible mistakes, thirty-four refused at compile time.**
-Five files hold one `@ts-expect-error` per mistake, beside the calls that
+**Thirty-six plausible mistakes, thirty-six refused at compile time.**
+Six files hold one `@ts-expect-error` per mistake, beside the calls that
 must keep compiling:
 [`test/types/send-refusals.ts`](test/types/send-refusals.ts) the eight of a
 send, 1 to 8;
@@ -391,9 +405,11 @@ template;
 [`test/types/expiry-refusals.ts`](test/types/expiry-refusals.ts) the five of
 the expiry and the clock, 21 to 25;
 [`test/types/notice-refusals.ts`](test/types/notice-refusals.ts) the four of
-the two-factor notices and the welcome, 26 to 29; and
+the two-factor notices and the welcome, 26 to 29;
 [`test/types/recovery-refusals.ts`](test/types/recovery-refusals.ts) the
-five of the recovery code notice, 30 to 34:
+five of the recovery code notice, 30 to 34; and
+[`test/types/change-refusals.ts`](test/types/change-refusals.ts) the two of
+the e-mail change notice sent on its event, 35 and 36:
 
 1. A sign-in code given to `verifyEmail`: it has no token.
 2. A one-time token given to `signInCode`: it has no code.
@@ -429,8 +445,10 @@ five of the recovery code notice, 30 to 34:
 32. The count as `recoveryCodesLeft()` answered it, not checked for `null` first.
 33. `when` given as the event's `Date` rather than the text in the recipient's locale and time zone.
 34. `links.recoveryCodes` given as a URL rather than a function.
+35. `user.emailChanged`'s `formerEmail` given to `emailChanged` unchecked: it is `null` for a user who had none.
+36. The `user.emailChanged` event itself given to `emailChanged`: it has the former address, but neither a name nor the new one.
 
-In JavaScript, 19 to 23, 26 to 28 and 30 to 33 are a `TypeError` at send
+In JavaScript, 19 to 23, 26 to 28, 30 to 33, 35 and 36 are a `TypeError` at send
 time instead, naming the call or the field, and 25, 29 and 34 one from
 `janusMail()`.
 

package/docs/README.md

@@ -5,7 +5,7 @@ the detail.
 
 | Page | Read it when |
 | --- | --- |
-| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options, `clock` among them; each method, the welcome on `user.created` and the recovery code notice on `user.recoveryCodeUsed` among them; the expiry an e-mail states and how to set it, where each e-mail goes, what a failure looks like, retrying and tracing the mailer, and a test |
+| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options, `clock` among them; each method, the welcome on `user.created`, the recovery code notice on `user.recoveryCodeUsed` and the change notices on `user.passwordChanged` and `user.emailChanged` among them; the expiry an e-mail states and how to set it, where each e-mail goes, what a failure looks like, retrying and tracing the mailer, and a test |
 | [Templates](guide/templates.md) | You want an e-mail of your own: what a template takes and answers, a partial override, `janusTemplates()`, and what the defaults say |
 | [Locales](guide/locales.md) | You send in more than one language: how the locale is picked, `fallbackLocale`, fewer locales, and adding one |
 | [Building](guide/building.md) | You work on this package: the Maizzle project in `mail/`, `mails/`, the generated files, and why none of it reaches a consumer's build |

package/docs/guide/sending.md

@@ -117,26 +117,52 @@ name — and only its `locale` is read.
 ### `passwordChanged(to)`
 
 ```ts
-const changed = await auth.changePassword(user, { current, next });
-await mail.passwordChanged({ name: changed.name, locale: changed.locale, email: changed.email });
+// On the user event @nxgt/janus 0.14 sends once the password is written:
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type !== 'user.passwordChanged') return;
+		const user = await auth.get(event.userId);
+		await mail.passwordChanged({ name: user.name, locale: user.locale, email: user.email });
+	},
+});
 ```
 
 A notice: the password of the account at `to.email` changed, with a link to
-`links.secureAccount()` for a user who did not change it. Send it after
-`changePassword`, `setPassword` and `resetPassword.confirm`.
+`links.secureAccount()` for a user who did not change it. Send it on the
+`user.passwordChanged` event, which `changePassword` and `setPassword` send.
+A reset sends `user.passwordReset` instead, never both: to tell a reset too,
+send the same notice on that type — `event.type === 'user.passwordChanged'
+|| event.type === 'user.passwordReset'`. The event names the user by id
+alone, so read the name, the locale and the address from the user.
+`setPassword` sends it for a user's first password too — an account created
+without one — so the notice then tells them a password was set on their
+account, which is worth knowing all the same.
 
 ### `emailChanged(to)`
 
 ```ts
-const formerEmail = user.email;
-const updated = await auth.update(user, { email: next });
-await mail.emailChanged({ name: updated.name, locale: updated.locale, formerEmail, newEmail: updated.email });
+// On the user event @nxgt/janus 0.14 sends when an update changed the e-mail:
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type !== 'user.emailChanged' || event.formerEmail == null) return;
+		const user = await auth.get(event.userId);
+		await mail.emailChanged({ name: user.name, locale: user.locale, formerEmail: event.formerEmail, newEmail: user.email });
+	},
+});
 ```
 
 Sent to **`formerEmail`**: the owner of the old address is the one to warn,
 since whoever changed it already controls the new one. It names `newEmail`,
-and links to `links.secureAccount()`. Read the former address before the
-update: the user `update` answers already holds the new one.
+and links to `links.secureAccount()`. The `user.emailChanged` event is the
+one that carries an address — `event.formerEmail`, the e-mail before the
+update — since the user read back already holds the new one. It is `null`
+for a user who had no e-mail before: there is no former inbox to tell, and
+the type refuses it unchecked. The example assumes a required e-mail: with
+an optional one, `update` also sends the event when it removes the address,
+and the user read back has no `newEmail` to name — check `user.email` first,
+and tell the former address your own way or not at all.
 
 ### `twoFactorEnabled(to)` and `twoFactorDisabled(to)`
 

package/docs/roadmap.md

@@ -47,6 +47,13 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **The change notices on their events, v0.6.0.** `passwordChanged` and
+  `emailChanged` are sent from `@nxgt/janus` 0.14's `user.passwordChanged`
+  and `user.emailChanged` events, as the two-factor notices are, rather than
+  after the call: whoever changed the password or the e-mail, the user is
+  told. `emailChanged` goes to the event's `formerEmail`, the inbox the
+  account just left, and the compiler refuses it unchecked for `null`.
+
 - **The recovery code notice, and a readable link in both modes, v0.5.0.**
   `recoveryCodeUsed(to, { when, recoveryCodesLeft })`, built from
   `@nxgt/mail-presets` 1.0.0's `recovery-code-used` in English and French:

package/docs/troubleshooting.md

@@ -255,14 +255,29 @@ number of seconds: pass the text to show, `{ expiresIn: '1 hour' }`, or
 leave it out.
 
 `janusMail.twoFactorEnabled: email must be a string` (or `twoFactorDisabled`,
-`recoveryCodeUsed` or `welcome`) is the user event itself given to the
-e-mail: an event names the user by id alone. Read the user first:
+`passwordChanged`, `recoveryCodeUsed` or `welcome`) is the user event itself
+given to the e-mail: an event names the user by id alone. Read the user first:
 
 ```ts
 const user = await auth.get(event.userId);
 await mail.twoFactorDisabled({ name: user.name, locale: user.locale, email: user.email });
 ```
 
+On `user.emailChanged`, `janusMail.emailChanged: name must be a string` is
+the event itself given to `emailChanged`, and `janusMail.emailChanged:
+formerEmail must be a string` is `event.formerEmail` passed without its
+check — it is `null` for a user who had no e-mail before. `janusMail.emailChanged:
+newEmail must be a string` is an update that removed the e-mail: there is no
+new address to name. Check both, and read the rest from the user:
+
+```ts
+if (event.type === 'user.emailChanged' && event.formerEmail != null) {
+	const user = await auth.get(event.userId);
+	if (user.email === undefined) return; // removed: tell the former address your own way
+	await mail.emailChanged({ name: user.name, locale: user.locale, formerEmail: event.formerEmail, newEmail: user.email });
+}
+```
+
 `janusMail.recoveryCodeUsed: when must be a string` is the second argument
 missing, or its `when` given as the event's `Date`: pass the text to show,
 formatted in the recipient's locale and time zone —

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-mail",
-	"version": "0.5.1",
+	"version": "0.6.0",
 	"description": "The e-mails of @nxgt/janus's flows — e-mail verification, password reset, sign-in code, password changed, e-mail changed, two-factor enabled and disabled, recovery code used, welcome — rendered in English and French from a prebuilt Maizzle build, with your brand, sent through any @nxgt/mail transport",
 	"license": "MIT",
 	"type": "module",
@@ -54,7 +54,7 @@
 		"@maizzle/framework": "6.1.7",
 		"@maizzle/tailwindcss": "1.5.6",
 		"@formatjs/icu-messageformat-parser": "3.5.20",
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.14.0",
 		"@nxgt/mail": "1.0.1",
 		"@nxgt/mail-config": "1.0.1",
 		"@nxgt/mail-i18n": "1.0.1",
@@ -66,7 +66,7 @@
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.12.0",
+		"@nxgt/janus": "^0.14.0",
 		"@nxgt/mail": ">=0.1.0 <2",
 		"typescript": "^6.0.3"
 	}