portage-ucp-bigcommerce 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 825aa48c9aba12a11801d6512c4400019a727fc6f0d76c4dd6073f16e7c81482
+  data.tar.gz: 8a710386fdfe7d542f6a22d8c5c3a518541f8a19a68149283eac96d77ddf440d
+SHA512:
+  metadata.gz: cd5bd467d2c454680e20e943b2a7095df5ede07fa6a9c6fbbd1a7641e7319faf2bc8386b902e7d6c2cbe0238dc858beb6aa1af7bfb7df346c46016afc96c4d73
+  data.tar.gz: a6f1a7a5cab4ba465b5602669646cbb74c86f55ed1bc0a4c8a9de4ee0f2c47fc8352f5ea7e6145ad5659e4b2c1827429815b180948fda66473873367b64fff4f

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. BigCommerce adapter against the v3 Catalog/Carts/
+  Checkouts APIs and v2 Orders API.

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,126 @@
+# portage-ucp-bigcommerce
+
+BigCommerce adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::Adapter` against a BigCommerce store's v3 Catalog/Carts/Checkouts APIs and v2 Orders API. Generic only — no merchant-specific business logic. Plain `Net::HTTP`, no `bigcommerce_api` runtime dependency.
+
+## What it covers
+
+| UCP capability | Backing BigCommerce API | Notes |
+|---|---|---|
+| `dev.ucp.shopping.catalog` | v3 Catalog | `search_catalog`, `get_product` |
+| `dev.ucp.shopping.cart` | v3 Carts | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
+| `dev.ucp.shopping.checkout` | v3 Checkouts (shares its cart's id), plus Orders + Payments to complete | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
+| `dev.ucp.shopping.order` | v2 Orders | `get_order` |
+| `dev.ucp.shopping.identity` | — | not implemented; BigCommerce's storefront Customer Login API is a separate concern from the store-owner API account used here |
+
+Unlike Shopify/WooCommerce, BigCommerce's Checkout **is** a distinct resource from its Cart — but they share the same id, created together by a single `POST /carts` call. `update_cart`/`update_checkout` are full-replacement: the Carts API has no atomic "replace all lines" endpoint, so the adapter adds the desired lines *before* removing the old ones — BigCommerce auto-deletes a cart when its last remaining line item is removed, so removing old lines first would destroy the cart the call is supposed to be updating. `cancel_cart` deletes the cart resource outright (BigCommerce is the only one of the three adapters whose Carts API actually supports this). Mutating methods dedup by `idempotency_key` in-process so a dropped-connection retry can't double-charge.
+
+Unlike Shopify/Wix, there's no `AccessTokenFetcher` — a BigCommerce API account (Settings → API → Create API Account) hands back a static `client_id`/`access_token` pair with no expiry, same posture as `portage-ucp-woocommerce`. The separate OAuth authorization-code flow BigCommerce uses for public Marketplace apps is a different concern, out of scope here.
+
+## ⚠️ Unverified against a live store
+
+Built from BigCommerce's documented REST API shapes, not run against a real store yet. Before relying on this in production, confirm:
+
+- **`#complete_checkout`** — creates an order from the checkout, mints a single-order Payment Access Token, then submits `payment_token` as a tokenized instrument to the separate Payments API (`payments.bigcommerce.com`). The exact `payment_instrument` shape a given gateway expects (`payment_gateway_id:`) is gateway-specific and hasn't been confirmed against a live store with a real gateway installed.
+- **Cart/Checkout line item price fields** — `Mapper.cart_line_item` assumes plain decimal fields (`sale_price`, `extended_sale_price`); some BigCommerce API surfaces instead nest money under a `{value:, currency:}` sub-object.
+- **`Order#permalink_url`** — built from BigCommerce's documented storefront order-status route, not confirmed against a live storefront theme.
+- **Order fulfillment** — BigCommerce core has no per-line-item fulfillment tracking, so every order line is given the same coarse status derived from the order's own `status_id`, not a real per-line signal.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-ucp-bigcommerce"
+```
+
+```bash
+bundle install
+```
+
+## Setup
+
+You need your store hash (from the BigCommerce control panel URL or API path), and a client_id/access_token pair from an API account (Settings → API → Create API Account — grant the scopes you need for Products/Carts/Checkouts/Orders), your store's currency (the Catalog product resource doesn't return one), and — only if you'll call `complete_checkout` — the payment gateway id you want to submit orders through.
+
+```ruby
+require "portage/ucp/bigcommerce"
+
+client = Portage::Ucp::BigCommerce::Client.new(
+  store_hash: ENV.fetch("BIGCOMMERCE_STORE_HASH"),
+  client_id: ENV.fetch("BIGCOMMERCE_CLIENT_ID"),
+  access_token: ENV.fetch("BIGCOMMERCE_ACCESS_TOKEN")
+)
+
+adapter = Portage::Ucp::BigCommerce::Adapter.new(
+  client: client,
+  site_url: "https://your-shop.example.com",
+  currency: "USD",
+  payment_gateway_id: "stripe" # 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 comes back from the create response
+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 — shares the same id as the cart it was created from
+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::BigCommerce::Error    # base class
+Portage::Ucp::BigCommerce::ApiError # any non-2xx response from the Admin or Payments API
+```
+
+## Development
+
+```bash
+bundle exec rspec   # tests (WebMock-stubbed, no live store needed)
+bundle exec rubocop  # lint
+
+# verify a real store's client_id/access_token by listing one product
+BIGCOMMERCE_STORE_HASH=abc123 \
+BIGCOMMERCE_CLIENT_ID=... BIGCOMMERCE_ACCESS_TOKEN=... \
+  bundle exec rake bigcommerce_smoke_test
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage-ucp-bigcommerce

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Standalone MCP server over stdio. Configure the store 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.
+#
+# BIGCOMMERCE_PAYMENT_GATEWAY_ID is optional — only needed to call
+# #complete_checkout.
+
+require "portage/ucp"
+require "portage/ucp/bigcommerce"
+
+require ENV["PORTAGE_UCP_CONFIG"] if ENV["PORTAGE_UCP_CONFIG"]
+
+client = Portage::Ucp::BigCommerce::Client.new(
+  store_hash: ENV.fetch("BIGCOMMERCE_STORE_HASH"),
+  client_id: ENV.fetch("BIGCOMMERCE_CLIENT_ID"),
+  access_token: ENV.fetch("BIGCOMMERCE_ACCESS_TOKEN")
+)
+adapter = Portage::Ucp::BigCommerce::Adapter.new(
+  client: client,
+  site_url: ENV.fetch("BIGCOMMERCE_SITE_URL"),
+  currency: ENV.fetch("BIGCOMMERCE_CURRENCY", "USD"),
+  payment_gateway_id: ENV.fetch("BIGCOMMERCE_PAYMENT_GATEWAY_ID", nil)
+)
+
+Portage::Ucp::Mcp::Server.build(adapter: adapter).start

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

@@ -0,0 +1,224 @@
+require "uri"
+
+module Portage
+  module Ucp
+    module BigCommerce
+      # Generic Portage::Ucp::Adapter over a BigCommerce store's v3 Catalog/
+      # Carts/Checkouts APIs and v2 Orders API — no merchant-specific
+      # business logic, same posture as Portage::Ucp::Shopify::Adapter and
+      # Portage::Ucp::WooCommerce::Adapter.
+      #
+      # Deliberately doesn't override `link_identity`: BigCommerce's storefront
+      # customer login (JWT-based Customer Login API) is a separate concern
+      # from the store-owner API account 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 (v3 and v2
+      # respectively — Orders has never moved off v2). Cart and Checkout are
+      # read/written through the v3 Carts/Checkouts APIs: unlike Shopify/
+      # WooCommerce, BigCommerce's Checkout *is* a distinct resource from its
+      # Cart, but shares the same id — creating a Cart implicitly creates its
+      # matching Checkout.
+      #
+      # IMPORTANT CAVEAT: #complete_checkout creates an order from the
+      # checkout, mints a single-order Payment Access Token, then submits
+      # `payment_token` as a tokenized instrument to the separate Payments
+      # API (`payments.bigcommerce.com`). The exact `payment_instrument`
+      # shape a given payment gateway expects hasn't been confirmed against
+      # a live store with a real gateway installed — same "needs confirming
+      # against a live store" posture as Portage::Ucp::Shopify::Adapter and
+      # Portage::Ucp::WooCommerce::Adapter's own payment steps.
+      class Adapter < Portage::Ucp::Adapter
+        # Neither the Carts nor the Checkouts API takes an idempotency key
+        # natively, so §9a dedup comes from Support::Idempotency's in-process
+        # table.
+        include Portage::Ucp::Support::Idempotency
+        # BigCommerce's Checkout has no native status field of its own, and
+        # v2 Orders don't link back to the Checkout that produced them —
+        # both are tracked adapter-side via Support::CheckoutState, keyed by
+        # the shared cart/checkout id.
+        include Portage::Ucp::Support::CheckoutState
+        # The v3 and v2 APIs both answer a missing resource 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_gateway_id: nil)
+          super()
+          @client = client
+          @site_url = site_url.chomp("/")
+          @currency = currency
+          @payment_gateway_id = payment_gateway_id
+        end
+
+        def search_catalog(query:, limit:)
+          path = "/catalog/products?keyword=#{URI.encode_www_form_component(query)}&limit=#{limit}&include=variants"
+          @client.v3_get(path)["data"].map { |node| Mapper.product(node, currency: @currency, site_url: @site_url) }
+        end
+
+        def get_product(product_id:)
+          nil_on_not_found do
+            node = @client.v3_get("/catalog/products/#{product_id}?include=variants")["data"]
+            node && Mapper.product(node, currency: @currency, site_url: @site_url)
+          end
+        end
+
+        def get_cart(cart_id:)
+          nil_on_not_found do
+            node = fetch_cart_node(cart_id)
+            node && Mapper.cart(node, id: cart_id)
+          end
+        end
+
+        def create_cart(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            node = @client.v3_post("/carts", { line_items: cart_lines(line_items) })["data"]
+            Mapper.cart(node, id: node["id"])
+          end
+        end
+
+        # Full replacement, matching UCP's real cart semantics: the Carts API
+        # has no atomic "replace all lines" endpoint either. New lines are
+        # added *before* the old ones are removed — BigCommerce auto-deletes
+        # the whole cart when its last remaining line item is removed, so
+        # removing old lines first (when the desired list is non-empty)
+        # would destroy the cart this call is supposed to be updating.
+        def update_cart(cart_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) { Mapper.cart(replace_cart_lines(cart_id, line_items), id: cart_id) }
+        end
+
+        # Unlike Shopify (no cancellation mutation at all) and WooCommerce
+        # (only a session cart to clear), BigCommerce's Carts API supports
+        # deleting the cart resource outright — the closest real equivalent
+        # to cancellation available on any of the three. The returned Cart
+        # reflects that the resource is now gone (empty line_items, no
+        # currency) rather than raising: schema-valid, just not information-
+        # complete, same posture as
+        # Portage::Ucp::Shopify::Adapter#link_cart_to_order's best-effort miss.
+        def cancel_cart(cart_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            delete_cart(cart_id)
+            Mapper.cart({}, id: cart_id)
+          end
+        end
+
+        def create_checkout(line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            cart_node = @client.v3_post("/carts", { line_items: cart_lines(line_items) })["data"]
+            record_checkout_status(cart_node["id"], "incomplete")
+            Mapper.checkout(fetch_checkout_node(cart_node["id"]), id: cart_node["id"], status: "incomplete")
+          end
+        end
+
+        def get_checkout(checkout_id:)
+          nil_on_not_found do
+            node = fetch_checkout_node(checkout_id)
+            node && Mapper.checkout(node, id: checkout_id, status: checkout_status(checkout_id))
+          end
+        end
+
+        # Full replacement, same rationale as #update_cart — BigCommerce's
+        # Checkout shares its underlying cart with #update_cart.
+        def update_checkout(checkout_id:, line_items:, idempotency_key:)
+          dedup(idempotency_key) do
+            replace_cart_lines(checkout_id, line_items)
+            record_checkout_status(checkout_id, "incomplete")
+            Mapper.checkout(fetch_checkout_node(checkout_id), 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 Checkouts API has no cancellation endpoint for an in-progress
+        # checkout either (see #cancel_cart's contrast) — this just marks the
+        # tracked status canceled without touching the underlying cart.
+        def cancel_checkout(checkout_id:, idempotency_key:)
+          dedup(idempotency_key) do
+            record_checkout_status(checkout_id, "canceled")
+            Mapper.checkout(fetch_checkout_node(checkout_id), id: checkout_id, status: "canceled")
+          end
+        end
+
+        def get_order(order_id:)
+          nil_on_not_found do
+            node = @client.v2_get("/orders/#{order_id}")
+            next nil unless node["id"]
+
+            products = @client.v2_get("/orders/#{order_id}/products")
+            Mapper.order(node, products: products, site_url: @site_url,
+                               checkout_id: checkout_id_for(order_id))
+          end
+        end
+
+        private
+
+        def fetch_cart_node(cart_id)
+          include_param = "line_items.physical_items.options,line_items.digital_items.options"
+          @client.v3_get("/carts/#{cart_id}?include=#{include_param}")["data"]
+        end
+
+        def fetch_checkout_node(checkout_id)
+          @client.v3_get("/checkouts/#{checkout_id}")["data"]
+        end
+
+        def delete_cart(cart_id)
+          nil_on_not_found { @client.v3_delete("/carts/#{cart_id}") }
+        end
+
+        # Maps a UCP line item request straight to `{product_id, quantity}`.
+        # A real variant-level add needs `{product_id, variant_id}` together
+        # — this generic adapter, same as
+        # Portage::Ucp::WooCommerce::Adapter#cart_lines, assumes the given id
+        # already identifies the exact sellable unit and doesn't attempt to
+        # split it back into a product/variant pair.
+        def cart_lines(line_items)
+          line_items.map { |li| { product_id: li[:product_id].to_i, quantity: li[:quantity] } }
+        end
+
+        def cart_item_ids(node)
+          ((node.dig("line_items", "physical_items") || []) + (node.dig("line_items", "digital_items") || []))
+            .map { |item| item["id"] }
+        end
+
+        def replace_cart_lines(cart_id, line_items)
+          current_item_ids = cart_item_ids(fetch_cart_node(cart_id))
+          @client.v3_post("/carts/#{cart_id}/items", { line_items: cart_lines(line_items) }) unless line_items.empty?
+          current_item_ids.each { |item_id| @client.v3_delete("/carts/#{cart_id}/items/#{item_id}") }
+          return {} if line_items.empty?
+
+          fetch_cart_node(cart_id)
+        end
+
+        # See the class-level CAVEAT: `payment_instrument` uses a single
+        # configurable gateway id (`payment_gateway_id:`) rather than a
+        # confirmed gateway-specific instrument shape.
+        def submit_checkout(checkout_id, payment_token)
+          unless @payment_gateway_id
+            raise Portage::Ucp::BigCommerce::Error,
+                  "no payment_gateway_id configured on this Adapter"
+          end
+
+          checkout_node = fetch_checkout_node(checkout_id)
+          order_id = @client.v3_post("/checkouts/#{checkout_id}/orders", {}).dig("data", "id")
+          access_token = @client.v3_post("/payments/access_tokens", { order: { id: order_id } }).dig("data", "id")
+          @client.process_payment(payment_access_token: access_token, order_id: order_id,
+                                  payment_instrument: { type: "tokenized_instrument", token: payment_token,
+                                                        gateway: @payment_gateway_id })
+
+          record_checkout_status(checkout_id, "completed")
+          record_order_checkout(order_id, checkout_id)
+          Mapper.checkout(checkout_node, id: checkout_id, status: "completed", order: order_confirmation(order_id))
+        end
+
+        # Same order-status URL pattern as Mapper.order's `permalink_url`.
+        def order_confirmation(order_id)
+          Portage::Ucp::OrderConfirmation.new(
+            id: order_id.to_s, permalink_url: "#{@site_url}/account.php?action=order_status&order_id=#{order_id}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+require "net/http"
+require "json"
+
+module Portage
+  module Ucp
+    module BigCommerce
+      # Minimal REST client over a BigCommerce store's Admin APIs.
+      #
+      # Deliberately plain Net::HTTP, not the `bigcommerce_api` gem — a
+      # generic adapter that any Ruby app can drop in only needs a store hash
+      # and a pair of static API account credentials, no framework coupling,
+      # trivially stubbable with WebMock.
+      #
+      # Unlike Shopify/Wix, there's no Portage::Ucp::BigCommerce::AccessTokenFetcher:
+      # a store-owner-created API account (Settings → API → Create API Account)
+      # hands back a client_id/access_token pair with no expiry, same static-
+      # credential posture as Portage::Ucp::WooCommerce::Client. The separate
+      # OAuth authorization-code flow BigCommerce uses for public Marketplace
+      # apps is a different concern, out of scope here.
+      #
+      # BigCommerce splits its Admin surface across two API generations under
+      # the same host: catalog/carts/checkouts live on v3, Orders is still v2
+      # only — both are exposed here rather than picking one.
+      #
+      # Completing a checkout also requires the separate Payments API, which
+      # lives on a *different* host (`payments.bigcommerce.com`) and is
+      # authorized with a short-lived payment access token rather than the
+      # store's own API credentials — see #process_payment.
+      class Client
+        include Portage::Ucp::Support::HttpClient
+
+        def initialize(store_hash:, client_id:, access_token:)
+          @store_hash = store_hash
+          @client_id = client_id
+          @access_token = access_token
+        end
+
+        def v2_get(path)
+          admin_request(Net::HTTP::Get, "v2", path)
+        end
+
+        def v2_post(path, body = {})
+          admin_request(Net::HTTP::Post, "v2", path, body)
+        end
+
+        def v3_get(path)
+          admin_request(Net::HTTP::Get, "v3", path)
+        end
+
+        def v3_post(path, body = {})
+          admin_request(Net::HTTP::Post, "v3", path, body)
+        end
+
+        def v3_put(path, body = {})
+          admin_request(Net::HTTP::Put, "v3", path, body)
+        end
+
+        def v3_delete(path)
+          admin_request(Net::HTTP::Delete, "v3", path)
+        end
+
+        # Authorized with the payment access token minted by
+        # POST /v3/payments/access_tokens (see Adapter#submit_checkout), not
+        # the store's own client_id/access_token — BigCommerce scopes a
+        # payment token to a single order for a single completion attempt.
+        def process_payment(payment_access_token:, order_id:, payment_instrument:)
+          json_request(
+            Net::HTTP::Post, "https://payments.bigcommerce.com/stores/#{@store_hash}/payments",
+            body: { payment: { instrument: payment_instrument }, order: { id: order_id } },
+            headers: { "Authorization" => payment_access_token,
+                       "Content-Type" => "application/vnd.bc.payments.v1+json",
+                       "Accept" => "application/vnd.bc.payments.v1+json" }
+          )
+        end
+
+        private
+
+        def admin_request(http_method, version, path, body = nil)
+          json_request(http_method, "https://api.bigcommerce.com/stores/#{@store_hash}/#{version}#{path}",
+                       body: body,
+                       headers: { "X-Auth-Client" => @client_id, "X-Auth-Token" => @access_token,
+                                  "Accept" => "application/json" })
+        end
+
+        def api_error_class = Portage::Ucp::BigCommerce::ApiError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Portage
+  module Ucp
+    module BigCommerce
+      class Error < StandardError; end
+
+      # Raised for any non-2xx response from the Admin API (v2 Orders, v3
+      # Catalog/Carts/Checkouts) or the Payments API. BigCommerce's error body
+      # shape isn't uniform across API generations — v3 responses carry a
+      # `title`, v2 responses (and some v3 validation failures) carry an
+      # `errors` array/hash instead — so this tries both rather than assuming
+      # one.
+      class ApiError < Error
+        include Portage::Ucp::Support::ApiError
+
+        private
+
+        def detail(body)
+          body["title"] || body["errors"] || body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,175 @@
+module Portage
+  module Ucp
+    module BigCommerce
+      # Converts BigCommerce Admin API response bodies (v3 Catalog/Carts/
+      # Checkouts, v2 Orders) into the protocol-layer value objects from
+      # Portage::Ucp::ValueObjects — nothing BigCommerce-shaped is allowed to
+      # leak past this file.
+      #
+      # `currency` is threaded in by the caller everywhere it's needed: the
+      # v3 Catalog product resource doesn't carry a currency field at all
+      # (it's a store-wide default currency setting), unlike Cart/Checkout
+      # responses, which carry their own `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
+
+        # `site_url` is only used to turn `custom_url.url` (always store-
+        # relative, e.g. "/cold-brew/") into an absolute product URL — the v3
+        # Catalog resource never returns an absolute one itself.
+        def product(node, currency:, site_url:)
+          Portage::Ucp::Product.new(
+            id: node["id"].to_s,
+            title: node["name"],
+            description: node["description"],
+            price: money(node["price"], currency),
+            available: node["availability"] != "disabled",
+            variants: variants(node, currency),
+            url: node.dig("custom_url", "url") ? "#{site_url}#{node.dig('custom_url', 'url')}" : nil
+          )
+        end
+
+        # A product with no configured variants has no real Catalog
+        # "variants" entries at all — it's its own single implicit variant,
+        # same as Portage::Ucp::WooCommerce::Mapper.variants for a simple product.
+        def variants(node, currency)
+          nodes = node["variants"]
+          unless nodes&.any?
+            return [{ id: node["id"].to_s, title: node["name"], available: node["availability"] != "disabled",
+                      price: money(node["price"], currency) }]
+          end
+
+          nodes.map { |v| variant(v, node, currency) }
+        end
+
+        # A variant's own `price` is 0/null when it doesn't override the
+        # base product price — falls back to the parent product's price in
+        # that case, same "inherits unless overridden" rule BigCommerce
+        # documents for variant pricing.
+        def variant(node, parent_node, currency)
+          title = (node["option_values"] || []).map { |ov| ov["label"] }.join(" / ")
+          price = node["price"].to_f.zero? ? parent_node["price"] : node["price"]
+          { id: node["id"].to_s, title: title, available: !node["purchasing_disabled"], price: money(price, currency) }
+        end
+
+        # `id:` is caller-supplied rather than read off the response body's
+        # own top-level id in every call site: a v3 Cart's `id` field is a
+        # real, stable resource id (unlike WooCommerce's headerless Cart-
+        # Token), but callers pass it explicitly anyway so Adapter can reuse
+        # this same method for both the cart-creation response (id known
+        # from the body) and a checkout's embedded `cart` sub-object (no
+        # top-level id of its own).
+        def cart(node, id:)
+          currency = node.dig("currency", "code")
+          items = (node.dig("line_items", "physical_items") || []) + (node.dig("line_items", "digital_items") || [])
+          Portage::Ucp::Cart.new(
+            id: id,
+            line_items: items.map { |n| cart_line_item(n) },
+            currency: currency,
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: minor_units(node["base_amount"]),
+                                                          total: minor_units(node["cart_amount"]))
+          )
+        end
+
+        # `status` isn't a v3 Checkout field either — BigCommerce's Checkout
+        # is the cart plus billing/consignment/order-linkage data, not a
+        # resource with its own lifecycle enum, so the Adapter tracks status
+        # itself and passes it in, same rationale as
+        # Portage::Ucp::Shopify::Mapper.checkout and Portage::Ucp::WooCommerce::Mapper.checkout.
+        def checkout(node, id:, status:, order: nil)
+          cart_node = node["cart"] || node
+
+          Portage::Ucp::Checkout.new(
+            id: id,
+            status: status,
+            line_items: cart(cart_node, id: id).line_items,
+            currency: cart_node.dig("currency", "code"),
+            totals: checkout_totals(node, cart_node),
+            links: [],
+            order: order
+          )
+        end
+
+        def checkout_totals(node, cart_node)
+          Portage::Ucp::Support::Totals.summary(
+            subtotal: minor_units(node["subtotal"] || cart_node["base_amount"]),
+            tax: minor_units(node["tax_total"]),
+            total: minor_units(node["grand_total"] || cart_node["cart_amount"])
+          )
+        end
+
+        # CAVEAT: assumes physical/digital cart line items carry plain
+        # decimal price fields (`sale_price`, `extended_sale_price`), the
+        # shape BigCommerce's own docs show — not confirmed against a live
+        # cart response, which some BigCommerce API surfaces instead nest
+        # under a `{value:, currency:}` sub-object.
+        def cart_line_item(node)
+          unit_price = minor_units(node["sale_price"])
+          line_total = minor_units(node["extended_sale_price"])
+          Portage::Ucp::LineItem.new(
+            id: node["id"],
+            item: Portage::Ucp::Item.new(id: (node["variant_id"] || node["product_id"]).to_s, title: node["name"],
+                                         price: unit_price, image_url: node["image_url"]),
+            quantity: node["quantity"],
+            totals: Portage::Ucp::Support::Totals.line(minor_units(node["extended_list_price"]), line_total)
+          )
+        end
+
+        # BigCommerce's fixed, store-independent order status_id enum — see
+        # https://developer.bigcommerce.com/docs/rest-management/order-statuses.
+        # Core has no per-line-item fulfillment tracking (that's a shipping-
+        # app concern), so every order line is given the same coarse status
+        # derived from the order's own top-level status, same posture as
+        # Portage::Ucp::WooCommerce::Mapper::ORDER_LINE_ITEM_STATUS.
+        ORDER_STATUS = {
+          2 => "fulfilled", 8 => "fulfilled", 10 => "fulfilled",
+          4 => "removed", 5 => "removed", 6 => "removed", 14 => "removed"
+        }.freeze
+
+        # `permalink_url` is built from BigCommerce's documented storefront
+        # order-status route — not confirmed against a live storefront theme,
+        # same "needs confirming" posture as
+        # Portage::Ucp::WooCommerce::Mapper.order's order-received URL.
+        #
+        # `products` is the separate v2 `/orders/{id}/products` response —
+        # unlike WooCommerce/Shopify, a v2 Order's own resource doesn't embed
+        # its line items, so the Adapter fetches and merges them in.
+        def order(node, products:, site_url:, checkout_id: "")
+          currency = node["currency_code"]
+          status = Portage::Ucp::Support::LineItemStatus.from_table(ORDER_STATUS, node["status_id"])
+          Portage::Ucp::Order.new(
+            id: node["id"].to_s,
+            checkout_id: checkout_id,
+            permalink_url: "#{site_url}/account.php?action=order_status&order_id=#{node['id']}",
+            line_items: products.map { |n| order_line_item(n, status) },
+            fulfillment: Portage::Ucp::Fulfillment.new,
+            currency: currency,
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: minor_units(node["subtotal_ex_tax"]),
+                                                          total: minor_units(node["total_inc_tax"]))
+          )
+        end
+
+        def order_line_item(node, status)
+          quantity = node["quantity"]
+          fulfilled = Portage::Ucp::Support::LineItemStatus.fulfilled_quantity(status, quantity)
+          Portage::Ucp::OrderLineItem.new(
+            id: node["id"].to_s,
+            item: Portage::Ucp::Item.new(id: node["product_id"].to_s, title: node["name"],
+                                         price: minor_units(node["price_ex_tax"])),
+            quantity: { original: quantity, total: quantity, fulfilled: fulfilled },
+            totals: Portage::Ucp::Support::Totals.line(minor_units(node["total_ex_tax"]),
+                                                       minor_units(node["total_inc_tax"])),
+            status: status
+          )
+        end
+      end
+    end
+  end
+end

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

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

data/lib/portage/ucp/bigcommerce.rb

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

metadata

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