portage-ucp-magento 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85fd968524956be2175b09568a42d4ebd9613f2004c9dd3e4497b36c14f60eb9
+  data.tar.gz: f97c08659973cc75e6569cce14166af3e665dc41427442acd8c5fdb08bd42d0c
+SHA512:
+  metadata.gz: 6ace0250eb9bb47f8efe87fa9e8195ce043c3ff6ec58c7da409070572d8e61358dd54b7916e21f35fcec3873fd45ad1c59e0b5c5b2a35b822631763e856f4a5b
+  data.tar.gz: a028622437eaf233e7e786419151c9421ed68885c8dab4b569252ce5c5ca66a6352fff7aeea7a3f4add23d453e3246272ea22be72eeb6e340a0e7c954d1246f5

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. Magento/Adobe Commerce adapter against the REST v1 API
+  (admin-token catalog/order, anonymous guest-cart cart/checkout).

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,145 @@
+# portage-ucp-magento
+
+Magento/Adobe Commerce adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::Adapter` against a Magento site's REST v1 API. Generic only — no merchant-specific business logic. Plain `Net::HTTP`, no Magento PHP SDK dependency.
+
+## What it covers
+
+| UCP capability | Backing Magento API | Notes |
+|---|---|---|
+| `dev.ucp.shopping.catalog` | Admin-token REST v1 | `search_catalog`, `get_product` |
+| `dev.ucp.shopping.cart` | Anonymous guest-cart REST v1 | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
+| `dev.ucp.shopping.checkout` | Same guest-cart, plus `shipping-information`/`payment-information` | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
+| `dev.ucp.shopping.order` | Admin-token REST v1 | `get_order` |
+| `dev.ucp.shopping.identity` | — | not implemented; Magento customer account login is a separate concern from the admin token + anonymous guest-cart flow used here |
+
+Like Shopify, a Magento guest cart *is* the checkout — there's no separate Checkout resource, just the same cart plus two extra calls at completion time. Cart/checkout ids are Magento's masked guest-cart id, not a numeric id. Line items are keyed by **sku**, not product id — that's what Magento's `cartItem` payloads take, so `product_id` in every `line_items:` argument means sku here.
+
+Update/replace operations (`update_cart`, `update_checkout`) are full-replacement: the guest-cart items API has no atomic "replace all lines" either, 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.
+
+Like Shopify/Wix, there's an `AccessTokenFetcher` — but it's a plain username/password exchange (`/rest/V1/integration/admin/token`), not a client_credentials grant, and Magento doesn't report an expiry, so plan to refresh on a 401 rather than a known lifetime.
+
+## ⚠️ Unverified against a live site, and one real gap
+
+Built from Magento's documented REST shapes, not run against a real site yet.
+
+- **`#complete_checkout` needs an address UCP doesn't carry.** Magento's real guest-checkout flow requires a billing/shipping address before `payment-information` will create an order, but `complete_checkout(checkout_id:, payment_token:, idempotency_key:)` has no address parameter at all. This adapter works around that with a single `default_address:` configured once at initialization — every order ships and bills to the same address. That's fine for a single-fulfillment-address integration (e.g. all-digital goods, or a business account with one known destination) and wrong for anything where the address varies per order. A real UCP address extension, if one lands, would replace this.
+- **`payment_data` shape is gateway-specific** (configured via `payment_method:`/`payment_data_key:`) and hasn't been confirmed against a live site with a real payment gateway installed — same posture as the other adapters' payment steps.
+- **Order fulfillment** — Magento core has no per-line-item fulfillment tracking on the Order resource (that's the separate Shipments API), so every order line gets the same coarse status derived from the order's own top-level `status`.
+- **`Order#permalink_url`** — left blank; Magento's Orders API doesn't return a public order-status page URL.
+- **Configurable product variant titles** — built from each child's own `name`, not verified against how a real store names its configurable children.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-magento"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+You need a base URL, an admin bearer token (catalog/order), your store's currency (the product resource doesn't return one), and — only if you'll call `complete_checkout` — a payment method id and a default address.
+
+```ruby
+require "portage/ucp/magento"
+
+client = Portage::Ucp::Magento::Client.new(
+  base_url: "https://your-shop.example.com",
+  admin_token: ENV.fetch("MAGENTO_ADMIN_TOKEN")
+)
+
+adapter = Portage::Ucp::Magento::Adapter.new(
+  client: client,
+  currency: "USD",
+  site_url: "https://your-shop.example.com",
+  payment_method: "checkmo", # only required for #complete_checkout
+  default_address: { firstname: "Store", lastname: "Fulfillment", street: ["1 Main St"], city: "Boston",
+                     region: "MA", postcode: "02110", country_id: "US", telephone: "555-0100",
+                     email: "orders@your-shop.example.com" }
+)
+```
+
+### Fetching an admin token from username/password
+
+```ruby
+fetcher = Portage::Ucp::Magento::AccessTokenFetcher.new(
+  base_url: "https://your-shop.example.com",
+  username: ENV.fetch("MAGENTO_USERNAME"),
+  password: ENV.fetch("MAGENTO_PASSWORD")
+)
+
+result = fetcher.fetch
+result.access_token # => admin_token to pass into Client.new
+```
+
+## Usage
+
+```ruby
+# Catalog — product_id is a sku, e.g. "cold-brew"
+products = adapter.search_catalog(query: "cold brew", limit: 10)
+product  = adapter.get_product(product_id: products.first.id)
+
+# Cart — cart_id is only known after the first call, since Magento assigns
+# it (as a masked guest-cart id) rather than taking one from the caller
+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_order_id) # only once linked post-completion
+```
+
+## 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: "cold-brew", 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::Magento::Error    # base class
+Portage::Ucp::Magento::ApiError # any non-2xx response from Magento's REST API
+```
+
+## Development
+
+```bash
+bundle exec rspec   # tests (WebMock-stubbed, no live site needed)
+bundle exec rubocop  # lint
+
+# fetch a real admin token for a dev site
+MAGENTO_BASE_URL=https://your-shop.example.com \
+MAGENTO_USERNAME=... MAGENTO_PASSWORD=... \
+  bundle exec rake magento_access_token
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-magento

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone MCP server over stdio. Configure the site 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.
+#
+# Only MAGENTO_ADMIN_TOKEN is read here, not username/password: this exe
+# expects a bearer token you've already fetched (e.g. via
+# `bundle exec rake magento_access_token`) and refresh out-of-band, since
+# Magento's token endpoint reports no expiry to plan a refresh against.
+#
+# MAGENTO_PAYMENT_METHOD/MAGENTO_DEFAULT_ADDRESS (a JSON object) are optional
+# — only needed to call #complete_checkout, see the README's CAVEATS.
+
+require "json"
+require "portage/ucp"
+require "portage/ucp/magento"
+
+require ENV["PORTAGE_UCP_CONFIG"] if ENV["PORTAGE_UCP_CONFIG"]
+
+client = Portage::Ucp::Magento::Client.new(
+  base_url: ENV.fetch("MAGENTO_BASE_URL"),
+  admin_token: ENV.fetch("MAGENTO_ADMIN_TOKEN")
+)
+default_address = ENV.fetch("MAGENTO_DEFAULT_ADDRESS", nil)
+
+adapter = Portage::Ucp::Magento::Adapter.new(
+  client: client,
+  currency: ENV.fetch("MAGENTO_CURRENCY", "USD"),
+  site_url: ENV.fetch("MAGENTO_SITE_URL", ENV.fetch("MAGENTO_BASE_URL", nil)),
+  payment_method: ENV.fetch("MAGENTO_PAYMENT_METHOD", nil),
+  default_address: default_address && JSON.parse(default_address, symbolize_names: true)
+)
+
+Portage::Ucp::Mcp::Server.build(adapter: adapter).start

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

@@ -0,0 +1,40 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Magento
+      # Exchanges Magento admin credentials for a bearer token via
+      # `/rest/V1/integration/admin/token`.
+      #
+      # Unlike Shopify/Wix's client_credentials grant, this is a plain
+      # username/password exchange (Magento's third-party OAuth1 Integration
+      # flow is the alternative, but that signs every request rather than
+      # handing back a bearer token, which doesn't fit this gem's plain-
+      # Net::HTTP posture). Also unlike Shopify/Wix, the endpoint returns a
+      # bare token string with no `expires_in` — Magento's default admin
+      # token lifetime is a store-config value (`admin/security/session_
+      # lifetime`-adjacent, but token-specific), not something this response
+      # reports, so callers need their own refresh-on-401 strategy rather
+      # than a reported expiry.
+      class AccessTokenFetcher
+        include Portage::Ucp::Support::TokenExchange
+
+        Result = Struct.new(:access_token, keyword_init: true)
+
+        def initialize(base_url:, username:, password:)
+          @base_url = base_url.chomp("/")
+          @username = username
+          @password = password
+        end
+
+        def fetch
+          body = exchange("#{@base_url}/rest/V1/integration/admin/token",
+                          { username: @username, password: @password },
+                          error_class: Portage::Ucp::Magento::Error)
+          Result.new(access_token: body)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,248 @@
+require "uri"
+
+module Portage
+  module Ucp
+    module Magento
+      # Generic Portage::Ucp::Adapter over a Magento/Adobe Commerce site's
+      # REST v1 API — no merchant-specific business logic, same posture as
+      # Portage::Ucp::Shopify::Adapter and Portage::Ucp::WooCommerce::Adapter.
+      #
+      # Deliberately doesn't override `link_identity`: Magento customer
+      # account login is a separate concern from the admin token and
+      # anonymous guest-cart flow this gem uses, so this generic adapter
+      # leaves it unimplemented — Capability#advertised_for? simply won't
+      # advertise dev.ucp.shopping.identity for this adapter, not a 500.
+      #
+      # Catalog and Order are read through the admin-token API. Cart and
+      # Checkout are read/written through the anonymous guest-cart API — a
+      # Magento guest cart *is* the checkout (there's no separate Checkout
+      # resource), same as Shopify's Cart-as-Checkout.
+      #
+      # IMPORTANT CAVEATS:
+      #
+      # - #complete_checkout needs a billing/shipping address to call
+      #   Magento's real guest-checkout flow (`shipping-information` then
+      #   `payment-information`) — UCP's `complete_checkout(checkout_id:,
+      #   payment_token:, idempotency_key:)` carries no address at all. This
+      #   adapter works around that with a single `default_address:`
+      #   configured at initialization (every order ships/bills to the
+      #   same address) rather than guessing a UCP address extension that
+      #   doesn't exist yet — fine for a single-fulfillment-address
+      #   integration, wrong for anything else.
+      # - `payment_data` shape is gateway-specific (configured via
+      #   `payment_method:`/`payment_data_key:`) and hasn't been confirmed
+      #   against a live site with a real gateway installed — same posture
+      #   as Portage::Ucp::WooCommerce::Adapter's own payment step.
+      class Adapter < Portage::Ucp::Adapter
+        # The guest-cart API takes no idempotency key natively, so §9a dedup
+        # comes from Support::Idempotency's in-process table.
+        include Portage::Ucp::Support::Idempotency
+        # A Magento guest cart has no native status field, and an Order's own
+        # `quote_id` is the cart's internal integer id rather than the masked
+        # guest-cart id this gem uses (see Mapper.order) — both are tracked
+        # adapter-side via Support::CheckoutState.
+        include Portage::Ucp::Support::CheckoutState
+        # The admin-token API answers a missing product or order with a 404
+        # rather than an empty body, which UCP's reads report as nil.
+        include Portage::Ucp::Support::NotFound
+
+        def initialize(client:, currency:, site_url: nil, payment_method: nil, payment_data_key: "cc_token",
+                       default_address: nil)
+          super()
+          @client = client
+          @currency = currency
+          @site_url = site_url&.chomp("/")
+          @payment_method = payment_method
+          @payment_data_key = payment_data_key
+          @default_address = default_address
+        end
+
+        def search_catalog(query:, limit:)
+          params = { "searchCriteria[filterGroups][0][filters][0][field]" => "name",
+                     "searchCriteria[filterGroups][0][filters][0][value]" => "%#{query}%",
+                     "searchCriteria[filterGroups][0][filters][0][conditionType]" => "like",
+                     "searchCriteria[pageSize]" => limit }
+          data = @client.admin_get("/products?#{URI.encode_www_form(params)}")
+          (data["items"] || []).map { |node| Mapper.product(node, currency: @currency, site_url: @site_url) }
+        end
+
+        def get_product(product_id:)
+          nil_on_not_found do
+            node = @client.admin_get("/products/#{URI.encode_www_form_component(product_id)}")
+            node["sku"] ? Mapper.product(with_children(node), currency: @currency, site_url: @site_url) : nil
+          end
+        end
+
+        def get_cart(cart_id:)
+          items, currency = cart_snapshot(cart_id)
+          Mapper.cart(items, id: cart_id, currency: currency)
+        end
+
+        def create_cart(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            cart_id = @client.guest_post("/guest-carts")
+            add_items(cart_id, line_items)
+            items, currency = cart_snapshot(cart_id)
+            Mapper.cart(items, id: cart_id, currency: currency)
+          end
+        end
+
+        # Full replacement, same rationale as Portage::Ucp::Shopify::Adapter
+        # #update_cart: Magento's guest-cart items API has no atomic
+        # "replace all lines" either, so this removes every current line
+        # then adds the desired ones back.
+        def update_cart(cart_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            replace_items(cart_id, line_items)
+            items, currency = cart_snapshot(cart_id)
+            Mapper.cart(items, id: cart_id, currency: currency)
+          end
+        end
+
+        # A guest cart is tied to its quote, not a deletable resource with
+        # its own lifecycle — there's no cancellation call, so this clears
+        # every line and returns the now-empty cart, the closest real
+        # equivalent (same posture as Portage::Ucp::WooCommerce::Adapter).
+        def cancel_cart(cart_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            replace_items(cart_id, [])
+            items, currency = cart_snapshot(cart_id)
+            Mapper.cart(items, id: cart_id, currency: currency)
+          end
+        end
+
+        def create_checkout(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            cart_id = @client.guest_post("/guest-carts")
+            add_items(cart_id, line_items)
+            record_checkout_status(cart_id, "incomplete")
+            items, currency = cart_snapshot(cart_id)
+            Mapper.checkout(items, id: cart_id, currency: currency, status: "incomplete")
+          end
+        end
+
+        def get_checkout(checkout_id:)
+          items, currency = cart_snapshot(checkout_id)
+          Mapper.checkout(items, id: checkout_id, currency: currency,
+                                 status: checkout_status(checkout_id))
+        end
+
+        # Full replacement, same rationale as #update_cart.
+        def update_checkout(checkout_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            replace_items(checkout_id, line_items)
+            items, currency = cart_snapshot(checkout_id)
+            record_checkout_status(checkout_id, "incomplete")
+            Mapper.checkout(items, id: checkout_id, currency: currency, status: "incomplete")
+          end
+        end
+
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key:)
+          dedup(idempotency_key) { submit_checkout(checkout_id, payment_token) }
+        end
+
+        # Magento has no cancellation endpoint for an in-progress guest cart
+        # either (see #cancel_cart) — this just marks the tracked status
+        # canceled without touching the underlying cart contents.
+        def cancel_checkout(checkout_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            record_checkout_status(checkout_id, "canceled")
+            items, currency = cart_snapshot(checkout_id)
+            Mapper.checkout(items, id: checkout_id, currency: currency, status: "canceled")
+          end
+        end
+
+        def get_order(order_id:)
+          nil_on_not_found do
+            node = @client.admin_get("/orders/#{order_id}")
+            next nil unless node["entity_id"]
+
+            Mapper.order(node, checkout_id: checkout_id_for(order_id))
+          end
+        end
+
+        private
+
+        # Merges the guest-cart `items` resource (sku/name/qty/price) with
+        # the `totals` resource (row_total/tax_amount/quote_currency_code)
+        # by `item_id` — see Mapper.cart's comment on why Magento needs this
+        # two-call merge where Shopify/Wix/WooCommerce each have one
+        # response that already carries everything.
+        def cart_snapshot(cart_id)
+          items = @client.guest_get("/guest-carts/#{cart_id}/items")
+          totals_data = @client.guest_get("/guest-carts/#{cart_id}/totals")
+          totals_by_id = (totals_data["items"] || []).to_h { |t| [t["item_id"], t] }
+          merged = items.map { |i| i.merge(totals_by_id.fetch(i["item_id"], {})) }
+          [merged, totals_data["quote_currency_code"] || @currency]
+        end
+
+        # A variable product's own resource only lists child skus under
+        # `extension_attributes.configurable_product_links` — fetching the
+        # full child product objects is a second call, only made for
+        # #get_product's single-product path, not #search_catalog's list
+        # (an N+1 fetch per search result would be too expensive).
+        def with_children(node)
+          return node unless node["type_id"] == "configurable"
+
+          children = @client.admin_get("/configurable-products/#{URI.encode_www_form_component(node['sku'])}/children")
+          node.merge("children_detail" => children)
+        end
+
+        def add_items(cart_id, line_items)
+          line_items.each do |li|
+            @client.guest_post("/guest-carts/#{cart_id}/items",
+                               { cartItem: { sku: li[:product_id], qty: li[:quantity], quote_id: cart_id } })
+          end
+        end
+
+        def replace_items(cart_id, line_items)
+          current = @client.guest_get("/guest-carts/#{cart_id}/items")
+          current.each { |item| @client.guest_delete("/guest-carts/#{cart_id}/items/#{item['item_id']}") }
+          add_items(cart_id, line_items)
+        end
+
+        # See the class-level CAVEATS: `default_address` stands in for
+        # UCP's missing per-checkout address, and `payment_data` uses a
+        # single configurable key rather than a confirmed gateway-specific
+        # shape.
+        def verify_checkout_configured!
+          raise Portage::Ucp::Magento::Error, "no payment_method configured on this Adapter" unless @payment_method
+          raise Portage::Ucp::Magento::Error, "no default_address configured on this Adapter" unless @default_address
+        end
+
+        def submit_checkout(checkout_id, payment_token)
+          verify_checkout_configured!
+          items, currency = cart_snapshot(checkout_id)
+          submit_shipping_information(checkout_id)
+          order_id = submit_payment_information(checkout_id, payment_token)
+          record_checkout_status(checkout_id, "completed")
+          record_order_checkout(order_id, checkout_id)
+          Mapper.checkout(items, id: checkout_id, currency: currency, status: "completed",
+                                 order: order_confirmation(order_id))
+        end
+
+        def submit_shipping_information(checkout_id)
+          @client.guest_post("/guest-carts/#{checkout_id}/shipping-information",
+                             { addressInformation: { shipping_address: @default_address,
+                                                     billing_address: @default_address,
+                                                     shipping_carrier_code: "flatrate",
+                                                     shipping_method_code: "flatrate" } })
+        end
+
+        def submit_payment_information(checkout_id, payment_token)
+          @client.guest_post("/guest-carts/#{checkout_id}/payment-information",
+                             { email: @default_address[:email] || "guest@example.com",
+                               paymentMethod: { method: @payment_method,
+                                                additional_data: { @payment_data_key => payment_token } },
+                               billingAddress: @default_address })
+        end
+
+        # Same blank permalink_url posture as Mapper.order — Magento has no
+        # public order-status link to hand back here either.
+        def order_confirmation(order_id)
+          Portage::Ucp::OrderConfirmation.new(id: order_id.to_s, permalink_url: "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Magento
+      # Minimal REST client over a Magento/Adobe Commerce site's `/rest/V1`
+      # API.
+      #
+      # Deliberately plain Net::HTTP, not the Magento PHP SDK (there isn't a
+      # Ruby one) — a generic adapter that any Ruby app can drop in only
+      # needs a base URL and a bearer token, no framework coupling,
+      # trivially stubbable with WebMock.
+      #
+      # Like Shopify's Admin/Storefront split and WooCommerce's Admin/Store
+      # API split, Magento's REST surface has two effective auth tiers under
+      # the same `/rest/V1` path:
+      #
+      # - Admin-token calls (catalog, order): require a Bearer token minted
+      #   from admin credentials (see
+      #   Portage::Ucp::Magento::AccessTokenFetcher) or a pre-generated
+      #   Integration token.
+      # - Guest-cart calls (cart, checkout): Magento's guest-cart endpoints
+      #   (`/guest-carts/*`) are anonymous by design — no token at all,
+      #   identified purely by the masked cart id in the URL.
+      class Client
+        include Portage::Ucp::Support::HttpClient
+
+        def initialize(base_url:, admin_token: nil)
+          @base_url = base_url.chomp("/")
+          @admin_token = admin_token
+        end
+
+        def admin_get(path)
+          admin_request(Net::HTTP::Get, path)
+        end
+
+        def admin_post(path, body = {})
+          admin_request(Net::HTTP::Post, path, body)
+        end
+
+        def guest_get(path)
+          guest_request(Net::HTTP::Get, path)
+        end
+
+        def guest_post(path, body = {})
+          guest_request(Net::HTTP::Post, path, body)
+        end
+
+        def guest_delete(path)
+          guest_request(Net::HTTP::Delete, path)
+        end
+
+        private
+
+        def admin_request(http_method, path, body = nil)
+          raise ArgumentError, "Portage::Ucp::Magento::Client requires admin_token for this call" unless @admin_token
+
+          json_request(http_method, "#{@base_url}/rest/V1#{path}",
+                       body: body, headers: { "Authorization" => "Bearer #{@admin_token}" })
+        end
+
+        def guest_request(http_method, path, body = nil)
+          json_request(http_method, "#{@base_url}/rest/V1#{path}", body: body)
+        end
+
+        def api_error_class = Portage::Ucp::Magento::ApiError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Portage
+  module Ucp
+    module Magento
+      class Error < StandardError; end
+
+      # Raised for any non-2xx response from Magento's REST API (`/rest/V1`)
+      # — both the admin-token side (catalog, order) and the anonymous
+      # guest-cart side (cart, checkout) report errors the same way: a
+      # non-2xx status with a JSON `{message, parameters}` body.
+      class ApiError < Error
+        include Portage::Ucp::Support::ApiError
+
+        private
+
+        def detail(body)
+          body["message"] || body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+module Portage
+  module Ucp
+    module Magento
+      # Converts Magento REST v1 response bodies into the protocol-layer
+      # value objects from Portage::Ucp::ValueObjects — nothing Magento-
+      # shaped is allowed to leak past this file.
+      #
+      # `currency` is threaded in by the caller everywhere it's needed: the
+      # product resource has no currency field (a site-wide/store-view
+      # setting, not per-product), same limitation as WooCommerce's Admin
+      # product resource.
+      #
+      # Cart items are identified by `sku`, not a numeric id — Magento's
+      # `cartItem` add/update payloads take `sku`, so that's what's threaded
+      # through as UCP's `product_id` everywhere in this gem, not the
+      # product's numeric `id`.
+      module Mapper
+        module_function
+
+        def money(amount, currency)
+          Portage::Ucp::Support::Amounts.money(amount, currency)
+        end
+
+        def minor_units(amount)
+          Portage::Ucp::Support::Amounts.decimal_to_minor(amount)
+        end
+
+        def custom_attribute(node, code)
+          (node["custom_attributes"] || []).find { |a| a["attribute_code"] == code }&.dig("value")
+        end
+
+        def in_stock?(node)
+          node.dig("extension_attributes", "stock_item", "is_in_stock") != false
+        end
+
+        # `node["children_detail"]` is adapter-populated, not a real Magento
+        # field: a configurable product's own resource only lists child skus
+        # under `extension_attributes.configurable_product_links` (bare ids)
+        # — fetching the full child product objects
+        # (`/configurable-products/{sku}/children`) is a second request the
+        # Adapter makes and merges in before calling this, same reasoning as
+        # Portage::Ucp::WooCommerce::Mapper's `variations_detail`.
+        def product(node, currency:, site_url: nil)
+          Portage::Ucp::Product.new(
+            id: node["sku"],
+            title: node["name"],
+            description: custom_attribute(node, "description"),
+            price: money(node["price"], currency),
+            available: node["status"] == 1 && in_stock?(node),
+            variants: variants(node, currency),
+            url: product_url(node, site_url)
+          )
+        end
+
+        def product_url(node, site_url)
+          url_key = custom_attribute(node, "url_key")
+          return nil unless site_url && url_key
+
+          "#{site_url}/#{url_key}.html"
+        end
+
+        # A simple product has no real variants — it's its own single
+        # implicit variant, same as a single-variant Shopify product using
+        # that variant's own id.
+        def variants(node, currency)
+          children = node["children_detail"]
+          unless children
+            return [{ id: node["sku"], title: node["name"], available: node["status"] == 1 && in_stock?(node),
+                      price: money(node["price"], currency) }]
+          end
+
+          children.map do |c|
+            { id: c["sku"], title: c["name"], available: c["status"] == 1 && in_stock?(c),
+              price: money(c["price"], currency) }
+          end
+        end
+
+        # `id:` and `currency:` are caller-supplied: the guest-cart `items`
+        # resource (sku/name/qty/price) and `totals` resource (row totals,
+        # tax, `quote_currency_code`) are two separate Magento REST calls —
+        # the Adapter merges them by `item_id` before calling this, same
+        # reasoning as Portage::Ucp::WooCommerce::Mapper needing `id:`
+        # supplied (Magento's cart has no single resource id of its own
+        # either, just the masked cart id used in the URL).
+        def cart(items, id:, currency:)
+          Portage::Ucp::Cart.new(
+            id: id,
+            line_items: items.map { |n| cart_line_item(n) },
+            currency: currency,
+            totals: totals(items)
+          )
+        end
+
+        # `status` isn't a Magento cart field — a Magento guest cart *is*
+        # the checkout (there's no separate Checkout resource, only the
+        # shipping-information/payment-information calls that act on the
+        # same cart), so the Adapter tracks status itself and passes it in
+        # here, same rationale as Shopify's Cart-as-Checkout.
+        def checkout(items, id:, currency:, status:, order: nil)
+          Portage::Ucp::Checkout.new(
+            id: id,
+            status: status,
+            line_items: items.map { |n| cart_line_item(n) },
+            currency: currency,
+            totals: totals(items),
+            links: [],
+            order: order
+          )
+        end
+
+        def cart_line_item(node)
+          line_total = minor_units(node["row_total"])
+          quantity = node["qty"]
+          unit_price = quantity.to_i.positive? ? (line_total / quantity).round : minor_units(node["price"])
+          Portage::Ucp::LineItem.new(
+            id: node["item_id"].to_s,
+            item: Portage::Ucp::Item.new(id: node["sku"], title: node["name"], price: unit_price),
+            quantity: quantity,
+            totals: Portage::Ucp::Support::Totals.line(line_total)
+          )
+        end
+
+        # Builds the top-level totals array from the merged line items'
+        # row_total (subtotal) plus each line's own tax_amount, since
+        # there's no single caller-supplied totals hash here the way
+        # Shopify/Wix/WooCommerce have one — see #cart's comment on why
+        # items/totals are merged per-line before reaching this module.
+        def totals(items)
+          subtotal = items.sum { |n| minor_units(n["row_total"]) }
+          tax = items.sum { |n| minor_units(n["tax_amount"]) }
+          Portage::Ucp::Support::Totals.summary(subtotal: subtotal, tax: tax, total: subtotal + tax)
+        end
+
+        # Magento core has no per-line-item fulfillment tracking on the
+        # Order resource itself (that's the separate Shipments API) — every
+        # line is given the same coarse status derived from the order's own
+        # top-level `status`, same simplification as
+        # Portage::Ucp::WooCommerce::Mapper.
+        ORDER_LINE_ITEM_STATUS = {
+          "complete" => "fulfilled", "closed" => "fulfilled", "processing" => "processing",
+          "pending" => "processing", "canceled" => "removed"
+        }.freeze
+
+        # `permalink_url` is left blank — Magento's Orders API doesn't
+        # return a public order-status page URL (guest order tracking is a
+        # storefront form, not a direct link). `checkout_id` isn't a
+        # reachable Magento order field either: `order.quote_id` is the
+        # cart's *internal* integer id, not the masked guest-cart id used in
+        # every REST URL, and Magento doesn't expose the mapping between the
+        # two via the API — so, like WooCommerce, the Adapter records it
+        # itself at #complete_checkout time instead.
+        def order(node, checkout_id: "")
+          currency = node["order_currency_code"]
+          subtotal = minor_units(node["subtotal"])
+          total = minor_units(node["grand_total"])
+          status = Portage::Ucp::Support::LineItemStatus.from_table(ORDER_LINE_ITEM_STATUS, node["status"])
+          Portage::Ucp::Order.new(
+            id: node["entity_id"].to_s,
+            checkout_id: checkout_id,
+            permalink_url: "",
+            line_items: (node["items"] || []).map { |n| order_line_item(n, status) },
+            fulfillment: Portage::Ucp::Fulfillment.new,
+            currency: currency,
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal, total: total)
+          )
+        end
+
+        def order_line_item(node, status)
+          quantity = node["qty_ordered"].to_i
+          fulfilled = Portage::Ucp::Support::LineItemStatus.fulfilled_quantity(status, quantity)
+          line_total = minor_units(node["row_total"])
+          Portage::Ucp::OrderLineItem.new(
+            id: node["item_id"].to_s,
+            item: Portage::Ucp::Item.new(id: node["sku"], title: node["name"], price: minor_units(node["price"])),
+            quantity: { original: quantity, total: quantity, fulfilled: fulfilled },
+            totals: Portage::Ucp::Support::Totals.line(line_total),
+            status: status
+          )
+        end
+      end
+    end
+  end
+end

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

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

data/lib/portage/ucp/magento.rb

@@ -0,0 +1,7 @@
+require "portage/ucp"
+require_relative "magento/version"
+require_relative "magento/errors"
+require_relative "magento/client"
+require_relative "magento/access_token_fetcher"
+require_relative "magento/mapper"
+require_relative "magento/adapter"

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: portage-ucp-magento
+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 a Magento/Adobe Commerce site's
+  REST v1 API (admin-token catalog/order, anonymous guest-cart cart/checkout). Generic
+  only — no merchant-specific business logic. Plain Net::HTTP, no Magento PHP SDK
+  dependency.
+email:
+executables:
+- portage-ucp-magento
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/portage-ucp-magento
+- lib/portage/ucp/magento.rb
+- lib/portage/ucp/magento/access_token_fetcher.rb
+- lib/portage/ucp/magento/adapter.rb
+- lib/portage/ucp/magento/client.rb
+- lib/portage/ucp/magento/errors.rb
+- lib/portage/ucp/magento/mapper.rb
+- lib/portage/ucp/magento/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-magento
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-magento
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-magento/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: Magento/Adobe Commerce adapter for portage-ucp — standard catalog/cart/checkout/order
+  over MCP and UCP
+test_files: []