@fleetbase/fleetops-engine 0.6.65 → 0.6.67

package/server/src/Support/Telematics/Safee/Transport.php

@@ -0,0 +1,210 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Safee;
+
+use Fleetbase\FleetOps\Exceptions\TelematicProviderException;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Http;
+
+/** Safee's documented OAuth and per-user request budget, shared across workers. */
+class Transport
+{
+    protected ?string $token    = null;
+    protected ?float $expiresAt = null;
+
+    public function __construct(protected string $baseUrl, protected array $credentials)
+    {
+        $this->token = $credentials['access_token'] ?? null;
+    }
+
+    public function fingerprint(): string
+    {
+        $credentials = $this->credentials;
+        ksort($credentials);
+
+        return hash('sha256', $this->baseUrl . '|' . json_encode($credentials, JSON_THROW_ON_ERROR));
+    }
+
+    public function accountKey(): string
+    {
+        return hash('sha256', implode('|', [$this->baseUrl, $this->credentials['realm_id'] ?? '', $this->credentials['username'] ?? $this->credentials['access_token'] ?? '']));
+    }
+
+    public function request(string $method, string $endpoint, array|\stdClass $payload, float $deadline, int $timeout, int $connectTimeout): array
+    {
+        $refreshed = false;
+        while (true) {
+            if (!$this->token || ($this->expiresAt !== null && $this->expiresAt <= $this->wallTime() + 5)) {
+                $this->token = $this->cachedToken($deadline, $timeout, $connectTimeout);
+            }
+            $this->reserveRequest($deadline);
+            try {
+                $request = Http::withHeaders([
+                    'Accept'          => 'application/json', 'Content-Type' => 'application/json',
+                    'Accept-Language' => $this->credentials['language'] ?? 'en',
+                    'Authorization'   => trim(($this->credentials['authorization_scheme'] ?? 'Bearer') . ' ' . $this->token),
+                ])->timeout($this->remaining($deadline, $timeout))
+                    ->connectTimeout($this->remaining($deadline, $connectTimeout));
+                $response = $method === 'GET' ? $request->get($this->baseUrl . $endpoint) : $request->post($this->baseUrl . $endpoint, $payload);
+            } catch (ConnectionException $e) {
+                throw new TelematicProviderException('Safee request timed out or could not connect.', ['endpoint' => $endpoint], previous: $e);
+            }
+            $this->checkThrottle($response);
+            // A rejected token is refreshed once; a second rejection fails as an unsuccessful response.
+            if ($response->status() === 401 && !$refreshed && $this->canAuthenticate()) {
+                $refreshed   = true;
+                $this->token = $this->cachedToken($deadline, $timeout, $connectTimeout, $this->token);
+                continue;
+            }
+            if ($response->failed()) {
+                throw new TelematicProviderException('Safee API request failed with status ' . $response->status(), ['endpoint' => $endpoint, 'status' => $response->status()]);
+            }
+            $json = $response->json();
+            if (!is_array($json) || !array_key_exists('code', $json) || !is_numeric($json['code']) || (float) $json['code'] !== 0.0) {
+                throw new TelematicProviderException('Safee returned an invalid or unsuccessful response.', ['endpoint' => $endpoint]);
+            }
+
+            return $json;
+        }
+    }
+
+    public function authenticate(float $deadline, int $timeout = 30, int $connectTimeout = 5): string
+    {
+        return $this->cachedToken($deadline, $timeout, $connectTimeout);
+    }
+
+    protected function canAuthenticate(): bool
+    {
+        foreach (['realm_id', 'client_id', 'client_secret', 'username', 'password'] as $field) {
+            if (empty($this->credentials[$field])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    protected function cachedToken(float $deadline, int $timeout, int $connectTimeout, ?string $rejected = null): string
+    {
+        if (!$this->canAuthenticate()) {
+            throw new \InvalidArgumentException('Safee realm, client and user credentials are required to authenticate.');
+        }
+        $key = 'safee:token:' . $this->fingerprint();
+
+        return Cache::lock($key . ':lock', 60)->block($this->remaining($deadline, 2), function () use ($key, $deadline, $timeout, $connectTimeout, $rejected) {
+            $cached = null;
+            if ($encrypted = Cache::get($key)) {
+                try {
+                    $cached = json_decode(Crypt::decryptString($encrypted), true, 512, JSON_THROW_ON_ERROR);
+                } catch (DecryptException|\JsonException) {
+                    // Only the disposable token cache is recoverable this way.
+                    Cache::forget($key);
+                }
+            }
+            if (is_array($cached) && is_string($cached['access_token'] ?? null) && $cached['access_token'] !== $rejected && ($cached['expires_at'] ?? 0) > $this->wallTime() + 5) {
+                $this->expiresAt = (float) $cached['expires_at'];
+
+                return $cached['access_token'];
+            }
+            $refresh         = is_array($cached) && is_string($cached['refresh_token'] ?? null) ? $cached['refresh_token'] : null;
+            $tokens          = $this->tokenRequest($deadline, $timeout, $connectTimeout, $refresh);
+            $lifetime        = is_numeric($tokens['expires_in'] ?? null) ? max(0, (int) $tokens['expires_in']) : 0;
+            $this->expiresAt = $lifetime > 0 ? $this->wallTime() + $lifetime : null;
+            if ($lifetime > 0) {
+                $tokens['expires_at'] = $this->expiresAt;
+                Cache::put($key, Crypt::encryptString(json_encode($tokens, JSON_THROW_ON_ERROR)), max($lifetime, min(86400, (int) ($tokens['refresh_expires_in'] ?? $lifetime))));
+            } else {
+                // An undocumented expiry must not create a long-lived cached token.
+                Cache::forget($key);
+            }
+
+            return $tokens['access_token'];
+        });
+    }
+
+    protected function tokenRequest(float $deadline, int $timeout, int $connectTimeout, ?string $refresh = null): array
+    {
+        $body = ['grant_type' => $refresh ? 'refresh_token' : 'password', 'client_id' => $this->credentials['client_id'], 'client_secret' => $this->credentials['client_secret']];
+        $body += $refresh ? ['refresh_token' => $refresh] : ['username' => $this->credentials['username'], 'password' => $this->credentials['password']];
+        $this->reserveRequest($deadline);
+        try {
+            $response = Http::asForm()->acceptJson()->timeout($this->remaining($deadline, $timeout))
+                ->connectTimeout($this->remaining($deadline, $connectTimeout))
+                ->post($this->baseUrl . '/auth/realms/' . rawurlencode($this->credentials['realm_id']) . '/protocol/openid-connect/token', $body);
+        } catch (ConnectionException $e) {
+            throw new TelematicProviderException('Safee authentication timed out or could not connect.', previous: $e);
+        }
+        $this->checkThrottle($response);
+        // Expired/revoked refresh tokens may be exchanged for a new password grant once.
+        if ($refresh && in_array($response->status(), [400, 401], true)) {
+            return $this->tokenRequest($deadline, $timeout, $connectTimeout);
+        }
+        if ($response->failed()) {
+            throw new TelematicProviderException('Safee authentication failed with status ' . $response->status());
+        }
+        $tokens = $response->json();
+        if (!is_array($tokens) || !is_string($tokens['access_token'] ?? null) || $tokens['access_token'] === '') {
+            throw new TelematicProviderException('Safee authentication did not return an access token.');
+        }
+
+        return array_intersect_key($tokens, array_flip(['access_token', 'refresh_token', 'expires_in', 'refresh_expires_in']));
+    }
+
+    protected function reserveRequest(float $deadline): void
+    {
+        $key = 'safee:rate:' . $this->accountKey();
+        Cache::lock($key . ':lock', 5)->block($this->remaining($deadline, 2), function () use ($key, $deadline) {
+            $this->remaining($deadline, 1);
+            $now      = $this->wallTime();
+            $until    = (float) Cache::get($key . ':blocked', 0);
+            $requests = array_values(array_filter(Cache::get($key, []), fn ($at) => $at > $now - 1));
+            if ($until > $now || count($requests) >= 50) {
+                throw new TelematicRateLimitExceededException('Safee request budget exhausted.', ['retry_after' => max(1, (int) ceil(max($until, ($requests[0] ?? $now) + 1) - $now))]);
+            }
+            $requests[] = $now;
+            Cache::put($key, $requests, 2);
+        });
+    }
+
+    protected function checkThrottle(Response $response): void
+    {
+        if ($response->status() !== 429) {
+            return;
+        }
+        $header = $response->header('Retry-After');
+        $delay  = is_numeric($header) ? (int) ceil((float) $header) : max(1, (strtotime($header ?: '') ?: time() + 1) - time());
+        $delay  = max(1, min($delay, 3600));
+        $key    = 'safee:rate:' . $this->accountKey();
+        Cache::lock($key . ':lock', 5)->block(1, function () use ($key, $delay) {
+            $until = max((float) Cache::get($key . ':blocked', 0), $this->wallTime() + $delay);
+            Cache::put($key . ':blocked', $until, (int) ceil($until - $this->wallTime()));
+        });
+
+        throw new TelematicRateLimitExceededException('Safee rate limited the request.', ['retry_after' => $delay]);
+    }
+
+    protected function remaining(float $deadline, int $maximum): int
+    {
+        $remaining = (int) floor($deadline - $this->time());
+        if ($remaining < 1) {
+            throw new TelematicProviderException('Safee request time budget exhausted before another operation could start.');
+        }
+
+        return min(max(1, $maximum), $remaining);
+    }
+
+    protected function time(): float
+    {
+        return hrtime(true) / 1_000_000_000;
+    }
+
+    protected function wallTime(): float
+    {
+        return microtime(true);
+    }
+}

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

@@ -152,6 +152,11 @@ class TelematicService
      */
     public function discoverDevices(Telematic $telematic, array $options = []): string
     {
+        $provider = $this->registry->resolve($telematic->provider);
+        if ($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface
+            && (Telemetry\Configuration::options($provider)['manual_batch_sync'] ?? false)) {
+            return $this->queueTelemetrySync($telematic, $options);
+        }
         $jobId = (string) Str::uuid();
         dispatch(new SyncTelematicDevicesJob($telematic, $options, $jobId));
 
@@ -167,6 +172,41 @@ class TelematicService
         return $jobId;
     }
 
+    /** Queue current telemetry through bounded, durable batches for opted-in providers. */
+    public function queueTelemetrySync(Telematic $telematic, array $options = [], ?string $jobId = null): string
+    {
+        $settings = Telemetry\Configuration::options($this->registry->resolve($telematic->provider));
+        if (!Telemetry\Inbox::enabled($telematic) || !($settings['polling_enabled'] ?? false)) {
+            throw ValidationException::withMessages(['telematic' => ['Telemetry synchronization is disabled for this connection.']]);
+        }
+        $jobId ??= (string) Str::uuid();
+
+        return \Illuminate\Support\Facades\DB::transaction(function () use ($telematic, $options, $settings, $jobId) {
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $telematic->uuid)->lockForUpdate()->firstOrFail();
+            if (!Telemetry\Inbox::enabled($connection)) {
+                throw ValidationException::withMessages(['telematic' => ['Telemetry synchronization is disabled for this connection.']]);
+            }
+            $job = (new \Fleetbase\FleetOps\Jobs\PollTelematicTelemetry($connection->uuid, $jobId, $options))
+                ->onQueue($settings['poll_queue'] ?? 'default');
+            if (!Telemetry\Queue::dispatch($job)) {
+                $existing = data_get($connection->meta, 'last_sync_job_id');
+                if ($existing && in_array(data_get($connection->meta, 'last_sync_result'), ['queued', 'running', 'retrying'], true)) {
+                    return $existing;
+                }
+                throw ValidationException::withMessages(['telematic' => ['Telemetry synchronization is already queued or running.']]);
+            }
+            $connection->status = 'synchronizing';
+            $connection->meta   = array_merge($connection->meta ?? [], [
+                'last_sync_job_id'     => $jobId, 'last_sync_run_uuid' => null, 'last_sync_run_job_id' => null,
+                'last_sync_started_at' => now()->toDateTimeString(), 'last_sync_result' => 'queued',
+                'last_sync_phase'      => 'queued', 'last_sync_error' => null, 'last_sync_failed_reason' => null,
+            ]);
+            $connection->save();
+
+            return $jobId;
+        });
+    }
+
     /**
      * Link a device to a telematic.
      */
@@ -194,6 +234,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;
@@ -296,9 +339,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';
@@ -504,7 +551,8 @@ class TelematicService
         $this->setDeviceAttributeIfPresent($device, 'model', $payload['model'] ?? $payload['device_model'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'provider', $payload['provider'] ?? $payload['device_provider'] ?? $telematic?->provider);
         $this->setDeviceAttributeIfPresent($device, 'type', $payload['type'] ?? null);
-        $this->setDeviceAttributeIfPresent($device, 'internal_id', $payload['internal_id'] ?? $externalId);
+        // Partial messages must not replace an existing identity with the external ID fallback.
+        $this->setDeviceAttributeIfPresent($device, 'internal_id', $payload['internal_id'] ?? (filled($device->internal_id) ? null : $externalId));
         $this->setDeviceAttributeIfPresent($device, 'imei', $payload['imei'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'imsi', $payload['imsi'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'serial_number', $payload['serial_number'] ?? null);
@@ -535,7 +583,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,
@@ -636,6 +685,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) {
@@ -654,6 +707,13 @@ 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) {
@@ -689,7 +749,8 @@ class TelematicService
         ]);
         $trailer->save();
 
-        broadcast(new TrailerLocationChanged($trailer, ['source' => 'telematics', 'device_event_uuid' => $event->uuid, 'provider' => $event->provider]));
+        $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
@@ -717,7 +778,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([
@@ -731,11 +792,23 @@ 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
+    {
+        $event = Telemetry\Configuration::withBroadcastQueue($event);
+        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,46 @@
+<?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());
+    }
+
+    /** Queue for connection-level jobs that predate durable polling (discovery and connection tests). */
+    public static function pollQueue(): string
+    {
+        return config('telematics.telemetry.poll_queue') ?: 'default';
+    }
+
+    /** Route a telemetry broadcast to the configured queue without changing other callers of the event. */
+    public static function withBroadcastQueue(object $event): object
+    {
+        if ($queue = config('telematics.telemetry.broadcast_queue')) {
+            $event->broadcastQueue = $queue;
+        }
+
+        return $event;
+    }
+
+    public static function forConnection(Telematic $connection): array
+    {
+        return self::options(self::provider($connection));
+    }
+}

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

@@ -0,0 +1,89 @@
+<?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');
+            $applied = (clone $items)->sum('applied');
+            $status  = $run->status === 'incomplete' ? 'incomplete' : ($failed ? 'partial' : 'completed');
+            DB::table('telematic_sync_runs')->where('uuid', $id)->update([
+                'status'  => $status,
+                'applied' => $applied, 'failed' => $failed, 'updated_at' => now(),
+            ]);
+            // An incomplete fetch can still have accepted batches, but the poll
+            // job owns its retry/failure lifecycle. Draining them must not end the
+            // manual request while its next fetch attempt is still queued.
+            if ($status === 'incomplete') {
+                return;
+            }
+            // A previous sweep may finish after another manual request was queued.
+            // Only the run explicitly associated with that request may finalize it.
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $run->telematic_uuid)->lockForUpdate()->first();
+            if (!$connection || !self::enabled($connection)
+                || data_get($connection->meta, 'last_sync_run_uuid') !== $id
+                || !data_get($connection->meta, 'last_sync_run_job_id')
+                || data_get($connection->meta, 'last_sync_run_job_id') !== data_get($connection->meta, 'last_sync_job_id')) {
+                return;
+            }
+            $connection->status = $status === 'completed' ? 'active' : 'error';
+            $connection->meta   = array_merge($connection->meta ?? [], [
+                'last_sync_result'                                                         => $status === 'completed' ? 'success' : $status,
+                'last_sync_phase'                                                          => $status, 'last_sync_progress_at' => now()->toDateTimeString(),
+                'last_sync_fetched_total'                                                  => (int) $run->units, 'last_sync_page_count' => (int) $run->pages,
+                'last_sync_total'                                                          => (int) $applied, 'last_sync_linked_total' => (int) $applied,
+                'last_sync_failed_total'                                                   => (int) $failed,
+                'last_sync_error'                                                          => $status === 'completed' ? null : ($run->error ?? 'Some units could not be applied; inspect telemetry diagnostics.'),
+                $status === 'completed' ? 'last_sync_completed_at' : 'last_sync_failed_at' => now()->toDateTimeString(),
+            ]);
+            $connection->save();
+        });
+    }
+}

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

@@ -0,0 +1,112 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Telemetry;
+
+use Fleetbase\FleetOps\Contracts\TelemetryProviderInterface;
+use Fleetbase\FleetOps\Events\DeviceTelemetryUpdated;
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\DeviceEvent;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicService;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+
+class Ingestor
+{
+    public function ingest(Telematic $telematic, TelemetryProviderInterface $provider, array $raw, TelematicService $service, ?string $receivedAt = null, string $source = 'poll'): array
+    {
+        $sample                = $provider->normalizeTelemetrySnapshot($raw);
+        $normalized            = $sample['device'];
+        $event                 = $sample['event'];
+        $event['occurred_at']  = Sample::timestamp($event['occurred_at'] ?? null);
+        $event['last_seen_at'] = Sample::timestamp($event['last_seen_at'] ?? $event['occurred_at']);
+        $event['ignition'] ??= null;
+        $normalized['last_seen_at']       = Sample::timestamp($normalized['last_seen_at'] ?? $event['last_seen_at']);
+        $options                          = Configuration::options($provider);
+        $normalized['_ordered_telemetry'] = true;
+        $event['_ordered_telemetry']      = true;
+        $id                               = $normalized['device_id'] ?? null;
+        if (!$id) {
+            throw new \InvalidArgumentException('Unit identity is required.');
+        }
+        $key = 'telemetry:device:' . hash('sha256', $telematic->uuid . '|' . $id);
+
+        return Cache::lock($key, 60)->block(5, fn () => DB::transaction(function () use ($telematic, $sample, $options, $service, $receivedAt, $source, $normalized, $event, $id) {
+            $device            = Device::withoutGlobalScopes()->where('company_uuid', $telematic->company_uuid)->where('telematic_uuid', $telematic->uuid)->where('device_id', $id)->lockForUpdate()->first();
+            $current           = data_get($device?->meta, 'telemetry.position_at') ?? data_get($device?->meta, 'last_update.occurred_at');
+            $valid             = Sample::validPosition($event);
+            $newer             = $valid && (!$current || Carbon::parse($event['occurred_at'])->gt(Carbon::parse($current)));
+            $event['event_id'] = Sample::signalKey($event);
+            // Same identity as TelematicService::makeEventKey, serialized under the device lock.
+            $eventKey  = sha1(implode('|', [$telematic->provider, $telematic->public_id ?? $telematic->uuid, $id, $event['event_id'], $event['event_type'], $event['occurred_at']]));
+            $duplicate = $valid && DeviceEvent::withoutGlobalScopes()->where('_key', $eventKey)->exists();
+            $received  = Sample::timestamp($receivedAt ?? now()->toISOString());
+            $meta      = array_filter([
+                'position_at'          => $event['occurred_at'], 'provider_at' => data_get($event, 'meta.telemetry.provider_at'),
+                'received_at'          => $received, 'processed_at' => now()->toISOString(), 'source' => $source,
+                'queue_delay_seconds'  => max(0, now()->timestamp - Carbon::parse($received)->timestamp),
+                'source_delay_seconds' => $event['occurred_at'] ? max(0, Carbon::parse($received)->timestamp - Carbon::parse($event['occurred_at'])->timestamp) : null,
+                'ignition'             => $event['ignition'],
+            ], fn ($value) => $value !== null);
+            $ignition                    = $event['ignition'] ?? data_get($device?->meta, 'telemetry.ignition');
+            $meta['stale_after_seconds'] = (int) ($options[$ignition === true ? 'stale_engine_on_seconds' : 'stale_engine_off_seconds'] ?? ($ignition === true ? 120 : 600));
+            if (!$device || $newer) {
+                $contactAt = $normalized['last_seen_at'] ?? null;
+                if ($contactAt && Carbon::parse($contactAt)->gt(now()->addMinutes(5))) {
+                    $contactAt = null;
+                }
+                if ($device?->last_online_at && (!$contactAt || Carbon::parse($contactAt)->lt($device->last_online_at))) {
+                    $contactAt = $device->last_online_at->toISOString();
+                }
+                $normalized['last_seen_at'] = $contactAt;
+                if (!$valid) {
+                    unset($normalized['location'], $normalized['meta']['last_update']);
+                }
+                $normalized['meta'] = array_replace_recursive($device?->meta ?? [], $normalized['meta'] ?? []);
+                if ($newer) {
+                    $normalized['meta']['telemetry'] = array_replace(data_get($device?->meta, 'telemetry', []), $meta);
+                }
+                $normalized['meta'] = array_replace_recursive($device?->meta ?? [], array_filter($normalized['meta'], fn ($v) => $v !== null));
+                $device             = $service->linkDevice($telematic, $normalized);
+            }
+            // Last contact can advance independently of an old/repeated GPS fix.
+            $contactChanged = false;
+            $contact        = $event['last_seen_at'];
+            if ($contact && Carbon::parse($contact)->lte(now()->addMinutes(5)) && (!$device->last_online_at || Carbon::parse($contact)->gt($device->last_online_at))) {
+                $device->last_online_at = Carbon::parse($contact)->utc()->toDateTimeString();
+                $device->online         = $device->last_online_at->gt(now()->subMinutes(10));
+                if (in_array($device->status, ['online', 'recently_offline', 'offline', 'long_offline', 'never_connected'], true)) {
+                    $minutes        = $device->last_online_at->diffInMinutes(now());
+                    $device->status = $minutes <= 10 ? 'online' : ($minutes <= 60 ? 'recently_offline' : ($minutes <= 1440 ? 'offline' : 'long_offline'));
+                }
+                $device->meta           = array_replace_recursive($device->meta ?? [], ['telemetry' => ['provider_at' => $contact, 'last_received_at' => $received]]);
+                $device->save();
+                $contactChanged = true;
+            }
+            $stored = null;
+            if ($valid && !$duplicate) {
+                $event['_history_only']     = !$newer;
+                $event['meta']['telemetry'] = $meta;
+                // Do not replace the higher contact watermark with delayed transmission time.
+                $event['last_seen_at'] = $device->last_online_at?->toISOString();
+                $stored                = $service->storeDeviceEvent($telematic, $event, $device);
+            }
+            $sensors    = 0;
+            foreach ($sample['sensors'] ?? [] as $sensor) {
+                $sensor['_ordered_telemetry'] = true;
+                if (!$sensor['recorded_at'] || Carbon::parse($sensor['recorded_at'])->gt(now()->addMinutes(5))) {
+                    continue;
+                }
+                $service->storeSensor($telematic, $sensor, $device);
+                $sensors++;
+            }
+            if ($newer || $contactChanged) {
+                $snapshot = $device->fresh() ?? $device;
+                DB::afterCommit(fn () => broadcast(Configuration::withBroadcastQueue(new DeviceTelemetryUpdated($snapshot))));
+            }
+
+            return ['device' => $device, 'event' => $stored, 'events' => $stored ? [$stored] : [], 'sensors' => $sensors, 'duplicate' => $duplicate, 'invalid_position' => !$valid];
+        }, 3));
+    }
+}

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

@@ -0,0 +1,28 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Telemetry;
+
+use Illuminate\Bus\UniqueLock;
+use Illuminate\Contracts\Bus\Dispatcher;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Support\Facades\Cache;
+
+class Queue
+{
+    /** Unlike PendingDispatch, release the uniqueness lease when broker dispatch fails. */
+    public static function dispatch(ShouldBeUnique $job): bool
+    {
+        $lock = new UniqueLock(Cache::store());
+        if (!$lock->acquire($job)) {
+            return false;
+        }
+        try {
+            app(Dispatcher::class)->dispatch($job);
+
+            return true;
+        } catch (\Throwable $e) {
+            $lock->release($job);
+            throw $e;
+        }
+    }
+}