@upyo/pool 0.5.0-dev.87 → 0.5.0

package/README.md

@@ -97,7 +97,7 @@ const transport = new PoolTransport({
     { transport: backupTransport, priority: 50 },
     { transport: emergencyTransport, priority: 10 },
   ],
-  maxRetries: 3, // Try up to 3 transports
+  maxRetries: 2, // Retry up to 2 other transports
 });
 
 // Always tries primary first, only uses backup if primary fails
@@ -219,13 +219,13 @@ Configuration
 
 ### `PoolConfig`
 
-| Property            | Type                                                                        | Required | Default              | Description                                                       |
-| ------------------- | --------------------------------------------------------------------------- | -------- | -------------------- | ----------------------------------------------------------------- |
-| `strategy`          | `"round-robin" \| "weighted" \| "priority" \| "selector-based" \| Strategy` | Yes      |                      | The strategy for selecting transports                             |
-| `transports`        | `TransportEntry[]`                                                          | Yes      |                      | Array of transport configurations                                 |
-| `maxRetries`        | `number`                                                                    | No       | Number of transports | Maximum retry attempts on failure                                 |
-| `timeout`           | `number`                                                                    | No       |                      | Timeout in milliseconds for each send attempt                     |
-| `continueOnSuccess` | `boolean`                                                                   | No       | `false`              | Continue trying transports after success (selector strategy only) |
+| Property            | Type                                                                        | Required | Default                           | Description                                                       |
+| ------------------- | --------------------------------------------------------------------------- | -------- | --------------------------------- | ----------------------------------------------------------------- |
+| `strategy`          | `"round-robin" \| "weighted" \| "priority" \| "selector-based" \| Strategy` | Yes      |                                   | The strategy for selecting transports                             |
+| `transports`        | `TransportEntry[]`                                                          | Yes      |                                   | Array of transport configurations                                 |
+| `maxRetries`        | `number`                                                                    | No       | Enough to try each transport once | Maximum retry attempts after the initial attempt                  |
+| `timeout`           | `number`                                                                    | No       |                                   | Timeout in milliseconds for each send attempt                     |
+| `continueOnSuccess` | `boolean`                                                                   | No       | `false`                           | Continue trying transports after success (selector strategy only) |
 
 ### `TransportEntry`
 

package/dist/index.cjs

@@ -1,3 +1,27 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __upyo_core = __toESM(require("@upyo/core"));
 
 //#region src/config.ts
 /**
@@ -26,7 +50,7 @@ function createPoolConfig(config) {
 	return {
 		strategy: config.strategy,
 		transports: resolvedTransports,
-		maxRetries: config.maxRetries ?? enabledTransports.length,
+		maxRetries: config.maxRetries ?? enabledTransports.length - 1,
 		timeout: config.timeout,
 		continueOnSuccess: config.continueOnSuccess ?? false
 	};
@@ -273,6 +297,7 @@ var SelectorStrategy = class {
 * @since 0.3.0
 */
 var PoolTransport = class {
+	id = "pool";
 	/**
 	* The resolved configuration used by this pool transport.
 	*/
@@ -301,27 +326,57 @@ var PoolTransport = class {
 	*/
 	async send(message, options) {
 		const attemptedIndices = /* @__PURE__ */ new Set();
+		const errorMessages = [];
 		const errors = [];
-		for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+		let checkCallerAbortBeforeFailure = false;
+		for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
 			if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
 			const selection = this.strategy.select(message, this.config.transports, attemptedIndices);
 			if (!selection) break;
 			attemptedIndices.add(selection.index);
+			let abortedByCaller = false;
 			try {
 				const sendOptions = this.createSendOptions(options);
-				const receipt = await selection.entry.transport.send(message, sendOptions);
+				let receipt;
+				try {
+					receipt = await selection.entry.transport.send(message, sendOptions.options);
+				} catch (error) {
+					if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) abortedByCaller = true;
+					throw error;
+				} finally {
+					sendOptions.cleanup();
+				}
 				if (receipt.successful) return receipt;
-				errors.push(...receipt.errorMessages);
+				errorMessages.push(...receipt.errorMessages);
+				errors.push(...getReceiptErrors(receipt, selection.entry.transport.id));
+				checkCallerAbortBeforeFailure = true;
 			} catch (error) {
-				if (error instanceof DOMException && error.name === "AbortError") throw error;
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				errors.push(errorMessage);
+				if (abortedByCaller && isCallerAbort(error, options?.signal)) throw error;
+				const thrownErrors = getThrownReceiptErrors(error, selection.entry.transport.id);
+				if (thrownErrors.length > 0) {
+					errorMessages.push(...thrownErrors.map((item) => item.message));
+					errors.push(...thrownErrors);
+					checkCallerAbortBeforeFailure = true;
+					continue;
+				}
+				const timeoutMessage = "Transport send timed out.";
+				const abortError = isAbortError(error);
+				const errorMessage = abortError ? timeoutMessage : error instanceof Error ? error.message : String(error);
+				errorMessages.push(errorMessage);
+				errors.push((0, __upyo_core.createReceiptError)(errorMessage, {
+					provider: selection.entry.transport.id,
+					category: abortError ? "timeout" : void 0,
+					retryable: abortError ? true : void 0
+				}));
+				checkCallerAbortBeforeFailure ||= !abortError;
 			}
 		}
-		return {
-			successful: false,
-			errorMessages: errors.length > 0 ? errors : ["All transports failed to send the message"]
-		};
+		if (checkCallerAbortBeforeFailure) options?.signal?.throwIfAborted();
+		return (0, __upyo_core.createFailedReceipt)(errorMessages.length > 0 ? errorMessages : ["All transports failed to send the message."], {
+			provider: "pool",
+			errors: errors.length > 0 ? errors : void 0,
+			attempts: attemptedIndices.size
+		});
 	}
 	/**
 	* Sends multiple email messages using the pool strategy.
@@ -376,22 +431,88 @@ var PoolTransport = class {
 	* Creates send options with timeout if configured.
 	*/
 	createSendOptions(options) {
-		if (!this.config.timeout) return options;
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-		if (options?.signal) options.signal.addEventListener("abort", () => {
-			clearTimeout(timeoutId);
-			controller.abort();
-		});
-		controller.signal.addEventListener("abort", () => {
+		if (!this.config.timeout) return {
+			options,
+			abortedByCaller: () => options?.signal?.aborted ?? false,
+			cleanup: () => {}
+		};
+		const timeoutController = new AbortController();
+		let abortSource;
+		const timeoutId = setTimeout(() => {
+			abortSource ??= "timeout";
+			timeoutController.abort(createAbortError());
+		}, this.config.timeout);
+		let cleanupAbortSource = () => {};
+		let signal = timeoutController.signal;
+		let cleanupCombinedSignal = () => {};
+		if (options?.signal) {
+			const markCallerAbort = () => {
+				abortSource ??= "caller";
+				clearTimeout(timeoutId);
+			};
+			if (options.signal.aborted) markCallerAbort();
+			else options.signal.addEventListener("abort", markCallerAbort, { once: true });
+			cleanupAbortSource = () => options.signal?.removeEventListener("abort", markCallerAbort);
+			const combinedSignal = (0, __upyo_core.combineSignals)(timeoutController.signal, options.signal);
+			signal = combinedSignal.signal;
+			cleanupCombinedSignal = combinedSignal.cleanup;
+		}
+		timeoutController.signal.addEventListener("abort", () => {
 			clearTimeout(timeoutId);
 		});
 		return {
-			...options,
-			signal: controller.signal
+			options: {
+				...options,
+				signal
+			},
+			abortedByCaller: () => abortSource === "caller",
+			cleanup: () => {
+				clearTimeout(timeoutId);
+				cleanupAbortSource();
+				cleanupCombinedSignal();
+			}
 		};
 	}
 };
+function createAbortError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+function isCallerAbort(error, signal) {
+	return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+}
+function getReceiptErrors(receipt, provider) {
+	if (receipt.errors != null && receipt.errors.length > 0) return receipt.errors.map((error) => withReceiptErrorProvider(error, provider));
+	return receipt.errorMessages.map((message) => (0, __upyo_core.createReceiptError)(message, {
+		provider: receipt.provider ?? provider,
+		retryable: receipt.retryable
+	}));
+}
+function getThrownReceiptErrors(error, provider) {
+	if (isReceiptError(error)) return [withReceiptErrorProvider(error, provider)];
+	if (isFailedReceipt(error)) return getReceiptErrors(error, provider);
+	return [];
+}
+function withReceiptErrorProvider(error, provider) {
+	return {
+		message: error.message,
+		code: error.code,
+		category: error.category,
+		retryable: error.retryable,
+		provider: error.provider ?? provider,
+		statusCode: error.statusCode,
+		retryAfterMilliseconds: error.retryAfterMilliseconds,
+		providerDetails: error.providerDetails
+	};
+}
+function isReceiptError(value) {
+	return typeof value === "object" && value != null && typeof value.message === "string" && typeof value.code === "string" && typeof value.retryable === "boolean" && typeof value.category === "string";
+}
+function isFailedReceipt(value) {
+	return typeof value === "object" && value != null && value.successful === false && Array.isArray(value.errorMessages);
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
 
 //#endregion
 exports.PoolTransport = PoolTransport;

package/dist/index.d.cts

@@ -6,11 +6,11 @@ import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
  * Result of transport selection by a strategy.
  * @since 0.3.0
  */
-interface TransportSelection {
+interface TransportSelection<TProviderId extends string = string> {
   /**
    * The selected transport entry.
    */
-  readonly entry: ResolvedTransportEntry;
+  readonly entry: ResolvedTransportEntry<TProviderId>;
   /**
    * Index of the selected transport in the original list.
    */
@@ -20,7 +20,7 @@ interface TransportSelection {
  * Base interface for transport selection strategies.
  * @since 0.3.0
  */
-interface Strategy {
+interface Strategy<TProviderId extends string = string> {
   /**
    * Selects a transport for sending a message.
    *
@@ -31,7 +31,7 @@ interface Strategy {
    * @returns The selected transport or `undefined` if no suitable transport is
    *          available.
    */
-  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets any internal state of the strategy.
    */
@@ -53,11 +53,11 @@ type TransportSelector = (message: Message) => boolean;
  * Configuration for a transport entry in the pool.
  * @since 0.3.0
  */
-interface TransportEntry {
+interface TransportEntry<TProviderId extends string = string> {
   /**
    * The transport instance to use.
    */
-  readonly transport: Transport;
+  readonly transport: Transport<TProviderId>;
   /**
    * Weight for weighted distribution strategy.
    * Higher values mean more traffic. Defaults to 1.
@@ -84,19 +84,20 @@ interface TransportEntry {
  * Configuration options for the pool transport.
  * @since 0.3.0
  */
-interface PoolConfig {
+interface PoolConfig<TProviderId extends string = string> {
   /**
    * The strategy to use for selecting transports.
    * Can be a built-in strategy name or a custom Strategy instance.
    */
-  readonly strategy: PoolStrategy | Strategy;
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
   /**
    * The transports in the pool.
    */
-  readonly transports: readonly TransportEntry[];
+  readonly transports: readonly TransportEntry<TProviderId>[];
   /**
-   * Maximum number of retry attempts when a transport fails.
-   * Set to 0 to disable retries. Defaults to the number of transports.
+   * Maximum number of retry attempts after the initial send attempt fails.
+   * Set to 0 to disable retries. Defaults to enough retries to try every
+   * enabled transport once.
    */
   readonly maxRetries?: number;
   /**
@@ -114,9 +115,9 @@ interface PoolConfig {
  * Resolved pool configuration with defaults applied.
  * @since 0.3.0
  */
-interface ResolvedPoolConfig {
-  readonly strategy: PoolStrategy | Strategy;
-  readonly transports: readonly ResolvedTransportEntry[];
+interface ResolvedPoolConfig<TProviderId extends string = string> {
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
+  readonly transports: readonly ResolvedTransportEntry<TProviderId>[];
   readonly maxRetries: number;
   readonly timeout?: number;
   readonly continueOnSuccess: boolean;
@@ -125,8 +126,8 @@ interface ResolvedPoolConfig {
  * Resolved transport entry with defaults applied.
  * @since 0.3.0
  */
-interface ResolvedTransportEntry {
-  readonly transport: Transport;
+interface ResolvedTransportEntry<TProviderId extends string = string> {
+  readonly transport: Transport<TProviderId>;
   readonly weight: number;
   readonly priority: number;
   readonly selector?: TransportSelector;
@@ -196,11 +197,12 @@ interface ResolvedTransportEntry {
  *
  * @since 0.3.0
  */
-declare class PoolTransport implements Transport, AsyncDisposable {
+declare class PoolTransport<TProviderId extends string = string> implements Transport<TProviderId | "pool">, AsyncDisposable {
+  readonly id = "pool";
   /**
    * The resolved configuration used by this pool transport.
    */
-  readonly config: ResolvedPoolConfig;
+  readonly config: ResolvedPoolConfig<TProviderId>;
   private readonly strategy;
   /**
    * Creates a new PoolTransport instance.
@@ -208,7 +210,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param config Configuration options for the pool transport.
    * @throws {Error} If the configuration is invalid.
    */
-  constructor(config: PoolConfig);
+  constructor(config: PoolConfig<TProviderId>);
   /**
    * Sends a single email message using the pool strategy.
    *
@@ -220,7 +222,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param options Optional transport options including abort signal.
    * @returns A promise that resolves to a receipt indicating success or failure.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId | "pool">>;
   /**
    * Sends multiple email messages using the pool strategy.
    *
@@ -231,7 +233,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param options Optional transport options including abort signal.
    * @returns An async iterable of receipts, one for each message.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId | "pool">>;
   /**
    * Disposes of all underlying transports that support disposal.
    *
@@ -258,7 +260,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
  * all enabled transports.
  * @since 0.3.0
  */
-declare class RoundRobinStrategy implements Strategy {
+declare class RoundRobinStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   private currentIndex;
   /**
    * Selects the next transport in round-robin order.
@@ -270,7 +272,7 @@ declare class RoundRobinStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the round-robin counter to start from the beginning.
    */
@@ -287,7 +289,7 @@ declare class RoundRobinStrategy implements Strategy {
  * messages as a transport with weight 1.
  * @since 0.3.0
  */
-declare class WeightedStrategy implements Strategy {
+declare class WeightedStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects a transport based on weighted random distribution.
    *
@@ -298,7 +300,7 @@ declare class WeightedStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for weighted strategy as it's stateless).
    */
@@ -315,7 +317,7 @@ declare class WeightedStrategy implements Strategy {
  * equivalent and one is selected randomly.
  * @since 0.3.0
  */
-declare class PriorityStrategy implements Strategy {
+declare class PriorityStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects the highest priority transport that hasn't been attempted.
    *
@@ -326,7 +328,7 @@ declare class PriorityStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for priority strategy as it's stateless).
    */
@@ -343,7 +345,7 @@ declare class PriorityStrategy implements Strategy {
  * one is selected randomly.
  * @since 0.3.0
  */
-declare class SelectorStrategy implements Strategy {
+declare class SelectorStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects a transport based on selector function matching.
    *
@@ -353,7 +355,7 @@ declare class SelectorStrategy implements Strategy {
    *                         attempted.
    * @returns The selected transport or `undefined` if no transport matches.
    */
-  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for selector strategy as it's stateless).
    */

package/dist/index.d.ts

@@ -6,11 +6,11 @@ import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
  * Result of transport selection by a strategy.
  * @since 0.3.0
  */
-interface TransportSelection {
+interface TransportSelection<TProviderId extends string = string> {
   /**
    * The selected transport entry.
    */
-  readonly entry: ResolvedTransportEntry;
+  readonly entry: ResolvedTransportEntry<TProviderId>;
   /**
    * Index of the selected transport in the original list.
    */
@@ -20,7 +20,7 @@ interface TransportSelection {
  * Base interface for transport selection strategies.
  * @since 0.3.0
  */
-interface Strategy {
+interface Strategy<TProviderId extends string = string> {
   /**
    * Selects a transport for sending a message.
    *
@@ -31,7 +31,7 @@ interface Strategy {
    * @returns The selected transport or `undefined` if no suitable transport is
    *          available.
    */
-  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets any internal state of the strategy.
    */
@@ -53,11 +53,11 @@ type TransportSelector = (message: Message) => boolean;
  * Configuration for a transport entry in the pool.
  * @since 0.3.0
  */
-interface TransportEntry {
+interface TransportEntry<TProviderId extends string = string> {
   /**
    * The transport instance to use.
    */
-  readonly transport: Transport;
+  readonly transport: Transport<TProviderId>;
   /**
    * Weight for weighted distribution strategy.
    * Higher values mean more traffic. Defaults to 1.
@@ -84,19 +84,20 @@ interface TransportEntry {
  * Configuration options for the pool transport.
  * @since 0.3.0
  */
-interface PoolConfig {
+interface PoolConfig<TProviderId extends string = string> {
   /**
    * The strategy to use for selecting transports.
    * Can be a built-in strategy name or a custom Strategy instance.
    */
-  readonly strategy: PoolStrategy | Strategy;
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
   /**
    * The transports in the pool.
    */
-  readonly transports: readonly TransportEntry[];
+  readonly transports: readonly TransportEntry<TProviderId>[];
   /**
-   * Maximum number of retry attempts when a transport fails.
-   * Set to 0 to disable retries. Defaults to the number of transports.
+   * Maximum number of retry attempts after the initial send attempt fails.
+   * Set to 0 to disable retries. Defaults to enough retries to try every
+   * enabled transport once.
    */
   readonly maxRetries?: number;
   /**
@@ -114,9 +115,9 @@ interface PoolConfig {
  * Resolved pool configuration with defaults applied.
  * @since 0.3.0
  */
-interface ResolvedPoolConfig {
-  readonly strategy: PoolStrategy | Strategy;
-  readonly transports: readonly ResolvedTransportEntry[];
+interface ResolvedPoolConfig<TProviderId extends string = string> {
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
+  readonly transports: readonly ResolvedTransportEntry<TProviderId>[];
   readonly maxRetries: number;
   readonly timeout?: number;
   readonly continueOnSuccess: boolean;
@@ -125,8 +126,8 @@ interface ResolvedPoolConfig {
  * Resolved transport entry with defaults applied.
  * @since 0.3.0
  */
-interface ResolvedTransportEntry {
-  readonly transport: Transport;
+interface ResolvedTransportEntry<TProviderId extends string = string> {
+  readonly transport: Transport<TProviderId>;
   readonly weight: number;
   readonly priority: number;
   readonly selector?: TransportSelector;
@@ -196,11 +197,12 @@ interface ResolvedTransportEntry {
  *
  * @since 0.3.0
  */
-declare class PoolTransport implements Transport, AsyncDisposable {
+declare class PoolTransport<TProviderId extends string = string> implements Transport<TProviderId | "pool">, AsyncDisposable {
+  readonly id = "pool";
   /**
    * The resolved configuration used by this pool transport.
    */
-  readonly config: ResolvedPoolConfig;
+  readonly config: ResolvedPoolConfig<TProviderId>;
   private readonly strategy;
   /**
    * Creates a new PoolTransport instance.
@@ -208,7 +210,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param config Configuration options for the pool transport.
    * @throws {Error} If the configuration is invalid.
    */
-  constructor(config: PoolConfig);
+  constructor(config: PoolConfig<TProviderId>);
   /**
    * Sends a single email message using the pool strategy.
    *
@@ -220,7 +222,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param options Optional transport options including abort signal.
    * @returns A promise that resolves to a receipt indicating success or failure.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId | "pool">>;
   /**
    * Sends multiple email messages using the pool strategy.
    *
@@ -231,7 +233,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
    * @param options Optional transport options including abort signal.
    * @returns An async iterable of receipts, one for each message.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId | "pool">>;
   /**
    * Disposes of all underlying transports that support disposal.
    *
@@ -258,7 +260,7 @@ declare class PoolTransport implements Transport, AsyncDisposable {
  * all enabled transports.
  * @since 0.3.0
  */
-declare class RoundRobinStrategy implements Strategy {
+declare class RoundRobinStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   private currentIndex;
   /**
    * Selects the next transport in round-robin order.
@@ -270,7 +272,7 @@ declare class RoundRobinStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the round-robin counter to start from the beginning.
    */
@@ -287,7 +289,7 @@ declare class RoundRobinStrategy implements Strategy {
  * messages as a transport with weight 1.
  * @since 0.3.0
  */
-declare class WeightedStrategy implements Strategy {
+declare class WeightedStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects a transport based on weighted random distribution.
    *
@@ -298,7 +300,7 @@ declare class WeightedStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for weighted strategy as it's stateless).
    */
@@ -315,7 +317,7 @@ declare class WeightedStrategy implements Strategy {
  * equivalent and one is selected randomly.
  * @since 0.3.0
  */
-declare class PriorityStrategy implements Strategy {
+declare class PriorityStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects the highest priority transport that hasn't been attempted.
    *
@@ -326,7 +328,7 @@ declare class PriorityStrategy implements Strategy {
    * @returns The selected transport or `undefined` if all transports have been
    *          attempted.
    */
-  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(_message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for priority strategy as it's stateless).
    */
@@ -343,7 +345,7 @@ declare class PriorityStrategy implements Strategy {
  * one is selected randomly.
  * @since 0.3.0
  */
-declare class SelectorStrategy implements Strategy {
+declare class SelectorStrategy<TProviderId extends string = string> implements Strategy<TProviderId> {
   /**
    * Selects a transport based on selector function matching.
    *
@@ -353,7 +355,7 @@ declare class SelectorStrategy implements Strategy {
    *                         attempted.
    * @returns The selected transport or `undefined` if no transport matches.
    */
-  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  select(message: Message, transports: readonly ResolvedTransportEntry<TProviderId>[], attemptedIndices: ReadonlySet<number>): TransportSelection<TProviderId> | undefined;
   /**
    * Resets the strategy (no-op for selector strategy as it's stateless).
    */

package/dist/index.js

@@ -1,3 +1,5 @@
+import { combineSignals, createFailedReceipt, createReceiptError } from "@upyo/core";
+
 //#region src/config.ts
 /**
 * Creates a resolved pool configuration with defaults applied.
@@ -25,7 +27,7 @@ function createPoolConfig(config) {
 	return {
 		strategy: config.strategy,
 		transports: resolvedTransports,
-		maxRetries: config.maxRetries ?? enabledTransports.length,
+		maxRetries: config.maxRetries ?? enabledTransports.length - 1,
 		timeout: config.timeout,
 		continueOnSuccess: config.continueOnSuccess ?? false
 	};
@@ -272,6 +274,7 @@ var SelectorStrategy = class {
 * @since 0.3.0
 */
 var PoolTransport = class {
+	id = "pool";
 	/**
 	* The resolved configuration used by this pool transport.
 	*/
@@ -300,27 +303,57 @@ var PoolTransport = class {
 	*/
 	async send(message, options) {
 		const attemptedIndices = /* @__PURE__ */ new Set();
+		const errorMessages = [];
 		const errors = [];
-		for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+		let checkCallerAbortBeforeFailure = false;
+		for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
 			if (options?.signal?.aborted) throw new DOMException("The operation was aborted.", "AbortError");
 			const selection = this.strategy.select(message, this.config.transports, attemptedIndices);
 			if (!selection) break;
 			attemptedIndices.add(selection.index);
+			let abortedByCaller = false;
 			try {
 				const sendOptions = this.createSendOptions(options);
-				const receipt = await selection.entry.transport.send(message, sendOptions);
+				let receipt;
+				try {
+					receipt = await selection.entry.transport.send(message, sendOptions.options);
+				} catch (error) {
+					if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) abortedByCaller = true;
+					throw error;
+				} finally {
+					sendOptions.cleanup();
+				}
 				if (receipt.successful) return receipt;
-				errors.push(...receipt.errorMessages);
+				errorMessages.push(...receipt.errorMessages);
+				errors.push(...getReceiptErrors(receipt, selection.entry.transport.id));
+				checkCallerAbortBeforeFailure = true;
 			} catch (error) {
-				if (error instanceof DOMException && error.name === "AbortError") throw error;
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				errors.push(errorMessage);
+				if (abortedByCaller && isCallerAbort(error, options?.signal)) throw error;
+				const thrownErrors = getThrownReceiptErrors(error, selection.entry.transport.id);
+				if (thrownErrors.length > 0) {
+					errorMessages.push(...thrownErrors.map((item) => item.message));
+					errors.push(...thrownErrors);
+					checkCallerAbortBeforeFailure = true;
+					continue;
+				}
+				const timeoutMessage = "Transport send timed out.";
+				const abortError = isAbortError(error);
+				const errorMessage = abortError ? timeoutMessage : error instanceof Error ? error.message : String(error);
+				errorMessages.push(errorMessage);
+				errors.push(createReceiptError(errorMessage, {
+					provider: selection.entry.transport.id,
+					category: abortError ? "timeout" : void 0,
+					retryable: abortError ? true : void 0
+				}));
+				checkCallerAbortBeforeFailure ||= !abortError;
 			}
 		}
-		return {
-			successful: false,
-			errorMessages: errors.length > 0 ? errors : ["All transports failed to send the message"]
-		};
+		if (checkCallerAbortBeforeFailure) options?.signal?.throwIfAborted();
+		return createFailedReceipt(errorMessages.length > 0 ? errorMessages : ["All transports failed to send the message."], {
+			provider: "pool",
+			errors: errors.length > 0 ? errors : void 0,
+			attempts: attemptedIndices.size
+		});
 	}
 	/**
 	* Sends multiple email messages using the pool strategy.
@@ -375,22 +408,88 @@ var PoolTransport = class {
 	* Creates send options with timeout if configured.
 	*/
 	createSendOptions(options) {
-		if (!this.config.timeout) return options;
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-		if (options?.signal) options.signal.addEventListener("abort", () => {
-			clearTimeout(timeoutId);
-			controller.abort();
-		});
-		controller.signal.addEventListener("abort", () => {
+		if (!this.config.timeout) return {
+			options,
+			abortedByCaller: () => options?.signal?.aborted ?? false,
+			cleanup: () => {}
+		};
+		const timeoutController = new AbortController();
+		let abortSource;
+		const timeoutId = setTimeout(() => {
+			abortSource ??= "timeout";
+			timeoutController.abort(createAbortError());
+		}, this.config.timeout);
+		let cleanupAbortSource = () => {};
+		let signal = timeoutController.signal;
+		let cleanupCombinedSignal = () => {};
+		if (options?.signal) {
+			const markCallerAbort = () => {
+				abortSource ??= "caller";
+				clearTimeout(timeoutId);
+			};
+			if (options.signal.aborted) markCallerAbort();
+			else options.signal.addEventListener("abort", markCallerAbort, { once: true });
+			cleanupAbortSource = () => options.signal?.removeEventListener("abort", markCallerAbort);
+			const combinedSignal = combineSignals(timeoutController.signal, options.signal);
+			signal = combinedSignal.signal;
+			cleanupCombinedSignal = combinedSignal.cleanup;
+		}
+		timeoutController.signal.addEventListener("abort", () => {
 			clearTimeout(timeoutId);
 		});
 		return {
-			...options,
-			signal: controller.signal
+			options: {
+				...options,
+				signal
+			},
+			abortedByCaller: () => abortSource === "caller",
+			cleanup: () => {
+				clearTimeout(timeoutId);
+				cleanupAbortSource();
+				cleanupCombinedSignal();
+			}
 		};
 	}
 };
+function createAbortError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+function isCallerAbort(error, signal) {
+	return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+}
+function getReceiptErrors(receipt, provider) {
+	if (receipt.errors != null && receipt.errors.length > 0) return receipt.errors.map((error) => withReceiptErrorProvider(error, provider));
+	return receipt.errorMessages.map((message) => createReceiptError(message, {
+		provider: receipt.provider ?? provider,
+		retryable: receipt.retryable
+	}));
+}
+function getThrownReceiptErrors(error, provider) {
+	if (isReceiptError(error)) return [withReceiptErrorProvider(error, provider)];
+	if (isFailedReceipt(error)) return getReceiptErrors(error, provider);
+	return [];
+}
+function withReceiptErrorProvider(error, provider) {
+	return {
+		message: error.message,
+		code: error.code,
+		category: error.category,
+		retryable: error.retryable,
+		provider: error.provider ?? provider,
+		statusCode: error.statusCode,
+		retryAfterMilliseconds: error.retryAfterMilliseconds,
+		providerDetails: error.providerDetails
+	};
+}
+function isReceiptError(value) {
+	return typeof value === "object" && value != null && typeof value.message === "string" && typeof value.code === "string" && typeof value.retryable === "boolean" && typeof value.category === "string";
+}
+function isFailedReceipt(value) {
+	return typeof value === "object" && value != null && value.successful === false && Array.isArray(value.errorMessages);
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
 
 //#endregion
 export { PoolTransport, PriorityStrategy, RoundRobinStrategy, SelectorStrategy, WeightedStrategy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/pool",
-  "version": "0.5.0-dev.87",
+  "version": "0.5.0",
   "description": "Pool transport for Upyo email library—provides load balancing and failover for multiple email providers",
   "keywords": [
     "email",
@@ -56,19 +56,14 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.5.0-dev.87+50b9f2d4"
+    "@upyo/core": "0.5.0"
   },
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.47.3",
     "tsdown": "^0.12.7",
     "typescript": "5.8.3",
-    "@upyo/mock": "0.5.0-dev.87+50b9f2d4"
+    "@upyo/mock": "0.5.0"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepublish": "tsdown",
-    "test": "tsdown && dotenvx run --ignore=MISSING_ENV_FILE -- node --experimental-transform-types --test",
-    "test:bun": "tsdown && bun test --timeout=30000 --env-file=.env",
-    "test:deno": "deno test --allow-env --env-file=.env"
+    "prepublish": "mise run --no-deps :build"
   }
 }