@amqp-contract/client 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -1,10 +1,11 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _amqp_contract_contract = require("@amqp-contract/contract");
 let _amqp_contract_core = require("@amqp-contract/core");
 let _swan_io_boxed = require("@swan-io/boxed");
+let node_crypto = require("node:crypto");
 let node_zlib = require("node:zlib");
 let ts_pattern = require("ts-pattern");
 let node_util = require("node:util");
-
 //#region src/compression.ts
 const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
 const deflateAsync = (0, node_util.promisify)(node_zlib.deflate);
@@ -20,16 +21,74 @@ const deflateAsync = (0, node_util.promisify)(node_zlib.deflate);
 function compressBuffer(buffer, algorithm) {
 	return (0, ts_pattern.match)(algorithm).with("gzip", () => _swan_io_boxed.Future.fromPromise(gzipAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to compress with gzip", error))).with("deflate", () => _swan_io_boxed.Future.fromPromise(deflateAsync(buffer)).mapError((error) => new _amqp_contract_core.TechnicalError("Failed to compress with deflate", error))).exhaustive();
 }
-
+//#endregion
+//#region src/errors.ts
+/**
+* Captured `Error.captureStackTrace` shim — only present on Node.js.
+*/
+function captureStack(target, ctor) {
+	const ErrorConstructor = Error;
+	if (typeof ErrorConstructor.captureStackTrace === "function") ErrorConstructor.captureStackTrace(target, ctor);
+}
+/**
+* Returned from `TypedAmqpClient.call()` when the configured `timeoutMs` elapses
+* before the RPC server publishes a reply with the matching `correlationId`.
+*
+* The pending call is removed from the in-memory correlation map; if a reply
+* arrives after the timeout it is dropped (and a debug log is emitted by the
+* client if a logger is configured).
+*/
+var RpcTimeoutError = class extends Error {
+	constructor(rpcName, timeoutMs) {
+		super(`RPC call to "${rpcName}" timed out after ${timeoutMs}ms with no reply received`);
+		this.rpcName = rpcName;
+		this.timeoutMs = timeoutMs;
+		this.name = "RpcTimeoutError";
+		captureStack(this, this.constructor);
+	}
+};
+/**
+* Returned from any in-flight RPC call when the client is closed before the
+* reply is received. The correlation map is cleared on close and every pending
+* caller's promise resolves with `Result.Error(RpcCancelledError)`.
+*/
+var RpcCancelledError = class extends Error {
+	constructor(rpcName) {
+		super(`RPC call to "${rpcName}" was cancelled because the client was closed`);
+		this.rpcName = rpcName;
+		this.name = "RpcCancelledError";
+		captureStack(this, this.constructor);
+	}
+};
 //#endregion
 //#region src/client.ts
 /**
+* The RabbitMQ direct-reply-to pseudo-queue. Publishing with `replyTo` set to
+* this value tells the server to deliver the response back to the consumer
+* subscribed on this queue on the same channel — no real queue is created and
+* no setup is required beyond consuming from it once with `noAck: true`.
+*
+* @see https://www.rabbitmq.com/docs/direct-reply-to
+*/
+const DIRECT_REPLY_TO = "amq.rabbitmq.reply-to";
+/**
 * Type-safe AMQP client for publishing messages
 */
 var TypedAmqpClient = class TypedAmqpClient {
-	constructor(contract, amqpClient, logger, telemetry = _amqp_contract_core.defaultTelemetryProvider) {
+	/**
+	* In-flight RPC calls keyed by `correlationId`. Cleared when a reply is
+	* received, when the call times out, or when the client is closed.
+	*/
+	pendingCalls = /* @__PURE__ */ new Map();
+	/**
+	* Consumer tag of the reply consumer subscribed on `amq.rabbitmq.reply-to`.
+	* Set when the contract has at least one entry in `rpcs`; undefined otherwise.
+	*/
+	replyConsumerTag;
+	constructor(contract, amqpClient, defaultPublishOptions, logger, telemetry = _amqp_contract_core.defaultTelemetryProvider) {
 		this.contract = contract;
 		this.amqpClient = amqpClient;
+		this.defaultPublishOptions = defaultPublishOptions;
 		this.logger = logger;
 		this.telemetry = telemetry;
 	}
@@ -43,12 +102,77 @@ var TypedAmqpClient = class TypedAmqpClient {
 	* Connections are automatically shared across clients with the same URLs and
 	* connection options, following RabbitMQ best practices.
 	*/
-	static create({ contract, urls, connectionOptions, logger, telemetry }) {
+	static create({ contract, urls, connectionOptions, defaultPublishOptions, logger, telemetry, connectTimeoutMs }) {
 		const client = new TypedAmqpClient(contract, new _amqp_contract_core.AmqpClient(contract, {
 			urls,
-			connectionOptions
-		}), logger, telemetry ?? _amqp_contract_core.defaultTelemetryProvider);
-		return client.waitForConnectionReady().mapOk(() => client);
+			connectionOptions,
+			connectTimeoutMs
+		}), {
+			persistent: true,
+			...defaultPublishOptions
+		}, logger, telemetry ?? _amqp_contract_core.defaultTelemetryProvider);
+		return client.waitForConnectionReady().flatMapOk(() => client.setupReplyConsumerIfNeeded()).flatMap((result) => result.match({
+			Ok: () => _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(client)),
+			Error: (error) => client.close().tapError((closeError) => {
+				logger?.warn("Failed to close client after connection failure", { error: closeError });
+			}).map(() => _swan_io_boxed.Result.Error(error))
+		}));
+	}
+	/**
+	* If the contract has any RPC entry, subscribe to `amq.rabbitmq.reply-to`
+	* once. Replies for every in-flight call arrive on this single consumer and
+	* are demultiplexed by `correlationId`.
+	*/
+	setupReplyConsumerIfNeeded() {
+		const rpcs = this.contract.rpcs ?? {};
+		if (Object.keys(rpcs).length === 0) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0));
+		return this.amqpClient.consume(DIRECT_REPLY_TO, (msg) => this.handleRpcReply(msg), { noAck: true }).tapOk((tag) => {
+			this.replyConsumerTag = tag;
+		}).mapOk(() => void 0);
+	}
+	/**
+	* Demultiplex an RPC reply by `correlationId`, validate the body against the
+	* call's response schema, and resolve the awaiting caller. Replies with no
+	* matching pending call (e.g. arriving after the call timed out) are dropped
+	* with a debug log.
+	*/
+	handleRpcReply(msg) {
+		if (!msg) return;
+		const correlationId = msg.properties.correlationId;
+		if (typeof correlationId !== "string") {
+			this.logger?.warn("Received RPC reply without correlationId; dropping", { deliveryTag: msg.fields.deliveryTag });
+			return;
+		}
+		const pending = this.pendingCalls.get(correlationId);
+		if (!pending) {
+			this.logger?.debug("Received RPC reply for unknown correlationId", { correlationId });
+			return;
+		}
+		this.pendingCalls.delete(correlationId);
+		clearTimeout(pending.timer);
+		let parsed;
+		try {
+			parsed = JSON.parse(msg.content.toString());
+		} catch (error) {
+			pending.resolve(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`Failed to parse RPC reply JSON for "${pending.rpcName}"`, error)));
+			return;
+		}
+		let rawValidation;
+		try {
+			rawValidation = pending.responseSchema["~standard"].validate(parsed);
+		} catch (error) {
+			pending.resolve(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`RPC reply validation threw for "${pending.rpcName}"`, error)));
+			return;
+		}
+		(rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation)).then((validation) => {
+			if (validation.issues) {
+				pending.resolve(_swan_io_boxed.Result.Error(new _amqp_contract_core.MessageValidationError(pending.rpcName, validation.issues)));
+				return;
+			}
+			pending.resolve(_swan_io_boxed.Result.Ok(validation.value));
+		}, (error) => {
+			pending.resolve(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`RPC reply validation threw for "${pending.rpcName}"`, error)));
+		});
 	}
 	/**
 	* Publish a message using a defined publisher
@@ -81,7 +205,10 @@ var TypedAmqpClient = class TypedAmqpClient {
 			});
 		};
 		const publishMessage = (validatedMessage) => {
-			const { compression, ...restOptions } = options ?? {};
+			const { compression, ...restOptions } = {
+				...this.defaultPublishOptions,
+				...options
+			};
 			const publishOptions = { ...restOptions };
 			const preparePayload = () => {
 				if (compression) {
@@ -113,21 +240,120 @@ var TypedAmqpClient = class TypedAmqpClient {
 		});
 	}
 	/**
-	* Close the channel and connection
+	* Invoke an RPC defined via `defineRpc` and await the typed response.
+	*
+	* The request payload is validated against the RPC's request schema, then
+	* published to the AMQP default exchange with the server's queue name as
+	* routing key, `replyTo` set to `amq.rabbitmq.reply-to`, and a fresh UUID
+	* `correlationId`. The returned Future resolves once a matching reply
+	* arrives and validates against the response schema, or once `timeoutMs`
+	* elapses (whichever comes first).
+	*
+	* @typeParam TName - An RPC name from `contract.rpcs`.
+	* @param rpcName - The RPC name from the contract.
+	* @param request - The request payload, validated against the request schema.
+	* @param options - Per-call options. `timeoutMs` is required.
+	*
+	* @returns `Result.Ok(response)` on a successful round-trip; `Result.Error`
+	*   on validation, transport, timeout, or cancel.
+	*
+	* @example
+	* ```typescript
+	* const result = await client
+	*   .call('calculate', { a: 1, b: 2 }, { timeoutMs: 5_000 })
+	*   .toPromise();
+	* if (result.isOk()) console.log(result.value.sum); // 3
+	* ```
+	*/
+	call(rpcName, request, options) {
+		const TIMEOUT_MAX_MS = 2147483647;
+		if (typeof options.timeoutMs !== "number" || !Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > TIMEOUT_MAX_MS) return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`Invalid timeoutMs for RPC call to "${String(rpcName)}": expected a finite positive number ≤ ${TIMEOUT_MAX_MS}, got ${String(options.timeoutMs)}`)));
+		const startTime = Date.now();
+		const rpc = this.contract.rpcs[rpcName];
+		const requestSchema = rpc.request.payload;
+		const responseSchema = rpc.response.payload;
+		const queueName = (0, _amqp_contract_contract.extractQueue)(rpc.queue).name;
+		const span = (0, _amqp_contract_core.startPublishSpan)(this.telemetry, "", queueName, { [_amqp_contract_core.MessagingSemanticConventions.AMQP_PUBLISHER_NAME]: String(rpcName) });
+		const correlationId = (0, node_crypto.randomUUID)();
+		const callFuture = _swan_io_boxed.Future.make((resolve) => {
+			const timer = setTimeout(() => {
+				if (!this.pendingCalls.get(correlationId)) return;
+				this.pendingCalls.delete(correlationId);
+				resolve(_swan_io_boxed.Result.Error(new RpcTimeoutError(String(rpcName), options.timeoutMs)));
+			}, options.timeoutMs);
+			this.pendingCalls.set(correlationId, {
+				rpcName: String(rpcName),
+				responseSchema,
+				resolve,
+				timer
+			});
+		});
+		const validateRequest = () => {
+			let rawValidation;
+			try {
+				rawValidation = requestSchema["~standard"].validate(request);
+			} catch (error) {
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError("RPC request validation threw", error)));
+			}
+			const validationPromise = rawValidation instanceof Promise ? rawValidation : Promise.resolve(rawValidation);
+			return _swan_io_boxed.Future.fromPromise(validationPromise).mapError((error) => new _amqp_contract_core.TechnicalError("RPC request validation threw", error)).mapOkToResult((validation) => validation.issues ? _swan_io_boxed.Result.Error(new _amqp_contract_core.MessageValidationError(String(rpcName), validation.issues)) : _swan_io_boxed.Result.Ok(validation.value));
+		};
+		const publishRequest = (validatedRequest) => {
+			const { compression: _ignoredCompression, ...defaultsWithoutCompression } = this.defaultPublishOptions;
+			const publishOptions = {
+				...defaultsWithoutCompression,
+				...options.publishOptions,
+				replyTo: DIRECT_REPLY_TO,
+				correlationId,
+				contentType: "application/json"
+			};
+			return this.amqpClient.publish("", queueName, validatedRequest, publishOptions).mapOkToResult((published) => published ? _swan_io_boxed.Result.Ok(void 0) : _swan_io_boxed.Result.Error(new _amqp_contract_core.TechnicalError(`Failed to publish RPC request for "${String(rpcName)}": channel buffer full`)));
+		};
+		return validateRequest().flatMapOk((validated) => publishRequest(validated)).flatMap((preflight) => {
+			if (preflight.isError()) {
+				const pending = this.pendingCalls.get(correlationId);
+				if (pending) {
+					clearTimeout(pending.timer);
+					this.pendingCalls.delete(correlationId);
+				}
+				return _swan_io_boxed.Future.value(_swan_io_boxed.Result.Error(preflight.error));
+			}
+			return callFuture;
+		}).tapOk(() => {
+			const durationMs = Date.now() - startTime;
+			(0, _amqp_contract_core.endSpanSuccess)(span);
+			(0, _amqp_contract_core.recordPublishMetric)(this.telemetry, "", queueName, true, durationMs);
+		}).tapError((error) => {
+			const durationMs = Date.now() - startTime;
+			(0, _amqp_contract_core.endSpanError)(span, error);
+			(0, _amqp_contract_core.recordPublishMetric)(this.telemetry, "", queueName, false, durationMs);
+		});
+	}
+	/**
+	* Close the channel and connection. Cancels the reply consumer (if any) and
+	* rejects every in-flight RPC call with `RpcCancelledError`.
 	*/
 	close() {
-		return this.amqpClient.close().mapOk(() => void 0);
+		for (const [, pending] of this.pendingCalls) {
+			clearTimeout(pending.timer);
+			pending.resolve(_swan_io_boxed.Result.Error(new RpcCancelledError(pending.rpcName)));
+		}
+		this.pendingCalls.clear();
+		return (this.replyConsumerTag ? this.amqpClient.cancel(this.replyConsumerTag).tapError((error) => {
+			this.logger?.warn("Failed to cancel RPC reply consumer during close", { error });
+		}) : _swan_io_boxed.Future.value(_swan_io_boxed.Result.Ok(void 0))).flatMap(() => this.amqpClient.close()).mapOk(() => void 0);
 	}
 	waitForConnectionReady() {
 		return this.amqpClient.waitForConnect();
 	}
 };
-
 //#endregion
-Object.defineProperty(exports, 'MessageValidationError', {
-  enumerable: true,
-  get: function () {
-    return _amqp_contract_core.MessageValidationError;
-  }
+Object.defineProperty(exports, "MessageValidationError", {
+	enumerable: true,
+	get: function() {
+		return _amqp_contract_core.MessageValidationError;
+	}
 });
-exports.TypedAmqpClient = TypedAmqpClient;
+exports.RpcCancelledError = RpcCancelledError;
+exports.RpcTimeoutError = RpcTimeoutError;
+exports.TypedAmqpClient = TypedAmqpClient;

package/dist/index.d.cts

@@ -1,13 +1,12 @@
-import { Logger, MessageValidationError, TechnicalError, TelemetryProvider } from "@amqp-contract/core";
+import { CompressionAlgorithm, ContractDefinition, InferPublisherNames, InferRpcNames, MessageDefinition, PublisherEntry, RpcDefinition } from "@amqp-contract/contract";
+import { Logger, MessageValidationError, PublishOptions as PublishOptions$1, TechnicalError, TelemetryProvider } from "@amqp-contract/core";
+import { Future, Result } from "@swan-io/boxed";
 import * as amqp from "amqplib";
-import { Options } from "amqplib";
 import { TcpSocketConnectOpts } from "net";
 import { ConnectionOptions } from "tls";
-import { CompressionAlgorithm, ContractDefinition, InferPublisherNames, PublisherEntry } from "@amqp-contract/contract";
-import { Future, Result } from "@swan-io/boxed";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region ../../node_modules/.pnpm/amqp-connection-manager@5.0.0_amqplib@0.10.9/node_modules/amqp-connection-manager/dist/types/AmqpConnectionManager.d.ts
+//#region ../../node_modules/.pnpm/amqp-connection-manager@5.0.0_amqplib@1.0.3/node_modules/amqp-connection-manager/dist/types/AmqpConnectionManager.d.ts
 type ConnectionUrl = string | amqp.Options.Connect | {
   url: string;
   connectionOptions?: AmqpConnectionOptions;
@@ -48,11 +47,39 @@ interface AmqpConnectionManagerOptions {
   connectionOptions?: AmqpConnectionOptions;
 }
 //#endregion
+//#region src/errors.d.ts
+/**
+ * Returned from `TypedAmqpClient.call()` when the configured `timeoutMs` elapses
+ * before the RPC server publishes a reply with the matching `correlationId`.
+ *
+ * The pending call is removed from the in-memory correlation map; if a reply
+ * arrives after the timeout it is dropped (and a debug log is emitted by the
+ * client if a logger is configured).
+ */
+declare class RpcTimeoutError extends Error {
+  readonly rpcName: string;
+  readonly timeoutMs: number;
+  constructor(rpcName: string, timeoutMs: number);
+}
+/**
+ * Returned from any in-flight RPC call when the client is closed before the
+ * reply is received. The correlation map is cleared on close and every pending
+ * caller's promise resolves with `Result.Error(RpcCancelledError)`.
+ */
+declare class RpcCancelledError extends Error {
+  readonly rpcName: string;
+  constructor(rpcName: string);
+}
+//#endregion
 //#region src/types.d.ts
 /**
- * Infer the TypeScript type from a schema
+ * Infer the TypeScript type from a schema (input side, used for publish payloads).
  */
 type InferSchemaInput<TSchema extends StandardSchemaV1> = TSchema extends StandardSchemaV1<infer TInput> ? TInput : never;
+/**
+ * Infer the TypeScript type from a schema (output side, used for validated responses).
+ */
+type InferSchemaOutput<TSchema extends StandardSchemaV1> = TSchema extends StandardSchemaV1<infer _TInput, infer TOutput> ? TOutput : never;
 /**
  * Infer publisher message input type.
  * Works with both PublisherDefinition and EventPublisherConfig since both have
@@ -63,24 +90,28 @@ type PublisherInferInput<TPublisher extends PublisherEntry> = TPublisher extends
     payload: StandardSchemaV1;
   };
 } ? InferSchemaInput<TPublisher["message"]["payload"]> : never;
+type InferPublishers<TContract extends ContractDefinition> = NonNullable<TContract["publishers"]>;
+type InferPublisher<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = InferPublishers<TContract>[TName];
 /**
- * Infer all publishers from contract
+ * Input type accepted by `client.publish(name, ...)` for a specific publisher.
  */
-type InferPublishers<TContract extends ContractDefinition> = NonNullable<TContract["publishers"]>;
+type ClientInferPublisherInput<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = PublisherInferInput<InferPublisher<TContract, TName>>;
+type InferRpcs<TContract extends ContractDefinition> = NonNullable<TContract["rpcs"]>;
+type InferRpc<TContract extends ContractDefinition, TName extends InferRpcNames<TContract>> = InferRpcs<TContract>[TName];
 /**
- * Get specific publisher definition from contract
+ * Input type accepted by `client.call(name, request, ...)`.
  */
-type InferPublisher<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = InferPublishers<TContract>[TName];
+type ClientInferRpcRequestInput<TContract extends ContractDefinition, TName extends InferRpcNames<TContract>> = InferRpc<TContract, TName> extends RpcDefinition<infer TRequest, MessageDefinition> ? TRequest extends MessageDefinition ? InferSchemaInput<TRequest["payload"]> : never : never;
 /**
- * Infer publisher input type (message payload) for a specific publisher in a contract
+ * Output (validated) response type returned by `client.call(name, ...)`.
  */
-type ClientInferPublisherInput<TContract extends ContractDefinition, TName extends InferPublisherNames<TContract>> = PublisherInferInput<InferPublisher<TContract, TName>>;
+type ClientInferRpcResponseOutput<TContract extends ContractDefinition, TName extends InferRpcNames<TContract>> = InferRpc<TContract, TName> extends RpcDefinition<MessageDefinition, infer TResponse> ? TResponse extends MessageDefinition ? InferSchemaOutput<TResponse["payload"]> : never : never;
 //#endregion
 //#region src/client.d.ts
 /**
- * Publish options that extend amqplib's Options.Publish with optional compression support.
+ * Publish options that extend amqp-client's PublishOptions with optional compression support.
  */
-type PublishOptions = Options.Publish & {
+type PublishOptions = PublishOptions$1 & {
   /**
    * Optional compression algorithm to use for the message payload.
    * When specified, the message will be compressed using the chosen algorithm
@@ -102,6 +133,37 @@ type CreateClientOptions<TContract extends ContractDefinition> = {
    * OpenTelemetry instrumentation is automatically enabled if @opentelemetry/api is installed.
    */
   telemetry?: TelemetryProvider | undefined;
+  /**
+   * Default publish options that will be applied to all publish operations.
+   * These can be overridden by options passed to the publish method.
+   * By default, persistent is set to true for message durability.
+   */
+  defaultPublishOptions?: PublishOptions | undefined;
+  /**
+   * Maximum time in ms to wait for the AMQP connection to become ready before
+   * `create()` resolves to `Result.Error<TechnicalError>`. Without this option,
+   * `create()` waits forever — the underlying amqp-connection-manager retries
+   * indefinitely.
+   */
+  connectTimeoutMs?: number | undefined;
+};
+/**
+ * Per-call options for `client.call()`.
+ */
+type CallOptions = {
+  /**
+   * Maximum time in ms to wait for an RPC reply. If exceeded, the call resolves
+   * to `Result.Error<RpcTimeoutError>` and the in-memory correlation entry is
+   * cleared. A late reply arriving after the timeout is silently dropped.
+   *
+   * Required: RPC without a timeout is a footgun.
+   */
+  timeoutMs: number;
+  /**
+   * Optional AMQP message properties to merge into the request. `replyTo` and
+   * `correlationId` are managed by the client and cannot be overridden.
+   */
+  publishOptions?: Omit<PublishOptions$1, "replyTo" | "correlationId">;
 };
 /**
  * Type-safe AMQP client for publishing messages
@@ -109,8 +171,19 @@ type CreateClientOptions<TContract extends ContractDefinition> = {
 declare class TypedAmqpClient<TContract extends ContractDefinition> {
   private readonly contract;
   private readonly amqpClient;
+  private readonly defaultPublishOptions;
   private readonly logger?;
   private readonly telemetry;
+  /**
+   * In-flight RPC calls keyed by `correlationId`. Cleared when a reply is
+   * received, when the call times out, or when the client is closed.
+   */
+  private readonly pendingCalls;
+  /**
+   * Consumer tag of the reply consumer subscribed on `amq.rabbitmq.reply-to`.
+   * Set when the contract has at least one entry in `rpcs`; undefined otherwise.
+   */
+  private replyConsumerTag?;
   private constructor();
   /**
    * Create a type-safe AMQP client from a contract.
@@ -126,9 +199,24 @@ declare class TypedAmqpClient<TContract extends ContractDefinition> {
     contract,
     urls,
     connectionOptions,
+    defaultPublishOptions,
     logger,
-    telemetry
+    telemetry,
+    connectTimeoutMs
   }: CreateClientOptions<TContract>): Future<Result<TypedAmqpClient<TContract>, TechnicalError>>;
+  /**
+   * If the contract has any RPC entry, subscribe to `amq.rabbitmq.reply-to`
+   * once. Replies for every in-flight call arrive on this single consumer and
+   * are demultiplexed by `correlationId`.
+   */
+  private setupReplyConsumerIfNeeded;
+  /**
+   * Demultiplex an RPC reply by `correlationId`, validate the body against the
+   * call's response schema, and resolve the awaiting caller. Replies with no
+   * matching pending call (e.g. arriving after the call timed out) are dropped
+   * with a debug log.
+   */
+  private handleRpcReply;
   /**
    * Publish a message using a defined publisher
    *
@@ -149,11 +237,39 @@ declare class TypedAmqpClient<TContract extends ContractDefinition> {
    */
   publish<TName extends InferPublisherNames<TContract>>(publisherName: TName, message: ClientInferPublisherInput<TContract, TName>, options?: PublishOptions): Future<Result<void, TechnicalError | MessageValidationError>>;
   /**
-   * Close the channel and connection
+   * Invoke an RPC defined via `defineRpc` and await the typed response.
+   *
+   * The request payload is validated against the RPC's request schema, then
+   * published to the AMQP default exchange with the server's queue name as
+   * routing key, `replyTo` set to `amq.rabbitmq.reply-to`, and a fresh UUID
+   * `correlationId`. The returned Future resolves once a matching reply
+   * arrives and validates against the response schema, or once `timeoutMs`
+   * elapses (whichever comes first).
+   *
+   * @typeParam TName - An RPC name from `contract.rpcs`.
+   * @param rpcName - The RPC name from the contract.
+   * @param request - The request payload, validated against the request schema.
+   * @param options - Per-call options. `timeoutMs` is required.
+   *
+   * @returns `Result.Ok(response)` on a successful round-trip; `Result.Error`
+   *   on validation, transport, timeout, or cancel.
+   *
+   * @example
+   * ```typescript
+   * const result = await client
+   *   .call('calculate', { a: 1, b: 2 }, { timeoutMs: 5_000 })
+   *   .toPromise();
+   * if (result.isOk()) console.log(result.value.sum); // 3
+   * ```
+   */
+  call<TName extends InferRpcNames<TContract>>(rpcName: TName, request: ClientInferRpcRequestInput<TContract, TName>, options: CallOptions): Future<Result<ClientInferRpcResponseOutput<TContract, TName>, TechnicalError | MessageValidationError | RpcTimeoutError | RpcCancelledError>>;
+  /**
+   * Close the channel and connection. Cancels the reply consumer (if any) and
+   * rejects every in-flight RPC call with `RpcCancelledError`.
    */
   close(): Future<Result<void, TechnicalError>>;
   private waitForConnectionReady;
 }
 //#endregion
-export { type ClientInferPublisherInput, type CreateClientOptions, MessageValidationError, type PublishOptions, TypedAmqpClient };
+export { type CallOptions, type ClientInferPublisherInput, type ClientInferRpcRequestInput, type ClientInferRpcResponseOutput, type CreateClientOptions, MessageValidationError, type PublishOptions, RpcCancelledError, RpcTimeoutError, TypedAmqpClient };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":["amqp","EventEmitter","TcpSocketConnectOpts","ConnectionOptions","ChannelWrapper","CreateChannelOpts","ConnectionUrl","Options","Connect","AmqpConnectionOptions","url","connectionOptions","ConnectListener","Connection","connection","arg","ConnectFailedListener","Error","err","Buffer","noDelay","timeout","keepAlive","keepAliveDelay","clientProperties","credentials","mechanism","username","password","response","AmqpConnectionManagerOptions","Promise","heartbeatIntervalInSeconds","reconnectTimeInSeconds","findServers","urls","callback","IAmqpConnectionManager","Function","ChannelModel","addListener","event","args","listener","reason","listeners","eventName","on","once","prependListener","prependOnceListener","removeListener","connect","options","reconnect","createChannel","close","isConnected","channelCount","AmqpConnectionManager","_channels","_currentUrl","_closed","_cancelRetriesHandler","_connectPromise","_currentConnection","_findServers","_urls","constructor","_connect","default"],"sources":["../../../node_modules/.pnpm/amqp-connection-manager@5.0.0_amqplib@0.10.9/node_modules/amqp-connection-manager/dist/types/AmqpConnectionManager.d.ts","../src/types.ts","../src/client.ts"],"x_google_ignoreList":[0],"mappings":";;;;;;;;;;KAKYM,aAAAA,YAAyBN,IAAAA,CAAKO,OAAAA,CAAQC,OAAAA;EAC9CE,GAAAA;EACAC,iBAAAA,GAAoBF,qBAAAA;AAAAA;AAAAA,KAcZA,qBAAAA,IAAyBN,iBAAAA,GAAoBD,oBAAAA;EACrDkB,OAAAA;EACAC,OAAAA;EACAC,SAAAA;EACAC,cAAAA;EACAC,gBAAAA;EACAC,WAAAA;IACIC,SAAAA;IACAC,QAAAA;IACAC,QAAAA;IACAC,QAAAA,QAAgBV,MAAAA;EAAAA;IAEhBO,SAAAA;IACAG,QAAAA,QAAgBV,MAAAA;EAAAA;AAAAA;AAAAA,UAGPW,4BAAAA;EAVbL;EAYAO,0BAAAA;EAVIL;;;;EAeJM,sBAAAA;EAVIJ;;;;AAGR;;;EAeIK,WAAAA,KAAgBE,QAAAA,GAAWD,IAAAA,EAAM7B,aAAAA,GAAgBA,aAAAA,+BAA4CyB,OAAAA,CAAQzB,aAAAA,GAAgBA,aAAAA;EAApEA;EAEjDK,iBAAAA,GAAoBF,qBAAAA;AAAAA;;;;;;KC5CnB,gBAAA,iBAAiC,gBAAA,IACpC,OAAA,SAAgB,gBAAA,iBAAiC,MAAA;;;;;ADNnD;KCaK,mBAAA,oBAAuC,cAAA,IAAkB,UAAA;EAC5D,OAAA;IAAW,OAAA,EAAS,gBAAA;EAAA;AAAA,IAElB,gBAAA,CAAiB,UAAA;;;;KAMhB,eAAA,mBAAkC,kBAAA,IAAsB,WAAA,CAAY,SAAA;;;ADNzE;KCWK,cAAA,mBACe,kBAAA,gBACJ,mBAAA,CAAoB,SAAA,KAChC,eAAA,CAAgB,SAAA,EAAW,KAAA;;;;KAKnB,yBAAA,mBACQ,kBAAA,gBACJ,mBAAA,CAAoB,SAAA,KAChC,mBAAA,CAAoB,cAAA,CAAe,SAAA,EAAW,KAAA;;;;;;KChBtC,cAAA,GAAiB,OAAA,CAAQ,OAAA;EFtBZ;;;;;EE4BvB,WAAA,GAAc,oBAAA;AAAA;;;;KAMJ,mBAAA,mBAAsC,kBAAA;EAChD,QAAA,EAAU,SAAA;EACV,IAAA,EAAM,aAAA;EACN,iBAAA,GAAoB,4BAAA;EACpB,MAAA,GAAS,MAAA;EFtB8CP;;;;;EE4BvD,SAAA,GAAY,iBAAA;AAAA;;;;cAMD,eAAA,mBAAkC,kBAAA;EAAA,iBAE1B,QAAA;EAAA,iBACA,UAAA;EAAA,iBACA,MAAA;EAAA,iBACA,SAAA;EAAA,QAJZ,WAAA,CAAA;EFzBD2B;;;;;;;AAMR;;;EANQA,OE0CC,MAAA,mBAAyB,kBAAA,CAAA,CAAA;IAC9B,QAAA;IACA,IAAA;IACA,iBAAA;IACA,MAAA;IACA;EAAA,GACC,mBAAA,CAAoB,SAAA,IAAa,MAAA,CAAO,MAAA,CAAO,eAAA,CAAgB,SAAA,GAAY,cAAA;EF3B3BvB;;;;;;;;;;;;;;EAA4CyB;;;;EEwD/F,OAAA,eAAsB,mBAAA,CAAoB,SAAA,EAAA,CACxC,aAAA,EAAe,KAAA,EACf,OAAA,EAAS,yBAAA,CAA0B,SAAA,EAAW,KAAA,GAC9C,OAAA,GAAU,cAAA,GACT,MAAA,CAAO,MAAA,OAAa,cAAA,GAAiB,sBAAA;EF1DG;;;EEoJ3C,KAAA,CAAA,GAAS,MAAA,CAAO,MAAA,OAAa,cAAA;EAAA,QAIrB,sBAAA;AAAA"}
+{"version":3,"file":"index.d.cts","names":["amqp","EventEmitter","TcpSocketConnectOpts","ConnectionOptions","ChannelWrapper","CreateChannelOpts","ConnectionUrl","Options","Connect","AmqpConnectionOptions","url","connectionOptions","ConnectListener","Connection","connection","arg","ConnectFailedListener","Error","err","Buffer","noDelay","timeout","keepAlive","keepAliveDelay","clientProperties","credentials","mechanism","username","password","response","AmqpConnectionManagerOptions","Promise","heartbeatIntervalInSeconds","reconnectTimeInSeconds","findServers","urls","callback","IAmqpConnectionManager","Function","ChannelModel","addListener","event","args","listener","reason","listeners","eventName","on","once","prependListener","prependOnceListener","removeListener","connect","options","reconnect","createChannel","close","isConnected","channelCount","AmqpConnectionManager","_channels","_currentUrl","_closed","_cancelRetriesHandler","_connectPromise","_currentConnection","_findServers","_urls","constructor","_connect","default"],"sources":["../../../node_modules/.pnpm/amqp-connection-manager@5.0.0_amqplib@1.0.3/node_modules/amqp-connection-manager/dist/types/AmqpConnectionManager.d.ts","../src/errors.ts","../src/types.ts","../src/client.ts"],"x_google_ignoreList":[0],"mappings":";;;;;;;;;KAKYM,aAAAA,YAAyBN,IAAAA,CAAKO,OAAAA,CAAQC,OAAAA;EAC9CE,GAAAA;EACAC,iBAAAA,GAAoBF,qBAAAA;AAAAA;AAAAA,KAcZA,qBAAAA,IAAyBN,iBAAAA,GAAoBD,oBAAAA;EACrDkB,OAAAA;EACAC,OAAAA;EACAC,SAAAA;EACAC,cAAAA;EACAC,gBAAAA;EACAC,WAAAA;IACIC,SAAAA;IACAC,QAAAA;IACAC,QAAAA;IACAC,QAAAA,QAAgBV,MAAAA;EAAAA;IAEhBO,SAAAA;IACAG,QAAAA,QAAgBV,MAAAA;EAAAA;AAAAA;AAAAA,UAGPW,4BAAAA;EATTJ;EAWJM,0BAAAA;EATIJ;;;;EAcJK,sBAAAA;EAVoBd;;;AAGxB;;;;EAeIe,WAAAA,KAAgBE,QAAAA,GAAWD,IAAAA,EAAM7B,aAAAA,GAAgBA,aAAAA,+BAA4CyB,OAAAA,CAAQzB,aAAAA,GAAgBA,aAAAA;EAAhBA;EAErGK,iBAAAA,GAAoBF,qBAAAA;AAAAA;;;;;;;;;;;cChCX,eAAA,SAAwB,KAAA;EAAA,SAEjB,OAAA;EAAA,SACA,SAAA;cADA,OAAA,UACA,SAAA;AAAA;;;;;;cAaP,iBAAA,SAA0B,KAAA;EAAA,SACT,OAAA;cAAA,OAAA;AAAA;;;;;;KC1BzB,gBAAA,iBAAiC,gBAAA,IACpC,OAAA,SAAgB,gBAAA,iBAAiC,MAAA;;;;KAK9C,iBAAA,iBAAkC,gBAAA,IACrC,OAAA,SAAgB,gBAAA,iCAAiD,OAAA;;;;;;KAO9D,mBAAA,oBAAuC,cAAA,IAAkB,UAAA;EAC5D,OAAA;IAAW,OAAA,EAAS,gBAAA;EAAA;AAAA,IAElB,gBAAA,CAAiB,UAAA;AAAA,KAGhB,eAAA,mBAAkC,kBAAA,IAAsB,WAAA,CAAY,SAAA;AAAA,KACpE,cAAA,mBACe,kBAAA,gBACJ,mBAAA,CAAoB,SAAA,KAChC,eAAA,CAAgB,SAAA,EAAW,KAAA;;;;KAKnB,yBAAA,mBACQ,kBAAA,gBACJ,mBAAA,CAAoB,SAAA,KAChC,mBAAA,CAAoB,cAAA,CAAe,SAAA,EAAW,KAAA;AAAA,KAM7C,SAAA,mBAA4B,kBAAA,IAAsB,WAAA,CAAY,SAAA;AAAA,KAC9D,QAAA,mBACe,kBAAA,gBACJ,aAAA,CAAc,SAAA,KAC1B,SAAA,CAAU,SAAA,EAAW,KAAA;;;;KAKb,0BAAA,mBACQ,kBAAA,gBACJ,aAAA,CAAc,SAAA,KAE5B,QAAA,CAAS,SAAA,EAAW,KAAA,UAAe,aAAA,iBAA8B,iBAAA,IAC7D,QAAA,SAAiB,iBAAA,GACf,gBAAA,CAAiB,QAAA;;;;KAOb,4BAAA,mBACQ,kBAAA,gBACJ,aAAA,CAAc,SAAA,KAE5B,QAAA,CAAS,SAAA,EAAW,KAAA,UAAe,aAAA,CAAc,iBAAA,qBAC7C,SAAA,SAAkB,iBAAA,GAChB,iBAAA,CAAkB,SAAA;;;;;;KClBd,cAAA,GAAiB,gBAAA;EHxDJ;;;;;EG8DvB,WAAA,GAAc,oBAAA;AAAA;;;;KAMJ,mBAAA,mBAAsC,kBAAA;EAChD,QAAA,EAAU,SAAA;EACV,IAAA,EAAM,aAAA;EACN,iBAAA,GAAoB,4BAAA;EACpB,MAAA,GAAS,MAAA;EHxD8CP;;;;;EG8DvD,SAAA,GAAY,iBAAA;EH9D2CA;;;;;EGoEvD,qBAAA,GAAwB,cAAA;EH9DtBuB;;;;;;EGqEF,gBAAA;AAAA;;;;KAMU,WAAA;EHjEiC;;;;;;;EGyE3C,SAAA;EHxD2C;;;;EG8D3C,cAAA,GAAiB,IAAA,CAAK,gBAAA;AAAA;;;;cAMX,eAAA,mBAAkC,kBAAA;EAAA,iBAc1B,QAAA;EAAA,iBACA,UAAA;EAAA,iBACA,qBAAA;EAAA,iBACA,MAAA;EAAA,iBACA,SAAA;EHtFwB;;;;EAAA,iBGyE1B,YAAA;EFzGU;;;;EAAA,QE+GnB,gBAAA;EAAA,QAED,WAAA,CAAA;;;;;;AFjGT;;;;;SEmHS,MAAA,mBAAyB,kBAAA,CAAA,CAAA;IAC9B,QAAA;IACA,IAAA;IACA,iBAAA;IACA,qBAAA;IACA,MAAA;IACA,SAAA;IACA;EAAA,GACC,mBAAA,CAAoB,SAAA,IAAa,MAAA,CAAO,MAAA,CAAO,eAAA,CAAgB,SAAA,GAAY,cAAA;;;;;;UAkCtE,0BAAA;;AD3LoD;;;;;UC+MpD,cAAA;EDzMwB;;;;;;;;;;AAAuB;;;;EAMvD;;;;ECuRA,OAAA,eAAsB,mBAAA,CAAoB,SAAA,EAAA,CACxC,aAAA,EAAe,KAAA,EACf,OAAA,EAAS,yBAAA,CAA0B,SAAA,EAAW,KAAA,GAC9C,OAAA,GAAU,cAAA,GACT,MAAA,CAAO,MAAA,OAAa,cAAA,GAAiB,sBAAA;ED5RH;;;;;;;;AACmC;;;;;;;;;;;;;;;;;;EC+YxE,IAAA,eAAmB,aAAA,CAAc,SAAA,EAAA,CAC/B,OAAA,EAAS,KAAA,EACT,OAAA,EAAS,0BAAA,CAA2B,SAAA,EAAW,KAAA,GAC/C,OAAA,EAAS,WAAA,GACR,MAAA,CACD,MAAA,CACE,4BAAA,CAA6B,SAAA,EAAW,KAAA,GACxC,cAAA,GAAiB,sBAAA,GAAyB,eAAA,GAAkB,iBAAA;ED5YnC;AAAA;;;EC6hB7B,KAAA,CAAA,GAAS,MAAA,CAAO,MAAA,OAAa,cAAA;EAAA,QAiBrB,sBAAA;AAAA"}