portage-ucp-shopify 0.1.0 → 0.2.0

checksums.yaml

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

data/CHANGELOG.md

@@ -4,7 +4,47 @@ 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
+## [0.2.0] - 2026-08-21
+
+- `CartInput.discountCodes` on create, `cartDiscountCodesUpdate` on update —
+  backs the core gem's new `dev.ucp.shopping.discount` extension, same
+  full-replacement posture `update_cart`'s line-item handling already uses.
+  `CART_FIELDS` grows `discountCodes` and `discountAllocations`; `#discounts`
+  treats the former as every code Shopify has on record and the latter as the
+  applied list. `AppliedDiscount#allocations` is left unpopulated —
+  `discountAllocations` doesn't resolve to a line-item index without a second
+  per-line query this pass didn't add. Only Shopify implements this so far.
+- `dev.ucp.shopping.fulfillment` mapped onto Cart `deliveryGroups`: an address
+  via `cartDeliveryAddressesAdd`, a rate selection via
+  `cartSelectedDeliveryOptionsUpdate`. Storefront has no "fulfillment method"
+  above `deliveryGroups`, so the adapter synthesizes one `FulfillmentMethod`
+  per checkout wrapping all of a cart's `deliveryGroups` underneath it — see
+  design-log. The two mutations' input shapes
+  (`CartSelectableAddressInput`, `CartSelectedDeliveryOptionInput`) are this
+  pass's best-effort mapping, same unconfirmed-against-a-real-store caveat
+  `cartPaymentUpdate` already carries; the nullability mismatch on
+  `cartDiscountCodesUpdate`'s clear-codes path was caught and fixed against a
+  dev store, this one is still pending.
+- `#complete_checkout` now raises `Portage::Ucp::OutOfStockError` (design-log
+  §16 "Stock/availability going stale") when a cart line is no longer
+  available for sale, instead of the generic `Portage::Ucp::Shopify::Error`
+  every other submission failure raises. Checked against a live dev store:
+  `cartSubmitForCompletion`'s `SubmitFailed` result doesn't give a sold-out
+  line its own error code — Shopify raises the same
+  `NO_DELIVERY_GROUP_SELECTED` it uses for an ordinary in-progress checkout
+  that hasn't picked a delivery option yet, so that mutation's errors can't
+  tell stale stock apart from an ordinary incomplete checkout. Detection
+  instead reads each line's `merchandise.availableForSale` off the cart
+  itself, before a payment is attempted.
+- `#cancel_order` (`orderCancel`), `#refund_order` (`suggestedRefund` +
+  `refundCreate`), `#request_return` (`returnCreate`) — implements the core
+  gem's new `dev.ucp.shopping.order` cancel/return/refund extension. Each
+  re-fetches the order afterwards rather than trusting the mutation's own
+  payload, same posture as `#cancel_checkout`; the resulting
+  cancellation/refund/return state is read off `GET_ORDER`'s
+  `cancelledAt`/`refunds`/`returns` fields into `Order#adjustments`.
+
+## [0.1.0] - 2026-08-14
 
 - Initial pre-release. Shopify adapter against the Admin (catalog, order) and
   Storefront (cart, checkout) GraphQL APIs.

data/README.md

@@ -9,13 +9,15 @@ Shopify adapter for [`portage-ucp`](../portage-ucp). Implements `Portage::Ucp::A
 | `dev.ucp.shopping.catalog` | Admin | `search_catalog`, `get_product` |
 | `dev.ucp.shopping.cart` | Storefront (Cart) | `get_cart`, `create_cart`, `update_cart`, `cancel_cart` |
 | `dev.ucp.shopping.checkout` | Storefront (same Cart object) | `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout` |
-| `dev.ucp.shopping.order` | Admin | `get_order` |
+| `dev.ucp.shopping.order` | Admin | `get_order`, `cancel_order`, `refund_order`, `request_return` (gem-side extension beyond the real UCP spec — see below) |
 | `dev.ucp.shopping.identity` | — | not implemented; Shopify's OAuth identity story lives in the separate Customer Account API, out of scope here |
 
 Shopify has no separate "Checkout" object — Storefront's `Cart` **is** the checkout. The adapter tracks checkout status (`incomplete` / `completed` / `canceled` / `complete_in_progress`) itself, keyed by cart id, and resolves `Order#checkout_id` after completion via a `cart_token:` order search.
 
 Update/replace operations (`update_cart`, `update_checkout`) are full-replacement: Storefront has no atomic "replace all lines" mutation, so the adapter removes every current line then re-adds the desired ones. Mutating methods dedup by `idempotency_key` in-process so a dropped-connection retry can't double-charge.
 
+`cancel_order`, `refund_order`, and `request_return` cancel via `orderCancel`, refund via `suggestedRefund` + `refundCreate`, and request a return via `returnCreate`, respectively — each re-fetches the order afterwards rather than trusting the mutation's own payload, and the result shows up as an appended `Portage::Ucp::Adjustment` on `Order#adjustments` (type `cancellation`/`refund`/`return`). These three aren't in the real UCP spec's order lifecycle (get-only today) — they're a deliberate extension of the existing `dev.ucp.shopping.order` capability rather than a new top-level family, since it's the same resource as `get_order`.
+
 ## Installation
 
 ```ruby

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

@@ -56,15 +56,15 @@ module Portage
           cart_node && Mapper.cart(cart_node)
         end
 
-        def create_cart(line_items:, idempotency_key:)
-          dedup(idempotency_key) { Mapper.cart(create_cart_node(line_items)) }
+        def create_cart(line_items:, idempotency_key:, discount_codes: nil)
+          dedup(idempotency_key) { Mapper.cart(create_cart_node(line_items, discount_codes)) }
         end
 
         # Full replacement, matching UCP's real cart semantics: Storefront has
         # no atomic "replace all lines" mutation, so this removes every current
         # line then adds the desired ones back (two Storefront calls).
-        def update_cart(cart_id:, line_items:, idempotency_key:)
-          dedup(idempotency_key) { Mapper.cart(replace_lines(cart_id, line_items)) }
+        def update_cart(cart_id:, line_items:, idempotency_key:, discount_codes: nil)
+          dedup(idempotency_key) { Mapper.cart(replace_lines(cart_id, line_items, discount_codes)) }
         end
 
         # Shopify has no cart-cancellation mutation — carts simply expire.
@@ -74,9 +74,10 @@ module Portage
           dedup(idempotency_key) { get_cart(cart_id: cart_id) }
         end
 
-        def create_checkout(line_items:, idempotency_key:)
+        def create_checkout(line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
           dedup(idempotency_key) do
-            cart_node = create_cart_node(line_items)
+            cart_node = create_cart_node(line_items, discount_codes)
+            cart_node = apply_fulfillment(cart_node["id"], fulfillment) if fulfillment
             record_checkout_status(cart_node["id"], "incomplete")
             Mapper.checkout(cart_node, status: "incomplete")
           end
@@ -89,14 +90,18 @@ module Portage
 
         # Full replacement, same rationale as #update_cart — Shopify checkout
         # *is* the cart object.
-        def update_checkout(checkout_id:, line_items:, idempotency_key:)
+        def update_checkout(checkout_id:, line_items:, idempotency_key:, discount_codes: nil, fulfillment: nil)
           dedup(idempotency_key) do
-            cart_node = replace_lines(checkout_id, line_items)
+            cart_node = replace_lines(checkout_id, line_items, discount_codes)
+            cart_node = apply_fulfillment(checkout_id, fulfillment) if fulfillment
             record_checkout_status(checkout_id, "incomplete")
             Mapper.checkout(cart_node, status: "incomplete")
           end
         end
 
+        def discount_codes_supported? = true
+        def fulfillment_supported? = true
+
         # `payment_token` is the single-use tokenized credential from a UCP
         # payment handler (already validated as non-PAN by PaymentTokenGuard
         # before this is ever called, per §9). It's threaded straight into
@@ -123,8 +128,112 @@ module Portage
           node && Mapper.order(node, checkout_id: checkout_id_for(order_id))
         end
 
+        # orderCancel returns only a (possibly still-pending) job — the
+        # updated cancellation state is read back via #get_order, same
+        # "trust a fresh read over the mutation payload" posture as
+        # #cancel_checkout.
+        def cancel_order(order_id:, idempotency_key:, reason: nil)
+          dedup(idempotency_key) do
+            data = @client.admin_query(Queries::ORDER_CANCEL, variables: { orderId: order_id, staffNote: reason })
+            raise_on_errors!(data, "orderCancel", "orderCancelUserErrors")
+            get_order(order_id: order_id)
+          end
+        end
+
+        # `line_items:` here are order line items ({id:, quantity:}) — the
+        # same ids GET_ORDER's line_items carry — since refundLineItems keys
+        # off the plain LineItem id, unlike request_return's
+        # fulfillmentLineItemId below.
+        def refund_order(order_id:, line_items:, idempotency_key:, reason: nil)
+          dedup(idempotency_key) do
+            refund_line_items = line_items.map { |li| { lineItemId: li[:id], quantity: li[:quantity] } }
+            transactions = suggested_refund_transactions(order_id, refund_line_items)
+            data = @client.admin_query(
+              Queries::REFUND_CREATE,
+              variables: { input: { orderId: order_id, note: reason, refundLineItems: refund_line_items,
+                                    transactions: transactions } }
+            )
+            raise_on_errors!(data, "refundCreate", "userErrors")
+            get_order(order_id: order_id)
+          end
+        end
+
+        def request_return(order_id:, line_items:, idempotency_key:, reason: nil)
+          dedup(idempotency_key) do
+            return_line_items = line_items.map do |li|
+              { fulfillmentLineItemId: li[:id], quantity: li[:quantity], returnReason: "OTHER",
+                returnReasonNote: reason }
+            end
+            data = @client.admin_query(Queries::RETURN_CREATE,
+                                       variables: { returnInput: { orderId: order_id,
+                                                                   returnLineItems: return_line_items } })
+            raise_on_errors!(data, "returnCreate", "userErrors")
+            get_order(order_id: order_id)
+          end
+        end
+
         private
 
+        def raise_on_errors!(data, field, errors_key)
+          errors = data.dig(field, errors_key)
+          raise Portage::Ucp::Shopify::UserError.new(field, errors) if errors && !errors.empty?
+        end
+
+        def suggested_refund_transactions(order_id, refund_line_items)
+          data = @client.admin_query(Queries::SUGGESTED_REFUND,
+                                     variables: { orderId: order_id, refundLineItems: refund_line_items })
+          (data.dig("order", "suggestedRefund", "transactions") || []).map do |t|
+            { orderId: order_id, gateway: t["gateway"], kind: t["kind"],
+              amount: t.dig("amountSet", "shopMoney", "amount"), parentId: t.dig("parentTransaction", "id") }
+          end
+        end
+
+        # Applies the agent's fulfillment request onto the cart: submits a
+        # shipping address (if the agent supplied one on `destinations`, the
+        # only way Shopify's deliveryOptions get priced at all) and/or the
+        # agent's `selected_option_id` choices per group. Either half is
+        # optional and independent — an agent picking a rate on an
+        # already-addressed cart sends only the latter.
+        def apply_fulfillment(cart_id, fulfillment)
+          cart_node = fetch_cart_node(cart_id)
+
+          destination = fulfillment.shipping_methods.flat_map(&:destinations).first
+          cart_node = apply_delivery_address(cart_id, destination.address) if destination
+
+          selections = fulfillment.shipping_methods.flat_map(&:groups).filter_map { |g| delivery_selection(g) }
+          cart_node = apply_delivery_selections(cart_id, selections) unless selections.empty?
+
+          cart_node
+        end
+
+        def delivery_selection(group)
+          return nil unless group.selected_option_id
+
+          { deliveryGroupId: group.id, deliveryOptionHandle: group.selected_option_id }
+        end
+
+        def apply_delivery_address(cart_id, address)
+          data = @client.storefront_query(
+            Queries::CART_DELIVERY_ADDRESSES_ADD,
+            variables: { cartId: cart_id,
+                         addresses: [{ address: { deliveryAddress: delivery_address_input(address) },
+                                       selected: true }] }
+          )
+          unwrap!(data, "cartDeliveryAddressesAdd")
+        end
+
+        def delivery_address_input(address)
+          { address1: address.street_address, address2: address.extended_address, city: address.address_locality,
+            provinceCode: address.address_region, countryCode: address.address_country, zip: address.postal_code,
+            firstName: address.first_name, lastName: address.last_name, phone: address.phone_number }.compact
+        end
+
+        def apply_delivery_selections(cart_id, selections)
+          data = @client.storefront_query(Queries::CART_SELECTED_DELIVERY_OPTIONS_UPDATE,
+                                          variables: { cartId: cart_id, selectedDeliveryOptions: selections })
+          unwrap!(data, "cartSelectedDeliveryOptionsUpdate")
+        end
+
         def fetch_cart_node(cart_id)
           @client.storefront_query(Queries::GET_CART, variables: { id: cart_id })["cart"]
         end
@@ -133,23 +242,37 @@ module Portage
           line_items.map { |li| { merchandiseId: li[:product_id], quantity: li[:quantity] } }
         end
 
-        def create_cart_node(line_items)
-          data = @client.storefront_query(Queries::CART_CREATE, variables: { input: { lines: cart_lines(line_items) } })
+        def create_cart_node(line_items, discount_codes)
+          input = { lines: cart_lines(line_items) }
+          input[:discountCodes] = discount_codes if discount_codes
+          data = @client.storefront_query(Queries::CART_CREATE, variables: { input: input })
           unwrap!(data, "cartCreate")
         end
 
-        def replace_lines(cart_id, line_items)
+        def replace_lines(cart_id, line_items, discount_codes)
           current_line_ids = fetch_cart_node(cart_id).dig("lines", "nodes").map { |n| n["id"] }
           unless current_line_ids.empty?
             removed = @client.storefront_query(Queries::CART_LINES_REMOVE,
                                                variables: { cartId: cart_id, lineIds: current_line_ids })
             unwrap!(removed, "cartLinesRemove")
           end
-          return fetch_cart_node(cart_id) if line_items.empty?
 
-          added = @client.storefront_query(Queries::CART_LINES_ADD,
-                                           variables: { cartId: cart_id, lines: cart_lines(line_items) })
-          unwrap!(added, "cartLinesAdd")
+          cart_node = if line_items.empty?
+                        fetch_cart_node(cart_id)
+                      else
+                        added = @client.storefront_query(Queries::CART_LINES_ADD,
+                                                         variables: { cartId: cart_id, lines: cart_lines(line_items) })
+                        unwrap!(added, "cartLinesAdd")
+                      end
+          return cart_node if discount_codes.nil?
+
+          apply_discount_codes(cart_id, discount_codes)
+        end
+
+        def apply_discount_codes(cart_id, discount_codes)
+          data = @client.storefront_query(Queries::CART_DISCOUNT_CODES_UPDATE,
+                                          variables: { cartId: cart_id, discountCodes: discount_codes })
+          unwrap!(data, "cartDiscountCodesUpdate")
         end
 
         # Reuses idempotency_key as cartSubmitForCompletion's own attemptId too
@@ -159,6 +282,8 @@ module Portage
           cart_node = fetch_cart_node(checkout_id)
           raise Portage::Ucp::Shopify::Error, "cart #{checkout_id} not found" unless cart_node
 
+          raise_if_any_line_unavailable!(cart_node)
+
           pay_for_cart(checkout_id, cart_node.dig("cost", "totalAmount"), payment_token)
 
           submit_data = @client.storefront_query(Queries::CART_SUBMIT_FOR_COMPLETION,
@@ -209,6 +334,23 @@ module Portage
           payload.fetch("cart")
         end
 
+        # Checked against a live dev store: a sold-out line doesn't get its
+        # own SubmissionErrorCode on cartSubmitForCompletion — Shopify raises
+        # the same NO_DELIVERY_GROUP_SELECTED code it uses for an ordinary
+        # incomplete checkout that simply hasn't picked a delivery option yet,
+        # so a code-substring match on that mutation's errors can't tell stale
+        # stock apart from a normal in-progress checkout. availableForSale on
+        # each line's merchandise is the one field that actually flips when a
+        # variant goes out of stock, so the check happens here instead, before
+        # a payment is even attempted.
+        def raise_if_any_line_unavailable!(cart_node)
+          unavailable = cart_node.dig("lines", "nodes").reject { |n| n.dig("merchandise", "availableForSale") }
+          return if unavailable.empty?
+
+          titles = unavailable.map { |n| n.dig("merchandise", "product", "title") }.join(", ")
+          raise Portage::Ucp::OutOfStockError, "no longer available: #{titles}"
+        end
+
         def unwrap_submit!(data)
           payload = data.fetch("cartSubmitForCompletion")
           errors = payload["userErrors"]

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

@@ -42,7 +42,30 @@ module Portage
             id: node["id"],
             line_items: node.dig("lines", "nodes").map { |n| cart_line_item(n) },
             currency: node.dig("cost", "subtotalAmount", "currencyCode"),
-            totals: totals(node)
+            totals: totals(node),
+            discounts: discounts(node)
+          )
+        end
+
+        # dev.ucp.shopping.discount — `codes` echoes every code Shopify has on
+        # record for the cart (applicable or not); `applied` only lists
+        # allocations that actually reduced the price, since that's all
+        # `discountAllocations` ever returns. Allocation-level breakdown
+        # (applied_discount's `allocations` field) isn't sourced here —
+        # per-line attribution needs a separate line-level query this adapter
+        # doesn't make yet.
+        def discounts(node)
+          codes = (node["discountCodes"] || []).map { |c| c["code"] }
+          applied = (node["discountAllocations"] || []).map { |a| applied_discount(a) }
+          Portage::Ucp::Discounts.new(codes: codes, applied: applied)
+        end
+
+        def applied_discount(node)
+          Portage::Ucp::AppliedDiscount.new(
+            title: node["title"] || node["code"],
+            amount: minor_units(node["discountedAmount"]),
+            code: node["code"],
+            automatic: !node["code"]
           )
         end
 
@@ -69,10 +92,73 @@ module Portage
             currency: node.dig("cost", "subtotalAmount", "currencyCode"),
             totals: totals(node),
             links: [],
-            order: order
+            order: order,
+            discounts: discounts(node),
+            fulfillment: checkout_fulfillment(node)
+          )
+        end
+
+        # dev.ucp.shopping.fulfillment (pre-purchase shipping-option
+        # selection) built from Cart#deliveryGroups — read straight off
+        # CART_FIELDS, no separate query. Shopify has no "fulfillment method"
+        # grouping above deliveryGroups, and a cart only ever carries the one
+        # buyer-submitted address (split-shipment-to-multiple-addresses isn't
+        # modeled here), so every deliveryGroup collapses into a single
+        # synthesized FulfillmentMethod rather than one per Shopify group.
+        def checkout_fulfillment(node)
+          groups_nodes = node["deliveryGroups"] || []
+          return Portage::Ucp::CheckoutFulfillment.new if groups_nodes.empty?
+
+          groups = groups_nodes.map { |g| fulfillment_group(g) }
+          destination = shipping_destination(groups_nodes.first["deliveryAddress"])
+          method = Portage::Ucp::FulfillmentMethod.new(
+            id: "fm_#{node['id']}",
+            type: DELIVERY_METHOD_TYPES.fetch(groups_nodes.first.dig("deliveryOptions", 0, "deliveryMethodType"),
+                                              "shipping"),
+            line_item_ids: groups.flat_map(&:line_item_ids),
+            destinations: destination ? [destination] : [],
+            selected_destination_id: destination&.id,
+            groups: groups
+          )
+          Portage::Ucp::CheckoutFulfillment.new(shipping_methods: [method])
+        end
+
+        def fulfillment_group(node)
+          Portage::Ucp::FulfillmentGroup.new(
+            id: node["id"],
+            line_item_ids: (node.dig("cartLines", "nodes") || []).map { |n| n["id"] },
+            options: (node["deliveryOptions"] || []).map { |o| fulfillment_option(o) },
+            selected_option_id: node.dig("selectedDeliveryOption", "handle")
           )
         end
 
+        def fulfillment_option(node)
+          Portage::Ucp::FulfillmentOption.new(
+            id: node["handle"], title: node["title"] || node["handle"],
+            totals: [Portage::Ucp::Total.new(type: "total", amount: minor_units(node["estimatedCost"]))],
+            description: node["description"]
+          )
+        end
+
+        # Shopify's CartDeliveryGroup#deliveryAddress is a bare MailingAddress
+        # with no id of its own (unlike a saved address-book entry) — since a
+        # cart only ever carries the one buyer-submitted address (see
+        # #checkout_fulfillment), this always exposes it as the single
+        # destination "current" rather than fabricating a hash-based id that
+        # would drift for no real change.
+        def shipping_destination(address_node)
+          return nil unless address_node
+
+          Portage::Ucp::ShippingDestination.new(id: "current",
+                                                address: Portage::Ucp::PostalAddress.new(**fulfillment_address(address_node)))
+        end
+
+        def fulfillment_address(node)
+          { street_address: node["address1"], extended_address: node["address2"], address_locality: node["city"],
+            address_region: node["provinceCode"], address_country: node["countryCode"], postal_code: node["zip"],
+            first_name: node["firstName"], last_name: node["lastName"], phone_number: node["phone"] }.compact
+        end
+
         # `checkout_id` isn't a Shopify Order field — nothing on Order links
         # back to its originating cart, so the adapter resolves it itself (via
         # a cart_token order search at completion time, see
@@ -88,7 +174,60 @@ module Portage
             line_items: node.dig("lineItems", "nodes").map { |n| order_line_item(n) },
             fulfillment: fulfillment(node),
             currency: node.dig("currentTotalPriceSet", "shopMoney", "currencyCode"),
-            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal_amount, total: total_amount)
+            totals: Portage::Ucp::Support::Totals.summary(subtotal: subtotal_amount, total: total_amount),
+            adjustments: adjustments(node)
+          )
+        end
+
+        # cancel_order/refund_order/request_return (design-log §16) don't map
+        # to a dedicated Shopify response shape each — they all resolve back
+        # to a fresh GET_ORDER read, so the order's cancellation/refund/return
+        # state is read straight off the Order node here rather than
+        # synthesized ad hoc per adapter method.
+        def adjustments(node)
+          [
+            *(node["cancelledAt"] ? [cancellation_adjustment(node)] : []),
+            *(node["refunds"] || []).map { |n| refund_adjustment(n) },
+            *(node.dig("returns", "nodes") || []).map { |n| return_adjustment(n) }
+          ]
+        end
+
+        def cancellation_adjustment(node)
+          Portage::Ucp::Adjustment.new(
+            id: "#{node['id']}-cancellation", type: "cancellation", occurred_at: node["cancelledAt"],
+            status: "completed", description: node["cancelReason"]
+          )
+        end
+
+        def refund_adjustment(node)
+          line_items = (node.dig("refundLineItems", "nodes") || []).map { |n| order_line_ref(n, -n["quantity"]) }
+          Portage::Ucp::Adjustment.new(
+            id: node["id"], type: "refund", occurred_at: node["createdAt"], status: "completed",
+            line_items: line_items.empty? ? nil : line_items,
+            totals: [Portage::Ucp::Total.new(type: "total", amount: -minor_units(node.dig("totalRefundedSet",
+                                                                                          "shopMoney")))],
+            description: node["note"]
+          )
+        end
+
+        # Shopify's ReturnStatus enum (OPEN/REQUESTED/CLOSED/DECLINED/
+        # CANCELED/...); unmapped values fall back to "pending", same
+        # unmapped-enum posture as DELIVERY_METHOD_TYPES/
+        # FULFILLMENT_EVENT_TYPES below.
+        RETURN_STATUSES = {
+          "OPEN" => "pending", "REQUESTED" => "pending", "CLOSED" => "completed",
+          "DECLINED" => "failed", "CANCELED" => "failed"
+        }.freeze
+
+        def return_adjustment(node)
+          line_items = (node.dig("returnLineItems", "nodes") || []).map do |n|
+            { "id" => n.dig("fulfillmentLineItem", "lineItem", "id"), "quantity" => -n["quantity"] }
+          end
+          description = node.dig("returnLineItems", "nodes")&.first&.fetch("returnReasonNote", nil)
+          Portage::Ucp::Adjustment.new(
+            id: node["id"], type: "return", occurred_at: node["requestedAt"],
+            status: RETURN_STATUSES.fetch(node["status"], "pending"),
+            line_items: line_items.empty? ? nil : line_items, description: description
           )
         end
 

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

@@ -38,9 +38,30 @@ module Portage
             nodes {
               id quantity
               cost { totalAmount { amount currencyCode } }
-              merchandise { ... on ProductVariant { id product { id title } price { amount currencyCode } } }
+              merchandise {
+                ... on ProductVariant {
+                  id
+                  product { id title }
+                  price { amount currencyCode }
+                  availableForSale
+                }
+              }
             }
           }
+          deliveryGroups {
+            id
+            cartLines(first: 100) { nodes { id } }
+            deliveryOptions { handle title description deliveryMethodType estimatedCost { amount currencyCode } }
+            selectedDeliveryOption { handle }
+            deliveryAddress { address1 address2 city provinceCode zip firstName lastName phone
+                              countryCode: countryCodeV2 }
+          }
+          discountCodes { code applicable }
+          discountAllocations {
+            discountedAmount { amount currencyCode }
+            ... on CartAutomaticDiscountAllocation { title }
+            ... on CartCodeDiscountAllocation { code }
+          }
         GRAPHQL
 
         GET_CART = <<~GRAPHQL.freeze
@@ -73,6 +94,43 @@ module Portage
           }
         GRAPHQL
 
+        # `CartSelectableAddressInput`'s nested shape (Storefront API's
+        # current replacement for the deprecated
+        # CartBuyerIdentityInput#deliveryAddressPreferences path) is the
+        # adapter's mapping of dev.ucp.shopping.fulfillment's
+        # ShippingDestination onto it. Confirmed live against a real dev
+        # store 2026-08-21 — see design-log.md #18. CART_PAYMENT_UPDATE's
+        # paymentMethod sub-shape below is still unconfirmed (roadmap step 5).
+        CART_DELIVERY_ADDRESSES_ADD = <<~GRAPHQL.freeze
+          mutation CartDeliveryAddressesAdd($cartId: ID!, $addresses: [CartSelectableAddressInput!]!) {
+            cartDeliveryAddressesAdd(cartId: $cartId, addresses: $addresses) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        CART_SELECTED_DELIVERY_OPTIONS_UPDATE = <<~GRAPHQL.freeze
+          mutation CartSelectedDeliveryOptionsUpdate($cartId: ID!,
+                                                      $selectedDeliveryOptions: [CartSelectedDeliveryOptionInput!]!) {
+            cartSelectedDeliveryOptionsUpdate(cartId: $cartId, selectedDeliveryOptions: $selectedDeliveryOptions) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        # Full-replacement, matching dev.ucp.shopping.discount's `codes`
+        # semantics — an empty array clears whatever codes were on the cart.
+        CART_DISCOUNT_CODES_UPDATE = <<~GRAPHQL.freeze
+          mutation CartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]!) {
+            cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
+              cart { #{CART_FIELDS} }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
         CART_BUYER_IDENTITY_UPDATE = <<~GRAPHQL.freeze
           mutation CartBuyerIdentityUpdate($cartId: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
             cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
@@ -110,6 +168,8 @@ module Portage
             order(id: $id) {
               id
               statusPageUrl
+              cancelledAt
+              cancelReason
               currentTotalPriceSet { shopMoney { amount currencyCode } }
               currentSubtotalPriceSet { shopMoney { amount currencyCode } }
               lineItems(first: 100) {
@@ -139,6 +199,96 @@ module Portage
                   nodes { quantity lineItem { id } }
                 }
               }
+              refunds(first: 25) {
+                id
+                createdAt
+                note
+                totalRefundedSet { shopMoney { amount currencyCode } }
+                refundLineItems(first: 100) {
+                  nodes { quantity lineItem { id } }
+                }
+              }
+              returns(first: 25) {
+                nodes {
+                  id
+                  status
+                  requestedAt
+                  returnLineItems(first: 100) {
+                    nodes {
+                      quantity
+                      returnReasonNote
+                      fulfillmentLineItem { lineItem { id } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        GRAPHQL
+
+        # orderCancel is async (returns a job, not the updated Order) — the
+        # adapter re-fetches via GET_ORDER afterwards for the current state,
+        # same posture as #cancel_checkout not trusting a mutation payload
+        # over a fresh read. `reason` is fixed to OTHER: UCP's cancel_order
+        # only carries a free-text note (`staffNote`), it doesn't expose
+        # Shopify's closed OrderCancelReason enum.
+        ORDER_CANCEL = <<~GRAPHQL.freeze
+          mutation OrderCancel($orderId: ID!, $staffNote: String) {
+            orderCancel(orderId: $orderId, reason: OTHER, refund: false, restock: false, staffNote: $staffNote) {
+              job { id done }
+              orderCancelUserErrors { field message code }
+            }
+          }
+        GRAPHQL
+
+        # refundCreate requires explicit `transactions:` (which gateway
+        # transaction to refund against, and how much) — suggestedRefund is
+        # Shopify's documented way to compute that breakdown instead of the
+        # adapter guessing at payment-gateway specifics. #refund_order runs
+        # this first, then feeds its `transactions` straight into
+        # REFUND_CREATE's input.
+        SUGGESTED_REFUND = <<~GRAPHQL.freeze
+          query SuggestedRefund($orderId: ID!, $refundLineItems: [RefundLineItemInput!]!) {
+            order(id: $orderId) {
+              suggestedRefund(refundLineItems: $refundLineItems) {
+                transactions {
+                  orderId
+                  gateway
+                  kind
+                  amountSet { shopMoney { amount currencyCode } }
+                  parentTransaction { id }
+                }
+              }
+            }
+          }
+        GRAPHQL
+
+        REFUND_CREATE = <<~GRAPHQL.freeze
+          mutation RefundCreate($input: RefundInput!) {
+            refundCreate(input: $input) {
+              refund {
+                id
+                createdAt
+                note
+                totalRefundedSet { shopMoney { amount currencyCode } }
+                refundLineItems(first: 100) { nodes { quantity lineItem { id } } }
+              }
+              userErrors { field message }
+            }
+          }
+        GRAPHQL
+
+        # returnCreate's returnLineItems key off `fulfillmentLineItemId`, not
+        # the plain order-line-item id REFUND_CREATE's refundLineItems use —
+        # a real return targets what was actually fulfilled. `request_return`
+        # callers pass fulfillment line item ids in `line_items:` for this
+        # action specifically; needs confirming against a live store, same
+        # caveat as #complete_checkout's payment sub-shape.
+        RETURN_CREATE = <<~GRAPHQL.freeze
+          mutation ReturnCreate($returnInput: ReturnInput!) {
+            returnCreate(returnInput: $returnInput) {
+              return { id status }
+              userErrors { field message }
             }
           }
         GRAPHQL

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

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-shopify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tom Whitbread
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -16,14 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -83,7 +96,6 @@ dependencies:
 description: Implements Portage::Ucp::Adapter against Shopify's Admin (catalog, order)
   and Storefront (cart, checkout) GraphQL APIs. Generic only — no merchant-specific
   business logic. Plain Net::HTTP, no shopify_api runtime dependency.
-email:
 executables:
 - portage-ucp-shopify
 extensions: []
@@ -108,7 +120,6 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-shopify
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-shopify/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -123,8 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Shopify adapter for portage-ucp — standard catalog/cart/checkout/order over
   MCP and UCP