@reactionary/ucp 0.10.34 → 0.10.36

package/src/lib/reactionary-ucp-mapping.d.ts

@@ -0,0 +1,41 @@
+import type { Address, Cart, Checkout, CostBreakDown, MonetaryAmount, Order } from '@reactionary/core';
+import type { components } from './ucp-shopping.openapi.js';
+import type { UCPPaymentHandlers } from './reactionary-ucp-common.js';
+export declare const UCP_VERSION = "2026-08-25";
+export type UCPCheckout = components['schemas']['checkout'];
+export type UCPLineItem = components['schemas']['line_item'];
+export type UCPMessage = components['schemas']['message'];
+export type UCPTotal = components['schemas']['total'];
+export type UCPPostalAddress = components['schemas']['postal_address'];
+export type UCPSelectedPaymentInstrument = NonNullable<NonNullable<UCPCheckout['payment']>['instruments']>[number];
+export declare function getSelectedPaymentInstrument(checkout: Pick<UCPCheckout, 'payment'>): UCPSelectedPaymentInstrument | undefined;
+/**
+ * The buyer-facing order page under the merchant's site. The spec requires a
+ * valid URL; without a configured merchant URL there is nothing to link to,
+ * and the empty string is left for the caller's schema to flag.
+ */
+export declare function toOrderPermalinkUrl(merchantUrl: string | undefined, orderId: string): string;
+export declare function toReactionaryAddress(address: UCPPostalAddress): Omit<Address, 'identifier'>;
+export type UCPPricedItem = Pick<Cart['items'][number] | Checkout['items'][number] | Order['items'][number], 'identifier' | 'variant' | 'quantity' | 'price'>;
+/** A line's undiscounted amount (unit price × quantity), in minor units. */
+export declare function getLineSubtotal(lineItem: UCPPricedItem): number;
+/** The discount allocated to a line, in minor units. */
+export declare function getLineDiscount(lineItem: UCPPricedItem): number;
+export declare function toUcpCartLineItem(lineItem: UCPPricedItem): UCPLineItem;
+/**
+ * Order-level totals. With line items, the subtotal is their undiscounted
+ * sum, discounts allocated to lines are reported as `items_discount` and the
+ * remainder of the total discount as order-level `discount` (discount
+ * extension, "Impact on Line Items and Totals").
+ */
+export declare function toUcpCostTotals(price: CostBreakDown, items?: UCPPricedItem[]): UCPTotal[];
+export declare function toUcpTotals(amount: MonetaryAmount): UCPTotal[];
+export declare function getMoneyValue(amount: MonetaryAmount): number;
+export declare function getMoneyCurrency(amount: MonetaryAmount): string;
+export declare function createUcpSuccessMetadata(): components['schemas']['ucp_$defs-base'] & {
+    status: 'success';
+};
+export declare function createUcpCheckoutSuccessMetadata(paymentHandlers: UCPPaymentHandlers): components['schemas']['response_checkout_schema'];
+export declare function createUcpErrorMessage(code: string, message: string, path?: string): UCPMessage;
+export declare function createUCPError<TResponse>(code: string, message: string, path?: string): TResponse;
+export declare function createUcpWarning(code: string, content: string, path: string): UCPMessage;

package/src/lib/reactionary-ucp-order.d.ts

@@ -0,0 +1,77 @@
+import * as z from 'zod';
+import type { ReactionaryUCPClient } from './reactionary-ucp-common.js';
+import { type ReactionaryUCPSessionStore } from './reactionary-ucp-session-store.js';
+import type { ReactionaryUCPWebhooks } from './reactionary-ucp-webhooks.js';
+import type { components } from './ucp-shopping.openapi.js';
+type UCPErrorResponse = components['schemas']['error_response'];
+type UCPOrder = Omit<components['schemas']['order'], '$defs'>;
+export type UCPOrderResponse = UCPOrder | UCPErrorResponse;
+/**
+ * The parts of a PUT /orders/{id} body applied by testOrderUpdates: the
+ * fulfillment event log and the adjustments, each replaced as a whole.
+ */
+export declare const UCPOrderUpdateSchema: z.ZodObject<{
+    fulfillment: z.ZodOptional<z.ZodObject<{
+        events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            occurred_at: z.ZodISODateTime;
+            type: z.ZodString;
+            line_items: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                quantity: z.ZodInt;
+            }, z.core.$strip>>;
+            tracking_number: z.ZodOptional<z.ZodString>;
+            tracking_url: z.ZodOptional<z.ZodURL>;
+            carrier: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    adjustments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        occurred_at: z.ZodISODateTime;
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            failed: "failed";
+        }>;
+        line_items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            quantity: z.ZodInt;
+        }, z.core.$strip>>>;
+        totals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            amount: z.ZodInt;
+        }, z.core.$loose>>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type UCPOrderUpdate = z.infer<typeof UCPOrderUpdateSchema>;
+export interface UCPOrderContext {
+    client: ReactionaryUCPClient;
+    store: ReactionaryUCPSessionStore;
+    merchantUrl?: string;
+    webhooks?: ReactionaryUCPWebhooks;
+}
+/**
+ * The backend scopes orders to the session's identity (the session that
+ * placed the order, or a linked identity), so an order this session may not
+ * see is not found rather than forbidden.
+ */
+export declare function getOrder(context: UCPOrderContext, orderId: string): Promise<UCPOrderResponse>;
+/**
+ * Test-only: records fulfillment events and adjustments on an order placed
+ * through a UCP checkout session, as a business would post them.
+ */
+export declare function updateOrder(context: UCPOrderContext, orderId: string, update: UCPOrderUpdate): Promise<UCPOrderResponse>;
+/**
+ * Test-only: records a shipment of every line item, as a business would
+ * when the order ships, and notifies the platform.
+ */
+export declare function simulateShipping(context: UCPOrderContext, orderId: string): Promise<UCPOrderResponse>;
+/**
+ * Sends the "Order created" event for a newly placed order, resolving the
+ * platform's webhook URL from its profile.
+ */
+export declare function notifyOrderPlaced(context: UCPOrderContext, orderId: string): Promise<void>;
+export {};

package/src/lib/reactionary-ucp-rest.d.ts

@@ -1,6 +1,32 @@
+import type { Identity } from '@reactionary/core';
 import type { ReactionaryUCPClient, UCPPaymentHandlers } from './reactionary-ucp-common.js';
+import type { ReactionaryUCPWebhooks } from './reactionary-ucp-webhooks.js';
 import type { ReactionaryUCPSessionStore } from './reactionary-ucp-session-store.js';
-export declare function handleRestRequest(request: Request, client: ReactionaryUCPClient, path: string, sessionId: string, sessionStore: ReactionaryUCPSessionStore, paymentHandlers?: UCPPaymentHandlers): Promise<Response | undefined>;
+import { type UCPInventoryOptions, type UCPPaymentAuthorizationWait, type UCPTestPaymentHandler } from './reactionary-ucp-checkout-session.js';
+export declare function handleRestRequest(request: Request, client: ReactionaryUCPClient, path: string, sessionId: string, sessionStore: ReactionaryUCPSessionStore, options: UCPRestOptions): Promise<Response | undefined>;
+export interface UCPRestOptions {
+    paymentHandlers: UCPPaymentHandlers;
+    placeholderEmail: string;
+    paymentAuthorizationWait: UCPPaymentAuthorizationWait;
+    identity: Identity;
+    /** The merchant's site URL, used to build order permalinks. */
+    merchantUrl?: string;
+    /** See ReactionaryUCPServerOptions.anonymousOrderEmail. */
+    anonymousOrderEmail?: string;
+    /** See ReactionaryUCPServerOptions.testPaymentHandlers. */
+    testPaymentHandlers?: UCPTestPaymentHandler[];
+    /** See ReactionaryUCPServerOptions.acceptRawCardCredentials. */
+    acceptRawCardCredentials?: boolean;
+    /** See ReactionaryUCPServerOptions.inventory. */
+    inventory?: UCPInventoryOptions;
+    /** See ReactionaryUCPServerOptions.testOrderUpdates. */
+    testOrderUpdates?: boolean;
+    /** See ReactionaryUCPServerOptions.testSimulationSecret. */
+    testSimulationSecret?: string;
+    webhooks?: ReactionaryUCPWebhooks;
+    /** The requesting platform's UCP-Agent profile URL. */
+    agentProfile?: string;
+}
 export declare class UCPHttpError extends Error {
     readonly status: number;
     readonly body: unknown;

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

@@ -5,6 +5,7 @@ export declare class ReactionaryUCPServer<TClient extends ReactionaryUCPClient =
     private readonly clientFactory;
     private readonly options;
     private readonly sessionStore;
+    private readonly webhooks?;
     readonly identity?: ReactionaryUCPIdentity;
     constructor(clientFactory: ReactionaryUCPClientFactory<TClient>, options?: ReactionaryUCPServerOptions);
     fetch(request: Request): Promise<Response>;
@@ -12,6 +13,19 @@ export declare class ReactionaryUCPServer<TClient extends ReactionaryUCPClient =
     getHandler(): ReactionaryUCPHttpHandler;
     toNodeHandler(): ReactionaryUCPNodeRequestHandler;
     close(): Promise<void>;
+    /**
+     * Requests addressing a cart or checkout session resume the session that
+     * created it: agents rarely echo the UCP session header, but backends scope
+     * carts to that session's (anonymous) identity.
+     */
+    private resolveSessionId;
+    /**
+     * Orders resume the session that placed them only for the platform that
+     * completed the checkout (order capability: the business verifies the
+     * requesting platform created the checkout). Any other request runs in its
+     * own session, where the backend does not find the order.
+     */
+    private resolveOrderSessionId;
     private createRequestContext;
     private handleRequest;
 }

package/src/lib/reactionary-ucp-session-store.d.ts

@@ -1,5 +1,184 @@
 import { type Cache, type Session } from '@reactionary/core';
 import * as z from 'zod';
+/**
+ * Buyer consent per purpose (buyer consent extension): the spec's purpose
+ * map ({ granted, source, segments }), or the flat booleans of earlier
+ * versions still used by the conformance SDK (e.g. { marketing: true }).
+ */
+export declare const UCPBuyerConsentSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    granted: z.ZodBoolean;
+    source: z.ZodEnum<{
+        business: "business";
+        platform: "platform";
+    }>;
+    segments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        granted: z.ZodBoolean;
+        source: z.ZodEnum<{
+            business: "business";
+            platform: "platform";
+        }>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>]>>;
+export declare const UCPCheckoutSessionStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    cartId: z.ZodString;
+    status: z.ZodEnum<{
+        canceled: "canceled";
+        complete_in_progress: "complete_in_progress";
+        completed: "completed";
+        open: "open";
+    }>;
+    buyer: z.ZodOptional<z.ZodObject<{
+        first_name: z.ZodOptional<z.ZodString>;
+        last_name: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        phone_number: z.ZodOptional<z.ZodString>;
+        /** Round-tripped only; not persisted beyond the session yet. */
+        consent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            granted: z.ZodBoolean;
+            source: z.ZodEnum<{
+                business: "business";
+                platform: "platform";
+            }>;
+            segments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                granted: z.ZodBoolean;
+                source: z.ZodEnum<{
+                    business: "business";
+                    platform: "platform";
+                }>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>]>>>;
+    }, z.core.$loose>>;
+    billingAddress: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        first_name: z.ZodOptional<z.ZodString>;
+        last_name: z.ZodOptional<z.ZodString>;
+        street_address: z.ZodOptional<z.ZodString>;
+        extended_address: z.ZodOptional<z.ZodString>;
+        address_locality: z.ZodOptional<z.ZodString>;
+        address_region: z.ZodOptional<z.ZodString>;
+        address_country: z.ZodOptional<z.ZodString>;
+        postal_code: z.ZodOptional<z.ZodString>;
+        phone_number: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    destination: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        first_name: z.ZodOptional<z.ZodString>;
+        last_name: z.ZodOptional<z.ZodString>;
+        street_address: z.ZodOptional<z.ZodString>;
+        extended_address: z.ZodOptional<z.ZodString>;
+        address_locality: z.ZodOptional<z.ZodString>;
+        address_region: z.ZodOptional<z.ZodString>;
+        address_country: z.ZodOptional<z.ZodString>;
+        postal_code: z.ZodOptional<z.ZodString>;
+        phone_number: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    selectedOptionId: z.ZodOptional<z.ZodString>;
+    /** The selected fulfillment option's title, as last shown to the agent. */
+    selectedOptionTitle: z.ZodOptional<z.ZodString>;
+    instrument: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        handler_id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$loose>>;
+    lastTotal: z.ZodOptional<z.ZodNumber>;
+    finalCheckoutId: z.ZodOptional<z.ZodString>;
+    orderId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type UCPCheckoutSessionState = z.infer<typeof UCPCheckoutSessionStateSchema>;
+export declare const UCPFulfillmentEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    occurred_at: z.ZodISODateTime;
+    type: z.ZodString;
+    line_items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        quantity: z.ZodInt;
+    }, z.core.$strip>>;
+    tracking_number: z.ZodOptional<z.ZodString>;
+    tracking_url: z.ZodOptional<z.ZodURL>;
+    carrier: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const UCPAdjustmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    occurred_at: z.ZodISODateTime;
+    status: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        failed: "failed";
+    }>;
+    line_items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        quantity: z.ZodInt;
+    }, z.core.$strip>>>;
+    totals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        amount: z.ZodInt;
+    }, z.core.$loose>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * What UCP knows about an order placed through a checkout session: its
+ * origin, the fulfillment the agent selected, and (with testOrderUpdates)
+ * the events and adjustments posted to it.
+ */
+export declare const UCPOrderStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    checkoutSessionId: z.ZodString;
+    /** The UCP session that completed the checkout and owns the order. */
+    sessionId: z.ZodString;
+    /** The UCP-Agent profile of the platform that completed the checkout. */
+    agentProfile: z.ZodOptional<z.ZodString>;
+    /** The order webhook URL from the platform's profile, resolved at placement. */
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    destination: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        first_name: z.ZodOptional<z.ZodString>;
+        last_name: z.ZodOptional<z.ZodString>;
+        street_address: z.ZodOptional<z.ZodString>;
+        extended_address: z.ZodOptional<z.ZodString>;
+        address_locality: z.ZodOptional<z.ZodString>;
+        address_region: z.ZodOptional<z.ZodString>;
+        address_country: z.ZodOptional<z.ZodString>;
+        postal_code: z.ZodOptional<z.ZodString>;
+        phone_number: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    fulfillmentTitle: z.ZodOptional<z.ZodString>;
+    events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        occurred_at: z.ZodISODateTime;
+        type: z.ZodString;
+        line_items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            quantity: z.ZodInt;
+        }, z.core.$strip>>;
+        tracking_number: z.ZodOptional<z.ZodString>;
+        tracking_url: z.ZodOptional<z.ZodURL>;
+        carrier: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    adjustments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        occurred_at: z.ZodISODateTime;
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            failed: "failed";
+        }>;
+        line_items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            quantity: z.ZodInt;
+        }, z.core.$strip>>>;
+        totals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            amount: z.ZodInt;
+        }, z.core.$loose>>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type UCPOrderState = z.output<typeof UCPOrderStateSchema>;
 declare const UCPIdempotencyRecordSchema: z.ZodObject<{
     action: z.ZodString;
     fingerprint: z.ZodOptional<z.ZodString>;
@@ -15,6 +194,18 @@ export declare class ReactionaryUCPSessionStore {
     put(sessionId: string, session: Session): Promise<void>;
     getIdempotencyRecord(sessionId: string, idempotencyKey: string): Promise<UCPIdempotencyRecord | undefined>;
     putIdempotencyRecord(sessionId: string, idempotencyKey: string, record: UCPIdempotencyRecord): Promise<void>;
+    getCheckoutSession(checkoutSessionId: string): Promise<UCPCheckoutSessionState | undefined>;
+    putCheckoutSession(state: UCPCheckoutSessionState): Promise<void>;
+    getOrder(orderId: string): Promise<UCPOrderState | undefined>;
+    putOrder(state: UCPOrderState): Promise<void>;
+    /**
+     * Binds a created resource (cart or checkout session) to the UCP session
+     * that owns its backend state. Agents address resources by id and rarely
+     * echo the UCP session header, yet backends scope carts to the session's
+     * (anonymous) identity, so later requests must resume the owning session.
+     */
+    bindResource(resourceId: string, sessionId: string): Promise<void>;
+    getResourceSession(resourceId: string): Promise<string | undefined>;
     private getCacheKey;
     private getDependencyId;
     private getIdempotencyCacheKey;

package/src/lib/reactionary-ucp-signing.d.ts

@@ -0,0 +1,27 @@
+import { type JsonWebKey } from 'node:crypto';
+/**
+ * A business signing key for UCP message signatures (RFC 9421). Its public
+ * part must be published under `keys` in the business profile; see
+ * toPublicSigningJwk.
+ */
+export interface UCPSigningKey {
+    /** The key id, referenced as `keyid` in signatures and `kid` in the profile. */
+    kid: string;
+    /** The private key as a JWK: EC P-256 (ES256), EC P-384 (ES384) or OKP Ed25519. */
+    privateKeyJwk: JsonWebKey;
+}
+export interface UCPSignableRequest {
+    method: string;
+    url: string;
+    /** Request headers by lower-case name; signed when listed as components. */
+    headers: Record<string, string>;
+    body: string;
+}
+/** The public JWK to publish in the business profile's `keys` for a signing key. */
+export declare function toPublicSigningJwk(key: UCPSigningKey): Record<string, string>;
+/**
+ * Signs a REST request per the UCP REST binding of RFC 9421: computes the
+ * Content-Digest (RFC 9530) of the raw body and signs the required
+ * components, returning the headers to add.
+ */
+export declare function signRestRequest(request: UCPSignableRequest, key: UCPSigningKey, created?: number): Record<string, string>;

package/src/lib/reactionary-ucp-webhooks.d.ts

@@ -0,0 +1,48 @@
+import { type UCPSigningKey } from './reactionary-ucp-signing.js';
+export interface ReactionaryUCPWebhookOptions {
+    /**
+     * Signs deliveries; the order capability requires signed webhook payloads.
+     * Without it deliveries are sent unsigned, and a warning is logged.
+     */
+    signingKey?: UCPSigningKey;
+    /**
+     * 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:` agent profile and webhook URLs. Only https URLs are
+     * fetched otherwise. Intended for conformance and test environments.
+     */
+    allowInsecureUrls?: boolean;
+    /** Fetch implementation; defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Delivers order events to the webhook URL a platform declares in its
+ * profile (order capability `config.webhook_url`), following Standard
+ * Webhooks headers and the UCP REST signing binding.
+ */
+export declare class ReactionaryUCPWebhooks {
+    private readonly options;
+    /** The business profile URL, sent as the deliveries' UCP-Agent. */
+    private readonly businessProfileUrl;
+    private readonly profileCache;
+    private readonly retryDelaysMs;
+    private readonly fetchImpl;
+    private warnedUnsigned;
+    constructor(options: ReactionaryUCPWebhookOptions, 
+    /** The business profile URL, sent as the deliveries' UCP-Agent. */
+    businessProfileUrl: string);
+    /** The order webhook URL declared in a platform's profile, if any. */
+    resolveOrderWebhookUrl(agentProfileUrl: string): Promise<string | undefined>;
+    /**
+     * Sends an order event without waiting for it. Failed attempts are retried
+     * as the same event: same Webhook-Id, Webhook-Timestamp and body.
+     */
+    deliver(webhookUrl: string, order: object): void;
+    private attempt;
+    private fetchOrderWebhookUrl;
+    private isAllowedUrl;
+}