@nxgt/mail-smtp 0.1.0 → 0.3.0

package/README.md

@@ -37,8 +37,9 @@ bun add @nxgt/mail-smtp @nxgt/mail nodemailer
 
 Peers, all required:
 
-- `@nxgt/mail` — the port and the errors. One copy in your tree, so
-  `error instanceof MailFailure` holds.
+- `@nxgt/mail` — the port, the errors and the checks: `^0.3`, the version
+  with attachments and `idempotencyKey`. One copy in your tree, so `error instanceof MailFailure`
+  holds.
 - `nodemailer` (`>=7 <11`; tested with 10). This package never imports it:
   you create the transporter, with every SMTP option nodemailer has.
 - `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
@@ -88,15 +89,46 @@ await mailer.send({
 - A name is handed to nodemailer as `{ name, address }`: nodemailer quotes and
   encodes it, so `Doe, John` names one recipient.
 - `messageId` is nodemailer's id (`<…@host>`), or `null` when it gives none.
-- The parts are strings: nodemailer is told never to read a file or a URL
-  (`disableFileAccess`, `disableUrlAccess`).
+- The parts are strings and the attachments bytes: nodemailer is told never
+  to read a file or a URL (`disableFileAccess`, `disableUrlAccess`).
+- `idempotencyKey` is ignored: SMTP has no such mechanism, so a message sent
+  twice is delivered twice. See
+  [Setting up — the idempotency key](docs/guide/setup.md#the-idempotency-key).
+
+### Attachments
+
+`attachments` on the message are handed to nodemailer as bytes — a `Buffer`
+copied from each `Uint8Array` — with their file name and type:
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+await mailer.send({
+	to: 'ada@example.com',
+	subject: 'Your invoice',
+	html: '<p>Your invoice is attached.</p>',
+	text: 'Your invoice is attached.',
+	attachments: [
+		{ filename: 'invoice-42.pdf', content: await readFile('/srv/invoices/42.pdf'), contentType: 'application/pdf' },
+	],
+});
+```
+
+There is no `path` or `href`, as nodemailer would take them: read the file
+yourself, where your code decides which files may be read. A file name
+outside ASCII is encoded by nodemailer. The server caps the whole message,
+attachments in base64 included — a third larger than the files — at about
+25 MB sending through Gmail, often 10 to 50 MB elsewhere; over it, the
+server answers `552` and `send` throws `MailRefused`. **A large or sensitive
+file is a signed link in the template**, not an attachment. See
+[Setting up — attachments](docs/guide/setup.md#attachments).
 
 ### Errors — a refusal or a failure
 
 | When | Throws | `cause` |
 | --- | --- | --- |
 | The server cannot be reached, a timeout, a `4xx` (try later), credentials refused (`530`–`539`), the sender refused (`5xx` on `MAIL FROM`) | `MailFailure` — `send: the SMTP server could not take the message` | nodemailer's error, with its `code` and `responseCode` |
-| A permanent `5xx` on every recipient or on the content (`550`, `552` too large, `554`) | `MailRefused` — `send: the SMTP server refused the message` | nodemailer's error |
+| A permanent `5xx` on every recipient or on the content (`550`; `552` too large, attachments included; `554`) | `MailRefused` — `send: the SMTP server refused the message` | nodemailer's error |
 | Some recipients refused, the others accepted — **they may have the message** | `MailRefused` — `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others` — or `MailFailure` — `send: the SMTP server could not take <n> of <total> recipients, …` when a refusal is not permanent, or nodemailer gives no reason | nodemailer's error for the first refused recipient |
 | No sender, on the message or as a default | `MailRefused` — `send: from is missing — give the message a from, or createSmtpMailer a default one` | — |
 | A bad option | `TypeError` from `createSmtpMailer` | — |
@@ -141,11 +173,21 @@ A timeout ends in `MailFailure`.
 `539`) and a sender refused at `MAIL FROM`: the next message would be refused
 the same way, so it is a failure of the wiring, not of the message.
 
+**A retry after a timeout can deliver twice.** SMTP cannot deduplicate, and
+the transport ignores `idempotencyKey`: after a `MailFailure` from a
+timeout, the server may already have the message. Retry only what you can
+afford to send twice.
+
 **Some recipients refused still throws, after the others got it.** The
 server may accept one recipient and refuse another; the message then went out
 to the accepted one. Retrying it whole sends it to them twice — send to one
 recipient per `send` when every result must be all or nothing.
 
+**An attachment is held in memory, whole, and grows a third on the way.**
+nodemailer encodes it in base64 into the message it streams; a file of tens
+of megabytes is refused by most servers (`552`, `MailRefused`) after it was
+read. Send a signed link instead.
+
 **A custom header cannot set an address.** `headers: { Bcc: '…' }` would add
 an envelope recipient no check saw: `checkMessage` refuses `To`, `Cc`, `Bcc`,
 `From`, `Sender`, `Reply-To`, `Return-Path`, `Subject`, `MIME-Version` and

package/dist/index.d.ts

@@ -48,6 +48,15 @@ export interface SmtpTransporter {
         html: string;
         text: string;
         headers?: Record<string, string>;
+        /**
+         * A `Buffer`, not a `Uint8Array`: nodemailer's own types want one, and
+         * what `nodemailer.createTransport(…)` answers then fits with no cast.
+         */
+        attachments?: {
+            filename: string;
+            content: Buffer;
+            contentType: string;
+        }[];
         disableFileAccess: boolean;
         disableUrlAccess: boolean;
     }): Promise<SmtpSentInfo>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE;QACd,IAAI,EAAE,iBAAiB,CAAC;QACxB,EAAE,EAAE,iBAAiB,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,iBAAiB,EAAE,OAAO,CAAC;QAC3B,gBAAgB,EAAE,OAAO,CAAC;KAC1B,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AA+ED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CA4EnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,KAAK,OAAO,EAGZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE;QACd,IAAI,EAAE,iBAAiB,CAAC;QACxB,EAAE,EAAE,iBAAiB,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC;;;WAGG;QACH,WAAW,CAAC,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC3E,iBAAiB,EAAE,OAAO,CAAC;QAC3B,gBAAgB,EAAE,OAAO,CAAC;KAC1B,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AA0FD,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAiFnE"}

package/dist/index.js

@@ -5,6 +5,11 @@ import {
   MailRefused
 } from "@nxgt/mail";
 var toNodemailer = (address) => typeof address === "string" ? { name: "", address } : { name: address.name, address: address.address };
+var toNodemailerAttachment = (attachment) => ({
+  filename: attachment.filename,
+  content: Buffer.from(attachment.content),
+  contentType: attachment.contentType
+});
 var fieldsOf = (error) => typeof error === "object" && error !== null ? error : {};
 function isPermanentRefusal(error) {
   const { code, responseCode, command } = fieldsOf(error);
@@ -66,6 +71,7 @@ function createSmtpMailer(options) {
           html: message.html,
           text: message.text,
           ...message.headers === undefined ? {} : { headers: { ...message.headers } },
+          ...message.attachments === undefined || message.attachments.length === 0 ? {} : { attachments: message.attachments.map(toNodemailerAttachment) },
           disableFileAccess: true,
           disableUrlAccess: true
         });
@@ -89,5 +95,5 @@ export {
   createSmtpMailer
 };
 
-//# debugId=748DA33D57D71AF564756E2164756E21
+//# debugId=E9820236D701396064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/index.ts"],
   "sourcesContent": [
-    "/**\n * `@nxgt/mail-smtp` — an SMTP transport for `@nxgt/mail`, on the `nodemailer`\n * the application installs and configures.\n *\n * ```ts\n * import nodemailer from 'nodemailer';\n * import { createSmtpMailer } from '@nxgt/mail-smtp';\n *\n * const mailer = createSmtpMailer({\n *   transporter: nodemailer.createTransport({ host, port: 587, auth }),\n *   from: { name: 'Acme', address: 'noreply@acme.test' },\n * });\n * ```\n *\n * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`\n * peer, nodemailer's error as the `cause`. Nothing is retried.\n */\n\nimport {\n\ttype Address,\n\tcheckMessage,\n\ttype Mailer,\n\tMailFailure,\n\ttype MailMessage,\n\tMailRefused,\n\ttype SentMail,\n} from '@nxgt/mail';\n\n/**\n * An address as nodemailer takes it: always an object, so nodemailer never\n * parses a string — it quotes and encodes the name itself.\n */\ntype NodemailerAddress = { name: string; address: string };\n\n/**\n * What nodemailer answers once the server took the message: its id, and the\n * recipients it refused while accepting others — nodemailer resolves then.\n */\nexport interface SmtpSentInfo {\n\treadonly messageId?: string;\n\treadonly accepted?: readonly unknown[] | undefined;\n\treadonly rejected?: readonly unknown[] | undefined;\n\t/** One nodemailer error per refused recipient, with its `responseCode`. */\n\treadonly rejectedErrors?: readonly unknown[] | undefined;\n}\n\n/**\n * The part of a nodemailer transporter this transport calls — what\n * `nodemailer.createTransport(…)` answers, from nodemailer 7 on.\n */\nexport interface SmtpTransporter {\n\tsendMail(mail: {\n\t\tfrom: NodemailerAddress;\n\t\tto: NodemailerAddress[];\n\t\treplyTo?: NodemailerAddress;\n\t\tsubject: string;\n\t\thtml: string;\n\t\ttext: string;\n\t\theaders?: Record<string, string>;\n\t\tdisableFileAccess: boolean;\n\t\tdisableUrlAccess: boolean;\n\t}): Promise<SmtpSentInfo>;\n}\n\nexport interface SmtpMailerOptions {\n\t/** `nodemailer.createTransport(…)`, configured by the application. */\n\treadonly transporter: SmtpTransporter;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n}\n\nconst toNodemailer = (address: Address): NodemailerAddress =>\n\ttypeof address === 'string'\n\t\t? { name: '', address }\n\t\t: { name: address.name, address: address.address };\n\ninterface SmtpError {\n\treadonly code?: unknown;\n\treadonly responseCode?: unknown;\n\treadonly command?: unknown;\n\treadonly message?: unknown;\n\treadonly rejectedErrors?: unknown;\n}\n\nconst fieldsOf = (error: unknown): SmtpError =>\n\ttypeof error === 'object' && error !== null ? (error as SmtpError) : {};\n\n/**\n * Whether one nodemailer error is the server refusing **this message** for\n * good — a permanent `5xx` on a recipient or on the content (`552` for a\n * message too large) — rather\n * than the server, the network or the wiring failing. Two `5xx` are\n * failures: authentication (`530`–`539`), and a sender refused at\n * `MAIL FROM` — the next message would be refused the same way.\n */\nfunction isPermanentRefusal(error: unknown): boolean {\n\tconst { code, responseCode, command } = fieldsOf(error);\n\treturn (\n\t\t(code === 'EENVELOPE' || code === 'EMESSAGE') &&\n\t\tcommand !== 'MAIL FROM' &&\n\t\ttypeof responseCode === 'number' &&\n\t\tresponseCode >= 500 &&\n\t\tresponseCode < 600 &&\n\t\t(responseCode < 530 || responseCode > 539)\n\t);\n}\n\n/**\n * Whether a rejected send is a refusal of the message. When every recipient\n * was refused, nodemailer's error carries the code of the **last** one only:\n * each refusal is read instead, and it is a refusal only if every one is.\n */\nfunction isRefusal(error: unknown): boolean {\n\tconst { rejectedErrors } = fieldsOf(error);\n\tif (Array.isArray(rejectedErrors) && rejectedErrors.length > 0) {\n\t\treturn rejectedErrors.every(isPermanentRefusal);\n\t}\n\treturn isPermanentRefusal(error);\n}\n\n/**\n * Throws when nodemailer resolved with some recipients refused: the server\n * took the message for the others, so it may already have reached them.\n */\nfunction throwOnPartialRejection(info: SmtpSentInfo): void {\n\tconst errors = Array.isArray(info.rejectedErrors) ? info.rejectedErrors : [];\n\tconst rejected = Array.isArray(info.rejected) ? info.rejected : [];\n\tconst refusedCount = Math.max(errors.length, rejected.length);\n\tif (refusedCount === 0) return;\n\tconst accepted = Array.isArray(info.accepted) ? info.accepted.length : 0;\n\tconst counted = `${refusedCount} of ${refusedCount + accepted} recipients`;\n\tconst cause =\n\t\terrors[0] ??\n\t\tObject.assign(new Error('the SMTP server refused some recipients'), {\n\t\t\trejected,\n\t\t});\n\tif (errors.length > 0 && errors.every(isPermanentRefusal)) {\n\t\tthrow new MailRefused(\n\t\t\t`send: the SMTP server refused ${counted}, and may have delivered to the others`,\n\t\t\t{ cause },\n\t\t);\n\t}\n\tthrow new MailFailure(\n\t\t`send: the SMTP server could not take ${counted}, and may have delivered to the others`,\n\t\t{ cause },\n\t);\n}\n\n/** Creates a {@link Mailer} that hands each message to `transporter`. */\nexport function createSmtpMailer(options: SmtpMailerOptions): Mailer {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: options must be an object, as { transporter }',\n\t\t);\n\t}\n\tconst { transporter, from } = options;\n\tif (\n\t\ttypeof transporter !== 'object' ||\n\t\ttransporter === null ||\n\t\ttypeof transporter.sendMail !== 'function'\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers',\n\t\t);\n\t}\n\tif (from !== undefined) {\n\t\t// Checked once, as the message's own sender is: a wiring mistake.\n\t\ttry {\n\t\t\tcheckMessage({ to: from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createSmtpMailer: from must be an e-mail address, as noreply@example.com or { name, address }',\n\t\t\t);\n\t\t}\n\t}\n\n\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? from;\n\t\t\tif (sender === undefined) {\n\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t'send: from is missing — give the message a from, or createSmtpMailer a default one',\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\t\t\tlet info: SmtpSentInfo;\n\t\t\ttry {\n\t\t\t\tinfo = await transporter.sendMail({\n\t\t\t\t\tfrom: toNodemailer(sender),\n\t\t\t\t\tto: to.map(toNodemailer),\n\t\t\t\t\t...(message.replyTo === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { replyTo: toNodemailer(message.replyTo) }),\n\t\t\t\t\tsubject: message.subject,\n\t\t\t\t\thtml: message.html,\n\t\t\t\t\ttext: message.text,\n\t\t\t\t\t...(message.headers === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { headers: { ...message.headers } }),\n\t\t\t\t\t// The parts are strings: nothing is ever read from a file or a URL.\n\t\t\t\t\tdisableFileAccess: true,\n\t\t\t\t\tdisableUrlAccess: true,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (isRefusal(error)) {\n\t\t\t\t\tthrow new MailRefused('send: the SMTP server refused the message', {\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t'send: the SMTP server could not take the message',\n\t\t\t\t\t{\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrowOnPartialRejection(info ?? {});\n\t\t\tconst messageId =\n\t\t\t\ttypeof info?.messageId === 'string' && info.messageId !== ''\n\t\t\t\t\t? info.messageId\n\t\t\t\t\t: null;\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
+    "/**\n * `@nxgt/mail-smtp` — an SMTP transport for `@nxgt/mail`, on the `nodemailer`\n * the application installs and configures.\n *\n * ```ts\n * import nodemailer from 'nodemailer';\n * import { createSmtpMailer } from '@nxgt/mail-smtp';\n *\n * const mailer = createSmtpMailer({\n *   transporter: nodemailer.createTransport({ host, port: 587, auth }),\n *   from: { name: 'Acme', address: 'noreply@acme.test' },\n * });\n * ```\n *\n * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`\n * peer, nodemailer's error as the `cause`. Nothing is retried.\n */\n\nimport {\n\ttype Address,\n\tcheckMessage,\n\ttype MailAttachment,\n\ttype Mailer,\n\tMailFailure,\n\ttype MailMessage,\n\tMailRefused,\n\ttype SentMail,\n} from '@nxgt/mail';\n\n/**\n * An address as nodemailer takes it: always an object, so nodemailer never\n * parses a string — it quotes and encodes the name itself.\n */\ntype NodemailerAddress = { name: string; address: string };\n\n/**\n * What nodemailer answers once the server took the message: its id, and the\n * recipients it refused while accepting others — nodemailer resolves then.\n */\nexport interface SmtpSentInfo {\n\treadonly messageId?: string;\n\treadonly accepted?: readonly unknown[] | undefined;\n\treadonly rejected?: readonly unknown[] | undefined;\n\t/** One nodemailer error per refused recipient, with its `responseCode`. */\n\treadonly rejectedErrors?: readonly unknown[] | undefined;\n}\n\n/**\n * The part of a nodemailer transporter this transport calls — what\n * `nodemailer.createTransport(…)` answers, from nodemailer 7 on.\n */\nexport interface SmtpTransporter {\n\tsendMail(mail: {\n\t\tfrom: NodemailerAddress;\n\t\tto: NodemailerAddress[];\n\t\treplyTo?: NodemailerAddress;\n\t\tsubject: string;\n\t\thtml: string;\n\t\ttext: string;\n\t\theaders?: Record<string, string>;\n\t\t/**\n\t\t * A `Buffer`, not a `Uint8Array`: nodemailer's own types want one, and\n\t\t * what `nodemailer.createTransport(…)` answers then fits with no cast.\n\t\t */\n\t\tattachments?: { filename: string; content: Buffer; contentType: string }[];\n\t\tdisableFileAccess: boolean;\n\t\tdisableUrlAccess: boolean;\n\t}): Promise<SmtpSentInfo>;\n}\n\nexport interface SmtpMailerOptions {\n\t/** `nodemailer.createTransport(…)`, configured by the application. */\n\treadonly transporter: SmtpTransporter;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n}\n\nconst toNodemailer = (address: Address): NodemailerAddress =>\n\ttypeof address === 'string'\n\t\t? { name: '', address }\n\t\t: { name: address.name, address: address.address };\n\n/**\n * An attachment as nodemailer takes it: its bytes as a `Buffer` — copied, so\n * a change the caller makes during the send reaches no one — and never a\n * `path` or an `href`, which nodemailer would read or fetch.\n */\nconst toNodemailerAttachment = (attachment: MailAttachment) => ({\n\tfilename: attachment.filename,\n\tcontent: Buffer.from(attachment.content),\n\tcontentType: attachment.contentType,\n});\n\ninterface SmtpError {\n\treadonly code?: unknown;\n\treadonly responseCode?: unknown;\n\treadonly command?: unknown;\n\treadonly message?: unknown;\n\treadonly rejectedErrors?: unknown;\n}\n\nconst fieldsOf = (error: unknown): SmtpError =>\n\ttypeof error === 'object' && error !== null ? (error as SmtpError) : {};\n\n/**\n * Whether one nodemailer error is the server refusing **this message** for\n * good — a permanent `5xx` on a recipient or on the content (`552` for a\n * message too large) — rather\n * than the server, the network or the wiring failing. Two `5xx` are\n * failures: authentication (`530`–`539`), and a sender refused at\n * `MAIL FROM` — the next message would be refused the same way.\n */\nfunction isPermanentRefusal(error: unknown): boolean {\n\tconst { code, responseCode, command } = fieldsOf(error);\n\treturn (\n\t\t(code === 'EENVELOPE' || code === 'EMESSAGE') &&\n\t\tcommand !== 'MAIL FROM' &&\n\t\ttypeof responseCode === 'number' &&\n\t\tresponseCode >= 500 &&\n\t\tresponseCode < 600 &&\n\t\t(responseCode < 530 || responseCode > 539)\n\t);\n}\n\n/**\n * Whether a rejected send is a refusal of the message. When every recipient\n * was refused, nodemailer's error carries the code of the **last** one only:\n * each refusal is read instead, and it is a refusal only if every one is.\n */\nfunction isRefusal(error: unknown): boolean {\n\tconst { rejectedErrors } = fieldsOf(error);\n\tif (Array.isArray(rejectedErrors) && rejectedErrors.length > 0) {\n\t\treturn rejectedErrors.every(isPermanentRefusal);\n\t}\n\treturn isPermanentRefusal(error);\n}\n\n/**\n * Throws when nodemailer resolved with some recipients refused: the server\n * took the message for the others, so it may already have reached them.\n */\nfunction throwOnPartialRejection(info: SmtpSentInfo): void {\n\tconst errors = Array.isArray(info.rejectedErrors) ? info.rejectedErrors : [];\n\tconst rejected = Array.isArray(info.rejected) ? info.rejected : [];\n\tconst refusedCount = Math.max(errors.length, rejected.length);\n\tif (refusedCount === 0) return;\n\tconst accepted = Array.isArray(info.accepted) ? info.accepted.length : 0;\n\tconst counted = `${refusedCount} of ${refusedCount + accepted} recipients`;\n\tconst cause =\n\t\terrors[0] ??\n\t\tObject.assign(new Error('the SMTP server refused some recipients'), {\n\t\t\trejected,\n\t\t});\n\tif (errors.length > 0 && errors.every(isPermanentRefusal)) {\n\t\tthrow new MailRefused(\n\t\t\t`send: the SMTP server refused ${counted}, and may have delivered to the others`,\n\t\t\t{ cause },\n\t\t);\n\t}\n\tthrow new MailFailure(\n\t\t`send: the SMTP server could not take ${counted}, and may have delivered to the others`,\n\t\t{ cause },\n\t);\n}\n\n/** Creates a {@link Mailer} that hands each message to `transporter`. */\nexport function createSmtpMailer(options: SmtpMailerOptions): Mailer {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: options must be an object, as { transporter }',\n\t\t);\n\t}\n\tconst { transporter, from } = options;\n\tif (\n\t\ttypeof transporter !== 'object' ||\n\t\ttransporter === null ||\n\t\ttypeof transporter.sendMail !== 'function'\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers',\n\t\t);\n\t}\n\tif (from !== undefined) {\n\t\t// Checked once, as the message's own sender is: a wiring mistake.\n\t\ttry {\n\t\t\tcheckMessage({ to: from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createSmtpMailer: from must be an e-mail address, as noreply@example.com or { name, address }',\n\t\t\t);\n\t\t}\n\t}\n\n\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? from;\n\t\t\tif (sender === undefined) {\n\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t'send: from is missing — give the message a from, or createSmtpMailer a default one',\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\t\t\tlet info: SmtpSentInfo;\n\t\t\ttry {\n\t\t\t\tinfo = await transporter.sendMail({\n\t\t\t\t\tfrom: toNodemailer(sender),\n\t\t\t\t\tto: to.map(toNodemailer),\n\t\t\t\t\t...(message.replyTo === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { replyTo: toNodemailer(message.replyTo) }),\n\t\t\t\t\tsubject: message.subject,\n\t\t\t\t\thtml: message.html,\n\t\t\t\t\ttext: message.text,\n\t\t\t\t\t...(message.headers === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { headers: { ...message.headers } }),\n\t\t\t\t\t...(message.attachments === undefined ||\n\t\t\t\t\tmessage.attachments.length === 0\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { attachments: message.attachments.map(toNodemailerAttachment) }),\n\t\t\t\t\t// The parts are strings and the attachments bytes: nothing is ever\n\t\t\t\t\t// read from a file or a URL.\n\t\t\t\t\tdisableFileAccess: true,\n\t\t\t\t\tdisableUrlAccess: true,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (isRefusal(error)) {\n\t\t\t\t\tthrow new MailRefused('send: the SMTP server refused the message', {\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t'send: the SMTP server could not take the message',\n\t\t\t\t\t{\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrowOnPartialRejection(info ?? {});\n\t\t\tconst messageId =\n\t\t\t\ttypeof info?.messageId === 'string' && info.messageId !== ''\n\t\t\t\t\t? info.messageId\n\t\t\t\t\t: null;\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "748DA33D57D71AF564756E2164756E21",
+  "mappings": "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",
+  "debugId": "E9820236D701396064756E2164756E21",
   "names": []
 }

package/docs/README.md

@@ -7,7 +7,7 @@ mailer, transport, hand-over, refusal, failure — are defined once, in the
 
 | Page | Read it when |
 | --- | --- |
-| [Setting up](guide/setup.md) | You are wiring `createSmtpMailer` to a nodemailer transporter: host, port and TLS, credentials, a pool, timeouts, the default sender, and what a message becomes on the wire |
+| [Setting up](guide/setup.md) | You are wiring `createSmtpMailer` to a nodemailer transporter: host, port and TLS, credentials, a pool, timeouts, the default sender, what a message becomes on the wire, and why `idempotencyKey` is ignored (with Resend's SMTP relay header) |
 | [Errors](guide/errors.md) | You are handling what `send` throws: which SMTP answers are a `MailRefused`, which a `MailFailure`, what is on `cause`, and every `TypeError` at wiring |
 | [Testing](guide/testing.md) | You are testing the transport against a real SMTP server — `smtp-server`, `mailparser`, `describeMailer` — or an application that uses it |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |

package/docs/guide/errors.md

@@ -19,7 +19,9 @@ recipients may already have the message. The message says so
 ([below](#some-recipients-refused)); retrying it whole sends it to them again.
 
 Nothing is retried. Whether and when to retry is yours to decide, where you
-can see it.
+can see it. SMTP cannot deduplicate — the transport ignores
+`idempotencyKey` — so a retry after a timeout may deliver the e-mail twice
+([Setting up — the idempotency key](setup.md#the-idempotency-key)).
 
 ```ts
 import { MailError, type MailErrorCode, type Mailer, type MailMessage } from '@nxgt/mail';
@@ -58,7 +60,7 @@ a `responseCode`. The transport reads both:
 | The sender refused (`550`, `553` on `MAIL FROM`) | `EENVELOPE` with a `5xx` and `command: 'MAIL FROM'` | `MailFailure` |
 | A recipient refused for good (`550`, `553`) | `EENVELOPE` with a `5xx` | `MailRefused` |
 | Every recipient refused | `EENVELOPE`, one error per recipient on `rejectedErrors` | `MailRefused` if every one is a permanent `5xx` (not `530`–`539`), else `MailFailure` |
-| The content refused for good (`552` too large, `554` rejected) | `EMESSAGE` with a `5xx` | `MailRefused` |
+| The content refused for good (`552` too large, attachments included; `554` rejected) | `EMESSAGE` with a `5xx` | `MailRefused` |
 | Anything else | — | `MailFailure` |
 
 Two `5xx` are failures: authentication, and a sender refused at

package/docs/guide/setup.md

@@ -49,6 +49,7 @@ interface SmtpTransporter {
 		html: string;
 		text: string;
 		headers?: Record<string, string>;
+		attachments?: { filename: string; content: Buffer; contentType: string }[];
 		disableFileAccess: boolean;
 		disableUrlAccess: boolean;
 	}): Promise<SmtpSentInfo>;
@@ -171,7 +172,9 @@ A string is only an address: `'Acme <noreply@acme.test>'` is refused. Write
 | `from`, `replyTo` | `from`, `replyTo` |
 | `subject`, `html`, `text` | the same, as strings — the e-mail is `multipart/alternative` |
 | `headers` | `headers`, copied |
-| — | `disableFileAccess: true`, `disableUrlAccess: true`: a part is never read from a file or fetched from a URL |
+| `idempotencyKey` | nothing: ignored — see [below](#the-idempotency-key) |
+| `attachments`, each `{ filename, content, contentType }` | `attachments`, each `{ filename, content: Buffer, contentType }` — the bytes copied into a `Buffer`, never a `path` or an `href`; the e-mail is then `multipart/mixed`. Left out when the list is empty |
+| — | `disableFileAccess: true`, `disableUrlAccess: true`: a part or an attachment is never read from a file or fetched from a URL |
 
 Before any of it, `checkMessage` from `@nxgt/mail` refuses what no transport
 hands over — no recipient, something that is not an address, a line break in
@@ -182,6 +185,95 @@ subject or the MIME structure (`Bcc`, `To`, `Content-Type`…). Its messages are
 `send` answers `{ messageId }`: nodemailer's `Message-ID` (`<…@acme.test>`), or
 `null` when the transporter answers none — an absence, not a failure.
 
+## The idempotency key
+
+SMTP has no idempotency: a server takes every message it is handed, and
+cannot tell a retry from a new e-mail. The transport therefore **ignores**
+`idempotencyKey` — it neither refuses the message nor writes the key into it
+— and a message sent twice is delivered twice:
+
+```ts
+const once = {
+	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', // still checked by checkMessage; not sent
+};
+
+await mailer.send(once);
+await mailer.send(once); // a second e-mail
+```
+
+Setting the key is still worth it when the same code may run on a
+transport that deduplicates, as `@nxgt/mail-resend`. Over SMTP, a retry
+after a `MailFailure` from a timeout or a dropped connection may deliver
+twice: the server may have taken the message before the connection ended.
+
+**Relaying through Resend's SMTP server** (`smtp.resend.com`)? Resend reads
+its own `Resend-Idempotency-Key` header there. The transport does not set it
+from `idempotencyKey`; set it yourself among the headers, with the same
+value:
+
+```ts
+const key = 'order-42/receipt';
+
+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: key,
+	headers: { 'Resend-Idempotency-Key': key }, // read by Resend's relay; any other server passes it on as a header
+});
+```
+
+On any other server, that header travels with the e-mail to the recipient:
+set it only when the relay is Resend's.
+
+## Attachments
+
+```ts
+import { readFile } from 'node:fs/promises';
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport(process.env.SMTP_URL ?? 'smtp://localhost:1025'),
+	from: 'billing@acme.test',
+});
+
+await mailer.send({
+	to: 'ada@example.com',
+	subject: 'Your invoice',
+	html: '<p>Your invoice is attached.</p>',
+	text: 'Your invoice is attached.',
+	attachments: [
+		{ filename: 'facture n° 42.pdf', content: await readFile('/srv/invoices/42.pdf'), contentType: 'application/pdf' },
+		{ filename: 'invoice.ics', content: new TextEncoder().encode('BEGIN:VCALENDAR…'), contentType: 'text/calendar' },
+	],
+});
+```
+
+- Each attachment is checked by `checkMessage` first: bytes as a
+  `Uint8Array`, a file name not empty, not `.` or `..`, without `/`, `\`, a line break (U+2028 and U+2029 included), a control character or a format character such as a right-to-left override, a `type/subtype` that is not `multipart/*` or `message/*` (which
+  nodemailer would write unencoded, as parts of the message) — see
+  [`@nxgt/mail` — attachments](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/sending.md#attachments).
+- The bytes are **copied** into a `Buffer` when `send` is called: changing
+  your array while the message is on its way changes nothing.
+- nodemailer writes each one as a base64 MIME part, the name encoded
+  (RFC 2231) when it is not ASCII.
+- nodemailer's `path`, `href`, `raw` and streams are never used, and
+  `disableFileAccess` and `disableUrlAccess` stay on: an attachment is bytes
+  your code already holds.
+
+**Size.** The server caps the whole message after encoding — base64 makes a
+file a third larger. Gmail's SMTP takes about 25 MB; other servers advertise
+their limit in `EHLO` (`SIZE`), often 10 to 50 MB. Over it, the server
+answers `552` once the message is sent, and `send` throws `MailRefused`:
+[Errors](errors.md#which-smtp-answer-is-which). A large or sensitive file is a
+signed, expiring link in the template instead, which never sits in an inbox.
+
 ## With the renderer
 
 What `@nxgt/mail/renderer` answers spreads into the message:

package/docs/guide/testing.md

@@ -60,6 +60,11 @@ export async function startSmtpServer() {
 						subject: parsed.subject ?? '',
 						html: typeof parsed.html === 'string' ? parsed.html : '',
 						text: parsed.text ?? '',
+						attachments: parsed.attachments.map((file) => ({
+							filename: file.filename ?? '',
+							content: new Uint8Array(file.content), // a Buffer, read back as bytes
+							contentType: file.contentType,
+						})),
 					});
 					callback();
 				},
@@ -81,7 +86,9 @@ export async function startSmtpServer() {
 
 `to` is read from the **envelope** (`RCPT TO`), not from the `To:` header: it
 is who the server was asked to deliver to, and what proves a name did not
-smuggle a second recipient in.
+smuggle a second recipient in. `attachments` is what `mailparser` decoded,
+the file name included: `send.attachment` fails on a harness that leaves it
+out.
 
 ## The conformance suite
 
@@ -120,10 +127,11 @@ describeMailer({
 });
 ```
 
-All eleven cases pass: a send answers `SentMail`, the message arrives byte for
+All thirteen cases pass: a send answers `SentMail`, the message arrives byte for
 byte (accents, an emoji, `&` in a link), every recipient is delivered to,
-a hostile name reaches only its own address, the refusals — a `Bcc` among the
-custom headers included — and the three
+a hostile name reaches only its own address, an attachment arrives byte for
+byte with its name and type, the refusals — a `Bcc` among the custom headers
+and an attachment named with a path included — and the three
 failure cases — an outage is a `MailFailure` with its `cause` and one attempt,
 a refusal a `MailRefused`, and the next send goes through.
 
@@ -146,7 +154,14 @@ add what the suite does not ask of every transport:
 - no error message holds the password or a recipient's address;
 - the default `from`, `replyTo` and `headers` reach the server, and the id is
   nodemailer's;
-- nodemailer is told never to read a file or a URL.
+- nodemailer is told never to read a file or a URL;
+- `idempotencyKey` is ignored: the same message sent twice is handed over
+  twice, and the key appears nowhere in what nodemailer receives;
+- attachments are handed over as `{ filename, content, contentType }` with a
+  `Buffer` copied from the bytes — a change to the caller's array during the
+  send reaches no one — and an empty list sends none;
+- a message over the server's size limit (`552`, from `smtp-server`'s `size`)
+  is a `MailRefused`, and nothing is delivered.
 
 A transporter can also be a plain object, when a test only needs to see what
 was handed over:

package/docs/roadmap.md

@@ -5,7 +5,10 @@ no dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing between releases.
+- **Messages with an idempotency key** — a message that carries an
+  `idempotencyKey` is accepted, and the key is ignored: SMTP has no
+  idempotency, so a message sent twice is delivered twice. Needs `@nxgt/mail`
+  0.3. Built, not yet published.
 
 ## Next
 
@@ -25,8 +28,9 @@ Nothing planned yet. Say what you need in an issue.
   twice.
 - **A transport's own error class** — it throws `@nxgt/mail`'s `MailFailure`
   and `MailRefused`, so `instanceof` holds whichever transport you wire.
-- **Attachments and files read by nodemailer** — a message is three strings;
-  `disableFileAccess` and `disableUrlAccess` stay on.
+- **Files and URLs read by nodemailer** — an attachment is bytes your code
+  already holds; `disableFileAccess` and `disableUrlAccess` stay on, so no
+  value from outside can make nodemailer read a file or fetch a URL.
 - **Bundling nodemailer** — it is a peer: one copy, the version you choose.
 
 ## Shipped
@@ -34,6 +38,12 @@ Nothing planned yet. Say what you need in an issue.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Attachments, v0.2.0** — the `attachments` of a message are handed to nodemailer
+  as bytes, a `Buffer` copied from each `Uint8Array`, with their file name
+  (encoded by nodemailer when it is not ASCII) and their type. Never a `path`
+  or an `href`: `disableFileAccess` and `disableUrlAccess` stay on. A message
+  over the server's size limit (`552`) is a `MailRefused`. Needs
+  `@nxgt/mail` 0.2.
 - **An SMTP transport on your nodemailer, v0.1.0** — `createSmtpMailer({ transporter,
   from })`: every SMTP option is nodemailer's, set where you create the
   transporter. Each message is checked as every transport checks it, a name is

package/docs/troubleshooting.md

@@ -79,6 +79,11 @@ try {
 A retry is yours to decide — from a queue, with a delay. The transport never
 retries in secret.
 
+An `idempotencyKey` does not make that retry safe here: SMTP has no
+idempotency, and this transport ignores the key. If the first attempt went
+through after all, the retry delivers a second copy — weigh that before
+retrying after a timeout.
+
 ### `send: the SMTP server refused the message`
 
 A `MailRefused`, code `MAIL_REFUSED`.
@@ -95,6 +100,24 @@ every recipient refused, `cause.rejectedErrors` holds one error per
 recipient; correct the address or the content. A recipient that does not
 exist is usually worth telling the user about.
 
+A `552` on a message with attachments is the server's size limit — the
+whole message, after base64 has made each file a third larger. Sending it
+again fails again: send the file as a signed link in the template instead.
+
+```ts
+import { MailRefused } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	const cause = error instanceof MailRefused ? (error.cause as { responseCode?: number }) : null;
+	if (cause?.responseCode === 552 && message.attachments?.length) {
+		// too large: resend with a link to the file rather than the file
+	}
+	throw error;
+}
+```
+
 ### `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others`
 
 A `MailRefused`, code `MAIL_REFUSED`. **The accepted recipients may already

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail-smtp",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "An SMTP transport for @nxgt/mail, on the nodemailer you install: it throws the MailFailure and MailRefused of its @nxgt/mail peer, and passes the conformance suite.",
 	"license": "MIT",
 	"type": "module",
@@ -44,7 +44,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@nxgt/mail": "0.1.0",
+		"@nxgt/mail": "0.3.0",
 		"@types/bun": "^1.4.2",
 		"@types/mailparser": "^3.4.6",
 		"@types/nodemailer": "^8.0.2",
@@ -54,7 +54,7 @@
 		"smtp-server": "^3.19.13"
 	},
 	"peerDependencies": {
-		"@nxgt/mail": "^0.1.0",
+		"@nxgt/mail": "^0.3.0",
 		"nodemailer": ">=7.0.0 <11",
 		"typescript": "^6.0.3"
 	}