@fleetbase/fleetops-engine 0.6.53 → 0.6.55

package/server/src/Support/Telematics/Providers/FlespiProvider.php

@@ -2,6 +2,8 @@
 
 namespace Fleetbase\FleetOps\Support\Telematics\Providers;
 
+use Illuminate\Support\Carbon;
+
 /**
  * Class FlespiProvider.
  *
@@ -77,34 +79,71 @@ class FlespiProvider extends AbstractProvider
 
     public function normalizeDevice(array $payload): array
     {
+        $telemetry  = $payload['telemetry'] ?? $payload;
+        $externalId = $payload['id'] ?? $payload['device.id'] ?? null;
+        $occurredAt = $this->parseTimestamp($telemetry['timestamp'] ?? $payload['last_active'] ?? null);
+
         return [
-            'external_id'     => $payload['id'],
-            'device_name'     => $payload['name'] ?? 'Unknown Device',
-            'device_provider' => 'flespi',
-            'device_model'    => $payload['device_type_id'] ?? null,
-            'imei'            => $payload['configuration']['ident'] ?? null,
-            'phone'           => $payload['configuration']['phone'] ?? null,
-            'status'          => isset($payload['telemetry']) ? 'active' : 'inactive',
-            'location'        => [
-                'lat' => $payload['telemetry']['position.latitude'] ?? null,
-                'lng' => $payload['telemetry']['position.longitude'] ?? null,
+            'device_id'     => $externalId,
+            'external_id'   => $externalId,
+            'name'          => $payload['name'] ?? $telemetry['device.name'] ?? 'Unknown Device',
+            'provider'      => 'flespi',
+            'model'         => $payload['device_type_id'] ?? $payload['device_type_name'] ?? null,
+            'imei'          => $payload['configuration']['ident'] ?? $payload['ident'] ?? $telemetry['ident'] ?? null,
+            'serial_number' => $payload['configuration']['serial'] ?? $payload['serial'] ?? null,
+            'phone'         => $payload['configuration']['phone'] ?? null,
+            'status'        => isset($payload['telemetry']) ? 'active' : 'inactive',
+            'online'        => $this->resolveOnline($telemetry),
+            'last_seen_at'  => $occurredAt,
+            'location'      => [
+                'lat' => $telemetry['position.latitude'] ?? null,
+                'lng' => $telemetry['position.longitude'] ?? null,
+            ],
+            'speed'      => $telemetry['position.speed'] ?? $telemetry['vehicle.speed'] ?? null,
+            'heading'    => $telemetry['position.direction'] ?? $telemetry['position.heading'] ?? null,
+            'altitude'   => $telemetry['position.altitude'] ?? null,
+            'odometer'   => $telemetry['vehicle.mileage'] ?? $telemetry['vehicle.odometer'] ?? null,
+            'ignition'   => $this->extractIgnition($telemetry),
+            'fuel_level' => $telemetry['fuel.level'] ?? $telemetry['can.fuel.level'] ?? null,
+            'meta'       => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'status'    => $payload['status'] ?? $telemetry['status'] ?? null,
+                    'online'    => $telemetry['online'] ?? null,
+                    'connected' => $telemetry['device.connected'] ?? $telemetry['connected'] ?? null,
+                ], fn ($value) => $value !== null),
             ],
-            'meta' => $payload,
         ];
     }
 
     public function normalizeEvent(array $payload): array
     {
+        $deviceId = $payload['device.id'] ?? $payload['id'] ?? null;
+
         return [
-            'external_id' => $payload['id'] ?? null,
-            'device_id'   => $payload['device.id'] ?? null,
+            'external_id' => $payload['id'] ?? $deviceId,
+            'device_id'   => $deviceId,
             'event_type'  => $payload['event.enum'] ?? 'telemetry_update',
-            'occurred_at' => isset($payload['timestamp']) ? date('Y-m-d H:i:s', $payload['timestamp']) : now(),
+            'occurred_at' => $this->parseTimestamp($payload['timestamp'] ?? null) ?? now(),
+            'online'      => $this->resolveOnline($payload),
             'location'    => [
                 'lat' => $payload['position.latitude'] ?? null,
                 'lng' => $payload['position.longitude'] ?? null,
             ],
-            'meta' => $payload,
+            'speed'      => $payload['position.speed'] ?? $payload['vehicle.speed'] ?? null,
+            'heading'    => $payload['position.direction'] ?? $payload['position.heading'] ?? null,
+            'altitude'   => $payload['position.altitude'] ?? null,
+            'odometer'   => $payload['vehicle.mileage'] ?? $payload['vehicle.odometer'] ?? null,
+            'ignition'   => $this->extractIgnition($payload),
+            'fuel_level' => $payload['fuel.level'] ?? $payload['can.fuel.level'] ?? null,
+            'meta'       => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'status'    => $payload['status'] ?? null,
+                    'online'    => $payload['online'] ?? null,
+                    'connected' => $payload['device.connected'] ?? $payload['connected'] ?? null,
+                ], fn ($value) => $value !== null),
+            ],
         ];
     }
 
@@ -180,4 +219,39 @@ class FlespiProvider extends AbstractProvider
     {
         return true;
     }
+
+    protected function parseTimestamp($value): ?string
+    {
+        if (!$value) {
+            return null;
+        }
+
+        if (is_numeric($value)) {
+            return Carbon::createFromTimestamp((float) $value)->toDateTimeString();
+        }
+
+        return Carbon::parse($value)->toDateTimeString();
+    }
+
+    protected function resolveOnline(array $payload): ?bool
+    {
+        $value = $payload['online'] ?? $payload['device.connected'] ?? $payload['connected'] ?? null;
+
+        if ($value === null) {
+            return isset($payload['timestamp']);
+        }
+
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? (bool) $value;
+    }
+
+    protected function extractIgnition(array $payload): ?bool
+    {
+        $value = $payload['engine.ignition.status'] ?? $payload['ignition.status'] ?? null;
+
+        if ($value === null) {
+            return null;
+        }
+
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? (bool) $value;
+    }
 }

package/server/src/Support/Telematics/Providers/GeotabProvider.php

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Support\Telematics\Providers;
 
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Http;
 
 /**
@@ -75,19 +76,21 @@ class GeotabProvider extends AbstractProvider
     {
         $limit = $options['limit'] ?? 100;
 
-        $response = Http::post($this->baseUrl, [
-            'method' => 'Get',
-            'params' => [
-                'credentials' => [
-                    'database'  => $this->credentials['database'],
-                    'sessionId' => $this->sessionId,
-                ],
-                'typeName'     => 'Device',
-                'resultsLimit' => $limit,
-            ],
-        ])->json();
+        $response = $this->apiCall('Get', [
+            'typeName'     => 'Device',
+            'resultsLimit' => $limit,
+        ]);
 
-        $devices = $response['result'] ?? [];
+        $devices      = $response['result'] ?? [];
+        $logsByDevice = $this->fetchLatestLogRecords($devices, $options);
+        $devices      = array_map(function ($device) use ($logsByDevice) {
+            $deviceId = $device['id'] ?? null;
+            if ($deviceId && isset($logsByDevice[$deviceId])) {
+                $device['latest_log_record'] = $logsByDevice[$deviceId];
+            }
+
+            return $device;
+        }, $devices);
 
         return [
             'devices'     => $devices,
@@ -98,43 +101,76 @@ class GeotabProvider extends AbstractProvider
 
     public function fetchDeviceDetails(string $externalId): array
     {
-        $response = Http::post($this->baseUrl, [
-            'method' => 'Get',
-            'params' => [
-                'credentials' => [
-                    'database'  => $this->credentials['database'],
-                    'sessionId' => $this->sessionId,
-                ],
-                'typeName' => 'Device',
-                'search'   => ['id' => $externalId],
-            ],
-        ])->json();
+        $response = $this->apiCall('Get', [
+            'typeName' => 'Device',
+            'search'   => ['id' => $externalId],
+        ]);
 
         return $response['result'][0] ?? [];
     }
 
     public function normalizeDevice(array $payload): array
     {
+        $latestLog    = $payload['latest_log_record'] ?? [];
+        $hasTelemetry = isset($latestLog['dateTime']) || isset($latestLog['latitude'], $latestLog['longitude']);
+
         return [
-            'external_id'     => $payload['id'],
-            'device_name'     => $payload['name'] ?? 'Unknown Device',
-            'device_provider' => 'geotab',
-            'device_model'    => $payload['deviceType'] ?? null,
-            'imei'            => $payload['serialNumber'] ?? null,
-            'vin'             => $payload['vehicleIdentificationNumber'] ?? null,
-            'status'          => 'active',
-            'meta'            => $payload,
+            'device_id'     => $payload['id'] ?? null,
+            'external_id'   => $payload['id'] ?? null,
+            'name'          => $payload['name'] ?? 'Unknown Device',
+            'provider'      => 'geotab',
+            'model'         => $payload['deviceType'] ?? null,
+            'imei'          => $payload['serialNumber'] ?? null,
+            'vin'           => $payload['vehicleIdentificationNumber'] ?? null,
+            'serial_number' => $payload['serialNumber'] ?? null,
+            'status'        => 'active',
+            'online'        => $hasTelemetry ? true : null,
+            'last_seen_at'  => $latestLog ? $this->parseTimestamp($latestLog['dateTime'] ?? null) : null,
+            'location'      => [
+                'lat' => $latestLog['latitude'] ?? null,
+                'lng' => $latestLog['longitude'] ?? null,
+            ],
+            'speed'    => $latestLog['speed'] ?? null,
+            'heading'  => $latestLog['bearing'] ?? $latestLog['heading'] ?? null,
+            'altitude' => $latestLog['altitude'] ?? null,
+            'meta'     => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'active_from' => $payload['activeFrom'] ?? null,
+                    'active_to'   => $payload['activeTo'] ?? null,
+                    'groups'      => $payload['groups'] ?? null,
+                    'has_log'     => $hasTelemetry,
+                ], fn ($value) => $value !== null),
+            ],
         ];
     }
 
     public function normalizeEvent(array $payload): array
     {
+        $latestLog    = $payload['latest_log_record'] ?? $payload;
+        $deviceId     = data_get($latestLog, 'device.id') ?? $payload['deviceId'] ?? $payload['id'] ?? null;
+        $hasTelemetry = isset($latestLog['dateTime']) || isset($latestLog['latitude'], $latestLog['longitude']);
+
         return [
-            'external_id' => $payload['id'] ?? null,
-            'device_id'   => $payload['device']['id'] ?? $payload['deviceId'] ?? null,
+            'external_id' => $latestLog['id'] ?? $payload['id'] ?? null,
+            'device_id'   => $deviceId,
             'event_type'  => $payload['type'] ?? 'status_data',
-            'occurred_at' => $payload['dateTime'] ?? now(),
-            'meta'        => $payload,
+            'occurred_at' => $this->parseTimestamp($latestLog['dateTime'] ?? null) ?? now(),
+            'online'      => $hasTelemetry ? true : null,
+            'location'    => [
+                'lat' => $latestLog['latitude'] ?? null,
+                'lng' => $latestLog['longitude'] ?? null,
+            ],
+            'speed'    => $latestLog['speed'] ?? null,
+            'heading'  => $latestLog['bearing'] ?? $latestLog['heading'] ?? null,
+            'altitude' => $latestLog['altitude'] ?? null,
+            'meta'     => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'has_log' => $hasTelemetry,
+                    'device'  => data_get($latestLog, 'device.id'),
+                ], fn ($value) => $value !== null),
+            ],
         ];
     }
 
@@ -179,4 +215,56 @@ class GeotabProvider extends AbstractProvider
     {
         return false;
     }
+
+    protected function apiCall(string $method, array $params): array
+    {
+        $params['credentials'] = [
+            'database'  => $this->credentials['database'],
+            'sessionId' => $this->sessionId,
+        ];
+
+        return Http::post($this->baseUrl, [
+            'method' => $method,
+            'params' => $params,
+        ])->json() ?? [];
+    }
+
+    protected function fetchLatestLogRecords(array $devices, array $options = []): array
+    {
+        $deviceIds = array_values(array_filter(array_map(fn ($device) => $device['id'] ?? null, $devices)));
+        if (empty($deviceIds)) {
+            return [];
+        }
+
+        $fromDate = $options['from_date'] ?? Carbon::now()->subHours(24)->toIso8601String();
+        $response = $this->apiCall('Get', [
+            'typeName'     => 'LogRecord',
+            'search'       => ['fromDate' => $fromDate],
+            'resultsLimit' => max(count($deviceIds) * 5, 100),
+        ]);
+
+        $logsByDevice = [];
+        foreach ($response['result'] ?? [] as $record) {
+            $deviceId = data_get($record, 'device.id');
+            if (!$deviceId || !in_array($deviceId, $deviceIds, true)) {
+                continue;
+            }
+
+            $current = $logsByDevice[$deviceId] ?? null;
+            if (!$current || Carbon::parse($record['dateTime'] ?? now())->greaterThan(Carbon::parse($current['dateTime'] ?? now()))) {
+                $logsByDevice[$deviceId] = $record;
+            }
+        }
+
+        return $logsByDevice;
+    }
+
+    protected function parseTimestamp($value): ?string
+    {
+        if (!$value) {
+            return null;
+        }
+
+        return Carbon::parse($value)->toDateTimeString();
+    }
 }

package/server/src/Support/Telematics/Providers/SafeeProvider.php

@@ -16,10 +16,11 @@ class SafeeProvider extends AbstractProvider
     protected string $baseUrl        = 'https://api.safee.com';
     protected int $requestsPerMinute = 3000;
     protected ?string $accessToken   = null;
+    protected array $authContext     = [];
 
     protected function prepareAuthentication(): void
     {
-        $this->baseUrl     = rtrim($this->credentials['api_base_url'] ?? $this->credentials['server_uri'] ?? $this->baseUrl, '/');
+        $this->baseUrl     = $this->resolveBaseUrl();
         $this->accessToken = $this->credentials['access_token'] ?? $this->authenticate();
         $scheme            = $this->credentials['authorization_scheme'] ?? 'Bearer';
 
@@ -45,13 +46,14 @@ class SafeeProvider extends AbstractProvider
                 'metadata' => [
                     'status' => $response['status'] ?? null,
                     'time'   => $response['time'] ?? null,
+                    ...$this->safeDiagnosticMetadata(),
                 ],
             ];
         } catch (\Throwable $e) {
             return [
                 'success'  => false,
                 'message'  => $e->getMessage(),
-                'metadata' => [],
+                'metadata' => $this->safeDiagnosticMetadata(),
             ];
         }
     }
@@ -108,8 +110,19 @@ class SafeeProvider extends AbstractProvider
                 'lat' => $position['lat'] ?? null,
                 'lng' => $position['lng'] ?? null,
             ],
-            'meta' => [
-                'raw'          => $payload,
+            'speed'      => $payload['speed'] ?? $payload['lastSpeed'] ?? null,
+            'heading'    => $payload['heading'] ?? $payload['angle'] ?? null,
+            'altitude'   => $payload['altitude'] ?? $payload['alt'] ?? null,
+            'odometer'   => $this->extractOdometer($payload),
+            'ignition'   => $this->extractIgnition($payload),
+            'fuel_level' => $this->extractFuelLevel($payload),
+            'meta'       => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'status'        => $rawStatus,
+                    'normalized'    => $status,
+                    'vehicleStatus' => $payload['vehicleStatus'] ?? null,
+                ], fn ($value) => $value !== null),
                 'plate_number' => $payload['plateNumber'] ?? $payload['plate_number'] ?? null,
                 'door_number'  => $payload['doorNumber'] ?? null,
                 'driver'       => $payload['driver'] ?? null,
@@ -134,12 +147,14 @@ class SafeeProvider extends AbstractProvider
             'event_type'  => data_get($payload, 'event.code') ?? data_get($payload, 'event.name') ?? 'telemetry_update',
             'message'     => data_get($payload, 'event.name') ?? data_get($payload, 'event.message') ?? null,
             'occurred_at' => $this->parseTimestamp($payload['date'] ?? $payload['deviceTime'] ?? $payload['time'] ?? null),
+            'online'      => $this->resolveOnline($payload),
             'location'    => [
                 'lat' => $position['lat'] ?? null,
                 'lng' => $position['lng'] ?? null,
             ],
             'speed'      => $payload['speed'] ?? $payload['lastSpeed'] ?? null,
             'heading'    => $payload['heading'] ?? $payload['angle'] ?? null,
+            'altitude'   => $payload['altitude'] ?? $payload['alt'] ?? null,
             'odometer'   => $this->extractOdometer($payload),
             'ignition'   => $this->extractIgnition($payload),
             'fuel_level' => $this->extractFuelLevel($payload),
@@ -219,7 +234,8 @@ class SafeeProvider extends AbstractProvider
             }
         }
 
-        $tokenUrl = $this->baseUrl . '/auth/realms/' . $this->credentials['realm_id'] . '/protocol/openid-connect/token';
+        $tokenUrl          = $this->baseUrl . '/auth/realms/' . $this->credentials['realm_id'] . '/protocol/openid-connect/token';
+        $this->authContext = $this->buildAuthContext($tokenUrl);
 
         $response = Http::asForm()
             ->acceptJson()
@@ -245,6 +261,44 @@ class SafeeProvider extends AbstractProvider
         return $token;
     }
 
+    protected function resolveBaseUrl(): string
+    {
+        $baseUrl = $this->filledCredential('api_base_url') ?? $this->filledCredential('server_uri') ?? $this->baseUrl;
+
+        return rtrim($baseUrl, '/');
+    }
+
+    protected function filledCredential(string $key): ?string
+    {
+        $value = $this->credentials[$key] ?? null;
+
+        if (!is_string($value)) {
+            return null;
+        }
+
+        $value = trim($value);
+
+        return $value === '' ? null : $value;
+    }
+
+    protected function buildAuthContext(string $tokenUrl): array
+    {
+        $parts  = parse_url($tokenUrl) ?: [];
+        $scheme = $parts['scheme'] ?? null;
+        $host   = $parts['host'] ?? null;
+
+        return [
+            'auth_host' => $host ? trim(($scheme ? $scheme . '://' : '') . $host, '/') : null,
+            'auth_path' => $parts['path'] ?? null,
+            'realm_id'  => $this->credentials['realm_id'] ?? null,
+        ];
+    }
+
+    protected function safeDiagnosticMetadata(): array
+    {
+        return array_filter($this->authContext, fn ($value) => $value !== null && $value !== '');
+    }
+
     protected function safeeGet(string $endpoint): array
     {
         $response = Http::withHeaders($this->headers)
@@ -306,6 +360,17 @@ class SafeeProvider extends AbstractProvider
         return in_array(strtolower($status), ['offline', 'inactive', 'deleted', 'expired'], true) ? 'inactive' : 'active';
     }
 
+    protected function resolveOnline(array $payload): ?bool
+    {
+        if (array_key_exists('online', $payload)) {
+            return filter_var($payload['online'], FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? (bool) $payload['online'];
+        }
+
+        $status = $payload['status'] ?? $payload['vehicleStatus'] ?? null;
+
+        return $status ? $this->normalizeVehicleStatus($status) === 'active' : null;
+    }
+
     protected function extractOdometer(array $payload): mixed
     {
         return data_get($payload, 'canbus.odometer')

package/server/src/Support/Telematics/Providers/SamsaraProvider.php

@@ -2,6 +2,8 @@
 
 namespace Fleetbase\FleetOps\Support\Telematics\Providers;
 
+use Illuminate\Support\Carbon;
+
 /**
  * Class SamsaraProvider.
  *
@@ -78,30 +80,68 @@ class SamsaraProvider extends AbstractProvider
 
     public function normalizeDevice(array $payload): array
     {
+        $position = $this->extractPosition($payload);
+
         return [
-            'external_id'     => $payload['id'],
-            'device_name'     => $payload['name'] ?? 'Unknown Device',
-            'device_provider' => 'samsara',
-            'device_model'    => $payload['make'] ?? null,
-            'vin'             => $payload['vin'] ?? null,
-            'license_plate'   => $payload['licensePlate'] ?? null,
-            'status'          => 'active',
-            'meta'            => $payload,
+            'device_id'      => $payload['id'] ?? null,
+            'external_id'    => $payload['id'] ?? null,
+            'name'           => $payload['name'] ?? 'Unknown Device',
+            'provider'       => 'samsara',
+            'model'          => $payload['make'] ?? $payload['model'] ?? null,
+            'vin'            => $payload['vin'] ?? null,
+            'serial_number'  => $payload['serial'] ?? $payload['serialNumber'] ?? null,
+            'license_plate'  => $payload['licensePlate'] ?? null,
+            'status'         => $this->normalizeStatus($payload),
+            'online'         => $this->resolveOnline($payload),
+            'last_seen_at'   => $this->parseTimestamp($payload['time'] ?? data_get($payload, 'location.time') ?? data_get($payload, 'gps.time') ?? null),
+            'location'       => [
+                'lat' => $position['lat'] ?? null,
+                'lng' => $position['lng'] ?? null,
+            ],
+            'speed'      => $this->extractSpeed($payload),
+            'heading'    => $this->extractHeading($payload),
+            'altitude'   => $this->extractAltitude($payload),
+            'odometer'   => data_get($payload, 'odometerMeters') ?? data_get($payload, 'obdOdometerMeters.value'),
+            'fuel_level' => data_get($payload, 'fuelPercent.value') ?? data_get($payload, 'fuelPercent'),
+            'meta'       => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'status'         => $payload['status'] ?? null,
+                    'gateway_status' => data_get($payload, 'gateway.status'),
+                    'online'         => $payload['online'] ?? $payload['isOnline'] ?? data_get($payload, 'gateway.online'),
+                ], fn ($value) => $value !== null),
+            ],
         ];
     }
 
     public function normalizeEvent(array $payload): array
     {
+        $position = $this->extractPosition($payload);
+        $deviceId = data_get($payload, 'vehicle.id') ?? $payload['vehicleId'] ?? $payload['id'] ?? null;
+
         return [
-            'external_id' => $payload['id'] ?? null,
-            'device_id'   => $payload['vehicle']['id'] ?? $payload['vehicleId'] ?? null,
+            'external_id' => $payload['id'] ?? $deviceId,
+            'device_id'   => $deviceId,
             'event_type'  => $payload['eventType'] ?? 'vehicle_update',
-            'occurred_at' => $payload['time'] ?? now(),
+            'occurred_at' => $this->parseTimestamp($payload['time'] ?? data_get($payload, 'location.time') ?? data_get($payload, 'gps.time') ?? null) ?? now(),
+            'online'      => $this->resolveOnline($payload),
             'location'    => [
-                'lat' => $payload['location']['latitude'] ?? null,
-                'lng' => $payload['location']['longitude'] ?? null,
+                'lat' => $position['lat'] ?? null,
+                'lng' => $position['lng'] ?? null,
+            ],
+            'speed'      => $this->extractSpeed($payload),
+            'heading'    => $this->extractHeading($payload),
+            'altitude'   => $this->extractAltitude($payload),
+            'odometer'   => data_get($payload, 'odometerMeters') ?? data_get($payload, 'obdOdometerMeters.value'),
+            'fuel_level' => data_get($payload, 'fuelPercent.value') ?? data_get($payload, 'fuelPercent'),
+            'meta'       => [
+                'raw'             => $payload,
+                'provider_status' => array_filter([
+                    'status'         => $payload['status'] ?? null,
+                    'gateway_status' => data_get($payload, 'gateway.status'),
+                    'online'         => $payload['online'] ?? $payload['isOnline'] ?? data_get($payload, 'gateway.online'),
+                ], fn ($value) => $value !== null),
             ],
-            'meta' => $payload,
         ];
     }
 
@@ -176,4 +216,72 @@ class SamsaraProvider extends AbstractProvider
     {
         return true;
     }
+
+    protected function extractPosition(array $payload): array
+    {
+        $position = $payload['location']
+            ?? $payload['gps']
+            ?? $payload['currentLocation']
+            ?? $payload['lastKnownLocation']
+            ?? data_get($payload, 'vehicle.location')
+            ?? [];
+
+        return [
+            'lat' => $position['latitude'] ?? $position['lat'] ?? null,
+            'lng' => $position['longitude'] ?? $position['lng'] ?? null,
+        ];
+    }
+
+    protected function extractSpeed(array $payload): mixed
+    {
+        return data_get($payload, 'location.speedMilesPerHour')
+            ?? data_get($payload, 'location.speed')
+            ?? data_get($payload, 'gps.speedMilesPerHour')
+            ?? data_get($payload, 'speedMilesPerHour')
+            ?? data_get($payload, 'speed');
+    }
+
+    protected function extractHeading(array $payload): mixed
+    {
+        return data_get($payload, 'location.headingDegrees')
+            ?? data_get($payload, 'location.heading')
+            ?? data_get($payload, 'gps.headingDegrees')
+            ?? data_get($payload, 'headingDegrees')
+            ?? data_get($payload, 'heading');
+    }
+
+    protected function extractAltitude(array $payload): mixed
+    {
+        return data_get($payload, 'location.altitudeMeters')
+            ?? data_get($payload, 'gps.altitudeMeters')
+            ?? data_get($payload, 'altitudeMeters')
+            ?? data_get($payload, 'altitude');
+    }
+
+    protected function parseTimestamp($value): ?string
+    {
+        if (!$value) {
+            return null;
+        }
+
+        return Carbon::parse($value)->toDateTimeString();
+    }
+
+    protected function resolveOnline(array $payload): ?bool
+    {
+        $value = $payload['online'] ?? $payload['isOnline'] ?? data_get($payload, 'gateway.online') ?? null;
+
+        if ($value === null) {
+            return $this->extractPosition($payload)['lat'] !== null;
+        }
+
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? (bool) $value;
+    }
+
+    protected function normalizeStatus(array $payload): string
+    {
+        $status = strtolower((string) ($payload['status'] ?? data_get($payload, 'gateway.status') ?? 'active'));
+
+        return in_array($status, ['inactive', 'offline', 'deactivated'], true) ? 'inactive' : 'active';
+    }
 }