@devlab.group/agent-commerce 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-B-9IjMbO.js';
-export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-B-9IjMbO.js';
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-CC6EFmLP.js';
+export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-CC6EFmLP.js';
 import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
-import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
-export { d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-DZ8qkkAa.js';
+export { A as AdapterHttpRoute, d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-DZ8qkkAa.js';
 import { FastifyInstance } from 'fastify';
 import 'node:http';
 
@@ -362,6 +362,10 @@ interface GatewayConfig {
             readonly enabled: boolean;
             readonly mountPath: string;
         };
+        readonly a2a: {
+            readonly enabled: boolean;
+            readonly mountPath: string;
+        };
     };
     /** Canonical resources, already normalised. */
     readonly resources: readonly CommerceResource[];

package/dist/index.js

@@ -1,6 +1,6 @@
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-MEPETSP6.js';
-import { CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-BQNE3A5H.js';
-export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-BQNE3A5H.js';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-M4I7I2UY.js';
+import { CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-64UZVJEO.js';
+export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-64UZVJEO.js';
 import { promises, existsSync, mkdirSync, accessSync, constants, closeSync, openSync, chmodSync } from 'fs';
 import * as path from 'path';
 import { dirname } from 'path';
@@ -1125,13 +1125,16 @@ var RESERVED_GATEWAY_PATHS = [
   "/health",
   "/ready",
   "/.well-known/agent-commerce",
+  // Fixed by the A2A specification, so it is the adapter's to serve and never
+  // a configurable mount's to claim.
+  "/.well-known/agent-card.json",
   "/api/resources",
   "/api/resources/:id/invoke",
   "/api/receipts",
   "/api/events",
   "/api/events/stream"
 ];
-var McpMountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
+var MountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
   message: 'must start with "/" \u2014 it is an absolute gateway path, e.g. "/mcp".'
 }).refine((value) => !/[:*?\s]/.test(value), {
   message: 'must not contain ":", "*", "?" or whitespace \u2014 the mount is a literal path prefix, not a Fastify route pattern, and registers its own wildcard.'
@@ -1150,9 +1153,16 @@ var ProtocolsSchema = z.object({
   http: z.object({ enabled: BooleanOrString }).strict(),
   mcp: z.object({
     enabled: BooleanOrString,
-    mountPath: McpMountPathSchema
-  }).strict()
+    mountPath: MountPathSchema
+  }).strict(),
+  // Optional block: A2A is off unless an operator asks for it, and an
+  // existing config predating the adapter stays valid.
+  a2a: z.object({
+    enabled: BooleanOrString,
+    mountPath: MountPathSchema.optional()
+  }).strict().optional()
 }).strict();
+var DEFAULT_A2A_MOUNT_PATH = "/a2a";
 var BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
 var BackendHandlerSchema = z.object({
   type: z.literal("http"),
@@ -1336,7 +1346,7 @@ function toBoolean(value, path2) {
     { details: { path: path2 } }
   );
 }
-var SUPPORTED_PROTOCOLS = /* @__PURE__ */ new Set(["http", "mcp"]);
+var SUPPORTED_PROTOCOLS = /* @__PURE__ */ new Set(["http", "mcp", "a2a"]);
 var SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
 function normalise(raw) {
   const protocols = {
@@ -1344,8 +1354,13 @@ function normalise(raw) {
     mcp: {
       enabled: toBoolean(raw.protocols.mcp.enabled, "protocols.mcp.enabled"),
       mountPath: raw.protocols.mcp.mountPath
+    },
+    a2a: {
+      enabled: toBoolean(raw.protocols.a2a?.enabled ?? false, "protocols.a2a.enabled"),
+      mountPath: raw.protocols.a2a?.mountPath ?? DEFAULT_A2A_MOUNT_PATH
     }
   };
+  validateMountPaths(protocols);
   const x402Raw = raw.payments.x402;
   const facilitator = x402Raw === void 0 ? void 0 : x402Raw.facilitator.mode === "local" ? { mode: "local", signerPrivateKey: x402Raw.facilitator.signerPrivateKey } : {
     mode: "remote",
@@ -1420,6 +1435,25 @@ function normalise(raw) {
     }
   };
 }
+function validateMountPaths(protocols) {
+  const mounts = [
+    ["mcp", protocols.mcp],
+    ["a2a", protocols.a2a]
+  ].filter(([, p]) => p.enabled);
+  for (const [index, [nameA, a]] of mounts.entries()) {
+    for (const [nameB, b] of mounts.slice(index + 1)) {
+      const baseA = a.mountPath.replace(/\/+$/, "");
+      const baseB = b.mountPath.replace(/\/+$/, "");
+      if (baseA === baseB || baseA.startsWith(`${baseB}/`) || baseB.startsWith(`${baseA}/`)) {
+        throw new CommerceError(
+          "CONFIG_INVALID",
+          `protocols.${nameA}.mountPath ("${a.mountPath}") collides with protocols.${nameB}.mountPath ("${b.mountPath}") \u2014 each mount registers a wildcard, so overlapping prefixes cannot both be served`,
+          { details: { path: `protocols.${nameA}.mountPath` } }
+        );
+      }
+    }
+  }
+}
 function normaliseResource(id, entry, protocols, x402) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
@@ -1440,7 +1474,7 @@ function normaliseResource(id, entry, protocols, x402) {
       const hint = protocol === "ucp" ? " (UCP is planned, not supported in this release)" : "";
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp.`,
+        `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp, a2a.`,
         { details: { path: `resources.${id}.expose`, resourceId: id, protocol } }
       );
     }
@@ -1461,6 +1495,13 @@ function normaliseResource(id, entry, protocols, x402) {
       );
     }
   }
+  if (entry.expose.includes("a2a") && !protocols.a2a.enabled) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" is exposed via "a2a" but protocols.a2a.enabled is false`,
+      { details: { path: `resources.${id}.expose`, resourceId: id } }
+    );
+  }
   if (entry.expose.includes("http") && !protocols.http.enabled) {
     throw new CommerceError(
       "CONFIG_INVALID",
@@ -1977,6 +2018,7 @@ function hashToken(value) {
 // src/gateway/adapters.ts
 var MOUNT_BODY_LIMIT_BYTES = 256 * 1024;
 async function startAndMountAdapters(options) {
+  assertNoRouteConflicts(options.adapters);
   const runtimes = [];
   for (const adapter of options.adapters) {
     const adapterLogger = options.logger.child({ adapter: adapter.name });
@@ -2002,11 +2044,51 @@ async function startAndMountAdapters(options) {
   }
   return runtimes;
 }
+function routeClaims(adapters) {
+  const claims = [];
+  for (const adapter of adapters) {
+    if (!isHttpProtocolAdapter(adapter)) continue;
+    claims.push({
+      adapter: adapter.name,
+      path: adapter.mountPath.replace(/\/+$/, ""),
+      wildcard: true,
+      method: "ALL"
+    });
+    for (const route of adapter.additionalHttpRoutes ?? []) {
+      claims.push({
+        adapter: adapter.name,
+        path: route.path.replace(/\/+$/, ""),
+        wildcard: false,
+        method: route.method
+      });
+    }
+  }
+  return claims;
+}
+function claimsCollide(a, b) {
+  if (a.wildcard && (b.path === a.path || b.path.startsWith(`${a.path}/`))) return true;
+  if (b.wildcard && a.path.startsWith(`${b.path}/`)) return true;
+  return a.path === b.path && (a.method === b.method || a.method === "ALL" || b.method === "ALL");
+}
+function assertNoRouteConflicts(adapters) {
+  const claims = routeClaims(adapters);
+  for (const [index, a] of claims.entries()) {
+    for (const b of claims.slice(index + 1)) {
+      if (a.adapter === b.adapter || !claimsCollide(a, b)) continue;
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Protocol adapters "${a.adapter}" and "${b.adapter}" both claim the HTTP path "${b.path}"; each adapter path must be served by exactly one adapter`,
+        { details: { adapters: [a.adapter, b.adapter], path: b.path } }
+      );
+    }
+  }
+}
 var MOUNT_MAX_CONCURRENT_REQUESTS = 20;
 var MOUNT_BUSY_RETRY_AFTER_SECONDS = 1;
 function mountHttpAdapter(server, adapter, logger) {
   const mountPath = adapter.mountPath;
   const wildcard = mountPath.endsWith("/") ? `${mountPath}*` : `${mountPath}/*`;
+  const additionalRoutes = adapter.additionalHttpRoutes ?? [];
   let inFlight = 0;
   void server.register(async (instance) => {
     instance.addContentTypeParser(
@@ -2018,7 +2100,7 @@ function mountHttpAdapter(server, adapter, logger) {
     instance.addContentTypeParser("*", (_request, _payload, done) => {
       done(null);
     });
-    const handler = async (request, reply) => {
+    const makeHandler = (handleHttp) => async (request, reply) => {
       if (inFlight >= MOUNT_MAX_CONCURRENT_REQUESTS) {
         const error = new CommerceError(
           "GATEWAY_BUSY",
@@ -2036,7 +2118,7 @@ function mountHttpAdapter(server, adapter, logger) {
           logger
         );
         try {
-          await adapter.handleHttp(request.raw, reply.raw);
+          await handleHttp(request.raw, reply.raw);
         } catch (error) {
           logger.error({ err: describeError3(error) }, "Protocol adapter request handler threw");
           if (!reply.raw.headersSent) {
@@ -2050,8 +2132,16 @@ function mountHttpAdapter(server, adapter, logger) {
         inFlight -= 1;
       }
     };
-    instance.all(mountPath, handler);
-    instance.all(wildcard, handler);
+    const mountHandler = makeHandler((req, res) => adapter.handleHttp(req, res));
+    instance.all(mountPath, mountHandler);
+    instance.all(wildcard, mountHandler);
+    for (const route of additionalRoutes) {
+      instance.route({
+        method: route.method,
+        url: route.path,
+        handler: makeHandler((req, res) => route.handleHttp(req, res))
+      });
+    }
   });
 }
 function enforceMountBodyLimit(req, res, maxBytes, logger) {