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

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
+ -  Structured SMTP enhanced status codes
  -  SMTPUTF8 internationalized address delivery
  -  SMTP delivery status notification requests
  -  Custom headers
@@ -184,6 +185,40 @@ See [RFC 1870] for the SMTP Message Size Declaration extension.
 [RFC 1870]: https://www.rfc-editor.org/rfc/rfc1870
 
 
+Enhanced status codes
+---------------------
+
+SMTP failures include a parsed enhanced status code when the server prefixes
+its reply text with a valid RFC 2034 code such as `5.1.1`.  The final reply
+line's text remains in `providerDetails.response`, while
+`providerDetails.enhancedStatusCode` provides the complete code and its numeric
+`class`, `subject`, and `detail` fields.  Address and message-content statuses
+are categorized as validation failures, and network/routing statuses as network
+failures.
+
+Use `isSmtpResponseProviderDetails()` to narrow the provider-specific details:
+
+~~~~ typescript
+import { isSmtpResponseProviderDetails } from "@upyo/smtp";
+
+const error = receipt.successful ? undefined : receipt.errors?.[0];
+if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+  console.log(error.providerDetails.enhancedStatusCode?.subject);
+}
+~~~~
+
+Partially rejected recipients expose the same structure through
+`receipt.rejectedRecipients[].enhancedStatusCode`.  Replies without an enhanced
+code, with malformed fields, or with a class that conflicts with the
+three-digit SMTP reply continue to use the traditional reply classification.
+
+See [RFC 2034] for the SMTP extension and [RFC 3463] for the status-code
+structure.
+
+[RFC 2034]: https://www.rfc-editor.org/rfc/rfc2034
+[RFC 3463]: https://www.rfc-editor.org/rfc/rfc3463
+
+
 Internationalized addresses
 ---------------------------
 

package/dist/index.cjs

@@ -472,6 +472,34 @@ var OAuth2TokenManager = class {
 	}
 };
 
+//#endregion
+//#region src/smtp-status-code.ts
+/**
+* Parses an enhanced SMTP status code from the beginning of reply text.
+*
+* RFC 2034 requires the enhanced class to agree with the three-digit SMTP
+* reply class.  RFC 3463 also prohibits leading zeroes and limits the subject
+* and detail fields to three digits.
+*
+* @param replyCode The three-digit SMTP reply code.
+* @param response The textual part of the SMTP reply.
+* @returns The parsed enhanced status code, or `undefined` when the reply does
+*          not begin with a valid, consistent code.
+* @since 0.6.0
+*/
+function parseEnhancedSmtpStatusCode(replyCode, response) {
+	const match = /^([245])\.((?:0|[1-9][0-9]{0,2}))\.((?:0|[1-9][0-9]{0,2})) +/.exec(response);
+	if (match == null) return void 0;
+	const statusClass = Number(match[1]);
+	if (Math.trunc(replyCode / 100) !== statusClass) return void 0;
+	return {
+		code: `${match[1]}.${match[2]}.${match[3]}`,
+		class: statusClass,
+		subject: Number(match[2]),
+		detail: Number(match[3])
+	};
+}
+
 //#endregion
 //#region src/smtp-connection.ts
 /**
@@ -1043,12 +1071,16 @@ var SmtpConnection = class {
 			signal?.throwIfAborted();
 			const rcptResponse = pipelining ? recipientResponses[index] : await this.sendCommand(recipientCommands[index], signal);
 			if (rcptResponse.code === 421) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
-			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) rejectedRecipients.push({
-				recipient,
-				code: rcptResponse.code,
-				response: rcptResponse.message,
-				retryable: rcptResponse.code >= 400 && rcptResponse.code < 500
-			});
+			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) {
+				const enhancedStatusCode = parseEnhancedSmtpStatusCode(rcptResponse.code, rcptResponse.message);
+				rejectedRecipients.push({
+					recipient,
+					code: rcptResponse.code,
+					response: rcptResponse.message,
+					retryable: rcptResponse.code >= 400 && rcptResponse.code < 500,
+					...enhancedStatusCode == null ? {} : { enhancedStatusCode }
+				});
+			}
 		}
 		if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
 			const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
@@ -2018,7 +2050,8 @@ function createSmtpFailure(message, error) {
 		providerDetails: { missingCapability: error.missingCapability }
 	});
 	if (error instanceof SmtpResponseError) {
-		const classification = classifySmtpReply(error.code);
+		const enhancedStatusCode = parseEnhancedSmtpStatusCode(error.code, error.response);
+		const classification = classifySmtpReply(error.code, enhancedStatusCode);
 		return (0, __upyo_core.createFailedReceipt)(message, {
 			provider: "smtp",
 			code: `smtp.${error.code}`,
@@ -2028,7 +2061,8 @@ function createSmtpFailure(message, error) {
 			providerDetails: {
 				command: error.command,
 				response: error.response,
-				rejectedRecipients: error.rejectedRecipients
+				rejectedRecipients: error.rejectedRecipients,
+				...enhancedStatusCode == null ? {} : { enhancedStatusCode }
 			}
 		});
 	}
@@ -2040,14 +2074,23 @@ function createSmtpFailure(message, error) {
 function isReusableLocalFailure(error) {
 	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
 }
-function classifySmtpReply(code) {
+function classifySmtpReply(code, enhancedStatusCode) {
+	const retryable = enhancedStatusCode == null ? code >= 400 && code < 500 : enhancedStatusCode.class === 4;
+	if (enhancedStatusCode?.subject === 1 || enhancedStatusCode?.subject === 6) return {
+		category: "validation",
+		retryable
+	};
+	if (enhancedStatusCode?.subject === 4) return {
+		category: "network",
+		retryable
+	};
 	if (code >= 400 && code < 500) return {
 		category: "service-unavailable",
-		retryable: true
+		retryable
 	};
 	if (code >= 500 && code < 600) return {
 		category: "rejected",
-		retryable: false
+		retryable
 	};
 	return {
 		category: "unknown",
@@ -2055,8 +2098,22 @@ function classifySmtpReply(code) {
 	};
 }
 
+//#endregion
+//#region src/smtp-receipt.ts
+/**
+* Checks whether provider details came from an SMTP server response.
+*
+* @param value Provider details from an SMTP receipt error.
+* @returns Whether the value contains SMTP response details.
+* @since 0.6.0
+*/
+function isSmtpResponseProviderDetails(value) {
+	return value != null && typeof value === "object" && "command" in value && typeof value.command === "string" && "response" in value && typeof value.response === "string";
+}
+
 //#endregion
 exports.SmtpAuthError = SmtpAuthError;
 exports.SmtpDsnUnsupportedError = SmtpDsnUnsupportedError;
 exports.SmtpDsnValidationError = SmtpDsnValidationError;
-exports.SmtpTransport = SmtpTransport;
+exports.SmtpTransport = SmtpTransport;
+exports.isSmtpResponseProviderDetails = isSmtpResponseProviderDetails;

package/dist/index.d.cts

@@ -510,6 +510,21 @@ declare class SmtpDsnUnsupportedError extends Error {
 /** @internal */
 //#endregion
 //#region src/smtp-receipt.d.ts
+/**
+ * A machine-readable enhanced SMTP status code defined by RFC 3463.
+ *
+ * @since 0.6.0
+ */
+interface SmtpEnhancedStatusCode {
+  /** The complete enhanced status code. */
+  readonly code: string;
+  /** The delivery result class: success, transient failure, or permanent failure. */
+  readonly class: 2 | 4 | 5;
+  /** The subject identifying the probable source of the condition. */
+  readonly subject: number;
+  /** The detail identifying the precise condition. */
+  readonly detail: number;
+}
 /**
  * An SMTP envelope recipient that the server rejected during an otherwise
  * successful delivery.
@@ -525,7 +540,62 @@ interface SmtpRejectedRecipient {
   readonly response: string;
   /** Whether retrying delivery to this recipient may succeed. */
   readonly retryable: boolean;
+  /**
+   * The enhanced status code returned for this recipient, when valid.
+   *
+   * @since 0.6.0
+   */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
 }
+/**
+ * Provider details for a failure returned by an SMTP server.
+ *
+ * @since 0.6.0
+ */
+interface SmtpResponseProviderDetails {
+  /** The SMTP command that failed. */
+  readonly command: string;
+  /** The text from the SMTP server's final reply line. */
+  readonly response: string;
+  /** Recipient-level failures collected for the transaction. */
+  readonly rejectedRecipients?: readonly SmtpRejectedRecipient[];
+  /** The enhanced status code in the server reply, when valid. */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
+}
+/**
+ * Checks whether provider details came from an SMTP server response.
+ *
+ * @param value Provider details from an SMTP receipt error.
+ * @returns Whether the value contains SMTP response details.
+ * @since 0.6.0
+ */
+declare function isSmtpResponseProviderDetails(value: unknown): value is SmtpResponseProviderDetails;
+/**
+ * Provider details for a locally rejected oversized message.
+ *
+ * @since 0.6.0
+ */
+interface SmtpMessageSizeProviderDetails {
+  /** The encoded message size in octets. */
+  readonly actualSize: number;
+  /** The server's advertised maximum size in octets. */
+  readonly maximumSize: string;
+}
+/**
+ * Provider details for a missing internationalization capability.
+ *
+ * @since 0.6.0
+ */
+interface SmtpUtf8ProviderDetails {
+  /** The SMTP extension required by the message. */
+  readonly missingCapability: "SMTPUTF8" | "8BITMIME";
+}
+/**
+ * Provider-specific details attached to SMTP receipt errors.
+ *
+ * @since 0.6.0
+ */
+type SmtpProviderDetails = SmtpResponseProviderDetails | SmtpMessageSizeProviderDetails | SmtpUtf8ProviderDetails;
 /**
  * A receipt returned by {@link SmtpTransport}.
  *
@@ -727,4 +797,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };

package/dist/index.d.ts

@@ -510,6 +510,21 @@ declare class SmtpDsnUnsupportedError extends Error {
 /** @internal */
 //#endregion
 //#region src/smtp-receipt.d.ts
+/**
+ * A machine-readable enhanced SMTP status code defined by RFC 3463.
+ *
+ * @since 0.6.0
+ */
+interface SmtpEnhancedStatusCode {
+  /** The complete enhanced status code. */
+  readonly code: string;
+  /** The delivery result class: success, transient failure, or permanent failure. */
+  readonly class: 2 | 4 | 5;
+  /** The subject identifying the probable source of the condition. */
+  readonly subject: number;
+  /** The detail identifying the precise condition. */
+  readonly detail: number;
+}
 /**
  * An SMTP envelope recipient that the server rejected during an otherwise
  * successful delivery.
@@ -525,7 +540,62 @@ interface SmtpRejectedRecipient {
   readonly response: string;
   /** Whether retrying delivery to this recipient may succeed. */
   readonly retryable: boolean;
+  /**
+   * The enhanced status code returned for this recipient, when valid.
+   *
+   * @since 0.6.0
+   */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
 }
+/**
+ * Provider details for a failure returned by an SMTP server.
+ *
+ * @since 0.6.0
+ */
+interface SmtpResponseProviderDetails {
+  /** The SMTP command that failed. */
+  readonly command: string;
+  /** The text from the SMTP server's final reply line. */
+  readonly response: string;
+  /** Recipient-level failures collected for the transaction. */
+  readonly rejectedRecipients?: readonly SmtpRejectedRecipient[];
+  /** The enhanced status code in the server reply, when valid. */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
+}
+/**
+ * Checks whether provider details came from an SMTP server response.
+ *
+ * @param value Provider details from an SMTP receipt error.
+ * @returns Whether the value contains SMTP response details.
+ * @since 0.6.0
+ */
+declare function isSmtpResponseProviderDetails(value: unknown): value is SmtpResponseProviderDetails;
+/**
+ * Provider details for a locally rejected oversized message.
+ *
+ * @since 0.6.0
+ */
+interface SmtpMessageSizeProviderDetails {
+  /** The encoded message size in octets. */
+  readonly actualSize: number;
+  /** The server's advertised maximum size in octets. */
+  readonly maximumSize: string;
+}
+/**
+ * Provider details for a missing internationalization capability.
+ *
+ * @since 0.6.0
+ */
+interface SmtpUtf8ProviderDetails {
+  /** The SMTP extension required by the message. */
+  readonly missingCapability: "SMTPUTF8" | "8BITMIME";
+}
+/**
+ * Provider-specific details attached to SMTP receipt errors.
+ *
+ * @since 0.6.0
+ */
+type SmtpProviderDetails = SmtpResponseProviderDetails | SmtpMessageSizeProviderDetails | SmtpUtf8ProviderDetails;
 /**
  * A receipt returned by {@link SmtpTransport}.
  *
@@ -727,4 +797,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };

package/dist/index.js

@@ -449,6 +449,34 @@ var OAuth2TokenManager = class {
 	}
 };
 
+//#endregion
+//#region src/smtp-status-code.ts
+/**
+* Parses an enhanced SMTP status code from the beginning of reply text.
+*
+* RFC 2034 requires the enhanced class to agree with the three-digit SMTP
+* reply class.  RFC 3463 also prohibits leading zeroes and limits the subject
+* and detail fields to three digits.
+*
+* @param replyCode The three-digit SMTP reply code.
+* @param response The textual part of the SMTP reply.
+* @returns The parsed enhanced status code, or `undefined` when the reply does
+*          not begin with a valid, consistent code.
+* @since 0.6.0
+*/
+function parseEnhancedSmtpStatusCode(replyCode, response) {
+	const match = /^([245])\.((?:0|[1-9][0-9]{0,2}))\.((?:0|[1-9][0-9]{0,2})) +/.exec(response);
+	if (match == null) return void 0;
+	const statusClass = Number(match[1]);
+	if (Math.trunc(replyCode / 100) !== statusClass) return void 0;
+	return {
+		code: `${match[1]}.${match[2]}.${match[3]}`,
+		class: statusClass,
+		subject: Number(match[2]),
+		detail: Number(match[3])
+	};
+}
+
 //#endregion
 //#region src/smtp-connection.ts
 /**
@@ -1020,12 +1048,16 @@ var SmtpConnection = class {
 			signal?.throwIfAborted();
 			const rcptResponse = pipelining ? recipientResponses[index] : await this.sendCommand(recipientCommands[index], signal);
 			if (rcptResponse.code === 421) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
-			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) rejectedRecipients.push({
-				recipient,
-				code: rcptResponse.code,
-				response: rcptResponse.message,
-				retryable: rcptResponse.code >= 400 && rcptResponse.code < 500
-			});
+			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) {
+				const enhancedStatusCode = parseEnhancedSmtpStatusCode(rcptResponse.code, rcptResponse.message);
+				rejectedRecipients.push({
+					recipient,
+					code: rcptResponse.code,
+					response: rcptResponse.message,
+					retryable: rcptResponse.code >= 400 && rcptResponse.code < 500,
+					...enhancedStatusCode == null ? {} : { enhancedStatusCode }
+				});
+			}
 		}
 		if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
 			const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
@@ -1995,7 +2027,8 @@ function createSmtpFailure(message, error) {
 		providerDetails: { missingCapability: error.missingCapability }
 	});
 	if (error instanceof SmtpResponseError) {
-		const classification = classifySmtpReply(error.code);
+		const enhancedStatusCode = parseEnhancedSmtpStatusCode(error.code, error.response);
+		const classification = classifySmtpReply(error.code, enhancedStatusCode);
 		return createFailedReceipt(message, {
 			provider: "smtp",
 			code: `smtp.${error.code}`,
@@ -2005,7 +2038,8 @@ function createSmtpFailure(message, error) {
 			providerDetails: {
 				command: error.command,
 				response: error.response,
-				rejectedRecipients: error.rejectedRecipients
+				rejectedRecipients: error.rejectedRecipients,
+				...enhancedStatusCode == null ? {} : { enhancedStatusCode }
 			}
 		});
 	}
@@ -2017,14 +2051,23 @@ function createSmtpFailure(message, error) {
 function isReusableLocalFailure(error) {
 	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
 }
-function classifySmtpReply(code) {
+function classifySmtpReply(code, enhancedStatusCode) {
+	const retryable = enhancedStatusCode == null ? code >= 400 && code < 500 : enhancedStatusCode.class === 4;
+	if (enhancedStatusCode?.subject === 1 || enhancedStatusCode?.subject === 6) return {
+		category: "validation",
+		retryable
+	};
+	if (enhancedStatusCode?.subject === 4) return {
+		category: "network",
+		retryable
+	};
 	if (code >= 400 && code < 500) return {
 		category: "service-unavailable",
-		retryable: true
+		retryable
 	};
 	if (code >= 500 && code < 600) return {
 		category: "rejected",
-		retryable: false
+		retryable
 	};
 	return {
 		category: "unknown",
@@ -2033,4 +2076,17 @@ function classifySmtpReply(code) {
 }
 
 //#endregion
-export { SmtpAuthError, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpTransport };
+//#region src/smtp-receipt.ts
+/**
+* Checks whether provider details came from an SMTP server response.
+*
+* @param value Provider details from an SMTP receipt error.
+* @returns Whether the value contains SMTP response details.
+* @since 0.6.0
+*/
+function isSmtpResponseProviderDetails(value) {
+	return value != null && typeof value === "object" && "command" in value && typeof value.command === "string" && "response" in value && typeof value.response === "string";
+}
+
+//#endregion
+export { SmtpAuthError, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpTransport, isSmtpResponseProviderDetails };

package/package.json

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