@fleetbase/fleetops-engine 0.6.54 → 0.6.56

package/server/tests/TelematicsHardeningTest.php

@@ -1,9 +1,14 @@
 <?php
 
 use Fleetbase\FleetOps\Contracts\TelematicProviderDescriptor;
+use Fleetbase\FleetOps\Models\Telematic;
 use Fleetbase\FleetOps\Support\Telematics\Providers\AfaqyProvider;
+use Fleetbase\FleetOps\Support\Telematics\Providers\FlespiProvider;
+use Fleetbase\FleetOps\Support\Telematics\Providers\GeotabProvider;
 use Fleetbase\FleetOps\Support\Telematics\Providers\SafeeProvider;
+use Fleetbase\FleetOps\Support\Telematics\Providers\SamsaraProvider;
 use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Http;
 
 test('device event model and migration expose lifecycle fields used by telematics workflows', function () {
@@ -21,6 +26,11 @@ test('device event model and migration expose lifecycle fields used by telematic
         ->toContain("'occurred_at'")
         ->toContain("'processed_at'")
         ->toContain("'data'")
+        ->toContain("'device_imei'")
+        ->toContain("'device_connection_status'")
+        ->toContain("'provider_descriptor'")
+        ->toContain('public function getDeviceImeiAttribute(): ?string')
+        ->toContain('public function getProviderDescriptorAttribute(): array')
         ->toContain("'occurred_at'     => 'datetime'")
         ->toContain("'processed_at'    => 'datetime'");
 });
@@ -46,6 +56,7 @@ test('telematics service requires provider identity and stores idempotent event
     expect($service)
         ->toContain('Provider device identity is required to link a telematics device.')
         ->toContain('public function ingestDeviceSnapshot')
+        ->toContain('normalizeEvents')
         ->toContain('DeviceEvent::firstOrNew([\'_key\' => $eventKey])')
         ->toContain('reconcileDeviceTelemetry')
         ->toContain('PROTECTED_DEVICE_STATUSES')
@@ -55,9 +66,19 @@ test('telematics service requires provider identity and stores idempotent event
         ->toContain('applyDeviceEventTelemetry')
         ->toContain('$event->createPosition($positionData)')
         ->toContain('updateVehicleTelemetry')
+        ->toContain('$vehicle->odometer = $eventData[\'odometer\'];')
         ->toContain('broadcast(new VehicleLocationChanged')
+        ->toContain("'heading'   => \$eventData['heading'] ?? null")
+        ->toContain("'bearing'   => \$eventData['heading'] ?? null")
+        ->toContain("'speed'     => \$eventData['speed'] ?? null")
+        ->toContain("'altitude'  => \$eventData['altitude'] ?? null")
         ->toContain('storeSnapshotSensors')
         ->toContain("\$payload['sensors'] ?? \$payload['sensors_last_val']")
+        ->toContain("'sensor_key' => \$name")
+        ->toContain('Sensor::firstOrNew')
+        ->toContain("'telematic_uuid' => \$telematic->uuid")
+        ->toContain("'device_uuid'    => \$device?->uuid")
+        ->toContain("'internal_id'    => \$sensorIdentity ?? \$this->makeSensorIdentity")
         ->toContain('protected function makeEventKey')
         ->toContain('$telematic->public_id ?? $telematic->uuid')
         ->toContain('resolveWebhookTelematic')
@@ -79,20 +100,794 @@ test('device details render consistent telematics connection state and timestamp
 });
 
 test('native providers normalize device payloads to canonical FleetOps keys', function () {
-    $afaqy = file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/AfaqyProvider.php');
-    $safee = file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/SafeeProvider.php');
+    $providers = [
+        file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/AfaqyProvider.php'),
+        file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/FlespiProvider.php'),
+        file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/GeotabProvider.php'),
+        file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/SafeeProvider.php'),
+        file_get_contents(__DIR__ . '/../src/Support/Telematics/Providers/SamsaraProvider.php'),
+    ];
 
-    foreach ([$afaqy, $safee] as $provider) {
+    foreach ($providers as $provider) {
         expect($provider)
             ->toContain("'device_id'")
+            ->toContain("'external_id'")
             ->toContain("'name'")
             ->toContain("'provider'")
             ->toContain("'model'")
             ->toContain("'online'")
-            ->toContain("'last_seen_at'");
+            ->toContain("'last_seen_at'")
+            ->toContain("'location'")
+            ->toContain("'speed'")
+            ->toContain("'heading'")
+            ->toContain("'altitude'");
     }
 });
 
+test('flespi telemetry normalizes positional event fields', function () {
+    $event = (new FlespiProvider())->normalizeEvent([
+        'id'                     => 'message-1',
+        'device.id'              => 'device-1',
+        'timestamp'              => 1781769600,
+        'position.latitude'      => 25.2048,
+        'position.longitude'     => 55.2708,
+        'position.speed'         => 42,
+        'position.direction'     => 91,
+        'position.altitude'      => 12,
+        'vehicle.mileage'        => 12345,
+        'engine.ignition.status' => true,
+        'fuel.level'             => 67,
+    ]);
+
+    expect($event)->toMatchArray([
+        'external_id' => 'message-1',
+        'device_id'   => 'device-1',
+        'event_type'  => 'telemetry_update',
+        'online'      => true,
+        'location'    => ['lat' => 25.2048, 'lng' => 55.2708],
+        'speed'       => 42,
+        'heading'     => 91,
+        'altitude'    => 12,
+        'odometer'    => 12345,
+        'ignition'    => true,
+        'fuel_level'  => 67,
+    ]);
+    expect($event['meta'])->toHaveKeys(['raw', 'provider_status']);
+});
+
+test('samsara telemetry variants normalize positional event fields', function () {
+    $event = (new SamsaraProvider())->normalizeEvent([
+        'id'                 => 'event-1',
+        'vehicle'            => ['id' => 'vehicle-1'],
+        'time'               => '2026-06-18T08:00:00Z',
+        'location'           => [
+            'latitude'          => 25.2048,
+            'longitude'         => 55.2708,
+            'speedMilesPerHour' => 30,
+            'headingDegrees'    => 180,
+            'altitudeMeters'    => 16,
+        ],
+        'odometerMeters'     => 1000,
+        'fuelPercent'        => 50,
+        'gateway'            => ['status' => 'connected', 'online' => true],
+    ]);
+
+    expect($event)->toMatchArray([
+        'external_id' => 'event-1',
+        'device_id'   => 'vehicle-1',
+        'event_type'  => 'vehicle_update',
+        'online'      => true,
+        'location'    => ['lat' => 25.2048, 'lng' => 55.2708],
+        'speed'       => 30,
+        'heading'     => 180,
+        'altitude'    => 16,
+        'odometer'    => 1000,
+        'fuel_level'  => 50,
+    ]);
+    expect($event['meta']['provider_status'])->toMatchArray([
+        'gateway_status' => 'connected',
+        'online'         => true,
+    ]);
+});
+
+test('safee telemetry includes online and altitude event fields', function () {
+    $event = (new SafeeProvider())->normalizeEvent([
+        'id'            => 'event-1',
+        'deviceId'      => 'device-1',
+        'status'        => 'online',
+        'date'          => '2026-06-18T08:00:00Z',
+        'lat'           => 25.2048,
+        'lon'           => 55.2708,
+        'speed'         => 30,
+        'heading'       => 100,
+        'altitude'      => 15,
+    ]);
+
+    expect($event)->toMatchArray([
+        'device_id'   => 'device-1',
+        'online'      => true,
+        'location'    => ['lat' => 25.2048, 'lng' => 55.2708],
+        'speed'       => 30,
+        'heading'     => 100,
+        'altitude'    => 15,
+    ]);
+    expect($event['external_id'])->toContain('event-1');
+});
+
+test('safee sync returns inventory first then enriches with last info positions and events', function () {
+    Carbon::setTestNow(Carbon::parse('2026-06-23T09:15:40Z'));
+    $requests = [];
+
+    Http::fake(function ($request) use (&$requests) {
+        $requests[] = $request;
+        $path       = parse_url($request->url(), PHP_URL_PATH);
+        $body       = $request->data();
+
+        return match ($path) {
+            '/api/v2/vehicle/list-info' => Http::response([
+                'code'   => 0,
+                'result' => [
+                    [
+                        'id'      => 105,
+                        'uuid'    => 'vehicle-uuid-105',
+                        'plateNo' => 'ABC-1234',
+                        'driver'  => ['id' => 2, 'name' => 'Ahmad'],
+                        'device'  => ['id' => 315, 'imei' => 'imei-315', 'serial' => 'serial-315'],
+                    ],
+                ],
+            ], 200),
+            '/api/v2/vehicle/last-state' => Http::response([
+                'code'   => 0,
+                'result' => [
+                    [
+                        'id'       => 105,
+                        'plateNo'  => 'ABC-1234',
+                        'date'     => 1782206130.5,
+                        'speed'    => 41,
+                        'heading'  => 90,
+                        'status'   => 'moving',
+                        'position' => ['lat' => 25.1, 'lon' => 55.1, 'alt' => 10],
+                        'event'    => ['id' => 2, 'code' => 'ignition_on', 'name' => 'Ignition On'],
+                    ],
+                ],
+            ], 200),
+            '/api/v2/vehicle/last-info' => Http::response([
+                'code'   => 0,
+                'result' => [
+                    'id'          => 105,
+                    'plateNo'     => 'ABC-1234',
+                    'date'        => 1782206140.5,
+                    'speed'       => 45,
+                    'heading'     => 100,
+                    'status'      => 'moving',
+                    'position'    => ['lat' => 25.2, 'lon' => 55.2, 'alt' => 12],
+                    'event'       => ['id' => 3, 'code' => 'over_speed', 'name' => 'Over Speed'],
+                    'odometer'    => 1232.4,
+                    'temperature' => ['Temp Sensor 1' => 36.8],
+                    'door'        => ['Door1' => 'Open'],
+                    'humidity'    => ['Humidity Sensor 1' => 44.2],
+                ],
+            ], 200),
+            '/api/v2/vehicle/positions' => Http::response([
+                'code'   => 0,
+                'result' => [
+                    [
+                        'id'       => 501,
+                        'plateNo'  => 'ABC-1234',
+                        'date'     => 1782206100.5,
+                        'speed'    => 35,
+                        'heading'  => 80,
+                        'status'   => 'moving',
+                        'position' => ['lat' => 25.0, 'lon' => 55.0, 'alt' => 8],
+                        'event'    => ['id' => 2, 'code' => 'ignition_on', 'name' => 'Ignition On'],
+                    ],
+                ],
+            ], 200),
+            '/api/v2/vehicle/events' => Http::response([
+                'code'   => 0,
+                'result' => [
+                    [
+                        'id'        => 601,
+                        'plateNo'   => 'ABC-1234',
+                        'reason'    => 'External Power Disconnected',
+                        'date'      => 1782206110.5,
+                        'speed'     => 12,
+                        'heading'   => 20,
+                        'status'    => 'moving',
+                        'position'  => ['lat' => 25.05, 'lon' => 55.05, 'alt' => 9],
+                        'type'      => ['key' => '1212', 'value' => 'External Power Disconnected'],
+                        'vehicle'   => ['id' => 105, 'name' => 'ABC-1234'],
+                        'event'     => ['id' => 4, 'code' => 'external_power_disconnected', 'name' => 'External Power Disconnected'],
+                        'arguments' => [['name' => 'Speed', 'type' => 'double', 'value' => '12']],
+                    ],
+                ],
+            ], 200),
+            default => Http::response(['code' => 0, 'result' => []], 200),
+        };
+    });
+
+    $telematic       = new Telematic();
+    $telematic->meta = [];
+
+    $provider = new class extends SafeeProvider {
+        public function fetchDevicesForTest(Telematic $telematic): array
+        {
+            $this->telematic = $telematic;
+            $this->baseUrl   = 'https://fms.example.test';
+            $this->headers   = ['Authorization' => 'Bearer testing-token'];
+
+            return $this->fetchDevices();
+        }
+
+        public function fetchTelemetryForTest(array $devices): array
+        {
+            return $this->fetchDeviceTelemetrySnapshots($devices);
+        }
+    };
+
+    $inventoryResult = $provider->fetchDevicesForTest($telematic);
+    $inventoryDevice = $inventoryResult['devices'][0];
+
+    expect($inventoryResult['devices'])->toHaveCount(1);
+    expect($inventoryDevice['_safee']['identity']['plateNo'])->toBe('ABC-1234');
+    expect($inventoryDevice['_safee']['current_info'])->toBeNull();
+    expect($inventoryDevice['_safee']['current_state'])->toMatchArray([
+        'id'       => 105,
+        'status'   => 'moving',
+        'speed'    => 45,
+        'heading'  => 100,
+        'position' => ['lat' => 25.2, 'lon' => 55.2, 'alt' => 12],
+    ]);
+    expect($inventoryDevice['_safee']['positions'])->toBe([]);
+    expect($inventoryDevice['_safee']['events'])->toBe([]);
+    expect($inventoryDevice['sensors'])->toBe([]);
+    expect(data_get($inventoryResult, 'sync_meta.safee_last_endpoint_counts'))->toMatchArray([
+        'vehicles_listed'                  => 1,
+        'unique_vehicle_ids'               => 1,
+        'missing_vehicle_ids'              => 0,
+        'duplicate_vehicle_ids'            => [],
+        'devices_returned_for_ingestion'   => 1,
+        'list_info_page_size'              => 0,
+        'list_info_requested_unpaginated'  => true,
+        'last_state_fetched'               => 1,
+        'last_info_fetched'                => 0,
+        'positions_fetched'                => 0,
+        'events_fetched'                   => 0,
+    ]);
+
+    expect(array_map(fn ($request) => parse_url($request->url(), PHP_URL_PATH), $requests))->toBe([
+        '/api/v2/vehicle/list-info',
+        '/api/v2/vehicle/last-state',
+    ]);
+
+    $result = $provider->fetchTelemetryForTest($inventoryResult['devices']);
+    $device = $result['devices'][0];
+
+    expect($result['sync_meta'])->toMatchArray([
+        'safee_last_telemetry_synced_at'  => 1782206140.0,
+        'safee_last_enrichment_total'     => 1,
+        'safee_last_enrichment_completed' => 1,
+        'safee_last_enrichment_failures'  => [],
+    ]);
+    expect(data_get($result, 'sync_meta.safee_last_sync_window'))->toMatchArray([
+        'startDate' => 1782205240.0,
+        'endDate'   => 1782206140.0,
+    ]);
+    expect($device['_safee']['identity']['plateNo'])->toBe('ABC-1234');
+    expect($device['_safee']['current_info']['odometer'])->toBe(1232.4);
+    expect($device['_safee']['positions'])->toHaveCount(1);
+    expect($device['_safee']['events'])->toHaveCount(1);
+    expect($device['sensors'])->toHaveCount(3);
+    expect($device['sensors'][0])->toMatchArray([
+        'internal_id' => 'safee:105:temperature:Temp Sensor 1',
+        'name'        => 'Temp Sensor 1',
+        'type'        => 'temperature',
+        'value'       => 36.8,
+    ]);
+    expect($device['sensors'][1])->toMatchArray([
+        'internal_id' => 'safee:105:door:Door1',
+        'name'        => 'Door1',
+        'type'        => 'door',
+        'value'       => 'Open',
+    ]);
+    expect($device['sensors'][2])->toMatchArray([
+        'internal_id' => 'safee:105:humidity:Humidity Sensor 1',
+        'name'        => 'Humidity Sensor 1',
+        'type'        => 'humidity',
+        'value'       => 44.2,
+    ]);
+
+    $paths = array_map(fn ($request) => parse_url($request->url(), PHP_URL_PATH), $requests);
+    expect($paths)->toBe([
+        '/api/v2/vehicle/list-info',
+        '/api/v2/vehicle/last-state',
+        '/api/v2/vehicle/last-info',
+        '/api/v2/vehicle/positions',
+        '/api/v2/vehicle/events',
+    ]);
+
+    expect($requests[0]->data())->toMatchArray(['pageSize' => 0]);
+    expect($requests[1]->data())->toMatchArray([
+        'live'      => true,
+        'startDate' => null,
+        'endDate'   => null,
+        'vehicles'  => [105],
+    ]);
+    expect($requests[2]->data())->toMatchArray(['vehicleId' => 105]);
+    expect($requests[3]->data())->toMatchArray(['vehicleId' => 105]);
+    expect($requests[4]->data())->toMatchArray(['vehicleId' => 105, 'status' => 'ALL']);
+
+    Carbon::setTestNow();
+});
+
+test('safee list info requests all vehicles and preserves filters', function () {
+    Carbon::setTestNow(Carbon::parse('2026-06-23T09:15:40Z'));
+    $requests = [];
+
+    Http::fake(function ($request) use (&$requests) {
+        $requests[] = $request;
+        $path       = parse_url($request->url(), PHP_URL_PATH);
+
+        if ($path === '/api/v2/vehicle/list-info') {
+            return Http::response([
+                'code'   => 0,
+                'result' => array_map(fn ($id) => [
+                    'id'      => $id,
+                    'plateNo' => 'SAFE-' . $id,
+                    'device'  => ['id' => 'device-' . $id],
+                ], range(101, 107)),
+            ], 200);
+        }
+
+        return Http::response(['code' => 0, 'result' => []], 200);
+    });
+
+    $telematic       = new Telematic();
+    $telematic->meta = [];
+
+    $provider = new class extends SafeeProvider {
+        public function fetchDevicesForTest(Telematic $telematic): array
+        {
+            $this->telematic = $telematic;
+            $this->baseUrl   = 'https://fms.example.test';
+            $this->headers   = ['Authorization' => 'Bearer testing-token'];
+
+            return $this->fetchDevices([
+                'filter' => [
+                    'plateNo' => 'SAFE',
+                ],
+            ]);
+        }
+    };
+
+    $result = $provider->fetchDevicesForTest($telematic);
+
+    expect($result['devices'])->toHaveCount(7);
+    expect($requests)->toHaveCount(2);
+    expect($requests[0]->data())->toMatchArray([
+        'plateNo'  => 'SAFE',
+        'pageSize' => 0,
+    ]);
+    expect($requests[1]->data())->toMatchArray([
+        'vehicles' => range(101, 107),
+    ]);
+    expect(data_get($result, 'sync_meta.safee_last_endpoint_counts'))->toMatchArray([
+        'vehicles_listed'                  => 7,
+        'unique_vehicle_ids'               => 7,
+        'missing_vehicle_ids'              => 0,
+        'duplicate_vehicle_ids'            => [],
+        'devices_returned_for_ingestion'   => 7,
+        'list_info_page_size'              => 0,
+        'list_info_requested_unpaginated'  => true,
+    ]);
+
+    Carbon::setTestNow();
+});
+
+test('safee list info reports duplicate and missing vehicle identities', function () {
+    Carbon::setTestNow(Carbon::parse('2026-06-23T09:15:40Z'));
+    $requests = [];
+
+    Http::fake(function ($request) use (&$requests) {
+        $requests[] = $request;
+        $path       = parse_url($request->url(), PHP_URL_PATH);
+
+        if ($path === '/api/v2/vehicle/list-info') {
+            return Http::response([
+                'code'   => 0,
+                'result' => [
+                    ['id' => 105, 'plateNo' => 'SAFE-105'],
+                    ['id'      => 105, 'plateNo' => 'SAFE-105-DUP'],
+                    ['id'      => 106, 'plateNo' => 'SAFE-106'],
+                    ['plateNo' => 'SAFE-MISSING'],
+                ],
+            ], 200);
+        }
+
+        return Http::response(['code' => 0, 'result' => []], 200);
+    });
+
+    $telematic       = new Telematic();
+    $telematic->meta = [];
+
+    $provider = new class extends SafeeProvider {
+        public function fetchDevicesForTest(Telematic $telematic): array
+        {
+            $this->telematic = $telematic;
+            $this->baseUrl   = 'https://fms.example.test';
+            $this->headers   = ['Authorization' => 'Bearer testing-token'];
+
+            return $this->fetchDevices();
+        }
+    };
+
+    $result = $provider->fetchDevicesForTest($telematic);
+
+    expect($result['devices'])->toHaveCount(4);
+    expect($requests)->toHaveCount(2);
+    expect($requests[1]->data())->toMatchArray([
+        'vehicles' => [105, 106],
+    ]);
+    expect(data_get($result, 'sync_meta.safee_last_endpoint_counts'))->toMatchArray([
+        'vehicles_listed'                => 4,
+        'unique_vehicle_ids'             => 2,
+        'missing_vehicle_ids'            => 1,
+        'duplicate_vehicle_ids'          => ['105' => 2],
+        'devices_returned_for_ingestion' => 4,
+    ]);
+
+    Carbon::setTestNow();
+});
+
+test('telematics sync job counts unique persisted devices separately from link attempts', function () {
+    $job = file_get_contents(__DIR__ . '/../src/Jobs/SyncTelematicDevicesJob.php');
+
+    expect($job)
+        ->toContain('public int $timeout = 3600')
+        ->toContain('public bool $failOnTimeout = true')
+        ->toContain('$linkedDeviceKeys')
+        ->toContain('resolveLinkedDeviceKey($result, $normalizedDevice)')
+        ->toContain('fetchDeviceTelemetrySnapshots')
+        ->toContain('Safee inventory sync completed')
+        ->toContain('last_sync_link_attempts_total')
+        ->toContain('last_sync_inventory_linked_total')
+        ->toContain('last_sync_enrichment_completed')
+        ->toContain('last_sync_failed_reason')
+        ->toContain('last_sync_linked_total');
+});
+
+test('safee vehicle id resolution tolerates missing id fields', function () {
+    $events = (new SafeeProvider())->normalizeEvents([
+        '_safee' => [
+            'identity'     => ['plateNo' => 'NO-ID'],
+            'current_info' => ['status' => 'offline'],
+        ],
+    ]);
+
+    expect($events)->toHaveCount(1);
+    expect($events[0]['device_id'])->toBeNull();
+});
+
+test('safee current telemetry merges last state with last info fallback fields', function () {
+    $device = (new SafeeProvider())->normalizeDevice([
+        'id'      => 105,
+        'plateNo' => 'ABC-1234',
+        '_safee'  => [
+            'vehicle_id'     => 105,
+            'identity'       => ['id' => 105, 'plateNo' => 'ABC-1234'],
+            'current_state'  => [
+                'id'       => 105,
+                'date'     => 1782206120.5,
+                'status'   => 'offline',
+                'speed'    => 12,
+                'heading'  => 30,
+                'position' => ['lat' => 25.1, 'lon' => 55.1, 'alt' => 5],
+            ],
+            'current_info'  => [
+                'odometer' => 1234.5,
+            ],
+        ],
+    ]);
+
+    expect($device)->toMatchArray([
+        'device_id'    => 105,
+        'status'       => 'inactive',
+        'online'       => false,
+        'last_seen_at' => Carbon::createFromTimestamp(1782206120.5)->toDateTimeString(),
+        'location'     => ['lat' => 25.1, 'lng' => 55.1],
+        'speed'        => 12,
+        'heading'      => 30,
+        'altitude'     => 5,
+        'odometer'     => 1234.5,
+    ]);
+});
+
+test('safee normalizes documented vehicle identity current telemetry positions and events', function () {
+    $provider = new SafeeProvider();
+    $payload  = [
+        'id'      => 105,
+        'uuid'    => 'vehicle-uuid-105',
+        'plateNo' => 'ABC-1234',
+        'driver'  => ['id' => 2, 'name' => 'Ahmad'],
+        'device'  => ['id' => 315, 'imei' => 'imei-315', 'serial' => 'serial-315'],
+        '_safee'  => [
+            'identity'     => [
+                'id'      => 105,
+                'uuid'    => 'vehicle-uuid-105',
+                'plateNo' => 'ABC-1234',
+                'device'  => ['id' => 315, 'imei' => 'imei-315', 'serial' => 'serial-315'],
+            ],
+            'current_state' => [
+                'id'       => 105,
+                'date'     => 1782206120.5,
+                'status'   => 'moving',
+                'speed'    => 22,
+                'heading'  => 45,
+                'position' => ['lat' => 24.9, 'lon' => 54.9, 'alt' => 7],
+            ],
+            'current_info' => [
+                'id'          => 999,
+                'plateNo'     => 'ABC-1234',
+                'date'        => 1782206140.5,
+                'speed'       => 45,
+                'heading'     => 100,
+                'status'      => 'moving',
+                'position'    => ['lat' => 25.2, 'lon' => 55.2, 'alt' => 12],
+                'vehicle'     => ['id' => 6],
+                'event'       => ['id' => 3, 'code' => 'over_speed', 'name' => 'Over Speed'],
+                'odometer'    => 1232.4,
+                'temperature' => ['Temp Sensor 1' => 36.8],
+                'door'        => ['Door1' => 'Open'],
+                'humidity'    => ['Humidity Sensor 1' => 44.2],
+            ],
+            'positions'    => [
+                [
+                    'id'       => 501,
+                    'plateNo'  => 'ABC-1234',
+                    'date'     => 1782206100.5,
+                    'speed'    => 35,
+                    'heading'  => 80,
+                    'status'   => 'moving',
+                    'position' => ['lat' => 25.0, 'lon' => 55.0, 'alt' => 8],
+                    'event'    => ['id' => 2, 'code' => 'ignition_on', 'name' => 'Ignition On'],
+                ],
+            ],
+            'events'       => [
+                [
+                    'id'        => 601,
+                    'plateNo'   => 'ABC-1234',
+                    'reason'    => 'External Power Disconnected',
+                    'date'      => 1782206110.5,
+                    'speed'     => 12,
+                    'heading'   => 20,
+                    'status'    => 'moving',
+                    'position'  => ['lat' => 25.05, 'lon' => 55.05, 'alt' => 9],
+                    'type'      => ['key' => '1212', 'value' => 'External Power Disconnected'],
+                    'vehicle'   => ['id' => 105, 'name' => 'ABC-1234'],
+                    'event'     => ['id' => 4, 'code' => 'external_power_disconnected', 'name' => 'External Power Disconnected'],
+                    'arguments' => [['name' => 'Speed', 'type' => 'double', 'value' => '12']],
+                ],
+            ],
+        ],
+    ];
+
+    $device = $provider->normalizeDevice($payload);
+    $events = $provider->normalizeEvents($payload);
+
+    expect($device)->toMatchArray([
+        'device_id'     => 105,
+        'external_id'   => 105,
+        'name'          => 'ABC-1234',
+        'provider'      => 'safee',
+        'internal_id'   => 'vehicle-uuid-105',
+        'imei'          => 'imei-315',
+        'serial_number' => 'serial-315',
+        'status'        => 'active',
+        'online'        => true,
+        'location'      => ['lat' => 25.2, 'lng' => 55.2],
+        'speed'         => 45,
+        'heading'       => 100,
+        'altitude'      => 12,
+        'odometer'      => 1232.4,
+    ]);
+    expect($device['meta'])->toMatchArray([
+        'plate_number' => 'ABC-1234',
+        'temperature'  => ['Temp Sensor 1' => 36.8],
+        'door'         => ['Door1' => 'Open'],
+        'humidity'     => ['Humidity Sensor 1' => 44.2],
+    ]);
+
+    expect($events)->toHaveCount(3);
+    expect($events[0])->toMatchArray([
+        'device_id'   => 105,
+        'event_type'  => 'over_speed',
+        'code'        => 'over_speed',
+        'message'     => 'Over Speed',
+        'location'    => ['lat' => 25.2, 'lng' => 55.2],
+        'speed'       => 45,
+        'heading'     => 100,
+        'altitude'    => 12,
+        'odometer'    => 1232.4,
+    ]);
+    expect($events[0]['data'])->toMatchArray([
+        'temperature' => ['Temp Sensor 1' => 36.8],
+        'door'        => ['Door1' => 'Open'],
+        'humidity'    => ['Humidity Sensor 1' => 44.2],
+    ]);
+    expect($events[1])->toMatchArray([
+        'event_type' => 'ignition_on',
+        'location'   => ['lat' => 25.0, 'lng' => 55.0],
+        'altitude'   => 8,
+    ]);
+    expect($events[2])->toMatchArray([
+        'event_type' => 'external_power_disconnected',
+        'reason'     => 'External Power Disconnected',
+        'location'   => ['lat' => 25.05, 'lng' => 55.05],
+        'altitude'   => 9,
+    ]);
+});
+
+test('safee sensors normalize stable parent scoped identities and latest values', function () {
+    $provider = new SafeeProvider();
+
+    $open = $provider->normalizeSensor([
+        'internal_id' => 'safee:105:door:Door1',
+        'name'        => 'Door1',
+        'type'        => 'door',
+        'value'       => 'Open',
+        'recorded_at' => 1782206140.5,
+        'vehicle_id'  => 105,
+        'plate_no'    => 'ABC-1234',
+        'source'      => 'door',
+    ]);
+
+    $closed = $provider->normalizeSensor([
+        'internal_id' => 'safee:105:door:Door1',
+        'name'        => 'Door1',
+        'type'        => 'door',
+        'value'       => 'Closed',
+        'recorded_at' => 1782206200.5,
+        'vehicle_id'  => 105,
+        'plate_no'    => 'ABC-1234',
+        'source'      => 'door',
+    ]);
+
+    expect($open)->toMatchArray([
+        'internal_id' => 'safee:105:door:Door1',
+        'external_id' => 'safee:105:door:Door1',
+        'name'        => 'Door1',
+        'type'        => 'door',
+        'sensor_type' => 'door',
+        'value'       => 'Open',
+        'status'      => 'active',
+    ]);
+    expect(data_get($open, 'meta.provider'))->toBe('safee');
+    expect(data_get($open, 'meta.vehicle_id'))->toBe(105);
+    expect(data_get($open, 'meta.plate_no'))->toBe('ABC-1234');
+    expect($closed['internal_id'])->toBe($open['internal_id']);
+    expect($closed['value'])->toBe('Closed');
+});
+
+test('geotab latest log record drives device and event telemetry', function () {
+    $payload = [
+        'id'                          => 'device-1',
+        'name'                        => 'Truck 1',
+        'deviceType'                  => 'GO9',
+        'serialNumber'                => 'serial-1',
+        'vehicleIdentificationNumber' => 'VIN123',
+        'latest_log_record'           => [
+            'id'        => 'log-1',
+            'dateTime'  => '2026-06-18T08:00:00Z',
+            'latitude'  => 25.2048,
+            'longitude' => 55.2708,
+            'speed'     => 55,
+            'bearing'   => 90,
+            'altitude'  => 20,
+            'device'    => ['id' => 'device-1'],
+        ],
+    ];
+
+    $provider = new GeotabProvider();
+    $device   = $provider->normalizeDevice($payload);
+    $event    = $provider->normalizeEvent($payload);
+
+    expect($device)->toMatchArray([
+        'device_id'     => 'device-1',
+        'external_id'   => 'device-1',
+        'name'          => 'Truck 1',
+        'provider'      => 'geotab',
+        'model'         => 'GO9',
+        'imei'          => 'serial-1',
+        'vin'           => 'VIN123',
+        'serial_number' => 'serial-1',
+        'online'        => true,
+        'location'      => ['lat' => 25.2048, 'lng' => 55.2708],
+        'speed'         => 55,
+        'heading'       => 90,
+        'altitude'      => 20,
+    ]);
+
+    expect($event)->toMatchArray([
+        'external_id' => 'log-1',
+        'device_id'   => 'device-1',
+        'event_type'  => 'status_data',
+        'online'      => true,
+        'location'    => ['lat' => 25.2048, 'lng' => 55.2708],
+        'speed'       => 55,
+        'heading'     => 90,
+        'altitude'    => 20,
+    ]);
+});
+
+test('geotab polling fetches recent log records and merges latest record into device snapshots', function () {
+    $requests = [];
+
+    Http::fake(function ($request) use (&$requests) {
+        $requests[] = $request;
+        $body       = json_decode($request->body(), true);
+        $typeName   = data_get($body, 'params.typeName');
+
+        if ($typeName === 'Device') {
+            return Http::response([
+                'result' => [
+                    ['id' => 'device-1', 'name' => 'Truck 1'],
+                    ['id' => 'device-2', 'name' => 'Truck 2'],
+                ],
+            ], 200);
+        }
+
+        if ($typeName === 'LogRecord') {
+            return Http::response([
+                'result' => [
+                    ['id' => 'old-log', 'device' => ['id' => 'device-1'], 'dateTime' => '2026-06-18T07:00:00Z', 'latitude' => 1, 'longitude' => 2],
+                    ['id' => 'new-log', 'device' => ['id' => 'device-1'], 'dateTime' => '2026-06-18T08:00:00Z', 'latitude' => 3, 'longitude' => 4],
+                    ['id' => 'other-log', 'device' => ['id' => 'other-device'], 'dateTime' => '2026-06-18T08:00:00Z', 'latitude' => 5, 'longitude' => 6],
+                ],
+            ], 200);
+        }
+
+        return Http::response(['result' => []], 200);
+    });
+
+    $provider = new class extends GeotabProvider {
+        public function fetchDevicesForTest(): array
+        {
+            $this->credentials = [
+                'database' => 'testing-db',
+            ];
+            $this->sessionId = 'testing-session';
+
+            return $this->fetchDevices(['limit' => 2, 'from_date' => '2026-06-18T00:00:00Z']);
+        }
+    };
+
+    $result = $provider->fetchDevicesForTest();
+
+    expect($result['devices'])->toHaveCount(2);
+    expect($result['devices'][0]['latest_log_record'])->toMatchArray([
+        'id'        => 'new-log',
+        'latitude'  => 3,
+        'longitude' => 4,
+    ]);
+    expect($result['devices'][1])->not->toHaveKey('latest_log_record');
+    expect($requests)->toHaveCount(2);
+    expect($requests[0]->data())->toMatchArray([
+        'method' => 'Get',
+        'params' => [
+            'typeName'     => 'Device',
+            'resultsLimit' => 2,
+        ],
+    ]);
+    expect($requests[1]->data())->toMatchArray([
+        'method' => 'Get',
+        'params' => [
+            'typeName'     => 'LogRecord',
+            'search'       => ['fromDate' => '2026-06-18T00:00:00Z'],
+            'resultsLimit' => 100,
+        ],
+    ]);
+});
+
 test('telematics details use public id for consumer webhook URLs and do not read ember uuid', function () {
     $component = file_get_contents(__DIR__ . '/../../addon/components/telematic/details.js');
     $template  = file_get_contents(__DIR__ . '/../../addon/components/telematic/details.hbs');
@@ -218,6 +1013,74 @@ test('afaqy sync stores compact device diagnostics and paginates complete units
         ->toContain("'altitude'   => \$lastUpdate['alt'] ?? null");
 });
 
+test('afaqy sensors normalize stable parent scoped identities and latest values', function () {
+    $provider = new AfaqyProvider();
+
+    $open = $provider->normalizeSensor([
+        'device_id'  => 'unit-123',
+        'sensor_key' => 'Door1',
+        'name'       => 'Door1',
+        'type'       => 'digital',
+        'last_val'   => [
+            'value' => 'Open',
+            'dtt'   => '2026-06-23T09:00:00Z',
+        ],
+    ]);
+
+    $closed = $provider->normalizeSensor([
+        'device_id'  => 'unit-123',
+        'sensor_key' => 'Door1',
+        'name'       => 'Door1',
+        'type'       => 'digital',
+        'last_val'   => [
+            'value' => 'Closed',
+            'dtt'   => '2026-06-23T09:05:00Z',
+        ],
+    ]);
+
+    expect($open)->toMatchArray([
+        'internal_id' => 'afaqy:unit-123:door1',
+        'external_id' => 'afaqy:unit-123:door1',
+        'name'        => 'Door1',
+        'type'        => 'door',
+        'sensor_type' => 'door',
+        'value'       => 'Open',
+        'status'      => 'active',
+    ]);
+    expect($open['recorded_at'])->toBe('2026-06-23 09:00:00');
+    expect(data_get($open, 'meta.provider'))->toBe('afaqy');
+    expect(data_get($open, 'meta.unit_id'))->toBe('unit-123');
+    expect($closed['internal_id'])->toBe($open['internal_id']);
+    expect($closed['value'])->toBe('Closed');
+});
+
+test('afaqy sensors reject event shaped payloads without scalar sensor values', function () {
+    $provider = new AfaqyProvider();
+
+    expect(fn () => $provider->normalizeSensor([
+        'device_id'    => 'unit-123',
+        'sensor_key'   => 'ignition_event',
+        'name'         => 'ignition_event',
+        'last_update'  => [
+            'lat'   => 25.2,
+            'lng'   => 55.2,
+            'speed' => 40,
+        ],
+    ]))->toThrow(InvalidArgumentException::class);
+});
+
+test('afaqy bad sensor cleanup migration targets only afaqy telematics sensors', function () {
+    $migration = file_get_contents(__DIR__ . '/../migrations/2026_06_23_000001_delete_bad_afaqy_telematics_sensors.php');
+
+    expect($migration)
+        ->toContain("->from('telematics')")
+        ->toContain("->where('provider', 'afaqy')")
+        ->toContain("->whereIn('telematic_uuid'")
+        ->toContain("JSON_EXTRACT(meta, '$.provider')")
+        ->toContain('Run an AFAQY sync to recreate')
+        ->toContain('public function down(): void');
+});
+
 test('afaqy sync keeps default limit and uses extended data request path', function () {
     $requests = [];
 
@@ -444,17 +1307,20 @@ test('telematics device sync records provider pagination and skipped device coun
         ->toContain("method_exists(\$e, 'context') ? \$e->context() : []");
 });
 
-test('telematics polling command is registered and scheduled for no webhook providers', function () {
+test('telematics polling command is registered and scheduled for discovery providers by default', function () {
     $command  = file_get_contents(__DIR__ . '/../src/Console/Commands/SyncTelematics.php');
     $provider = file_get_contents(__DIR__ . '/../src/Providers/FleetOpsServiceProvider.php');
     $details  = file_get_contents(__DIR__ . '/../../addon/components/telematic/details.hbs');
 
     expect($command)
         ->toContain("protected \$signature = 'fleetops:sync-telematics")
+        ->toContain('{--exclude-webhook-providers : Skip providers that support webhooks}')
         ->toContain('SyncTelematicDevicesJob::dispatch($telematic')
-        ->toContain('!$descriptor->supportsWebhooks')
+        ->toContain('$excludeWebhookProviders = (bool) $this->option(\'exclude-webhook-providers\')')
+        ->toContain('!$excludeWebhookProviders || !$descriptor->supportsWebhooks')
         ->toContain('$descriptor->supportsDiscovery')
-        ->toContain("whereIn('status', ['active', 'connected'])");
+        ->toContain("whereIn('status', ['active', 'connected'])")
+        ->not->toContain('sync-webhook-providers');
 
     expect($provider)
         ->toContain('Console\\Commands\\SyncTelematics::class')