@fleetbase/fleetops-engine 0.6.64 → 0.6.66

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

@@ -3,9 +3,12 @@
 namespace Fleetbase\FleetOps\Support\Telematics\Providers;
 
 use Fleetbase\FleetOps\Exceptions\TelematicProviderException;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Fleetbase\FleetOps\Support\Telematics\Afaqy\Payload;
 use Illuminate\Http\Client\ConnectionException;
 use Illuminate\Http\Client\Response;
-use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Crypt;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Log;
 
@@ -15,7 +18,7 @@ use Illuminate\Support\Facades\Log;
  * AFAQY uses token-based REST endpoints for authentication, unit discovery,
  * latest unit telemetry, historical signals, and track generation.
  */
-class AfaqyProvider extends AbstractProvider
+class AfaqyProvider extends AbstractProvider implements \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface
 {
     protected string $baseUrl                   = 'https://api.afaqy.sa';
     protected int $requestsPerMinute            = 60;
@@ -27,7 +30,7 @@ class AfaqyProvider extends AbstractProvider
     protected function prepareAuthentication(): void
     {
         $this->baseUrl = rtrim($this->credentials['base_url'] ?? $this->baseUrl, '/');
-        $token         = $this->canRefreshToken() ? $this->authenticate() : ($this->credentials['token'] ?? null);
+        $token         = $this->canRefreshToken() ? $this->cachedToken() : ($this->credentials['token'] ?? null);
 
         if (!$token) {
             throw new \InvalidArgumentException('AFAQY username/password or token is required.');
@@ -44,7 +47,8 @@ class AfaqyProvider extends AbstractProvider
 
             $response = $this->afaqyPost('/units/lists', [
                 'data' => [
-                    'projection' => ['_id', 'name', 'imei', 'last_update'],
+                    'offset'     => 0, 'limit' => 1, 'simplify' => 0,
+                    'projection' => ['basic', 'last_update'],
                     'filters'    => new \stdClass(),
                 ],
             ], true, $this->connectionTestTimeout, $this->connectionTestConnectTimeout);
@@ -68,7 +72,7 @@ class AfaqyProvider extends AbstractProvider
 
     public function fetchDevices(array $options = []): array
     {
-        $limit   = max(1, min((int) ($options['limit'] ?? 500), 500));
+        $limit   = max(1, min((int) ($options['limit'] ?? 1000), 1000));
         $offset  = (int) ($options['cursor'] ?? 0);
         $filters = $options['filters'] ?? new \stdClass();
 
@@ -82,30 +86,36 @@ class AfaqyProvider extends AbstractProvider
                 'filters'    => $filters,
                 'limit'      => $limit,
                 'offset'     => $offset,
-                'projection' => $options['projection'] ?? [
-                    '_id',
-                    'name',
-                    'imei',
-                    'sim_number',
-                    'device_serial',
-                    'active',
-                    'driver_id',
-                    'last_update',
-                    'counters',
-                    'profile',
-                    'sensors_last_val',
-                ],
+                'simplify'   => 0,
+                'projection' => $options['projection'] ?? ['basic', 'last_update'],
             ],
-        ], true);
+        ], true, $options['timeout'] ?? null, $options['connect_timeout'] ?? null);
+
+        if (!isset($response['data']) || !is_array($response['data']) || !array_is_list($response['data'])) {
+            throw new TelematicProviderException('AFAQY returned an invalid units envelope.');
+        }
+        $devices = array_map(function ($unit) {
+            if (!is_array($unit)) {
+                throw new TelematicProviderException('AFAQY returned an invalid unit.');
+            }
 
-        $devices     = $response['data'] ?? [];
+            return Payload::unit($unit);
+        }, $response['data']);
         $pagination  = $response['pagination'] ?? [];
         $pageOffset  = (int) ($pagination['offset'] ?? $offset);
         $pageLimit   = (int) ($pagination['limit'] ?? $limit);
         $resultCount = (int) ($pagination['resultCount'] ?? count($devices));
-        $total       = (int) ($pagination['filtersCount'] ?? $pagination['allCount'] ?? count($devices));
-        $advanceBy   = $resultCount > 0 ? $resultCount : max($pageLimit, count($devices), 1);
-        $nextCursor  = ($pageOffset + $advanceBy) < $total ? $pageOffset + $advanceBy : null;
+        $total       = $pagination['filtersCount'] ?? $pagination['allCount'] ?? null;
+        if ($resultCount !== count($devices) || $pageLimit < 1 || ($total !== null && (int) $total < 0)) {
+            throw new TelematicProviderException('AFAQY returned inconsistent pagination; sweep incomplete.');
+        }
+        $advanceBy = count($devices);
+        if ($pageOffset !== $offset || ($devices === [] && $total !== null && $offset < (int) $total)) {
+            throw new TelematicProviderException('AFAQY pagination did not advance; sweep incomplete.');
+        }
+        $nextCursor = $total !== null
+            ? (($pageOffset + $advanceBy) < (int) $total ? $pageOffset + $advanceBy : null)
+            : (count($devices) >= max(1, $pageLimit) ? $pageOffset + count($devices) : null);
 
         Log::info('AFAQY units page fetched', [
             'telematic_uuid'        => $this->telematic?->uuid,
@@ -146,21 +156,22 @@ class AfaqyProvider extends AbstractProvider
 
     public function normalizeDevice(array $payload): array
     {
+        $payload    = Payload::unit($payload);
         $lastUpdate = $payload['last_update'] ?? [];
         $profile    = $payload['profile'] ?? [];
 
         return [
             'device_id'    => $payload['_id'] ?? $payload['id'] ?? null,
             'external_id'  => $payload['_id'] ?? $payload['id'] ?? null,
-            'name'         => $payload['name'] ?? data_get($payload, 'profile.plate_number') ?? 'Unknown Unit',
+            'name'         => $payload['name'] ?? data_get($payload, 'profile.plate_number') ?? null,
             'provider'     => 'afaqy',
             'model'        => data_get($payload, 'profile.model') ?? $payload['device'] ?? null,
             'imei'         => $payload['imei'] ?? null,
             'phone'        => $payload['sim_number'] ?? null,
             'vin'          => data_get($payload, 'profile.vin'),
-            'status'       => ($payload['active'] ?? false) ? 'active' : 'inactive',
-            'online'       => $payload['active'] ?? null,
-            'last_seen_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
+            'status'       => array_key_exists('active', $payload) ? ($payload['active'] ? 'active' : 'inactive') : null,
+            'online'       => null,
+            'last_seen_at' => $this->parseTimestamp($lastUpdate['dts'] ?? $lastUpdate['dtt'] ?? null),
             'location'     => [
                 'lat' => $lastUpdate['lat'] ?? null,
                 'lng' => $lastUpdate['lng'] ?? null,
@@ -174,18 +185,19 @@ class AfaqyProvider extends AbstractProvider
                 'sim_number'       => $payload['sim_number'] ?? null,
                 'driver_id'        => $payload['driver_id'] ?? null,
                 'last_update'      => $this->compactLastUpdate($lastUpdate),
-                'capabilities'     => [
-                    'tracking'       => isset($lastUpdate['lat'], $lastUpdate['lng']),
-                    'odometer'       => data_get($payload, 'counters.odometer') !== null,
-                    'fuel_level'     => $this->extractFuelLevel($payload) !== null,
-                    'ignition_state' => $this->extractIgnition($payload) !== null,
-                ],
+                'capabilities'     => array_filter([
+                    'tracking'       => isset($lastUpdate['lat'], $lastUpdate['lng']) ? true : null,
+                    'odometer'       => data_get($payload, 'counters.odometer') !== null ? true : null,
+                    'fuel_level'     => $this->extractFuelLevel($payload) !== null ? true : null,
+                    'ignition_state' => $this->extractIgnition($payload) !== null ? true : null,
+                ], fn ($value) => $value !== null),
             ],
         ];
     }
 
     public function normalizeEvent(array $payload): array
     {
+        $payload    = Payload::unit($payload);
         $lastUpdate = $payload['last_update'] ?? $payload;
 
         return [
@@ -193,22 +205,61 @@ class AfaqyProvider extends AbstractProvider
             'device_id'   => $payload['_id'] ?? $payload['id'] ?? null,
             'event_type'  => $payload['event'] ?? $payload['event_type'] ?? 'telemetry_update',
             'message'     => $payload['message'] ?? $payload['event'] ?? null,
-            'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
-            'online'      => $payload['active'] ?? null,
+            'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? null),
+            'online'      => null,
             'location'    => [
                 'lat' => $lastUpdate['lat'] ?? data_get($lastUpdate, 'loc.coordinates.1'),
                 'lng' => $lastUpdate['lng'] ?? data_get($lastUpdate, 'loc.coordinates.0'),
             ],
-            'speed'      => $lastUpdate['speed'] ?? $lastUpdate['spd'] ?? null,
-            'heading'    => $lastUpdate['angle'] ?? $lastUpdate['ang'] ?? null,
-            'altitude'   => $lastUpdate['alt'] ?? null,
-            'odometer'   => data_get($payload, 'counters.odometer'),
-            'ignition'   => $this->extractIgnition($payload),
-            'fuel_level' => $this->extractFuelLevel($payload),
-            'meta'       => $payload,
+            'speed'        => $lastUpdate['speed'] ?? $lastUpdate['spd'] ?? null,
+            'heading'      => $lastUpdate['angle'] ?? $lastUpdate['ang'] ?? null,
+            'altitude'     => $lastUpdate['alt'] ?? null,
+            'odometer'     => data_get($payload, 'counters.odometer'),
+            'ignition'     => $this->extractIgnition($payload),
+            'fuel_level'   => $this->extractFuelLevel($payload),
+            'last_seen_at' => $this->parseTimestamp($lastUpdate['dts'] ?? $lastUpdate['dtt'] ?? null),
+            'meta'         => array_merge($payload, ['telemetry' => [
+                'position_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? null),
+                'provider_at' => $this->parseTimestamp($lastUpdate['dts'] ?? null),
+            ]]),
         ];
     }
 
+    public function telemetryOptions(): array
+    {
+        return config('telematics.afaqy', []);
+    }
+
+    public function telemetryUnits(array $payload): array
+    {
+        return Payload::units($payload);
+    }
+
+    public function normalizeTelemetrySnapshot(array $payload): array
+    {
+        $payload    = Payload::unit($payload);
+        $device     = $this->normalizeDevice($payload);
+        $event      = $this->normalizeEvent($payload);
+        $sensors    = [];
+        $rawSensors = $payload['sensors'] ?? $payload['sensors_last_val'] ?? [];
+        // sensors_chDate is not a documented collection of latest sensor values.
+        foreach (is_array($rawSensors) ? $rawSensors : [] as $name => $sensor) {
+            if (!is_array($sensor)) {
+                $sensor = ['sensor_key' => (string) $name, 'name' => (string) $name, 'value' => $sensor];
+            }
+            try {
+                $sensors[] = $this->normalizeSensor(array_merge([
+                    'device_id'  => $device['device_id'], 'sensor_key' => is_string($name) ? $name : null,
+                    'updated_at' => $event['occurred_at'],
+                ], $sensor));
+            } catch (\InvalidArgumentException) {
+                // Protocol descriptors without scalar values are not sensor readings.
+            }
+        }
+
+        return compact('device', 'event', 'sensors');
+    }
+
     public function normalizeSensor(array $payload): array
     {
         $unitId         = $payload['device_id'] ?? $payload['unit_id'] ?? $payload['vehicle_id'] ?? null;
@@ -291,6 +342,7 @@ class AfaqyProvider extends AbstractProvider
             throw new \InvalidArgumentException('AFAQY username/password or token is required.');
         }
 
+        $this->reserveRequest();
         $response = Http::asJson()
             ->acceptJson()
             ->timeout(30)
@@ -298,10 +350,10 @@ class AfaqyProvider extends AbstractProvider
                 'data' => [
                     'username' => $this->credentials['username'],
                     'password' => $this->credentials['password'],
-                    'expire'   => $this->credentials['expire'] ?? 1,
                 ],
             ]);
 
+        $this->checkThrottle($response);
         if ($response->failed()) {
             throw new TelematicProviderException('AFAQY authentication failed with status ' . $response->status(), $this->providerErrorContext('/auth/login', $response, false));
         }
@@ -328,6 +380,7 @@ class AfaqyProvider extends AbstractProvider
         $timeout ??= $this->dataTimeout;
         $connectTimeout ??= $this->connectTimeout;
 
+        $this->reserveRequest();
         try {
             $response = Http::withHeaders($this->headers)
                 ->timeout($timeout)
@@ -337,6 +390,7 @@ class AfaqyProvider extends AbstractProvider
             throw new TelematicProviderException('AFAQY API request timed out while waiting for provider response.', $this->transportErrorContext($endpoint, $payload, $e, !$allowRetry, $startedAt, $timeout, $connectTimeout), previous: $e);
         }
 
+        $this->checkThrottle($response);
         if ($this->isTokenRejected($response)) {
             if (!$allowRetry || !$this->canRefreshToken()) {
                 $message = $this->canRefreshToken()
@@ -357,7 +411,12 @@ class AfaqyProvider extends AbstractProvider
             throw new TelematicProviderException('AFAQY API request failed with status ' . $response->status(), $this->providerErrorContext($endpoint, $response, !$allowRetry));
         }
 
-        return $response->json() ?? [];
+        $json = $response->json();
+        if (!is_array($json) || (isset($json['status_code']) && (int) $json['status_code'] >= 400)) {
+            throw new TelematicProviderException('AFAQY returned an invalid or unsuccessful response.');
+        }
+
+        return $json;
     }
 
     protected function buildAuthenticatedRequest(string $endpoint, array $payload = [], bool $tokenInQuery = false): array
@@ -384,9 +443,68 @@ class AfaqyProvider extends AbstractProvider
 
     protected function refreshToken(): void
     {
-        unset($this->credentials['token']);
+        $rejected = $this->credentials['token'] ?? null;
+        $this->setToken($this->cachedToken($rejected));
+    }
+
+    public function supportsWebhooks(): bool
+    {
+        return true;
+    }
+
+    public function processWebhook(array $payload, array $headers = []): array
+    {
+        $units = Payload::units($payload);
 
-        $this->setToken($this->authenticate());
+        return ['devices' => array_map([$this, 'normalizeDevice'], $units), 'events' => array_map([$this, 'normalizeEvent'], $units), 'sensors' => []];
+    }
+
+    protected function accountKey(): string
+    {
+        return hash('sha256', $this->baseUrl . '|' . ($this->credentials['username'] ?? $this->credentials['token'] ?? ''));
+    }
+
+    protected function cachedToken(?string $rejected = null): string
+    {
+        $key = 'afaqy:token:' . $this->accountKey() . ':' . hash('sha256', $this->credentials['password'] ?? '');
+
+        return Cache::lock($key . ':lock', 40)->block(5, function () use ($key, $rejected) {
+            $stored = Cache::get($key);
+            $token  = $stored ? Crypt::decryptString($stored) : null;
+            if (!$token || $token === $rejected) {
+                $token = $this->authenticate();
+                Cache::put($key, Crypt::encryptString($token), 29 * 86400);
+            }
+
+            return $token;
+        });
+    }
+
+    protected function reserveRequest(): void
+    {
+        $key = 'afaqy:rate:' . $this->accountKey();
+        Cache::lock($key . ':lock', 5)->block(2, function () use ($key) {
+            $now      = microtime(true);
+            $until    = (float) Cache::get($key . ':blocked', 0);
+            $requests = array_values(array_filter(Cache::get($key, []), fn ($at) => $at > $now - 60));
+            if ($until > $now || count($requests) >= 60) {
+                throw new TelematicRateLimitExceededException('AFAQY request budget exhausted.', ['retry_after' => max(1, (int) ceil(max($until, ($requests[0] ?? $now) + 60) - $now))]);
+            }
+            $requests[] = $now;
+            Cache::put($key, $requests, 61);
+        });
+    }
+
+    protected function checkThrottle(Response $response): void
+    {
+        if ($response->status() !== 429) {
+            return;
+        }
+        $header = $response->header('Retry-After');
+        $delay  = is_numeric($header) ? (int) $header : max(1, (strtotime($header ?: '') ?: time() + 60) - time());
+        $delay  = max(1, min($delay, 3600));
+        Cache::put('afaqy:rate:' . $this->accountKey() . ':blocked', microtime(true) + $delay, $delay);
+        throw new TelematicRateLimitExceededException('AFAQY rate limited the request.', ['retry_after' => $delay]);
     }
 
     protected function canRefreshToken(): bool
@@ -421,7 +539,17 @@ class AfaqyProvider extends AbstractProvider
             ?? data_get($json, 'error_description')
             ?? data_get($json, 'error');
 
-        return is_scalar($message) ? (string) $message : null;
+        if (!is_scalar($message)) {
+            return null;
+        }
+        $message = (string) $message;
+        foreach (['token', 'password'] as $secret) {
+            if (!empty($this->credentials[$secret])) {
+                $message = str_replace($this->credentials[$secret], '[redacted]', $message);
+            }
+        }
+
+        return preg_replace('/(token|password|key)=([^&\s]+)/i', '$1=[redacted]', $message);
     }
 
     protected function transportErrorContext(string $endpoint, array $payload, ConnectionException $e, bool $retryAttempted, float $startedAt, int $timeout, int $connectTimeout): array
@@ -454,7 +582,8 @@ class AfaqyProvider extends AbstractProvider
         $params = $lastUpdate['params'] ?? $lastUpdate['prms'] ?? [];
 
         return array_filter([
-            'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
+            'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? null),
+            'provider_at' => $this->parseTimestamp($lastUpdate['dts'] ?? null),
             'lat'         => $lastUpdate['lat'] ?? null,
             'lng'         => $lastUpdate['lng'] ?? null,
             'speed'       => $lastUpdate['speed'] ?? $lastUpdate['spd'] ?? null,
@@ -467,24 +596,13 @@ class AfaqyProvider extends AbstractProvider
 
     protected function parseTimestamp($value): ?string
     {
-        if (!$value) {
-            return null;
-        }
-
-        if (is_numeric($value)) {
-            $timestamp = (float) $value;
-            $seconds   = $timestamp > 9999999999 ? $timestamp / 1000 : $timestamp;
-
-            return Carbon::createFromTimestamp($seconds)->toDateTimeString();
-        }
-
-        return Carbon::parse($value)->toDateTimeString();
+        return Payload::timestamp($value);
     }
 
     protected function extractIgnition(array $payload): ?bool
     {
         $params = data_get($payload, 'last_update.params', []);
-        $value  = data_get($params, 'acc') ?? data_get($params, 'di1') ?? data_get($payload, 'counters.last_acc');
+        $value  = data_get($payload, 'last_update.acc') ?? data_get($params, 'acc') ?? data_get($params, 'di1') ?? data_get($payload, 'counters.last_acc');
 
         if ($value === null) {
             return null;

package/server/src/Support/Telematics/TelematicService.php

@@ -3,6 +3,7 @@
 namespace Fleetbase\FleetOps\Support\Telematics;
 
 use Fleetbase\FleetOps\Contracts\TelematicProviderInterface;
+use Fleetbase\FleetOps\Events\TrailerLocationChanged;
 use Fleetbase\FleetOps\Events\VehicleLocationChanged;
 use Fleetbase\FleetOps\Jobs\SyncTelematicDevicesJob;
 use Fleetbase\FleetOps\Jobs\TestTelematicConnectionJob;
@@ -10,6 +11,7 @@ use Fleetbase\FleetOps\Models\Device;
 use Fleetbase\FleetOps\Models\DeviceEvent;
 use Fleetbase\FleetOps\Models\Sensor;
 use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Illuminate\Support\Carbon;
@@ -192,6 +194,9 @@ class TelematicService
 
     public function ingestDeviceSnapshot(Telematic $telematic, TelematicProviderInterface $provider, array $payload): array
     {
+        if ($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface) {
+            return app(Telemetry\Ingestor::class)->ingest($telematic, $provider, $payload, $this);
+        }
         $device = $this->linkDevice($telematic, $provider->normalizeDevice($payload));
 
         $event  = null;
@@ -294,9 +299,13 @@ class TelematicService
             'internal_id'    => $sensorIdentity ?? $this->makeSensorIdentity($sensorData, $device),
         ]);
 
+        if (($sensorData['_ordered_telemetry'] ?? false) && $sensor->exists && $sensor->last_reading_at
+            && (!$sensorData['recorded_at'] || Carbon::parse($sensorData['recorded_at'])->lte(Carbon::parse($sensor->last_reading_at)))) {
+            return $sensor;
+        }
         $sensor->company_uuid     = $telematic->company_uuid;
         $sensor->name             = $sensorData['name'] ?? $sensorData['sensor_type'] ?? $sensor->type ?? 'Sensor';
-        $sensor->unit             = $sensorData['unit'] ?? null;
+        $sensor->unit             = $sensorData['unit'] ?? (($sensorData['_ordered_telemetry'] ?? false) ? $sensor->unit : null);
         $sensor->last_value       = isset($sensorData['value']) ? (string) $sensorData['value'] : $sensor->last_value;
         $sensor->last_reading_at  = $sensorData['recorded_at'] ?? $sensorData['last_reading_at'] ?? $sensor->last_reading_at ?? now();
         $sensor->status           = $sensorData['status'] ?? 'active';
@@ -533,7 +542,8 @@ class TelematicService
             $device->status = $connectionStatus;
         }
 
-        $device->meta = array_merge($device->meta ?? [], [
+        $mergeMeta    = ($payload['_ordered_telemetry'] ?? false) ? 'array_replace_recursive' : 'array_merge';
+        $device->meta = $mergeMeta($device->meta ?? [], [
             'external_id'       => $externalId,
             'provider_status'   => array_filter([
                 'status'    => $payload['status'] ?? null,
@@ -634,6 +644,10 @@ class TelematicService
     protected function applyDeviceEventTelemetry(DeviceEvent $event, array $eventData, ?Device $device = null, bool $wasRecentlyCreated = true, ?Telematic $telematic = null): void
     {
         $location = $this->normalizeLocation($eventData['location'] ?? null);
+        if (($eventData['_history_only'] ?? false) && ($eventData['_ordered_telemetry'] ?? false)) {
+            // DeviceEvent retains source-time history; Position would timestamp this old fix as current.
+            return;
+        }
 
         $device ??= $event->device;
         if ($device) {
@@ -652,9 +666,50 @@ class TelematicService
         }
 
         $attachable = $device?->attachable;
+        if (($eventData['_ordered_telemetry'] ?? false) && $attachable) {
+            $attachable = $attachable->newQuery()->where('uuid', $attachable->uuid)->lockForUpdate()->first();
+            $currentAt  = data_get($attachable?->telematics, 'last_event_at');
+            if ($currentAt && $event->occurred_at && $event->occurred_at->lte(Carbon::parse($currentAt))) {
+                return;
+            }
+        }
         if ($attachable instanceof Vehicle) {
             $this->updateVehicleTelemetry($attachable, $location, $eventData, $event);
+        } elseif ($attachable instanceof Trailer) {
+            $this->updateTrailerTelemetry($attachable, $location, $eventData, $event);
+        }
+    }
+
+    protected function updateTrailerTelemetry(Trailer $trailer, array $location, array $eventData, DeviceEvent $event): void
+    {
+        $observedAt = $event->occurred_at ?? $event->created_at ?? now();
+        $currentAt  = data_get($trailer->telematics, 'last_event_at');
+        if ($currentAt && $observedAt->lt(Carbon::parse($currentAt))) {
+            return;
+        }
+
+        $trailer->location       = new SpatialPoint($location['latitude'], $location['longitude']);
+        $trailer->online         = array_key_exists('online', $eventData) && $eventData['online'] !== null ? (bool) $eventData['online'] : true;
+        $trailer->last_online_at = $observedAt;
+        foreach (['speed', 'heading', 'altitude', 'odometer', 'reefer_engine_hours'] as $field) {
+            if (array_key_exists($field, $eventData) && $eventData[$field] !== null) {
+                $trailer->{$field} = $eventData[$field];
+            }
         }
+
+        $trailer->telematics = array_merge($trailer->telematics ?? [], [
+            'last_event_uuid'     => $event->uuid,
+            'last_event_id'       => $event->public_id,
+            'last_event_type'     => $event->event_type,
+            'last_event_at'       => $observedAt->toISOString(),
+            'last_device_uuid'    => $event->device_uuid,
+            'last_provider'       => $event->provider,
+            'last_telemetry_data' => array_filter($eventData, fn ($value) => $value !== null),
+        ]);
+        $trailer->save();
+
+        $broadcast = new TrailerLocationChanged($trailer, ['source' => 'telematics', 'device_event_uuid' => $event->uuid, 'provider' => $event->provider, 'position_at' => $event->occurred_at?->toISOString()]);
+        $this->broadcastTelemetry($broadcast, $eventData['_ordered_telemetry'] ?? false);
     }
 
     protected function updateVehicleTelemetry(Vehicle $vehicle, array $location, array $eventData, DeviceEvent $event): void
@@ -682,7 +737,7 @@ class TelematicService
             'last_event_uuid'     => $event->uuid,
             'last_event_id'       => $event->public_id,
             'last_event_type'     => $event->event_type,
-            'last_event_at'       => optional($event->occurred_at)->toDateTimeString() ?? now()->toDateTimeString(),
+            'last_event_at'       => ($eventData['_ordered_telemetry'] ?? false) ? $event->occurred_at?->toISOString() : (optional($event->occurred_at)->toDateTimeString() ?? now()->toDateTimeString()),
             'last_device_uuid'    => $event->device_uuid,
             'last_provider'       => $event->provider,
             'last_telemetry_data' => array_filter([
@@ -696,11 +751,22 @@ class TelematicService
         ]);
         $vehicle->save();
 
-        broadcast(new VehicleLocationChanged($vehicle, [
+        $broadcast = new VehicleLocationChanged($vehicle, [
             'source'            => 'telematics',
             'device_event_uuid' => $event->uuid,
             'provider'          => $event->provider,
-        ]));
+            'position_at'       => $event->occurred_at?->toISOString(),
+        ]);
+        $this->broadcastTelemetry($broadcast, $eventData['_ordered_telemetry'] ?? false);
+    }
+
+    protected function broadcastTelemetry(object $event, bool $afterCommit): void
+    {
+        if ($afterCommit) {
+            \Illuminate\Support\Facades\DB::afterCommit(fn () => broadcast($event));
+        } else {
+            broadcast($event);
+        }
     }
 
     protected function makePositionData(array $location, array $eventData): array

package/server/src/Support/Telematics/Telemetry/Configuration.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Telemetry;
+
+use Fleetbase\FleetOps\Contracts\TelemetryProviderInterface;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+
+class Configuration
+{
+    public static function provider(Telematic $connection): TelemetryProviderInterface
+    {
+        $provider = app(TelematicProviderRegistry::class)->resolve($connection->provider);
+        if (!$provider instanceof TelemetryProviderInterface) {
+            throw new \InvalidArgumentException('Provider does not support durable position ingestion.');
+        }
+
+        return $provider;
+    }
+
+    public static function options(TelemetryProviderInterface $provider): array
+    {
+        return array_replace(config('telematics.telemetry', []), $provider->telemetryOptions());
+    }
+
+    public static function forConnection(Telematic $connection): array
+    {
+        return self::options(self::provider($connection));
+    }
+}

package/server/src/Support/Telematics/Telemetry/Inbox.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Telemetry;
+
+use Fleetbase\FleetOps\Jobs\ProcessTelematicDelivery;
+use Fleetbase\FleetOps\Models\Telematic;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class Inbox
+{
+    public function accept(Telematic $telematic, array $payload, string $source, ?string $run = null, ?string $receivedAt = null): string
+    {
+        $json = json_encode($payload, JSON_THROW_ON_ERROR);
+        $id   = (string) Str::uuid();
+        DB::table('telematic_deliveries')->insert([
+            'uuid'         => $id, 'telematic_uuid' => $telematic->uuid, 'run_uuid' => $run,
+            'source'       => $source, 'status' => 'pending', 'payload_hash' => hash('sha256', $json),
+            'payload'      => Crypt::encryptString($json), 'received_at' => $receivedAt ?? now()->utc()->toDateTimeString(),
+            'available_at' => now(), 'created_at' => now(), 'updated_at' => now(),
+        ]);
+        // The scheduled drain also dispatches pending records if the broker is unavailable.
+        try {
+            Queue::dispatch((new ProcessTelematicDelivery($id))->onQueue(Configuration::forConnection($telematic)['ingestion_queue'] ?? 'default'));
+        } catch (\Throwable) {
+            // Durable acceptance succeeded. The payload must not be logged here.
+        }
+
+        return $id;
+    }
+
+    public static function enabled(Telematic $telematic): bool
+    {
+        return (bool) $telematic->company_uuid
+            && in_array($telematic->status, ['active', 'connected', 'error', 'synchronizing'], true)
+            && data_get($telematic->meta, 'telemetry_sync_enabled', true) !== false;
+    }
+
+    public static function finishRun(?string $id): void
+    {
+        if (!$id) {
+            return;
+        }
+        DB::transaction(function () use ($id) {
+            $run = DB::table('telematic_sync_runs')->where('uuid', $id)->lockForUpdate()->first();
+            if (!$run || $run->status === 'fetching') {
+                return;
+            }
+            $items = DB::table('telematic_deliveries')->where('run_uuid', $id);
+            if ((clone $items)->whereIn('status', ['pending', 'processing', 'retry'])->exists()) {
+                return;
+            }
+            $failed = (clone $items)->sum('failed');
+            DB::table('telematic_sync_runs')->where('uuid', $id)->update([
+                'status'  => $run->status === 'incomplete' ? 'incomplete' : ($failed ? 'partial' : 'completed'),
+                'applied' => (clone $items)->sum('applied'), 'failed' => $failed, 'updated_at' => now(),
+            ]);
+        });
+    }
+}