@devlab.group/agent-commerce 1.6.0 → 2.0.0

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import picocolors from 'picocolors';
 import { randomUUID } from 'crypto';
 import 'module';
 import Database from 'better-sqlite3';
-import { writeFile, stat, rename, rm, open } from 'fs/promises';
+import { writeFile, stat, mkdir, rename, rm, open } from 'fs/promises';
 import { validate } from '@scalar/openapi-parser';
 import * as clack from '@clack/prompts';
 
@@ -279,6 +279,12 @@ var init_backend_http = __esm({
     PATH_PARAM_PATTERN = /\{([a-zA-Z0-9_.-]+)\}/g;
   }
 });
+
+// src/core/execution/settlement-order.ts
+var init_settlement_order = __esm({
+  "src/core/execution/settlement-order.ts"() {
+  }
+});
 function typeList(raw) {
   if (typeof raw === "string") return [raw];
   if (Array.isArray(raw) && raw.every((entry) => typeof entry === "string")) {
@@ -302,6 +308,7 @@ var init_pipeline = __esm({
     init_errors();
     init_is_record();
     init_backend_http();
+    init_settlement_order();
     init_validation();
     [...RESERVED_INPUT_FIELDS, "__proto__"];
   }
@@ -341,12 +348,12 @@ var init_constants2 = __esm({
   "src/payments/mpp/constants.ts"() {
     MPP_SPEC_COMMIT = "806fdb8b8c92cda5c84b8660558921b6bbeef7e0";
     MPP_SPEC_DRAFTS = {
-      core: "draft-httpauth-payment-00",
+      core: "draft-httpauth-payment-01",
       intent: "draft-payment-intent-charge-00",
       method: "draft-evm-charge-00"
     };
     MPP_MIN_CHALLENGE_SECRET_LENGTH = 32;
-    MPPX_VERSION = "0.10.1";
+    MPPX_VERSION = "0.13.1";
     MPP_PROFILE = {
       intent: "charge",
       method: "evm",
@@ -419,7 +426,7 @@ var init_networks = __esm({
 });
 
 // src/protocols/acp/constants.ts
-var ACP_SPEC_VERSION, ACP_API_VERSION, ACP_WELL_KNOWN_PATH, ACP_CHECKOUT_OPERATIONS, ACP_OPERATION_INPUT_KEYS, ACP_OPERATION_OPTIONAL_INPUT_KEYS;
+var ACP_SPEC_VERSION, ACP_API_VERSION, ACP_WELL_KNOWN_PATH, ACP_CHECKOUT_OPERATIONS, ACP_OPERATION_INPUT_KEYS, ACP_OPERATION_OPTIONAL_INPUT_KEYS, ACP_SESSION_ID_INPUT_KEY;
 var init_constants3 = __esm({
   "src/protocols/acp/constants.ts"() {
     ACP_SPEC_VERSION = "2026-04-17";
@@ -442,6 +449,7 @@ var init_constants3 = __esm({
     ACP_OPERATION_OPTIONAL_INPUT_KEYS = {
       cancelCheckoutSession: ["body"]
     };
+    ACP_SESSION_ID_INPUT_KEY = "checkout_session_id";
   }
 });
 
@@ -694,6 +702,15 @@ var init_guardrails = __esm({
   }
 });
 
+// src/payments/x402/payment-flow.ts
+var X402_PAYMENT_FLOWS, X402_DEFAULT_PAYMENT_FLOW;
+var init_payment_flow = __esm({
+  "src/payments/x402/payment-flow.ts"() {
+    X402_PAYMENT_FLOWS = ["authorization", "upfront"];
+    X402_DEFAULT_PAYMENT_FLOW = "authorization";
+  }
+});
+
 // src/protocols/mcp/constants.ts
 var MCP_TOOL_NAME_CHARS, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_PATTERN;
 var init_constants4 = __esm({
@@ -836,6 +853,7 @@ function normalize(raw) {
         min: 1
       }
     ),
+    paymentFlow: x402Raw.paymentFlow ?? X402_DEFAULT_PAYMENT_FLOW,
     facilitator: normalizeFacilitator(x402Raw.facilitator),
     ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {},
     ...x402Raw.allowUnauthenticatedFacilitator !== void 0 ? {
@@ -867,7 +885,22 @@ function normalize(raw) {
   const resources = Object.entries(raw.resources).map(
     ([id, entry]) => normalizeResource(id, entry, protocols, x402, mpp, ap2)
   );
+  const resourcePaymentFlows = Object.fromEntries(
+    Object.entries(raw.resources).flatMap(
+      ([id, entry]) => entry.paymentFlow !== void 0 ? [[id, entry.paymentFlow]] : []
+    )
+  );
+  const hasFlowOverrides = Object.keys(resourcePaymentFlows).length > 0;
+  const x402WithFlows = x402 !== void 0 && hasFlowOverrides ? { ...x402, resourcePaymentFlows } : x402;
+  const mppWithFlows = mpp !== void 0 && hasFlowOverrides ? { ...mpp, resourcePaymentFlows } : mpp;
   if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
+  if (protocols.a2a.enabled && !resources.some((r) => r.exposedVia.includes("a2a"))) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      'protocols.a2a.enabled is true but no resource lists "a2a" in its expose',
+      { details: { path: "protocols.a2a.enabled" } }
+    );
+  }
   return {
     version: SUPPORTED_CONFIG_VERSION,
     merchant: {
@@ -886,8 +919,8 @@ function normalize(raw) {
     protocols,
     resources,
     payments: {
-      ...x402 !== void 0 ? { x402 } : {},
-      ...mpp !== void 0 ? { mpp } : {}
+      ...x402WithFlows !== void 0 ? { x402: x402WithFlows } : {},
+      ...mppWithFlows !== void 0 ? { mpp: mppWithFlows } : {}
     },
     ...ap2 !== void 0 ? { authorization: { ap2 } } : {}
   };
@@ -956,6 +989,14 @@ function normalizeAp2(raw) {
       "authorization.ap2.clockSkewSeconds",
       { min: 0, max: AP2_MAX_CLOCK_SKEW_SECONDS }
     ),
+    requireMandateAudience: toBoolean(
+      raw.requireMandateAudience ?? false,
+      "authorization.ap2.requireMandateAudience"
+    ),
+    requireMandateExpiry: toBoolean(
+      raw.requireMandateExpiry ?? false,
+      "authorization.ap2.requireMandateExpiry"
+    ),
     replay: { path: raw.replay.path }
   };
 }
@@ -1131,7 +1172,8 @@ function normalizeAcp(raw) {
         raw.idempotency.retentionHours ?? ACP_RETENTION_HOURS,
         "protocols.acp.idempotency.retentionHours",
         { min: ACP_RETENTION_HOURS }
-      )
+      ),
+      merchantIdempotent: raw.idempotency.merchantIdempotent ?? false
     },
     checkout: { operations: normalizeAcpOperations(raw.checkout) },
     // Built key by key so absent metadata stays absent rather than `undefined`
@@ -1214,10 +1256,11 @@ function validateAcpOperationInput(path2, operation, resource) {
   if (schema === void 0) return;
   const keys = ACP_OPERATION_INPUT_KEYS[operation];
   const optionalKeys = ACP_OPERATION_OPTIONAL_INPUT_KEYS[operation] ?? [];
-  const properties = schema["properties"];
-  if (schema["additionalProperties"] === false && isRecord(properties)) {
-    for (const key of [...keys, ...optionalKeys]) {
-      if (!Object.hasOwn(properties, key)) {
+  const sent = [...keys, ...optionalKeys];
+  const topLevel = closedObjectProperties(schema);
+  if (topLevel !== void 0) {
+    for (const key of sent) {
+      if (!Object.hasOwn(topLevel, key)) {
         const when = keys.includes(key) ? "always sends" : "sends when the caller supplies it";
         throw acpInvalid(
           path2,
@@ -1227,6 +1270,23 @@ function validateAcpOperationInput(path2, operation, resource) {
       }
     }
   }
+  const declared = isRecord(schema["properties"]) ? schema["properties"] : {};
+  const pathKeys = closedObjectProperties(declared["path"]);
+  if (sent.includes("path") && pathKeys !== void 0 && !Object.hasOwn(pathKeys, ACP_SESSION_ID_INPUT_KEY)) {
+    throw acpInvalid(
+      path2,
+      `Resource "${resource.id}" implements ACP operation "${operation}" but its "path" schema sets additionalProperties: false without declaring "${ACP_SESSION_ID_INPUT_KEY}", which the adapter always sends inside "path"`,
+      { resourceId: resource.id }
+    );
+  }
+  const bodyKeys = closedObjectProperties(declared["body"]);
+  if (sent.includes("body") && bodyKeys !== void 0 && Object.keys(bodyKeys).length === 0) {
+    throw acpInvalid(
+      path2,
+      `Resource "${resource.id}" implements ACP operation "${operation}" but its "body" schema accepts no keys, so it refuses every ACP document. Config load closes an object schema that omits additionalProperties: declare body as { type: object, additionalProperties: true }`,
+      { resourceId: resource.id }
+    );
+  }
   const required = schema["required"];
   if (Array.isArray(required)) {
     for (const entry of required) {
@@ -1240,6 +1300,10 @@ function validateAcpOperationInput(path2, operation, resource) {
     }
   }
 }
+function closedObjectProperties(schema) {
+  if (!isRecord(schema) || schema["additionalProperties"] !== false) return void 0;
+  return isRecord(schema["properties"]) ? schema["properties"] : {};
+}
 function normalizeFacilitator(raw) {
   return raw.mode === "local" ? { mode: "local", signerPrivateKey: raw.signerPrivateKey } : { mode: "remote", url: raw.url, auth: raw.auth ?? { type: "none" } };
 }
@@ -1270,6 +1334,7 @@ function normalizeMpp(raw) {
         { min: 1 }
       )
     } : {},
+    paymentFlow: raw.paymentFlow ?? X402_DEFAULT_PAYMENT_FLOW,
     facilitator: normalizeFacilitator(raw.facilitator),
     ...raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(raw.allowMainnet, "payments.mpp.allowMainnet") } : {},
     ...raw.allowUnauthenticatedFacilitator !== void 0 ? {
@@ -1423,6 +1488,13 @@ function normalizeResource(id, entry, protocols, x402, mpp, ap2) {
       validatePricingAmount(id, entry.pricing.amount, MPP_PROFILE.assetDecimals);
     }
   }
+  if (entry.paymentFlow !== void 0 && (entry.pricing.type !== "fixed" || !paymentMethods.some((method) => method === "x402" || method === "mpp"))) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Resource "${id}" sets paymentFlow, which requires fixed pricing and "x402" or "mpp" in payments`,
+      { details: { path: `resources.${id}.paymentFlow`, resourceId: id } }
+    );
+  }
   const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
   const authorization = normalizeResourceAuthorization(id, entry, pricing, ap2);
   return {
@@ -1745,6 +1817,7 @@ var init_schema = __esm({
     init_is_record();
     init_constants2();
     init_guardrails();
+    init_payment_flow();
     init_constants3();
     init_constants4();
     init_env();
@@ -1812,7 +1885,11 @@ var init_schema = __esm({
       }
     );
     AcpAuthSchema = z.object({ type: z.literal("bearer"), token: z.string().min(1) }).strict();
-    AcpIdempotencySchema = z.object({ path: z.string().min(1), retentionHours: NumberOrString.optional() }).strict();
+    AcpIdempotencySchema = z.object({
+      path: z.string().min(1),
+      retentionHours: NumberOrString.optional(),
+      merchantIdempotent: z.boolean().optional()
+    }).strict();
     AcpCheckoutSchema = z.object({ operations: z.record(z.string().min(1)) }).strict();
     AcpDiscoverySchema = z.object({
       documentationUrl: z.string().min(1).optional(),
@@ -1882,6 +1959,7 @@ var init_schema = __esm({
       pricing: PricingSchema,
       expose: z.array(z.string().min(1)).min(1),
       payments: z.array(z.string().min(1)).optional(),
+      paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
       authorization: z.object({ required: z.array(z.string().min(1)).min(1) }).strict().optional()
     }).strict();
     ResourcesMapSchema = z.record(z.string().min(1), ResourceEntrySchema);
@@ -1919,6 +1997,8 @@ var init_schema = __esm({
       assetDecimals: NumberOrString,
       payTo: z.string().min(1),
       maxTimeoutSeconds: NumberOrString,
+      // `authorization` (the x402 default) settles after the backend call
+      paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
       facilitator: FacilitatorSchema,
       // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
       allowMainnet: BooleanOrString.optional(),
@@ -1936,6 +2016,8 @@ var init_schema = __esm({
       realm: z.string().min(1),
       challengeSecret: z.string().min(1),
       challengeTtlSeconds: NumberOrString.optional(),
+      // Same values and default as `payments.x402.paymentFlow`
+      paymentFlow: z.enum(X402_PAYMENT_FLOWS).optional(),
       facilitator: FacilitatorSchema,
       // Real funds. Never defaulted; see src/payments/x402/guardrails.ts
       allowMainnet: BooleanOrString.optional(),
@@ -1966,6 +2048,8 @@ var init_schema = __esm({
         checkoutIssuers: z.array(Ap2IssuerSchema).optional()
       }).strict().optional(),
       clockSkewSeconds: NumberOrString.optional(),
+      requireMandateAudience: BooleanOrString.optional(),
+      requireMandateExpiry: BooleanOrString.optional(),
       replay: z.object({ path: z.string().min(1) }).strict().optional()
     }).strict();
     AuthorizationSchema = z.object({ ap2: Ap2Schema.optional() }).strict();
@@ -2166,10 +2250,12 @@ var AP2_UNSUPPORTED = [
   // Mandate kinds. Open mandates are refused: see AP2_CHECKOUT_MANDATE_VCT
   "autonomous mode",
   "open checkout mandates (mandate.checkout.open.1)",
-  "intent mandates",
-  "cart mandates",
+  "payment mandates (mandate.payment.1)",
   "spending constraint evaluation",
   "cnf-bound agent keys",
+  // Delegation models other than a trusted agent provider
+  "user credential delegation (OpenID4VP)",
+  "delegation chains and key-binding JWTs",
   // Key handling. Every key is written into config by an operator
   "JWKS and any key discovery by URL (jku, x5u)",
   "issuer metadata fetching",
@@ -2179,6 +2265,7 @@ var AP2_UNSUPPORTED = [
   "digest algorithms other than sha-256",
   // Roles this gateway does not play
   "mandate issuance",
+  "checkout receipts",
   "AP2 over the ACP checkout adapter"
 ];
 
@@ -2189,20 +2276,23 @@ init_constants2();
 init_networks();
 
 // src/protocols/a2a/constants.ts
-var A2A_SPEC_VERSION = "1.0.0";
+var A2A_SPEC_VERSION = "1.0.1";
 var A2A_PROTOCOL_VERSION = "1.0";
 var A2A_PROTOCOL_BINDING = "JSONRPC";
 var A2A_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+var A2A_PUSH_CONFIG_METHODS = [
+  "CreateTaskPushNotificationConfig",
+  "GetTaskPushNotificationConfig",
+  "ListTaskPushNotificationConfigs",
+  "DeleteTaskPushNotificationConfig"
+];
 var A2A_UNSUPPORTED_METHODS = [
   "SendStreamingMessage",
   "GetTask",
   "ListTasks",
   "CancelTask",
   "SubscribeToTask",
-  "CreateTaskPushNotificationConfig",
-  "GetTaskPushNotificationConfig",
-  "ListTaskPushNotificationConfigs",
-  "DeleteTaskPushNotificationConfig",
+  ...A2A_PUSH_CONFIG_METHODS,
   "GetExtendedAgentCard"
 ];
 
@@ -2216,12 +2306,14 @@ var A2A_UNSUPPORTED = [
   // Behaviors
   "SSE",
   "long-running task persistence",
-  "task resumption",
+  "task resumption other than an x402 extension payment",
   "push notifications",
   "multi-turn conversational continuation",
   "authenticated extended agent cards",
   "A2A authentication schemes",
-  "artifact types beyond Agent Commerce outcome data"
+  "artifact types beyond Agent Commerce outcome data",
+  // Pending x402 payments live in process memory
+  "x402 extension payments across gateway restarts or instances"
 ];
 
 // src/cli/commands/doctor.ts
@@ -2233,7 +2325,9 @@ init_constants3();
   "rest transport",
   "well-known discovery",
   "bearer authentication",
-  "API-Version negotiation",
+  "API-Version enforcement",
+  // Forwarded as received: the gateway verifies neither signature header
+  "request header forwarding to the merchant",
   "checkout service",
   ...ACP_CHECKOUT_OPERATIONS
 ];
@@ -2262,7 +2356,7 @@ var ACP_UNSUPPORTED = [
 
 // src/storage/receipts/store.ts
 init_core();
-var PACKAGE_VERSION = "1.6.0" ;
+var PACKAGE_VERSION = "2.0.0" ;
 
 // src/storage/sqlite.ts
 init_core();
@@ -2558,6 +2652,9 @@ function createSqliteReceiptStore(options) {
   const listPaymentAttemptsByRequestStmt = db.prepare(
     "SELECT * FROM payment_attempts WHERE request_id = ? ORDER BY created_at DESC, seq DESC LIMIT ?"
   );
+  const paymentAttemptStatusStmt = db.prepare(
+    "SELECT status FROM payment_attempts WHERE replay_key = ?"
+  );
   let closed = false;
   const descriptor = {
     name: "sqlite-receipt-store",
@@ -2614,10 +2711,15 @@ function createSqliteReceiptStore(options) {
         });
       } catch (err) {
         if (isUniqueConstraintOn(err, "payment_attempts.replay_key")) {
+          const existing = paymentAttemptStatusStmt.get(reservation.replayKey);
           throw new CommerceError(
             "PAYMENT_REPLAYED",
             `Payment authorization has already been used (replayKey=${reservation.replayKey})`,
-            { requestId: reservation.requestId, resourceId: reservation.resourceId }
+            {
+              requestId: reservation.requestId,
+              resourceId: reservation.resourceId,
+              ...existing !== void 0 ? { details: { attemptStatus: existing.status } } : {}
+            }
           );
         }
         throw toCommerceError(err, "STORAGE_ERROR", "Failed to reserve payment attempt");
@@ -3003,7 +3105,7 @@ var package_default = {
     "ajv-formats": "3.0.1",
     "better-sqlite3": "13.0.3",
     commander: "15.0.0",
-    fastify: "5.12.0",
+    fastify: "5.12.5",
     picocolors: "1.1.1",
     pino: "10.3.1",
     yaml: "2.9.0",
@@ -3011,19 +3113,19 @@ var package_default = {
   },
   peerDependencies: {
     "@coinbase/x402": "2.1.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.3.0",
     "@sd-jwt/core": "0.20.1",
-    "@x402/core": "2.23.0",
-    "@x402/evm": "2.23.0",
+    "@x402/core": "2.25.0",
+    "@x402/evm": "2.25.0",
     canonicalize: "5.0.0",
     jose: "6.2.12",
-    mppx: "0.10.1",
-    viem: "2.55.18"
+    mppx: "0.13.1",
+    viem: "2.57.1"
   }};
 
 // src/cli/lib/versions.ts
 var PINS = [
-  ["@modelcontextprotocol/sdk", "protocols/mcp"],
+  ["@modelcontextprotocol/server", "protocols/mcp"],
   ["ajv", "protocols/acp"],
   ["ajv-formats", "protocols/acp"],
   ["@x402/core", "payments/x402"],
@@ -3071,6 +3173,11 @@ function substitutePathParams(url) {
   }
   return filled;
 }
+function describePaymentFlow(rail) {
+  const overrides = Object.keys(rail.resourcePaymentFlows ?? {}).length;
+  const overrideCount = overrides > 0 ? ` (${overrides} resource ${overrides === 1 ? "override" : "overrides"})` : "";
+  return `paymentFlow=${rail.paymentFlow ?? "authorization"}${overrideCount}`;
+}
 function extractWellKnownX402(body, rail = "x402") {
   const payments = body?.["payments"];
   if (typeof payments !== "object" || payments === null) return void 0;
@@ -3327,7 +3434,7 @@ async function runDoctor(options, deps = {}) {
     checks.push({
       name: "AP2",
       status: "PASS",
-      detail: `experimental \xB7 spec ${AP2_SPEC_VERSION} \xB7 mode ${ap2.mode} \xB7 ${AP2_CHECKOUT_MANDATE_VCT} \xB7 profile ${AP2_CHECKOUT_PROFILE} \xB7 clock skew ${ap2.clockSkewSeconds}s`
+      detail: `experimental \xB7 spec ${AP2_SPEC_VERSION} \xB7 mode ${ap2.mode} \xB7 ${AP2_CHECKOUT_MANDATE_VCT} \xB7 profile ${AP2_CHECKOUT_PROFILE} \xB7 clock skew ${ap2.clockSkewSeconds}s \xB7 mandate aud ${ap2.requireMandateAudience === true ? "required" : "optional"} \xB7 mandate exp ${ap2.requireMandateExpiry === true ? "required" : "optional"}`
     });
     checks.push({
       name: "AP2 trust",
@@ -3359,7 +3466,8 @@ async function runDoctor(options, deps = {}) {
     checks.push({ name: "Payments", status: "INFO", detail: "x402 not configured" });
   } else {
     const { mode, where, via } = describeSettlement(x402.network, x402.facilitator);
-    const summary = `x402 v2 (scheme=exact) enabled - ${where}, destination=${maskMiddle(x402.payTo)}, facilitator=${via}`;
+    const flow = describePaymentFlow(x402);
+    const summary = `x402 v2 (scheme=exact) enabled - ${where}, destination=${maskMiddle(x402.payTo)}, facilitator=${via}, ${flow}`;
     const live = wellKnown?.ok ? extractWellKnownX402(wellKnown.body) : void 0;
     if (sameAddress2(x402.asset, PLACEHOLDER_ASSET_ADDRESS)) {
       checks.push({
@@ -3394,7 +3502,7 @@ async function runDoctor(options, deps = {}) {
     checks.push({ name: "Payments (MPP)", status: "INFO", detail: "MPP not configured" });
   } else {
     const { mode, where, via } = describeSettlement(mpp.network, mpp.facilitator);
-    const summary = `MPP ${MPP_PROFILE.intent}/${MPP_PROFILE.method}/${MPP_PROFILE.credentialType} enabled - ${where}, asset=${MPP_PROFILE.assetSymbol} ${maskMiddle(mpp.asset)}, recipient=${maskMiddle(mpp.recipient)}, facilitator=${via}, spec ${MPP_SPEC_DRAFTS.core}@${MPP_SPEC_COMMIT.slice(0, 7)}, mppx ${MPPX_VERSION}`;
+    const summary = `MPP ${MPP_PROFILE.intent}/${MPP_PROFILE.method}/${MPP_PROFILE.credentialType} enabled - ${where}, asset=${MPP_PROFILE.assetSymbol} ${maskMiddle(mpp.asset)}, recipient=${maskMiddle(mpp.recipient)}, facilitator=${via}, ${describePaymentFlow(mpp)}, spec ${MPP_SPEC_DRAFTS.core}@${MPP_SPEC_COMMIT.slice(0, 7)}, mppx ${MPPX_VERSION}`;
     const configured = { asset: mpp.asset, network: mpp.network, payTo: mpp.recipient };
     const live = wellKnown?.ok ? extractWellKnownX402(wellKnown.body, "mpp") : void 0;
     if (live === "disabled") {
@@ -4662,6 +4770,7 @@ async function writeAtomically(outputPath, content, deps) {
   const target = resolve(outputPath);
   const temporary = `${target}.${process.pid}.tmp`;
   try {
+    await mkdir(dirname(target), { recursive: true });
     await writeFile(temporary, content, "utf8");
     await rename(temporary, target);
   } catch (error) {