@reactionary/ucp 0.10.35 → 0.10.36

package/lib/reactionary-ucp-session-store.js

@@ -2,6 +2,97 @@ import { SessionSchema } from "@reactionary/core";
 import * as z from "zod";
 const SESSION_CACHE_KEY_PREFIX = "reactionary:ucp:session";
 const IDEMPOTENCY_CACHE_KEY_PREFIX = "reactionary:ucp:idempotency";
+const CHECKOUT_SESSION_CACHE_KEY_PREFIX = "reactionary:ucp:checkout-session";
+const RESOURCE_SESSION_CACHE_KEY_PREFIX = "reactionary:ucp:resource-session";
+const ORDER_CACHE_KEY_PREFIX = "reactionary:ucp:order";
+const UCPPostalAddressStateSchema = z.looseObject({
+  id: z.string().optional(),
+  first_name: z.string().optional(),
+  last_name: z.string().optional(),
+  street_address: z.string().optional(),
+  extended_address: z.string().optional(),
+  address_locality: z.string().optional(),
+  address_region: z.string().optional(),
+  address_country: z.string().optional(),
+  postal_code: z.string().optional(),
+  phone_number: z.string().optional()
+});
+const UCPConsentSourceSchema = z.enum(["business", "platform"]);
+const UCPBuyerConsentSchema = z.record(z.string(), z.union([
+  z.boolean(),
+  z.looseObject({
+    granted: z.boolean(),
+    source: UCPConsentSourceSchema,
+    segments: z.record(z.string(), z.looseObject({
+      granted: z.boolean(),
+      source: UCPConsentSourceSchema
+    })).optional()
+  })
+]));
+const UCPCheckoutSessionStateSchema = z.looseObject({
+  id: z.string(),
+  cartId: z.string(),
+  status: z.enum(["open", "complete_in_progress", "completed", "canceled"]),
+  buyer: z.looseObject({
+    first_name: z.string().optional(),
+    last_name: z.string().optional(),
+    email: z.string().optional(),
+    phone_number: z.string().optional(),
+    /** Round-tripped only; not persisted beyond the session yet. */
+    consent: UCPBuyerConsentSchema.optional()
+  }).optional(),
+  billingAddress: UCPPostalAddressStateSchema.optional(),
+  destination: UCPPostalAddressStateSchema.optional(),
+  selectedOptionId: z.string().optional(),
+  /** The selected fulfillment option's title, as last shown to the agent. */
+  selectedOptionTitle: z.string().optional(),
+  instrument: z.looseObject({
+    id: z.string(),
+    handler_id: z.string(),
+    type: z.string()
+  }).optional(),
+  lastTotal: z.number().optional(),
+  finalCheckoutId: z.string().optional(),
+  orderId: z.string().optional()
+});
+const UCPOrderLineItemReferenceSchema = z.object({
+  id: z.string(),
+  quantity: z.int()
+});
+const UCPFulfillmentEventSchema = z.looseObject({
+  id: z.string(),
+  occurred_at: z.iso.datetime({ offset: true }),
+  type: z.string(),
+  line_items: z.array(UCPOrderLineItemReferenceSchema.extend({ quantity: z.int().min(1) })),
+  tracking_number: z.string().optional(),
+  tracking_url: z.url().optional(),
+  carrier: z.string().optional(),
+  description: z.string().optional()
+});
+const UCPAdjustmentSchema = z.looseObject({
+  id: z.string(),
+  type: z.string(),
+  occurred_at: z.iso.datetime({ offset: true }),
+  status: z.enum(["pending", "completed", "failed"]),
+  line_items: z.array(UCPOrderLineItemReferenceSchema).optional(),
+  totals: z.array(z.looseObject({ type: z.string(), amount: z.int() })).optional(),
+  description: z.string().optional()
+});
+const UCPOrderStateSchema = z.looseObject({
+  id: z.string(),
+  checkoutSessionId: z.string(),
+  /** The UCP session that completed the checkout and owns the order. */
+  sessionId: z.string(),
+  /** The UCP-Agent profile of the platform that completed the checkout. */
+  agentProfile: z.string().optional(),
+  /** The order webhook URL from the platform's profile, resolved at placement. */
+  webhookUrl: z.string().optional(),
+  destination: UCPPostalAddressStateSchema.optional(),
+  fulfillmentTitle: z.string().optional(),
+  events: z.array(UCPFulfillmentEventSchema).default([]),
+  adjustments: z.array(UCPAdjustmentSchema).default([])
+});
+const UCPResourceSessionSchema = z.looseObject({ sessionId: z.string() });
 const UCPActionResponseSchema = z.looseObject({});
 const UCPIdempotencyRecordSchema = z.looseObject({
   action: z.string(),
@@ -45,6 +136,54 @@ class ReactionaryUCPSessionStore {
       }
     );
   }
+  async getCheckoutSession(checkoutSessionId) {
+    return await this.cache.get(
+      `${CHECKOUT_SESSION_CACHE_KEY_PREFIX}:${checkoutSessionId}`,
+      UCPCheckoutSessionStateSchema
+    ) ?? void 0;
+  }
+  async putCheckoutSession(state) {
+    const key = `${CHECKOUT_SESSION_CACHE_KEY_PREFIX}:${state.id}`;
+    await this.cache.invalidate([key]);
+    await this.cache.put(key, state, {
+      ttlSeconds: this.ttlSeconds,
+      dependencyIds: [key]
+    });
+  }
+  async getOrder(orderId) {
+    return await this.cache.get(
+      `${ORDER_CACHE_KEY_PREFIX}:${orderId}`,
+      UCPOrderStateSchema
+    ) ?? void 0;
+  }
+  async putOrder(state) {
+    const key = `${ORDER_CACHE_KEY_PREFIX}:${state.id}`;
+    await this.cache.invalidate([key]);
+    await this.cache.put(key, state, {
+      ttlSeconds: this.ttlSeconds,
+      dependencyIds: [key]
+    });
+  }
+  /**
+   * 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.
+   */
+  async bindResource(resourceId, sessionId) {
+    await this.cache.put(
+      `${RESOURCE_SESSION_CACHE_KEY_PREFIX}:${resourceId}`,
+      { sessionId },
+      { ttlSeconds: this.ttlSeconds, dependencyIds: [] }
+    );
+  }
+  async getResourceSession(resourceId) {
+    const binding = await this.cache.get(
+      `${RESOURCE_SESSION_CACHE_KEY_PREFIX}:${resourceId}`,
+      UCPResourceSessionSchema
+    );
+    return binding?.sessionId;
+  }
   getCacheKey(sessionId) {
     return `${SESSION_CACHE_KEY_PREFIX}:${sessionId}`;
   }
@@ -59,5 +198,10 @@ class ReactionaryUCPSessionStore {
   }
 }
 export {
-  ReactionaryUCPSessionStore
+  ReactionaryUCPSessionStore,
+  UCPAdjustmentSchema,
+  UCPBuyerConsentSchema,
+  UCPCheckoutSessionStateSchema,
+  UCPFulfillmentEventSchema,
+  UCPOrderStateSchema
 };

package/lib/reactionary-ucp-signing.js

@@ -0,0 +1,72 @@
+import { createHash, createPrivateKey, sign } from "node:crypto";
+function toPublicSigningJwk(key) {
+  const { kty, crv, x, y } = key.privateKeyJwk;
+  return {
+    kid: key.kid,
+    ...kty ? { kty } : {},
+    ...crv ? { crv } : {},
+    ...x ? { x } : {},
+    ...y ? { y } : {},
+    use: "sig",
+    alg: getAlgorithm(key.privateKeyJwk).alg
+  };
+}
+function signRestRequest(request, key, created = Math.floor(Date.now() / 1e3)) {
+  const url = new URL(request.url);
+  const headers = {
+    ...request.headers,
+    "content-digest": `sha-256=:${createHash("sha256").update(request.body).digest("base64")}:`
+  };
+  const components = [
+    "@method",
+    "@authority",
+    "@path",
+    ...url.search ? ["@query"] : [],
+    ...["ucp-agent", "idempotency-key", "content-digest", "content-type"].filter((name) => headers[name] !== void 0)
+  ];
+  const signatureParams = `(${components.map((name) => `"${name}"`).join(" ")});created=${created};keyid="${key.kid}"`;
+  const signatureBase = [
+    ...components.map((name) => `"${name}": ${getComponentValue(name, request.method, url, headers)}`),
+    `"@signature-params": ${signatureParams}`
+  ].join("\n");
+  return {
+    "content-digest": headers["content-digest"],
+    "signature-input": `sig1=${signatureParams}`,
+    "signature": `sig1=:${createSignature(signatureBase, key).toString("base64")}:`
+  };
+}
+function getComponentValue(name, method, url, headers) {
+  switch (name) {
+    case "@method":
+      return method.toUpperCase();
+    case "@authority":
+      return url.host.toLowerCase();
+    case "@path":
+      return url.pathname;
+    case "@query":
+      return url.search;
+    default:
+      return (headers[name] ?? "").trim();
+  }
+}
+function createSignature(signatureBase, key) {
+  const privateKey = createPrivateKey({ key: key.privateKeyJwk, format: "jwk" });
+  const { hash } = getAlgorithm(key.privateKeyJwk);
+  return hash ? sign(hash, Buffer.from(signatureBase), { key: privateKey, dsaEncoding: "ieee-p1363" }) : sign(null, Buffer.from(signatureBase), privateKey);
+}
+function getAlgorithm(jwk) {
+  if (jwk.kty === "EC" && jwk.crv === "P-256") {
+    return { alg: "ES256", hash: "sha256" };
+  }
+  if (jwk.kty === "EC" && jwk.crv === "P-384") {
+    return { alg: "ES384", hash: "sha384" };
+  }
+  if (jwk.kty === "OKP" && jwk.crv === "Ed25519") {
+    return { alg: "EdDSA" };
+  }
+  throw new Error(`Unsupported UCP signing key: kty=${jwk.kty ?? "?"} crv=${jwk.crv ?? "?"}`);
+}
+export {
+  signRestRequest,
+  toPublicSigningJwk
+};

package/lib/reactionary-ucp-webhooks.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import * as z from "zod";
+import { signRestRequest } from "./reactionary-ucp-signing.js";
+const DEFAULT_RETRY_DELAYS_MS = [500, 2e3, 1e4, 6e4, 3e5];
+const PROFILE_CACHE_TTL_MS = 5 * 60 * 1e3;
+const REQUEST_TIMEOUT_MS = 5e3;
+const ORDER_CAPABILITY = "dev.ucp.shopping.order";
+const AgentProfileSchema = z.looseObject({
+  ucp: z.looseObject({
+    capabilities: z.record(z.string(), z.array(z.looseObject({
+      config: z.looseObject({ webhook_url: z.string().optional() }).optional()
+    }))).optional()
+  })
+});
+class ReactionaryUCPWebhooks {
+  constructor(options, businessProfileUrl) {
+    this.options = options;
+    this.businessProfileUrl = businessProfileUrl;
+    this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  options;
+  businessProfileUrl;
+  profileCache = /* @__PURE__ */ new Map();
+  retryDelaysMs;
+  fetchImpl;
+  warnedUnsigned = false;
+  /** The order webhook URL declared in a platform's profile, if any. */
+  async resolveOrderWebhookUrl(agentProfileUrl) {
+    const cached = this.profileCache.get(agentProfileUrl);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.webhookUrl;
+    }
+    const webhookUrl = this.isAllowedUrl(agentProfileUrl) ? await this.fetchOrderWebhookUrl(agentProfileUrl) : void 0;
+    this.profileCache.set(agentProfileUrl, { webhookUrl, expiresAt: Date.now() + PROFILE_CACHE_TTL_MS });
+    return webhookUrl;
+  }
+  /**
+   * 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, order) {
+    if (!this.isAllowedUrl(webhookUrl)) {
+      return;
+    }
+    const webhookId = `evt_${randomUUID()}`;
+    const body = JSON.stringify(order);
+    const headers = {
+      "content-type": "application/json",
+      "webhook-id": webhookId,
+      "webhook-timestamp": String(Math.floor(Date.now() / 1e3)),
+      "ucp-agent": `profile="${this.businessProfileUrl}"`,
+      // Deliveries are state-changing POSTs; retries keep the key.
+      "idempotency-key": webhookId
+    };
+    if (this.options.signingKey) {
+      Object.assign(headers, signRestRequest({ method: "POST", url: webhookUrl, headers, body }, this.options.signingKey));
+    } else if (!this.warnedUnsigned) {
+      this.warnedUnsigned = true;
+      console.warn("UCP: order webhooks are sent unsigned; configure webhooks.signingKey (the order capability requires signed payloads).");
+    }
+    void this.attempt(webhookUrl, headers, body, 0);
+  }
+  async attempt(webhookUrl, headers, body, attempt) {
+    let failure;
+    try {
+      const response = await this.fetchImpl(webhookUrl, {
+        method: "POST",
+        headers,
+        body,
+        redirect: "manual",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+      if (response.ok) {
+        return;
+      }
+      failure = `HTTP ${response.status}`;
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error);
+    }
+    const delay = this.retryDelaysMs[attempt];
+    if (delay === void 0) {
+      console.error(`UCP: giving up on webhook ${headers["webhook-id"]} to ${webhookUrl} after ${attempt + 1} attempts: ${failure}`);
+      return;
+    }
+    setTimeout(() => void this.attempt(webhookUrl, headers, body, attempt + 1), delay).unref();
+  }
+  async fetchOrderWebhookUrl(agentProfileUrl) {
+    try {
+      const response = await this.fetchImpl(agentProfileUrl, {
+        headers: { accept: "application/json" },
+        redirect: "manual",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+      const profile = response.ok ? AgentProfileSchema.safeParse(await response.json()) : void 0;
+      const capabilities = profile?.success ? profile.data.ucp.capabilities?.[ORDER_CAPABILITY] ?? [] : [];
+      return capabilities.find((capability) => capability.config?.webhook_url)?.config?.webhook_url;
+    } catch {
+      return void 0;
+    }
+  }
+  isAllowedUrl(value) {
+    try {
+      const { protocol } = new URL(value);
+      return protocol === "https:" || protocol === "http:" && Boolean(this.options.allowInsecureUrls);
+    } catch {
+      return false;
+    }
+  }
+}
+export {
+  ReactionaryUCPWebhooks
+};

package/package.json

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

package/src/index.d.ts

@@ -1,2 +1,6 @@
 export * from './lib/reactionary-ucp-server.js';
 export * from './lib/reactionary-ucp-identity.js';
+export * from './lib/reactionary-ucp-localization.js';
+export { toPublicSigningJwk, type UCPSigningKey } from './lib/reactionary-ucp-signing.js';
+export type { ReactionaryUCPWebhookOptions } from './lib/reactionary-ucp-webhooks.js';
+export { DEFAULT_UCP_PAYMENT_AUTHORIZATION_WAIT, DEFAULT_UCP_PLACEHOLDER_EMAIL, type UCPPaymentAuthorizationWait, type UCPInventoryOptions, type UCPTestPaymentHandler, } from './lib/reactionary-ucp-checkout-session.js';

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

@@ -0,0 +1,91 @@
+import type { Cart } from '@reactionary/core';
+import type { ReactionaryUCPClient, UCPPaymentHandlers } from './reactionary-ucp-common.js';
+import { type UCPCheckout, type UCPLineItem, type UCPPostalAddress } from './reactionary-ucp-mapping.js';
+import { type ReactionaryUCPSessionStore } from './reactionary-ucp-session-store.js';
+import type { components } from './ucp-shopping.openapi.js';
+type UCPErrorResponse = components['schemas']['error_response'];
+type UCPCheckoutResponse = components['schemas']['checkout_response'];
+export type UCPCheckoutRequest = UCPCheckout & {
+    cart_id?: string;
+};
+export declare const DEFAULT_UCP_PLACEHOLDER_EMAIL = "pending@checkout.invalid";
+/**
+ * How long completion waits for the placed checkout to become
+ * `readyForFinalization` — which implies an authorized payment, typically
+ * recorded on the backend by a PSP webhook — before answering
+ * `complete_in_progress`. A timeout of 0 disables waiting.
+ */
+export interface UCPPaymentAuthorizationWait {
+    timeoutMs: number;
+    intervalMs: number;
+}
+export declare const DEFAULT_UCP_PAYMENT_AUTHORIZATION_WAIT: UCPPaymentAuthorizationWait;
+/**
+ * A payment handler that exists only for testing. Agents complete with its
+ * instruments, and the payment is placed through a real advertised handler
+ * with a substitute credential (e.g. a PSP test token), so suites that
+ * hardcode a mock handler still exercise real payments.
+ */
+export interface UCPTestPaymentHandler {
+    /** The handler id agents send, e.g. the UCP conformance suite's `mock_payment_handler`. */
+    id: string;
+    /** Id of the advertised handler the payment is placed through, e.g. `stripe`. */
+    delegateHandlerId: string;
+    /**
+     * Maps the agent's credential to one the delegate handler accepts.
+     * Returning undefined declines the payment.
+     */
+    resolveCredential(credential: unknown): unknown;
+}
+/**
+ * Line items are checked against the combined stock of these fulfillment
+ * centers. Items without inventory records are treated as untracked.
+ */
+export interface UCPInventoryOptions {
+    fulfillmentCenterKeys: string[];
+}
+/**
+ * A UCP checkout session is a mutable, progressively filled resource, while a
+ * reactionary checkout is a frozen snapshot of a finished cart. Sessions are
+ * therefore UCP-owned state over a reactionary cart: views are priced with a
+ * transient reactionary checkout that is discarded again, and only completion
+ * creates the real checkout.
+ */
+export interface UCPCheckoutSessionContext {
+    client: ReactionaryUCPClient;
+    store: ReactionaryUCPSessionStore;
+    sessionId: string;
+    paymentHandlers: UCPPaymentHandlers;
+    placeholderEmail: string;
+    paymentAuthorizationWait: UCPPaymentAuthorizationWait;
+    /** 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;
+    /** The requesting platform's UCP-Agent profile URL. */
+    agentProfile?: string;
+    /** Called once when a checkout completes into a recorded order. */
+    onOrderPlaced?(orderId: string): void;
+    /** Email of the session's registered identity, if logged in. */
+    getIdentityEmail(): Promise<string | undefined>;
+    createCart(lineItems: UCPLineItem[]): Promise<Cart | UCPErrorResponse>;
+    reconcileCart(cartId: string, lineItems: UCPLineItem[]): Promise<UCPErrorResponse | undefined>;
+}
+export declare function createCheckoutSession(context: UCPCheckoutSessionContext, body: UCPCheckoutRequest): Promise<UCPCheckoutResponse>;
+export declare function getCheckoutSession(context: UCPCheckoutSessionContext, checkoutSessionId: string): Promise<UCPCheckoutResponse>;
+export declare function updateCheckoutSession(context: UCPCheckoutSessionContext, checkoutSessionId: string, body: UCPCheckoutRequest): Promise<UCPCheckoutResponse>;
+export declare function cancelCheckoutSession(context: UCPCheckoutSessionContext, checkoutSessionId: string): Promise<UCPCheckoutResponse>;
+/**
+ * Creates the real checkout from the session state and finalizes it. When the
+ * backend is not ready yet — typically a payment awaiting the payment service
+ * provider's asynchronous authorization — the session reports
+ * `complete_in_progress`, and a repeated complete retries finalization.
+ */
+export declare function completeCheckoutSession(context: UCPCheckoutSessionContext, checkoutSessionId: string, body: UCPCheckoutRequest): Promise<UCPCheckoutResponse>;
+export type { UCPPostalAddress };

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

@@ -1,7 +1,10 @@
-import type { Cache, Cart, Checkout, Client, FacetValueIdentifier, Order, Product, ProductSearchResult, RequestContext, Result } from '@reactionary/core';
+import type { Cache, Cart, Checkout, Client, FacetValueIdentifier, Inventory, Order, Product, ProductSearchResult, Profile, RequestContext, Result, ShippingMethod } from '@reactionary/core';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { components } from './ucp-shopping.openapi.js';
 import type { ReactionaryUCPIdentityOptions } from './reactionary-ucp-identity.js';
+import type { ReactionaryUCPLocalizationOptions } from './reactionary-ucp-localization.js';
+import type { ReactionaryUCPWebhookOptions } from './reactionary-ucp-webhooks.js';
+import type { UCPInventoryOptions, UCPPaymentAuthorizationWait, UCPTestPaymentHandler } from './reactionary-ucp-checkout-session.js';
 type UCPService = components['schemas']['base'];
 type UCPCapability = components['schemas']['$defs-base'];
 export type UCPPaymentHandler = components['schemas']['entity'] & {
@@ -42,16 +45,27 @@ export type ReactionaryUCPClient = object & {
         deleteCart: UCPMethod<Client['cart']['deleteCart'], void>;
         getById: UCPMethod<Client['cart']['getById'], Cart>;
         remove: UCPMethod<Client['cart']['remove'], Cart>;
+        applyCouponCode?: UCPMethod<Client['cart']['applyCouponCode'], Cart>;
+        removeCouponCode?: UCPMethod<Client['cart']['removeCouponCode'], Cart>;
     };
     checkout?: {
         addPaymentInstruction: UCPMethod<Client['checkout']['addPaymentInstruction'], Checkout>;
         finalizeCheckout: UCPMethod<Client['checkout']['finalizeCheckout'], Checkout>;
         getById: UCPMethod<Client['checkout']['getById'], Checkout>;
         initiateCheckoutForCart: UCPMethod<Client['checkout']['initiateCheckoutForCart'], Checkout>;
+        getAvailableShippingMethods?: UCPMethod<Client['checkout']['getAvailableShippingMethods'], ShippingMethod[]>;
+        setShippingAddress?: UCPMethod<Client['checkout']['setShippingAddress'], Checkout>;
+        setShippingInstruction?: UCPMethod<Client['checkout']['setShippingInstruction'], Checkout>;
     };
     order?: {
         getById: UCPMethod<Client['order']['getById'], Order>;
     };
+    inventory?: {
+        getBySKU: UCPMethod<Client['inventory']['getBySKU'], Inventory>;
+    };
+    profile?: {
+        getById: UCPMethod<Client['profile']['getById'], Profile>;
+    };
 };
 export type ReactionaryUCPClientFactory<TClient extends ReactionaryUCPClient = ReactionaryUCPClient> = (requestContext: RequestContext) => TClient;
 export interface ReactionaryUCPServerOptions {
@@ -59,6 +73,84 @@ export interface ReactionaryUCPServerOptions {
     sessionTtlSeconds?: number;
     profile?: ReactionaryUCPProfileOptions;
     identity?: ReactionaryUCPIdentityOptions;
+    /**
+     * Maps buyer signals (UCP `context.address_country`, `Accept-Language`) to a
+     * language context. Without it, every request uses the client factory's
+     * initial context. The negotiated context sticks to the UCP session.
+     */
+    localization?: ReactionaryUCPLocalizationOptions;
+    /**
+     * Email used to price transient checkouts before the buyer has supplied
+     * one (backends require an email to quote shipping and tax). Never used for
+     * the real checkout created on completion. Defaults to
+     * `pending@checkout.invalid` — `.invalid` is a reserved, undeliverable TLD.
+     */
+    placeholderEmail?: string;
+    /**
+     * Email used to place REAL orders when the agent never supplied a buyer
+     * email and no identity is logged in. Unset (the default), such completions
+     * answer `incomplete` asking for `$.buyer.email`. Setting it lets anonymous
+     * agent checkouts complete, but the buyer cannot be sent a receipt, which
+     * may be illegal in some jurisdictions — the server logs a prominent
+     * warning while it is set. Intended for conformance and test environments.
+     */
+    anonymousOrderEmail?: 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 `complete_in_progress`. Defaults to 10s
+     * timeout, polled every 1s.
+     */
+    paymentAuthorizationWait?: Partial<UCPPaymentAuthorizationWait>;
+    /**
+     * Payment handlers that exist only for testing, e.g. the UCP conformance
+     * suite's hardcoded `mock_payment_handler`. Each is accepted on checkout
+     * sessions without being advertised, and its payments are placed through
+     * its delegate — an advertised handler — with the credential it resolves.
+     * The server logs a prominent warning while any is set. Intended for
+     * conformance and test environments.
+     */
+    testPaymentHandlers?: UCPTestPaymentHandler[];
+    /**
+     * Accepts raw card credentials (a card number, e.g. the `pan` credential)
+     * 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 answer `payment_failed`, and platforms are expected to
+     * submit delegated tokens (UCP: credentials are opaque tokens, not raw
+     * PANs). Credentials resolved by a test payment handler are checked too.
+     */
+    acceptRawCardCredentials?: boolean;
+    /**
+     * Checks checkout session line items against these fulfillment centers'
+     * combined stock, reporting `out_of_stock` per line item. Unset (the
+     * default), stock is left to the backend.
+     */
+    inventory?: UCPInventoryOptions;
+    /**
+     * Accepts PUT /orders/{id} with fulfillment events and adjustments for
+     * orders placed through a UCP checkout session, and reports them on the
+     * order — a stand-in for the business posting order updates, as the UCP
+     * conformance suite expects. Not part of the UCP specification; any agent
+     * that can read an order could rewrite its history. The server logs a
+     * prominent warning while it is set. Intended for conformance and test
+     * environments.
+     */
+    testOrderUpdates?: boolean;
+    /**
+     * Sends order events (created, and every update) to the webhook URL the
+     * platform declares in its profile, as the order capability requires.
+     * Unset (the default), no webhooks are sent and agent profiles are never
+     * fetched.
+     */
+    webhooks?: ReactionaryUCPWebhookOptions;
+    /**
+     * Enables POST /testing/simulate-shipping/{orderId}, guarded by this value
+     * in the Simulation-Secret header: records a shipment of the order and
+     * sends the update webhook. Not part of the UCP specification. The server
+     * logs a prominent warning while it is set. Intended for conformance and
+     * test environments.
+     */
+    testSimulationSecret?: string;
 }
 export interface ReactionaryUCPProfileOptions {
     endpoint: string;

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

@@ -0,0 +1,24 @@
+import type { Cart } from '@reactionary/core';
+import type { ReactionaryUCPClient } from './reactionary-ucp-common.js';
+import { type UCPMessage } from './reactionary-ucp-mapping.js';
+/** The discount codes a request submits, if it submits any (`[]` clears them). */
+export declare function getRequestedDiscountCodes(body: Record<string, unknown>): string[] | undefined;
+/**
+ * Applies a submitted code set to the cart with replacement semantics: codes
+ * no longer submitted are removed, new ones are applied. Codes match
+ * case-insensitively; a backend that matches exactly is also tried with the
+ * upper-cased code. Rejected codes are reported as warnings.
+ */
+export declare function applyDiscountCodes(client: ReactionaryUCPClient, cart: Cart, codes: string[]): Promise<{
+    cart: Cart;
+    messages: UCPMessage[];
+}>;
+/**
+ * The discount extension's view of the cart's promotions. Amounts come from
+ * the promotion when the backend reports them; otherwise a sole promotion is
+ * attributed the cart's whole discount, with per-line allocations when it is
+ * allocated to lines only.
+ */
+export declare function toUcpDiscounts(cart: Cart): {
+    discounts: Record<string, unknown>;
+};

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

@@ -9,4 +9,6 @@ export declare function jsonResponse(body: unknown, options?: {
 }): Response;
 export declare function toWebRequest(request: IncomingMessage): Promise<Request>;
 export declare function sendWebResponse(response: ServerResponse, webResponse: Response): Promise<void>;
+/** Constant-time string comparison. */
+export declare function secureEquals(left: string, right: string): boolean;
 export {};

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

@@ -0,0 +1,35 @@
+import { type LanguageContext, type Session } from '@reactionary/core';
+/**
+ * Maps a buyer signal — the UCP `context.address_country` of a request payload,
+ * or an `Accept-Language` language tag — to a language context. Mirrors the
+ * mapping frontends maintain today, since neither the core store model nor the
+ * providers carry a locale/currency catalogue yet.
+ */
+export interface ReactionaryUCPLocalizationRule {
+    /** ISO 3166-1 alpha-2 country code matched against `context.address_country`, case-insensitive. */
+    country?: string;
+    /** BCP 47 language tag matched against `Accept-Language` tags, case-insensitive; `da` matches `da-DK`. */
+    language?: string;
+    languageContext: LanguageContext;
+}
+export interface ReactionaryUCPLocalizationOptions {
+    rules: ReactionaryUCPLocalizationRule[];
+    /** Used when no rule matches. Without it, the server's initial context stays in effect. */
+    fallback?: LanguageContext;
+}
+/**
+ * Default Nordic-oriented mapping: Sweden → SEK, Norway → NOK, Denmark → DKK,
+ * Finland → EUR, and English-speaking buyers → USD. Country signals match
+ * first; the language rules catch buyers whose requests only carry
+ * Accept-Language.
+ */
+export declare const DEFAULT_UCP_LOCALIZATION_RULES: ReactionaryUCPLocalizationRule[];
+/**
+ * Resolves the language context for a request. The result is persisted in the
+ * session and reused for every later request of that session: backends fix a
+ * cart's currency and locale at creation, so renegotiating mid-session would
+ * detach the context from the carts and checkouts the session already created.
+ */
+export declare function resolveLanguageContext(request: Request, session: Session, options: ReactionaryUCPLocalizationOptions | undefined): Promise<LanguageContext | undefined>;
+/** Returns the accepted language tags, highest quality first, `*` excluded. */
+export declare function parseAcceptLanguage(header: string | null): string[];