@nxgt/mail 0.2.0 → 0.4.0

package/docs/troubleshooting.md

@@ -10,7 +10,8 @@ How the messages are shaped:
   verification e-mail is a credential, and it never reaches a log through an
   error.
 - **Every message starts with the call you wrote**: `send: …`,
-  `createMailRenderer: …`, `render: …`, `pickLocale: …`, `describeMailer: …`.
+  `listUnsubscribe: …`, `createMailRenderer: …`, `render: …`,
+  `pickLocale: …`, `describeMailer: …`.
   A conformance case that fails starts with `conformance: …`.
 - **A `TypeError` is a wiring mistake**: it comes from how the application
   was put together — or, from `render`, from how the call was written —
@@ -64,8 +65,19 @@ How the messages are shaped:
 - [`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)
 
+**Unsubscribe**
+- [`listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma`](#listunsubscribe-url-must-be-an-https-url-in-printable-ascii-without-credentials---quotes-or-a-raw-comma)
+- [`listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com`](#listunsubscribe-mailto-must-be-a-bare-e-mail-address-as-unsubscribeexamplecom)
+- [`listUnsubscribe: options must be an object, as { url }`](#listunsubscribe-options-must-be-an-object-as--url-)
+- [`listUnsubscribe: url must be a string`](#listunsubscribe-url-must-be-a-string)
+- [`listUnsubscribe: mailto must be a string`](#listunsubscribe-mailto-must-be-a-string)
+- [Gmail shows no unsubscribe button](#gmail-shows-no-unsubscribe-button)
+
 **Locale**
 - [`pickLocale: supported must hold at least one locale`](#picklocale-supported-must-hold-at-least-one-locale)
 - [`pickLocale: fallback must be one of supported`](#picklocale-fallback-must-be-one-of-supported)
@@ -495,8 +507,11 @@ whether the e-mail is still worth sending.
 the transport's message when the provider answered that the message is
 malformed or too large.
 **Why:** something in the message would break a header, has no valid
-recipient, or is an attachment that is not bytes or is badly named — or the
-whole message is over the provider's size limit. Sending it again unchanged fails again.
+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)
@@ -756,6 +771,91 @@ const notes: MailAttachment = {
 };
 ```
 
+### `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
@@ -778,6 +878,164 @@ beforeEach(() => mailer.clear());
 
 ---
 
+## Unsubscribe
+
+`listUnsubscribe` checks its options **when it is called**, before any
+`send`. A value that is text but not a usable URL or address is a
+`MailRefused` (`code: 'MAIL_REFUSED'`), and it never quotes the value: the
+URL usually carries a per-recipient token, and a token is a credential. A
+value that is not text at all is a `TypeError`, a mistake in the code.
+
+### `listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma`
+
+A `MailRefused`, `code: 'MAIL_REFUSED'`.
+
+**When:** `listUnsubscribe({ url })`, with a `url` that does not start with
+`https://` (`http:`, `mailto:`, relative, empty, `HTTPS://` in capitals), that
+carries a user or a password (`https://user:pass@…`), or that holds a space,
+a line break, a character outside ASCII, `<`, `>`, a double quote, a backtick, a backslash, a
+brace, `|`, `^` or a `,` as it is: typically a token or a list name pasted
+into a template string without being encoded, or an `http:` URL from a
+development configuration.
+**Why:** RFC 8058 accepts only an `https:` URL for one-click unsubscribe, and
+RFC 2369 an RFC 3986 URI — printable ASCII — between `<` and `>`. A
+transport encodes a header holding anything else, and no client finds the URL
+in it; a `>` would end the URL, and a raw comma is RFC 2369's separator
+between two URLs, so a mail client would read the rest as a second one. A
+user and a password would be read by every relay and recipient.
+**Fix:** build the URL with `new URL()` and set each value with
+`searchParams.set`, which percent-encodes it (`,` becomes `%2C`, a space
+`+`), then pass `.href`:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const url = new URL('https://example.com/unsubscribe');
+url.searchParams.set('token', token);
+
+const headers = listUnsubscribe({ url: url.href });
+```
+
+A value in the path is encoded with `encodeURIComponent` (`/u/${encodeURIComponent(list)}`).
+In development, use an `https:` URL as well, or leave the headers out.
+
+### `listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com`
+
+A `MailRefused`, `code: 'MAIL_REFUSED'`.
+
+**When:** `listUnsubscribe({ url, mailto })`, with a `mailto` that has a
+display name (`Unsubscribe <unsubscribe@example.com>`), a `mailto:` prefix,
+two addresses, no `@`, a domain without a dot, a character outside ASCII,
+or `?`, `&`, `=`, `#`, `%` or a double quote (`u@example.com?subject=stop`).
+**Why:** `mailto` is one mailbox, and `listUnsubscribe` writes the
+`<mailto:…>` around it itself; a name, a prefix or a second address would
+break the header or be read as something else — in a `mailto:`, `?` starts
+header fields, and `?cc=` would add a recipient.
+**Fix:** pass the address alone:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const headers = listUnsubscribe({
+  url: `https://example.com/unsubscribe?token=${encodeURIComponent(token)}`,
+  mailto: 'unsubscribe@example.com', // ✗ 'mailto:unsubscribe@example.com'
+});
+```
+
+### `listUnsubscribe: options must be an object, as { url }`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe()` with no argument, or with the URL alone:
+typically `listUnsubscribe(url)`.
+**Why:** the options are one object, and `url` is required in it.
+**Fix:** `listUnsubscribe({ url })`.
+
+### `listUnsubscribe: url must be a string`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe({ url })`, with a `url` that is a `URL` object,
+`undefined` or anything else that is not text — from untyped code, since
+TypeScript already refuses a `URL` object (`Type 'URL' is not assignable to
+type 'string'`).
+**Why:** the header holds text; the helper does not guess how to turn a
+value into a URL.
+**Fix:** pass the URL's text:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+const url = new URL('https://example.com/unsubscribe');
+
+const headers = listUnsubscribe({ url: url.href }); // ✗ { url }
+```
+
+### `listUnsubscribe: mailto must be a string`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe({ url, mailto })`, with a `mailto` that is set
+but is not a string — `null`, or an `{ name, address }` object.
+**Why:** `mailto` is one bare address, as text; leave it out for none.
+**Fix:** `mailto: 'unsubscribe@example.com'`, or no `mailto` at all.
+
+### Gmail shows no unsubscribe button
+
+**When:** the message carries both headers from `listUnsubscribe`, yet
+Gmail (or Yahoo) shows no "Unsubscribe" link next to the sender.
+**Why:** the headers make the button possible; the mailbox provider decides
+whether to show it. The usual causes:
+
+- **The sender is not a bulk sender, or its reputation is low.** Gmail shows
+  the button to senders it recognises as sending bulk mail with a good
+  reputation; a new domain, or a handful of test messages, may never get it.
+- **The message is not DKIM-signed by the sending domain**, or the signature
+  does not cover the two headers. RFC 8058 requires a valid DKIM signature
+  whose `h=` includes `List-Unsubscribe` and `List-Unsubscribe-Post`, and
+  Gmail and Yahoo also want it aligned with the `From` domain. Check the received message's original: the
+  `DKIM-Signature` must have `d=` your domain and name both headers.
+- **The endpoint does not unsubscribe on the POST alone.** The client POSTs
+  `List-Unsubscribe=One-Click` to the URL, with no cookie and no session. An
+  answer that is a redirect, a login page, a confirmation page, or an error
+  for a `POST` (a route that only answers `GET`) is a failed unsubscribe.
+- **The e-mail is transactional** — a sign-in code, a password reset, a
+  receipt. Gmail does not offer to unsubscribe from those, and they should
+  not carry the headers: nobody unsubscribes from their own password reset.
+
+**Fix:** set the headers only on e-mails a recipient subscribed to, send
+from a domain that signs with DKIM, and make the URL unsubscribe on the
+`POST` itself:
+
+```ts
+declare function unsubscribeByToken(token: string): Promise<void>; // yours
+
+// POST https://example.com/unsubscribe?token=…, body List-Unsubscribe=One-Click
+async function unsubscribe(request: Request): Promise<Response> {
+  const token = new URL(request.url).searchParams.get('token') ?? '';
+  if (request.method === 'POST') {
+    const form = await request.formData();
+    if (form.get('List-Unsubscribe') !== 'One-Click') return new Response(null, { status: 400 });
+    await unsubscribeByToken(token); // no login, no confirmation
+    return new Response(null, { status: 200 }); // never a redirect
+  }
+  // GET: a person followed the link. Show a page that posts the same form.
+  return new Response(
+    '<form method="post"><input type="hidden" name="List-Unsubscribe" value="One-Click"><button>Unsubscribe</button></form>',
+    { headers: { 'content-type': 'text/html; charset=utf-8' } },
+  );
+}
+```
+
+The full handler, with what the `GET` page may show, is in
+[the sending guide](guide/sending.md#one-click-unsubscribe).
+
+---
+
 ## Locale
 
 ### `pickLocale: supported must hold at least one locale`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail",
-	"version": "0.2.0",
+	"version": "0.4.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-4h39j3n7.js.map

@@ -1,11 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/message.ts", "../src/memory.ts"],
-  "sourcesContent": [
-    "import { MailRefused } from './errors';\nimport type { Address, MailAttachment, 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// A file name is shown and saved by the recipient's mail client: no path\n// separator and no `.` or `..` (a client that saves it as is writes\n// elsewhere), no line break or other control character, C1 included (a header\n// could be split on one), and no format character — a right-to-left override\n// disguises `fdp.exe` as `exe.pdf`.\nconst FILENAME_REFUSED = /[/\\\\\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}]/u;\nconst DOT_NAME = /^\\.\\.?$/;\n// RFC 2045: type \"/\" subtype, each a token — any printable ASCII but space\n// and the tspecials ()<>@,;:\\\"/[]?=. No parameters: a charset or a name\n// there would be a second, unchecked place to write the file's name.\nconst CONTENT_TYPE =\n\t/^[!#$%&'*+.^_`{|}~0-9A-Za-z-]+\\/[!#$%&'*+.^_`{|}~0-9A-Za-z-]+$/;\n// multipart/* and message/* are MIME containers, not files: nodemailer writes\n// them unencoded, and the receiving end reads back no attachment at all.\nconst CONTAINER_TYPE = /^(?:multipart|message)\\//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/** Refuses `attachment` unless it is a {@link MailAttachment}. */\nfunction checkAttachment(attachment: MailAttachment, where: string): void {\n\tif (typeof attachment !== 'object' || attachment === null) {\n\t\tthrow new MailRefused(\n\t\t\t`send: ${where} must be an object, as { filename, content, contentType }`,\n\t\t);\n\t}\n\tif (!(attachment.content instanceof Uint8Array)) {\n\t\tthrow new MailRefused(\n\t\t\t`send: ${where}.content must be a Uint8Array — the file's bytes, never a path or a URL`,\n\t\t);\n\t}\n\tif (\n\t\ttypeof attachment.filename !== 'string' ||\n\t\tattachment.filename === '' ||\n\t\tDOT_NAME.test(attachment.filename) ||\n\t\tFILENAME_REFUSED.test(attachment.filename)\n\t) {\n\t\tthrow new MailRefused(\n\t\t\t`send: ${where}.filename must be a file name — not empty, not . or .., without / or \\\\, a line break or a control character`,\n\t\t);\n\t}\n\tif (\n\t\ttypeof attachment.contentType !== 'string' ||\n\t\t!CONTENT_TYPE.test(attachment.contentType) ||\n\t\tCONTAINER_TYPE.test(attachment.contentType)\n\t) {\n\t\tthrow new MailRefused(\n\t\t\t`send: ${where}.contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*`,\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 * - `attachments`, when present, is an array without holes — empty is the\n *   same as absent — and each entry has its bytes as a `Uint8Array`, a\n *   `filename` that is not empty, `.` or `..` and holds no `/`, `\\`, line\n *   break, control or format character, and a `contentType` that is a bare\n *   `type/subtype`, never `multipart/*` or `message/*`.\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\tif (message.attachments !== undefined) {\n\t\tif (!Array.isArray(message.attachments)) {\n\t\t\tthrow new MailRefused('send: attachments must be an array');\n\t\t}\n\t\t// Indexed, not forEach: a hole in the array is refused, not skipped.\n\t\tfor (let index = 0; index < message.attachments.length; index++) {\n\t\t\tcheckAttachment(message.attachments[index], `attachments[${index}]`);\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/**\n * A copy of `message` the caller cannot change afterwards. Each attachment's\n * bytes are copied to a plain `Uint8Array` of their own: a `Buffer` from\n * Node's pool is a view on a larger, shared buffer, which a clone would copy\n * whole.\n */\nfunction copyOf(message: MailMessage): MailMessage {\n\tconst { attachments, ...rest } = message;\n\tconst copy = structuredClone(rest);\n\tif (attachments === undefined) return copy;\n\treturn {\n\t\t...copy,\n\t\tattachments: attachments.map((attachment) => ({\n\t\t\tfilename: attachment.filename,\n\t\t\tcontent: new Uint8Array(attachment.content),\n\t\t\tcontentType: attachment.contentType,\n\t\t})),\n\t};\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({ ...copyOf(message), messageId });\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
-  ],
-  "mappings": "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",
-  "debugId": "49A96A07CA93F79964756E2164756E21",
-  "names": []
-}