Feature: Shipment Updates to handle COD

src/Shipping/Carriers/BoxNow/BoxNowFulfillmentService.php

@@ -2,9 +2,15 @@
 
 namespace Modules\Core\Shipping\Carriers\BoxNow;
 
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
 use Lunar\Models\Order;
 use Modules\Core\Shipping\Carriers\BoxNow\Exceptions\BoxNowApiException;
 use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
+use Modules\Core\Shipping\Contracts\SupportsTracking;
+use Modules\Core\Shipping\DataTransferObjects\ShipmentRequest;
+use Modules\Core\Shipping\DataTransferObjects\TrackingCheckpoint;
+use Modules\Core\Shipping\Enums\TrackingStatus;
 use Modules\Core\Shipping\Models\Shipment;
 
 /**
@@ -13,28 +19,32 @@ use Modules\Core\Shipping\Models\Shipment;
  * CarrierFulfillmentInterface (not SupportsManifestBatching).
  *
  * Box Now delivers to lockers, not addresses. The storefront locker-picker
- * is out of scope for this pass — createShipment() expects the chosen
- * locker's Box Now locationId via $overrides['locationId'] (e.g. set
- * manually by admin staff until checkout UI exists).
+ * is out of scope for this pass — createShipment() requires the chosen
+ * locker's Box Now locationId via ShipmentRequest::$destinationLocationId
+ * (e.g. set manually by admin staff until checkout UI exists).
  */
-class BoxNowFulfillmentService implements CarrierFulfillmentInterface
+class BoxNowFulfillmentService implements CarrierFulfillmentInterface, SupportsTracking
 {
     public function __construct(private readonly BoxNowClient $client) {}
 
-    public function createShipment(Order $order, array $overrides = []): Shipment
+    public function createShipment(Order $order, ShipmentRequest $request): Shipment
     {
         $address = $order->shippingAddress;
-        $destinationLocationId = $overrides['locationId'] ?? null;
+        $destinationLocationId = $request->destinationLocationId;
 
         if (! $destinationLocationId) {
             throw new BoxNowApiException('No Box Now locker (locationId) was provided for this shipment.');
         }
 
+        $isCod = $request->paymentMode === 'cod';
+
         $response = $this->client->request('post', '/delivery-requests', [
             'orderNumber' => $order->reference.'-'.$order->id,
             'invoiceValue' => number_format($order->total->decimal, 2, '.', ''),
-            'paymentMode' => 'prepaid',
-            'amountToBeCollected' => '0.00',
+            'paymentMode' => $isCod ? 'cod' : 'prepaid',
+            'amountToBeCollected' => $isCod
+                ? number_format($request->amountToCollect ?? $order->total->decimal, 2, '.', '')
+                : '0.00',
             'origin' => [
                 'contactNumber' => config('boxnow.sender.phone'),
                 'contactEmail' => config('boxnow.sender.email'),
@@ -52,8 +62,8 @@ class BoxNowFulfillmentService implements CarrierFulfillmentInterface
                     'id' => (string) $order->id,
                     'name' => 'Order '.$order->reference,
                     'value' => '0.00',
-                    'compartmentSize' => $overrides['compartmentSize'] ?? 1,
-                    'weight' => $overrides['weight'] ?? 0,
+                    'compartmentSize' => 1,
+                    'weight' => $request->weight ?? 0,
                 ],
             ],
         ]);
@@ -89,4 +99,52 @@ class BoxNowFulfillmentService implements CarrierFulfillmentInterface
 
         $shipment->update(['cancelled_at' => now()]);
     }
+
+    public function trackShipment(Shipment $shipment): Collection
+    {
+        $response = $this->client->request('get', '/parcels', [
+            'parcelId' => $shipment->tracking_reference,
+        ]);
+
+        $parcel = $response['data'][0] ?? null;
+
+        if (! $parcel) {
+            return collect();
+        }
+
+        $events = $parcel['events'] ?? [];
+
+        // Fall back to a single checkpoint from the parcel's current state
+        // if Box Now didn't return a detailed events history.
+        if (empty($events)) {
+            $events = [[
+                'type' => $parcel['state'] ?? 'new',
+                'locationDisplayName' => null,
+                'createTime' => $parcel['updateTime'] ?? $parcel['createTime'] ?? now()->toIso8601String(),
+            ]];
+        }
+
+        return collect($events)->map(fn (array $event) => new TrackingCheckpoint(
+            status: $this->mapState($event['type'] ?? $parcel['state'] ?? 'new'),
+            carrierStatus: $event['type'] ?? $parcel['state'] ?? null,
+            message: null,
+            location: $event['locationDisplayName'] ?? null,
+            occurredAt: Carbon::parse($event['createTime']),
+            meta: $event,
+        ));
+    }
+
+    private function mapState(string $state): TrackingStatus
+    {
+        return match ($state) {
+            'new' => TrackingStatus::Pending,
+            'in-transit', 'in-depot' => TrackingStatus::InTransit,
+            'in-final-destination', 'wait-for-load' => TrackingStatus::OutForDelivery,
+            'delivered' => TrackingStatus::Delivered,
+            'returned', 'accepted-for-return' => TrackingStatus::Returned,
+            'cancelled' => TrackingStatus::Cancelled,
+            'expired-return', 'missing' => TrackingStatus::Failed,
+            default => TrackingStatus::Unknown,
+        };
+    }
 }