portage-ucp 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7615fe9307cfc4a996c1f1842bcad557e4b2f67b336516d0dc767f5cbfb88c7b
-  data.tar.gz: b220392e3d403db32f750805fb18ec008b8c7c23a55f6f15ce0a6cddc71be8ff
+  metadata.gz: 9c0a19a01df5cf624b7e08f79b9a8e21a8d9d348ce68469c932233f77e8f65b7
+  data.tar.gz: ab6342cc1a9045662a0caba73858f2d1fc97f253c2df1593ab1ca629cc870055
 SHA512:
-  metadata.gz: 9664fd1f78821b3afeac62b2fd9cd09971e9daa279aa65e4f1de44ebe7989ccc5d180e7efc0fe9b9ab6b4ca0320a851dd045aae5f736e44bcb64a237b4ac948e
-  data.tar.gz: 1f2bc7debcc1afb3f54fa4e6072391c76f3347df24e462488db69ab33e67c92fca6129dc6d1b18442e503a7d53f3b2ca2f5f284061e88cf9c4793e42f02ea6b9
+  metadata.gz: 830f760577b2d590337cb38eced77dc7d8a4b102f0e946dd6e8fcfce24078ebb754334615707217ce6b2e9ce1f966b45e830c6dfd14e7dd220515a72644375b8
+  data.tar.gz: 28139b13e1cc2716f16be0b3bfe35182e9bd48b5508a5e61f4bde1a164e93caf6d9b525d87def91153fea157b789b591fdb179251eb11d377a749b1eb6d1d413

data/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.9.0] - 2026-09-23
+
+- New `Support::OfferRanking` and `Support::Escalation`: the offer-ranking
+  and escalation rules, held in core the way `PolicyGuard` holds the policy
+  rule. `portage-ucp-decision`'s `OfferRanking` and `EscalationPolicy` wrap
+  them, and `portage-cli` calls them directly, so there's one copy of each
+  rule instead of a gem copy and a CLI fallback.
+  - `OfferRanking.rank(offers) { |offer| [buyable, amount] }` puts buyable
+    offers first, then priced, then cheapest, and keeps ties in input
+    order.
+  - `Escalation.reason(checkout_status:, warnings:)` returns
+    `:requires_escalation`, then `:mismatch` for any warning, else nil.
+- New `Support::Totals.amount(totals, type: "total")`, the reader for the
+  arrays `Totals.summary`/`Totals.line` build. It takes `Total` value
+  objects or wire hashes, and returns nil when there's no entry of that
+  type. `Dispatcher` and `ReferenceAdapter` use it in place of their own
+  copies of the lookup, as does `portage-cli`.
+- Fix: `SchemaValidator` failed to load any vendored UCP schema in a process
+  with no `LANG` set (a bare Docker image, a CI runner). The schemas contain
+  non-ASCII, and Ruby then reads files as US-ASCII, so every validation
+  raised `Encoding::InvalidByteSequenceError`. It now reads them as UTF-8.
+
+## [0.8.1] - 2026-09-22
+
+- `Resolver`'s WooCommerce platform entry threads `payment_method`/
+  `billing_address` from `WOOCOMMERCE_PAYMENT_METHOD`/`WOOCOMMERCE_BILLING_ADDRESS`
+  through to `Adapter.new`. It previously built the client and adapter
+  without either, so `complete_checkout` failed with no gateway or address
+  configured even when both env vars were set — the resolver's `env:` map
+  simply never named them.
+
 ## [0.8.0] - 2026-09-17
 
 - **Breaking:** `Manifest#to_h` now emits the shape live UCP stores actually

data/README.md

@@ -30,6 +30,7 @@ in this gem.
 | `Portage::Ucp::Support::OrderLedger` | Durable snapshot written after settlement, alongside (not instead of) the transaction record — a failed snapshot write surfaces without flipping an already-settled charge to failed. |
 | `Portage::Ucp::Confirmer` | Gate run just before `complete_checkout` dispatch, after `PolicyGuard`. `Confirmer::Terminal` blocks on stdin and fails closed on anything but an explicit `"y"`; `Confirmer::AutoApprove` is for specs/conformance kits that need a real `confirm!` without blocking; `Confirmer::Webhook` is an out-of-band transport (POST + poll a status URL, or a caller-supplied `wait:` callback) for a Slack/WhatsApp/etc. approval flow — same fail-closed-on-timeout contract, its own longer default timeout. |
 | `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
+| `Portage::Ucp::Support::OfferRanking` / `Portage::Ucp::Support::Escalation` | The offer-ranking rule (buyable, then priced, then cheapest, ties stable) and the escalation rule (`requires_escalation`, then a mismatch). `portage-ucp-decision` wraps both as typed verdicts; `portage-cli` calls them directly. |
 | `Portage::Ucp::PaymentEnrollmentGuard` | Validates every `create_payment_enrollment`/`get_payment_enrollment` result an `Adapter` returns — `status` must be `"pending"` (with a `setup_url`, no `payment_token`) or `"complete"` (with a `payment_token`, no `setup_url`). Runs automatically in `Dispatcher#call`. |
 | `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and shape-only validation (required fields + expiry — not cryptographic verification) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
 

data/lib/portage/ucp/dispatcher.rb

@@ -230,8 +230,7 @@ module Portage
         # `Total#amount` is a bare integer minor-unit amount (the parent
         # object's `currency` applies), not a Money struct — see
         # value_objects.rb's Total/Item comments.
-        total = Array(result.totals).find { |t| t.type == "total" }
-        total&.amount
+        Support::Totals.amount(result.totals)
       end
 
       def settled_currency(result)

data/lib/portage/ucp/reference_adapter.rb

@@ -301,7 +301,7 @@ module Portage
 
         amount = line_items.sum do |li|
           order_line = order.line_items.find { |oli| oli.id == li[:id] }
-          unit_price = order_line.totals.find { |t| t.type == "total" }.amount / order_line.quantity
+          unit_price = Portage::Ucp::Support::Totals.amount(order_line.totals) / order_line.quantity
           unit_price * li[:quantity]
         end
         [Portage::Ucp::Total.new(type: "total", amount: -amount)]
@@ -372,7 +372,7 @@ module Portage
       end
 
       def totals_for(line_items, discounts)
-        subtotal = line_items.sum { |li| li.totals.find { |t| t.type == "total" }.amount }
+        subtotal = line_items.sum { |li| Portage::Ucp::Support::Totals.amount(li.totals) }
         discount_amount = discounts.applied.sum(&:amount)
         [Portage::Ucp::Total.new(type: "subtotal", amount: subtotal),
          Portage::Ucp::Total.new(type: "total", amount: subtotal - discount_amount)]

data/lib/portage/ucp/resolver.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module Portage
   module Ucp
     # Shared platform-detection + adapter-building logic for anything that
@@ -39,14 +41,16 @@ module Portage
           namespace: "WooCommerce",
           markers: [/woocommerce/i, %r{wp-content/plugins/woocommerce}i],
           env: { site_url: "WOOCOMMERCE_SITE_URL", consumer_key: "WOOCOMMERCE_CONSUMER_KEY",
-                 consumer_secret: "WOOCOMMERCE_CONSUMER_SECRET", currency: "WOOCOMMERCE_CURRENCY" },
+                 consumer_secret: "WOOCOMMERCE_CONSUMER_SECRET", currency: "WOOCOMMERCE_CURRENCY",
+                 payment_method: "WOOCOMMERCE_PAYMENT_METHOD", billing_address: "WOOCOMMERCE_BILLING_ADDRESS" },
           required: %i[site_url consumer_key consumer_secret],
           build_client: lambda { |ns, env|
             ns::Client.new(site_url: env.fetch(:site_url), consumer_key: env.fetch(:consumer_key),
                            consumer_secret: env.fetch(:consumer_secret))
           },
           build_adapter: lambda { |ns, client, env|
-            ns::Adapter.new(client: client, site_url: env.fetch(:site_url), currency: env.fetch(:currency, "USD"))
+            ns::Adapter.new(client: client, site_url: env.fetch(:site_url), currency: env.fetch(:currency, "USD"),
+                            payment_method: env[:payment_method], billing_address: woocommerce_billing_address(env))
           }
         ),
         Platform.new(
@@ -128,6 +132,45 @@ module Portage
         client = platform.build_client.call(namespace, env)
         platform.build_adapter.call(namespace, client, env)
       end
+
+      # WOOCOMMERCE_BILLING_ADDRESS wins when set (raises ArgumentError, not
+      # a raw JSON::ParserError, on malformed JSON — callers building an
+      # adapter from env expect a config error to name what's wrong).
+      # Otherwise falls back to the same PORTAGE_SHIP_* env `portage buy`
+      # already reads for shipping (Portage::Cli::ShippingProfile) mapped to
+      # WooCommerce's Store API billing_address field names, so a shopper
+      # who already set a shipping profile doesn't also have to hand-build a
+      # separate JSON blob just for WooCommerce's stopgap billing_address
+      # (see Adapter's class-level CAVEAT #2). Returns nil when neither is
+      # configured — #submit_checkout already raises a clear error for that.
+      def self.woocommerce_billing_address(env)
+        return parse_woocommerce_billing_address(env[:billing_address]) if env[:billing_address]
+
+        address = WOOCOMMERCE_BILLING_FROM_SHIP_ENV.filter_map do |var, key|
+          value = ENV.fetch(var, nil)
+          [key, value] if value && !value.empty?
+        end.to_h
+        address.empty? ? nil : address
+      end
+
+      def self.parse_woocommerce_billing_address(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        raise ArgumentError, "WOOCOMMERCE_BILLING_ADDRESS must be valid JSON: #{e.message}"
+      end
+
+      # Same env vars as Portage::Cli::ShippingProfile::ENV_VARS, mapped to
+      # WooCommerce's Store API billing_address keys (first_name/last_name/
+      # address_1/address_2/city/state/postcode/country/phone) rather than
+      # required here as a gem dependency on portage-cli.
+      WOOCOMMERCE_BILLING_FROM_SHIP_ENV = {
+        "PORTAGE_SHIP_FIRST_NAME" => "first_name", "PORTAGE_SHIP_LAST_NAME" => "last_name",
+        "PORTAGE_SHIP_STREET" => "address_1", "PORTAGE_SHIP_EXTENDED" => "address_2",
+        "PORTAGE_SHIP_CITY" => "city", "PORTAGE_SHIP_REGION" => "state",
+        "PORTAGE_SHIP_POSTAL_CODE" => "postcode", "PORTAGE_SHIP_COUNTRY" => "country",
+        "PORTAGE_SHIP_PHONE" => "phone"
+      }.freeze
+      private_constant :WOOCOMMERCE_BILLING_FROM_SHIP_ENV
     end
   end
 end

data/lib/portage/ucp/schema_validator.rb

@@ -66,8 +66,12 @@ module Portage
         load(relative_path)
       end
 
+      # Explicit encoding: the vendored schemas contain non-ASCII (e.g. "—"),
+      # and a process with no LANG set (a bare Docker image, a CI runner)
+      # defaults Encoding.default_external to US-ASCII, which made every
+      # schema load raise Encoding::InvalidByteSequenceError.
       def load(relative_path)
-        JSON.parse(File.read(File.join(@base_dir, relative_path)))
+        JSON.parse(File.read(File.join(@base_dir, relative_path), encoding: "UTF-8"))
       end
     end
   end

data/lib/portage/ucp/support/escalation.rb

@@ -0,0 +1,31 @@
+module Portage
+  module Ucp
+    module Support
+      # The escalation rule (docs/plans/system-one-decision-layer.md
+      # § Responsibilities 2), held in core for the same reason as
+      # OfferRanking: portage-ucp-decision's EscalationPolicy wraps it, and
+      # portage-cli calls it directly.
+      #
+      # The store's own `requires_escalation` wins over a mismatch the
+      # caller found, so a checkout that is both reports the store's answer.
+      module Escalation
+        STATUS = "requires_escalation".freeze
+
+        module_function
+
+        # @param checkout_status [String, nil] a Checkout#status value.
+        # @param warnings [Array<String>, nil] mismatches that should stop
+        #   the purchase. Any one escalates. Pass none when mismatches are
+        #   only to be reported.
+        # @return [Symbol, nil] `:requires_escalation`, `:mismatch`, or nil
+        #   to keep going.
+        def reason(checkout_status:, warnings: [])
+          return :requires_escalation if checkout_status == STATUS
+          return :mismatch if Array(warnings).any?
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/support/offer_ranking.rb

@@ -0,0 +1,30 @@
+module Portage
+  module Ucp
+    module Support
+      # The offer-ranking rule (docs/plans/system-one-decision-layer.md
+      # § Responsibilities 1), held in core the way PolicyGuard holds the
+      # policy rule. portage-ucp-decision's OfferRanking is a typed wrapper
+      # around it, and portage-cli calls it directly, so `portage find`
+      # ranks the same way whether or not that gem is installed.
+      #
+      # Buyable first, then priced, then cheapest, with ties kept in input
+      # order. Sorting on price alone would float a browse-only offer above
+      # one you can actually check out from.
+      module OfferRanking
+        module_function
+
+        # @param offers [Array] in whatever shape the caller holds them.
+        # @yieldparam offer one element of `offers`.
+        # @yieldreturn [Array(Boolean, Integer)] whether the offer can be
+        #   checked out, and its minor-unit amount (nil when unpriced).
+        # @return [Array] the same offers, ranked.
+        def rank(offers)
+          offers.sort_by.with_index do |offer, index|
+            buyable, amount = yield(offer)
+            [buyable ? 0 : 1, amount ? 0 : 1, amount || 0, index]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/support/totals.rb

@@ -25,6 +25,21 @@ module Portage
           [Portage::Ucp::Total.new(type: "subtotal", amount: subtotal),
            Portage::Ucp::Total.new(type: "total", amount: total)]
         end
+
+        # The reader for the arrays above: the amount of the first entry of
+        # `type`, or nil when there is none. Takes `Total` value objects or
+        # their wire hashes (string- or symbol-keyed), since callers hold
+        # either — an adapter's own result, or a checkout read back through
+        # a Session.
+        def amount(totals, type: "total")
+          entry = Array(totals).find { |total| field(total, :type) == type }
+          entry && field(entry, :amount)
+        end
+
+        def field(total, name)
+          total.is_a?(Hash) ? total.fetch(name.to_s) { total[name] } : total.public_send(name)
+        end
+        private_class_method :field
       end
     end
   end

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.8.0".freeze
+    VERSION = "0.9.0".freeze
   end
 end

data/lib/portage/ucp.rb

@@ -10,6 +10,8 @@ require_relative "ucp/adapter"
 # conversion, dedup table and HTTP plumbing.
 require_relative "ucp/support/amounts"
 require_relative "ucp/support/totals"
+require_relative "ucp/support/offer_ranking"
+require_relative "ucp/support/escalation"
 require_relative "ucp/support/line_item_status"
 require_relative "ucp/support/idempotency"
 require_relative "ucp/support/checkout_state"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -137,6 +138,7 @@ dependencies:
         version: '0.9'
 description: 'Protocol-only core gem: Adapter contract, capability registry, manifest
   builder, and an MCP server wrapper. No commerce-backend deps.'
+email:
 executables:
 - portage-ucp-check
 extensions: []
@@ -194,12 +196,14 @@ files:
 - lib/portage/ucp/support/amounts.rb
 - lib/portage/ucp/support/api_error.rb
 - lib/portage/ucp/support/checkout_state.rb
+- lib/portage/ucp/support/escalation.rb
 - lib/portage/ucp/support/http_client.rb
 - lib/portage/ucp/support/idempotency.rb
 - lib/portage/ucp/support/idempotency/file_store.rb
 - lib/portage/ucp/support/idempotency/memory_store.rb
 - lib/portage/ucp/support/line_item_status.rb
 - lib/portage/ucp/support/not_found.rb
+- lib/portage/ucp/support/offer_ranking.rb
 - lib/portage/ucp/support/order_ledger.rb
 - lib/portage/ucp/support/order_ledger/file_store.rb
 - lib/portage/ucp/support/order_ledger/store.rb
@@ -291,6 +295,7 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -305,7 +310,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.21
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Expose a commerce backend to AI shopping agents over MCP and UCP
 test_files: []