diff --git a/generate_ts_schema_types.js b/generate_ts_schema_types.js index 1b0120d9..72453f70 100644 --- a/generate_ts_schema_types.js +++ b/generate_ts_schema_types.js @@ -2,7 +2,7 @@ const fs = require('node:fs'); const path = require('node:path'); const { compile } = require('json-schema-to-typescript'); -const SOURCE_ROOT = path.resolve(__dirname, 'spec'); +const SOURCE_ROOT = path.resolve(__dirname, 'source'); const OUTPUT_FILE = path.resolve(__dirname, './generated/schema-types.ts'); const WRAPPER_NAME = 'SCHEMA_WRAPPER'; @@ -16,17 +16,30 @@ async function generate() { const properties = {}; - // Add shopping schemas - const shoppingDir = path.join(SOURCE_ROOT, 'schemas/shopping'); - if (fs.existsSync(shoppingDir)) { - for (const file of fs.readdirSync(shoppingDir)) { - if (file.endsWith('.json')) { - properties[path.basename(file, '.json')] = { - $ref: path.join(shoppingDir, file) - }; + const addSchemasFromDir = (dir, prefix = '') => { + if (fs.existsSync(dir)) { + for (const file of fs.readdirSync(dir)) { + const fullPath = path.join(dir, file); + const stat = fs.statSync(fullPath); + if (stat.isDirectory()) { + // Skip types directory as they are pulled in by refs + continue; + } else if (file.endsWith('.json')) { + const name = (prefix + path.basename(file, '.json')).replace(/[-.]/g, '_'); + properties[name] = { $ref: fullPath }; + } } } - } + }; + + // Add core schemas + addSchemasFromDir(path.join(SOURCE_ROOT, 'schemas')); + // Add transport schemas + addSchemasFromDir(path.join(SOURCE_ROOT, 'schemas/transports'), 'transport_'); + // Add shopping schemas + addSchemasFromDir(path.join(SOURCE_ROOT, 'schemas/shopping')); + // Add discovery schemas + addSchemasFromDir(path.join(SOURCE_ROOT, 'discovery')); // Add handler schemas const handlersDir = path.join(SOURCE_ROOT, 'handlers'); @@ -34,13 +47,18 @@ async function generate() { for (const handler of fs.readdirSync(handlersDir)) { const handlerPath = path.join(handlersDir, handler); if (fs.statSync(handlerPath).isDirectory()) { - for (const file of fs.readdirSync(handlerPath)) { - if (file.endsWith('.json')) { - const name = - `${handler}_${path.basename(file, '.json')}`.replace(/-/g, '_'); - properties[name] = {$ref: path.join(handlerPath, file)}; - } - } + addSchemasFromDir(handlerPath, `${handler}_`); + } + } + } + + // Add service schemas + const servicesDir = path.join(SOURCE_ROOT, 'services'); + if (fs.existsSync(servicesDir)) { + for (const service of fs.readdirSync(servicesDir)) { + const servicePath = path.join(servicesDir, service); + if (fs.statSync(servicePath).isDirectory()) { + addSchemasFromDir(servicePath, `${service}_`); } } } diff --git a/generated/schema-types.ts b/generated/schema-types.ts index 92f481ca..ab5f53a7 100644 --- a/generated/schema-types.ts +++ b/generated/schema-types.ts @@ -8,200 +8,329 @@ */ /** - * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "merchant_authorization". - */ -export type MerchantAuthorizationCompleteRequest = string; -/** - * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. - * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout_mandate". - */ -export type CheckoutMandateCompleteRequest = string; -/** - * Checkout extended with AP2 mandate support. + * Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". + * This interface was referenced by `UCPCapability`'s JSON-Schema + * via the `definition` "platform_schema". */ -export type CheckoutWithAP2MandateCompleteRequest = CheckoutCompleteRequest & { - ap2?: Ap2WithMerchantAuthorization & Ap2WithCheckoutMandate; +export type CapabilityPlatformSchema = (Entity & { + /** + * Parent capability this extends. Present for extensions, absent for root capabilities. + */ + extends?: string; + [k: string]: unknown; +}) & { [k: string]: unknown; }; /** - * Matches a specific instrument type based on validation logic. - */ -export type PaymentInstrument = CardPaymentInstrument; -/** - * A basic card payment instrument with visible card details. Can be inherited by a handler's instrument schema to define handler-specific display details or more complex credential structures. + * Capability configuration for business/merchant level. May include business-specific config overrides. + * + * This interface was referenced by `UCPCapability`'s JSON-Schema + * via the `definition` "business_schema". */ -export type CardPaymentInstrument = PaymentInstrumentBase & { - /** - * Indicates this is a card payment instrument. - */ - type: 'card'; - /** - * The card brand/network (e.g., visa, mastercard, amex). - */ - brand: string; - /** - * Last 4 digits of the card number. - */ - last_digits: string; - /** - * The month of the card's expiration date (1-12). - */ - expiry_month?: number; - /** - * The year of the card's expiration date. - */ - expiry_year?: number; - /** - * An optional rich text description of the card to display to the user (e.g., 'Visa ending in 1234, expires 12/2025'). - */ - rich_text_description?: string; +export type CapabilityBusinessSchema = Entity & { /** - * An optional URI to a rich image representing the card (e.g., card art provided by the issuer). + * Parent capability this extends. Present for extensions, absent for root capabilities. */ - rich_card_art?: string; + extends?: string; [k: string]: unknown; }; /** - * Container for sensitive payment data. Use the specific schema matching the 'type' field. - */ -export type PaymentCredential = TokenCredentialResponse | CardCredential; -/** - * Error codes specific to AP2 mandate verification. + * Capability reference in responses. Only name/version required to confirm active capabilities. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "error_code". + * This interface was referenced by `UCPCapability`'s JSON-Schema + * via the `definition` "response_schema". */ -export type AP2ErrorCodeCompleteRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; +export type CapabilityResponseSchema = Entity & { + /** + * Parent capability this extends. Present for extensions, absent for root capabilities. + */ + extends?: string; + [k: string]: unknown; +}; /** - * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. + * Platform declaration for discovery profiles. May include partial config state required for discovery. * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "merchant_authorization". + * This interface was referenced by `PaymentHandler`'s JSON-Schema + * via the `definition` "platform_schema". */ -export type MerchantAuthorizationCreateRequest = string; +export type PaymentHandlerPlatformSchema = (Entity & { + [k: string]: unknown; +}) & { + [k: string]: unknown; +}; /** - * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. + * Business declaration for discovery profiles. May include partial config state required for discovery. * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout_mandate". + * This interface was referenced by `PaymentHandler`'s JSON-Schema + * via the `definition` "business_schema". */ -export type CheckoutMandateCreateRequest = string; +export type PaymentHandlerBusinessSchema = Entity & { + [k: string]: unknown; +}; /** - * Checkout extended with AP2 mandate support. + * Handler reference in responses. May include full config state for runtime usage of the handler. * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". + * This interface was referenced by `PaymentHandler`'s JSON-Schema + * via the `definition` "response_schema". */ -export type CheckoutWithAP2MandateCreateRequest = CheckoutCreateRequest & { +export type PaymentHandlerResponseSchema = Entity & { [k: string]: unknown; }; /** - * Error codes specific to AP2 mandate verification. + * Full service declaration for platform-level discovery. Different transports require different fields. * - * This interface was referenced by `AP2MandateExtensionCreateRequest`'s JSON-Schema - * via the `definition` "error_code". - */ -export type AP2ErrorCodeCreateRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; + * This interface was referenced by `UCPService`'s JSON-Schema + * via the `definition` "platform_schema". + */ +export type ServicePlatformSchema = (Entity & { + /** + * Transport protocol for this service binding. + */ + transport: 'rest' | 'mcp' | 'a2a' | 'embedded'; + /** + * Endpoint URL for this transport binding. + */ + endpoint?: string; + [k: string]: unknown; +}) & { + [k: string]: unknown; +} & ( + | { + transport?: 'rest'; + [k: string]: unknown; + } + | { + transport?: 'mcp'; + [k: string]: unknown; + } + | { + transport?: 'a2a'; + [k: string]: unknown; + } + | { + transport?: 'embedded'; + [k: string]: unknown; + } + ); +/** + * Service binding for business/merchant configuration. May override platform endpoints. + * + * This interface was referenced by `UCPService`'s JSON-Schema + * via the `definition` "business_schema". + */ +export type ServiceBusinessSchema = (Entity & { + /** + * Transport protocol for this service binding. + */ + transport: 'rest' | 'mcp' | 'a2a' | 'embedded'; + /** + * Endpoint URL for this transport binding. + */ + endpoint?: string; + [k: string]: unknown; +}) & + ( + | { + transport?: 'rest'; + [k: string]: unknown; + } + | { + transport?: 'mcp'; + [k: string]: unknown; + } + | { + transport?: 'a2a'; + [k: string]: unknown; + } + | { + transport?: 'embedded'; + config?: EmbeddedTransportConfig; + [k: string]: unknown; + } + ); +/** + * Service binding in API responses. Includes per-resource transport configuration via typed config. + * + * This interface was referenced by `UCPService`'s JSON-Schema + * via the `definition` "response_schema". + */ +export type ServiceResponseSchema = (Entity & { + /** + * Transport protocol for this service binding. + */ + transport: 'rest' | 'mcp' | 'a2a' | 'embedded'; + /** + * Endpoint URL for this transport binding. + */ + endpoint?: string; + [k: string]: unknown; +}) & + ( + | { + transport?: 'rest'; + [k: string]: unknown; + } + | { + transport?: 'mcp'; + [k: string]: unknown; + } + | { + transport?: 'a2a'; + [k: string]: unknown; + } + | { + transport?: 'embedded'; + config?: EmbeddedTransportConfig; + [k: string]: unknown; + } + ); +/** + * Full UCP metadata for platform-level configuration. Hosted at a URI advertised by the platform in request headers. + * + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "platform_schema". + */ +export type UCPPlatformSchema = Base & { + services: { + [k: string]: ServicePlatformSchema[]; + }; + capabilities?: { + [k: string]: CapabilityPlatformSchema[]; + }; + payment_handlers: { + [k: string]: PaymentHandlerPlatformSchema[]; + }; + [k: string]: unknown; +}; /** - * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. + * UCP metadata for business/merchant-level configuration. Subset of platform schema with business-specific settings. * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "merchant_authorization". + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "business_schema". */ -export type MerchantAuthorizationUpdateRequest = string; +export type UCPBusinessSchema = Base & { + services: { + [k: string]: ServiceBusinessSchema[]; + }; + capabilities?: { + [k: string]: CapabilityBusinessSchema[]; + }; + payment_handlers: { + [k: string]: PaymentHandlerBusinessSchema[]; + }; + [k: string]: unknown; +}; /** - * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. + * UCP metadata for checkout responses. * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout_mandate". + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "response_checkout_schema". */ -export type CheckoutMandateUpdateRequest = string; +export type UCPCheckoutResponseSchema = Base & { + services?: { + [k: string]: ServiceResponseSchema[]; + }; + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + payment_handlers: { + [k: string]: PaymentHandlerResponseSchema[]; + }; + [k: string]: unknown; +}; /** - * Checkout extended with AP2 mandate support. + * UCP metadata for order responses. No payment handlers needed post-purchase. * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "response_order_schema". */ -export type CheckoutWithAP2MandateUpdateRequest = CheckoutUpdateRequest & { +export type UCPOrderResponseSchema = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; [k: string]: unknown; }; /** - * Error codes specific to AP2 mandate verification. + * UCP metadata for cart responses. No payment handlers needed pre-checkout. * - * This interface was referenced by `AP2MandateExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "error_code". + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "response_cart_schema". */ -export type AP2ErrorCodeUpdateRequest = - | 'mandate_required' - | 'agent_missing_key' - | 'mandate_invalid_signature' - | 'mandate_expired' - | 'mandate_scope_mismatch' - | 'merchant_authorization_invalid' - | 'merchant_authorization_missing'; +export type UCPCartResponseSchema = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + [k: string]: unknown; +}; /** * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "merchant_authorization". */ -export type MerchantAuthorizationResponse = string; +export type MerchantAuthorization = string; /** * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "checkout_mandate". */ -export type CheckoutMandateResponse = string; +export type CheckoutMandate = string; +/** + * JWS Detached Content signature (RFC 7515 Appendix F) over the checkout response body (excluding ap2 field). Format: `..`. The header MUST contain 'alg' (ES256/ES384/ES512) and 'kid' claims. The signature covers both the header and JCS-canonicalized checkout payload. + */ +export type MerchantAuthorization1 = string; +/** + * SD-JWT+kb credential in `ap2.checkout_mandate`. Proving user authorization for the checkout. Contains the full checkout including `ap2.merchant_authorization`. + */ +export type CheckoutMandate1 = string; /** * Checkout extended with AP2 mandate support. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "checkout". */ -export type CheckoutWithAP2MandateResponse = CheckoutResponse & { - ap2?: Ap2WithMerchantAuthorization1 & Ap2WithCheckoutMandate1; +export type CheckoutWithAP2Mandate = Checkout & { + ap2?: Ap2WithMerchantAuthorization & Ap2WithCheckoutMandate; [k: string]: unknown; }; /** - * Capability reference in responses. Only name/version required to confirm active capabilities. + * UCP metadata for checkout responses. */ -export type CapabilityResponse = Base & { +export type UCPCheckoutResponseSchema1 = Base & { + services?: { + [k: string]: ServiceResponseSchema[]; + }; + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; + payment_handlers: { + [k: string]: PaymentHandlerResponseSchema[]; + }; [k: string]: unknown; }; /** * Container for error, warning, or info messages. */ export type Message = MessageError | MessageWarning | MessageInfo; +/** + * A payment instrument with selection state. + */ +export type SelectedPaymentInstrument = PaymentInstrument & { + /** + * Whether this instrument is selected by the user. + */ + selected?: boolean; + [k: string]: unknown; +}; /** * Error codes specific to AP2 mandate verification. * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "error_code". */ -export type AP2ErrorCodeResponse = +export type AP2ErrorCode = | 'mandate_required' | 'agent_missing_key' | 'mandate_invalid_signature' @@ -212,384 +341,356 @@ export type AP2ErrorCodeResponse = /** * Buyer object extended with consent tracking. * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema * via the `definition` "buyer". */ -export type BuyerWithConsentCompleteRequest = Buyer & { +export type BuyerWithConsent = Buyer1 & { consent?: Consent; [k: string]: unknown; }; /** * Checkout extended with consent tracking via buyer object. * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema * via the `definition` "checkout". */ -export type CheckoutWithBuyerConsentCompleteRequest = CheckoutCompleteRequest & { +export type CheckoutWithBuyerConsent = Checkout & { + buyer?: BuyerWithConsent1; [k: string]: unknown; }; /** * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "buyer". */ -export type BuyerWithConsentCreateRequest = Buyer & { - consent?: Consent1; +export type BuyerWithConsent1 = Buyer1 & { + consent?: Consent; [k: string]: unknown; }; /** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". + * UCP metadata for cart responses. No payment handlers needed pre-checkout. */ -export type CheckoutWithBuyerConsentCreateRequest = CheckoutCreateRequest & { - buyer?: BuyerWithConsentCreateRequest; +export type UCPCartResponseSchema1 = Base & { + capabilities?: { + [k: string]: CapabilityResponseSchema[]; + }; [k: string]: unknown; }; /** - * Buyer object extended with consent tracking. + * Checkout extended with cart capability. Adds cart_id to create_checkout for cart-to-checkout conversion. * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "buyer". + * This interface was referenced by `Cart`'s JSON-Schema + * via the `definition` "checkout". */ -export type BuyerWithConsentUpdateRequest = Buyer & { - consent?: Consent2; +export type CheckoutWithCart = Checkout & { + /** + * Cart ID to convert to checkout. Business MUST use cart contents (line_items, context, buyer) and MUST ignore overlapping fields in checkout payload. + */ + cart_id?: string; [k: string]: unknown; }; /** - * Checkout extended with consent tracking via buyer object. + * Checkout extended with discount capability. * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema + * This interface was referenced by `DiscountExtension`'s JSON-Schema * via the `definition` "checkout". */ -export type CheckoutWithBuyerConsentUpdateRequest = CheckoutUpdateRequest & { - buyer?: BuyerWithConsentUpdateRequest; +export type CheckoutWithDiscount = Checkout & { + discounts?: DiscountsObject; [k: string]: unknown; }; /** - * Buyer object extended with consent tracking. - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "buyer". + * A destination for fulfillment. */ -export type BuyerWithConsentResponse = Buyer & { - consent?: Consent3; - [k: string]: unknown; -}; +export type FulfillmentDestination = ShippingDestination | RetailLocation; /** - * Checkout extended with consent tracking via buyer object. - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". + * Shipping destination. */ -export type CheckoutWithBuyerConsentResponse = CheckoutResponse & { - buyer?: BuyerWithConsentResponse; +export type ShippingDestination = PostalAddress & { + /** + * ID specific to this shipping destination. + */ + id: string; [k: string]: unknown; }; /** - * Checkout extended with discount capability. + * Checkout extended with hierarchical fulfillment. * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "checkout". */ -export type CheckoutWithDiscountCompleteRequest = CheckoutCompleteRequest & { +export type CheckoutWithFulfillment = Checkout & { + fulfillment?: Fulfillment1; [k: string]: unknown; }; /** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". + * Schema for UCP discovery profiles. Business profiles are hosted at /.well-known/ucp; platform profiles are hosted at URIs advertised in request headers. */ -export type CheckoutWithDiscountCreateRequest = CheckoutCreateRequest & { - discounts?: DiscountsObject; - [k: string]: unknown; -}; +export type UCPDiscoveryProfile = UCPPlatformDiscoveryProfile | UCPBusinessDiscoveryProfile; /** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". + * Full discovery profile for platforms. Exposes complete service, capability, and payment handler registries. */ -export type CheckoutWithDiscountUpdateRequest = CheckoutUpdateRequest & { - discounts?: DiscountsObject1; +export type UCPPlatformDiscoveryProfile = Base1 & { + ucp?: UCPPlatformSchema; [k: string]: unknown; }; /** - * Checkout extended with discount capability. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". + * Discovery profile for businesses/merchants. Subset of platform profile with business-specific configuration. */ -export type CheckoutWithDiscountResponse = CheckoutResponse & { - discounts?: DiscountsObject2; +export type UCPBusinessDiscoveryProfile = Base1 & { + ucp?: UCPBusinessSchema; [k: string]: unknown; }; + /** - * A destination for fulfillment. + * Schema for UCP capabilities and extensions. Extensions are capabilities with an 'extends' field. Uses reverse-domain naming for governance. */ -export type FulfillmentDestinationRequest = ShippingDestinationRequest | RetailLocationRequest; +export declare interface UCPCapability { + [k: string]: unknown; +} /** - * Shipping destination. + * Shared foundation for all UCP entities. + * + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "entity". */ -export type ShippingDestinationRequest = PostalAddress & { +export declare interface Entity { /** - * ID specific to this shipping destination. + * UCP version in YYYY-MM-DD format. + * + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "version". + */ + version: string; + /** + * URL to human-readable specification document. + */ + spec?: string; + /** + * URL to JSON Schema defining this entity's structure and payloads. + */ + schema?: string; + /** + * Unique identifier for this entity instance. Used to disambiguate when multiple instances exist. */ id?: string; + /** + * Entity-specific configuration. Structure defined by each entity's schema. + */ + config?: { + [k: string]: unknown; + }; [k: string]: unknown; -}; +} /** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "checkout". + * Schema for UCP payment handlers. Handlers define how payment instruments are processed. */ -export type CheckoutWithFulfillmentCompleteRequest = CheckoutCompleteRequest & { +export declare interface PaymentHandler { [k: string]: unknown; -}; +} /** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "checkout". + * Service binding for a specific transport. Each transport binding is a separate entry in the service array. */ -export type CheckoutWithFulfillmentCreateRequest = CheckoutCreateRequest & { - fulfillment?: FulfillmentRequest; +export declare interface UCPService { [k: string]: unknown; -}; +} /** - * Checkout extended with hierarchical fulfillment. - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "checkout". + * Per-checkout configuration for embedded transport binding. Allows businesses to vary ECP availability and delegations based on cart contents, agent authorization, or policy. */ -export type CheckoutWithFulfillmentUpdateRequest = CheckoutUpdateRequest & { - fulfillment?: FulfillmentRequest; +export declare interface EmbeddedTransportConfig { + /** + * Delegations the business allows. At service-level, declares available delegations. In checkout responses, confirms accepted delegations for this session. + */ + delegate?: string[]; [k: string]: unknown; -}; -/** - * A destination for fulfillment. - */ -export type FulfillmentDestinationResponse = ShippingDestinationResponse | RetailLocationResponse; +} /** - * Shipping destination. + * Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields. */ -export type ShippingDestinationResponse = PostalAddress & { - /** - * ID specific to this shipping destination. - */ - id: string; +export declare interface UCPMetadata { [k: string]: unknown; -}; +} /** - * Checkout extended with hierarchical fulfillment. + * Base UCP metadata with shared properties for all schema types. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema - * via the `definition` "checkout". + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "base". */ -export type CheckoutWithFulfillmentResponse = CheckoutResponse & { - fulfillment?: FulfillmentResponse; +export declare interface Base { + /** + * UCP version in YYYY-MM-DD format. + * + * This interface was referenced by `UCPMetadata`'s JSON-Schema + * via the `definition` "version". + */ + version: string; + /** + * Service registry keyed by reverse-domain name. + */ + services?: { + [k: string]: Array; + }; + /** + * Capability registry keyed by reverse-domain name. + */ + capabilities?: { + [k: string]: Array; + }; + /** + * Payment handler registry keyed by reverse-domain name. + */ + payment_handlers?: { + [k: string]: Array; + }; [k: string]: unknown; -}; - +} /** * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. */ -export declare interface AP2MandateExtensionCompleteRequest { +export declare interface AP2MandateExtension { [k: string]: unknown; } /** * AP2 extension data including merchant authorization. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "ap2_with_merchant_authorization". */ export declare interface Ap2WithMerchantAuthorization { + merchant_authorization?: MerchantAuthorization1; [k: string]: unknown; } /** * AP2 extension data including checkout mandate. * - * This interface was referenced by `AP2MandateExtensionCompleteRequest`'s JSON-Schema + * This interface was referenced by `AP2MandateExtension`'s JSON-Schema * via the `definition` "ap2_with_checkout_mandate". */ export declare interface Ap2WithCheckoutMandate { - checkout_mandate?: CheckoutMandateCompleteRequest; + checkout_mandate?: CheckoutMandate1; [k: string]: unknown; } /** * Base checkout schema. Extensions compose onto this using allOf. */ -export declare interface CheckoutCompleteRequest { - payment: PaymentCompleteRequest; - [k: string]: unknown; -} -/** - * Payment configuration containing handlers. - */ -export declare interface PaymentCompleteRequest { +export declare interface Checkout { + ucp: UCPCheckoutResponseSchema1; /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. + * Unique identifier of the checkout session. */ - selected_instrument_id?: string; + id: string; /** - * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. + * List of line items being checked out. */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -/** - * The base definition for any payment instrument. It links the instrument to a specific Merchant configuration (handler_id) and defines common fields like billing address. - */ -export declare interface PaymentInstrumentBase { + line_items: LineItem[]; + buyer?: Buyer; + context?: Context; /** - * A unique identifier for this instrument instance, assigned by the Agent. Used to reference this specific instrument in the 'payment.selected_instrument_id' field. + * Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. */ - id: string; - /** - * The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition. - */ - handler_id: string; - /** - * The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value. - */ - type: string; - billing_address?: PostalAddress; - credential?: PaymentCredential; - [k: string]: unknown; -} -export declare interface PostalAddress { - /** - * An address extension such as an apartment number, C/O or alternative name. - */ - extended_address?: string; - /** - * The street address. - */ - street_address?: string; - /** - * The locality in which the street address is, and which is in the region. For example, Mountain View. - */ - address_locality?: string; - /** - * The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division. - */ - address_region?: string; + status: + | 'incomplete' + | 'requires_escalation' + | 'ready_for_complete' + | 'complete_in_progress' + | 'completed' + | 'canceled'; /** - * The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. + * ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency. */ - address_country?: string; + currency: string; /** - * The postal code. For example, 94043. + * Different cart totals. */ - postal_code?: string; + totals: Total[]; /** - * Optional. First name of the contact associated with the address. + * List of messages with error and info about the checkout session state. */ - first_name?: string; + messages?: Message[]; /** - * Optional. Last name of the contact associated with the address. + * Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance. */ - last_name?: string; + links: Link[]; /** - * Optional. Phone number of the contact associated with the address. + * RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent. */ - phone_number?: string; - [k: string]: unknown; -} -/** - * Base token credential schema. Concrete payment handlers may extend this schema with additional fields and define their own constraints. - */ -export declare interface TokenCredentialResponse { + expires_at?: string; /** - * The specific type of token produced by the handler (e.g., 'stripe_token'). + * URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements. */ - type: string; + continue_url?: string; + payment?: Payment; + order?: OrderConfirmation; [k: string]: unknown; } /** - * A card credential containing sensitive payment card details including raw Primary Account Numbers (PANs). This credential type MUST NOT be used for checkout, only with payment handlers that tokenize or encrypt credentials. CRITICAL: Both parties handling CardCredential (sender and receiver) MUST be PCI DSS compliant. Transmission MUST use HTTPS/TLS with strong cipher suites. + * Line item object. Expected to use the currency of the parent object. */ -export declare interface CardCredential { - /** - * The credential type identifier for card credentials. - */ - type: 'card'; - /** - * The type of card number. Network tokens are preferred with fallback to FPAN. See PCI Scope for more details. - */ - card_number_type: 'fpan' | 'network_token' | 'dpan'; +export declare interface LineItem { + id: string; + item: Item; /** - * Card number. + * Quantity of the item being purchased. */ - number?: string; + quantity: number; /** - * The month of the card's expiration date (1-12). + * Line item totals breakdown. */ - expiry_month?: number; + totals: Total[]; /** - * The year of the card's expiration date. + * Parent line item identifier for any nested structures. */ - expiry_year?: number; + parent_id?: string; + [k: string]: unknown; +} +export declare interface Item { /** - * Cardholder name. + * The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business. */ - name?: string; + id: string; /** - * Card CVC number. + * Product title. */ - cvc?: string; + title: string; /** - * Cryptogram provided with network tokens. + * Unit price in minor (cents) currency units. */ - cryptogram?: string; + price: number; /** - * Electronic Commerce Indicator / Security Level Indicator provided with network tokens. + * Product image URI. */ - eci_value?: string; - [k: string]: unknown; -} -/** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. - */ -export declare interface AP2MandateExtensionCreateRequest { + image_url?: string; [k: string]: unknown; } -/** - * Base checkout schema. Extensions compose onto this using allOf. - */ -export declare interface CheckoutCreateRequest { - /** - * List of line items being checked out. - */ - line_items: LineItemCreateRequest[]; - buyer?: Buyer; +export declare interface Total { /** - * ISO 4217 currency code. + * Type of total categorization. */ - currency: string; - payment?: PaymentCreateRequest; - [k: string]: unknown; -} -/** - * Line item object. Expected to use the currency of the parent object. - */ -export declare interface LineItemCreateRequest { - item: ItemCreateRequest; + type: 'items_discount' | 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total'; /** - * Quantity of the item being purchased. + * Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery'). */ - quantity: number; - [k: string]: unknown; -} -export declare interface ItemCreateRequest { + display_text?: string; /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. + * If type == total, sums subtotal - discount + fulfillment + tax + fee. Should be >= 0. Amount in minor (cents) currency units. */ - id: string; + amount: number; [k: string]: unknown; } export declare interface Buyer { @@ -612,391 +713,194 @@ export declare interface Buyer { [k: string]: unknown; } /** - * Payment configuration containing handlers. + * Provisional buyer signals for relevance and localization: product availability, pricing, currency, tax, shipping, payment methods, and eligibility (e.g., student or affiliation discounts). Businesses SHOULD use these values when authoritative data (e.g., address) is absent, and MAY ignore unsupported values without returning errors. Context can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context. Platforms SHOULD progressively enhance context throughout the buyer journey. */ -export declare interface PaymentCreateRequest { +export declare interface Context { /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. + * The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value. */ - selected_instrument_id?: string; + address_country?: string; /** - * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. + * The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value. */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -/** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. - */ -export declare interface AP2MandateExtensionUpdateRequest { + address_region?: string; + /** + * The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. + */ + postal_code?: string; [k: string]: unknown; } -/** - * Base checkout schema. Extensions compose onto this using allOf. - */ -export declare interface CheckoutUpdateRequest { +export declare interface MessageError { /** - * Unique identifier of the checkout session. + * Message type discriminator. */ - id: string; + type: 'error'; /** - * List of line items being checked out. + * Error code. Possible values include: missing, invalid, out_of_stock, payment_declined, requires_sign_in, requires_3ds, requires_identity_linking. Freeform codes also allowed. */ - line_items: LineItemUpdateRequest[]; - buyer?: Buyer; + code: string; /** - * ISO 4217 currency code. + * RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]). */ - currency: string; - payment?: PaymentUpdateRequest; - [k: string]: unknown; -} -/** - * Line item object. Expected to use the currency of the parent object. - */ -export declare interface LineItemUpdateRequest { - id?: string; - item: ItemUpdateRequest; + path?: string; /** - * Quantity of the item being purchased. + * Content format, default = plain. */ - quantity: number; + content_type?: 'plain' | 'markdown'; /** - * Parent line item identifier for any nested structures. + * Human-readable message. */ - parent_id?: string; - [k: string]: unknown; -} -export declare interface ItemUpdateRequest { + content: string; /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. + * Declares who resolves this error. 'recoverable': agent can fix via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules (checkout complete). Errors with 'requires_*' severity contribute to 'status: requires_escalation'. */ - id: string; + severity: 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review'; [k: string]: unknown; } -/** - * Payment configuration containing handlers. - */ -export declare interface PaymentUpdateRequest { +export declare interface MessageWarning { /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. + * Message type discriminator. */ - selected_instrument_id?: string; + type: 'warning'; /** - * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. + * JSONPath (RFC 9535) to related field (e.g., $.line_items[0]). */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -/** - * Extends Checkout with cryptographic mandate support for non-repudiable authorization per the AP2 protocol. Uses embedded signature model with ap2 namespace. - */ -export declare interface AP2MandateExtensionResponse { - [k: string]: unknown; -} -/** - * AP2 extension data including merchant authorization. - * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "ap2_with_merchant_authorization". - */ -export declare interface Ap2WithMerchantAuthorization1 { - merchant_authorization?: MerchantAuthorizationResponse; - [k: string]: unknown; -} -/** - * AP2 extension data including checkout mandate. - * - * This interface was referenced by `AP2MandateExtensionResponse`'s JSON-Schema - * via the `definition` "ap2_with_checkout_mandate". - */ -export declare interface Ap2WithCheckoutMandate1 { - checkout_mandate?: CheckoutMandateResponse; - [k: string]: unknown; -} -/** - * Base checkout schema. Extensions compose onto this using allOf. - */ -export declare interface CheckoutResponse { - ucp: UCPCheckoutResponse; + path?: string; /** - * Unique identifier of the checkout session. + * Warning code. Machine-readable identifier for the warning type (e.g., final_sale, prop65, fulfillment_changed, age_restricted, etc.). */ - id: string; + code: string; /** - * List of line items being checked out. + * Human-readable warning message that MUST be displayed. */ - line_items: LineItemResponse[]; - buyer?: Buyer; + content: string; /** - * Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. + * Content format, default = plain. */ - status: - | 'incomplete' - | 'requires_escalation' - | 'ready_for_complete' - | 'complete_in_progress' - | 'completed' - | 'canceled'; + content_type?: 'plain' | 'markdown'; + [k: string]: unknown; +} +export declare interface MessageInfo { /** - * ISO 4217 currency code. + * Message type discriminator. */ - currency: string; + type: 'info'; /** - * Different cart totals. + * RFC 9535 JSONPath to the component the message refers to. */ - totals: TotalResponse[]; + path?: string; /** - * List of messages with error and info about the checkout session state. + * Info code for programmatic handling. */ - messages?: Message[]; + code?: string; /** - * Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance. + * Content format, default = plain. */ - links: Link[]; + content_type?: 'plain' | 'markdown'; /** - * RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent. + * Human-readable message. */ - expires_at?: string; + content: string; + [k: string]: unknown; +} +export declare interface Link { /** - * URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements. + * Type of link. Well-known values: `privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`. Consumers SHOULD handle unknown values gracefully by displaying them using the `title` field or omitting the link. */ - continue_url?: string; - payment: PaymentResponse; - order?: OrderConfirmation; + type: string; + /** + * The actual URL pointing to the content to be displayed. + */ + url: string; + /** + * Optional display text for the link. When provided, use this instead of generating from type. + */ + title?: string; [k: string]: unknown; } /** - * UCP metadata for checkout responses. + * Payment configuration containing handlers. */ -export declare interface UCPCheckoutResponse { - /** - * UCP protocol version in YYYY-MM-DD format. - */ - version: string; +export declare interface Payment { /** - * Active capabilities for this response. + * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. */ - capabilities: CapabilityResponse[]; + instruments?: SelectedPaymentInstrument[]; [k: string]: unknown; } -export declare interface Base { +/** + * The base definition for any payment instrument. It links the instrument to a specific payment handler. + */ +export declare interface PaymentInstrument { /** - * Stable capability identifier in reverse-domain notation (e.g., dev.ucp.shopping.checkout). Used in capability negotiation. + * A unique identifier for this instrument instance, assigned by the platform. */ - name?: string; + id: string; /** - * UCP protocol version in YYYY-MM-DD format. + * The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition. */ - version?: string; - /** - * URL to human-readable specification document. - */ - spec?: string; - /** - * URL to JSON Schema for this capability's payload. - */ - schema?: string; + handler_id: string; /** - * Parent capability this extends. Present for extensions, absent for root capabilities. + * The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value. */ - extends?: string; + type: string; + billing_address?: PostalAddress; + credential?: PaymentCredential; /** - * Capability-specific configuration (structure defined by each capability). + * Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler. */ - config?: { + display?: { [k: string]: unknown; }; [k: string]: unknown; } -/** - * Line item object. Expected to use the currency of the parent object. - */ -export declare interface LineItemResponse { - id: string; - item: ItemResponse; - /** - * Quantity of the item being purchased. - */ - quantity: number; - /** - * Line item totals breakdown. - */ - totals: TotalResponse[]; - /** - * Parent line item identifier for any nested structures. - */ - parent_id?: string; - [k: string]: unknown; -} -export declare interface ItemResponse { - /** - * Should be recognized by both the Platform, and the Business. For Google it should match the id provided in the "id" field in the product feed. - */ - id: string; - /** - * Product title. - */ - title: string; - /** - * Unit price in minor (cents) currency units. - */ - price: number; - /** - * Product image URI. - */ - image_url?: string; - [k: string]: unknown; -} -export declare interface TotalResponse { - /** - * Type of total categorization. - */ - type: 'items_discount' | 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total'; - /** - * Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery'). - */ - display_text?: string; - /** - * If type == total, sums subtotal - discount + fulfillment + tax + fee. Should be >= 0. Amount in minor (cents) currency units. - */ - amount: number; - [k: string]: unknown; -} -export declare interface MessageError { - /** - * Message type discriminator. - */ - type: 'error'; - /** - * Error code. Possible values include: missing, invalid, out_of_stock, payment_declined, requires_sign_in, requires_3ds, requires_identity_linking. Freeform codes also allowed. - */ - code: string; - /** - * RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]). - */ - path?: string; - /** - * Content format, default = plain. - */ - content_type?: 'plain' | 'markdown'; - /** - * Human-readable message. - */ - content: string; - /** - * Declares who resolves this error. 'recoverable': agent can fix via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules (checkout complete). Errors with 'requires_*' severity contribute to 'status: requires_escalation'. - */ - severity: 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review'; - [k: string]: unknown; -} -export declare interface MessageWarning { - /** - * Message type discriminator. - */ - type: 'warning'; - /** - * JSONPath (RFC 9535) to related field (e.g., $.line_items[0]). - */ - path?: string; - /** - * Warning code. Machine-readable identifier for the warning type (e.g., final_sale, prop65, fulfillment_changed, age_restricted, etc.). - */ - code: string; - /** - * Human-readable warning message that MUST be displayed. - */ - content: string; +export declare interface PostalAddress { /** - * Content format, default = plain. + * An address extension such as an apartment number, C/O or alternative name. */ - content_type?: 'plain' | 'markdown'; - [k: string]: unknown; -} -export declare interface MessageInfo { + extended_address?: string; /** - * Message type discriminator. + * The street address. */ - type: 'info'; + street_address?: string; /** - * RFC 9535 JSONPath to the component the message refers to. + * The locality in which the street address is, and which is in the region. For example, Mountain View. */ - path?: string; + address_locality?: string; /** - * Info code for programmatic handling. + * The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division. */ - code?: string; + address_region?: string; /** - * Content format, default = plain. + * The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. */ - content_type?: 'plain' | 'markdown'; + address_country?: string; /** - * Human-readable message. + * The postal code. For example, 94043. */ - content: string; - [k: string]: unknown; -} -export declare interface Link { + postal_code?: string; /** - * Type of link. Well-known values: `privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`. Consumers SHOULD handle unknown values gracefully by displaying them using the `title` field or omitting the link. + * Optional. First name of the contact associated with the address. */ - type: string; + first_name?: string; /** - * The actual URL pointing to the content to be displayed. + * Optional. Last name of the contact associated with the address. */ - url: string; + last_name?: string; /** - * Optional display text for the link. When provided, use this instead of generating from type. + * Optional. Phone number of the contact associated with the address. */ - title?: string; + phone_number?: string; [k: string]: unknown; } /** - * Payment configuration containing handlers. + * The base definition for any payment credential. Handlers define specific credential types. */ -export declare interface PaymentResponse { - /** - * Processing configurations that define how payment instruments can be collected. Each handler specifies a tokenization or payment collection strategy. - */ - handlers: PaymentHandlerResponse[]; - /** - * The id of the currently selected payment instrument from the instruments array. Set by the agent when submitting payment, and echoed back by the merchant in finalized state. - */ - selected_instrument_id?: string; - /** - * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. - */ - instruments?: PaymentInstrument[]; - [k: string]: unknown; -} -export declare interface PaymentHandlerResponse { +export declare interface PaymentCredential { /** - * The unique identifier for this handler instance within the payment.handlers. Used by payment instruments to reference which handler produced them. + * The credential type discriminator. Specific schemas will constrain this to a constant value. */ - id: string; - /** - * The specification name using reverse-DNS format. For example, dev.ucp.delegate_payment. - */ - name: string; - /** - * UCP protocol version in YYYY-MM-DD format. - */ - version: string; - /** - * A URI pointing to the technical specification or schema that defines how this handler operates. - */ - spec: string; - /** - * A URI pointing to a JSON Schema used to validate the structure of the config object. - */ - config_schema: string; - instrument_schemas: string[]; - /** - * A dictionary containing provider-specific configuration details, such as merchant IDs, supported networks, or gateway credentials. - */ - config: { - [k: string]: unknown; - }; + type: string; [k: string]: unknown; } /** @@ -1008,655 +912,226 @@ export declare interface OrderConfirmation { */ id: string; /** - * Permalink to access the order on merchant site. - */ - permalink_url: string; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionCompleteRequest { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent { - /** - * Consent for analytics and performance tracking. - */ - analytics?: boolean; - /** - * Consent for storing user preferences. - */ - preferences?: boolean; - /** - * Consent for marketing communications. - */ - marketing?: boolean; - /** - * Consent for selling data to third parties (CCPA). - */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionCreateRequest { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent1 { - /** - * Consent for analytics and performance tracking. - */ - analytics?: boolean; - /** - * Consent for storing user preferences. - */ - preferences?: boolean; - /** - * Consent for marketing communications. - */ - marketing?: boolean; - /** - * Consent for selling data to third parties (CCPA). - */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionUpdateRequest { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent2 { - /** - * Consent for analytics and performance tracking. - */ - analytics?: boolean; - /** - * Consent for storing user preferences. - */ - preferences?: boolean; - /** - * Consent for marketing communications. - */ - marketing?: boolean; - /** - * Consent for selling data to third parties (CCPA). - */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. - */ -export declare interface BuyerConsentExtensionResponse { - [k: string]: unknown; -} -/** - * User consent states for data processing - * - * This interface was referenced by `BuyerConsentExtensionResponse`'s JSON-Schema - * via the `definition` "consent". - */ -export declare interface Consent3 { - /** - * Consent for analytics and performance tracking. - */ - analytics?: boolean; - /** - * Consent for storing user preferences. - */ - preferences?: boolean; - /** - * Consent for marketing communications. - */ - marketing?: boolean; - /** - * Consent for selling data to third parties (CCPA). - */ - sale_of_data?: boolean; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionCompleteRequest { - [k: string]: unknown; -} -/** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "allocation". - */ -export declare interface Allocation { - /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). - */ - path: string; - /** - * Amount allocated to this target in minor (cents) currency units. - */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; - /** - * Total discount amount in minor (cents) currency units. - */ - amount: number; - /** - * True if applied automatically by merchant rules (no code required). - */ - automatic?: boolean; - /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. - */ - method?: 'each' | 'across'; - /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). - */ - priority?: number; - /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. - */ - allocations?: Allocation[]; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionCreateRequest { - [k: string]: unknown; -} -/** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "allocation". - */ -export declare interface Allocation1 { - /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). - */ - path: string; - /** - * Amount allocated to this target in minor (cents) currency units. - */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount1 { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; - /** - * Total discount amount in minor (cents) currency units. - */ - amount: number; - /** - * True if applied automatically by merchant rules (no code required). - */ - automatic?: boolean; - /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. - */ - method?: 'each' | 'across'; - /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). - */ - priority?: number; - /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. - */ - allocations?: Allocation1[]; - [k: string]: unknown; -} -/** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionCreateRequest`'s JSON-Schema - * via the `definition` "discounts_object". - */ -export declare interface DiscountsObject { - /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. - */ - codes?: string[]; - /** - * Discounts successfully applied (code-based and automatic). - */ - applied?: AppliedDiscount1[]; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionUpdateRequest { - [k: string]: unknown; -} -/** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "allocation". - */ -export declare interface Allocation2 { - /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). - */ - path: string; - /** - * Amount allocated to this target in minor (cents) currency units. - */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount2 { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; - /** - * Total discount amount in minor (cents) currency units. - */ - amount: number; - /** - * True if applied automatically by merchant rules (no code required). - */ - automatic?: boolean; - /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. - */ - method?: 'each' | 'across'; - /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). - */ - priority?: number; - /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. - */ - allocations?: Allocation2[]; - [k: string]: unknown; -} -/** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "discounts_object". - */ -export declare interface DiscountsObject1 { - /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. - */ - codes?: string[]; - /** - * Discounts successfully applied (code-based and automatic). - */ - applied?: AppliedDiscount2[]; - [k: string]: unknown; -} -/** - * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. - */ -export declare interface DiscountExtensionResponse { - [k: string]: unknown; -} -/** - * Breakdown of how a discount amount was allocated to a specific target. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "allocation". - */ -export declare interface Allocation3 { - /** - * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). - */ - path: string; - /** - * Amount allocated to this target in minor (cents) currency units. - */ - amount: number; - [k: string]: unknown; -} -/** - * A discount that was successfully applied. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "applied_discount". - */ -export declare interface AppliedDiscount3 { - /** - * The discount code. Omitted for automatic discounts. - */ - code?: string; - /** - * Human-readable discount name (e.g., 'Summer Sale 20% Off'). - */ - title: string; - /** - * Total discount amount in minor (cents) currency units. - */ - amount: number; - /** - * True if applied automatically by merchant rules (no code required). - */ - automatic?: boolean; - /** - * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. - */ - method?: 'each' | 'across'; - /** - * Stacking order for discount calculation. Lower numbers applied first (1 = first). - */ - priority?: number; - /** - * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. - */ - allocations?: Allocation3[]; - [k: string]: unknown; -} -/** - * Discount codes input and applied discounts output. - * - * This interface was referenced by `DiscountExtensionResponse`'s JSON-Schema - * via the `definition` "discounts_object". - */ -export declare interface DiscountsObject2 { - /** - * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. - */ - codes?: string[]; - /** - * Discounts successfully applied (code-based and automatic). + * Permalink to access the order on merchant site. */ - applied?: AppliedDiscount3[]; + permalink_url: string; [k: string]: unknown; } /** - * Extends Checkout with fulfillment support using methods, destinations, and groups. + * Extends Checkout with buyer consent tracking for privacy compliance via the buyer object. */ -export declare interface FulfillmentExtensionCompleteRequest { +export declare interface BuyerConsentExtension { [k: string]: unknown; } /** - * A fulfillment option within a group (e.g., Standard Shipping $5, Express $15). - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". + * User consent states for data processing * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_option". + * This interface was referenced by `BuyerConsentExtension`'s JSON-Schema + * via the `definition` "consent". */ -export declare interface FulfillmentOptionRequest { +export declare interface Consent { + /** + * Consent for analytics and performance tracking. + */ + analytics?: boolean; + /** + * Consent for storing user preferences. + */ + preferences?: boolean; + /** + * Consent for marketing communications. + */ + marketing?: boolean; + /** + * Consent for selling data to third parties (CCPA). + */ + sale_of_data?: boolean; [k: string]: unknown; } -/** - * A merchant-generated package/group of line items with fulfillment options. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". - */ -export declare interface FulfillmentGroupCompleteRequest { +export declare interface Buyer1 { /** - * Group identifier for referencing merchant-generated groups in updates. + * First name of the buyer. */ - id: string; + first_name?: string; /** - * ID of the selected fulfillment option for this group. + * Last name of the buyer. */ - selected_option_id?: string | null; + last_name?: string; + /** + * Email of the buyer. + */ + email?: string; + /** + * E.164 standard. + */ + phone_number?: string; [k: string]: unknown; } /** - * A fulfillment method (shipping or pickup) with destinations and groups. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". + * Shopping cart with estimated pricing before checkout. Lightweight pre-purchase exploration with no payment info or complex status states. Cart exists (200) or doesn't (404). */ -export declare interface FulfillmentMethodCompleteRequest { +export declare interface Cart { + ucp: UCPCartResponseSchema1; /** - * Unique fulfillment method identifier. + * Unique cart identifier. */ id: string; /** - * Fulfillment method type. + * Cart line items. Same structure as checkout. Full replacement on update. */ - type: 'shipping' | 'pickup'; + line_items: LineItem[]; + context?: Context1; + buyer?: Buyer2; /** - * Line item IDs fulfilled via this method. + * ISO 4217 currency code. Determined by merchant based on context or geo-IP. */ - line_item_ids: string[]; + currency: string; /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * Estimated cost breakdown. May be partial if shipping/tax not yet calculable. */ - destinations?: FulfillmentDestinationRequest[]; + totals: Total[]; /** - * ID of the selected destination. + * Validation messages, warnings, or informational notices. */ - selected_destination_id?: string | null; + messages?: Message[]; /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Optional merchant links (policies, FAQs). */ - groups?: FulfillmentGroupCompleteRequest[]; - [k: string]: unknown; -} -/** - * A pickup location (retail store, locker, etc.). - */ -export declare interface RetailLocationRequest { + links?: Link[]; /** - * Location name (e.g., store name). + * URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows. */ - name: string; - address?: PostalAddress; - [k: string]: unknown; -} -/** - * Inventory availability hint for a fulfillment method type. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_available_method". - */ -export declare interface FulfillmentAvailableMethodRequest { - [k: string]: unknown; -} -/** - * Container for fulfillment methods and availability. - * - * This interface was referenced by `FulfillmentExtensionCompleteRequest`'s JSON-Schema - * via the `definition` "fulfillment". - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment". - * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment". - */ -export declare interface FulfillmentRequest { + continue_url?: string; /** - * Fulfillment methods for cart items. + * Cart expiry timestamp (RFC 3339). Optional. */ - methods?: FulfillmentMethodCreateRequest[]; + expires_at?: string; [k: string]: unknown; } /** - * A fulfillment method (shipping or pickup) with destinations and groups. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". + * Provisional buyer signals for relevance and localization: product availability, pricing, currency, tax, shipping, payment methods, and eligibility (e.g., student or affiliation discounts). Businesses SHOULD use these values when authoritative data (e.g., address) is absent, and MAY ignore unsupported values without returning errors. Context can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context. Platforms SHOULD progressively enhance context throughout the buyer journey. */ -export declare interface FulfillmentMethodCreateRequest { +export declare interface Context1 { /** - * Fulfillment method type. + * The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value. */ - type: 'shipping' | 'pickup'; + address_country?: string; /** - * Line item IDs fulfilled via this method. + * The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value. */ - line_item_ids?: string[]; + address_region?: string; /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. */ - destinations?: FulfillmentDestinationRequest[]; + postal_code?: string; + [k: string]: unknown; +} +export declare interface Buyer2 { /** - * ID of the selected destination. + * First name of the buyer. */ - selected_destination_id?: string | null; + first_name?: string; /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Last name of the buyer. */ - groups?: FulfillmentGroupCreateRequest[]; - [k: string]: unknown; -} -/** - * A merchant-generated package/group of line items with fulfillment options. - * - * This interface was referenced by `FulfillmentExtensionCreateRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". - */ -export declare interface FulfillmentGroupCreateRequest { + last_name?: string; /** - * ID of the selected fulfillment option for this group. + * Email of the buyer. */ - selected_option_id?: string | null; - [k: string]: unknown; -} -/** - * Extends Checkout with fulfillment support using methods, destinations, and groups. - */ -export declare interface FulfillmentExtensionCreateRequest { + email?: string; + /** + * E.164 standard. + */ + phone_number?: string; [k: string]: unknown; } /** - * Extends Checkout with fulfillment support using methods, destinations, and groups. + * Extends Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes. */ -export declare interface FulfillmentExtensionUpdateRequest { +export declare interface DiscountExtension { [k: string]: unknown; } /** - * A merchant-generated package/group of line items with fulfillment options. + * Breakdown of how a discount amount was allocated to a specific target. * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_group". + * This interface was referenced by `DiscountExtension`'s JSON-Schema + * via the `definition` "allocation". */ -export declare interface FulfillmentGroupUpdateRequest { +export declare interface Allocation { /** - * Group identifier for referencing merchant-generated groups in updates. + * JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping'). */ - id: string; + path: string; /** - * ID of the selected fulfillment option for this group. + * Amount allocated to this target in minor (cents) currency units. */ - selected_option_id?: string | null; + amount: number; [k: string]: unknown; } /** - * A fulfillment method (shipping or pickup) with destinations and groups. + * A discount that was successfully applied. * - * This interface was referenced by `FulfillmentExtensionUpdateRequest`'s JSON-Schema - * via the `definition` "fulfillment_method". + * This interface was referenced by `DiscountExtension`'s JSON-Schema + * via the `definition` "applied_discount". */ -export declare interface FulfillmentMethodUpdateRequest { +export declare interface AppliedDiscount { /** - * Unique fulfillment method identifier. + * The discount code. Omitted for automatic discounts. */ - id: string; + code?: string; /** - * Line item IDs fulfilled via this method. + * Human-readable discount name (e.g., 'Summer Sale 20% Off'). */ - line_item_ids: string[]; + title: string; /** - * Available destinations. For shipping: addresses. For pickup: retail locations. + * Total discount amount in minor (cents) currency units. */ - destinations?: FulfillmentDestinationRequest[]; + amount: number; /** - * ID of the selected destination. + * True if applied automatically by merchant rules (no code required). */ - selected_destination_id?: string | null; + automatic?: boolean; /** - * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. + * Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value. + */ + method?: 'each' | 'across'; + /** + * Stacking order for discount calculation. Lower numbers applied first (1 = first). + */ + priority?: number; + /** + * Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount. + */ + allocations?: Allocation[]; + [k: string]: unknown; +} +/** + * Discount codes input and applied discounts output. + */ +export declare interface DiscountsObject { + /** + * Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear. */ - groups?: FulfillmentGroupUpdateRequest[]; + codes?: string[]; + /** + * Discounts successfully applied (code-based and automatic). + */ + applied?: AppliedDiscount[]; [k: string]: unknown; } /** * Extends Checkout with fulfillment support using methods, destinations, and groups. */ -export declare interface FulfillmentExtensionResponse { +export declare interface FulfillmentExtension { [k: string]: unknown; } /** * A fulfillment option within a group (e.g., Standard Shipping $5, Express $15). * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_option". */ -export declare interface FulfillmentOptionResponse { +export declare interface FulfillmentOption { /** * Unique fulfillment option identifier. */ @@ -1684,16 +1159,16 @@ export declare interface FulfillmentOptionResponse { /** * Fulfillment option totals breakdown. */ - totals: TotalResponse[]; + totals: Total[]; [k: string]: unknown; } /** * A merchant-generated package/group of line items with fulfillment options. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_group". */ -export declare interface FulfillmentGroupResponse { +export declare interface FulfillmentGroup { /** * Group identifier for referencing merchant-generated groups in updates. */ @@ -1705,7 +1180,7 @@ export declare interface FulfillmentGroupResponse { /** * Available fulfillment options for this group. */ - options?: FulfillmentOptionResponse[]; + options?: FulfillmentOption[]; /** * ID of the selected fulfillment option for this group. */ @@ -1715,10 +1190,10 @@ export declare interface FulfillmentGroupResponse { /** * A fulfillment method (shipping or pickup) with destinations and groups. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_method". */ -export declare interface FulfillmentMethodResponse { +export declare interface FulfillmentMethod { /** * Unique fulfillment method identifier. */ @@ -1734,7 +1209,7 @@ export declare interface FulfillmentMethodResponse { /** * Available destinations. For shipping: addresses. For pickup: retail locations. */ - destinations?: FulfillmentDestinationResponse[]; + destinations?: FulfillmentDestination[]; /** * ID of the selected destination. */ @@ -1742,13 +1217,13 @@ export declare interface FulfillmentMethodResponse { /** * Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method. */ - groups?: FulfillmentGroupResponse[]; + groups?: FulfillmentGroup[]; [k: string]: unknown; } /** * A pickup location (retail store, locker, etc.). */ -export declare interface RetailLocationResponse { +export declare interface RetailLocation { /** * Unique location identifier. */ @@ -1763,10 +1238,10 @@ export declare interface RetailLocationResponse { /** * Inventory availability hint for a fulfillment method type. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment_available_method". */ -export declare interface FulfillmentAvailableMethodResponse { +export declare interface FulfillmentAvailableMethod { /** * Fulfillment method type this availability applies to. */ @@ -1788,25 +1263,39 @@ export declare interface FulfillmentAvailableMethodResponse { /** * Container for fulfillment methods and availability. * - * This interface was referenced by `FulfillmentExtensionResponse`'s JSON-Schema + * This interface was referenced by `FulfillmentExtension`'s JSON-Schema * via the `definition` "fulfillment". */ -export declare interface FulfillmentResponse { +export declare interface Fulfillment { + /** + * Fulfillment methods for cart items. + */ + methods?: FulfillmentMethod[]; + /** + * Inventory availability hints. + */ + available_methods?: FulfillmentAvailableMethod[]; + [k: string]: unknown; +} +/** + * Container for fulfillment methods and availability. + */ +export declare interface Fulfillment1 { /** * Fulfillment methods for cart items. */ - methods?: FulfillmentMethodResponse[]; + methods?: FulfillmentMethod[]; /** * Inventory availability hints. */ - available_methods?: FulfillmentAvailableMethodResponse[]; + available_methods?: FulfillmentAvailableMethod[]; [k: string]: unknown; } /** * Order schema with immutable line items, buyer-facing fulfillment expectations, and append-only event logs. */ export declare interface Order { - ucp: UCPOrderResponse; + ucp: UCPOrderResponseSchema; /** * Unique order identifier. */ @@ -1844,21 +1333,7 @@ export declare interface Order { /** * Different totals for the order. */ - totals: TotalResponse[]; - [k: string]: unknown; -} -/** - * UCP metadata for order responses. No payment handlers needed post-purchase. - */ -export declare interface UCPOrderResponse { - /** - * UCP protocol version in YYYY-MM-DD format. - */ - version: string; - /** - * Active capabilities for this response. - */ - capabilities: CapabilityResponse[]; + totals: Total[]; [k: string]: unknown; } export declare interface OrderLineItem { @@ -1866,7 +1341,7 @@ export declare interface OrderLineItem { * Line item identifier. */ id: string; - item: ItemResponse; + item: Item; /** * Quantity tracking. Both total and fulfilled are derived from events. */ @@ -1884,7 +1359,7 @@ export declare interface OrderLineItem { /** * Line item totals breakdown. */ - totals: TotalResponse[]; + totals: Total[]; /** * Derived status: fulfilled if quantity.fulfilled == quantity.total, partial if quantity.fulfilled > 0, otherwise processing. */ @@ -2028,12 +1503,81 @@ export declare interface Adjustment { * Platform's order capability configuration. * * This interface was referenced by `Order`'s JSON-Schema - * via the `definition` "platform_config". + * via the `definition` "platform_schema". */ -export declare interface PlatformOrderConfig { +export declare interface PlatformOrderSchema { /** * URL where merchant sends order lifecycle events (webhooks). */ webhook_url: string; [k: string]: unknown; } +/** + * Payment configuration containing handlers. + */ +export declare interface Payment1 { + /** + * The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields. + */ + instruments?: SelectedPaymentInstrument[]; + [k: string]: unknown; +} +/** + * Base discovery profile with shared properties for all profile types. + */ +export declare interface Base1 { + ucp: Base; + /** + * Public keys for signature verification (JWK format). Used to verify signed responses, webhooks, and other authenticated messages from this party. + */ + signing_keys?: SigningKey[]; + [k: string]: unknown; +} +/** + * Public key for signature verification in JWK format. + */ +export declare interface SigningKey { + /** + * Key ID. Referenced in signature headers to identify which key to use for verification. + */ + kid: string; + /** + * Key type (e.g., 'EC', 'RSA'). + */ + kty: string; + /** + * Curve name for EC keys (e.g., 'P-256'). + */ + crv?: string; + /** + * X coordinate for EC public keys (base64url encoded). + */ + x?: string; + /** + * Y coordinate for EC public keys (base64url encoded). + */ + y?: string; + /** + * Modulus for RSA public keys (base64url encoded). + */ + n?: string; + /** + * Exponent for RSA public keys (base64url encoded). + */ + e?: string; + /** + * Key usage. Should be 'sig' for signing keys. + */ + use?: 'sig' | 'enc'; + /** + * Algorithm (e.g., 'ES256', 'RS256'). + */ + alg?: string; + [k: string]: unknown; +} +/** + * Embedded Protocol (EP) methods for UCP capabilities. Methods are sent from Merchant to Host via postMessage/JSON-RPC 2.0. Method prefixes indicate capability scope: ec.* (checkout). Future capabilities may define additional prefixes (e.g., eo.* for order). + */ +export declare interface EmbeddedProtocol { + [k: string]: unknown; +} \ No newline at end of file