@reactionary/acp 0.10.35 → 0.10.37

package/lib/acp-schemas.js

@@ -40,11 +40,15 @@ const ACPCompleteCheckoutSessionRequestSchema = z.object({
 });
 const ACPCheckoutSessionStateSchema = z.looseObject({
   id: z.string(),
+  // The ACP session owning the backend cart, resumed for later requests.
+  sessionId: z.string().optional(),
   cartId: z.string(),
-  checkoutId: z.string(),
+  // Set once completion has created the real reactionary checkout.
+  checkoutId: z.string().optional(),
   status: z.enum([
     "not_ready_for_payment",
     "ready_for_payment",
+    "in_progress",
     "completed",
     "canceled"
   ]),

package/lib/reactionary-acp-server.js

@@ -18,6 +18,11 @@ import {
 const ACP_SESSION_ID_HEADER = "acp-session-id";
 const SESSION_CACHE_KEY_PREFIX = "reactionary:acp:session";
 const CHECKOUT_SESSION_CACHE_KEY_PREFIX = "reactionary:acp:checkout-session";
+const DEFAULT_ACP_PLACEHOLDER_EMAIL = "pending@checkout.invalid";
+const DEFAULT_ACP_PAYMENT_AUTHORIZATION_WAIT = {
+  timeoutMs: 1e4,
+  intervalMs: 1e3
+};
 const ACP_DISCOVERY_PATHS = ["/.well-known/acp.json", "/.well-known/acp"];
 const ACP_DEFAULT_API_VERSION = "2026-01-30";
 class ReactionaryACPServer {
@@ -50,7 +55,7 @@ class ReactionaryACPServer {
     );
   }
   async handleFetch(request) {
-    const sessionId = getOrCreateSessionId(request);
+    const sessionId = await this.resolveSessionId(request);
     const requestContext = await this.createRequestContext(sessionId);
     const requestedFeed = this.getRequestedProductFeed(request);
     if (requestedFeed) {
@@ -58,11 +63,21 @@ class ReactionaryACPServer {
     }
     const client = this.clientFactory(requestContext);
     assertACPClient(client);
-    const response = await this.handleRequest(request, client, requestContext).catch((error) => toACPErrorResponse(error));
+    const response = await this.handleRequest(request, client, requestContext, sessionId).catch((error) => toACPErrorResponse(error));
     await this.sessionStore.put(sessionId, requestContext.session);
     response.headers.set(ACP_SESSION_ID_HEADER, sessionId);
     return response;
   }
+  /**
+   * Requests addressing a checkout session resume the session that created
+   * it: agents need not echo the ACP session header, but backends scope carts
+   * to that session's (anonymous) identity.
+   */
+  async resolveSessionId(request) {
+    const checkoutSessionId = getCheckoutSessionId(request, this.options.basePath);
+    const state = checkoutSessionId ? await this.checkoutSessionStore.get(checkoutSessionId) : void 0;
+    return state?.sessionId ?? getOrCreateSessionId(request);
+  }
   getHandler() {
     return {
       fetch: (request) => this.fetch(request),
@@ -86,7 +101,7 @@ class ReactionaryACPServer {
     }
     return requestContext;
   }
-  async handleRequest(request, client, requestContext) {
+  async handleRequest(request, client, requestContext, sessionId) {
     if (request.method === "OPTIONS") {
       return new Response(null, {
         status: 204,
@@ -137,7 +152,7 @@ class ReactionaryACPServer {
       });
     }
     if (request.method === "POST") {
-      return this.handlePost(request, client, requestContext);
+      return this.handlePost(request, client, requestContext, sessionId);
     }
     return jsonResponse({
       error: {
@@ -230,7 +245,7 @@ class ReactionaryACPServer {
   getProductFeedDefinition(feedId) {
     return this.options.productFeed?.feeds[feedId];
   }
-  async handlePost(request, client, requestContext) {
+  async handlePost(request, client, requestContext, sessionId) {
     const checkoutSessionId = getCheckoutSessionId(
       request,
       this.options.basePath
@@ -239,7 +254,8 @@ class ReactionaryACPServer {
       return this.createCheckoutSession(
         await parseJsonBody(request, ACPCreateCheckoutSessionRequestSchema),
         client,
-        requestContext
+        requestContext,
+        sessionId
       );
     }
     if (isCheckoutSessionCompleteRequest(request, this.options.basePath)) {
@@ -259,84 +275,39 @@ class ReactionaryACPServer {
       requestContext
     );
   }
-  async createCheckoutSession(input, client, requestContext) {
+  async createCheckoutSession(input, client, requestContext, sessionId) {
     const cart = await this.createCartForItems(input.items, client);
-    const checkout = await unwrapACPResult(
-      client.checkout.initiateCheckoutForCart({
-        cart,
-        billingAddress: input.fulfillment_address ? toReactionaryAddress(input.fulfillment_address) : void 0,
-        notificationEmail: input.buyer?.email,
-        notificationPhone: input.buyer?.phone_number
-      })
-    );
     const state = {
       id: `checkout_session_${crypto.randomUUID()}`,
+      sessionId,
       cartId: cart.identifier.key,
-      checkoutId: checkout.identifier.key,
-      status: getCheckoutStatus(checkout),
+      status: "not_ready_for_payment",
       buyer: input.buyer,
       fulfillmentAddress: input.fulfillment_address
     };
-    await this.checkoutSessionStore.put(state.id, state);
     return jsonResponse(
-      await this.toACPCheckoutSession(state, checkout, client, requestContext),
+      await this.toACPCheckoutSession(state, client, requestContext),
       { status: 201 }
     );
   }
   async updateCheckoutSession(checkoutSessionId, input, client, requestContext) {
     const state = await this.getRequiredCheckoutSessionState(checkoutSessionId);
-    let checkout = await this.getReactionaryCheckout(state, client);
-    let cartId = state.cartId;
-    if (input.items) {
-      const cart = await this.createCartForItems(input.items, client);
-      checkout = await unwrapACPResult(
-        client.checkout.initiateCheckoutForCart({
-          cart,
-          billingAddress: input.fulfillment_address ? toReactionaryAddress(input.fulfillment_address) : state.fulfillmentAddress ? toReactionaryAddress(state.fulfillmentAddress) : void 0,
-          notificationEmail: input.buyer?.email ?? state.buyer?.email,
-          notificationPhone: input.buyer?.phone_number ?? state.buyer?.phone_number
-        })
-      );
-      cartId = cart.identifier.key;
-    }
-    if (input.fulfillment_address) {
-      checkout = await unwrapACPResult(
-        client.checkout.setShippingAddress({
-          checkout: checkout.identifier,
-          shippingAddress: toReactionaryAddress(input.fulfillment_address)
-        })
-      );
-    }
-    if (input.fulfillment_option_id) {
-      checkout = await unwrapACPResult(
-        client.checkout.setShippingInstruction({
-          checkout: checkout.identifier,
-          shippingInstruction: {
-            shippingMethod: { key: input.fulfillment_option_id },
-            pickupPoint: "",
-            instructions: "",
-            consentForUnattendedDelivery: false
-          }
-        })
-      );
+    if (state.checkoutId || state.status === "canceled") {
+      return acpErrorResponse(405, {
+        type: "invalid_request",
+        code: "invalid",
+        message: "The checkout session can no longer be modified."
+      });
     }
     const updatedState = {
       ...state,
-      cartId,
-      checkoutId: checkout.identifier.key,
-      status: getCheckoutStatus(checkout),
+      cartId: input.items ? (await this.createCartForItems(input.items, client)).identifier.key : state.cartId,
       buyer: input.buyer ?? state.buyer,
       fulfillmentAddress: input.fulfillment_address ?? state.fulfillmentAddress,
       fulfillmentOptionId: input.fulfillment_option_id ?? state.fulfillmentOptionId
     };
-    await this.checkoutSessionStore.put(checkoutSessionId, updatedState);
     return jsonResponse(
-      await this.toACPCheckoutSession(
-        updatedState,
-        checkout,
-        client,
-        requestContext
-      )
+      await this.toACPCheckoutSession(updatedState, client, requestContext)
     );
   }
   async getCheckoutSession(checkoutSessionId, client, omitBody) {
@@ -348,12 +319,16 @@ class ReactionaryACPServer {
         message: `Checkout session not found: ${checkoutSessionId}`
       });
     }
-    const checkout = await this.getReactionaryCheckout(state, client);
     return jsonResponse(
-      await this.toACPCheckoutSession(state, checkout, client),
+      await this.toACPCheckoutSession(state, client),
       { omitBody }
     );
   }
+  /**
+   * Creates the real checkout from the session state and finalizes it. A
+   * payment the PSP has not authorized yet leaves the session `in_progress`;
+   * a repeated complete retries finalization.
+   */
   async completeCheckoutSession(checkoutSessionId, input, client) {
     const state = await this.getRequiredCheckoutSessionState(checkoutSessionId);
     if (state.status === "canceled") {
@@ -363,55 +338,58 @@ class ReactionaryACPServer {
         message: "Canceled checkout sessions cannot be completed."
       });
     }
-    let checkout = await this.getReactionaryCheckout(state, client);
-    checkout = await unwrapACPResult(
-      client.checkout.addPaymentInstruction({
-        checkout: checkout.identifier,
-        paymentInstruction: {
-          amount: checkout.price.grandTotal,
-          paymentMethod: toPaymentMethodIdentifier(input.payment_data.provider),
-          protocolData: [
-            {
-              key: "delegated_payment_token",
-              value: input.payment_data.token
-            }
-          ]
-        }
-      })
-    );
-    checkout = await unwrapACPResult(
-      client.checkout.finalizeCheckout({
-        checkout: checkout.identifier
-      })
-    );
-    const completedState = {
-      ...state,
-      status: "completed",
-      buyer: input.buyer ?? state.buyer,
-      orderId: checkout.resultingOrder?.key
-    };
-    await this.checkoutSessionStore.put(checkoutSessionId, completedState);
-    return jsonResponse(
-      await this.toACPCheckoutSession(completedState, checkout, client)
-    );
+    const buyer = input.buyer ?? state.buyer;
+    let current = { ...state, buyer };
+    if (!current.checkoutId) {
+      const view = await this.priceSession(current, client);
+      if (view.status !== "ready_for_payment") {
+        return acpErrorResponse(400, {
+          type: "invalid_request",
+          code: "invalid",
+          message: "The checkout session is missing the buyer email, fulfillment address or fulfillment option."
+        });
+      }
+      const checkout = await this.placeCheckout(current, input, client);
+      current = {
+        ...current,
+        checkoutId: checkout.identifier.key,
+        status: "in_progress"
+      };
+      await this.checkoutSessionStore.put(current.id, current);
+    }
+    if (current.status !== "completed" && current.checkoutId) {
+      const checkoutId = current.checkoutId;
+      const wait = {
+        ...DEFAULT_ACP_PAYMENT_AUTHORIZATION_WAIT,
+        ...this.options.paymentAuthorizationWait
+      };
+      const checkout = await pollUntil(
+        () => unwrapACPResult(client.checkout.getById({ identifier: { key: checkoutId } })),
+        (candidate) => Boolean(candidate.resultingOrder || candidate.readyForFinalization),
+        wait
+      );
+      if (checkout.resultingOrder) {
+        current = { ...current, status: "completed", orderId: checkout.resultingOrder.key };
+      } else if (checkout.readyForFinalization) {
+        const finalized = await unwrapACPResult(
+          client.checkout.finalizeCheckout({ checkout: checkout.identifier })
+        );
+        current = { ...current, status: "completed", orderId: finalized.resultingOrder?.key };
+      }
+    }
+    return jsonResponse(await this.toACPCheckoutSession(current, client));
   }
   async cancelCheckoutSession(checkoutSessionId, client) {
     const state = await this.getRequiredCheckoutSessionState(checkoutSessionId);
-    if (state.status === "completed" || state.status === "canceled") {
+    if (state.checkoutId || state.status === "completed" || state.status === "canceled") {
       return acpErrorResponse(405, {
         type: "invalid_request",
         code: "invalid",
         message: "Completed or canceled checkout sessions cannot be canceled."
       });
     }
-    const canceledState = {
-      ...state,
-      status: "canceled"
-    };
-    const checkout = await this.getReactionaryCheckout(canceledState, client);
-    await this.checkoutSessionStore.put(checkoutSessionId, canceledState);
     return jsonResponse(
-      await this.toACPCheckoutSession(canceledState, checkout, client)
+      await this.toACPCheckoutSession({ ...state, status: "canceled" }, client)
     );
   }
   async createCartForItems(items, client) {
@@ -438,35 +416,109 @@ class ReactionaryACPServer {
     }
     return state;
   }
-  async getReactionaryCheckout(state, client) {
-    return unwrapACPResult(
-      client.checkout.getById({
-        identifier: { key: state.checkoutId }
+  async placeCheckout(state, input, client) {
+    const cart = await unwrapACPResult(client.cart.getById({ cart: { key: state.cartId } }));
+    let checkout = await unwrapACPResult(
+      client.checkout.initiateCheckoutForCart({
+        cart,
+        billingAddress: state.fulfillmentAddress ? toReactionaryAddress(state.fulfillmentAddress) : void 0,
+        notificationEmail: state.buyer?.email,
+        notificationPhone: state.buyer?.phone_number
       })
     );
-  }
-  async toACPCheckoutSession(state, checkout, client, requestContext = createInitialRequestContext()) {
-    const fulfillmentOptions = await this.getFulfillmentOptions(
-      checkout,
-      client
+    if (state.fulfillmentOptionId) {
+      checkout = await unwrapACPResult(
+        client.checkout.setShippingInstruction(toShippingInstruction(checkout, state.fulfillmentOptionId))
+      );
+    }
+    const paid = await client.checkout.addPaymentInstruction({
+      checkout: checkout.identifier,
+      paymentInstruction: {
+        amount: checkout.price.grandTotal,
+        paymentMethod: toPaymentMethodIdentifier(input.payment_data.provider),
+        protocolData: [
+          {
+            key: "delegated_payment_token",
+            value: input.payment_data.token
+          },
+          {
+            key: "delegated_payment_provider",
+            value: input.payment_data.provider
+          }
+        ]
+      }
+    });
+    if (!paid.success) {
+      throw new ACPHttpError(400, {
+        type: "processing_error",
+        code: "payment_declined",
+        message: "The payment could not be authorized with the delegated payment token."
+      });
+    }
+    return paid.value;
+  }
+  /**
+   * Prices the open session with a transient checkout, which is discarded
+   * again: a reactionary checkout is a frozen snapshot, while an ACP session
+   * keeps changing until completion. Backends need an email to quote, so a
+   * placeholder stands in until the buyer supplies one.
+   */
+  async priceSession(state, client) {
+    const cart = await unwrapACPResult(client.cart.getById({ cart: { key: state.cartId } }));
+    if (!state.fulfillmentAddress || state.status === "canceled") {
+      return { cart, price: cart.price, options: [], status: state.status === "canceled" ? "canceled" : "not_ready_for_payment" };
+    }
+    let checkout = await unwrapACPResult(
+      client.checkout.initiateCheckoutForCart({
+        cart,
+        billingAddress: toReactionaryAddress(state.fulfillmentAddress),
+        notificationEmail: state.buyer?.email ?? this.options.placeholderEmail ?? DEFAULT_ACP_PLACEHOLDER_EMAIL,
+        notificationPhone: state.buyer?.phone_number
+      })
     );
+    try {
+      const shippingMethods = await client.checkout.getAvailableShippingMethods({ checkout: checkout.identifier });
+      const options = shippingMethods.success ? shippingMethods.value : [];
+      const selected = options.find((option) => option.identifier.key === state.fulfillmentOptionId);
+      if (selected) {
+        const withShipping = await client.checkout.setShippingInstruction(
+          toShippingInstruction(checkout, selected.identifier.key)
+        );
+        checkout = withShipping.success ? withShipping.value : checkout;
+      }
+      const ready = Boolean(state.buyer?.email) && (options.length === 0 || Boolean(selected));
+      return {
+        cart,
+        checkout,
+        price: checkout.price,
+        options,
+        status: ready ? "ready_for_payment" : "not_ready_for_payment"
+      };
+    } finally {
+      if (checkout.identifier.key !== cart.identifier.key && client.cart.deleteCart) {
+        await client.cart.deleteCart({ cart: checkout.identifier });
+      }
+    }
+  }
+  async toACPCheckoutSession(state, client, requestContext = createInitialRequestContext()) {
+    const view = state.checkoutId ? await this.getPlacedView(state, client) : await this.priceSession(state, client);
+    const persisted = { ...state, status: view.status };
+    await this.checkoutSessionStore.put(persisted.id, persisted);
     return {
-      id: state.id,
-      ...state.buyer ? { buyer: state.buyer } : {},
-      payment_provider: await this.getPaymentProvider(checkout, client),
-      status: state.status === "completed" || state.status === "canceled" ? state.status : getCheckoutStatus(checkout),
-      currency: getCurrency(checkout, requestContext),
-      line_items: checkout.items.map(toACPLineItem),
-      ...state.fulfillmentAddress ? { fulfillment_address: state.fulfillmentAddress } : {},
-      fulfillment_options: fulfillmentOptions,
-      ...state.fulfillmentOptionId ? { fulfillment_option_id: state.fulfillmentOptionId } : checkout.shippingInstruction?.shippingMethod.key ? {
-        fulfillment_option_id: checkout.shippingInstruction.shippingMethod.key
-      } : {},
-      totals: toACPTotals(checkout),
-      ...state.orderId ? {
+      id: persisted.id,
+      ...persisted.buyer ? { buyer: persisted.buyer } : {},
+      payment_provider: await this.getPaymentProvider(view.checkout, client),
+      status: persisted.status,
+      currency: getCurrency(view.price, requestContext),
+      line_items: (view.checkout?.items ?? view.cart?.items ?? []).map(toACPLineItem),
+      ...persisted.fulfillmentAddress ? { fulfillment_address: persisted.fulfillmentAddress } : {},
+      fulfillment_options: view.options.map(toACPFulfillmentOption),
+      ...persisted.fulfillmentOptionId ? { fulfillment_option_id: persisted.fulfillmentOptionId } : {},
+      totals: toACPTotals(view.price),
+      ...persisted.orderId ? {
         order: {
-          id: state.orderId,
-          checkout_session_id: state.id,
+          id: persisted.orderId,
+          checkout_session_id: persisted.id,
           permalink_url: ""
         }
       } : {},
@@ -474,23 +526,25 @@ class ReactionaryACPServer {
       links: this.options.links ?? []
     };
   }
-  async getFulfillmentOptions(checkout, client) {
-    const result = await client.checkout.getAvailableShippingMethods({
-      checkout: checkout.identifier
-    });
-    if (!result.success) {
-      return [];
-    }
-    return result.value.map(toACPFulfillmentOption);
+  async getPlacedView(state, client) {
+    const checkout = await unwrapACPResult(
+      client.checkout.getById({ identifier: { key: state.checkoutId ?? "" } })
+    );
+    return {
+      checkout,
+      price: checkout.price,
+      options: [],
+      status: state.status === "completed" || checkout.resultingOrder ? "completed" : "in_progress"
+    };
   }
   async getPaymentProvider(checkout, client) {
     if (this.options.paymentProvider) {
       return this.options.paymentProvider;
     }
-    const result = await client.checkout.getAvailablePaymentMethods({
+    const result = checkout ? await client.checkout.getAvailablePaymentMethods({
       checkout: checkout.identifier
-    });
-    if (result.success) {
+    }) : void 0;
+    if (result?.success) {
       const supported = result.value.find(
         (method) => ["stripe", "adyen", "braintree"].includes(
           method.identifier.paymentProcessor
@@ -509,6 +563,26 @@ class ReactionaryACPServer {
     };
   }
 }
+function toShippingInstruction(checkout, fulfillmentOptionId) {
+  return {
+    checkout: checkout.identifier,
+    shippingInstruction: {
+      shippingMethod: { key: fulfillmentOptionId },
+      pickupPoint: "",
+      instructions: "",
+      consentForUnattendedDelivery: false
+    }
+  };
+}
+async function pollUntil(read, done, wait) {
+  const deadline = Date.now() + wait.timeoutMs;
+  let value = await read();
+  while (!done(value) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(wait.intervalMs, Math.max(deadline - Date.now(), 0))));
+    value = await read();
+  }
+  return value;
+}
 class ACPHttpError extends Error {
   constructor(status, body) {
     super(body.message);
@@ -680,11 +754,8 @@ async function unwrapACPResult(resultPromise) {
   }
   return result.value;
 }
-function getCheckoutStatus(checkout) {
-  return checkout.readyForFinalization ? "ready_for_payment" : "not_ready_for_payment";
-}
-function getCurrency(checkout, requestContext) {
-  return (checkout.price.grandTotal.currency ?? requestContext.languageContext.currencyCode).toLowerCase();
+function getCurrency(price, requestContext) {
+  return (price.grandTotal.currency ?? requestContext.languageContext.currencyCode).toLowerCase();
 }
 function toACPLineItem(item) {
   const baseAmount = toMinorUnits(item.price.unitPrice.value * item.quantity);
@@ -703,13 +774,13 @@ function toACPLineItem(item) {
     total
   };
 }
-function toACPTotals(checkout) {
-  const base = toMinorUnits(checkout.price.totalProductPrice.value);
-  const discount = toMinorUnits(checkout.price.totalDiscount.value);
+function toACPTotals(price) {
+  const base = toMinorUnits(price.totalProductPrice.value);
+  const discount = toMinorUnits(price.totalDiscount.value);
   const subtotal = Math.max(base - discount, 0);
-  const fulfillment = toMinorUnits(checkout.price.totalShipping.value);
-  const tax = toMinorUnits(checkout.price.totalTax.value);
-  const total = toMinorUnits(checkout.price.grandTotal.value);
+  const fulfillment = toMinorUnits(price.totalShipping.value);
+  const tax = toMinorUnits(price.totalTax.value);
+  const total = toMinorUnits(price.grandTotal.value);
   return [
     {
       type: "items_base_amount",
@@ -858,5 +929,7 @@ function getAcpOperationPath(request, basePath) {
   return pathname.replace(/^\/checkout_sessions\/[^/]+/, "/checkout_sessions/{id}").replace(/^\/product_feeds\/[^/]+/, "/product_feeds/{id}");
 }
 export {
+  DEFAULT_ACP_PAYMENT_AUTHORIZATION_WAIT,
+  DEFAULT_ACP_PLACEHOLDER_EMAIL,
   ReactionaryACPServer
 };

package/package.json

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

package/src/lib/acp-schemas.d.ts

@@ -106,13 +106,15 @@ export declare const ACPCompleteCheckoutSessionRequestSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const ACPCheckoutSessionStateSchema: z.ZodObject<{
     id: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
     cartId: z.ZodString;
-    checkoutId: z.ZodString;
+    checkoutId: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
+        canceled: "canceled";
+        completed: "completed";
         not_ready_for_payment: "not_ready_for_payment";
         ready_for_payment: "ready_for_payment";
-        completed: "completed";
-        canceled: "canceled";
+        in_progress: "in_progress";
     }>;
     buyer: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;

package/src/lib/reactionary-acp-server.d.ts

@@ -6,6 +6,7 @@ export interface ReactionaryACPClient {
         createCart(payload: unknown): Promise<Result<Cart>>;
         add(payload: unknown): Promise<Result<Cart>>;
         getById(payload: unknown): Promise<Result<Cart>>;
+        deleteCart?(payload: unknown): Promise<Result<void>>;
     };
     checkout?: {
         initiateCheckoutForCart(payload: unknown): Promise<Result<Checkout>>;
@@ -43,7 +44,25 @@ export interface ReactionaryACPServerOptions {
     links?: ACPLink[];
     productFeed?: ACPProductFeedOptions;
     discovery?: ACPDiscoveryOptions;
+    /**
+     * Email used to price transient checkouts before the buyer has supplied
+     * one. Never used for the real checkout created on completion.
+     */
+    placeholderEmail?: string;
+    /**
+     * How long checkout completion waits for the placed checkout to become
+     * `readyForFinalization` (i.e. its payment authorized, e.g. by a PSP
+     * webhook) before answering `in_progress`. Defaults to 10s timeout,
+     * polled every 1s; a timeout of 0 disables it.
+     */
+    paymentAuthorizationWait?: Partial<ACPPaymentAuthorizationWait>;
 }
+export declare const DEFAULT_ACP_PLACEHOLDER_EMAIL = "pending@checkout.invalid";
+export interface ACPPaymentAuthorizationWait {
+    timeoutMs: number;
+    intervalMs: number;
+}
+export declare const DEFAULT_ACP_PAYMENT_AUTHORIZATION_WAIT: ACPPaymentAuthorizationWait;
 export interface ACPDiscoveryOptions {
     apiVersion?: string;
     supportedVersions?: string[];
@@ -101,6 +120,12 @@ export declare class ReactionaryACPServer<TClient extends ReactionaryACPClient =
     constructor(clientFactory: ReactionaryACPClientFactory<TClient>, options?: ReactionaryACPServerOptions);
     fetch(request: Request): Promise<Response>;
     private handleFetch;
+    /**
+     * Requests addressing a checkout session resume the session that created
+     * it: agents need not echo the ACP session header, but backends scope carts
+     * to that session's (anonymous) identity.
+     */
+    private resolveSessionId;
     getHandler(): ReactionaryACPHttpHandler;
     toNodeHandler(): ReactionaryACPNodeRequestHandler;
     close(): Promise<void>;
@@ -115,12 +140,24 @@ export declare class ReactionaryACPServer<TClient extends ReactionaryACPClient =
     private createCheckoutSession;
     private updateCheckoutSession;
     private getCheckoutSession;
+    /**
+     * Creates the real checkout from the session state and finalizes it. A
+     * payment the PSP has not authorized yet leaves the session `in_progress`;
+     * a repeated complete retries finalization.
+     */
     private completeCheckoutSession;
     private cancelCheckoutSession;
     private createCartForItems;
     private getRequiredCheckoutSessionState;
-    private getReactionaryCheckout;
+    private placeCheckout;
+    /**
+     * Prices the open session with a transient checkout, which is discarded
+     * again: a reactionary checkout is a frozen snapshot, while an ACP session
+     * keeps changing until completion. Backends need an email to quote, so a
+     * placeholder stands in until the buyer supplies one.
+     */
+    private priceSession;
     private toACPCheckoutSession;
-    private getFulfillmentOptions;
+    private getPlacedView;
     private getPaymentProvider;
 }