Feature: Adding Checkout Services and Events

src/Checkout/Events/BillingAddressSet.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Base\Addressable;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::setBillingAddress() — see
+ * ShippingAddressSet's docblock for the full reasoning (Lunar dispatches no
+ * checkout-lifecycle events; this feeds funnel-stage tracking, not built
+ * yet).
+ */
+class BillingAddressSet
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array|Addressable $address,
+    ) {}
+}

src/Checkout/Events/OrderPlaced.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by CheckoutService::placeOrder() the moment an Order exists —
+ * the handoff point between Checkout and Order (see docs/checkout.md's
+ * "Three-stage lifecycle"). Checkout has no opinion about what happens
+ * after this fires; Order's own listeners (not built yet — Order is a
+ * named-but-unscoped concern, same status Recovery had before it existed)
+ * would be what reacts to it — e.g. a confirmation email, initializing
+ * order status tracking.
+ */
+class OrderPlaced
+{
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Checkout/Events/ShippingAddressSet.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Base\Addressable;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::setShippingAddress() — Lunar itself
+ * dispatches no checkout-lifecycle events at all (same gap CartService's
+ * events fill for cart mutations; see docs/cart.md). Feeds
+ * abandoned-checkout stage tracking / conversion-funnel analytics (neither
+ * built yet — see docs/checkout.md), which is why $address is carried
+ * directly rather than requiring a listener to re-read it off the cart.
+ */
+class ShippingAddressSet
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array|Addressable $address,
+    ) {}
+}

src/Checkout/Events/ShippingOptionSelected.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\DataTypes\ShippingOption;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::selectShippingOption() — carries the fully
+ * resolved ShippingOption (name, price, carrier identifier), not just the
+ * string identifier the caller passed in. Deliberate divergence from
+ * CartService's events, which carry a plain Cart/CartLine model reference —
+ * a live-priced carrier quote (see docs/checkout.md's note on
+ * ShippingManifest::getOptions() already being backed by the merged
+ * Shipping-Carriers ACS/Box Now live-rate drivers) is meaningfully more
+ * expensive for a listener to re-derive later than a CartLine reference is.
+ */
+class ShippingOptionSelected
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly ShippingOption $option,
+    ) {}
+}