@nxgt/mail 0.2.0 → 0.3.0

package/README.md

@@ -154,6 +154,45 @@ larger on the way.
 Inline images (`cid:`) are not supported yet. See
 [Sending — attachments](docs/guide/sending.md#attachments).
 
+### Idempotency — a retry that delivers once
+
+`idempotencyKey` names a send, so sending it again — a retry after a timeout,
+a job run twice — delivers it once where the transport can deduplicate.
+Derive it from what the e-mail is about, never from the time or a random
+value. The memory mailer honours it, so a test can prove a retry is safe:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer } from '@nxgt/mail';
+
+it('sends one receipt, however often the job runs', async () => {
+	const mailer = createMemoryMailer();
+	const receipt = {
+		to: 'ada@example.com',
+		subject: 'Your receipt',
+		html: '<p>Thank you for your order.</p>',
+		text: 'Thank you for your order.',
+		idempotencyKey: 'order-42/receipt', // 1 to 256 visible ASCII characters
+	};
+
+	const first = await mailer.send(receipt);
+	const again = await mailer.send(receipt); // the retry
+
+	expect(again).toEqual(first); // { messageId: 'memory-1' }
+	expect(mailer.sent).toHaveLength(1); // delivered once
+	expect(mailer.attempts).toBe(2);
+});
+```
+
+A different message under a key already delivered is refused with
+`MailRefused` — a key names one e-mail — and a failed send leaves its key
+free, so its retry delivers. `@nxgt/mail-resend`
+sends the key as Resend's `Idempotency-Key`, which Resend keeps for 24 hours;
+`@nxgt/mail-smtp` ignores it — SMTP has no such mechanism, and a message sent
+twice is delivered twice. A key that is not 1 to 256 visible ASCII characters
+is refused with `MailRefused`. See
+[Sending — idempotency](docs/guide/sending.md#idempotency--sending-once).
+
 ### Errors — switch on `code`
 
 Both errors extend `MailError`, whose `code` is a union a `switch` exhausts.
@@ -251,13 +290,19 @@ export function createHttpMailer(endpoint: string, apiKey: string): Mailer {
 	return {
 		async send(message) {
 			checkMessage(message); // MailRefused, naming where, never the value
+			const { idempotencyKey, ...fields } = message; // names the send: never in the body
 			const attachments = message.attachments?.length
 				? message.attachments.map((file) => ({ ...file, content: base64Of(file.content) }))
 				: undefined; // an empty list is none
 			const response = await fetch(endpoint, {
 				method: 'POST',
-				headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
-				body: JSON.stringify({ ...message, to: recipientsOf(message), attachments }),
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					'content-type': 'application/json',
+					// if the provider deduplicates; a transport whose provider cannot ignores the key
+					...(idempotencyKey === undefined ? {} : { 'idempotency-key': idempotencyKey }),
+				},
+				body: JSON.stringify({ ...fields, to: recipientsOf(message), attachments }),
 			}).catch((cause: unknown) => {
 				throw new MailFailure('send: the provider could not be reached', { cause });
 			});
@@ -334,6 +379,10 @@ a recipient no check saw: `checkMessage` refuses `To`, `Cc`, `Bcc`, `From`,
 again unchanged. Nothing in this package retries a `MAIL_FAILED`: a retry is
 your decision, made where you can see it.
 
+**An idempotency key from the clock or a random value protects nothing.**
+``idempotencyKey: `receipt-${Date.now()}` `` gives the retry a new key, and
+the e-mail goes out twice; write ``idempotencyKey: `order-${order.id}/receipt` ``.
+
 **The locale is the recipient's, not the request's.** An administrator who
 invites a user sends the invitation in the *user's* locale:
 `pickLocale(invitee.locale, supported, fallback)`.
@@ -347,7 +396,7 @@ gives a test file `describe` and `it` as bare identifiers, not on `globalThis`.
 
 ## Type safety, counted
 
-**21 plausible mistakes, 21 refused** at compile time, each measured by a
+**22 plausible mistakes, 22 refused** at compile time, each measured by a
 `@ts-expect-error` in
 [`test/types/refusals.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/test/types/refusals.ts)
 that fails the typecheck the moment it stops holding:
@@ -384,6 +433,11 @@ And an attachment:
 20. No `contentType`: nothing guesses it from the file name.
 21. One attachment, not in a list.
 
+And the idempotency key:
+
+22. A number (`idempotencyKey: order.id`): the key is a string, as
+    `order-42/receipt`.
+
 The same file holds the calls that must keep compiling: a refusal that refuses
 the correct call is a bug.
 

package/dist/chunks/{index-4h39j3n7.js → index-nkzwt8vn.js}

@@ -12,6 +12,7 @@ var FILENAME_REFUSED = /[/\\\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
 var DOT_NAME = /^\.\.?$/;
 var CONTENT_TYPE = /^[!#$%&'*+.^_`{|}~0-9A-Za-z-]+\/[!#$%&'*+.^_`{|}~0-9A-Za-z-]+$/;
 var CONTAINER_TYPE = /^(?:multipart|message)\//i;
+var IDEMPOTENCY_KEY = /^[\x21-\x7E]{1,256}$/;
 function recipientsOf2(message) {
   const to = Array.isArray(message.to) ? message.to : [message.to];
   return to.map(addressOf2);
@@ -95,6 +96,9 @@ function checkMessage2(message) {
       checkAttachment(message.attachments[index], `attachments[${index}]`);
     }
   }
+  if (message.idempotencyKey !== undefined && (typeof message.idempotencyKey !== "string" || !IDEMPOTENCY_KEY.test(message.idempotencyKey))) {
+    throw new MailRefused2("send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt");
+  }
 }
 
 // src/memory.ts
@@ -112,11 +116,32 @@ function copyOf(message) {
     }))
   };
 }
+var hexOf = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+function fingerprintOf(message) {
+  const address = (value) => typeof value === "object" ? [value.name, value.address] : value;
+  const to = Array.isArray(message.to) ? message.to : [message.to];
+  const headers = Object.entries(message.headers ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return JSON.stringify([
+    to.map(address),
+    address(message.from),
+    address(message.replyTo),
+    message.subject,
+    message.html,
+    message.text,
+    headers,
+    (message.attachments ?? []).map((file) => [
+      file.filename,
+      file.contentType,
+      hexOf(file.content)
+    ])
+  ]);
+}
 function createMemoryMailer2() {
   let sent = [];
   let failures = [];
   let attempts = 0;
   let counter = 0;
+  let keys = new Map;
   return {
     get sent() {
       return sent.map((mail) => structuredClone(mail));
@@ -133,6 +158,7 @@ function createMemoryMailer2() {
       sent = [];
       failures = [];
       attempts = 0;
+      keys = new Map;
     },
     async send(message) {
       checkMessage2(message);
@@ -140,9 +166,20 @@ function createMemoryMailer2() {
       const failure = failures.shift();
       if (failure !== undefined)
         throw failure;
+      const key = message.idempotencyKey;
+      const fingerprint = key === undefined ? "" : fingerprintOf(message);
+      const delivered = key === undefined ? undefined : keys.get(key);
+      if (delivered !== undefined) {
+        if (delivered.fingerprint !== fingerprint) {
+          throw new MailRefused2("send: idempotencyKey was already used for a different message — a key names one e-mail");
+        }
+        return { messageId: delivered.messageId };
+      }
       counter += 1;
       const messageId = `memory-${counter}`;
       sent.push({ ...copyOf(message), messageId });
+      if (key !== undefined)
+        keys.set(key, { messageId, fingerprint });
       return { messageId };
     }
   };
@@ -150,5 +187,5 @@ function createMemoryMailer2() {
 
 export { recipientsOf2, addressOf2, checkMessage2, createMemoryMailer2 };
 
-//# debugId=49A96A07CA93F79964756E2164756E21
-//# sourceMappingURL=index-4h39j3n7.js.map
+//# debugId=1A74D07F2680AEF664756E2164756E21
+//# sourceMappingURL=index-nkzwt8vn.js.map

package/dist/chunks/index-nkzwt8vn.js.map

@@ -0,0 +1,11 @@
+{
+  "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// Written into a header by the transports that use it (Resend's\n// `Idempotency-Key`): visible ASCII only, so no line break, and Resend's length.\nconst IDEMPOTENCY_KEY = /^[\\x21-\\x7E]{1,256}$/;\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 * - `idempotencyKey`, when present, is 1 to 256 visible ASCII characters.\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\tif (\n\t\tmessage.idempotencyKey !== undefined &&\n\t\t(typeof message.idempotencyKey !== 'string' ||\n\t\t\t!IDEMPOTENCY_KEY.test(message.idempotencyKey))\n\t) {\n\t\tthrow new MailRefused(\n\t\t\t'send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt',\n\t\t);\n\t}\n}\n",
+    "import { type MailError, MailFailure, MailRefused } from './errors';\nimport { checkMessage } from './message';\nimport type { Address, 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 *\n * It honours `idempotencyKey`, as Resend does: the same message again under a\n * key it already delivered resolves with that delivery's `messageId`, and is\n * not delivered again; a different message under that key is a\n * {@link MailRefused}. A send that failed delivered nothing, so its key stays\n * free.\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, any queued failure, and the idempotency keys. */\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/** Bytes as hex: short to compare, whatever holds them. */\nconst hexOf = (bytes: Uint8Array) =>\n\tArray.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');\n\n/**\n * What makes two messages the same one, for an idempotency key: the fields of\n * the port, read by name as `checkMessage` reads them — so a field on a\n * prototype counts and a field the port does not know does not — in one\n * form, however the object was written: `to` as one address or a list of\n * one, no `headers` or `attachments` or an empty one, headers in any order,\n * bytes in a `Buffer` or a plain `Uint8Array`.\n */\nfunction fingerprintOf(message: MailMessage): string {\n\tconst address = (value: Address | undefined) =>\n\t\ttypeof value === 'object' ? [value.name, value.address] : value;\n\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\tconst headers = Object.entries(message.headers ?? {}).sort(([a], [b]) =>\n\t\ta < b ? -1 : a > b ? 1 : 0,\n\t);\n\treturn JSON.stringify([\n\t\tto.map(address),\n\t\taddress(message.from),\n\t\taddress(message.replyTo),\n\t\tmessage.subject,\n\t\tmessage.html,\n\t\tmessage.text,\n\t\theaders,\n\t\t(message.attachments ?? []).map((file) => [\n\t\t\tfile.filename,\n\t\t\tfile.contentType,\n\t\t\thexOf(file.content),\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\tlet keys = new Map<string, { messageId: string; fingerprint: string }>();\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\tkeys = new Map();\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\tconst key = message.idempotencyKey;\n\t\t\tconst fingerprint = key === undefined ? '' : fingerprintOf(message);\n\t\t\tconst delivered = key === undefined ? undefined : keys.get(key);\n\t\t\tif (delivered !== undefined) {\n\t\t\t\tif (delivered.fingerprint !== fingerprint) {\n\t\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t\t'send: idempotencyKey was already used for a different message — a key names one e-mail',\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn { messageId: delivered.messageId };\n\t\t\t}\n\n\t\t\tcounter += 1;\n\t\t\tconst messageId = `memory-${counter}`;\n\t\t\tsent.push({ ...copyOf(message), messageId });\n\t\t\tif (key !== undefined) keys.set(key, { messageId, fingerprint });\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "1A74D07F2680AEF664756E2164756E21",
+  "names": []
+}

package/dist/conformance/index.js

@@ -1,7 +1,7 @@
 import {
   recipientsOf2,
   createMemoryMailer2
-} from "../chunks/index-4h39j3n7.js";
+} from "../chunks/index-nkzwt8vn.js";
 import {
   MailError2,
   MailFailure2,

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   addressOf2,
   checkMessage2,
   createMemoryMailer2
-} from "./chunks/index-4h39j3n7.js";
+} from "./chunks/index-nkzwt8vn.js";
 import {
   MailError2,
   MailFailure2,

package/dist/memory.d.ts

@@ -10,6 +10,12 @@ export interface MemoryMail extends MailMessage {
  * It refuses exactly what every transport refuses (it calls
  * {@link checkMessage}), and it can be told to fail, so a test can prove what
  * the application does when a send throws.
+ *
+ * It honours `idempotencyKey`, as Resend does: the same message again under a
+ * key it already delivered resolves with that delivery's `messageId`, and is
+ * not delivered again; a different message under that key is a
+ * {@link MailRefused}. A send that failed delivered nothing, so its key stays
+ * free.
  */
 export interface MemoryMailer extends Mailer {
     /** Every message accepted so far, oldest first. A copy: mutating it changes nothing. */
@@ -26,7 +32,7 @@ export interface MemoryMailer extends Mailer {
      * fail the next two sends.
      */
     failNext(error?: MailError): void;
-    /** Forgets what was sent, the attempts, and any queued failure. */
+    /** Forgets what was sent, the attempts, any queued failure, and the idempotency keys. */
     clear(): void;
 }
 /** Creates a {@link MemoryMailer}. Message ids are `memory-1`, `memory-2`, … */

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,UAAU,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAY,MAAM,SAAS,CAAC;AAE7D,sEAAsE;AACtE,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAC;CACd;AAsBD,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,YAAY,CAyCjD"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA4B,MAAM,UAAU,CAAC;AAEpE,OAAO,KAAK,EAAW,MAAM,EAAE,WAAW,EAAY,MAAM,SAAS,CAAC;AAEtE,sEAAsE;AACtE,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACd;AAyDD,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,YAAY,CAwDjD"}

package/dist/message.d.ts

@@ -22,7 +22,8 @@ export declare function addressOf(address: Address): string;
  *   same as absent — and each entry has its bytes as a `Uint8Array`, a
  *   `filename` that is not empty, `.` or `..` and holds no `/`, `\`, line
  *   break, control or format character, and a `contentType` that is a bare
- *   `type/subtype`, never `multipart/*` or `message/*`.
+ *   `type/subtype`, never `multipart/*` or `message/*`;
+ * - `idempotencyKey`, when present, is 1 to 256 visible ASCII characters.
  */
 export declare function checkMessage(message: MailMessage): void;
 //# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAgCpE,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAG3D;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAElD;AAwDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAqDvD"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAmCpE,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAG3D;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAElD;AAwDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA+DvD"}

package/dist/types.d.ts

@@ -62,6 +62,19 @@ export interface MailMessage extends Rendered {
      * Each is bytes, checked by `checkMessage`: see {@link MailAttachment}.
      */
     readonly attachments?: readonly MailAttachment[];
+    /**
+     * Names this send, so sending it again — a retry after a timeout, a job run
+     * twice — delivers it once. 1 to 256 visible ASCII characters, as
+     * `order-42/receipt`; derive it from what the e-mail is about, never from
+     * the time or a random value, or a retry carries a new one.
+     *
+     * **A transport that can deduplicate uses it; one that cannot ignores it.**
+     * Resend keeps a key for 24 hours; SMTP has no such thing, and ignores it.
+     * The memory mailer answers the same message under a key it already
+     * delivered with the same `messageId`, and delivers nothing more; a
+     * different message under that key is a `MailRefused`, as Resend's `409`.
+     */
+    readonly idempotencyKey?: string;
 }
 /** 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;;;;;;;;;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"}
+{"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;IACjD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;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,9 +8,9 @@ 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, 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 |
+| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, attachments, the idempotency key, 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, a retry under an idempotency key |
 | [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 |
+| [Writing a transport](guide/transports.md) | You are implementing the `Mailer` port for a provider — the idempotency key included — and running `@nxgt/mail/conformance` against it |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
 | [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/sending.md

@@ -1,8 +1,8 @@
 # Sending
 
 This page is for calling `mailer.send`: the shape of what it takes, the
-addresses, headers and attachments it accepts, what it answers, and what it
-throws.
+addresses, headers and attachments it accepts, the idempotency key that makes
+a retry safe, what it answers, and what it throws.
 
 ```ts
 import { createMemoryMailer } from '@nxgt/mail';
@@ -75,6 +75,7 @@ interface MailMessage extends Rendered {
 	readonly replyTo?: Address;
 	readonly headers?: Readonly<Record<string, string>>;
 	readonly attachments?: readonly MailAttachment[];
+	readonly idempotencyKey?: string;
 }
 
 interface MailAttachment {
@@ -94,6 +95,7 @@ interface MailAttachment {
 | `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 |
+| `idempotencyKey` | `string` | no | Names this send, so sending it again delivers it once where the transport can deduplicate — see [Idempotency](#idempotency--sending-once). 1 to 256 visible ASCII characters |
 
 `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
@@ -302,6 +304,91 @@ 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.
 
+## Idempotency — sending once
+
+A send that fails with `MailFailure` may still have reached the provider: a
+timeout, a dropped connection. Retrying it can deliver the e-mail twice.
+`idempotencyKey` names the send, so a transport that can deduplicate delivers
+it once however often it is sent:
+
+```ts
+import type { Mailer, Rendered } from '@nxgt/mail';
+
+export async function sendReceipt(mailer: Mailer, order: { id: string; email: string }, rendered: Rendered): Promise<void> {
+	await mailer.send({
+		...rendered,
+		to: order.email,
+		idempotencyKey: `order-${order.id}/receipt`, // the same for every retry of this receipt
+	});
+}
+```
+
+**Derive the key from what the e-mail is about** — an order id, a user id
+and a purpose (`user-7/welcome`, `invitation-19`) — **never from the time or
+a random value**: a retry would carry a new key, and deliver again. **A key
+names one e-mail**: two different e-mails about the same thing need two keys
+(`order-42/receipt`, `order-42/shipped`) — a transport that deduplicates
+refuses a different message under a key it already delivered.
+
+```ts
+declare const order: { id: string };
+declare const userId: string;
+declare const resetRequestId: string;
+
+const receipt = `order-${order.id}/receipt`; // one receipt per order
+const welcome = `user-${userId}/welcome`; // one welcome per user
+const reset = `password-reset/${resetRequestId}`; // per request, not per user: a second request is a second e-mail
+
+const wrong = `receipt-${Date.now()}`; // a retry gets a new key, and delivers again
+const wrongToo = crypto.randomUUID(); // the same
+```
+
+**What each transport does with it:**
+
+| Transport | Effect |
+| --- | --- |
+| `createMemoryMailer()` | The same message under a key it already delivered answers that delivery's `messageId`, and delivers nothing more; a different message under that key is a `MailRefused`. A send that failed leaves its key free. See [Testing — idempotency](testing.md#idempotencykey--a-retry-delivers-once) |
+| `@nxgt/mail-resend` | Sent as Resend's `Idempotency-Key` header. Resend keeps a key for 24 hours: a retry within them answers the first send's id and delivers nothing more; the same key with a different message is refused (`MailRefused`) |
+| `@nxgt/mail-smtp` | Ignored: SMTP has no such mechanism, so a message sent twice is delivered twice |
+
+A transport that cannot deduplicate ignores the key; it never refuses the
+message for carrying one. So a key is always safe to set, and only makes a
+retry safe where the transport honours it. It is never written into the
+e-mail itself.
+
+`checkMessage` refuses a key that is not 1 to 256 visible ASCII characters —
+empty, too long, holding a space, a line break or an accented letter, or not
+a string — without quoting it:
+
+| Written | Answer |
+| --- | --- |
+| `'order-42/receipt'`, `'a:b_c.d~e'`, `'k'.repeat(256)` | accepted |
+| `''`, `'k'.repeat(257)`, `'order 42'`, `'commande-42-reçu'`, `'order-42\r\nX-Evil: 1'`, `42` | `MailRefused`: `send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt` |
+
+A transport that deduplicates also refuses **a different message** under a
+key it already delivered, with `MailRefused` — the memory mailer with
+`send: idempotencyKey was already used for a different message — a key names one e-mail`,
+Resend's transport with `send: Resend refused the message` on its `409`.
+Sending it again fails again: give that e-mail its own key.
+
+A retry from a queue, with the key the job carries:
+
+```ts
+import { MailFailure, type Mailer, type MailMessage } from '@nxgt/mail';
+
+// Yours: the queue that runs a job again later.
+declare function retryLater(job: { message: MailMessage }, delaySeconds: number): Promise<void>;
+
+export async function runSendJob(mailer: Mailer, job: { message: MailMessage }): Promise<void> {
+	try {
+		await mailer.send(job.message); // job.message.idempotencyKey was set when the job was queued
+	} catch (error) {
+		if (error instanceof MailFailure) return retryLater(job, 60); // the same key: delivered once, where the transport deduplicates
+		throw error; // MailRefused: sending it again fails again
+	}
+}
+```
+
 ## Errors
 
 ```ts
@@ -325,8 +412,8 @@ 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, 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 |
+| `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 — with an [`idempotencyKey`](#idempotency--sending-once), without a second delivery where the transport deduplicates. 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, an attachment that is not bytes or is badly named, a malformed idempotency key or one already used for a different message, 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

@@ -143,18 +143,105 @@ await mailer
 mailer.attempts; // 0 — and the failure is still queued for the next well-formed send
 ```
 
+## `idempotencyKey` — a retry delivers once
+
+The memory mailer honours a message's
+[`idempotencyKey`](sending.md#idempotency--sending-once) as Resend does:
+
+- the **same message** under a key it already delivered answers that
+  delivery's `messageId`, and nothing more reaches `sent`;
+- a **different message** under that key — another subject, another
+  recipient, other attachment bytes, any field — is refused with
+  `MailRefused`: `send: idempotencyKey was already used for a different message — a key names one e-mail`,
+  as Resend answers `409 invalid_idempotent_request`;
+- a send that **failed** delivered nothing, so its key stays free, and the
+  retry delivers;
+- each send still counts in `attempts`, the answered duplicate and the
+  refused reuse included: both reached the hand-over;
+- `clear()` forgets the keys.
+
+A test proving that a job run twice e-mails once:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer, type Mailer, MailRefused } from '@nxgt/mail';
+
+// The code under test: a job that may run more than once for the same order.
+async function sendReceipt(mailer: Mailer, orderId: string): Promise<string | null> {
+	const { messageId } = await mailer.send({
+		to: 'ada@example.com',
+		subject: 'Your receipt',
+		html: '<p>Thank you for your order.</p>',
+		text: 'Thank you for your order.',
+		idempotencyKey: `order-${orderId}/receipt`,
+	});
+	return messageId;
+}
+
+it('sends one receipt, however often the job runs', async () => {
+	const mailer = createMemoryMailer();
+
+	const first = await sendReceipt(mailer, '42');
+	const again = await sendReceipt(mailer, '42');
+
+	expect(again).toBe(first); // 'memory-1', both times
+	expect(mailer.sent).toHaveLength(1);
+	expect(mailer.attempts).toBe(2);
+});
+
+it('refuses another e-mail under the same key', async () => {
+	const mailer = createMemoryMailer();
+	await sendReceipt(mailer, '42');
+
+	const error = await mailer
+		.send({
+			to: 'ada@example.com',
+			subject: 'Your order has shipped', // another e-mail, the receipt's key
+			html: '<p>Your order has shipped.</p>',
+			text: 'Your order has shipped.',
+			idempotencyKey: 'order-42/receipt',
+		})
+		.then(() => null, (e: unknown) => e);
+
+	expect(error).toBeInstanceOf(MailRefused); // give it its own key: order-42/shipped
+	expect(mailer.sent).toHaveLength(1);
+});
+
+it('delivers the retry of a send that failed', async () => {
+	const mailer = createMemoryMailer();
+	mailer.failNext();
+
+	await sendReceipt(mailer, '42').then(() => null, (e: unknown) => e); // MailFailure
+	await sendReceipt(mailer, '42');
+
+	expect(mailer.sent).toHaveLength(1);
+	expect(mailer.sent[0]?.idempotencyKey).toBe('order-42/receipt');
+});
+```
+
+"The same message" is what it would deliver: every field of `MailMessage`,
+read by name, the attachments by their bytes. How the object was written
+does not count — the order of its fields or of its headers, `to` as one
+address or a list of one, no `headers` or `attachments` or an empty one,
+the bytes in a `Buffer` or a plain `Uint8Array` — and neither does a field
+`MailMessage` does not have. SMTP ignores
+the key altogether, so this is the behaviour of a deduplicating transport,
+not of every one. A queued `failNext` fails the next send even when its key
+was already delivered.
+
 ## `clear()`
 
-Forgets the outbox, the attempts, and any queued failure. The id counter keeps
-going, so an id is never reused within one mailer.
+Forgets the outbox, the attempts, any queued failure, and the idempotency
+keys. 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, 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
+missing part, an attachment that is not bytes or whose file name or type is
+malformed, or an idempotency key that is not 1 to 256 visible ASCII
+characters. 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) and
 [Sending — attachments](sending.md#attachments).

package/docs/guide/transports.md

@@ -54,9 +54,12 @@ A transport:
    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
+7. **uses `idempotencyKey` if the provider deduplicates, and ignores it
+   otherwise** — see [The idempotency key](#the-idempotency-key). It never
+   refuses a message for carrying one, and never writes it into the e-mail;
+8. **never retries in secret**, never resolves `false`, never logs and
    resolves;
-8. **defines no error class of its own**. It throws the classes imported from
+9. **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:
@@ -64,14 +67,15 @@ A transport:
 ```json
 {
 	"peerDependencies": {
-		"@nxgt/mail": "^0.2.0"
+		"@nxgt/mail": "^0.3.0"
 	}
 }
 ```
 
-On `0.x`, a caret covers one minor: `^0.2.0` is `>=0.2.0 <0.3.0`. Declare the
+On `0.x`, a caret covers one minor: `^0.3.0` is `>=0.3.0 <0.4.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.
+`attachments`, `0.3` the one with `idempotencyKey` — 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
@@ -105,9 +109,12 @@ Throws `MailRefused`, naming **where** the problem is and never the value:
 | 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 `idempotencyKey` that is not 1 to 256 visible ASCII characters — empty, a space, a line break, a letter outside ASCII, not a string | `send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt` |
 
 An empty `attachments` is accepted, and is the same as none: send no
-attachment field to the provider then.
+attachment field to the provider then. A key that passes is safe to write in
+an HTTP header as it is: no line break, no character a header would need to
+encode.
 
 Two helpers turn addresses into what a provider wants:
 
@@ -153,6 +160,8 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 	return {
 		async send(message) {
 			checkMessage(message);
+			// The key names the send; it is not part of the e-mail, so it stays out of the body.
+			const { idempotencyKey, ...fields } = 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
@@ -167,8 +176,13 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 			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, attachments }),
+					headers: {
+						authorization: `Bearer ${options.apiKey}`,
+						'content-type': 'application/json',
+						// This provider deduplicates on a header; with one that does not, leave the key out.
+						...(idempotencyKey === undefined ? {} : { 'idempotency-key': idempotencyKey }),
+					},
+					body: JSON.stringify({ ...fields, from: message.from ?? options.from, attachments }),
 				});
 			} catch (cause) {
 				throw new MailFailure('send: the provider could not be reached', { cause });
@@ -190,6 +204,51 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 }
 ```
 
+## The idempotency key
+
+`idempotencyKey` names a send, so that sending the same message again — a
+retry after a timeout, a job run twice — delivers it once. What a transport
+does with it depends on its provider:
+
+| The provider | The transport |
+| --- | --- |
+| deduplicates requests on a key — an `Idempotency-Key` header, a field of its API | passes the key there, as it is. A repeated key answers the first send's id: resolve with it, as for any hand-over. Map the provider's answers: a key reused for a **different** message is a `MailRefused` (sending it again fails again); a key whose first send is **still in progress** is a `MailFailure` (a later retry may work) |
+| has no such mechanism — SMTP, most relays | ignores the key. It does not refuse the message, and does not emulate deduplication with state of its own: a cache in one process is not what the caller was promised |
+
+Either way, **never put the key in the e-mail** — not in the body, not as a
+header the recipient receives. It names the send, not the message, and it is
+derived from what the e-mail is about (`order-42/receipt`): a caller did not
+choose to show it. `@nxgt/mail-resend` sends it as Resend's `Idempotency-Key`;
+`@nxgt/mail-smtp` ignores it.
+
+Document which one yours does, and for how long the provider remembers a key:
+past that window, a retry delivers again.
+
+The conformance suite has no case for it — a transport that ignores the key
+is as correct as one that honours it. Test it in your own specs: the key
+reaches the provider where it should, and nowhere else.
+
+```ts
+import { expect, test } from 'bun:test';
+import { sampleMessage } from '@nxgt/mail/conformance';
+import { createHttpMailer } from './http-mailer';
+
+test('sends the idempotency key as a header, never in the body', async () => {
+	const requests: { headers: Headers; body: Record<string, unknown> }[] = [];
+	const mailer = createHttpMailer({
+		endpoint: 'https://mail.example.test/send',
+		apiKey: 'test',
+		fetch: async (_url, init) => {
+			requests.push({ headers: new Headers(init.headers), body: JSON.parse(String(init.body)) });
+			return Response.json({ id: 'm-1' });
+		},
+	});
+	await mailer.send({ ...sampleMessage, idempotencyKey: 'order-42/receipt' });
+	expect(requests[0]?.headers.get('idempotency-key')).toBe('order-42/receipt');
+	expect('idempotencyKey' in (requests[0]?.body ?? {})).toBe(false);
+});
+```
+
 ## The conformance suite
 
 ```ts

package/docs/roadmap.md

@@ -6,16 +6,15 @@ the only number.
 
 ## Now
 
-- **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.
+- **An idempotency key per send** — `idempotencyKey` on a `MailMessage`
+  names the send, so sending it again — a retry after a timeout, a job run
+  twice — delivers it once where the transport can deduplicate; a transport
+  that cannot ignores it. `checkMessage` refuses a key that is not 1 to 256
+  visible ASCII characters, never quoting it. The memory mailer honours it as
+  Resend does: the same message under a key it already delivered answers
+  that delivery's `messageId` and delivers nothing more, a different message
+  under it is a `MailRefused`, a failed send leaves its key free, and
+  `clear()` forgets the keys. Built, not yet published.
 
 ## Next
 
@@ -72,6 +71,16 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Attachments, v0.2.0** — `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.
 - **The run-time core, v0.1.0** — `@nxgt/mail`, with no dependency: the `Mailer` port
   a transport implements, the `Rendered` and `MailMessage` shapes it sends, and
   its two errors — `MailFailure` (`MAIL_FAILED`) when the transport could not

package/docs/troubleshooting.md

@@ -64,6 +64,9 @@ 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)
 
 **Locale**
@@ -495,8 +498,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 +762,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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail",
-	"version": "0.2.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-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": []
-}