portage-ucp-shopify 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8f438d6772598dbb5b6fcf3af94f98e6d63d4b2e4b79168aa86821ebb02d087
-  data.tar.gz: 72e29d9c756a5fbee5484bb7aa1a31780f7bf7682634da0681a2d6486befc465
+  metadata.gz: ac2f2ad9119012864ff7ab41827c1cff716f4f7b1092d200d2810d8cb2ef7b5b
+  data.tar.gz: 4225325c543f10ed8a2c1f0adda77667f6224ec70c8e3d412b666a55345a81f4
 SHA512:
-  metadata.gz: ae783d948bf5cc3fa62e4dc23daaccf816af84504bd6cf9d371ff53fa3354a37a952e1d643d158fb725ccd31b97f88d276c051ea13761ee214233c23932240c3
-  data.tar.gz: 0f61debccf472e8d803bdf6c09ec40fce927bae828f6aba4a5d2191a79638613b9a896ee2ad42d8ebbccea5e150cd5769317942dee3a792afa91986655719ac5
+  metadata.gz: 49d90b4545a07f1685fe54d34bf53f0acc3919c0e1d8ca37398d3ac460ab460047ba42406d711c3e7c27c42c26d677c625114693be3914aa3676023dee6d5325
+  data.tar.gz: 81aba41eed72b01960b045978c9657de5b29d352df4ce52f3c165deee1f833d3ca2c9274e55e6a08d4a110ffcadcfb8dcf737eeff22c5412c517ca8e3cad5b12

data/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.3.0] - 2026-08-27
+
+- `metadata_field` config DSL (`Configuration`) — lets a merchant map their
+  own Shopify metafields onto UCP catalog attributes without a code change,
+  instead of every merchant-specific field needing a fork of `mapper.rb`.
+- Four catalog/cart GraphQL shape fixes against the real Admin/Storefront
+  API, none catchable by `adapter_spec.rb`'s hand-rolled webmock stubs since
+  those fabricate response shapes by hand:
+  - `ProductVariant#price`/`#compareAtPrice` are the bare `Money` scalar (a
+    decimal string), not a `MoneyV2` object — the live Admin API 2026-04
+    schema rejects `{ amount currencyCode }` sub-selections on them.
+  - `ProductCompareAtPriceRange`'s fields are `minVariantCompareAtPrice`/
+    `maxVariantCompareAtPrice`, not `minVariantPrice`/`maxVariantPrice`
+    (those belong to `ProductPriceRangeV2` and were copy-pasted onto the
+    compare-at query and mapper).
+  - Cart `deliveryGroups` is a connection (`.nodes`), not a bare array.
+  - Cart `totalTaxAmount` is nullable — a fresh cart genuinely has no tax
+    amount yet rather than a zero one, until Shopify has enough context
+    (shipping address, tax-registered market) to compute it.
+- Bounded retry with backoff and normalized conflict/throttle errors on
+  requests to Shopify, via the core gem's new `Support::Retry`.
+- Per-cart/checkout mutations against Shopify are now serialized per session
+  (core gem's new `Support::SessionLock`), so two concurrent requests against
+  the same cart can't race each other.
+- `existing_variant_id` support in the adapter conformance kit — Shopify
+  needs a Product GID for catalog lookups and a separate ProductVariant GID
+  for cart line items, which `existing_product_id` alone can't express.
+- Adapter now runs the core gem's conformance kit against a real `Adapter`
+  through a real `Dispatcher` (`spec/portage/ucp/shopify/conformance_spec.rb`).
+
 ## [0.2.0] - 2026-08-21
 
 - `CartInput.discountCodes` on create, `cartDiscountCodesUpdate` on update —

data/lib/portage/ucp/shopify/adapter.rb

@@ -34,6 +34,20 @@ module Portage
         # back to the cart that produced it — both are tracked adapter-side
         # via Support::CheckoutState.
         include Portage::Ucp::Support::CheckoutState
+        # #replace_lines, #apply_fulfillment and #submit_payment are each a
+        # read-modify-write across multiple Storefront calls with no atomic
+        # equivalent upstream — two concurrent calls against the same
+        # cart/checkout id can interleave and drop each other's writes, not
+        # just race on the same eventual value (§21). Support::SessionLock
+        # serializes by id so the second call waits instead of interleaving.
+        include Portage::Ucp::Support::SessionLock
+        # #poll_submission retries a SubmitThrottled cartSubmitForCompletion
+        # response instead of handing the caller an ambiguous
+        # "complete_in_progress" — safe because #submit_payment (its only
+        # caller) is always reached through #complete_checkout's dedup.
+        include Portage::Ucp::Support::Retry
+
+        SUBMIT_POLL_MAX_ATTEMPTS = 3
 
         def initialize(client:)
           super()
@@ -41,14 +55,15 @@ module Portage
         end
 
         def search_catalog(query:, limit:)
-          data = @client.admin_query(Queries::SEARCH_CATALOG, variables: { query: query, first: limit })
-          data.dig("products", "nodes").map { |node| Mapper.product(node) }
+          data = @client.admin_query(Queries.search_catalog_query, variables: { query: query, first: limit })
+          products = data.dig("products", "nodes").map { |node| Mapper.product(node) }
+          Portage::Ucp::CatalogSearchResult.new(products: products)
         end
 
         def get_product(product_id:)
-          data = @client.admin_query(Queries::GET_PRODUCT, variables: { id: product_id })
+          data = @client.admin_query(Queries.product_by_id_query, variables: { id: product_id })
           node = data["product"]
-          node && Mapper.product(node)
+          node && Portage::Ucp::ProductDetail.new(product: Mapper.product(node))
         end
 
         def get_cart(cart_id:)
@@ -195,15 +210,17 @@ module Portage
         # optional and independent — an agent picking a rate on an
         # already-addressed cart sends only the latter.
         def apply_fulfillment(cart_id, fulfillment)
-          cart_node = fetch_cart_node(cart_id)
+          synchronize(cart_id) do
+            cart_node = fetch_cart_node(cart_id)
 
-          destination = fulfillment.shipping_methods.flat_map(&:destinations).first
-          cart_node = apply_delivery_address(cart_id, destination.address) if destination
+            destination = fulfillment.shipping_methods.flat_map(&:destinations).first
+            cart_node = apply_delivery_address(cart_id, destination.address) if destination
 
-          selections = fulfillment.shipping_methods.flat_map(&:groups).filter_map { |g| delivery_selection(g) }
-          cart_node = apply_delivery_selections(cart_id, selections) unless selections.empty?
+            selections = fulfillment.shipping_methods.flat_map(&:groups).filter_map { |g| delivery_selection(g) }
+            cart_node = apply_delivery_selections(cart_id, selections) unless selections.empty?
 
-          cart_node
+            cart_node
+          end
         end
 
         def delivery_selection(group)
@@ -250,23 +267,27 @@ module Portage
         end
 
         def replace_lines(cart_id, line_items, discount_codes)
-          current_line_ids = fetch_cart_node(cart_id).dig("lines", "nodes").map { |n| n["id"] }
-          unless current_line_ids.empty?
-            removed = @client.storefront_query(Queries::CART_LINES_REMOVE,
-                                               variables: { cartId: cart_id, lineIds: current_line_ids })
-            unwrap!(removed, "cartLinesRemove")
-          end
-
-          cart_node = if line_items.empty?
-                        fetch_cart_node(cart_id)
-                      else
-                        added = @client.storefront_query(Queries::CART_LINES_ADD,
-                                                         variables: { cartId: cart_id, lines: cart_lines(line_items) })
-                        unwrap!(added, "cartLinesAdd")
-                      end
-          return cart_node if discount_codes.nil?
+          synchronize(cart_id) do
+            current_line_ids = fetch_cart_node(cart_id).dig("lines", "nodes").map { |n| n["id"] }
+            unless current_line_ids.empty?
+              removed = @client.storefront_query(Queries::CART_LINES_REMOVE,
+                                                 variables: { cartId: cart_id, lineIds: current_line_ids })
+              unwrap!(removed, "cartLinesRemove")
+            end
 
-          apply_discount_codes(cart_id, discount_codes)
+            cart_node = if line_items.empty?
+                          fetch_cart_node(cart_id)
+                        else
+                          added = @client.storefront_query(
+                            Queries::CART_LINES_ADD,
+                            variables: { cartId: cart_id, lines: cart_lines(line_items) }
+                          )
+                          unwrap!(added, "cartLinesAdd")
+                        end
+            next cart_node if discount_codes.nil?
+
+            apply_discount_codes(cart_id, discount_codes)
+          end
         end
 
         def apply_discount_codes(cart_id, discount_codes)
@@ -279,19 +300,17 @@ module Portage
         # — Shopify natively dedups that one call via SubmitAlreadyAccepted, on
         # top of #complete_checkout's own dedup wrapper.
         def submit_payment(checkout_id, payment_token, idempotency_key)
-          cart_node = fetch_cart_node(checkout_id)
-          raise Portage::Ucp::Shopify::Error, "cart #{checkout_id} not found" unless cart_node
+          synchronize(checkout_id) do
+            cart_node = fetch_cart_node(checkout_id)
+            raise Portage::Ucp::Shopify::Error, "cart #{checkout_id} not found" unless cart_node
 
-          raise_if_any_line_unavailable!(cart_node)
+            raise_if_any_line_unavailable!(cart_node)
 
-          pay_for_cart(checkout_id, cart_node.dig("cost", "totalAmount"), payment_token)
+            pay_for_cart(checkout_id, cart_node.dig("cost", "totalAmount"), payment_token)
 
-          submit_data = @client.storefront_query(Queries::CART_SUBMIT_FOR_COMPLETION,
-                                                 variables: { cartId: checkout_id, attemptToken: idempotency_key })
-          status = unwrap_submit!(submit_data)
-          record_checkout_status(checkout_id, status)
-          order = link_cart_to_order(checkout_id) if status == "completed"
-          Mapper.checkout(cart_node, status: status, order: order)
+            status, order = poll_submission(checkout_id, idempotency_key)
+            Mapper.checkout(cart_node, status: status, order: order)
+          end
         end
 
         def pay_for_cart(checkout_id, total, payment_token)
@@ -304,16 +323,14 @@ module Portage
           unwrap!(payment_data, "cartPaymentUpdate")
         end
 
-        # Best-effort: if `status` is `complete_in_progress` (SubmitThrottled),
-        # the order doesn't exist yet, so there's nothing to look up — a poller
-        # calling #get_checkout again later would need to retry this too, which
-        # this adapter doesn't do on its own. If the order search index hasn't
-        # caught up yet even for a synchronously-completed cart, this silently
-        # finds nothing (returns nil, #get_order's checkout_id stays blank)
-        # rather than raising, matching the "not information-complete but
-        # schema-valid" posture used elsewhere in this file. Also the only
-        # place that can hand the freshly-created order id back to
-        # #complete_checkout's own caller — nothing else surfaces it.
+        # Best-effort: only called once `status` is "completed" (#poll_submission
+        # already retried through any SubmitThrottled), but if the order search
+        # index hasn't caught up yet even so, this silently finds nothing
+        # (returns nil, #get_order's checkout_id stays blank) rather than
+        # raising, matching the "not information-complete but schema-valid"
+        # posture used elsewhere in this file. Also the only place that can
+        # hand the freshly-created order id back to #complete_checkout's own
+        # caller — nothing else surfaces it.
         def link_cart_to_order(checkout_id)
           token = checkout_id[%r{Cart/([^?]+)}, 1]
           return unless token
@@ -326,6 +343,29 @@ module Portage
           Portage::Ucp::OrderConfirmation.new(id: order_node["id"], permalink_url: order_node["statusPageUrl"])
         end
 
+        # Retries a SubmitThrottled cartSubmitForCompletion up to
+        # SUBMIT_POLL_MAX_ATTEMPTS, honoring each attempt's own pollAfter as
+        # the wait (see SubmitThrottled#retry_after). If Shopify is still
+        # throttled once attempts run out, that's surfaced to the caller as
+        # Portage::Ucp::UpstreamThrottledError rather than silently handing
+        # back an ambiguous "complete_in_progress" forever.
+        def poll_submission(checkout_id, idempotency_key)
+          with_retry(max_attempts: SUBMIT_POLL_MAX_ATTEMPTS) do
+            submit_data = @client.storefront_query(Queries::CART_SUBMIT_FOR_COMPLETION,
+                                                   variables: { cartId: checkout_id, attemptToken: idempotency_key })
+            status = unwrap_submit!(submit_data)
+            record_checkout_status(checkout_id, status)
+            order = link_cart_to_order(checkout_id) if status == "completed"
+            [status, order]
+          end
+        rescue Portage::Ucp::Shopify::SubmitThrottled
+          raise Portage::Ucp::UpstreamThrottledError, "checkout #{checkout_id} still processing after retries"
+        end
+
+        def retryable_error?(error)
+          error.is_a?(Portage::Ucp::Shopify::SubmitThrottled) || super
+        end
+
         def unwrap!(data, field)
           payload = data.fetch(field)
           errors = payload["userErrors"]
@@ -358,8 +398,9 @@ module Portage
 
           result = payload["result"]
           raise Portage::Ucp::Shopify::Error, result.dig("errors", 0, "message") if result["errors"]
+          raise Portage::Ucp::Shopify::SubmitThrottled, result["pollAfter"] if result.key?("pollAfter")
 
-          result.key?("pollAfter") ? "complete_in_progress" : "completed"
+          "completed"
         end
       end
     end

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

@@ -19,6 +19,12 @@ module Portage
       # arbitrary order). The adapter picks whichever API actually has the
       # data it needs (see Portage::Ucp::Shopify::Adapter).
       class Client
+        # Retries a bare THROTTLED GraphQL response or a transport 5xx —
+        # safe here because every Adapter mutation calling into this Client
+        # is already wrapped in Support::Idempotency#dedup, and every read
+        # is naturally idempotent (see Support::Retry's own doc comment).
+        include Portage::Ucp::Support::Retry
+
         DEFAULT_API_VERSION = "2026-04".freeze
 
         def initialize(shop_domain:, admin_access_token: nil, storefront_access_token: nil,
@@ -31,15 +37,19 @@ module Portage
 
         def admin_query(query, variables: {})
           require_token!(@admin_access_token, "admin_access_token")
-          post("/admin/api/#{@api_version}/graphql.json", headers: { "X-Shopify-Access-Token" => @admin_access_token },
-                                                          query: query, variables: variables)
+          with_retry do
+            post("/admin/api/#{@api_version}/graphql.json",
+                 headers: { "X-Shopify-Access-Token" => @admin_access_token }, query: query, variables: variables)
+          end
         end
 
         def storefront_query(query, variables: {})
           require_token!(@storefront_access_token, "storefront_access_token")
-          post("/api/#{@api_version}/graphql.json",
-               headers: { "X-Shopify-Storefront-Access-Token" => @storefront_access_token },
-               query: query, variables: variables)
+          with_retry do
+            post("/api/#{@api_version}/graphql.json",
+                 headers: { "X-Shopify-Storefront-Access-Token" => @storefront_access_token },
+                 query: query, variables: variables)
+          end
         end
 
         private
@@ -48,6 +58,18 @@ module Portage
           raise ArgumentError, "Portage::Ucp::Shopify::Client requires #{name} for this call" unless token
         end
 
+        # Shopify's GraphQL THROTTLED code has no HTTP status of its own, and
+        # a transport 5xx here has no well-formed userErrors/GraphQL body to
+        # fall back on — Support::Retry's default `#status`-based check
+        # covers neither, so this hands both to it explicitly.
+        def retryable_error?(error)
+          case error
+          when Portage::Ucp::Shopify::ServerError then true
+          when Portage::Ucp::Shopify::GraphqlError then error.throttled?
+          else super
+          end
+        end
+
         def post(path, headers:, query:, variables:)
           uri = URI("https://#{@shop_domain}#{path}")
           request = Net::HTTP::Post.new(uri)
@@ -56,6 +78,9 @@ module Portage
           request.body = JSON.generate({ query: query, variables: variables })
 
           response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+          status = response.code.to_i
+          raise Portage::Ucp::Shopify::ServerError, status if status >= 500
+
           body = JSON.parse(response.body)
           raise Portage::Ucp::Shopify::GraphqlError, body["errors"] if body["errors"]
 

data/lib/portage/ucp/shopify/configuration.rb

@@ -0,0 +1,70 @@
+module Portage
+  module Ucp
+    module Shopify
+      # Shopify-specific config, deliberately separate from core's own
+      # Portage::Ucp::Configuration (registry/authenticator/rate_limiter/...,
+      # already adapter-agnostic — see portage-ucp/lib/portage/ucp/configuration.rb).
+      # `Portage::Ucp::Shopify.configuration.metadata_fields` living on this
+      # singleton instead is what keeps Mapper's "nothing Shopify-shaped leaks
+      # past this file" posture intact: a Wix/WooCommerce consumer configuring
+      # their own adapter never sees Shopify's metafield config surface.
+      class Configuration
+        # Shopify caps `metafields(identifiers:)` at 250 identifiers per call
+        # (design-log §20). Enforced here rather than left to a confusing
+        # GraphQL cost-limit rejection from Shopify itself.
+        MAX_METAFIELD_IDENTIFIERS = 250
+
+        class InvalidMetadataField < ArgumentError; end
+
+        def initialize
+          @product_metadata_fields = []
+          @variant_metadata_fields = []
+        end
+
+        # Registers a merchant-defined metafield as a Product/Variant#metadata
+        # entry. `metafield:` is "namespace.key" (Shopify's own addressing,
+        # e.g. "custom.color_code"). `scope:` picks which GraphQL field
+        # (Product#metafields vs. ProductVariant#metafields — separate fields,
+        # separate cost, per Shopify's Admin API) the identifier is fetched
+        # through, since a real catalog needs both (color_hex naturally varies
+        # per variant, fabric_content is usually product-wide).
+        def metadata_field(key, metafield:, scope: :product)
+          namespace, metafield_key = metafield.split(".", 2)
+          unless metafield_key
+            raise InvalidMetadataField, "metafield: must be \"namespace.key\", got #{metafield.inspect}"
+          end
+
+          fields = fields_for(scope)
+          if fields.size >= MAX_METAFIELD_IDENTIFIERS
+            raise InvalidMetadataField,
+                  "#{scope} metadata_fields already at Shopify's #{MAX_METAFIELD_IDENTIFIERS}-identifier " \
+                  "metafields(identifiers:) cap — drop one before adding #{key.inspect}"
+          end
+
+          fields << { key: key.to_s, namespace: namespace, metafield_key: metafield_key }
+        end
+
+        # Read by Queries (to build the metafields fragment) and Mapper (to
+        # know which response entry maps to which UCP key) — both index by
+        # scope, not by name, so this is the one shared accessor.
+        def fields_for(scope)
+          case scope
+          when :product then @product_metadata_fields
+          when :variant then @variant_metadata_fields
+          else raise InvalidMetadataField, "scope: must be :product or :variant, got #{scope.inspect}"
+          end
+        end
+      end
+
+      class << self
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        def configure
+          yield configuration
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/shopify/errors.rb

@@ -1,3 +1,5 @@
+require "time"
+
 module Portage
   module Ucp
     module Shopify
@@ -9,8 +11,16 @@ module Portage
       # rejection (e.g. "line item not found").
       class GraphqlError < Error
         def initialize(errors)
+          @errors = errors
           super(errors.map { |e| e["message"] }.join("; "))
         end
+
+        # Shopify's cost-throttling reports THROTTLED as a top-level error's
+        # extensions.code, not an HTTP status — Client#retryable_error? uses
+        # this to hand it to Support::Retry alongside 429/5xx.
+        def throttled?
+          @errors.any? { |e| e.dig("extensions", "code") == "THROTTLED" }
+        end
       end
 
       # Raised when a mutation's `userErrors` array is non-empty.
@@ -19,6 +29,39 @@ module Portage
           super("#{field} userErrors: #{errors.map { |e| e['message'] }.join('; ')}")
         end
       end
+
+      # Raised for a bare 5xx HTTP status from either GraphQL endpoint —
+      # unlike GraphqlError/UserError, there's no well-formed JSON body to
+      # read a message from at this layer. Retryable by
+      # Client#retryable_error?, same as any other platform's transport 5xx.
+      class ServerError < Error
+        attr_reader :status
+
+        def initialize(status)
+          @status = status
+          super("Shopify API server error (#{status})")
+        end
+      end
+
+      # Raised when cartSubmitForCompletion answers SubmitThrottled —
+      # Shopify is still processing the submission and says to poll again
+      # after `poll_after`. Adapter#poll_submission retries on this (see
+      # Support::Retry) instead of handing an ambiguous
+      # "complete_in_progress" straight back to the caller; if retries
+      # exhaust while Shopify is still throttled, it's re-raised as
+      # Portage::Ucp::UpstreamThrottledError.
+      class SubmitThrottled < Error
+        attr_reader :poll_after
+
+        def initialize(poll_after)
+          @poll_after = poll_after
+          super("cartSubmitForCompletion still processing, poll after #{poll_after}")
+        end
+
+        def retry_after
+          [Time.parse(poll_after) - Time.now, 0].max
+        end
+      end
     end
   end
 end

data/lib/portage/ucp/shopify/mapper.rb

@@ -21,20 +21,153 @@ module Portage
           Portage::Ucp::Support::Amounts.decimal_to_minor(price["amount"])
         end
 
+        # dev.ucp.shopping.catalog's Price (types/price.json) — the
+        # wire-shape counterpart to #money above, used everywhere a Product/
+        # Variant field carries currency directly rather than through the
+        # arithmetic-only Money type.
+        def price(node)
+          Portage::Ucp::Price.new(amount: minor_units(node), currency: node["currencyCode"])
+        end
+
         def product(node)
+          currency = node.dig("priceRange", "minVariantPrice", "currencyCode")
           Portage::Ucp::Product.new(
             id: node["id"],
+            handle: node["handle"],
             title: node["title"],
-            description: node["description"],
-            price: money(node.dig("priceRange", "minVariantPrice")),
-            available: node["availableForSale"],
-            variants: node.dig("variants", "nodes").map { |v| variant(v) },
-            url: node["onlineStoreUrl"]
+            description: description(node),
+            price_range: price_range(node["priceRange"]),
+            list_price_range: compare_at_price_range(node["compareAtPriceRange"]),
+            variants: node.dig("variants", "nodes").map { |v| variant(v, description(node), currency) },
+            options: (node["options"] || []).map { |o| product_option(o) },
+            media: product_media(node.dig("featuredMedia", "nodes", 0)),
+            tags: node["tags"] || [],
+            url: node["onlineStoreUrl"],
+            metadata: metafields_metadata(node["metafields"], :product)
           )
         end
 
-        def variant(node)
-          { id: node["id"], title: node["title"], available: node["availableForSale"], price: money(node["price"]) }
+        # Shopify's `type` tags a metafield with one of ~20 encodings
+        # (design-log §20 handoff). Only the ones where passing the raw
+        # string through would be actively wrong for an agent to consume get
+        # parsed here — `json`, `dimension`/`measurement` (both
+        # `{"value":..,"unit":..}`-shaped JSON strings), and any `list.*`
+        # (a JSON array of the scalar type). Everything else (plain text,
+        # numbers, dates, refs, ...) passes through as Shopify sent it.
+        METAFIELD_JSON_TYPES = %w[json dimension measurement].freeze
+
+        def parse_metafield_value(value, type)
+          return JSON.parse(value) if METAFIELD_JSON_TYPES.include?(type) || type&.start_with?("list.")
+
+          value
+        end
+
+        # `metafields` is nil when nothing's configured for `scope` (the
+        # fragment itself was omitted from the query — see
+        # Queries.metafields_fragment) — that's the common case and returns
+        # nil rather than {}, matching Product/Variant#metadata's own
+        # nil-by-default. Otherwise it's Shopify's `metafields(identifiers:)`
+        # array, positional against the same
+        # `Portage::Ucp::Shopify.configuration.fields_for(scope)` list the
+        # query was built from, with a nil entry wherever that metafield
+        # isn't set on this product/variant.
+        def metafields_metadata(metafields, scope)
+          return nil if metafields.nil?
+
+          fields = Portage::Ucp::Shopify.configuration.fields_for(scope)
+          metadata = fields.zip(metafields).each_with_object({}) do |(field, metafield), acc|
+            next unless field && metafield && metafield["value"]
+
+            acc[field[:key]] = parse_metafield_value(metafield["value"], metafield["type"])
+          end
+          metadata.empty? ? nil : metadata
+        end
+
+        def description(node)
+          Portage::Ucp::Description.new(plain: node["description"], html: node["descriptionHtml"])
+        end
+
+        def price_range(node)
+          Portage::Ucp::PriceRange.new(min: price(node["minVariantPrice"]), max: price(node["maxVariantPrice"]))
+        end
+
+        # nil when Shopify's compareAtPriceRange itself is nil (no variant
+        # has a compare-at price set) rather than a zeroed-out range —
+        # Product#list_price_range is optional, so "no strikethrough price"
+        # should mean the field is absent, not present-and-zero.
+        def compare_at_price_range(node)
+          return nil unless node
+
+          Portage::Ucp::PriceRange.new(min: price(node["minVariantCompareAtPrice"]),
+                                       max: price(node["maxVariantCompareAtPrice"]))
+        end
+
+        def product_option(node)
+          values = (node["optionValues"] || []).map { |v| Portage::Ucp::OptionValue.new(id: v["id"], label: v["name"]) }
+          Portage::Ucp::ProductOption.new(name: node["name"], values: values)
+        end
+
+        def product_media(node)
+          image = node && node["image"]
+          return [] unless image
+
+          [Portage::Ucp::Media.new(type: "image", url: image["url"], alt_text: image["altText"],
+                                   width: image["width"], height: image["height"])]
+        end
+
+        # `barcode` is a single untyped Shopify string with no declared
+        # standard — inferred from length rather than asserted, since
+        # Shopify doesn't tag which GS1 standard (UPC-A/EAN-13/EAN-8) a
+        # given value follows. Anything else (an internal SKU-shaped
+        # barcode, a non-numeric value) is passed through as bare "GTIN"
+        # rather than dropped, so the field still reaches the agent.
+        BARCODE_TYPES = { 8 => "EAN", 12 => "UPC", 13 => "EAN" }.freeze
+
+        def barcodes(value)
+          return [] if value.nil? || value.empty?
+
+          [{ "type" => BARCODE_TYPES.fetch(value.length, "GTIN"), "value" => value }]
+        end
+
+        # `product_description` is the parent Product's own Description —
+        # Shopify's ProductVariant has no description field of its own, and
+        # types/variant.json requires one, so this reuses the product's, same
+        # posture as Wix's variant title falling back to its product's (see
+        # Portage::Ucp::Wix::Mapper#variant).
+        # `price`/`compareAtPrice` come back as the bare `Money` scalar (a
+        # decimal string, no currency of its own) rather than a MoneyV2
+        # object — confirmed against the live Admin API 2026-04 schema, which
+        # rejects `{ amount currencyCode }` sub-selections on them. `currency`
+        # is the product's own (from priceRange), which every variant shares.
+        def scalar_price(amount, currency)
+          Portage::Ucp::Price.new(amount: Portage::Ucp::Support::Amounts.decimal_to_minor(amount), currency: currency)
+        end
+
+        def variant(node, product_description, currency)
+          Portage::Ucp::Variant.new(
+            id: node["id"],
+            title: node["title"],
+            description: product_description,
+            price: scalar_price(node["price"], currency),
+            sku: node["sku"],
+            barcodes: barcodes(node["barcode"]),
+            list_price: node["compareAtPrice"] && scalar_price(node["compareAtPrice"], currency),
+            availability: { "available" => node["availableForSale"] },
+            options: selected_options(node["selectedOptions"]),
+            media: variant_media(node["image"]),
+            metadata: metafields_metadata(node["metafields"], :variant)
+          )
+        end
+
+        def selected_options(nodes)
+          (nodes || []).map { |o| Portage::Ucp::SelectedOption.new(name: o["name"], label: o["value"]) }
+        end
+
+        def variant_media(image)
+          return [] unless image
+
+          [Portage::Ucp::Media.new(type: "image", url: image["url"], alt_text: image["altText"],
+                                   width: image["width"], height: image["height"])]
         end
 
         def cart(node)
@@ -106,7 +239,7 @@ module Portage
         # modeled here), so every deliveryGroup collapses into a single
         # synthesized FulfillmentMethod rather than one per Shopify group.
         def checkout_fulfillment(node)
-          groups_nodes = node["deliveryGroups"] || []
+          groups_nodes = node.dig("deliveryGroups", "nodes") || []
           return Portage::Ucp::CheckoutFulfillment.new if groups_nodes.empty?
 
           groups = groups_nodes.map { |g| fulfillment_group(g) }
@@ -317,10 +450,16 @@ module Portage
         end
 
         # Builds the top-level totals array from Shopify's cost breakdown.
+        # `totalTaxAmount` is nullable on a real cart — Shopify doesn't
+        # compute tax until it has enough context (a shipping address, a
+        # tax-registered market), so a fresh cart genuinely has no tax
+        # amount yet rather than a zero one. Confirmed live against
+        # ucp-test-bc2vif1p.myshopify.com (design-log §17).
         def totals(node)
           cost = node["cost"]
+          tax = cost["totalTaxAmount"]
           Portage::Ucp::Support::Totals.summary(subtotal: minor_units(cost["subtotalAmount"]),
-                                                tax: minor_units(cost["totalTaxAmount"]),
+                                                tax: tax ? minor_units(tax) : 0,
                                                 total: minor_units(cost["totalAmount"]))
         end
       end

data/lib/portage/ucp/shopify/queries.rb

@@ -5,29 +5,83 @@ module Portage
       # and the response mapping (Mapper) can each be read and tested on their
       # own.
       module Queries
-        PRODUCT_FIELDS = <<~GRAPHQL.freeze
+        # `descriptionHtml` sourced alongside plain `description` — UCP's
+        # description.json accepts both, and Storefront sanitizes its own
+        # HTML output, satisfying the schema's "platforms MUST sanitize"
+        # note on the read side without this gem doing its own pass.
+        # `options`/`selectedOptions` and `sku`/`barcode` back the
+        # dev.ucp.shopping.catalog structured-attribute gap (design-log
+        # §20): GS1 identifiers and Size/Color axes as real fields instead
+        # of chaotic HTML the agent has to parse itself.
+        # `%<product_metafields>s`/`%<variant_metafields>s` carry whatever
+        # Portage::Ucp::Shopify.configuration.metadata_field entries a
+        # consumer has registered (design-log §20's metadata_field DSL).
+        # Kept as a template rather than the frozen constant the rest of this
+        # file uses: configured metafield identifiers aren't known until
+        # `Shopify.configure` runs, which happens after this file loads, so
+        # the fragment has to be built per call — see .product_fields below.
+        PRODUCT_FIELDS_TEMPLATE = <<~GRAPHQL.freeze
           id
+          handle
           title
           description
+          descriptionHtml
           onlineStoreUrl
-          availableForSale
-          priceRange { minVariantPrice { amount currencyCode } }
+          tags
+          priceRange { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } }
+          compareAtPriceRange {
+            minVariantCompareAtPrice { amount currencyCode }
+            maxVariantCompareAtPrice { amount currencyCode }
+          }
+          featuredMedia: media(first: 1) { nodes { ... on MediaImage { image { url altText width height } } } }
+          options(first: 10) { name optionValues { id name } }
+          %<product_metafields>s
           variants(first: 25) {
-            nodes { id title availableForSale price { amount currencyCode } }
+            nodes {
+              id title availableForSale sku barcode
+              price
+              compareAtPrice
+              selectedOptions { name value }
+              image { url altText width height }
+              %<variant_metafields>s
+            }
           }
         GRAPHQL
 
-        SEARCH_CATALOG = <<~GRAPHQL.freeze
-          query SearchCatalog($query: String!, $first: Int!) {
-            products(query: $query, first: $first) { nodes { #{PRODUCT_FIELDS} } }
-          }
-        GRAPHQL
+        # Product-level and variant-level metafields are separate GraphQL
+        # fields with separate cost on Shopify's Admin API (Product#metafields
+        # vs. ProductVariant#metafields) — `scope` picks which configured list
+        # to build the identifiers from. Empty when nothing's configured for
+        # that scope, so an unconfigured consumer's query is byte-identical to
+        # before this fragment existed.
+        def self.metafields_fragment(scope)
+          fields = Portage::Ucp::Shopify.configuration.fields_for(scope)
+          return "" if fields.empty?
 
-        GET_PRODUCT = <<~GRAPHQL.freeze
-          query GetProduct($id: ID!) {
-            product(id: $id) { #{PRODUCT_FIELDS} }
-          }
-        GRAPHQL
+          identifiers = fields.map { |f| %({namespace: "#{f[:namespace]}", key: "#{f[:metafield_key]}"}) }.join(", ")
+          "metafields(identifiers: [#{identifiers}]) { key namespace value type }"
+        end
+
+        def self.product_fields
+          format(PRODUCT_FIELDS_TEMPLATE, product_metafields: metafields_fragment(:product),
+                                          variant_metafields: metafields_fragment(:variant))
+        end
+
+        def self.search_catalog_query
+          <<~GRAPHQL
+            query SearchCatalog($query: String!, $first: Int!) {
+              products(query: $query, first: $first) { nodes { #{product_fields} } }
+            }
+          GRAPHQL
+        end
+
+        def self.product_by_id_query
+          <<~GRAPHQL
+            query GetProduct($id: ID!) {
+              product(id: $id) { #{product_fields} }
+            }
+          GRAPHQL
+        end
 
         CART_FIELDS = <<~GRAPHQL.freeze
           id
@@ -48,13 +102,15 @@ module Portage
               }
             }
           }
-          deliveryGroups {
-            id
-            cartLines(first: 100) { nodes { id } }
-            deliveryOptions { handle title description deliveryMethodType estimatedCost { amount currencyCode } }
-            selectedDeliveryOption { handle }
-            deliveryAddress { address1 address2 city provinceCode zip firstName lastName phone
-                              countryCode: countryCodeV2 }
+          deliveryGroups(first: 10) {
+            nodes {
+              id
+              cartLines(first: 100) { nodes { id } }
+              deliveryOptions { handle title description deliveryMethodType estimatedCost { amount currencyCode } }
+              selectedDeliveryOption { handle }
+              deliveryAddress { address1 address2 city provinceCode zip firstName lastName phone
+                                countryCode: countryCodeV2 }
+            }
           }
           discountCodes { code applicable }
           discountAllocations {

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

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

data/lib/portage/ucp/shopify.rb

@@ -1,5 +1,6 @@
 require "portage/ucp"
 require_relative "shopify/version"
+require_relative "shopify/configuration"
 require_relative "shopify/errors"
 require_relative "shopify/client"
 require_relative "shopify/access_token_fetcher"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-shopify
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Whitbread
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -109,6 +109,7 @@ files:
 - lib/portage/ucp/shopify/access_token_fetcher.rb
 - lib/portage/ucp/shopify/adapter.rb
 - lib/portage/ucp/shopify/client.rb
+- lib/portage/ucp/shopify/configuration.rb
 - lib/portage/ucp/shopify/errors.rb
 - lib/portage/ucp/shopify/mapper.rb
 - lib/portage/ucp/shopify/queries.rb
@@ -134,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Shopify adapter for portage-ucp — standard catalog/cart/checkout/order over
   MCP and UCP