@nxgt/janus-mail 0.1.0 → 0.2.0

package/README.md

@@ -29,8 +29,8 @@ The e-mails are built with [Maizzle](https://maizzle.com) when **this
 package** is built — from
 [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail-presets),
 CSS inlined for mail clients — and shipped as HTML and text. At send time
-they are only filled in: your brand, the recipient's name, your links, every
-value escaped. No template engine and no Maizzle run in your server.
+they are only filled in: your brand, the recipient's name, your links, how
+long the link or code lasts, every value escaped. No template engine and no Maizzle run in your server.
 
 > **0.x.** A minor version may still change the surface; the changelog says how.
 
@@ -54,11 +54,12 @@ runtime. Like `@nxgt/janus`, it expects `"moduleResolution": "bundler"`.
 
 | Export | What it is |
 | --- | --- |
-| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `passwordChanged`, `emailChanged`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`), `locales?`, `fallbackLocale?`, `templates?`. A wrong option is a bare `TypeError`, thrown here |
+| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `passwordChanged`, `emailChanged`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`), `locales?`, `fallbackLocale?`, `templates?`, `clock?`. A wrong option is a bare `TypeError`, thrown here |
 | `janusTemplates()` | The five 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 five of them, and their names |
-| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code` or `newEmail` as its e-mail needs |
+| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code`, `expiresIn` or `newEmail` 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? }` |
 
@@ -68,12 +69,21 @@ class.
 
 | Method | Sends | To |
 | --- | --- | --- |
-| `verifyEmail(issued, to)` | `issued` from `auth.verifyEmail.send(user)`; a link from `links.verifyEmail(issued.token)` | `issued.email` |
-| `resetPassword(issued, to)` | `issued` from `auth.resetPassword.request(email)`, checked for `null`; a link from `links.resetPassword(issued.token)` | `issued.email` |
-| `signInCode(issued, to?)` | `issued.code` from `auth.signInCode.request(email)` — **never the challenge** | `issued.email` |
+| `verifyEmail(issued, to, options?)` | `issued` from `auth.verifyEmail.send(user)`; a link from `links.verifyEmail(issued.token)`, and how long it lasts | `issued.email` |
+| `resetPassword(issued, to, options?)` | `issued` from `auth.resetPassword.request(email)`, checked for `null`; a link from `links.resetPassword(issued.token)`, and how long it lasts | `issued.email` |
+| `signInCode(issued, to?, options?)` | `issued.code` from `auth.signInCode.request(email)`, and how long it lasts — **never the challenge** | `issued.email` |
 | `passwordChanged(to)` | A notice, with `links.secureAccount()` | `to.email` |
 | `emailChanged(to)` | A notice naming `to.newEmail`, with `links.secureAccount()` | `to.formerEmail` |
 
+The three e-mails of a link or a code say how long it lasts — "This link
+expires in 1 hour.", "Ce lien expire dans 1 heure." — from the flow's
+`issued.expiresAt`: the time left at send time, rounded to the minute, then
+down to the largest whole unit (days, hours or minutes), formatted with
+`Intl.NumberFormat` in the recipient's locale. The time is read from
+`janusMail({ clock })` — give it the clock you gave `janus({ clock })` —
+else the system clock. Pass `{ expiresIn }` to say it yourself, as plain
+text in the recipient's language.
+
 ## Usage
 
 The examples use `mail` from above, and an `auth` whose user schema has a
@@ -110,6 +120,12 @@ if (issued !== null) {
 }
 ```
 
+### Saying the expiry yourself
+
+```ts
+await mail.verifyEmail(issued, { name: user.name, locale: 'fr' }, { expiresIn: '24 heures' });
+```
+
 ### Telling a user their password changed
 
 ```ts
@@ -192,9 +208,27 @@ templates is a compile error, and a `TypeError` in JavaScript.
 body and the footer, escaped: no logo, no link, no markup. For those, replace
 the templates.
 
-**The default e-mails do not state the expiry.** `@nxgt/mail-presets`' bodies
-say nothing of how long a link or a code lasts. If yours must, replace the
-template: `issued.expiresAt` is yours to format.
+**Send the flow's answer as it came: `expiresAt` must be a `Date`.** The
+expiry is derived from `issued.expiresAt` at send time. A flow's answer that
+went through JSON — a job queue — holds a string there, which is a compile
+error and, in JavaScript, a `TypeError` (`expiresAt must be a Date`); revive
+it with `new Date(...)`, or pass `{ expiresIn }`. An `expiresAt` already past
+is a `TypeError` too: the link would not work, so nothing is sent.
+
+**Give `janusMail()` the clock you gave `janus()`.** The time left is
+measured against `clock`, the system clock by default. Tests that run
+`janus({ clock: fixedClock(...) })` issue an `expiresAt` in the clock's time:
+without the same `clock` here, a clock set in the past makes every send an
+`expiresAt is past` `TypeError`, and one set ahead a wrong duration.
+
+**Locales are BCP 47 tags: `fr-CA`, never `fr_CA`.** The expiry is
+formatted by `Intl` in the locale picked, so a locale `Intl` refuses is a
+`TypeError` from `janusMail()`.
+
+**The expiry is formatted by the runtime's `Intl`.** A locale the runtime has
+no data for is formatted in its default language, and French puts a no-break
+space between the number and some units, as CLDR says. For a wording of your
+own, pass `{ expiresIn }`.
 
 **A failed send is `MAIL_FAILED`; answer it as an outage.** In an HTTP
 handler, a `MailFailure` is a `503` — nothing is known to have been sent —
@@ -224,10 +258,12 @@ The symptoms and fixes are in [troubleshooting](docs/troubleshooting.md).
 
 ## Type safety, counted
 
-**Twenty plausible mistakes, twenty refused at compile time.**
+**Twenty-five plausible mistakes, twenty-five refused at compile time.**
 [`test/types/refusals.ts`](test/types/refusals.ts) holds one
 `@ts-expect-error` per mistake, beside the calls that must keep compiling —
-among them adding a language with every template:
+among them adding a language with every template — and
+[`test/types/expiry-refusals.ts`](test/types/expiry-refusals.ts) the five of
+the expiry and the clock, 21 to 25:
 
 1. A sign-in code given to `verifyEmail`: it has no token.
 2. A one-time token given to `signInCode`: it has no code.
@@ -249,9 +285,14 @@ among them adding a language with every template:
 18. A template read from `mail.templates` that does not exist.
 19. A link computed asynchronously.
 20. A link answered as a `URL` object rather than its `href`.
-
-In JavaScript, 19 and 20 are a `TypeError` at send time instead, naming the
-call.
+21. A sign-in code without its `expiresAt`.
+22. A flow's answer that went through JSON: `expiresAt` a string.
+23. `expiresIn` given as a number of seconds rather than the text to show.
+24. `expiresIn` given with the recipient rather than as the send's option.
+25. `clock` given as a function rather than `@nxgt/janus`'s `Clock`.
+
+In JavaScript, 19 to 23 are a `TypeError` at send time instead, naming the
+call or the field, and 25 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/expiring-mails.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedOptions } from './options';
+import type { JanusMail } from './types';
+type ExpiringMails = Pick<JanusMail<string>, 'verifyEmail' | 'resetPassword' | 'signInCode'>;
+/** `verifyEmail`, `resetPassword` and `signInCode`, over the resolved options. */
+export declare function expiringMails(options: ResolvedOptions): ExpiringMails;
+export {};
+//# sourceMappingURL=expiring-mails.d.ts.map

package/dist/expiring-mails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiring-mails.d.ts","sourceRoot":"","sources":["../src/expiring-mails.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,KAAK,aAAa,GAAG,IAAI,CACxB,SAAS,CAAC,MAAM,CAAC,EACjB,aAAa,GAAG,eAAe,GAAG,YAAY,CAC9C,CAAC;AAoBF,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAqBrE"}

package/dist/expiry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `expiresIn`: how long the link or the code of an e-mail stays valid, as
+ * the text the e-mail shows — "1 hour", "1 heure". Derived from the
+ * `expiresAt` the flow answered and the locale the recipient gets, unless the
+ * send passes its own.
+ */
+import type { Clock } from '@nxgt/janus';
+/**
+ * A duration in the locale, in the largest unit it holds at least once:
+ * rounded to the minute first — the flow set `expiresAt` a moment before the
+ * send, so an hour is 59 minutes and 59 seconds by then — and then down to a
+ * whole unit: 90 minutes is "1 hour", 36 hours "1 day". At 30 seconds or
+ * more, the e-mail never promises more than half a minute beyond what is
+ * left; under that, it says "1 minute".
+ *
+ * ```ts
+ * formatExpiry(3_600_000, 'fr'); // '1 heure'
+ * ```
+ */
+export declare function formatExpiry(ms: number, locale: string): string;
+/**
+ * The `expiresIn` of one send: the one passed, as is, or the time left
+ * until the flow's `expiresAt` by `clock` — the one given to `janus()`, when
+ * it was given to `janusMail()` too — in `locale`. A `TypeError` naming the method
+ * when `expiresAt` is not a valid `Date` — a flow's answer that went through
+ * JSON holds a string there — or is already past.
+ */
+export declare function expiresInFor(method: string, issued: unknown, locale: string, options: unknown, clock: Clock): string;
+//# sourceMappingURL=expiry.d.ts.map

package/dist/expiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.d.ts","sourceRoot":"","sources":["../src/expiry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAMzC;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAa/D;AAcD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,GACV,MAAM,CAqBR"}

package/dist/generated/mail.d.ts

@@ -13,15 +13,18 @@ export interface MailEmails {
     };
     "reset-password": {
         readonly brand: string | number;
+        readonly expiresIn: string | number;
         readonly link: string;
         readonly name: string | number;
     };
     "sign-in-code": {
         readonly brand: string | number;
         readonly code: string | number;
+        readonly expiresIn: string | number;
     };
     "verify-email": {
         readonly brand: string | number;
+        readonly expiresIn: string | number;
         readonly link: string;
         readonly name: 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,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7G,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACpF,cAAc,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;CAC3G"}
+{"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,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;CAChJ"}

package/dist/index.d.ts

@@ -16,5 +16,5 @@
  */
 export { janusMail } from './janus-mail';
 export { janusTemplates } from './templates';
-export type { JanusMail, JanusMailLinks, JanusMailLocale, JanusMailOptions, JanusMailTemplate, JanusMailTemplateName, JanusMailTemplates, JanusMailVariables, Recipient, } from './types';
+export type { JanusMail, JanusMailLinks, JanusMailLocale, JanusMailOptions, JanusMailSendOptions, JanusMailTemplate, JanusMailTemplateName, JanusMailTemplates, JanusMailVariables, Recipient, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACX,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACX,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,5 +1,128 @@
-// src/janus-mail.ts
+// src/expiry.ts
+var MINUTE_MS = 60000;
+var MINUTES_IN_HOUR = 60;
+var MINUTES_IN_DAY = 24 * MINUTES_IN_HOUR;
+function formatExpiry(ms, locale) {
+  const minutes = Math.max(1, Math.round(ms / MINUTE_MS));
+  const [value, unit] = minutes >= MINUTES_IN_DAY ? [Math.floor(minutes / MINUTES_IN_DAY), "day"] : minutes >= MINUTES_IN_HOUR ? [Math.floor(minutes / MINUTES_IN_HOUR), "hour"] : [minutes, "minute"];
+  return new Intl.NumberFormat(locale, {
+    style: "unit",
+    unit,
+    unitDisplay: "long"
+  }).format(value);
+}
+function passedExpiresIn(method, options) {
+  const read = typeof options === "object" && options !== null ? options.expiresIn : undefined;
+  if (read !== undefined && typeof read !== "string") {
+    throw new TypeError(`janusMail.${method}: expiresIn must be a string`);
+  }
+  return read;
+}
+function expiresInFor(method, issued, locale, options, clock) {
+  const passed = passedExpiresIn(method, options);
+  if (passed !== undefined)
+    return passed;
+  const expiresAt = typeof issued === "object" && issued !== null ? issued.expiresAt : undefined;
+  if (!(expiresAt instanceof Date) || Number.isNaN(expiresAt.getTime())) {
+    throw new TypeError(`janusMail.${method}: expiresAt must be a Date`);
+  }
+  const now = clock.now();
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
+    throw new TypeError(`janusMail.${method}: clock.now() must answer a Date`);
+  }
+  const left = expiresAt.getTime() - now.getTime();
+  if (left <= 0) {
+    throw new TypeError(`janusMail.${method}: expiresAt is past — the link or code would not work`);
+  }
+  return formatExpiry(left, locale);
+}
+
+// src/send.ts
 import { pickLocale } from "@nxgt/mail";
+function field(method, value, key) {
+  const read = typeof value === "object" && value !== null ? value[key] : undefined;
+  if (typeof read !== "string") {
+    throw new TypeError(`janusMail.${method}: ${key} must be a string`);
+  }
+  return read;
+}
+function link(method, value, call) {
+  if (typeof value !== "string") {
+    throw new TypeError(`janusMail.${method}: links.${call} must answer a string`);
+  }
+  return value;
+}
+function localeFor(options, to) {
+  const wanted = typeof to === "object" && to !== null ? to.locale : undefined;
+  return pickLocale(wanted, options.locales, options.fallbackLocale);
+}
+async function send(options, name, address, variables) {
+  const template = options.templates[name];
+  const { subject, html, text } = await template(variables);
+  const replyTo = options.replyTo === undefined ? {} : { replyTo: options.replyTo };
+  return options.mailer.send({
+    to: address,
+    from: options.from,
+    ...replyTo,
+    subject,
+    html,
+    text
+  });
+}
+
+// src/expiring-mails.ts
+function linkMail(options, name) {
+  return async (issued, to, sendOptions) => {
+    const token = field(name, issued, "token");
+    const locale = localeFor(options, to);
+    return send(options, name, field(name, issued, "email"), {
+      brand: options.brand,
+      name: field(name, to, "name"),
+      link: link(name, options.links[name](token), `${name}(token)`),
+      expiresIn: expiresInFor(name, issued, locale, sendOptions, options.clock),
+      locale
+    });
+  };
+}
+function expiringMails(options) {
+  return {
+    verifyEmail: linkMail(options, "verifyEmail"),
+    resetPassword: linkMail(options, "resetPassword"),
+    async signInCode(issued, to, sendOptions) {
+      const locale = localeFor(options, to);
+      return send(options, "signInCode", field("signInCode", issued, "email"), {
+        brand: options.brand,
+        code: field("signInCode", issued, "code"),
+        expiresIn: expiresInFor("signInCode", issued, locale, sendOptions, options.clock),
+        locale
+      });
+    }
+  };
+}
+
+// src/notice-mails.ts
+function noticeMails(options) {
+  const { brand, links } = options;
+  return {
+    async passwordChanged(to) {
+      return send(options, "passwordChanged", field("passwordChanged", to, "email"), {
+        brand,
+        name: field("passwordChanged", to, "name"),
+        link: link("passwordChanged", links.secureAccount(), "secureAccount()"),
+        locale: localeFor(options, to)
+      });
+    },
+    async emailChanged(to) {
+      return send(options, "emailChanged", field("emailChanged", to, "formerEmail"), {
+        brand,
+        name: field("emailChanged", to, "name"),
+        link: link("emailChanged", links.secureAccount(), "secureAccount()"),
+        newEmail: field("emailChanged", to, "newEmail"),
+        locale: localeFor(options, to)
+      });
+    }
+  };
+}
 
 // src/generated/locales.ts
 var LOCALES = ["en", "fr"];
@@ -17,9 +140,9 @@ function defaultRenderer() {
 // src/templates.ts
 function janusTemplates() {
   return Object.freeze({
-    verifyEmail: ({ brand, name, link, locale }) => defaultRenderer().render("verify-email", { brand, name, link }, { locale }),
-    resetPassword: ({ brand, name, link, locale }) => defaultRenderer().render("reset-password", { brand, name, link }, { locale }),
-    signInCode: ({ brand, code, locale }) => defaultRenderer().render("sign-in-code", { brand, code }, { locale }),
+    verifyEmail: ({ brand, name, link, expiresIn, locale }) => defaultRenderer().render("verify-email", { brand, name, link, expiresIn }, { locale }),
+    resetPassword: ({ brand, name, link, expiresIn, locale }) => defaultRenderer().render("reset-password", { brand, name, link, expiresIn }, { locale }),
+    signInCode: ({ brand, code, expiresIn, locale }) => defaultRenderer().render("sign-in-code", { brand, code, expiresIn }, { locale }),
     passwordChanged: ({ brand, name, link, locale }) => defaultRenderer().render("password-changed", { brand, name, link }, { locale }),
     emailChanged: ({ brand, name, link, newEmail, locale }) => defaultRenderer().render("email-changed", { brand, name, link, newEmail }, { locale })
   });
@@ -34,6 +157,7 @@ var TEMPLATE_NAMES = [
   "emailChanged"
 ];
 var LINK_NAMES = ["verifyEmail", "resetPassword", "secureAccount"];
+var SYSTEM_CLOCK = Object.freeze({ now: () => new Date });
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -68,12 +192,31 @@ function checkSending(options) {
     }
   }
 }
+function resolveClock(clock) {
+  if (clock === undefined)
+    return SYSTEM_CLOCK;
+  if (!isObject(clock) || typeof clock.now !== "function") {
+    refuse("clock must be a Clock — an object with a now function");
+  }
+  return Object.freeze({ now: clock.now.bind(clock) });
+}
+function isLanguageTag(locale) {
+  try {
+    Intl.getCanonicalLocales(locale);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function resolveLocales(options) {
   const wanted = options.locales ?? LOCALES;
   if (!Array.isArray(wanted) || wanted.length === 0 || !wanted.every((locale) => typeof locale === "string" && locale !== "")) {
     refuse("locales must list at least one locale, as ['en', 'fr']");
   }
   const locales = Object.freeze([...wanted]);
+  if (!locales.every(isLanguageTag)) {
+    refuse("locales must be BCP 47 language tags, with hyphens, as 'fr-CA'");
+  }
   if (new Set(locales).size !== locales.length) {
     refuse("locales holds the same locale twice");
   }
@@ -134,92 +277,17 @@ function resolveOptions(options) {
     links: frozenLinks(options.links),
     locales,
     fallbackLocale,
-    templates: resolveTemplates(options, locales)
+    templates: resolveTemplates(options, locales),
+    clock: resolveClock(options.clock)
   });
 }
 
 // src/janus-mail.ts
-function field(method, value, key) {
-  const read = typeof value === "object" && value !== null ? value[key] : undefined;
-  if (typeof read !== "string") {
-    throw new TypeError(`janusMail.${method}: ${key} must be a string`);
-  }
-  return read;
-}
-function link(method, value, call) {
-  if (typeof value !== "string") {
-    throw new TypeError(`janusMail.${method}: links.${call} must answer a string`);
-  }
-  return value;
-}
-function localeFor(options, to) {
-  const wanted = typeof to === "object" && to !== null ? to.locale : undefined;
-  return pickLocale(wanted, options.locales, options.fallbackLocale);
-}
-async function send(options, name, address, variables) {
-  const template = options.templates[name];
-  const { subject, html, text } = await template(variables);
-  const replyTo = options.replyTo === undefined ? {} : { replyTo: options.replyTo };
-  return options.mailer.send({
-    to: address,
-    from: options.from,
-    ...replyTo,
-    subject,
-    html,
-    text
-  });
-}
-function methods(options) {
-  const { brand, links } = options;
-  return {
-    async verifyEmail(issued, to) {
-      const token = field("verifyEmail", issued, "token");
-      return send(options, "verifyEmail", field("verifyEmail", issued, "email"), {
-        brand,
-        name: field("verifyEmail", to, "name"),
-        link: link("verifyEmail", links.verifyEmail(token), "verifyEmail(token)"),
-        locale: localeFor(options, to)
-      });
-    },
-    async resetPassword(issued, to) {
-      const token = field("resetPassword", issued, "token");
-      return send(options, "resetPassword", field("resetPassword", issued, "email"), {
-        brand,
-        name: field("resetPassword", to, "name"),
-        link: link("resetPassword", links.resetPassword(token), "resetPassword(token)"),
-        locale: localeFor(options, to)
-      });
-    },
-    async signInCode(issued, to) {
-      return send(options, "signInCode", field("signInCode", issued, "email"), {
-        brand,
-        code: field("signInCode", issued, "code"),
-        locale: localeFor(options, to)
-      });
-    },
-    async passwordChanged(to) {
-      return send(options, "passwordChanged", field("passwordChanged", to, "email"), {
-        brand,
-        name: field("passwordChanged", to, "name"),
-        link: link("passwordChanged", links.secureAccount(), "secureAccount()"),
-        locale: localeFor(options, to)
-      });
-    },
-    async emailChanged(to) {
-      return send(options, "emailChanged", field("emailChanged", to, "formerEmail"), {
-        brand,
-        name: field("emailChanged", to, "name"),
-        link: link("emailChanged", links.secureAccount(), "secureAccount()"),
-        newEmail: field("emailChanged", to, "newEmail"),
-        locale: localeFor(options, to)
-      });
-    }
-  };
-}
 function janusMail(options) {
   const resolved = resolveOptions(options);
   const mail = Object.freeze({
-    ...methods(resolved),
+    ...expiringMails(resolved),
+    ...noticeMails(resolved),
     templates: resolved.templates,
     locales: resolved.locales
   });
@@ -230,5 +298,5 @@ export {
   janusTemplates
 };
 
-//# debugId=B2A314C222070DD464756E2164756E21
+//# debugId=941D325BF4DF9C0164756E2164756E21
 //# sourceMappingURL=index.js.map