@nxgt/janus-mail 0.4.1 → 0.5.0

package/README.md

@@ -3,7 +3,8 @@
 The e-mails of [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus)'s
 flows, ready to send: **e-mail verification, password reset, sign-in code,
 password changed, e-mail changed, two-factor authentication turned on or
-off, and a welcome to a new user**, in English and French, with your brand
+off, a recovery code used, and a welcome to a new user**, in English and
+French, with your brand
 in them. `@nxgt/janus` sends no e-mail — its flows answer what to send — and
 this package turns that answer into an e-mail and hands it to any
 [`@nxgt/mail`](https://www.npmjs.com/package/@nxgt/mail) transport.
@@ -21,6 +22,7 @@ const mail = janusMail({
 		resetPassword: (token) => `https://acme.example/reset?token=${token}`,
 		secureAccount: () => 'https://acme.example/account/security',
 		getStarted: () => 'https://acme.example/',
+		recoveryCodes: () => 'https://acme.example/account/recovery-codes', // optional
 	},
 });
 
@@ -43,9 +45,9 @@ bun add @nxgt/janus-mail @nxgt/mail @nxgt/janus
 bun add -d typescript
 ```
 
-Three peers, all required: `@nxgt/mail` (0.1 or later, below 1 — the
-transports of 0.4 included), which defines the `Mailer` port and the errors;
-`@nxgt/janus` (0.9), whose flows' answers the methods take — types only,
+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,
 nothing of it is loaded; and `typescript` (6). **No Maizzle, no Vue, no
 Tailwind**: they run at this package's build, not in yours.
 
@@ -53,18 +55,20 @@ The `@nxgt/mail` floor is tested, not claimed: the package's specs and its
 typecheck run on `@nxgt/mail` 0.1.0 as well, in the Floors job, on every CI
 run.
 
-It reads its prebuilt e-mails with `node:fs`: **Node, Bun or Deno**, not an edge
-runtime. Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`.
+It reads its prebuilt e-mails with `node:fs`: **Node (20 or later), Bun or
+Deno**, not an edge runtime. Rebuilding the e-mails from this repository
+needs Node `^22.22.3`, `^24.15.0` or `>=26`, for Maizzle — see
+[Building](docs/guide/building.md); installing the package needs no build. Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`.
 
 ## API
 
 | Export | What it is |
 | --- | --- |
-| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`, `welcome`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`, `getStarted`), `locales?`, `fallbackLocale?`, `templates?`, `clock?`. A wrong option is a bare `TypeError`, thrown here |
-| `janusTemplates()` | The eight default templates alone, each `(variables & { locale }) => Rendered` |
+| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`, `recoveryCodeUsed`, `welcome`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`, `getStarted`, and `recoveryCodes?`), `locales?`, `fallbackLocale?`, `templates?`, `clock?`. A wrong option is a bare `TypeError`, thrown here |
+| `janusTemplates()` | The nine default templates alone, each `(variables & { locale }) => Rendered` |
 | `JanusMail<L>`, `JanusMailOptions<L>` | What `janusMail()` answers and takes, for the locales `L` |
-| `JanusMailTemplate<V, L>`, `JanusMailTemplates<L>`, `JanusMailTemplateName` | One template, the eight of them, and their names |
-| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code`, `expiresIn` or `newEmail` as its e-mail needs |
+| `JanusMailTemplate<V, L>`, `JanusMailTemplates<L>`, `JanusMailTemplateName` | One template, the nine of them, and their names |
+| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code`, `expiresIn`, `newEmail`, `when` or `recoveryCodesLeft` as its e-mail needs |
 | `JanusMailSendOptions` | The third argument of `verifyEmail`, `resetPassword` and `signInCode`: `{ expiresIn? }`, the expiry as text, over the one derived |
 | `JanusMailLocale` | `'en' \| 'fr'`: the locales the defaults are built in |
 | `JanusMailLinks`, `Recipient` | The `links` option; who an e-mail is for — `{ name, locale? }` |
@@ -73,8 +77,8 @@ Each method answers the mailer's `SentMail` and **rejects with the mailer's
 `MailFailure` or `MailRefused`, untouched**: this package defines no error
 class. To retry a `MailFailure` or trace each send, wrap the mailer you pass:
 `withMailTelemetry(withRetry(mailer), { transport })` — `withRetry` from
-`@nxgt/mail` 0.8, `withMailTelemetry` from `@nxgt/mail/telemetry` 0.9 (0.8
-names it `withTelemetry`, a deprecated alias until 1.0); see
+`@nxgt/mail` 0.8 or later, `withMailTelemetry` from `@nxgt/mail/telemetry`
+0.9 or later (0.8 names it `withTelemetry`, which 1.0 removed); see
 [Sending](docs/guide/sending.md#retrying-and-tracing-the-mailer).
 
 | Method | Sends | To |
@@ -86,6 +90,7 @@ names it `withTelemetry`, a deprecated alias until 1.0); see
 | `emailChanged(to)` | A notice naming `to.newEmail`, with `links.secureAccount()` | `to.formerEmail` |
 | `twoFactorEnabled(to)` | A notice: two-factor authentication was turned on, with `links.secureAccount()` | `to.email` |
 | `twoFactorDisabled(to)` | A notice: two-factor authentication was turned off, with `links.secureAccount()` | `to.email` |
+| `recoveryCodeUsed(to, { when, recoveryCodesLeft })` | A notice: a recovery code was used, `when`, and how many are left — "You have 9 recovery codes left." — with `links.recoveryCodes()`, else `links.secureAccount()` | `to.email` |
 | `welcome(to)` | A welcome to a new user — "Welcome, Ada" — with `links.getStarted()` | `to.email` |
 
 The three e-mails of a link or a code say how long it lasts — "This link
@@ -200,6 +205,36 @@ out before the address is verified; to welcome proven addresses only, send
 it on `user.emailVerified` instead — see
 [Sending](docs/guide/sending.md#welcometo).
 
+### Telling a user a recovery code was used
+
+`@nxgt/janus` sends `user.recoveryCodeUsed` once `secondFactor.recover`
+spent a code: a sign-in without the user's phone. The event names the user
+by id only, so read the user, and the codes left with
+`secondFactor.recoveryCodesLeft` (`@nxgt/janus` 0.11):
+
+```ts
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type === 'user.recoveryCodeUsed') {
+			const user = await auth.get(event.userId);
+			const recoveryCodesLeft = await auth.secondFactor.recoveryCodesLeft(user);
+			if (recoveryCodesLeft === null) return; // the factor was turned off since
+			const when = new Intl.DateTimeFormat(user.locale, { dateStyle: 'long', timeStyle: 'short', timeZone: 'Europe/Paris' })
+				.format(event.occurredAt);
+			await mail.recoveryCodeUsed({ name: user.name, locale: user.locale, email: user.email }, { when, recoveryCodesLeft });
+		}
+	},
+});
+```
+
+`when` is text: format it in the recipient's locale and time zone.
+`recoveryCodesLeft` is the count, written as a sentence in the recipient's
+locale — "You have 1 recovery code left.", "Il ne vous reste aucun code de
+récupération." — or the sentence itself, as text. The button links to
+`links.recoveryCodes()`, where the user regenerates their codes, and to
+`links.secureAccount()` when you give no `recoveryCodes`.
+
 ### Replacing a template
 
 Any template can be your own function — React Email, a string, another
@@ -245,10 +280,19 @@ writes that name in its subject — "Welcome, <anything>" — so on
 `user.created` anyone can make your brand send it to any address. Once the
 address is proven, only its owner receives it.
 
-**Every link is required, `getStarted` included.** `links` written for 0.3
-has no `getStarted`: a compile error on `links`, and in JavaScript
-`janusMail: links.getStarted must be a function`. Add it even if you never
-send the welcome.
+**Every link is required, `getStarted` included — but `recoveryCodes`.**
+`links` written for 0.3 has no `getStarted`: a compile error on `links`, and
+in JavaScript `janusMail: links.getStarted must be a function`. Add it even
+if you never send the welcome. `recoveryCodes` is optional: without it,
+`recoveryCodeUsed` links to `secureAccount`.
+
+**The recovery code event carries no count.** `user.recoveryCodeUsed` names
+the user only; pass `recoveryCodesLeft` as
+`auth.secondFactor.recoveryCodesLeft(user)` answers it, once checked for
+`null` — a user whose factor was turned off since has no codes to count, and
+`null` is a compile error here. With a locale the defaults are not built in,
+pass the sentence rather than the count: the build has no plural for it, and
+a count is a `TypeError` at send.
 
 **`node:fs` means no edge runtime.** The default e-mails are read from the
 package's `mails/` folder, on the first one sent. On an edge runtime, pass
@@ -277,8 +321,9 @@ and are refused with a `TypeError`; its fields (`signInCode = (variables) =>
 …`) pass.
 
 **A locale beyond `en` and `fr` needs every template.** The defaults are
-built in those two only, so `locales: ['en', 'fr', 'de']` without all eight
-templates is a compile error, and a `TypeError` in JavaScript.
+built in those two only, so `locales: ['en', 'fr', 'de']` without all nine
+templates — `recoveryCodeUsed` included, since 0.5 — is a compile error, and
+a `TypeError` in JavaScript.
 
 **The brand is text only.** `brand: 'Acme'` is written in the header, the
 body and the footer, escaped: no logo, no link, no markup. For those, replace
@@ -335,8 +380,8 @@ The symptoms and fixes are in [troubleshooting](docs/troubleshooting.md).
 
 ## Type safety, counted
 
-**Twenty-nine plausible mistakes, twenty-nine refused at compile time.**
-Four files hold one `@ts-expect-error` per mistake, beside the calls that
+**Thirty-four plausible mistakes, thirty-four refused at compile time.**
+Five 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;
@@ -344,9 +389,11 @@ send, 1 to 8;
 of `janusMail()`'s options, 9 to 20, beside adding a language with every
 template;
 [`test/types/expiry-refusals.ts`](test/types/expiry-refusals.ts) the five of
-the expiry and the clock, 21 to 25; and
+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:
+the two-factor notices and the welcome, 26 to 29; and
+[`test/types/recovery-refusals.ts`](test/types/recovery-refusals.ts) the
+five of the recovery code notice, 30 to 34:
 
 1. A sign-in code given to `verifyEmail`: it has no token.
 2. A one-time token given to `signInCode`: it has no code.
@@ -377,9 +424,15 @@ the two-factor notices and the welcome, 26 to 29:
 27. `twoFactorEnabled` given `emailChanged`'s `formerEmail` rather than `email`.
 28. The `user.created` event itself given to `welcome`: it has neither a name nor an address.
 29. `links` written before the welcome, without `getStarted`.
-
-In JavaScript, 19 to 23 and 26 to 28 are a `TypeError` at send time instead, naming the
-call or the field, and 25 and 29 one from `janusMail()`.
+30. The `user.recoveryCodeUsed` event itself given to `recoveryCodeUsed`: it has neither a name nor an address.
+31. `recoveryCodeUsed` without `when` and the count.
+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.
+
+In JavaScript, 19 to 23, 26 to 28 and 30 to 33 are a `TypeError` at send
+time instead, naming the call or the field, and 25, 29 and 34 one from
+`janusMail()`.
 
 [`test/types/variables.ts`](test/types/variables.ts) also holds
 `JanusMailVariables` equal to the variables of the build: an e-mail that

package/dist/codes-left.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The sentence for `count` codes left in `locale`, or `undefined` for a
+ * locale the default e-mails are not built in.
+ */
+export declare function codesLeftText(locale: string, count: number): string | undefined;
+//# sourceMappingURL=codes-left.d.ts.map

package/dist/codes-left.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes-left.d.ts","sourceRoot":"","sources":["../src/codes-left.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CASpB"}

package/dist/generated/codes-left.d.ts

@@ -0,0 +1,3 @@
+/** Each locale's plural for the recovery codes left: branches by selector, `null` where the count goes. */
+export declare const CODES_LEFT: Readonly<Record<string, Readonly<Record<string, readonly (string | null)[]>>>>;
+//# sourceMappingURL=codes-left.d.ts.map

package/dist/generated/codes-left.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes-left.d.ts","sourceRoot":"","sources":["../../src/generated/codes-left.ts"],"names":[],"mappings":"AAGA,2GAA2G;AAC3G,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CA+BrG,CAAC"}

package/dist/generated/mail.d.ts

@@ -11,6 +11,13 @@ export interface MailEmails {
         readonly link: string;
         readonly name: string | number;
     };
+    "recovery-code-used": {
+        readonly brand: string | number;
+        readonly link: string;
+        readonly name: string | number;
+        readonly recoveryCodesLeft: string | number;
+        readonly when: string | number;
+    };
     "reset-password": {
         readonly brand: string | number;
         readonly expiresIn: string | number;

package/dist/generated/mail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../../src/generated/mail.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,MAAM,WAAW,UAAU;IAC1B,eAAe,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,kBAAkB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC/G,gBAAgB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClJ,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACzH,qBAAqB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClH,oBAAoB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjH,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtG"}
+{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../../src/generated/mail.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,MAAM,WAAW,UAAU;IAC1B,eAAe,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,kBAAkB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC/G,oBAAoB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC9L,gBAAgB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClJ,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACzH,qBAAqB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClH,oBAAoB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjH,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtG"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * `@nxgt/janus` sends no e-mail: its flows answer what to send — a one-time
  * token, a sign-in code, the address — and this package turns that answer
- * into an e-mail and hands it to an `@nxgt/mail` transport. Eight e-mails, in
+ * into an e-mail and hands it to an `@nxgt/mail` transport. Nine e-mails, in
  * English and French, prebuilt with Maizzle when this package is built, and
  * filled at send time with your brand, the recipient's name and your links.
  * Any of them can be replaced by a function of your own.

package/dist/index.js

@@ -129,6 +129,47 @@ function noticeMails(options) {
 // src/generated/locales.ts
 var LOCALES = ["en", "fr"];
 
+// src/refuse.ts
+function refuse(message) {
+  throw new TypeError(`janusMail: ${message}`);
+}
+
+// src/links.ts
+var REQUIRED_LINKS = [
+  "verifyEmail",
+  "resetPassword",
+  "secureAccount",
+  "getStarted"
+];
+var OPTIONAL_LINKS = ["recoveryCodes"];
+function checkLinks(links) {
+  if (typeof links !== "object" || links === null || Array.isArray(links)) {
+    refuse("links must be an object, as { verifyEmail, resetPassword, secureAccount, getStarted }");
+  }
+  const given = links;
+  for (const name of REQUIRED_LINKS) {
+    if (typeof given[name] !== "function") {
+      refuse(`links.${name} must be a function`);
+    }
+  }
+  for (const name of OPTIONAL_LINKS) {
+    if (given[name] !== undefined && typeof given[name] !== "function") {
+      refuse(`links.${name} must be a function, or left out`);
+    }
+  }
+}
+function frozenLinks(links) {
+  const given = links;
+  const names = [
+    ...REQUIRED_LINKS,
+    ...OPTIONAL_LINKS.filter((name) => given[name] !== undefined)
+  ];
+  return Object.freeze(Object.fromEntries(names.map((name) => [
+    name,
+    given[name].bind(links)
+  ])));
+}
+
 // src/mails.ts
 import { fileURLToPath } from "node:url";
 import { createMailRenderer } from "@nxgt/mail/renderer";
@@ -149,6 +190,14 @@ function janusTemplates() {
     emailChanged: ({ brand, name, link, newEmail, locale }) => defaultRenderer().render("email-changed", { brand, name, link, newEmail }, { locale }),
     twoFactorEnabled: ({ brand, name, link, locale }) => defaultRenderer().render("two-factor-enabled", { brand, name, link }, { locale }),
     twoFactorDisabled: ({ brand, name, link, locale }) => defaultRenderer().render("two-factor-disabled", { brand, name, link }, { locale }),
+    recoveryCodeUsed: ({
+      brand,
+      name,
+      when,
+      recoveryCodesLeft,
+      link,
+      locale
+    }) => defaultRenderer().render("recovery-code-used", { brand, name, when, recoveryCodesLeft, link }, { locale }),
     welcome: ({ brand, name, link, locale }) => defaultRenderer().render("welcome", { brand, name, link }, { locale })
   });
 }
@@ -162,14 +211,9 @@ var TEMPLATE_NAMES = [
   "emailChanged",
   "twoFactorEnabled",
   "twoFactorDisabled",
+  "recoveryCodeUsed",
   "welcome"
 ];
-var LINK_NAMES = [
-  "verifyEmail",
-  "resetPassword",
-  "secureAccount",
-  "getStarted"
-];
 var SYSTEM_CLOCK = Object.freeze({ now: () => new Date });
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -179,9 +223,6 @@ function isAddress(value) {
     return value.trim() !== "";
   return isObject(value) && typeof value.name === "string" && typeof value.address === "string" && value.address.trim() !== "";
 }
-function refuse(message) {
-  throw new TypeError(`janusMail: ${message}`);
-}
 function checkSending(options) {
   const { mailer, from, replyTo, brand, links } = options;
   if (!isObject(mailer) || typeof mailer.send !== "function") {
@@ -196,14 +237,7 @@ function checkSending(options) {
   if (typeof brand !== "string" || brand.trim() === "") {
     refuse("brand must be the name the e-mails show, as 'Acme'");
   }
-  if (!isObject(links)) {
-    refuse("links must be an object, as { verifyEmail, resetPassword, secureAccount, getStarted }");
-  }
-  for (const name of LINK_NAMES) {
-    if (typeof links[name] !== "function") {
-      refuse(`links.${name} must be a function`);
-    }
-  }
+  checkLinks(links);
 }
 function resolveClock(clock) {
   if (clock === undefined)
@@ -269,9 +303,6 @@ function resolveTemplates(options, locales) {
 function frozenAddress(address) {
   return typeof address === "string" ? address : Object.freeze({ name: address.name, address: address.address });
 }
-function frozenLinks(links) {
-  return Object.freeze(Object.fromEntries(LINK_NAMES.map((name) => [name, links[name].bind(links)])));
-}
 function resolveOptions(options) {
   if (!isObject(options)) {
     refuse("options must be an object, as { mailer, from, brand, links }");
@@ -291,12 +322,90 @@ function resolveOptions(options) {
   });
 }
 
+// src/generated/codes-left.ts
+var CODES_LEFT = {
+  en: {
+    "=0": [
+      "You have no recovery codes left."
+    ],
+    one: [
+      "You have ",
+      null,
+      " recovery code left."
+    ],
+    other: [
+      "You have ",
+      null,
+      " recovery codes left."
+    ]
+  },
+  fr: {
+    "=0": [
+      "Il ne vous reste aucun code de récupération."
+    ],
+    one: [
+      "Il vous reste ",
+      null,
+      " code de récupération."
+    ],
+    other: [
+      "Il vous reste ",
+      null,
+      " codes de récupération."
+    ]
+  }
+};
+
+// src/codes-left.ts
+function codesLeftText(locale, count) {
+  if (!Object.hasOwn(CODES_LEFT, locale))
+    return;
+  const branches = CODES_LEFT[locale];
+  const branch = branches[`=${count}`] ?? branches[new Intl.PluralRules(locale).select(count)] ?? branches.other;
+  const digits = new Intl.NumberFormat(locale).format(count);
+  return (branch ?? []).map((part) => part ?? digits).join("");
+}
+
+// src/recovery-mail.ts
+var METHOD = "recoveryCodeUsed";
+var isCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function codesLeft(used, locale) {
+  const given = typeof used === "object" && used !== null ? used.recoveryCodesLeft : undefined;
+  if (typeof given === "string")
+    return given;
+  if (!isCount(given)) {
+    throw new TypeError(`janusMail.${METHOD}: recoveryCodesLeft must be a count — a whole number, 0 or more — or the sentence to show`);
+  }
+  const text = codesLeftText(locale, given);
+  if (text === undefined) {
+    throw new TypeError(`janusMail.${METHOD}: recoveryCodesLeft must be the sentence to show in a locale the default e-mails are not built in`);
+  }
+  return text;
+}
+function recoveryMail(options) {
+  const { brand, links } = options;
+  return {
+    async recoveryCodeUsed(to, used) {
+      const locale = localeFor(options, to);
+      return send(options, METHOD, field(METHOD, to, "email"), {
+        brand,
+        name: field(METHOD, to, "name"),
+        when: field(METHOD, used, "when"),
+        recoveryCodesLeft: codesLeft(used, locale),
+        link: links.recoveryCodes === undefined ? link(METHOD, links.secureAccount(), "secureAccount()") : link(METHOD, links.recoveryCodes(), "recoveryCodes()"),
+        locale
+      });
+    }
+  };
+}
+
 // src/janus-mail.ts
 function janusMail(options) {
   const resolved = resolveOptions(options);
   const mail = Object.freeze({
     ...expiringMails(resolved),
     ...noticeMails(resolved),
+    ...recoveryMail(resolved),
     templates: resolved.templates,
     locales: resolved.locales
   });
@@ -307,5 +416,5 @@ export {
   janusTemplates
 };
 
-//# debugId=D782DBFE9A92F69064756E2164756E21
+//# debugId=E470EFFF013B3B0B64756E2164756E21
 //# sourceMappingURL=index.js.map