@reactionary/acp 0.10.41 → 0.10.43

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

@@ -0,0 +1,48 @@
+/** An agent's order webhook receiver and the secret shared with it. */
+export interface ACPWebhookEndpoint {
+    /** e.g. the agent's `.../agentic_checkout/webhooks/order_events` URL. */
+    url: string;
+    /** Shared secret for the `Merchant-Signature` HMAC. */
+    secret: string;
+    /**
+     * The authenticated agent (see `authenticate`) whose orders go to this
+     * endpoint. Endpoints without one receive orders of every agent that has
+     * no endpoint of its own.
+     */
+    agentId?: string;
+}
+export interface ACPWebhookOptions {
+    endpoints: ACPWebhookEndpoint[];
+    /**
+     * Delays before each retry of a failed delivery. Retries are held in
+     * memory, so they do not survive a restart. Defaults to 0.5s, 2s, 10s, 1m
+     * and 5m.
+     */
+    retryDelaysMs?: number[];
+    /** Accepts `http:` endpoint URLs; intended for test environments. */
+    allowInsecureUrls?: boolean;
+    /** Fetch implementation; defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export type ACPOrderEventType = 'order_create' | 'order_update';
+/**
+ * Delivers order lifecycle events to agents' webhook receivers (checkout
+ * RFC §2.3), signed with `Merchant-Signature: t=<unix>,v1=<hex>` over
+ * `timestamp + "." + body` (HMAC-SHA256). Failed deliveries are retried as
+ * the same event, with a fresh timestamp and signature, as in the UCP
+ * adapter.
+ */
+export declare class ACPOrderWebhooks {
+    private readonly options;
+    private readonly retryDelaysMs;
+    private readonly fetchImpl;
+    constructor(options: ACPWebhookOptions);
+    /** The endpoint for an agent's orders, if any. */
+    getEndpoint(agentId: string | undefined): ACPWebhookEndpoint | undefined;
+    /** Sends an event without waiting for it; the order is the full current state. */
+    deliver(endpoint: ACPWebhookEndpoint, type: ACPOrderEventType, order: object): void;
+    private attempt;
+    private isAllowedUrl;
+}
+/** `t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">`, as receivers verify. */
+export declare function signWebhookPayload(body: string, secret: string, timestamp?: number): string;

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

@@ -1,36 +1,38 @@
-import { type Cache, type Cart, type Checkout, type Inventory, type LanguageContext, type PaymentMethod, type Price, type Product, type ProductSearchResult, type RequestContext, type Result, type SearchIdentifier, type ShippingMethod } from '@reactionary/core';
-import { type ReactionaryFeedInventoryOptions, type ReactionaryFeedProcessingOptions } from '@reactionary/feeds';
+import { type Cache, type Cart, type Checkout, type Inventory, type Order, type MonetaryAmount, type PaymentMethod, type Product, type RequestContext, type Result, type ShippingMethod } from '@reactionary/core';
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ACPAffiliateAttribution, type ACPIntentTrace, type ACPAddress, type ACPAuthenticationMetadata, type ACPInterventionType, type ACPPaymentData } from './acp-schemas.js';
+import { type ACPWebhookOptions } from './acp-webhooks.js';
+import { type ACPPaymentHandler, type ACPPaymentHandlerOption } from './acp-payment-handlers.js';
 export interface ReactionaryACPClient {
     cart?: {
         createCart(payload: unknown): Promise<Result<Cart>>;
         add(payload: unknown): Promise<Result<Cart>>;
         getById(payload: unknown): Promise<Result<Cart>>;
         deleteCart?(payload: unknown): Promise<Result<void>>;
+        applyCouponCode?(payload: unknown): Promise<Result<Cart>>;
+        removeCouponCode?(payload: unknown): Promise<Result<Cart>>;
+        changeQuantity?(payload: unknown): Promise<Result<Cart>>;
+        remove?(payload: unknown): Promise<Result<Cart>>;
     };
     checkout?: {
         initiateCheckoutForCart(payload: unknown): Promise<Result<Checkout>>;
         getById(payload: unknown): Promise<Result<Checkout>>;
         setShippingAddress(payload: unknown): Promise<Result<Checkout>>;
         getAvailableShippingMethods(payload: unknown): Promise<Result<ShippingMethod[]>>;
-        getAvailablePaymentMethods(payload: unknown): Promise<Result<PaymentMethod[]>>;
+        getAvailablePaymentMethods?(payload: unknown): Promise<Result<PaymentMethod[]>>;
         setShippingInstruction(payload: unknown): Promise<Result<Checkout>>;
         addPaymentInstruction(payload: unknown): Promise<Result<Checkout>>;
         finalizeCheckout(payload: unknown): Promise<Result<Checkout>>;
     };
-    productSearch?: {
-        queryByTerm(payload: unknown): Promise<Result<ProductSearchResult>>;
-    };
     product?: {
         getBySKU(payload: unknown): Promise<Result<Product>>;
     };
-    price?: {
-        getListPrice(payload: unknown): Promise<Result<Price>>;
-        getCustomerPrice(payload: unknown): Promise<Result<Price>>;
-    };
     inventory?: {
         getBySKU(payload: unknown): Promise<Result<Inventory>>;
     };
+    order?: {
+        getById(payload: unknown): Promise<Result<Order>>;
+    };
 }
 export type ReactionaryACPClientFactory<TClient extends ReactionaryACPClient = ReactionaryACPClient> = (requestContext: RequestContext) => TClient;
 export interface ReactionaryACPServerOptions {
@@ -39,24 +41,219 @@ export interface ReactionaryACPServerOptions {
     basePath?: string;
     sessionCache?: Cache;
     sessionTtlSeconds?: number;
+    /**
+     * How long orders placed through ACP are remembered for order updates
+     * (`notifyOrderUpdated`). Defaults to 90 days.
+     */
+    orderTtlSeconds?: number;
+    /**
+     * How long Idempotency-Key responses are kept for replay. At least, and by
+     * default, 24 hours (checkout RFC §6.6).
+     */
+    idempotencyTtlSeconds?: number;
     checkoutSessionTtlSeconds?: number;
-    paymentProvider?: ACPPaymentProvider;
+    /**
+     * Authenticates agents on checkout endpoints, e.g. by their
+     * `Authorization: Bearer` token (see `createBearerTokenAuthenticator`) or a
+     * request signature. Returning undefined answers 401. Checkout sessions are
+     * visible only to the agent that created them. Unset, checkout endpoints
+     * are open — the server logs a warning, as ACP requires authentication.
+     */
+    authenticate?: (request: Request) => ACPAgent | undefined | Promise<ACPAgent | undefined>;
+    /**
+     * The buyer-facing order page, as a URL template with an `{orderId}`
+     * placeholder, e.g. `https://shop.example/account/orders/{orderId}`. Orders
+     * MUST carry a permalink; without this option it is left out and a warning
+     * is logged.
+     */
+    orderPermalinkUrl?: string;
+    /**
+     * Asks for 3D Secure authentication: returning metadata makes completion
+     * answer `authentication_required` until the agent completes again with an
+     * `authentication_result`, which is passed to the backend's payment
+     * integration as protocol data `acp_authentication_result`. Advertise
+     * `3ds` in `interventions.supported` for agents to know.
+     */
+    authentication?: ACPAuthenticationOptions;
+    /**
+     * Receives an order's affiliate attribution (first touch from session
+     * creation, last touch from completion) once the order exists, for the
+     * affiliate network. Attribution is write-only: never returned to agents
+     * or sent in webhooks.
+     */
+    onOrderAttribution?: (attribution: {
+        orderId: string;
+        checkoutSessionId: string;
+        agentId?: string;
+        firstTouch?: ACPAffiliateAttribution;
+        lastTouch?: ACPAffiliateAttribution;
+    }) => void | Promise<void>;
+    /**
+     * Marketing consent (marketing consent RFC): channels offered to the
+     * buyer on every session, and where the buyer's decisions go once the
+     * order exists. Unset, no consent is offered.
+     */
+    marketingConsent?: ACPMarketingConsentOptions;
+    /**
+     * Receives the agent's reason for canceling a session (intent traces),
+     * e.g. for conversion analytics. Traces are also kept on the session state
+     * but never returned to agents.
+     */
+    onIntentTrace?: (trace: ACPIntentTrace, context: {
+        checkoutSessionId: string;
+        agentId?: string;
+    }) => void | Promise<void>;
+    /**
+     * Classifies backend shipping methods into ACP fulfillment types, e.g.
+     * click-and-collect methods as `pickup` with their location. Methods are
+     * `shipping` by default, as core shipping methods carry no type.
+     */
+    classifyFulfillmentOption?: (method: ShippingMethod) => ACPFulfillmentClassification | undefined;
+    /**
+     * The URL where the buyer can continue the checkout on the merchant's
+     * site, as a template with a `{checkoutSessionId}` placeholder.
+     */
+    continueUrl?: string;
+    /**
+     * Serves the ACP MCP transport binding at `{basePath}/mcp`: the checkout
+     * tools over JSON-RPC 2.0 (Streamable HTTP), dispatched to the REST
+     * handlers with the connection's Authorization. Discovery then lists the
+     * `mcp` transport.
+     */
+    mcp?: boolean;
+    /**
+     * Sends signed order events (`order_create` on placement, `order_update`
+     * via `notifyOrderUpdated`) to the agents' webhook receivers, as ACP
+     * requires. Needs the client's `order.getById`. Unset, no webhooks are
+     * sent and a warning is logged.
+     */
+    webhooks?: ACPWebhookOptions;
+    /**
+     * Payment handlers advertised in `capabilities.payment.handlers`, e.g.
+     * `createTokenizedCardHandler(...)`. Each maps to the backend payment
+     * method its payments are placed with.
+     */
+    paymentHandlers?: ACPPaymentHandlerOption[];
+    /**
+     * Accepts raw card credentials (anything carrying a card number or CVC)
+     * and forwards them to the backend's payment integration, which persists
+     * payment data — putting the deployment in PCI DSS scope. Off by default:
+     * such completions are rejected, as handlers are expected to submit
+     * delegated tokens.
+     */
+    acceptRawCardCredentials?: boolean;
     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;
+    /**
+     * The interventions (e.g. 3DS) this seller can handle, and which it
+     * requires. Sessions report the intersection with what the agent declared.
+     * Defaults to none supported and none required.
+     */
+    interventions?: ACPInterventionOptions;
+    /**
+     * Whether orders need a fulfillment option. When the backend offers none
+     * for an address, the session cannot become payable. Defaults to true;
+     * disable it for stores selling only goods that need no shipping.
+     */
+    requireFulfillment?: boolean;
+    /**
+     * Checks line items against these fulfillment centers' combined stock,
+     * reporting `out_of_stock` per line item. Unset, stock is left to the
+     * backend.
+     */
+    inventory?: ACPInventoryOptions;
     /**
      * 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,
+     * webhook) before answering `complete_in_progress`. Defaults to 10s timeout,
      * polled every 1s; a timeout of 0 disables it.
      */
     paymentAuthorizationWait?: Partial<ACPPaymentAuthorizationWait>;
 }
+export interface ACPInventoryOptions {
+    fulfillmentCenterKeys: string[];
+}
+export interface ACPAuthenticationOptions {
+    getMetadata(context: {
+        checkoutSessionId: string;
+        handler: ACPPaymentHandler;
+        instrument: ACPPaymentData['instrument'];
+        amount: MonetaryAmount;
+    }): ACPAuthenticationMetadata | undefined | Promise<ACPAuthenticationMetadata | undefined>;
+}
+export interface ACPMarketingConsentChannel {
+    /** e.g. `email`, `sms`, `whatsapp`. */
+    channel: string;
+    /** What the buyer consents to receive. */
+    display_text: string;
+    privacy_policy_url: string;
+}
+export interface ACPMarketingConsentOptions {
+    channels: ACPMarketingConsentChannel[];
+    /**
+     * Whether the contact is already subscribed on the channel, so agents
+     * pre-check the box. Defaults to not subscribed.
+     */
+    isSubscribed?(contact: string, channel: string): boolean | Promise<boolean>;
+    /**
+     * Receives the buyer's decisions for offered channels, with the contact
+     * they apply to. Channels the agent did not surface are left out, which
+     * preserves their current state.
+     */
+    onConsents(consents: Array<{
+        channel: string;
+        opted_in: boolean;
+        contact: string;
+    }>, context: {
+        orderId: string;
+        checkoutSessionId: string;
+        agentId?: string;
+    }): void | Promise<void>;
+}
+/** An ACP fulfillment option type with its type-specific details. */
+export type ACPFulfillmentClassification = {
+    type: 'shipping';
+} | {
+    type: 'digital';
+} | {
+    type: 'pickup';
+    location: {
+        name: string;
+        address: ACPAddress;
+        phone?: string;
+        instructions?: string;
+    };
+    pickup_type?: 'in_store' | 'curbside' | 'locker';
+    ready_by?: string;
+    pickup_by?: string;
+} | {
+    type: 'local_delivery';
+    delivery_window?: {
+        start: string;
+        end: string;
+    };
+    service_area?: Record<string, unknown>;
+};
+/** An authenticated agent (platform) calling the checkout API. */
+export interface ACPAgent {
+    id: string;
+}
+/**
+ * Authenticates agents by `Authorization: Bearer <token>`, given each
+ * agent's token. Tokens are compared in constant time.
+ */
+export declare function createBearerTokenAuthenticator(tokensByAgentId: Record<string, string>): (request: Request) => ACPAgent | undefined;
+export interface ACPInterventionOptions {
+    supported: ACPInterventionType[];
+    required?: Array<'3ds' | 'biometric'>;
+    /** When required interventions apply. Defaults to `conditional`. */
+    enforcement?: 'always' | 'conditional' | 'optional';
+}
 export declare const DEFAULT_ACP_PLACEHOLDER_EMAIL = "pending@checkout.invalid";
 export interface ACPPaymentAuthorizationWait {
     timeoutMs: number;
@@ -64,11 +261,14 @@ export interface ACPPaymentAuthorizationWait {
 }
 export declare const DEFAULT_ACP_PAYMENT_AUTHORIZATION_WAIT: ACPPaymentAuthorizationWait;
 export interface ACPDiscoveryOptions {
-    apiVersion?: string;
-    supportedVersions?: string[];
     apiBaseUrl?: string;
     documentationUrl?: string;
     supportedCurrencies?: string[];
+    /**
+     * BCP 47 locales the backend can localize for. Advertised in discovery,
+     * and checkout requests are localized to the best match of their
+     * Accept-Language.
+     */
     supportedLocales?: string[];
 }
 export interface ACPDiscoveryResponse {
@@ -79,34 +279,30 @@ export interface ACPDiscoveryResponse {
         documentation_url?: string;
     };
     api_base_url: string;
-    transports: ['rest'];
+    transports: Array<'rest' | 'mcp'>;
     capabilities: {
-        services: Array<'checkout' | 'feeds'>;
+        services: Array<'checkout' | 'orders' | 'delegate_payment' | 'carts'>;
+        extensions?: ACPDiscoveryExtension[];
+        intervention_types?: ACPInterventionType[];
         supported_currencies?: string[];
         supported_locales?: string[];
     };
 }
-export type ACPPaymentProcessor = 'stripe' | 'adyen' | 'braintree';
-export interface ACPPaymentProvider {
-    provider: ACPPaymentProcessor;
-    supported_payment_methods: ['card'];
+/** An extension the seller supports, as listed in discovery. */
+export interface ACPDiscoveryExtension {
+    name: string;
+    spec?: string;
+    schema?: string;
 }
+/** The only ACP API version this adapter implements. */
+export declare const ACP_API_VERSION = "2026-04-17";
+/** A policy or support link shown with the checkout (2026-04-17 Link). */
 export interface ACPLink {
-    type: 'terms_of_use' | 'privacy_policy' | 'seller_shop_policies';
+    type: 'terms_of_use' | 'privacy_policy' | 'return_policy' | 'shipping_policy' | 'contact_us' | 'about_us' | 'faq' | 'support';
+    /** Display text for the link. */
+    title?: string;
     url: string;
 }
-export interface ACPProductFeedOptions extends ReactionaryFeedInventoryOptions, ReactionaryFeedProcessingOptions {
-    feeds: Record<string, ACPProductFeedDefinition>;
-}
-export interface ACPProductFeedDefinition {
-    languageContext: LanguageContext;
-    search: SearchIdentifier;
-    pageSize?: number;
-    maxPages?: number;
-    productUrlBase?: string;
-    fulfillmentCenterKeys?: string[];
-    fulfillmentCenterKey?: string;
-}
 export interface ReactionaryACPHttpHandler {
     fetch(request: Request): Promise<Response>;
     close(): Promise<void>;
@@ -117,36 +313,81 @@ export declare class ReactionaryACPServer<TClient extends ReactionaryACPClient =
     private readonly options;
     private readonly sessionStore;
     private readonly checkoutSessionStore;
+    private readonly idempotency;
+    private readonly webhooks;
+    private readonly supportsDiscounts;
+    private readonly mcp;
     constructor(clientFactory: ReactionaryACPClientFactory<TClient>, options?: ReactionaryACPServerOptions);
     fetch(request: Request): Promise<Response>;
     private handleFetch;
+    /**
+     * Checkout endpoints require an authenticated agent (checkout RFC §3.1),
+     * and a checkout session is visible only to the agent that created it, so
+     * another agent's session is reported as missing. Discovery and the
+     * readiness document stay public.
+     */
+    private authenticate;
     /**
      * 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;
+    /**
+     * The best supported locale for the request's Accept-Language: an exact
+     * tag, else one of the same language. Only locales advertised in
+     * `discovery.supportedLocales` are used, as backends may not localize
+     * others.
+     */
+    private resolveLocale;
+    /**
+     * The currency a checkout session is priced in: the one requested on its
+     * creation, which later requests for the session keep using.
+     */
+    private resolveCheckoutCurrency;
+    /**
+     * Sends an `order_update` event with the order's current state, e.g. when
+     * the OMS ships or cancels it. Returns false for orders not placed through
+     * an ACP checkout session, or when webhooks are not configured.
+     */
+    notifyOrderUpdated(orderId: string): Promise<boolean>;
     getHandler(): ReactionaryACPHttpHandler;
     toNodeHandler(): ReactionaryACPNodeRequestHandler;
     close(): Promise<void>;
     private createRequestContext;
     private handleRequest;
+    /**
+     * The cart capability (cart RFC): pre-checkout baskets over a backend
+     * cart. Carts have no status — they exist, or answer 404 once canceled or
+     * expired — and no payment or negotiation, which belong to checkout.
+     */
+    private handleCartRequest;
+    private getCartExpiry;
+    /** A cart's authoritative state; totals are estimates without an address. */
+    private toACPCart;
     private getDiscoveryDocument;
+    /** The extensions the server implements; extension PRs add theirs here. */
+    private getDiscoveryExtensions;
     private getReadinessDocument;
-    private getProductFeed;
-    private getRequestedProductFeed;
-    private getProductFeedDefinition;
     private handlePost;
     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`;
+     * payment the PSP has not authorized yet leaves the session
+     * `complete_in_progress`, without an order yet;
      * a repeated complete retries finalization.
      */
     private completeCheckoutSession;
     private cancelCheckoutSession;
+    /**
+     * Gives the session's cart exactly the requested items (line items are a
+     * full replacement), updating it in place where the backend supports it.
+     * Otherwise a new cart replaces it and the old one is deleted, if possible.
+     * Returns the cart key.
+     */
+    private replaceCartItems;
     private createCartForItems;
     private getRequiredCheckoutSessionState;
     private placeCheckout;
@@ -158,6 +399,69 @@ export declare class ReactionaryACPServer<TClient extends ReactionaryACPClient =
      */
     private priceSession;
     private toACPCheckoutSession;
+    private classifyFulfillmentOption;
+    /**
+     * Whether the discount extension is active for a session: the backend can
+     * apply coupons, and the agent declared the extension.
+     */
+    private isDiscountExtensionActive;
+    /** Applies submitted discount codes, when the extension is active. */
+    private applyRequestedDiscounts;
+    /**
+     * 3D Secure (checkout RFC §4.4): when the authentication hook asks for it,
+     * the first completion answers `authentication_required` with the
+     * metadata; completing such a session without `authentication_result` is
+     * a 4XX `requires_3ds`. Failed or refused authentications are not
+     * authorized. Returns a response when completion must stop here.
+     */
+    private checkAuthentication;
+    /**
+     * Records an order placed through a session once, and announces it to the
+     * creating agent's webhook receiver.
+     */
+    private recordOrder;
+    /**
+     * Reports the order's affiliate attribution once it exists: first touch
+     * from the session's creation, last touch from its completion. A failing
+     * hook never blocks the checkout.
+     */
+    private reportAttribution;
+    /**
+     * Passes the buyer's consent decisions on, once the order exists. Only
+     * offered channels with a resolvable contact count: email uses the buyer's
+     * email, falling back to the fulfillment email; sms and whatsapp the phone
+     * likewise (marketing consent RFC §3.5). Omitted channels are not consent.
+     */
+    private reportMarketingConsents;
+    /** The offered marketing channels, with the buyer's subscription state. */
+    private getMarketingConsentOptions;
+    private sendOrderEvent;
+    /** The full current order (webhooks carry the whole order, not deltas). */
+    private toACPOrder;
+    /**
+     * The advertised handler a completion pays with. Sellers MUST check the
+     * handler is one they declared (sellers guide, "Complete a checkout
+     * session"), and raw card numbers are refused unless explicitly accepted,
+     * so they never reach the backend's persisted payment data.
+     */
+    private resolvePaymentHandler;
+    /**
+     * The seller's capabilities for a session: interventions are the
+     * intersection of what the agent declared and what the seller supports,
+     * plus the seller's requirements (capability negotiation RFC §4.5.1).
+     */
+    private getNegotiatedCapabilities;
+    /**
+     * An out_of_stock error per line item requesting more than the configured
+     * fulfillment centers hold (as in the UCP adapter). Back-ordered and
+     * pre-ordered items are always purchasable; without configured centers,
+     * stock is left to the backend.
+     */
+    private getStockMessages;
+    /**
+     * Required interventions the agent cannot perform block the session when
+     * they always apply (checkout RFC §5, intervention_required).
+     */
+    private getInterventionMessages;
     private getPlacedView;
-    private getPaymentProvider;
 }