@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/server/tests/Unit/Http/Resources/IndexVehicleResourceTest.php

@@ -21,6 +21,11 @@ class FleetOpsIndexVehicleResourceProbe extends IndexVehicleResource
         return $this->compactDevices();
     }
 
+    public function compactTrailersForTest(): array
+    {
+        return $this->compactTrailers();
+    }
+
     public function locationCoordinatesForTest(): ?string
     {
         return $this->locationCoordinates();
@@ -147,9 +152,39 @@ test('index vehicle resource helper methods resolve devices and position labels'
         ],
     ]));
 
+    $vehicle->setRelation('currentTrailers', new Collection([
+        (object) [
+            'uuid'                => 'trailer-uuid',
+            'public_id'           => 'trailer_public',
+            'name'                => 'Reefer 12',
+            'display_name'        => 'Reefer 12',
+            'type'                => 'reefer',
+            'plate_number'        => 'TRL-12',
+            'status'              => 'in_use',
+            'connectivity_status' => 'online',
+            'online'              => 1,
+        ],
+    ]));
+
     $resource = new FleetOpsIndexVehicleResourceProbe($vehicle);
     fleetopsIndexVehicleResourceRequest(true);
 
+    expect($resource->compactTrailersForTest())->toBe([
+        [
+            'id'                  => 'trailer-uuid',
+            'uuid'                => 'trailer-uuid',
+            'public_id'           => 'trailer_public',
+            'name'                => 'Reefer 12',
+            'display_name'        => 'Reefer 12',
+            'type'                => 'reefer',
+            'plate_number'        => 'TRL-12',
+            'status'              => 'in_use',
+            'attachment_state'    => 'attached',
+            'connectivity_status' => 'online',
+            'online'              => true,
+        ],
+    ]);
+
     expect($resource->compactDevicesForTest())->toBe([
         [
             'id'            => 'device-uuid',

package/server/tests/Unit/Http/Resources/ManifestResourceTest.php

@@ -64,7 +64,7 @@ class FleetOpsManifestFake extends Manifest
 }
 
 test('manifest resource publishes what a driver needs to run a route', function () {
-    $request                             = Request::create('/v1/manifests/manifest_public', 'GET');
+    $request                              = Request::create('/v1/manifests/manifest_public', 'GET');
     FleetOpsSupportRequestState::$request = $request;
 
     $manifest = new FleetOpsManifestFake();
@@ -94,7 +94,7 @@ test('manifest resource publishes what a driver needs to run a route', function
 test('manifest resource omits stops when they were not loaded, so a list stays a list', function () {
     // A driver's manifest list on a busy fleet must not drag every stop of
     // every route along with it.
-    $request                             = Request::create('/v1/drivers/driver_public/manifests', 'GET');
+    $request                              = Request::create('/v1/drivers/driver_public/manifests', 'GET');
     FleetOpsSupportRequestState::$request = $request;
 
     $manifest = new FleetOpsManifestFake();
@@ -106,7 +106,7 @@ test('manifest resource omits stops when they were not loaded, so a list stays a
 });
 
 test('manifest stop resource carries the sequence a re-sequence rewrites', function () {
-    $request                             = Request::create('/v1/manifest-stops/stop_public', 'GET');
+    $request                              = Request::create('/v1/manifest-stops/stop_public', 'GET');
     FleetOpsSupportRequestState::$request = $request;
 
     $stop = new ManifestStop();

package/server/tests/Unit/Models/EquipmentTest.php

@@ -15,6 +15,7 @@ if (!function_exists('Fleetbase\FleetOps\Models\activity')) {
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Maintenance;
+use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\Warranty;
 use Fleetbase\FleetOps\Support\Utils;
@@ -270,6 +271,27 @@ test('equipment mutators and appended accessors normalize assignment state', fun
         ->and($equipment->getReplacementCostEstimate())->toBeNull();
 });
 
+test('equipment assignment supports first class trailers without changing vehicle compatibility', function () {
+    $trailer = new Trailer();
+    $trailer->forceFill(['uuid' => 'trailer-uuid', 'name' => 'Reefer 7']);
+
+    $trailerEquipment = new Equipment([
+        'equipable_type' => 'fleet-ops:trailer',
+        'equipable_uuid' => 'trailer-uuid',
+    ]);
+    $trailerEquipment->setRelation('equipable', $trailer);
+
+    $vehicleEquipment = new Equipment([
+        'equipable_type' => 'fleet-ops:vehicle',
+        'equipable_uuid' => 'vehicle-uuid',
+    ]);
+
+    expect($trailerEquipment->equipable_type)->toBe(Utils::getMutationType('fleet-ops:trailer'))
+        ->and($trailerEquipment->equipped_to_name)->toBe('Reefer 7')
+        ->and($trailerEquipment->is_equipped)->toBeTrue()
+        ->and($vehicleEquipment->equipable_type)->toBe(Utils::getMutationType('fleet-ops:vehicle'));
+});
+
 test('equipment query scopes add expected filters', function () {
     $equipment = new Equipment();
     $query     = new FleetOpsEquipmentQueryFake();

package/server/tests/Unit/Models/ModelLookupFallbackSeamsTest.php

@@ -3,6 +3,7 @@
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\VehicleDevice;
 use Illuminate\Database\ConnectionResolver;
@@ -114,16 +115,19 @@ test('vehicle devices fall back to a direct vehicle lookup by uuid', function ()
         ->and($seen)->toBe(['vehicle_lookupone']);
 });
 
-test('unrecognised equipable types are stored verbatim', function () {
+test('known equipable aliases are normalized and unrecognised types are stored verbatim', function () {
     $equipment = new Equipment();
 
     // Known short names map onto their fully qualified model class
     $equipment->equipable_type = 'vehicle';
     expect($equipment->getAttributes()['equipable_type'])->toContain('Vehicle');
 
-    // Anything else is kept as given rather than silently dropped
     $equipment->equipable_type = 'trailer';
-    expect($equipment->getAttributes()['equipable_type'])->toBe('trailer');
+    expect($equipment->getAttributes()['equipable_type'])->toBe(Trailer::class);
+
+    // Anything else is kept as given rather than silently dropped
+    $equipment->equipable_type = 'cargo-bay';
+    expect($equipment->getAttributes()['equipable_type'])->toBe('cargo-bay');
 });
 
 test('tracking number generation redraws when the first number is already taken', function () {

package/server/tests/Unit/Models/TrailerTest.php

@@ -0,0 +1,204 @@
+<?php
+
+use Fleetbase\FleetOps\Events\TrailerLocationChanged;
+use Fleetbase\FleetOps\Models\AssetConnection;
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\Equipment;
+use Fleetbase\FleetOps\Models\Maintenance;
+use Fleetbase\FleetOps\Models\MaintenanceSchedule;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Models\Trailer;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\WorkOrder;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasManyThrough;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+
+// Model identifier hooks bind to the dispatcher present when the class boots.
+if (!EloquentModel::getEventDispatcher()) {
+    EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher());
+}
+
+function fleetOpsTrailerUseInMemoryConnection(): SQLiteConnection
+{
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $connection = new SQLiteConnection($pdo);
+    $connection->statement('create table assets (
+        id integer primary key autoincrement,
+        uuid varchar(64),
+        public_id varchar(64) null unique,
+        company_uuid varchar(64),
+        name varchar(255),
+        code varchar(64) null,
+        type varchar(64) null,
+        asset_class varchar(64) null,
+        status varchar(64) null,
+        slug varchar(255) null,
+        last_online_at datetime null,
+        created_at datetime null,
+        updated_at datetime null,
+        deleted_at datetime null
+    )');
+    $connection->statement('create table positions (
+        id integer primary key autoincrement,
+        uuid varchar(64), public_id varchar(64), company_uuid varchar(64),
+        subject_uuid varchar(64), subject_type varchar(255), destination_uuid varchar(64),
+        coordinates text, heading varchar(64), bearing varchar(64), speed varchar(64), altitude varchar(64),
+        created_at datetime null, updated_at datetime null, deleted_at datetime null
+    )');
+
+    $resolver = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('responsecache', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+
+    return $connection;
+}
+
+test('trailer creation enforces its discriminator defaults and public id namespace', function () {
+    fleetOpsTrailerUseInMemoryConnection();
+
+    $trailer = new Trailer([
+        'company_uuid'  => 'company-a',
+        'name'          => 'Reefer 12',
+        'asset_class'   => 'vehicle',
+    ]);
+    Trailer::getEventDispatcher()->until('eloquent.creating: ' . Trailer::class, $trailer);
+
+    expect($trailer->asset_class)->toBe(Trailer::ASSET_CLASS)
+        ->and($trailer->status)->toBe('available')
+        ->and($trailer->public_id)->toStartWith('trailer_')
+        ->and($trailer->uuid)->not->toBeEmpty();
+
+    EloquentModel::unsetEventDispatcher();
+});
+
+test('trailer global scope never returns another asset class', function () {
+    $connection = fleetOpsTrailerUseInMemoryConnection();
+    $connection->table('assets')->insert([
+        ['uuid' => 'trailer-uuid', 'public_id' => 'trailer_public', 'company_uuid' => 'company-a', 'name' => 'Trailer', 'asset_class' => 'trailer', 'status' => 'available'],
+        ['uuid' => 'vehicle-uuid', 'public_id' => 'asset_public', 'company_uuid' => 'company-a', 'name' => 'Vehicle-like asset', 'asset_class' => 'vehicle', 'status' => 'available'],
+    ]);
+
+    expect(Trailer::query()->pluck('uuid')->all())->toBe(['trailer-uuid'])
+        ->and(Trailer::query()->toSql())->toContain('asset_class');
+});
+
+test('trailer exposes first class connection device equipment maintenance and position relations', function () {
+    fleetOpsTrailerUseInMemoryConnection();
+    $trailer = new Trailer();
+
+    expect($trailer->currentConnection())->toBeInstanceOf(HasOne::class)
+        ->and($trailer->currentConnection()->getRelated())->toBeInstanceOf(AssetConnection::class)
+        ->and($trailer->connections())->toBeInstanceOf(HasMany::class)
+        ->and($trailer->devices()->getRelated())->toBeInstanceOf(Device::class)
+        ->and($trailer->equipments()->getRelated())->toBeInstanceOf(Equipment::class)
+        ->and($trailer->positions()->getRelated())->toBeInstanceOf(Position::class)
+        ->and($trailer->maintenances()->getRelated())->toBeInstanceOf(Maintenance::class)
+        ->and($trailer->maintenanceSchedules()->getRelated())->toBeInstanceOf(MaintenanceSchedule::class)
+        ->and($trailer->workOrders()->getRelated())->toBeInstanceOf(WorkOrder::class);
+});
+
+test('asset connections preserve effective dated vehicle and trailer identities', function () {
+    fleetOpsTrailerUseInMemoryConnection();
+    $connection = new AssetConnection([
+        'relationship_type' => 'towing',
+        'position'          => 2,
+        'connected_at'      => '2026-09-03 12:00:00',
+        'disconnected_at'   => null,
+    ]);
+
+    expect($connection->vehicle())->toBeInstanceOf(BelongsTo::class)
+        ->and($connection->vehicle()->getRelated())->toBeInstanceOf(Vehicle::class)
+        ->and($connection->trailer())->toBeInstanceOf(BelongsTo::class)
+        ->and($connection->trailer()->getRelated())->toBeInstanceOf(Trailer::class)
+        ->and($connection->relationship_type)->toBe('towing')
+        ->and($connection->position)->toBe(2)
+        ->and($connection->disconnected_at)->toBeNull();
+});
+
+test('vehicles expose current and historical trailer relationships', function () {
+    fleetOpsTrailerUseInMemoryConnection();
+    $vehicle = new Vehicle();
+
+    expect($vehicle->trailerConnections())->toBeInstanceOf(HasMany::class)
+        ->and($vehicle->trailerConnections()->getRelated())->toBeInstanceOf(AssetConnection::class)
+        ->and($vehicle->currentTrailers())->toBeInstanceOf(HasManyThrough::class)
+        ->and($vehicle->currentTrailers()->getRelated())->toBeInstanceOf(Trailer::class);
+});
+
+test('trailer connectivity is distinct from lifecycle and attachment state', function () {
+    Carbon::setTestNow('2026-09-03 12:00:00');
+
+    $trailer = new Trailer(['status' => 'maintenance']);
+    expect($trailer->connectivity_status)->toBe('never_connected')
+        ->and($trailer->status)->toBe('maintenance')
+        ->and($trailer->attachment_state)->toBe('detached');
+
+    $vehicle    = new Vehicle();
+    $connection = new AssetConnection();
+    $connection->setRelation('vehicle', $vehicle);
+    $trailer->setRelation('currentConnection', $connection);
+    expect($trailer->current_vehicle)->toBe($vehicle)
+        ->and($trailer->attachment_state)->toBe('attached');
+
+    $trailer->last_online_at = Carbon::now()->subMinutes(5);
+    expect($trailer->connectivity_status)->toBe('online');
+
+    $trailer->last_online_at = Carbon::now()->subHours(2);
+    expect($trailer->connectivity_status)->toBe('recently_offline');
+
+    $trailer->last_online_at = Carbon::now()->subDays(2);
+    expect($trailer->connectivity_status)->toBe('offline');
+
+    Carbon::setTestNow();
+});
+
+test('trailer positions require coordinates and preserve model or scalar destinations', function () {
+    fleetOpsTrailerUseInMemoryConnection();
+    $trailer = new Trailer();
+    $trailer->forceFill(['uuid' => 'trailer-position', 'company_uuid' => 'company-a']);
+    expect($trailer->createPosition())->toBeNull();
+
+    $vehicle = new Vehicle();
+    $vehicle->forceFill(['uuid' => 'vehicle-destination']);
+    $fromModel  = $trailer->createPosition(['latitude' => 1.3, 'longitude' => 103.8, 'heading' => 90, 'bearing' => 91, 'speed' => 40, 'altitude' => 12], $vehicle);
+    $fromScalar = $trailer->createPosition(['latitude' => 1.4, 'longitude' => 103.9], 'place-destination');
+    expect($fromModel)->toBeInstanceOf(Position::class)
+        ->and($fromModel->destination_uuid)->toBe('vehicle-destination')
+        ->and($fromScalar->destination_uuid)->toBe('place-destination');
+});
+
+test('trailer location broadcasts use tenant and trailer channels without exposing internal ids', function () {
+    Carbon::setTestNow('2026-09-03 12:00:00');
+
+    $trailer = new Trailer();
+    $trailer->forceFill([
+        'uuid'         => 'internal-trailer-uuid',
+        'public_id'    => 'trailer_public',
+        'company_uuid' => 'company-a',
+        'speed'        => 42,
+        'heading'      => 180,
+    ]);
+    $event = new TrailerLocationChanged($trailer, ['source' => 'telematics']);
+
+    expect(array_map(fn ($channel) => $channel->name, $event->broadcastOn()))
+        ->toBe(['company.company-a', 'trailer.trailer_public', 'trailer.internal-trailer-uuid'])
+        ->and($event->broadcastWith()['data']['id'])->toBe('trailer_public')
+        ->and($event->broadcastWith()['data'])->not->toHaveKey('uuid')
+        ->and($event->broadcastWith()['data']['additionalData'])->toBe(['source' => 'telematics']);
+
+    Carbon::setTestNow();
+});

package/server/tests/Unit/Support/FuelProviderServiceMatchingTest.php

@@ -38,6 +38,8 @@ class FleetOpsFuelServiceMatchingProbe extends FuelProviderService
 
 function fleetopsFuelServiceMatchingBoot(): SQLiteConnection
 {
+    EloquentModel::setEventDispatcher(new Illuminate\Events\Dispatcher(app()));
+    EloquentModel::clearBootedModels();
     $pdo = new PDO('sqlite::memory:');
     // SQLite lacks the MySQL spatial functions used by the fuel report
     // location cast; a passthrough keeps the WKT string intact.
@@ -91,6 +93,13 @@ function fleetopsFuelServiceMatchingBoot(): SQLiteConnection
         });
     }
 
+    // Exercise real UUID assignment without unrelated HTTP-cache observers.
+    foreach ([FuelProviderTransaction::class, Fleetbase\FleetOps\Models\FuelReport::class, Fleetbase\FleetOps\Models\FuelProviderSyncRun::class] as $modelClass) {
+        new $modelClass();
+        $modelClass::flushEventListeners();
+        $modelClass::bootHasUuid();
+    }
+
     session(['company' => 'company-1']);
     FleetOpsFuelServiceMatchingRecorder::$events = [];
 
@@ -177,8 +186,12 @@ test('match vehicle and match order resolve string identifiers', function () {
     $matched = $service->matchVehicle($transaction, 'vehicle_test');
     expect($matched->vehicle_uuid)->toBe('vehicle-1')
         ->and($matched->sync_status)->toBe('matched')
+        ->and($matched->fuel_report_uuid)->not->toBeNull()
         ->and($connection->table('fuel_reports')->count())->toBe(1);
 
+    $service->matchVehicle($matched, 'vehicle_test');
+    expect($connection->table('fuel_reports')->count())->toBe(1);
+
     $withOrder = $service->matchOrder($matched, 'order_test');
     expect($withOrder->order_uuid)->toBe('order-1');
 });
@@ -278,3 +291,117 @@ test('ensure fuel report reuses existing reports and skips vehicleless transacti
     expect($report)->not->toBeNull()
         ->and($connection->table('fuel_reports')->where('uuid', $report->uuid)->value('location'))->toBe('POINT(103.85 1.29)');
 });
+
+test('reimport updates a transaction without duplicating its report and preserves ignored review', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $service = fleetopsFuelServiceMatchingService();
+    $payload = ['provider_transaction_id' => 'repeat-1', 'plate_number' => 'SGX-1234', 'amount' => 1250, 'currency' => 'SAR', 'volume' => 5];
+    $first   = $service->ingestTransaction($connection, $payload);
+    $second  = $service->ingestTransaction($connection, $payload);
+    expect($first->wasRecentlyCreated)->toBeTrue()
+        ->and($second->wasRecentlyCreated)->toBeFalse()
+        ->and($db->table('fuel_provider_transactions')->count())->toBe(1)
+        ->and($db->table('fuel_reports')->count())->toBe(1)
+        ->and($second->fuel_report_uuid)->toBe($first->fuel_report_uuid);
+    $service->reviewTransaction($second, 'ignored');
+    expect($service->ingestTransaction($connection, $payload)->sync_status)->toBe('ignored');
+});
+
+test('sandbox and production connections cannot overwrite one another’s provider transactions', function () {
+    $db           = fleetopsFuelServiceMatchingBoot();
+    $first        = fleetopsFuelServiceMatchingConnection($db);
+    $second       = clone $first;
+    $second->uuid = 'production-connection';
+    $service      = fleetopsFuelServiceMatchingService();
+    $payload      = ['provider_transaction_id' => 'shared-bill-id', 'amount' => 1000, 'currency' => 'SAR'];
+    $sandbox      = $service->ingestTransaction($first, $payload);
+    $production   = $service->ingestTransaction($second, $payload);
+    expect($sandbox->uuid)->not->toBe($production->uuid)
+        ->and($db->table('fuel_provider_transactions')->count())->toBe(2)
+        ->and($sandbox->fuel_provider_connection_uuid)->toBe($first->uuid)
+        ->and($production->fuel_provider_connection_uuid)->toBe($second->uuid);
+});
+
+test('empty matching rules disable automatic matching', function () {
+    $db                        = fleetopsFuelServiceMatchingBoot();
+    $connection                = fleetopsFuelServiceMatchingConnection($db);
+    $connection->sync_settings = ['matching_order' => []];
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $transaction = fleetopsFuelServiceMatchingService()->ingestTransaction($connection, ['provider_transaction_id' => 'manual-only', 'plate_number' => 'SGX-1234']);
+    expect($transaction->sync_status)->toBe('unmatched')->and($transaction->vehicle_uuid)->toBeNull();
+});
+
+test('sync windows retain the configured lookback after empty runs and reject reversed dates', function () {
+    $db                         = fleetopsFuelServiceMatchingBoot();
+    $connection                 = fleetopsFuelServiceMatchingConnection($db);
+    $connection->sync_settings  = ['window_days' => 7];
+    $connection->last_synced_at = now();
+    $service                    = fleetopsFuelServiceMatchingService();
+    [$from, $to]                = $service->syncWindow($connection);
+    expect($from->toDateString())->toBe(now()->subDays(7)->toDateString())->and($to->toDateString())->toBe(now()->toDateString());
+    expect(fn () => $service->syncWindow($connection, now(), now()->subDay()))->toThrow(InvalidArgumentException::class);
+});
+
+test('ambiguous vehicle identifiers require manual matching', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db, ['sync_settings' => json_encode(['matching_order' => ['plate_number']])]);
+    $db->table('vehicles')->insert([
+        ['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'ABC 1234'],
+        ['uuid' => 'vehicle-2', 'company_uuid' => 'company-1', 'plate_number' => 'ABC-1234'],
+    ]);
+    $transaction = fleetopsFuelServiceMatchingService()->ingestTransaction($connection, ['provider_transaction_id' => 'ambiguous', 'plate_number' => 'ABC 1234']);
+    expect($transaction->sync_status)->toBe('unmatched')
+        ->and($transaction->vehicle_uuid)->toBeNull()
+        ->and($db->table('fuel_reports')->count())->toBe(0);
+});
+
+test('activity reports persisted totals and isolates the company and connection', function () {
+    $db         = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    foreach ([['conn-1', 'company-1', 300], ['conn-2', 'company-1', 900], ['conn-3', 'company-2', 500]] as [$id, $company, $amount]) {
+        $db->table('fuel_provider_transactions')->insert(['uuid' => 'txn-' . $id, 'fuel_provider_connection_uuid' => $id, 'company_uuid' => $company, 'sync_status' => 'unmatched', 'amount' => $amount, 'currency' => 'SAR', 'volume' => 4]);
+    }
+    $controller = new Fleetbase\FleetOps\Http\Controllers\Internal\v1\FuelProviderConnectionController(fleetopsFuelServiceMatchingService());
+    $activity   = $controller->activity(new Illuminate\Http\Request(), 'conn-1')->getData(true);
+    expect($activity['totals'])->toMatchArray(['transactions' => 1, 'unmatched' => 1, 'liters' => 4, 'fuel_reports' => 0])
+        ->and($activity['totals']['spend'])->toBe([['currency' => 'SAR', 'amount' => 300]])
+        ->and($activity['connection'])->not->toHaveKey('credentials');
+    session(['company' => 'company-2']);
+    expect(fn () => $controller->activity(new Illuminate\Http\Request(), 'conn-1'))->toThrow(Illuminate\Database\Eloquent\ModelNotFoundException::class);
+});
+
+test('terminal worker failures mark a sync failed without destroying its last successful summary', function () {
+    $db = fleetopsFuelServiceMatchingBoot();
+    $db->getSchemaBuilder()->table('fuel_provider_connections', function ($table) {
+        $table->text('last_error')->nullable();
+        $table->text('last_sync_state')->nullable();
+    });
+    $db->getSchemaBuilder()->table('fuel_provider_sync_runs', function ($table) { $table->timestamp('finished_at')->nullable(); });
+    fleetopsFuelServiceMatchingConnection($db, ['last_sync_state' => json_encode(['summary' => ['imported' => 1]])]);
+    $db->table('fuel_provider_sync_runs')->insert(['uuid' => 'run-1', 'fuel_provider_connection_uuid' => 'conn-1', 'status' => 'running']);
+    $job = new Fleetbase\FleetOps\Jobs\SyncFuelProviderTransactionsJob('conn-1', syncRunUuid: 'run-1');
+    $job->failed(new RuntimeException('worker stopped'));
+    expect($db->table('fuel_provider_sync_runs')->value('status'))->toBe('error')
+        ->and($db->table('fuel_provider_sync_runs')->value('finished_at'))->not->toBeNull()
+        ->and(FuelProviderConnection::where('uuid', 'conn-1')->first()->last_sync_state)->toBe(['summary' => ['imported' => 1]]);
+});
+
+test('ingestion persists the report returned by a custom report resolution strategy', function () {
+    $db = fleetopsFuelServiceMatchingBoot();
+    $connection = fleetopsFuelServiceMatchingConnection($db);
+    $db->table('vehicles')->insert(['uuid' => 'vehicle-1', 'company_uuid' => 'company-1', 'plate_number' => 'SGX-1234']);
+    $db->table('fuel_reports')->insert(['uuid' => 'existing-report', 'company_uuid' => 'company-1', 'vehicle_uuid' => 'vehicle-1']);
+    $service = new class(new FuelProviderRegistry()) extends FleetOpsFuelServiceMatchingProbe {
+        protected function ensureFuelReport(FuelProviderTransaction $transaction): ?Fleetbase\FleetOps\Models\FuelReport
+        {
+            return Fleetbase\FleetOps\Models\FuelReport::where('company_uuid', $transaction->company_uuid)->where('vehicle_uuid', $transaction->vehicle_uuid)->firstOrFail();
+        }
+    };
+    $transaction = $service->ingestTransaction($connection, ['provider_transaction_id' => 'existing-report-transaction', 'plate_number' => 'SGX-1234']);
+    expect($transaction->sync_status)->toBe('matched');
+    expect($transaction->fuel_report_uuid)->toBe('existing-report');
+    expect($db->table('fuel_provider_transactions')->value('fuel_report_uuid'))->toBe('existing-report');
+    expect($db->table('fuel_reports')->count())->toBe(1);
+});

package/server/tests/Unit/Support/PetroAppFuelProviderTest.php

@@ -38,7 +38,7 @@ function fleetopsPetroAppConnection(array $credentials = []): FuelProviderConnec
 test('test connection reports success failure and exceptions', function () {
     fleetopsPetroAppFreshHttp();
     Http::fake([
-        'https://petroapp.test/webservice/vehicles*' => Http::response(['data' => ['total' => 12]], 200),
+        'https://petroapp.test/webservice/vehicles*' => Http::response(['data' => ['total' => 12, 'data' => []]], 200),
     ]);
 
     $provider = new PetroAppFuelProvider();
@@ -163,3 +163,128 @@ test('provider identity and header variants resolve correctly', function () {
 
     expect($probe->exposeBaseUrl(fleetopsPetroAppConnection()))->toBe('https://petroapp.test/webservice');
 });
+
+test('environment selects the endpoint for connection tests and imports', function (string $environment, string $baseUrl) {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake([
+        $baseUrl . '/vehicles*' => Http::response(['success' => true, 'data' => ['data' => [], 'meta' => ['total' => 123]]]),
+        $baseUrl . '/bills*'    => Http::response(['success' => true, 'data' => ['data' => []]]),
+    ]);
+    $connection              = fleetopsPetroAppConnection(['base_url' => '  ', 'auth_type' => 'ws_sk_header']);
+    $connection->environment = $environment;
+    $provider                = new PetroAppFuelProvider();
+
+    expect($provider->testConnection($connection))
+        ->toMatchArray(['success' => true]);
+    expect($provider->testConnection($connection)['metadata'])->toMatchArray(['total_vehicles' => 123, 'environment' => $environment, 'auth_type' => 'ws_sk_header']);
+    expect($provider->listTransactions($connection, Carbon::parse('2026-09-08'), Carbon::parse('2026-09-15')))->toBeEmpty();
+    Http::assertSent(fn ($request) => $request->url() === $baseUrl . '/vehicles?page=1'
+        && $request->hasHeader('WS-SK', 'token-123') && !$request->hasHeader('Authorization'));
+    Http::assertSent(fn ($request) => str_starts_with($request->url(), $baseUrl . '/bills?')
+        && $request['from'] === '2026-09-08' && $request['to'] === '2026-09-15' && $request['lang'] === 'en');
+})->with([
+    ['sandbox', 'https://app-public.staging.petroapp.app/webservice'],
+    ['production', 'https://app.petroapp.com.sa/webservice'],
+]);
+
+test('HTTP 200 provider errors and malformed payloads fail tests and imports', function ($payload) {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response($payload, 200)]);
+    $provider   = new PetroAppFuelProvider();
+    $connection = fleetopsPetroAppConnection();
+
+    expect($provider->testConnection($connection)['success'])->toBeFalse();
+    expect(fn () => $provider->listTransactions($connection, Carbon::now()->subDay(), Carbon::now()))->toThrow(RuntimeException::class);
+})->with([
+    'missing secret'  => [['status' => false, 'message' => 'Secret key is not found']],
+    'invalid bearer'  => [['success' => false, 'message' => 'Unauthenticated.', 'data' => null]],
+    'false with data' => [['success' => false, 'data' => ['data' => []]]],
+    'numeric status'  => [['status' => 0, 'data' => ['data' => []]]],
+    'HTML'            => ['<html>Login</html>'],
+    'missing data'    => [['message' => 'Secret key is not found']],
+]);
+
+test('vehicle resource pagination follows meta and links without following insecure URLs', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake([
+        'https://petroapp.test/webservice/vehicles?page=1' => Http::response([
+            'success' => true,
+            'data'    => ['data' => [['vehicle_id' => 1]], 'meta' => ['last_page' => 2], 'links' => ['next' => 'http://petroapp.test/webservice/vehicles?page=2']],
+        ]),
+        'https://petroapp.test/webservice/vehicles?page=2' => Http::response([
+            'success' => true,
+            'data'    => ['data' => [['vehicle_id' => 2]], 'meta' => ['last_page' => 2], 'links' => ['next' => null]],
+        ]),
+    ]);
+
+    expect((new PetroAppFuelProvider())->listVehicles(fleetopsPetroAppConnection())->pluck('vehicle_id')->all())->toBe([1, 2]);
+    Http::assertSentCount(2);
+});
+
+test('legacy token-only forms retry WS-SK only when PetroApp requests the missing secret key', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake(function ($request) {
+        if ($request->hasHeader('WS-SK', 'token-123')) {
+            expect($request->hasHeader('Authorization'))->toBeFalse();
+
+            return Http::response(['success' => true, 'data' => ['data' => [['id' => 1]], 'total' => 1]]);
+        }
+
+        expect($request->hasHeader('Authorization', 'Bearer token-123'))->toBeTrue();
+
+        return Http::response(['status' => false, 'message' => 'Secret key is not found']);
+    });
+    $connection = fleetopsPetroAppConnection(['api_token' => " token-123\n"]);
+    $provider   = new PetroAppFuelProvider();
+    $result     = $provider->testConnection($connection);
+    expect($result['success'])->toBeTrue()
+        ->and($result['metadata']['auth_type'])->toBe('ws_sk_header')
+        ->and(data_get($connection->credentials, 'auth_type'))->toBeNull();
+    expect($provider->listVehicles($connection))->toHaveCount(1);
+    Http::assertSentCount(4);
+});
+
+test('explicit authentication is never changed after a missing secret error', function (string $authType) {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response(['status' => false, 'message' => 'Secret key is not found'])]);
+    $result = (new PetroAppFuelProvider())->testConnection(fleetopsPetroAppConnection(['auth_type' => $authType]));
+    expect($result['success'])->toBeFalse()->and($result['metadata']['auth_type'])->toBe($authType);
+    Http::assertSentCount(1);
+})->with(['bearer_token', 'ws_sk_header']);
+
+test('working legacy bearer tokens are not retried', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::fake(['*' => Http::response(['success' => true, 'data' => ['data' => [], 'total' => 0]])]);
+    $result = (new PetroAppFuelProvider())->testConnection(fleetopsPetroAppConnection());
+    expect($result['success'])->toBeTrue()->and($result['metadata']['auth_type'])->toBe('bearer_token');
+    Http::assertSentCount(1);
+});
+
+test('PetroApp bill numbers remain stable when a bill is corrected and split plates are combined', function () {
+    $provider = new class extends PetroAppFuelProvider {
+        public function normalize(array $bill): array
+        {
+            return $this->normalizeBill($bill);
+        }
+    };
+    $bill      = ['bill_number' => 32549086, 'plate_letter' => 'ABC', 'plate_snum' => '1234', 'cost' => '3.00', 'num_of_liters' => '4'];
+    $original  = $provider->normalize($bill);
+    $corrected = $provider->normalize(array_merge($bill, ['cost' => '4.50']));
+    expect($original['provider_transaction_id'])->toBe('32549086')
+        ->and($corrected['provider_transaction_id'])->toBe($original['provider_transaction_id'])
+        ->and($original['plate_number'])->toBe('ABC 1234')
+        ->and($corrected['amount'])->toBe(450)
+        ->and($provider->normalize(array_merge($bill, ['plate_snum' => 'ABC 1234']))['plate_number'])->toBe('ABC 1234');
+});
+
+test('pagination limits fail visibly instead of returning a silently incomplete import', function () {
+    fleetopsPetroAppFreshHttp();
+    Http::preventStrayRequests();
+    Http::fake(['*' => Http::response(['success' => true, 'data' => ['data' => [['bill_number' => 1]], 'last_page' => 3]])]);
+    expect(fn () => (new PetroAppFuelProvider())->listTransactions(fleetopsPetroAppConnection(), Carbon::parse('2026-06-23'), Carbon::parse('2026-06-23'), ['max_pages' => 1]))
+        ->toThrow(RuntimeException::class, 'Choose a shorter date range');
+    Http::assertSentCount(1);
+});