Feature: Adding Caches and Fallbacks to Live Pricing Requests

src/Shipping/Concerns/CachesLivePricing.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Modules\Core\Shipping\Concerns;
+
+use Illuminate\Support\Facades\Cache;
+use Lunar\DataTypes\ShippingOption;
+use Lunar\Models\Cart;
+use Lunar\Shipping\Models\ShippingRate;
+
+/**
+ * Shared by any Modules\Core\Shipping\Contracts\SupportsLivePricing driver —
+ * a live carrier price quote is a real, billed API call, but stable from
+ * one fetch to the next within a single checkout attempt. Keyed by rate id
+ * + cart id, so two different live-priced rates (e.g. ACS and a future
+ * carrier) never collide — each is its own ShippingRate row. Not shared
+ * across carts: the quote depends on cart-specific weight/quantity/
+ * destination (see docs/checkout.md).
+ *
+ * Invalidated by Modules\Core\Shipping\Listeners\FlushLivePricingCache on
+ * the only two things that can change what this cart's quote should be: a
+ * cart line changing (add/update/remove/clear) or the shipping address
+ * changing. Deliberately NOT invalidated on order placement — the price
+ * the shopper was quoted must still be there if anything re-reads it after
+ * the order exists; Cart::createOrder() persists the resolved price onto
+ * the order anyway, so nothing should be re-querying the live driver for
+ * that cart again regardless of cache state.
+ */
+trait CachesLivePricing
+{
+    private function cached(ShippingRate $shippingRate, Cart $cart, \Closure $resolve): ?ShippingOption
+    {
+        return Cache::remember(
+            "shipping.live_price.{$shippingRate->id}.{$cart->id}",
+            now()->addMinutes(30),
+            $resolve,
+        );
+    }
+}