@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Models/TrackingSessionGrant.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Fleetbase\FleetOps\Models;
+
+use Fleetbase\Models\Model;
+use Fleetbase\Traits\HasUuid;
+
+/**
+ * What a verified device may see: one customer within one order, until `expires_at`.
+ */
+class TrackingSessionGrant extends Model
+{
+    use HasUuid;
+
+    protected $table = 'tracking_session_grants';
+
+    protected $fillable = ['tracking_session_uuid', 'company_uuid', 'order_uuid', 'customer_type', 'customer_uuid', 'channel', 'expires_at'];
+
+    protected $casts = [
+        'expires_at' => 'datetime',
+    ];
+}

package/server/src/Models/TrackingStatus.php

@@ -7,6 +7,7 @@ use Fleetbase\FleetOps\Casts\Point;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\LaravelMysqlSpatial\Eloquent\SpatialTrait;
 use Fleetbase\Models\Model;
+use Fleetbase\Support\ApiModelCache;
 use Fleetbase\Traits\HasApiModelBehavior;
 use Fleetbase\Traits\HasMetaAttributes;
 use Fleetbase\Traits\HasPublicId;
@@ -177,6 +178,11 @@ class TrackingStatus extends Model
 
         $result = static::insertTrackingStatus($values);
 
+        // Inserted without model events
+        if ($result) {
+            ApiModelCache::invalidateModelCache($instance, $values['company_uuid']);
+        }
+
         return $result ? $uuid : false;
     }
 

package/server/src/Models/Vehicle.php

@@ -81,6 +81,23 @@ class Vehicle extends Model
      */
     protected $with = [];
 
+    /**
+     * Relation paths the cached vehicle lists embed or filter on (fleetbase/core-api#301).
+     *
+     * The public list loads vendor (with its place), category, warranty and
+     * driver; driver, current trailers (through asset_connections) and fleets
+     * (through fleet_vehicles) decide which vehicles the filters return.
+     * photo is left out: files is written by every upload, and a new photo is
+     * set by writing the vehicle's own photo_uuid. devices is left out too: the
+     * device filters only read which devices are attached, but telemetry saves
+     * the device row on every ping, which would keep vehicle lists from ever
+     * being served from cache. Device::attachTo() and detach() invalidate the
+     * vehicle lists instead.
+     *
+     * @var string[]
+     */
+    protected $apiCacheDependencies = ['vendor', 'vendor.place', 'category', 'warranty', 'driver', 'currentTrailers', 'fleets'];
+
     /**
      * Get the activity log options for the model.
      */
@@ -525,7 +542,8 @@ class Vehicle extends Model
             return static::getAvatar($value);
         }
 
-        return $value;
+        // legacy rows hold an absolute URL; re-sign it if it points into the private media bucket
+        return Utils::signStoredFileUrl($value);
     }
 
     /**
@@ -628,6 +646,7 @@ class Vehicle extends Model
     public function unassignDriver(): self
     {
         Driver::where('vehicle_uuid', $this->uuid)->update(['vehicle_uuid' => null]);
+        Driver::invalidateApiCacheManually($this->company_uuid);
         $this->unsetRelation('driver');
 
         return $this;
@@ -794,7 +813,7 @@ class Vehicle extends Model
             return null;
         }
 
-        return static::where(function ($query) use ($vehicleName) {
+        return static::where('company_uuid', session('company'))->where(function ($query) use ($vehicleName) {
             $query->where('public_id', $vehicleName)
                     ->orWhere('internal_id', $vehicleName)
                     ->orWhere('plate_number', $vehicleName)

package/server/src/Models/Vendor.php

@@ -117,6 +117,13 @@ class Vendor extends Model
      */
     protected $with = ['place'];
 
+    /**
+     * Relation paths the cached vendor lists embed through `$with` (fleetbase/core-api#301).
+     *
+     * @var string[]
+     */
+    protected $apiCacheDependencies = ['place'];
+
     /**
      * Get the activity log options for the model.
      */

package/server/src/Models/Waypoint.php

@@ -8,6 +8,7 @@ use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\FleetOps\Traits\HasTrackingNumber;
 use Fleetbase\FleetOps\Traits\PayloadAccessors;
 use Fleetbase\Models\Model;
+use Fleetbase\Traits\HasApiModelCache;
 use Fleetbase\Traits\HasPublicId;
 use Fleetbase\Traits\HasUuid;
 use Fleetbase\Traits\TracksApiCredential;
@@ -20,6 +21,8 @@ use Illuminate\Support\Str;
 class Waypoint extends Model
 {
     use HasUuid;
+    // Writes bump the waypoints API cache version, which cached order lists embed.
+    use HasApiModelCache;
     use HasPublicId;
     use TracksApiCredential;
     use HasTrackingNumber;
@@ -221,16 +224,22 @@ class Waypoint extends Model
         if ($result && $payload) {
             // create tracking number for entity
             $trackingNumberId = static::createTrackingNumber([
-                'owner_uuid' => $uuid,
-                'owner_type' => Utils::getModelClassName('waypoint'),
-                'region'     => $payload->getPickupRegion(),
-                'location'   => static::pickupLocationWkt($payload),
+                'owner_uuid'      => $uuid,
+                'owner_type'      => Utils::getModelClassName('waypoint'),
+                'owner_public_id' => $values['public_id'],
+                'region'          => $payload->getPickupRegion(),
+                'location'        => static::pickupLocationWkt($payload),
             ]);
 
             // set tracking number
             static::updateTrackingNumberUuid($uuid, $trackingNumberId);
         }
 
+        // Inserted and updated without model events
+        if ($result) {
+            static::invalidateApiCacheManually($values['company_uuid']);
+        }
+
         return $result ? $uuid : false;
     }
 

package/server/src/Notifications/OrderAssigned.php

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Notifications;
 
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -128,7 +129,7 @@ class OrderAssigned extends Notification implements ShouldQueue
             $message->line('Dispatch is scheduled for ' . $this->order->scheduled_at);
         }
 
-        $message->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->order->trackingNumber->tracking_number]));
+        $message->action('Track Order', TrackingCode::pageUrl($this->order->trackingNumber->tracking_number, data_get($this, 'order.company_uuid')));
 
         return $message;
     }

package/server/src/Notifications/OrderCanceled.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Notifications;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -81,6 +82,11 @@ class OrderCanceled extends Notification implements ShouldQueue
         $this->title       = 'Order ' . $this->getTrackingNumber() . ' was canceled';
         $this->message     = 'Order ' . $this->getTrackingNumber() . ' has been canceled.';
         $this->data        = ['id' => $this->order->public_id, 'type' => 'order_canceled'];
+
+        // apps show why the order was canceled when a reason was given
+        if ($reason !== '') {
+            $this->data['reason'] = $reason;
+        }
     }
 
     /**
@@ -138,7 +144,7 @@ class OrderCanceled extends Notification implements ShouldQueue
             ->line($this->message)
             ->line($this->reason)
             ->line('No further action is necessary.')
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->getTrackingNumber()]));
+            ->action('Track Order', TrackingCode::pageUrl($this->getTrackingNumber(), data_get($this, 'order.company_uuid')));
     }
 
     /**

package/server/src/Notifications/OrderChanged.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Fleetbase\FleetOps\Notifications;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Support\PushNotification;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Notifications\Notification;
+use NotificationChannels\Apn\ApnChannel;
+use NotificationChannels\Fcm\FcmChannel;
+
+/**
+ * Tells the assigned driver that an order they have changed.
+ *
+ * Push data: { type: "order_changed", id: order public id, changes: [...] }.
+ */
+class OrderChanged extends Notification implements ShouldQueue
+{
+    use Queueable;
+
+    public static string $name        = 'Order Changed';
+    public static string $description = 'Notify the assigned driver when an order they have is changed.';
+    public static string $package     = 'fleet-ops';
+
+    public Order $order;
+
+    public array $changes = [];
+
+    public string $title;
+
+    public string $message;
+
+    public array $data = [];
+
+    public function __construct(Order $order, array $changes = [], string $summary = '')
+    {
+        $this->order   = $order;
+        $this->changes = array_values($changes);
+        $this->title   = 'Order ' . (data_get($order, 'trackingNumber.tracking_number') ?? $order->public_id) . ' changed';
+        $this->message = $summary !== '' ? $summary : 'This order was changed, tap for details.';
+        $this->data    = ['type' => 'order_changed', 'id' => $order->public_id, 'changes' => $this->changes];
+    }
+
+    public function via($notifiable): array
+    {
+        return ['broadcast', FcmChannel::class, ApnChannel::class];
+    }
+
+    public function broadcastOn(): array
+    {
+        return [
+            new Channel('driver.' . data_get($this->order, 'driver_assigned_uuid')),
+            new Channel('driver.' . data_get($this->order, 'driverAssigned.public_id')),
+        ];
+    }
+
+    public function toArray($notifiable = null): array
+    {
+        return [
+            'event' => 'order.changed_notification',
+            'title' => $this->title,
+            'body'  => $this->message,
+            'data'  => $this->data,
+        ];
+    }
+
+    public function toFcm($notifiable)
+    {
+        return PushNotification::createFcmMessage($this->title, $this->message, $this->fcmData());
+    }
+
+    public function toApn($notifiable)
+    {
+        return PushNotification::createApnMessage($this->title, $this->message, $this->data, 'view_order');
+    }
+
+    /**
+     * FCM data values must be strings, so on FCM the change list travels comma
+     * separated ("dropoff,items"); APNs and the broadcast carry it as a list.
+     */
+    public function fcmData(): array
+    {
+        return array_merge($this->data, ['changes' => implode(',', $this->changes)]);
+    }
+}

package/server/src/Notifications/OrderCompleted.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Notifications;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -131,7 +132,7 @@ class OrderCompleted extends Notification implements ShouldQueue
             ->subject($this->title)
             ->line($this->message)
             ->line('No further action is necessary.')
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->getTrackingNumber()]));
+            ->action('Track Order', TrackingCode::pageUrl($this->getTrackingNumber(), data_get($this, 'order.company_uuid')));
     }
 
     /**

package/server/src/Notifications/OrderDispatchFailed.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Notifications;
 use Fleetbase\FleetOps\Events\OrderDispatchFailed as OrderDispatchFailedEvent;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Illuminate\Broadcasting\Channel;
 use Illuminate\Bus\Queueable;
@@ -127,6 +128,6 @@ class OrderDispatchFailed extends Notification implements ShouldQueue
         return (new MailMessage())
             ->subject($this->title)
             ->line($this->message)
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->order->trackingNumber->tracking_number]));
+            ->action('Track Order', TrackingCode::pageUrl($this->order->trackingNumber->tracking_number, data_get($this, 'order.company_uuid')));
     }
 }

package/server/src/Notifications/OrderDispatched.php

@@ -6,6 +6,7 @@ use Fleetbase\Events\ResourceLifecycleEvent;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -170,7 +171,7 @@ class OrderDispatched extends Notification implements ShouldQueue
         return (new MailMessage())
             ->subject($this->title)
             ->line($this->message)
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->getTrackingNumber()]));
+            ->action('Track Order', TrackingCode::pageUrl($this->getTrackingNumber(), data_get($this, 'order.company_uuid')));
     }
 
     /**

package/server/src/Notifications/OrderFailed.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Notifications;
 use Fleetbase\FleetOps\Http\Resources\v1\Order as OrderResource;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -138,7 +139,7 @@ class OrderFailed extends Notification implements ShouldQueue
             ->line($this->message)
             ->line($this->reason)
             ->line('No further action is necessary.')
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->getTrackingNumber()]));
+            ->action('Track Order', TrackingCode::pageUrl($this->getTrackingNumber(), data_get($this, 'order.company_uuid')));
     }
 
     /**

package/server/src/Notifications/OrderUnassigned.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace Fleetbase\FleetOps\Notifications;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Support\PushNotification;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Notifications\Notification;
+use NotificationChannels\Apn\ApnChannel;
+use NotificationChannels\Fcm\FcmChannel;
+
+/**
+ * Tells a driver that an order was taken off them (unassigned or reassigned).
+ *
+ * Push data: { type: "order_unassigned", id: order public id }.
+ */
+class OrderUnassigned extends Notification implements ShouldQueue
+{
+    use Queueable;
+
+    public static string $name        = 'Order Unassigned';
+    public static string $description = 'Notify a driver when an order is unassigned from them or reassigned to another driver.';
+    public static string $package     = 'fleet-ops';
+
+    public Order $order;
+
+    public string $title;
+
+    public string $message;
+
+    public array $data = [];
+
+    public function __construct(Order $order)
+    {
+        $this->order   = $order;
+        $this->title   = 'Order ' . (data_get($order, 'trackingNumber.tracking_number') ?? $order->public_id) . ' unassigned';
+        $this->message = 'This order is no longer assigned to you.';
+        $this->data    = ['type' => 'order_unassigned', 'id' => $order->public_id];
+    }
+
+    public function via($notifiable): array
+    {
+        return [FcmChannel::class, ApnChannel::class];
+    }
+
+    public function toArray($notifiable = null): array
+    {
+        return [
+            'event' => 'order.unassigned_notification',
+            'title' => $this->title,
+            'body'  => $this->message,
+            'data'  => $this->data,
+        ];
+    }
+
+    public function toFcm($notifiable)
+    {
+        return PushNotification::createFcmMessage($this->title, $this->message, $this->data);
+    }
+
+    public function toApn($notifiable)
+    {
+        return PushNotification::createApnMessage($this->title, $this->message, $this->data, 'view_order');
+    }
+}

package/server/src/Notifications/WaypointCompleted.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Notifications;
 use Fleetbase\FleetOps\Flow\Activity;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\TrackingCode;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Support\PushNotification;
 use Illuminate\Broadcasting\Channel;
@@ -132,7 +133,7 @@ class WaypointCompleted extends Notification implements ShouldQueue
             ->subject($this->title)
             ->line($this->message)
             ->line('No further action is necessary.')
-            ->action('Track Order', Utils::consoleUrl('track-order', ['order' => $this->waypoint->trackingNumber->tracking_number]));
+            ->action('Track Order', TrackingCode::pageUrl($this->waypoint->trackingNumber->tracking_number, data_get($this, 'waypoint.company_uuid')));
     }
 
     /**

package/server/src/Observers/CompanyUserObserver.php

@@ -14,8 +14,8 @@ class CompanyUserObserver
      */
     public function deleted(CompanyUser $companyUser)
     {
-        // if the company user deleted is a driver, delete their driver record to
-        $this->deleteDrivers($companyUser->user_uuid);
+        // if the company user deleted is a driver, delete their driver record in that company
+        $this->deleteDrivers($companyUser->user_uuid, $companyUser->company_uuid);
     }
 
     /**
@@ -26,19 +26,20 @@ class CompanyUserObserver
     public function updated(CompanyUser $companyUser)
     {
         // If the company user has any driver assosciated update status to same as company_users
-        $driver = $this->findDriver($companyUser->user_uuid);
+        $driver = $this->findDriver($companyUser->user_uuid, $companyUser->company_uuid);
         if ($driver && $companyUser->wasChanged('status')) {
             $driver->update(['status' => $companyUser->status]);
         }
     }
 
-    protected function deleteDrivers(string $userUuid): void
+    protected function deleteDrivers(string $userUuid, ?string $companyUuid): void
     {
-        Driver::where('user_uuid', $userUuid)->delete();
+        // Delete each driver through the model so DriverObserver cleans up after it
+        Driver::where(['user_uuid' => $userUuid, 'company_uuid' => $companyUuid])->get()->each->delete();
     }
 
-    protected function findDriver(string $userUuid): ?Driver
+    protected function findDriver(string $userUuid, ?string $companyUuid): ?Driver
     {
-        return Driver::where('user_uuid', $userUuid)->first();
+        return Driver::where(['user_uuid' => $userUuid, 'company_uuid' => $companyUuid])->first();
     }
 }

package/server/src/Observers/DriverObserver.php

@@ -79,7 +79,12 @@ class DriverObserver
 
     protected function unassignOrders(Driver $driver): int
     {
-        return Order::where(['driver_assigned_uuid' => $driver->uuid])->update(['driver_assigned_uuid' => null]);
+        $unassigned = Order::where(['driver_assigned_uuid' => $driver->uuid])->update(['driver_assigned_uuid' => null]);
+        if ($unassigned > 0) {
+            Order::invalidateApiCacheManually($driver->company_uuid);
+        }
+
+        return $unassigned;
     }
 
     protected function findDriverUser(Driver $driver): ?User

package/server/src/Observers/OrderObserver.php

@@ -2,12 +2,28 @@
 
 namespace Fleetbase\FleetOps\Observers;
 
+use Fleetbase\FleetOps\Models\Entity;
 use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\TrackingStatus;
+use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\FleetOps\Support\LiveCacheService;
+use Fleetbase\FleetOps\Support\TrackingPublisher;
+use Fleetbase\Support\ApiModelCache;
 use Illuminate\Support\Facades\Cache;
 
 class OrderObserver
 {
+    /**
+     * Deletion timestamps captured while an order is being restored, keyed by order uuid.
+     * Restoring clears the order's deleted_at before "restored" fires, so the timestamp the
+     * children were deleted with is read in "restoring" and used once the restore succeeds.
+     *
+     * @var array<string, string>
+     */
+    protected static array $restoringFrom = [];
+
     /**
      * Handle the Order "created" event.
      *
@@ -42,10 +58,21 @@ class OrderObserver
         $order->setDriverLocationAsPickup();
 
         if ($order->wasChanged('driver_assigned_uuid')) {
-            $order->notifyDriverAssigned();
+            // The driver taken off the order hears about it, whether it was unassigned or reassigned.
+            $previousDriverUuid = $order->getOriginal('driver_assigned_uuid');
+            if ($previousDriverUuid) {
+                $order->notifyDriverUnassigned($previousDriverUuid);
+            }
+
+            if (!$order->silentDriverAssignment) {
+                $order->notifyDriverAssigned();
+            }
         }
 
         $this->invalidateCache($order);
+
+        // Public tracking channels follow status, assignment and ETA changes.
+        app(TrackingPublisher::class)->orderChanged($order);
     }
 
     /**
@@ -59,9 +86,122 @@ class OrderObserver
             $order->facilitator->provider()->callback('onDeleted', $order);
         }
 
+        $this->cascadeDelete($order);
+        $this->invalidateCache($order);
+    }
+
+    /**
+     * Handle the Order "restoring" event: remember when the order was deleted.
+     */
+    public function restoring(Order $order): void
+    {
+        if ($order->uuid && $order->deleted_at) {
+            static::$restoringFrom[$order->uuid] = $order->fromDateTime($order->deleted_at);
+        }
+    }
+
+    /**
+     * Handle the Order "restored" event: bring back the children deleted with the order.
+     */
+    public function restored(Order $order): void
+    {
+        $deletedAt = static::$restoringFrom[$order->uuid] ?? null;
+        unset(static::$restoringFrom[$order->uuid]);
+
+        if ($deletedAt) {
+            $this->cascadeRestore($order, $deletedAt);
+        }
+
         $this->invalidateCache($order);
     }
 
+    /**
+     * Soft-deletes what belongs to the order: its tracking number and, unless another live
+     * order shares it, its payload with the payload's entities and waypoints and their
+     * tracking numbers, plus every one of those tracking numbers' statuses. Children are
+     * stamped with the order's own deleted_at so a restore can find exactly those rows.
+     */
+    protected function cascadeDelete(Order $order): void
+    {
+        $deletedAt = $order->fromDateTime($order->deleted_at ?? $order->freshTimestamp());
+        $tree      = $this->childTree($order, Payload::query(), Entity::query(), Waypoint::query());
+
+        if ($tree['payload']) {
+            Payload::where('uuid', $tree['payload'])->update(['deleted_at' => $deletedAt]);
+            Entity::whereIn('uuid', $tree['entities'])->update(['deleted_at' => $deletedAt]);
+            Waypoint::whereIn('uuid', $tree['waypoints'])->update(['deleted_at' => $deletedAt]);
+        }
+
+        $trackingNumbers = TrackingNumber::where(fn ($query) => $query->whereIn('uuid', $tree['tracking_numbers'])->orWhereIn('owner_uuid', $tree['owners']))->pluck('uuid')->all();
+        TrackingStatus::whereIn('tracking_number_uuid', $trackingNumbers)->update(['deleted_at' => $deletedAt]);
+        TrackingNumber::whereIn('uuid', $trackingNumbers)->update(['deleted_at' => $deletedAt]);
+
+        $this->invalidateChildApiCaches($order);
+    }
+
+    /**
+     * Restores the children cascadeDelete() removed: the rows of the same tree whose
+     * deleted_at matches the order's. Children deleted on their own beforehand carry
+     * a different timestamp and stay deleted.
+     */
+    protected function cascadeRestore(Order $order, string $deletedAt): void
+    {
+        $trashed = fn (string $model) => $model::onlyTrashed()->where('deleted_at', $deletedAt);
+        $tree    = $this->childTree($order, $trashed(Payload::class), $trashed(Entity::class), $trashed(Waypoint::class));
+
+        $trackingNumbers = $trashed(TrackingNumber::class)->where(fn ($query) => $query->whereIn('uuid', $tree['tracking_numbers'])->orWhereIn('owner_uuid', $tree['owners']))->pluck('uuid')->all();
+        $trashed(TrackingNumber::class)->whereIn('uuid', $trackingNumbers)->update(['deleted_at' => null]);
+        $trashed(TrackingStatus::class)->whereIn('tracking_number_uuid', $trackingNumbers)->update(['deleted_at' => null]);
+
+        if ($tree['payload']) {
+            $trashed(Payload::class)->where('uuid', $tree['payload'])->update(['deleted_at' => null]);
+            $trashed(Entity::class)->whereIn('uuid', $tree['entities'])->update(['deleted_at' => null]);
+            $trashed(Waypoint::class)->whereIn('uuid', $tree['waypoints'])->update(['deleted_at' => null]);
+        }
+
+        $this->invalidateChildApiCaches($order);
+    }
+
+    /**
+     * The cascades write their tables without model events, so invalidate the API
+     * caches of every table they touch.
+     */
+    protected function invalidateChildApiCaches(Order $order): void
+    {
+        foreach ([Payload::class, Entity::class, Waypoint::class, TrackingNumber::class, TrackingStatus::class] as $modelClass) {
+            ApiModelCache::invalidateModelCache(new $modelClass(), $order->company_uuid);
+        }
+    }
+
+    /**
+     * Collects the uuids under an order from the given payload, entity and waypoint
+     * queries. The payload is left out when another live order still references it.
+     *
+     * @return array{payload: ?string, entities: array, waypoints: array, tracking_numbers: array, owners: array}
+     */
+    protected function childTree(Order $order, $payloads, $entities, $waypoints): array
+    {
+        $tree = ['payload' => null, 'entities' => [], 'waypoints' => [], 'tracking_numbers' => [$order->tracking_number_uuid], 'owners' => [$order->uuid]];
+
+        $shared  = $order->payload_uuid && Order::where('payload_uuid', $order->payload_uuid)->where('uuid', '!=', $order->uuid)->exists();
+        $payload = $order->payload_uuid && !$shared ? $payloads->where('uuid', $order->payload_uuid)->first() : null;
+
+        if ($payload) {
+            $children = $entities->where('payload_uuid', $payload->uuid)->get(['uuid', 'tracking_number_uuid'])
+                ->concat($waypoints->where('payload_uuid', $payload->uuid)->get(['uuid', 'tracking_number_uuid']));
+
+            $tree['payload']          = $payload->uuid;
+            $tree['entities']         = $children->whereInstanceOf(Entity::class)->pluck('uuid')->all();
+            $tree['waypoints']        = $children->whereInstanceOf(Waypoint::class)->pluck('uuid')->all();
+            $tree['tracking_numbers'] = array_merge($tree['tracking_numbers'], [$payload->pickup_tracking_number_uuid, $payload->dropoff_tracking_number_uuid, $payload->return_tracking_number_uuid], $children->pluck('tracking_number_uuid')->all());
+            $tree['owners']           = array_merge($tree['owners'], $children->pluck('uuid')->all());
+        }
+
+        $tree['tracking_numbers'] = array_values(array_filter($tree['tracking_numbers']));
+
+        return $tree;
+    }
+
     /**
      * Invalidate relevant cache tags for live endpoints.
      *