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¶
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¶
License¶
MIT — Copyright (c) 2026 Tom Whitbread.