portage-ucp-client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88904b38d834b4f1b1343d35f50db2149828dc76edd179a778c511cb17119880
-  data.tar.gz: 334b55de228968238f9737e079ee719119232c81c631dcda00be1bd68e7c44d2
+  metadata.gz: 8ca449d6a513f5b79171362c5fbd7830812fecf99abc5b60d88e98c6362faf10
+  data.tar.gz: fa8e0a0f2a00f3b62431303aafabfb94228e9fecae184c1d5ab9df3752240b46
 SHA512:
-  metadata.gz: ba6fbffe20114f8c1d328dd7399f792a4dbaa81d03fb589366e8ec312c8efd08299b349aa5c0eaa9fd16254c4af9c4e3d9881387ae61163fb0d40ecebb92a7dc
-  data.tar.gz: 5dbce7d84c0b54d8068be7d95713855b94e765a6c945ea4c9e13bc86c02bf19683b87b6db8431173eb27b46363df3838bc264147259a470c430cf3a0ee48c79d
+  metadata.gz: 15a8962035eef888342055b2307304c89fa97e180c1a2ebb70e9ae25cbf8bd35212d95f1b83a09afa0d27c0a6003bba92b3a844fc58145b04d0eed759fc4d366
+  data.tar.gz: ed79009feffcc06418784907007b210250edc1e95182c48a8c8408f8de3db226da082cc55f3d50bc532707ebe682618a4b7040963001c963c068497a12a79364

data/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.3.0] - 2026-09-14
+
+- `Session` gains `#create_payment_enrollment(idempotency_key: nil)` /
+  `#get_payment_enrollment(enrollment_id:)`, covering the new
+  `app.portage-ucp.payment_enrollment` capability (docs/plans/agentic-payments.md
+  Phase 1). `create_payment_enrollment` is added to `MUTATING_ACTIONS`, so a
+  caller that omits `idempotency_key:` still gets one generated.
+- Every transport (http, stdio, loopback) and `Session` grow an optional
+  `meta:` kwarg, threaded through the same way `correlation_id` already
+  reaches the server from `traceparent` — additive only, no caller passing
+  `meta:` is required to change.
+- Widened the `portage-ucp` dependency pin from `~> 0.4` to `~> 0.5` —
+  `#create_payment_enrollment`/`#get_payment_enrollment` need the
+  `app.portage-ucp.payment_enrollment` capability, only present from
+  `portage-ucp` 0.5.0 on.
+
 ## [0.2.0] - 2026-08-21
 
 - `Session#create_checkout`/`#update_checkout` gain an optional `fulfillment:`

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

@@ -18,7 +18,7 @@ module Portage
       # 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
+                              complete_checkout cancel_checkout create_payment_enrollment].freeze
 
         # @param capabilities [Array<String>, nil] reverse-domain capability
         #   names advertised by the server, when known upfront (Client.discover
@@ -38,21 +38,26 @@ module Portage
           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 search_catalog(query:, limit: 20,
+                           meta: nil)
+          call("search_catalog", meta: meta, query: query, limit: limit)
+        end
+
+        def get_product(product_id:, meta: nil) = call("get_product", meta: meta, product_id: product_id)
+        def lookup_catalog(product_ids:, meta: nil) = call("lookup_catalog", meta: meta, product_ids: product_ids)
 
-        def get_cart(cart_id:) = call("get_cart", cart_id: cart_id)
+        def get_cart(cart_id:, meta: nil) = call("get_cart", meta: meta, cart_id: cart_id)
 
-        def create_cart(line_items:, idempotency_key: nil)
-          call("create_cart", line_items: line_items, idempotency_key: idempotency_key)
+        def create_cart(line_items:, idempotency_key: nil, meta: nil)
+          call("create_cart", meta: meta, 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)
+        def update_cart(cart_id:, line_items:, idempotency_key: nil, meta: nil)
+          call("update_cart", meta: meta, 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)
+        def cancel_cart(cart_id:, idempotency_key: nil, meta: nil)
+          call("cancel_cart", meta: meta, cart_id: cart_id, idempotency_key: idempotency_key)
         end
 
         # `fulfillment:` (dev.ucp.shopping.fulfillment) is only exercised over
@@ -61,36 +66,48 @@ module Portage
         # (a Portage::Ucp::CheckoutFulfillment for loopback). Over stdio/HTTP
         # it would need a JSON wire shape this gem doesn't build yet, so
         # callers on those transports should leave it nil.
-        def create_checkout(line_items:, idempotency_key: nil, fulfillment: nil)
-          call("create_checkout", line_items: line_items, idempotency_key: idempotency_key,
+        def create_checkout(line_items:, idempotency_key: nil, fulfillment: nil, meta: nil)
+          call("create_checkout", meta: meta, line_items: line_items, idempotency_key: idempotency_key,
                                   **(fulfillment ? { fulfillment: fulfillment } : {}))
         end
 
-        def get_checkout(checkout_id:) = call("get_checkout", checkout_id: checkout_id)
+        def get_checkout(checkout_id:, meta: nil) = call("get_checkout", meta: meta, checkout_id: checkout_id)
 
-        def update_checkout(checkout_id:, line_items:, idempotency_key: nil, fulfillment: nil)
-          call("update_checkout", checkout_id: checkout_id, line_items: line_items, idempotency_key: idempotency_key,
+        def update_checkout(checkout_id:, line_items:, idempotency_key: nil, fulfillment: nil, meta: nil)
+          call("update_checkout", meta: meta, checkout_id: checkout_id, line_items: line_items,
+                                  idempotency_key: idempotency_key,
                                   **(fulfillment ? { fulfillment: fulfillment } : {}))
         end
 
-        def complete_checkout(checkout_id:, payment_token:, idempotency_key: nil)
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key: nil, meta: nil)
           Portage::Ucp::PaymentTokenGuard.validate!(payment_token)
-          call("complete_checkout", checkout_id: checkout_id, payment_token: payment_token,
+          call("complete_checkout", meta: meta, 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)
+        def cancel_checkout(checkout_id:, idempotency_key: nil, meta: nil)
+          call("cancel_checkout", meta: meta, checkout_id: checkout_id, idempotency_key: idempotency_key)
+        end
+
+        def get_order(order_id:, meta: nil) = call("get_order", meta: meta, order_id: order_id)
+        def link_identity(oauth_token:, meta: nil) = call("link_identity", meta: meta, oauth_token: oauth_token)
+
+        # app.portage-ucp.payment_enrollment (Portage extension, §ref
+        # docs/plans/agentic-payments.md Phase 1) — not every adapter
+        # advertises this, check #advertises? first.
+        def create_payment_enrollment(idempotency_key: nil, meta: nil)
+          call("create_payment_enrollment", meta: meta, 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)
+        def get_payment_enrollment(enrollment_id:, meta: nil)
+          call("get_payment_enrollment", meta: meta, enrollment_id: enrollment_id)
+        end
 
         private
 
-        def call(action, **arguments)
+        def call(action, meta: nil, **arguments)
           arguments[:idempotency_key] ||= SecureRandom.uuid if MUTATING_ACTIONS.include?(action)
-          @transport.call_tool(name: action, arguments: arguments)
+          @transport.call_tool(name: action, arguments: arguments, meta: meta)
         end
       end
     end

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

@@ -12,8 +12,8 @@ module Portage
             @client.connect
           end
 
-          def call_tool(name:, arguments:)
-            response = @client.call_tool(name: name, arguments: arguments)
+          def call_tool(name:, arguments:, meta: nil)
+            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
             ToolResult.extract(response, symbol_keys: false)
           end
         end

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

@@ -15,10 +15,11 @@ module Portage
             @next_id = 0
           end
 
-          def call_tool(name:, arguments:)
+          def call_tool(name:, arguments:, meta: nil)
             @next_id += 1
             response = @server.handle(
-              { jsonrpc: "2.0", id: @next_id, method: "tools/call", params: { name: name, arguments: arguments } }
+              { jsonrpc: "2.0", id: @next_id, method: "tools/call",
+                params: { name: name, arguments: arguments, **(meta ? { _meta: meta } : {}) } }
             )
             ToolResult.extract(response, symbol_keys: true)
           end

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

@@ -12,8 +12,8 @@ module Portage
             @client.connect
           end
 
-          def call_tool(name:, arguments:)
-            response = @client.call_tool(name: name, arguments: arguments)
+          def call_tool(name:, arguments:, meta: nil)
+            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
             ToolResult.extract(response, symbol_keys: false)
           end
         end

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

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -29,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -99,6 +100,7 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
   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: []
@@ -121,6 +123,7 @@ 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
@@ -135,7 +138,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+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