@nxgt/mail 0.1.0

package/docs/guide/sending.md

@@ -0,0 +1,325 @@
+# Sending
+
+This page is for calling `mailer.send`: the shape of what it takes, the
+addresses and headers it accepts, what it answers, and what it throws.
+
+```ts
+import { createMemoryMailer } from '@nxgt/mail';
+
+const mailer = createMemoryMailer(); // in production, a transport's mailer
+
+const sent = await mailer.send({
+	to: 'ada@example.com',
+	from: { name: 'Example', address: 'noreply@example.com' },
+	subject: 'Your password was changed',
+	html: '<p>Your password was changed.</p>',
+	text: 'Your password was changed.',
+});
+
+sent.messageId; // 'memory-1'
+```
+
+## The port
+
+```ts
+interface Mailer {
+	send(message: MailMessage): Promise<SentMail>;
+}
+
+interface SentMail {
+	readonly messageId: string | null;
+}
+```
+
+`send` resolves **only once the transport has handed the e-mail over** to its
+provider. `messageId` is the id the provider gave it, or `null` when it gives
+none — an absence, not a failure. It is not a promise the e-mail reached an
+inbox: a bounce happens after the hand-over, and `send` does not report it.
+
+Anything else rejects, with one of the two errors below. A mailer never
+resolves `false` and never logs and resolves.
+
+Depend on `Mailer`, not on a transport, so a test can pass the memory mailer
+where production passes SMTP:
+
+```ts
+import type { Mailer } from '@nxgt/mail';
+
+export class Accounts {
+	constructor(private readonly mailer: Mailer) {}
+
+	async passwordChanged(user: { email: string }): Promise<void> {
+		await this.mailer.send({
+			to: user.email,
+			subject: 'Your password was changed',
+			html: '<p>Your password was changed.</p>',
+			text: 'Your password was changed.',
+		});
+	}
+}
+```
+
+## The message
+
+```ts
+interface Rendered {
+	readonly subject: string;
+	readonly html: string;
+	readonly text: string;
+}
+
+interface MailMessage extends Rendered {
+	readonly to: Address | readonly Address[];
+	readonly from?: Address;
+	readonly replyTo?: Address;
+	readonly headers?: Readonly<Record<string, string>>;
+}
+```
+
+| Field | Type | Required | Effect |
+| --- | --- | --- | --- |
+| `subject` | `string` | yes | The subject line. No line break: a line break in a subject is a header injection |
+| `html` | `string` | yes | The HTML part, sent as is — escaping is the renderer's job |
+| `text` | `string` | yes | The plain-text part. Every e-mail has one |
+| `to` | `Address \| readonly Address[]` | yes | One recipient or several, at least one |
+| `from` | `Address` | no | The sender. `checkMessage` does not require one: a transport is usually wired with a default sender, and one without a default may refuse a message without `from` — see its documentation |
+| `replyTo` | `Address` | no | Where replies go |
+| `headers` | `Record<string, string>` | no | Extra headers, such as `List-Unsubscribe` |
+
+`Rendered` is what the renderer answers — `mails.render('verify-email', { name, link })`
+fills the values only known at send time into a built Maizzle template — and a
+rendered e-mail is spread into the message and addressed:
+
+```ts
+import { type Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendVerification(mailer: Mailer, to: string, name: string, link: string): Promise<void> {
+	await mailer.send({ to, ...mails.render('verify-email', { name, link }) });
+}
+```
+
+See [Rendering](rendering.md). Any function answering the same shape fits too:
+
+```ts
+import type { Mailer, Rendered } from '@nxgt/mail';
+
+// Hand-written: any function answering Rendered is accepted.
+function welcome(): Rendered {
+	return {
+		subject: 'Welcome aboard',
+		html: '<p>Welcome aboard.</p>',
+		text: 'Welcome aboard.',
+	};
+}
+
+export async function sendWelcome(mailer: Mailer, email: string): Promise<void> {
+	await mailer.send({ ...welcome(), to: email });
+}
+```
+
+Escaping is the renderer's job: `createMailRenderer` HTML-escapes every value
+it fills into `html` ([Rendering — escaping](rendering.md#escaping)). A
+hand-written function that interpolates a value must escape it in `html`
+itself.
+
+## Addresses
+
+```ts
+type Address = string | { readonly name: string; readonly address: string };
+```
+
+A string is **only** an address. A display name goes in the object form, so a
+transport never parses one — and a string a parser would read as more than
+one mailbox is refused. A name is free text — `Doe, John` is a name — and
+is refused only when it holds a line break; quoting or encoding it in a header
+is the transport's job, which the conformance suite checks:
+
+```ts
+import type { MailMessage, Rendered } from '@nxgt/mail';
+
+declare const rendered: Rendered;
+
+const message: MailMessage = {
+	...rendered,
+	to: ['ada@example.com', { name: 'Grace Hopper', address: 'grace@example.com' }],
+	from: { name: 'Example', address: 'noreply@example.com' },
+	replyTo: 'support@example.com',
+};
+```
+
+What is checked is deliberately loose: one `@`, something on each side, and
+none of what an address list reads as structure — no whitespace, no angle
+bracket, no `,` or `;` (a second address), no `:` (a group). Whether the
+mailbox exists is the receiving server's question.
+
+| Written | Answer |
+| --- | --- |
+| `'ada@example.com'` | accepted |
+| `{ name: 'Ada', address: 'ada@example.com' }` | accepted |
+| `'Ada <ada@example.com>'` | `MailRefused`: `send: to is not an e-mail address` |
+| `'root,ada@example.com'` | `MailRefused`: `send: to is not an e-mail address` — a provider parsing it would send to `ada` alone, or to two mailboxes |
+| `{ name: 'Doe, John', address: 'john@example.com' }` | accepted: a name is free text |
+| no `to`, or `to: []` | `MailRefused`: `send: to must hold at least one address` |
+| `to: [undefined]` | `MailRefused`: `send: to[0] is not an e-mail address` |
+| `{ name: 'A\r\nBcc: x@y.z', address: 'a@b.c' }` in `from` | `MailRefused`: `send: from.name must be a string without a line break` |
+| `{ name: 'Ada' }` | a compile error: `address` is required |
+
+`addressOf(address)` answers the bare address of either form, and
+`recipientsOf(message)` every recipient's, in order — mostly useful to a
+transport:
+
+```ts
+import { addressOf, recipientsOf } from '@nxgt/mail';
+
+addressOf({ name: 'Ada', address: 'ada@example.com' }); // 'ada@example.com'
+recipientsOf({
+	to: ['a@example.com', { name: 'B', address: 'b@example.com' }],
+	subject: 's',
+	html: 'h',
+	text: 't',
+}); // ['a@example.com', 'b@example.com']
+```
+
+## Headers
+
+A header name is letters, digits and hyphens; neither a name nor a value may
+hold a line break. What the transport writes from the message — the
+addresses, the subject, the MIME structure — cannot be set here: `To`, `Cc`,
+`Bcc`, `From`, `Sender`, `Reply-To`, `Return-Path`, `Subject`,
+`MIME-Version` and any `Content-*` are refused, in any case. A `Bcc` among
+the headers would reach an SMTP envelope as a recipient no check saw:
+
+```ts
+import type { MailMessage, Rendered } from '@nxgt/mail';
+
+declare const rendered: Rendered;
+
+const message: MailMessage = {
+	...rendered,
+	to: 'ada@example.com',
+	headers: {
+		'List-Unsubscribe': '<https://example.com/unsubscribe?u=42>',
+		'X-Entity-Ref-ID': 'welcome-42',
+	},
+};
+```
+
+| Written | Answer |
+| --- | --- |
+| `{ 'X Bad': 'v' }` | `MailRefused`: `send: a header name must be letters, digits and hyphens` |
+| `{ 'X-Ref': 'a\r\nb' }` | `MailRefused`: `send: header X-Ref must be a string without a line break` |
+| `{ Bcc: 'eve@example.com' }` | `MailRefused`: `send: header Bcc is reserved — addresses, the subject and the MIME structure are never custom headers` |
+| `{ 'content-type': 'text/plain' }` | `MailRefused`: `send: header content-type is reserved — …` |
+
+## Errors
+
+```ts
+type MailErrorCode = 'MAIL_FAILED' | 'MAIL_REFUSED';
+
+interface MailErrorOptions {
+	readonly cause?: unknown; // the error that caused this one, typically the transport's
+}
+
+abstract class MailError extends Error {
+	abstract readonly code: MailErrorCode;
+	constructor(message: string, options?: MailErrorOptions);
+}
+class MailFailure extends MailError {
+	readonly code: 'MAIL_FAILED';
+}
+class MailRefused extends MailError {
+	readonly code: 'MAIL_REFUSED';
+}
+```
+
+| Code | Class | When | Sending it again |
+| --- | --- | --- | --- |
+| `MAIL_FAILED` | `MailFailure` | The transport could not hand the e-mail over: a refused connection, a timeout, a 5xx from the provider, an expired credential. The transport's error is the `cause`. **Nothing is known to have been sent**: after a timeout or a dropped connection the provider may have taken it all the same | May work later. Never report it as sent |
+| `MAIL_REFUSED` | `MailRefused` | The e-mail itself was refused, before or by the transport: no recipient, something that is not an address, a line break in the subject or a header, a reserved header, or the provider answering that the message is malformed | Fails again, unchanged |
+
+`MailError` is **abstract**: catch it, test `instanceof MailError`, but
+`new MailError(…)` does not compile — a bare one would pass a `code` check and
+fail `instanceof MailFailure`. What is thrown is always one of the two
+subclasses. `MailError` extends `Error`, not `TypeError`, so a `catch` needs no
+ordering.
+`code` is a union, so a `switch` over it is exhaustive: when a code is added, a
+function like `statusOf` below stops compiling instead of answering
+`undefined`.
+
+```ts
+import { MailError, type MailErrorCode, type Mailer, type MailMessage } from '@nxgt/mail';
+
+export function statusOf(code: MailErrorCode): number {
+	switch (code) {
+		case 'MAIL_FAILED':
+			return 503;
+		case 'MAIL_REFUSED':
+			return 422;
+	}
+}
+
+export async function sendOrRespond(mailer: Mailer, message: MailMessage): Promise<Response> {
+	try {
+		await mailer.send(message);
+		return new Response(null, { status: 202 });
+	} catch (error) {
+		if (!(error instanceof MailError)) throw error;
+		return Response.json({ code: error.code }, { status: statusOf(error.code) });
+	}
+}
+```
+
+**An error's `message` reports a shape, never a value.** It names where the
+problem is — `send: to[1] is not an e-mail address` — and never the address,
+the subject or a link: the link in a verification e-mail is a credential, and
+an address is personal data. What the provider said is on `cause`, for your
+logs.
+
+A refusal that can only come from how the application was wired — a bad option
+passed to a transport's factory — is a bare `TypeError`. No request handler
+should answer one, so none needs to tell it apart.
+
+## A realistic case — a sign-up handler
+
+The account is created whatever happens to the e-mail; what the visitor is told
+depends on whether the e-mail left:
+
+```ts
+import { MailError, type Mailer } from '@nxgt/mail';
+import { type MailRenderer } from '@nxgt/mail/renderer';
+
+// Yours: your user store, your token issuer.
+declare function createUser(email: string): Promise<{ id: string; email: string; name: string }>;
+declare function issueVerificationToken(userId: string): Promise<string>;
+
+export function signUpHandler(mailer: Mailer, mails: MailRenderer) {
+	return async (request: Request): Promise<Response> => {
+		const { email } = (await request.json()) as { email: string };
+		const user = await createUser(email);
+		const token = await issueVerificationToken(user.id);
+		const link = `https://app.example.com/verify?token=${encodeURIComponent(token)}`;
+
+		try {
+			// Inside the try: render throws MailRefused for a link that is not a safe URL.
+			await mailer.send({ to: user.email, ...mails.render('verify-email', { name: user.name, link }) });
+		} catch (error) {
+			if (!(error instanceof MailError)) throw error;
+			// MAIL_FAILED: offer "send it again" later. MAIL_REFUSED: the address is unusable.
+			return Response.json({ userId: user.id, emailSent: false, code: error.code }, { status: 201 });
+		}
+		return Response.json({ userId: user.id, emailSent: true }, { status: 201 });
+	};
+}
+```
+
+## See also
+
+- [Rendering](rendering.md) — filling a Maizzle build into the `Rendered` a message spreads.
+- [Testing](testing.md) — the memory mailer, and making a send fail on purpose.
+- [Locales](locales.md) — choosing the locale an e-mail is rendered in.
+- [Writing a transport](transports.md) — implementing the port.
+- [Troubleshooting](../troubleshooting.md) — each error message, its cause and
+  its fix.

package/docs/guide/testing.md

@@ -0,0 +1,175 @@
+# Testing with the memory mailer
+
+This page is for testing code that sends e-mail: `createMemoryMailer()` keeps
+what it accepts in an outbox, refuses what every transport refuses, and can be
+told to fail, so a test proves what your code does when a send throws.
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer } from '@nxgt/mail';
+
+it('sends one e-mail', async () => {
+	const mailer = createMemoryMailer();
+
+	await mailer.send({ to: 'ada@example.com', subject: 'Hello', html: '<p>Hello</p>', text: 'Hello' });
+
+	expect(mailer.sent.map((mail) => [mail.messageId, mail.subject])).toEqual([['memory-1', 'Hello']]);
+});
+```
+
+## The signature
+
+```ts
+function createMemoryMailer(): MemoryMailer;
+
+interface MemoryMailer extends Mailer {
+	readonly sent: readonly MemoryMail[];
+	readonly attempts: number;
+	failNext(error?: MailError): void;
+	clear(): void;
+}
+
+interface MemoryMail extends MailMessage {
+	readonly messageId: string;
+}
+```
+
+A `MemoryMailer` **is** a `Mailer`: pass it wherever your code takes the port.
+It takes no option.
+
+## `sent` — the outbox
+
+Every message accepted so far, oldest first, each with the id it was answered:
+`memory-1`, `memory-2`, … The counter is per mailer.
+
+`sent` is **a copy** on every read: mutating it, or the message you passed to
+`send`, changes nothing in the outbox.
+
+```ts
+import { createMemoryMailer } from '@nxgt/mail';
+
+const mailer = createMemoryMailer();
+const headers = { 'X-Ref': 'a' };
+await mailer.send({ to: 'ada@example.com', subject: 'Hi', html: '<p>Hi</p>', text: 'Hi', headers });
+headers['X-Ref'] = 'changed';
+
+mailer.sent[0]?.headers; // { 'X-Ref': 'a' }
+```
+
+## `failNext(error?)` — making a send fail
+
+The next send that reaches the hand-over rejects with `error` — by default a
+`MailFailure`, as an outage would, with a `cause` (an `Error` whose message is
+`memory mailer: failNext`) as a real transport's has. Calls queue: two calls fail the next two
+sends, in order. The send after them goes through.
+
+```ts
+import { createMemoryMailer, MailRefused } from '@nxgt/mail';
+
+const mailer = createMemoryMailer();
+const refused = new MailRefused('send: the provider refused the message');
+mailer.failNext(refused); // the first send rejects with this very error
+mailer.failNext(); // the second with a MailFailure
+```
+
+Settle the expected rejection where it is created, with `.then(ok, ko)`, so a
+send that resolves by mistake fails the test rather than slipping past it:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer, MailFailure } from '@nxgt/mail';
+
+it('fails the next send when told to', async () => {
+	const mailer = createMemoryMailer();
+	mailer.failNext();
+
+	const error = await mailer
+		.send({ to: 'ada@example.com', subject: 'Hi', html: '<p>Hi</p>', text: 'Hi' })
+		.then(() => null, (e: unknown) => e);
+
+	expect(error).toBeInstanceOf(MailFailure);
+	expect(mailer.sent).toEqual([]);
+});
+```
+
+## `attempts` — proving nothing retries in secret
+
+How many sends reached the hand-over, failed ones included. A message refused
+as malformed never reaches it, and a queued failure keeps waiting for one that
+does:
+
+```ts
+import { createMemoryMailer } from '@nxgt/mail';
+
+const mailer = createMemoryMailer();
+mailer.failNext();
+
+await mailer
+	.send({ to: [], subject: 'Hi', html: '<p>Hi</p>', text: 'Hi' })
+	.then(() => null, (e: unknown) => e); // MailRefused: to must hold at least one address
+
+mailer.attempts; // 0 — and the failure is still queued for the next well-formed send
+```
+
+## `clear()`
+
+Forgets the outbox, the attempts, and any queued failure. The id counter keeps
+going, so an id is never reused within one mailer.
+
+## What it refuses
+
+Exactly what every transport refuses, because it calls
+[`checkMessage`](transports.md#checkmessage-first) first: no recipient, something
+that is not an address, a line break in a name, the subject or a header, a
+missing part. A test that passes against the memory mailer does not pass by
+accident a message a real transport would refuse. The full list is in
+[Sending](sending.md#addresses).
+
+## A realistic case — the failure path of a service
+
+A service that depends on the port gets the memory mailer in its test, and the
+test proves the user is told the truth when the send fails:
+
+```ts
+import { describe, expect, it } from 'bun:test';
+import { createMemoryMailer, MailError, type Mailer } from '@nxgt/mail';
+
+// The code under test: it answers whether the e-mail left.
+async function sendReset(mailer: Mailer, email: string): Promise<{ sent: boolean }> {
+	try {
+		await mailer.send({
+			to: email,
+			subject: 'Reset your password',
+			html: '<p>Follow the link to reset your password.</p>',
+			text: 'Follow the link to reset your password.',
+		});
+		return { sent: true };
+	} catch (error) {
+		if (error instanceof MailError) return { sent: false };
+		throw error;
+	}
+}
+
+describe('sendReset', () => {
+	it('reports a sent e-mail as sent', async () => {
+		const mailer = createMemoryMailer();
+		expect(await sendReset(mailer, 'ada@example.com')).toEqual({ sent: true });
+		expect(mailer.sent[0]?.to).toBe('ada@example.com');
+	});
+
+	it('never reports a failed e-mail as sent, and does not retry it', async () => {
+		const mailer = createMemoryMailer();
+		mailer.failNext();
+
+		expect(await sendReset(mailer, 'ada@example.com')).toEqual({ sent: false });
+		expect(mailer.sent).toEqual([]);
+		expect(mailer.attempts).toBe(1);
+	});
+});
+```
+
+## See also
+
+- [Sending](sending.md) — the message shape and the two errors.
+- [Writing a transport](transports.md) — the memory mailer is also the
+  reference transport the conformance suite is proven against.