@nxgt/mail 0.1.0 → 0.3.0

package/docs/troubleshooting.md

@@ -40,6 +40,10 @@ How the messages are shaped:
 - [`TS2511: Cannot create an instance of an abstract class.`](#ts2511-cannot-create-an-instance-of-an-abstract-class)
 - [`TS2345: Argument of type '"verify-emial"' is not assignable to parameter of type '"sign-in-code" | "verify-email"'.`](#ts2345-argument-of-type-verify-emial-is-not-assignable-to-parameter-of-type-sign-in-code--verify-email)
 - [`TS2307: Cannot find module './generated/mail' or its corresponding type declarations.`](#ts2307-cannot-find-module-generatedmail-or-its-corresponding-type-declarations)
+- [`TS2322: Type 'string' is not assignable to type 'Uint8Array<ArrayBufferLike>'.`](#ts2322-type-string-is-not-assignable-to-type-uint8arrayarraybufferlike)
+- [`TS2353: Object literal may only specify known properties, and 'path' does not exist in type 'MailAttachment'.`](#ts2353-object-literal-may-only-specify-known-properties-and-path-does-not-exist-in-type-mailattachment)
+- [`TS2741: Property 'contentType' is missing in type '…' but required in type 'MailAttachment'.`](#ts2741-property-contenttype-is-missing-in-type--but-required-in-type-mailattachment)
+- [`TS2740: Type 'MailAttachment' is missing the following properties from type 'readonly MailAttachment[]': length, concat, join, slice, and 26 more.`](#ts2740-type-mailattachment-is-missing-the-following-properties-from-type-readonly-mailattachment-length-concat-join-slice-and-26-more)
 - [`error instanceof MailFailure` is `false` for an outage](#error-instanceof-mailfailure-is-false-for-an-outage)
 
 **Sending**
@@ -55,6 +59,14 @@ How the messages are shaped:
 - [`send: a header name must be letters, digits and hyphens`](#send-a-header-name-must-be-letters-digits-and-hyphens)
 - [`send: header <name> must be a string without a line break`](#send-header-name-must-be-a-string-without-a-line-break)
 - [`send: header <name> is reserved — addresses, the subject and the MIME structure are never custom headers`](#send-header-name-is-reserved--addresses-the-subject-and-the-mime-structure-are-never-custom-headers)
+- [`send: attachments must be an array`](#send-attachments-must-be-an-array)
+- [`send: attachments[<n>] must be an object, as { filename, content, contentType }`](#send-attachmentsn-must-be-an-object-as--filename-content-contenttype-)
+- [`send: attachments[<n>].content must be a Uint8Array — the file's bytes, never a path or a URL`](#send-attachmentsncontent-must-be-a-uint8array--the-files-bytes-never-a-path-or-a-url)
+- [`send: attachments[<n>].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character`](#send-attachmentsnfilename-must-be-a-file-name--not-empty-not--or--without--or--a-line-break-or-a-control-character)
+- [`send: attachments[<n>].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*`](#send-attachmentsncontenttype-must-be-a-files-typesubtype-as-applicationpdf--never-multipart-or-message)
+- [`send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt`](#send-idempotencykey-must-be-1-to-256-visible-ascii-characters-as-order-42receipt)
+- [`send: idempotencyKey was already used for a different message — a key names one e-mail`](#send-idempotencykey-was-already-used-for-a-different-message--a-key-names-one-e-mail)
+- [An e-mail is delivered twice although it has an `idempotencyKey`](#an-e-mail-is-delivered-twice-although-it-has-an-idempotencykey)
 - [`send: the memory mailer was told to fail this send`](#send-the-memory-mailer-was-told-to-fail-this-send)
 
 **Locale**
@@ -96,6 +108,9 @@ How the messages are shaped:
 - [`conformance: the transport retried a failed hand-over`](#conformance-the-transport-retried-a-failed-hand-over)
 - [`conformance: a name let a second recipient through`](#conformance-a-name-let-a-second-recipient-through)
 - [`conformance: <what>, yet something was delivered`](#conformance-what-yet-something-was-delivered)
+- [`conformance: the harness's delivered() reads back no attachments — read them from the receiving end, or skip send.attachment with the reason`](#conformance-the-harnesss-delivered-reads-back-no-attachments--read-them-from-the-receiving-end-or-skip-sendattachment-with-the-reason)
+- [`conformance: expected 1 delivered attachment, got <n>`](#conformance-expected-1-delivered-attachment-got-n)
+- [`conformance: the attachment was not delivered byte for byte`](#conformance-the-attachment-was-not-delivered-byte-for-byte)
 - [Other `conformance:` messages](#other-conformance-messages)
 - [A bug in `@nxgt/mail` itself](#a-bug-in-nxgtmail-itself)
 
@@ -340,6 +355,64 @@ To go without it, leave the type parameter out:
 `createMailRenderer({ dir: 'dist' })` takes any name and any
 `MailVariables`, checked at run time only.
 
+### `TS2322: Type 'string' is not assignable to type 'Uint8Array<ArrayBufferLike>'.`
+
+**When:** `tsc`, on an attachment whose `content` is text:
+`{ filename: 'notes.txt', content: 'notes', contentType: 'text/plain' }`.
+**Why:** an attachment is bytes. A string would be sent in whatever encoding
+the transport picked; bytes are sent as they are.
+**Fix:** encode the text yourself, in the encoding you mean:
+
+```ts
+import type { MailAttachment } from '@nxgt/mail';
+
+declare const csv: string;
+
+const report: MailAttachment = {
+  filename: 'report.csv',
+  content: new TextEncoder().encode(csv), // UTF-8
+  contentType: 'text/csv',
+};
+```
+
+### `TS2353: Object literal may only specify known properties, and 'path' does not exist in type 'MailAttachment'.`
+
+**When:** `tsc`, on an attachment written as nodemailer's, with a `path` (or
+an `href`) for the transport to read.
+**Why:** no transport reads a file or fetches a URL to attach it — a value
+from outside could then make an e-mail carry any file the server can read.
+`MailAttachment` holds the bytes.
+**Fix:** read the file where your code decides which files may be read, and
+pass its bytes:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import type { MailAttachment } from '@nxgt/mail';
+
+const invoice: MailAttachment = {
+  filename: 'invoice-42.pdf',
+  content: await readFile('/srv/invoices/42.pdf'),
+  contentType: 'application/pdf',
+};
+```
+
+A file too large to hold in memory is too large for an e-mail: send a signed
+link instead — [Sending — attachments](guide/sending.md#attachments).
+
+### `TS2741: Property 'contentType' is missing in type '…' but required in type 'MailAttachment'.`
+
+**When:** `tsc`, on an attachment without its `contentType`.
+**Why:** nothing guesses the type from the file name: a guess can be wrong,
+and a mail client opens a file by its type.
+**Fix:** name it — `application/pdf`, `text/calendar`, `image/png`, or
+`application/octet-stream` for bytes of no particular type.
+
+### `TS2740: Type 'MailAttachment' is missing the following properties from type 'readonly MailAttachment[]': length, concat, join, slice, and 26 more.`
+
+**When:** `tsc`, on `attachments: invoice` — one attachment, not in a list.
+**Why:** `attachments` is a list, even of one.
+**Fix:** `attachments: [invoice]`.
+
 ### `error instanceof MailFailure` is `false` for an outage
 
 **When:** at run time, with a transport from another package or your own. An
@@ -423,9 +496,13 @@ whether the e-mail is still worth sending.
 **When:** `await mailer.send(message)` rejects, either with one of the
 `send: …` messages below (the message was refused before it left), or with
 the transport's message when the provider answered that the message is
-malformed.
-**Why:** something in the message would break a header or has no valid
-recipient. Sending it again unchanged fails again.
+malformed or too large.
+**Why:** something in the message would break a header, has no valid
+recipient, is an attachment that is not bytes or is badly named, or is an
+`idempotencyKey` that is malformed or already used for a different message
+(the memory mailer's refusal, or Resend's `409 invalid_idempotent_request`) —
+or the whole message is over the provider's size limit. Sending it again
+unchanged fails again.
 **Fix:** read `error.message` for where the problem is, and fix the message;
 the entries below cover each one. Handle the code as in the
 [`MAIL_FAILED`](#mail_failed--mailfailure-the-transport-could-not-hand-the-message-over)
@@ -592,6 +669,184 @@ await mailer.send({ ...rendered, to: 'ada@example.com' });
 await mailer.send({ ...rendered, to: 'audit@example.com' }); // ✓ the copy, on its own
 ```
 
+### `send: attachments must be an array`
+
+**When:** `send`, with `attachments` that is not a list — one attachment on
+its own, or `null`.
+**Why:** the attachments are a list, in order, even of one.
+**Fix:** `attachments: [invoice]`; leave the field out, or pass `[]`, for none.
+
+### `send: attachments[<n>] must be an object, as { filename, content, contentType }`
+
+**When:** `send`, with an entry of `attachments` that is not an object —
+`undefined` from a lookup that found nothing, `null`, or a hole in the list
+(`[, pdf]`, `new Array(2)`). `<n>` is its index.
+**Why:** each entry is one file: its name, its bytes and its type.
+**Fix:** filter the list before sending, or refuse to send when a file you
+meant to attach is missing — an e-mail that says "attached" with nothing
+attached is worse than an error.
+
+### `send: attachments[<n>].content must be a Uint8Array — the file's bytes, never a path or a URL`
+
+**When:** `send`, with an attachment whose `content` is not a `Uint8Array`:
+a string, an `ArrayBuffer`, a stream, or no `content` at all because the
+attachment was written with a `path` or an `href`, as nodemailer takes them.
+A Node `Buffer` is a `Uint8Array`, and accepted.
+**Why:** an attachment is bytes the application already holds. No
+transport reads a file or fetches a URL to attach it, so a value from outside
+can never make an e-mail carry a file it should not.
+**Fix:** read or convert it first:
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+declare const csv: string;
+declare const response: Response;
+
+const fromDisk = await readFile('/srv/invoices/42.pdf'); // a Buffer
+const fromText = new TextEncoder().encode(csv);
+const fromFetch = new Uint8Array(await response.arrayBuffer());
+const fromArrayBuffer = new Uint8Array(new ArrayBuffer(8));
+```
+
+A file too large to read into memory is too large for an e-mail: send a
+signed link instead.
+
+### `send: attachments[<n>].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character`
+
+**When:** `send`, with an attachment whose `filename` is empty, is not a
+string, is `.` or `..`, or holds `/`, `\`, a line break (U+2028 and U+2029
+included), a NUL or another control character, or a format character such
+as a right-to-left override.
+The message never holds the name.
+**Why:** the recipient's mail client shows the name and saves the file under
+it. A path — `../…`, `invoices/42.pdf`, `C:\…`, `..` — asks it to save
+elsewhere, a line break or a control character can split the header the name
+is written in, and a right-to-left override shows `invoice\u202Efdp.exe` as
+`invoiceexe.pdf`.
+**Fix:** a bare file name. Accents, spaces and parentheses are fine — the
+transport encodes them. From a name you did not write, keep the last segment
+of the path and drop the control characters:
+
+```ts
+const safeName = (name: string) =>
+  name.split(/[\\/]/).pop()?.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '').trim().replace(/^\.\.?$/, '') ||
+  'attachment';
+
+safeName('../uploads/Relevé\nmars.pdf'); // 'Relevémars.pdf'
+```
+
+### `send: attachments[<n>].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*`
+
+**When:** `send`, with an attachment whose `contentType` is not a bare
+`type/subtype`: an extension (`pdf`), a type with parameters
+(`text/plain; charset=utf-8`), a space or a line break — or a MIME container,
+`multipart/*` or `message/*`, in any case.
+**Why:** the type is written into the attachment's `Content-Type` header; a
+parameter there is a second, unchecked place for a name or a charset. The
+transport writes the parameters it needs. A container is not a file: SMTP
+writes `message/rfc822` and `multipart/mixed` unencoded, as parts of the
+message itself, and the recipient gets no attachment while `send` resolves.
+To forward an e-mail, attach it as `application/octet-stream` with a `.eml`
+name.
+**Fix:** the bare type — `text/plain`, and encode the text as UTF-8, which is
+what a mail client assumes:
+
+```ts
+import type { MailAttachment } from '@nxgt/mail';
+
+const notes: MailAttachment = {
+  filename: 'notes.txt',
+  content: new TextEncoder().encode('Hello'),
+  contentType: 'text/plain',
+};
+```
+
+### `send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt`
+
+**When:** `send`, with an `idempotencyKey` that is empty, not a string,
+longer than 256 characters, or holds a space, a line break, a control
+character or anything outside ASCII — an accent, an emoji.
+The message never holds the key.
+**Why:** a transport that deduplicates writes the key into a header (Resend's
+`Idempotency-Key`), where only visible ASCII is safe, and Resend takes at most
+256 characters. The key is checked the same way on every transport, even one
+that ignores it, so switching transports never turns a working key into a
+refusal.
+**Fix:** build the key from what the e-mail is about, and encode what you did
+not write. `encodeURIComponent` keeps a readable key in visible ASCII; a hash
+bounds its length:
+
+```ts
+const orderRef = 'Commande n° 42'; // yours, not ASCII
+
+// Readable, when the reference is short:
+const key = `order-${encodeURIComponent(orderRef)}/receipt`; // order-Commande%20n%C2%B0%2042/receipt
+
+// Always under 256, whatever the reference:
+const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(orderRef));
+const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+const hashed = `order-${hex}/receipt`; // 64 hex digits, on any runtime
+
+// Pick one, and build it the same way on every attempt:
+await mailer.send({ ...message, idempotencyKey: hashed });
+```
+
+### `send: idempotencyKey was already used for a different message — a key names one e-mail`
+
+**When:** a test, on a send through `createMemoryMailer()` whose
+`idempotencyKey` the mailer already delivered, with a message that differs —
+another recipient, subject, body, header or attachment. A `MailRefused`,
+`code: 'MAIL_REFUSED'`; nothing is delivered. The same message again, key
+included, is not refused: it answers the first `messageId`.
+**Why:** a key names one e-mail. The memory mailer refuses a second, different
+message under it as Resend does (a `409` `invalid_idempotent_request`, which
+`@nxgt/mail-resend` throws as `send: Resend refused the message`), so the test
+fails where production would. The usual causes: a key per user or per job
+rather than per e-mail, or a retry that rendered the e-mail again with a
+template or a variable that changed in between.
+**Fix:** one key per e-mail, and the same message on every attempt at it —
+render once, keep the result with the job, and send that on retry:
+
+```ts
+const message = { ...rendered, to: user.email, idempotencyKey: `order-${order.id}/receipt` };
+
+await mailer.send(message); // the first attempt
+await mailer.send(message); // a retry: the same message, the first messageId
+```
+
+A message meant to be different — a corrected receipt — is a new e-mail:
+give it a new key (`order-42/receipt-2`). Between tests, `clear()` forgets the
+keys.
+
+### An e-mail is delivered twice although it has an `idempotencyKey`
+
+**When:** a retry — after a `MailFailure`, a timeout, a job run twice —
+delivers a second copy, although both sends carried an `idempotencyKey`.
+**Why:** either the key changed between the attempts, or the transport cannot
+deduplicate. A key built from `Date.now()` or `crypto.randomUUID()` at each
+attempt names a new send each time, so it deduplicates nothing. SMTP has no
+idempotency: `@nxgt/mail-smtp` ignores the key, and a message sent twice is
+delivered twice. Resend keeps a key for 24 hours; a retry after that is a new
+send.
+**Fix:** derive the key from what the e-mail is about — one key per e-mail
+the application means to send once — and compute it the same way on every
+attempt:
+
+```ts
+// ✗ a new key per attempt: every retry is a new e-mail
+await mailer.send({ ...message, idempotencyKey: crypto.randomUUID() });
+
+// ✓ the same key for every attempt at this e-mail
+await mailer.send({ ...message, idempotencyKey: `order-${order.id}/receipt` });
+```
+
+A key per user (`user-${user.id}`) is the opposite mistake: the second,
+different e-mail to that user is refused — by the memory mailer, as
+[`send: idempotencyKey was already used for a different message — a key names one e-mail`](#send-idempotencykey-was-already-used-for-a-different-message--a-key-names-one-e-mail),
+and by Resend, as `send: Resend refused the message`. When a random key is
+what you have, create it once, store it with the job, and reuse it on retry.
+
 ### `send: the memory mailer was told to fail this send`
 
 **When:** a test, on a send through `createMemoryMailer()` after
@@ -1188,7 +1443,8 @@ simulated, so the skip is on purpose and visible.
 
 `<send>` is, for example, `a send during an outage`, `a refused send`,
 `a send with no recipient`, `a send with a line break in the subject`,
-`a send with a Bcc header` or `a send to something that is not an address`.
+`a send with a Bcc header`, `a send with an attachment named with a path` or
+`a send to something that is not an address`.
 
 **When:** a `failure.*` or `send.refuses*` case.
 **Why:** the transport answered where it had to throw: it caught the
@@ -1298,6 +1554,64 @@ told "not sent" retries, and the e-mail arrives twice.
 **Fix:** call `checkMessage(message)` **before** the hand-over, and throw only
 for a hand-over that did not succeed.
 
+### `conformance: the harness's delivered() reads back no attachments — read them from the receiving end, or skip send.attachment with the reason`
+
+**When:** `send.attachment`, on a harness whose `delivered()` answers
+messages without an `attachments` field — typically one written before
+`@nxgt/mail` had attachments.
+**Why:** a missing field is not "no attachment arrived": the case cannot tell
+a transport that drops files from a harness that does not look. It fails
+rather than pass a transport it did not check.
+**Fix:** read the attachments back from the receiving end, decoded to bytes
+— `[]` when none arrived:
+
+```ts
+import type { DeliveredMail } from '@nxgt/mail/conformance';
+import type { ParsedMail } from 'mailparser';
+
+// Over SMTP, from what mailparser parsed:
+const fromSmtp = (parsed: ParsedMail): DeliveredMail['attachments'] =>
+  parsed.attachments.map((file) => ({
+    filename: file.filename ?? '',
+    content: new Uint8Array(file.content),
+    contentType: file.contentType,
+  }));
+
+// From a JSON body, where the content is base64:
+const fromJson = (files: { filename: string; content: string; contentType: string }[]) =>
+  files.map((file) => ({
+    ...file,
+    content: Uint8Array.from(atob(file.content), (char) => char.charCodeAt(0)),
+  }));
+```
+
+If the provider cannot carry attachments at all, say so:
+`skip: { 'send.attachment': 'the provider takes no attachments' }`.
+
+### `conformance: expected 1 delivered attachment, got <n>`
+
+**When:** `send.attachment`: the message arrived with no attachment, or
+with more than the one sent.
+**Why:** the transport left `message.attachments` out of what it handed
+over — the usual cause when a transport builds the provider's request field
+by field — or the harness reads the parts of the body as attachments too.
+**Fix:** map each attachment into the provider's request, as in
+[the transports guide](guide/transports.md#a-transport-over-http); in the
+harness, read only the parts the provider marks as attachments.
+
+### `conformance: the attachment was not delivered byte for byte`
+
+**When:** `send.attachment`, whose file holds every byte from 0 to 255.
+**Why:** the bytes were read as text on the way — decoded as UTF-8 (every
+byte above 127 changes), a NUL cut short, or line breaks rewritten — or
+base64 was encoded from a string instead of the bytes. Over JSON, the usual
+cause is a `Uint8Array` handed to `JSON.stringify` as it is: it becomes an
+object keyed by index (`{"0":0,"1":1,…}`), never base64, so the harness's
+`atob` throws or decodes something else.
+**Fix:** encode the bytes, never a string made of them: base64 from the
+`Uint8Array` for a JSON API, a `Buffer` of the same bytes for nodemailer.
+In the harness, decode base64 back to bytes, not to a string.
+
 ### Other `conformance:` messages
 
 Each names what the transport did not do, in the case whose id is in the
@@ -1316,7 +1630,12 @@ test title:
 | `conformance: a line break in the subject must throw MailRefused` | `send.refusesLineBreakInSubject` | call `checkMessage` |
 | `conformance: a malformed address must throw MailRefused` | `send.refusesWithoutTheValue` | call `checkMessage` |
 | `conformance: a Bcc header must throw MailRefused` | `send.refusesAddressHeader` | call `checkMessage`, from a version of `@nxgt/mail` that refuses reserved headers |
-| `conformance: the refusal message holds the refused value` | `send.refusesWithoutTheValue`, `send.refusesAddressHeader` | name where the problem is, never the value |
+| `conformance: an attachment named with a path must throw MailRefused` | `send.refusesAttachmentPath` | call `checkMessage`, from a version of `@nxgt/mail` that checks attachments (0.2 on) |
+| `conformance: the refusal message holds the refused value` | `send.refusesWithoutTheValue`, `send.refusesAddressHeader`, `send.refusesAttachmentPath` | name where the problem is, never the value |
+| `conformance: the message with an attachment was not delivered` | `send.attachment` | a message with attachments is a message: deliver it |
+| `conformance: the attachment was not delivered with its file name` | `send.attachment` | pass the name as is; the name `reçu n° 42.pdf` needs RFC 2231 encoding in a raw header — nodemailer and a JSON API do it for you |
+| `conformance: the attachment was not delivered with its content type` | `send.attachment` | pass `contentType` through; do not guess it from the name |
+| `conformance: the parts of a message with an attachment were not delivered as sent` | `send.attachment` | keep the HTML and the text parts beside the attachment — `multipart/mixed` around `multipart/alternative` |
 | `conformance: the send after a failure was not delivered` | `failure.recovers` | do not leave the transport broken after a failure: reopen the connection on the next send |
 | `conformance: faults are required` | a `failure.*` case whose `run` you called yourself | pass `faults` in the context, or go through `runMailerCase`, which skips the case instead |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "The run-time side of transactional e-mail: the renderer that fills a Maizzle build made with @nxgt/mail-i18n, the Mailer a transport implements, its errors, a memory transport and locale selection. No dependency.",
 	"license": "MIT",
 	"type": "module",

package/dist/chunks/index-0f7kdb8k.js.map

@@ -1,11 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/message.ts", "../src/memory.ts"],
-  "sourcesContent": [
-    "import { MailRefused } from './errors';\nimport type { Address, MailMessage } from './types';\n\nconst LINE_BREAK = /[\\r\\n]/;\n// Deliberately loose: one `@`, something on each side, and none of what an\n// address list parser reads as structure — whitespace, `<` `>` (a display\n// name), `,` `;` (a second address), `:` (a group). A provider that parses\n// the string then finds one mailbox, the one checked. Whether the mailbox\n// exists is the receiving server's question.\nconst ADDRESS = /^[^\\s@<>,;:]+@[^\\s@<>,;:]+$/;\nconst HEADER_NAME = /^[A-Za-z0-9-]+$/;\n// The headers a transport writes from the message: the addresses, the subject\n// and the MIME structure. Set through `headers`, a Bcc reaches an SMTP\n// envelope unchecked, and a Content-Type rewrites how the parts are read.\nconst RESERVED_HEADER =\n\t/^(?:to|cc|bcc|from|sender|reply-to|return-path|subject|mime-version|content-.*)$/i;\n\n/** Every recipient of a message, as bare addresses, in order. */\nexport function recipientsOf(message: MailMessage): string[] {\n\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\treturn to.map(addressOf);\n}\n\n/** The bare address of an {@link Address}. */\nexport function addressOf(address: Address): string {\n\treturn typeof address === 'string' ? address : address.address;\n}\n\n/** Refuses `address` unless it is an {@link Address}. `undefined` is refused too. */\nfunction checkAddress(address: Address | undefined, where: string): void {\n\tif (typeof address === 'string') {\n\t\tif (!ADDRESS.test(address)) {\n\t\t\tthrow new MailRefused(`send: ${where} is not an e-mail address`);\n\t\t}\n\t\treturn;\n\t}\n\tif (typeof address !== 'object' || address === null) {\n\t\tthrow new MailRefused(`send: ${where} is not an e-mail address`);\n\t}\n\tif (typeof address.address !== 'string' || !ADDRESS.test(address.address)) {\n\t\tthrow new MailRefused(`send: ${where}.address is not an e-mail address`);\n\t}\n\tif (typeof address.name !== 'string' || LINE_BREAK.test(address.name)) {\n\t\tthrow new MailRefused(\n\t\t\t`send: ${where}.name must be a string without a line break`,\n\t\t);\n\t}\n}\n\n/**\n * Refuses a message no transport should hand over, with a {@link MailRefused}\n * that names **where** the problem is and never the value.\n *\n * A transport calls it first thing in `send`, so the refusals are the same\n * whichever transport is wired. It checks:\n *\n * - at least one recipient, each one an address;\n * - `from` and `replyTo`, when present, are addresses;\n * - `subject`, `html` and `text` are strings, and `subject` holds no line\n *   break — a line break in a subject is a header injection;\n * - every header name is letters, digits and hyphens, none names what the\n *   transport writes from the message (`To`, `Cc`, `Bcc`, `From`, `Sender`,\n *   `Reply-To`, `Return-Path`, `Subject`, `MIME-Version`, `Content-*`, in\n *   any case), and no header value holds a line break.\n */\nexport function checkMessage(message: MailMessage): void {\n\tif (typeof message !== 'object' || message === null) {\n\t\tthrow new MailRefused('send: the message must be an object');\n\t}\n\tif (message.to === undefined || message.to === null) {\n\t\tthrow new MailRefused('send: to must hold at least one address');\n\t}\n\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\tif (to.length === 0) {\n\t\tthrow new MailRefused('send: to must hold at least one address');\n\t}\n\tto.forEach((address, index) => {\n\t\tcheckAddress(address, Array.isArray(message.to) ? `to[${index}]` : 'to');\n\t});\n\tif (message.from !== undefined) checkAddress(message.from, 'from');\n\tif (message.replyTo !== undefined) checkAddress(message.replyTo, 'replyTo');\n\n\tfor (const part of ['subject', 'html', 'text'] as const) {\n\t\tif (typeof message[part] !== 'string') {\n\t\t\tthrow new MailRefused(`send: ${part} must be a string`);\n\t\t}\n\t}\n\tif (LINE_BREAK.test(message.subject)) {\n\t\tthrow new MailRefused('send: subject must not hold a line break');\n\t}\n\n\tfor (const [name, value] of Object.entries(message.headers ?? {})) {\n\t\tif (!HEADER_NAME.test(name)) {\n\t\t\tthrow new MailRefused(\n\t\t\t\t'send: a header name must be letters, digits and hyphens',\n\t\t\t);\n\t\t}\n\t\tif (RESERVED_HEADER.test(name)) {\n\t\t\tthrow new MailRefused(\n\t\t\t\t`send: header ${name} is reserved — addresses, the subject and the MIME structure are never custom headers`,\n\t\t\t);\n\t\t}\n\t\tif (typeof value !== 'string' || LINE_BREAK.test(value)) {\n\t\t\tthrow new MailRefused(\n\t\t\t\t`send: header ${name} must be a string without a line break`,\n\t\t\t);\n\t\t}\n\t}\n}\n",
-    "import { type MailError, MailFailure } from './errors';\nimport { checkMessage } from './message';\nimport type { Mailer, MailMessage, SentMail } from './types';\n\n/** One message the memory mailer accepted, with the id it gave it. */\nexport interface MemoryMail extends MailMessage {\n\treadonly messageId: string;\n}\n\n/**\n * The reference transport: it keeps what it sends in memory, for tests.\n *\n * It refuses exactly what every transport refuses (it calls\n * {@link checkMessage}), and it can be told to fail, so a test can prove what\n * the application does when a send throws.\n */\nexport interface MemoryMailer extends Mailer {\n\t/** Every message accepted so far, oldest first. A copy: mutating it changes nothing. */\n\treadonly sent: readonly MemoryMail[];\n\t/**\n\t * How many sends reached the hand-over, failed ones included. A message\n\t * refused as malformed never reaches it. A caller that retries in secret\n\t * shows up here.\n\t */\n\treadonly attempts: number;\n\t/**\n\t * Makes the next send that reaches the hand-over reject with `error`, by\n\t * default a {@link MailFailure} as an outage would. Calls queue: two calls\n\t * fail the next two sends.\n\t */\n\tfailNext(error?: MailError): void;\n\t/** Forgets what was sent, the attempts, and any queued failure. */\n\tclear(): void;\n}\n\n/** Creates a {@link MemoryMailer}. Message ids are `memory-1`, `memory-2`, … */\nexport function createMemoryMailer(): MemoryMailer {\n\tlet sent: MemoryMail[] = [];\n\tlet failures: MailError[] = [];\n\tlet attempts = 0;\n\tlet counter = 0;\n\n\treturn {\n\t\tget sent() {\n\t\t\treturn sent.map((mail) => structuredClone(mail));\n\t\t},\n\t\tget attempts() {\n\t\t\treturn attempts;\n\t\t},\n\t\tfailNext(error) {\n\t\t\tfailures.push(\n\t\t\t\terror ??\n\t\t\t\t\tnew MailFailure(\n\t\t\t\t\t\t'send: the memory mailer was told to fail this send',\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcause: new Error('memory mailer: failNext'),\n\t\t\t\t\t\t},\n\t\t\t\t\t),\n\t\t\t);\n\t\t},\n\t\tclear() {\n\t\t\tsent = [];\n\t\t\tfailures = [];\n\t\t\tattempts = 0;\n\t\t},\n\t\tasync send(message): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tattempts += 1;\n\t\t\tconst failure = failures.shift();\n\t\t\tif (failure !== undefined) throw failure;\n\n\t\t\tcounter += 1;\n\t\t\tconst messageId = `memory-${counter}`;\n\t\t\tsent.push({ ...structuredClone(message), messageId });\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
-  ],
-  "mappings": ";;;;;;AAGA,IAAM,aAAa;AAMnB,IAAM,UAAU;AAChB,IAAM,cAAc;AAIpB,IAAM,kBACL;AAGM,SAAS,aAAY,CAAC,SAAgC;AAAA,EAC5D,MAAM,KAAK,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE;AAAA,EAC/D,OAAO,GAAG,IAAI,UAAS;AAAA;AAIjB,SAAS,UAAS,CAAC,SAA0B;AAAA,EACnD,OAAO,OAAO,YAAY,WAAW,UAAU,QAAQ;AAAA;AAIxD,SAAS,YAAY,CAAC,SAA8B,OAAqB;AAAA,EACxE,IAAI,OAAO,YAAY,UAAU;AAAA,IAChC,IAAI,CAAC,QAAQ,KAAK,OAAO,GAAG;AAAA,MAC3B,MAAM,IAAI,aAAY,SAAS,gCAAgC;AAAA,IAChE;AAAA,IACA;AAAA,EACD;AAAA,EACA,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AAAA,IACpD,MAAM,IAAI,aAAY,SAAS,gCAAgC;AAAA,EAChE;AAAA,EACA,IAAI,OAAO,QAAQ,YAAY,YAAY,CAAC,QAAQ,KAAK,QAAQ,OAAO,GAAG;AAAA,IAC1E,MAAM,IAAI,aAAY,SAAS,wCAAwC;AAAA,EACxE;AAAA,EACA,IAAI,OAAO,QAAQ,SAAS,YAAY,WAAW,KAAK,QAAQ,IAAI,GAAG;AAAA,IACtE,MAAM,IAAI,aACT,SAAS,kDACV;AAAA,EACD;AAAA;AAmBM,SAAS,aAAY,CAAC,SAA4B;AAAA,EACxD,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AAAA,IACpD,MAAM,IAAI,aAAY,qCAAqC;AAAA,EAC5D;AAAA,EACA,IAAI,QAAQ,OAAO,aAAa,QAAQ,OAAO,MAAM;AAAA,IACpD,MAAM,IAAI,aAAY,yCAAyC;AAAA,EAChE;AAAA,EACA,MAAM,KAAK,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE;AAAA,EAC/D,IAAI,GAAG,WAAW,GAAG;AAAA,IACpB,MAAM,IAAI,aAAY,yCAAyC;AAAA,EAChE;AAAA,EACA,GAAG,QAAQ,CAAC,SAAS,UAAU;AAAA,IAC9B,aAAa,SAAS,MAAM,QAAQ,QAAQ,EAAE,IAAI,MAAM,WAAW,IAAI;AAAA,GACvE;AAAA,EACD,IAAI,QAAQ,SAAS;AAAA,IAAW,aAAa,QAAQ,MAAM,MAAM;AAAA,EACjE,IAAI,QAAQ,YAAY;AAAA,IAAW,aAAa,QAAQ,SAAS,SAAS;AAAA,EAE1E,WAAW,QAAQ,CAAC,WAAW,QAAQ,MAAM,GAAY;AAAA,IACxD,IAAI,OAAO,QAAQ,UAAU,UAAU;AAAA,MACtC,MAAM,IAAI,aAAY,SAAS,uBAAuB;AAAA,IACvD;AAAA,EACD;AAAA,EACA,IAAI,WAAW,KAAK,QAAQ,OAAO,GAAG;AAAA,IACrC,MAAM,IAAI,aAAY,0CAA0C;AAAA,EACjE;AAAA,EAEA,YAAY,MAAM,UAAU,OAAO,QAAQ,QAAQ,WAAW,CAAC,CAAC,GAAG;AAAA,IAClE,IAAI,CAAC,YAAY,KAAK,IAAI,GAAG;AAAA,MAC5B,MAAM,IAAI,aACT,yDACD;AAAA,IACD;AAAA,IACA,IAAI,gBAAgB,KAAK,IAAI,GAAG;AAAA,MAC/B,MAAM,IAAI,aACT,gBAAgB,2FACjB;AAAA,IACD;AAAA,IACA,IAAI,OAAO,UAAU,YAAY,WAAW,KAAK,KAAK,GAAG;AAAA,MACxD,MAAM,IAAI,aACT,gBAAgB,4CACjB;AAAA,IACD;AAAA,EACD;AAAA;;;ACvEM,SAAS,mBAAkB,GAAiB;AAAA,EAClD,IAAI,OAAqB,CAAC;AAAA,EAC1B,IAAI,WAAwB,CAAC;AAAA,EAC7B,IAAI,WAAW;AAAA,EACf,IAAI,UAAU;AAAA,EAEd,OAAO;AAAA,QACF,IAAI,GAAG;AAAA,MACV,OAAO,KAAK,IAAI,CAAC,SAAS,gBAAgB,IAAI,CAAC;AAAA;AAAA,QAE5C,QAAQ,GAAG;AAAA,MACd,OAAO;AAAA;AAAA,IAER,QAAQ,CAAC,OAAO;AAAA,MACf,SAAS,KACR,SACC,IAAI,aACH,sDACA;AAAA,QACC,OAAO,IAAI,MAAM,yBAAyB;AAAA,MAC3C,CACD,CACF;AAAA;AAAA,IAED,KAAK,GAAG;AAAA,MACP,OAAO,CAAC;AAAA,MACR,WAAW,CAAC;AAAA,MACZ,WAAW;AAAA;AAAA,SAEN,KAAI,CAAC,SAA4B;AAAA,MACtC,cAAa,OAAO;AAAA,MACpB,YAAY;AAAA,MACZ,MAAM,UAAU,SAAS,MAAM;AAAA,MAC/B,IAAI,YAAY;AAAA,QAAW,MAAM;AAAA,MAEjC,WAAW;AAAA,MACX,MAAM,YAAY,UAAU;AAAA,MAC5B,KAAK,KAAK,KAAK,gBAAgB,OAAO,GAAG,UAAU,CAAC;AAAA,MACpD,OAAO,EAAE,UAAU;AAAA;AAAA,EAErB;AAAA;",
-  "debugId": "44B7D62837EFA8BB64756E2164756E21",
-  "names": []
-}