@reactionary/ucp 0.10.35 → 0.10.37

package/lib/reactionary-ucp-rest.js

@@ -1,5 +1,28 @@
-import { jsonResponse } from "./reactionary-ucp-http.js";
-async function handleRestRequest(request, client, path, sessionId, sessionStore, paymentHandlers = {}) {
+import * as z from "zod";
+import { jsonResponse, secureEquals } from "./reactionary-ucp-http.js";
+import { getOrder, notifyOrderPlaced, simulateShipping, UCPOrderUpdateSchema, updateOrder } from "./reactionary-ucp-order.js";
+import {
+  cancelCheckoutSession,
+  completeCheckoutSession,
+  createCheckoutSession,
+  getCheckoutSession,
+  updateCheckoutSession
+} from "./reactionary-ucp-checkout-session.js";
+import {
+  createUCPError,
+  createUcpSuccessMetadata,
+  createUcpWarning,
+  getMoneyCurrency,
+  toUcpCartLineItem,
+  toUcpCostTotals
+} from "./reactionary-ucp-mapping.js";
+async function handleRestRequest(request, client, path, sessionId, sessionStore, options) {
+  const orderContext = { client, store: sessionStore, merchantUrl: options.merchantUrl, webhooks: options.webhooks };
+  const checkoutContext = createCheckoutSessionContext(client, sessionId, sessionStore, options, (orderId) => {
+    notifyOrderPlaced(orderContext, orderId).catch((error) => {
+      console.error(`UCP: failed to send the order created webhook for ${orderId}`, error);
+    });
+  });
   if (request.method === "POST" && path === "/catalog/search") {
     return jsonResponse(await handleCatalogSearch(client, await parseJsonBody(request)));
   }
@@ -17,7 +40,13 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore,
       "REST POST /carts",
       body,
       sessionStore,
-      async () => jsonResponse(await handleCreateCart(client, body), { status: 201 })
+      async () => {
+        const cart = await handleCreateCart(client, body);
+        if (isUcpCart(cart)) {
+          await sessionStore.bindResource(cart.id, sessionId);
+        }
+        return createdResponse(cart);
+      }
     );
   }
   const cartMatch = /^\/carts\/([^/]+)$/.exec(path);
@@ -54,12 +83,12 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore,
       "REST POST /checkout-sessions",
       body,
       sessionStore,
-      async () => jsonResponse(await handleCreateCheckout(client, body, paymentHandlers), { status: 201 })
+      async () => createdResponse(await createCheckoutSession(checkoutContext, body))
     );
   }
   const checkoutMatch = /^\/checkout-sessions\/([^/]+)$/.exec(path);
   if (checkoutMatch && request.method === "GET") {
-    return jsonResponse(await handleGetCheckout(client, decodeURIComponent(checkoutMatch[1]), paymentHandlers));
+    return checkoutResponse(await getCheckoutSession(checkoutContext, decodeURIComponent(checkoutMatch[1])));
   }
   if (checkoutMatch && request.method === "PUT") {
     const body = await parseJsonBody(request);
@@ -69,18 +98,19 @@ 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, paymentHandlers))
+      async () => checkoutResponse(await updateCheckoutSession(checkoutContext, decodeURIComponent(checkoutMatch[1]), body))
     );
   }
   const checkoutCompleteMatch = /^\/checkout-sessions\/([^/]+)\/complete$/.exec(path);
   if (checkoutCompleteMatch && request.method === "POST") {
+    const body = await parseJsonBody(request);
     return withRestIdempotency(
       request,
       sessionId,
       `REST POST /checkout-sessions/${decodeURIComponent(checkoutCompleteMatch[1])}/complete`,
-      {},
+      body,
       sessionStore,
-      async () => jsonResponse(await handleCompleteCheckout(client, decodeURIComponent(checkoutCompleteMatch[1]), paymentHandlers))
+      async () => checkoutResponse(await completeCheckoutSession(checkoutContext, decodeURIComponent(checkoutCompleteMatch[1]), body))
     );
   }
   const checkoutCancelMatch = /^\/checkout-sessions\/([^/]+)\/cancel$/.exec(path);
@@ -91,31 +121,114 @@ async function handleRestRequest(request, client, path, sessionId, sessionStore,
       `REST POST /checkout-sessions/${decodeURIComponent(checkoutCancelMatch[1])}/cancel`,
       {},
       sessionStore,
-      async () => jsonResponse(createUCPError("not_implemented", "Checkout cancellation is not represented by Reactionary checkout capabilities yet."), { status: 501 })
+      async () => checkoutResponse(await cancelCheckoutSession(checkoutContext, decodeURIComponent(checkoutCancelMatch[1])))
     );
   }
   const orderMatch = /^\/orders\/([^/]+)$/.exec(path);
   if (orderMatch && request.method === "GET") {
-    return jsonResponse(await handleGetOrder(client, decodeURIComponent(orderMatch[1])));
+    return jsonResponse(await getOrder(orderContext, decodeURIComponent(orderMatch[1])));
+  }
+  if (orderMatch && request.method === "PUT" && options.testOrderUpdates) {
+    const update = UCPOrderUpdateSchema.safeParse(await parseJsonBody(request));
+    if (!update.success) {
+      throw new UCPHttpError(422, createUCPError("invalid_request", `Invalid order update: ${z.prettifyError(update.error)}`));
+    }
+    return jsonResponse(await updateOrder(orderContext, decodeURIComponent(orderMatch[1]), update.data));
+  }
+  const simulateShippingMatch = /^\/testing\/simulate-shipping\/([^/]+)$/.exec(path);
+  if (simulateShippingMatch && request.method === "POST" && options.testSimulationSecret) {
+    if (!secureEquals(request.headers.get("Simulation-Secret") ?? "", options.testSimulationSecret)) {
+      throw new UCPHttpError(403, createUCPError("forbidden", "A valid Simulation-Secret header is required."));
+    }
+    return jsonResponse(await simulateShipping(orderContext, decodeURIComponent(simulateShippingMatch[1])));
   }
   return void 0;
 }
+function createCheckoutSessionContext(client, sessionId, sessionStore, options, onOrderPlaced) {
+  let identityEmail;
+  return {
+    client,
+    store: sessionStore,
+    sessionId,
+    paymentHandlers: options.paymentHandlers,
+    placeholderEmail: options.placeholderEmail,
+    paymentAuthorizationWait: options.paymentAuthorizationWait,
+    merchantUrl: options.merchantUrl,
+    anonymousOrderEmail: options.anonymousOrderEmail,
+    testPaymentHandlers: options.testPaymentHandlers,
+    acceptRawCardCredentials: options.acceptRawCardCredentials,
+    inventory: options.inventory,
+    agentProfile: options.agentProfile,
+    onOrderPlaced,
+    getIdentityEmail() {
+      identityEmail ??= getRegisteredIdentityEmail(client, options.identity);
+      return identityEmail;
+    },
+    async createCart(lineItems) {
+      const created = await handleCreateCart(client, {
+        id: "",
+        line_items: lineItems,
+        currency: "",
+        totals: [],
+        ucp: createUcpSuccessMetadata()
+      });
+      if (!isUcpCart(created)) {
+        return created;
+      }
+      return await getReactionaryCart(client, created.id) ?? createUCPError("not_found", `Cart was not found: ${created.id}`);
+    },
+    async reconcileCart(cartId, lineItems) {
+      const updated = await handleUpdateCart(client, cartId, {
+        id: cartId,
+        line_items: lineItems,
+        currency: "",
+        totals: [],
+        ucp: createUcpSuccessMetadata()
+      });
+      return isUcpCart(updated) ? void 0 : updated;
+    }
+  };
+}
+async function getRegisteredIdentityEmail(client, identity) {
+  if (identity.type !== "Registered" || !client.profile) {
+    return void 0;
+  }
+  const profile = await client.profile.getById({ identifier: identity.id });
+  return profile.success && profile.value.email ? profile.value.email : void 0;
+}
+function getAgentProfile(request) {
+  const agent = request.headers.get("UCP-Agent");
+  const profile = agent ? /profile="([^"]*)"/.exec(agent)?.[1] : void 0;
+  return profile ? `agent:${profile}` : void 0;
+}
+const CHECKOUT_ERROR_STATUSES = {
+  not_found: 404,
+  checkout_not_modifiable: 409
+};
+function checkoutResponse(body) {
+  const code = body.ucp.status === "error" ? body.messages?.[0]?.code : void 0;
+  return jsonResponse(body, { status: code && CHECKOUT_ERROR_STATUSES[code] || 200 });
+}
+function createdResponse(body) {
+  return jsonResponse(body, { status: body.ucp.status === "error" ? 200 : 201 });
+}
 async function withRestIdempotency(request, sessionId, action, payload, sessionStore, createResponse) {
   const idempotencyKey = request.headers.get("Idempotency-Key");
   if (!idempotencyKey) {
     return createResponse();
   }
+  const scope = getAgentProfile(request) ?? sessionId;
   const fingerprint = JSON.stringify(payload);
-  const cached = await sessionStore.getIdempotencyRecord(sessionId, idempotencyKey);
+  const cached = await sessionStore.getIdempotencyRecord(scope, idempotencyKey);
   if (cached) {
     if (cached.action !== action || cached.fingerprint !== fingerprint) {
-      return jsonResponse(createUCPError("idempotency_key_conflict", "The supplied Idempotency-Key was already used for a different UCP REST mutation in this session."), { status: 409 });
+      return jsonResponse(createUCPError("idempotency_key_conflict", "The supplied Idempotency-Key was already used for a different UCP REST mutation."), { status: 409 });
     }
     return jsonResponse(cached.response, { status: cached.status ?? 200 });
   }
   const response = await createResponse();
   const responseBody = await response.clone().json();
-  await sessionStore.putIdempotencyRecord(sessionId, idempotencyKey, {
+  await sessionStore.putIdempotencyRecord(scope, idempotencyKey, {
     action,
     fingerprint,
     status: response.status,
@@ -212,7 +325,11 @@ async function handleCreateCart(client, body) {
       quantity: lineItem.quantity
     });
     if (!addResult.success) {
-      return createUCPError("cart_add_failed", `Unable to add item to cart: ${lineItem.item.id}`);
+      return createUCPError(
+        "item_unavailable",
+        `Item is not available for purchase: ${lineItem.item.id}`,
+        `$.line_items[${body["line_items"].indexOf(lineItem)}]`
+      );
     }
     cart = addResult.value;
   }
@@ -291,103 +408,14 @@ async function handleCancelCart(client, cartId) {
     return createUCPError("not_available", "Cart capability is not available.");
   }
   const current = await client.cart.getById({ cart: { key: cartId } });
-  const deleted = await client.cart.deleteCart({ cart: { key: cartId } });
+  const deleted = await client.cart.deleteCart({
+    cart: current.success ? current.value.identifier : { key: cartId }
+  });
   if (!deleted.success) {
     return createUCPError("cart_cancel_failed", `Unable to cancel cart: ${cartId}`);
   }
   return current.success ? toUcpCart(current.value) : createEmptyUcpCart(cartId);
 }
-async function handleCreateCheckout(client, body, paymentHandlers) {
-  if (!client.checkout) {
-    return createUCPError("not_available", "Checkout capability is not available.");
-  }
-  const cart = body.cart_id ? await getReactionaryCart(client, body.cart_id) : await createCartForCheckout(client, body);
-  if (!cart) {
-    return createUCPError("invalid_request", "A checkout session requires cart_id or line_items.");
-  }
-  const result = await client.checkout.initiateCheckoutForCart({ cart });
-  if (!result.success) {
-    return createUCPError("checkout_create_failed", "Checkout session creation failed.");
-  }
-  return toUcpCheckout(result.value, paymentHandlers);
-}
-async function handleGetCheckout(client, checkoutId, paymentHandlers) {
-  if (!client.checkout) {
-    return createUCPError("not_available", "Checkout capability is not available.");
-  }
-  const result = await client.checkout.getById({ identifier: { key: checkoutId } });
-  if (!result.success) {
-    return createUCPError("not_found", `Checkout was not found: ${checkoutId}`);
-  }
-  return toUcpCheckout(result.value, paymentHandlers);
-}
-async function handleUpdateCheckout(client, checkoutId, body, paymentHandlers) {
-  if (!client.checkout) {
-    return createUCPError("not_available", "Checkout capability is not available.");
-  }
-  const current = await client.checkout.getById({ identifier: { key: checkoutId } });
-  if (!current.success) {
-    return createUCPError("not_found", `Checkout was not found: ${checkoutId}`);
-  }
-  let checkout = current.value;
-  const selectedInstrument = body.payment?.instruments?.find((instrument) => instrument.selected);
-  if (selectedInstrument) {
-    const paymentResult = await client.checkout.addPaymentInstruction({
-      checkout: checkout.identifier,
-      paymentInstruction: {
-        amount: checkout.price.grandTotal,
-        paymentMethod: {
-          method: selectedInstrument.type,
-          name: selectedInstrument.id,
-          paymentProcessor: selectedInstrument.handler_id
-        },
-        protocolData: [
-          { key: "ucp_payment_instrument_id", value: selectedInstrument.id },
-          { key: "ucp_payment_handler_id", value: selectedInstrument.handler_id },
-          { key: "ucp_payment_instrument_type", value: selectedInstrument.type }
-        ]
-      }
-    });
-    if (!paymentResult.success) {
-      return createUCPError("checkout_update_failed", "Unable to add selected payment instruction.");
-    }
-    checkout = paymentResult.value;
-  }
-  return toUcpCheckout(checkout, paymentHandlers);
-}
-async function handleCompleteCheckout(client, checkoutId, paymentHandlers) {
-  if (!client.checkout) {
-    return createUCPError("not_available", "Checkout capability is not available.");
-  }
-  const result = await client.checkout.finalizeCheckout({ checkout: { key: checkoutId } });
-  if (!result.success) {
-    return createUCPError("checkout_complete_failed", "Checkout completion failed.");
-  }
-  return toUcpCheckout(result.value, paymentHandlers, "completed");
-}
-async function handleGetOrder(client, orderId) {
-  if (!client.order) {
-    return createUCPError("not_available", "Order capability is not available.");
-  }
-  const result = await client.order.getById({ order: { key: orderId } });
-  if (!result.success) {
-    return createUCPError("not_found", `Order was not found: ${orderId}`);
-  }
-  return {
-    ucp: createUcpSuccessMetadata(),
-    id: result.value.identifier.key,
-    checkout_id: "",
-    permalink_url: "",
-    line_items: [],
-    currency: getMoneyCurrency(result.value.price?.grandTotal),
-    totals: toUcpCostTotals(result.value.price),
-    fulfillment: {
-      expectations: [],
-      events: []
-    },
-    messages: []
-  };
-}
 async function getReactionaryCart(client, cartId) {
   if (!client.cart) {
     return void 0;
@@ -395,19 +423,6 @@ async function getReactionaryCart(client, cartId) {
   const result = await client.cart.getById({ cart: { key: cartId } });
   return result.success ? result.value : void 0;
 }
-async function createCartForCheckout(client, checkout) {
-  if (!checkout.line_items?.length) {
-    return void 0;
-  }
-  const cartResponse = await handleCreateCart(client, {
-    id: "",
-    line_items: checkout.line_items,
-    currency: checkout.currency,
-    totals: checkout.totals,
-    ucp: createUcpSuccessMetadata()
-  });
-  return isUcpCart(cartResponse) ? getReactionaryCart(client, cartResponse.id) : void 0;
-}
 async function getReactionaryProduct(client, id) {
   if (!client.product) {
     return void 0;
@@ -487,7 +502,7 @@ function toUcpCart(cart) {
     id: cart.identifier.key,
     line_items: cart.items.map(toUcpCartLineItem),
     currency: getMoneyCurrency(cart.price?.grandTotal),
-    totals: toUcpCostTotals(cart.price),
+    totals: toUcpCostTotals(cart.price, cart.items),
     ucp: createUcpSuccessMetadata()
   };
 }
@@ -503,120 +518,15 @@ function createEmptyUcpCart(cartId) {
 function isUcpCart(response) {
   return "id" in response && "line_items" in response && "currency" in response;
 }
-function toUcpCartLineItem(lineItem) {
-  const sku = lineItem.variant.sku || lineItem.identifier.key;
-  return {
-    id: lineItem.identifier.key,
-    item: {
-      id: sku,
-      title: sku,
-      price: getMoneyValue(lineItem.price.unitPrice)
-    },
-    quantity: lineItem.quantity,
-    totals: toUcpTotals(lineItem.price.totalPrice)
-  };
-}
-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: toUcpCostTotals(checkout.price),
-    links: [],
-    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 [
-    {
-      type: "total",
-      amount: getMoneyValue(amount)
-    }
-  ];
-}
-function getMoneyValue(amount) {
-  return amount.value;
-}
-function getMoneyCurrency(amount) {
-  return amount.currency;
-}
 function createUcpPrice(amount = 0, currency = "EUR") {
   return {
     amount,
     currency
   };
 }
-function createUcpSuccessMetadata() {
-  return {
-    version: "2026-08-25",
-    status: "success"
-  };
-}
-function createUcpCheckoutSuccessMetadata(paymentHandlers) {
-  const candidate = paymentHandlers;
-  return {
-    version: "2026-08-25",
-    status: "success",
-    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: {
-      version: "2026-08-25",
-      status: "error"
-    },
-    messages: [
-      {
-        message: {
-          type: "error",
-          content_type: "plain",
-          content: message,
-          code
-        }
-      }
-    ]
-  };
-}
-function createUcpWarning(code, content, path) {
-  return {
-    type: "warning",
-    code,
-    path,
-    content,
-    content_type: "plain",
-    presentation: "notice"
-  };
-}
 function getLimit(body) {
   return body.pagination?.limit ?? 10;
 }

package/lib/reactionary-ucp-server.js

@@ -8,9 +8,16 @@ import {
 } from "./reactionary-ucp-common.js";
 import { getOrCreateSessionId, jsonResponse, sendWebResponse, toWebRequest, UCP_SESSION_ID_HEADER } from "./reactionary-ucp-http.js";
 import { ReactionaryUCPIdentity } from "./reactionary-ucp-identity.js";
+import { resolveLanguageContext } from "./reactionary-ucp-localization.js";
+import {
+  DEFAULT_UCP_PAYMENT_AUTHORIZATION_WAIT,
+  DEFAULT_UCP_PLACEHOLDER_EMAIL
+} from "./reactionary-ucp-checkout-session.js";
+import { createUCPError, UCP_VERSION } from "./reactionary-ucp-mapping.js";
 import { createUCPProfile, getRequestRoute } from "./reactionary-ucp-profile.js";
 import { handleRestRequest, UCPHttpError } from "./reactionary-ucp-rest.js";
 import { ReactionaryUCPSessionStore } from "./reactionary-ucp-session-store.js";
+import { ReactionaryUCPWebhooks } from "./reactionary-ucp-webhooks.js";
 class ReactionaryUCPServer {
   constructor(clientFactory, options = {}) {
     this.clientFactory = clientFactory;
@@ -23,10 +30,50 @@ class ReactionaryUCPServer {
     if (this.options.identity) {
       this.identity = new ReactionaryUCPIdentity(this.options.identity, cache);
     }
+    if (this.options.anonymousOrderEmail) {
+      console.warn(
+        "\n############################################################################\n# UCP: anonymousOrderEmail is set. Checkouts WITHOUT a buyer email will    #\n# place REAL orders under this address. The buyer cannot be sent a        #\n# receipt, which may make such purchases illegal in some jurisdictions.   #\n# Use for conformance/test environments only.                             #\n############################################################################"
+      );
+    }
+    if (this.options.testPaymentHandlers?.length) {
+      assertTestPaymentHandlerDelegates(this.options.testPaymentHandlers, this.options.profile?.paymentHandlers ?? {});
+      console.warn(
+        `
+############################################################################
+# UCP: testPaymentHandlers is set. Checkouts paying with a test handler   #
+# are charged through its REAL delegate handler with substitute           #
+# credentials. Use for conformance/test environments only.                #
+############################################################################
+Test payment handlers: ${this.options.testPaymentHandlers.map((handler) => `${handler.id} -> ${handler.delegateHandlerId}`).join(", ")}`
+      );
+    }
+    if (this.options.webhooks) {
+      const signingKey = this.options.webhooks.signingKey;
+      if (signingKey && !this.options.profile?.keys.some((key) => key["kid"] === signingKey.kid)) {
+        throw new Error(
+          `UCP webhook signing key '${signingKey.kid}' is not published in profile.keys; add toPublicSigningJwk(signingKey).`
+        );
+      }
+      this.webhooks = new ReactionaryUCPWebhooks(
+        this.options.webhooks,
+        new URL("/.well-known/ucp", this.options.profile?.endpoint ?? "http://localhost/ucp").toString()
+      );
+    }
+    if (this.options.testSimulationSecret) {
+      console.warn(
+        "\n############################################################################\n# UCP: testSimulationSecret is set. POST /testing/simulate-shipping/{id}  #\n# marks orders as shipped for anyone holding the secret. Not part of the  #\n# UCP specification. Use for conformance/test environments only.          #\n############################################################################"
+      );
+    }
+    if (this.options.testOrderUpdates) {
+      console.warn(
+        "\n############################################################################\n# UCP: testOrderUpdates is set. Agents can PUT fulfillment events and     #\n# adjustments (e.g. refunds) onto the orders they placed. Not part of the #\n# UCP specification. Use for conformance/test environments only.          #\n############################################################################"
+      );
+    }
   }
   clientFactory;
   options;
   sessionStore;
+  webhooks;
   identity;
   async fetch(request) {
     const route = getRequestRoute(request, this.options.profile);
@@ -41,14 +88,22 @@ class ReactionaryUCPServer {
     );
   }
   async handleFetch(request) {
-    const sessionId = getOrCreateSessionId(request);
     const bearerResolution = await this.identity?.resolveBearer(request);
     if (bearerResolution instanceof Response) {
       return bearerResolution;
     }
+    const sessionId = bearerResolution ? getOrCreateSessionId(request) : await this.resolveSessionId(request);
     const requestContext = await this.createRequestContext(sessionId, bearerResolution);
+    const negotiatedLanguageContext = await resolveLanguageContext(
+      request,
+      requestContext.session,
+      this.options.localization
+    );
+    if (negotiatedLanguageContext) {
+      requestContext.languageContext = negotiatedLanguageContext;
+    }
     const client = this.clientFactory(requestContext);
-    const response = await this.handleRequest(request, client, sessionId, bearerResolution);
+    const response = await this.handleRequest(request, client, requestContext, sessionId, bearerResolution);
     if (bearerResolution) {
       await this.identity?.persistBearerSession(bearerResolution, requestContext.session);
     } else {
@@ -76,6 +131,28 @@ class ReactionaryUCPServer {
   close() {
     return Promise.resolve();
   }
+  /**
+   * Requests addressing a cart or checkout session resume the session that
+   * created it: agents rarely echo the UCP session header, but backends scope
+   * carts to that session's (anonymous) identity.
+   */
+  async resolveSessionId(request) {
+    const route = getRequestRoute(request, this.options.profile);
+    const resourceId = /^\/(?:carts|checkout-sessions)\/([^/]+)/.exec(route.path)?.[1];
+    const orderId = /^\/(?:orders|testing\/simulate-shipping)\/([^/]+)/.exec(route.path)?.[1];
+    const boundSessionId = resourceId ? await this.sessionStore.getResourceSession(decodeURIComponent(resourceId)) : orderId ? await this.resolveOrderSessionId(request, decodeURIComponent(orderId)) : void 0;
+    return boundSessionId ?? getOrCreateSessionId(request);
+  }
+  /**
+   * Orders resume the session that placed them only for the platform that
+   * completed the checkout (order capability: the business verifies the
+   * requesting platform created the checkout). Any other request runs in its
+   * own session, where the backend does not find the order.
+   */
+  async resolveOrderSessionId(request, orderId) {
+    const order = await this.sessionStore.getOrder(orderId);
+    return order?.agentProfile && order.agentProfile === getAgentProfile(request) ? order.sessionId : void 0;
+  }
   async createRequestContext(sessionId, bearerResolution) {
     const requestContext = createInitialRequestContext();
     if (bearerResolution) {
@@ -88,7 +165,7 @@ class ReactionaryUCPServer {
     }
     return requestContext;
   }
-  async handleRequest(request, client, sessionId, bearerResolution) {
+  async handleRequest(request, client, requestContext, sessionId, bearerResolution) {
     const route = getRequestRoute(request, this.options.profile);
     if (request.method === "OPTIONS") {
       return new Response(null, {
@@ -111,6 +188,13 @@ class ReactionaryUCPServer {
         return accessResponse;
       }
     }
+    const agentVersion = getAgentVersion(request);
+    if (agentVersion && agentVersion > UCP_VERSION) {
+      return jsonResponse(
+        createUCPError("version_unsupported", `UCP version ${agentVersion} is not supported; this business supports ${UCP_VERSION}.`),
+        { status: 422 }
+      );
+    }
     try {
       const restResponse = await handleRestRequest(
         request,
@@ -118,7 +202,24 @@ class ReactionaryUCPServer {
         route.path,
         sessionId,
         this.sessionStore,
-        this.options.profile?.paymentHandlers
+        {
+          paymentHandlers: this.options.profile?.paymentHandlers ?? {},
+          placeholderEmail: this.options.placeholderEmail ?? DEFAULT_UCP_PLACEHOLDER_EMAIL,
+          paymentAuthorizationWait: {
+            ...DEFAULT_UCP_PAYMENT_AUTHORIZATION_WAIT,
+            ...this.options.paymentAuthorizationWait
+          },
+          identity: requestContext.session.identityContext.identity,
+          merchantUrl: this.options.profile?.merchant?.url,
+          anonymousOrderEmail: this.options.anonymousOrderEmail,
+          testPaymentHandlers: this.options.testPaymentHandlers,
+          acceptRawCardCredentials: this.options.acceptRawCardCredentials,
+          inventory: this.options.inventory,
+          testOrderUpdates: this.options.testOrderUpdates,
+          testSimulationSecret: this.options.testSimulationSecret,
+          webhooks: this.webhooks,
+          agentProfile: getAgentProfile(request)
+        }
       );
       if (restResponse) {
         return restResponse;
@@ -140,6 +241,24 @@ class ReactionaryUCPServer {
     });
   }
 }
+function assertTestPaymentHandlerDelegates(testHandlers, paymentHandlers) {
+  const advertised = new Set(Object.values(paymentHandlers).flat().map((handler) => handler.id));
+  for (const handler of testHandlers) {
+    if (!advertised.has(handler.delegateHandlerId)) {
+      throw new Error(
+        `UCP test payment handler '${handler.id}' delegates to '${handler.delegateHandlerId}', which is not an advertised payment handler.`
+      );
+    }
+  }
+}
+function getAgentProfile(request) {
+  const agent = request.headers.get("UCP-Agent");
+  return agent ? /profile="([^"]*)"/.exec(agent)?.[1] : void 0;
+}
+function getAgentVersion(request) {
+  const agent = request.headers.get("UCP-Agent");
+  return agent ? /version="([^"]*)"/.exec(agent)?.[1] : void 0;
+}
 function getUcpOperationPath(path) {
   return path.replace(/^\/carts\/[^/]+/, "/carts/{id}").replace(/^\/checkout-sessions\/[^/]+/, "/checkout-sessions/{id}").replace(/^\/orders\/[^/]+/, "/orders/{id}");
 }