portage-ucp-wix 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3982d49401e0956a0ab63673941a7b943868d1ce104224e78b057b62b5befde
+  data.tar.gz: 6a0e9017b011b1f3b1182857865ad926a3e3839c09afd7fdb215eec8d3cbf843
+SHA512:
+  metadata.gz: 75d3d83ea3bc81837f7ada0d3513faa85b1a37f878e99af219b291d3a8fc83482379d6116863f54b17ae8f14e0fe049651eb641159bbb73c0c17a1bab2d4398c
+  data.tar.gz: '008f09ea6d0e5da325ba2aa847f0604ef662c672ed60dceb4a6d964eba2c655bcd54bc43a31b92177373a03e63493ef03f168a4c173b272afa50b779a078db65'

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. Wix adapter against the Stores (catalog) and eCommerce
+  (cart, checkout, order) REST 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,129 @@
+# portage-ucp-wix
+
+Wix adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::Adapter` against Wix's Stores (catalog) and eCommerce (cart, checkout, order) REST APIs. Generic only — no merchant-specific business logic. Plain `Net::HTTP`, no Wix SDK runtime dependency.
+
+## What it covers
+
+| UCP capability | Backing Wix API | Notes |
+|---|---|---|
+| `dev.ucp.shopping.catalog` | Stores Catalog V1 | `search_catalog`, `get_product` |
+| `dev.ucp.shopping.cart` | eCommerce Carts | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
+| `dev.ucp.shopping.checkout` | eCommerce Checkouts | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
+| `dev.ucp.shopping.order` | eCommerce Orders | `get_order` |
+| `dev.ucp.shopping.identity` | — | not implemented; Wix Members/visitor OAuth is a separate concern from the site-level app auth used here |
+
+Unlike Shopify, Wix models Cart and Checkout as genuinely separate resources, and a Wix Order links back to its originating Checkout natively via `checkoutId` — no cart-token reconciliation search needed for `Order#checkout_id`.
+
+Update/replace operations (`update_cart`, `update_checkout`) are full-replacement: Wix's add/remove-line-items endpoints aren't an 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.
+
+## ⚠️ Unverified against a live site
+
+This adapter is built from Wix's documented REST API shapes but hasn't been run against a real Wix site. Before relying on it in production, confirm:
+
+- **Catalog shape** — targets Stores Catalog **V1** (`priceData`, `stock`, `productPageUrl`, variant `choices`), not V3. If your site's app only has V3 access, `Mapper.product`/`.variant` need rewriting against V3's shape.
+- **`#complete_checkout`** — calls Wix's `create-order` endpoint bare. Wix's documented flow expects payment to already be authorized through a connected payment provider (Wix Payments or a PSP) before an order is created; there's no confirmed Wix equivalent of Shopify's `cartPaymentUpdate` that accepts an arbitrary single-use token. `payment_token` is accepted for interface parity with other `Portage::Ucp` adapters but currently isn't sent anywhere — wiring real payment capture needs confirming against a live site with a configured payment provider.
+- **Order fulfillment** — Wix order line items only expose a coarse `fulfillmentStatus` (not/partially/fully fulfilled quantities); `Order#fulfillment` is left as `{}` since real per-shipment tracking would need Wix's separate Fulfillments API, which isn't wired up here.
+- **`Order#permalink_url`** — left blank; Wix's Orders API doesn't return a public order-status page URL.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-wix"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+You need a single site-scoped access token — unlike Shopify's split Admin/Storefront tokens, Wix's REST surface sits behind one token, already scoped to a site.
+
+```ruby
+require "portage/ucp/wix"
+
+client = Portage::Ucp::Wix::Client.new(access_token: ENV.fetch("WIX_ACCESS_TOKEN"))
+adapter = Portage::Ucp::Wix::Adapter.new(client: client)
+```
+
+### Fetching an access token from an app's client credentials
+
+```ruby
+fetcher = Portage::Ucp::Wix::AccessTokenFetcher.new(
+  client_id: ENV.fetch("WIX_CLIENT_ID"),
+  client_secret: ENV.fetch("WIX_CLIENT_SECRET"),
+  instance_id: ENV.fetch("WIX_INSTANCE_ID")
+)
+
+result = fetcher.fetch
+result.access_token # => 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
+```
+
+## 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::Wix::Error    # base class
+Portage::Ucp::Wix::ApiError # any non-2xx Wix REST response (bad auth, malformed request, business rejection)
+```
+
+## Development
+
+```bash
+bundle exec rspec   # tests (WebMock-stubbed, no live site needed)
+bundle exec rubocop  # lint
+
+# fetch a real access_token for a dev site, via client_credentials
+WIX_CLIENT_ID=... WIX_CLIENT_SECRET=... WIX_INSTANCE_ID=... \
+  bundle exec rake wix_access_token
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-wix

@@ -0,0 +1,24 @@
+#!/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 WIX_ACCESS_TOKEN is read here, not client_id/client_secret/
+# instance_id: this exe expects a site-scoped token you've already fetched
+# (e.g. via `bundle exec rake wix_access_token`) and refresh out-of-band,
+# same as any other long-lived process holding a token with an expiry.
+
+require "portage/ucp"
+require "portage/ucp/wix"
+
+require ENV["PORTAGE_UCP_CONFIG"] if ENV["PORTAGE_UCP_CONFIG"]
+
+client = Portage::Ucp::Wix::Client.new(access_token: ENV.fetch("WIX_ACCESS_TOKEN"))
+adapter = Portage::Ucp::Wix::Adapter.new(client: client)
+
+Portage::Ucp::Mcp::Server.build(adapter: adapter).start

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

@@ -0,0 +1,42 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Wix
+      # Exchanges a Wix app's client_id/client_secret (plus the target site's
+      # instance_id) for a site-scoped access token via Wix's OAuth
+      # client_credentials grant.
+      #
+      # Wix apps authenticate server-to-server the same way Shopify custom
+      # apps now do: no static, copy-once token — client_id/client_secret get
+      # exchanged (and re-exchanged once expired) for the real access_token
+      # used by Portage::Ucp::Wix::Client. The one addition versus Shopify is
+      # `instance_id`: Wix's OAuth endpoint is one shared host
+      # (www.wixapis.com) serving every site, so the token has to be scoped
+      # to a specific site's app instance at exchange time rather than via a
+      # per-shop subdomain.
+      class AccessTokenFetcher
+        include Portage::Ucp::Support::TokenExchange
+
+        Result = Struct.new(:access_token, :expires_in, keyword_init: true)
+
+        ENDPOINT = "https://www.wixapis.com/oauth2/token".freeze
+
+        def initialize(client_id:, client_secret:, instance_id:)
+          @client_id = client_id
+          @client_secret = client_secret
+          @instance_id = instance_id
+        end
+
+        def fetch
+          body = exchange(ENDPOINT,
+                          { grant_type: "client_credentials", client_id: @client_id,
+                            client_secret: @client_secret, instance_id: @instance_id },
+                          error_class: Portage::Ucp::Wix::Error)
+          Result.new(access_token: body["access_token"], expires_in: body["expires_in"])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+require "json"
+
+module Portage
+  module Ucp
+    module Wix
+      # Generic Portage::Ucp::Adapter over Wix's Stores (catalog) and
+      # eCommerce (cart/checkout/order) REST APIs — no merchant-specific
+      # business logic, same posture as Portage::Ucp::Shopify::Adapter.
+      #
+      # Deliberately doesn't override `link_identity`: Wix's OAuth identity
+      # story (Wix Members/visitor auth) is a separate concern from the
+      # site-level app auth this gem uses for catalog/cart/checkout/order, so
+      # this generic adapter leaves it unimplemented — Capability#
+      # advertised_for? simply won't advertise dev.ucp.shopping.identity for
+      # this adapter, not a 500.
+      #
+      # Unlike Shopify, where Cart and Checkout are the same underlying
+      # object, Wix models them as genuinely separate resources with their
+      # own REST endpoints — so, unlike Shopify's Adapter, there's no shared
+      # create_cart_node/create_checkout_node plumbing between the two.
+      #
+      # IMPORTANT CAVEAT: #complete_checkout's call to Wix's "Create Order"
+      # endpoint hasn't been confirmed against a live site. Wix's documented
+      # checkout flow expects payment to already be authorized through a
+      # payment provider (Wix Payments or a connected PSP) before an order
+      # is created — there's no confirmed equivalent of Shopify's
+      # cartPaymentUpdate that accepts an arbitrary single-use payment_token
+      # directly. `payment_token` is accepted for interface parity with the
+      # other Portage::Ucp adapters but isn't currently sent anywhere; wiring
+      # real payment capture needs confirming against a live Wix site with a
+      # configured payment provider before this method is production-ready.
+      class Adapter < Portage::Ucp::Adapter
+        # Wix's fixed app id for its own Stores catalog, required on every
+        # cart/checkout line item's catalogReference so Wix knows which
+        # catalog `catalogItemId` belongs to.
+        STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e".freeze
+
+        # Wix's cart/checkout REST endpoints don't take an idempotency key
+        # natively, so §9a dedup comes from Support::Idempotency's in-process
+        # table.
+        include Portage::Ucp::Support::Idempotency
+        # Wix Checkout has no confirmed native status field, so status is
+        # tracked adapter-side via Support::CheckoutState. Only the status
+        # half is used here: unlike Shopify and WooCommerce, a Wix Order
+        # carries its originating `checkoutId` natively (see #get_order).
+        include Portage::Ucp::Support::CheckoutState
+
+        def initialize(client:)
+          super()
+          @client = client
+        end
+
+        def search_catalog(query:, limit:)
+          body = { query: { filter: JSON.generate({ name: { "$contains" => query } }), paging: { limit: limit } } }
+          data = @client.post("/stores/v1/products/query", body)
+          (data["products"] || []).map { |node| Mapper.product(node) }
+        end
+
+        def get_product(product_id:)
+          node = @client.get("/stores/v1/products/#{product_id}")["product"]
+          node && Mapper.product(node)
+        end
+
+        def get_cart(cart_id:)
+          node = fetch_cart_node(cart_id)
+          node && Mapper.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: this removes
+        # every current line then adds the desired ones back, same as
+        # Portage::Ucp::Shopify::Adapter#update_cart (Wix's add/remove-line-
+        # items endpoints aren't an atomic "replace all lines" either).
+        def update_cart(cart_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(replace_cart_lines(cart_id, line_items)) }
+        end
+
+        # Wix carts can actually be deleted (unlike Shopify's, which just
+        # expire) — this deletes the cart, then returns its last-known state
+        # since there's nothing more to hand back once it's gone.
+        def cancel_cart(cart_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            node = fetch_cart_node(cart_id)
+            @client.delete("/ecom/v1/carts/#{cart_id}")
+            Mapper.cart(node)
+          end
+        end
+
+        def create_checkout(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            node = create_checkout_node(line_items)
+            record_checkout_status(node["id"], "incomplete")
+            Mapper.checkout(node, status: "incomplete")
+          end
+        end
+
+        def get_checkout(checkout_id:)
+          node = fetch_checkout_node(checkout_id)
+          node && Mapper.checkout(node, 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 = @client.patch("/ecom/v1/checkouts/#{checkout_id}", { lineItems: cart_lines(line_items) })["checkout"]
+            record_checkout_status(checkout_id, "incomplete")
+            Mapper.checkout(node, status: "incomplete")
+          end
+        end
+
+        # See the class-level CAVEAT: payment_token isn't currently sent to
+        # Wix — see this method's implementation note below.
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key:)
+          dedup(idempotency_key) { submit_order(checkout_id, payment_token) }
+        end
+
+        def cancel_checkout(checkout_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            record_checkout_status(checkout_id, "canceled")
+            node = fetch_checkout_node(checkout_id)
+            Mapper.checkout(node, status: "canceled")
+          end
+        end
+
+        # `checkout_id` comes straight off the Wix Order's own `checkoutId`
+        # field — unlike Shopify, Wix's Order object links back to its
+        # originating Checkout natively, so there's no cart_token-style
+        # reconciliation search needed here.
+        def get_order(order_id:)
+          node = @client.get("/ecom/v1/orders/#{order_id}")["order"]
+          node && Mapper.order(node)
+        end
+
+        private
+
+        def fetch_cart_node(cart_id)
+          @client.get("/ecom/v1/carts/#{cart_id}")["cart"]
+        end
+
+        def fetch_checkout_node(checkout_id)
+          @client.get("/ecom/v1/checkouts/#{checkout_id}")["checkout"]
+        end
+
+        def cart_lines(line_items)
+          line_items.map do |li|
+            { catalogReference: { catalogItemId: li[:product_id], appId: STORES_APP_ID },
+              quantity: li[:quantity] }
+          end
+        end
+
+        def create_cart_node(line_items)
+          @client.post("/ecom/v1/carts", { lineItems: cart_lines(line_items) })["cart"]
+        end
+
+        def create_checkout_node(line_items)
+          @client.post("/ecom/v1/checkouts", { lineItems: cart_lines(line_items) })["checkout"]
+        end
+
+        def replace_cart_lines(cart_id, line_items)
+          current_ids = fetch_cart_node(cart_id)["lineItems"].map { |n| n["id"] }
+          unless current_ids.empty?
+            @client.post("/ecom/v1/carts/#{cart_id}/remove-line-items", { lineItemIds: current_ids })
+          end
+          return fetch_cart_node(cart_id) if line_items.empty?
+
+          @client.post("/ecom/v1/carts/#{cart_id}/add-line-items", { lineItems: cart_lines(line_items) })["cart"]
+        end
+
+        # `payment_token` is deliberately not sent anywhere yet — see the
+        # class-level CAVEAT. `create-order` is called bare; a checkout that
+        # hasn't actually been paid through a real Wix payment provider will
+        # be rejected by Wix itself here, surfacing as an ApiError rather
+        # than silently succeeding.
+        def submit_order(checkout_id, _payment_token)
+          node = fetch_checkout_node(checkout_id)
+          raise Portage::Ucp::Wix::Error, "checkout #{checkout_id} not found" unless node
+
+          data = @client.post("/ecom/v1/checkouts/#{checkout_id}/create-order", {})
+          order_id = data["orderId"]
+          status = order_id ? "completed" : "complete_in_progress"
+          record_checkout_status(checkout_id, status)
+          # Same "not information-complete but schema-valid" posture as
+          # Mapper.order's own blank permalink_url — Wix's create-order
+          # response has no storefront order-status link to hand back.
+          order = order_id && Portage::Ucp::OrderConfirmation.new(id: order_id, permalink_url: "")
+          Mapper.checkout(node, status: status, order: order)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module Wix
+      # Minimal REST client over the Wix APIs (www.wixapis.com).
+      #
+      # Deliberately plain Net::HTTP, not the `wix-ruby-sdk` (there isn't a
+      # first-party one) — a generic adapter that any Ruby app can drop in
+      # only needs one bearer-style access token and a handful of JSON
+      # endpoints, no framework coupling, trivially stubbable with WebMock.
+      #
+      # Unlike Shopify's split Admin/Storefront APIs with separate tokens,
+      # Wix's REST surface (Stores catalog, eCommerce carts/checkouts/orders)
+      # is a single API behind one access token — an app's client_credentials
+      # token is already scoped to one site via `instance_id` at fetch time
+      # (see Portage::Ucp::Wix::AccessTokenFetcher), so there's nothing here
+      # analogous to Shopify's per-call token selection.
+      class Client
+        include Portage::Ucp::Support::HttpClient
+
+        BASE_URL = "https://www.wixapis.com".freeze
+
+        def initialize(access_token:)
+          @access_token = access_token
+        end
+
+        def get(path)
+          request(Net::HTTP::Get, path)
+        end
+
+        def post(path, body = {})
+          request(Net::HTTP::Post, path, body)
+        end
+
+        def patch(path, body = {})
+          request(Net::HTTP::Patch, path, body)
+        end
+
+        def delete(path)
+          request(Net::HTTP::Delete, path)
+        end
+
+        private
+
+        def request(http_method, path, body = nil)
+          json_request(http_method, "#{BASE_URL}#{path}", body: body,
+                                                          headers: { "Authorization" => @access_token })
+        end
+
+        def api_error_class = Portage::Ucp::Wix::ApiError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Portage
+  module Ucp
+    module Wix
+      class Error < StandardError; end
+
+      # Raised for any non-2xx response from a Wix REST call. Unlike Shopify's
+      # GraphQL/userErrors split, Wix's REST APIs report both transport-level
+      # rejections (bad auth, malformed request) and business rejections
+      # (e.g. "line item not found") the same way — a non-2xx status with a
+      # JSON error body — so one error class covers both.
+      class ApiError < Error
+        include Portage::Ucp::Support::ApiError
+
+        private
+
+        def detail(body)
+          body["message"] || body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+module Portage
+  module Ucp
+    module Wix
+      # Converts Wix Stores/eCommerce REST response bodies into the
+      # protocol-layer value objects from Portage::Ucp::ValueObjects
+      # (Product/Cart/LineItem/Checkout/Order/Money) — nothing Wix-shaped is
+      # allowed to leak past this file.
+      #
+      # Targets the Wix Stores Catalog V1 product shape (`priceData`,
+      # `stock`, `productPageUrl`) rather than V3 — V1's fields are the
+      # stable, longer-documented ones. A merchant on V3-only endpoints would
+      # need their own Mapper.
+      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 product(node)
+          currency = node.dig("priceData", "currency")
+          Portage::Ucp::Product.new(
+            id: node["id"],
+            title: node["name"],
+            description: node["description"],
+            price: money(node.dig("priceData", "price"), currency),
+            available: node.dig("stock", "inStock") != false,
+            variants: (node["variants"] || []).map { |v| variant(v, node["name"], currency) },
+            url: product_url(node["productPageUrl"])
+          )
+        end
+
+        def product_url(page)
+          return nil unless page && page["base"]
+
+          "#{page['base']}#{page['path']}"
+        end
+
+        # A V1 variant's own identity is its `choices` (e.g. {"Size"=>"Large"})
+        # — there's no separate variant title field, so one is built from the
+        # choice values, falling back to the parent product's title for a
+        # single-variant (no options) product.
+        def variant(node, product_title, currency)
+          choices = node["choices"] || {}
+          title = choices.values.join(" / ")
+          title = product_title if title.empty?
+          { id: node["id"], title: title, available: node.dig("stock", "inStock") != false,
+            price: money(node.dig("variant", "priceData", "price"), currency) }
+        end
+
+        def cart(node)
+          Portage::Ucp::Cart.new(
+            id: node["id"],
+            line_items: (node["lineItems"] || []).map { |n| line_item(n) },
+            currency: node["currency"],
+            totals: totals(node["priceSummary"] || {})
+          )
+        end
+
+        # `status` isn't reliably present on a Wix Checkout the way it is on
+        # a Shopify Cart/Checkout hybrid — the adapter tracks it itself
+        # across the create/update/complete/cancel lifecycle and passes it
+        # in here, same rationale as Shopify's Mapper.checkout.
+        def checkout(node, status:, order: nil)
+          Portage::Ucp::Checkout.new(
+            id: node["id"],
+            status: status,
+            line_items: (node["lineItems"] || []).map { |n| line_item(n) },
+            currency: node["currency"],
+            totals: totals(node["priceSummary"] || {}),
+            links: [],
+            order: order
+          )
+        end
+
+        # Shared by Cart and Checkout line items — both are Wix `lineItem`
+        # shapes with the same fields. There's no documented per-line total
+        # field (only a per-cart/checkout `priceSummary` aggregate), so the
+        # line total is unit price * quantity, same as Shopify's variant
+        # price * quantity for a line with no discounts applied.
+        def line_item(node)
+          unit_price = minor_units(node.dig("price", "amount"))
+          quantity = node["quantity"]
+          line_total = unit_price * quantity
+          Portage::Ucp::LineItem.new(
+            id: node["id"],
+            item: Portage::Ucp::Item.new(id: node.dig("catalogReference", "catalogItemId"),
+                                         title: node.dig("productName", "original"), price: unit_price),
+            quantity: quantity,
+            totals: Portage::Ucp::Support::Totals.line(line_total)
+          )
+        end
+
+        # Builds the top-level totals array from Wix's priceSummary.
+        def totals(summary)
+          Portage::Ucp::Support::Totals.summary(subtotal: minor_units(summary.dig("subtotal", "amount")),
+                                                tax: minor_units(summary.dig("tax", "amount")),
+                                                total: minor_units(summary.dig("total", "amount")))
+        end
+
+        # Wix Order line items carry their own coarse fulfillmentStatus
+        # (NOT_FULFILLED/PARTIALLY_FULFILLED/FULFILLED/CANCELED) rather than
+        # Shopify's separate quantity/unfulfilledQuantity counters, so exact
+        # partial-fulfillment quantities aren't derivable from the Orders API
+        # alone (Wix's separate Fulfillments API has those, and isn't wired
+        # up here) — `fulfilled` is a best-effort all-or-nothing based on
+        # that status.
+        ORDER_LINE_ITEM_STATUS = {
+          "FULFILLED" => "fulfilled", "CANCELED" => "removed",
+          "PARTIALLY_FULFILLED" => "partial", "NOT_FULFILLED" => "processing"
+        }.freeze
+
+        # `permalink_url` is left blank — Wix's Orders API doesn't return a
+        # public order-status page URL (that's rendered on the buyer's Thank
+        # You page client-side, not exposed via this API).
+        def order(node)
+          subtotal_amount = minor_units(node.dig("priceSummary", "subtotal", "amount"))
+          total_amount = minor_units(node.dig("priceSummary", "total", "amount"))
+          Portage::Ucp::Order.new(
+            id: node["id"],
+            checkout_id: node["checkoutId"] || "",
+            permalink_url: "",
+            line_items: (node["lineItems"] || []).map { |n| order_line_item(n) },
+            fulfillment: Portage::Ucp::Fulfillment.new,
+            currency: node["currency"],
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal_amount, total: total_amount)
+          )
+        end
+
+        def order_line_item(node)
+          quantity = node["quantity"]
+          status = Portage::Ucp::Support::LineItemStatus.from_table(ORDER_LINE_ITEM_STATUS, node["fulfillmentStatus"])
+          fulfilled = Portage::Ucp::Support::LineItemStatus.fulfilled_quantity(status, quantity)
+          unit_price = minor_units(node.dig("price", "amount"))
+          line_total = unit_price * quantity
+          Portage::Ucp::OrderLineItem.new(
+            id: node["id"],
+            item: Portage::Ucp::Item.new(id: node.dig("catalogReference", "catalogItemId"),
+                                         title: node.dig("productName", "original"), price: unit_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/wix/version.rb

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

data/lib/portage/ucp/wix.rb

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

metadata

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