portage-ucp 0.1.0

data/lib/portage/ucp/mcp/server.rb

@@ -0,0 +1,83 @@
+require "mcp"
+
+module Portage
+  module Ucp
+    module Mcp
+      # Builds an MCP::Server (from the `mcp` gem) whose tools are generated
+      # from the CapabilityRegistry's advertised actions for a given adapter,
+      # so tools/list and tools/call stay in sync with the Dispatcher/registry
+      # instead of being hand-duplicated per capability.
+      class Server
+        # Collaborators shared by every generated tool, bundled so build_tool
+        # doesn't need one keyword argument per collaborator.
+        Context = Struct.new(:dispatcher, :authenticator, :rate_limiter, :logger, keyword_init: true)
+
+        def self.build(adapter:, registry: Portage::Ucp.configuration.registry,
+                       authenticator: Portage::Ucp.configuration.authenticator,
+                       rate_limiter: Portage::Ucp.configuration.rate_limiter,
+                       logger: Portage::Ucp.configuration.logger, **server_opts)
+          context = Context.new(dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry),
+                                authenticator: authenticator, rate_limiter: rate_limiter, logger: logger)
+          tools = registry.advertised(adapter).flat_map do |capability|
+            capability.actions.map do |action_name, method_name|
+              build_tool(adapter: adapter, capability: capability, action_name: action_name,
+                         method_name: method_name, context: context)
+            end
+          end
+
+          ::MCP::Server.new(name: "portage-ucp", tools: tools, **server_opts)
+        end
+
+        def self.build_tool(adapter:, capability:, action_name:, method_name:, context:)
+          keyword_params = adapter.method(method_name).parameters.select { |type, _| %i[key keyreq].include?(type) }
+          required = keyword_params.select { |type, _| type == :keyreq }.map { |_, name| name.to_s }
+          properties = keyword_params.to_h { |_, name| [name.to_s, {}] }
+          mutating = keyword_params.any? { |_, name| name == :idempotency_key }
+
+          ::MCP::Tool.define(
+            name: action_name,
+            description: "#{capability.name}##{action_name}",
+            input_schema: { type: "object", properties: properties, required: required }
+          ) do |**kwargs|
+            Portage::Ucp::Mcp::Server.call_tool(context: context, capability: capability, action_name: action_name,
+                                                mutating: mutating, kwargs: kwargs)
+          end
+        end
+
+        def self.call_tool(context:, capability:, action_name:, mutating:, kwargs:)
+          server_context = kwargs.delete(:server_context)
+          Portage::Ucp::Observability.log(context.logger, "tool_called", capability: capability.name,
+                                                                         action: action_name, arguments: kwargs)
+
+          rejection = authorize(context.authenticator, server_context, mutating: mutating) ||
+                      rate_limit(context.rate_limiter, server_context, capability.name, mutating: mutating)
+          return rejection if rejection
+
+          result = context.dispatcher.call(capability: capability.name, action: action_name, arguments: kwargs)
+          ::MCP::Tool::Response.new(result[:content], structured_content: result[:structuredContent])
+        end
+
+        def self.authorize(authenticator, server_context, mutating:)
+          return unless mutating
+
+          authenticator.call(server_context)
+          nil
+        rescue Portage::Ucp::AuthenticationError => e
+          ::MCP::Tool::Response.new([{ type: "text", text: e.message }], error: true)
+        end
+
+        # @param key [Object] whatever the consumer's RateLimiter derives an
+        #   identity from — the gem hands over the raw MCP server_context
+        #   rather than inventing its own per-session/per-key extraction (§9).
+        def self.rate_limit(rate_limiter, key, capability_name, mutating:)
+          return unless mutating
+
+          rate_limiter.check!(key, capability_name)
+          nil
+        rescue Portage::Ucp::RateLimitExceededError => e
+          ::MCP::Tool::Response.new([{ type: "text", text: e.message }], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/observability.rb

@@ -0,0 +1,31 @@
+require "json"
+require "logger"
+
+module Portage
+  module Ucp
+    # Structured log events (§12), emitted through a consumer-injected logger
+    # (defaults to Logger.new($stdout)) so the gem instruments nothing to a
+    # specific APM — it just exposes the events. Redacts payment_token,
+    # oauth_token, and Authorization by default so a debugging trail never
+    # leaks the exact values this gem is most careful never to log.
+    module Observability
+      REDACTED_KEYS = %w[payment_token oauth_token authorization].freeze
+      REDACTED = "[REDACTED]".freeze
+
+      def self.log(logger, event, **fields)
+        logger.info(JSON.generate({ event: event }.merge(redact(fields))))
+      end
+
+      def self.redact(value)
+        case value
+        when Hash
+          value.to_h { |key, val| [key, REDACTED_KEYS.include?(key.to_s.downcase) ? REDACTED : redact(val)] }
+        when Array
+          value.map { |val| redact(val) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/payment_token_guard.rb

@@ -0,0 +1,41 @@
+module Portage
+  module Ucp
+    # PCI boundary guard (§9). complete_checkout's payment_token must be a
+    # single-use, tokenized credential from a UCP payment handler / AP2
+    # exchange — never a raw PAN. This can't prove a string *is* an opaque
+    # token, but it can catch the clearest misintegration: something that
+    # looks exactly like a card number (digits only, 12-19 characters,
+    # Luhn-valid) gets rejected before it ever reaches an Adapter, so a
+    # misintegrated agent can't push card numbers through the gem.
+    module PaymentTokenGuard
+      PAN_LENGTHS = (12..19)
+
+      def self.validate!(token)
+        return unless looks_like_pan?(token)
+
+        raise Portage::Ucp::RawPanRejectedError,
+              "payment_token looks like a raw PAN (digits only, Luhn-valid) — " \
+              "complete_checkout requires a tokenized credential, never card data"
+      end
+
+      def self.looks_like_pan?(token)
+        digits = token.to_s
+        return false unless digits.match?(/\A\d+\z/) && PAN_LENGTHS.cover?(digits.length)
+
+        luhn_valid?(digits)
+      end
+
+      def self.luhn_valid?(digits)
+        sum = digits.reverse.chars.map(&:to_i).each_with_index.sum do |digit, index|
+          next digit if index.even?
+
+          doubled = digit * 2
+          doubled > 9 ? doubled - 9 : doubled
+        end
+
+        (sum % 10).zero?
+      end
+      private_class_method :luhn_valid?
+    end
+  end
+end

data/lib/portage/ucp/rack/manifest_endpoint.rb

@@ -0,0 +1,49 @@
+require "json"
+require "rack"
+
+module Portage
+  module Ucp
+    module Rack
+      # Rack app serving GET /.well-known/ucp — the signed UCP discovery document.
+      # Mount it however suits the consumer's app (in-process or standalone, §7.3);
+      # this gem makes no assumption about host framework or process model.
+      class ManifestEndpoint
+        # @param allow_insecure [Boolean] TLS termination is the consumer's job
+        #   (§9), so by default this refuses to serve payment-handler
+        #   declarations over plaintext HTTP rather than silently leaking them.
+        #   Set true only for local development over http://localhost.
+        def initialize(manifest:, allow_insecure: false)
+          @manifest = manifest
+          @allow_insecure = allow_insecure
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+          return not_found unless request.get?
+
+          payload = @manifest.to_h
+          return insecure_rejected if payment_handlers_over_plaintext?(payload, request)
+
+          [200, { "content-type" => "application/json" }, [JSON.generate(payload)]]
+        end
+
+        private
+
+        def payment_handlers_over_plaintext?(payload, request)
+          return false if @allow_insecure || request.ssl?
+
+          !Array(payload[:payment_handlers]).empty?
+        end
+
+        def not_found
+          [404, { "content-type" => "application/json" }, [JSON.generate(error: "not_found")]]
+        end
+
+        def insecure_rejected
+          [496, { "content-type" => "application/json" },
+           [JSON.generate(error: "payment_handlers require TLS — refusing to serve over plaintext HTTP")]]
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/rack/webhook_endpoint.rb

@@ -0,0 +1,54 @@
+require "json"
+require "openssl"
+require "rack"
+
+module Portage
+  module Ucp
+    module Rack
+      # Receives backend order-lifecycle webhooks (§11). Verifies the HMAC
+      # signature against the raw body *before* parsing anything, per the
+      # standard webhook guardrail: never trust a payload before you've
+      # authenticated it. Normalizes to a Portage::Ucp::Order and hands off to a
+      # consumer-supplied `on_order_event` callback — the gem doesn't assume
+      # anything about how the consumer stores or reacts to order events.
+      class WebhookEndpoint
+        def initialize(secret:, on_order_event:, signature_header: "HTTP_X_UCP_SIGNATURE")
+          @secret = secret
+          @on_order_event = on_order_event
+          @signature_header = signature_header
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+          return respond(404, error: "not_found") unless request.post?
+
+          body = request.body.read
+          return respond(401, error: "invalid_signature") unless valid_signature?(body, env[@signature_header])
+
+          handle_order_event(body)
+        end
+
+        private
+
+        def handle_order_event(body)
+          payload = JSON.parse(body, symbolize_names: true)
+          @on_order_event.call(Portage::Ucp::Order.new(**payload))
+          respond(200, ok: true)
+        rescue JSON::ParserError, ArgumentError
+          respond(400, error: "bad_request")
+        end
+
+        def valid_signature?(body, signature)
+          return false unless signature
+
+          expected = OpenSSL::HMAC.hexdigest("SHA256", @secret, body)
+          ::Rack::Utils.secure_compare(expected, signature)
+        end
+
+        def respond(status, body)
+          [status, { "content-type" => "application/json" }, [JSON.generate(body)]]
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/rate_limiter.rb

@@ -0,0 +1,27 @@
+module Portage
+  module Ucp
+    # @abstract Pluggable rate-limit hook for mutating capabilities (§9). The
+    #   gem bundles no limiter (no storage assumption) — #check! is called
+    #   before every mutating tool call and must raise
+    #   Portage::Ucp::RateLimitExceededError to block it. The default, NullRateLimiter,
+    #   never limits: a consumer opts in to limiting by configuring one, same
+    #   as the manifest/webhook signing story elsewhere in §9.
+    class RateLimiter
+      # @param key [String] a per-session/per-caller identifier the consumer
+      #   derives from the MCP server_context (§9 says "per-session/per-key" —
+      #   which one is up to the consumer's auth setup).
+      # @param capability [String] the capability name being called, e.g.
+      #   "dev.ucp.shopping.cart", so limits can be scoped per capability.
+      def check!(_key, _capability)
+        raise NotImplementedError, "#{self.class} must implement #check!"
+      end
+    end
+
+    # The default: never limits. Present so an unconfigured server behaves
+    # exactly as it did before this hook existed, rather than silently
+    # blocking mutations the way UnconfiguredAuthenticator does for auth.
+    class NullRateLimiter < RateLimiter
+      def check!(_key, _capability); end
+    end
+  end
+end

data/lib/portage/ucp/resolver.rb

@@ -0,0 +1,133 @@
+module Portage
+  module Ucp
+    # Shared platform-detection + adapter-building logic for anything that
+    # needs to go from "a URL" to "a live Adapter for whatever commerce
+    # platform that URL runs on" — originally `Check`-only, now also used by
+    # `portage buy`'s adapter-fallback step. Neither caller should duplicate
+    # the platform table; both go through here.
+    class Resolver
+      Platform = Struct.new(:name, :gem, :require_path, :namespace, :markers, :env, :required, :build_client,
+                            :build_adapter, keyword_init: true)
+
+      # One entry per adapter gem: how to recognize the platform from its
+      # homepage, which env vars its Client/Adapter need (mirroring each
+      # gem's exe/, see their READMEs), and how to build a live instance from
+      # those env vars.
+      PLATFORMS = [
+        Platform.new(
+          name: "Shopify", gem: "portage-ucp-shopify", require_path: "portage/ucp/shopify", namespace: "Shopify",
+          markers: [/cdn\.shopify\.com/i, /Shopify\.theme/i, /\.myshopify\.com/i],
+          env: { shop_domain: "SHOPIFY_SHOP_DOMAIN", admin_access_token: "SHOPIFY_ADMIN_ACCESS_TOKEN",
+                 storefront_access_token: "SHOPIFY_STOREFRONT_ACCESS_TOKEN" },
+          required: %i[shop_domain],
+          build_client: lambda { |ns, env|
+            ns::Client.new(shop_domain: env.fetch(:shop_domain), admin_access_token: env[:admin_access_token],
+                           storefront_access_token: env[:storefront_access_token])
+          },
+          build_adapter: ->(ns, client, _env) { ns::Adapter.new(client: client) }
+        ),
+        Platform.new(
+          name: "Wix", gem: "portage-ucp-wix", require_path: "portage/ucp/wix", namespace: "Wix",
+          markers: [/static\.parastorage\.com/i, /wixstatic\.com/i, /X-Wix-Request-Id/i],
+          env: { access_token: "WIX_ACCESS_TOKEN" },
+          required: %i[access_token],
+          build_client: ->(ns, env) { ns::Client.new(access_token: env.fetch(:access_token)) },
+          build_adapter: ->(ns, client, _env) { ns::Adapter.new(client: client) }
+        ),
+        Platform.new(
+          name: "WooCommerce", gem: "portage-ucp-woocommerce", require_path: "portage/ucp/woocommerce",
+          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" },
+          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"))
+          }
+        ),
+        Platform.new(
+          name: "BigCommerce", gem: "portage-ucp-bigcommerce", require_path: "portage/ucp/bigcommerce",
+          namespace: "BigCommerce",
+          markers: [/cdn11\.bigcommerce\.com/i, /bigcommerce/i],
+          env: { store_hash: "BIGCOMMERCE_STORE_HASH", client_id: "BIGCOMMERCE_CLIENT_ID",
+                 access_token: "BIGCOMMERCE_ACCESS_TOKEN", site_url: "BIGCOMMERCE_SITE_URL",
+                 currency: "BIGCOMMERCE_CURRENCY" },
+          required: %i[store_hash client_id access_token site_url],
+          build_client: lambda { |ns, env|
+            ns::Client.new(store_hash: env.fetch(:store_hash), client_id: env.fetch(:client_id),
+                           access_token: env.fetch(:access_token))
+          },
+          build_adapter: lambda { |ns, client, env|
+            ns::Adapter.new(client: client, site_url: env.fetch(:site_url), currency: env.fetch(:currency, "USD"))
+          }
+        ),
+        Platform.new(
+          name: "Magento", gem: "portage-ucp-magento", require_path: "portage/ucp/magento", namespace: "Magento",
+          markers: [/Mage\.Cookies/i, /Magento_/i],
+          env: { base_url: "MAGENTO_BASE_URL", admin_token: "MAGENTO_ADMIN_TOKEN", currency: "MAGENTO_CURRENCY" },
+          required: %i[base_url],
+          build_client: lambda { |ns, env|
+            ns::Client.new(base_url: env.fetch(:base_url), admin_token: env[:admin_token])
+          },
+          build_adapter: lambda { |ns, client, env|
+            ns::Adapter.new(client: client, site_url: env.fetch(:base_url), currency: env.fetch(:currency, "USD"))
+          }
+        ),
+        Platform.new(
+          name: "Etsy", gem: "portage-ucp-etsy", require_path: "portage/ucp/etsy", namespace: "Etsy",
+          markers: [/etsy\.com/i],
+          env: { access_token: "ETSY_ACCESS_TOKEN", api_key: "ETSY_API_KEY", shop_id: "ETSY_SHOP_ID" },
+          required: %i[access_token api_key shop_id],
+          build_client: lambda { |ns, env|
+            ns::Client.new(access_token: env.fetch(:access_token), api_key: env.fetch(:api_key))
+          },
+          build_adapter: ->(ns, client, env) { ns::Adapter.new(client: client, shop_id: env.fetch(:shop_id)) }
+        ),
+        Platform.new(
+          name: "Instagram/Facebook Shops", gem: "portage-ucp-instagram", require_path: "portage/ucp/instagram",
+          namespace: "Instagram",
+          markers: [%r{instagram\.com/[^/]+/shop}i, %r{facebook\.com/.*/shop}i],
+          env: { access_token: "META_ACCESS_TOKEN", catalog_id: "META_CATALOG_ID" },
+          required: %i[access_token catalog_id],
+          build_client: ->(ns, env) { ns::Client.new(access_token: env.fetch(:access_token)) },
+          build_adapter: ->(ns, client, env) { ns::Adapter.new(client: client, catalog_id: env.fetch(:catalog_id)) }
+        )
+      ].freeze
+
+      # @return [Platform, nil] the first platform whose markers match the
+      #   given homepage body/headers, or nil if nothing recognizable was found.
+      def self.detect_platform(body, headers)
+        haystack = [body, headers.to_a.flatten.join(" ")].compact.join(" ")
+        PLATFORMS.find { |platform| platform.markers.any? { |marker| haystack =~ marker } }
+      end
+
+      # @return [Hash<Symbol, String, nil>] the platform's env vars read from
+      #   the process environment, keyed the same as Platform#env/#required.
+      def self.env_for(platform)
+        platform.env.transform_values { |var| ENV.fetch(var, nil) }
+      end
+
+      # @return [Array<String>] the env var names still missing for this
+      #   platform to be usable, or an empty array if all required vars are set.
+      def self.missing_env(platform, env)
+        platform.required.select { |key| env[key].nil? }.map { |key| platform.env[key] }
+      end
+
+      # Builds a live Adapter for the given platform from the given env hash
+      # (as returned by .env_for). Raises LoadError if the adapter gem isn't
+      # installed — callers decide how to handle that (e.g. Check reports it
+      # as a skipped probe rather than crashing).
+      # @return [Portage::Ucp::Adapter]
+      def self.build_adapter(platform, env)
+        require platform.require_path
+        namespace = Portage::Ucp.const_get(platform.namespace)
+        client = platform.build_client.call(namespace, env)
+        platform.build_adapter.call(namespace, client, env)
+      end
+    end
+  end
+end

data/lib/portage/ucp/schema_validator.rb

@@ -0,0 +1,53 @@
+require "json"
+require "json_schemer"
+
+module Portage
+  module Ucp
+    # Validates data against UCP's own published JSON Schemas / OpenRPC docs —
+    # offline, against the copy vendored under schemas/<version>/ (see §13:
+    # ucpchecker.com is a manual pre-release check only, never a CI gate; this
+    # is the CI-safe equivalent).
+    #
+    # The vendored tree mirrors https://ucp.dev/<version>/... path-for-path
+    # (schemas/2026-04-08/schemas/shopping/cart.json <->
+    # https://ucp.dev/2026-04-08/schemas/shopping/cart.json), so every $ref
+    # inside a vendored document — however deeply nested — resolves to another
+    # vendored file with a single prefix rewrite, no network access needed.
+    class SchemaValidator
+      def initialize(version: "2026-04-08", root: File.join(__dir__, "..", "..", "..", "schemas"))
+        @base_url = "https://ucp.dev/#{version}/"
+        @base_dir = File.expand_path(File.join(root, version))
+      end
+
+      # @param relative_path [String] e.g. "schemas/shopping/cart.json", matching
+      #   the vendored path under schemas/<version>/.
+      # @return [Array<String>] human-readable validation error messages: empty
+      #   means `data` conforms.
+      def errors_for(relative_path, data)
+        schemer = JSONSchemer.schema(load(relative_path), ref_resolver: method(:resolve_ref))
+        schemer.validate(data).map { |error| JSONSchemer::Errors.pretty(error) }
+      end
+
+      def valid?(relative_path, data)
+        errors_for(relative_path, data).empty?
+      end
+
+      # Method names declared by a vendored OpenRPC document, e.g.
+      # "services/shopping/mcp.openrpc.json" -> %w[create_checkout get_cart ...].
+      def method_names(relative_path)
+        load(relative_path).fetch("methods").map { |m| m.fetch("name") }
+      end
+
+      private
+
+      def resolve_ref(uri)
+        relative_path = uri.to_s.delete_prefix(@base_url).sub(/#.*/, "")
+        load(relative_path)
+      end
+
+      def load(relative_path)
+        JSON.parse(File.read(File.join(@base_dir, relative_path)))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+require "bigdecimal"
+
+module Portage
+  module Ucp
+    module Support
+      # Money arithmetic every adapter gem's Mapper needs. UCP wire shapes
+      # carry integer minor units (schemas/shopping/types/total.json), while
+      # commerce APIs hand back either decimal strings ("12.50") or already-
+      # minor-unit integers-as-strings ("1250") — one conversion per shape,
+      # defined once here rather than re-derived per gem.
+      #
+      # Mappers keep their own one-line `money`/`minor_units` wrappers around
+      # these: the wrapper's signature is platform-shaped (a GraphQL price
+      # node, an amount plus a threaded-in currency), only the arithmetic is
+      # shared.
+      module Amounts
+        module_function
+
+        # Decimal-string (or numeric) major units -> integer minor units.
+        # nil/"" is 0 rather than an exception: several APIs omit a money
+        # field entirely instead of sending a zero.
+        def decimal_to_minor(amount)
+          return 0 if amount.nil? || amount == ""
+
+          (BigDecimal(amount.to_s) * 100).to_i
+        end
+
+        # Already-minor-unit values (e.g. WooCommerce's Store API sends "500"
+        # for $5.00, tagged with its own `currency_minor_unit`) — an integer
+        # parse, no BigDecimal scaling.
+        def subunits_to_minor(amount)
+          return 0 if amount.nil?
+
+          amount.to_i
+        end
+
+        def money(amount, currency)
+          Portage::Ucp::Money.new(amount_minor: decimal_to_minor(amount), currency: currency)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Portage
+  module Ucp
+    module Support
+      # Mixed into each adapter gem's own ApiError, which stays a subclass of
+      # that gem's Error (so `rescue Portage::Ucp::Wix::Error` keeps catching
+      # everything the Wix gem raises) — a module rather than a base class
+      # precisely to leave that hierarchy alone.
+      #
+      # Carries the two things every gem's ApiError carried identically: the
+      # HTTP status (which Support::NotFound#nil_on_not_found reads) and the parsed
+      # body. What differs per platform is only where the human-readable
+      # message lives inside that body, which is the `detail` hook.
+      module ApiError
+        attr_reader :status, :body
+
+        def initialize(status, body)
+          @status = status
+          @body = body
+          super("#{api_label} API error (#{status}): #{detail(body)}")
+        end
+
+        private
+
+        # Defaults to the including gem's module name — Portage::Ucp::Wix::
+        # ApiError reports "Wix". Override where the API's public name isn't
+        # the gem's (e.g. Instagram calls into Meta's Graph API).
+        def api_label
+          self.class.name.split("::")[-2]
+        end
+
+        # Override with the platform's error-body shape, e.g.
+        # `body["message"] || body`.
+        def detail(body)
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Portage
+  module Ucp
+    module Support
+      # Adapter-side bookkeeping for the two things UCP's schemas require but
+      # most commerce APIs don't model:
+      #
+      # - Checkout#status. Shopify, WooCommerce and BigCommerce all treat a
+      #   checkout as the cart (or as the cart plus billing data), with no
+      #   lifecycle enum of its own, so the adapter tracks status itself
+      #   across create/update/complete/cancel.
+      # - Order#checkout_id. Nothing on those platforms' Order links back to
+      #   the cart/checkout that produced it, so the adapter records the pair
+      #   at completion time — the only moment both ids are in hand.
+      #
+      # Both default rather than raise on an unknown id ("incomplete" and "",
+      # respectively): a checkout this process didn't create is still
+      # schema-valid to report, just not information-complete.
+      module CheckoutState
+        private
+
+        def checkout_status(checkout_id)
+          (@checkout_status ||= {}).fetch(checkout_id, "incomplete")
+        end
+
+        def record_checkout_status(checkout_id, status)
+          (@checkout_status ||= {})[checkout_id] = status
+        end
+
+        # Keyed by String: adapters are called with an order id straight off
+        # a JSON body, which is an Integer on some platforms and a String on
+        # others depending on the call path.
+        def record_order_checkout(order_id, checkout_id)
+          (@order_checkout_ids ||= {})[order_id.to_s] = checkout_id
+        end
+
+        def checkout_id_for(order_id)
+          (@order_checkout_ids ||= {}).fetch(order_id.to_s, "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Portage
+  module Ucp
+    module Support
+      # The plain Net::HTTP + JSON request/response handling every adapter
+      # gem's Client repeated. Deliberately Net::HTTP rather than a per-
+      # platform vendor gem: a generic adapter any Ruby app can drop in
+      # shouldn't drag in framework coupling, and it stays trivially
+      # stubbable with WebMock.
+      #
+      # An including Client supplies two things — its auth headers and paths
+      # (by building the uri/headers it passes to #json_request) and
+      # #api_error_class, the gem's own ApiError to raise on a non-2xx.
+      module HttpClient
+        private
+
+        # @param basic_auth [Array(String, String), nil] user/password pair
+        #   for APIs authorized with HTTP Basic rather than a header token
+        #   (e.g. WooCommerce's Admin consumer key/secret).
+        # @param raw [Boolean] return the Net::HTTPResponse itself instead of
+        #   the parsed body — for callers that need response headers (e.g.
+        #   WooCommerce's Cart-Token session threading). They call #parse!
+        #   themselves once they're done reading headers.
+        def json_request(http_method, uri, body: nil, headers: {}, basic_auth: nil, raw: false)
+          uri = URI(uri.to_s)
+          request = http_method.new(uri)
+          request.basic_auth(*basic_auth) if basic_auth
+          headers.each { |name, value| request[name] = value }
+          request["Content-Type"] ||= "application/json"
+          request.body = JSON.generate(body) if body
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
+          raw ? response : parse!(response)
+        end
+
+        # An empty body is `{}` rather than a parse error: several APIs
+        # answer a successful DELETE with 204 and no content at all.
+        def parse!(response)
+          parsed = response.body.nil? || response.body.empty? ? {} : JSON.parse(response.body)
+          raise api_error_class.new(response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
+
+          parsed
+        end
+
+        def api_error_class
+          raise Portage::Ucp::NotImplementedError, "#{self.class} must implement #api_error_class"
+        end
+      end
+    end
+  end
+end