@reactionary/ucp 0.10.31 → 0.10.33

package/README.md

@@ -83,7 +83,9 @@ The official discovery profile is served from `/.well-known/ucp`. The profile ad
 - capabilities derived from the configured Reactionary client
 - configured merchant metadata
 - configured public keys
-- configured payment handlers, if supplied
+- configured payment handlers (`profile.paymentHandlers`), if supplied; the same handlers are echoed in checkout responses' `ucp.payment_handlers`
+
+Payment handlers are static configuration. The handler `id` is forwarded as `paymentMethod.paymentProcessor` when a payment instrument is selected, so it must match a payment provider id in the backend (for example Medusa's `pp_system_default`).
 
 Capability advertisement is intentionally derived from the instantiated client:
 

package/lib/reactionary-ucp-profile.js

@@ -1,4 +1,5 @@
 import { getCapability, hasCapability } from "./reactionary-ucp-capabilities.js";
+const UCP_DOCS_BASE_URL = "https://ucp.dev/2026-08-25";
 function getRequestRoute(request, profile) {
   const url = new URL(request.url);
   const endpointPath = profile ? new URL(profile.endpoint).pathname.replace(/\/$/, "") : "";
@@ -21,7 +22,9 @@ function createUCPProfile(client, profile) {
           {
             version: "2026-08-25",
             transport: "rest",
-            endpoint
+            endpoint,
+            spec: `${UCP_DOCS_BASE_URL}/specification/overview/`,
+            schema: `${UCP_DOCS_BASE_URL}/services/shopping/rest.openapi.json`
           }
         ]
       },
@@ -41,29 +44,31 @@ function createUCPProfile(client, profile) {
 function createUcpCapabilities(client) {
   const capabilities = {};
   if (hasCapability(client, "product-search")) {
-    capabilities["dev.ucp.shopping.catalog.search"] = [createUcpCapability()];
+    capabilities["dev.ucp.shopping.catalog.search"] = [createUcpCapability("catalog/search", "catalog_search")];
   }
   if (hasCapability(client, "product")) {
-    capabilities["dev.ucp.shopping.catalog.lookup"] = [createUcpCapability()];
+    capabilities["dev.ucp.shopping.catalog.lookup"] = [createUcpCapability("catalog/lookup", "catalog_lookup")];
   }
   if (hasCapability(client, "cart")) {
-    capabilities["dev.ucp.shopping.cart"] = [createUcpCapability()];
+    capabilities["dev.ucp.shopping.cart"] = [createUcpCapability("cart", "cart")];
     const cart = getCapability(client, "cart");
     if (cart && typeof Reflect.get(cart, "applyCouponCode") === "function") {
-      capabilities["dev.ucp.shopping.discount"] = [createUcpCapability()];
+      capabilities["dev.ucp.shopping.discount"] = [createUcpCapability("extensions/discount", "discount")];
     }
   }
   if (hasCapability(client, "checkout")) {
-    capabilities["dev.ucp.shopping.checkout"] = [createUcpCapability()];
+    capabilities["dev.ucp.shopping.checkout"] = [createUcpCapability("checkout", "checkout")];
   }
   if (hasCapability(client, "order")) {
-    capabilities["dev.ucp.shopping.order"] = [createUcpCapability()];
+    capabilities["dev.ucp.shopping.order"] = [createUcpCapability("order", "order")];
   }
   return capabilities;
 }
-function createUcpCapability() {
+function createUcpCapability(specPath, schemaName) {
   return {
-    version: "2026-08-25"
+    version: "2026-08-25",
+    spec: `${UCP_DOCS_BASE_URL}/specification/shopping/${specPath}/`,
+    schema: `${UCP_DOCS_BASE_URL}/schemas/shopping/${schemaName}.json`
   };
 }
 export {

package/lib/reactionary-ucp-rest.js

@@ -1,5 +1,5 @@
 import { jsonResponse } from "./reactionary-ucp-http.js";
-async function handleRestRequest(request, client, path, sessionId, sessionStore) {
+async function handleRestRequest(request, client, path, sessionId, sessionStore, paymentHandlers = {}) {
   if (request.method === "POST" && path === "/catalog/search") {
     return jsonResponse(await handleCatalogSearch(client, await parseJsonBody(request)));
   }
@@ -54,12 +54,12 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore)
       "REST POST /checkout-sessions",
       body,
       sessionStore,
-      async () => jsonResponse(await handleCreateCheckout(client, body), { status: 201 })
+      async () => jsonResponse(await handleCreateCheckout(client, body, paymentHandlers), { status: 201 })
     );
   }
   const checkoutMatch = /^\/checkout-sessions\/([^/]+)$/.exec(path);
   if (checkoutMatch && request.method === "GET") {
-    return jsonResponse(await handleGetCheckout(client, decodeURIComponent(checkoutMatch[1])));
+    return jsonResponse(await handleGetCheckout(client, decodeURIComponent(checkoutMatch[1]), paymentHandlers));
   }
   if (checkoutMatch && request.method === "PUT") {
     const body = await parseJsonBody(request);
@@ -69,7 +69,7 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore)
       `REST PUT /checkout-sessions/${decodeURIComponent(checkoutMatch[1])}`,
       body,
       sessionStore,
-      async () => jsonResponse(await handleUpdateCheckout(client, decodeURIComponent(checkoutMatch[1]), body))
+      async () => jsonResponse(await handleUpdateCheckout(client, decodeURIComponent(checkoutMatch[1]), body, paymentHandlers))
     );
   }
   const checkoutCompleteMatch = /^\/checkout-sessions\/([^/]+)\/complete$/.exec(path);
@@ -80,7 +80,7 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore)
       `REST POST /checkout-sessions/${decodeURIComponent(checkoutCompleteMatch[1])}/complete`,
       {},
       sessionStore,
-      async () => jsonResponse(await handleCompleteCheckout(client, decodeURIComponent(checkoutCompleteMatch[1])))
+      async () => jsonResponse(await handleCompleteCheckout(client, decodeURIComponent(checkoutCompleteMatch[1]), paymentHandlers))
     );
   }
   const checkoutCancelMatch = /^\/checkout-sessions\/([^/]+)\/cancel$/.exec(path);
@@ -297,7 +297,7 @@ async function handleCancelCart(client, cartId) {
   }
   return current.success ? toUcpCart(current.value) : createEmptyUcpCart(cartId);
 }
-async function handleCreateCheckout(client, body) {
+async function handleCreateCheckout(client, body, paymentHandlers) {
   if (!client.checkout) {
     return createUCPError("not_available", "Checkout capability is not available.");
   }
@@ -309,9 +309,9 @@ async function handleCreateCheckout(client, body) {
   if (!result.success) {
     return createUCPError("checkout_create_failed", "Checkout session creation failed.");
   }
-  return toUcpCheckout(result.value);
+  return toUcpCheckout(result.value, paymentHandlers);
 }
-async function handleGetCheckout(client, checkoutId) {
+async function handleGetCheckout(client, checkoutId, paymentHandlers) {
   if (!client.checkout) {
     return createUCPError("not_available", "Checkout capability is not available.");
   }
@@ -319,9 +319,9 @@ async function handleGetCheckout(client, checkoutId) {
   if (!result.success) {
     return createUCPError("not_found", `Checkout was not found: ${checkoutId}`);
   }
-  return toUcpCheckout(result.value);
+  return toUcpCheckout(result.value, paymentHandlers);
 }
-async function handleUpdateCheckout(client, checkoutId, body) {
+async function handleUpdateCheckout(client, checkoutId, body, paymentHandlers) {
   if (!client.checkout) {
     return createUCPError("not_available", "Checkout capability is not available.");
   }
@@ -353,9 +353,9 @@ async function handleUpdateCheckout(client, checkoutId, body) {
     }
     checkout = paymentResult.value;
   }
-  return toUcpCheckout(checkout);
+  return toUcpCheckout(checkout, paymentHandlers);
 }
-async function handleCompleteCheckout(client, checkoutId) {
+async function handleCompleteCheckout(client, checkoutId, paymentHandlers) {
   if (!client.checkout) {
     return createUCPError("not_available", "Checkout capability is not available.");
   }
@@ -363,7 +363,7 @@ async function handleCompleteCheckout(client, checkoutId) {
   if (!result.success) {
     return createUCPError("checkout_complete_failed", "Checkout completion failed.");
   }
-  return toUcpCheckout(result.value, "completed");
+  return toUcpCheckout(result.value, paymentHandlers, "completed");
 }
 async function handleGetOrder(client, orderId) {
   if (!client.order) {
@@ -380,7 +380,7 @@ async function handleGetOrder(client, orderId) {
     permalink_url: "",
     line_items: [],
     currency: getMoneyCurrency(result.value.price?.grandTotal),
-    totals: toUcpTotals(result.value.price?.grandTotal),
+    totals: toUcpCostTotals(result.value.price),
     fulfillment: {
       expectations: [],
       events: []
@@ -487,7 +487,7 @@ function toUcpCart(cart) {
     id: cart.identifier.key,
     line_items: cart.items.map(toUcpCartLineItem),
     currency: getMoneyCurrency(cart.price?.grandTotal),
-    totals: toUcpTotals(cart.price?.grandTotal),
+    totals: toUcpCostTotals(cart.price),
     ucp: createUcpSuccessMetadata()
   };
 }
@@ -516,20 +516,38 @@ function toUcpCartLineItem(lineItem) {
     totals: toUcpTotals(lineItem.price.totalPrice)
   };
 }
-function toUcpCheckout(checkout, status) {
+function toUcpCheckout(checkout, paymentHandlers, status) {
   return {
     id: checkout.identifier.key,
     status: status ?? (checkout.readyForFinalization ? "ready_for_complete" : "incomplete"),
     line_items: checkout.items.map(toUcpCartLineItem),
     currency: getMoneyCurrency(checkout.price?.grandTotal),
-    totals: toUcpTotals(checkout.price?.grandTotal),
+    totals: toUcpCostTotals(checkout.price),
     links: [],
-    ucp: createUcpCheckoutSuccessMetadata()
+    ucp: createUcpCheckoutSuccessMetadata(paymentHandlers)
   };
 }
 function toUcpDescription(text) {
   return text ? { plain: text } : { plain: "" };
 }
+function toUcpCostTotals(price) {
+  const totals = [
+    { type: "subtotal", amount: getMoneyValue(price.totalProductPrice) }
+  ];
+  const optionalTotals = [
+    ["discount", -Math.abs(getMoneyValue(price.totalDiscount))],
+    ["fulfillment", getMoneyValue(price.totalShipping)],
+    ["tax", getMoneyValue(price.totalTax)],
+    ["fee", getMoneyValue(price.totalSurcharge)]
+  ];
+  for (const [type, amount] of optionalTotals) {
+    if (amount !== 0) {
+      totals.push({ type, amount });
+    }
+  }
+  totals.push({ type: "total", amount: getMoneyValue(price.grandTotal) });
+  return totals;
+}
 function toUcpTotals(amount) {
   return [
     {
@@ -556,13 +574,21 @@ function createUcpSuccessMetadata() {
     status: "success"
   };
 }
-function createUcpCheckoutSuccessMetadata() {
+function createUcpCheckoutSuccessMetadata(paymentHandlers) {
+  const candidate = paymentHandlers;
   return {
     version: "2026-08-25",
     status: "success",
-    payment_handlers: {}
+    payment_handlers: isUcpCheckoutPaymentHandlers(candidate) ? candidate : {}
   };
 }
+function isUcpCheckoutPaymentHandlers(value) {
+  return typeof value === "object" && value !== null && Object.values(value).every(
+    (handlers) => Array.isArray(handlers) && handlers.every(
+      (handler) => typeof handler === "object" && handler !== null && typeof Reflect.get(handler, "version") === "string"
+    )
+  );
+}
 function createUCPError(code, message) {
   return {
     ucp: {

package/lib/reactionary-ucp-server.js

@@ -75,7 +75,8 @@ class ReactionaryUCPServer {
         client,
         route.path,
         sessionId,
-        this.sessionStore
+        this.sessionStore,
+        this.options.profile?.paymentHandlers
       );
       if (restResponse) {
         return restResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/ucp",
-  "version": "0.10.31",
+  "version": "0.10.33",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/Solteq/reactionary.git"
   },
   "dependencies": {
-    "@reactionary/core": "0.10.31",
+    "@reactionary/core": "0.10.33",
     "zod": "4.1.9"
   },
   "devDependencies": {

package/src/lib/reactionary-ucp-common.d.ts

@@ -3,13 +3,16 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { components } from './ucp-shopping.openapi.js';
 type UCPService = components['schemas']['base'];
 type UCPCapability = components['schemas']['$defs-base'];
-type UCPPaymentHandler = components['schemas']['payment_handler_$defs-base'];
+export type UCPPaymentHandler = components['schemas']['entity'] & {
+    available_instruments?: components['schemas']['available_payment_instrument'][];
+};
+export type UCPPaymentHandlers = Record<string, UCPPaymentHandler[]>;
 export interface ReactionaryUCPProfile {
     ucp: {
         version: string;
         services: Record<string, UCPService[]>;
         capabilities: Record<string, UCPCapability[]>;
-        payment_handlers?: Record<string, UCPPaymentHandler[]>;
+        payment_handlers?: UCPPaymentHandlers;
     };
     keys: Array<Record<string, unknown>>;
     merchant: {

package/src/lib/reactionary-ucp-rest.d.ts

@@ -1,6 +1,6 @@
-import type { ReactionaryUCPClient } from './reactionary-ucp-common.js';
+import type { ReactionaryUCPClient, UCPPaymentHandlers } from './reactionary-ucp-common.js';
 import type { ReactionaryUCPSessionStore } from './reactionary-ucp-session-store.js';
-export declare function handleRestRequest(request: Request, client: ReactionaryUCPClient, path: string, sessionId: string, sessionStore: ReactionaryUCPSessionStore): Promise<Response | undefined>;
+export declare function handleRestRequest(request: Request, client: ReactionaryUCPClient, path: string, sessionId: string, sessionStore: ReactionaryUCPSessionStore, paymentHandlers?: UCPPaymentHandlers): Promise<Response | undefined>;
 export declare class UCPHttpError extends Error {
     readonly status: number;
     readonly body: unknown;