@upyo/smtp 0.6.0-dev.291 → 0.6.0-dev.294

package/README.md

@@ -28,6 +28,7 @@ Features
  -  Multiple recipients (To, CC, BCC)
  -  SMTP PIPELINING for faster multi-recipient delivery
  -  SMTP SIZE declaration and advertised-limit checks
+ -  SMTP delivery status notification requests
  -  Custom headers
  -  Priority levels
  -  Comprehensive testing utilities
@@ -182,6 +183,40 @@ See [RFC 1870] for the SMTP Message Size Declaration extension.
 [RFC 1870]: https://www.rfc-editor.org/rfc/rfc1870
 
 
+Delivery status notifications
+-----------------------------
+
+Pass SMTP-specific DSN settings to `send()` to request delivery status
+notifications under [RFC 3461]:
+
+~~~~ typescript
+const receipt = await transport.send(message, {
+  dsn: {
+    envelopeId: "campaign+42",
+    return: "headers",
+    recipients: {
+      "recipient@example.net": {
+        notify: ["success", "failure", "delay"],
+        originalRecipient: "recipient@example.net",
+      },
+    },
+  },
+});
+~~~~
+
+`envelopeId` and `return` become `ENVID` and `RET` parameters on `MAIL FROM`.
+Each recipient's `notify` and `originalRecipient` values become `NOTIFY` and
+`ORCPT` parameters on its `RCPT TO` command.  Upyo validates and `xtext`-escapes
+the values without adding them to the message headers.  `envelopeId` must not
+be empty, and `originalRecipient` must exactly match its envelope recipient.
+
+If the server does not advertise `DSN`, the transport returns a non-retryable
+failed receipt with the code `smtp.dsn-unsupported` before sending `MAIL FROM`.
+Invalid settings use `smtp.dsn-invalid`.
+
+[RFC 3461]: https://www.rfc-editor.org/rfc/rfc3461
+
+
 DKIM signing
 ------------
 

package/dist/index.cjs

@@ -26,6 +26,119 @@ const node_buffer = __toESM(require("node:buffer"));
 const node_net = __toESM(require("node:net"));
 const node_tls = __toESM(require("node:tls"));
 
+//#region src/delivery-status.ts
+/**
+* Error produced when SMTP delivery status notification settings are invalid.
+*
+* @since 0.6.0
+*/
+var SmtpDsnValidationError = class extends TypeError {
+	/**
+	* Creates a delivery status notification validation error.
+	*
+	* @param message A description of the invalid setting.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "SmtpDsnValidationError";
+	}
+};
+/**
+* Error produced when delivery status notifications were requested from an
+* SMTP server that did not advertise the RFC 3461 `DSN` extension.
+*
+* @since 0.6.0
+*/
+var SmtpDsnUnsupportedError = class extends Error {
+	/** Creates an error for a server without the `DSN` extension. */
+	constructor() {
+		super("Delivery status notifications were requested, but the server does not advertise the DSN extension.");
+		this.name = "SmtpDsnUnsupportedError";
+	}
+};
+const NOTIFICATION_CONDITIONS = new Set([
+	"never",
+	"success",
+	"failure",
+	"delay"
+]);
+/**
+* Validates and serializes the RFC 3461 envelope parameters for a message.
+*
+* @param message The message whose SMTP envelope will carry the parameters.
+* @param dsn The caller-supplied delivery status notification settings.
+* @returns Serialized parameters, or `undefined` when none were requested.
+* @throws {SmtpDsnValidationError} If any setting violates RFC 3461 or does
+* not correspond to the message envelope.
+* @internal
+*/
+function resolveSmtpDsn(message, dsn) {
+	if (dsn == null) return void 0;
+	if (typeof dsn !== "object" || Array.isArray(dsn)) throw new SmtpDsnValidationError("DSN options must be an object.");
+	const mailParameters = [];
+	if (dsn.return != null) {
+		if (dsn.return !== "full" && dsn.return !== "headers") throw new SmtpDsnValidationError(`Unsupported DSN return value: ${String(dsn.return)}`);
+		mailParameters.push(`RET=${dsn.return === "full" ? "FULL" : "HDRS"}`);
+	}
+	if (dsn.envelopeId != null) {
+		if (dsn.envelopeId === "") throw new SmtpDsnValidationError("DSN envelope ID must not be empty.");
+		const encoded = encodeXtext(dsn.envelopeId, "DSN envelope ID");
+		const parameter = `ENVID=${encoded}`;
+		assertParameterLength(parameter, 100, "ENVID");
+		mailParameters.push(parameter);
+	}
+	const envelopeRecipients = [
+		...message.recipients.map((recipient) => recipient.address),
+		...message.ccRecipients.map((recipient) => recipient.address),
+		...message.bccRecipients.map((recipient) => recipient.address)
+	];
+	const envelopeRecipientSet = new Set(envelopeRecipients);
+	const configuredRecipients = dsn.recipients;
+	if (configuredRecipients != null && (typeof configuredRecipients !== "object" || Array.isArray(configuredRecipients))) throw new SmtpDsnValidationError("DSN recipient options must be an object.");
+	const serializedByAddress = /* @__PURE__ */ new Map();
+	for (const [address, options] of Object.entries(configuredRecipients ?? {})) {
+		if (!envelopeRecipientSet.has(address)) throw new SmtpDsnValidationError(`DSN recipient ${address} is not an envelope recipient.`);
+		if (options == null || typeof options !== "object" || Array.isArray(options)) throw new SmtpDsnValidationError(`DSN options for ${address} must be an object.`);
+		const parameters = [];
+		if (options.notify != null) {
+			const notify = options.notify;
+			if (!Array.isArray(notify) || notify.length === 0) throw new SmtpDsnValidationError(`DSN notification conditions for ${address} must be a non-empty array.`);
+			for (const condition of notify) if (typeof condition !== "string" || !NOTIFICATION_CONDITIONS.has(condition)) throw new SmtpDsnValidationError(`Unsupported DSN notification condition: ${String(condition)}`);
+			if (notify.includes("never") && notify.length !== 1) throw new SmtpDsnValidationError("The DSN notification condition NEVER must appear by itself.");
+			parameters.push(`NOTIFY=${notify.map((condition) => condition.toUpperCase()).join(",")}`);
+		}
+		if (options.originalRecipient != null) {
+			const encoded = encodeXtext(options.originalRecipient, `DSN original recipient for ${address}`);
+			if (options.originalRecipient !== address) throw new SmtpDsnValidationError(`DSN original recipient for ${address} must match the envelope recipient address.`);
+			const parameter = `ORCPT=rfc822;${encoded}`;
+			assertParameterLength(parameter, 500, "ORCPT");
+			parameters.push(parameter);
+		}
+		serializedByAddress.set(address, parameters);
+	}
+	const recipientParameters = envelopeRecipients.map((address) => serializedByAddress.get(address) ?? []);
+	const requested = mailParameters.length > 0 || recipientParameters.some((parameters) => parameters.length > 0);
+	return requested ? {
+		mailParameters,
+		recipientParameters
+	} : void 0;
+}
+function encodeXtext(value, name) {
+	if (typeof value !== "string") throw new SmtpDsnValidationError(`${name} must be a string.`);
+	let encoded = "";
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code < 32 || code > 126) throw new SmtpDsnValidationError(`${name} must contain only printable US-ASCII characters.`);
+		if (code >= 33 && code <= 126 && code !== 43 && code !== 61) encoded += value[index];
+		else encoded += `+${code.toString(16).toUpperCase().padStart(2, "0")}`;
+	}
+	return encoded;
+}
+function assertParameterLength(parameter, maximum, name) {
+	if (parameter.length > maximum) throw new SmtpDsnValidationError(`${name} parameter exceeds the RFC 3461 limit of ${maximum} characters.`);
+}
+
+//#endregion
 //#region src/config.ts
 /**
 * Creates a resolved SMTP configuration by applying default values to optional fields.
@@ -868,8 +981,15 @@ var SmtpConnection = class {
 			if (sizeCapability.maximum != null && BigInt(messageSize) > sizeCapability.maximum) throw new SmtpMessageSizeError(messageSize, sizeCapability.maximum);
 			sizeParameter = ` SIZE=${messageSize}`;
 		}
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}`;
-		const recipientCommands = message.envelope.to.map((recipient) => `RCPT TO:<${recipient}>`);
+		const dsn = message.envelope.dsn;
+		if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) throw new SmtpDsnUnsupportedError();
+		const mailDsnParameters = dsn == null || dsn.mailParameters.length === 0 ? "" : ` ${dsn.mailParameters.join(" ")}`;
+		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${mailDsnParameters}`;
+		const recipientCommands = message.envelope.to.map((recipient, index) => {
+			const parameters = dsn?.recipientParameters[index] ?? [];
+			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
+			return `RCPT TO:<${recipient}>${suffix}`;
+		});
 		const pipelining = this.capabilities.some((capability) => /^PIPELINING(?:\s|$)/i.test(capability));
 		let mailResponse;
 		let recipientResponses;
@@ -1296,18 +1416,20 @@ function arrayBufferToBase64(buffer) {
 *
 * @param message The message to convert.
 * @param dkimConfig Optional DKIM signing configuration.
+* @param dsn Optional validated SMTP delivery status notification parameters.
 * @returns The converted SMTP message.
 * @throws {RangeError} If a header contains a token that cannot be folded
 * within the RFC 5322 hard line-length limit.
 */
-async function convertMessage(message, dkimConfig) {
+async function convertMessage(message, dkimConfig, dsn) {
 	const envelope = {
 		from: message.sender.address,
 		to: [
 			...message.recipients.map((r) => r.address),
 			...message.ccRecipients.map((r) => r.address),
 			...message.bccRecipients.map((r) => r.address)
-		]
+		],
+		dsn
 	};
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
@@ -1621,9 +1743,10 @@ var SmtpTransport = class {
 		options?.signal?.throwIfAborted();
 		let connection;
 		try {
+			const dsn = resolveSmtpDsn(message, options?.dsn);
 			connection = await this.getConnection(options?.signal);
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message, this.config.dkim);
+			const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 			options?.signal?.throwIfAborted();
 			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -1634,7 +1757,7 @@ var SmtpTransport = class {
 				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
-			if (connection != null) if (error instanceof SmtpMessageSizeError) await this.returnConnection(connection);
+			if (connection != null) if (isReusableLocalFailure(error)) await this.returnConnection(connection);
 			else await this.discardConnection(connection);
 			options?.signal?.throwIfAborted();
 			return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
@@ -1694,7 +1817,8 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message, this.config.dkim);
+					const dsn = resolveSmtpDsn(message, options?.dsn);
+					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 					options?.signal?.throwIfAborted();
 					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -1705,7 +1829,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
+					if (!isReusableLocalFailure(error)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1716,7 +1840,8 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message, this.config.dkim);
+					const dsn = resolveSmtpDsn(message, options?.dsn);
+					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 					options?.signal?.throwIfAborted();
 					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -1727,7 +1852,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
+					if (!isReusableLocalFailure(error)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1822,6 +1947,20 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpDsnValidationError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "smtp",
+		code: "smtp.dsn-invalid",
+		category: "validation",
+		retryable: false,
+		attempts: 1
+	});
+	if (error instanceof SmtpDsnUnsupportedError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "smtp",
+		code: "smtp.dsn-unsupported",
+		category: "configuration",
+		retryable: false,
+		attempts: 1
+	});
 	if (error instanceof SmtpMessageSizeError) return (0, __upyo_core.createFailedReceipt)(message, {
 		provider: "smtp",
 		code: "smtp.message-size-exceeded",
@@ -1853,6 +1992,9 @@ function createSmtpFailure(message, error) {
 		attempts: 1
 	});
 }
+function isReusableLocalFailure(error) {
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+}
 function classifySmtpReply(code) {
 	if (code >= 400 && code < 500) return {
 		category: "service-unavailable",
@@ -1870,4 +2012,6 @@ function classifySmtpReply(code) {
 
 //#endregion
 exports.SmtpAuthError = SmtpAuthError;
+exports.SmtpDsnUnsupportedError = SmtpDsnUnsupportedError;
+exports.SmtpDsnValidationError = SmtpDsnValidationError;
 exports.SmtpTransport = SmtpTransport;

package/dist/index.d.cts

@@ -417,6 +417,98 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/delivery-status.d.ts
+/**
+ * A condition under which an SMTP server should issue a delivery status
+ * notification for a recipient.
+ *
+ * `"never"` must be the only condition when it is used.
+ *
+ * @since 0.6.0
+ */
+type SmtpDsnNotification = "never" | "success" | "failure" | "delay";
+/**
+ * Delivery status notification settings for one SMTP envelope recipient.
+ *
+ * @since 0.6.0
+ */
+interface SmtpDsnRecipientOptions {
+  /**
+   * Conditions under which the server should issue a notification.
+   *
+   * `"never"` must appear by itself.  When omitted, the server applies its
+   * default behavior, which is normally equivalent to `"failure"` or to
+   * `"failure"` together with `"delay"`.
+   */
+  readonly notify?: readonly SmtpDsnNotification[];
+  /**
+   * The original Internet mail address to identify in notifications.
+   *
+   * Upyo serializes this as an RFC 3461 `ORCPT` parameter with the `rfc822`
+   * address type.  For an initial submission, RFC 3461 requires this value to
+   * equal the corresponding envelope recipient address.
+   */
+  readonly originalRecipient?: string;
+}
+/**
+ * SMTP delivery status notification settings for one message.
+ *
+ * These settings are serialized as SMTP envelope parameters and are not added
+ * to the message headers.
+ *
+ * @since 0.6.0
+ */
+interface SmtpDsnOptions {
+  /**
+   * An identifier that will be returned in delivery status notifications.
+   * Serialized as the RFC 3461 `ENVID` parameter.  The identifier must not be
+   * empty.
+   */
+  readonly envelopeId?: string;
+  /**
+   * How much of the original message a failure notification should return.
+   * Serialized as `RET=FULL` or `RET=HDRS`.
+   */
+  readonly return?: "full" | "headers";
+  /**
+   * Per-recipient notification settings, keyed by exact envelope address.
+   */
+  readonly recipients?: Readonly<Record<string, SmtpDsnRecipientOptions>>;
+}
+/**
+ * SMTP-specific options for sending messages.
+ *
+ * @since 0.6.0
+ */
+interface SmtpTransportOptions extends TransportOptions {
+  /** Delivery status notification settings for this SMTP transaction. */
+  readonly dsn?: SmtpDsnOptions;
+}
+/**
+ * Error produced when SMTP delivery status notification settings are invalid.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpDsnValidationError extends TypeError {
+  /**
+   * Creates a delivery status notification validation error.
+   *
+   * @param message A description of the invalid setting.
+   */
+  constructor(message: string);
+}
+/**
+ * Error produced when delivery status notifications were requested from an
+ * SMTP server that did not advertise the RFC 3461 `DSN` extension.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpDsnUnsupportedError extends Error {
+  /** Creates an error for a server without the `DSN` extension. */
+  constructor();
+}
+/** @internal */
+//#endregion
 //#region src/smtp-receipt.d.ts
 /**
  * An SMTP envelope recipient that the server rejected during an otherwise
@@ -539,7 +631,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  send(message: Message, options?: TransportOptions): Promise<SmtpReceipt>;
+  send(message: Message, options?: SmtpTransportOptions): Promise<SmtpReceipt>;
   /**
    * Sends multiple email messages efficiently using a single SMTP connection.
    *
@@ -570,7 +662,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<SmtpReceipt>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: SmtpTransportOptions): AsyncIterable<SmtpReceipt>;
   private getConnection;
   private connectAndSetup;
   private returnConnection;
@@ -635,4 +727,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth };

package/dist/index.d.ts

@@ -417,6 +417,98 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/delivery-status.d.ts
+/**
+ * A condition under which an SMTP server should issue a delivery status
+ * notification for a recipient.
+ *
+ * `"never"` must be the only condition when it is used.
+ *
+ * @since 0.6.0
+ */
+type SmtpDsnNotification = "never" | "success" | "failure" | "delay";
+/**
+ * Delivery status notification settings for one SMTP envelope recipient.
+ *
+ * @since 0.6.0
+ */
+interface SmtpDsnRecipientOptions {
+  /**
+   * Conditions under which the server should issue a notification.
+   *
+   * `"never"` must appear by itself.  When omitted, the server applies its
+   * default behavior, which is normally equivalent to `"failure"` or to
+   * `"failure"` together with `"delay"`.
+   */
+  readonly notify?: readonly SmtpDsnNotification[];
+  /**
+   * The original Internet mail address to identify in notifications.
+   *
+   * Upyo serializes this as an RFC 3461 `ORCPT` parameter with the `rfc822`
+   * address type.  For an initial submission, RFC 3461 requires this value to
+   * equal the corresponding envelope recipient address.
+   */
+  readonly originalRecipient?: string;
+}
+/**
+ * SMTP delivery status notification settings for one message.
+ *
+ * These settings are serialized as SMTP envelope parameters and are not added
+ * to the message headers.
+ *
+ * @since 0.6.0
+ */
+interface SmtpDsnOptions {
+  /**
+   * An identifier that will be returned in delivery status notifications.
+   * Serialized as the RFC 3461 `ENVID` parameter.  The identifier must not be
+   * empty.
+   */
+  readonly envelopeId?: string;
+  /**
+   * How much of the original message a failure notification should return.
+   * Serialized as `RET=FULL` or `RET=HDRS`.
+   */
+  readonly return?: "full" | "headers";
+  /**
+   * Per-recipient notification settings, keyed by exact envelope address.
+   */
+  readonly recipients?: Readonly<Record<string, SmtpDsnRecipientOptions>>;
+}
+/**
+ * SMTP-specific options for sending messages.
+ *
+ * @since 0.6.0
+ */
+interface SmtpTransportOptions extends TransportOptions {
+  /** Delivery status notification settings for this SMTP transaction. */
+  readonly dsn?: SmtpDsnOptions;
+}
+/**
+ * Error produced when SMTP delivery status notification settings are invalid.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpDsnValidationError extends TypeError {
+  /**
+   * Creates a delivery status notification validation error.
+   *
+   * @param message A description of the invalid setting.
+   */
+  constructor(message: string);
+}
+/**
+ * Error produced when delivery status notifications were requested from an
+ * SMTP server that did not advertise the RFC 3461 `DSN` extension.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpDsnUnsupportedError extends Error {
+  /** Creates an error for a server without the `DSN` extension. */
+  constructor();
+}
+/** @internal */
+//#endregion
 //#region src/smtp-receipt.d.ts
 /**
  * An SMTP envelope recipient that the server rejected during an otherwise
@@ -539,7 +631,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  send(message: Message, options?: TransportOptions): Promise<SmtpReceipt>;
+  send(message: Message, options?: SmtpTransportOptions): Promise<SmtpReceipt>;
   /**
    * Sends multiple email messages efficiently using a single SMTP connection.
    *
@@ -570,7 +662,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<SmtpReceipt>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: SmtpTransportOptions): AsyncIterable<SmtpReceipt>;
   private getConnection;
   private connectAndSetup;
   private returnConnection;
@@ -635,4 +727,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth };

package/dist/index.js

@@ -3,6 +3,119 @@ import { Buffer } from "node:buffer";
 import { Socket } from "node:net";
 import { TLSSocket, connect } from "node:tls";
 
+//#region src/delivery-status.ts
+/**
+* Error produced when SMTP delivery status notification settings are invalid.
+*
+* @since 0.6.0
+*/
+var SmtpDsnValidationError = class extends TypeError {
+	/**
+	* Creates a delivery status notification validation error.
+	*
+	* @param message A description of the invalid setting.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "SmtpDsnValidationError";
+	}
+};
+/**
+* Error produced when delivery status notifications were requested from an
+* SMTP server that did not advertise the RFC 3461 `DSN` extension.
+*
+* @since 0.6.0
+*/
+var SmtpDsnUnsupportedError = class extends Error {
+	/** Creates an error for a server without the `DSN` extension. */
+	constructor() {
+		super("Delivery status notifications were requested, but the server does not advertise the DSN extension.");
+		this.name = "SmtpDsnUnsupportedError";
+	}
+};
+const NOTIFICATION_CONDITIONS = new Set([
+	"never",
+	"success",
+	"failure",
+	"delay"
+]);
+/**
+* Validates and serializes the RFC 3461 envelope parameters for a message.
+*
+* @param message The message whose SMTP envelope will carry the parameters.
+* @param dsn The caller-supplied delivery status notification settings.
+* @returns Serialized parameters, or `undefined` when none were requested.
+* @throws {SmtpDsnValidationError} If any setting violates RFC 3461 or does
+* not correspond to the message envelope.
+* @internal
+*/
+function resolveSmtpDsn(message, dsn) {
+	if (dsn == null) return void 0;
+	if (typeof dsn !== "object" || Array.isArray(dsn)) throw new SmtpDsnValidationError("DSN options must be an object.");
+	const mailParameters = [];
+	if (dsn.return != null) {
+		if (dsn.return !== "full" && dsn.return !== "headers") throw new SmtpDsnValidationError(`Unsupported DSN return value: ${String(dsn.return)}`);
+		mailParameters.push(`RET=${dsn.return === "full" ? "FULL" : "HDRS"}`);
+	}
+	if (dsn.envelopeId != null) {
+		if (dsn.envelopeId === "") throw new SmtpDsnValidationError("DSN envelope ID must not be empty.");
+		const encoded = encodeXtext(dsn.envelopeId, "DSN envelope ID");
+		const parameter = `ENVID=${encoded}`;
+		assertParameterLength(parameter, 100, "ENVID");
+		mailParameters.push(parameter);
+	}
+	const envelopeRecipients = [
+		...message.recipients.map((recipient) => recipient.address),
+		...message.ccRecipients.map((recipient) => recipient.address),
+		...message.bccRecipients.map((recipient) => recipient.address)
+	];
+	const envelopeRecipientSet = new Set(envelopeRecipients);
+	const configuredRecipients = dsn.recipients;
+	if (configuredRecipients != null && (typeof configuredRecipients !== "object" || Array.isArray(configuredRecipients))) throw new SmtpDsnValidationError("DSN recipient options must be an object.");
+	const serializedByAddress = /* @__PURE__ */ new Map();
+	for (const [address, options] of Object.entries(configuredRecipients ?? {})) {
+		if (!envelopeRecipientSet.has(address)) throw new SmtpDsnValidationError(`DSN recipient ${address} is not an envelope recipient.`);
+		if (options == null || typeof options !== "object" || Array.isArray(options)) throw new SmtpDsnValidationError(`DSN options for ${address} must be an object.`);
+		const parameters = [];
+		if (options.notify != null) {
+			const notify = options.notify;
+			if (!Array.isArray(notify) || notify.length === 0) throw new SmtpDsnValidationError(`DSN notification conditions for ${address} must be a non-empty array.`);
+			for (const condition of notify) if (typeof condition !== "string" || !NOTIFICATION_CONDITIONS.has(condition)) throw new SmtpDsnValidationError(`Unsupported DSN notification condition: ${String(condition)}`);
+			if (notify.includes("never") && notify.length !== 1) throw new SmtpDsnValidationError("The DSN notification condition NEVER must appear by itself.");
+			parameters.push(`NOTIFY=${notify.map((condition) => condition.toUpperCase()).join(",")}`);
+		}
+		if (options.originalRecipient != null) {
+			const encoded = encodeXtext(options.originalRecipient, `DSN original recipient for ${address}`);
+			if (options.originalRecipient !== address) throw new SmtpDsnValidationError(`DSN original recipient for ${address} must match the envelope recipient address.`);
+			const parameter = `ORCPT=rfc822;${encoded}`;
+			assertParameterLength(parameter, 500, "ORCPT");
+			parameters.push(parameter);
+		}
+		serializedByAddress.set(address, parameters);
+	}
+	const recipientParameters = envelopeRecipients.map((address) => serializedByAddress.get(address) ?? []);
+	const requested = mailParameters.length > 0 || recipientParameters.some((parameters) => parameters.length > 0);
+	return requested ? {
+		mailParameters,
+		recipientParameters
+	} : void 0;
+}
+function encodeXtext(value, name) {
+	if (typeof value !== "string") throw new SmtpDsnValidationError(`${name} must be a string.`);
+	let encoded = "";
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code < 32 || code > 126) throw new SmtpDsnValidationError(`${name} must contain only printable US-ASCII characters.`);
+		if (code >= 33 && code <= 126 && code !== 43 && code !== 61) encoded += value[index];
+		else encoded += `+${code.toString(16).toUpperCase().padStart(2, "0")}`;
+	}
+	return encoded;
+}
+function assertParameterLength(parameter, maximum, name) {
+	if (parameter.length > maximum) throw new SmtpDsnValidationError(`${name} parameter exceeds the RFC 3461 limit of ${maximum} characters.`);
+}
+
+//#endregion
 //#region src/config.ts
 /**
 * Creates a resolved SMTP configuration by applying default values to optional fields.
@@ -845,8 +958,15 @@ var SmtpConnection = class {
 			if (sizeCapability.maximum != null && BigInt(messageSize) > sizeCapability.maximum) throw new SmtpMessageSizeError(messageSize, sizeCapability.maximum);
 			sizeParameter = ` SIZE=${messageSize}`;
 		}
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}`;
-		const recipientCommands = message.envelope.to.map((recipient) => `RCPT TO:<${recipient}>`);
+		const dsn = message.envelope.dsn;
+		if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) throw new SmtpDsnUnsupportedError();
+		const mailDsnParameters = dsn == null || dsn.mailParameters.length === 0 ? "" : ` ${dsn.mailParameters.join(" ")}`;
+		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${mailDsnParameters}`;
+		const recipientCommands = message.envelope.to.map((recipient, index) => {
+			const parameters = dsn?.recipientParameters[index] ?? [];
+			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
+			return `RCPT TO:<${recipient}>${suffix}`;
+		});
 		const pipelining = this.capabilities.some((capability) => /^PIPELINING(?:\s|$)/i.test(capability));
 		let mailResponse;
 		let recipientResponses;
@@ -1273,18 +1393,20 @@ function arrayBufferToBase64(buffer) {
 *
 * @param message The message to convert.
 * @param dkimConfig Optional DKIM signing configuration.
+* @param dsn Optional validated SMTP delivery status notification parameters.
 * @returns The converted SMTP message.
 * @throws {RangeError} If a header contains a token that cannot be folded
 * within the RFC 5322 hard line-length limit.
 */
-async function convertMessage(message, dkimConfig) {
+async function convertMessage(message, dkimConfig, dsn) {
 	const envelope = {
 		from: message.sender.address,
 		to: [
 			...message.recipients.map((r) => r.address),
 			...message.ccRecipients.map((r) => r.address),
 			...message.bccRecipients.map((r) => r.address)
-		]
+		],
+		dsn
 	};
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
@@ -1598,9 +1720,10 @@ var SmtpTransport = class {
 		options?.signal?.throwIfAborted();
 		let connection;
 		try {
+			const dsn = resolveSmtpDsn(message, options?.dsn);
 			connection = await this.getConnection(options?.signal);
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message, this.config.dkim);
+			const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 			options?.signal?.throwIfAborted();
 			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -1611,7 +1734,7 @@ var SmtpTransport = class {
 				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
-			if (connection != null) if (error instanceof SmtpMessageSizeError) await this.returnConnection(connection);
+			if (connection != null) if (isReusableLocalFailure(error)) await this.returnConnection(connection);
 			else await this.discardConnection(connection);
 			options?.signal?.throwIfAborted();
 			return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
@@ -1671,7 +1794,8 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message, this.config.dkim);
+					const dsn = resolveSmtpDsn(message, options?.dsn);
+					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 					options?.signal?.throwIfAborted();
 					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -1682,7 +1806,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
+					if (!isReusableLocalFailure(error)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1693,7 +1817,8 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message, this.config.dkim);
+					const dsn = resolveSmtpDsn(message, options?.dsn);
+					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
 					options?.signal?.throwIfAborted();
 					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -1704,7 +1829,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
+					if (!isReusableLocalFailure(error)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1799,6 +1924,20 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpDsnValidationError) return createFailedReceipt(message, {
+		provider: "smtp",
+		code: "smtp.dsn-invalid",
+		category: "validation",
+		retryable: false,
+		attempts: 1
+	});
+	if (error instanceof SmtpDsnUnsupportedError) return createFailedReceipt(message, {
+		provider: "smtp",
+		code: "smtp.dsn-unsupported",
+		category: "configuration",
+		retryable: false,
+		attempts: 1
+	});
 	if (error instanceof SmtpMessageSizeError) return createFailedReceipt(message, {
 		provider: "smtp",
 		code: "smtp.message-size-exceeded",
@@ -1830,6 +1969,9 @@ function createSmtpFailure(message, error) {
 		attempts: 1
 	});
 }
+function isReusableLocalFailure(error) {
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+}
 function classifySmtpReply(code) {
 	if (code >= 400 && code < 500) return {
 		category: "service-unavailable",
@@ -1846,4 +1988,4 @@ function classifySmtpReply(code) {
 }
 
 //#endregion
-export { SmtpAuthError, SmtpTransport };
+export { SmtpAuthError, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpTransport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.6.0-dev.291",
+  "version": "0.6.0-dev.294",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.291+280167d7"
+    "@upyo/core": "0.6.0-dev.294+88e02bad"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",