@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/server/src/Http/Resources/v1/InspectionLink.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionLinkPin;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Support\Http;
+
+/**
+ * A public inspection link, as the console lists it.
+ *
+ * `state` is the computed one — active, expired, used or revoked — not the
+ * stored `status`, because a link that has run out of time still says
+ * `active` in the column. `url` is the link itself, present only for links
+ * minted since the token has been kept.
+ */
+class InspectionLink extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $internal = Http::isInternalRequest();
+
+        return [
+            // Always the public id: it is what identifies a link back to the
+            // revoke endpoint. `$this->id` is the table's auto-increment
+            // column, which no lookup here resolves — a list built from it
+            // could show links but never revoke one.
+            'id'             => $this->public_id,
+            'uuid'           => $this->when($internal, $this->uuid),
+            'public_id'      => $this->when($internal, $this->public_id),
+            'path'           => $this->path,
+            'state'          => $this->state,
+            'status'         => $this->status,
+            'single_use'     => (bool) $this->single_use,
+            'has_pin'        => $this->hasPin(),
+            // Shown in the console, like the link, so a dispatcher can read it
+            // out or send it again. Never on a public request.
+            'pin'            => $this->when($internal, fn () => $this->pin),
+            'pin_sent_via'   => $this->pin_sent_via,
+            'pin_sent_at'    => $this->pin_sent_at,
+            'pin_attempts'   => $this->when($internal, fn () => (int) $this->pin_attempts),
+            'recipient'      => $this->when($internal, function () {
+                $recipient = InspectionLinkPin::recipientFor($this->resource);
+
+                return $recipient ? ['name' => $recipient->name] : null;
+            }),
+            'can_send_pin'   => $this->when($internal, function () {
+                $recipient = InspectionLinkPin::recipientFor($this->resource);
+
+                return [
+                    'email' => InspectionLinkPin::unavailableReason($recipient, 'email') === null,
+                    'sms'   => InspectionLinkPin::unavailableReason($recipient, 'sms') === null,
+                ];
+            }),
+            'assignee'       => $this->assignee ? [
+                'id'   => $this->assignee->public_id,
+                'name' => $this->assignee->name,
+            ] : null,
+            'driver'         => $this->driver ? [
+                'id'   => $this->driver->public_id,
+                'name' => $this->driver->name,
+            ] : null,
+            'vehicle'        => $this->vehicle ? [
+                'id'   => $this->vehicle->public_id,
+                'name' => $this->vehicle->display_name ?? $this->vehicle->name,
+            ] : null,
+            'created_by'     => $this->createdBy ? [
+                'id'   => $this->createdBy->public_id,
+                'name' => $this->createdBy->name,
+            ] : null,
+            'expires_at'     => $this->expires_at,
+            'last_viewed_at' => $this->last_viewed_at,
+            'used_at'        => $this->used_at,
+            'created_at'     => $this->created_at,
+        ];
+    }
+}

package/server/src/Http/Resources/v1/InspectionSubmission.php

@@ -0,0 +1,173 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionFileStore;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Http\Resources\User;
+use Fleetbase\Models\CustomFieldValue;
+use Fleetbase\Models\File;
+use Fleetbase\Support\Http;
+
+class InspectionSubmission extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $data = $this->withCustomFields([
+            'id'                   => $this->when(Http::isInternalRequest(), $this->id, $this->public_id),
+            'uuid'                 => $this->when(Http::isInternalRequest(), $this->uuid),
+            'public_id'            => $this->when(Http::isInternalRequest(), $this->public_id),
+            'company_uuid'         => $this->when(Http::isInternalRequest(), $this->company_uuid),
+            'inspection_form_uuid' => $this->when(Http::isInternalRequest(), $this->inspection_form_uuid),
+            'vehicle_uuid'         => $this->when(Http::isInternalRequest(), $this->vehicle_uuid),
+            'driver_uuid'          => $this->when(Http::isInternalRequest(), $this->driver_uuid),
+            'submitted_by_uuid'    => $this->when(Http::isInternalRequest(), $this->submitted_by_uuid),
+            'issue_uuid'           => $this->when(Http::isInternalRequest(), $this->issue_uuid),
+            'work_order_uuid'      => $this->when(Http::isInternalRequest(), $this->work_order_uuid),
+            'form'                 => $this->whenLoaded('form', fn () => new InspectionForm($this->form)),
+            'vehicle'              => $this->whenLoaded('vehicle', fn () => new Vehicle($this->vehicle)),
+            'driver'               => $this->whenLoaded('driver', fn () => new Driver($this->driver)),
+            'submitted_by'         => $this->whenLoaded('submittedBy', fn () => new User($this->submittedBy)),
+            'issue'                => $this->whenLoaded('issue', fn () => new Issue($this->issue)),
+            'work_order'           => $this->whenLoaded('workOrder', fn () => new WorkOrder($this->workOrder)),
+            'item_results'         => InspectionItemResult::collection($this->whenLoaded('itemResults')),
+            'type'                 => $this->type,
+            'status'               => $this->status,
+            'result'               => $this->result,
+            'source'               => $this->source,
+            'odometer'             => $this->odometer,
+            'engine_hours'         => $this->engine_hours,
+            'total_items'          => $this->total_items,
+            'failed_items'         => $this->failed_items,
+            'location'             => data_get($this, 'location', (object) []),
+            'signature'            => data_get($this, 'signature', (object) []),
+            'attachments'          => data_get($this, 'attachments', []),
+            'meta'                 => data_get($this, 'meta', Utils::createObject()),
+            'form_name'            => $this->form_name,
+            'vehicle_name'         => $this->vehicle_name,
+            'driver_name'          => $this->driver_name,
+            'has_failures'         => $this->has_failures,
+            'started_at'           => $this->started_at,
+            'submitted_at'         => $this->submitted_at,
+            'resolved_at'          => $this->resolved_at,
+            'updated_at'           => $this->updated_at,
+            'created_at'           => $this->created_at,
+        ]);
+
+        // The platform's own `withCustomFields` puts the raw value models
+        // under `custom_field_values` for the console. What both consoles and
+        // the app want is the field's identity beside its answer, with file
+        // references resolved, so that projection replaces it.
+        //
+        // A form has `fields`; a submission has `answers` to them. The stored
+        // shape is the platform's custom-field values, but that is how it is
+        // built rather than what it is, and an integrator reading a DVIR
+        // should not have to know the difference.
+        $answers = $this->projectCustomFieldValues();
+        if (Http::isInternalRequest()) {
+            $data['custom_field_values'] = $answers;
+        }
+        $data['answers'] = $answers;
+        $data['files']   = $this->projectFiles();
+
+        return $data;
+    }
+
+    /**
+     * The answers, as the app and the console read them: which field, what it
+     * is called, its type, and the value with every `file:<uuid>` resolved to
+     * something fetchable.
+     */
+    protected function projectCustomFieldValues(): array
+    {
+        // `withCustomFields()` has already loaded the values and the fields
+        // they answer, so there is nothing to guard against here.
+        $internal = Http::isInternalRequest();
+
+        return collect($this->resource?->customFieldValues)->map(function (CustomFieldValue $value) use ($internal) {
+            $field = $value->customField;
+            $row   = [
+                // The field's public id, as the form hands it out. `value_type`
+                // describes how the answer is stored, which is the platform's
+                // business and not an integrator's, so it stays internal.
+                'field'      => $internal ? $value->custom_field_uuid : ($field?->public_id ?? $value->custom_field_uuid),
+                'name'       => $field?->name,
+                'label'      => $field?->label ?? $value->custom_field_label,
+                'type'       => $field?->type ?? $value->value_type,
+                'value'      => static::projectValue($value),
+            ];
+
+            if ($internal) {
+                $row['custom_field'] = $value->custom_field_uuid;
+                $row['value_type']   = $value->value_type;
+                $row['uuid']          = $value->uuid;
+                $row['category_uuid'] = $field?->category_uuid;
+                $row['order']         = $field?->order === null ? null : (int) $field->order;
+                $row['meta']          = is_array($field?->meta) && !empty($field->meta) ? $field->meta : (object) [];
+            }
+
+            return $row;
+        })->values()->all();
+    }
+
+    /**
+     * One stored value, with file references resolved. A pass-fail answer
+     * carries its photos inside it, so those are resolved too.
+     */
+    protected static function projectValue(CustomFieldValue $value): mixed
+    {
+        $raw = $value->getRawOriginal('value');
+
+        if (in_array($value->value_type, ['object', 'array'], true)) {
+            $decoded = is_string($raw) ? json_decode($raw, true) : $raw;
+            if (!is_array($decoded)) {
+                return $decoded;
+            }
+
+            if (isset($decoded['photos']) && is_array($decoded['photos'])) {
+                $decoded['photos'] = array_values(array_map(fn ($photo) => InspectionFileStore::project($photo), $decoded['photos']));
+            }
+
+            return $decoded;
+        }
+
+        // A value column is a string, so a meter reading comes back as one.
+        // The app compares and charts these; hand it the number it wrote.
+        if ($value->value_type === 'number') {
+            return is_numeric($raw) ? $raw + 0 : $raw;
+        }
+
+        if ($value->value_type === 'boolean') {
+            return filter_var($raw, FILTER_VALIDATE_BOOLEAN);
+        }
+
+        return InspectionFileStore::project($raw);
+    }
+
+    /** The photos and signatures filed with the inspection. */
+    protected function projectFiles(): array
+    {
+        if (!$this->resource || !$this->resource->relationLoaded('files')) {
+            return [];
+        }
+
+        return $this->resource->files->map(fn (File $file) => [
+            'id'                => $file->public_id ?? $file->uuid,
+            'uuid'              => $file->uuid,
+            'url'               => $file->url,
+            'original_filename' => $file->original_filename,
+            'content_type'      => $file->content_type,
+            'type'              => $file->type,
+            'caption'           => $file->caption,
+            'created_at'        => $file->created_at,
+        ])->values()->all();
+    }
+}

package/server/src/Http/Resources/v1/Trailer.php

@@ -0,0 +1,199 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Http\Resources\v1\Concerns\ResolvesPublicRelationFields;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Support\Http;
+use Fleetbase\Support\Resolve;
+
+/**
+ * First-class Trailer representation.
+ *
+ * Internal (console) responses expose the record with its UUID identity and fully
+ * embedded relations so Ember Data can hydrate the store. Public API responses use
+ * the `trailer_` public identifier, additive `*_id` relation identifiers, and only
+ * expand relation objects that were requested through `with`.
+ */
+class Trailer extends FleetbaseResource
+{
+    use ResolvesPublicRelationFields;
+
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     */
+    public function toArray($request): array
+    {
+        $internal = Http::isInternalRequest();
+        $with     = $this->requestedRelations($request);
+
+        return $this->withCustomFields([
+            // Identity
+            'id'                   => $this->when($internal, $this->id, $this->public_id),
+            'uuid'                 => $this->when(Http::isInternalRequest(), $this->uuid),
+            'public_id'            => $this->when($internal, $this->public_id),
+            'company_uuid'         => $this->when(Http::isInternalRequest(), $this->company_uuid),
+            'category_uuid'        => $this->when(Http::isInternalRequest(), $this->category_uuid),
+            'vendor_uuid'          => $this->when(Http::isInternalRequest(), $this->vendor_uuid),
+            'warranty_uuid'        => $this->when(Http::isInternalRequest(), $this->warranty_uuid),
+            'photo_uuid'           => $this->when(Http::isInternalRequest(), $this->photo_uuid),
+            'asset_class'          => 'trailer',
+            'name'                 => $this->name,
+            'display_name'         => $this->display_name,
+            'code'                 => $this->code,
+            'description'          => $this->description,
+            'slug'                 => $this->when($internal, $this->slug),
+            // Classification & lifecycle
+            'type'                 => $this->type,
+            'body_type'            => $this->body_type,
+            'usage_type'           => $this->usage_type,
+            'status'               => $this->status,
+            'attachment_state'     => $this->attachment_state,
+            'connectivity_status'  => $this->connectivity_status,
+            'online'               => $this->online,
+            // Registration
+            'vin'                  => $this->vin,
+            'plate_number'         => $this->plate_number,
+            'serial_number'        => $this->serial_number,
+            'make'                 => $this->make,
+            'model'                => $this->model,
+            'year'                 => $this->year,
+            'color'                => $this->color,
+            // Media
+            'photo_url'            => $this->photo_url,
+            // Relationships. Identifiers are additive and always present so a write
+            // can be read back; relation objects follow the public `with` contract.
+            'category_id'          => $this->publicIdForRelation('category', 'category_uuid'),
+            'vendor_id'            => $this->publicIdForRelation('vendor', 'vendor_uuid'),
+            'warranty_id'          => $this->publicIdForRelation('warranty', 'warranty_uuid'),
+            'photo_id'             => $this->publicIdForRelation('photo', 'photo_uuid'),
+            'category_name'        => $this->when($internal, $this->category_name),
+            'vendor_name'          => $this->when($internal, $this->vendor_name),
+            'warranty_name'        => $this->when($internal, $this->warranty_name),
+            'category'             => $this->publicRelationObject('category', $with, fn () => Resolve::httpResourceForModel($this->category)),
+            'vendor'               => $this->publicRelationObject('vendor', $with, fn () => new Vendor($this->vendor)),
+            'warranty'             => $this->publicRelationObject('warranty', $with, fn () => Resolve::httpResourceForModel($this->warranty)),
+            'photo'                => $this->publicRelationObject('photo', $with, fn () => Resolve::httpResourceForModel($this->photo)),
+            // Towing connection
+            'vehicle_id'           => $this->whenLoaded('currentConnection', fn () => $this->currentConnection?->vehicle?->public_id),
+            'current_vehicle_name' => $this->whenLoaded('currentConnection', fn () => $this->currentConnection?->vehicle?->display_name),
+            'attached_at'          => $this->whenLoaded('currentConnection', fn () => $this->currentConnection?->connected_at),
+            'current_vehicle'      => $this->whenLoaded('currentConnection', fn () => $this->currentVehicleRepresentation($internal)),
+            'current_connection'   => $this->whenLoaded('currentConnection', fn () => $this->currentConnection ? new AssetConnection($this->currentConnection) : null),
+            // Ember Data embeds these collections, so the console always receives an array;
+            // the public API only includes them when they were loaded.
+            'connections'          => $this->embeddedCollection('connections', AssetConnection::class, $internal),
+            'devices'              => $this->embeddedCollection('devices', Device::class, $internal),
+            // Ember Data embeds the `equipments` relationship; the public contract reads `equipment`.
+            'equipment'            => $this->when(!$internal, fn () => $this->whenLoaded('equipments', fn () => Equipment::collection($this->equipments))),
+            'equipments'           => $this->when($internal, fn () => $this->embeddedCollection('equipments', Equipment::class, true)),
+            'devices_count'        => $this->whenCounted('devices'),
+            'equipment_count'      => $this->whenCounted('equipments'),
+            // Dimensions & capacity
+            'measurement_system'   => $this->measurement_system,
+            'length'               => $this->length,
+            'width'                => $this->width,
+            'height'               => $this->height,
+            'tare_weight'          => $this->tare_weight,
+            'gvwr'                 => $this->gvwr,
+            'payload_capacity'     => $this->payload_capacity,
+            'cargo_volume'         => $this->cargo_volume,
+            'capacity'             => data_get($this, 'capacity', Utils::createObject()),
+            // Running gear
+            'axle_count'           => $this->axle_count,
+            'tire_count'           => $this->tire_count,
+            'door_count'           => $this->door_count,
+            'coupling_type'        => $this->coupling_type,
+            'brake_type'           => $this->brake_type,
+            'abs_equipped'         => $this->abs_equipped,
+            'ebs_equipped'         => $this->ebs_equipped,
+            // Refrigeration
+            'refrigerated'         => $this->refrigerated,
+            'temperature_min'      => $this->temperature_min,
+            'temperature_max'      => $this->temperature_max,
+            'reefer_engine_hours'  => $this->reefer_engine_hours,
+            // Usage
+            'odometer'             => $this->odometer,
+            'odometer_unit'        => $this->odometer_unit,
+            'engine_hours'         => $this->engine_hours,
+            // Ownership & finance
+            'ownership_type'       => $this->ownership_type,
+            'financing_status'     => $this->financing_status,
+            'currency'             => $this->currency,
+            'acquisition_cost'     => $this->acquisition_cost,
+            'current_value'        => $this->current_value,
+            'insurance_value'      => $this->insurance_value,
+            'depreciation_rate'    => $this->depreciation_rate,
+            'purchased_at'         => $this->purchased_at,
+            'lease_expires_at'     => $this->lease_expires_at,
+            // Location & telematics
+            'location'             => Utils::castPoint($this->location),
+            'speed'                => $this->speed,
+            'heading'              => $this->heading,
+            'altitude'             => $this->altitude,
+            'last_online_at'       => $this->last_online_at,
+            'telematics'           => $this->telematicsRepresentation($internal),
+            'positions'            => $this->whenLoaded('positions', fn () => Position::collection($this->positions)),
+            // Blobs, notes & timestamps
+            'specs'                => data_get($this, 'specs', Utils::createObject()),
+            'attributes'           => $this->resource->getAttribute('attributes') ?? Utils::createObject(),
+            'notes'                => $this->notes,
+            'created_at'           => $this->created_at,
+            'updated_at'           => $this->updated_at,
+        ]);
+    }
+
+    /**
+     * A loaded relation serializes through its resource; an unloaded one is omitted for the
+     * public API and an empty array for the console, which embeds the relationship.
+     */
+    protected function embeddedCollection(string $relation, string $resourceClass, bool $internal): mixed
+    {
+        if ($this->resource->relationLoaded($relation)) {
+            return $resourceClass::collection($this->{$relation});
+        }
+
+        return $internal ? [] : new \Illuminate\Http\Resources\MissingValue();
+    }
+
+    /**
+     * The console receives the full Vehicle record so Ember Data can hydrate it; the
+     * public API receives a compact public identity.
+     */
+    protected function currentVehicleRepresentation(bool $internal): mixed
+    {
+        $vehicle = $this->currentConnection?->vehicle;
+
+        if (!$vehicle) {
+            return null;
+        }
+
+        if ($internal) {
+            return Resolve::httpResourceForModel($vehicle);
+        }
+
+        return [
+            'id'           => $vehicle->public_id,
+            'name'         => $vehicle->display_name,
+            'plate_number' => $vehicle->plate_number,
+        ];
+    }
+
+    /**
+     * Telemetry provenance references devices and events by UUID for the console;
+     * the public API must never expose internal identifiers.
+     */
+    protected function telematicsRepresentation(bool $internal): mixed
+    {
+        $telematics = $this->telematics;
+
+        if ($internal || !is_array($telematics)) {
+            return $telematics;
+        }
+
+        return array_filter($telematics, fn ($key) => !preg_match('/(^uuid$|_uuid$)/', (string) $key), ARRAY_FILTER_USE_KEY);
+    }
+}

package/server/src/Http/Resources/v1/Vehicle.php

@@ -68,6 +68,8 @@ class Vehicle extends FleetbaseResource
             'warranty'               => $this->publicRelationObject('warranty', $with, fn () => Resolve::httpResourceForModel($this->warranty)),
             'photo'                  => $this->publicRelationObject('photo', $with, fn () => Resolve::httpResourceForModel($this->photo)),
             'devices'                => $this->whenLoaded('devices', fn () => $this->devices),
+            // Trailers currently coupled to this vehicle (`with=trailers` on the public API).
+            'trailers'               => $this->publicRelationObject('currentTrailers', $with, fn () => Trailer::collection($this->currentTrailers)),
             // Vehicle identification
             'make'                   => $this->make,
             'model'                  => $this->model,

package/server/src/Http/Resources/v1/VehicleWithoutDriver.php

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Resources\v1;
 
+use Fleetbase\FleetOps\Support\TrailerSummary;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Resources\FleetbaseResource;
 use Fleetbase\Support\Http;
@@ -41,6 +42,8 @@ class VehicleWithoutDriver extends FleetbaseResource
             'vendor_name'            => $this->when(Http::isInternalRequest(), $this->vendor_name),
             // Relationships
             'devices'                => $this->whenLoaded('devices', fn () => $this->devices),
+            // Current towing connections, compact; the console vehicle cards list them.
+            'trailers'               => $this->whenLoaded('currentTrailers', fn () => TrailerSummary::collection($this->currentTrailers)),
             // Vehicle identification
             'make'                   => $this->make,
             'model'                  => $this->model,

package/server/src/Imports/TrailerImport.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Fleetbase\FleetOps\Imports;
+
+use Fleetbase\FleetOps\Models\Trailer;
+use Illuminate\Support\Collection;
+use Illuminate\Validation\ValidationException;
+use Maatwebsite\Excel\Concerns\ToCollection;
+use Maatwebsite\Excel\Concerns\WithHeadingRow;
+
+class TrailerImport implements ToCollection, WithHeadingRow
+{
+    public int $imported = 0;
+
+    public function collection(Collection $rows)
+    {
+        foreach ($rows as $index => $row) {
+            $data = $row instanceof Collection ? array_filter($row->toArray(), fn ($v) => $v !== null && $v !== '') : $row;
+            if (!$data) {
+                continue;
+            }
+            if (empty($data['name'])) {
+                throw ValidationException::withMessages(["row.$index.name" => ['Name is required.']]);
+            }
+            if (!empty($data['type']) && !in_array($data['type'], Trailer::TYPES, true)) {
+                throw ValidationException::withMessages(["row.$index.type" => ['Invalid trailer type.']]);
+            }
+            $allowed = ['name', 'code', 'description', 'type', 'status', 'vin', 'plate_number', 'serial_number', 'make', 'model', 'year', 'length', 'width', 'height', 'tare_weight', 'gvwr', 'payload_capacity', 'cargo_volume', 'axle_count', 'tire_count', 'coupling_type', 'brake_type', 'refrigerated', 'measurement_system', 'odometer', 'odometer_unit', 'ownership_type', 'purchased_at', 'lease_expires_at', 'notes'];
+            Trailer::create(array_merge(array_intersect_key($data, array_flip($allowed)), ['company_uuid' => session('company')]));
+            $this->imported++;
+        }
+    }
+}

package/server/src/Jobs/PollTelematicTelemetry.php

@@ -0,0 +1,118 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Contracts\TelemetryProviderInterface;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class PollTelematicTelemetry implements ShouldQueue, ShouldBeUnique
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+
+    public int $tries     = 5;
+    public int $timeout   = 120;
+    public int $uniqueFor = 3600;
+
+    public function __construct(public string $telematicUuid)
+    {
+    }
+
+    public function uniqueId(): string
+    {
+        return $this->telematicUuid;
+    }
+
+    public function backoff(): array
+    {
+        return [15, 60, 180, 300];
+    }
+
+    public function handle(TelematicProviderRegistry $registry, Inbox $inbox): void
+    {
+        $telematic = Telematic::withoutGlobalScopes()->where('uuid', $this->telematicUuid)->first();
+        if (!$telematic || !Inbox::enabled($telematic)) {
+            return;
+        }
+        $provider = $registry->resolve($telematic->provider);
+        if (!$provider instanceof TelemetryProviderInterface) {
+            return;
+        }
+        $options = Configuration::options($provider);
+        if (!($options['polling_enabled'] ?? false)) {
+            return;
+        }
+        // Coalesce ticks while a previous sweep is still being ingested.
+        if (DB::table('telematic_deliveries')->where('telematic_uuid', $this->telematicUuid)->where('source', 'poll')->whereIn('status', ['pending', 'retry', 'processing'])->exists()) {
+            return;
+        }
+        $lock = Cache::lock('telemetry:poll:' . $this->telematicUuid, 150);
+        if (!$lock->get()) {
+            return;
+        }
+        $run = (string) Str::uuid();
+        DB::table('telematic_sync_runs')->insert(['uuid' => $run, 'telematic_uuid' => $telematic->uuid, 'status' => 'fetching', 'created_at' => now(), 'updated_at' => now()]);
+        try {
+            $provider->connect($telematic);
+            $cursor  = null;
+            $cursors = [];
+            $seen    = [];
+            $started = microtime(true);
+            for ($page = 0; $page < ($options['max_pages'] ?? 100); $page++) {
+                if (microtime(true) - $started > 90) {
+                    throw new \RuntimeException('Polling time budget exceeded; sweep incomplete.');
+                }
+                $response = $provider->fetchDevices(['limit' => $options['page_size'] ?? 1000, 'cursor' => $cursor, 'timeout' => 20, 'connect_timeout' => 5]);
+                $received = now()->utc();
+                $units    = $response['devices'];
+                $ids      = array_map(fn ($unit) => $provider->normalizeDevice($unit)['device_id'] ?? null, $units);
+                foreach ($ids as $id) {
+                    if (!$id || isset($seen[(string) $id])) {
+                        throw new \RuntimeException('Repeated or unidentified unit; sweep incomplete.');
+                    }
+                    $seen[(string) $id] = true;
+                }
+                foreach (array_chunk($units, max(1, (int) ($options['batch_size'] ?? 100))) as $batch) {
+                    $inbox->accept($telematic, $batch, 'poll', $run, $received->toDateTimeString());
+                }
+                DB::table('telematic_sync_runs')->where('uuid', $run)->update(['pages' => $page + 1, 'units' => count($seen), 'updated_at' => now()]);
+                if (!$response['has_more']) {
+                    DB::table('telematic_sync_runs')->where('uuid', $run)->update(['status' => 'ingesting', 'updated_at' => now()]);
+                    Inbox::finishRun($run);
+
+                    return;
+                }
+                $next = $response['next_cursor'];
+                if ($next === null || isset($cursors[(string) $next]) || (string) $next === (string) $cursor) {
+                    throw new \RuntimeException('Non-advancing pagination; sweep incomplete.');
+                }
+                $cursors[(string) $next] = true;
+                $cursor                  = $next;
+            }
+            throw new \RuntimeException('Maximum page count reached; sweep incomplete.');
+        } catch (\Throwable $e) {
+            DB::table('telematic_sync_runs')->where('uuid', $run)->update(['status' => 'incomplete', 'error' => $e instanceof TelematicRateLimitExceededException ? 'Rate limited; retry scheduled.' : 'Polling failed; retry scheduled. ' . class_basename($e), 'updated_at' => now()]);
+            if ($e instanceof TelematicRateLimitExceededException && $this->job) {
+                $this->release($e->context()['retry_after'] ?? 60);
+
+                return;
+            }
+            throw $e;
+        } finally {
+            $lock->release();
+        }
+    }
+}