@nxgt/mail 0.1.0 → 0.3.0

package/dist/conformance/types.d.ts

@@ -1,4 +1,4 @@
-import type { Mailer } from '../types';
+import type { MailAttachment, Mailer } from '../types';
 /**
  * What the receiving end got, as the harness reads it back: from the test
  * SMTP server, from the recorded HTTP request, from the memory outbox.
@@ -9,6 +9,16 @@ export interface DeliveredMail {
     readonly subject: string;
     readonly html: string;
     readonly text: string;
+    /**
+     * The files that arrived with it, in order, each with its bytes, its name
+     * and its type as the receiving end read them — `[]` when none did.
+     *
+     * Optional, so a harness written before attachments still compiles; but
+     * **its absence is reported, never passed over**: `send.attachment` fails
+     * on a harness that leaves it out, until it reads them back or skips the
+     * case with a reason.
+     */
+    readonly attachments?: readonly MailAttachment[];
 }
 /**
  * How the suite makes a transport fail **the way its provider fails**: a

package/dist/conformance/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/conformance/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,SAAS,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,2CAA2C;IAC3C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9B;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/C,EAAE,EAAE;QACH,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;KACpD,CAAC;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/conformance/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,SAAS,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,2CAA2C;IAC3C,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9B;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/C,EAAE,EAAE;QACH,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;KACpD,CAAC;CACF"}

package/dist/errors.d.ts

@@ -22,10 +22,10 @@ export type MailErrorCode =
 /**
  * The message 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 provider answering that the message is
- * malformed, or — from `@nxgt/mail/renderer` — a URL variable that is not
- * an `http:`, `https:` or `mailto:` URL. Sending it again unchanged fails
- * again.
+ * subject or a header, an attachment that is not bytes or is badly named,
+ * a provider answering that the message is malformed or too large, or —
+ * from `@nxgt/mail/renderer` — a URL variable that is not an `http:`,
+ * `https:` or `mailto:` URL. Sending it again unchanged fails again.
  */
  | 'MAIL_REFUSED';
 /** Options every error of this package accepts. */

package/dist/index.d.ts

@@ -17,5 +17,5 @@ export { MailError, type MailErrorCode, type MailErrorOptions, MailFailure, Mail
 export { parseAcceptLanguage, pickLocale, type WantedLocales } from './locale';
 export { createMemoryMailer, type MemoryMail, type MemoryMailer, } from './memory';
 export { addressOf, checkMessage, recipientsOf } from './message';
-export type { Address, Mailer, MailMessage, Rendered, SentMail } from './types';
+export type { Address, MailAttachment, Mailer, MailMessage, Rendered, SentMail, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACN,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,WAAW,EACX,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACN,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,WAAW,EACX,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACX,OAAO,EACP,cAAc,EACd,MAAM,EACN,WAAW,EACX,QAAQ,EACR,QAAQ,GACR,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   addressOf2,
   checkMessage2,
   createMemoryMailer2
-} from "./chunks/index-0f7kdb8k.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;AAED,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

@@ -17,7 +17,13 @@ export declare function addressOf(address: Address): string;
  * - every header name is letters, digits and hyphens, none names what the
  *   transport writes from the message (`To`, `Cc`, `Bcc`, `From`, `Sender`,
  *   `Reply-To`, `Return-Path`, `Subject`, `MIME-Version`, `Content-*`, in
- *   any case), and no header value holds a line break.
+ *   any case), and no header value holds a line break;
+ * - `attachments`, when present, is an array without holes — empty is the
+ *   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/*`;
+ * - `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,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAgBpD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAG3D;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAElD;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA2CvD"}
+{"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

@@ -24,6 +24,21 @@ export interface Rendered {
     readonly html: string;
     readonly text: string;
 }
+/**
+ * A file sent with an e-mail, **as bytes**: never a path or a URL for the
+ * transport to read, never a stream. A large or sensitive file is a signed
+ * link in the template instead — a URL variable.
+ *
+ * `filename` is what the recipient's mail client shows and saves it as: no
+ * path (`/`, `\`, `.`, `..`), no line break, no control or format character.
+ * `contentType` is a bare `type/subtype`, as `application/pdf`, without
+ * parameters, and never a MIME container (`multipart/*`, `message/*`).
+ */
+export interface MailAttachment {
+    readonly filename: string;
+    readonly content: Uint8Array;
+    readonly contentType: string;
+}
 /**
  * A rendered e-mail, addressed. What a {@link Mailer} sends.
  *
@@ -42,6 +57,24 @@ export interface MailMessage extends Rendered {
      * case — is refused.
      */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Files sent with the e-mail, in order. An empty list is the same as none.
+     * Each is bytes, checked by `checkMessage`: see {@link MailAttachment}.
+     */
+    readonly attachments?: readonly MailAttachment[];
+    /**
+     * 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;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAChB,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;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, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
-| [Testing](guide/testing.md) | You are testing code that sends e-mail with `createMemoryMailer`: reading the outbox, making a send fail, counting attempts |
+| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, attachments, 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,7 +1,8 @@
 # Sending
 
 This page is for calling `mailer.send`: the shape of what it takes, the
-addresses and headers it accepts, what it answers, and what it throws.
+addresses, headers and attachments it accepts, the idempotency key that makes
+a retry safe, what it answers, and what it throws.
 
 ```ts
 import { createMemoryMailer } from '@nxgt/mail';
@@ -73,6 +74,14 @@ interface MailMessage extends Rendered {
 	readonly from?: Address;
 	readonly replyTo?: Address;
 	readonly headers?: Readonly<Record<string, string>>;
+	readonly attachments?: readonly MailAttachment[];
+	readonly idempotencyKey?: string;
+}
+
+interface MailAttachment {
+	readonly filename: string;
+	readonly content: Uint8Array;
+	readonly contentType: string;
 }
 ```
 
@@ -85,6 +94,8 @@ interface MailMessage extends Rendered {
 | `from` | `Address` | no | The sender. `checkMessage` does not require one: a transport is usually wired with a default sender, and one without a default may refuse a message without `from` — see its documentation |
 | `replyTo` | `Address` | no | Where replies go |
 | `headers` | `Record<string, string>` | no | Extra headers, such as `List-Unsubscribe` |
+| `attachments` | `readonly MailAttachment[]` | no | Files sent with the e-mail, in order, as bytes — see [Attachments](#attachments). An empty list is the same as none |
+| `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
@@ -214,6 +225,170 @@ const message: MailMessage = {
 | `{ Bcc: 'eve@example.com' }` | `MailRefused`: `send: header Bcc is reserved — addresses, the subject and the MIME structure are never custom headers` |
 | `{ 'content-type': 'text/plain' }` | `MailRefused`: `send: header content-type is reserved — …` |
 
+## Attachments
+
+An attachment is a file's **bytes**, its name and its type:
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `filename` | `string` | The name the recipient's mail client shows and saves it as. Not empty, not `.` or `..`; no `/` or `\`, no line break, no control or format character. Accents and spaces are fine: the transport encodes the name |
+| `content` | `Uint8Array` | The bytes, sent as they are. A Node `Buffer` is a `Uint8Array` |
+| `contentType` | `string` | A bare `type/subtype`, as `application/pdf` or `text/calendar` — no parameters, and never `multipart/*` or `message/*`, which are not files. Nothing guesses it from the file name |
+
+```ts
+import { readFile } from 'node:fs/promises';
+import type { Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendInvoice(mailer: Mailer, to: string, name: string, number: string): Promise<void> {
+	const pdf = await readFile(`invoices/${number}.pdf`); // your storage: a Buffer
+	await mailer.send({
+		to,
+		...mails.render('invoice', { name, number }),
+		attachments: [{ filename: `invoice-${number}.pdf`, content: pdf, contentType: 'application/pdf' }],
+	});
+}
+```
+
+Bytes from anywhere fit — a file read with `readFile`, a PDF your code just
+generated, what `fetch` answered (`new Uint8Array(await response.arrayBuffer())`),
+or text you encoded (`new TextEncoder().encode(csv)`).
+
+**There is no `path`, no URL and no stream.** A transport never reads a file
+from disk or fetches a URL to attach it: a value that came from outside —
+a file name in a request, a link in a database — can then never make an
+e-mail carry a file it should not. The SMTP transport tells nodemailer so
+explicitly. Read the file yourself, where you decide which files may be read.
+
+**A large or sensitive file is a link.** Every provider caps the whole
+message — about 25 MB sending through Gmail, 40 MB at Resend once encoded —
+and base64, which every transport uses on the way, makes a file a third
+larger. A file in an e-mail also stays in an inbox forever, forwarded or not.
+Put a signed, expiring URL in the template instead; a
+[URL variable](rendering.md) is already checked (`http:`, `https:` or
+`mailto:` only):
+
+```ts
+import type { Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+declare function signedUrl(key: string, expiresInSeconds: number): Promise<string>; // your storage
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendExport(mailer: Mailer, to: string, key: string): Promise<void> {
+	const link = await signedUrl(key, 24 * 3600);
+	await mailer.send({ to, ...mails.render('export-ready', { link }) });
+}
+```
+
+Inline images — a `cid:` the HTML points at — are not supported yet: a
+logo belongs on an `https:` URL, which is what the templates of
+`@nxgt/mail-ui` already use.
+
+`checkMessage` refuses, naming where and never the file's name:
+
+| Written | Answer |
+| --- | --- |
+| `attachments: pdf` — one, not in a list | a compile error; at run time `MailRefused`: `send: attachments must be an array` |
+| `[null]` | `MailRefused`: `send: attachments[0] must be an object, as { filename, content, contentType }` |
+| `{ filename, content: '%PDF-1.7', contentType }`, or `{ filename, path, contentType }` | a compile error; at run time `MailRefused`: `send: attachments[0].content must be a Uint8Array — the file's bytes, never a path or a URL` |
+| `filename: 'invoices/42.pdf'`, `'..\\42.pdf'`, `'..'`, `''`, or one holding a line break or a right-to-left override | `MailRefused`: `send: attachments[0].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character` |
+| `contentType: 'text/plain; charset=utf-8'`, `'pdf'`, or `'message/rfc822'` | `MailRefused`: `send: attachments[0].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*` |
+| `attachments: []` | accepted: the same as none |
+
+A message the provider refuses — too large, or an attachment it will not
+carry — is a `MailRefused` from the transport (an SMTP `552`; a Resend `400`,
+`413` or `422`), and sending it again unchanged fails again: send a link
+instead.
+
+## 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
@@ -237,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, or the provider answering that the message is malformed | 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

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