portage-ucp-client 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eeeb1c006e06155791f086b9dbfce78562ecb4281412c18dbdf5794a4189c08
-  data.tar.gz: 6be190c6cb00f34b0d0978b522da1e912f3a0b33973b6eb813db72859869b491
+  metadata.gz: 89837fec9676ad52dd925e44ea86b12df99ae2f01ea56eccd4b877bbde7dfb7a
+  data.tar.gz: 34e0f987ba86fb975eaed185950cc6c2690c3f177ae8eacbbdb718560be4fb5e
 SHA512:
-  metadata.gz: c3ce4e8717a67bce1e3614677ec6b850ac58f6a598402debc78371b3a11fd3ebfde1d876375d6ed588d7ad9a7cde8a5a2806e982f2c5ab9ea8c14c72136b6651
-  data.tar.gz: a559406993fc8f3d9bb95f59df96e8fd70a6a45672675a9255e84857b1e36778993a1be498ca710ad8c60cb27cc27da3d48a4d2d8d3065550ee1254b141d2569
+  metadata.gz: 99581702b0ff34ed5a8fd680ffac05a05576823a6381bf312b63436107fb55977be865f7649be32827b3503b28465e3a862df9730058fe7ba4033179acd28505
+  data.tar.gz: db7d14a2a8149ca8b526ab4fc0ee6f6f807cad84b83eb57229879659e75e5d13207f96faada575354da1981fb78bc2a1de72edc98c38405a81a5efc3ddcfa7e1

data/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.6.2] - 2026-09-23
+
+- Fix: the loopback and stdio transports dropped `cart_id` from every call,
+  so `get_cart`, `update_cart` and `cancel_cart` always failed with
+  "Missing required arguments: cart_id". `cart_id` is a real-UCP wire
+  argument only on `create_checkout` (the cart-to-checkout conversion), and
+  now only that call drops it. The shared rule is
+  `Transports::LocalArguments`.
+- The UCP wire reshaping in `Transports::Http` moved to
+  `Transports::UcpWireShape`, so other transports can build the same body.
+  `portage-ucp-webmcp` uses it for UCP-shaped page tools. There is no
+  behavior change for `Http`.
+
 ## [0.6.1] - 2026-09-22
 
 - `ServerError` carries the parsed error document on `#payload` when the

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

@@ -1,5 +1,5 @@
 require_relative "../errors"
-require_relative "http/complete_checkout_wire_shape"
+require_relative "ucp_wire_shape"
 
 module Portage
   module Ucp
@@ -23,18 +23,7 @@ module Portage
         # into that real wire format before the request goes out — Loopback
         # and Stdio are untouched.
         class Http
-          include CompleteCheckoutWireShape
-
-          # 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
+          include UcpWireShape
 
           def initialize(url:, headers: {})
             @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
@@ -77,93 +66,6 @@ module Portage
             wire["idempotency-key"] = idempotency_key if idempotency_key
             wire
           end
-
-          def wire_arguments(name, arguments)
-            idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
-            arguments = arguments.dup
-            arguments.delete(:idempotency_key)
-
-            return complete_checkout_body(arguments, idempotency_key) if name == "complete_checkout"
-            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)
-
-            arguments
-          end
-
-          def catalog_body(name, arguments)
-            body = case name
-                   when "get_product" then { "id" => arguments.fetch(:product_id) }
-                   when "lookup_catalog" then { "ids" => arguments.fetch(:product_ids) }
-                   when "search_catalog" then search_catalog_body(arguments)
-                   end
-            { "catalog" => with_context(body, arguments) }
-          end
-
-          # `context` carries the buyer's locale/currency/region hints the UCP
-          # `context` object is specified for. It looks optional and isn't:
-          # Shopify resolves which market (and therefore which publication and
-          # inventory) a call is scoped to from it, and a cart built without it
-          # comes back with `line_items: []`, zeroed totals, and a
-          # `merchandise_out_of_stock` warning naming a product `search_catalog`
-          # had just reported as `availability.available == true` on the same
-          # store. Confirmed live 2026-09-22: identical `create_cart`, context
-          # added, returns the line item at its real price.
-          #
-          # A sweep of nine third-party Shopify stores the same day found the
-          # empty cart is only the loudest of three outcomes for an omitted
-          # context. Three stores built a correct cart without one; one
-          # emptied it; five priced it in the market of the *caller's IP*
-          # (a run from Bangkok got THB totals from stores whose shoppers had
-          # asked for nothing of the sort). So an omitted context doesn't
-          # merely degrade results — it produces a valid-shaped cart at the
-          # wrong currency, with nothing on the response saying so, which is
-          # the harder failure to notice of the two.
-          #
-          # Sending one is necessary, not sufficient: the cart is scoped to
-          # the market the context names, so a product the store doesn't
-          # publish into that market drops out with the same
-          # `merchandise_out_of_stock` message (mejuri.com, `US`/`USD` and
-          # `GB`/`GBP` empty, `CA`/`CAD` fine). That store's `search_catalog`
-          # ignored the context entirely and quoted CAD at
-          # `available: true` for every market asked, so the search result
-          # gives a caller no warning. Nothing to fix here — it's the store's
-          # market config — but callers shouldn't read this code as a
-          # guarantee that a context makes carts work.
-          def with_context(body, arguments)
-            context = arguments[:context] || arguments["context"]
-            return body if context.nil? || context.empty?
-
-            body.merge("context" => stringify(context))
-          end
-
-          def stringify(context)
-            context.to_h { |key, value| [key.to_s, value] }
-          end
-
-          def search_catalog_body(arguments)
-            { "query" => arguments[:query], "pagination" => { "limit" => arguments[:limit] }.compact }.compact
-          end
-
-          # `cart_id` on a checkout body is the cart→checkout conversion the
-          # spec's `checkout.cart_id` describes ("the business uses cart
-          # contents and ignores overlapping fields"). Its schema says
-          # `cart_id` alone is enough; the live server disagrees and rejects
-          # that with `Invalid arguments: object at '/checkout' is missing
-          # required properties: line_items` (confirmed live 2026-09-22), so
-          # the line items go out alongside it rather than instead of it.
-          def wrap_line_items(wrapper, arguments, id_key:)
-            body = { "line_items" => Array(arguments[:line_items]).map { |li| wire_line_item(li) } }
-            body["cart_id"] = arguments[:cart_id] if wrapper == "checkout" && arguments[:cart_id]
-            body = with_context(body, arguments)
-            { 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/local_arguments.rb

@@ -0,0 +1,30 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Session's arguments trimmed to what this gem's own flat-argument
+        # server (Portage::Ucp::Mcp::Server -> Dispatcher -> Adapter) takes.
+        # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
+        # wire concerns Session offers for Transports::Http to nest into a
+        # request body; the Adapter method signatures have no such keywords,
+        # so passing them on would be an ArgumentError on every call.
+        #
+        # `cart_id` is the exception that needs care: it is only a wire
+        # concern on create_checkout (the cart->checkout conversion). On
+        # get_cart/update_cart/cancel_cart it *is* the Adapter's own keyword,
+        # and dropping it there made every cart read/update/cancel fail with
+        # "Missing required arguments: cart_id".
+        module LocalArguments
+          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+          CART_ID_IS_WIRE_ONLY = %w[create_checkout].freeze
+
+          def self.strip(name, arguments)
+            remote = REMOTE_WIRE_ARGUMENTS
+            remote -= [:cart_id] unless CART_ID_IS_WIRE_ONLY.include?(name.to_s)
+            arguments.except(*remote)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -15,19 +15,15 @@ module Portage
             @next_id = 0
           end
 
-          # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
-          # wire concerns Session offers for Transports::Http to nest into a
-          # request body. This transport hands arguments straight to this
-          # gem's own Dispatcher, which splats them into an Adapter method
-          # signature that has no such keywords, so passing them on would be
-          # an ArgumentError on every call. Dropped here rather than branched
-          # on in Session, so each transport keeps owning which arguments it
+          # Real-UCP wire concerns this transport drops before they reach the
+          # Adapter — see LocalArguments. Dropped here rather than branched on
+          # in Session, so each transport keeps owning which arguments it
           # understands.
-          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+          REMOTE_WIRE_ARGUMENTS = LocalArguments::REMOTE_WIRE_ARGUMENTS
 
           def call_tool(name:, arguments:, meta: nil)
             @next_id += 1
-            arguments = arguments.except(*REMOTE_WIRE_ARGUMENTS)
+            arguments = LocalArguments.strip(name, arguments)
             response = @server.handle(
               { jsonrpc: "2.0", id: @next_id, method: "tools/call",
                 params: { name: name, arguments: arguments, **(meta ? { _meta: wire_meta(meta) } : {}) } }

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

@@ -12,18 +12,14 @@ module Portage
             @client.connect
           end
 
-          # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
-          # wire concerns Session offers for Transports::Http to nest into a
-          # request body. This transport hands arguments straight to this
-          # gem's own Dispatcher, which splats them into an Adapter method
-          # signature that has no such keywords, so passing them on would be
-          # an ArgumentError on every call. Dropped here rather than branched
-          # on in Session, so each transport keeps owning which arguments it
+          # Real-UCP wire concerns this transport drops before they reach the
+          # Adapter — see LocalArguments. Dropped here rather than branched on
+          # in Session, so each transport keeps owning which arguments it
           # understands.
-          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+          REMOTE_WIRE_ARGUMENTS = LocalArguments::REMOTE_WIRE_ARGUMENTS
 
           def call_tool(name:, arguments:, meta: nil)
-            response = @client.call_tool(name: name, arguments: arguments.except(*REMOTE_WIRE_ARGUMENTS), meta: meta)
+            response = @client.call_tool(name: name, arguments: LocalArguments.strip(name, arguments), meta: meta)
             ToolResult.extract(response, symbol_keys: false)
           end
         end

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

@@ -0,0 +1,121 @@
+require_relative "http/complete_checkout_wire_shape"
+
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Session's flat arguments reshaped into the real UCP wire format —
+        # every tool nests its arguments under a capability key
+        # (catalog:/cart:/checkout:), confirmed live against Shopify's
+        # 2026-08-25 rollout (see Transports::Http). Split out of Http so any
+        # transport that reaches a UCP-shaped tool surface (Streamable HTTP
+        # today, a page's WebMCP tools in portage-ucp-webmcp) builds the same
+        # body from the same code rather than a second copy drifting from it.
+        # Private instance methods of the including transport, as before.
+        module UcpWireShape
+          include Http::CompleteCheckoutWireShape
+
+          # 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
+
+          private
+
+          def wire_arguments(name, arguments)
+            idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
+            arguments = arguments.dup
+            arguments.delete(:idempotency_key)
+
+            return complete_checkout_body(arguments, idempotency_key) if name == "complete_checkout"
+            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)
+
+            arguments
+          end
+
+          def catalog_body(name, arguments)
+            body = case name
+                   when "get_product" then { "id" => arguments.fetch(:product_id) }
+                   when "lookup_catalog" then { "ids" => arguments.fetch(:product_ids) }
+                   when "search_catalog" then search_catalog_body(arguments)
+                   end
+            { "catalog" => with_context(body, arguments) }
+          end
+
+          # `context` carries the buyer's locale/currency/region hints the UCP
+          # `context` object is specified for. It looks optional and isn't:
+          # Shopify resolves which market (and therefore which publication and
+          # inventory) a call is scoped to from it, and a cart built without it
+          # comes back with `line_items: []`, zeroed totals, and a
+          # `merchandise_out_of_stock` warning naming a product `search_catalog`
+          # had just reported as `availability.available == true` on the same
+          # store. Confirmed live 2026-09-22: identical `create_cart`, context
+          # added, returns the line item at its real price.
+          #
+          # A sweep of nine third-party Shopify stores the same day found the
+          # empty cart is only the loudest of three outcomes for an omitted
+          # context. Three stores built a correct cart without one; one
+          # emptied it; five priced it in the market of the *caller's IP*
+          # (a run from Bangkok got THB totals from stores whose shoppers had
+          # asked for nothing of the sort). So an omitted context doesn't
+          # merely degrade results — it produces a valid-shaped cart at the
+          # wrong currency, with nothing on the response saying so, which is
+          # the harder failure to notice of the two.
+          #
+          # Sending one is necessary, not sufficient: the cart is scoped to
+          # the market the context names, so a product the store doesn't
+          # publish into that market drops out with the same
+          # `merchandise_out_of_stock` message (mejuri.com, `US`/`USD` and
+          # `GB`/`GBP` empty, `CA`/`CAD` fine). That store's `search_catalog`
+          # ignored the context entirely and quoted CAD at
+          # `available: true` for every market asked, so the search result
+          # gives a caller no warning. Nothing to fix here — it's the store's
+          # market config — but callers shouldn't read this code as a
+          # guarantee that a context makes carts work.
+          def with_context(body, arguments)
+            context = arguments[:context] || arguments["context"]
+            return body if context.nil? || context.empty?
+
+            body.merge("context" => stringify(context))
+          end
+
+          def stringify(context)
+            context.to_h { |key, value| [key.to_s, value] }
+          end
+
+          def search_catalog_body(arguments)
+            { "query" => arguments[:query], "pagination" => { "limit" => arguments[:limit] }.compact }.compact
+          end
+
+          # `cart_id` on a checkout body is the cart→checkout conversion the
+          # spec's `checkout.cart_id` describes ("the business uses cart
+          # contents and ignores overlapping fields"). Its schema says
+          # `cart_id` alone is enough; the live server disagrees and rejects
+          # that with `Invalid arguments: object at '/checkout' is missing
+          # required properties: line_items` (confirmed live 2026-09-22), so
+          # the line items go out alongside it rather than instead of it.
+          def wrap_line_items(wrapper, arguments, id_key:)
+            body = { "line_items" => Array(arguments[:line_items]).map { |li| wire_line_item(li) } }
+            body["cart_id"] = arguments[:cart_id] if wrapper == "checkout" && arguments[:cart_id]
+            body = with_context(body, arguments)
+            { 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
+  end
+end

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

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

data/lib/portage/ucp/client.rb

@@ -8,6 +8,7 @@ require_relative "client/version"
 require_relative "client/errors"
 require_relative "client/tool_result"
 require_relative "client/session"
+require_relative "client/transports/local_arguments"
 require_relative "client/transports/loopback"
 require_relative "client/transports/stdio"
 require_relative "client/transports/http"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -129,8 +129,10 @@ files:
 - lib/portage/ucp/client/tool_result.rb
 - lib/portage/ucp/client/transports/http.rb
 - lib/portage/ucp/client/transports/http/complete_checkout_wire_shape.rb
+- lib/portage/ucp/client/transports/local_arguments.rb
 - lib/portage/ucp/client/transports/loopback.rb
 - lib/portage/ucp/client/transports/stdio.rb
+- lib/portage/ucp/client/transports/ucp_wire_shape.rb
 - lib/portage/ucp/client/version.rb
 homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
 licenses: