@fleetbase/fleetops-engine 0.6.51 → 0.6.53

package/server/migrations/2026_06_15_000001_normalize_device_attachable_vehicle_morph_types.php

@@ -0,0 +1,30 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Vehicle;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        if (!Schema::hasTable('devices') || !Schema::hasColumn('devices', 'attachable_type') || !Schema::hasColumn('devices', 'attachable_uuid')) {
+            return;
+        }
+
+        DB::table('devices')
+            ->whereNotNull('attachable_uuid')
+            ->whereIn('attachable_type', [
+                'Fleetbase\\Models\\Vehicle',
+                '\\Fleetbase\\Models\\Vehicle',
+            ])
+            ->update([
+                'attachable_type' => Vehicle::class,
+            ]);
+    }
+
+    public function down(): void
+    {
+        // Intentionally do not restore invalid legacy morph class names.
+    }
+};

package/server/src/Console/Commands/FixInvalidPolymorphicRelationTypeNamespaces.php

@@ -37,6 +37,7 @@ class FixInvalidPolymorphicRelationTypeNamespaces extends Command
             ['model' => \Fleetbase\FleetOps\Models\Place::class, 'columns' => ['owner_type']],
             ['model' => \Fleetbase\FleetOps\Models\Entity::class, 'columns' => ['customer_type']],
             ['model' => \Fleetbase\FleetOps\Models\PurchaseRate::class, 'columns' => ['customer_type']],
+            ['model' => \Fleetbase\FleetOps\Models\Device::class, 'columns' => ['attachable_type']],
         ];
 
         foreach ($models as $modelConfig) {

package/server/src/Contracts/FuelProvider.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Contracts;
+
+use Fleetbase\FleetOps\Models\FuelProviderConnection;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+
+interface FuelProvider
+{
+    public function key(): string;
+
+    public function name(): string;
+
+    public function authenticate(FuelProviderConnection $connection): array;
+
+    public function testConnection(FuelProviderConnection $connection): array;
+
+    public function listVehicles(FuelProviderConnection $connection, array $options = []): Collection;
+
+    public function listTransactions(FuelProviderConnection $connection, Carbon $from, Carbon $to, array $options = []): Collection;
+
+    public function listStations(FuelProviderConnection $connection, array $options = []): Collection;
+
+    public function pushTrip(FuelProviderConnection $connection, array $trip): array;
+
+    public function syncVehicle(FuelProviderConnection $connection, array $vehicle): array;
+
+    public function webhookPayloadToTransaction(FuelProviderConnection $connection, array $payload): ?array;
+}

package/server/src/Contracts/TelematicProviderDescriptor.php

@@ -12,6 +12,8 @@ use Fleetbase\FleetOps\Support\Utils;
  */
 class TelematicProviderDescriptor
 {
+    public const DEFAULT_ICON = '/engines-dist/images/telematics/providers/default.webp';
+
     public string $key;
     public string $label;
     public string $type; // 'native' or 'custom'
@@ -33,7 +35,7 @@ class TelematicProviderDescriptor
         $this->label             = $data['label'];
         $this->type              = $data['type'] ?? 'native';
         $this->driverClass       = $data['driver_class'] ?? null;
-        $this->icon              = $data['icon'] ?? null;
+        $this->icon              = $data['icon'] ?? self::DEFAULT_ICON;
         $this->description       = $data['description'] ?? null;
         $this->docsUrl           = $data['docs_url'] ?? null;
         $this->requiredFields    = $data['required_fields'] ?? [];

package/server/src/Events/FuelProviderTransactionImported.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\FuelProviderTransaction;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FuelProviderTransactionImported
+{
+    use Dispatchable;
+    use SerializesModels;
+
+    public function __construct(public FuelProviderTransaction $transaction)
+    {
+    }
+}

package/server/src/Events/FuelProviderTransactionMatched.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\FuelProviderTransaction;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FuelProviderTransactionMatched
+{
+    use Dispatchable;
+    use SerializesModels;
+
+    public function __construct(public FuelProviderTransaction $transaction)
+    {
+    }
+}

package/server/src/Events/FuelProviderTransactionUnmatched.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\FuelProviderTransaction;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FuelProviderTransactionUnmatched
+{
+    use Dispatchable;
+    use SerializesModels;
+
+    public function __construct(public FuelProviderTransaction $transaction)
+    {
+    }
+}

package/server/src/Events/FuelReportCreatedFromProvider.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\FuelProviderTransaction;
+use Fleetbase\FleetOps\Models\FuelReport;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FuelReportCreatedFromProvider
+{
+    use Dispatchable;
+    use SerializesModels;
+
+    public function __construct(public FuelProviderTransaction $transaction, public FuelReport $fuelReport)
+    {
+    }
+}

package/server/src/Http/Controllers/Internal/v1/AnalyticsController.php

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics;
 use Fleetbase\FleetOps\Support\Analytics\FuelEfficiency;
+use Fleetbase\FleetOps\Support\Analytics\FuelProviderSummary;
 use Fleetbase\FleetOps\Support\Analytics\GeofenceViolations;
 use Fleetbase\FleetOps\Support\Analytics\IssuesInsights;
 use Fleetbase\FleetOps\Support\Analytics\LiveFleet;
@@ -64,6 +65,11 @@ class AnalyticsController extends Controller
         return $this->run($request, FuelEfficiency::class, defaultDays: 90);
     }
 
+    public function fuelProviders(Request $request)
+    {
+        return $this->run($request, FuelProviderSummary::class, defaultDays: 30);
+    }
+
     public function issuesInsights(Request $request)
     {
         return $this->run($request, IssuesInsights::class);

package/server/src/Http/Controllers/Internal/v1/DeviceController.php

@@ -3,6 +3,11 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Log;
 
 class DeviceController extends FleetOpsController
 {
@@ -21,7 +26,23 @@ class DeviceController extends FleetOpsController
      */
     public static function onQueryRecord($query, $request): void
     {
-        $query->with(['telematic', 'warranty']);
+        $query->with(['telematic', 'warranty', 'attachable']);
+
+        if ($request->filled('attachment_state')) {
+            match ($request->input('attachment_state')) {
+                'attached'   => $query->whereNotNull('attachable_uuid'),
+                'unattached' => $query->whereNull('attachable_uuid'),
+                default      => null,
+            };
+        }
+
+        if ($request->filled('vehicle')) {
+            $query->where('attachable_uuid', $request->input('vehicle'));
+        }
+
+        if ($request->filled('device_id')) {
+            $query->where('device_id', 'like', '%' . $request->input('device_id') . '%');
+        }
     }
 
     /**
@@ -32,6 +53,123 @@ class DeviceController extends FleetOpsController
      */
     public static function onFindRecord($query, $request): void
     {
-        $query->with(['telematic', 'warranty']);
+        $query->with(['telematic', 'warranty', 'attachable']);
+    }
+
+    /**
+     * Attach a device to a supported FleetOps resource.
+     */
+    public function attach(Request $request, string $id): JsonResponse
+    {
+        $request->validate([
+            'vehicle' => 'required_without:attachable_uuid|nullable|string',
+        ]);
+
+        $vehicleId = $request->input('vehicle') ?? $request->input('attachable_uuid');
+        $device    = $this->resolveDevice($id);
+        $vehicle   = $this->resolveVehicle($vehicleId);
+
+        if (!$device) {
+            $this->logDeviceAttachmentLookupFailure('attach', 'device', $id, $vehicleId);
+
+            return response()->error('Device not found or not available for this organization.', 404);
+        }
+
+        if (!$vehicle) {
+            $this->logDeviceAttachmentLookupFailure('attach', 'vehicle', $id, $vehicleId);
+
+            return response()->error('Vehicle not found or not available for this organization.', 404);
+        }
+
+        try {
+            $device->attachTo($vehicle);
+            $device->load(['telematic', 'warranty', 'attachable']);
+        } catch (\Throwable $e) {
+            $this->logDeviceAttachmentFailure('attach', $device, $vehicle, $e);
+
+            return response()->error('Unable to attach device to vehicle. Please try again or contact support.', 500);
+        }
+
+        return response()->json([
+            'status' => 'ok',
+            'device' => $device,
+        ]);
+    }
+
+    /**
+     * Detach a device from its current FleetOps resource.
+     */
+    public function detach(string $id): JsonResponse
+    {
+        $device = $this->resolveDevice($id);
+
+        if (!$device) {
+            $this->logDeviceAttachmentLookupFailure('detach', 'device', $id, null);
+
+            return response()->error('Device not found or not available for this organization.', 404);
+        }
+
+        try {
+            $device->detach();
+            $device->load(['telematic', 'warranty', 'attachable']);
+        } catch (\Throwable $e) {
+            $this->logDeviceAttachmentFailure('detach', $device, null, $e);
+
+            return response()->error('Unable to detach device from vehicle. Please try again or contact support.', 500);
+        }
+
+        return response()->json([
+            'status' => 'ok',
+            'device' => $device,
+        ]);
+    }
+
+    protected function resolveDevice(string $id): ?Device
+    {
+        return Device::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('public_id', $id);
+        })
+            ->where('company_uuid', session('company'))
+            ->first();
+    }
+
+    protected function resolveVehicle(?string $id): ?Vehicle
+    {
+        if (!$id) {
+            return null;
+        }
+
+        return Vehicle::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('public_id', $id);
+        })
+            ->where('company_uuid', session('company'))
+            ->first();
+    }
+
+    protected function logDeviceAttachmentLookupFailure(string $action, string $missingResource, string $deviceId, ?string $vehicleId): void
+    {
+        Log::warning('Device attachment lookup failed', [
+            'action'           => $action,
+            'missing_resource' => $missingResource,
+            'device_id'        => $deviceId,
+            'vehicle_id'       => $vehicleId,
+            'company_uuid'     => session('company'),
+            'request_id'       => request()->headers->get('X-Request-ID') ?? request()->headers->get('X-Correlation-ID'),
+        ]);
+    }
+
+    protected function logDeviceAttachmentFailure(string $action, Device $device, ?Vehicle $vehicle, \Throwable $exception): void
+    {
+        Log::error('Device attachment failed', [
+            'action'          => $action,
+            'device_uuid'     => $device->uuid,
+            'device_id'       => $device->public_id,
+            'vehicle_uuid'    => $vehicle?->uuid,
+            'vehicle_id'      => $vehicle?->public_id,
+            'company_uuid'    => session('company'),
+            'request_id'      => request()->headers->get('X-Request-ID') ?? request()->headers->get('X-Correlation-ID'),
+            'exception_class' => get_class($exception),
+            'exception'       => $exception->getMessage(),
+        ]);
     }
 }

package/server/src/Http/Controllers/Internal/v1/DeviceEventController.php

@@ -3,6 +3,8 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Models\DeviceEvent;
+use Illuminate\Http\JsonResponse;
 
 class DeviceEventController extends FleetOpsController
 {
@@ -12,4 +14,46 @@ class DeviceEventController extends FleetOpsController
      * @var string
      */
     public $resource = 'device-event';
+
+    /**
+     * Query callback when querying record.
+     *
+     * @param \Illuminate\Database\Query\Builder $query
+     * @param Request                            $request
+     */
+    public static function onQueryRecord($query, $request): void
+    {
+        $query->with(['device']);
+
+        if ($request->filled('telematic')) {
+            $query->whereHas('device', function ($deviceQuery) use ($request) {
+                $deviceQuery->where('telematic_uuid', $request->input('telematic'));
+            });
+        }
+
+        if ($request->filled('processed')) {
+            match ($request->input('processed')) {
+                'processed'   => $query->whereNotNull('processed_at'),
+                'unprocessed' => $query->whereNull('processed_at'),
+                default       => null,
+            };
+        }
+    }
+
+    public function markProcessed(string $id): JsonResponse
+    {
+        $deviceEvent = DeviceEvent::where('company_uuid', session('company'))
+            ->where(function ($query) use ($id) {
+                $query->where('uuid', $id)->orWhere('public_id', $id);
+            })
+            ->firstOrFail();
+
+        $processed = $deviceEvent->markAsProcessed();
+
+        return response()->json([
+            'status'       => 'ok',
+            'message'      => $processed ? 'Event marked processed.' : 'Event was already processed.',
+            'device_event' => $deviceEvent->fresh(),
+        ]);
+    }
 }

package/server/src/Http/Controllers/Internal/v1/DriverController.php

@@ -6,12 +6,13 @@ use Fleetbase\Exceptions\FleetbaseRequestValidationException;
 use Fleetbase\FleetOps\Exports\DriverExport;
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\DriverController as ApiDriverController;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
-use Fleetbase\FleetOps\Http\Requests\Internal\AssignOrderRequest;
 use Fleetbase\FleetOps\Http\Requests\Internal\CreateDriverRequest;
 use Fleetbase\FleetOps\Http\Requests\Internal\UpdateDriverRequest;
+use Fleetbase\FleetOps\Http\Resources\v1\Index\Order as IndexOrderResource;
 use Fleetbase\FleetOps\Imports\DriverImport;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
@@ -21,6 +22,7 @@ use Fleetbase\Models\User;
 use Fleetbase\Models\VerificationCode;
 use Fleetbase\Support\Auth;
 use Illuminate\Database\QueryException;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Validator;
@@ -303,7 +305,7 @@ class DriverController extends FleetOpsController
                 function (&$request, &$driver, &$input) {
                     $driver->load(['user'])->guard(['user_uuid']);
                     $input     = collect($input);
-                    $userInput = $input->only(['name', 'password', 'email', 'phone', 'avatar_uuid'])->toArray();
+                    $userInput = $input->only(['name', 'password', 'email', 'phone', 'avatar_uuid'])->reject(fn ($value) => $value === null)->toArray();
                     // handle `photo_uuid`
                     if (isset($input['photo_uuid']) && Str::isUuid($input['photo_uuid'])) {
                         $userInput['avatar_uuid'] = $input['photo_uuid'];
@@ -312,9 +314,8 @@ class DriverController extends FleetOpsController
 
                     // Update driver user details
                     $driverUser = $driver->getUser();
-                    if ($driverUser) {
+                    if ($driverUser && !empty($userInput)) {
                         $driverUser->update($userInput);
-                        $input['slug'] = $driverUser->slug;
                     }
 
                     // Flush cache
@@ -396,10 +397,18 @@ class DriverController extends FleetOpsController
      *
      * @return \Illuminate\Http\Response $response
      */
-    public function assignOrder(AssignOrderRequest $request)
+    public function assignOrder(Request $request, ?string $id = null)
     {
-        $driver = Driver::where('public_id', $request->driver)->first();
-        $order  = Order::where('public_id', $request->order)->first();
+        $request->validate([
+            'driver' => ($id ? 'nullable' : 'required') . '|string',
+            'order'  => 'required|string',
+        ]);
+
+        $driverIdentifier = $id ?? $request->input('driver');
+        $orderIdentifier  = $request->input('order');
+
+        $driver = $this->findDriver($driverIdentifier);
+        $order  = $this->findOrder($orderIdentifier);
 
         if ($order->hasDriverAssigned) {
             return response()->error('A driver is already assigned to this order.');
@@ -410,13 +419,155 @@ class DriverController extends FleetOpsController
         }
 
         $order->assignDriver($driver);
+        $driver->update(['current_job_uuid' => $order->uuid]);
 
         return response()->json([
             'status'  => 'ok',
             'message' => 'Driver assigned',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'order'   => $order->fresh(['driverAssigned']),
+        ]);
+    }
+
+    public function assignedOrders(string $id): JsonResponse
+    {
+        $driver = $this->findDriver($id);
+        $orders = Order::where('driver_assigned_uuid', $driver->uuid)
+            ->where('company_uuid', session('company'))
+            ->with(['payload', 'trackingNumber', 'orderConfig', 'driverAssigned', 'vehicleAssigned'])
+            ->orderByRaw('uuid = ? desc', [$driver->current_job_uuid])
+            ->latest()
+            ->get();
+
+        return response()->json([
+            'status'  => 'ok',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'orders'  => IndexOrderResource::collection($orders)->resolve(),
+            'current' => $driver->current_job_uuid,
+            'count'   => $orders->count(),
+        ]);
+    }
+
+    public function unassignOrders(Request $request, string $id): JsonResponse
+    {
+        $request->validate([
+            'orders'   => 'required|array|min:1',
+            'orders.*' => 'required|string',
+        ]);
+
+        $driver = $this->findDriver($id);
+        $ids    = collect($request->input('orders'))->filter()->unique()->values();
+        $orders = Order::where('driver_assigned_uuid', $driver->uuid)
+            ->where('company_uuid', session('company'))
+            ->where(function ($query) use ($ids) {
+                $query->whereIn('uuid', $ids)->orWhereIn('public_id', $ids);
+            })
+            ->get();
+
+        if ($orders->isEmpty()) {
+            return response()->error('No assigned orders were selected for this driver.');
+        }
+
+        DB::transaction(function () use ($driver, $orders): void {
+            Order::whereIn('uuid', $orders->pluck('uuid'))->update([
+                'driver_assigned_uuid' => null,
+                'updated_at'           => now(),
+            ]);
+
+            if ($driver->current_job_uuid && $orders->contains('uuid', $driver->current_job_uuid)) {
+                $driver->update(['current_job_uuid' => null]);
+            }
+        });
+
+        return response()->json([
+            'status'  => 'ok',
+            'message' => 'Driver unassigned from selected orders.',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'orders'  => IndexOrderResource::collection($orders->fresh(['driverAssigned', 'vehicleAssigned']))->resolve(),
+            'count'   => $orders->count(),
+        ]);
+    }
+
+    public function unassignOrder(string $id): JsonResponse
+    {
+        $driver = $this->findDriver($id);
+        $order  = Order::where('driver_assigned_uuid', $driver->uuid)
+            ->where('company_uuid', session('company'))
+            ->first() ?? $driver->getCurrentOrder();
+
+        if ($order) {
+            $order->update(['driver_assigned_uuid' => null]);
+        }
+
+        $driver->unassignCurrentJob();
+
+        return response()->json([
+            'status'  => 'ok',
+            'message' => 'Driver unassigned from order.',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'order'   => $order?->fresh(['driverAssigned']),
         ]);
     }
 
+    public function assignVehicle(Request $request, string $id): JsonResponse
+    {
+        $request->validate(['vehicle' => 'required|string']);
+
+        $driver  = $this->findDriver($id);
+        $vehicle = $this->findVehicle($request->input('vehicle'));
+
+        $driver->assignVehicle($vehicle);
+
+        return response()->json([
+            'status'  => 'ok',
+            'message' => 'Vehicle assigned to driver.',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'vehicle' => $vehicle->fresh(['driver']),
+        ]);
+    }
+
+    public function unassignVehicle(string $id): JsonResponse
+    {
+        $driver  = $this->findDriver($id);
+        $vehicle = $driver->vehicle;
+
+        $driver->update(['vehicle_uuid' => null]);
+
+        return response()->json([
+            'status'  => 'ok',
+            'message' => 'Vehicle unassigned from driver.',
+            'driver'  => $driver->fresh(['vehicle', 'currentOrder']),
+            'vehicle' => $vehicle?->fresh(['driver']),
+        ]);
+    }
+
+    protected function findDriver(?string $id): Driver
+    {
+        return Driver::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('public_id', $id);
+        })
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+    }
+
+    protected function findOrder(?string $id): Order
+    {
+        return Order::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('public_id', $id);
+        })
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+    }
+
+    protected function findVehicle(?string $id): Vehicle
+    {
+        return Vehicle::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('public_id', $id);
+        })
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+    }
+
     /**
      * Update drivers geolocation data.
      *