feat(cart): Embedded protocol transport binding for cart capability

[jingyli]

Reopening the PR to avoid recreating the working-draft branch. This is a mirror copy of #109 and will also cross-reference/carry-over comments from the old PR.

Summary

Cart capability (dev.ucp.shopping.cart) is being introduced in #73. This adds an additional transport binding (EP) on the capability (building directly upon the referenced PR), on top of existing REST & MCP bindings.

Motivation

Businesses need a way to embed their cart building UI into eligible platforms, especially when complex experiences (i.e. item recommendations & upsells) are involved during cart building. Embedded Cart Protocol (ECaP) addresses this need and also offers a seamless connection to existing Embedded Checkout Protocol to continue the purchase experience.

Goals

• Enable businesses to embed cart UI into eligible hosts in a secure manner, especially if identity linking is a required pre-requisite for the flow.
• Provide seamless transition between embedded protocols to enable cart-to-checkout conversions.
• Maintain general schema & design consistency with existing ECP (i.e. reuse naming conventions, message types, etc.)
  • There remains some fundamental design differences in the design (i.e. host-initiated notification to share required authorization data, change requests that require host responses, etc.)

Non-Goals

• Support for extensions (i.e. fulfillment) on top of cart capability in the embedded protocol.
  • This is because extensions are out-of-scope in feat(cart): Cart capability for basket building #73

Detailed Design

Key methods supported by ECaP:

Category	Communication Direction	Purpose	Pattern	Core Messages
Handshake	Embedded Cart -> Host	Establish connection between host and Embedded Cart.	Request	ect.ready
Authentication	Host -> Embedded Cart	Inform any additional auth data required by Embedded Cart from host.	Notification	ect.auth
Lifecycle	Embedded Cart -> Host	Inform of cart state transitions.	Notification	ect.start, ect.transition.checkout
State Change	Embedded Cart -> Host	Inform of cart field changes.	Notification	ect.line_items.change, ect.buyer.change, ect.context.change, ect.messages.change
State Change	Embedded Cart -> Host	Inform of cart field changes but also require host input.	Request	ect.line_items.change_request

Protocol transition

• Introducing a new message type: [protocol namespace].transition.[capability transitioning to] that can be generally extended if conversions between multiple capabilities are possible.
  • First use case we are introducing is ect.transition.checkout that would denote a cart transitioning to a checkout session on the business's iframe.

Risks and Mitigations

• Complexity: ECaP introduces another transport mechanism to implement & support. Mitigation: Not all businesses need to support it as part of its services advertisement. Also structurally it's also very similar to ECP so businesses already supporting ECP should be familiar with the design already.
• Security: Introduced new host-initiated notification mechanism ect.auth to exchange required authorization data instead of adding them as query parameters in continue_url to avoid hijacking attacks.
• Backward Compatibility: None, new transport binding on a new capability.
• Schema Drift: Not introducing any new schemas, only new methods that utilizes existing schema components.

Graduation Criteria

Working Draft → Candidate:

• Schema merged and documented (with Working Draft disclaimer).
• Unit and integration tests are passing.
• Initial documentation is written.
• TC majority vote to advance.

Candidate → Stable:

• Adoption feedback has been collected and addressed.
• Full documentation and migration guides are published.
• TC majority vote to advance.

Implementation History

TBD