@fleetbase/fleetops-engine 0.6.65 → 0.6.66

package/server/src/Contracts/TelemetryProviderInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Fleetbase\FleetOps\Contracts;
+
+/** Optional extension: existing integrations need not change their provider contract. */
+interface TelemetryProviderInterface extends TelematicProviderInterface
+{
+    /** Runtime switches and protocol-specific limits; must not authenticate. */
+    public function telemetryOptions(): array;
+
+    /** Split a provider delivery into raw position samples; reject unsupported envelopes. */
+    public function telemetryUnits(array $payload): array;
+
+    /**
+     * Normalize one raw sample without network access using existing device/event/sensor fields.
+     *
+     * device.device_id and event.device_id identify the same unit within this connection.
+     * event includes event_type, occurred_at (device time), last_seen_at (contact time),
+     * location {lat, lng}, and optional meta.telemetry.provider_at. Missing/invalid
+     * timestamps or coordinates must remain null; never replace them with receipt time.
+     * Each sensor includes recorded_at in UTC and its existing normalized identity fields.
+     * Preserve omissions in partial messages, rather than synthesizing metadata defaults.
+     *
+     * @return array{device: array, event: array, sensors?: array}
+     */
+    public function normalizeTelemetrySnapshot(array $payload): array;
+}

package/server/src/Events/DeviceTelemetryUpdated.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\Device;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+
+class DeviceTelemetryUpdated implements ShouldBroadcast
+{
+    public bool $afterCommit = true;
+    public string $companyUuid;
+    public string $deviceUuid;
+    public array $data;
+
+    public function __construct(Device $device)
+    {
+        $this->companyUuid = $device->company_uuid;
+        $this->deviceUuid  = $device->uuid;
+        $this->data        = ['id' => $device->uuid, 'device_id' => $device->public_id, 'telemetry' => data_get($device->meta, 'telemetry', [])];
+    }
+
+    public function broadcastOn(): array
+    {
+        return [new Channel('company.' . $this->companyUuid), new Channel('device.' . $this->deviceUuid)];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'device.telemetry_updated';
+    }
+
+    public function broadcastWith(): array
+    {
+        return ['event' => $this->broadcastAs(), 'data' => $this->data];
+    }
+}

package/server/src/Events/VehicleLocationChanged.php

@@ -22,6 +22,8 @@ class VehicleLocationChanged implements ShouldBroadcast
      * @var string
      */
     public $eventId;
+    public ?string $companyUuid;
+    public ?string $apiCredentialUuid;
 
     /**
      * The datetime instance the broadcast ws triggered.
@@ -100,6 +102,8 @@ class VehicleLocationChanged implements ShouldBroadcast
      */
     public function __construct(Vehicle $vehicle, array $additionalData = [])
     {
+        $this->companyUuid        = $vehicle->company_uuid;
+        $this->apiCredentialUuid  = session('api_credential');
         $this->eventId            = uniqid('event_');
         $this->sentAt             = Carbon::now()->toDateTimeString();
         $this->additionalData     = $additionalData;
@@ -120,12 +124,12 @@ class VehicleLocationChanged implements ShouldBroadcast
      */
     public function broadcastOn()
     {
-        return [
-            new Channel('company.' . session('company')),
-            new Channel('api.' . session('api_credential')),
+        return array_values(array_filter([
+            $this->companyUuid ? new Channel('company.' . $this->companyUuid) : null,
+            $this->apiCredentialUuid ? new Channel('api.' . $this->apiCredentialUuid) : null,
             new Channel('vehicle.' . $this->vehicleId),
             new Channel('vehicle.' . $this->vehicleUuid),
-        ];
+        ]));
     }
 
     /**

package/server/src/Exports/InspectionExport.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exports;
+
+use Fleetbase\FleetOps\Models\InspectionSubmission;
+use Maatwebsite\Excel\Concerns\FromCollection;
+use Maatwebsite\Excel\Concerns\ShouldAutoSize;
+use Maatwebsite\Excel\Concerns\WithColumnFormatting;
+use Maatwebsite\Excel\Concerns\WithHeadings;
+use Maatwebsite\Excel\Concerns\WithMapping;
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat;
+
+/**
+ * Inspections as a spreadsheet — what a compliance officer is asked for.
+ *
+ * One row per submission, not per answer: the question a DVIR export answers
+ * is "which trucks failed, when, and did anyone deal with it", so the defects
+ * are summarised into a column and the follow-up is named. The per-answer
+ * detail lives on the record, where the photos are.
+ */
+class InspectionExport implements FromCollection, WithHeadings, WithMapping, WithColumnFormatting, ShouldAutoSize
+{
+    protected array $selections = [];
+
+    public function __construct(array $selections = [])
+    {
+        $this->selections = $selections;
+    }
+
+    public function map($submission): array
+    {
+        return [
+            $submission->public_id,
+            $submission->form_name,
+            $submission->vehicle_name,
+            $submission->driver_name,
+            $submission->type,
+            $submission->status,
+            $submission->result,
+            $submission->source,
+            $submission->odometer,
+            $submission->engine_hours,
+            $submission->total_items,
+            $submission->failed_items,
+            static::failedLabels($submission),
+            static::unsafeLabel($submission),
+            $submission->issue?->public_id,
+            $submission->workOrder?->public_id,
+            $submission->started_at,
+            $submission->submitted_at,
+            $submission->resolved_at,
+            $submission->created_at,
+        ];
+    }
+
+    public function headings(): array
+    {
+        return [
+            'ID',
+            'Form',
+            'Vehicle',
+            'Driver',
+            'Type',
+            'Status',
+            'Result',
+            'Source',
+            'Odometer',
+            'Engine Hours',
+            'Items',
+            'Defects',
+            'Failed Items',
+            'Unsafe',
+            'Issue',
+            'Work Order',
+            'Started',
+            'Submitted',
+            'Resolved',
+            'Date Created',
+        ];
+    }
+
+    public function columnFormats(): array
+    {
+        return [
+            'Q' => NumberFormat::FORMAT_DATE_DDMMYYYY,
+            'R' => NumberFormat::FORMAT_DATE_DDMMYYYY,
+            'S' => NumberFormat::FORMAT_DATE_DDMMYYYY,
+            'T' => NumberFormat::FORMAT_DATE_DDMMYYYY,
+        ];
+    }
+
+    /** The defects, named, so the spreadsheet says what actually failed. */
+    public static function failedLabels(InspectionSubmission $submission): string
+    {
+        return $submission->itemResults
+            ->filter(fn ($result) => !$result->passed)
+            ->map(fn ($result) => trim((string) $result->label))
+            ->filter()
+            ->implode(', ');
+    }
+
+    /** Whether the inspection took the vehicle out of service. */
+    public static function unsafeLabel(InspectionSubmission $submission): string
+    {
+        $unsafe = filter_var(data_get($submission->meta, 'unsafe', false), FILTER_VALIDATE_BOOLEAN)
+            || $submission->itemResults->contains(fn ($result) => filter_var(data_get($result->meta, 'unsafe', false), FILTER_VALIDATE_BOOLEAN));
+
+        return $unsafe ? 'Yes' : 'No';
+    }
+
+    /**
+     * @return \Illuminate\Support\Collection
+     */
+    public function collection()
+    {
+        $query = InspectionSubmission::where('company_uuid', session('company'))
+            ->with(['form', 'vehicle', 'driver', 'itemResults', 'issue', 'workOrder']);
+
+        if ($this->selections) {
+            $query->whereIn('uuid', $this->selections);
+        }
+
+        return $query->get();
+    }
+}

package/server/src/Http/Controllers/Api/v1/GeofenceController.php

@@ -2,9 +2,9 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 
+use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\GeofenceEventLog;
 use Fleetbase\FleetOps\Support\Utils;
-use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;

package/server/src/Http/Controllers/Api/v1/InspectionController.php

@@ -0,0 +1,300 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
+
+use Fleetbase\FleetOps\Http\Resources\v1\InspectionForm as InspectionFormResource;
+use Fleetbase\FleetOps\Http\Resources\v1\InspectionSubmission as InspectionSubmissionResource;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\FleetOps\Models\InspectionSubmission;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\InspectionSubmitter;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
+
+/**
+ * Driver-facing inspections.
+ *
+ * A DVIR is filled in by the driver, on a handset, often before the vehicle
+ * has left the yard and sometimes with no signal. Until now the only way in
+ * was a tokenised public link minted from the console, one per inspection —
+ * which is fine for a contractor with a phone number and no app, and useless
+ * for a driver who inspects the same truck every morning.
+ *
+ * These endpoints let the app read the forms its company has published, file
+ * a submission against one, and read back what was filed. Authoring forms,
+ * reviewing and resolving submissions stay on the internal namespace: that is
+ * fleet management, not driving.
+ */
+class InspectionController extends Controller
+{
+    /**
+     * The relations a submission is answered with, so the app never has to
+     * make a second request to learn what its own submission produced.
+     */
+    protected const SUBMISSION_RELATIONS = ['form', 'vehicle', 'driver', 'itemResults', 'issue', 'workOrder', 'customFieldValues.customField', 'files'];
+
+    /**
+     * GET /v1/inspection-forms — the published forms a driver may fill in.
+     *
+     * `vehicle` narrows to forms bound to that vehicle *and* forms bound to
+     * nothing: an organisation-wide pre-trip form applies to every truck, and
+     * a form written for one truck's lift gate applies to that truck only.
+     */
+    public function queryForms(Request $request)
+    {
+        $query = static::publishedForms();
+
+        if ($request->filled('type')) {
+            $query->whereIn('type', Utils::arrayFrom($request->input('type')));
+        }
+
+        if ($request->filled('vehicle')) {
+            $vehicle = static::findVehicleRecord($request->input('vehicle'));
+            if (!$vehicle) {
+                return response()->apiError('Vehicle resource not found.', 404);
+            }
+
+            $query->where(function ($query) use ($vehicle) {
+                $query->whereNull('subject_uuid')->orWhere(function ($query) use ($vehicle) {
+                    $query->where('subject_type', Vehicle::class)->where('subject_uuid', $vehicle->uuid);
+                });
+            });
+        }
+
+        return InspectionFormResource::collection($query->limit(static::limit($request))->get());
+    }
+
+    /**
+     * GET /v1/inspection-forms/{id} — one published form, items and settings included.
+     *
+     * A draft or archived form answers 404 rather than 403: to a driver a form
+     * that cannot be filled in does not exist, and the distinction would only
+     * tell them something about the console they cannot act on.
+     */
+    public function findForm(string $id)
+    {
+        $form = static::findPublishedForm($id);
+        if (!$form) {
+            return response()->apiError('Inspection form resource not found.', 404);
+        }
+
+        return new InspectionFormResource($form);
+    }
+
+    /**
+     * POST /v1/inspections — file an inspection against a published form.
+     *
+     * The body is exactly what the public link accepts, plus the three things
+     * the link already knew: which form, which vehicle, which driver. The app
+     * queues a submit when it is offline and replays it later, so a replay
+     * that carries the same `Idempotency-Key` header answers with the
+     * submission the first attempt created rather than filing a second one.
+     */
+    public function submit(Request $request)
+    {
+        $validated = $request->validate(array_merge(InspectionSubmitter::rules(), [
+            'inspection_form' => 'required|string',
+            'driver'          => 'required|string',
+            'vehicle'         => 'nullable|string',
+            'started_at'      => 'nullable|date',
+        ]));
+
+        $driver = static::findDriverRecord($request->input('driver'));
+        if (!$driver) {
+            return response()->apiError('Driver resource not found.', 404);
+        }
+
+        $form = static::findPublishedForm($request->input('inspection_form'));
+        if (!$form) {
+            return response()->apiError('Inspection form resource not found.', 404);
+        }
+
+        $vehicle = null;
+        if ($request->filled('vehicle')) {
+            $vehicle = static::findVehicleRecord($request->input('vehicle'));
+            if (!$vehicle) {
+                return response()->apiError('Vehicle resource not found.', 404);
+            }
+        }
+
+        $idempotencyKey = trim((string) $request->header('Idempotency-Key'));
+        if ($idempotencyKey !== '') {
+            $replayed = static::findSubmissionByIdempotencyKey($driver, $idempotencyKey);
+            if ($replayed) {
+                return new InspectionSubmissionResource($replayed->load(static::SUBMISSION_RELATIONS));
+            }
+        }
+
+        $attributes = [
+            // Without an explicit vehicle the inspection is of the truck the
+            // driver is assigned to, which is what a pre-trip almost always is.
+            'vehicle_uuid'      => $vehicle?->uuid ?? $driver->vehicle_uuid,
+            'driver_uuid'       => $driver->uuid,
+            'submitted_by_uuid' => $driver->user_uuid,
+            'source'            => 'navigator',
+            'meta'              => $idempotencyKey !== '' ? ['idempotency_key' => $idempotencyKey] : [],
+        ];
+
+        if ($request->filled('started_at')) {
+            $attributes['started_at'] = Carbon::parse($request->input('started_at'));
+        }
+
+        $submission = InspectionSubmitter::submit($form, $validated, $attributes);
+
+        return new InspectionSubmissionResource($submission->fresh(static::SUBMISSION_RELATIONS));
+    }
+
+    /**
+     * GET /v1/inspections — submissions, newest first.
+     */
+    public function query(Request $request)
+    {
+        $query = static::submissions();
+
+        if ($request->filled('driver')) {
+            $driver = static::findDriverRecord($request->input('driver'));
+            if (!$driver) {
+                return response()->apiError('Driver resource not found.', 404);
+            }
+
+            $query->where('driver_uuid', $driver->uuid);
+        }
+
+        if ($request->filled('vehicle')) {
+            $vehicle = static::findVehicleRecord($request->input('vehicle'));
+            if (!$vehicle) {
+                return response()->apiError('Vehicle resource not found.', 404);
+            }
+
+            $query->where('vehicle_uuid', $vehicle->uuid);
+        }
+
+        static::applySubmissionFilters($request, $query);
+
+        return InspectionSubmissionResource::collection($query->limit(static::limit($request))->get());
+    }
+
+    /**
+     * GET /v1/inspections/{id} — one submission with its item results and follow-up.
+     */
+    public function find(string $id)
+    {
+        $submission = static::findSubmission($id);
+        if (!$submission) {
+            return response()->apiError('Inspection resource not found.', 404);
+        }
+
+        return new InspectionSubmissionResource($submission->load(static::SUBMISSION_RELATIONS));
+    }
+
+    /**
+     * GET /v1/vehicles/{id}/inspections — a vehicle's inspection history.
+     *
+     * The same rows `query` answers with `vehicle=`, addressed the way the app
+     * holds them: it is on a vehicle's screen, and wants that vehicle's history.
+     */
+    public function forVehicle(Request $request, string $id)
+    {
+        $vehicle = static::findVehicleRecord($id);
+        if (!$vehicle) {
+            return response()->apiError('Vehicle resource not found.', 404);
+        }
+
+        $query = static::submissions()->where('vehicle_uuid', $vehicle->uuid);
+        static::applySubmissionFilters($request, $query);
+
+        return InspectionSubmissionResource::collection($query->limit(static::limit($request))->get());
+    }
+
+    /** The column filters shared by the two listings. Each accepts one value or a comma separated list. */
+    protected static function applySubmissionFilters(Request $request, $query): void
+    {
+        foreach (['type', 'result', 'status'] as $column) {
+            if ($request->filled($column)) {
+                $query->whereIn($column, Utils::arrayFrom($request->input($column)));
+            }
+        }
+    }
+
+    /**
+     * How many rows a listing answers with. Defaults to what fits on a screen;
+     * a driver's whole history is thousands of rows nobody asked for.
+     */
+    protected static function limit(Request $request): int
+    {
+        $limit = (int) $request->input('limit', 30);
+
+        return $limit > 0 ? $limit : 30;
+    }
+
+    /**
+     * Every lookup is scoped to the company the API key belongs to. The
+     * consumable API serves one company per credential, and a public id from
+     * another company must be indistinguishable from one that does not exist.
+     */
+    protected static function publishedForms()
+    {
+        return InspectionForm::where('company_uuid', session('company'))
+            ->where('status', 'published')
+            ->whereNotNull('published_at')
+            // The form's structure is the point of the read; loading it with
+            // the forms keeps a listing to two queries instead of two a form.
+            ->with(['fieldGroups', 'fields'])
+            ->orderBy('published_at', 'desc');
+    }
+
+    protected static function submissions()
+    {
+        return InspectionSubmission::where('company_uuid', session('company'))
+            ->with(['form', 'vehicle', 'driver', 'customFieldValues.customField', 'files'])
+            ->orderBy('submitted_at', 'desc')
+            ->orderBy('created_at', 'desc');
+    }
+
+    protected static function findPublishedForm(string $id): ?InspectionForm
+    {
+        return static::publishedForms()
+            ->where(function ($query) use ($id) {
+                $query->where('public_id', $id)->orWhere('uuid', $id);
+            })
+            ->first();
+    }
+
+    protected static function findSubmission(string $id): ?InspectionSubmission
+    {
+        return InspectionSubmission::where('company_uuid', session('company'))
+            ->where(function ($query) use ($id) {
+                $query->where('public_id', $id)->orWhere('uuid', $id);
+            })
+            ->first();
+    }
+
+    protected static function findSubmissionByIdempotencyKey(Driver $driver, string $key): ?InspectionSubmission
+    {
+        return InspectionSubmission::where('company_uuid', $driver->company_uuid)
+            ->where('driver_uuid', $driver->uuid)
+            ->where('meta->idempotency_key', $key)
+            ->first();
+    }
+
+    protected static function findDriverRecord(string $id): ?Driver
+    {
+        return Driver::where('company_uuid', session('company'))
+            ->where(function ($query) use ($id) {
+                $query->where('public_id', $id)->orWhere('uuid', $id);
+            })
+            ->first();
+    }
+
+    protected static function findVehicleRecord(string $id): ?Vehicle
+    {
+        return Vehicle::where('company_uuid', session('company'))
+            ->where(function ($query) use ($id) {
+                $query->where('public_id', $id)->orWhere('uuid', $id);
+            })
+            ->first();
+    }
+}

package/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php

@@ -64,15 +64,28 @@ class FuelProviderConnectionController extends FleetOpsController
 
     public function sync(Request $request, string $id): JsonResponse
     {
+        $request->validate([
+            'from'    => 'nullable|date',
+            'to'      => 'nullable|date|after_or_equal:from',
+            'options' => 'nullable|array',
+        ]);
         $connection = $this->findConnection($id);
-        $async      = $request->boolean('async', true);
-        $from       = $request->input('from') ? Carbon::parse($request->input('from')) : null;
-        $to         = $request->input('to') ? Carbon::parse($request->input('to')) : null;
-        $options    = $request->array('options', []);
-        $syncRun    = $this->fuelProviderService->createSyncRun($connection, $from, $to, $async ? 'queued' : 'running');
+        if ($connection->status === 'disabled') {
+            throw ValidationException::withMessages(['connection' => 'Enable this integration before syncing.']);
+        }
+        $async   = $request->boolean('async', true);
+        $from    = $request->input('from') ? Carbon::parse($request->input('from'))->startOfDay() : null;
+        $to      = $request->input('to') ? Carbon::parse($request->input('to'))->endOfDay() : null;
+        $options = $request->array('options', []);
+        $syncRun = $this->fuelProviderService->createSyncRun($connection, $from, $to, $async ? 'queued' : 'running');
 
         if ($async) {
-            SyncFuelProviderTransactionsJob::dispatch($connection->uuid, $from?->toIso8601String(), $to?->toIso8601String(), $options, $syncRun->uuid);
+            try {
+                SyncFuelProviderTransactionsJob::dispatch($connection->uuid, $syncRun->from?->toIso8601String(), $syncRun->to?->toIso8601String(), $options, $syncRun->uuid);
+            } catch (\Throwable $error) {
+                $syncRun->update(['status' => 'error', 'finished_at' => now(), 'error' => 'Unable to queue sync. Please retry.']);
+                throw $error;
+            }
 
             return response()->json(['status' => 'ok', 'message' => 'Fuel provider sync queued.', 'sync_run' => $syncRun], 202);
         }
@@ -82,9 +95,28 @@ class FuelProviderConnectionController extends FleetOpsController
         return response()->json(['status' => 'ok', 'summary' => $summary, 'sync_run' => $syncRun->fresh()]);
     }
 
+    public function activity(Request $request, string $id): JsonResponse
+    {
+        $connection   = $this->findConnection($id);
+        $transactions = $connection->transactions();
+        $totals       = (clone $transactions)->selectRaw('COUNT(*) as transactions, SUM(volume) as liters, COUNT(fuel_report_uuid) as fuel_reports')->first();
+        $unmatched    = (clone $transactions)->where('sync_status', 'unmatched')->count();
+        $spend        = (clone $transactions)->selectRaw('currency, SUM(amount) as amount')->groupBy('currency')->get()->map(fn ($row) => ['currency' => $row->currency, 'amount' => (int) $row->amount]);
+        $runs         = $connection->syncRuns()->latest()->limit(20)->get();
+
+        return response()->json([
+            'connection' => $connection->only(['status', 'last_synced_at', 'last_tested_at', 'last_error', 'last_sync_state']),
+            'totals'     => ['transactions' => (int) $totals->transactions, 'liters' => (float) $totals->liters, 'fuel_reports' => (int) $totals->fuel_reports, 'unmatched' => $unmatched, 'spend' => $spend],
+            'runs'       => $runs->map(fn ($run) => $run->only(['uuid', 'status', 'from', 'to', 'imported', 'matched', 'unmatched', 'fuel_reports_created', 'liters', 'amount', 'started_at', 'finished_at', 'created_at', 'error', 'summary'])),
+        ]);
+    }
+
     protected function validateConnectionInput(array $input, ?FuelProviderConnection $connection = null): void
     {
         $provider = data_get($input, 'provider');
+        if (isset($input['environment']) && !in_array($input['environment'], ['production', 'sandbox'], true)) {
+            throw ValidationException::withMessages(['environment' => 'Choose Production or Sandbox.']);
+        }
         if (!$provider) {
             throw ValidationException::withMessages(['provider' => 'Fuel integration provider is required.']);
         }
@@ -104,13 +136,13 @@ class FuelProviderConnectionController extends FleetOpsController
     protected function normalizeConnectionInput(array &$input, ?FuelProviderConnection $connection = null): void
     {
         $input['company_uuid'] ??= session('company');
-        $input['environment'] ??= 'production';
+        $input['environment'] ??= $connection?->environment ?? 'production';
         $input['status']        = $connection?->status && $connection->status !== 'draft' ? $connection->status : ($input['status'] ?? 'configured');
         $input['sync_settings'] = array_merge([
             'window_days'              => 7,
             'matching_order'           => ['plate_number', 'internal_id', 'vin', 'serial_number', 'call_sign', 'fuel_card_number', 'trip_number'],
             'auto_create_fuel_reports' => true,
-        ], (array) data_get($input, 'sync_settings', []));
+        ], (array) $connection?->sync_settings, (array) data_get($input, 'sync_settings', []));
     }
 
     protected function findConnection(string $id): FuelProviderConnection