Feature: Order Service Provider, Order Events Observers

composer.json

@@ -42,7 +42,8 @@
         "Modules\\Core\\Providers\\CatalogServiceProvider",
         "Modules\\Core\\Providers\\CartServiceProvider",
         "Modules\\Core\\Providers\\ReviewServiceProvider",
-        "Modules\\Core\\Providers\\ShippingServiceProvider"
+        "Modules\\Core\\Providers\\ShippingServiceProvider",
+        "Modules\\Core\\Providers\\OrderServiceProvider"
       ]
     }
   },

resources/views/order/notifications/captured.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Payment of <strong>{{ $amount }}</strong> for your order <strong>{{ $reference }}</strong> has been captured.</p>

resources/views/order/notifications/delivered.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Good news — your order <strong>{{ $reference }}</strong> has been delivered.</p>

resources/views/order/notifications/refunded.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>A refund of <strong>{{ $amount }}</strong> has been issued for your order <strong>{{ $reference }}</strong>.</p>

resources/views/order/notifications/status-updated.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is now: <strong>{{ $statusLabel }}</strong></p>

src/Order/Enums/FulfillmentStatus.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Modules\Core\Order\Enums;
+
+/**
+ * Derived from Shipment/ShipmentInfo — no equivalent existed anywhere in
+ * Lunar or this codebase before OrderStatus::fulfillment().
+ */
+enum FulfillmentStatus: string
+{
+    case Unfulfilled = 'unfulfilled';
+    case Shipped = 'shipped';
+    case PartiallyShipped = 'partially-shipped';
+    case Delivered = 'delivered';
+}

src/Order/Enums/PaymentStatus.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Modules\Core\Order\Enums;
+
+/**
+ * Same states/logic as Lunar's own ManageOrder::paymentStatus(), which
+ * only exists as a Filament-page Livewire #[Computed] method — this is
+ * that same derivation, reusable from anywhere via Order::paymentStatus().
+ */
+enum PaymentStatus: string
+{
+    case Offline = 'offline';
+    case Uncaptured = 'uncaptured';
+    case Captured = 'captured';
+    case PartialRefund = 'partial-refund';
+    case Refunded = 'refunded';
+}

src/Order/Events/OrderCaptured.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Lunar\Models\Transaction;
+
+/**
+ * Dispatched by TransactionObserver::saved() when a Transaction's type
+ * changes to 'capture' (from 'intent') and succeeds. Unlike refunds,
+ * Lunar's Stripe driver (StoreCharges) reuses the same Transaction row
+ * across intent -> capture rather than creating a new one, so this can't
+ * key off `wasRecentlyCreated` the way OrderRefunded does.
+ */
+class OrderCaptured
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly Transaction $transaction,
+    ) {}
+}

src/Order/Events/OrderDelivered.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Modules\Core\Shipping\Models\ShipmentInfo;
+
+/**
+ * Dispatched by Order's DeriveOrderDeliveredFromShipment listener, which
+ * reacts to Shipping's ShipmentStatusUpdatedByCarrier — delivery is a
+ * tracking checkpoint, not a manual status write, so it never goes through
+ * OrderStatusUpdated. Order.status itself is left untouched here; this is
+ * only the signal for delivery notifications and similar reactions.
+ */
+class OrderDelivered
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ShipmentInfo $shipmentInfo,
+    ) {}
+}

src/Order/Events/OrderRefunded.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Lunar\Models\Transaction;
+
+/**
+ * Dispatched by TransactionObserver::saved() whenever a successful
+ * type=refund Transaction row is written — every payment driver (Lunar's
+ * own StripePaymentType::refund(), or a future boboko-owned driver for a
+ * provider Lunar doesn't ship) creates a new row for each refund, so
+ * `created` alone (filtered to type+success) is enough here, unlike
+ * captures which can reuse an existing row.
+ */
+class OrderRefunded
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly Transaction $transaction,
+    ) {}
+}

src/Order/Events/OrderStatusUpdated.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by OrderObserver::updated() whenever an Order's status column
+ * changes, regardless of what wrote it — Filament's UpdateStatusAction,
+ * artisan tinker, a future API. Lunar's own UpdatesOrderStatus trait fires
+ * mailers inline, but only for that one admin action; this event is the
+ * general-purpose hook everything else (our own mailers, automations,
+ * derived payment/fulfillment status) should listen to instead.
+ */
+class OrderStatusUpdated
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ?string $previousStatus,
+        public readonly string $newStatus,
+    ) {}
+}

src/Order/Listeners/DeriveOrderDeliveredFromShipment.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Modules\Core\Order\Listeners;
+
+use Modules\Core\Order\Events\OrderDelivered;
+use Modules\Core\Shipping\Enums\TrackingStatus;
+use Modules\Core\Shipping\Events\ShipmentStatusUpdatedByCarrier;
+
+/**
+ * Translates a carrier tracking checkpoint into OrderDelivered — the event
+ * OrderDeliveredNotification (via NotificationRegistry) actually listens
+ * to. Kept separate from the notification itself so the "is this checkpoint
+ * a delivery" filtering doesn't leak into notification code.
+ */
+class DeriveOrderDeliveredFromShipment
+{
+    public function handle(ShipmentStatusUpdatedByCarrier $event): void
+    {
+        if ($event->shipmentInfo->status !== TrackingStatus::Delivered) {
+            return;
+        }
+
+        $order = $event->shipmentInfo->shipment->order;
+
+        if (! $order) {
+            return;
+        }
+
+        OrderDelivered::dispatch($order, $event->shipmentInfo);
+    }
+}

src/Order/Notifications/OrderCapturedNotification.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Modules\Core\Order\Notifications;
+
+use Illuminate\Notifications\AnonymousNotifiable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Support\Facades\Notification as NotificationFacade;
+use Modules\Core\Notification\BaseNotification;
+use Modules\Core\Order\Events\OrderCaptured;
+
+class OrderCapturedNotification extends BaseNotification
+{
+    public function __construct(private readonly OrderCaptured $event) {}
+
+    public static function getKey(): string
+    {
+        return 'order.captured.customer.mail';
+    }
+
+    public static function listensTo(): string
+    {
+        return OrderCaptured::class;
+    }
+
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    public function notifiable(): AnonymousNotifiable
+    {
+        $order = $this->event->order;
+
+        $email = $order->billingAddress?->contact_email ?? $order->shippingAddress?->contact_email;
+
+        return NotificationFacade::route('mail', $email);
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        $order = $this->event->order;
+
+        return (new MailMessage)
+            ->subject(__('Payment captured for your order :reference', ['reference' => $order->reference]))
+            ->view('core::order.notifications.captured', [
+                'reference' => $order->reference,
+                'amount' => $this->event->transaction->amount->formatted,
+            ]);
+    }
+}

src/Order/Notifications/OrderDeliveredNotification.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Modules\Core\Order\Notifications;
+
+use Illuminate\Notifications\AnonymousNotifiable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Support\Facades\Notification as NotificationFacade;
+use Modules\Core\Notification\BaseNotification;
+use Modules\Core\Order\Events\OrderDelivered;
+
+class OrderDeliveredNotification extends BaseNotification
+{
+    public function __construct(private readonly OrderDelivered $event) {}
+
+    public static function getKey(): string
+    {
+        return 'order.delivered.customer.mail';
+    }
+
+    public static function listensTo(): string
+    {
+        return OrderDelivered::class;
+    }
+
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    public function notifiable(): AnonymousNotifiable
+    {
+        $order = $this->event->order;
+
+        $email = $order->billingAddress?->contact_email ?? $order->shippingAddress?->contact_email;
+
+        return NotificationFacade::route('mail', $email);
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        $order = $this->event->order;
+
+        return (new MailMessage)
+            ->subject(__('Your order :reference has been delivered', ['reference' => $order->reference]))
+            ->view('core::order.notifications.delivered', [
+                'reference' => $order->reference,
+            ]);
+    }
+}

src/Order/Notifications/OrderRefundedNotification.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Modules\Core\Order\Notifications;
+
+use Illuminate\Notifications\AnonymousNotifiable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Support\Facades\Notification as NotificationFacade;
+use Modules\Core\Notification\BaseNotification;
+use Modules\Core\Order\Events\OrderRefunded;
+
+class OrderRefundedNotification extends BaseNotification
+{
+    public function __construct(private readonly OrderRefunded $event) {}
+
+    public static function getKey(): string
+    {
+        return 'order.refunded.customer.mail';
+    }
+
+    public static function listensTo(): string
+    {
+        return OrderRefunded::class;
+    }
+
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    public function notifiable(): AnonymousNotifiable
+    {
+        $order = $this->event->order;
+
+        $email = $order->billingAddress?->contact_email ?? $order->shippingAddress?->contact_email;
+
+        return NotificationFacade::route('mail', $email);
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        $order = $this->event->order;
+
+        return (new MailMessage)
+            ->subject(__('A refund has been issued for your order :reference', ['reference' => $order->reference]))
+            ->view('core::order.notifications.refunded', [
+                'reference' => $order->reference,
+                'amount' => $this->event->transaction->amount->formatted,
+            ]);
+    }
+}

src/Order/Notifications/OrderStatusUpdatedNotification.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Modules\Core\Order\Notifications;
+
+use Illuminate\Notifications\AnonymousNotifiable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Support\Facades\Notification as NotificationFacade;
+use Modules\Core\Notification\BaseNotification;
+use Modules\Core\Order\Events\OrderStatusUpdated;
+
+class OrderStatusUpdatedNotification extends BaseNotification
+{
+    public function __construct(private readonly OrderStatusUpdated $event) {}
+
+    public static function getKey(): string
+    {
+        return 'order.status_updated.customer.mail';
+    }
+
+    public static function listensTo(): string
+    {
+        return OrderStatusUpdated::class;
+    }
+
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    public function notifiable(): AnonymousNotifiable
+    {
+        $order = $this->event->order;
+
+        $email = $order->billingAddress?->contact_email ?? $order->shippingAddress?->contact_email;
+
+        return NotificationFacade::route('mail', $email);
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        $order = $this->event->order;
+
+        return (new MailMessage)
+            ->subject(__('Your order :reference has been updated', ['reference' => $order->reference]))
+            ->view('core::order.notifications.status-updated', [
+                'reference' => $order->reference,
+                'statusLabel' => config("lunar.orders.statuses.{$order->status}.label", $order->status),
+            ]);
+    }
+}

src/Order/Observers/OrderObserver.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Order\Observers;
+
+use Lunar\Models\Order;
+use Modules\Core\Order\Events\OrderStatusUpdated;
+
+class OrderObserver
+{
+    public function updated(Order $order): void
+    {
+        if (! $order->wasChanged('status')) {
+            return;
+        }
+
+        OrderStatusUpdated::dispatch(
+            $order,
+            $order->getOriginal('status'),
+            $order->status,
+        );
+    }
+}

src/Order/Observers/TransactionObserver.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Modules\Core\Order\Observers;
+
+use Lunar\Models\Transaction;
+use Modules\Core\Order\Events\OrderCaptured;
+use Modules\Core\Order\Events\OrderRefunded;
+
+class TransactionObserver
+{
+    public function saved(Transaction $transaction): void
+    {
+        if (! $transaction->success) {
+            return;
+        }
+
+        if ($transaction->type === 'refund' && $transaction->wasRecentlyCreated) {
+            OrderRefunded::dispatch($transaction->order, $transaction);
+
+            return;
+        }
+
+        if ($transaction->type === 'capture' && $transaction->wasChanged('type')) {
+            OrderCaptured::dispatch($transaction->order, $transaction);
+        }
+    }
+}

src/Order/Support/OrderStatus.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Modules\Core\Order\Support;
+
+use Lunar\Models\Order;
+use Modules\Core\Order\Enums\FulfillmentStatus;
+use Modules\Core\Order\Enums\PaymentStatus;
+use Modules\Core\Shipping\Enums\TrackingStatus;
+
+/**
+ * Payment/fulfillment state, derived on read from transactions and
+ * shipments rather than stored — mirrors the logic Lunar's own
+ * ManageOrder::paymentStatus() computes as a Livewire #[Computed] method
+ * (Filament-page-only, not reusable), reimplemented here as a plain,
+ * queryable value any code can call via Order::macro() in
+ * OrderServiceProvider.
+ */
+class OrderStatus
+{
+    public static function payment(Order $order): PaymentStatus
+    {
+        $transactions = $order->transactions;
+
+        $intentTotal = $transactions
+            ->filter(fn ($t) => $t->type === 'intent' && $t->success)
+            ->sum('amount.value');
+
+        $captureTotal = $transactions
+            ->filter(fn ($t) => $t->type === 'capture' && $t->success)
+            ->sum('amount.value');
+
+        $refundTotal = $transactions
+            ->filter(fn ($t) => $t->type === 'refund' && $t->success)
+            ->sum('amount.value');
+
+        $total = $intentTotal ?: $captureTotal;
+
+        if (! $total) {
+            return PaymentStatus::Offline;
+        }
+
+        if (
+            ($refundTotal && $refundTotal < $total) ||
+            ($captureTotal && $captureTotal < $intentTotal)
+        ) {
+            return PaymentStatus::PartialRefund;
+        }
+
+        if ($refundTotal >= $total) {
+            return PaymentStatus::Refunded;
+        }
+
+        if ($captureTotal >= $intentTotal) {
+            return PaymentStatus::Captured;
+        }
+
+        return PaymentStatus::Uncaptured;
+    }
+
+    /**
+     * Reads shipments.shipmentInfo if already eager-loaded (the caller's
+     * job — e.g. Order::with('shipments.shipmentInfo')) and picks the
+     * latest checkpoint in PHP, instead of Shipment::latestShipmentInfo()'s
+     * per-shipment query — calling this across a list of orders would
+     * otherwise be an extra query per shipment.
+     */
+    public static function fulfillment(Order $order): FulfillmentStatus
+    {
+        $shipments = $order->shipments->reject(fn ($shipment) => $shipment->cancelled_at !== null);
+
+        if ($shipments->isEmpty()) {
+            return FulfillmentStatus::Unfulfilled;
+        }
+
+        $latestStatuses = $shipments->map(function ($shipment) {
+            $latest = $shipment->relationLoaded('shipmentInfo')
+                ? $shipment->shipmentInfo->sortByDesc('occurred_at')->first()
+                : $shipment->latestShipmentInfo();
+
+            return $latest?->status ?? TrackingStatus::Pending;
+        });
+
+        if ($latestStatuses->every(fn (TrackingStatus $status) => $status === TrackingStatus::Delivered)) {
+            return FulfillmentStatus::Delivered;
+        }
+
+        if ($latestStatuses->contains(fn (TrackingStatus $status) => $status === TrackingStatus::Delivered)) {
+            return FulfillmentStatus::PartiallyShipped;
+        }
+
+        return FulfillmentStatus::Shipped;
+    }
+}

src/Providers/OrderServiceProvider.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Modules\Core\Providers;
+
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\ServiceProvider;
+use Lunar\Models\Order;
+use Lunar\Models\Transaction;
+use Modules\Core\Notification\NotificationRegistry;
+use Modules\Core\Order\Listeners\DeriveOrderDeliveredFromShipment;
+use Modules\Core\Order\Notifications\OrderCapturedNotification;
+use Modules\Core\Order\Notifications\OrderDeliveredNotification;
+use Modules\Core\Order\Notifications\OrderRefundedNotification;
+use Modules\Core\Order\Notifications\OrderStatusUpdatedNotification;
+use Modules\Core\Order\Observers\OrderObserver;
+use Modules\Core\Order\Observers\TransactionObserver;
+use Modules\Core\Order\Support\OrderStatus;
+use Modules\Core\Shipping\Events\ShipmentStatusUpdatedByCarrier;
+
+class OrderServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        Order::observe(OrderObserver::class);
+        Transaction::observe(TransactionObserver::class);
+
+        Order::macro('paymentStatus', fn () => OrderStatus::payment($this));
+        Order::macro('fulfillmentStatus', fn () => OrderStatus::fulfillment($this));
+
+        Event::listen(ShipmentStatusUpdatedByCarrier::class, DeriveOrderDeliveredFromShipment::class);
+
+        NotificationRegistry::get()->register([
+            OrderDeliveredNotification::class,
+            OrderStatusUpdatedNotification::class,
+            OrderRefundedNotification::class,
+            OrderCapturedNotification::class,
+        ]);
+
+        // Lets the consuming app override copy/markup without forking core
+        // — published into resources/views/vendor/core/order/notifications,
+        // which loadViewsFrom() (CoreServiceProvider) already resolves
+        // ahead of the package's own views for the `core::` namespace.
+        $this->publishes([
+            __DIR__ . '/../../resources/views/order/notifications' => resource_path('views/vendor/core/order/notifications'),
+        ], 'core-views');
+    }
+}