@reactionary/acp 0.10.42 → 0.10.44

package/README.md

@@ -8,51 +8,48 @@ The package keeps Reactionary core protocol-neutral: host applications mount thi
 
 The adapter implements the merchant-hosted ACP checkout endpoints:
 
-- `GET /product_feeds/{id}/products`
 - `POST /checkout_sessions`
 - `POST /checkout_sessions/{checkout_session_id}`
 - `GET /checkout_sessions/{checkout_session_id}`
 - `POST /checkout_sessions/{checkout_session_id}/complete`
 - `POST /checkout_sessions/{checkout_session_id}/cancel`
 
+and the cart capability:
+
+- `POST /carts`
+- `GET /carts/{id}`
+- `PUT /carts/{id}` (full replacement of line items)
+- `POST /carts/{id}/cancel`
+
+Carts are pre-checkout baskets over a backend cart: no status (canceled or expired carts answer 404), no payment and no capability negotiation; totals are estimates. They expire after `checkoutSessionTtlSeconds`, refreshed on update, and are visible only to the agent that created them.
+
 It also serves a readiness document from `GET` / `HEAD`.
 
 If the adapter is mounted under `/acp`, both `/checkout_sessions/...` and `/acp/checkout_sessions/...` paths are understood. Set `basePath` when mounting somewhere else.
 
-## Discovery
-
-`GET /.well-known/acp.json` (alias `/.well-known/acp`) serves the ACP discovery document with `Cache-Control: public, max-age=3600`. It advertises the `checkout` service, plus `feeds` when `productFeed` is configured. `api_base_url` defaults to the request origin plus `basePath` (default `/acp`); override it and other fields with the `discovery` option. The host application must route the well-known path to this handler. Payment handlers are not part of ACP discovery; they are negotiated per checkout session.
+## Protocol version
 
-## Product feed generation
+The adapter implements ACP API version `2026-04-17` only. Checkout requests must send `API-Version: 2026-04-17`; requests without it, or with another version, are rejected with `400` and code `missing_api_version` / `unsupported_api_version`, listing `supported_versions`.
 
-`GET /product_feeds/{id}/products` generates an ACP-compatible product feed from the configured feed definition whose key matches `{id}`.
+## MCP transport
 
-The feed enumeration and serialization pipeline is shared with `@reactionary/feeds`; this adapter keeps the ACP-compatible route shape while delegating normalization and ACP product feed output to the reusable feed package.
+With `mcp: true`, the adapter also serves the ACP MCP binding at `{basePath}/mcp`: JSON-RPC 2.0 over Streamable HTTP (JSON responses) with `initialize`, `ping`, `tools/list` and `tools/call` for the five checkout tools (`create_`, `get_`, `update_`, `complete_`, `cancel_checkout_session`). Tool arguments are `{ meta, id?, payload? }`: `meta` maps to the protocol headers (`api_version` is required), `id` to the path and `payload` to the REST body; the MCP connection's `Authorization` applies to every call. Results are the REST bodies as-is (the ACP binding's mapping); errors are `-32000` with the ACP `Error` in `data`, `-32602` for malformed arguments. Tool calls without `meta.idempotency_key` get a fresh key. Discovery then lists `mcp` in `transports`.
 
-Each feed definition provides:
+## Authentication
 
-- `languageContext` — applied to the `RequestContext` before the Reactionary client is created.
-- `search` — a `ProductSearchIdentifierSchema`-compatible search object passed to `productSearch.queryByTerm`.
-- `productUrlBase` — either a base URL that the product slug is resolved against, or a URL template supporting `{lang}` and `{slug}` placeholders.
+ACP requires agents to authenticate with `Authorization: Bearer <token>`. Configure `authenticate` with a function returning the calling agent (or `undefined` for 401); `createBearerTokenAuthenticator({ agentId: token })` covers static per-agent tokens, and request-signature checks can be added in the same hook. A checkout session is visible only to the agent that created it — others get 404. Discovery and the readiness document stay public. Without `authenticate` the checkout endpoints are open and a warning is logged.
 
-By default it returns the ACP JSON shape:
+## Idempotency
 
-```json
-{
-  "target_country": "FI",
-  "products": []
-}
-```
+Every checkout `POST` must carry an `Idempotency-Key` (at most 255 characters), scoped to the authenticated agent and endpoint. Repeating a request with the same key and a semantically equal JSON body returns the stored response with `Idempotent-Replayed: true` and no side effects; a different body answers `422 idempotency_conflict`, and a key still being processed `409 idempotency_in_flight` with `Retry-After`. Missing keys answer `400 idempotency_key_required`. Responses are kept for `idempotencyTtlSeconds` (at least 24 hours) in `sessionCache`; server errors are never stored. Concurrent requests are serialized per instance; across instances the in-flight marker in the shared cache is best effort, as the `Cache` interface has no atomic insert.
 
-`target_country` is derived from `languageContext.locale` when the locale includes a region, e.g. `fi-FI` -> `FI`.
+## Discovery
 
-For file generation, request JSONL:
+`GET /.well-known/acp.json` (alias `/.well-known/acp`) serves the ACP discovery document with `Cache-Control: public, max-age=3600`. It advertises protocol version `2026-04-17` and the `checkout` and `carts` services (the services enum is closed per version: `checkout`, `orders`, `delegate_payment`, `carts`), the `intervention_types` of the `interventions` option, and the extensions the server implements. `api_base_url` defaults to the request origin plus `basePath` (default `/acp`); override it and other fields with the `discovery` option. The host application must route the well-known path to this handler. Payment handlers are not part of ACP discovery; they are negotiated per checkout session.
 
-```bash
-curl "https://example.com/acp/product_feeds/default/products?format=jsonl" > products.jsonl
-```
+## Product feeds
 
-The first implementation streams the response directly instead of generating a download URL. That keeps the adapter stateless and lets callers pipe the result to a file, object storage upload, or feed-ingestion job. A signed download URL can be layered on later by a host application or a storage-backed feed job.
+ACP feeds are **pushed** by the merchant to the agent's Feed API (2026-04-17): the agent hosts `POST /feeds` and `GET`/`PATCH /feeds/{id}/products`, and never calls the merchant for feeds, so this server has no feed endpoints. Publish feeds from a scheduled job with the `@reactionary/feeds` CLI (`reactionary-feeds publish-acp`), configured with the Feed API URL, API key and feed ids from the agent's onboarding — see "Publishing ACP feeds to an agent" in the `@reactionary/feeds` README. `ReactionaryACPFeedPublisher` is re-exported here for programmatic use.
 
 ## Required Reactionary capabilities
 
@@ -67,15 +64,10 @@ Required operations:
 - `checkout.getById`
 - `checkout.setShippingAddress`
 - `checkout.getAvailableShippingMethods`
-- `checkout.getAvailablePaymentMethods`
 - `checkout.setShippingInstruction`
 - `checkout.addPaymentInstruction`
 - `checkout.finalizeCheckout`
-- `productSearch.queryByTerm`
 - `product.getBySKU`
-- `price.getListPrice`
-- `price.getCustomerPrice`
-- `inventory.getBySKU`
 
 This is deliberate because Reactionary clients can be built with different capability sets. A partially capable client should fail fast instead of advertising ACP checkout.
 
@@ -122,40 +114,43 @@ new ReactionaryACPServer(createClient, {
   sessionCache: redisCache,
   sessionTtlSeconds: 60 * 60,
   checkoutSessionTtlSeconds: 60 * 60,
-  productFeed: {
-    feeds: {
-      finnish: {
-        languageContext: {
-          locale: 'fi-FI',
-          currencyCode: 'EUR',
-        },
-        search: {
-          term: '',
-          facets: [],
-          filters: ['market:fi'],
-          paginationOptions: {
-            pageNumber: 1,
-            pageSize: 50,
-          },
-        },
-        productUrlBase: 'https://shop.example/{lang}/products/{slug}',
-      },
-    },
-  },
 });
 ```
 
+## Specification conformance
+
+`acp-spec-conformance.spec.ts` validates every response shape the adapter produces — checkout sessions in each state (including `complete_in_progress`, `authentication_required`, declined, canceled and completed with order), errors, discovery, carts and webhook orders — against the official ACP 2026-04-17 JSON Schemas vendored in `src/lib/__fixtures__`, includes negative controls, and replays the specification's example requests. The ACP e2e suite validates the live backend's responses against the same schemas, and `@reactionary/feeds` validates feed products and metadata against the Feed schema.
+
 ## Mapping notes
 
-- ACP item `id` maps to Reactionary `ProductVariantIdentifier.sku`.
+- ACP item `id` maps to Reactionary `ProductVariantIdentifier.sku`. Requests send `line_items`; an item's optional `quantity` (decimal, default 1) is outside the 2026-04-17 `Item` schema but accepted as the checkout RFC sends it, and repeated ids add up.
+- The buyer follows the 2026-04-17 `Buyer` schema (`email` required; names, phone, company, loyalty and tax exemption optional). Buyer updates are merged into what the session already holds.
+- `fulfillment_details` (contact and nested address) is the shipping address; its email and phone stand in for the buyer's. `selected_fulfillment_options` picks the backend shipping method (one per checkout, so the first selection applies to all line items). `null` clears either field.
+- Create requests must declare the agent's `capabilities`. Every session response returns the negotiated `capabilities`: `interventions.supported` is the intersection of the agent's declaration with the `interventions` server option (none by default), plus the seller's `required` interventions and `enforcement`. A required intervention the agent lacks, enforced `always`, blocks the session with an `intervention_required` message.
+- Responses echo `Request-Id`, and `Idempotency-Key` on POSTs. When `discovery.supportedLocales` is set, requests are localized to the best match of their `Accept-Language` (exact tag, else same language); other locales are ignored.
+- Sessions report what is still needed in `messages[]`: `missing` buyer email, shipping address or fulfillment option, an `invalid` (unavailable) fulfillment option, and — with the `inventory` option's fulfillment centers — `out_of_stock` line items. Each carries its JSONPath `param` and a `resolution`; any error keeps the session `not_ready_for_payment`, and completing such a session answers 400 with the first blocking message.
+- Completion waits up to `paymentAuthorizationWait` for the backend to authorize the payment. If it is still pending, the session answers `complete_in_progress` without an order and with an info message; retrieving the session (or completing again with a new `Idempotency-Key`) reports `completed` with the order once the backend has it. `completed` always carries the order.
+- Completed sessions carry `order { type, id, checkout_session_id, permalink_url }`; `permalink_url` comes from the `orderPermalinkUrl` template (`{orderId}` placeholder). Without it the permalink is omitted and a warning is logged.
+- When the backend offers no fulfillment option for an address, the session reports `region_restricted` and cannot become payable — unless `requireFulfillment: false` (stores selling only goods that need no shipping).
+- 3D Secure: with the `authentication` option, `getMetadata(...)` decides per completion whether issuer authentication is needed. If so, completion answers `authentication_required` with `authentication_metadata`; completing again without `authentication_result` is `400 requires_3ds`, an unsuccessful outcome is not authorized (`payment_declined` message), and a successful one is passed to the backend as protocol data `acp_authentication_result`. Updating the session drops a pending authentication.
+- Discount extension: when the client supports `cart.applyCouponCode`/`removeCouponCode` and the agent declares `discount` in `capabilities.extensions`, sessions activate the extension. `discounts.codes` (or the deprecated `coupons`) replace the submitted codes (case-insensitive, `[]` clears); responses carry `discounts { codes, applied, rejected }` and a `discount_code_invalid` warning per rejected code. Discovery lists the `discount` extension.
+- Affiliate attribution: `affiliate_attribution` (provider plus token or publisher id, flat metadata up to 20 keys/4KB) is accepted on create (first touch) and complete (last touch, first claim wins). Once the order exists, both are passed to the `onOrderAttribution` hook; they are never returned, sent in webhooks or logged.
+- Marketing consent: the `marketingConsent` option lists channels offered on every open session (`marketing_consent_options`, with `is_subscribed` from `isSubscribed`). Decisions in the complete request's `marketing_consents` go to `onConsents` once the order exists — only offered channels with a resolvable contact (email: buyer, then fulfillment email; sms/whatsapp: phone). Omitted channels keep their state.
+- Cancel accepts an optional `intent_trace` (reason code, summary up to 500 characters, flat metadata). Unknown reason codes count as `other`; the trace is kept on the session and passed to the `onIntentTrace` hook but never returned to agents.
+- Fulfillment types: backend shipping methods are `shipping` options unless `classifyFulfillmentOption(method)` classifies them as `digital`, `pickup` (with `location`, `pickup_type`, `ready_by`, `pickup_by`) or `local_delivery` (with `delivery_window`, `service_area`); selections and order webhooks follow the classification.
+- Sessions report `locale` and `timezone` (from the create request, else the request context locale), `created_at`, `updated_at`, and while open `expires_at` and — with the `continueUrl` template (`{checkoutSessionId}`) — `continue_url`.
+- A declined payment answers the session (200) still `ready_for_payment`, with a `payment_declined` error message, so the agent can retry with another instrument; the declined backend checkout is discarded.
+- The create request's `currency` sets the request context currency for the session's lifetime.
 - ACP amounts are returned as integer minor units.
-- ACP product feed variant `price` comes from `price.getCustomerPrice`, which includes active customer/global campaign prices and can fall back to list prices in providers.
-- ACP product feed variant `list_price` comes from `price.getListPrice`.
-- ACP product feed availability comes from `inventory.getBySKU`.
-- ACP payment data is passed as checkout payment-instruction protocol data with key `delegated_payment_token`.
-- Fulfillment options are sourced from `checkout.getAvailableShippingMethods`.
-- Payment provider information is sourced from `checkout.getAvailablePaymentMethods`, with a configurable fallback through `paymentProvider`.
+- Line items report `item.id` (the SKU), `quantity`, `unit_amount` and a `totals[]` breakdown (`items_base_amount`, `discount`, `subtotal`, `total`), plus `name`, `description`, `images`, `product_id`, `sku` and `variant_options` from `product.getBySKU`. Per-line tax is not known to the cart and is not reported.
+- Feed variant `price` comes from `price.getCustomerPrice` (active customer/global campaign prices, falling back to list prices in providers), `list_price` from `price.getListPrice` when it is higher, and availability from `inventory.getBySKU`.
+- Completion takes `payment_data { handler_id, instrument { type, credential { type, token } }, billing_address? }`. The handler must be one advertised in `paymentHandlers`; the credential token is passed to the backend as payment-instruction protocol data `delegated_payment_token` (with `delegated_payment_provider` = the handler's PSP, plus `acp_payment_handler_id`, `acp_payment_instrument_type`, `acp_payment_credential_type`). `billing_address` becomes the checkout's billing address. Raw card credentials are refused unless `acceptRawCardCredentials` is set; purchase-order payments are not supported.
+- The `links` option lists policy links (`terms_of_use`, `privacy_policy`, `return_policy`, `shipping_policy`, `contact_us`, `about_us`, `faq`, `support`, with an optional `title`) returned on every session.
+- Fulfillment options are sourced from `checkout.getAvailableShippingMethods` as `shipping` options with a distinct `title`, the delivery estimate as `description`, the `carrier`, and the cost as `totals[]`.
+- Payment handlers are configured with the `paymentHandlers` option and advertised in `capabilities.payment.handlers`; `createTokenizedCardHandler({ psp, merchantId })` builds the reference `dev.acp.tokenized.card` handler. Each handler maps to the backend payment method its payments are placed with (default: method `card`, name and processor = the handler's PSP). Handler configs must carry `merchant_id` and `psp`; without handlers, `capabilities.payment` is omitted.
 
 Use `@reactionary/feeds` directly when you want Google Merchant, sitemap XML, or PriceRunner outputs from the same feed definitions.
 
-Product-feed upsert/push APIs and order webhooks are separate ACP surfaces and are not implemented yet.
+## Order webhooks
+
+With `webhooks: { endpoints: [{ url, secret, agentId? }] }`, orders placed through a checkout session are announced to the creating agent's receiver (`order_create`), and `server.notifyOrderUpdated(orderId)` sends `order_update` with the order's current state — call it when your OMS changes the order (ships, cancels). Events carry the full ACP `Order` (status, line items with ordered/current/fulfilled quantities, the shipping fulfillment, totals) and are signed with `Merchant-Signature: t=<unix>,v1=<HMAC-SHA256 hex of "t.body">` using the endpoint secret (`signWebhookPayload` builds the header). Failed deliveries are retried in memory (0.5s … 5m). Webhooks need the client's `order.getById`, and discovery then advertises the `orders` service.

package/index.js

@@ -1,2 +1,13 @@
 export * from "./lib/acp-schemas.js";
 export * from "./lib/reactionary-acp-server.js";
+export * from "./lib/acp-payment-handlers.js";
+import {
+  ReactionaryACPFeedPublisher,
+  createACPFeedPublisherFromConfig
+} from "@reactionary/feeds";
+export * from "./lib/acp-webhooks.js";
+export * from "./lib/acp-discounts.js";
+export {
+  ReactionaryACPFeedPublisher,
+  createACPFeedPublisherFromConfig
+};

package/lib/acp-discounts.js

@@ -0,0 +1,113 @@
+import * as z from "zod";
+const ACP_DISCOUNT_EXTENSION = {
+  name: "discount",
+  extends: [
+    "$.CheckoutSessionCreateRequest.discounts",
+    "$.CheckoutSessionUpdateRequest.discounts",
+    "$.CheckoutSession.discounts"
+  ]
+};
+const ACPDiscountsRequestSchema = z.object({
+  codes: z.array(z.string().min(1)).optional()
+});
+const ACPRejectedDiscountSchema = z.object({
+  code: z.string(),
+  reason: z.string(),
+  message: z.string().optional()
+});
+function getRequestedDiscountCodes(discounts, coupons) {
+  return discounts?.codes ?? coupons;
+}
+async function applyDiscountCodes(cartCapability, cart, codes) {
+  const { applyCouponCode, removeCouponCode } = cartCapability;
+  if (!applyCouponCode || !removeCouponCode) {
+    return { cart, rejected: codes.map(rejectedCode) };
+  }
+  let current = cart;
+  const requested = new Set(codes.map((code) => code.toUpperCase()));
+  for (const code of getAppliedCodes(current)) {
+    if (!requested.has(code.toUpperCase())) {
+      const removed = await cartCapability.removeCouponCode?.({ cart: current.identifier, couponCode: code });
+      if (removed?.success) {
+        current = removed.value;
+      }
+    }
+  }
+  const rejected = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const code of codes) {
+    const normalized = code.toUpperCase();
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    if (getAppliedCodes(current).some((candidate) => candidate.toUpperCase() === normalized)) {
+      continue;
+    }
+    const applied = await applyCode(cartCapability, current, code);
+    if (applied) {
+      current = applied;
+    } else {
+      rejected.push(rejectedCode(code));
+    }
+  }
+  return { cart: current, rejected };
+}
+async function applyCode(cartCapability, cart, code) {
+  for (const candidate of /* @__PURE__ */ new Set([code, code.toUpperCase()])) {
+    const result = await cartCapability.applyCouponCode?.({ cart: cart.identifier, couponCode: candidate });
+    if (result?.success) {
+      return result.value;
+    }
+  }
+  return void 0;
+}
+function toACPDiscounts(cart, codes, rejected, toMinorUnits) {
+  const promotions = cart.appliedPromotions;
+  const lineDiscounts = cart.items.map((item) => Math.abs(toMinorUnits(item.price.totalDiscount)));
+  const itemsDiscount = lineDiscounts.reduce((sum, amount) => sum + amount, 0);
+  const totalDiscount = Math.max(Math.abs(toMinorUnits(cart.price.totalDiscount)), itemsDiscount);
+  const soleLineAllocated = promotions.length === 1 && totalDiscount === itemsDiscount && itemsDiscount > 0;
+  return {
+    codes,
+    applied: promotions.map((promotion, index) => {
+      const amount = promotion.amount ? Math.abs(toMinorUnits(promotion.amount)) : promotions.length === 1 ? totalDiscount : 0;
+      const name = promotion.name || promotion.code || "Discount";
+      return {
+        id: `discount_${index + 1}`,
+        ...promotion.isCouponCode && promotion.code ? { code: promotion.code } : {},
+        coupon: {
+          id: promotion.code || `promotion_${index + 1}`,
+          name,
+          amount_off: amount,
+          currency: cart.price.grandTotal.currency.toLowerCase()
+        },
+        amount,
+        automatic: !promotion.isCouponCode,
+        ...soleLineAllocated ? {
+          method: "each",
+          allocations: lineDiscounts.flatMap((lineAmount, lineIndex) => lineAmount > 0 ? [{ path: `$.line_items[${lineIndex}]`, amount: lineAmount }] : [])
+        } : {}
+      };
+    }),
+    rejected
+  };
+}
+function getAppliedCodes(cart) {
+  return cart.appliedPromotions.filter((promotion) => promotion.isCouponCode && promotion.code).map((promotion) => promotion.code);
+}
+function rejectedCode(code) {
+  return {
+    code,
+    reason: "discount_code_invalid",
+    message: `Discount code '${code}' could not be applied.`
+  };
+}
+export {
+  ACPDiscountsRequestSchema,
+  ACPRejectedDiscountSchema,
+  ACP_DISCOUNT_EXTENSION,
+  applyDiscountCodes,
+  getRequestedDiscountCodes,
+  toACPDiscounts
+};

package/lib/acp-idempotency.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import * as z from "zod";
+const IDEMPOTENCY_CACHE_KEY_PREFIX = "reactionary:acp:idempotency";
+const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
+const ACP_MIN_IDEMPOTENCY_TTL_SECONDS = 24 * 60 * 60;
+const IN_FLIGHT_TTL_SECONDS = 60;
+const RETRY_AFTER_SECONDS = 1;
+const ACPIdempotencyRecordSchema = z.looseObject({
+  fingerprint: z.string(),
+  inFlight: z.boolean(),
+  status: z.number().optional(),
+  body: z.string().optional()
+});
+class ACPIdempotency {
+  constructor(cache, ttlSeconds) {
+    this.cache = cache;
+    this.ttlSeconds = ttlSeconds;
+  }
+  cache;
+  ttlSeconds;
+  /** Fingerprints of the requests in flight on this instance, by cache key. */
+  inFlight = /* @__PURE__ */ new Map();
+  async run(request, scope, handle) {
+    const idempotencyKey = request.headers.get("idempotency-key");
+    if (!idempotencyKey) {
+      return idempotencyError(400, "idempotency_key_required", "Idempotency-Key header is required on all POST requests");
+    }
+    if (idempotencyKey.length > IDEMPOTENCY_KEY_MAX_LENGTH) {
+      return idempotencyError(400, "invalid", `Idempotency-Key must be at most ${IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
+    }
+    const cacheKey = `${IDEMPOTENCY_CACHE_KEY_PREFIX}:${hash(`${scope}
+${new URL(request.url).pathname}
+${idempotencyKey}`)}`;
+    const fingerprint = await getBodyFingerprint(request);
+    const inFlightFingerprint = this.inFlight.get(cacheKey);
+    if (inFlightFingerprint !== void 0) {
+      return replay({ fingerprint: inFlightFingerprint, inFlight: true }, fingerprint);
+    }
+    this.inFlight.set(cacheKey, fingerprint);
+    try {
+      const existing = await this.cache.get(cacheKey, ACPIdempotencyRecordSchema);
+      if (existing) {
+        return replay(existing, fingerprint);
+      }
+      await this.put(cacheKey, { fingerprint, inFlight: true }, IN_FLIGHT_TTL_SECONDS);
+      const response = await handle();
+      if (response.status >= 500) {
+        await this.cache.invalidate([cacheKey]);
+        return response;
+      }
+      await this.put(cacheKey, {
+        fingerprint,
+        inFlight: false,
+        status: response.status,
+        body: await response.clone().text()
+      }, this.ttlSeconds);
+      return response;
+    } catch (error) {
+      await this.cache.invalidate([cacheKey]);
+      throw error;
+    } finally {
+      this.inFlight.delete(cacheKey);
+    }
+  }
+  async put(cacheKey, record, ttlSeconds) {
+    await this.cache.invalidate([cacheKey]);
+    await this.cache.put(cacheKey, record, { ttlSeconds, dependencyIds: [cacheKey] });
+  }
+}
+function replay(record, fingerprint) {
+  if (record.fingerprint !== fingerprint) {
+    return idempotencyError(422, "idempotency_conflict", "Idempotency-Key has already been used with a different request body");
+  }
+  if (record.inFlight) {
+    return idempotencyError(
+      409,
+      "idempotency_in_flight",
+      "A request with this Idempotency-Key is currently being processed",
+      { "retry-after": String(RETRY_AFTER_SECONDS) }
+    );
+  }
+  return new Response(record.body ?? null, {
+    status: record.status ?? 200,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "idempotent-replayed": "true"
+    }
+  });
+}
+function idempotencyError(status, code, message, headers = {}) {
+  return new Response(JSON.stringify({ type: "invalid_request", code, message }), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", ...headers }
+  });
+}
+async function getBodyFingerprint(request) {
+  const text = await request.clone().text();
+  try {
+    return hash(canonicalize(JSON.parse(text)));
+  } catch {
+    return hash(text);
+  }
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(Reflect.get(value, key))}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+export {
+  ACPIdempotency,
+  ACP_MIN_IDEMPOTENCY_TTL_SECONDS
+};

package/lib/acp-mcp.js

@@ -0,0 +1,206 @@
+import * as z from "zod";
+import {
+  ACPCancelCheckoutSessionRequestSchema,
+  ACPCompleteCheckoutSessionRequestSchema,
+  ACPCreateCheckoutSessionRequestSchema,
+  ACPUpdateCheckoutSessionRequestSchema
+} from "./acp-schemas.js";
+const MCP_PROTOCOL_VERSION = "2025-11-25";
+const JSON_RPC_INVALID_REQUEST = -32600;
+const JSON_RPC_METHOD_NOT_FOUND = -32601;
+const JSON_RPC_INVALID_PARAMS = -32602;
+const JSON_RPC_PARSE_ERROR = -32700;
+const JSON_RPC_ACP_ERROR = -32e3;
+const ACPMcpMetaSchema = z.looseObject({
+  api_version: z.string(),
+  idempotency_key: z.string().max(255).optional(),
+  request_id: z.string().optional(),
+  user_agent: z.string().optional(),
+  accept_language: z.string().optional(),
+  signature: z.string().optional(),
+  timestamp: z.string().optional()
+});
+const META_HEADERS = {
+  api_version: "api-version",
+  idempotency_key: "idempotency-key",
+  request_id: "request-id",
+  user_agent: "user-agent",
+  accept_language: "accept-language",
+  signature: "signature",
+  timestamp: "timestamp"
+};
+const ACP_MCP_TOOLS = [
+  {
+    name: "create_checkout_session",
+    description: "Create a checkout session from line items, currency and capabilities. Maps to POST /checkout_sessions.",
+    method: "POST",
+    path: () => "/checkout_sessions",
+    needsId: false,
+    payload: { schema: ACPCreateCheckoutSessionRequestSchema, required: true }
+  },
+  {
+    name: "get_checkout_session",
+    description: "Retrieve the current state of a checkout session. Maps to GET /checkout_sessions/{id}.",
+    method: "GET",
+    path: (id) => `/checkout_sessions/${encodeURIComponent(id)}`,
+    needsId: true
+  },
+  {
+    name: "update_checkout_session",
+    description: "Update items, fulfillment details or selected options. Maps to POST /checkout_sessions/{id}.",
+    method: "POST",
+    path: (id) => `/checkout_sessions/${encodeURIComponent(id)}`,
+    needsId: true,
+    payload: { schema: ACPUpdateCheckoutSessionRequestSchema, required: true }
+  },
+  {
+    name: "complete_checkout_session",
+    description: "Submit payment and finalize the order. Maps to POST /checkout_sessions/{id}/complete.",
+    method: "POST",
+    path: (id) => `/checkout_sessions/${encodeURIComponent(id)}/complete`,
+    needsId: true,
+    payload: { schema: ACPCompleteCheckoutSessionRequestSchema, required: true }
+  },
+  {
+    name: "cancel_checkout_session",
+    description: "Cancel a checkout session, optionally with an intent trace. Maps to POST /checkout_sessions/{id}/cancel.",
+    method: "POST",
+    path: (id) => `/checkout_sessions/${encodeURIComponent(id)}/cancel`,
+    needsId: true,
+    payload: { schema: ACPCancelCheckoutSessionRequestSchema, required: false }
+  }
+];
+const JsonRpcRequestSchema = z.looseObject({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number(), z.null()]).optional(),
+  method: z.string(),
+  params: z.unknown().optional()
+});
+const ToolCallParamsSchema = z.looseObject({
+  name: z.string(),
+  arguments: z.looseObject({}).optional()
+});
+class ACPMcpEndpoint {
+  constructor(serverInfo, rest) {
+    this.serverInfo = serverInfo;
+    this.rest = rest;
+  }
+  serverInfo;
+  rest;
+  async handle(request, restBaseUrl) {
+    if (request.method !== "POST") {
+      return new Response(null, { status: 405, headers: { allow: "POST" } });
+    }
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return jsonRpcResponse(null, { error: { code: JSON_RPC_PARSE_ERROR, message: "Parse error" } });
+    }
+    const message = JsonRpcRequestSchema.safeParse(body);
+    if (!message.success) {
+      return jsonRpcResponse(null, { error: { code: JSON_RPC_INVALID_REQUEST, message: "Invalid Request" } });
+    }
+    if (message.data.id === void 0) {
+      return new Response(null, { status: 202 });
+    }
+    const id = message.data.id;
+    switch (message.data.method) {
+      case "initialize":
+        return jsonRpcResponse(id, {
+          result: {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: this.serverInfo
+          }
+        });
+      case "ping":
+        return jsonRpcResponse(id, { result: {} });
+      case "tools/list":
+        return jsonRpcResponse(id, { result: { tools: ACP_MCP_TOOLS.map(toToolDefinition) } });
+      case "tools/call":
+        return jsonRpcResponse(id, await this.callTool(message.data.params, request, restBaseUrl));
+      default:
+        return jsonRpcResponse(id, { error: { code: JSON_RPC_METHOD_NOT_FOUND, message: `Method not found: ${message.data.method}` } });
+    }
+  }
+  async callTool(params, mcpRequest, restBaseUrl) {
+    const call = ToolCallParamsSchema.safeParse(params);
+    const tool = call.success ? ACP_MCP_TOOLS.find((candidate) => candidate.name === call.data.name) : void 0;
+    if (!call.success || !tool) {
+      return { error: { code: JSON_RPC_INVALID_PARAMS, message: `Unknown tool: ${call.success ? call.data.name : ""}` } };
+    }
+    const args = call.data.arguments ?? {};
+    const meta = ACPMcpMetaSchema.safeParse(args["meta"]);
+    const resourceId = args["id"];
+    const payload = args["payload"];
+    if (!meta.success) {
+      return { error: { code: JSON_RPC_INVALID_PARAMS, message: "meta.api_version is required" } };
+    }
+    if (tool.needsId && (typeof resourceId !== "string" || resourceId.length === 0)) {
+      return { error: { code: JSON_RPC_INVALID_PARAMS, message: "id is required" } };
+    }
+    if (tool.payload?.required && (typeof payload !== "object" || payload === null)) {
+      return { error: { code: JSON_RPC_INVALID_PARAMS, message: "payload is required" } };
+    }
+    const headers = new Headers({ accept: "application/json" });
+    const authorization = mcpRequest.headers.get("authorization");
+    if (authorization) {
+      headers.set("authorization", authorization);
+    }
+    for (const [field, header] of Object.entries(META_HEADERS)) {
+      const value = meta.data[field];
+      if (typeof value === "string") {
+        headers.set(header, value);
+      }
+    }
+    if (tool.method === "POST" && !headers.has("idempotency-key")) {
+      headers.set("idempotency-key", crypto.randomUUID());
+    }
+    const hasBody = tool.method === "POST" && payload !== void 0;
+    if (hasBody) {
+      headers.set("content-type", "application/json");
+    }
+    const response = await this.rest(new Request(`${restBaseUrl}${tool.path(typeof resourceId === "string" ? resourceId : "")}`, {
+      method: tool.method,
+      headers,
+      ...hasBody ? { body: JSON.stringify(payload) } : {}
+    }));
+    const text = await response.text();
+    const result = text ? JSON.parse(text) : {};
+    if (response.ok) {
+      return { result };
+    }
+    const message = typeof result === "object" && result !== null && typeof Reflect.get(result, "message") === "string" ? String(Reflect.get(result, "message")) : `HTTP ${response.status}`;
+    return { error: { code: JSON_RPC_ACP_ERROR, message, data: result } };
+  }
+}
+function toToolDefinition(tool) {
+  const properties = {
+    meta: z.toJSONSchema(ACPMcpMetaSchema, { io: "input", unrepresentable: "any" })
+  };
+  const required = ["meta"];
+  if (tool.needsId) {
+    properties["id"] = { type: "string", description: "Checkout session id" };
+    required.push("id");
+  }
+  if (tool.payload) {
+    properties["payload"] = z.toJSONSchema(tool.payload.schema, { io: "input", unrepresentable: "any" });
+    if (tool.payload.required) {
+      required.push("payload");
+    }
+  }
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: { type: "object", properties, required }
+  };
+}
+function jsonRpcResponse(id, outcome) {
+  return new Response(JSON.stringify({ jsonrpc: "2.0", id, ...outcome }), {
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+export {
+  ACPMcpEndpoint
+};

package/lib/acp-payment-handlers.js

@@ -0,0 +1,38 @@
+const TOKENIZED_CARD_VERSION = "2026-01-22";
+function createTokenizedCardHandler(options) {
+  return {
+    handler: {
+      id: options.id ?? "card_tokenized",
+      name: "dev.acp.tokenized.card",
+      ...options.displayName ? { display_name: options.displayName } : {},
+      version: TOKENIZED_CARD_VERSION,
+      spec: "https://acp.dev/handlers/tokenized.card",
+      requires_delegate_payment: true,
+      requires_pci_compliance: false,
+      psp: options.psp,
+      config_schema: "https://acp.dev/schemas/handlers/tokenized.card/config.json",
+      instrument_schemas: ["https://acp.dev/schemas/handlers/tokenized.card/instrument.json"],
+      config: {
+        ...options.config,
+        merchant_id: options.merchantId,
+        psp: options.psp,
+        ...options.acceptedBrands ? { accepted_brands: options.acceptedBrands } : {},
+        ...options.acceptedFundingTypes ? { accepted_funding_types: options.acceptedFundingTypes } : {},
+        ...options.supports3ds !== void 0 ? { supports_3ds: options.supports3ds } : {}
+      },
+      ...options.displayOrder !== void 0 ? { display_order: options.displayOrder } : {}
+    },
+    ...options.paymentMethod ? { paymentMethod: options.paymentMethod } : {}
+  };
+}
+function getHandlerPaymentMethod(option) {
+  return option.paymentMethod ?? {
+    method: "card",
+    name: option.handler.psp,
+    paymentProcessor: option.handler.psp
+  };
+}
+export {
+  createTokenizedCardHandler,
+  getHandlerPaymentMethod
+};