portage-ucp 0.1.0

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

@@ -0,0 +1,26 @@
+module Portage
+  module Ucp
+    module Support
+      # §9a: mutating Adapter methods must dedup by idempotency_key so an
+      # agent's retry on a dropped connection can't double-charge. None of
+      # the commerce APIs behind the bundled adapter gems takes an
+      # idempotency key natively (Shopify's cartSubmitForCompletion attemptId
+      # is the one partial exception), so every adapter keeps an in-process
+      # dedup table — this is that table.
+      #
+      # In-process only: a multi-process deployment that must dedup across
+      # workers needs a shared store, which is a consumer concern the same
+      # way RateLimiter is.
+      module Idempotency
+        private
+
+        def dedup(idempotency_key)
+          @idempotency_results ||= {}
+          return @idempotency_results[idempotency_key] if @idempotency_results.key?(idempotency_key)
+
+          @idempotency_results[idempotency_key] = yield
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Portage
+  module Ucp
+    module Support
+      # schemas/shopping/types/order_line_item.json's `status` derived from
+      # the line's own quantity tracking, for platforms that report
+      # per-line fulfilled quantities.
+      #
+      # Platforms whose core has no per-line fulfillment (WooCommerce,
+      # BigCommerce) instead map their order-level status enum onto this same
+      # vocabulary with a table of their own, then hand every line the same
+      # coarse value. The tables themselves stay in their gems — the enums
+      # are platform-specific — but #from_table and #fulfilled_quantity are
+      # what those gems do with them, and that part is not.
+      module LineItemStatus
+        module_function
+
+        def derive(total:, fulfilled:)
+          return "removed" if total.zero?
+          return "fulfilled" if fulfilled == total
+          return "partial" if fulfilled.positive?
+
+          "processing"
+        end
+
+        # "processing" is the fallback for an unmapped platform status on
+        # purpose: every table here is written against a documented enum that
+        # the platform is free to extend, and an order in a status we've never
+        # seen is far more likely to be in flight than cancelled or delivered.
+        # Guessing "removed" would tell a caller an order is dead when it
+        # isn't.
+        def from_table(table, key)
+          table.fetch(key, "processing")
+        end
+
+        # Platforms without per-line fulfillment still owe
+        # schemas/shopping/types/order_line_item.json a `fulfilled` count, so
+        # the order-level status stands in for it: all of the line or none.
+        def fulfilled_quantity(status, quantity)
+          status == "fulfilled" ? quantity : 0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Portage
+  module Ucp
+    module Support
+      # UCP's read methods return nil for a missing resource (see
+      # Portage::Ucp::Adapter's `@return [..., nil]` annotations), but REST
+      # APIs signal that with a 404 rather than an empty success body — so
+      # every REST-backed adapter wrapped its reads in the same
+      # rescue-404-return-nil block.
+      #
+      # Only 404 is swallowed: a 401 or 500 is a real failure the caller
+      # needs to see, not an absent product.
+      module NotFound
+        private
+
+        def nil_on_not_found
+          yield
+        rescue Portage::Ucp::Support::ApiError => e
+          raise unless e.status == 404
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Portage
+  module Ucp
+    module Support
+      # The POST-JSON-and-parse half of every adapter gem's
+      # AccessTokenFetcher. What each gem keeps is the part that genuinely
+      # differs: its endpoint, its grant payload, and how it maps the
+      # response body onto its own Result struct (Magento reports no
+      # `expires_in` at all; Etsy rotates the refresh_token on every use).
+      #
+      # Separate from Support::HttpClient because the failure mode is
+      # different: a token exchange has no ApiError/status contract to honor
+      # — a non-2xx here means "these credentials don't work", which is the
+      # gem's plain Error, not something a caller retries on a 404.
+      module TokenExchange
+        private
+
+        # @param error_class [Class] the gem's own Error
+        # @param description [String] what failed, e.g. "token refresh failed"
+        # @param form [Boolean] send the grant as form-encoded rather than
+        #   JSON. OAuth 2.0 specifies form encoding for the token endpoint and
+        #   Shopify follows it to the letter; the others accept JSON, so JSON
+        #   stays the default rather than churn three working callers.
+        # @return [Hash, String] the parsed response body
+        def exchange(endpoint, payload, error_class:, description: "token exchange failed", form: false)
+          uri = URI(endpoint)
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = form ? "application/x-www-form-urlencoded" : "application/json"
+          request.body = form ? URI.encode_www_form(payload) : JSON.generate(payload)
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
+          body = JSON.parse(response.body)
+          raise error_class, "#{description}: #{body}" unless response.is_a?(Net::HTTPSuccess)
+
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Portage
+  module Ucp
+    module Support
+      # Builders for the two Total-array shapes the shopping schemas use.
+      # Both encode rules that were previously restated in every mapper: the
+      # top-level array is exactly one subtotal plus one total with an
+      # optional tax entry between them, and a line item's array is the same
+      # amount reported twice unless the line carries its own discount.
+      module Totals
+        module_function
+
+        # Top-level cost breakdown for a Cart/Checkout/Order. The tax entry
+        # is emitted only when positive — a zero-tax order shouldn't claim a
+        # tax line it doesn't have.
+        def summary(subtotal:, total:, tax: nil)
+          entries = [Portage::Ucp::Total.new(type: "subtotal", amount: subtotal)]
+          entries << Portage::Ucp::Total.new(type: "tax", amount: tax) if tax&.positive?
+          entries << Portage::Ucp::Total.new(type: "total", amount: total)
+          entries
+        end
+
+        # A line item's own totals. `total` defaults to `subtotal` for the
+        # common case where nothing discounts the line.
+        def line(subtotal, total = subtotal)
+          [Portage::Ucp::Total.new(type: "subtotal", amount: subtotal),
+           Portage::Ucp::Total.new(type: "total", amount: total)]
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/value_objects.rb

@@ -0,0 +1,186 @@
+module Portage
+  module Ucp
+    # Internal arithmetic helper only — never appears in a wire shape directly.
+    Money = Data.define(:amount_minor, :currency)
+
+    Product = Data.define(:id, :title, :description, :price, :available, :variants, :url)
+
+    # One cost-breakdown entry (schemas/shopping/types/total.json). `amount` is a
+    # signed integer in the parent object's currency's minor units.
+    Total = Data.define(:type, :amount, :display_text) do
+      def initialize(type:, amount:, display_text: nil) = super
+
+      def to_wire_h
+        h = { "type" => type, "amount" => amount }
+        h["display_text"] = display_text if display_text
+        h
+      end
+    end
+
+    # Product identity on a line item (schemas/shopping/types/item.json). `price`
+    # is a bare integer minor-unit amount — the parent object's currency applies.
+    Item = Data.define(:id, :title, :price, :image_url) do
+      def initialize(id:, title:, price:, image_url: nil) = super
+
+      def to_wire_h
+        h = { "id" => id, "title" => title, "price" => price }
+        h["image_url"] = image_url if image_url
+        h
+      end
+    end
+
+    # schemas/shopping/types/line_item.json — id/item/quantity/totals, not a
+    # flat product_id/unit_price/total triple.
+    LineItem = Data.define(:id, :item, :quantity, :totals) do
+      def to_wire_h
+        { "id" => id, "item" => item.to_wire_h, "quantity" => quantity,
+          "totals" => totals.map(&:to_wire_h) }
+      end
+    end
+
+    # schemas/shopping/types/link.json
+    Link = Data.define(:type, :url, :title) do
+      def initialize(type:, url:, title: nil) = super
+
+      def to_wire_h
+        h = { "type" => type, "url" => url }
+        h["title"] = title if title
+        h
+      end
+    end
+
+    # schemas/shopping/cart.json — requires ucp/id/line_items/currency/totals.
+    # The "ucp" envelope is added centrally by Portage::Ucp::WireEnvelope, not stored
+    # on the value object itself.
+    Cart = Data.define(:id, :line_items, :currency, :totals) do
+      def to_wire_h
+        { "id" => id, "line_items" => line_items.map(&:to_wire_h), "currency" => currency,
+          "totals" => totals.map(&:to_wire_h) }
+      end
+    end
+
+    # schemas/shopping/types/order_confirmation.json — requires id/permalink_url.
+    # Carried on Checkout#order once complete_checkout actually produces an
+    # order; nil until then.
+    OrderConfirmation = Data.define(:id, :permalink_url, :label) do
+      def initialize(id:, permalink_url:, label: nil) = super
+
+      def to_wire_h
+        h = { "id" => id, "permalink_url" => permalink_url }
+        h["label"] = label if label
+        h
+      end
+    end
+
+    # schemas/shopping/checkout.json — requires ucp/id/line_items/status/
+    # currency/totals/links. `status` is the real enum (incomplete,
+    # requires_escalation, ready_for_complete, complete_in_progress, completed,
+    # canceled) — not the old ad hoc "pending"/"completed" strings. `order` is
+    # the schema's optional order_confirmation — set once complete_checkout
+    # actually produces an order, nil otherwise.
+    Checkout = Data.define(:id, :status, :line_items, :currency, :totals, :links, :order) do
+      def initialize(id:, status:, line_items:, currency:, totals:, links:, order: nil) = super
+
+      def to_wire_h
+        h = { "id" => id, "status" => status, "line_items" => line_items.map(&:to_wire_h),
+              "currency" => currency, "totals" => totals.map(&:to_wire_h), "links" => links.map(&:to_wire_h) }
+        h["order"] = order.to_wire_h if order
+        h
+      end
+    end
+
+    # schemas/shopping/types/order_line_item.json — distinct from LineItem:
+    # quantity is {original,total,fulfilled} tracking, plus a derived status
+    # enum, not a bare integer.
+    OrderLineItem = Data.define(:id, :item, :quantity, :totals, :status, :parent_id) do
+      def initialize(id:, item:, quantity:, totals:, status:, parent_id: nil) = super
+
+      def to_wire_h
+        q = { "total" => quantity[:total], "fulfilled" => quantity[:fulfilled] }
+        q["original"] = quantity[:original] if quantity[:original]
+        h = { "id" => id, "item" => item.to_wire_h, "quantity" => q, "totals" => totals.map(&:to_wire_h),
+              "status" => status }
+        h["parent_id"] = parent_id if parent_id
+        h
+      end
+    end
+
+    # schemas/shopping/types/expectation.json — buyer-facing delivery grouping.
+    Expectation = Data.define(:id, :line_items, :method_type, :destination, :description, :fulfillable_on) do
+      def initialize(id:, line_items:, method_type:, destination:, description: nil, fulfillable_on: nil) = super
+
+      def to_wire_h
+        h = { "id" => id, "line_items" => line_items, "method_type" => method_type, "destination" => destination }
+        h["description"] = description if description
+        h["fulfillable_on"] = fulfillable_on if fulfillable_on
+        h
+      end
+    end
+
+    # schemas/shopping/types/fulfillment_event.json — append-only shipment event.
+    FulfillmentEvent = Data.define(:id, :occurred_at, :type, :line_items, :tracking_number, :tracking_url, :carrier,
+                                   :description) do
+      def initialize(id:, occurred_at:, type:, line_items:, tracking_number: nil, tracking_url: nil, carrier: nil,
+                     description: nil)
+        super
+      end
+
+      def to_wire_h
+        h = { "id" => id, "occurred_at" => occurred_at, "type" => type, "line_items" => line_items }
+        h["tracking_number"] = tracking_number if tracking_number
+        h["tracking_url"] = tracking_url if tracking_url
+        h["carrier"] = carrier if carrier
+        h["description"] = description if description
+        h
+      end
+    end
+
+    # schemas/shopping/order.json#/properties/fulfillment — no required inner
+    # fields (expectations/events are both optional), so an adapter that
+    # doesn't model buyer-facing delivery expectations yet can pass
+    # Fulfillment.new and still be schema-conformant.
+    Fulfillment = Data.define(:expectations, :events) do
+      def initialize(expectations: [], events: []) = super
+
+      def to_wire_h
+        { "expectations" => expectations.map(&:to_wire_h), "events" => events.map(&:to_wire_h) }
+      end
+    end
+
+    # schemas/shopping/types/adjustment.json — post-order event independent of
+    # fulfillment (refund, return, credit, price_adjustment, dispute,
+    # cancellation, ...). `status` is pending/completed/failed.
+    Adjustment = Data.define(:id, :type, :occurred_at, :status, :line_items, :totals, :description) do
+      def initialize(id:, type:, occurred_at:, status:, line_items: nil, totals: nil, description: nil) = super
+
+      def to_wire_h
+        h = { "id" => id, "type" => type, "occurred_at" => occurred_at, "status" => status }
+        h["line_items"] = line_items if line_items
+        h["totals"] = totals.map(&:to_wire_h) if totals
+        h["description"] = description if description
+        h
+      end
+    end
+
+    # schemas/shopping/order.json — requires ucp/id/checkout_id/permalink_url/
+    # line_items/fulfillment/currency/totals. `adjustments` is optional —
+    # omitted from the wire payload when empty.
+    Order = Data.define(:id, :checkout_id, :permalink_url, :line_items, :fulfillment, :currency, :totals,
+                        :adjustments) do
+      def initialize(id:, checkout_id:, permalink_url:, line_items:, fulfillment:, currency:, totals:,
+                     adjustments: [])
+        super
+      end
+
+      def to_wire_h
+        h = { "id" => id, "checkout_id" => checkout_id, "permalink_url" => permalink_url,
+              "line_items" => line_items.map(&:to_wire_h), "fulfillment" => fulfillment.to_wire_h,
+              "currency" => currency, "totals" => totals.map(&:to_wire_h) }
+        h["adjustments"] = adjustments.map(&:to_wire_h) unless adjustments.empty?
+        h
+      end
+    end
+
+    Identity = Data.define(:subject, :email, :linked_at)
+  end
+end

data/lib/portage/ucp/version.rb

@@ -0,0 +1,5 @@
+module Portage
+  module Ucp
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/portage/ucp/wire_envelope.rb

@@ -0,0 +1,25 @@
+module Portage
+  module Ucp
+    # Adds the "ucp" response envelope UCP requires on Cart/Checkout/Order
+    # payloads (schemas/ucp.json's response_cart_schema/response_checkout_schema/
+    # response_order_schema) — centralized here so the version string and each
+    # capability's minimum envelope shape live in one place, not duplicated
+    # across value objects.
+    module WireEnvelope
+      SPEC_VERSION = "2026-04-08".freeze
+
+      ENVELOPES = {
+        "dev.ucp.shopping.cart" => -> { { "version" => SPEC_VERSION } },
+        "dev.ucp.shopping.checkout" => -> { { "version" => SPEC_VERSION, "payment_handlers" => {} } },
+        "dev.ucp.shopping.order" => -> { { "version" => SPEC_VERSION } }
+      }.freeze
+
+      def self.wrap(capability_name, payload_hash)
+        envelope = ENVELOPES[capability_name]
+        return payload_hash unless envelope
+
+        payload_hash.merge("ucp" => envelope.call)
+      end
+    end
+  end
+end

data/lib/portage/ucp.rb

@@ -0,0 +1,44 @@
+require_relative "ucp/version"
+require_relative "ucp/configuration"
+require_relative "ucp/errors"
+require_relative "ucp/value_objects"
+require_relative "ucp/wire_envelope"
+require_relative "ucp/adapter"
+# Shared building blocks for adapter gems (Portage::Ucp::Support) — nothing in
+# the core gem's own request path uses them, they exist so the bundled
+# Shopify/Wix/WooCommerce/... gems don't each re-derive the same money
+# conversion, dedup table and HTTP plumbing.
+require_relative "ucp/support/amounts"
+require_relative "ucp/support/totals"
+require_relative "ucp/support/line_item_status"
+require_relative "ucp/support/idempotency"
+require_relative "ucp/support/checkout_state"
+require_relative "ucp/support/api_error"
+require_relative "ucp/support/not_found"
+require_relative "ucp/support/http_client"
+require_relative "ucp/support/token_exchange"
+require_relative "ucp/payment_token_guard"
+require_relative "ucp/authenticator"
+require_relative "ucp/rate_limiter"
+require_relative "ucp/observability"
+require_relative "ucp/capability"
+require_relative "ucp/manifest"
+require_relative "ucp/schema_validator"
+require_relative "ucp/capabilities/catalog"
+require_relative "ucp/capabilities/cart"
+require_relative "ucp/capabilities/checkout"
+require_relative "ucp/capabilities/order"
+require_relative "ucp/capabilities/identity_linking"
+require_relative "ucp/capability_registry"
+require_relative "ucp/capability_negotiator"
+require_relative "ucp/dispatcher"
+require_relative "ucp/mcp/server"
+require_relative "ucp/rack/manifest_endpoint"
+require_relative "ucp/rack/webhook_endpoint"
+require_relative "ucp/resolver"
+require_relative "ucp/check"
+
+module Portage
+  module Ucp
+  end
+end

data/schemas/2026-04-08/schemas/capability.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/capability.json",
+  "title": "UCP Capability",
+  "description": "Schema for UCP capabilities and extensions. Extensions are capabilities with an 'extends' field. Uses reverse-domain naming for governance.",
+  "$defs": {
+    "base": {
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/entity"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "extends": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                  },
+                  "minItems": 1
+                }
+              ],
+              "description": "Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions."
+            }
+          }
+        }
+      ]
+    },
+    "platform_schema": {
+      "title": "Capability (Platform Schema)",
+      "description": "Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "spec",
+            "schema"
+          ]
+        }
+      ]
+    },
+    "business_schema": {
+      "title": "Capability (Business Schema)",
+      "description": "Capability configuration for business/merchant level. May include business-specific config overrides.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        }
+      ]
+    },
+    "response_schema": {
+      "title": "Capability (Response Schema)",
+      "description": "Capability reference in responses. Only name/version required to confirm active capabilities.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        }
+      ]
+    }
+  }
+}

data/schemas/2026-04-08/schemas/payment_handler.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/payment_handler.json",
+  "title": "Payment Handler",
+  "description": "Schema for UCP payment handlers. Handlers define how payment instruments are processed.",
+  "$defs": {
+    "base": {
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/entity"
+        },
+        {
+          "type": "object",
+          "required": [
+            "id"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "available_instruments": {
+              "type": "array",
+              "items": {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/available_payment_instrument.json"
+              },
+              "description": "Instrument types this handler supports, with optional constraints. When absent, every instrument should be considered available.",
+              "minItems": 1
+            }
+          }
+        }
+      ]
+    },
+    "platform_schema": {
+      "title": "Payment Handler (Platform Schema)",
+      "description": "Platform declaration for discovery profiles. May include partial config state required for discovery.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "spec",
+            "schema"
+          ]
+        }
+      ]
+    },
+    "business_schema": {
+      "title": "Payment Handler (Business Schema)",
+      "description": "Business declaration for discovery profiles. May include partial config state required for discovery.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        }
+      ]
+    },
+    "response_schema": {
+      "title": "Payment Handler (Response Schema)",
+      "description": "Handler reference in responses. May include full config state for runtime usage of the handler.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        }
+      ]
+    }
+  }
+}