portage-ucp-client 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89837fec9676ad52dd925e44ea86b12df99ae2f01ea56eccd4b877bbde7dfb7a
-  data.tar.gz: 34e0f987ba86fb975eaed185950cc6c2690c3f177ae8eacbbdb718560be4fb5e
+  metadata.gz: a1a9cbc441c1893347b4f899fe968932fb297f626285f37d848d65d2ca91e749
+  data.tar.gz: 0455b81249ce937ccbc88fb3ee19cf5590e1b0c94a187490ffb35116863bbf72
 SHA512:
-  metadata.gz: 99581702b0ff34ed5a8fd680ffac05a05576823a6381bf312b63436107fb55977be865f7649be32827b3503b28465e3a862df9730058fe7ba4033179acd28505
-  data.tar.gz: db7d14a2a8149ca8b526ab4fc0ee6f6f807cad84b83eb57229879659e75e5d13207f96faada575354da1981fb78bc2a1de72edc98c38405a81a5efc3ddcfa7e1
+  metadata.gz: 0ef87e49709386c5f6f05ac388526ef9df1bedf8f7f2d5e6609a26b769d2ba3c9f56d5e4160e03eced891f502a55c795c340ffd17d09b694c8f4fe5d8ee81bb7
+  data.tar.gz: 712af022a1faea02752ba88b2023e34ec893bf567d6f8d2cc237ccf15981994fb7f85bee20124368369f4984c43699ca011b2d4af194ed308fc128a3dd46d0af

data/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.
 
+## [Unreleased]
+
+## [0.7.0] - 2026-10-22
+
+- **Changed: requires `mcp` `~> 1.8`** (was `~> 0.24`), which serves MCP 2026-07-28 through `server/discover` and keeps `initialize` for 2025-11-25 and earlier. Minor bump because the `mcp` requirement moved from 0.x to 1.x; no API change and no changes under `lib/`. `portage-ucp` stays at `~> 0.8`: the client calls nothing newer, and the shared `mcp` `~> 1.8` requirement makes resolution pick `portage-ucp` 0.17.0 or later.
+- Documentation only, no code change. Fixes a wrong comment on
+  `Client.ucp_section`. It said `Portage::Ucp::Manifest` still emits the old
+  flat manifest shape. It hasn't since `portage-ucp` 0.8.0, which nests
+  everything under `ucp` like live Shopify stores do. The flat fallback
+  stays, and the comment now says why: a store may still serve a manifest
+  from an older `portage-ucp`.
+
+## [0.6.3] - 2026-09-24
+
+- `Client.connect(url:, proxy:)` and `Client.discover(url, proxy:)` take a
+  `proxy:` option (a URL string, Hash or `URI`), passed straight to
+  Faraday's own `proxy=` on the Streamable HTTP transport. Faraday already
+  reads the env proxy vars itself; this adds an explicit override.
+- Every store-facing request now identifies itself: `Client::USER_AGENT`
+  (`"portage-ucp-client/<ver> (+https://github.com/tomtom87/Portage)"`) is
+  sent on the manifest GET and every UCP transport call, via
+  `Client.with_user_agent(headers)`. A caller's own `User-Agent` header
+  still wins (case-insensitive). `discover(url, headers: {})` now forwards
+  `headers` to both the manifest GET and the transport it builds.
+  `Transports::Http` merges the UA into its `MCP::Client::HTTP` headers.
+
 ## [0.6.2] - 2026-09-23
 
 - Fix: the loopback and stdio transports dropped `cart_id` from every call,

data/README.md

@@ -15,7 +15,7 @@ got:
 | `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. |
+| `Portage::Ucp::Client.discover(url)` | Fetches `<url>/.well-known/ucp`, parses the manifest, and connects to its `mcp` service — 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.
@@ -39,11 +39,13 @@ 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
 
-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")
+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

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

@@ -25,8 +25,20 @@ module Portage
         class Http
           include UcpWireShape
 
-          def initialize(url:, headers: {})
-            @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
+          # @param proxy [String, Hash, URI, nil] docs/plans/proxy-support.md
+          #   Phase 1's "lighter touch" for this gem: Faraday already reads
+          #   the env proxy vars itself (`Faraday.ignore_env_proxy` is
+          #   false) and accepts a `proxy:` connection option, so this just
+          #   wires that option through rather than reimplementing Faraday's
+          #   own proxy handling. Accepts anything
+          #   `Faraday::Connection#proxy=`/`Faraday::ProxyOptions.from`
+          #   accepts — a bare URL string is the common case.
+          def initialize(url:, headers: {}, proxy: nil)
+            @client = ::MCP::Client.new(
+              transport: ::MCP::Client::HTTP.new(url: url, headers: Client.with_user_agent(headers)) do |faraday|
+                faraday.proxy = proxy if proxy
+              end
+            )
             @client.connect
           end
 

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

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

data/lib/portage/ucp/client.rb

@@ -22,6 +22,11 @@ module Portage
     # Adapter directly, and place an order.
     module Client
       MANIFEST_PATH = "/.well-known/ucp".freeze
+      # Sent on every request this gem makes to a store (the manifest GET and
+      # each Streamable HTTP call) unless the caller's own headers name one,
+      # so a merchant reading its logs can tell a Portage agent from Ruby's
+      # or Faraday's default and find out what it is.
+      USER_AGENT = "portage-ucp-client/#{VERSION} (+https://github.com/tomtom87/Portage)".freeze
 
       # Wraps an already-built Adapter directly — no subprocess/socket. Still
       # runs the real merchant-side contract (authenticator, rate limiter,
@@ -35,11 +40,13 @@ module Portage
 
       # 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)
+      # @param proxy [String, Hash, nil] forwarded to Transports::Http (a
+      #   `url:` connection only) — see its own doc comment.
+      def self.connect(command: nil, args: [], env: nil, url: nil, headers: {}, capabilities: nil, proxy: nil)
         transport = if command
                       Transports::Stdio.new(command: command, args: args, env: env)
                     elsif url
-                      Transports::Http.new(url: url, headers: headers)
+                      Transports::Http.new(url: url, headers: headers, proxy: proxy)
                     else
                       raise ArgumentError, "connect requires either command: or url:"
                     end
@@ -51,14 +58,19 @@ module Portage
       # 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))
+      # @param headers [Hash{String => String}] sent with the manifest GET
+      #   and every call after it — e.g. a "User-Agent" naming the app
+      #   built on this gem.
+      # @param proxy [String, Hash, nil] forwarded to the Streamable HTTP
+      #   connection this discovers into — see Transports::Http.
+      def self.discover(url, headers: {}, proxy: nil)
+        manifest = fetch_manifest(url, headers)
+        connect(url: mcp_endpoint(manifest), headers: headers, capabilities: capability_names(manifest), proxy: proxy)
       end
 
-      def self.fetch_manifest(url)
+      def self.fetch_manifest(url, headers = {})
         uri = URI.parse("#{url.to_s.sub(%r{/\z}, '')}#{MANIFEST_PATH}")
-        response = Net::HTTP.get_response(uri)
+        response = Net::HTTP.get_response(uri, with_user_agent(headers))
         raise DiscoveryError, "GET #{uri} returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
 
         JSON.parse(response.body)
@@ -71,11 +83,23 @@ module Portage
       end
       private_class_method :fetch_manifest
 
+      # USER_AGENT unless `headers` already names one, in any case.
+      def self.with_user_agent(headers)
+        return headers if headers.keys.any? { |name| name.to_s.casecmp?("user-agent") }
+
+        { "User-Agent" => USER_AGENT }.merge(headers)
+      end
+
       # Real UCP manifests (confirmed live on Casper, Allbirds, Glossier, and
       # 34+ other Shopify UCP rollouts as of "2026-08-25") nest everything one
-      # level deeper under a "ucp" key. This gem's own server side
-      # (Portage::Ucp::Manifest) still emits the old flat shape, so both are
-      # supported rather than picking one — see docs/well-known-ucp.md.
+      # level deeper under a "ucp" key. Portage::Ucp::Manifest has emitted
+      # the same nested shape since portage-ucp 0.8.0. The flat fallback
+      # stays for stores still serving a manifest from an older portage-ucp:
+      # there, services and capabilities sit at the top level and
+      # capabilities is an array of {name:, version:}. This gem needing
+      # portage-ucp 0.8 says nothing about what a store runs, so dropping
+      # the fallback would break discovery against those stores — see
+      # docs/well-known-ucp.md.
       def self.ucp_section(manifest)
         manifest["ucp"] || manifest
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: portage-ucp
   requirement: !ruby/object:Gem::Requirement