@upyo/smtp 0.6.0-dev.295 → 0.6.0-dev.296

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
+ -  SMTPUTF8 internationalized address delivery
  -  SMTP delivery status notification requests
  -  Custom headers
  -  Priority levels
@@ -183,6 +184,22 @@ See [RFC 1870] for the SMTP Message Size Declaration extension.
 [RFC 1870]: https://www.rfc-editor.org/rfc/rfc1870
 
 
+Internationalized addresses
+---------------------------
+
+The transport automatically negotiates [RFC 6531] SMTPUTF8 when any sender,
+recipient, or reply-to mailbox contains a non-ASCII character.  A supporting
+server must advertise both `SMTPUTF8` and `8BITMIME`; Upyo then sends
+`BODY=8BITMIME SMTPUTF8` on `MAIL FROM`.
+
+If either capability is missing, delivery returns a non-retryable failed
+receipt with the code `smtp.smtputf8-unsupported` before the mail transaction
+starts.  Unicode display names and subjects continue to use RFC 2047 encoding
+and do not require SMTPUTF8 when the mailbox addresses remain ASCII-only.
+
+[RFC 6531]: https://www.rfc-editor.org/rfc/rfc6531
+
+
 Delivery status notifications
 -----------------------------
 

package/dist/index.cjs

@@ -501,6 +501,29 @@ var SmtpMessageSizeError = class extends RangeError {
 		this.maximumSize = maximumSize;
 	}
 };
+/**
+* Error thrown when an internationalized message requires an SMTP extension
+* that the server did not advertise.
+*
+* The check happens before `MAIL FROM`, so the SMTP connection remains usable
+* for another message.
+*
+* @since 0.6.0
+*/
+var SmtpUtf8UnsupportedError = class extends Error {
+	/** The required SMTP extension that the server did not advertise. */
+	missingCapability;
+	/**
+	* Creates an SMTPUTF8 support error.
+	*
+	* @param missingCapability The required extension that was not advertised.
+	*/
+	constructor(missingCapability) {
+		super(missingCapability === "SMTPUTF8" ? "The SMTP server does not advertise SMTPUTF8." : "The SMTP server advertises SMTPUTF8 without the required 8BITMIME capability.");
+		this.name = "SmtpUtf8UnsupportedError";
+		this.missingCapability = missingCapability;
+	}
+};
 var SmtpPipelineTerminatedError = class extends Error {
 	responseIndex;
 	response;
@@ -974,6 +997,12 @@ var SmtpConnection = class {
 	}
 	async sendMessage(message, signal) {
 		signal?.throwIfAborted();
+		let smtpUtf8Parameters = "";
+		if (message.requiresSmtpUtf8 === true) {
+			if (!this.capabilities.some((capability) => /^SMTPUTF8(?:[ \t]|$)/i.test(capability))) throw new SmtpUtf8UnsupportedError("SMTPUTF8");
+			if (!this.capabilities.some((capability) => /^8BITMIME(?:[ \t]|$)/i.test(capability))) throw new SmtpUtf8UnsupportedError("8BITMIME");
+			smtpUtf8Parameters = " BODY=8BITMIME SMTPUTF8";
+		}
 		const sizeCapability = parseSizeCapability(this.capabilities);
 		let sizeParameter = "";
 		if (sizeCapability != null) {
@@ -984,7 +1013,7 @@ var SmtpConnection = class {
 		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 mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
 		const recipientCommands = message.envelope.to.map((recipient, index) => {
 			const parameters = dsn?.recipientParameters[index] ?? [];
 			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
@@ -1431,6 +1460,13 @@ async function convertMessage(message, dkimConfig, dsn) {
 		],
 		dsn
 	};
+	const requiresSmtpUtf8 = [
+		message.sender,
+		...message.recipients,
+		...message.ccRecipients,
+		...message.bccRecipients,
+		...message.replyRecipients
+	].some((address) => Array.from(address.address).some((character) => (character.codePointAt(0) ?? 0) > 127));
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
 		for (const sig of dkimConfig.signatures) {
@@ -1443,7 +1479,8 @@ async function convertMessage(message, dkimConfig, dsn) {
 	}
 	return {
 		envelope,
-		raw
+		raw,
+		requiresSmtpUtf8
 	};
 }
 async function buildRawMessage(message) {
@@ -1614,7 +1651,7 @@ function foldHeader(name, value) {
 		remaining = remaining.slice(whitespaceEnd);
 	}
 	lines.push(prefix + remaining);
-	if (lines.some((line) => line.length > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
+	if (lines.some((line) => node_buffer.Buffer.byteLength(line, "utf8") > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
 	return lines.join("\r\n");
 }
 function encodeQuotedPrintable(text) {
@@ -1972,6 +2009,14 @@ function createSmtpFailure(message, error) {
 			maximumSize: error.maximumSize.toString()
 		}
 	});
+	if (error instanceof SmtpUtf8UnsupportedError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "smtp",
+		code: "smtp.smtputf8-unsupported",
+		category: "configuration",
+		retryable: false,
+		attempts: 1,
+		providerDetails: { missingCapability: error.missingCapability }
+	});
 	if (error instanceof SmtpResponseError) {
 		const classification = classifySmtpReply(error.code);
 		return (0, __upyo_core.createFailedReceipt)(message, {
@@ -1993,7 +2038,7 @@ function createSmtpFailure(message, error) {
 	});
 }
 function isReusableLocalFailure(error) {
-	return error instanceof SmtpMessageSizeError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
 }
 function classifySmtpReply(code) {
 	if (code >= 400 && code < 500) return {

package/dist/index.js

@@ -478,6 +478,29 @@ var SmtpMessageSizeError = class extends RangeError {
 		this.maximumSize = maximumSize;
 	}
 };
+/**
+* Error thrown when an internationalized message requires an SMTP extension
+* that the server did not advertise.
+*
+* The check happens before `MAIL FROM`, so the SMTP connection remains usable
+* for another message.
+*
+* @since 0.6.0
+*/
+var SmtpUtf8UnsupportedError = class extends Error {
+	/** The required SMTP extension that the server did not advertise. */
+	missingCapability;
+	/**
+	* Creates an SMTPUTF8 support error.
+	*
+	* @param missingCapability The required extension that was not advertised.
+	*/
+	constructor(missingCapability) {
+		super(missingCapability === "SMTPUTF8" ? "The SMTP server does not advertise SMTPUTF8." : "The SMTP server advertises SMTPUTF8 without the required 8BITMIME capability.");
+		this.name = "SmtpUtf8UnsupportedError";
+		this.missingCapability = missingCapability;
+	}
+};
 var SmtpPipelineTerminatedError = class extends Error {
 	responseIndex;
 	response;
@@ -951,6 +974,12 @@ var SmtpConnection = class {
 	}
 	async sendMessage(message, signal) {
 		signal?.throwIfAborted();
+		let smtpUtf8Parameters = "";
+		if (message.requiresSmtpUtf8 === true) {
+			if (!this.capabilities.some((capability) => /^SMTPUTF8(?:[ \t]|$)/i.test(capability))) throw new SmtpUtf8UnsupportedError("SMTPUTF8");
+			if (!this.capabilities.some((capability) => /^8BITMIME(?:[ \t]|$)/i.test(capability))) throw new SmtpUtf8UnsupportedError("8BITMIME");
+			smtpUtf8Parameters = " BODY=8BITMIME SMTPUTF8";
+		}
 		const sizeCapability = parseSizeCapability(this.capabilities);
 		let sizeParameter = "";
 		if (sizeCapability != null) {
@@ -961,7 +990,7 @@ var SmtpConnection = class {
 		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 mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
 		const recipientCommands = message.envelope.to.map((recipient, index) => {
 			const parameters = dsn?.recipientParameters[index] ?? [];
 			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
@@ -1408,6 +1437,13 @@ async function convertMessage(message, dkimConfig, dsn) {
 		],
 		dsn
 	};
+	const requiresSmtpUtf8 = [
+		message.sender,
+		...message.recipients,
+		...message.ccRecipients,
+		...message.bccRecipients,
+		...message.replyRecipients
+	].some((address) => Array.from(address.address).some((character) => (character.codePointAt(0) ?? 0) > 127));
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
 		for (const sig of dkimConfig.signatures) {
@@ -1420,7 +1456,8 @@ async function convertMessage(message, dkimConfig, dsn) {
 	}
 	return {
 		envelope,
-		raw
+		raw,
+		requiresSmtpUtf8
 	};
 }
 async function buildRawMessage(message) {
@@ -1591,7 +1628,7 @@ function foldHeader(name, value) {
 		remaining = remaining.slice(whitespaceEnd);
 	}
 	lines.push(prefix + remaining);
-	if (lines.some((line) => line.length > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
+	if (lines.some((line) => Buffer.byteLength(line, "utf8") > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
 	return lines.join("\r\n");
 }
 function encodeQuotedPrintable(text) {
@@ -1949,6 +1986,14 @@ function createSmtpFailure(message, error) {
 			maximumSize: error.maximumSize.toString()
 		}
 	});
+	if (error instanceof SmtpUtf8UnsupportedError) return createFailedReceipt(message, {
+		provider: "smtp",
+		code: "smtp.smtputf8-unsupported",
+		category: "configuration",
+		retryable: false,
+		attempts: 1,
+		providerDetails: { missingCapability: error.missingCapability }
+	});
 	if (error instanceof SmtpResponseError) {
 		const classification = classifySmtpReply(error.code);
 		return createFailedReceipt(message, {
@@ -1970,7 +2015,7 @@ function createSmtpFailure(message, error) {
 	});
 }
 function isReusableLocalFailure(error) {
-	return error instanceof SmtpMessageSizeError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
 }
 function classifySmtpReply(code) {
 	if (code >= 400 && code < 500) return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.6.0-dev.295",
+  "version": "0.6.0-dev.296",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.295+d64d0d8f"
+    "@upyo/core": "0.6.0-dev.296+edf6b8c1"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",