@fleetbase/fleetops-engine 0.6.65 → 0.6.66

package/app/components/vendor/summary.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/vendor/summary';

package/app/components/warranty/pill.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/warranty/pill';

package/app/components/warranty/summary.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/warranty/summary';

package/app/components/waypoint/pill.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/waypoint/pill';

package/app/components/waypoint/summary.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/waypoint/summary';

package/app/components/widget/radar.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/widget/radar';

package/app/components/work-order/panel-header.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/work-order/panel-header';

package/app/components/work-order/pill.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/work-order/pill';

package/app/components/work-order/summary.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/work-order/summary';

package/app/components/zone/pill.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/zone/pill';

package/app/components/zone/summary.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/zone/summary';

package/app/controllers/maintenance/inspection-forms/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-forms/index/details';

package/app/controllers/maintenance/inspection-forms/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-forms/index/edit';

package/app/controllers/maintenance/inspection-forms/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-forms/index/new';

package/app/controllers/maintenance/inspection-forms/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-forms/index';

package/app/controllers/maintenance/inspection-submissions/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-submissions/index/details';

package/app/controllers/maintenance/inspection-submissions/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-submissions/index/edit';

package/app/controllers/maintenance/inspection-submissions/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-submissions/index/new';

package/app/controllers/maintenance/inspection-submissions/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/maintenance/inspection-submissions/index';

package/app/helpers/initials.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/helpers/initials';

package/app/modifiers/inspection-flyout.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/modifiers/inspection-flyout';

package/app/modifiers/radar-keyboard.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/modifiers/radar-keyboard';

package/app/modifiers/sync-value.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/modifiers/sync-value';

package/app/modifiers/when-changed.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/modifiers/when-changed';

package/app/routes/maintenance/inspection-forms/index/details/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index/details/index';

package/app/routes/maintenance/inspection-forms/index/details/submissions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index/details/submissions';

package/app/routes/maintenance/inspection-forms/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index/details';

package/app/routes/maintenance/inspection-forms/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index/edit';

package/app/routes/maintenance/inspection-forms/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index/new';

package/app/routes/maintenance/inspection-forms/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms/index';

package/app/routes/maintenance/inspection-forms.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-forms';

package/app/routes/maintenance/inspection-submissions/index/details/audit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/details/audit';

package/app/routes/maintenance/inspection-submissions/index/details/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/details/index';

package/app/routes/maintenance/inspection-submissions/index/details/photos.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/details/photos';

package/app/routes/maintenance/inspection-submissions/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/details';

package/app/routes/maintenance/inspection-submissions/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/edit';

package/app/routes/maintenance/inspection-submissions/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index/new';

package/app/routes/maintenance/inspection-submissions/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions/index';

package/app/routes/maintenance/inspection-submissions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/maintenance/inspection-submissions';

package/app/routes/management/vehicles/index/details/inspections.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/management/vehicles/index/details/inspections';

package/app/services/inspection-form-actions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/services/inspection-form-actions';

package/app/services/inspection-submission-actions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/services/inspection-submission-actions';

package/app/templates/maintenance/inspection-forms/index/details/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index/details/index';

package/app/templates/maintenance/inspection-forms/index/details/submissions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index/details/submissions';

package/app/templates/maintenance/inspection-forms/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index/details';

package/app/templates/maintenance/inspection-forms/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index/edit';

package/app/templates/maintenance/inspection-forms/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index/new';

package/app/templates/maintenance/inspection-forms/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms/index';

package/app/templates/maintenance/inspection-forms.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-forms';

package/app/templates/maintenance/inspection-submissions/index/details/audit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/details/audit';

package/app/templates/maintenance/inspection-submissions/index/details/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/details/index';

package/app/templates/maintenance/inspection-submissions/index/details/photos.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/details/photos';

package/app/templates/maintenance/inspection-submissions/index/details.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/details';

package/app/templates/maintenance/inspection-submissions/index/edit.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/edit';

package/app/templates/maintenance/inspection-submissions/index/new.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index/new';

package/app/templates/maintenance/inspection-submissions/index.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions/index';

package/app/templates/maintenance/inspection-submissions.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/maintenance/inspection-submissions';

package/app/templates/management/vehicles/index/details/inspections.js

@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/management/vehicles/index/details/inspections';

package/app/utils/inspection-field-types.js

@@ -0,0 +1,2 @@
+export { default } from '@fleetbase/fleetops-engine/utils/inspection-field-types';
+export * from '@fleetbase/fleetops-engine/utils/inspection-field-types';

package/app/utils/inspection-form-structure.js

@@ -0,0 +1 @@
+export * from '@fleetbase/fleetops-engine/utils/inspection-form-structure';

package/app/utils/radar.js

@@ -0,0 +1 @@
+export * from '@fleetbase/fleetops-engine/utils/radar';

package/composer.json

@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.65",
+    "version": "0.6.66",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "keywords": [
         "fleetbase-extension",

package/docs/AFAQY.md

@@ -0,0 +1,91 @@
+# AFAQY live telemetry
+
+## Behavior
+
+AFAQY uses the provider-neutral telemetry infrastructure described in [TELEMETRY_ARCHITECTURE.md](TELEMETRY_ARCHITECTURE.md). Its adapter owns authentication and payload normalization; shared services own persistence, ingestion, and diagnostics.
+
+The existing AFAQY integration already used Units List. The new path requests 1,000 units per page with `simplify: 0` and the documented `basic` / `last_update` projection groups. It fetches all pages, places batches of 100 units in an encrypted durable inbox, and ingests them asynchronously. A connection in transient `error` status remains eligible; `disabled` connections and connections with `meta.telemetry_sync_enabled: false` do not.
+
+Position webhooks use the same ingestion path and do not authenticate against AFAQY. The adapter provisionally accepts a unit object, a unit array, or a `data` envelope containing either, including `_id` with nested `data.last_update`. This is an assumption, not a verified AFAQY webhook contract. Unsupported authenticated JSON is quarantined and can be replayed after an adapter correction. Vehicle event webhooks and Signals history are outside this implementation.
+
+`dtt` orders positions. `dts` records last contact, falling back to `dtt`. UTC receipt and processing times are recorded separately. Old signals can enter history but cannot replace newer device, vehicle, or trailer positions. Equal-time samples keep the first current position. Duplicate signals do not create another event or broadcast. `active` is not treated as connectivity.
+
+## Stage 1 deployment
+
+1. Apply the Fleet-Ops migration `2026_09_15_000001_create_telematic_telemetry_tables`. It adds shared `telematic_deliveries`, `telematic_sync_runs`, and `telematic_webhook_credentials` tables for any registered telemetry adapter. It also adds a composite device lookup index; existing telemetry data is preserved.
+2. Use a shared cache with distributed locks (Redis recommended) across all scheduler and worker instances. An array cache is suitable only for isolated tests. Cached login tokens are encrypted, scoped to account/host/password, and reused for up to 29 days; a credential change selects a new cache namespace. All API attempts for the same host/account share a rolling 60-request/minute budget.
+3. Set the following environment variables and rebuild the application's configuration cache:
+
+   ```dotenv
+   AFAQY_POLLING_ENABLED=true
+   AFAQY_WEBHOOKS_ENABLED=false
+   AFAQY_POLL_QUEUE=afaqy-poll
+   AFAQY_INGESTION_QUEUE=afaqy-ingest
+   ```
+
+4. Provision workers for both queues. For example:
+
+   ```sh
+   php artisan queue:work --queue=afaqy-poll --timeout=120 --tries=5
+   php artisan queue:work --queue=afaqy-ingest --timeout=60 --tries=1
+   ```
+
+   Set the queue connection's `retry_after` above 150 seconds (for example 180). Run multiple ingestion workers, and retain workers for the application's broadcast/default queue. Queue names default to `default` if not configured, for compatibility; dedicated workers prevent discovery or unrelated jobs from delaying telemetry.
+
+5. Confirm the application scheduler executes every minute. It runs both `fleetops:sync-telematics` and `fleetops:drain-telematic-inbox`. The drain recovers accepted deliveries if broker dispatch failed or a worker stopped; no payload is acknowledged before durable persistence.
+6. Open the connection's live telemetry panel. Verify a full polling run transitions from fetching to ingesting to completed, with expected unit/page/applied counts. `incomplete` and `partial` are failures to investigate, not complete fleet coverage.
+
+Rate-limit retries honor `Retry-After` (bounded to one hour). Other polling failures use 15/60/180/300-second backoff, with five queue attempts. Poll HTTP requests have 20-second response and five-second connection limits. Sweeps stop at a 90-second fetch budget or 100 pages and report incomplete coverage. Pending poll ingestion coalesces later polling ticks. Failed ingestion retries only failed units; the original encrypted body remains available. Five failed/interrupted attempts quarantine the delivery.
+
+## Stage 2 registration
+
+1. Configure the application's public API URL as HTTPS and set `AFAQY_WEBHOOKS_ENABLED=true`.
+2. In the connection's live telemetry panel select **Show registration URL**. Provide that exact URL to AFAQY and request **Device Signals / Positions** registration. Each URL contains the connection ID and a 256-bit random secret. The server requires both before accepting a body.
+3. Redact the `key` and `token` query parameters in reverse-proxy/access logs, tracing, error reporting, and shared screenshots. The application does not log webhook bodies or secrets. Protect database backups and the application encryption key.
+4. Confirm the first delivery's actual envelope, unit identifier, timestamps, content type, retry/acknowledgement behavior, and signing/header capabilities with AFAQY. Save a sanitized payload as a contract fixture. Until this is done, the UI continues to describe the adapter as provisional.
+5. Inspect quarantined deliveries in a restricted server session. Correct the adapter and use **Replay delivery**. The API deliberately does not expose raw location payloads or the stored secret through diagnostics.
+6. Run a 24-hour hybrid pilot before expanding. Polling continues every minute regardless of webhook capability. **Rotate secret and invalidate old URL** requires AFAQY to register the replacement URL.
+
+A successful HTTP 200 means **durably accepted**, not successfully applied. Bad credentials return 403, non-POST requests 405, malformed JSON 422, oversized bodies 413, and unavailable persistence/capacity 503. No undocumented provider signature scheme is assumed.
+
+## Interfaces and configuration
+
+Existing provider interfaces and vehicle/trailer event names remain compatible. New internal endpoints are scoped to the authenticated company:
+
+- `GET telematics/{id}/telemetry-diagnostics`
+- `POST telematics/{id}/telemetry-webhook`, with optional `{ "rotate": true }`
+- `POST telematics/{id}/telemetry-deliveries/{delivery}/replay`
+
+The public receiver remains `POST webhooks/telematics/afaqy?telematic=...&key=...` under the application's API prefix. A new `device.telemetry_updated` broadcast identifies the device; an open device panel reloads its authorized resource and refetches after socket reconnection. Company broadcast identity comes from the persisted asset, not a worker session. Map movement uses the existing vehicle/trailer events, rejects older source timestamps, and reloads visible telemetry assets after socket reconnection with at most five concurrent requests.
+
+Configure shared queues, retention, limits, and freshness under `telematics.telemetry` using `server/config/telemetry.php`. AFAQY's adapter switches and optional queue overrides remain under `telematics.afaqy` in `server/config/afaqy.php`. Defaults: two MiB per webhook, 10,000 pending deliveries per connection, processed payload retention 24 hours, quarantine retention seven days, stale-position thresholds 120 seconds with ignition on and 600 seconds with ignition off/unknown. Each device's metadata records the effective threshold. Connection status categories remain unchanged.
+
+## Incident verification
+
+For the screenshot's vehicle, compare the same AFAQY unit ID/IMEI and attached Fleetbase asset. Fetch its Units List record and compare raw UTC `dtt`/`dts` with `device.meta.telemetry`, `last_online_at`, and `vehicle.telematics.last_event_at`. Then inspect polling-run status, oldest pending delivery, worker/broadcast queue delay, and the open browser panel. A June-versus-September date gap cannot be accounted for by UTC+3 alone. No affected production account was accessed during implementation.
+
+## Validation and acceptance gates
+
+Run the new provider contract and database ingestion suites with the package Pest runner, and the provider-neutral telemetry browser tests with Ember:
+
+```sh
+php scripts/pest-runner.php server/tests/Unit/Support/Telematics/Providers/AfaqyRealtimeContractTest.php
+php scripts/pest-runner.php server/tests/Feature/Http/AfaqyRealtimeIngestionTest.php
+node_modules/.bin/ember test --filter=telemetry
+```
+
+The original implementation previously processed 5,000 signals plus 5,000 duplicate reconciliation observations in 45.9 seconds in the opt-in local SQLite benchmark (`XDEBUG_MODE=off AFAQY_RUN_LOAD_TESTS=1` with the ingestion suite above). During the provider-neutral refactor review, the final run took 66.5 seconds and failed the local 60-second budget; the original commit repeated in the same runtime took 83.4 seconds. Different machine/build load prevents a controlled speed comparison. The load gate remains open. It uses real model/database ingestion with indexed fixture tables, simulated spatial functions, and captured broadcasts; it excludes provider networking, broker latency, attached-asset load, and browser rendering.
+
+The original implementation validation passed 103 selected backend tests, including database ingestion, sensor preservation, retention recovery, and provider contracts. A separate check against the installed Laravel dispatcher verified that broker failures release uniqueness leases. The standard browser launcher is blocked by the linked Testem/execa CommonJS/ES-module mismatch; the two focused browser tests passed all nine assertions in an isolated local harness with lazy engine assets and dummy host configuration. These cover live panel refresh, reconnect, freshness labels, map movement, and reversed broadcasts; they do not exercise a production socket server. PHPStan is not clean in the package-only runtime (unresolved Laravel helpers/model types and strict type findings); it is not counted as a passing gate.
+
+The provider-neutral refactor passes 105 selected functional backend tests and five focused browser cases (19 assertions), including a second adapter with an unrelated payload format. See [the architecture review](TELEMETRY_ARCHITECTURE.md#review-and-validation) for the browser harness limits and current load-test results.
+
+Use an isolated deployment with 5,000 linked test units and production-like database/cache/queue/broadcast workers for load acceptance. Replay the confirmed position envelope at 167 signals/second while polling all 5,000 units. Measure gateway acknowledgement p95, inbox receipt-to-processing p95, browser receipt-to-render p95, and queue depth through a burst, worker restart, and provider timeout/429 period.
+
+Acceptance targets are a fully applied polling sweep within 60 seconds, webhook acknowledgement p95 below one second, receipt-to-visible-update p95 below five seconds, and bounded backlog that drains after disruption. Local contract tests validate five 1,000-unit pages; they are not proof of these deployment throughput or end-to-end latency targets. At 167 signals/second, 24-hour raw retention is about 14.4 million deliveries; size storage, retention, and cleanup capacity using actual encrypted payload sizes.
+
+Device reporting frequency still depends on AFAQY/device configuration: approximately 30 seconds engine-on and five minutes engine-off. Fleetbase cannot display a position before the physical device reports it.
+
+## Rollback
+
+Set `AFAQY_WEBHOOKS_ENABLED=false` to disable push independently; retained deliveries remain available. Keep polling enabled for reconciliation. Set `AFAQY_POLLING_ENABLED=false` to return scheduled AFAQY polling to the existing discovery path. Do not roll back/drop inbox tables until retained deliveries have been processed or deliberately exported/discarded. Preserve the shared encryption key for replay.

package/docs/TELEMETRY_ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# Provider-neutral telemetry infrastructure
+
+## Context and correction
+
+Fleet-Ops consumes third-party telematics through `TelematicProviderRegistry`,
+`TelematicProviderDescriptor`, and `TelematicProviderInterface`. Provider identity
+belongs at registration and adapter boundaries. Commit 9f561352 incorrectly
+extended AFAQY identity into shared resource components, map processing, and
+persistence. The performance requirement did not justify those dependencies.
+
+## Boundaries
+
+- Keep the existing provider interface compatible. Add an optional telemetry
+  interface for adapters opting into durable position ingestion and reconciliation.
+- Adapters interpret external identities, payload envelopes, timestamps, sensors,
+  authentication, rate limits, and reporting configuration. They return normalized
+  device/event/sensor samples. Shared workers never inspect vendor payload fields.
+- Use shared `telematic_sync_runs`, `telematic_deliveries`, and
+  `telematic_webhook_credentials` tables, scoped by `telematic_uuid`; the existing
+  connection identifies the provider and company. Do not create per-provider tables.
+- Shared services implement durable receipt, retries, replay, retention, ordering,
+  and diagnostics. Resolve adapters through the existing registry. Existing
+  providers retain their existing path until they implement the optional interface.
+- Declare UI capabilities in the existing provider descriptor. Shared connection
+  components render a reusable telemetry panel only when that capability is present.
+  Registration instructions and provider names are descriptor data, not template
+  branches. A registry of provider-specific components is unnecessary for the
+  currently identical diagnostics and registration UI.
+- Devices expose a normalized `meta.telemetry` snapshot. Maps consume a normalized
+  source timestamp from location events; neither knows which adapter produced it.
+- Keep provider configuration and public webhook URLs compatible. The original
+  migration has not been deployed or applied, as confirmed by the maintainer.
+  Replace it directly with the generic migration; no compatibility tables, rename
+  migration, or old job aliases are required. Existing pre-feature device metadata
+  remains readable through its established position timestamp fallback.
+
+## Review checks
+
+1. No provider-name branches in shared frontend components or movement tracking.
+2. Shared workers and ingestion accept a second registered adapter without edits.
+3. Unsupported providers expose no new telemetry UI or receiver capabilities.
+4. Storage, secret lookup, replay, and broadcasts remain connection/tenant scoped.
+5. Fresh installs create only generic infrastructure tables; rollback preserves
+   core device and integration tables.
+6. Polling/push deduplication, UTC timing, partial updates, ordering, and recovery
+   remain covered independently of the AFAQY adapter contract tests.
+
+## Tradeoffs
+
+Three shared tables separate run-level diagnostics, high-volume delivery retention,
+and connection-level secrets with different lifetimes. Provider-specific protocol
+classes remain appropriate. Capability opt-in avoids silently changing every
+existing integration's ingestion or webhook behavior. Production throughput and
+real AFAQY payload verification remain separate deployment gates.
+
+## Adding an adapter
+
+Implement `TelemetryProviderInterface` alongside the existing provider contract.
+`telemetryUnits()` recognizes the adapter's inbound envelope; it must also accept
+arrays of its raw samples for queued poll batches and failed-item retries.
+`normalizeTelemetrySnapshot()` returns `device`, `event`, and `sensors` using the
+existing normalization fields. `event.occurred_at` is device time,
+`event.last_seen_at` is provider contact time, and
+`event.meta.telemetry.provider_at` preserves the provider timestamp. No adapter
+normalization method may authenticate or perform network I/O.
+
+Register the driver with `TelematicProviderRegistry`, and declare
+`metadata.telemetry.durable_ingestion`, `secure_webhooks`, and `reconciliation`
+as appropriate. Optional `registration_instructions` and `contract_status`
+control explanatory UI copy. `telemetryOptions()` supplies adapter overrides for
+the shared `telematics.telemetry` configuration. Enabling an adapter does not
+require new tables, jobs, frontend components, or map branches.
+
+The example adapter in the database tests uses `tracker`, `measured`, `received`,
+and `point` fields and a `signals` envelope. It exercises shared poll and webhook
+processing, connection-scoped authentication, deduplication, and independent
+freshness settings without inheriting the AFAQY adapter.
+
+
+## Review and validation — 2026-09-16
+
+The refactor was checked against the boundaries above, then exercised through a
+second adapter. That feedback exposed numeric-cursor assumptions in the polling
+worker, provider registration failures interrupting shared inbox maintenance, and
+UI monitoring failing to start when capabilities arrived after the initial render.
+The shared paths now handle opaque cursors, isolate unavailable registrations
+while continuing recovery/retention, and restart monitoring on capability changes.
+
+Selected backend checks cover existing provider contracts and lifecycle behavior,
+database ingestion, poll/push deduplication, reversed delivery order, partial
+sensor values, tenant scoping, recovery, and migration up/down. The second adapter
+uses the same jobs, storage, receiver, and ingestion service without AFAQY
+inheritance or authentication during normalization. Source checks find no AFAQY
+identity in shared frontend components, map processing, telemetry workers,
+telemetry controllers, or the shared ingestion service.
+
+The location broadcast's additive `position_at` field is now asserted for a legacy
+provider too. It allows every adapter's map updates to use source time. The
+existing provider interface and legacy ingestion path remain available.
+
+Current functional checks: 105 selected backend tests pass; PHP syntax, ESLint,
+and template lint pass. The test-environment build succeeds. Five focused browser
+cases pass all 19 assertions against that build. Browser cases ran in fresh Chrome
+pages because the linked dummy host cannot recreate its universe registry across
+rendering tests; the standard launcher also has a Testem/execa module mismatch.
+These results do not establish a clean full browser suite or production socket
+latency.
+
+The opt-in local SQLite load gate remains open. The refactored path processed
+5,000 signals plus 5,000 duplicate reconciliation observations in 66.5 seconds,
+above its 60-second assertion. An earlier concurrent-build run took 109.2 seconds;
+the original commit, loaded from a temporary checkout with the same dependencies,
+took 83.4 seconds. Varying machine/build load prevents treating these runs as a
+controlled speed comparison. Each run retained exactly 5,000 events. Do not claim
+production throughput or the polling/webhook latency targets from these results.

package/extension.json

@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.65",
+    "version": "0.6.66",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.65",
+    "version": "0.6.66",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"
@@ -45,8 +45,8 @@
     "dependencies": {
         "@babel/core": "^7.23.2",
         "@fleetbase/ember-core": "^0.3.24",
-        "@fleetbase/ember-ui": "^0.3.41",
-        "@fleetbase/fleetops-data": "^0.1.40",
+        "@fleetbase/ember-ui": "^0.4.1",
+        "@fleetbase/fleetops-data": "^0.2.1",
         "@fleetbase/leaflet-routing-machine": "^3.2.17",
         "@fortawesome/ember-fontawesome": "^2.0.0",
         "@fortawesome/fontawesome-svg-core": "6.4.0",

package/scripts/coverage-summary.php

@@ -84,6 +84,13 @@ foreach ($project->xpath('.//file') ?: [] as $file) {
         continue;
     }
 
+    $uncoveredLines = [];
+    foreach ($file->line as $line) {
+        if ((string) $line['type'] === 'stmt' && (int) $line['count'] === 0) {
+            $uncoveredLines[] = (int) $line['num'];
+        }
+    }
+
     $files[] = [
         'path'            => $path,
         'covered'         => $coveredFileLines,
@@ -91,6 +98,7 @@ foreach ($project->xpath('.//file') ?: [] as $file) {
         'methods'         => $fileMethods,
         'covered_methods' => $coveredFileMethod,
         'percent'         => coveragePercent($coveredFileLines, $fileStatements),
+        'uncovered_lines' => $uncoveredLines,
     ];
 
     $relativePath = preg_replace('#^' . preg_quote(getcwd(), '#') . '/?#', '', $path);
@@ -141,6 +149,9 @@ echo "\nLowest covered files:\n";
 foreach (array_slice($files, 0, 20) as $file) {
     $relativePath = preg_replace('#^' . preg_quote(getcwd(), '#') . '/?#', '', $file['path']);
     printf("  %6.2f%%  %5d/%-5d  %s\n", $file['percent'], $file['covered'], $file['statements'], $relativePath ?: $file['path']);
+    if ($file['uncovered_lines']) {
+        printf("            Uncovered lines: %s\n", implode(', ', $file['uncovered_lines']));
+    }
 }
 
 if ($failUnder !== null && coveragePercent($coveredStatements, $statements) < $failUnder) {

package/scripts/pest-bootstrap.php

@@ -328,7 +328,7 @@ if (!class_exists('Fleetbase\TestSupport\PendingDispatch')) {
 }
 
 if (!class_exists('Fleetbase\TestSupport\DispatchRecorder')) {
-    eval('namespace Fleetbase\TestSupport; class DispatchRecorder { public static array $dispatched = []; public static function record(string $job, array $arguments): void { self::$dispatched[] = [\'job\' => $job, \'arguments\' => $arguments]; } }');
+    eval('namespace Fleetbase\TestSupport; class DispatchRecorder { public static array $dispatched = []; public static ?\Throwable $failure = null; public static function record(string $job, array $arguments): void { if (self::$failure) { throw self::$failure; } self::$dispatched[] = [\'job\' => $job, \'arguments\' => $arguments]; } }');
 }
 
 if (!trait_exists('Illuminate\Foundation\Bus\Dispatchable')) {

package/server/config/afaqy.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'polling_enabled'           => env('AFAQY_POLLING_ENABLED', false),
+    'webhooks_enabled'          => env('AFAQY_WEBHOOKS_ENABLED', false),
+    'poll_queue'                => env('AFAQY_POLL_QUEUE', env('TELEMATICS_POLL_QUEUE', 'default')),
+    'ingestion_queue'           => env('AFAQY_INGESTION_QUEUE', env('TELEMATICS_INGESTION_QUEUE', 'default')),
+];

package/server/config/fuel-providers.php

@@ -14,11 +14,30 @@ return [
             'required_fields' => [
                 [
                     'name' => 'api_token',
-                    'label' => 'API Token',
+                    'label' => 'Integration Token (WS-SK) or API Token',
                     'type' => 'password',
-                    'help_text' => 'Bearer API token from PetroApp.',
+                    'help_text' => 'Use the test token for Sandbox, or your company token for Production. Select the matching authentication method.',
                     'required' => true,
                 ],
+                [
+                    'name' => 'auth_type',
+                    'label' => 'Authentication method',
+                    'type' => 'select',
+                    'default' => 'ws_sk_header',
+                    'options' => [
+                        ['value' => 'ws_sk_header', 'label' => 'Integration Token (WS-SK)'],
+                        ['value' => 'bearer_token', 'label' => 'Bearer API Token'],
+                    ],
+                    'help_text' => 'Choose WS-SK for an integration token, or Bearer for a token returned by get_apiKey.',
+                    'required' => false,
+                ],
+                [
+                    'name' => 'base_url',
+                    'label' => 'Base URL override (optional)',
+                    'type' => 'url',
+                    'help_text' => 'Leave blank to use the selected environment. A custom URL overrides the environment selection.',
+                    'required' => false,
+                ],
             ],
             'capabilities' => ['vehicles', 'transactions', 'stations', 'trips'],
             'sync_defaults' => [
@@ -27,13 +46,15 @@ return [
                 'auto_create_fuel_reports' => true,
             ],
             'setup_instructions' => [
-                'Create or request a PetroApp API token.',
-                'Enter the token, then run Test Connection.',
-                'Run a date-window sync to import bills into Fuel Transactions.',
+                'Select Sandbox for PetroApp staging and enter the test integration token using WS-SK authentication.',
+                'Run Test Connection, then sync a small date window to verify imported bills and vehicle matches.',
+                'For Production, use your company integration token from the PetroApp API token profile page.',
+                'Alternatively, exchange company username and password at get_apiKey and use the returned Bearer API token.',
             ],
             'metadata' => [
-                'auth_type' => 'bearer_token',
-                'legacy_auth_type' => 'ws_sk_header',
+                'auth_type' => 'ws_sk_header',
+                'supported_auth_types' => ['ws_sk_header', 'bearer_token'],
+                'base_urls' => \Fleetbase\FleetOps\Support\FuelProviders\Providers\PetroAppFuelProvider::BASE_URLS,
                 'pagination' => 'page',
                 'default_currency' => 'SAR',
             ],

package/server/config/telematics.php

@@ -153,9 +153,16 @@ return [
                     'validation'  => 'required_without:username|string',
                 ],
             ],
-            'supports_webhooks'  => false,
+            'supports_webhooks'  => true,
             'supports_discovery' => true,
             'metadata'           => [
+                'telemetry' => [
+                    'durable_ingestion'         => true,
+                    'secure_webhooks'           => true,
+                    'reconciliation'            => true,
+                    'registration_instructions' => 'Provide the secure URL to AFAQY to register Device Signals / Positions. Polling continues after registration.',
+                    'contract_status'           => 'provisional',
+                ],
                 'rate_limit'   => 60,
                 'pagination'   => 'offset',
                 'capabilities' => ['tracking', 'speed', 'heading', 'odometer', 'fuel_level', 'ignition'],