@reactionary/ucp 0.0.1

package/README.md

@@ -0,0 +1,154 @@
+# @reactionary/ucp
+
+Framework shell for exposing Reactionary through a Universal Commerce Protocol (UCP) HTTP surface.
+
+This package exposes a thin Universal Commerce Protocol (UCP) HTTP surface on top of an instantiated Reactionary client. It serves the UCP discovery profile and a canonical Shopping REST surface.
+
+## Design goals
+
+- Keep Reactionary core protocol-neutral.
+- Accept a Reactionary client factory instead of a singleton client.
+- Create a fresh `RequestContext` per request.
+- Persist only `RequestContext.session` between requests for the same UCP session.
+- Let host applications mount the handler in Next.js, Node, Express, or another HTTP framework.
+
+## Usage
+
+```ts
+import { ReactionaryUCPServer } from '@reactionary/ucp';
+
+const ucp = new ReactionaryUCPServer(
+  (requestContext) => createReactionaryClient({ contextOverrides: requestContext }),
+  {
+    profile: {
+      endpoint: 'https://shop.example.com/ucp',
+      merchant: {
+        name: 'Example shop',
+        url: 'https://shop.example.com',
+        contact: {
+          email: 'support@example.com',
+        },
+      },
+      keys: [
+        // Public verification JWKs only. Never put private keys in the profile.
+      ],
+    },
+  },
+);
+
+export const POST = (request: Request) => ucp.fetch(request);
+export const GET = (request: Request) => ucp.fetch(request);
+```
+
+For Node HTTP:
+
+```ts
+import { createServer } from 'node:http';
+import { ReactionaryUCPServer } from '@reactionary/ucp';
+
+const ucp = new ReactionaryUCPServer(createClient);
+const handler = ucp.toNodeHandler();
+
+createServer((request, response) => {
+  void handler(request, response);
+}).listen(3000);
+```
+
+## Session handling
+
+The server uses the `ucp-session-id` header. If the request does not include one, the server creates a new session id and returns it in the response.
+
+Session state is stored through the Reactionary `Cache` interface. The default is `MemoryCache`, which is useful for local development only.
+
+```ts
+new ReactionaryUCPServer(createClient, {
+  sessionCache: redisCache,
+  sessionTtlSeconds: 60 * 60,
+});
+```
+
+## Current behavior
+
+- `GET /.well-known/ucp` returns a UCP discovery profile for the official Shopping REST service.
+- Canonical Shopping REST endpoints are available below the configured `profile.endpoint` path.
+- `OPTIONS` returns allowed methods.
+- Unmatched routes return `404 NOT_FOUND`.
+
+## UCP discovery profile
+
+The official discovery profile is served from `/.well-known/ucp`. The profile advertises:
+
+- `ucp.version: "2026-08-25"`
+- the `dev.ucp.shopping` REST service endpoint
+- capabilities derived from the configured Reactionary client
+- configured merchant metadata
+- configured public keys
+- configured payment handlers, if supplied
+
+Capability advertisement is intentionally derived from the instantiated client:
+
+| Advertised capability | Required Reactionary capability |
+| --- | --- |
+| `dev.ucp.shopping.catalog.search` | `product-search` |
+| `dev.ucp.shopping.catalog.lookup` | `product` |
+| `dev.ucp.shopping.cart` | `cart` |
+| `dev.ucp.shopping.discount` | `cart.applyCouponCode` |
+| `dev.ucp.shopping.checkout` | `checkout` |
+| `dev.ucp.shopping.order` | `order` |
+
+## Canonical Shopping REST endpoints
+
+The Shopping REST request and response types are generated from the official OpenAPI document:
+
+```bash
+npx --yes -p typescript@5.9.2 -p openapi-typescript@7.10.1 \
+  openapi-typescript https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json \
+  -o packages/ucp/src/lib/ucp-shopping.openapi.ts
+```
+
+The first REST implementation maps the endpoints that fit Reactionary's current provider model:
+
+| Endpoint | Reactionary mapping |
+| --- | --- |
+| `POST /catalog/search` | `product-search.queryByTerm` |
+| `POST /catalog/lookup` | `product.getById` / `product.getBySKU` |
+| `POST /catalog/product` | `product.getById` / `product.getBySKU` |
+| `POST /carts` | `cart.createCart` plus `cart.add` for submitted line items |
+| `GET /carts/{id}` | `cart.getById` |
+| `PUT /carts/{id}` | Composes `cart.getById`, `cart.remove`, `cart.changeQuantity`, and `cart.add` to reconcile line items by SKU |
+| `POST /carts/{id}/cancel` | `cart.deleteCart` |
+| `POST /checkout-sessions` | `checkout.initiateCheckoutForCart`; if `line_items` are supplied without `cart_id`, a cart is created first |
+| `GET /checkout-sessions/{id}` | `checkout.getById` |
+| `PUT /checkout-sessions/{id}` | Composes `checkout.getById` and `checkout.addPaymentInstruction` for selected delegated payment instruments |
+| `POST /checkout-sessions/{id}/complete` | `checkout.finalizeCheckout` |
+| `GET /orders/{id}` | `order.getById` |
+
+`POST /catalog/search` treats the UCP `pagination.cursor` as an opaque offset encoded as a base-10 string. When present, that offset is converted to Reactionary's page-based `paginationOptions.pageNumber` using the requested `pagination.limit` as `pageSize`. Search responses include `pagination.cursor` only when another page is available; the returned cursor is the next page boundary offset.
+
+UCP catalog search filters are mapped to Reactionary search inputs where possible:
+
+- `filters.categories[0]` is treated as a breadcrumb string separated by `>` and resolved through `product-search.createCategoryNavigationFilter` when available. The resolved value is passed as Reactionary `categoryFilter`.
+- Additional category values are ignored for now because Reactionary search has a single `categoryFilter`; the response includes a warning message when this happens.
+- `filters.price` is ignored for now because Reactionary product search has no provider-neutral price filter; the response includes a warning message.
+- Other extension filter keys are passed through as Reactionary string filters in `key:value` form. Array values produce one filter string per item.
+
+`PUT /carts/{id}` is implemented as a best-effort reconciliation against the current authoritative cart. It fetches the cart, removes existing SKUs absent from the request, changes quantities for existing SKUs, adds new SKUs, and returns the latest cart from the final mutation.
+
+`PUT /checkout-sessions/{id}` is implemented as a constrained composed update. Today it applies selected delegated payment instruments through `checkout.addPaymentInstruction` and returns the updated checkout. UCP fields that do not yet have a Reactionary checkout mutation, such as buyer/contact replacement or full payment-instruction replacement, are intentionally ignored rather than represented as successful core updates.
+
+`POST /checkout-sessions/{id}/cancel` is routed but currently returns a structured UCP error because checkout cancellation is not represented by Reactionary's current core checkout capabilities.
+
+REST requests may include:
+
+- `Request-Id`: echoed in the response header.
+- `Idempotency-Key`: supported for mutating REST endpoints and stored in the UCP session cache. Reusing a key with a different mutation payload returns `409`.
+
+## Request IDs and idempotency
+
+`Request-Id` is optional and echoed in the response header so agents can correlate calls and responses.
+
+Mutating REST endpoints also support an optional `Idempotency-Key` header. When a mutating REST request is called with an `Idempotency-Key`, the response is cached in the current UCP session storage. Repeating the same mutating request with the same key and payload in the same session replays the cached response instead of invoking the provider again.
+
+Reusing the same idempotency key for a different mutating REST route or payload in the same session returns `409 idempotency_key_conflict`.
+
+Idempotency records use the same TTL and cache backend as UCP session state. For the intended agent flow, a session is expected to be short-lived and contain a small number of requests.

package/index.js

@@ -0,0 +1 @@
+export * from "./lib/reactionary-ucp-server.js";

package/lib/reactionary-ucp-capabilities.js

@@ -0,0 +1,19 @@
+import { BaseCapability } from "@reactionary/core";
+function hasCapability(client, name) {
+  return Boolean(getCapability(client, name));
+}
+function getCapability(client, name) {
+  const capability = Object.values(client).find((value) => value instanceof BaseCapability && getCapabilityResourceName(value) === name);
+  return capability instanceof BaseCapability ? capability : void 0;
+}
+function getCapabilityResourceName(capability) {
+  const getResourceName = Reflect.get(capability, "getResourceName");
+  if (typeof getResourceName !== "function") {
+    return "";
+  }
+  return Reflect.apply(getResourceName, capability, []);
+}
+export {
+  getCapability,
+  hasCapability
+};

package/lib/reactionary-ucp-http.js

@@ -0,0 +1,79 @@
+const UCP_SESSION_ID_HEADER = "ucp-session-id";
+function getSessionId(request) {
+  return request.headers.get(UCP_SESSION_ID_HEADER) ?? void 0;
+}
+function getOrCreateSessionId(request) {
+  return getSessionId(request) ?? crypto.randomUUID();
+}
+function jsonResponse(body, options = {}) {
+  const headers = new Headers(options.headers);
+  headers.set("content-type", "application/json; charset=utf-8");
+  return new Response(
+    options.omitBody ? null : JSON.stringify(body),
+    {
+      status: options.status ?? 200,
+      headers
+    }
+  );
+}
+async function toWebRequest(request) {
+  const headers = toWebHeaders(request.headers);
+  const url = new URL(
+    request.url ?? "/",
+    `http://${request.headers.host ?? "localhost"}`
+  );
+  const body = await readNodeRequestBody(request);
+  return new Request(url, {
+    method: request.method,
+    headers,
+    body
+  });
+}
+function toWebHeaders(headers) {
+  const webHeaders = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value) {
+        webHeaders.append(key, entry);
+      }
+      continue;
+    }
+    webHeaders.set(key, value);
+  }
+  return webHeaders;
+}
+async function readNodeRequestBody(request) {
+  if (request.method === "GET" || request.method === "HEAD") {
+    return null;
+  }
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  if (chunks.length === 0) {
+    return null;
+  }
+  return Buffer.concat(chunks);
+}
+async function sendWebResponse(response, webResponse) {
+  response.writeHead(
+    webResponse.status,
+    Object.fromEntries(webResponse.headers.entries())
+  );
+  if (!webResponse.body) {
+    response.end();
+    return;
+  }
+  const body = Buffer.from(await webResponse.arrayBuffer());
+  response.end(body);
+}
+export {
+  UCP_SESSION_ID_HEADER,
+  getOrCreateSessionId,
+  jsonResponse,
+  sendWebResponse,
+  toWebRequest
+};

package/lib/reactionary-ucp-profile.js

@@ -0,0 +1,72 @@
+import { getCapability, hasCapability } from "./reactionary-ucp-capabilities.js";
+function getRequestRoute(request, profile) {
+  const url = new URL(request.url);
+  const endpointPath = profile ? new URL(profile.endpoint).pathname.replace(/\/$/, "") : "";
+  if (endpointPath && url.pathname.startsWith(`${endpointPath}/`)) {
+    return {
+      path: url.pathname.slice(endpointPath.length) || "/"
+    };
+  }
+  return {
+    path: url.pathname
+  };
+}
+function createUCPProfile(client, profile) {
+  const endpoint = profile?.endpoint ?? "http://localhost/ucp";
+  return {
+    ucp: {
+      version: "2026-08-25",
+      services: profile?.services ?? {
+        "dev.ucp.shopping": [
+          {
+            version: "2026-08-25",
+            transport: "rest",
+            endpoint
+          }
+        ]
+      },
+      capabilities: profile?.capabilities ?? createUcpCapabilities(client),
+      ...profile?.paymentHandlers ? { payment_handlers: profile.paymentHandlers } : {}
+    },
+    keys: profile?.keys ?? [],
+    merchant: profile?.merchant ?? {
+      name: "Reactionary",
+      url: endpoint,
+      contact: {
+        email: "support@example.com"
+      }
+    }
+  };
+}
+function createUcpCapabilities(client) {
+  const capabilities = {};
+  if (hasCapability(client, "product-search")) {
+    capabilities["dev.ucp.shopping.catalog.search"] = [createUcpCapability()];
+  }
+  if (hasCapability(client, "product")) {
+    capabilities["dev.ucp.shopping.catalog.lookup"] = [createUcpCapability()];
+  }
+  if (hasCapability(client, "cart")) {
+    capabilities["dev.ucp.shopping.cart"] = [createUcpCapability()];
+    const cart = getCapability(client, "cart");
+    if (cart && typeof Reflect.get(cart, "applyCouponCode") === "function") {
+      capabilities["dev.ucp.shopping.discount"] = [createUcpCapability()];
+    }
+  }
+  if (hasCapability(client, "checkout")) {
+    capabilities["dev.ucp.shopping.checkout"] = [createUcpCapability()];
+  }
+  if (hasCapability(client, "order")) {
+    capabilities["dev.ucp.shopping.order"] = [createUcpCapability()];
+  }
+  return capabilities;
+}
+function createUcpCapability() {
+  return {
+    version: "2026-08-25"
+  };
+}
+export {
+  createUCPProfile,
+  getRequestRoute
+};