portage-ucp-client 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f50b4b88bf8e387e11a7540f15ebef6a3a9d3b46fcb124497cdacca936ae555
-  data.tar.gz: 031ed26c26c706695ffdae1faff8f7d3a33d02cc0eafb1f8091a851af2a4a7af
+  metadata.gz: 7d63c926220d7d3aa15f0d11d4e2bdddc27ac0ad3227ae1bec20ed1beddd471a
+  data.tar.gz: 8fc8999401c53b2cc6db65347aa1a377a20a2c9d316a94354328237c4727ec78
 SHA512:
-  metadata.gz: 9824791a9f0fddf499773fdc0560a85dfd84cfb0071dc180b3b86d2a33d1ed2e1e05cfd9f59cb4737fe416ee26e5b72e2a65b1bfaf9898c8322e3caf149540f4
-  data.tar.gz: 5e805a953352027e67e5c803cf3f1f6bd8129c5bbf9f26e807b18bb06e926420d8aae59ac6e425532c511e444772a6a909bdd4a48c92ea86a6a9474d3f387d55
+  metadata.gz: bd5574b147b2552c3a304e49ec71bac10183cd20eab5a06b7df7c0aa261c36642af1d9885d5880b5d08fd2320b9211c3ecc921c849dfe20c9b39b3a7c39ce537
+  data.tar.gz: 31fa3387860b6d094399c5dd596fece5cf921e5f6b4b013f7180d37b8970f3c9b2981efd1cf37b7f8fada533439221e6c2d25e45e1078a597d13f88842a3f320

data/CHANGELOG.md

@@ -4,7 +4,41 @@ 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.4.0] - 2026-09-17
+
+- Fixed `Transports::Http` sending every tool call in the flat, unwrapped
+  shape this gem's own Dispatcher/adapters speak — real UCP servers
+  (confirmed live against Shopify's 2026-08-25 rollout) reject it with a 422,
+  since they expect arguments nested under a capability key
+  (`catalog:`/`cart:`/`checkout:`) and a `meta.ucp-agent.profile` URL they
+  fetch themselves to verify the caller's identity. `Http` now builds that
+  real wire shape; `Loopback`/`Stdio` are unchanged, since the former talks
+  to this gem's own Dispatcher (still the flat shape by design) and the
+  latter has no confirmed real-world shape to fix. Callers must now pass
+  `meta: { agent_profile: <url> }`, or `MissingAgentProfileError` explains
+  what's missing instead of a bare 422.
+- Added `MissingAgentProfileError` and `UnsupportedWireShapeError`.
+  `complete_checkout` over HTTP raises the latter rather than guessing at
+  the real payment-instrument shape (Apple Pay/Shop Pay/card-token variants
+  each have distinct required credential fields) with no way to verify it
+  against a real payment flow.
+- Widens the `portage-ucp` dependency pin to `~> 0.8` so this gem installs
+  alongside `portage-ucp` 0.8.0 (the `~> 0.7` pin published with 0.3.3 is
+  pessimistic and excludes it).
+
+## [0.3.3] - 2026-09-16
+
+- No behavior change — 0.3.2 was built and pushed with `gem build` run from
+  the workspace root instead of this gem's own directory, so `spec.files =
+  Dir[...]` resolved against the wrong working directory and packaged an
+  empty gem. 0.3.2 has been yanked; 0.3.3 repackages the exact same 0.3.2
+  code correctly.
+
+## [0.3.2] - 2026-09-16
+
+- No behavior change — widens the `portage-ucp` dependency pin to `~> 0.7`
+  so this gem can install alongside `portage-ucp` 0.7.0 (the pessimistic
+  `~> 0.6` pin published with 0.3.1 excludes it).
 
 ## [0.3.1] - 2026-09-15
 

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

@@ -10,10 +10,36 @@ module Portage
       # 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).
+      # Raised by .discover when the manifest can't be fetched at all: the URL
+      # 404s, the host refuses the connection, or the body isn't valid JSON.
+      # Indistinguishable from "this store doesn't run UCP" — callers that
+      # want to fall back silently for that case should rescue this.
       class DiscoveryError < Error; end
+
+      # Raised by .discover when the manifest *was* fetched and parsed as
+      # JSON, but this client couldn't make sense of its shape (no `services`
+      # entry advertising an `mcp` transport). Unlike DiscoveryError, this
+      # means the store *is* running UCP — the failure is on this client's
+      # side, not the store's — so callers shouldn't treat it the same as
+      # "no native UCP support" the way a 404 does.
+      class ManifestShapeError < DiscoveryError; end
+
+      # Raised by Transports::Http when a call is made without
+      # `meta: { agent_profile: <url> }` — real UCP servers (confirmed
+      # against Shopify's 2026-08-25 rollout) fetch and verify this URL
+      # themselves to identify the calling agent, so there's no sane default
+      # to fall back to; better to fail here than pass `meta: nil` through
+      # to a 422 the server explains as `profile_unreachable`.
+      class MissingAgentProfileError < Error; end
+
+      # Raised by Transports::Http for a mutating call this gem can't yet
+      # build the real wire shape for — currently only `complete_checkout`,
+      # whose `checkout.payment.instruments` shape (Apple Pay/Shop
+      # Pay/card-token variants, each with its own required credential
+      # fields) can't be safely guessed without a real payment flow to test
+      # against. Raised instead of sending a best-effort shape that might
+      # silently misbehave with real money on the line.
+      class UnsupportedWireShapeError < Error; end
     end
   end
 end

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

@@ -1,3 +1,5 @@
+require_relative "../errors"
+
 module Portage
   module Ucp
     module Client
@@ -6,16 +8,111 @@ module Portage
         # `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.
+        #
+        # Session's public API (query:/limit:, cart_id:/checkout_id:/
+        # order_id:, line_items: [{product_id:, quantity:}], ...) stays flat
+        # — it's shared with Loopback, which hands arguments straight to this
+        # gem's own Dispatcher/adapters, and those speak that flat shape by
+        # design (see portage-ucp/lib/portage/ucp/mcp/server.rb). Real UCP
+        # servers don't: confirmed live against Shopify's 2026-08-25 rollout,
+        # every tool nests its arguments under a capability key
+        # (catalog:/cart:/checkout:) and requires a `meta.ucp-agent.profile`
+        # URL the server itself fetches to verify the caller's identity. This
+        # transport is the one place that reshapes Session's flat arguments
+        # into that real wire format before the request goes out — Loopback
+        # and Stdio are untouched.
         class Http
+          # Actions whose one identifying argument becomes a top-level `id`.
+          ID_ARG = {
+            "get_cart" => :cart_id, "cancel_cart" => :cart_id,
+            "get_checkout" => :checkout_id, "cancel_checkout" => :checkout_id,
+            "get_order" => :order_id
+          }.freeze
+
+          CATALOG_ACTIONS = %w[get_product lookup_catalog search_catalog].freeze
+          CART_ACTIONS = %w[create_cart update_cart].freeze
+          CHECKOUT_ACTIONS = %w[create_checkout update_checkout].freeze
+
           def initialize(url:, headers: {})
             @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
             @client.connect
           end
 
+          # `meta` here is a *property of the tool's own `arguments` object*
+          # (confirmed live against Shopify's schema — every tool's
+          # input_schema lists "meta" as a top-level sibling of
+          # "catalog"/"cart"/"checkout"), not the MCP protocol's `_meta`
+          # envelope field. `MCP::Client#call_tool`'s own `meta:` kwarg sends
+          # the latter, so it's unused here — the caller-supplied meta gets
+          # folded into `arguments["meta"]` instead.
           def call_tool(name:, arguments:, meta: nil)
-            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
+            idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
+            wire = wire_arguments(name, arguments)
+            wire["meta"] = wire_meta(meta, idempotency_key)
+            response = @client.call_tool(name: name, arguments: wire)
             ToolResult.extract(response, symbol_keys: false)
           end
+
+          private
+
+          # `idempotency_key` arrives via `arguments` — Session#call folds it
+          # in there for every mutating action — not via `meta`, so it has to
+          # be threaded through here rather than read off `meta` directly.
+          def wire_meta(meta, idempotency_key)
+            profile = meta && (meta[:agent_profile] || meta["agent_profile"])
+            unless profile
+              raise MissingAgentProfileError,
+                    "meta: { agent_profile: <url> } is required for HTTP calls — real UCP servers fetch " \
+                    "and verify this URL to identify the calling agent"
+            end
+
+            wire = { "ucp-agent" => { "profile" => profile } }
+            wire["idempotency-key"] = idempotency_key if idempotency_key
+            wire
+          end
+
+          def wire_arguments(name, arguments)
+            arguments = arguments.dup
+            arguments.delete(:idempotency_key)
+
+            return { "id" => arguments.fetch(ID_ARG[name]) } if ID_ARG.key?(name)
+            return catalog_body(name, arguments) if CATALOG_ACTIONS.include?(name)
+            return wrap_line_items("cart", arguments, id_key: :cart_id) if CART_ACTIONS.include?(name)
+            return wrap_line_items("checkout", arguments, id_key: :checkout_id) if CHECKOUT_ACTIONS.include?(name)
+
+            raise_unsupported_payment_shape if name == "complete_checkout"
+
+            arguments
+          end
+
+          def catalog_body(name, arguments)
+            case name
+            when "get_product" then { "catalog" => { "id" => arguments.fetch(:product_id) } }
+            when "lookup_catalog" then { "catalog" => { "ids" => arguments.fetch(:product_ids) } }
+            when "search_catalog" then { "catalog" => search_catalog_body(arguments) }
+            end
+          end
+
+          def raise_unsupported_payment_shape
+            raise UnsupportedWireShapeError,
+                  "complete_checkout isn't wired to the real payment-instrument shape yet — " \
+                  "checkout.payment.instruments varies by handler (card/apple-pay/shop-pay) and hasn't " \
+                  "been verified against a real payment flow"
+          end
+
+          def search_catalog_body(arguments)
+            { "query" => arguments[:query], "pagination" => { "limit" => arguments[:limit] }.compact }.compact
+          end
+
+          def wrap_line_items(wrapper, arguments, id_key:)
+            body = { "line_items" => Array(arguments[:line_items]).map { |li| wire_line_item(li) } }
+            { wrapper => body }.tap { |h| h["id"] = arguments[id_key] if arguments[id_key] }
+          end
+
+          def wire_line_item(line_item)
+            { "item" => { "id" => line_item[:product_id] || line_item["product_id"] },
+              "quantity" => line_item[:quantity] || line_item["quantity"] }
+          end
         end
       end
     end

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

@@ -19,10 +19,28 @@ module Portage
             @next_id += 1
             response = @server.handle(
               { jsonrpc: "2.0", id: @next_id, method: "tools/call",
-                params: { name: name, arguments: arguments, **(meta ? { _meta: meta } : {}) } }
+                params: { name: name, arguments: arguments, **(meta ? { _meta: wire_meta(meta) } : {}) } }
             )
             ToolResult.extract(response, symbol_keys: true)
           end
+
+          private
+
+          # Session's transport-agnostic `meta: { agent_profile: <url> }`
+          # convention (the one `Buy#agent_meta` actually passes, regardless
+          # of which transport `session` turns out to be) has to reach
+          # `Mcp::Server.agent_profile_for`, which only ever looks at
+          # `_meta["ucp-agent.profile"]`/`_meta[:"ucp-agent.profile"]` — a
+          # different key. Without this, an own-store loopback buy silently
+          # dropped its agent_profile (no error, just a blank field in
+          # tool_call_received/tool_called events) while the real-store HTTP
+          # transport picked the same `agent_profile:` key up correctly.
+          # Merges rather than replaces so a caller already using the
+          # server's own key (as this gem's specs do) is untouched.
+          def wire_meta(meta)
+            profile = meta[:agent_profile] || meta["agent_profile"]
+            profile ? meta.merge("ucp-agent.profile" => profile) : meta
+          end
         end
       end
     end

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

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

data/lib/portage/ucp/client.rb

@@ -70,17 +70,31 @@ module Portage
       end
       private_class_method :fetch_manifest
 
+      # 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.
+      def self.ucp_section(manifest)
+        manifest["ucp"] || manifest
+      end
+      private_class_method :ucp_section
+
       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
+        services = ucp_section(manifest)["services"]
+        entries = services.is_a?(Hash) ? services.values.flatten : Array(services)
+        endpoint = entries.select { |s| s["transport"] == "mcp" }
+                          .max_by { |s| s["version"].to_s }
+                          &.fetch("endpoint", nil)
+        raise ManifestShapeError, "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"] }
+        capabilities = ucp_section(manifest)["capabilities"]
+        capabilities.is_a?(Hash) ? capabilities.keys : Array(capabilities).map { |c| c["name"] }
       end
       private_class_method :capability_names
     end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Tom Whitbread
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -30,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -99,8 +112,8 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
   /.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:
+  on portage-ucp, the mcp gem''s client half, and faraday (the HTTP transport''s backend);
+  no adapter gem is a dependency.'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -123,7 +136,6 @@ 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
@@ -138,8 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Client-side SDK for portage-ucp — act as the shopper's agent against any
   UCP/MCP server