@nxgt/janus-mail 0.3.1 → 0.4.0

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,7 +5,7 @@ the detail.
 
 | Page | Read it when |
 | --- | --- |
-| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options — `clock` among them — each method, the 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 |
@@ -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.

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
@@ -322,6 +360,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.1, built with a neutral grey theme and no logo:
+0.4.2, 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
@@ -184,11 +189,13 @@ is `@nxgt/mail-ui`'s default, a deep navy, but for the primary: the button
 is near-black (`#27272a`) with light text in light mode, and near-white
 (`#fafafa`) with near-black text (`#18181b`) in dark mode — 17:1 against the
 dark card, where the light primary would be 1.2:1. The page behind the card
-follows it, 5% of the dark primary over the dark background, so it sits
-close to the card, which its border outlines. The sign-in code's box is
-`@nxgt/mail-ui`'s muted grey, which has no dark value: it stays a light box
-with dark text 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
+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
 [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,19 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **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
+  again; light mode, the text parts, subjects and variables are unchanged.
+  Built from `@nxgt/mail-ui` 0.6.0 and `@nxgt/mail-presets` 0.4.2; the
+  manifest is still format 1, and the `@nxgt/mail` peer stays `>=0.1.0 <1`.
 - **A button that shows in dark mode, v0.3.1.** Under dark mode the button
   is near-white with near-black text, no longer a near-black one that all but
   vanished on the dark card; light mode, the text parts, subjects and

package/docs/troubleshooting.md

@@ -25,14 +25,14 @@ How the messages are shaped:
 - [`janusMail: from must be an address, as 'noreply@example.com' or { name, address }`](#janusmail-from-must-be-an-address-as-noreplyexamplecom-or--name-address-)
 - [`janusMail: replyTo must be an address, as 'support@example.com' or { name, address }`](#janusmail-replyto-must-be-an-address-as-supportexamplecom-or--name-address-)
 - [`janusMail: brand must be the name the e-mails show, as 'Acme'`](#janusmail-brand-must-be-the-name-the-e-mails-show-as-acme)
-- [`janusMail: links must be an object, as { verifyEmail, resetPassword, secureAccount }`](#janusmail-links-must-be-an-object-as--verifyemail-resetpassword-secureaccount-)
+- [`janusMail: links must be an object, as { verifyEmail, resetPassword, secureAccount, getStarted }`](#janusmail-links-must-be-an-object-as--verifyemail-resetpassword-secureaccount-getstarted-)
 - [`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, twoFactorEnabled, twoFactorDisabled`](#janusmail-templates-has-no-template-name--name-one-of-verifyemail-resetpassword-signincode-passwordchanged-emailchanged-twofactorenabled-twofactordisabled)
+- [`janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, welcome`](#janusmail-templates-has-no-template-name--name-one-of-verifyemail-resetpassword-signincode-passwordchanged-emailchanged-twofactorenabled-twofactordisabled-welcome)
 - [`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)
@@ -53,12 +53,14 @@ How the messages are shaped:
 - [`Could not resolve "node:fs"` on an edge runtime](#could-not-resolve-nodefs-on-an-edge-runtime)
 - [An e-mail stays light in dark mode](#an-e-mail-stays-light-in-dark-mode)
 - [The button all but vanishes in dark mode](#the-button-all-but-vanishes-in-dark-mode)
+- [The sign-in code's box stays a light slab in dark mode](#the-sign-in-codes-box-stays-a-light-slab-in-dark-mode)
 
 **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)
+- [`TS2741: Property 'getStarted' is missing in type '{ … }' but required in type 'JanusMailLinks'.`](#ts2741-property-getstarted-is-missing-in-type----but-required-in-type-janusmaillinks)
 
 ---
 
@@ -101,24 +103,32 @@ No `brand`, a blank one, or not a string — `{ name: 'Acme' }`, the shape of
 janusMail({ mailer, from, brand: 'Acme', links });
 ```
 
-### `janusMail: links must be an object, as { verifyEmail, resetPassword, secureAccount }`
+### `janusMail: links must be an object, as { verifyEmail, resetPassword, secureAccount, getStarted }`
 
-No `links`. All three are required: the notices link to `secureAccount`.
+No `links`. All four are required: the notices link to `secureAccount`, and
+the welcome to `getStarted`.
 
 ### `janusMail: links.<name> must be a function`
 
-`links.verifyEmail`, `links.resetPassword` or `links.secureAccount` missing,
-or given as a URL. The first two take the one-time token; the third takes
-nothing:
+`links.verifyEmail`, `links.resetPassword`, `links.secureAccount` or
+`links.getStarted` missing, or given as a URL. The first two take the
+one-time token; the other two take nothing:
 
 ```ts
 links: {
 	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/',
 },
 ```
 
+**`links.getStarted must be a function` right after an upgrade** is the
+link the welcome e-mail added in 0.4.0: `links` written for 0.3 has no
+`getStarted`. Add it — where a new user starts, your home page or your
+sign-in page — even if you never send the welcome. In TypeScript the same
+`links` is a compile error on `links`, `Property 'getStarted' is missing`.
+
 ### `janusMail: locales must list at least one locale, as ['en', 'fr']`
 
 `locales: []`, `locales: 'en'`, or a list holding something that is not a
@@ -151,9 +161,9 @@ A `fallbackLocale` the list does not hold — `'de'` with the default
 
 `templates` given as a list or a function. Key each template by its name.
 
-### `janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled`
+### `janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, welcome`
 
-A key that is not one of the seven — `welcome`, or the e-mail's file name
+A key that is not one of the eight — `magicLink`, or the e-mail's file name
 `'verify-email'` rather than the template's, `verifyEmail`. Other e-mails are
 on the [roadmap](roadmap.md); send them with `@nxgt/mail` directly meanwhile.
 
@@ -187,7 +197,7 @@ as it is: fields are own properties.
 ### `janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; <names> missing`
 
 `locales` holds a locale beyond `en` and `fr`, and `templates` leaves some
-out: the defaults could not render them in that locale. Pass all seven — see
+out: the defaults could not render them in that locale. Pass all eight — see
 [Adding a locale](guide/locales.md#adding-a-locale) — or drop the locale.
 The message lists the templates missing.
 
@@ -225,8 +235,8 @@ 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.twoFactorEnabled: email must be a string` (or `twoFactorDisabled`)
-is the user event itself given to the notice: an event names the user by id
+`janusMail.twoFactorEnabled: email must be a string` (or `twoFactorDisabled`,
+or `welcome`) is the user event itself given to the e-mail: an event names the user by id
 alone. Read the user first:
 
 ```ts
@@ -307,7 +317,8 @@ sends a user who did not make the change to your support desk.
 A `TypeError` from a call, before anything is rendered or sent
 (`mailer.attempts` stays 0) — `janusMail.verifyEmail: links.verifyEmail(token)
 must answer a string`, `janusMail.emailChanged: links.secureAccount() must
-answer a string`. The `links` function answered something other than a
+answer a string`, `janusMail.welcome: links.getStarted() must answer a
+string`. The `links` function answered something other than a
 string: a `URL` object, `undefined`, or a promise — an `async` function.
 Answer `url.href`, and compute the link synchronously:
 
@@ -383,7 +394,7 @@ avoids the read altogether. (In this repository: run `bun run build`.)
 
 The default templates read `mails/` with `node:fs`, through
 `@nxgt/mail/renderer`: Node, Bun or Deno only. On an edge runtime, pass all
-seven templates yourself; an inlined build is on the [roadmap](roadmap.md).
+eight templates yourself; an inlined build is on the [roadmap](roadmap.md).
 
 ### An e-mail stays light in dark mode
 
@@ -421,6 +432,26 @@ ui({
 });
 ```
 
+### The sign-in code's box stays a light slab in dark mode
+
+A `signInCode` template of your own, built with `@nxgt/mail-ui`'s `NxCode`,
+keeps its light box (`#f1f5f9`) on the dark card for a reader in dark mode;
+the defaults turn theirs a mid slate there since 0.3.2. The box is muted,
+which keeps its light value under dark mode unless the build gives it a dark
+one. Build the override with `@nxgt/mail-ui` 0.6.0 or later and set
+`color-muted-dark`. The code's text stays the light foreground (`#020918`) in
+both modes, so a dark muted such as `#1e293b` leaves it at 1.36:1: pick one
+light enough for that text, as the defaults do:
+
+```ts
+ui({
+	brand: { name: 'Acme' },
+	theme: {
+		'color-muted-dark': '#94a3b8', // the code at 7.76:1 on it, 6.95:1 against the dark card
+	},
+});
+```
+
 ## Compile errors
 
 ### `TS2345: Argument of type '(IssuedToken & { user: … }) | null' is not assignable to parameter of type 'IssuedToken'.`
@@ -449,9 +480,25 @@ whole.
 ### `TS2739: Type '{ … }' is missing the following properties from type 'JanusMailTemplates<…>'`
 
 `locales` holds a locale beyond `en` and `fr`, and `templates` does not give
-all seven. See [Adding a locale](guide/locales.md#adding-a-locale).
+all eight. See [Adding a locale](guide/locales.md#adding-a-locale).
 
 ### `TS2322: Type '"de"' is not assignable to type '"en" | "fr"'.`
 
 A `fallbackLocale` outside `locales`. Add it to `locales` — with every
 template, if it is not `en` or `fr` — or pick one of them.
+
+### `TS2741: Property 'getStarted' is missing in type '{ … }' but required in type 'JanusMailLinks'.`
+
+`links` written for 0.3, before the welcome e-mail: since 0.4.0 it takes
+`getStarted` too, where the welcome's **Get started** button leads. Add it,
+even if you never send the welcome — in JavaScript the same `links` is
+[`janusMail: links.<name> must be a function`](#janusmail-linksname-must-be-a-function):
+
+```ts
+links: {
+	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/',
+},
+```