@fleetbase/fleetops-engine 0.6.64 → 0.6.66

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/Exports/TrailerExport.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exports;
+
+use Fleetbase\FleetOps\Models\Trailer;
+use Maatwebsite\Excel\Concerns\FromCollection;
+use Maatwebsite\Excel\Concerns\ShouldAutoSize;
+use Maatwebsite\Excel\Concerns\WithHeadings;
+use Maatwebsite\Excel\Concerns\WithMapping;
+
+class TrailerExport implements FromCollection, WithHeadings, WithMapping, ShouldAutoSize
+{
+    public function __construct(protected array $selections = [])
+    {
+    }
+
+    public function headings(): array
+    {
+        return ['ID', 'Name', 'Code', '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', 'Date Created', 'Date Updated'];
+    }
+
+    public function map($trailer): array
+    {
+        return [$trailer->public_id, $trailer->name, $trailer->code, $trailer->type, $trailer->status, $trailer->vin, $trailer->plate_number, $trailer->serial_number, $trailer->make, $trailer->model, $trailer->year, $trailer->length, $trailer->width, $trailer->height, $trailer->tare_weight, $trailer->gvwr, $trailer->payload_capacity, $trailer->cargo_volume, $trailer->axle_count, $trailer->tire_count, $trailer->coupling_type, $trailer->brake_type, $trailer->refrigerated ? 'Yes' : 'No', $trailer->measurement_system, $trailer->odometer, $trailer->odometer_unit, $trailer->ownership_type, $trailer->purchased_at, $trailer->lease_expires_at, $trailer->notes, $trailer->created_at, $trailer->updated_at];
+    }
+
+    public function collection()
+    {
+        return Trailer::where('company_uuid', session('company'))->when($this->selections, fn ($q) => $q->whereIn('uuid', $this->selections))->get();
+    }
+}

package/server/src/Http/Controllers/Api/v1/Concerns/ResolvesFleetOpsApiResources.php

@@ -12,10 +12,10 @@ use Fleetbase\FleetOps\Models\FuelReport;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Part;
 use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Models\Warranty;
-use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Models\File;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
@@ -72,7 +72,10 @@ trait ResolvesFleetOpsApiResources
             return [null, null];
         }
 
-        $modelClass = Utils::getMutationType($type);
+        $modelClass = $this->allowedMorphTypes()[$type] ?? null;
+        if (!$modelClass) {
+            throw ValidationException::withMessages(['type' => ['Unsupported resource type.']]);
+        }
         $model      = $this->resolveModel($modelClass, $id);
 
         return [$modelClass, $model->uuid];
@@ -166,6 +169,9 @@ trait ResolvesFleetOpsApiResources
             'fleet-ops:vehicle'                  => Vehicle::class,
             'vehicle'                            => Vehicle::class,
             Vehicle::class                       => Vehicle::class,
+            'fleet-ops:trailer'                  => Trailer::class,
+            'trailer'                            => Trailer::class,
+            Trailer::class                       => Trailer::class,
             'fleet-ops:driver'                   => Driver::class,
             'driver'                             => Driver::class,
             Driver::class                        => Driver::class,

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

@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 
+use Fleetbase\FleetOps\Exceptions\DeviceAlreadyAttachedException;
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\Concerns\ResolvesFleetOpsApiResources;
 use Fleetbase\FleetOps\Http\Requests\CreateDeviceRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateDeviceRequest;
@@ -9,7 +10,6 @@ use Fleetbase\FleetOps\Http\Resources\v1\DeletedResource;
 use Fleetbase\FleetOps\Http\Resources\v1\Device as DeviceResource;
 use Fleetbase\FleetOps\Models\Device;
 use Fleetbase\FleetOps\Models\Telematic;
-use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\Warranty;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
@@ -90,28 +90,34 @@ class DeviceController extends Controller
         $this->rejectUuidIdentifiers($request);
 
         $request->validate([
-            'vehicle' => 'required_without:attachable|string|nullable',
+            'vehicle'         => 'required_without:attachable|string|nullable',
+            'attachable'      => 'required_without:vehicle|string|nullable',
+            'attachable_type' => 'nullable|in:fleet-ops:vehicle,fleet-ops:trailer,vehicle,trailer',
         ]);
 
-        $deviceId  = $id;
-        $vehicleId = $request->input('vehicle') ?? $request->input('attachable');
+        $deviceId       = $id;
+        $attachableId   = $request->input('vehicle') ?? $request->input('attachable');
+        $attachableType = $request->filled('vehicle') ? 'fleet-ops:vehicle' : $request->input('attachable_type', 'fleet-ops:vehicle');
 
         try {
-            $device  = $this->resolveModel(Device::class, $deviceId);
-            $vehicle = $this->resolveModel(Vehicle::class, $vehicleId);
+            $device       = $this->resolveModel(Device::class, $deviceId);
+            [$modelClass] = $this->resolveMorph($attachableType, $attachableId);
+            $attachable   = $this->resolveModel($modelClass, $attachableId);
         } catch (\Illuminate\Database\Eloquent\ModelNotFoundException $exception) {
-            $this->logDeviceAttachmentLookupFailure('attach', $deviceId, $vehicleId);
+            $this->logDeviceAttachmentLookupFailure('attach', $deviceId, $attachableId);
 
-            return response()->json(['error' => 'Device or vehicle resource not found.'], 404);
+            return response()->json(['error' => 'Device or attachable resource not found.'], 404);
         }
 
         try {
-            $device->attachTo($vehicle);
+            $device->attachTo($attachable);
             $this->loadDeviceRelations($device);
+        } catch (DeviceAlreadyAttachedException $e) {
+            return response()->json(['error' => $e->getMessage()], 409);
         } catch (\Throwable $e) {
-            $this->logDeviceAttachmentFailure('attach', $device, $vehicle, $e);
+            $this->logDeviceAttachmentFailure('attach', $device, $attachable, $e);
 
-            return response()->json(['error' => 'Unable to attach device to vehicle.'], 500);
+            return response()->json(['error' => 'Unable to attach device to resource.'], 500);
         }
 
         return response()->json([
@@ -136,7 +142,7 @@ class DeviceController extends Controller
         } catch (\Throwable $e) {
             $this->logDeviceAttachmentFailure('detach', $device, null, $e);
 
-            return response()->json(['error' => 'Unable to detach device from vehicle.'], 500);
+            return response()->json(['error' => 'Unable to detach device from resource.'], 500);
         }
 
         return response()->json([
@@ -242,14 +248,15 @@ class DeviceController extends Controller
         ]);
     }
 
-    protected function logDeviceAttachmentFailure(string $action, Device $device, ?Vehicle $vehicle, \Throwable $exception): void
+    protected function logDeviceAttachmentFailure(string $action, Device $device, ?\Illuminate\Database\Eloquent\Model $attachable, \Throwable $exception): void
     {
         Log::error('Public API device attachment failed', [
             'action'          => $action,
             'device_uuid'     => $device->uuid,
             'device_id'       => $device->public_id,
-            'vehicle_uuid'    => $vehicle?->uuid,
-            'vehicle_id'      => $vehicle?->public_id,
+            'attachable_type' => $attachable ? get_class($attachable) : null,
+            'attachable_uuid' => $attachable?->uuid,
+            'attachable_id'   => $attachable?->public_id,
             'company_uuid'    => session('company'),
             'request_id'      => request()->headers->get('X-Request-ID') ?? request()->headers->get('X-Correlation-ID'),
             'exception_class' => get_class($exception),

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

@@ -12,6 +12,7 @@ use Fleetbase\FleetOps\Models\Warranty;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\File;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 
 class EquipmentController extends Controller
 {
@@ -79,6 +80,52 @@ class EquipmentController extends Controller
         return $this->deletedEquipmentResource($equipment);
     }
 
+    public function attach(Request $request, string $id)
+    {
+        $this->rejectUuidIdentifiers($request);
+        $request->validate(['attachable_type' => ['required', 'in:fleet-ops:vehicle,fleet-ops:trailer,vehicle,trailer'], 'attachable' => ['required', 'string']]);
+        try {
+            $equipment     = $this->resolveModel(Equipment::class, $id);
+            [$type, $uuid] = $this->resolveMorph($request->attachable_type, $request->attachable);
+        } catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
+            return response()->json(['error' => 'Equipment or attachable resource not found.'], 404);
+        }
+        $equipment = DB::transaction(function () use ($equipment, $type, $uuid) {
+            $locked = Equipment::where('company_uuid', session('company'))->where('uuid', $equipment->uuid)->lockForUpdate()->firstOrFail();
+            if ($locked->equipable_type === $type && $locked->equipable_uuid === $uuid) {
+                return $locked;
+            }
+            $locked->update(['equipable_type' => $type, 'equipable_uuid' => $uuid]);
+            activity('equipment_attached')->performedOn($locked)->withProperties(['attachable_type' => $type, 'attachable_uuid' => $uuid])->log('Equipment attached');
+
+            return $locked;
+        });
+
+        return $this->equipmentResource($equipment->refresh()->load(['warranty', 'photo', 'equipable']));
+    }
+
+    public function detach(string $id)
+    {
+        try {
+            $equipment = $this->resolveModel(Equipment::class, $id);
+        } catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
+            return response()->json(['error' => 'Equipment resource not found.'], 404);
+        }
+        $equipment = DB::transaction(function () use ($equipment) {
+            $locked = Equipment::where('company_uuid', session('company'))->where('uuid', $equipment->uuid)->lockForUpdate()->firstOrFail();
+            if (!$locked->equipable_uuid) {
+                return $locked;
+            }
+            $previous = ['attachable_type' => $locked->equipable_type, 'attachable_uuid' => $locked->equipable_uuid];
+            $locked->update(['equipable_type' => null, 'equipable_uuid' => null]);
+            activity('equipment_detached')->performedOn($locked)->withProperties($previous)->log('Equipment detached');
+
+            return $locked;
+        });
+
+        return $this->equipmentResource($equipment->refresh()->load(['warranty', 'photo', 'equipable']));
+    }
+
     protected function input(Request $request): array
     {
         $input = $request->only([

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();
+    }
+}