@fleetbase/fleetops-engine 0.6.51 → 0.6.52

package/server/migrations/2026_06_08_000001_create_fuel_provider_connections_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up()
+    {
+        Schema::create('fuel_provider_connections', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('uuid', 191)->nullable()->unique();
+            $table->string('public_id', 191)->nullable()->unique();
+            $table->uuid('company_uuid')->nullable()->index();
+            $table->string('provider', 80)->index();
+            $table->string('name')->nullable();
+            $table->string('environment', 40)->default('production')->index();
+            $table->string('status', 50)->default('configured')->index();
+            $table->json('credentials')->nullable();
+            $table->json('sync_settings')->nullable();
+            $table->json('last_sync_state')->nullable();
+            $table->timestamp('last_synced_at')->nullable()->index();
+            $table->timestamp('last_tested_at')->nullable();
+            $table->text('last_error')->nullable();
+            $table->json('meta')->nullable();
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->unique(['company_uuid', 'provider', 'environment'], 'fuel_provider_connection_unique');
+        });
+    }
+
+    public function down()
+    {
+        Schema::dropIfExists('fuel_provider_connections');
+    }
+};

package/server/migrations/2026_06_08_000002_create_fuel_provider_transactions_table.php

@@ -0,0 +1,53 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up()
+    {
+        Schema::create('fuel_provider_transactions', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('uuid', 191)->nullable()->unique();
+            $table->string('public_id', 191)->nullable()->unique();
+            $table->uuid('company_uuid')->nullable()->index();
+            $table->uuid('fuel_provider_connection_uuid')->nullable()->index();
+            $table->uuid('fuel_report_uuid')->nullable()->index();
+            $table->uuid('vehicle_uuid')->nullable()->index();
+            $table->uuid('driver_uuid')->nullable()->index();
+            $table->uuid('order_uuid')->nullable()->index();
+            $table->string('provider', 80)->index();
+            $table->string('provider_transaction_id', 191)->index();
+            $table->string('provider_vehicle_id')->nullable()->index();
+            $table->string('vehicle_card_id')->nullable()->index();
+            $table->string('internal_number')->nullable()->index();
+            $table->string('structure_number')->nullable()->index();
+            $table->string('plate_number')->nullable()->index();
+            $table->string('trip_number')->nullable()->index();
+            $table->string('station_name')->nullable()->index();
+            $table->decimal('station_latitude', 10, 7)->nullable();
+            $table->decimal('station_longitude', 10, 7)->nullable();
+            $table->timestamp('transaction_at')->nullable()->index();
+            $table->decimal('volume', 12, 3)->nullable();
+            $table->string('metric_unit', 20)->default('l');
+            $table->unsignedBigInteger('amount')->nullable();
+            $table->string('currency', 10)->default('SAR');
+            $table->string('odometer')->nullable();
+            $table->string('sync_status', 50)->default('imported')->index();
+            $table->timestamp('matched_at')->nullable();
+            $table->json('normalized_payload')->nullable();
+            $table->json('raw_payload')->nullable();
+            $table->json('meta')->nullable();
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->unique(['provider', 'provider_transaction_id'], 'fuel_provider_txn_provider_unique');
+        });
+    }
+
+    public function down()
+    {
+        Schema::dropIfExists('fuel_provider_transactions');
+    }
+};

package/server/migrations/2026_06_08_000003_create_fuel_provider_sync_runs_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up()
+    {
+        Schema::create('fuel_provider_sync_runs', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('uuid', 191)->nullable()->unique();
+            $table->string('public_id', 191)->nullable()->unique();
+            $table->uuid('company_uuid')->nullable()->index();
+            $table->uuid('fuel_provider_connection_uuid')->nullable()->index();
+            $table->string('provider', 80)->index();
+            $table->string('status', 50)->default('queued')->index();
+            $table->timestamp('from')->nullable();
+            $table->timestamp('to')->nullable();
+            $table->unsignedInteger('imported')->default(0);
+            $table->unsignedInteger('matched')->default(0);
+            $table->unsignedInteger('unmatched')->default(0);
+            $table->unsignedInteger('fuel_reports_created')->default(0);
+            $table->decimal('liters', 12, 3)->default(0);
+            $table->unsignedBigInteger('amount')->default(0);
+            $table->timestamp('started_at')->nullable();
+            $table->timestamp('finished_at')->nullable();
+            $table->text('error')->nullable();
+            $table->json('summary')->nullable();
+            $table->json('meta')->nullable();
+            $table->softDeletes();
+            $table->timestamps();
+        });
+    }
+
+    public function down()
+    {
+        Schema::dropIfExists('fuel_provider_sync_runs');
+    }
+};

package/server/migrations/2026_06_10_000001_add_fuel_card_number_to_vehicles_table.php

@@ -0,0 +1,25 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up()
+    {
+        if (!Schema::hasColumn('vehicles', 'fuel_card_number')) {
+            Schema::table('vehicles', function (Blueprint $table) {
+                $table->string('fuel_card_number')->nullable()->index()->after('call_sign');
+            });
+        }
+    }
+
+    public function down()
+    {
+        if (Schema::hasColumn('vehicles', 'fuel_card_number')) {
+            Schema::table('vehicles', function (Blueprint $table) {
+                $table->dropColumn('fuel_card_number');
+            });
+        }
+    }
+};

package/server/migrations/2026_06_10_000002_add_vehicle_identity_columns_to_fuel_provider_transactions_table.php

@@ -0,0 +1,39 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up()
+    {
+        if (!Schema::hasColumn('fuel_provider_transactions', 'vin')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->string('vin')->nullable()->index()->after('plate_number');
+            });
+        }
+
+        if (!Schema::hasColumn('fuel_provider_transactions', 'serial_number')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->string('serial_number')->nullable()->index()->after('vin');
+            });
+        }
+
+        if (!Schema::hasColumn('fuel_provider_transactions', 'call_sign')) {
+            Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+                $table->string('call_sign')->nullable()->index()->after('serial_number');
+            });
+        }
+    }
+
+    public function down()
+    {
+        foreach (['call_sign', 'serial_number', 'vin'] as $column) {
+            if (Schema::hasColumn('fuel_provider_transactions', $column)) {
+                Schema::table('fuel_provider_transactions', function (Blueprint $table) use ($column) {
+                    $table->dropColumn($column);
+                });
+            }
+        }
+    }
+};

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,10 @@
 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;
 
 class DeviceController extends FleetOpsController
 {
@@ -21,7 +25,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 +52,60 @@ 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',
+        ]);
+
+        $device  = $this->findDevice($id);
+        $vehicle = $this->findVehicle($request->input('vehicle') ?? $request->input('attachable_uuid'));
+
+        $device->attachTo($vehicle);
+        $device->load(['telematic', 'warranty', 'attachable']);
+
+        return response()->json([
+            'status' => 'ok',
+            'device' => $device,
+        ]);
+    }
+
+    /**
+     * Detach a device from its current FleetOps resource.
+     */
+    public function detach(string $id): JsonResponse
+    {
+        $device = $this->findDevice($id);
+        $device->detach();
+        $device->load(['telematic', 'warranty', 'attachable']);
+
+        return response()->json([
+            'status' => 'ok',
+            'device' => $device,
+        ]);
+    }
+
+    protected function findDevice(string $id): Device
+    {
+        return Device::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();
     }
 }

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(),
+        ]);
+    }
 }