@nxgt/janus-mail 0.1.0

package/docs/guide/sending.md

@@ -0,0 +1,242 @@
+# Sending
+
+This page is for wiring `janusMail()` into an application: what it takes,
+what each method sends and to whom, what happens when a send fails, and how
+to test it.
+
+```ts
+import { janus, createMemoryStores, scryptHasher } from '@nxgt/janus';
+import { janusMail } from '@nxgt/janus-mail';
+import { createSmtpMailer } from '@nxgt/mail-smtp'; // or any @nxgt/mail transport
+import { z } from 'zod';
+
+export const auth = janus({
+	user: z.object({ email: z.email(), name: z.string(), locale: z.string().nullable() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+export const mail = janusMail({
+	mailer: createSmtpMailer({ transporter }), // transporter: nodemailer.createTransport(…)
+	from: { name: 'Acme', address: 'noreply@acme.example' },
+	replyTo: 'support@acme.example',
+	brand: 'Acme',
+	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',
+	},
+});
+```
+
+Create it once, at start-up, beside `janus()`. It reads nothing when called:
+the default e-mails are read from the package's `mails/` folder the first
+time one is sent, and kept.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mailer` | `Mailer` | required | The transport every e-mail is handed to |
+| `from` | `Address` | required | The sender: `'noreply@acme.example'` or `{ name, address }` |
+| `replyTo` | `Address` | none | Where a reply goes, when not to `from` |
+| `brand` | `string` | required | The name the e-mails show, in the header, the body and the footer. Text: escaped in the HTML |
+| `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 |
+| `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) |
+
+Every link is called at send time, and must answer an absolute `http:`,
+`https:` or `mailto:` URL: a default template refuses anything else with
+`MailRefused`, before the mailer is called. `mailto:` is accepted on purpose:
+`secureAccount: () => 'mailto:security@acme.example'` points a user who made
+no change at your support desk. A link must be answered synchronously, as a
+string — an `async` function or a `URL` object is a compile error in
+TypeScript, and a `TypeError` naming the call at send time in JavaScript,
+`janusMail.verifyEmail: links.verifyEmail(token) must answer a string`.
+Encode a token you put in a query string yourself (`encodeURIComponent`).
+
+`links`, `from` and `replyTo` are copied and frozen when `janusMail()` is
+called: what was checked then is what every send uses, and changing your
+object afterwards changes nothing.
+
+A wrong option is a bare `TypeError` when `janusMail()` is called, naming the
+option and never its value — every message is in
+[troubleshooting](../troubleshooting.md#wiring--janusmail).
+
+## The methods
+
+Each method renders its e-mail with its template, hands it to the mailer,
+and answers the mailer's `SentMail` (`{ messageId }`).
+
+### `verifyEmail(issued, to)`
+
+```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)`.
+
+### `resetPassword(issued, to)`
+
+```ts
+const issued = await auth.resetPassword.request(email); // (IssuedToken & { user }) | null
+if (issued !== null) {
+	await mail.resetPassword(issued, { name: issued.user.name, locale: issued.user.locale });
+}
+```
+
+`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)`.
+
+### `signInCode(issued, to?)`
+
+```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
+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.
+
+### `passwordChanged(to)`
+
+```ts
+const changed = await auth.changePassword(user, { current, next });
+await mail.passwordChanged({ name: changed.name, locale: changed.locale, email: changed.email });
+```
+
+A notice: the password of the account at `to.email` changed, with a link to
+`links.secureAccount()` for a user who did not change it. Send it after
+`changePassword`, `setPassword` and `resetPassword.confirm`.
+
+### `emailChanged(to)`
+
+```ts
+const formerEmail = user.email;
+const updated = await auth.update(user, { email: next });
+await mail.emailChanged({ name: updated.name, locale: updated.locale, formerEmail, newEmail: updated.email });
+```
+
+Sent to **`formerEmail`**: the owner of the old address is the one to warn,
+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.
+
+## Where each e-mail goes
+
+| Method | To | Never to |
+| --- | --- | --- |
+| `verifyEmail` | `issued.email` | what the visitor typed |
+| `resetPassword` | `issued.email` | the `email` passed to `request` |
+| `signInCode` | `issued.email` | the `email` passed to `request` |
+| `passwordChanged` | `to.email` | — |
+| `emailChanged` | `to.formerEmail` | `to.newEmail` |
+
+`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
+bare address: `to.name` is used in the greeting, not in the `To` header.
+
+Only `subject`, `html` and `text` are read from what a template answers. A
+template cannot add a recipient or a header: `to`, `from`, `replyTo` and
+`headers` are this package's alone.
+
+## When a send fails
+
+**Every method rejects with the error it met, untouched.** This package
+defines no error class and wraps nothing:
+
+| Error | From | Means | Answer |
+| --- | --- | --- | --- |
+| `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 |
+| `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
+a peer: one copy defines them.
+
+```ts
+import { MailError } from '@nxgt/mail';
+import { JanusError } from '@nxgt/janus';
+
+export async function sendVerification(user: User): Promise<Response> {
+	try {
+		await mail.verifyEmail(await auth.verifyEmail.send(user), { name: user.name, locale: user.locale });
+		return new Response(null, { status: 202 });
+	} catch (error) {
+		if (error instanceof MailError && error.code === 'MAIL_FAILED') {
+			return Response.json({ code: 'MAIL_FAILED' }, { status: 503 }); // offer to send it again
+		}
+		if (error instanceof JanusError && error.code === 'STORE_FAILED') {
+			return Response.json({ code: 'STORE_FAILED' }, { status: 503 });
+		}
+		throw error; // MAIL_REFUSED and TypeError are bugs: a 500
+	}
+}
+```
+
+**Never fire and forget.** `void mail.signInCode(issued)` turns a failure
+into an unhandled rejection. The [sign-in code guide of
+`@nxgt/janus`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/sign-in-code.md)
+advises sending *after* answering, so the time an answer takes does not tell
+whether the address exists: hand the send to a queue that awaits it and
+retries a `MAIL_FAILED`, rather than to a promise nobody awaits.
+
+## Testing
+
+`createMemoryMailer()` from `@nxgt/mail` keeps an outbox, and can be told to
+fail:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer, MailFailure } from '@nxgt/mail';
+import { janusMail } from '@nxgt/janus-mail';
+
+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',
+};
+
+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' };
+
+	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?.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 error = await mail
+		.signInCode({ code: '042817', email: 'ada@example.com' })
+		.then(() => null, (e: unknown) => e); // settled where it is created
+
+	expect(error).toBeInstanceOf(MailFailure);
+	expect(mailer.attempts).toBe(1); // tried once: nothing retried in secret
+});
+```
+
+## See also
+
+- [Templates](templates.md) — replacing an e-mail.
+- [Locales](locales.md) — how the locale is picked.
+- `@nxgt/mail`'s
+  [sending guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/sending.md)
+  — the `Mailer` port and its errors.

package/docs/guide/templates.md

@@ -0,0 +1,183 @@
+# 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 five, using the defaults on their
+own, and what the defaults say.
+
+```ts
+import { janusMail } from '@nxgt/janus-mail';
+
+const mail = janusMail({
+	mailer,
+	from: 'noreply@acme.example',
+	brand: 'Acme',
+	links,
+	templates: {
+		signInCode: ({ brand, code, locale }) => ({
+			subject: locale === 'fr' ? `Votre code ${brand} : ${code}` : `Your ${brand} code: ${code}`,
+			html: `<p style="font-size:24px;letter-spacing:4px">${code}</p>`,
+			text: code,
+		}),
+	},
+});
+```
+
+The sign-in code e-mail is now yours; the four others stay the defaults.
+
+## What a template is
+
+```ts
+import type { Rendered } from '@nxgt/mail';
+
+type JanusMailTemplate<V, L extends string = 'en' | 'fr'> = (
+	variables: V & { readonly locale: L },
+) => Rendered | PromiseLike<Rendered>;
+
+interface Rendered {
+	readonly subject: string;
+	readonly html: string;
+	readonly text: string;
+}
+```
+
+A template is a function: its variables and the locale picked for the
+recipient in, the three parts of the e-mail out — synchronously or as a
+promise. Anything that answers that shape fits: React Email's `render`, a
+template string, another Maizzle build read with `@nxgt/mail/renderer`.
+
+**Escaping is then the template's job.** The defaults escape every value in
+the HTML; a template of yours that writes `name` into HTML must escape it
+itself — a user's name is free text.
+
+Only `subject`, `html` and `text` are read from what it answers: a `to`, a
+`from` or `headers` it adds are ignored, so a template can never redirect an
+e-mail.
+
+## What each template is given
+
+`JanusMailVariables`, by template:
+
+| 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?)` |
+| `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.
+
+`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:
+
+```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 }) =>
+			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.` },
+	},
+});
+```
+
+A template that reads a variable its e-mail does not have is a compile error:
+
+```ts
+// @ts-expect-error — Property 'name' does not exist: the sign-in code e-mail greets nobody
+templates: { signInCode: ({ name }) => rendered },
+```
+
+## Some templates, or all of them
+
+`templates` is a plain object, or a class with template fields: a class's
+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 five, and the defaults render the rest. Once `locales` holds
+another locale, it takes **all five** — see
+[Adding a locale](locales.md#adding-a-locale).
+
+`mail.templates` answers the five in use — yours, and the defaults for the
+rest — frozen:
+
+```ts
+const rendered = await mail.templates.verifyEmail({ brand: 'Acme', name: 'Ada', link, locale: 'fr' });
+```
+
+## The defaults alone — `janusTemplates()`
+
+```ts
+import { janusTemplates } from '@nxgt/janus-mail';
+
+const defaults = janusTemplates();
+const { subject, html, text } = await defaults.resetPassword({
+	brand: 'Acme',
+	name: 'Ada',
+	link: 'https://acme.example/reset?token=abc',
+	locale: 'fr',
+});
+```
+
+It answers the five 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
+lacks.
+
+```ts
+import { janusTemplates, type JanusMailTemplates } from '@nxgt/janus-mail';
+
+const defaults = janusTemplates();
+
+// Wrapping a default: the same e-mail, with a line added to its text part.
+const templates: Partial<JanusMailTemplates> = {
+	verifyEmail: async (variables) => {
+		const rendered = await defaults.verifyEmail(variables);
+		return { ...rendered, text: `${rendered.text}\n\nAcme — 1 Example Street` };
+	},
+};
+```
+
+The default templates share one renderer, created the first time one of
+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:
+
+| Template | Built from | Subject (`en`) | Subject (`fr`) |
+| --- | --- | --- | --- |
+| `verifyEmail` | `verify-email` | Confirm your e-mail address | Confirmez votre adresse e-mail |
+| `resetPassword` | `reset-password` | Reset your password | Réinitialisez votre mot de passe |
+| `signInCode` | `sign-in-code` | Your sign-in code: `042817` | Votre code de connexion : `042817` |
+| `passwordChanged` | `password-changed` | Your password was changed | Votre mot de passe a été modifié |
+| `emailChanged` | `email-changed` | Your e-mail address was changed | Votre adresse e-mail a été modifiée |
+
+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 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.
+
+**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 is built. A logo takes a template of your own; the
+[roadmap](../roadmap.md) has a build of your own brand.
+
+## See also
+
+- [Sending](sending.md) — what each method passes its template.
+- [Locales](locales.md) — the `locale` a template is given.
+- `@nxgt/mail-presets`' [e-mails guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/docs/guide/emails.md)
+  — every message of the defaults, in both locales.

package/docs/roadmap.md

@@ -0,0 +1,52 @@
+# Roadmap
+
+Where `@nxgt/janus-mail` is heading. A direction, not a commitment: there are
+no dates here, and the version something shipped in is the only number.
+
+## Now
+
+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 expiry in the e-mail** — "the link expires in 24 hours", from the
+  flow's `expiresAt`, once the presets' messages take it.
+
+## Later
+
+- **An inlined build, for edge runtimes** — the default e-mails compiled into
+  the JavaScript itself rather than read from `mails/` with `node:fs`, so the
+  package runs where there is no file system.
+- **More built-in languages** — each one a catalogue of the presets'
+  messages, so a locale beyond `en` and `fr` no longer requires every
+  template.
+- **Your brand at build time** — a logo, a link and your colours, from a
+  Maizzle build of your own over the same presets, read by the same
+  renderer.
+
+## Not planned
+
+- **An error class of its own** — a send rejects with the mailer's
+  `MailFailure` or `MailRefused`, untouched, so one `instanceof` against
+  `@nxgt/mail` answers every failure, whichever package sent the e-mail.
+- **Retries or a queue** — a retry is the application's decision, made where
+  it can see it; hand a send to a queue that retries a `MAIL_FAILED`.
+- **Sending from inside `janus()`** — `@nxgt/janus` stays free of e-mail:
+  its flows answer what to send, and this package is called with that answer.
+  An application that sends its own way needs neither this package nor a
+  hook to turn off.
+- **The challenge in an e-mail** — a sign-in code e-mail carries the code and
+  never the challenge, not even through an override.
+
+## Shipped
+
+Newest first; from the first release on, the package's CHANGELOG holds every one.
+
+- **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
+  in `mails/`, and only filled in at send time, every value escaped.