Skip to content

portage-ucp-client

The client SDK — connect to somebody else's manifest, or drive your own Adapter, as the shopper's agent. Loopback/stdio/HTTP behind one interface; see the walkthrough for it in action.

portage-ucp-client

Client-side SDK for portage-ucp — the other direction from every adapter gem. Every adapter gem lets a Ruby program expose a commerce backend to agents (server side). This gem lets a Ruby program act as the shopper's agent: connect to somebody else's /.well-known/ucp manifest, or drive your own Adapter directly, and place an order as the client.

Four transports behind one Session interface — callers never know which they got:

Transport Use case
Portage::Ucp::Client.for_adapter(adapter) Loopback over an in-process Adapter — no subprocess, no socket. Still runs the real authenticator/rate-limiter/Dispatcher stack, just without the wire hop. For driving your own store's Adapter directly.
Portage::Ucp::Client.connect(command: ...) stdio, spawns a subprocess (an MCP server exe).
Portage::Ucp::Client.connect(url: ...) Streamable HTTP, connects to a remote MCP endpoint.
Portage::Ucp::Client.connect(url: ..., transport: :rest) UCP REST (2026-08-25's core transport), for stores that serve REST only.
Portage::Ucp::Client.discover(url) Fetches <url>/.well-known/ucp, parses the manifest, and connects to its mcp service, else its rest one — the entry point for buying from a store you've never talked to before. session.transport_name says which (:mcp or :rest).

Depends only on portage-ucp, the mcp gem's client half and faraday — no adapter gem is a dependency.

Installation

# Gemfile
gem "portage-ucp-client"
bundle install

Usage

require "portage/ucp"
require "portage/ucp/client"

# Discover and connect to a live store you've never talked to before:
session = Portage::Ucp::Client.discover("https://your-shop.example")
meta = { agent_profile: "https://example.com/agent-profile.json" } # required over HTTP

results = session.search_catalog(query: "snowboard", limit: 5, meta: meta) # string-keyed Hash, shaped by the store
product_id = "..." # pick from results
checkout = session.create_checkout(line_items: [{ product_id: product_id, quantity: 1 }], meta: meta)
completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: "spt_1a2b3c...", meta: meta)
order = session.get_order(order_id: "gid://shopify/Order/9001", meta: meta)

Session generates an idempotency_key for you on every mutating call unless you pass your own — retrying with the same key replays the cached result instead of double-charging.

See the detailed walkthrough for the full runnable example (via the loopback transport) including requires_escalation handling and RawPanRejectedError, and portage-cli for a ready-made portage buy <url> command built on top of this gem.

Development

bundle exec rspec
bundle exec rubocop

License

MIT — Copyright (c) 2026 Tom Whitbread.