@nxgt/janus-mail 0.3.2 → 0.4.1

package/dist/types.d.ts

@@ -4,75 +4,11 @@
  * once, in `janusMail()`.
  */
 import type { Clock, IssuedCode, IssuedToken } from '@nxgt/janus';
-import type { Address, Mailer, Rendered, SentMail, WantedLocales } from '@nxgt/mail';
+import type { Address, Mailer, SentMail, WantedLocales } from '@nxgt/mail';
 import type { JanusMailLocale } from './generated/locales';
+import type { JanusMailTemplates } from './template-types';
 export type { JanusMailLocale } from './generated/locales';
-/**
- * What each e-mail's template is given, by template name. Every value is
- * text: `brand` is the name `janusMail({ brand })` was given, `name` the
- * recipient's, `link` an absolute URL from `links`, and `expiresIn` how long
- * the link or the code stays valid, in the recipient's locale — "1 hour",
- * "1 heure" — or the send's own `expiresIn`.
- *
- * Held equal to the build's variables by `test/types/variables.ts`: an e-mail
- * of the build that gains or loses a variable fails the typecheck there.
- */
-export interface JanusMailVariables {
-    readonly verifyEmail: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-        readonly expiresIn: string;
-    };
-    readonly resetPassword: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-        readonly expiresIn: string;
-    };
-    /** No `challenge`, ever: it is the visitor's secret, and never goes in an e-mail. */
-    readonly signInCode: {
-        readonly brand: string;
-        readonly code: string;
-        readonly expiresIn: string;
-    };
-    readonly passwordChanged: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-    };
-    readonly emailChanged: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-        readonly newEmail: string;
-    };
-    readonly twoFactorEnabled: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-    };
-    readonly twoFactorDisabled: {
-        readonly brand: string;
-        readonly name: string;
-        readonly link: string;
-    };
-}
-/** The name of one of the seven templates: `verifyEmail`, `resetPassword`, … */
-export type JanusMailTemplateName = keyof JanusMailVariables;
-/**
- * One e-mail: its variables and the locale picked for the recipient, in; its
- * `subject`, `html` and `text`, out — escaping is then the function's job. A
- * default, from the prebuilt e-mails, or yours: React Email, a string, or
- * another Maizzle build.
- */
-export type JanusMailTemplate<V, L extends string = JanusMailLocale> = (variables: V & {
-    readonly locale: L;
-}) => Rendered | PromiseLike<Rendered>;
-/** The seven templates, each for the locales `L`. */
-export type JanusMailTemplates<L extends string = JanusMailLocale> = {
-    readonly [K in JanusMailTemplateName]: JanusMailTemplate<JanusMailVariables[K], L>;
-};
+export type { JanusMailTemplate, JanusMailTemplateName, JanusMailTemplates, JanusMailVariables, } from './template-types';
 /**
  * Who an e-mail is for, besides the address: the name it greets, and the
  * locales they want, most wanted first — their stored locale, then their
@@ -105,6 +41,12 @@ export interface JanusMailLinks {
      * and `twoFactorDisabled` link to it.
      */
     readonly secureAccount: () => string;
+    /**
+     * Where a new user starts — your application's home, or its sign-in page
+     * for an account someone else created. `welcome` links to it, from its
+     * "Get started" button.
+     */
+    readonly getStarted: () => string;
 }
 /** The options every locale set shares. */
 interface JanusMailBaseOptions<L extends string> {
@@ -196,6 +138,14 @@ export interface JanusMail<L extends string = JanusMailLocale> {
     twoFactorDisabled(to: Recipient & {
         readonly email: string;
     }): Promise<SentMail>;
+    /**
+     * Welcomes `to.email` to the brand, with a link to get started — on the
+     * `user.created` event, which `auth.create` and `auth.signUp` send once
+     * the user is inserted.
+     */
+    welcome(to: Recipient & {
+        readonly email: string;
+    }): Promise<SentMail>;
     /** The templates in use: the defaults, with `templates` over them. */
     readonly templates: JanusMailTemplates<L>;
     /** The locales sent in. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -5,11 +5,11 @@ 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 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` 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 |
-| [Troubleshooting](troubleshooting.md) | A `TypeError` at wiring or at a call, a `MailRefused`, a `MailFailure`, or a compile error |
+| [Troubleshooting](troubleshooting.md) | A `TypeError` at wiring or at a call, a `MailRefused`, a `MailFailure`, a compile error, or an e-mail that reads wrong in dark or light mode |
 | [Roadmap](roadmap.md) | You want to know what is coming, and what is deliberately not planned |
 
 ## Words
@@ -23,13 +23,14 @@ They mean the same here. These pages add:
 
 | Word | Means | Not |
 | --- | --- | --- |
-| **e-mail** | One of the seven this package sends: `verify-email`, `reset-password`, `sign-in-code`, `password-changed`, `email-changed`, `two-factor-enabled`, `two-factor-disabled` — by the name of its built file | "mail", "message" — a *message* is what a mailer sends, addressed |
+| **e-mail** | One of the eight this package sends: `verify-email`, `reset-password`, `sign-in-code`, `password-changed`, `email-changed`, `two-factor-enabled`, `two-factor-disabled`, `welcome` — by the name of its built file | "mail", "message" — a *message* is what a mailer sends, addressed |
 | **template** | The function that renders one e-mail: `(variables & { locale }) => Rendered`. Named in camelCase, after the method that sends it: `verifyEmail`, `signInCode` | "renderer" — the renderer is `@nxgt/mail`'s, and reads the build |
 | **default template** | A template of `janusTemplates()`: the prebuilt e-mail, filled by the renderer | "preset" — a preset is `@nxgt/mail-presets`' source, which the build compiles |
 | **override** | A template of yours, passed in `templates`, used instead of the default | "custom template" |
 | **issued** | What a flow answered: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` | "result", "payload" |
 | **recipient** | Who an e-mail is for besides the address: a `Recipient`, `{ name, locale? }` | "user" — a user is a record of `@nxgt/janus`; "to" is the address |
 | **notice** | An e-mail that tells, and asks for nothing: `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`. It links to `links.secureAccount()` | "alert", "notification" |
+| **welcome** | The e-mail sent once a user was created, on `@nxgt/janus`'s `user.created`: `welcome`. It links to `links.getStarted()` — not a notice, since it warns of nothing | "onboarding", "greeting" |
 | **expiry** | How long a link or a code lasts, as the e-mail says it: `expiresIn`, derived from the flow's `expiresAt` in the recipient's locale — "1 hour", "1 heure" — or passed per send | "TTL", "lifetime" — the `tokens` TTL is `@nxgt/janus`'s setting, which sets `expiresAt` |
 | **brand** | The name the e-mails show, `janusMail({ brand })`: text, filled at send time | "logo", "company" |
 | **the build** | The e-mails as `scripts/build-mail.ts` writes them to `mails/`: HTML and text per locale, and the manifest | "dist" — `mails/` is not `dist/` |

package/docs/guide/building.md

@@ -43,7 +43,7 @@ packages/janus-mail/
    `src/generated/mail.ts` (`rendererTypes`), from the build.
 3. `scripts/build-mail.ts` reads the manifest and **fails unless its
    format is one every `@nxgt/mail` the peer admits reads** — see below —
-   and **unless exactly the seven e-mails were built**: an eighth from a new
+   and **unless exactly the eight e-mails were built**: a ninth from a new
    `@nxgt/mail-presets`, or one missing, stops the build.
 4. It writes `src/generated/locales.ts` from the manifest's locales, only
    when its content changed.
@@ -53,10 +53,12 @@ Then `../../build.ts` builds `dist/`, as for every package.
 ## The manifest's format keeps the peer honest
 
 The package peers `@nxgt/mail` at `>=0.1.0 <1`, so the build it ships must
-be readable by `@nxgt/mail` 0.1.0. The manifest says which format it is in —
-`formatVersion`, its first key, `MANIFEST_FORMAT` of the `@nxgt/mail-i18n`
-that built it — and within 0.x a renderer reads every format up to its own.
-`@nxgt/mail` 0.1.0 through 0.8.0 read format 1, and a manifest without the
+be readable by `@nxgt/mail` 0.1.0 — the peer's floor, which the package's
+specs and its typecheck run on in the Floors job, on every CI run. The
+manifest says which format it is in — `formatVersion`, its first key,
+`MANIFEST_FORMAT` of the `@nxgt/mail-i18n` that built it — and within 0.x a
+renderer reads every format up to its own.
+`@nxgt/mail` 0.1.0 through 0.9.0 read format 1, and a manifest without the
 field is format 1.
 
 `formatProblem` in `scripts/build-mail.ts` (spec'd beside it) fails the build

package/docs/guide/locales.md

@@ -85,6 +85,7 @@ const templates: JanusMailTemplates<Locale> = {
 	emailChanged: ({ name, link, newEmail, locale }) => render('email-changed', locale, { name, link, newEmail }),
 	twoFactorEnabled: ({ name, link, locale }) => render('two-factor-enabled', locale, { name, link }),
 	twoFactorDisabled: ({ name, link, locale }) => render('two-factor-disabled', locale, { name, link }),
+	welcome: ({ name, link, locale }) => render('welcome', locale, { name, link }),
 };
 
 const mail = janusMail({ mailer, from, brand: 'Acme', links, locales: ['en', 'fr', 'de'], templates });
@@ -99,13 +100,13 @@ With only some templates, the call does not compile — the error lands on
 `templates`:
 
 ```text
-TS2739: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled
+TS2739: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, welcome
 ```
 
 and in JavaScript it throws when `janusMail()` is called:
 
 ```text
-TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled missing
+TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, welcome missing
 ```
 
 A default template is typed for `'en' | 'fr'`, so reusing one in a wider set
@@ -118,4 +119,4 @@ Built-in locales for more languages are on the [roadmap](../roadmap.md).
 
 - `@nxgt/mail`'s [locales guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/locales.md)
   — `pickLocale` and `parseAcceptLanguage` in full.
-- [Templates](templates.md) — writing the seven for a new locale.
+- [Templates](templates.md) — writing the eight for a new locale.

package/docs/guide/sending.md

@@ -26,6 +26,7 @@ export const mail = janusMail({
 		verifyEmail: (token) => `https://acme.example/verify?token=${encodeURIComponent(token)}`,
 		resetPassword: (token) => `https://acme.example/reset?token=${encodeURIComponent(token)}`,
 		secureAccount: () => 'https://acme.example/account/security',
+		getStarted: () => 'https://acme.example/',
 	},
 });
 ```
@@ -45,6 +46,7 @@ time one is sent, and kept.
 | `links.verifyEmail` | `(token) => string` | required | The page that confirms an address, given the one-time token |
 | `links.resetPassword` | `(token) => string` | required | The page that sets a new password, given the one-time token |
 | `links.secureAccount` | `() => string` | required | Where a user who made no change secures their account: the notices link to it |
+| `links.getStarted` | `() => string` | required | Where a new user starts — your home page, or your sign-in page for an account someone else created: the welcome's **Get started** button links to it |
 | `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) |
@@ -134,6 +136,68 @@ 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.
 
+### `twoFactorEnabled(to)` and `twoFactorDisabled(to)`
+
+```ts
+// On the user events @nxgt/janus sends once the write landed:
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type !== 'user.secondFactorEnabled' && event.type !== 'user.secondFactorDisabled') return;
+		const user = await auth.get(event.userId);
+		const to = { name: user.name, locale: user.locale, email: user.email };
+		await (event.type === 'user.secondFactorEnabled' ? mail.twoFactorEnabled(to) : mail.twoFactorDisabled(to));
+	},
+});
+```
+
+Two notices: two-factor authentication was turned on, or off, for the
+account at `to.email`, each with a link to `links.secureAccount()` — the
+user's security settings — for a user who did not make the change. Send
+`twoFactorEnabled` on the `user.secondFactorEnabled` event, which
+`auth.secondFactor.activate` sends once the factor is active, and
+`twoFactorDisabled` on `user.secondFactorDisabled`, which
+`auth.secondFactor.disable` sends only when it removed an active factor: a
+`disable` on a user who had none tells nobody anything. The event names the
+user by id alone, so read the name, the locale and the address from the
+user. Calling them right after `activate` or `disable` answered works as
+well — without the events, check `hasSecondFactor` before the `disable`.
+
+### `welcome(to)`
+
+```ts
+// On the user event @nxgt/janus sends once the user is inserted:
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type !== 'user.created') return;
+		const user = await auth.get(event.userId);
+		await mail.welcome({ name: user.name, locale: user.locale, email: user.email });
+	},
+});
+```
+
+Welcomes the new user at `to.email` — "Welcome, Ada", "Bienvenue, Ada", the
+name in the subject too — with a **Get started** button that links to
+`links.getStarted()`: your home page, or your sign-in page when the account
+was created for the user rather than by them. Send it on the `user.created`
+event, which `auth.signUp` and `auth.create` send once the user is inserted —
+even when `signUp`'s session then fails to open — and never for a sign-up
+refused. The event names the user by id alone, so read the name, the locale
+and the address from the user. With several user types, check
+`event.userType` first: a type with no e-mail has nobody to welcome.
+
+- **It goes out before the address is verified.** A sign-up with a mistyped
+  address welcomes whoever holds it, and with open sign-up anyone can make
+  your brand send "Welcome, <any name>" to any address. To welcome proven addresses only, send
+  it on `user.emailVerified` instead, sent once the address is proven —
+  and again after an address changed and was proven anew, so welcome only
+  a user you have not welcomed before.
+- **A failed welcome fails no sign-up.** `janus()` awaits the listener, but a
+  listener that throws is a `JANUS_EVENT_FAILED` warning: the user exists,
+  and `signUp` answers as it would have. For a welcome that must arrive, put
+  the event in a queue that retries a `MAIL_FAILED`, and send from there.
+
 ## The expiry
 
 `verifyEmail`, `resetPassword` and `signInCode` say how long the link or the
@@ -178,33 +242,6 @@ 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`.
 
-### `twoFactorEnabled(to)` and `twoFactorDisabled(to)`
-
-```ts
-// On the user events @nxgt/janus sends once the write landed:
-const auth = janus({
-	...config,
-	async events(event) {
-		if (event.type !== 'user.secondFactorEnabled' && event.type !== 'user.secondFactorDisabled') return;
-		const user = await auth.get(event.userId);
-		const to = { name: user.name, locale: user.locale, email: user.email };
-		await (event.type === 'user.secondFactorEnabled' ? mail.twoFactorEnabled(to) : mail.twoFactorDisabled(to));
-	},
-});
-```
-
-Two notices: two-factor authentication was turned on, or off, for the
-account at `to.email`, each with a link to `links.secureAccount()` — the
-user's security settings — for a user who did not make the change. Send
-`twoFactorEnabled` on the `user.secondFactorEnabled` event, which
-`auth.secondFactor.activate` sends once the factor is active, and
-`twoFactorDisabled` on `user.secondFactorDisabled`, which
-`auth.secondFactor.disable` sends only when it removed an active factor: a
-`disable` on a user who had none tells nobody anything. The event names the
-user by id alone, so read the name, the locale and the address from the
-user. Calling them right after `activate` or `disable` answered works as
-well — without the events, check `hasSecondFactor` before the `disable`.
-
 ## Where each e-mail goes
 
 | Method | To | Never to |
@@ -215,6 +252,7 @@ well — without the events, check `hasSecondFactor` before the `disable`.
 | `passwordChanged` | `to.email` | — |
 | `emailChanged` | `to.formerEmail` | `to.newEmail` |
 | `twoFactorEnabled`, `twoFactorDisabled` | `to.email` | — |
+| `welcome` | `to.email` | — |
 
 `issued.email` is the address the user's record holds, as they registered
 it; what the visitor typed may differ in case or spacing. The recipient is a
@@ -268,10 +306,11 @@ retries a `MAIL_FAILED`, rather than to a promise nobody awaits.
 
 ### Retrying and tracing the mailer
 
-From `@nxgt/mail` 0.8, wrap the mailer before you hand it to `janusMail()`:
-`withRetry` retries a `MailFailure` with backoff, reusing one idempotency
-key for every attempt, and never retries a `MailRefused`; `withTelemetry`
-from `@nxgt/mail/telemetry` opens a `mail.send` span per send. That entry
+Wrap the mailer before you hand it to `janusMail()`: `withRetry`, from
+`@nxgt/mail` 0.8, retries a `MailFailure` with backoff, reusing one
+idempotency key for every attempt, and never retries a `MailRefused`;
+`withMailTelemetry`, from `@nxgt/mail/telemetry` 0.9 (`withTelemetry` on
+0.8), opens a `mail.send` span per send. That entry
 needs `@opentelemetry/api` installed (an optional peer, loaded by it alone);
 with no OpenTelemetry SDK registered, its spans are no-ops. Put telemetry on the outside, so one
 send is one span:
@@ -279,7 +318,7 @@ send is one span:
 ```ts
 import { janusMail } from '@nxgt/janus-mail';
 import { withRetry } from '@nxgt/mail';
-import { withTelemetry as withMailTelemetry } from '@nxgt/mail/telemetry';
+import { withMailTelemetry } from '@nxgt/mail/telemetry';
 import { createSmtpMailer } from '@nxgt/mail-smtp';
 
 export const mail = janusMail({
@@ -290,12 +329,14 @@ export const mail = janusMail({
 });
 ```
 
-**Alias it.** `@nxgt/telemetry` — which `@nxgt/janus-telemetry` peers — also
-exports a `withTelemetry`, `withTelemetry(telemetry, fn)`, which scopes a
-telemetry to a block. The two are unrelated: `mail.send` is recorded
-through OpenTelemetry, not `@nxgt/telemetry`, so it does not nest under
-`@nxgt/janus-telemetry`'s spans. Import `@nxgt/mail`'s under another name,
-as above, when a module uses both.
+**Two telemetries, unrelated.** `@nxgt/telemetry` — which
+`@nxgt/janus-telemetry` peers — exports `withTelemetry(telemetry, fn)`,
+which scopes a telemetry to a block. `mail.send` is recorded through
+OpenTelemetry, not `@nxgt/telemetry`, so it does not nest under
+`@nxgt/janus-telemetry`'s spans. `@nxgt/mail` 0.9 renamed its decorator
+`withMailTelemetry` so the two no longer share a name; on 0.8 it is
+`withTelemetry`, still exported by 0.9 as a deprecated alias until 1.0 —
+import it under another name there when a module uses both.
 
 **SMTP ignores the idempotency key**, so a retry after an ambiguous SMTP
 timeout can deliver an e-mail twice. If a duplicate sign-in code or reset
@@ -322,6 +363,7 @@ const links = {
 	verifyEmail: (token: string) => `https://acme.example/verify?token=${token}`,
 	resetPassword: (token: string) => `https://acme.example/reset?token=${token}`,
 	secureAccount: () => 'https://acme.example/account/security',
+	getStarted: () => 'https://acme.example/',
 };
 
 it('sends the code, and never the challenge', async () => {

package/docs/guide/templates.md

@@ -1,7 +1,7 @@
 # Templates
 
 This page is for changing what an e-mail says or looks like: what a template
-is given and answers, replacing some of the seven, using the defaults on their
+is given and answers, replacing some of the eight, using the defaults on their
 own, and what the defaults say.
 
 ```ts
@@ -22,7 +22,7 @@ const mail = janusMail({
 });
 ```
 
-The sign-in code e-mail is now yours; the six others stay the defaults.
+The sign-in code e-mail is now yours; the seven others stay the defaults.
 
 ## What a template is
 
@@ -66,10 +66,12 @@ e-mail.
 | `emailChanged` | `brand`, `name`, `link`, `newEmail` | `mail.emailChanged(to)` |
 | `twoFactorEnabled` | `brand`, `name`, `link` | `mail.twoFactorEnabled(to)` |
 | `twoFactorDisabled` | `brand`, `name`, `link` | `mail.twoFactorDisabled(to)` |
+| `welcome` | `brand`, `name`, `link` | `mail.welcome(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 four notices — `code` and `newEmail` from the
+`links.secureAccount()` for the four notices, `links.getStarted()` for
+`welcome` — `code` and `newEmail` from the
 call, and `expiresIn` derived from the flow's `expiresAt` in the locale, or
 the send's own `expiresIn` ([Sending](sending.md#the-expiry)).
 
@@ -103,11 +105,11 @@ methods live on its prototype and are refused — see
 [troubleshooting](../troubleshooting.md#janusmail-templatesname-is-not-an-own-enumerable-property--pass-a-plain-object-as--name-variables--rendered-).
 
 `templates` is `Partial` while `locales` stays within `en` and `fr`: give
-any of the seven, and the defaults render the rest. Once `locales` holds
-another locale, it takes **all seven** — see
+any of the eight, and the defaults render the rest. Once `locales` holds
+another locale, it takes **all eight** — see
 [Adding a locale](locales.md#adding-a-locale).
 
-`mail.templates` answers the seven in use — yours, and the defaults for the
+`mail.templates` answers the eight in use — yours, and the defaults for the
 rest — frozen:
 
 ```ts
@@ -129,7 +131,7 @@ const { subject, html, text } = await defaults.resetPassword({
 });
 ```
 
-It answers the seven defaults, typed for `'en' | 'fr'`, without a mailer:
+It answers the eight defaults, typed for `'en' | 'fr'`, without a mailer:
 to preview an e-mail, to wrap one — add a line to the default text, say — or
 to send one through something other than `janusMail()`. A default reused for
 a wider set of locales is a compile error: it could not render the one it
@@ -155,7 +157,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.4.2, built with a neutral grey theme and no logo:
+0.4.3, built with a neutral grey theme and no logo:
 
 | Template | Built from | Subject (`en`) | Subject (`fr`) |
 | --- | --- | --- | --- |
@@ -166,11 +168,14 @@ The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail
 | `emailChanged` | `email-changed` | Your e-mail address was changed | Votre adresse e-mail a été modifiée |
 | `twoFactorEnabled` | `two-factor-enabled` | Two-factor authentication was turned on | L'authentification à deux facteurs a été activée |
 | `twoFactorDisabled` | `two-factor-disabled` | Two-factor authentication was turned off | L'authentification à deux facteurs a été désactivée |
+| `welcome` | `welcome` | Welcome, `Ada` | Bienvenue, `Ada` |
 
 Each has a header and a footer with the brand, a heading, a greeting by name
 (but `signInCode`), a button with its link and the link again in text for a
 client that shows no button, and a text part. The four notices add a warning:
-*if this was not you, secure your account now*.
+*if this was not you, secure your account now*. `welcome` has the brand in
+its heading — "Welcome to Acme" — and the recipient's name in its subject,
+filled at send time like the body; its button says **Get started**.
 
 `verifyEmail`, `resetPassword` and `signInCode` also say how long the link
 or the code lasts: "This link expires in 1 hour.", "Ce code expire dans
@@ -186,11 +191,18 @@ is near-black (`#27272a`) with light text in light mode, and near-white
 dark card, where the light primary would be 1.2:1. The page behind the card
 is 5% of the light primary over the dark background, a shade darker than the
 card, which its border outlines. The sign-in code's box is a light grey
-(`#f1f5f9`) in light mode and a mid slate (`#94a3b8`) in dark mode, 6.95:1
-against the dark card; the code on it stays near-black (`#020918`) in both,
-7.76:1 over the dark box. The footer's muted text keeps its grey (`#62748e`)
-in both modes. Nothing is passed for any of it, the text part has no
-colours, and a template of your own gets none of it. `@nxgt/mail-ui`'s
+(`#f1f5f9`) with near-black code (`#020918`) in light mode, and a slate a
+step above the dark card (`#1e293b`) with light code (`#cbd5e1`) in dark
+mode, 9.85:1. The muted text — the footer, and the closing *if you did not
+ask for this* — is a slate grey (`#5f718a`) in light mode, 4.53:1 on the
+page, and turns `#cbd5e1` in dark mode, 12.01:1 on the dark card and
+13.31:1 on the page. The notices' alerts keep their light ground and grey
+text in both modes, 4.56:1 at the least. Every
+text of the defaults reads at 4.5:1 or more in both modes, but the link
+under the button, which `@nxgt/mail-ui` colours with its info blue in
+both: 6.78:1 on the dark card, 2.63:1 on the light one, and no theme token
+moves it without breaking the other mode. Nothing is passed for any of it,
+the text part has no colours, and a template of your own gets none of it. `@nxgt/mail-ui`'s
 [Dark mode](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-ui/docs/guide/dark-mode.md)
 guide has the technique, client by client.
 

package/docs/roadmap.md

@@ -9,10 +9,9 @@ Nothing between releases.
 
 ## Next
 
-- **The other presets** — `magic-link`, `new-sign-in`, `welcome` and
-  `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 other presets** — `magic-link`, `new-sign-in` and `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, an invitation to a user type.
 - **The other presets of `@nxgt/mail-presets` 0.4.0** — `account-deleted`,
   after a user is deleted, once `@nxgt/janus` has a deletion a link can
   undo; and `invitation-accepted`, once it has invitations.
@@ -48,6 +47,22 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **Muted text at 4.5:1 or more in both modes, v0.4.1.** Under dark mode the
+  sign-in code's box is a slate a step above the dark card with light code on
+  it, 9.85:1, and the muted text turns light, 13.31:1 on the page and
+  12.01:1 on the card; in light mode
+  the muted grey is a shade darker, 4.53:1 on the page and 4.56:1 on the
+  notices' alerts at the least. Built from `@nxgt/mail-ui` 0.7.0 and
+  `@nxgt/mail-presets` 0.4.3; the text parts, subjects and variables are
+  unchanged, the manifest is still format 1, and the `@nxgt/mail` peer stays
+  `>=0.1.0 <1`.
+- **The welcome e-mail, v0.4.0.** `welcome(to)`, built from
+  `@nxgt/mail-presets` 0.4.2's `welcome` in English and French — "Welcome,
+  Ada" — with a **Get started** button linking to the new
+  `links.getStarted()`: send it on `@nxgt/janus`'s `user.created` event.
+  `links` now requires `getStarted`, and a locale beyond `en` and `fr` takes
+  eight templates.
+
 - **A sign-in code box that is not a light slab in dark mode, v0.3.2.** Under
   dark mode the code's box is a mid slate, 6.95:1 against the dark card, with
   the near-black code at 7.76:1 on it, and the page behind the card is darker