Feat: Updates to Payments, Checkout Services, Payment Events

src/Checkout/Events/PaymentConfirmed.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by a PaymentDriver once it has independently decided (by
+ * whatever mechanism is native to its gateway) that payment succeeded —
+ * the event-driven counterpart to what used to be a direct
+ * CheckoutService::placeOrder() call from inside confirm(). Listened to by
+ * CheckoutService itself, which places the order and dispatches
+ * OrderPlaced.
+ *
+ * $type/$data are carried through for the same reason PaymentDriver::
+ * confirm() takes them — a driver-specific post-placement step (e.g.
+ * OfflinePaymentDriver's status mapping, StripePaymentDriver's
+ * UpdateOrderFromIntent) still needs them, but can no longer receive the
+ * placed Order as a return value. Each driver instead listens for
+ * OrderPlaced and checks $order->meta['payment_method'] against its own
+ * type(s) to recognize which OrderPlaced is its own — carrying $fingerprint
+ * here too lets a driver correlate its own OrderPlaced listener call back
+ * to the specific confirmation that triggered it, if it needs to.
+ */
+class PaymentConfirmed
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly string $type,
+        public readonly string $fingerprint,
+        public readonly array $data = [],
+    ) {}
+}