@nxgt/janus-mail 0.1.0 → 0.2.1

package/docs/guide/sending.md

@@ -48,6 +48,7 @@ time one is sent, and kept.
 | `locales` | `readonly L[]` | `['en', 'fr']` | The locales sent in — see [Locales](locales.md) |
 | `fallbackLocale` | one of `locales` | `'en'`, else the first of `locales` | The locale when the recipient wants none of `locales` |
 | `templates` | `Partial<JanusMailTemplates<L>>` | none | Your own templates, over the defaults — see [Templates](templates.md) |
+| `clock` | `Clock` from `@nxgt/janus` | the system clock | What the time left until a flow's `expiresAt` is measured against — pass the one `janus({ clock })` was given; see [The expiry](#the-expiry) |
 
 Every link is called at send time, and must answer an absolute `http:`,
 `https:` or `mailto:` URL: a default template refuses anything else with
@@ -72,16 +73,17 @@ option and never its value — every message is in
 Each method renders its e-mail with its template, hands it to the mailer,
 and answers the mailer's `SentMail` (`{ messageId }`).
 
-### `verifyEmail(issued, to)`
+### `verifyEmail(issued, to, options?)`
 
 ```ts
 const issued = await auth.verifyEmail.send(user); // IssuedToken: { token, email, expiresAt }
 await mail.verifyEmail(issued, { name: user.name, locale: user.locale });
 ```
 
-Sent to `issued.email`, with the link `links.verifyEmail(issued.token)`.
+Sent to `issued.email`, with the link `links.verifyEmail(issued.token)` and
+how long it lasts — see [The expiry](#the-expiry).
 
-### `resetPassword(issued, to)`
+### `resetPassword(issued, to, options?)`
 
 ```ts
 const issued = await auth.resetPassword.request(email); // (IssuedToken & { user }) | null
@@ -92,16 +94,18 @@ if (issued !== null) {
 
 `request` answers `null` for an address nobody holds, and the compiler
 refuses `null` here: check it first, and answer the visitor the same either
-way. Sent to `issued.email`, with `links.resetPassword(issued.token)`.
+way. Sent to `issued.email`, with `links.resetPassword(issued.token)` and how
+long it lasts.
 
-### `signInCode(issued, to?)`
+### `signInCode(issued, to?, options?)`
 
 ```ts
 const issued = await auth.signInCode.request(email); // IssuedCode: { code, challenge, email, expiresAt, user } | null
 if (issued !== null) await mail.signInCode(issued, { locale: issued.user.locale });
 ```
 
-It reads `issued.code` and `issued.email`, **and nothing else**: the
+It reads `issued.code`, `issued.email` and `issued.expiresAt`, **and nothing
+else**: the
 challenge is the visitor's secret, and neither the default template nor an
 override is ever given it. `to` is optional — the e-mail greets nobody by
 name — and only its `locale` is read.
@@ -130,6 +134,50 @@ 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.
 
+## The expiry
+
+`verifyEmail`, `resetPassword` and `signInCode` say how long the link or the
+code lasts — "This link expires in 1 hour.", "Ce code expire dans
+10 minutes." The text is `expiresIn`, one of the template's variables,
+derived at send time from the flow's `issued.expiresAt`:
+
+1. the time left until `expiresAt`, rounded to the minute — the flow set it a
+   moment ago, so an hour is still "1 hour";
+2. then **down** to the largest whole unit it holds — days, hours or minutes
+   — so, 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". 90 minutes is
+   "1 hour", 36 hours "1 day";
+3. formatted by `Intl.NumberFormat` with `style: 'unit'` and
+   `unitDisplay: 'long'`, in the recipient's locale: "3 hours", "3 heures".
+
+With `@nxgt/janus`'s defaults, a verification link says "1 day", a reset
+link "1 hour" and a sign-in code "10 minutes".
+
+The time is `janusMail({ clock })`'s — pass the clock `janus({ clock })` was
+given, a `fixedClock` in tests — else the system clock:
+
+```ts
+import { fixedClock } from '@nxgt/janus';
+
+const clock = fixedClock(Date.UTC(2026, 0, 1));
+const auth = janus({ /* … */ clock });
+const mail = janusMail({ mailer, from, brand: 'Acme', links, clock });
+```
+
+To say it yourself — another wording, or a locale the runtime's `Intl` has no
+data for — pass `expiresIn` as the third argument, plain text already in the
+recipient's language. `expiresAt` is then not read:
+
+```ts
+await mail.verifyEmail(issued, { name: user.name, locale: 'fr' }, { expiresIn: '24 heures' });
+await mail.signInCode(issued, undefined, { expiresIn: 'ten minutes' });
+```
+
+A send whose `expiresAt` is not a valid `Date` — a flow's answer that went
+through JSON on its way to a queue holds a string — or is already past, is
+a `TypeError`, and nothing reaches the mailer: revive the date with
+`new Date(issued.expiresAt)` when the job runs, or pass `expiresIn`.
+
 ## Where each e-mail goes
 
 | Method | To | Never to |
@@ -157,7 +205,7 @@ defines no error class and wraps nothing:
 | --- | --- | --- | --- |
 | `MailFailure` (`MAIL_FAILED`) | the mailer | The transport could not hand the e-mail over. Nothing is known to have been sent | A `503`, or a retry from a queue |
 | `MailRefused` (`MAIL_REFUSED`) | the renderer, or the mailer | The e-mail itself is wrong: a link that is not `http:`, `https:` or `mailto:`, an address that is not one | A bug to fix; sending it again fails again |
-| `TypeError` | this package, or the renderer | A call without the value a flow answered — `janusMail.resetPassword: token must be a string` — or, in JavaScript, a link that is not a string (a compile error in TypeScript) — `janusMail.verifyEmail: links.verifyEmail(token) must answer a string` | A bug to fix |
+| `TypeError` | this package, or the renderer | A call without the value a flow answered — `janusMail.resetPassword: token must be a string` — or, in JavaScript, a link that is not a string (a compile error in TypeScript) — `janusMail.verifyEmail: links.verifyEmail(token) must answer a string`. For [the expiry](#the-expiry): `janusMail.<method>: expiresAt must be a Date`, `janusMail.<method>: expiresAt is past — the link or code would not work`, `janusMail.<method>: expiresIn must be a string`, `janusMail.<method>: clock.now() must answer a Date` | A bug to fix — for a past `expiresAt`, issue a new token or code and send that |
 | `Error` from `createMailRenderer` | the renderer | `mails/` is missing where the package runs: a bundler inlined `@nxgt/janus-mail`, or a deploy kept `dist/` only | Keep `@nxgt/janus-mail` external to your bundle and deploy its `mails/` with it; see [troubleshooting](../troubleshooting.md#createmailrenderer-mailsmail-manifestjson-cannot-be-read--run-maizzle-build-and-deploy-its-output-folder) |
 
 `instanceof` holds against the classes of your own `@nxgt/mail`, since it is
@@ -197,9 +245,14 @@ fail:
 
 ```ts
 import { expect, it } from 'bun:test';
+import { fixedClock } from '@nxgt/janus';
 import { createMemoryMailer, MailFailure } from '@nxgt/mail';
 import { janusMail } from '@nxgt/janus-mail';
 
+// The clock given to janus({ clock }) too: the codes it issues expire ten minutes on.
+const clock = fixedClock(Date.UTC(2026, 0, 1, 9));
+const expiresAt = new Date(Date.UTC(2026, 0, 1, 9, 10));
+
 const links = {
 	verifyEmail: (token: string) => `https://acme.example/verify?token=${token}`,
 	resetPassword: (token: string) => `https://acme.example/reset?token=${token}`,
@@ -208,24 +261,25 @@ const links = {
 
 it('sends the code, and never the challenge', async () => {
 	const mailer = createMemoryMailer();
-	const mail = janusMail({ mailer, from: 'noreply@acme.example', brand: 'Acme', links });
-	const issued = { code: '042817', challenge: 'secret', email: 'ada@example.com' };
+	const mail = janusMail({ mailer, from: 'noreply@acme.example', brand: 'Acme', links, clock });
+	const issued = { code: '042817', challenge: 'secret', email: 'ada@example.com', expiresAt };
 
 	await mail.signInCode(issued, { locale: 'fr-CA' });
 
 	const [sent] = mailer.sent;
 	expect(sent?.to).toBe('ada@example.com');
 	expect(sent?.subject).toBe('Votre code de connexion : 042817');
+	expect(sent?.text).toContain('10 minutes.');
 	expect(`${sent?.html}${sent?.text}`).not.toContain('secret');
 });
 
 it('says so when the mailer is down', async () => {
 	const mailer = createMemoryMailer();
 	mailer.failNext();
-	const mail = janusMail({ mailer, from: 'noreply@acme.example', brand: 'Acme', links });
+	const mail = janusMail({ mailer, from: 'noreply@acme.example', brand: 'Acme', links, clock });
 
 	const error = await mail
-		.signInCode({ code: '042817', email: 'ada@example.com' })
+		.signInCode({ code: '042817', email: 'ada@example.com', expiresAt })
 		.then(() => null, (e: unknown) => e); // settled where it is created
 
 	expect(error).toBeInstanceOf(MailFailure);

package/docs/guide/templates.md

@@ -59,30 +59,30 @@ e-mail.
 
 | Template | Variables | Sent by |
 | --- | --- | --- |
-| `verifyEmail` | `brand`, `name`, `link` | `mail.verifyEmail(issued, to)` |
-| `resetPassword` | `brand`, `name`, `link` | `mail.resetPassword(issued, to)` |
-| `signInCode` | `brand`, `code` | `mail.signInCode(issued, to?)` |
+| `verifyEmail` | `brand`, `name`, `link`, `expiresIn` | `mail.verifyEmail(issued, to, options?)` |
+| `resetPassword` | `brand`, `name`, `link`, `expiresIn` | `mail.resetPassword(issued, to, options?)` |
+| `signInCode` | `brand`, `code`, `expiresIn` | `mail.signInCode(issued, to?, options?)` |
 | `passwordChanged` | `brand`, `name`, `link` | `mail.passwordChanged(to)` |
 | `emailChanged` | `brand`, `name`, `link`, `newEmail` | `mail.emailChanged(to)` |
 
 Every one also gets `locale`, one of `locales`. Every value is a string:
 `brand` from the options, `name` from the recipient, `link` from `links` —
 `links.secureAccount()` for the two notices — `code` and `newEmail` from the
-call.
+call, and `expiresIn` derived from the flow's `expiresAt` in the locale, or
+the send's own `expiresIn` ([Sending](sending.md#the-expiry)).
 
 `signInCode` is **never given the challenge**: it is not in its variables,
-and the method never reads it. `expiresAt` is not given either — the flows
-answer it, so a template that states the lifetime takes it from a closure:
+and the method never reads it. An override states the expiry from
+`expiresIn`, already formatted:
 
 ```ts
 const mail = janusMail({
 	mailer, from, brand: 'Acme', links,
 	templates: {
-		// The code lives ten minutes, @nxgt/janus's default for tokens.signInCode.
-		signInCode: ({ code, locale }) =>
+		signInCode: ({ code, expiresIn, locale }) =>
 			locale === 'fr'
-				? { subject: `Code : ${code}`, html: `<p>${code} — valable 10 minutes.</p>`, text: `${code} — valable 10 minutes.` }
-				: { subject: `Code: ${code}`, html: `<p>${code} — valid for 10 minutes.</p>`, text: `${code} — valid for 10 minutes.` },
+				? { subject: `Code : ${code}`, html: `<p>${code} — valable ${expiresIn}.</p>`, text: `${code} — valable ${expiresIn}.` }
+				: { subject: `Code: ${code}`, html: `<p>${code} — valid for ${expiresIn}.</p>`, text: `${code} — valid for ${expiresIn}.` },
 	},
 });
 ```
@@ -109,7 +109,7 @@ another locale, it takes **all five** — see
 rest — frozen:
 
 ```ts
-const rendered = await mail.templates.verifyEmail({ brand: 'Acme', name: 'Ada', link, locale: 'fr' });
+const rendered = await mail.templates.verifyEmail({ brand: 'Acme', name: 'Ada', link, expiresIn: '1 heure', locale: 'fr' });
 ```
 
 ## The defaults alone — `janusTemplates()`
@@ -122,6 +122,7 @@ const { subject, html, text } = await defaults.resetPassword({
 	brand: 'Acme',
 	name: 'Ada',
 	link: 'https://acme.example/reset?token=abc',
+	expiresIn: '1 heure',
 	locale: 'fr',
 });
 ```
@@ -152,7 +153,7 @@ them renders: that is when the package's `mails/` folder is read, once.
 ## What the defaults say
 
 The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail-presets)
-0.1.0, built with a neutral grey theme and no logo:
+0.3.0, built with a neutral grey theme and no logo:
 
 | Template | Built from | Subject (`en`) | Subject (`fr`) |
 | --- | --- | --- | --- |
@@ -167,8 +168,9 @@ Each has a header and a footer with the brand, a heading, a greeting by name
 client that shows no button, and a text part. The two notices add a warning:
 *if this was not you, secure your account now*.
 
-**They do not state how long a link or a code lasts.** Replace the template
-when yours must: see above.
+`verifyEmail`, `resetPassword` and `signInCode` also say how long the link
+or the code lasts: "This link expires in 1 hour.", "Ce code expire dans
+10 minutes." The text part keeps each paragraph on one line.
 
 **The brand is text.** It is written in the header, the body and the footer,
 escaped — no logo and no link, which would need absolute URLs known when the

package/docs/roadmap.md

@@ -13,8 +13,6 @@ Nothing between releases.
   `invitation` from `@nxgt/mail-presets`, each once `@nxgt/janus` has a flow
   that sends it: a sign-in link, a sign-in from a new device, a user created,
   an invitation to a user type.
-- **The expiry in the e-mail** — "the link expires in 24 hours", from the
-  flow's `expiresAt`, once the presets' messages take it.
 
 ## Later
 
@@ -46,6 +44,15 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **The expiry in the e-mail, v0.2.0.** The verification, reset and sign-in
+  code e-mails say how long the link or code lasts — "1 hour", "1 heure" —
+  derived from the flow's `expiresAt` in the recipient's locale, measured
+  against `janusMail({ clock })` (the clock given to `janus()`), or given per
+  send as `{ expiresIn }`. Two breaks: a template called directly takes
+  `expiresIn`, and `signInCode` reads `issued.expiresAt`. Built from
+  `@nxgt/mail-presets` 0.2.0, whose text parts keep each paragraph on one
+  line.
+
 - **The first release, v0.1.0.** The five e-mails of `@nxgt/janus`'s flows,
   in English and French, over any `@nxgt/mail` transport: `janusMail()` and
   `janusTemplates()`. Built with Maizzle when the package is built, shipped

package/docs/troubleshooting.md

@@ -1,7 +1,7 @@
 # Troubleshooting `@nxgt/janus-mail`
 
-Each entry is headed by the text you see: a message, an error `code`, or a
-compiler error. Search this page for the words of your message.
+Each entry is headed by the text you see: a message, an error `code`, a
+compiler error — or, where nothing is thrown, what the e-mail says. Search this page for the words of your message.
 
 How the messages are shaped:
 
@@ -28,16 +28,22 @@ How the messages are shaped:
 - [`janusMail: links must be an object, as { verifyEmail, resetPassword, secureAccount }`](#janusmail-links-must-be-an-object-as--verifyemail-resetpassword-secureaccount-)
 - [`janusMail: links.<name> must be a function`](#janusmail-linksname-must-be-a-function)
 - [`janusMail: locales must list at least one locale, as ['en', 'fr']`](#janusmail-locales-must-list-at-least-one-locale-as-en-fr)
+- [`janusMail: locales must be BCP 47 language tags, as 'fr-CA'`](#janusmail-locales-must-be-bcp-47-language-tags-as-fr-ca)
 - [`janusMail: locales holds the same locale twice`](#janusmail-locales-holds-the-same-locale-twice)
 - [`janusMail: fallbackLocale must be one of locales`](#janusmail-fallbacklocale-must-be-one-of-locales)
 - [`janusMail: templates must be an object of functions, as { verifyEmail: (variables) => rendered }`](#janusmail-templates-must-be-an-object-of-functions-as--verifyemail-variables--rendered-)
 - [`janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, passwordChanged, emailChanged`](#janusmail-templates-has-no-template-name--name-one-of-verifyemail-resetpassword-signincode-passwordchanged-emailchanged)
 - [`janusMail: templates.<name> must be a function`](#janusmail-templatesname-must-be-a-function)
 - [`janusMail: templates.<name> is not an own enumerable property — pass a plain object, as { <name>: (variables) => rendered }`](#janusmail-templatesname-is-not-an-own-enumerable-property--pass-a-plain-object-as--name-variables--rendered-)
+- [`janusMail: clock must be a Clock — an object with a now function`](#janusmail-clock-must-be-a-clock--an-object-with-a-now-function)
 - [`janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; <names> missing`](#janusmail-the-default-templates-are-built-in-en-and-fr-only--with-another-locale-in-locales-pass-every-template-in-templates-names-missing)
 
 **Sending**
 - [`janusMail.<method>: <field> must be a string`](#janusmailmethod-field-must-be-a-string)
+- [`janusMail.<method>: expiresAt must be a Date`](#janusmailmethod-expiresat-must-be-a-date)
+- [`janusMail.<method>: clock.now() must answer a Date`](#janusmailmethod-clocknow-must-answer-a-date)
+- [`janusMail.<method>: expiresAt is past — the link or code would not work`](#janusmailmethod-expiresat-is-past--the-link-or-code-would-not-work)
+- [`This link expires in 1 hour.` — in the wrong language, or shorter than the `tokens` TTL](#this-link-expires-in-1-hour--in-the-wrong-language-or-shorter-than-the-tokens-ttl)
 - [`MAIL_REFUSED` — `render: <email>: link must be an http:, https: or mailto: URL`](#mail_refused--render-email-link-must-be-an-http-https-or-mailto-url)
 - [`janusMail.<method>: links.<call> must answer a string`](#janusmailmethod-linkscall-must-answer-a-string)
 - [`render: <email>: link must be a string or a finite number`](#render-email-link-must-be-a-string-or-a-finite-number)
@@ -48,6 +54,7 @@ How the messages are shaped:
 
 **Compile errors**
 - [`TS2345: Argument of type '(IssuedToken & { user: … }) | null' is not assignable to parameter of type 'IssuedToken'.`](#ts2345-argument-of-type-issuedtoken---user----null-is-not-assignable-to-parameter-of-type-issuedtoken)
+- [`TS2345: … Types of property 'expiresAt' are incompatible. Type 'string' is not assignable to type 'Date'.`](#ts2345--types-of-property-expiresat-are-incompatible-type-string-is-not-assignable-to-type-date)
 - [`TS2739: Type '{ … }' is missing the following properties from type 'JanusMailTemplates<…>'`](#ts2739-type----is-missing-the-following-properties-from-type-janusmailtemplates)
 - [`TS2322: Type '"de"' is not assignable to type '"en" | "fr"'.`](#ts2322-type-de-is-not-assignable-to-type-en--fr)
 
@@ -115,6 +122,19 @@ links: {
 `locales: []`, `locales: 'en'`, or a list holding something that is not a
 non-empty string. Leave it out for `['en', 'fr']`.
 
+### `janusMail: locales must be BCP 47 language tags, as 'fr-CA'`
+
+A `TypeError` when `janusMail()` is called: a locale in `locales` is one
+`Intl` refuses — `de_DE` with an underscore, a grandfathered `i-klingon`, a
+bare private-use `x-…`. The expiry is formatted by `Intl` in the locale
+picked, so a locale it cannot parse would fail at the first send; it is
+refused here instead. Write a tag `Intl` takes — `de-DE`, not `de_DE`; `tlh`,
+not `i-klingon`:
+
+```ts
+janusMail({ mailer, from, brand: 'Acme', links, locales: ['en', 'fr', 'de-DE'], templates });
+```
+
 ### `janusMail: locales holds the same locale twice`
 
 `['en', 'en']`. List each once.
@@ -169,6 +189,18 @@ out: the defaults could not render them in that locale. Pass all five — see
 [Adding a locale](guide/locales.md#adding-a-locale) — or drop the locale.
 The message lists the templates missing.
 
+### `janusMail: clock must be a Clock — an object with a now function`
+
+`clock` is `@nxgt/janus`'s `Clock`, `{ now(): Date }` — pass the one given to
+`janus({ clock })`, not `Date.now` or `() => new Date()`:
+
+```ts
+import { fixedClock } from '@nxgt/janus';
+
+const clock = fixedClock(Date.UTC(2026, 0, 1));
+janusMail({ mailer, from, brand: 'Acme', links, clock });
+```
+
 ## Sending
 
 ### `janusMail.<method>: <field> must be a string`
@@ -186,7 +218,61 @@ if (issued !== null) await mail.resetPassword(issued, { name: issued.user.name }
 
 `issued` needs `token` and `email` (`code` and `email` for `signInCode`), and
 the recipient its `name` — a user whose schema has no name passes one
-anyway: `{ name: user.email }`.
+anyway: `{ name: user.email }`. `janusMail.verifyEmail: expiresIn must be a
+string` is the third argument's `expiresIn` given as something else — a
+number of seconds: pass the text to show, `{ expiresIn: '1 hour' }`, or
+leave it out.
+
+### `janusMail.<method>: expiresAt must be a Date`
+
+A `TypeError` from `verifyEmail`, `resetPassword` or `signInCode`: the e-mail
+says how long its link or code lasts, from `issued.expiresAt`, and that is
+not a valid `Date`. The usual cause is a flow's answer that went through
+JSON — a job queue, a cache — where a `Date` becomes a string. Nothing is
+sent. Revive it when the job runs, or say the expiry yourself:
+
+```ts
+const issued = { ...job.issued, expiresAt: new Date(job.issued.expiresAt) };
+await mail.verifyEmail(issued, { name: job.name });
+// or
+await mail.verifyEmail(job.issued, { name: job.name }, { expiresIn: '1 day' });
+```
+
+### `janusMail.<method>: clock.now() must answer a Date`
+
+A `TypeError` from `verifyEmail`, `resetPassword` or `signInCode`: the
+`clock` given to `janusMail()` has a `now` that answered something else — a
+number from `Date.now()`, a string, an invalid `Date`. Nothing is sent.
+`clock` is `@nxgt/janus`'s `Clock`: pass the one `janus({ clock })` was
+given, or `{ now: () => new Date() }`.
+
+### `janusMail.<method>: expiresAt is past — the link or code would not work`
+
+A `TypeError`: the send came after the link or the code expired — a queue
+that waited too long, an `expiresAt` from another record, or, in tests,
+`janus({ clock: fixedClock(...) })` without the same `clock` given to
+`janusMail()`, so a date in the clock's past is measured against today. Nothing is
+sent: an e-mail whose link fails helps nobody. Issue a new one
+(`auth.verifyEmail.send(user)`, `auth.signInCode.request(email)`) and send
+that; if a queue can hold a send that long, lengthen the `tokens` TTL in
+`janus({ tokens })`.
+
+### `This link expires in 1 hour.` — in the wrong language, or shorter than the `tokens` TTL
+
+`expiresIn` is formatted by the runtime's `Intl.NumberFormat`, in the locale
+picked for the recipient. A locale the runtime has no data for — a Node
+built with `small-icu`, a locale of your own — is formatted in the
+runtime's default language. The time left is measured against
+`janusMail({ clock })`, rounded to the minute, then **down** to the largest
+whole unit: 90 minutes is "1 hour", 36 hours "1 day".
+For another wording, pass it:
+
+```ts
+await mail.resetPassword(issued, { name, locale: 'de' }, { expiresIn: '90 Minuten' });
+```
+
+French puts a no-break space between the number and some units (`1 heure`,
+per CLDR): compare with `\s` in a test, not a plain space.
 
 ### `MAIL_REFUSED` — `render: <email>: link must be an http:, https: or mailto: URL`
 
@@ -300,7 +386,15 @@ return new Response(null, { status: 202 });
 
 The same holds for `signInCode.request`, whose answer passed unchecked reads
 `Argument of type 'IssuedCode<…> | null' is not assignable to parameter of
-type 'Pick<IssuedCode<unknown>, "email" | "code">'`.
+type 'Pick<IssuedCode<unknown>, "email" | "code" | "expiresAt">'`.
+
+### `TS2345: … Types of property 'expiresAt' are incompatible. Type 'string' is not assignable to type 'Date'.`
+
+A flow's answer that went through JSON, typed as it came out. Revive the
+date — `{ ...issued, expiresAt: new Date(issued.expiresAt) }` — or pass the
+expiry as text in the third argument. A sign-in code built by hand without
+`expiresAt` reads `Property 'expiresAt' is missing`: pass the flow's answer
+whole.
 
 ### `TS2739: Type '{ … }' is missing the following properties from type 'JanusMailTemplates<…>'`
 

package/mails/en/reset-password.html

@@ -28,8 +28,8 @@ font-weight:600;color:#020918;color:lab(2.35721% .367686 -8.51797);">Reset your
 <!--[if mso]><i style="mso-font-width:114%;mso-text-raise:19px;" hidden>&emsp;</i>
 <![endif]--> <span style="mso-text-raise:10px;">Choose a new password</span>
 <!--[if mso]><i style="mso-font-width:114%;" hidden>&emsp;&#8203;</i>
-<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If the button does not work, open this link: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not ask for this, you can
-ignore this e-mail.</p>
+<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">This link expires in {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If the button does not work, open this link: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{
+link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not ask for this, you can ignore this e-mail.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">You received this e-mail because you have an account with {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/en/reset-password.txt

@@ -12,10 +12,11 @@ Choose a new password
 
 {{ link }}
 
+This link expires in {{ expiresIn }}.
+
 If the button does not work, open this link: {{ link }}
 
-If you did not ask for this, you can
-ignore this e-mail.
+If you did not ask for this, you can ignore this e-mail.
 
 You received this e-mail because you have an account with {{ brand }}.
 

package/mails/en/sign-in-code.html

@@ -25,7 +25,7 @@
 </td></tr><tr><td style="border-radius:14px;border-color:#e2e8f0;border-style:solid;border-width:1px;border-color:lab(91.7353% -.998765 -4.76968);background-color:#fff;background-color:lab(100% 0 0);padding:32px;font-size:14px;line-height:20px;color:#020618;color:lab(1.76974% 1.32743 -9.28855);box-shadow:0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 1px 3px rgba(0,0,0,.1),0 1px 2px -1px rgba(0,0,0,.1);"><h1 style="margin:0 0 16px;font-size:24px;line-height:32px;
 font-weight:600;color:#020918;color:lab(2.35721% .367686 -8.51797);">Your sign-in code</h1><p style="margin:0 0 16px;font-size:14px;line-height:20px;color:#020918;color:lab(2.35721% .367686 -8.51797);">Enter this code to sign in to {{ brand }}. It works once.</p>
 <table role="presentation" cellpadding="0" cellspacing="0" style="margin-bottom:16px;width:100%;"><tr><td style="border-radius:10px;background-color:#f1f5f9;background-color:lab(96.286% -.852436 -2.46847);padding:16px 24px;text-align:center;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:30px;line-height:36px;font-weight:600;letter-spacing:.3em;color:#020918;color:lab(2.35721% .367686 -8.51797);">{{ code }}
-</td></tr></table><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not try to sign in, you can ignore this e-mail: no one can sign in without the code.</p>
+</td></tr></table><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">This code expires in {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not try to sign in, you can ignore this e-mail: no one can sign in without the code.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">You received this e-mail because you have an account with {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/en/sign-in-code.txt

@@ -8,6 +8,8 @@ Enter this code to sign in to {{ brand }}. It works once.
 
 {{ code }}
 
+This code expires in {{ expiresIn }}.
+
 If you did not try to sign in, you can ignore this e-mail: no one can sign in without the code.
 
 You received this e-mail because you have an account with {{ brand }}.

package/mails/en/verify-email.html

@@ -28,8 +28,8 @@ background-color:#27272a;padding:10px 16px;font-family:ui-sans-serif,system-ui,-
 <!--[if mso]><i style="mso-font-width:114%;mso-text-raise:19px;" hidden>&emsp;</i>
 <![endif]--> <span style="mso-text-raise:10px;">Confirm my address</span>
 <!--[if mso]><i style="mso-font-width:114%;" hidden>&emsp;&#8203;</i>
-<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If the button does not work, open this link: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not ask for this, you can
-ignore this e-mail.</p>
+<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">This link expires in {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If the button does not work, open this link: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{
+link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">If you did not ask for this, you can ignore this e-mail.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">You received this e-mail because you have an account with {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/en/verify-email.txt

@@ -12,10 +12,11 @@ Confirm my address
 
 {{ link }}
 
+This link expires in {{ expiresIn }}.
+
 If the button does not work, open this link: {{ link }}
 
-If you did not ask for this, you can
-ignore this e-mail.
+If you did not ask for this, you can ignore this e-mail.
 
 You received this e-mail because you have an account with {{ brand }}.
 

package/mails/fr/reset-password.html

@@ -27,8 +27,8 @@ style="display:inline-block;border-radius:9999px;background-color:#27272a;paddin
 <!--[if mso]><i style="mso-font-width:114%;mso-text-raise:19px;" hidden>&emsp;</i>
 <![endif]--> <span style="mso-text-raise:10px;">Choisir un nouveau mot de passe</span>
 <!--[if mso]><i style="mso-font-width:114%;" hidden>&emsp;&#8203;</i>
-<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si le bouton ne fonctionne pas, ouvrez ce lien&nbsp;: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'êtes pas à l'origine
-de cette demande, vous pouvez ignorer cet e-mail.</p>
+<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">Ce lien expire dans {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si le bouton ne fonctionne pas, ouvrez ce lien&nbsp;: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:
+underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'êtes pas à l'origine de cette demande, vous pouvez ignorer cet e-mail.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/fr/reset-password.txt

@@ -12,10 +12,11 @@ Choisir un nouveau mot de passe
 
 {{ link }}
 
+Ce lien expire dans {{ expiresIn }}.
+
 Si le bouton ne fonctionne pas, ouvrez ce lien : {{ link }}
 
-Si vous n'êtes pas à l'origine
-de cette demande, vous pouvez ignorer cet e-mail.
+Si vous n'êtes pas à l'origine de cette demande, vous pouvez ignorer cet e-mail.
 
 Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.
 

package/mails/fr/sign-in-code.html

@@ -25,7 +25,7 @@
 </td></tr><tr><td style="border-radius:14px;border-color:#e2e8f0;border-style:solid;border-width:1px;border-color:lab(91.7353% -.998765 -4.76968);background-color:#fff;background-color:lab(100% 0 0);padding:32px;font-size:14px;line-height:20px;color:#020618;color:lab(1.76974% 1.32743 -9.28855);box-shadow:0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 0 rgba(0,0,0,0),0 1px 3px rgba(0,0,0,.1),0 1px 2px -1px rgba(0,0,0,.1);"><h1 style="margin:0 0 16px;font-size:24px;line-height:32px;
 font-weight:600;color:#020918;color:lab(2.35721% .367686 -8.51797);">Votre code de connexion</h1><p style="margin:0 0 16px;font-size:14px;line-height:20px;color:#020918;color:lab(2.35721% .367686 -8.51797);">Saisissez ce code pour vous connecter à {{ brand }}. Il ne fonctionne qu'une fois.</p>
 <table role="presentation" cellpadding="0" cellspacing="0" style="margin-bottom:16px;width:100%;"><tr><td style="border-radius:10px;background-color:#f1f5f9;background-color:lab(96.286% -.852436 -2.46847);padding:16px 24px;text-align:center;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:30px;line-height:36px;font-weight:600;letter-spacing:.3em;color:#020918;color:lab(2.35721% .367686 -8.51797);">{{ code }}
-</td></tr></table><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'avez pas essayé de vous connecter, vous pouvez ignorer cet e-mail&nbsp;: personne ne peut se connecter sans ce code.</p>
+</td></tr></table><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">Ce code expire dans {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'avez pas essayé de vous connecter, vous pouvez ignorer cet e-mail&nbsp;: personne ne peut se connecter sans ce code.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/fr/sign-in-code.txt

@@ -8,6 +8,8 @@ Saisissez ce code pour vous connecter à {{ brand }}. Il ne fonctionne qu'une fo
 
 {{ code }}
 
+Ce code expire dans {{ expiresIn }}.
+
 Si vous n'avez pas essayé de vous connecter, vous pouvez ignorer cet e-mail : personne ne peut se connecter sans ce code.
 
 Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.

package/mails/fr/verify-email.html

@@ -28,8 +28,8 @@ border-radius:9999px;background-color:#27272a;padding:10px 16px;font-family:ui-s
 <!--[if mso]><i style="mso-font-width:114%;mso-text-raise:19px;" hidden>&emsp;</i>
 <![endif]--> <span style="mso-text-raise:10px;">Confirmer mon adresse</span>
 <!--[if mso]><i style="mso-font-width:114%;" hidden>&emsp;&#8203;</i>
-<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si le bouton ne fonctionne pas, ouvrez ce lien&nbsp;: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'êtes pas à l'origine
-de cette demande, vous pouvez ignorer cet e-mail.</p>
+<![endif]--></a></div><div role="separator" style="line-height:24px;">&zwj;</div><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#020918;color:lab(2.35721% .367686 -8.51797);">Ce lien expire dans {{ expiresIn }}.</p><p style="margin:0 0 16px;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si le bouton ne fonctionne pas, ouvrez ce lien&nbsp;: <a href="{{ link }}" style="color:#54a2ff;color:lab(65.0361% -1.42065 -56.9802);text-decoration:
+underline;">{{ link }}</a></p><p style="margin:0 0 16px;font-size:10px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);">Si vous n'êtes pas à l'origine de cette demande, vous pouvez ignorer cet e-mail.</p>
 </td></tr><tr><td style="padding-left:24px;padding-right:24px;padding-top:24px;text-align:center;font-size:12px;line-height:16px;color:#62748e;color:lab(48.0876% -2.03595 -16.5814);"><p style="margin:0 0 8px;">Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.</p><p style="margin:0;">{{ brand }}</p>
 </td></tr></table></div>
 <!--[if mso]>

package/mails/fr/verify-email.txt

@@ -12,10 +12,11 @@ Confirmer mon adresse
 
 {{ link }}
 
+Ce lien expire dans {{ expiresIn }}.
+
 Si le bouton ne fonctionne pas, ouvrez ce lien : {{ link }}
 
-Si vous n'êtes pas à l'origine
-de cette demande, vous pouvez ignorer cet e-mail.
+Si vous n'êtes pas à l'origine de cette demande, vous pouvez ignorer cet e-mail.
 
 Vous recevez cet e-mail parce que vous avez un compte chez {{ brand }}.
 

package/mails/mail-manifest.json

@@ -58,6 +58,7 @@
 		"reset-password": {
 			"variables": [
 				"brand",
+				"expiresIn",
 				"link",
 				"name"
 			],
@@ -82,7 +83,8 @@
 		"sign-in-code": {
 			"variables": [
 				"brand",
-				"code"
+				"code",
+				"expiresIn"
 			],
 			"urlVariables": [],
 			"subject": {
@@ -103,6 +105,7 @@
 		"verify-email": {
 			"variables": [
 				"brand",
+				"expiresIn",
 				"link",
 				"name"
 			],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-mail",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "The e-mails of @nxgt/janus's flows — e-mail verification, password reset, sign-in code, password changed, e-mail changed — rendered in English and French from a prebuilt Maizzle build, with your brand, sent through any @nxgt/mail transport",
 	"license": "MIT",
 	"type": "module",
@@ -54,11 +54,11 @@
 		"@maizzle/framework": "6.1.7",
 		"@maizzle/tailwindcss": "1.5.6",
 		"@nxgt/janus": "^0.8.8",
-		"@nxgt/mail": "0.5.1",
-		"@nxgt/mail-config": "0.2.0",
-		"@nxgt/mail-i18n": "0.3.0",
-		"@nxgt/mail-presets": "0.1.2",
-		"@nxgt/mail-ui": "0.1.1",
+		"@nxgt/mail": "0.6.0",
+		"@nxgt/mail-config": "0.2.1",
+		"@nxgt/mail-i18n": "0.4.0",
+		"@nxgt/mail-presets": "0.3.0",
+		"@nxgt/mail-ui": "0.3.0",
 		"@types/bun": "^1.4.2",
 		"vue": "3.5.43",
 		"vue-tsc": "^3.3.11"