portage-ucp-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96ae3a5da5ef868663d2b296539ef3812249479031f6237f0c4dbb5679dda268
+  data.tar.gz: 7b132dc0d5c2152a2bba93db9629e5c897331a5360d95894cc84028fb9052ee9
+SHA512:
+  metadata.gz: 88439c696a4d6c6b4ead359c4b463b00fc07f02e811774096e745d7e95880b45b67ec3d948c5beffea0f0bd56456834305c774cc4d2b0a7281846840fd526bc3
+  data.tar.gz: d0965725d9e6914ae0bd19a0f2e8acabd182c943d01d0cb810458e3edc9d9d3001cf67bea1931eca3258b0315f32328e47b156a752c5f935bc07772d1ac9d0b3

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
+pre-1.0, so APIs may still shift between minor versions.
+
+## [0.1.0] - Unreleased
+
+- Initial pre-release. Client-side SDK — loopback, stdio, and Streamable HTTP
+  transports behind one `Session` interface.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# portage-ucp-client
+
+Client-side SDK for [`portage-ucp`](https://github.com/tomtom87/Portage/tree/main/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.
+
+Three 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.discover(url)` | Fetches `<url>/.well-known/ucp`, parses the manifest, and connects to whatever transport it advertises — the entry point for buying from a store you've never talked to before. |
+
+Depends only on `portage-ucp` and the `mcp` gem's client half — no adapter gem is
+a dependency.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-client"
+```
+
+```bash
+bundle install
+```
+
+## Usage
+
+```ruby
+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")
+
+products = session.search_catalog(query: "snowboard", limit: 5)
+checkout = session.create_checkout(line_items: [{ product_id: products.first.id, quantity: 1 }])
+completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: "spt_1a2b3c...")
+order = session.get_order(order_id: "gid://shopify/Order/9001")
+```
+
+`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](https://github.com/tomtom87/Portage/blob/main/docs/walkthrough.md)
+for the full runnable example (via the loopback transport) including
+`requires_escalation` handling and `RawPanRejectedError`, and
+[`portage-cli`](https://github.com/tomtom87/Portage/tree/main/portage-cli) for a
+ready-made `portage buy <url>` command built on top of this gem.
+
+## Development
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/lib/portage/ucp/client/errors.rb

@@ -0,0 +1,19 @@
+module Portage
+  module Ucp
+    module Client
+      # Base class for every error this gem raises.
+      class Error < StandardError; end
+
+      # Raised when a tool call's JSON-RPC response comes back with
+      # `isError: true` — e.g. an AuthenticationError/RateLimitExceededError/
+      # RawPanRejectedError the server side surfaced. `#message` is the text
+      # content the server returned, not a generic string.
+      class ServerError < Error; end
+
+      # Raised by .discover when the manifest can't be fetched/parsed, or has
+      # no `services` entry for the mcp transport to connect to (see
+      # Portage::Ucp::Manifest#services — the core-gem fix this depends on).
+      class DiscoveryError < Error; end
+    end
+  end
+end

data/lib/portage/ucp/client/session.rb

@@ -0,0 +1,90 @@
+require "securerandom"
+
+module Portage
+  module Ucp
+    module Client
+      # Caller-facing object returned by Client.for_adapter/.connect/.discover
+      # — same convenience method names as the merchant-side
+      # Portage::Ucp::Adapter, regardless of which transport is underneath
+      # (loopback/stdio/HTTP; callers never know which they got).
+      #
+      # Generates an `idempotency_key` per mutating call unless the caller
+      # supplies one, and runs PaymentTokenGuard client-side before a
+      # payment_token goes out over complete_checkout — belt-and-suspenders
+      # with the merchant's own guard (§9), not a replacement for it.
+      #
+      # A Checkout/Order response with `status == "requires_escalation"` is
+      # returned normally, with its `links`, not raised as an error — callers
+      # must branch on it themselves.
+      class Session
+        MUTATING_ACTIONS = %w[create_cart update_cart cancel_cart create_checkout update_checkout
+                              complete_checkout cancel_checkout].freeze
+
+        # @param capabilities [Array<String>, nil] reverse-domain capability
+        #   names advertised by the server, when known upfront (Client.discover
+        #   populates this from the manifest; Client.for_adapter/.connect leave
+        #   it nil since nothing was fetched to populate it from).
+        def initialize(transport:, capabilities: nil)
+          @transport = transport
+          @capabilities = capabilities
+        end
+
+        attr_reader :capabilities
+
+        # @return [Boolean, nil] nil when capabilities weren't known upfront
+        #   (see #capabilities) — callers with a nil result can't tell either
+        #   way and should just attempt the call.
+        def advertises?(capability_name)
+          capabilities&.include?(capability_name)
+        end
+
+        def search_catalog(query:, limit: 20) = call("search_catalog", query: query, limit: limit)
+        def get_product(product_id:) = call("get_product", product_id: product_id)
+
+        def get_cart(cart_id:) = call("get_cart", cart_id: cart_id)
+
+        def create_cart(line_items:, idempotency_key: nil)
+          call("create_cart", line_items: line_items, idempotency_key: idempotency_key)
+        end
+
+        def update_cart(cart_id:, line_items:, idempotency_key: nil)
+          call("update_cart", cart_id: cart_id, line_items: line_items, idempotency_key: idempotency_key)
+        end
+
+        def cancel_cart(cart_id:, idempotency_key: nil)
+          call("cancel_cart", cart_id: cart_id, idempotency_key: idempotency_key)
+        end
+
+        def create_checkout(line_items:, idempotency_key: nil)
+          call("create_checkout", line_items: line_items, idempotency_key: idempotency_key)
+        end
+
+        def get_checkout(checkout_id:) = call("get_checkout", checkout_id: checkout_id)
+
+        def update_checkout(checkout_id:, line_items:, idempotency_key: nil)
+          call("update_checkout", checkout_id: checkout_id, line_items: line_items, idempotency_key: idempotency_key)
+        end
+
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key: nil)
+          Portage::Ucp::PaymentTokenGuard.validate!(payment_token)
+          call("complete_checkout", checkout_id: checkout_id, payment_token: payment_token,
+                                    idempotency_key: idempotency_key)
+        end
+
+        def cancel_checkout(checkout_id:, idempotency_key: nil)
+          call("cancel_checkout", checkout_id: checkout_id, idempotency_key: idempotency_key)
+        end
+
+        def get_order(order_id:) = call("get_order", order_id: order_id)
+        def link_identity(oauth_token:) = call("link_identity", oauth_token: oauth_token)
+
+        private
+
+        def call(action, **arguments)
+          arguments[:idempotency_key] ||= SecureRandom.uuid if MUTATING_ACTIONS.include?(action)
+          @transport.call_tool(name: action, arguments: arguments)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/tool_result.rb

@@ -0,0 +1,29 @@
+module Portage
+  module Ucp
+    module Client
+      # Normalizes a tools/call JSON-RPC response into either the tool's
+      # structuredContent, or a raised ServerError — shared across transports
+      # since the loopback transport gets a symbol-keyed response (no JSON
+      # round-trip, see Transports::Loopback) while stdio/HTTP get a
+      # string-keyed one (real wire JSON, parsed by the `mcp` gem's client).
+      module ToolResult
+        def self.extract(response, symbol_keys:)
+          result = fetch(response, "result", symbol_keys) || {}
+          content = fetch(result, "content", symbol_keys)
+          raise ServerError, text(content, symbol_keys: symbol_keys) if fetch(result, "isError", symbol_keys)
+
+          fetch(result, "structuredContent", symbol_keys)
+        end
+
+        def self.text(content, symbol_keys:)
+          Array(content).filter_map { |block| fetch(block, "text", symbol_keys) }.join(" ")
+        end
+
+        def self.fetch(hash, key, symbol_keys)
+          hash[symbol_keys ? key.to_sym : key]
+        end
+        private_class_method :fetch
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/transports/http.rb

@@ -0,0 +1,23 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Connects to a UCP/MCP server over Streamable HTTP via the official
+        # `mcp` gem's client half (MCP::Client + MCP::Client::HTTP). Performs
+        # the `initialize` handshake eagerly so a caller's first real call
+        # doesn't pay for it.
+        class Http
+          def initialize(url:, headers: {})
+            @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
+            @client.connect
+          end
+
+          def call_tool(name:, arguments:)
+            response = @client.call_tool(name: name, arguments: arguments)
+            ToolResult.extract(response, symbol_keys: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/transports/loopback.rb

@@ -0,0 +1,29 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Wraps a Portage::Ucp::Mcp::Server built directly from an Adapter —
+        # no subprocess, no socket. This still runs the exact request a real
+        # server would handle over stdio/HTTP (authenticator, rate limiter,
+        # Dispatcher, WireEnvelope — see Portage::Ucp::Mcp::Server.build), it
+        # just skips the wire hop. This is what makes the
+        # merchant-buys-from-their-own-store case, and specs/examples that
+        # want a full buy cycle, possible without two processes.
+        class Loopback
+          def initialize(adapter:, **server_opts)
+            @server = Portage::Ucp::Mcp::Server.build(adapter: adapter, **server_opts)
+            @next_id = 0
+          end
+
+          def call_tool(name:, arguments:)
+            @next_id += 1
+            response = @server.handle(
+              { jsonrpc: "2.0", id: @next_id, method: "tools/call", params: { name: name, arguments: arguments } }
+            )
+            ToolResult.extract(response, symbol_keys: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/transports/stdio.rb

@@ -0,0 +1,23 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Connects to a UCP/MCP server over stdio — a subprocess speaking
+        # JSON-RPC on stdin/stdout — via the official `mcp` gem's client half
+        # (MCP::Client + MCP::Client::Stdio). Performs the `initialize`
+        # handshake eagerly so a caller's first real call doesn't pay for it.
+        class Stdio
+          def initialize(command:, args: [], env: nil)
+            @client = ::MCP::Client.new(transport: ::MCP::Client::Stdio.new(command: command, args: args, env: env))
+            @client.connect
+          end
+
+          def call_tool(name:, arguments:)
+            response = @client.call_tool(name: name, arguments: arguments)
+            ToolResult.extract(response, symbol_keys: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/version.rb

@@ -0,0 +1,7 @@
+module Portage
+  module Ucp
+    module Client
+      VERSION = "0.1.0".freeze
+    end
+  end
+end

data/lib/portage/ucp/client.rb

@@ -0,0 +1,88 @@
+require "net/http"
+require "uri"
+require "json"
+require "mcp"
+require "portage/ucp"
+
+require_relative "client/version"
+require_relative "client/errors"
+require_relative "client/tool_result"
+require_relative "client/session"
+require_relative "client/transports/loopback"
+require_relative "client/transports/stdio"
+require_relative "client/transports/http"
+
+module Portage
+  module Ucp
+    # Client-side counterpart to the rest of portage-ucp: everything else in
+    # this repo lets a Ruby program *expose* a commerce backend to agents
+    # (server side). This gem lets a Ruby program *act as* the shopper's
+    # agent — discover somebody else's manifest, or drive an owner's own
+    # Adapter directly, and place an order.
+    module Client
+      MANIFEST_PATH = "/.well-known/ucp".freeze
+
+      # Wraps an already-built Adapter directly — no subprocess/socket. Still
+      # runs the real merchant-side contract (authenticator, rate limiter,
+      # Dispatcher, WireEnvelope, via Portage::Ucp::Mcp::Server), just
+      # in-process. This is the transport for the "your own store" case: you
+      # already have credentials for this Adapter, so there's no manifest to
+      # discover and no wire hop to make.
+      def self.for_adapter(adapter, **server_opts)
+        Session.new(transport: Transports::Loopback.new(adapter: adapter, **server_opts))
+      end
+
+      # Connects over stdio (a subprocess) or Streamable HTTP (a URL) — pass
+      # exactly one of `command:` or `url:`.
+      def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil)
+        transport = if command
+                      Transports::Stdio.new(command: command, args: args, env: env)
+                    elsif url
+                      Transports::Http.new(url: url, headers: headers)
+                    else
+                      raise ArgumentError, "connect requires either command: or url:"
+                    end
+        Session.new(transport: transport, capabilities: capabilities)
+      end
+
+      # GETs `<url>/.well-known/ucp`, parses the manifest, and connects to the
+      # `mcp`-transport endpoint it advertises in `services` (see
+      # Portage::Ucp::Manifest#services — the core-gem fix this client
+      # depends on to know where to connect).
+      # @return [Session] scoped to the manifest's advertised capabilities.
+      def self.discover(url)
+        manifest = fetch_manifest(url)
+        connect(url: mcp_endpoint(manifest), capabilities: capability_names(manifest))
+      end
+
+      def self.fetch_manifest(url)
+        uri = URI.parse("#{url.to_s.sub(%r{/\z}, '')}#{MANIFEST_PATH}")
+        response = Net::HTTP.get_response(uri)
+        raise DiscoveryError, "GET #{uri} returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise DiscoveryError, "manifest at #{url} is not valid JSON: #{e.message}"
+      rescue DiscoveryError
+        raise
+      rescue StandardError => e
+        raise DiscoveryError, "couldn't reach #{url}: #{e.class}: #{e.message}"
+      end
+      private_class_method :fetch_manifest
+
+      def self.mcp_endpoint(manifest)
+        service = Array(manifest["services"]).find { |s| s["transport"] == "mcp" }
+        endpoint = service && service["endpoint"]
+        raise DiscoveryError, "manifest has no mcp service entry to connect to" unless endpoint
+
+        endpoint
+      end
+      private_class_method :mcp_endpoint
+
+      def self.capability_names(manifest)
+        Array(manifest["capabilities"]).map { |c| c["name"] }
+      end
+      private_class_method :capability_names
+    end
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: portage-ucp-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Whitbread
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: portage-ucp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'Every other portage-ucp gem lets a Ruby program expose a commerce backend
+  to agents (server side). This gem is the other direction: connect to somebody else''s
+  /.well-known/ucp manifest, or drive your own Adapter directly, and place an order
+  as the client. Three transports behind one interface (loopback over an in-process
+  Adapter, stdio, Streamable HTTP) — callers never know which they got. Depends only
+  on portage-ucp + the mcp gem''s client half; no adapter gem is a dependency.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/portage/ucp/client.rb
+- lib/portage/ucp/client/errors.rb
+- lib/portage/ucp/client/session.rb
+- lib/portage/ucp/client/tool_result.rb
+- lib/portage/ucp/client/transports/http.rb
+- lib/portage/ucp/client/transports/loopback.rb
+- lib/portage/ucp/client/transports/stdio.rb
+- lib/portage/ucp/client/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-client/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Client-side SDK for portage-ucp — act as the shopper's agent against any
+  UCP/MCP server
+test_files: []