portage-ucp-client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96ae3a5da5ef868663d2b296539ef3812249479031f6237f0c4dbb5679dda268
-  data.tar.gz: 7b132dc0d5c2152a2bba93db9629e5c897331a5360d95894cc84028fb9052ee9
+  metadata.gz: 8ca449d6a513f5b79171362c5fbd7830812fecf99abc5b60d88e98c6362faf10
+  data.tar.gz: fa8e0a0f2a00f3b62431303aafabfb94228e9fecae184c1d5ab9df3752240b46
 SHA512:
-  metadata.gz: 88439c696a4d6c6b4ead359c4b463b00fc07f02e811774096e745d7e95880b45b67ec3d948c5beffea0f0bd56456834305c774cc4d2b0a7281846840fd526bc3
-  data.tar.gz: d0965725d9e6914ae0bd19a0f2e8acabd182c943d01d0cb810458e3edc9d9d3001cf67bea1931eca3258b0315f32328e47b156a752c5f935bc07772d1ac9d0b3
+  metadata.gz: 15a8962035eef888342055b2307304c89fa97e180c1a2ebb70e9ae25cbf8bd35212d95f1b83a09afa0d27c0a6003bba92b3a844fc58145b04d0eed759fc4d366
+  data.tar.gz: ed79009feffcc06418784907007b210250edc1e95182c48a8c8408f8de3db226da082cc55f3d50bc532707ebe682618a4b7040963001c963c068497a12a79364

data/CHANGELOG.md

@@ -4,7 +4,34 @@ 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
+## [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:`
+  param, passed through only when given. Only exercised end-to-end over the
+  loopback transport (an in-process `Adapter`, taking a real
+  `Portage::Ucp::CheckoutFulfillment`); the stdio/HTTP wire shape for
+  `fulfillment` has no real UCP server to verify it against yet, so it's not
+  wired there.
+
+## [0.1.0] - 2026-08-14
 
 - Initial pre-release. Client-side SDK — loopback, stdio, and Streamable HTTP
   transports behind one `Session` interface.

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,51 +38,76 @@ 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
 
-        def create_checkout(line_items:, idempotency_key: nil)
-          call("create_checkout", line_items: line_items, idempotency_key: idempotency_key)
+        # `fulfillment:` (dev.ucp.shopping.fulfillment) is only exercised over
+        # the loopback transport today (Portage::Cli::Buy's own-store adapter
+        # path) — passed straight through as whatever value the caller built
+        # (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, 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)
-          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.1.0".freeze
+      VERSION = "0.3.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement