@reactionary/ucp 0.0.1

package/lib/reactionary-ucp-rest.js

@@ -0,0 +1,715 @@
+import { jsonResponse } from "./reactionary-ucp-http.js";
+async function handleRestRequest(request, client, path, sessionId, sessionStore) {
+  if (request.method === "POST" && path === "/catalog/search") {
+    return jsonResponse(await handleCatalogSearch(client, await parseJsonBody(request)));
+  }
+  if (request.method === "POST" && path === "/catalog/lookup") {
+    return jsonResponse(await handleCatalogLookup(client, await parseJsonBody(request)));
+  }
+  if (request.method === "POST" && path === "/catalog/product") {
+    return jsonResponse(await handleCatalogProduct(client, await parseJsonBody(request)));
+  }
+  if (request.method === "POST" && path === "/carts") {
+    const body = await parseJsonBody(request);
+    return withRestIdempotency(
+      request,
+      sessionId,
+      "REST POST /carts",
+      body,
+      sessionStore,
+      async () => jsonResponse(await handleCreateCart(client, body), { status: 201 })
+    );
+  }
+  const cartMatch = /^\/carts\/([^/]+)$/.exec(path);
+  if (cartMatch && request.method === "GET") {
+    return jsonResponse(await handleGetCart(client, decodeURIComponent(cartMatch[1])));
+  }
+  if (cartMatch && request.method === "PUT") {
+    const body = await parseJsonBody(request);
+    return withRestIdempotency(
+      request,
+      sessionId,
+      `REST PUT /carts/${decodeURIComponent(cartMatch[1])}`,
+      body,
+      sessionStore,
+      async () => jsonResponse(await handleUpdateCart(client, decodeURIComponent(cartMatch[1]), body))
+    );
+  }
+  const cartCancelMatch = /^\/carts\/([^/]+)\/cancel$/.exec(path);
+  if (cartCancelMatch && request.method === "POST") {
+    return withRestIdempotency(
+      request,
+      sessionId,
+      `REST POST /carts/${decodeURIComponent(cartCancelMatch[1])}/cancel`,
+      {},
+      sessionStore,
+      async () => jsonResponse(await handleCancelCart(client, decodeURIComponent(cartCancelMatch[1])))
+    );
+  }
+  if (request.method === "POST" && path === "/checkout-sessions") {
+    const body = await parseJsonBody(request);
+    return withRestIdempotency(
+      request,
+      sessionId,
+      "REST POST /checkout-sessions",
+      body,
+      sessionStore,
+      async () => jsonResponse(await handleCreateCheckout(client, body), { status: 201 })
+    );
+  }
+  const checkoutMatch = /^\/checkout-sessions\/([^/]+)$/.exec(path);
+  if (checkoutMatch && request.method === "GET") {
+    return jsonResponse(await handleGetCheckout(client, decodeURIComponent(checkoutMatch[1])));
+  }
+  if (checkoutMatch && request.method === "PUT") {
+    const body = await parseJsonBody(request);
+    return withRestIdempotency(
+      request,
+      sessionId,
+      `REST PUT /checkout-sessions/${decodeURIComponent(checkoutMatch[1])}`,
+      body,
+      sessionStore,
+      async () => jsonResponse(await handleUpdateCheckout(client, decodeURIComponent(checkoutMatch[1]), body))
+    );
+  }
+  const checkoutCompleteMatch = /^\/checkout-sessions\/([^/]+)\/complete$/.exec(path);
+  if (checkoutCompleteMatch && request.method === "POST") {
+    return withRestIdempotency(
+      request,
+      sessionId,
+      `REST POST /checkout-sessions/${decodeURIComponent(checkoutCompleteMatch[1])}/complete`,
+      {},
+      sessionStore,
+      async () => jsonResponse(await handleCompleteCheckout(client, decodeURIComponent(checkoutCompleteMatch[1])))
+    );
+  }
+  const checkoutCancelMatch = /^\/checkout-sessions\/([^/]+)\/cancel$/.exec(path);
+  if (checkoutCancelMatch && request.method === "POST") {
+    return withRestIdempotency(
+      request,
+      sessionId,
+      `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 })
+    );
+  }
+  const orderMatch = /^\/orders\/([^/]+)$/.exec(path);
+  if (orderMatch && request.method === "GET") {
+    return jsonResponse(await handleGetOrder(client, decodeURIComponent(orderMatch[1])));
+  }
+  return void 0;
+}
+async function withRestIdempotency(request, sessionId, action, payload, sessionStore, createResponse) {
+  const idempotencyKey = request.headers.get("Idempotency-Key");
+  if (!idempotencyKey) {
+    return createResponse();
+  }
+  const fingerprint = JSON.stringify(payload);
+  const cached = await sessionStore.getIdempotencyRecord(sessionId, 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(cached.response, { status: cached.status ?? 200 });
+  }
+  const response = await createResponse();
+  const responseBody = await response.clone().json();
+  await sessionStore.putIdempotencyRecord(sessionId, idempotencyKey, {
+    action,
+    fingerprint,
+    status: response.status,
+    response: responseBody
+  });
+  return response;
+}
+async function parseJsonBody(request) {
+  if (!request.body) {
+    return {};
+  }
+  try {
+    return await request.json();
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new UCPHttpError(400, createUCPError("invalid_json", "Request body must be valid JSON."));
+    }
+    throw error;
+  }
+}
+async function handleCatalogSearch(client, body) {
+  if (!client.productSearch) {
+    return createUCPError("not_available", "Product search capability is not available.");
+  }
+  const pageSize = getLimit(body);
+  const offset = getPaginationOffset(body);
+  if (offset === void 0) {
+    return createUCPError("invalid_request", "Catalog search pagination cursor must be a non-negative integer offset.");
+  }
+  const filterMapping = await getSearchFilterMapping(client, body.filters);
+  const result = await client.productSearch.queryByTerm({
+    search: {
+      term: body.query ?? "",
+      facets: [],
+      filters: filterMapping.filters,
+      paginationOptions: {
+        pageNumber: offsetToPageNumber(offset, pageSize),
+        pageSize
+      },
+      ...filterMapping.categoryFilter ? { categoryFilter: filterMapping.categoryFilter } : {}
+    }
+  });
+  if (!result.success) {
+    return createUCPError("search_failed", "Catalog search failed.");
+  }
+  return {
+    ucp: createUcpSuccessMetadata(),
+    products: result.value.items.map((product) => toUcpProduct(product)),
+    pagination: toUcpPagination(result.value),
+    ...filterMapping.messages.length > 0 ? { messages: filterMapping.messages } : {}
+  };
+}
+async function handleCatalogLookup(client, body) {
+  const products = await Promise.all(
+    body.ids.map((id) => getReactionaryProduct(client, id))
+  );
+  return {
+    ucp: createUcpSuccessMetadata(),
+    products: products.filter((product) => product !== void 0).map((product) => toUcpProduct(product))
+  };
+}
+async function handleCatalogProduct(client, body) {
+  const { id } = body;
+  if (!id) {
+    return createUCPError("invalid_request", "A product id, variant id, or sku is required.");
+  }
+  const product = await getReactionaryProduct(client, id);
+  if (!product) {
+    return createUCPError("not_found", `Product was not found: ${id}`);
+  }
+  return {
+    ucp: createUcpSuccessMetadata(),
+    product: toUcpProduct(product)
+  };
+}
+async function handleCreateCart(client, body) {
+  if (!client.cart) {
+    return createUCPError("not_available", "Cart capability is not available.");
+  }
+  const createResult = await client.cart.createCart({});
+  if (!createResult.success) {
+    return createUCPError("cart_create_failed", "Cart creation failed.");
+  }
+  let cart = createResult.value;
+  for (const lineItem of body["line_items"]) {
+    if (!lineItem.item.id) {
+      return createUCPError("cart_add_failed", "Unable to add cart line item without an item id.");
+    }
+    const addResult = await client.cart.add({
+      cart: cart.identifier,
+      variant: {
+        sku: lineItem.item.id
+      },
+      quantity: lineItem.quantity
+    });
+    if (!addResult.success) {
+      return createUCPError("cart_add_failed", `Unable to add item to cart: ${lineItem.item.id}`);
+    }
+    cart = addResult.value;
+  }
+  return toUcpCart(cart);
+}
+async function handleGetCart(client, cartId) {
+  if (!client.cart) {
+    return createUCPError("not_available", "Cart capability is not available.");
+  }
+  const result = await client.cart.getById({ cart: { key: cartId } });
+  if (!result.success) {
+    return createUCPError("not_found", `Cart was not found: ${cartId}`);
+  }
+  return toUcpCart(result.value);
+}
+async function handleUpdateCart(client, cartId, body) {
+  if (!client.cart) {
+    return createUCPError("not_available", "Cart capability is not available.");
+  }
+  const current = await client.cart.getById({ cart: { key: cartId } });
+  if (!current.success) {
+    return createUCPError("not_found", `Cart was not found: ${cartId}`);
+  }
+  const desiredItems = /* @__PURE__ */ new Map();
+  for (const lineItem of body.line_items) {
+    desiredItems.set(lineItem.item.id, lineItem);
+  }
+  let cart = current.value;
+  for (const existingItem of current.value.items) {
+    const sku = existingItem.variant.sku;
+    const desiredItem = desiredItems.get(sku);
+    if (!desiredItem) {
+      const removeResult = await client.cart.remove({
+        cart: current.value.identifier,
+        item: existingItem.identifier
+      });
+      if (!removeResult.success) {
+        return createUCPError("cart_update_failed", `Unable to remove item from cart: ${sku}`);
+      }
+      cart = removeResult.value;
+      continue;
+    }
+    if (existingItem.quantity !== desiredItem.quantity) {
+      const quantityResult = await client.cart.changeQuantity({
+        cart: current.value.identifier,
+        item: existingItem.identifier,
+        quantity: desiredItem.quantity
+      });
+      if (!quantityResult.success) {
+        return createUCPError("cart_update_failed", `Unable to change quantity for cart item: ${sku}`);
+      }
+      cart = quantityResult.value;
+    }
+  }
+  const existingSkus = new Set(current.value.items.map((item) => item.variant.sku));
+  for (const desiredItem of desiredItems.values()) {
+    if (existingSkus.has(desiredItem.item.id)) {
+      continue;
+    }
+    const addResult = await client.cart.add({
+      cart: current.value.identifier,
+      variant: {
+        sku: desiredItem.item.id
+      },
+      quantity: desiredItem.quantity
+    });
+    if (!addResult.success) {
+      return createUCPError("cart_update_failed", `Unable to add item to cart: ${desiredItem.item.id}`);
+    }
+    cart = addResult.value;
+  }
+  return toUcpCart(cart);
+}
+async function handleCancelCart(client, cartId) {
+  if (!client.cart) {
+    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 } });
+  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) {
+  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);
+}
+async function handleGetCheckout(client, checkoutId) {
+  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);
+}
+async function handleUpdateCheckout(client, checkoutId, body) {
+  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);
+}
+async function handleCompleteCheckout(client, checkoutId) {
+  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, "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: toUcpTotals(result.value.price?.grandTotal),
+    fulfillment: {
+      expectations: [],
+      events: []
+    },
+    messages: []
+  };
+}
+async function getReactionaryCart(client, cartId) {
+  if (!client.cart) {
+    return void 0;
+  }
+  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;
+  }
+  const byId = await client.product.getById({ identifier: { key: id } });
+  if (byId.success) {
+    return byId.value;
+  }
+  const bySku = await client.product.getBySKU({ variant: { sku: id } });
+  return bySku.success ? bySku.value : void 0;
+}
+function toUcpProduct(product) {
+  const ucpVariants = getUcpProductVariants(product);
+  return {
+    id: product.identifier.key,
+    handle: product.slug,
+    title: product.name,
+    description: toUcpDescription(getProductDescription(product)),
+    url: product.slug ? `/${product.slug}` : void 0,
+    price_range: {
+      min: ucpVariants[0]?.price ?? createUcpPrice(),
+      max: ucpVariants[0]?.price ?? createUcpPrice()
+    },
+    variants: ucpVariants,
+    media: []
+  };
+}
+function getUcpProductVariants(product) {
+  if (isProduct(product)) {
+    return [
+      product.mainVariant,
+      ...product.variants
+    ].map((variant, index) => toUcpProductVariant(variant, product, index));
+  }
+  return product.variants.map((variant, index) => toUcpSearchVariant(variant, product, index));
+}
+function isProduct(product) {
+  return "mainVariant" in product;
+}
+function getProductDescription(product) {
+  return isProduct(product) ? product.description || product.longDescription : void 0;
+}
+function toUcpProductVariant(variant, product, index) {
+  const sku = variant.identifier.sku || `${product.identifier.key}-${index + 1}`;
+  return {
+    id: sku,
+    sku,
+    title: variant.name || product.name,
+    description: toUcpDescription(void 0),
+    price: createUcpPrice(),
+    availability: {
+      status: "available"
+    },
+    media: []
+  };
+}
+function toUcpSearchVariant(variant, product, index) {
+  const sku = variant.variant.sku || `${product.identifier.key}-${index + 1}`;
+  return {
+    id: sku,
+    sku,
+    title: product.name,
+    description: toUcpDescription(void 0),
+    price: createUcpPrice(),
+    availability: {
+      status: "available"
+    },
+    media: variant.image.sourceUrl ? [{
+      type: "image",
+      url: variant.image.sourceUrl,
+      alt_text: variant.image.altText
+    }] : []
+  };
+}
+function toUcpCart(cart) {
+  return {
+    id: cart.identifier.key,
+    line_items: cart.items.map(toUcpCartLineItem),
+    currency: getMoneyCurrency(cart.price?.grandTotal),
+    totals: toUcpTotals(cart.price?.grandTotal),
+    ucp: createUcpSuccessMetadata()
+  };
+}
+function createEmptyUcpCart(cartId) {
+  return {
+    id: cartId,
+    line_items: [],
+    currency: "EUR",
+    totals: [],
+    ucp: createUcpSuccessMetadata()
+  };
+}
+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, 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),
+    links: [],
+    ucp: createUcpCheckoutSuccessMetadata()
+  };
+}
+function toUcpDescription(text) {
+  return text ? { plain: text } : { plain: "" };
+}
+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() {
+  return {
+    version: "2026-08-25",
+    status: "success",
+    payment_handlers: {}
+  };
+}
+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;
+}
+async function getSearchFilterMapping(client, filters) {
+  if (!filters) {
+    return {
+      filters: [],
+      messages: []
+    };
+  }
+  const messages = [];
+  const categoryFilter = await getCategoryFilter(client, filters.categories, messages);
+  if (filters.price) {
+    messages.push(createUcpWarning(
+      "price_filter_ignored",
+      "Price filters are not supported by Reactionary product search yet and were ignored.",
+      "$.filters.price"
+    ));
+  }
+  return {
+    ...categoryFilter ? { categoryFilter } : {},
+    filters: getExtensionFilters(filters),
+    messages
+  };
+}
+async function getCategoryFilter(client, categories, messages) {
+  const [category, ...additionalCategories] = categories ?? [];
+  if (!category) {
+    return void 0;
+  }
+  if (additionalCategories.length > 0) {
+    messages.push(createUcpWarning(
+      "additional_categories_ignored",
+      "Reactionary product search currently supports one category filter; additional UCP category filters were ignored.",
+      "$.filters.categories"
+    ));
+  }
+  const productSearch = client.productSearch;
+  if (!productSearch?.createCategoryNavigationFilter) {
+    return {
+      facet: { key: "categories" },
+      key: category
+    };
+  }
+  const result = await productSearch.createCategoryNavigationFilter({
+    categoryPath: toReactionaryCategoryPath(category)
+  });
+  if (!result.success) {
+    messages.push(createUcpWarning(
+      "category_filter_ignored",
+      `Category filter could not be resolved and was ignored: ${category}`,
+      "$.filters.categories[0]"
+    ));
+    return void 0;
+  }
+  return result.value;
+}
+function toReactionaryCategoryPath(category) {
+  return category.split(">").map((part) => part.trim()).filter((part) => part.length > 0).map((part) => ({
+    identifier: { key: part },
+    name: part,
+    slug: "",
+    text: "",
+    images: []
+  }));
+}
+function getExtensionFilters(filters) {
+  if (!filters) {
+    return [];
+  }
+  return Object.entries(filters).filter(([key]) => key !== "categories" && key !== "price").flatMap(([key, value]) => toReactionaryFilterStrings(key, value));
+}
+function toReactionaryFilterStrings(key, value) {
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => toReactionaryFilterStrings(key, item));
+  }
+  return [`${key}:${formatFilterValue(value)}`];
+}
+function formatFilterValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function getPaginationOffset(body) {
+  const cursor = body.pagination?.cursor;
+  if (cursor === void 0) {
+    return 0;
+  }
+  if (!/^(0|[1-9]\d*)$/.test(cursor)) {
+    return void 0;
+  }
+  return Number(cursor);
+}
+function offsetToPageNumber(offset, pageSize) {
+  return Math.floor(offset / pageSize) + 1;
+}
+function toUcpPagination(result) {
+  const nextOffset = result.pageNumber * result.pageSize;
+  const hasNextPage = nextOffset < result.totalCount;
+  return {
+    ...hasNextPage ? { cursor: String(nextOffset) } : {},
+    has_next_page: hasNextPage,
+    total_count: result.totalCount
+  };
+}
+class UCPHttpError extends Error {
+  constructor(status, body) {
+    super("UCP HTTP error");
+    this.status = status;
+    this.body = body;
+  }
+  status;
+  body;
+}
+export {
+  UCPHttpError,
+  handleRestRequest
+};