@nxgt/mail 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -24,6 +24,21 @@ export interface Rendered {
     readonly html: string;
     readonly text: string;
 }
+/**
+ * A file sent with an e-mail, **as bytes**: never a path or a URL for the
+ * transport to read, never a stream. A large or sensitive file is a signed
+ * link in the template instead — a URL variable.
+ *
+ * `filename` is what the recipient's mail client shows and saves it as: no
+ * path (`/`, `\`, `.`, `..`), no line break, no control or format character.
+ * `contentType` is a bare `type/subtype`, as `application/pdf`, without
+ * parameters, and never a MIME container (`multipart/*`, `message/*`).
+ */
+export interface MailAttachment {
+    readonly filename: string;
+    readonly content: Uint8Array;
+    readonly contentType: string;
+}
 /**
  * A rendered e-mail, addressed. What a {@link Mailer} sends.
  *
@@ -42,6 +57,11 @@ export interface MailMessage extends Rendered {
      * case — is refused.
      */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Files sent with the e-mail, in order. An empty list is the same as none.
+     * Each is bytes, checked by `checkMessage`: see {@link MailAttachment}.
+     */
+    readonly attachments?: readonly MailAttachment[];
 }
 /** What a transport answers once it has handed a message over. */
 export interface SentMail {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAChB,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAChB,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9C"}

package/docs/README.md

@@ -8,8 +8,8 @@ mailer, transport, hand-over, refusal, failure — are defined once, in the
 | Page | Read it when |
 | --- | --- |
 | [Rendering](guide/rendering.md) | You are turning a Maizzle build of `@nxgt/mail-i18n` into an e-mail with `createMailRenderer`: its options, typing it with the build's `MailEmails`, choosing the locale, escaping, URL variables, deploying the build, and every error |
-| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
-| [Testing](guide/testing.md) | You are testing code that sends e-mail with `createMemoryMailer`: reading the outbox, making a send fail, counting attempts |
+| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, attachments, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
+| [Testing](guide/testing.md) | You are testing code that sends e-mail with `createMemoryMailer`: reading the outbox and its attachments, making a send fail, counting attempts |
 | [Locales](guide/locales.md) | You are choosing the locale an e-mail is rendered in, with `pickLocale` and `parseAcceptLanguage` |
 | [Writing a transport](guide/transports.md) | You are implementing the `Mailer` port for a provider, and running `@nxgt/mail/conformance` against it |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |

package/docs/guide/sending.md

@@ -1,7 +1,8 @@
 # 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.
+addresses, headers and attachments it accepts, what it answers, and what it
+throws.
 
 ```ts
 import { createMemoryMailer } from '@nxgt/mail';
@@ -73,6 +74,13 @@ interface MailMessage extends Rendered {
 	readonly from?: Address;
 	readonly replyTo?: Address;
 	readonly headers?: Readonly<Record<string, string>>;
+	readonly attachments?: readonly MailAttachment[];
+}
+
+interface MailAttachment {
+	readonly filename: string;
+	readonly content: Uint8Array;
+	readonly contentType: string;
 }
 ```
 
@@ -85,6 +93,7 @@ interface MailMessage extends Rendered {
 | `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` |
+| `attachments` | `readonly MailAttachment[]` | no | Files sent with the e-mail, in order, as bytes — see [Attachments](#attachments). An empty list is the same as none |
 
 `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
@@ -214,6 +223,85 @@ const message: MailMessage = {
 | `{ 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 — …` |
 
+## Attachments
+
+An attachment is a file's **bytes**, its name and its type:
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `filename` | `string` | The name the recipient's mail client shows and saves it as. Not empty, not `.` or `..`; no `/` or `\`, no line break, no control or format character. Accents and spaces are fine: the transport encodes the name |
+| `content` | `Uint8Array` | The bytes, sent as they are. A Node `Buffer` is a `Uint8Array` |
+| `contentType` | `string` | A bare `type/subtype`, as `application/pdf` or `text/calendar` — no parameters, and never `multipart/*` or `message/*`, which are not files. Nothing guesses it from the file name |
+
+```ts
+import { readFile } from 'node:fs/promises';
+import type { Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendInvoice(mailer: Mailer, to: string, name: string, number: string): Promise<void> {
+	const pdf = await readFile(`invoices/${number}.pdf`); // your storage: a Buffer
+	await mailer.send({
+		to,
+		...mails.render('invoice', { name, number }),
+		attachments: [{ filename: `invoice-${number}.pdf`, content: pdf, contentType: 'application/pdf' }],
+	});
+}
+```
+
+Bytes from anywhere fit — a file read with `readFile`, a PDF your code just
+generated, what `fetch` answered (`new Uint8Array(await response.arrayBuffer())`),
+or text you encoded (`new TextEncoder().encode(csv)`).
+
+**There is no `path`, no URL and no stream.** A transport never reads a file
+from disk or fetches a URL to attach it: a value that came from outside —
+a file name in a request, a link in a database — can then never make an
+e-mail carry a file it should not. The SMTP transport tells nodemailer so
+explicitly. Read the file yourself, where you decide which files may be read.
+
+**A large or sensitive file is a link.** Every provider caps the whole
+message — about 25 MB sending through Gmail, 40 MB at Resend once encoded —
+and base64, which every transport uses on the way, makes a file a third
+larger. A file in an e-mail also stays in an inbox forever, forwarded or not.
+Put a signed, expiring URL in the template instead; a
+[URL variable](rendering.md) is already checked (`http:`, `https:` or
+`mailto:` only):
+
+```ts
+import type { Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+declare function signedUrl(key: string, expiresInSeconds: number): Promise<string>; // your storage
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendExport(mailer: Mailer, to: string, key: string): Promise<void> {
+	const link = await signedUrl(key, 24 * 3600);
+	await mailer.send({ to, ...mails.render('export-ready', { link }) });
+}
+```
+
+Inline images — a `cid:` the HTML points at — are not supported yet: a
+logo belongs on an `https:` URL, which is what the templates of
+`@nxgt/mail-ui` already use.
+
+`checkMessage` refuses, naming where and never the file's name:
+
+| Written | Answer |
+| --- | --- |
+| `attachments: pdf` — one, not in a list | a compile error; at run time `MailRefused`: `send: attachments must be an array` |
+| `[null]` | `MailRefused`: `send: attachments[0] must be an object, as { filename, content, contentType }` |
+| `{ filename, content: '%PDF-1.7', contentType }`, or `{ filename, path, contentType }` | a compile error; at run time `MailRefused`: `send: attachments[0].content must be a Uint8Array — the file's bytes, never a path or a URL` |
+| `filename: 'invoices/42.pdf'`, `'..\\42.pdf'`, `'..'`, `''`, or one holding a line break or a right-to-left override | `MailRefused`: `send: attachments[0].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character` |
+| `contentType: 'text/plain; charset=utf-8'`, `'pdf'`, or `'message/rfc822'` | `MailRefused`: `send: attachments[0].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*` |
+| `attachments: []` | accepted: the same as none |
+
+A message the provider refuses — too large, or an attachment it will not
+carry — is a `MailRefused` from the transport (an SMTP `552`; a Resend `400`,
+`413` or `422`), and sending it again unchanged fails again: send a link
+instead.
+
 ## Errors
 
 ```ts
@@ -238,7 +326,7 @@ class MailRefused extends MailError {
 | 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 |
+| `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, an attachment that is not bytes or is badly named, or the provider answering that the message is malformed or too large | 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

package/docs/guide/testing.md

@@ -56,6 +56,38 @@ headers['X-Ref'] = 'changed';
 mailer.sent[0]?.headers; // { 'X-Ref': 'a' }
 ```
 
+### Attachments in the outbox
+
+An attachment is kept with its bytes **copied** when it is sent: a caller that
+reuses or fills its buffer afterwards does not change what the outbox holds,
+and each read of `sent` hands out a fresh copy again. A Node `Buffer` comes
+back as a plain `Uint8Array` of the same bytes — compare the bytes, not the
+class:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer } from '@nxgt/mail';
+
+it('attaches the invoice', async () => {
+	const mailer = createMemoryMailer();
+	const pdf = Buffer.from('%PDF-1.7');
+
+	await mailer.send({
+		to: 'ada@example.com',
+		subject: 'Your invoice',
+		html: '<p>Your invoice is attached.</p>',
+		text: 'Your invoice is attached.',
+		attachments: [{ filename: 'invoice-42.pdf', content: pdf, contentType: 'application/pdf' }],
+	});
+	pdf.fill(0); // changes nothing in the outbox
+
+	const [file] = mailer.sent[0]?.attachments ?? [];
+	expect(file?.filename).toBe('invoice-42.pdf');
+	expect(file?.contentType).toBe('application/pdf');
+	expect(new TextDecoder().decode(file?.content)).toBe('%PDF-1.7');
+});
+```
+
 ## `failNext(error?)` — making a send fail
 
 The next send that reaches the hand-over rejects with `error` — by default a
@@ -121,9 +153,11 @@ going, so an id is never reused within one mailer.
 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
+missing part, an attachment that is not bytes, or whose file name or type is
+malformed. 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).
+[Sending](sending.md#addresses) and
+[Sending — attachments](sending.md#attachments).
 
 ## A realistic case — the failure path of a service
 

package/docs/guide/transports.md

@@ -50,9 +50,13 @@ A transport:
    separate field when the API has one, a quoted or encoded display name in a
    header otherwise. A name is free text: `Ada <mallory@example.test>, "Eve"`
    is a name, and it must reach only its own address;
-6. **never retries in secret**, never resolves `false`, never logs and
+6. **sends each attachment's bytes as they are**, with its file name and its
+   type — base64 in a JSON body, a MIME part over SMTP, the name encoded when
+   it is not ASCII — and **never reads a file or fetches a URL** to attach
+   one: `MailAttachment` holds bytes only;
+7. **never retries in secret**, never resolves `false`, never logs and
    resolves;
-7. **defines no error class of its own**. It throws the classes imported from
+8. **defines no error class of its own**. It throws the classes imported from
    `@nxgt/mail`, declared as a required peer, so `error instanceof MailFailure`
    holds in the application whichever transport threw it. `MailError` is
    abstract, so a bare one cannot be thrown:
@@ -60,11 +64,15 @@ A transport:
 ```json
 {
 	"peerDependencies": {
-		"@nxgt/mail": "^0.1.0"
+		"@nxgt/mail": "^0.2.0"
 	}
 }
 ```
 
+On `0.x`, a caret covers one minor: `^0.2.0` is `>=0.2.0 <0.3.0`. Declare the
+minor whose `MailMessage` your transport reads — `0.2` is the one with
+`attachments` — and release your transport when `@nxgt/mail` moves to the next.
+
 An error's `message` reports a shape, never a value: never an address, a
 subject, a link, an API key or a connection string. What the provider said goes
 on `cause`.
@@ -92,6 +100,14 @@ Throws `MailRefused`, naming **where** the problem is and never the value:
 | a header name that is not letters, digits and hyphens | `send: a header name must be letters, digits and hyphens` |
 | a line break in a header value | `send: header X-Ref must be a string without a line break` |
 | a header the transport writes from the message — `To`, `Cc`, `Bcc`, `From`, `Sender`, `Reply-To`, `Return-Path`, `Subject`, `MIME-Version`, `Content-*`, in any case | `send: header Bcc is reserved — addresses, the subject and the MIME structure are never custom headers` |
+| `attachments` that is not an array | `send: attachments must be an array` |
+| an attachment that is not an object | `send: attachments[0] must be an object, as { filename, content, contentType }` |
+| an attachment whose `content` is not a `Uint8Array` — a string, a path, an `ArrayBuffer` | `send: attachments[0].content must be a Uint8Array — the file's bytes, never a path or a URL` |
+| a file name that is empty, `.` or `..`, or holds `/`, `\`, a line break, a control character or a format character | `send: attachments[0].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character` |
+| a content type that is not a bare `type/subtype`, or is `multipart/*` or `message/*` | `send: attachments[0].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*` |
+
+An empty `attachments` is accepted, and is the same as none: send no
+attachment field to the provider then.
 
 Two helpers turn addresses into what a provider wants:
 
@@ -115,6 +131,15 @@ export interface HttpMailerOptions {
 	readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
 }
 
+/** Base64 with no Node built-in, read in slices so a large file spreads no huge argument list. */
+function base64Of(bytes: Uint8Array): string {
+	let binary = '';
+	for (let start = 0; start < bytes.length; start += 0x8000) {
+		binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+	}
+	return btoa(binary);
+}
+
 export function createHttpMailer(options: HttpMailerOptions): Mailer {
 	// Wiring mistakes: a bare TypeError, now, and never the value.
 	if (!/^https?:\/\//.test(options.endpoint)) {
@@ -128,13 +153,22 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 	return {
 		async send(message) {
 			checkMessage(message);
+			// A JSON API takes an attachment's bytes as base64.
+			// An empty list is none: the field is left out of the request.
+			const attachments = message.attachments?.length
+				? message.attachments.map((file) => ({
+						filename: file.filename,
+						content: base64Of(file.content),
+						contentType: file.contentType,
+					}))
+				: undefined;
 
 			let response: Response;
 			try {
 				response = await post(options.endpoint, {
 					method: 'POST',
 					headers: { authorization: `Bearer ${options.apiKey}`, 'content-type': 'application/json' },
-					body: JSON.stringify({ ...message, from: message.from ?? options.from }),
+					body: JSON.stringify({ ...message, from: message.from ?? options.from, attachments }),
 				});
 			} catch (cause) {
 				throw new MailFailure('send: the provider could not be reached', { cause });
@@ -204,16 +238,19 @@ and when `skip` names a case that does not exist
 | `send.deliversBytes` | the subject, the HTML and the text are delivered byte for byte: accents, an emoji, `&amp;` in a link | no |
 | `send.recipients` | every recipient is delivered to, written as a string or with a name | no |
 | `send.hostileName` | a name holding `<…>`, a comma and quotes — `Ada <mallory@example.test>, "Eve" <eve@example.test>;` — reaches only its own address: quoting the name is the transport's job | no |
+| `send.attachment` | an attachment — `sampleAttachment`, every byte from 0 to 255 named `reçu n° 42.pdf`, `application/pdf` — is delivered byte for byte, with its file name and its type (compared without case), and the parts beside it as sent | no |
 | `send.refusesNoRecipient` | no recipient throws `MailRefused`, and nothing is delivered | no |
 | `send.refusesLineBreakInSubject` | a line break in the subject throws `MailRefused`, and nothing is delivered | no |
 | `send.refusesAddressHeader` | a `Bcc` among the custom headers throws `MailRefused` without the address in its message, and nothing is delivered: it would add a recipient no check saw | no |
+| `send.refusesAttachmentPath` | an attachment named with a path (`../…/report.pdf`) throws `MailRefused` without the name in its message, and nothing is delivered: a mail client could save it elsewhere | no |
 | `send.refusesWithoutTheValue` | a refusal's `message` does not hold the refused value | no |
 | `failure.outage` | an outage throws `MailFailure` — **the class from `@nxgt/mail`** — with code `MAIL_FAILED` and a `cause`; one attempt; nothing delivered | yes |
 | `failure.refusal` | a provider's refusal throws `MailRefused` with code `MAIL_REFUSED` and a `cause`; one attempt | yes |
 | `failure.recovers` | after a failure, the next send goes through | yes |
 
-The message they send is exported as `sampleMessage`, and the cases as data:
-`sendCases` (the eight `send.*`), `failureCases` (the three `failure.*`) and
+The message they send is exported as `sampleMessage`, its attachment as
+`sampleAttachment`, and the cases as data:
+`sendCases` (the ten `send.*`), `failureCases` (the three `failure.*`) and
 `allMailerCases` (both, in the order above). A transport's own tests can reuse
 them — send the sample through your transport, or run only the cases that
 need no faults:
@@ -262,6 +299,7 @@ interface DeliveredMail {
 	readonly subject: string;
 	readonly html: string;
 	readonly text: string;
+	readonly attachments?: readonly MailAttachment[]; // as they arrived: [] when none did
 }
 
 interface MailerFaults {
@@ -274,7 +312,11 @@ interface MailerFaults {
   fresh receiving end, so no case sees another's messages.
 - `delivered()` reads back what **the receiving end** got — the test SMTP
   server, the recorded request, the fake provider — not what the mailer was
-  asked to send.
+  asked to send. That includes each attachment, decoded back to bytes:
+  `mailparser`'s `attachments` over SMTP, the base64 `content` of a JSON body
+  otherwise. `attachments` is optional so a harness written before it still
+  compiles, but `send.attachment` **fails** on a harness that leaves it out,
+  saying so — read them back, or skip the case with its reason.
 - `close()`, when present, is called after the case, pass or fail.
 
 ### Faults — failing the way the provider fails
@@ -290,11 +332,16 @@ translation of its provider's errors.
 
 ```ts
 // fake-provider.ts
-import { type MailMessage, recipientsOf } from '@nxgt/mail';
+import { addressOf, type MailMessage } from '@nxgt/mail';
 import type { DeliveredMail, MailerFaults } from '@nxgt/mail/conformance';
 
+/** What the HTTP mailer above posts: a message, its attachments' bytes as base64. */
+type Posted = Omit<MailMessage, 'attachments'> & {
+	readonly attachments?: readonly { filename: string; content: string; contentType: string }[];
+};
+
 export function fakeProvider() {
-	const inbox: MailMessage[] = [];
+	const inbox: Posted[] = [];
 	let attempts = 0;
 	let next: 'outage' | 'refusal' | null = null;
 
@@ -315,18 +362,28 @@ export function fakeProvider() {
 			next = null;
 			if (fault === 'outage') return new Response('unavailable', { status: 503 });
 			if (fault === 'refusal') return Response.json({ error: 'malformed' }, { status: 422 });
-			inbox.push(JSON.parse(String(init.body)) as MailMessage);
+			inbox.push(JSON.parse(String(init.body)) as Posted);
 			return Response.json({ id: `fake-${inbox.length}` });
 		},
 		delivered(): DeliveredMail[] {
-			return inbox.map((mail) => ({ to: recipientsOf(mail), subject: mail.subject, html: mail.html, text: mail.text }));
+			return inbox.map((mail) => ({
+				to: (Array.isArray(mail.to) ? mail.to : [mail.to]).map(addressOf),
+				subject: mail.subject,
+				html: mail.html,
+				text: mail.text,
+				attachments: (mail.attachments ?? []).map((file) => ({
+					filename: file.filename,
+					content: Uint8Array.from(atob(file.content), (char) => char.charCodeAt(0)),
+					contentType: file.contentType,
+				})),
+			}));
 		},
 	};
 }
 ```
 
 With the transport and the fake above, the example at the top of this page
-passes all eleven cases.
+passes all thirteen cases.
 
 ### Without faults
 

package/docs/roadmap.md

@@ -6,7 +6,16 @@ the only number.
 
 ## Now
 
-Nothing between releases.
+- **Attachments** — `attachments` on a `MailMessage`: each file's bytes as a
+  `Uint8Array`, its name and its type. Bytes only — no path, no URL, no
+  stream, so a transport never reads a file or fetches a URL for you; a large
+  or sensitive file stays a signed link in the template. `checkMessage`
+  refuses a name holding a path, a line break, a control or a format
+  character, `.` or `..`, and a type that is not `type/subtype` or is a MIME
+  container; the memory mailer keeps a copy of the
+  bytes; the conformance suite gains `send.attachment` and
+  `send.refusesAttachmentPath`, thirteen cases in all. The SMTP and Resend
+  transports send them. Built, not yet published.
 
 ## Next
 
@@ -14,6 +23,8 @@ Nothing yet.
 
 ## Later
 
+- **Inline images (`cid:`)** — an attachment the HTML shows by its content
+  id. Until then, an image is an `https:` URL, as `@nxgt/mail-ui`'s logo is.
 - **More transports** — Amazon SES, Postmark and Mailgun, one package each,
   each passing the conformance suite and throwing `@nxgt/mail`'s errors.