portage-ucp-shopify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b3dc91f25f74865134c14455b389377ae19c8fbbf8499d6b2830bbedec4ec26
+  data.tar.gz: b682672e45cf4242bbbfb67c005e3d1f521f5b3eff17faede2b4a36fe19bd5f6
+SHA512:
+  metadata.gz: 5132d69c63d402f907f51ce56bcc97bc2d3ac41ded7554cba49de1b7d1cc333d17beeca7fdfd6c7e48e17458df3b998e8145afbd79bfebc9b8019761495770d0
+  data.tar.gz: 901cae55f88b03b6af29feb48c30656921f77c7f97a88366c05e5556b3d7a980062a9f6f52f6d71c6ddf6b90cdd6b7ad8a7c286e0472ffe8e8a9a0cf4a8b1be8

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
+pre-1.0, so APIs may still shift between minor versions.
+
+## [0.1.0] - Unreleased
+
+- Initial pre-release. Shopify adapter against the Admin (catalog, order) and
+  Storefront (cart, checkout) GraphQL APIs.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,131 @@
+# portage-ucp-shopify
+
+Shopify adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::Adapter` against Shopify's Admin (catalog, order) and Storefront (cart, checkout) GraphQL APIs. Generic only — no merchant-specific business logic. Plain `Net::HTTP`, no `shopify_api` runtime dependency.
+
+## What it covers
+
+| UCP capability | Backing Shopify API | Notes |
+|---|---|---|
+| `dev.ucp.shopping.catalog` | Admin | `search_catalog`, `get_product` |
+| `dev.ucp.shopping.cart` | Storefront (Cart) | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
+| `dev.ucp.shopping.checkout` | Storefront (same Cart object) | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
+| `dev.ucp.shopping.order` | Admin | `get_order` |
+| `dev.ucp.shopping.identity` | — | not implemented; Shopify's OAuth identity story lives in the separate Customer Account API, out of scope here |
+
+Shopify has no separate "Checkout" object — Storefront's `Cart` **is** the checkout. The adapter tracks checkout status (`incomplete` / `completed` / `canceled` / `complete_in_progress`) itself, keyed by cart id, and resolves `Order#checkout_id` after completion via a `cart_token:` order search.
+
+Update/replace operations (`update_cart`, `update_checkout`) are full-replacement: Storefront has no atomic "replace all lines" mutation, so the adapter removes every current line then re-adds the desired ones. Mutating methods dedup by `idempotency_key` in-process so a dropped-connection retry can't double-charge.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-shopify"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+You need a shop domain plus an Admin API access token (for catalog/order) and a Storefront API access token (for cart/checkout). Either capability can be used alone if you only pass the token it needs.
+
+```ruby
+require "portage/ucp/shopify"
+
+client = Portage::Ucp::Shopify::Client.new(
+  shop_domain: "your-shop.myshopify.com",
+  admin_access_token: ENV.fetch("SHOPIFY_ADMIN_ACCESS_TOKEN"),
+  storefront_access_token: ENV.fetch("SHOPIFY_STOREFRONT_ACCESS_TOKEN")
+)
+
+adapter = Portage::Ucp::Shopify::Adapter.new(client: client)
+```
+
+### Fetching an Admin token from a custom app's client credentials
+
+Shopify custom apps no longer expose a static, copy-once admin token — only a `client_id`/`client_secret`. Exchange those for a real access token via OAuth's `client_credentials` grant:
+
+```ruby
+fetcher = Portage::Ucp::Shopify::AccessTokenFetcher.new(
+  shop_domain: "your-shop.myshopify.com",
+  client_id: ENV.fetch("SHOPIFY_CLIENT_ID"),
+  client_secret: ENV.fetch("SHOPIFY_CLIENT_SECRET")
+)
+
+result = fetcher.fetch
+result.access_token # => admin_access_token to pass into Client.new
+result.expires_in    # => seconds until it needs refetching
+```
+
+## Usage
+
+```ruby
+# Catalog
+products = adapter.search_catalog(query: "hoodie", limit: 10)
+product  = adapter.get_product(product_id: products.first.id)
+
+# Cart
+cart = adapter.create_cart(
+  line_items: [{ product_id: product.variants.first[:id], quantity: 2 }],
+  idempotency_key: SecureRandom.uuid
+)
+cart = adapter.update_cart(cart_id: cart.id, line_items: [], idempotency_key: SecureRandom.uuid) # empties cart
+
+# Checkout
+checkout = adapter.create_checkout(
+  line_items: [{ product_id: product.variants.first[:id], quantity: 1 }],
+  idempotency_key: SecureRandom.uuid
+)
+checkout = adapter.complete_checkout(
+  checkout_id: checkout.id,
+  payment_token: single_use_token_from_payment_handler,
+  idempotency_key: SecureRandom.uuid
+)
+
+# Order
+order = adapter.get_order(order_id: checkout.id) # only once linked post-completion
+```
+
+`payment_token` must already be a single-use tokenized credential from a UCP payment handler (validated as non-PAN by `Portage::Ucp::PaymentTokenGuard` upstream) — it's passed straight into Storefront's `cartPaymentUpdate`.
+
+## Wiring into portage-ucp
+
+Drop the adapter into a `Dispatcher` (or the MCP server) the same as any other backend:
+
+```ruby
+dispatcher = Portage::Ucp::Dispatcher.new(adapter: adapter)
+
+dispatcher.call(
+  capability: "dev.ucp.shopping.cart",
+  action: "create",
+  arguments: { line_items: [{ product_id: variant_id, quantity: 1 }], idempotency_key: SecureRandom.uuid }
+)
+```
+
+Because `link_identity` is left unoverridden, `Capability#advertised_for?` simply won't advertise `dev.ucp.shopping.identity` for this adapter — callers get an absent capability, not a 500.
+
+## Errors
+
+```ruby
+Portage::Ucp::Shopify::Error        # base class
+Portage::Ucp::Shopify::GraphqlError # top-level GraphQL `errors` (bad query, throttled, auth rejected)
+Portage::Ucp::Shopify::UserError    # a mutation's non-empty `userErrors` (e.g. "line item not found")
+```
+
+## Development
+
+```bash
+bundle exec rspec   # tests (WebMock-stubbed, no live store needed)
+bundle exec rubocop  # lint
+
+# fetch a real admin_access_token for a dev store, via client_credentials
+SHOPIFY_SHOP_DOMAIN=your-shop.myshopify.com \
+SHOPIFY_CLIENT_ID=... SHOPIFY_CLIENT_SECRET=... \
+  bundle exec rake shopify_access_token
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-shopify

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone MCP server over stdio. Configure the shop connection via env vars,
+# and — since this gem ships with permissive-nothing defaults (see README's
+# "Security hooks") — wire a real Authenticator/RateLimiter/etc. via a config
+# file loaded with PORTAGE_UCP_CONFIG, the same way `rackup -r` or Sidekiq's
+# `-r` work — see ../examples/portage_ucp.rb for a starting point. Without
+# one, the server still starts but rejects every mutating call.
+
+require "portage/ucp"
+require "portage/ucp/shopify"
+
+require ENV["PORTAGE_UCP_CONFIG"] if ENV["PORTAGE_UCP_CONFIG"]
+
+client = Portage::Ucp::Shopify::Client.new(
+  shop_domain: ENV.fetch("SHOPIFY_SHOP_DOMAIN"),
+  admin_access_token: ENV.fetch("SHOPIFY_ADMIN_ACCESS_TOKEN", nil),
+  storefront_access_token: ENV.fetch("SHOPIFY_STOREFRONT_ACCESS_TOKEN", nil)
+)
+adapter = Portage::Ucp::Shopify::Adapter.new(client: client)
+
+Portage::Ucp::Mcp::Server.build(adapter: adapter).start

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

@@ -0,0 +1,36 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Shopify
+      # Exchanges a custom app's client_id/client_secret for an Admin API
+      # access token via Shopify's OAuth client_credentials grant.
+      #
+      # Shopify moved custom apps off static, copy-once tokens shown in the
+      # admin UI: creating a custom app now only exposes a client_id and
+      # client_secret, and the actual admin_access_token used by
+      # Portage::Ucp::Shopify::Client must be fetched (and re-fetched once
+      # expired) from POST /admin/oauth/access_token.
+      class AccessTokenFetcher
+        include Portage::Ucp::Support::TokenExchange
+
+        Result = Struct.new(:access_token, :expires_in, keyword_init: true)
+
+        def initialize(shop_domain:, client_id:, client_secret:)
+          @shop_domain = shop_domain
+          @client_id = client_id
+          @client_secret = client_secret
+        end
+
+        def fetch
+          body = exchange("https://#{@shop_domain}/admin/oauth/access_token",
+                          { grant_type: "client_credentials", client_id: @client_id,
+                            client_secret: @client_secret },
+                          error_class: Portage::Ucp::Shopify::Error, form: true)
+          Result.new(access_token: body["access_token"], expires_in: body["expires_in"])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,225 @@
+require "bigdecimal"
+
+module Portage
+  module Ucp
+    module Shopify
+      # Generic Portage::Ucp::Adapter over standard Shopify catalog/cart/checkout/
+      # order primitives (roadmap step 4) — no merchant-specific business
+      # logic. A merchant with bespoke checkout semantics (subscriptions,
+      # bundles, whatever) writes their own Adapter on top of the same
+      # contract, same as anyone on any other backend would (§7.1).
+      #
+      # Deliberately doesn't override `link_identity`: Shopify's OAuth identity
+      # story lives in the separate Customer Account API, out of scope for
+      # this generic adapter (see roadmap step 4's explicit "catalog/cart/
+      # checkout/order only"). Leaving it un-overridden means Capability#
+      # advertised_for? simply doesn't advertise dev.ucp.shopping.identity for
+      # this adapter — not a 500, just an absent capability.
+      #
+      # Catalog and Order are read through the Admin API (Storefront can't
+      # look up an arbitrary order without a customer session). Cart and
+      # Checkout are read/written through the Storefront API's Cart object —
+      # Admin has no "Cart"; a headless checkout is a Storefront Cart plus its
+      # `checkoutUrl` payment/completion mutations, not a separate Checkout
+      # object. UCP's create_checkout/update_checkout/complete_checkout are
+      # threaded onto that one underlying Cart id.
+      class Adapter < Portage::Ucp::Adapter
+        # Neither Storefront cart mutations nor cartPaymentUpdate take an
+        # idempotency key natively — cartSubmitForCompletion's attemptId is
+        # the one exception, see #submit_payment — so §9a dedup comes from
+        # Support::Idempotency's in-process table.
+        include Portage::Ucp::Support::Idempotency
+        # Shopify's Cart has no native "checkout status" field (Checkout is
+        # modeled as the same underlying Cart), and its Order has no field
+        # back to the cart that produced it — both are tracked adapter-side
+        # via Support::CheckoutState.
+        include Portage::Ucp::Support::CheckoutState
+
+        def initialize(client:)
+          super()
+          @client = client
+        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) }
+        end
+
+        def get_product(product_id:)
+          data = @client.admin_query(Queries::GET_PRODUCT, variables: { id: product_id })
+          node = data["product"]
+          node && Mapper.product(node)
+        end
+
+        def get_cart(cart_id:)
+          cart_node = fetch_cart_node(cart_id)
+          cart_node && Mapper.cart(cart_node)
+        end
+
+        def create_cart(line_items:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(create_cart_node(line_items)) }
+        end
+
+        # Full replacement, matching UCP's real cart semantics: Storefront has
+        # no atomic "replace all lines" mutation, so this removes every current
+        # line then adds the desired ones back (two Storefront calls).
+        def update_cart(cart_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(replace_lines(cart_id, line_items)) }
+        end
+
+        # Shopify has no cart-cancellation mutation — carts simply expire.
+        # Returns the cart unchanged; there's nothing more accurate to do here
+        # against the real API.
+        def cancel_cart(cart_id:, idempotency_key:)
+          dedup(idempotency_key) { get_cart(cart_id: cart_id) }
+        end
+
+        def create_checkout(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            cart_node = create_cart_node(line_items)
+            record_checkout_status(cart_node["id"], "incomplete")
+            Mapper.checkout(cart_node, status: "incomplete")
+          end
+        end
+
+        def get_checkout(checkout_id:)
+          cart_node = fetch_cart_node(checkout_id)
+          cart_node && Mapper.checkout(cart_node, status: checkout_status(checkout_id))
+        end
+
+        # Full replacement, same rationale as #update_cart — Shopify checkout
+        # *is* the cart object.
+        def update_checkout(checkout_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            cart_node = replace_lines(checkout_id, line_items)
+            record_checkout_status(checkout_id, "incomplete")
+            Mapper.checkout(cart_node, status: "incomplete")
+          end
+        end
+
+        # `payment_token` is the single-use tokenized credential from a UCP
+        # payment handler (already validated as non-PAN by PaymentTokenGuard
+        # before this is ever called, per §9). It's threaded straight into
+        # Storefront's `cartPaymentUpdate` as a vaulted single-use token — the
+        # exact `paymentMethod` sub-shape is payment-handler-specific per
+        # Shopify's docs and needs confirming against a real dev store
+        # (roadmap step 5); this passes the token through rather than guessing
+        # a shape that only a live handler negotiation can pin down.
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key:)
+          dedup(idempotency_key) { submit_payment(checkout_id, payment_token, idempotency_key) }
+        end
+
+        def cancel_checkout(checkout_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            record_checkout_status(checkout_id, "canceled")
+            cart_node = fetch_cart_node(checkout_id)
+            Mapper.checkout(cart_node, status: "canceled")
+          end
+        end
+
+        def get_order(order_id:)
+          data = @client.admin_query(Queries::GET_ORDER, variables: { id: order_id })
+          node = data["order"]
+          node && Mapper.order(node, checkout_id: checkout_id_for(order_id))
+        end
+
+        private
+
+        def fetch_cart_node(cart_id)
+          @client.storefront_query(Queries::GET_CART, variables: { id: cart_id })["cart"]
+        end
+
+        def cart_lines(line_items)
+          line_items.map { |li| { merchandiseId: li[:product_id], quantity: li[:quantity] } }
+        end
+
+        def create_cart_node(line_items)
+          data = @client.storefront_query(Queries::CART_CREATE, variables: { input: { lines: cart_lines(line_items) } })
+          unwrap!(data, "cartCreate")
+        end
+
+        def replace_lines(cart_id, line_items)
+          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
+          return fetch_cart_node(cart_id) if line_items.empty?
+
+          added = @client.storefront_query(Queries::CART_LINES_ADD,
+                                           variables: { cartId: cart_id, lines: cart_lines(line_items) })
+          unwrap!(added, "cartLinesAdd")
+        end
+
+        # Reuses idempotency_key as cartSubmitForCompletion's own attemptId too
+        # — 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
+
+          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)
+        end
+
+        def pay_for_cart(checkout_id, total, payment_token)
+          payment_data = @client.storefront_query(
+            Queries::CART_PAYMENT_UPDATE,
+            variables: { cartId: checkout_id,
+                         payment: { totalAmount: total,
+                                    singleUseTokenPayment: { paymentAmount: total, singleUseToken: payment_token } } }
+          )
+          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.
+        def link_cart_to_order(checkout_id)
+          token = checkout_id[%r{Cart/([^?]+)}, 1]
+          return unless token
+
+          data = @client.admin_query(Queries::ORDER_BY_CART_TOKEN, variables: { query: "cart_token:#{token}" })
+          order_node = data.dig("orders", "nodes", 0)
+          return unless order_node
+
+          record_order_checkout(order_node["id"], checkout_id)
+          Portage::Ucp::OrderConfirmation.new(id: order_node["id"], permalink_url: order_node["statusPageUrl"])
+        end
+
+        def unwrap!(data, field)
+          payload = data.fetch(field)
+          errors = payload["userErrors"]
+          raise Portage::Ucp::Shopify::UserError.new(field, errors) if errors && !errors.empty?
+
+          payload.fetch("cart")
+        end
+
+        def unwrap_submit!(data)
+          payload = data.fetch("cartSubmitForCompletion")
+          errors = payload["userErrors"]
+          raise Portage::Ucp::Shopify::UserError.new("cartSubmitForCompletion", errors) if errors && !errors.empty?
+
+          result = payload["result"]
+          raise Portage::Ucp::Shopify::Error, result.dig("errors", 0, "message") if result["errors"]
+
+          result.key?("pollAfter") ? "complete_in_progress" : "completed"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Shopify
+      # Minimal GraphQL client over Shopify's Admin and Storefront APIs.
+      #
+      # Deliberately plain Net::HTTP, not the `shopify_api` gem: `shopify_api`
+      # requires a global `ShopifyAPI::Context.setup` and session object, which
+      # forces every consumer onto its config/session model just to make two
+      # GraphQL calls. A generic adapter that any Ruby app can drop in (§4 of
+      # the plan) is better served by a client that only needs a shop domain
+      # and the two tokens a merchant already has — no framework coupling, and
+      # trivially stubbable with WebMock in specs.
+      #
+      # Admin and Storefront are separate Shopify APIs with separate tokens and
+      # separate capabilities (Admin has no "Cart"; Storefront can't look up an
+      # arbitrary order). The adapter picks whichever API actually has the
+      # data it needs (see Portage::Ucp::Shopify::Adapter).
+      class Client
+        DEFAULT_API_VERSION = "2026-04".freeze
+
+        def initialize(shop_domain:, admin_access_token: nil, storefront_access_token: nil,
+                       api_version: DEFAULT_API_VERSION)
+          @shop_domain = shop_domain
+          @admin_access_token = admin_access_token
+          @storefront_access_token = storefront_access_token
+          @api_version = api_version
+        end
+
+        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)
+        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)
+        end
+
+        private
+
+        def require_token!(token, name)
+          raise ArgumentError, "Portage::Ucp::Shopify::Client requires #{name} for this call" unless token
+        end
+
+        def post(path, headers:, query:, variables:)
+          uri = URI("https://#{@shop_domain}#{path}")
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          headers.each { |key, value| request[key] = value }
+          request.body = JSON.generate({ query: query, variables: variables })
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+          body = JSON.parse(response.body)
+          raise Portage::Ucp::Shopify::GraphqlError, body["errors"] if body["errors"]
+
+          body["data"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module Portage
+  module Ucp
+    module Shopify
+      class Error < StandardError; end
+
+      # Raised when a GraphQL response carries top-level `errors` (malformed
+      # query, throttled, auth rejected) — distinct from a mutation's
+      # `userErrors`, which is a well-formed response describing a business
+      # rejection (e.g. "line item not found").
+      class GraphqlError < Error
+        def initialize(errors)
+          super(errors.map { |e| e["message"] }.join("; "))
+        end
+      end
+
+      # Raised when a mutation's `userErrors` array is non-empty.
+      class UserError < Error
+        def initialize(field, errors)
+          super("#{field} userErrors: #{errors.map { |e| e['message'] }.join('; ')}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+module Portage
+  module Ucp
+    module Shopify
+      # Converts Shopify GraphQL response nodes into the protocol-layer value
+      # objects from Portage::Ucp::ValueObjects (Product/Cart/LineItem/Checkout/Order/
+      # Money) — nothing Shopify-shaped is allowed to leak past this file.
+      #
+      # UCP's LineItem#item.id is Shopify's variant GID, not the parent
+      # product's GID: Shopify carts hold variants (a specific size/color), and
+      # a product with one variant just uses that variant's id.
+      module Mapper
+        module_function
+
+        # Both take a Shopify MoneyV2 node ({amount:, currencyCode:}) rather
+        # than a bare amount — the arithmetic itself is Support::Amounts'.
+        def money(price)
+          Portage::Ucp::Support::Amounts.money(price["amount"], price["currencyCode"])
+        end
+
+        def minor_units(price)
+          Portage::Ucp::Support::Amounts.decimal_to_minor(price["amount"])
+        end
+
+        def product(node)
+          Portage::Ucp::Product.new(
+            id: node["id"],
+            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"]
+          )
+        end
+
+        def variant(node)
+          { id: node["id"], title: node["title"], available: node["availableForSale"], price: money(node["price"]) }
+        end
+
+        def cart(node)
+          Portage::Ucp::Cart.new(
+            id: node["id"],
+            line_items: node.dig("lines", "nodes").map { |n| cart_line_item(n) },
+            currency: node.dig("cost", "subtotalAmount", "currencyCode"),
+            totals: totals(node)
+          )
+        end
+
+        def cart_line_item(node)
+          merchandise = node["merchandise"]
+          line_total = minor_units(node.dig("cost", "totalAmount"))
+          Portage::Ucp::LineItem.new(
+            id: node["id"],
+            item: Portage::Ucp::Item.new(id: merchandise["id"], title: merchandise.dig("product", "title"),
+                                         price: minor_units(merchandise["price"])),
+            quantity: node["quantity"],
+            totals: Portage::Ucp::Support::Totals.line(line_total)
+          )
+        end
+
+        # `status` isn't a Shopify Cart field — Cart/Checkout is one object in
+        # Shopify's model, so the adapter tracks status itself across the
+        # create/update/complete/cancel lifecycle and passes it in here.
+        def checkout(node, status:, order: nil)
+          Portage::Ucp::Checkout.new(
+            id: node["id"],
+            status: status,
+            line_items: node.dig("lines", "nodes").map { |n| cart_line_item(n) },
+            currency: node.dig("cost", "subtotalAmount", "currencyCode"),
+            totals: totals(node),
+            links: [],
+            order: order
+          )
+        end
+
+        # `checkout_id` isn't a Shopify Order field — nothing on Order links
+        # back to its originating cart, so the adapter resolves it itself (via
+        # a cart_token order search at completion time, see
+        # Portage::Ucp::Shopify::Adapter#link_cart_to_order) and passes it in here,
+        # the same way #checkout's `status:` is caller-supplied.
+        def order(node, checkout_id: "")
+          subtotal_amount = minor_units(node.dig("currentSubtotalPriceSet", "shopMoney"))
+          total_amount = minor_units(node.dig("currentTotalPriceSet", "shopMoney"))
+          Portage::Ucp::Order.new(
+            id: node["id"],
+            checkout_id: checkout_id,
+            permalink_url: node["statusPageUrl"],
+            line_items: node.dig("lineItems", "nodes").map { |n| order_line_item(n) },
+            fulfillment: fulfillment(node),
+            currency: node.dig("currentTotalPriceSet", "shopMoney", "currencyCode"),
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal_amount, total: total_amount)
+          )
+        end
+
+        def order_line_item(node)
+          variant_node = node["variant"]
+          line_total = minor_units(node.dig("discountedTotalSet", "shopMoney"))
+          total = node["currentQuantity"]
+          fulfilled = total - node["unfulfilledQuantity"]
+          Portage::Ucp::OrderLineItem.new(
+            id: node["id"],
+            item: Portage::Ucp::Item.new(id: variant_node && variant_node["id"],
+                                         title: variant_node && variant_node["title"],
+                                         price: variant_node && minor_units(variant_node["price"])),
+            quantity: { original: node["quantity"], total: total, fulfilled: fulfilled },
+            totals: Portage::Ucp::Support::Totals.line(line_total),
+            status: Portage::Ucp::Support::LineItemStatus.derive(total: total, fulfilled: fulfilled)
+          )
+        end
+
+        # DeliveryMethodType (Shopify) -> method_type enum (UCP). Unmapped
+        # values (new enum members Shopify adds later) fall back to "shipping"
+        # rather than raising, so a schema-valid guess beats a hard failure.
+        DELIVERY_METHOD_TYPES = {
+          "SHIPPING" => "shipping", "LOCAL" => "shipping", "PICKUP_POINT" => "shipping",
+          "PICK_UP" => "pickup", "RETAIL" => "pickup",
+          "NONE" => "digital"
+        }.freeze
+
+        # FulfillmentDisplayStatus (Shopify) -> fulfillment_event `type` (UCP).
+        # Unmapped values fall back to "processing", same rationale as above.
+        FULFILLMENT_EVENT_TYPES = {
+          "ATTEMPTED_DELIVERY" => "failed_attempt", "CANCELED" => "canceled", "CONFIRMED" => "processing",
+          "DELAYED" => "in_transit", "DELIVERED" => "delivered", "FAILURE" => "failed_attempt",
+          "FULFILLED" => "shipped", "CARRIER_PICKED_UP" => "shipped", "IN_TRANSIT" => "in_transit",
+          "LABEL_PRINTED" => "processing", "LABEL_PURCHASED" => "processing", "LABEL_VOIDED" => "canceled",
+          "MARKED_AS_FULFILLED" => "shipped", "NOT_DELIVERED" => "undeliverable", "OUT_FOR_DELIVERY" => "in_transit",
+          "READY_FOR_PICKUP" => "processing", "PICKED_UP" => "delivered", "SUBMITTED" => "processing"
+        }.freeze
+
+        # Builds the buyer-facing Fulfillment (schemas/shopping/order.json's
+        # `expectations`/`events`) from Shopify's fulfillmentOrders (what's
+        # expected to ship, and to where) and fulfillments (what actually
+        # shipped, with tracking).
+        def fulfillment(node)
+          Portage::Ucp::Fulfillment.new(
+            expectations: (node.dig("fulfillmentOrders", "nodes") || []).map { |n| expectation(n) },
+            events: (node["fulfillments"] || []).map { |n| fulfillment_event(n) }
+          )
+        end
+
+        def expectation(node)
+          Portage::Ucp::Expectation.new(
+            id: node["id"],
+            line_items: (node.dig("lineItems", "nodes") || []).map { |n| order_line_ref(n, n["totalQuantity"]) },
+            method_type: DELIVERY_METHOD_TYPES.fetch(node.dig("deliveryMethod", "methodType"), "shipping"),
+            destination: postal_address(node["destination"]),
+            fulfillable_on: node["fulfillAt"]
+          )
+        end
+
+        def postal_address(node)
+          return {} unless node
+
+          {
+            "street_address" => node["address1"], "extended_address" => node["address2"],
+            "address_locality" => node["city"], "address_region" => node["province"],
+            "address_country" => node["countryCode"], "postal_code" => node["zip"],
+            "first_name" => node["firstName"], "last_name" => node["lastName"], "phone_number" => node["phone"]
+          }.compact
+        end
+
+        def fulfillment_event(node)
+          tracking = node.dig("trackingInfo", 0) || {}
+          line_items = (node.dig("fulfillmentLineItems", "nodes") || [])
+                       .map { |n| order_line_ref(n, n["quantity"]) }
+                       .select { |n| n["quantity"]&.positive? }
+          Portage::Ucp::FulfillmentEvent.new(
+            id: node["id"], occurred_at: node["createdAt"],
+            type: FULFILLMENT_EVENT_TYPES.fetch(node["displayStatus"], "processing"),
+            line_items: line_items,
+            tracking_number: tracking["number"], tracking_url: tracking["url"], carrier: tracking["company"]
+          )
+        end
+
+        def order_line_ref(node, quantity)
+          { "id" => node.dig("lineItem", "id"), "quantity" => quantity }
+        end
+
+        # Builds the top-level totals array from Shopify's cost breakdown.
+        def totals(node)
+          cost = node["cost"]
+          Portage::Ucp::Support::Totals.summary(subtotal: minor_units(cost["subtotalAmount"]),
+                                                tax: minor_units(cost["totalTaxAmount"]),
+                                                total: minor_units(cost["totalAmount"]))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+module Portage
+  module Ucp
+    module Shopify
+      # Raw GraphQL documents, kept separate from Adapter so the request shape
+      # and the response mapping (Mapper) can each be read and tested on their
+      # own.
+      module Queries
+        PRODUCT_FIELDS = <<~GRAPHQL.freeze
+          id
+          title
+          description
+          onlineStoreUrl
+          availableForSale
+          priceRange { minVariantPrice { amount currencyCode } }
+          variants(first: 25) {
+            nodes { id title availableForSale price { amount currencyCode } }
+          }
+        GRAPHQL
+
+        SEARCH_CATALOG = <<~GRAPHQL.freeze
+          query SearchCatalog($query: String!, $first: Int!) {
+            products(query: $query, first: $first) { nodes { #{PRODUCT_FIELDS} } }
+          }
+        GRAPHQL
+
+        GET_PRODUCT = <<~GRAPHQL.freeze
+          query GetProduct($id: ID!) {
+            product(id: $id) { #{PRODUCT_FIELDS} }
+          }
+        GRAPHQL
+
+        CART_FIELDS = <<~GRAPHQL.freeze
+          id
+          checkoutUrl
+          cost { subtotalAmount { amount currencyCode } totalTaxAmount { amount currencyCode }
+                 totalAmount { amount currencyCode } }
+          lines(first: 100) {
+            nodes {
+              id quantity
+              cost { totalAmount { amount currencyCode } }
+              merchandise { ... on ProductVariant { id product { id title } price { amount currencyCode } } }
+            }
+          }
+        GRAPHQL
+
+        GET_CART = <<~GRAPHQL.freeze
+          query GetCart($id: ID!) {
+            cart(id: $id) { #{CART_FIELDS} }
+          }
+        GRAPHQL
+
+        CART_CREATE = <<~GRAPHQL.freeze
+          mutation CartCreate($input: CartInput!) {
+            cartCreate(input: $input) { cart { #{CART_FIELDS} } userErrors { field message } }
+          }
+        GRAPHQL
+
+        CART_LINES_ADD = <<~GRAPHQL.freeze
+          mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+            cartLinesAdd(cartId: $cartId, lines: $lines) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        CART_LINES_REMOVE = <<~GRAPHQL.freeze
+          mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+            cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        CART_BUYER_IDENTITY_UPDATE = <<~GRAPHQL.freeze
+          mutation CartBuyerIdentityUpdate($cartId: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
+            cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        CART_PAYMENT_UPDATE = <<~GRAPHQL.freeze
+          mutation CartPaymentUpdate($cartId: ID!, $payment: CartPaymentInput!) {
+            cartPaymentUpdate(cartId: $cartId, payment: $payment) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        CART_SUBMIT_FOR_COMPLETION = <<~GRAPHQL.freeze
+          mutation CartSubmitForCompletion($cartId: ID!, $attemptToken: String!) {
+            cartSubmitForCompletion(cartId: $cartId, attemptId: $attemptToken) {
+              result {
+                ... on SubmitSuccess { attemptId }
+                ... on SubmitAlreadyAccepted { attemptId }
+                ... on SubmitFailed { checkoutUrl errors { message } }
+                ... on SubmitThrottled { pollAfter }
+              }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        GET_ORDER = <<~GRAPHQL.freeze
+          query GetOrder($id: ID!) {
+            order(id: $id) {
+              id
+              statusPageUrl
+              currentTotalPriceSet { shopMoney { amount currencyCode } }
+              currentSubtotalPriceSet { shopMoney { amount currencyCode } }
+              lineItems(first: 100) {
+                nodes {
+                  id quantity currentQuantity unfulfilledQuantity
+                  discountedTotalSet { shopMoney { amount currencyCode } }
+                  variant { id title price { amount currencyCode } }
+                }
+              }
+              fulfillmentOrders(first: 25) {
+                nodes {
+                  id
+                  fulfillAt
+                  deliveryMethod { methodType }
+                  destination { address1 address2 city province zip countryCode firstName lastName phone }
+                  lineItems(first: 100) {
+                    nodes { totalQuantity lineItem { id } }
+                  }
+                }
+              }
+              fulfillments(first: 25) {
+                id
+                displayStatus
+                createdAt
+                trackingInfo(first: 5) { company number url }
+                fulfillmentLineItems(first: 100) {
+                  nodes { quantity lineItem { id } }
+                }
+              }
+            }
+          }
+        GRAPHQL
+
+        # Storefront's cartSubmitForCompletion never returns the resulting
+        # order's id (its SubmitSuccess payload only carries attemptId) — the
+        # Admin API's `orders(query:)` search supports a documented
+        # `cart_token:` filter ("the token references the cart that's
+        # associated with an order"), which is the only way to reconcile a
+        # completed cart back to the Order it produced.
+        ORDER_BY_CART_TOKEN = <<~GRAPHQL.freeze
+          query OrderByCartToken($query: String!) {
+            orders(first: 1, query: $query) { nodes { id statusPageUrl } }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

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

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

data/lib/portage/ucp/shopify.rb

@@ -0,0 +1,8 @@
+require "portage/ucp"
+require_relative "shopify/version"
+require_relative "shopify/errors"
+require_relative "shopify/client"
+require_relative "shopify/access_token_fetcher"
+require_relative "shopify/queries"
+require_relative "shopify/mapper"
+require_relative "shopify/adapter"

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: portage-ucp-shopify
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Whitbread
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: portage-ucp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Implements Portage::Ucp::Adapter against Shopify's Admin (catalog, order)
+  and Storefront (cart, checkout) GraphQL APIs. Generic only — no merchant-specific
+  business logic. Plain Net::HTTP, no shopify_api runtime dependency.
+email:
+executables:
+- portage-ucp-shopify
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/portage-ucp-shopify
+- lib/portage/ucp/shopify.rb
+- lib/portage/ucp/shopify/access_token_fetcher.rb
+- lib/portage/ucp/shopify/adapter.rb
+- lib/portage/ucp/shopify/client.rb
+- lib/portage/ucp/shopify/errors.rb
+- lib/portage/ucp/shopify/mapper.rb
+- lib/portage/ucp/shopify/queries.rb
+- lib/portage/ucp/shopify/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-shopify
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-shopify
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-shopify/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Shopify adapter for portage-ucp — standard catalog/cart/checkout/order over
+  MCP and UCP
+test_files: []