portage-ucp 0.1.0

data/schemas/2026-04-08/services/shopping/embedded.openrpc.json

@@ -0,0 +1,634 @@
+{
+  "openrpc": "1.3.2",
+  "info": {
+    "title": "UCP Shopping Embedded Protocol",
+    "description": "Embedded Protocol (EP) methods for the UCP shopping service. Methods are sent from Merchant to Host via postMessage using JSON-RPC 2.0. Method prefixes indicate capability scope: ep.{capability} (i.e. ep.checkout). Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\nEmbedded Protocol is a client-to-client postMessage interface, so there is no endpoint URL to access this API. Platforms detect merchant support for this protocol based on the presence of `services[\"dev.ucp.shopping\"][transport=embedded]` in discovery responses.",
+    "version": "2026-04-08"
+  },
+  "servers": [],
+  "methods": [
+    {
+      "name": "ec.ready",
+      "summary": "Handshake from merchant to host",
+      "description": "Initiates the Embedded Checkout Protocol. Merchant declares which delegations it accepts and requests any additional authorization, host responds with optional channel upgrade, auth credential, and initial checkout state.",
+      "params": [
+        {
+          "name": "delegate",
+          "required": true,
+          "schema": {
+            "type": "array",
+            "description": "Delegation types the merchant accepts. Must be subset of checkout.embedded.delegations.",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
+            },
+            "uniqueItems": true
+          }
+        },
+        {
+          "name": "auth",
+          "schema": {
+            "$ref": "#/components/schemas/auth"
+          }
+        }
+      ],
+      "result": {
+        "name": "readyResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Handshake response from host.",
+              "required": [
+                "ucp"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "upgrade": {
+                  "type": "object",
+                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
+                  "properties": {
+                    "port": {
+                      "type": "object",
+                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
+                    }
+                  }
+                },
+                "credential": {
+                  "type": "string",
+                  "description": "Requested authorization. Some common examples include API key and OAuth token."
+                },
+                "checkout": {
+                  "type": "object",
+                  "description": "Initial delegation state from host. Fields are permitted only when the corresponding delegation is accepted.",
+                  "properties": {
+                    "payment": {
+                      "$ref": "#/components/schemas/payment_instrument_selection"
+                    },
+                    "fulfillment": {
+                      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment.json"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ec.auth",
+      "summary": "Authorization exchange between host & business.",
+      "description": "Augments Embedded Checkout Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
+      "params": [
+        {
+          "name": "type",
+          "schema": {
+            "$ref": "#/components/schemas/type"
+          }
+        }
+      ],
+      "result": {
+        "name": "authResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Auth response from host containing the requested authorization data.",
+              "required": [
+                "ucp",
+                "credential"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "credential": {
+                  "type": "string",
+                  "description": "Requested authorization. Some common examples include API key and OAuth token."
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ec.error",
+      "summary": "A session-level error has occurred.",
+      "description": "Business notifies host that a session-level error, unrelated to the checkout resource, has occurred.",
+      "params": [
+        {
+          "name": "error",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json",
+            "description": "Session-level error raised by the business."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.start",
+      "summary": "Checkout visible to buyer",
+      "description": "Merchant notifies host that checkout UI is visible and ready for interaction. Sent after successful ec.ready handshake.",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.complete",
+      "summary": "Checkout completed successfully",
+      "description": "Merchant notifies host that order has been placed successfully.",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Final checkout state."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.messages.change",
+      "summary": "Checkout messages changed",
+      "description": "Merchant notifies host that checkout.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with updated messages."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.line_items.change",
+      "summary": "Line items changed",
+      "description": "Merchant notifies host that checkout.line_items has changed (item added, removed, quantity updated).",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with updated line items."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.buyer.change",
+      "summary": "Buyer information changed",
+      "description": "Merchant notifies host that checkout.buyer has changed (email, phone, address updated).",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with updated buyer."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.totals.change",
+      "summary": "Checkout totals changed",
+      "description": "Merchant notifies host that checkout.totals has changed. Covers all total line updates including taxes, fees, discounts, and fulfillment costs. For changes that also affect a specific domain (e.g., fulfillment cost update), this message MUST be sent after the domain-specific change message (e.g., ec.fulfillment.change).",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with updated totals."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.payment.change",
+      "summary": "Payment state changed",
+      "description": "Merchant notifies host that checkout.payment has changed (instrument selected, status updated).",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with updated payment."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ec.payment.instruments_change_request",
+      "summary": "Request payment instrument change",
+      "description": "Merchant requests host to present payment instrument selection UI for the buyer to change their payment method.",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state."
+          }
+        }
+      ],
+      "result": {
+        "name": "instrumentsChangeResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Checkout state after instrument selection.",
+              "required": [
+                "ucp",
+                "checkout"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "checkout": {
+                  "type": "object",
+                  "description": "Partial checkout update with payment instrument selection.",
+                  "properties": {
+                    "payment": {
+                      "$ref": "#/components/schemas/payment_instrument_selection"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ec.payment.credential_request",
+      "summary": "Request payment credential",
+      "description": "Merchant requests host to collect payment credential for selected instrument (CVV, 3DS, wallet confirmation).",
+      "params": [
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json",
+            "description": "Current checkout state with selected instrument."
+          }
+        }
+      ],
+      "result": {
+        "name": "credentialResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Checkout state with payment credential ready for completion.",
+              "required": [
+                "ucp",
+                "checkout"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "checkout": {
+                  "type": "object",
+                  "description": "Partial checkout update with payment credential.",
+                  "properties": {
+                    "payment": {
+                      "$ref": "#/components/schemas/payment_instruments"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ec.window.open_request",
+      "summary": "Request window open",
+      "description": "The buyer activated a link within checkout. The host MUST present the content to the buyer and respond with a success result, or respond with a window_open_rejected_error error if host policy prevented the navigation.",
+      "params": [
+        {
+          "name": "url",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL of the resource to present."
+          }
+        }
+      ],
+      "result": {
+        "name": "windowOpenResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Acknowledgement that the host handled the request.",
+              "required": [
+                "ucp"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.change"
+    },
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/fulfillment.json#/embedded/methods/ec.fulfillment.address_change_request"
+    },
+    {
+      "name": "ep.cart.ready",
+      "summary": "Handshake from business to host",
+      "description": "Initiates the Embedded Cart Protocol. Business declares which delegation it supports and requests any additional authorization, host responds with optional channel upgrade and auth credential.",
+      "params": [
+        {
+          "name": "delegate",
+          "required": true,
+          "schema": {
+            "type": "array",
+            "description": "Delegation types the merchant accepts.",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z_]+(?:\\.[a-z_]+)*$"
+            },
+            "uniqueItems": true
+          }
+        },
+        {
+          "name": "auth",
+          "schema": {
+            "$ref": "#/components/schemas/auth"
+          }
+        }
+      ],
+      "result": {
+        "name": "readyResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Handshake response from host.",
+              "required": [
+                "ucp"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "upgrade": {
+                  "type": "object",
+                  "description": "Channel upgrade instructions. If present, switch to provided MessagePort.",
+                  "properties": {
+                    "port": {
+                      "type": "object",
+                      "description": "MessagePort for upgraded channel. Runtime type is MessagePort."
+                    }
+                  }
+                },
+                "credential": {
+                  "type": "string",
+                  "description": "Requested authorization. Some common examples include API key and OAuth token."
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ep.cart.auth",
+      "summary": "Authorization exchange between host & business.",
+      "description": "Augments Embedded Cart Protocol by doing auth exchanges per business requirement. Can be used by business to refresh a previously exchanged authorization.",
+      "params": [
+        {
+          "name": "type",
+          "schema": {
+            "$ref": "#/components/schemas/type"
+          }
+        }
+      ],
+      "result": {
+        "name": "authResult",
+        "schema": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Auth response from host containing the requested authorization data.",
+              "required": [
+                "ucp",
+                "credential"
+              ],
+              "properties": {
+                "ucp": {
+                  "$ref": "#/components/schemas/ucp_success"
+                },
+                "credential": {
+                  "type": "string",
+                  "description": "Requested authorization. Some common examples include API key and OAuth token."
+                }
+              }
+            },
+            {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "ep.cart.error",
+      "summary": "A session-level error has occurred.",
+      "description": "Business notifies host that a session-level error, unrelated to the cart resource, has occurred.",
+      "params": [
+        {
+          "name": "error",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json",
+            "description": "Session-level error raised by the business."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ep.cart.start",
+      "summary": "Cart visible to buyer",
+      "description": "Business notifies host that cart UI is visible and ready for interaction.",
+      "params": [
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+            "description": "Current cart state."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ep.cart.complete",
+      "summary": "Cart completed successfully",
+      "description": "Business notifies host that cart building has completed.",
+      "params": [
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+            "description": "Final cart state."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ep.cart.line_items.change",
+      "summary": "Line items changed",
+      "description": "Business notifies host that cart.line_items has changed (item added, removed, quantity updated).",
+      "params": [
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+            "description": "Current cart state with updated line items."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ep.cart.buyer.change",
+      "summary": "Buyer information changed",
+      "description": "Business notifies host that cart.buyer has changed (email, phone, name updated).",
+      "params": [
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+            "description": "Current cart state with updated buyer."
+          }
+        }
+      ]
+    },
+    {
+      "name": "ep.cart.messages.change",
+      "summary": "Cart messages changed",
+      "description": "Business notifies host that cart.messages has changed. Includes errors, warnings, and info. Host should update UI accordingly.",
+      "params": [
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+            "description": "Current cart state with updated messages."
+          }
+        }
+      ]
+    }
+  ],
+  "components": {
+    "schemas": {
+      "ucp_success": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/success"
+      },
+      "payment_instruments": {
+        "type": "object",
+        "description": "Payment instruments from host.",
+        "properties": {
+          "instruments": {
+            "type": "array",
+            "items": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json#/$defs/selected_payment_instrument"
+            },
+            "description": "Available payment instruments."
+          }
+        }
+      },
+      "payment_instrument_selection": {
+        "description": "Payment instruments with selected instrument ID.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/payment_instruments"
+          },
+          {
+            "properties": {
+              "selected_instrument_id": {
+                "type": "string",
+                "description": "ID of the selected payment instrument."
+              }
+            }
+          }
+        ]
+      },
+      "type": {
+        "type": "string",
+        "description": "The type of authorization data business is requesting from the host.",
+        "examples": [
+          "oauth",
+          "api_key",
+          "jwt"
+        ]
+      },
+      "auth": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/type"
+          }
+        }
+      }
+    }
+  },
+  "x-delegations": [
+    "payment.instruments_change",
+    "payment.credential",
+    "fulfillment.address_change",
+    "window.open"
+  ]
+}