@upyo/core 0.5.0-dev.86 → 0.5.0

package/README.md

@@ -108,27 +108,57 @@ function handleReceipt(receipt: Receipt) {
     console.log("Message sent with ID:", receipt.messageId);
   } else {
     console.error("Send failed:", receipt.errorMessages.join(", "));
+    console.error("Retryable:", receipt.retryable ?? false);
+
+    for (const error of receipt.errors ?? []) {
+      console.error(error.category, error.code, error.provider);
+    }
   }
 }
 ~~~~
 
-### Implementing custom transports
+Failed receipts keep the legacy `errorMessages` array and can also carry
+structured `errors` for programmatic handling.  Transports use categories such
+as `auth`, `rate-limit`, `network`, `timeout`, `validation`, `rejected`,
+`server-error`, `service-unavailable`, `configuration`, and `unknown`.
+
+When implementing a transport, use `createFailedReceipt()` to keep these fields
+consistent:
+
+~~~~ typescript
+import { createFailedReceipt } from "@upyo/core";
+
+const receipt = createFailedReceipt("HTTP 429: Too Many Requests", {
+  provider: "example",
+  statusCode: 429,
+  retryAfterMilliseconds: 30_000,
+});
+~~~~
+
+
+Implementing custom transports
+------------------------------
 
 The `Transport` interface defines the contract for all email providers:
 
 ~~~~ typescript
 import type { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
 
-class MyCustomTransport implements Transport {
-  async send(message: Message, options?: TransportOptions): Promise<Receipt> {
+class MyCustomTransport implements Transport<"example"> {
+  readonly id = "example";
+
+  async send(
+    message: Message,
+    options?: TransportOptions,
+  ): Promise<Receipt<"example">> {
     // Implementation details...
-    return { successful: true, messageId: "12345" };
+    return { successful: true, messageId: "12345", provider: this.id };
   }
 
   async *sendMany(
     messages: Iterable<Message> | AsyncIterable<Message>,
     options?: TransportOptions,
-  ): AsyncIterable<Receipt> {
+  ): AsyncIterable<Receipt<"example">> {
     for await (const message of messages) {
       yield await this.send(message, options);
     }

package/dist/abort-signal.cjs

@@ -0,0 +1,53 @@
+
+//#region src/abort-signal.ts
+/**
+* Combines a primary abort signal with an optional external signal.
+*
+* The returned signal aborts as soon as either input signal aborts.  Runtimes
+* with `AbortSignal.any()` use the platform implementation; older runtimes use
+* a listener-based fallback that preserves the original abort reason.
+*
+* @param primarySignal The signal owned by the current operation.
+* @param externalSignal Optional caller-supplied signal to compose.
+* @returns A combined signal and cleanup callback.
+* @since 0.5.0
+*/
+function combineSignals(primarySignal, externalSignal) {
+	if (externalSignal == null) return {
+		signal: primarySignal,
+		cleanup: () => {}
+	};
+	if (typeof AbortSignal.any === "function") return {
+		signal: AbortSignal.any([primarySignal, externalSignal]),
+		cleanup: () => {}
+	};
+	const controller = new AbortController();
+	const cleanup = () => {
+		primarySignal.removeEventListener("abort", abortFromPrimary);
+		externalSignal.removeEventListener("abort", abortFromExternal);
+	};
+	const abortFromPrimary = () => {
+		cleanup();
+		controller.abort(getAbortReason(primarySignal));
+	};
+	const abortFromExternal = () => {
+		cleanup();
+		controller.abort(getAbortReason(externalSignal));
+	};
+	if (primarySignal.aborted) controller.abort(getAbortReason(primarySignal));
+	else if (externalSignal.aborted) controller.abort(getAbortReason(externalSignal));
+	else {
+		primarySignal.addEventListener("abort", abortFromPrimary, { once: true });
+		externalSignal.addEventListener("abort", abortFromExternal, { once: true });
+	}
+	return {
+		signal: controller.signal,
+		cleanup
+	};
+}
+function getAbortReason(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+
+//#endregion
+exports.combineSignals = combineSignals;

package/dist/abort-signal.d.cts

@@ -0,0 +1,32 @@
+//#region src/abort-signal.d.ts
+/**
+ * Result of combining abort signals.
+ *
+ * @since 0.5.0
+ */
+interface CombinedSignal {
+  /**
+   * The signal that aborts when any input signal aborts.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Removes fallback abort listeners when signal composition no longer needs
+   * them.
+   */
+  cleanup(): void;
+}
+/**
+ * Combines a primary abort signal with an optional external signal.
+ *
+ * The returned signal aborts as soon as either input signal aborts.  Runtimes
+ * with `AbortSignal.any()` use the platform implementation; older runtimes use
+ * a listener-based fallback that preserves the original abort reason.
+ *
+ * @param primarySignal The signal owned by the current operation.
+ * @param externalSignal Optional caller-supplied signal to compose.
+ * @returns A combined signal and cleanup callback.
+ * @since 0.5.0
+ */
+declare function combineSignals(primarySignal: AbortSignal, externalSignal?: AbortSignal | null): CombinedSignal;
+//#endregion
+export { CombinedSignal, combineSignals };

package/dist/abort-signal.d.ts

@@ -0,0 +1,32 @@
+//#region src/abort-signal.d.ts
+/**
+ * Result of combining abort signals.
+ *
+ * @since 0.5.0
+ */
+interface CombinedSignal {
+  /**
+   * The signal that aborts when any input signal aborts.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Removes fallback abort listeners when signal composition no longer needs
+   * them.
+   */
+  cleanup(): void;
+}
+/**
+ * Combines a primary abort signal with an optional external signal.
+ *
+ * The returned signal aborts as soon as either input signal aborts.  Runtimes
+ * with `AbortSignal.any()` use the platform implementation; older runtimes use
+ * a listener-based fallback that preserves the original abort reason.
+ *
+ * @param primarySignal The signal owned by the current operation.
+ * @param externalSignal Optional caller-supplied signal to compose.
+ * @returns A combined signal and cleanup callback.
+ * @since 0.5.0
+ */
+declare function combineSignals(primarySignal: AbortSignal, externalSignal?: AbortSignal | null): CombinedSignal;
+//#endregion
+export { CombinedSignal, combineSignals };

package/dist/abort-signal.js

@@ -0,0 +1,52 @@
+//#region src/abort-signal.ts
+/**
+* Combines a primary abort signal with an optional external signal.
+*
+* The returned signal aborts as soon as either input signal aborts.  Runtimes
+* with `AbortSignal.any()` use the platform implementation; older runtimes use
+* a listener-based fallback that preserves the original abort reason.
+*
+* @param primarySignal The signal owned by the current operation.
+* @param externalSignal Optional caller-supplied signal to compose.
+* @returns A combined signal and cleanup callback.
+* @since 0.5.0
+*/
+function combineSignals(primarySignal, externalSignal) {
+	if (externalSignal == null) return {
+		signal: primarySignal,
+		cleanup: () => {}
+	};
+	if (typeof AbortSignal.any === "function") return {
+		signal: AbortSignal.any([primarySignal, externalSignal]),
+		cleanup: () => {}
+	};
+	const controller = new AbortController();
+	const cleanup = () => {
+		primarySignal.removeEventListener("abort", abortFromPrimary);
+		externalSignal.removeEventListener("abort", abortFromExternal);
+	};
+	const abortFromPrimary = () => {
+		cleanup();
+		controller.abort(getAbortReason(primarySignal));
+	};
+	const abortFromExternal = () => {
+		cleanup();
+		controller.abort(getAbortReason(externalSignal));
+	};
+	if (primarySignal.aborted) controller.abort(getAbortReason(primarySignal));
+	else if (externalSignal.aborted) controller.abort(getAbortReason(externalSignal));
+	else {
+		primarySignal.addEventListener("abort", abortFromPrimary, { once: true });
+		externalSignal.addEventListener("abort", abortFromExternal, { once: true });
+	}
+	return {
+		signal: controller.signal,
+		cleanup
+	};
+}
+function getAbortReason(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+
+//#endregion
+export { combineSignals };

package/dist/index.cjs

@@ -1,11 +1,19 @@
+const require_abort_signal = require('./abort-signal.cjs');
 const require_address = require('./address.cjs');
 const require_attachment = require('./attachment.cjs');
 const require_message = require('./message.cjs');
 const require_priority = require('./priority.cjs');
+const require_receipt = require('./receipt.cjs');
 
+exports.classifyHttpStatus = require_receipt.classifyHttpStatus;
+exports.classifyReceiptError = require_receipt.classifyReceiptError;
+exports.combineSignals = require_abort_signal.combineSignals;
 exports.comparePriority = require_priority.comparePriority;
+exports.createFailedReceipt = require_receipt.createFailedReceipt;
 exports.createMessage = require_message.createMessage;
+exports.createReceiptError = require_receipt.createReceiptError;
 exports.formatAddress = require_address.formatAddress;
 exports.isAttachment = require_attachment.isAttachment;
 exports.isEmailAddress = require_address.isEmailAddress;
-exports.parseAddress = require_address.parseAddress;
+exports.parseAddress = require_address.parseAddress;
+exports.parseRetryAfter = require_receipt.parseRetryAfter;

package/dist/index.d.cts

@@ -1,7 +1,8 @@
+import { CombinedSignal, combineSignals } from "./abort-signal.cjs";
 import { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress } from "./address.cjs";
 import { Attachment, isAttachment } from "./attachment.cjs";
 import { Priority, comparePriority } from "./priority.cjs";
 import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.cjs";
-import { Receipt } from "./receipt.cjs";
+import { CreateFailedReceiptOptions, CreateReceiptErrorOptions, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter } from "./receipt.cjs";
 import { Transport, TransportOptions } from "./transport.cjs";
-export { Address, Attachment, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };
+export { Address, Attachment, CombinedSignal, CreateFailedReceiptOptions, CreateReceiptErrorOptions, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, Transport, TransportOptions, classifyHttpStatus, classifyReceiptError, combineSignals, comparePriority, createFailedReceipt, createMessage, createReceiptError, formatAddress, isAttachment, isEmailAddress, parseAddress, parseRetryAfter };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
+import { CombinedSignal, combineSignals } from "./abort-signal.js";
 import { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress } from "./address.js";
 import { Attachment, isAttachment } from "./attachment.js";
 import { Priority, comparePriority } from "./priority.js";
 import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.js";
-import { Receipt } from "./receipt.js";
+import { CreateFailedReceiptOptions, CreateReceiptErrorOptions, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter } from "./receipt.js";
 import { Transport, TransportOptions } from "./transport.js";
-export { Address, Attachment, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };
+export { Address, Attachment, CombinedSignal, CreateFailedReceiptOptions, CreateReceiptErrorOptions, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, Transport, TransportOptions, classifyHttpStatus, classifyReceiptError, combineSignals, comparePriority, createFailedReceipt, createMessage, createReceiptError, formatAddress, isAttachment, isEmailAddress, parseAddress, parseRetryAfter };

package/dist/index.js

@@ -1,6 +1,8 @@
+import { combineSignals } from "./abort-signal.js";
 import { formatAddress, isEmailAddress, parseAddress } from "./address.js";
 import { isAttachment } from "./attachment.js";
 import { createMessage } from "./message.js";
 import { comparePriority } from "./priority.js";
+import { classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter } from "./receipt.js";
 
-export { comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };
+export { classifyHttpStatus, classifyReceiptError, combineSignals, comparePriority, createFailedReceipt, createMessage, createReceiptError, formatAddress, isAttachment, isEmailAddress, parseAddress, parseRetryAfter };

package/dist/receipt.cjs

@@ -0,0 +1,184 @@
+
+//#region src/receipt.ts
+/**
+* Classifies an HTTP status code for delivery error handling.
+*
+* @param statusCode The HTTP status code to classify.
+* @returns The receipt error category and retryability.
+* @since 0.5.0
+*/
+function classifyHttpStatus(statusCode) {
+	if (statusCode === 401 || statusCode === 403) return {
+		category: "auth",
+		retryable: false
+	};
+	if (statusCode === 408 || statusCode === 504) return {
+		category: "timeout",
+		retryable: true
+	};
+	if (statusCode === 429) return {
+		category: "rate-limit",
+		retryable: true
+	};
+	if (statusCode === 503) return {
+		category: "service-unavailable",
+		retryable: true
+	};
+	if (statusCode >= 400 && statusCode < 500) return {
+		category: "validation",
+		retryable: false
+	};
+	if (statusCode >= 500 && statusCode < 600) return {
+		category: "server-error",
+		retryable: true
+	};
+	return {
+		category: "unknown",
+		retryable: false
+	};
+}
+/**
+* Classifies an arbitrary delivery failure.
+*
+* @param error The error to classify.
+* @returns The receipt error category, retryability, and default code.
+* @since 0.5.0
+*/
+function classifyReceiptError(error) {
+	const message = getStringProperty(error, "message") ?? String(error);
+	const name = getStringProperty(error, "name") ?? "";
+	const text = `${name} ${message}`.toLowerCase();
+	if (text.includes("timeout") || text.includes("timed out")) return {
+		category: "timeout",
+		retryable: true,
+		code: "timeout"
+	};
+	if (text.includes("network") || text.includes("connect") || text.includes("fetch failed") || text.includes("dns") || text.includes("econnreset") || text.includes("econnrefused") || text.includes("enotfound") || name === "NetworkError") return {
+		category: "network",
+		retryable: true,
+		code: "network"
+	};
+	if (text.includes("authentication") || text.includes("authenticate") || text.includes("authorization") || text.includes("authorize") || /\bauth\b/.test(text) || text.includes("unauthorized") || text.includes("not authorized") || text.includes("forbidden") || text.includes("invalid api key") || text.includes("invalid token") || text.includes("401") || text.includes("403")) return {
+		category: "auth",
+		retryable: false,
+		code: "auth"
+	};
+	if (text.includes("rate limit") || text.includes("rate-limit") || text.includes("too many requests") || text.includes("quota") || text.includes("throttle") || text.includes("429")) return {
+		category: "rate-limit",
+		retryable: true,
+		code: "rate-limit"
+	};
+	if (text.includes("invalid") || text.includes("malformed") || text.includes("validation") || text.includes("bad request") || text.includes("400") || text.includes("422")) return {
+		category: "validation",
+		retryable: false,
+		code: "validation"
+	};
+	if (text.includes("rejected") || text.includes("bounce") || text.includes("complaint") || text.includes("suppressed") || text.includes("unsubscribed")) return {
+		category: "rejected",
+		retryable: false,
+		code: "rejected"
+	};
+	if (text.includes("service unavailable") || text.includes("temporarily unavailable") || text.includes("503")) return {
+		category: "service-unavailable",
+		retryable: true,
+		code: "service-unavailable"
+	};
+	if (text.includes("internal server error") || text.includes("bad gateway") || text.includes("500") || text.includes("502")) return {
+		category: "server-error",
+		retryable: true,
+		code: "server-error"
+	};
+	if (text.includes("config") || text.includes("unsupported")) return {
+		category: "configuration",
+		retryable: false,
+		code: "configuration"
+	};
+	return {
+		category: "unknown",
+		retryable: false,
+		code: "unknown"
+	};
+}
+/**
+* Creates structured information about a delivery failure.
+*
+* @param message Human-readable error message.
+* @param options Optional structured error metadata.
+* @returns A structured receipt error.
+* @since 0.5.0
+*/
+function createReceiptError(message, options = {}) {
+	const classification = options.statusCode == null ? classifyReceiptError(message) : classifyHttpStatus(options.statusCode);
+	const category = options.category ?? classification.category;
+	const retryable = options.retryable ?? classification.retryable;
+	const code = options.code ?? (options.statusCode == null ? options.category != null ? category : classification.code ?? category : `http.${options.statusCode}`);
+	return omitUndefined({
+		message,
+		category,
+		code,
+		retryable,
+		provider: options.provider,
+		statusCode: options.statusCode,
+		retryAfterMilliseconds: options.retryAfterMilliseconds,
+		providerDetails: options.providerDetails
+	});
+}
+/**
+* Creates a failed receipt with human-readable and structured errors.
+*
+* @param error Error message, structured error, or list of structured errors.
+* @param options Optional receipt and error metadata.
+* @returns A failed receipt.
+* @since 0.5.0
+*/
+function createFailedReceipt(error, options = {}) {
+	const errors = options.errors ?? (typeof error === "string" ? [createReceiptError(error, options)] : Array.isArray(error) ? error.map((item) => typeof item === "string" ? createReceiptError(item, options) : item) : [error]);
+	const errorMessages = typeof error === "string" ? [error] : Array.isArray(error) ? error.map((item) => typeof item === "string" ? item : item.message) : errors.map((receiptError) => receiptError.message);
+	const retryable = options.retryable ?? errors.some((receiptError) => receiptError.retryable);
+	const provider = options.provider ?? errors[0]?.provider;
+	return omitUndefined({
+		successful: false,
+		errorMessages,
+		errors,
+		retryable,
+		provider,
+		attempts: options.attempts,
+		timestamp: options.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+/**
+* Parses an HTTP `Retry-After` header value into milliseconds.
+*
+* @param value Header value to parse.
+* @param now Current time used when parsing HTTP dates.
+* @returns Retry delay in milliseconds, or `undefined` if invalid.
+* @since 0.5.0
+*/
+function parseRetryAfter(value, now = /* @__PURE__ */ new Date()) {
+	if (value == null || value.trim() === "") return void 0;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const delay$1 = Number(trimmed) * 1e3;
+		return delay$1;
+	}
+	const timestamp = Date.parse(trimmed);
+	if (Number.isNaN(timestamp)) return void 0;
+	const delay = timestamp - now.getTime();
+	return delay > 0 ? delay : void 0;
+}
+function getStringProperty(value, property) {
+	if (value instanceof Error) return value[property];
+	if (typeof value !== "object" || value == null || !(property in value)) return void 0;
+	const propertyValue = value[property];
+	return propertyValue == null ? void 0 : String(propertyValue);
+}
+function omitUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+}
+
+//#endregion
+exports.classifyHttpStatus = classifyHttpStatus;
+exports.classifyReceiptError = classifyReceiptError;
+exports.createFailedReceipt = createFailedReceipt;
+exports.createReceiptError = createReceiptError;
+exports.parseRetryAfter = parseRetryAfter;

package/dist/receipt.d.cts

@@ -1,4 +1,49 @@
 //#region src/receipt.d.ts
+/**
+ * A machine-readable category for an email delivery failure.
+ *
+ * @since 0.5.0
+ */
+type ReceiptErrorCategory = "auth" | "rate-limit" | "network" | "timeout" | "validation" | "rejected" | "server-error" | "service-unavailable" | "configuration" | "unknown";
+/**
+ * Structured information about an email delivery failure.
+ *
+ * @since 0.5.0
+ */
+interface ReceiptError<TProviderId extends string = string> {
+  /**
+   * Human-readable error message.
+   */
+  readonly message: string;
+  /**
+   * Machine-readable provider or protocol error code.
+   */
+  readonly code: string;
+  /**
+   * Coarse error category for programmatic handling.
+   */
+  readonly category: ReceiptErrorCategory;
+  /**
+   * Whether retrying the same message may succeed.
+   */
+  readonly retryable: boolean;
+  /**
+   * Provider or transport that produced this error.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * HTTP status code, when the failure came from an HTTP API.
+   */
+  readonly statusCode?: number;
+  /**
+   * Provider-supplied retry delay in milliseconds, when available.
+   */
+  readonly retryAfterMilliseconds?: number;
+  /**
+   * Provider-specific error details, when available.
+   */
+  readonly providerDetails?: unknown;
+}
 /**
  * The response from the email service after sending an email message.
  *
@@ -6,8 +51,11 @@
  *
  * - Successful sends have a `messageId` but no `errorMessages`
  * - Failed sends have `errorMessages` but no `messageId`
+ *
+ * Failed receipts may also include structured `errors` and summary metadata
+ * for programmatic error handling.
  */
-type Receipt = {
+type Receipt<TProviderId extends string = string> = {
   /**
    * Indicates that the email was sent successfully.
    */
@@ -16,6 +64,18 @@ type Receipt = {
    * The unique identifier for the message that was sent.
    */
   readonly messageId: string;
+  /**
+   * Provider or transport that produced this receipt.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * Number of attempts made before this receipt was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * ISO 8601 timestamp for when this receipt was produced.
+   */
+  readonly timestamp?: string;
 } | {
   /**
    * Indicates that the email failed to send.
@@ -25,6 +85,105 @@ type Receipt = {
    * An array of error messages that occurred during the sending process.
    */
   readonly errorMessages: readonly string[];
+  /**
+   * Structured errors for programmatic handling.
+   */
+  readonly errors?: readonly ReceiptError<TProviderId>[];
+  /**
+   * Whether retrying the same message may succeed.
+   */
+  readonly retryable?: boolean;
+  /**
+   * Provider or transport that produced this receipt.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * Number of attempts made before this receipt was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * ISO 8601 timestamp for when this receipt was produced.
+   */
+  readonly timestamp?: string;
+};
+/**
+ * Result of classifying a delivery failure.
+ *
+ * @since 0.5.0
+ */
+interface ReceiptErrorClassification {
+  readonly category: ReceiptErrorCategory;
+  readonly retryable: boolean;
+  readonly code?: string;
+}
+/**
+ * Options for creating a structured receipt error.
+ *
+ * @since 0.5.0
+ */
+interface CreateReceiptErrorOptions<TProviderId extends string = string> {
+  readonly code?: string;
+  readonly category?: ReceiptErrorCategory;
+  readonly retryable?: boolean;
+  readonly provider?: TProviderId;
+  readonly statusCode?: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly providerDetails?: unknown;
+}
+/**
+ * Options for creating a failed receipt.
+ *
+ * @since 0.5.0
+ */
+interface CreateFailedReceiptOptions<TProviderId extends string = string> extends CreateReceiptErrorOptions<TProviderId> {
+  readonly errors?: readonly ReceiptError<TProviderId>[];
+  readonly attempts?: number;
+  readonly timestamp?: string;
+}
+/**
+ * Classifies an HTTP status code for delivery error handling.
+ *
+ * @param statusCode The HTTP status code to classify.
+ * @returns The receipt error category and retryability.
+ * @since 0.5.0
+ */
+declare function classifyHttpStatus(statusCode: number): ReceiptErrorClassification;
+/**
+ * Classifies an arbitrary delivery failure.
+ *
+ * @param error The error to classify.
+ * @returns The receipt error category, retryability, and default code.
+ * @since 0.5.0
+ */
+declare function classifyReceiptError(error: unknown): Required<ReceiptErrorClassification>;
+/**
+ * Creates structured information about a delivery failure.
+ *
+ * @param message Human-readable error message.
+ * @param options Optional structured error metadata.
+ * @returns A structured receipt error.
+ * @since 0.5.0
+ */
+declare function createReceiptError<TProviderId extends string = string>(message: string, options?: CreateReceiptErrorOptions<TProviderId>): ReceiptError<TProviderId>;
+/**
+ * Creates a failed receipt with human-readable and structured errors.
+ *
+ * @param error Error message, structured error, or list of structured errors.
+ * @param options Optional receipt and error metadata.
+ * @returns A failed receipt.
+ * @since 0.5.0
+ */
+declare function createFailedReceipt<TProviderId extends string = string>(error: string | readonly (string | ReceiptError<TProviderId>)[] | ReceiptError<TProviderId>, options?: CreateFailedReceiptOptions<TProviderId>): Receipt<TProviderId> & {
+  readonly successful: false;
 };
+/**
+ * Parses an HTTP `Retry-After` header value into milliseconds.
+ *
+ * @param value Header value to parse.
+ * @param now Current time used when parsing HTTP dates.
+ * @returns Retry delay in milliseconds, or `undefined` if invalid.
+ * @since 0.5.0
+ */
+declare function parseRetryAfter(value: string | null | undefined, now?: Date): number | undefined;
 //#endregion
-export { Receipt };
+export { CreateFailedReceiptOptions, CreateReceiptErrorOptions, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter };

package/dist/receipt.d.ts

@@ -1,4 +1,49 @@
 //#region src/receipt.d.ts
+/**
+ * A machine-readable category for an email delivery failure.
+ *
+ * @since 0.5.0
+ */
+type ReceiptErrorCategory = "auth" | "rate-limit" | "network" | "timeout" | "validation" | "rejected" | "server-error" | "service-unavailable" | "configuration" | "unknown";
+/**
+ * Structured information about an email delivery failure.
+ *
+ * @since 0.5.0
+ */
+interface ReceiptError<TProviderId extends string = string> {
+  /**
+   * Human-readable error message.
+   */
+  readonly message: string;
+  /**
+   * Machine-readable provider or protocol error code.
+   */
+  readonly code: string;
+  /**
+   * Coarse error category for programmatic handling.
+   */
+  readonly category: ReceiptErrorCategory;
+  /**
+   * Whether retrying the same message may succeed.
+   */
+  readonly retryable: boolean;
+  /**
+   * Provider or transport that produced this error.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * HTTP status code, when the failure came from an HTTP API.
+   */
+  readonly statusCode?: number;
+  /**
+   * Provider-supplied retry delay in milliseconds, when available.
+   */
+  readonly retryAfterMilliseconds?: number;
+  /**
+   * Provider-specific error details, when available.
+   */
+  readonly providerDetails?: unknown;
+}
 /**
  * The response from the email service after sending an email message.
  *
@@ -6,8 +51,11 @@
  *
  * - Successful sends have a `messageId` but no `errorMessages`
  * - Failed sends have `errorMessages` but no `messageId`
+ *
+ * Failed receipts may also include structured `errors` and summary metadata
+ * for programmatic error handling.
  */
-type Receipt = {
+type Receipt<TProviderId extends string = string> = {
   /**
    * Indicates that the email was sent successfully.
    */
@@ -16,6 +64,18 @@ type Receipt = {
    * The unique identifier for the message that was sent.
    */
   readonly messageId: string;
+  /**
+   * Provider or transport that produced this receipt.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * Number of attempts made before this receipt was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * ISO 8601 timestamp for when this receipt was produced.
+   */
+  readonly timestamp?: string;
 } | {
   /**
    * Indicates that the email failed to send.
@@ -25,6 +85,105 @@ type Receipt = {
    * An array of error messages that occurred during the sending process.
    */
   readonly errorMessages: readonly string[];
+  /**
+   * Structured errors for programmatic handling.
+   */
+  readonly errors?: readonly ReceiptError<TProviderId>[];
+  /**
+   * Whether retrying the same message may succeed.
+   */
+  readonly retryable?: boolean;
+  /**
+   * Provider or transport that produced this receipt.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * Number of attempts made before this receipt was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * ISO 8601 timestamp for when this receipt was produced.
+   */
+  readonly timestamp?: string;
+};
+/**
+ * Result of classifying a delivery failure.
+ *
+ * @since 0.5.0
+ */
+interface ReceiptErrorClassification {
+  readonly category: ReceiptErrorCategory;
+  readonly retryable: boolean;
+  readonly code?: string;
+}
+/**
+ * Options for creating a structured receipt error.
+ *
+ * @since 0.5.0
+ */
+interface CreateReceiptErrorOptions<TProviderId extends string = string> {
+  readonly code?: string;
+  readonly category?: ReceiptErrorCategory;
+  readonly retryable?: boolean;
+  readonly provider?: TProviderId;
+  readonly statusCode?: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly providerDetails?: unknown;
+}
+/**
+ * Options for creating a failed receipt.
+ *
+ * @since 0.5.0
+ */
+interface CreateFailedReceiptOptions<TProviderId extends string = string> extends CreateReceiptErrorOptions<TProviderId> {
+  readonly errors?: readonly ReceiptError<TProviderId>[];
+  readonly attempts?: number;
+  readonly timestamp?: string;
+}
+/**
+ * Classifies an HTTP status code for delivery error handling.
+ *
+ * @param statusCode The HTTP status code to classify.
+ * @returns The receipt error category and retryability.
+ * @since 0.5.0
+ */
+declare function classifyHttpStatus(statusCode: number): ReceiptErrorClassification;
+/**
+ * Classifies an arbitrary delivery failure.
+ *
+ * @param error The error to classify.
+ * @returns The receipt error category, retryability, and default code.
+ * @since 0.5.0
+ */
+declare function classifyReceiptError(error: unknown): Required<ReceiptErrorClassification>;
+/**
+ * Creates structured information about a delivery failure.
+ *
+ * @param message Human-readable error message.
+ * @param options Optional structured error metadata.
+ * @returns A structured receipt error.
+ * @since 0.5.0
+ */
+declare function createReceiptError<TProviderId extends string = string>(message: string, options?: CreateReceiptErrorOptions<TProviderId>): ReceiptError<TProviderId>;
+/**
+ * Creates a failed receipt with human-readable and structured errors.
+ *
+ * @param error Error message, structured error, or list of structured errors.
+ * @param options Optional receipt and error metadata.
+ * @returns A failed receipt.
+ * @since 0.5.0
+ */
+declare function createFailedReceipt<TProviderId extends string = string>(error: string | readonly (string | ReceiptError<TProviderId>)[] | ReceiptError<TProviderId>, options?: CreateFailedReceiptOptions<TProviderId>): Receipt<TProviderId> & {
+  readonly successful: false;
 };
+/**
+ * Parses an HTTP `Retry-After` header value into milliseconds.
+ *
+ * @param value Header value to parse.
+ * @param now Current time used when parsing HTTP dates.
+ * @returns Retry delay in milliseconds, or `undefined` if invalid.
+ * @since 0.5.0
+ */
+declare function parseRetryAfter(value: string | null | undefined, now?: Date): number | undefined;
 //#endregion
-export { Receipt };
+export { CreateFailedReceiptOptions, CreateReceiptErrorOptions, Receipt, ReceiptError, ReceiptErrorCategory, ReceiptErrorClassification, classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter };

package/dist/receipt.js

@@ -0,0 +1,179 @@
+//#region src/receipt.ts
+/**
+* Classifies an HTTP status code for delivery error handling.
+*
+* @param statusCode The HTTP status code to classify.
+* @returns The receipt error category and retryability.
+* @since 0.5.0
+*/
+function classifyHttpStatus(statusCode) {
+	if (statusCode === 401 || statusCode === 403) return {
+		category: "auth",
+		retryable: false
+	};
+	if (statusCode === 408 || statusCode === 504) return {
+		category: "timeout",
+		retryable: true
+	};
+	if (statusCode === 429) return {
+		category: "rate-limit",
+		retryable: true
+	};
+	if (statusCode === 503) return {
+		category: "service-unavailable",
+		retryable: true
+	};
+	if (statusCode >= 400 && statusCode < 500) return {
+		category: "validation",
+		retryable: false
+	};
+	if (statusCode >= 500 && statusCode < 600) return {
+		category: "server-error",
+		retryable: true
+	};
+	return {
+		category: "unknown",
+		retryable: false
+	};
+}
+/**
+* Classifies an arbitrary delivery failure.
+*
+* @param error The error to classify.
+* @returns The receipt error category, retryability, and default code.
+* @since 0.5.0
+*/
+function classifyReceiptError(error) {
+	const message = getStringProperty(error, "message") ?? String(error);
+	const name = getStringProperty(error, "name") ?? "";
+	const text = `${name} ${message}`.toLowerCase();
+	if (text.includes("timeout") || text.includes("timed out")) return {
+		category: "timeout",
+		retryable: true,
+		code: "timeout"
+	};
+	if (text.includes("network") || text.includes("connect") || text.includes("fetch failed") || text.includes("dns") || text.includes("econnreset") || text.includes("econnrefused") || text.includes("enotfound") || name === "NetworkError") return {
+		category: "network",
+		retryable: true,
+		code: "network"
+	};
+	if (text.includes("authentication") || text.includes("authenticate") || text.includes("authorization") || text.includes("authorize") || /\bauth\b/.test(text) || text.includes("unauthorized") || text.includes("not authorized") || text.includes("forbidden") || text.includes("invalid api key") || text.includes("invalid token") || text.includes("401") || text.includes("403")) return {
+		category: "auth",
+		retryable: false,
+		code: "auth"
+	};
+	if (text.includes("rate limit") || text.includes("rate-limit") || text.includes("too many requests") || text.includes("quota") || text.includes("throttle") || text.includes("429")) return {
+		category: "rate-limit",
+		retryable: true,
+		code: "rate-limit"
+	};
+	if (text.includes("invalid") || text.includes("malformed") || text.includes("validation") || text.includes("bad request") || text.includes("400") || text.includes("422")) return {
+		category: "validation",
+		retryable: false,
+		code: "validation"
+	};
+	if (text.includes("rejected") || text.includes("bounce") || text.includes("complaint") || text.includes("suppressed") || text.includes("unsubscribed")) return {
+		category: "rejected",
+		retryable: false,
+		code: "rejected"
+	};
+	if (text.includes("service unavailable") || text.includes("temporarily unavailable") || text.includes("503")) return {
+		category: "service-unavailable",
+		retryable: true,
+		code: "service-unavailable"
+	};
+	if (text.includes("internal server error") || text.includes("bad gateway") || text.includes("500") || text.includes("502")) return {
+		category: "server-error",
+		retryable: true,
+		code: "server-error"
+	};
+	if (text.includes("config") || text.includes("unsupported")) return {
+		category: "configuration",
+		retryable: false,
+		code: "configuration"
+	};
+	return {
+		category: "unknown",
+		retryable: false,
+		code: "unknown"
+	};
+}
+/**
+* Creates structured information about a delivery failure.
+*
+* @param message Human-readable error message.
+* @param options Optional structured error metadata.
+* @returns A structured receipt error.
+* @since 0.5.0
+*/
+function createReceiptError(message, options = {}) {
+	const classification = options.statusCode == null ? classifyReceiptError(message) : classifyHttpStatus(options.statusCode);
+	const category = options.category ?? classification.category;
+	const retryable = options.retryable ?? classification.retryable;
+	const code = options.code ?? (options.statusCode == null ? options.category != null ? category : classification.code ?? category : `http.${options.statusCode}`);
+	return omitUndefined({
+		message,
+		category,
+		code,
+		retryable,
+		provider: options.provider,
+		statusCode: options.statusCode,
+		retryAfterMilliseconds: options.retryAfterMilliseconds,
+		providerDetails: options.providerDetails
+	});
+}
+/**
+* Creates a failed receipt with human-readable and structured errors.
+*
+* @param error Error message, structured error, or list of structured errors.
+* @param options Optional receipt and error metadata.
+* @returns A failed receipt.
+* @since 0.5.0
+*/
+function createFailedReceipt(error, options = {}) {
+	const errors = options.errors ?? (typeof error === "string" ? [createReceiptError(error, options)] : Array.isArray(error) ? error.map((item) => typeof item === "string" ? createReceiptError(item, options) : item) : [error]);
+	const errorMessages = typeof error === "string" ? [error] : Array.isArray(error) ? error.map((item) => typeof item === "string" ? item : item.message) : errors.map((receiptError) => receiptError.message);
+	const retryable = options.retryable ?? errors.some((receiptError) => receiptError.retryable);
+	const provider = options.provider ?? errors[0]?.provider;
+	return omitUndefined({
+		successful: false,
+		errorMessages,
+		errors,
+		retryable,
+		provider,
+		attempts: options.attempts,
+		timestamp: options.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+/**
+* Parses an HTTP `Retry-After` header value into milliseconds.
+*
+* @param value Header value to parse.
+* @param now Current time used when parsing HTTP dates.
+* @returns Retry delay in milliseconds, or `undefined` if invalid.
+* @since 0.5.0
+*/
+function parseRetryAfter(value, now = /* @__PURE__ */ new Date()) {
+	if (value == null || value.trim() === "") return void 0;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const delay$1 = Number(trimmed) * 1e3;
+		return delay$1;
+	}
+	const timestamp = Date.parse(trimmed);
+	if (Number.isNaN(timestamp)) return void 0;
+	const delay = timestamp - now.getTime();
+	return delay > 0 ? delay : void 0;
+}
+function getStringProperty(value, property) {
+	if (value instanceof Error) return value[property];
+	if (typeof value !== "object" || value == null || !(property in value)) return void 0;
+	const propertyValue = value[property];
+	return propertyValue == null ? void 0 : String(propertyValue);
+}
+function omitUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+}
+
+//#endregion
+export { classifyHttpStatus, classifyReceiptError, createFailedReceipt, createReceiptError, parseRetryAfter };

package/dist/transport.d.cts

@@ -6,7 +6,13 @@ import { Receipt } from "./receipt.cjs";
 /**
  * A common interface for email sending services.
  */
-interface Transport {
+interface Transport<TProviderId extends string = string> {
+  /**
+   * Stable provider identifier for receipts produced by this transport.
+   *
+   * @since 0.5.0
+   */
+  readonly id: TProviderId;
   /**
    * Sends a single message using the email service.
    * @param message The message to send.
@@ -14,21 +20,21 @@ interface Transport {
    * @returns A promise that resolves to a receipt containing the result of
    *          the send operation.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
   /**
    * Sends multiple messages using the email service.
    * @param messages An iterable of messages to send.
    * @param options Optional parameters for sending the messages.
    * @return An async iterable that yields receipts for each sent message.
    */
-  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
   /**
    * Sends multiple messages using the email service.
    * @param messages An async iterable of messages to send.
    * @param options Optional parameters for sending the messages.
    * @return An async iterable that yields receipts for each sent message.
    */
-  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
 }
 /**
  * Options for sending messages with the email service.

package/dist/transport.d.ts

@@ -6,7 +6,13 @@ import { Receipt } from "./receipt.js";
 /**
  * A common interface for email sending services.
  */
-interface Transport {
+interface Transport<TProviderId extends string = string> {
+  /**
+   * Stable provider identifier for receipts produced by this transport.
+   *
+   * @since 0.5.0
+   */
+  readonly id: TProviderId;
   /**
    * Sends a single message using the email service.
    * @param message The message to send.
@@ -14,21 +20,21 @@ interface Transport {
    * @returns A promise that resolves to a receipt containing the result of
    *          the send operation.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
   /**
    * Sends multiple messages using the email service.
    * @param messages An iterable of messages to send.
    * @param options Optional parameters for sending the messages.
    * @return An async iterable that yields receipts for each sent message.
    */
-  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: Iterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
   /**
    * Sends multiple messages using the email service.
    * @param messages An async iterable of messages to send.
    * @param options Optional parameters for sending the messages.
    * @return An async iterable that yields receipts for each sent message.
    */
-  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
 }
 /**
  * Options for sending messages with the email service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/core",
-  "version": "0.5.0-dev.86",
+  "version": "0.5.0",
   "description": "Simple email sending library for Node.js, Deno, Bun, and edge functions",
   "keywords": [
     "email",
@@ -49,6 +49,14 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./abort-signal": {
+      "types": {
+        "import": "./dist/abort-signal.d.ts",
+        "require": "./dist/abort-signal.d.cts"
+      },
+      "import": "./dist/abort-signal.js",
+      "require": "./dist/abort-signal.cjs"
+    },
     "./address": {
       "types": {
         "import": "./dist/address.d.ts",
@@ -105,11 +113,6 @@
     "typescript": "5.8.3"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepublish": "tsdown",
-    "test": "tsdown && node --experimental-transform-types --test",
-    "test:bun": "tsdown && bun test",
-    "test:deno": "deno test",
-    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+    "prepublish": "mise run --no-deps :build"
   }
 }