@reactionary/acp 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @reactionary/acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+HTTP adapter for exposing Reactionary checkout capabilities through the Agentic Commerce Protocol (ACP) checkout surface.
+
+The package keeps Reactionary core protocol-neutral: host applications mount this adapter and provide a request-scoped Reactionary client factory.
+
+## Implemented surface
+
+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`
+
+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.
+
+## Product feed generation
+
+`GET /product_feeds/{id}/products` generates an ACP-compatible product feed from the configured feed definition whose key matches `{id}`.
+
+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.
+
+Each feed definition provides:
+
+- `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.
+
+By default it returns the ACP JSON shape:
+
+```json
+{
+  "target_country": "FI",
+  "products": []
+}
+```
+
+`target_country` is derived from `languageContext.locale` when the locale includes a region, e.g. `fi-FI` -> `FI`.
+
+For file generation, request JSONL:
+
+```bash
+curl "https://example.com/acp/product_feeds/default/products?format=jsonl" > products.jsonl
+```
+
+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.
+
+## Required Reactionary capabilities
+
+The server validates the supplied client during construction and on every request. If the client does not expose the operations required by ACP checkout, the server does not initialize.
+
+Required operations:
+
+- `cart.createCart`
+- `cart.add`
+- `cart.getById`
+- `checkout.initiateCheckoutForCart`
+- `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.
+
+## Usage
+
+```ts
+import { ReactionaryACPServer } from '@reactionary/acp';
+
+const acp = new ReactionaryACPServer((requestContext) =>
+  createReactionaryClient({ contextOverrides: requestContext }),
+);
+
+export const POST = (request: Request) => acp.fetch(request);
+export const GET = (request: Request) => acp.fetch(request);
+```
+
+For Node HTTP:
+
+```ts
+import { createServer } from 'node:http';
+import { ReactionaryACPServer } from '@reactionary/acp';
+
+const acp = new ReactionaryACPServer(createClient);
+const handler = acp.toNodeHandler();
+
+createServer((request, response) => {
+  void handler(request, response);
+}).listen(3000);
+```
+
+## Session handling
+
+The server uses two pieces of state:
+
+- `RequestContext.session`, keyed by the `acp-session-id` header.
+- ACP checkout-session state, keyed by `checkout_session_id`.
+
+If the request does not include `acp-session-id`, the server creates a new one and returns it in the response.
+
+State is stored through the Reactionary `Cache` interface. The default is `MemoryCache`, which is useful for local development only.
+
+```ts
+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}',
+      },
+    },
+  },
+});
+```
+
+## Mapping notes
+
+- ACP item `id` maps to Reactionary `ProductVariantIdentifier.sku`.
+- 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`.
+
+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.

package/index.js

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

package/lib/acp-schemas.js

@@ -0,0 +1,123 @@
+import * as z from "zod";
+const ACPItemSchema = z.object({
+  id: z.string().min(1),
+  quantity: z.int().min(1)
+});
+const ACPBuyerSchema = z.object({
+  name: z.string().min(1),
+  email: z.email(),
+  phone_number: z.string().optional()
+});
+const ACPAddressSchema = z.object({
+  name: z.string().min(1),
+  line_one: z.string().min(1),
+  line_two: z.string().optional(),
+  city: z.string().min(1),
+  state: z.string().min(1),
+  country: z.string().min(1),
+  postal_code: z.string().min(1),
+  phone_number: z.string().optional()
+});
+const ACPCreateCheckoutSessionRequestSchema = z.object({
+  buyer: ACPBuyerSchema.optional(),
+  items: z.array(ACPItemSchema).min(1),
+  fulfillment_address: ACPAddressSchema.optional()
+});
+const ACPUpdateCheckoutSessionRequestSchema = z.object({
+  buyer: ACPBuyerSchema.optional(),
+  items: z.array(ACPItemSchema).min(1).optional(),
+  fulfillment_address: ACPAddressSchema.optional(),
+  fulfillment_option_id: z.string().optional()
+});
+const ACPPaymentDataSchema = z.object({
+  token: z.string().min(1),
+  provider: z.enum(["stripe", "adyen", "braintree"]),
+  billing_address: ACPAddressSchema.optional()
+});
+const ACPCompleteCheckoutSessionRequestSchema = z.object({
+  buyer: ACPBuyerSchema.optional(),
+  payment_data: ACPPaymentDataSchema
+});
+const ACPCheckoutSessionStateSchema = z.looseObject({
+  id: z.string(),
+  cartId: z.string(),
+  checkoutId: z.string(),
+  status: z.enum([
+    "not_ready_for_payment",
+    "ready_for_payment",
+    "completed",
+    "canceled"
+  ]),
+  buyer: ACPBuyerSchema.optional(),
+  fulfillmentAddress: ACPAddressSchema.optional(),
+  fulfillmentOptionId: z.string().optional(),
+  orderId: z.string().optional()
+});
+const ACPDescriptionSchema = z.object({
+  plain: z.string().optional(),
+  html: z.string().optional(),
+  markdown: z.string().optional()
+});
+const ACPMediaSchema = z.object({
+  url: z.string(),
+  alt_text: z.string().optional()
+});
+const ACPFeedPriceSchema = z.object({
+  amount: z.int(),
+  currency: z.string().length(3)
+});
+const ACPAvailabilitySchema = z.object({
+  available: z.boolean().optional(),
+  status: z.string().optional()
+});
+const ACPBarcodeSchema = z.object({
+  type: z.string(),
+  value: z.string()
+});
+const ACPVariantOptionSchema = z.object({
+  name: z.string(),
+  value: z.string()
+});
+const ACPFeedVariantSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: ACPDescriptionSchema.optional(),
+  url: z.string().optional(),
+  barcodes: z.array(ACPBarcodeSchema).optional(),
+  price: ACPFeedPriceSchema.optional(),
+  list_price: ACPFeedPriceSchema.optional(),
+  availability: ACPAvailabilitySchema.optional(),
+  variant_options: z.array(ACPVariantOptionSchema).optional(),
+  media: z.array(ACPMediaSchema).optional()
+});
+const ACPFeedProductSchema = z.object({
+  id: z.string(),
+  title: z.string().optional(),
+  description: ACPDescriptionSchema.optional(),
+  url: z.string().optional(),
+  media: z.array(ACPMediaSchema).optional(),
+  variants: z.array(ACPFeedVariantSchema).min(1)
+});
+const ACPProductFeedResponseSchema = z.object({
+  target_country: z.string().length(2).optional(),
+  products: z.array(ACPFeedProductSchema)
+});
+export {
+  ACPAddressSchema,
+  ACPAvailabilitySchema,
+  ACPBarcodeSchema,
+  ACPBuyerSchema,
+  ACPCheckoutSessionStateSchema,
+  ACPCompleteCheckoutSessionRequestSchema,
+  ACPCreateCheckoutSessionRequestSchema,
+  ACPDescriptionSchema,
+  ACPFeedPriceSchema,
+  ACPFeedProductSchema,
+  ACPFeedVariantSchema,
+  ACPItemSchema,
+  ACPMediaSchema,
+  ACPPaymentDataSchema,
+  ACPProductFeedResponseSchema,
+  ACPUpdateCheckoutSessionRequestSchema,
+  ACPVariantOptionSchema
+};