portage-ucp-woocommerce 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4a4539d949226ab96ca758ccbea5d8ad40c789a7bd25d5512b9af0fcf8c0240
+  data.tar.gz: '0289fb79597b556193107a4d32efb3b10f2ae1800df73910e2d62793799fd6d8'
+SHA512:
+  metadata.gz: 9b442c458f7157abb0140eabb5700d87fdb7f55d7c34d740b4057d5530873bc6200342a5017aea73d402d04c86f7111858d369de7578907ed622164c4f4e36e3
+  data.tar.gz: 5790802bc3de14b69490c41eb50902d2ba36889256cb7077c990da6b296aff6c103c1f10a661e63dfb5a0372805a2f09a81bc51ba9673ec5c91dfd1ec1ba879f

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. WooCommerce adapter against the Admin REST API v3
+  (catalog, order) and Store API v1 (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,129 @@
+# portage-ucp-woocommerce
+
+WooCommerce adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::Adapter` against a WooCommerce site's Admin REST API v3 (catalog, order) and Store API v1 (cart, checkout). Generic only — no merchant-specific business logic. Plain `Net::HTTP`, no `woocommerce-api` runtime dependency.
+
+## What it covers
+
+| UCP capability | Backing WooCommerce API | Notes |
+|---|---|---|
+| `dev.ucp.shopping.catalog` | Admin REST v3 | `search_catalog`, `get_product` |
+| `dev.ucp.shopping.cart` | Store API (Cart) | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
+| `dev.ucp.shopping.checkout` | Store API (same Cart, plus `/checkout`) | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
+| `dev.ucp.shopping.order` | Admin REST v3 | `get_order` |
+| `dev.ucp.shopping.identity` | — | not implemented; WordPress/WooCommerce user auth is a separate concern from the Admin keys + anonymous Store API session used here |
+
+Like Shopify, WooCommerce has no separate "Checkout" object — the Store API's Cart **is** the checkout, identified by an opaque `Cart-Token` session header rather than a resource id. The adapter tracks checkout status itself, keyed by that token, and records `Order#checkout_id` itself at completion time (WooCommerce orders don't link back to their originating cart natively).
+
+Update/replace operations (`update_cart`, `update_checkout`) are full-replacement: the Store API has no atomic "replace all lines" mutation 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.
+
+Unlike Shopify/Wix, there's no `AccessTokenFetcher` — WooCommerce Admin keys are static, generated once in wp-admin (WooCommerce → Settings → Advanced → REST API), with nothing to exchange or expire.
+
+## ⚠️ Unverified against a live site
+
+Built from WooCommerce's documented REST/Store API shapes, not run against a real site yet. Before relying on this in production, confirm:
+
+- **`#complete_checkout`** — posts `payment_method` + `payment_data` to the Store API's `/checkout` endpoint. `payment_method` must match an installed, enabled WC gateway id, and the `payment_data` key a gateway expects (`payment_data_key:`, default `"token"`) is gateway-specific — Stripe's block-based gateway and PayPal's don't necessarily read the same key. Needs confirming against a live site with a real gateway installed.
+- **Variable product variants** — `Mapper.variant`'s title is built by joining `attributes[].option`; not verified against a real variable product's actual attribute shape.
+- **Order fulfillment** — WooCommerce core has no per-line-item fulfillment tracking (that's a shipment-tracking-plugin concern), so every order line is given the same coarse status derived from the order's own top-level `status`, not a real per-line signal.
+- **Store API checkout response shape** — assumed to carry the same `items`/`totals` shape as the Cart response, plus `order_id`. Not confirmed live.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-woocommerce"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+You need a site URL, an Admin REST API consumer key/secret pair (wp-admin → WooCommerce → Settings → Advanced → REST API — grant Read/Write), your store's currency (the Admin product resource doesn't return one), and — only if you'll call `complete_checkout` — the WC payment gateway id you want to submit orders through.
+
+```ruby
+require "portage/ucp/woocommerce"
+
+client = Portage::Ucp::WooCommerce::Client.new(
+  site_url: "https://your-shop.example.com",
+  consumer_key: ENV.fetch("WOOCOMMERCE_CONSUMER_KEY"),
+  consumer_secret: ENV.fetch("WOOCOMMERCE_CONSUMER_SECRET")
+)
+
+adapter = Portage::Ucp::WooCommerce::Adapter.new(
+  client: client,
+  site_url: "https://your-shop.example.com",
+  currency: "USD",
+  payment_method: "stripe_cc" # only required for #complete_checkout
+)
+```
+
+## Usage
+
+```ruby
+# Catalog
+products = adapter.search_catalog(query: "hoodie", limit: 10)
+product  = adapter.get_product(product_id: products.first.id)
+
+# Cart — cart_id is only known after the first call, since the Store API
+# assigns it (as a Cart-Token) 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: 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::WooCommerce::Error    # base class
+Portage::Ucp::WooCommerce::ApiError # any non-2xx response from either the Admin or Store API
+```
+
+## Development
+
+```bash
+bundle exec rspec   # tests (WebMock-stubbed, no live site needed)
+bundle exec rubocop  # lint
+
+# verify a real site's Admin key/secret by listing one product
+WOOCOMMERCE_SITE_URL=https://your-shop.example.com \
+WOOCOMMERCE_CONSUMER_KEY=... WOOCOMMERCE_CONSUMER_SECRET=... \
+  bundle exec rake woocommerce_smoke_test
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-woocommerce

@@ -0,0 +1,31 @@
+#!/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.
+#
+# WOOCOMMERCE_PAYMENT_METHOD is optional — only needed to call
+# #complete_checkout (must match an installed, enabled WC gateway id).
+
+require "portage/ucp"
+require "portage/ucp/woocommerce"
+
+require ENV["PORTAGE_UCP_CONFIG"] if ENV["PORTAGE_UCP_CONFIG"]
+
+client = Portage::Ucp::WooCommerce::Client.new(
+  site_url: ENV.fetch("WOOCOMMERCE_SITE_URL"),
+  consumer_key: ENV.fetch("WOOCOMMERCE_CONSUMER_KEY"),
+  consumer_secret: ENV.fetch("WOOCOMMERCE_CONSUMER_SECRET")
+)
+adapter = Portage::Ucp::WooCommerce::Adapter.new(
+  client: client,
+  site_url: ENV.fetch("WOOCOMMERCE_SITE_URL"),
+  currency: ENV.fetch("WOOCOMMERCE_CURRENCY", "USD"),
+  payment_method: ENV.fetch("WOOCOMMERCE_PAYMENT_METHOD", nil)
+)
+
+Portage::Ucp::Mcp::Server.build(adapter: adapter).start

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

@@ -0,0 +1,193 @@
+require "uri"
+
+module Portage
+  module Ucp
+    module WooCommerce
+      # Generic Portage::Ucp::Adapter over a WooCommerce site's Admin REST
+      # API v3 (catalog, order) and Store API v1 (cart, checkout) — no
+      # merchant-specific business logic, same posture as
+      # Portage::Ucp::Shopify::Adapter.
+      #
+      # Deliberately doesn't override `link_identity`: WooCommerce/WordPress
+      # user auth is a separate concern from the store-owner Admin keys and
+      # anonymous Store API session 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 API (the Store API has
+      # no product search and can't look up an arbitrary past order without
+      # a customer session). Cart and Checkout are read/written through the
+      # Store API — Admin's REST v3 has no "Cart" resource at all, only
+      # Orders, and an Order only exists once checkout completes.
+      #
+      # IMPORTANT CAVEAT: #complete_checkout calls the Store API's
+      # `/checkout` endpoint with `payment_method` (configured at
+      # initialization, since it must match an installed, enabled WC
+      # payment gateway id) and `payment_data` built from `payment_token`.
+      # The exact `payment_data` key(s) a given gateway expects are gateway-
+      # specific (e.g. Stripe's block-based gateway reads a different key
+      # than PayPal's) and this hasn't been confirmed against a live site
+      # with a real gateway installed — same "needs confirming against a
+      # live store" posture as Portage::Ucp::Shopify::Adapter's own payment
+      # step.
+      class Adapter < Portage::Ucp::Adapter
+        # The Store API takes no idempotency key natively, so §9a dedup comes
+        # from Support::Idempotency's in-process table.
+        include Portage::Ucp::Support::Idempotency
+        # Store API cart and checkout share one underlying session (keyed by
+        # Cart-Token) with no status of its own, and WC orders don't link
+        # back to the Cart-Token that produced them (see Mapper.order) —
+        # both are tracked adapter-side via Support::CheckoutState.
+        include Portage::Ucp::Support::CheckoutState
+        # The Admin 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:, site_url:, currency:, payment_method: nil, payment_data_key: "token")
+          super()
+          @client = client
+          @site_url = site_url.chomp("/")
+          @currency = currency
+          @payment_method = payment_method
+          @payment_data_key = payment_data_key
+        end
+
+        def search_catalog(query:, limit:)
+          data = @client.admin_get("/products?search=#{URI.encode_www_form_component(query)}&per_page=#{limit}")
+          data.map { |node| Mapper.product(node, currency: @currency) }
+        end
+
+        def get_product(product_id:)
+          nil_on_not_found do
+            node = @client.admin_get("/products/#{product_id}")
+            node["id"] ? Mapper.product(with_variations(node), currency: @currency) : nil
+          end
+        end
+
+        def get_cart(cart_id:)
+          Mapper.cart(fetch_cart_node, id: cart_id)
+        end
+
+        def create_cart(line_items:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(replace_cart_lines(line_items), id: @client.cart_token) }
+        end
+
+        # Full replacement, same rationale as Portage::Ucp::Shopify::Adapter
+        # #update_cart: the Store 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) { Mapper.cart(replace_cart_lines(line_items), id: cart_id) }
+        end
+
+        # The Store API's cart is tied to a session, 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.
+        def cancel_cart(cart_id:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(replace_cart_lines([]), id: cart_id) }
+        end
+
+        def create_checkout(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            node = replace_cart_lines(line_items)
+            record_checkout_status(@client.cart_token, "incomplete")
+            Mapper.checkout(node, id: @client.cart_token, status: "incomplete")
+          end
+        end
+
+        def get_checkout(checkout_id:)
+          Mapper.checkout(fetch_cart_node, id: checkout_id, 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
+            node = replace_cart_lines(line_items)
+            record_checkout_status(checkout_id, "incomplete")
+            Mapper.checkout(node, id: checkout_id, status: "incomplete")
+          end
+        end
+
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key:)
+          dedup(idempotency_key) { submit_checkout(checkout_id, payment_token) }
+        end
+
+        # The Store API has no cancellation endpoint for an in-progress
+        # checkout 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")
+            Mapper.checkout(fetch_cart_node, id: checkout_id, 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["id"]
+
+            Mapper.order(node, site_url: @site_url, checkout_id: checkout_id_for(order_id))
+          end
+        end
+
+        private
+
+        def fetch_cart_node
+          @client.store_get("/cart")
+        end
+
+        # A variable product's Admin resource only lists variation *ids*
+        # (`variations: [123, 124]`) — fetching the full variation objects
+        # (price, stock, attribute choices) 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_variations(node)
+          return node unless node["type"] == "variable" && node["variations"]&.any?
+
+          node.merge("variations_detail" => @client.admin_get("/products/#{node['id']}/variations?per_page=100"))
+        end
+
+        def cart_lines(line_items)
+          line_items.map { |li| { id: li[:product_id].to_i, quantity: li[:quantity] } }
+        end
+
+        def replace_cart_lines(line_items)
+          fetch_cart_node["items"].each { |item| @client.store_post("/cart/remove-item", { key: item["key"] }) }
+          cart_lines(line_items).each { |line| @client.store_post("/cart/add-item", line) }
+          fetch_cart_node
+        end
+
+        # See the class-level CAVEAT: `payment_data` uses a single
+        # configurable key (`payment_data_key:`, default "token") rather
+        # than a confirmed gateway-specific shape.
+        def submit_checkout(checkout_id, payment_token)
+          raise Portage::Ucp::WooCommerce::Error, "no payment_method configured on this Adapter" unless @payment_method
+
+          data = @client.store_post("/checkout", {
+                                      payment_method: @payment_method,
+                                      payment_data: [{ key: @payment_data_key, value: payment_token }]
+                                    })
+          record_checkout_status(checkout_id, "completed")
+          order = build_order_confirmation(data, checkout_id)
+          Mapper.checkout(data, id: checkout_id, status: "completed", order: order)
+        end
+
+        # Same order-received URL pattern as Mapper.order's `permalink_url` —
+        # the Store API's checkout response hands back order_id/order_key
+        # directly, so there's no need for a second Admin fetch just to build
+        # this link.
+        def build_order_confirmation(data, checkout_id)
+          return unless data["order_id"]
+
+          record_order_checkout(data["order_id"], checkout_id)
+          Portage::Ucp::OrderConfirmation.new(
+            id: data["order_id"].to_s,
+            permalink_url: "#{@site_url}/checkout/order-received/#{data['order_id']}/?key=#{data['order_key']}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module WooCommerce
+      # Minimal REST client over a WooCommerce site's two distinct APIs.
+      #
+      # Deliberately plain Net::HTTP, not the `woocommerce-api` gem — a
+      # generic adapter that any Ruby app can drop in only needs a site URL
+      # and a pair of keys, no framework coupling, trivially stubbable with
+      # WebMock.
+      #
+      # Like Shopify's Admin/Storefront split, WooCommerce has two separate
+      # APIs with two separate auth models:
+      #
+      # - Admin REST API (`/wp-json/wc/v3`): store-owner Basic Auth via a
+      #   static consumer_key/consumer_secret pair generated once in
+      #   wp-admin. No OAuth exchange, no expiry — unlike Shopify/Wix, there
+      #   is no Portage::Ucp::WooCommerce::AccessTokenFetcher because there's
+      #   nothing to exchange.
+      # - Store API (`/wp-json/wc/store/v1`): the public, unauthenticated
+      #   cart/checkout API WooCommerce Blocks itself uses. It's session-
+      #   based rather than token-based: the *first* request gets back a
+      #   `Cart-Token` response header identifying an anonymous cart, which
+      #   must be resent as a `Cart-Token` request header on every
+      #   subsequent call to stay on the same cart. State-changing calls
+      #   (POST/PUT/DELETE) also require a `Nonce` header, sourced the same
+      #   way from an earlier response. This client tracks both headers
+      #   in-instance so callers don't have to.
+      class Client
+        include Portage::Ucp::Support::HttpClient
+
+        def initialize(site_url:, consumer_key:, consumer_secret:)
+          @site_url = site_url.chomp("/")
+          @consumer_key = consumer_key
+          @consumer_secret = consumer_secret
+          @cart_token = nil
+          @nonce = nil
+        end
+
+        attr_reader :cart_token
+
+        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 store_get(path)
+          store_request(Net::HTTP::Get, path)
+        end
+
+        def store_post(path, body = {})
+          store_request(Net::HTTP::Post, path, body)
+        end
+
+        def store_delete(path)
+          store_request(Net::HTTP::Delete, path)
+        end
+
+        private
+
+        def admin_request(http_method, path, body = nil)
+          json_request(http_method, "#{@site_url}/wp-json/wc/v3#{path}",
+                       body: body, basic_auth: [@consumer_key, @consumer_secret])
+        end
+
+        # Threads `Cart-Token` on every call (once one's been seen) and
+        # `Nonce` on writes — see the class-level comment. Both are
+        # refreshed from whatever the response hands back, since WooCommerce
+        # can rotate the nonce between requests, which is why this reads the
+        # raw response before parsing it.
+        def store_request(http_method, path, body = nil)
+          headers = {}
+          headers["Cart-Token"] = @cart_token if @cart_token
+          headers["Nonce"] = @nonce if @nonce && http_method != Net::HTTP::Get
+          response = json_request(http_method, "#{@site_url}/wp-json/wc/store/v1#{path}",
+                                  body: body, headers: headers, raw: true)
+
+          @cart_token = response["Cart-Token"] if response["Cart-Token"]
+          @nonce = response["Nonce"] if response["Nonce"]
+          parse!(response)
+        end
+
+        def api_error_class = Portage::Ucp::WooCommerce::ApiError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Portage
+  module Ucp
+    module WooCommerce
+      class Error < StandardError; end
+
+      # Raised for any non-2xx response from either the Admin REST API (v3,
+      # Basic Auth) or the Store API (v1, cart-token session) — both surface
+      # errors the same way: a non-2xx status with a JSON `{code, message}`
+      # body (`rest_*` codes on the Admin side, `woocommerce_rest_*`/
+      # `woocommerce_store_api_*` on the Store side).
+      class ApiError < Error
+        include Portage::Ucp::Support::ApiError
+
+        private
+
+        def detail(body)
+          body["message"] || body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+module Portage
+  module Ucp
+    module WooCommerce
+      # Converts WooCommerce Admin REST v3 (products, orders) and Store API
+      # v1 (cart, checkout) response bodies into the protocol-layer value
+      # objects from Portage::Ucp::ValueObjects — nothing WooCommerce-shaped
+      # is allowed to leak past this file.
+      #
+      # `currency` is threaded in by the caller everywhere it's needed: the
+      # Admin product resource doesn't carry a currency field at all (it's a
+      # site-wide setting, not per-product), unlike the Store API's cart/
+      # checkout responses, which do include one (`totals.currency_code`).
+      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
+
+        # `node["variations_detail"]` is adapter-populated, not a real WC
+        # field: the Admin product resource only lists variation *ids* for a
+        # variable product (`variations: [123, 124]`), so fetching full
+        # variation objects is a second request the Adapter makes and merges
+        # in before calling this — Mapper stays pure translation, no I/O.
+        def product(node, currency:)
+          Portage::Ucp::Product.new(
+            id: node["id"].to_s,
+            title: node["name"],
+            description: node["description"],
+            price: money(node["price"], currency),
+            available: node["stock_status"] != "outofstock",
+            variants: variants(node, currency),
+            url: node["permalink"]
+          )
+        end
+
+        # A simple (non-variable) 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)
+          detail = node["variations_detail"]
+          unless detail
+            return [{ id: node["id"].to_s, title: node["name"],
+                      available: node["stock_status"] != "outofstock", price: money(node["price"], currency) }]
+          end
+
+          detail.map { |v| variant(v, currency) }
+        end
+
+        def variant(node, currency)
+          title = (node["attributes"] || []).map { |a| a["option"] }.join(" / ")
+          { id: node["id"].to_s, title: title, available: node["stock_status"] != "outofstock",
+            price: money(node["price"], currency) }
+        end
+
+        # `id:` is caller-supplied rather than read off the response body:
+        # the Store API cart has no in-body resource id, only a `cart_hash`
+        # change-detection fingerprint. What actually identifies "this cart"
+        # across calls is the opaque `Cart-Token` the session is keyed by
+        # (see Portage::Ucp::WooCommerce::Client) — the Adapter passes that
+        # token through as `id:`.
+        def cart(node, id:)
+          currency = node.dig("totals", "currency_code")
+          Portage::Ucp::Cart.new(
+            id: id,
+            line_items: (node["items"] || []).map { |n| cart_line_item(n, currency) },
+            currency: currency,
+            totals: totals(node["totals"] || {})
+          )
+        end
+
+        # `status` isn't a Store API cart field either — the Store API's
+        # cart *is* the checkout, same as Shopify's Cart-as-Checkout, so the
+        # adapter tracks status itself and passes it in here, same rationale
+        # as `id:` above.
+        def checkout(node, id:, status:, order: nil)
+          currency = node.dig("totals", "currency_code")
+          Portage::Ucp::Checkout.new(
+            id: id,
+            status: status,
+            line_items: (node["items"] || []).map { |n| cart_line_item(n, currency) },
+            currency: currency,
+            totals: totals(node["totals"] || {}),
+            links: [],
+            order: order
+          )
+        end
+
+        def cart_line_item(node, _currency)
+          unit_price = minor_units_from_subunits(node.dig("prices", "price"), node.dig("prices", "currency_minor_unit"))
+          line_total = unit_price * node["quantity"]
+          Portage::Ucp::LineItem.new(
+            id: node["key"],
+            item: Portage::Ucp::Item.new(id: node["id"].to_s, title: node["name"], price: unit_price,
+                                         image_url: node.dig("images", 0, "thumbnail")),
+            quantity: node["quantity"],
+            totals: Portage::Ucp::Support::Totals.line(line_total)
+          )
+        end
+
+        # Store API money fields are already minor-unit integers as strings
+        # (e.g. "500" for $5.00), tagged with `currency_minor_unit` (usually
+        # 2) — unlike the Admin API's decimal strings, there's no BigDecimal
+        # conversion needed here, just an integer parse.
+        def minor_units_from_subunits(amount, _minor_unit)
+          Portage::Ucp::Support::Amounts.subunits_to_minor(amount)
+        end
+
+        def totals(node)
+          Portage::Ucp::Support::Totals.summary(
+            subtotal: minor_units_from_subunits(node["total_items"], nil),
+            tax: minor_units_from_subunits(node["total_tax"], nil),
+            total: minor_units_from_subunits(node["total_price"], nil)
+          )
+        end
+
+        # WooCommerce core has no per-line-item fulfillment tracking (that's
+        # a shipment-tracking-plugin concern) — every line is given the same
+        # coarse status derived from the order's own top-level `status`,
+        # rather than a real per-line signal.
+        ORDER_LINE_ITEM_STATUS = {
+          "completed" => "fulfilled", "processing" => "processing", "pending" => "processing",
+          "on-hold" => "processing", "cancelled" => "removed", "refunded" => "removed", "failed" => "removed"
+        }.freeze
+
+        # `permalink_url` is built from WooCommerce's documented order-
+        # received URL pattern (`/checkout/order-received/{id}/?key={key}`)
+        # — the Admin order resource doesn't return a ready-made link the
+        # way Shopify's `statusPageUrl` does. `checkout_id` isn't a WC order
+        # field at all — nothing on Order links back to the Cart-Token that
+        # produced it, so the Adapter resolves it itself (tracked in-process
+        # from the #complete_checkout call that created the order, since the
+        # Store API's checkout response hands back the new order id right
+        # then) and passes it in here, same as Shopify's Mapper.order.
+        def order(node, site_url:, checkout_id: "")
+          currency = node["currency"]
+          subtotal = minor_units(node["total"]) - minor_units(node["total_tax"])
+          status = Portage::Ucp::Support::LineItemStatus.from_table(ORDER_LINE_ITEM_STATUS, node["status"])
+          Portage::Ucp::Order.new(
+            id: node["id"].to_s,
+            checkout_id: checkout_id,
+            permalink_url: "#{site_url}/checkout/order-received/#{node['id']}/?key=#{node['order_key']}",
+            line_items: (node["line_items"] || []).map { |n| order_line_item(n, currency, status) },
+            fulfillment: Portage::Ucp::Fulfillment.new,
+            currency: currency,
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal, total: minor_units(node["total"]))
+          )
+        end
+
+        def order_line_item(node, currency, status)
+          quantity = node["quantity"]
+          fulfilled = Portage::Ucp::Support::LineItemStatus.fulfilled_quantity(status, quantity)
+          line_total = minor_units(node["total"])
+          Portage::Ucp::OrderLineItem.new(
+            id: node["id"].to_s,
+            item: Portage::Ucp::Item.new(id: (node["variation_id"] || node["product_id"]).to_s, title: node["name"],
+                                         price: money(node["price"], currency).amount_minor),
+            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/woocommerce/version.rb

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

data/lib/portage/ucp/woocommerce.rb

@@ -0,0 +1,6 @@
+require "portage/ucp"
+require_relative "woocommerce/version"
+require_relative "woocommerce/errors"
+require_relative "woocommerce/client"
+require_relative "woocommerce/mapper"
+require_relative "woocommerce/adapter"

metadata

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