portage-ucp 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3dd667eb94ccfb68762797d5020e233f282d941b4790503a812b01067be09f
-  data.tar.gz: bb3cb10f93333cb720172aa427f2b09b03d186c03b98485b63a8dca9dae8a302
+  metadata.gz: 1e47e8018ba5966b67205cb9046efdf0e8f0edbe9ab58eef1e7613232a5b6b27
+  data.tar.gz: c5eaa266f8d88a7fda16a822e0eb0b6aad82465b1e6adbf36abe08e7d2c859c4
 SHA512:
-  metadata.gz: 58b3c2ab0aad754862745bf0381e8e37987d2fa8c4da6f80c6460284cb4242d7f9c45e74b83918f6ab032770f38467f6bb62f08cefa06555e2de2dedead2e588
-  data.tar.gz: e9dd08412d7fb321da9118ceb01804a71894da1bca6a7263ffab5ed3efda335657e5c1c2d3bf52d027056bd4a88ab0e6889eacdb9c454103e595ed961a0b885a
+  metadata.gz: '053845855d29f395fb001b78d13622798aadf54c8dc087c88bdf32a943e65e992e7d6d79a3f9a5c86232ebfb8f65f36eb1137888bd9a806e2ceeeef045a57789'
+  data.tar.gz: 6e1cec328b2d07567d4441340fe177367db3bbe7e094aa93388446cb062ea948e600abeb353dcf31b3833f7f76d2ccc189c275a44ab4c5ea546b94e4f3c152d7

data/CHANGELOG.md

@@ -6,6 +6,10 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-07
+
+- **Added: `Support::CheckoutState` can ask the platform about a checkout this process doesn't track.** An adapter may define a private `platform_checkout_order(checkout_id)` that returns the `Order` its platform placed from that checkout, or nil. `#checkout_status` then reports `completed` for an id with no in-process record, the new `#checkout_order` returns its `OrderConfirmation`, and the new `#checkout_from_platform_order` rebuilds a completed `Checkout` from the order when the platform has already dropped the cart. A found order is cached through `#record_checkout_status`/`#record_order_checkout`; no order, no hook, or a lookup error keeps today's `incomplete`. This lets `portage orders reconcile`, which runs in a new process, see a checkout the shopper paid for in the browser (design-log §55). The `Adapter` contract is unchanged. Minor-level.
+
 ## [0.12.0] - 2026-10-05
 
 - **Removed the unused `services/shopping/embedded.openrpc.json` schema.** Nothing loaded or listed it (`SchemaValidator` only reads `mcp.openrpc.json`); it just shipped in the gem. Patch-level.

data/lib/portage/ucp/support/checkout_state.rb

@@ -14,7 +14,9 @@ module Portage
       #
       # Both default rather than raise on an unknown id ("incomplete" and "",
       # respectively): a checkout this process didn't create is still
-      # schema-valid to report, just not information-complete.
+      # schema-valid to report, just not information-complete. An adapter
+      # can add a platform lookup for the unknown-id case (see
+      # #platform_order).
       module CheckoutState
         # Dispatcher wraps each adapter call in .with_observability rather
         # than writing [logger, correlation_id] onto an instance variable on
@@ -49,8 +51,77 @@ module Portage
 
         private
 
+        # A checkout this process has no record of falls back to the
+        # platform: `portage orders reconcile` runs in a new process, after
+        # the shopper paid in their browser, and the in-process hash alone
+        # would always say "incomplete" there (design-log §55). See
+        # #platform_order.
         def checkout_status(checkout_id)
-          (@checkout_status ||= {}).fetch(checkout_id, "incomplete")
+          recorded = (@checkout_status ||= {})[checkout_id]
+          return recorded if recorded
+
+          platform_order(checkout_id) ? "completed" : "incomplete"
+        end
+
+        # The order_confirmation for a checkout #platform_order found an order
+        # for, nil otherwise (an in-process #complete_checkout hands its own
+        # back directly).
+        def checkout_order(checkout_id)
+          order = (@platform_orders ||= {})[checkout_id]
+          order && Portage::Ucp::OrderConfirmation.new(id: order.id, permalink_url: order.permalink_url)
+        end
+
+        # For a #get_checkout whose cart read came back not-found: most
+        # platforms drop the cart once it becomes an order (BigCommerce
+        # deletes it on payment, Magento deactivates the quote), so a paid
+        # checkout would otherwise only ever read as not-found. This builds
+        # the completed Checkout from the order the platform reports for it.
+        # No order means nil: a vanished cart on its own is never read as a
+        # completion (docs/plans/handoff-reconcile.md, "Settle only on a
+        # `completed` status the store actually reports").
+        def checkout_from_platform_order(checkout_id)
+          order = platform_order(checkout_id)
+          return nil unless order
+
+          line_items = order.line_items.map do |li|
+            Portage::Ucp::LineItem.new(id: li.id, item: li.item, quantity: li.quantity[:total], totals: li.totals)
+          end
+          Portage::Ucp::Checkout.new(id: checkout_id, status: "completed", line_items: line_items,
+                                     currency: order.currency, totals: order.totals, links: [],
+                                     order: checkout_order(checkout_id))
+        end
+
+        # The optional per-adapter hook: an adapter that can ask its platform
+        # "did this checkout become a placed order?" defines a private
+        # `platform_checkout_order(checkout_id)` returning that Portage::Ucp::
+        # Order, or nil. Without the hook (or when this process already
+        # tracks the checkout) nothing changes. A found order is cached
+        # through #record_checkout_status/#record_order_checkout so the rest
+        # of this process agrees with it. A lookup error is swallowed: the
+        # caller gets today's in-process answer, which reconcile reads as
+        # "still pending", never as a settle. The hook is a private method
+        # rather than a new Adapter method or kwarg for the same §9/§23
+        # reason as .with_observability above.
+        def platform_order(checkout_id)
+          orders = (@platform_orders ||= {})
+          return orders[checkout_id] if orders.key?(checkout_id)
+
+          order = ask_platform(checkout_id)
+          return nil unless order
+
+          orders[checkout_id] = order
+          record_order_checkout(order.id, checkout_id)
+          record_checkout_status(checkout_id, "completed")
+          order
+        end
+
+        def ask_platform(checkout_id)
+          return nil if (@checkout_status ||= {}).key?(checkout_id)
+          return nil unless respond_to?(:platform_checkout_order, true)
+
+          platform_checkout_order(checkout_id)
+        rescue StandardError
+          nil
         end
 
         def record_checkout_status(checkout_id, status)

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.12.0".freeze
+    VERSION = "0.13.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64