@fleetbase/fleetops-engine 0.6.65 → 0.6.66

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

@@ -199,6 +199,73 @@ class TelematicController extends FleetOpsController
         ], 201);
     }
 
+    public function telemetryWebhook(Request $request, string $id): JsonResponse
+    {
+        $telematic = $this->findTelematic($id);
+        $provider  = $this->registry->resolve($telematic->provider);
+        abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
+        abort_unless($provider->supportsWebhooks(), 422);
+        $url = \Fleetbase\Support\Utils::apiUrl('webhooks/telematics/' . $telematic->provider);
+        abort_unless(str_starts_with($url, 'https://'), 422, 'Configure the public API URL with HTTPS before registering the webhook.');
+        $token = \Illuminate\Support\Facades\DB::transaction(function () use ($telematic, $request) {
+            // Serialize first-time provisioning as well as rotation.
+            Telematic::where('uuid', $telematic->uuid)->lockForUpdate()->firstOrFail();
+            $stored = \Illuminate\Support\Facades\DB::table('telematic_webhook_credentials')->where('telematic_uuid', $telematic->uuid)->first();
+            if ($stored && !$request->boolean('rotate')) {
+                return \Illuminate\Support\Facades\Crypt::decryptString($stored->token);
+            }
+            $token = bin2hex(random_bytes(32));
+            \Illuminate\Support\Facades\DB::table('telematic_webhook_credentials')->updateOrInsert(['telematic_uuid' => $telematic->uuid], [
+                'token' => \Illuminate\Support\Facades\Crypt::encryptString($token), 'created_at' => now(), 'updated_at' => now(),
+            ]);
+
+            return $token;
+        });
+
+        return response()->json(['url' => $url . '?' . http_build_query(['telematic' => $telematic->public_id, 'key' => $token])]);
+    }
+
+    public function telemetryDiagnostics(string $id): JsonResponse
+    {
+        $telematic = $this->findTelematic($id);
+        $provider  = $this->registry->resolve($telematic->provider);
+        abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
+        $options     = \Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration::options($provider);
+        $query       = \Illuminate\Support\Facades\DB::table('telematic_deliveries')->where('telematic_uuid', $telematic->uuid);
+        $last        = (clone $query)->where('source', 'webhook')->orderByDesc('received_at')->first(['uuid', 'status', 'received_at', 'processed_at', 'error']);
+        $provisioned = \Illuminate\Support\Facades\DB::table('telematic_webhook_credentials')->where('telematic_uuid', $telematic->uuid)->exists();
+        $state       = !$provisioned ? 'not_configured' : (!$last ? 'awaiting_first_delivery' : ($last->status === 'quarantined' || \Illuminate\Support\Carbon::parse($last->received_at)->lt(now()->subMinutes(10)) ? 'degraded' : 'receiving'));
+
+        return response()->json([
+            'polling_enabled'   => $options['polling_enabled'] ?? false,
+            'webhooks_enabled'  => $options['webhooks_enabled'] ?? false,
+            'webhook_state'     => $state, 'last_webhook' => $last,
+            'last_poll'         => \Illuminate\Support\Facades\DB::table('telematic_sync_runs')->where('telematic_uuid', $telematic->uuid)->orderByDesc('created_at')->first(),
+            'last_ingestion'    => (clone $query)->whereNotNull('processed_at')->orderByDesc('received_at')->first(['queue_delay_seconds', 'source_delay_seconds', 'processed_at']),
+            'delivery_counts'   => (clone $query)->whereIn('status', ['pending', 'retry', 'processing'])->selectRaw('status, count(*) as total')->groupBy('status')->pluck('total', 'status'),
+            'oldest_pending_at' => (clone $query)->whereIn('status', ['pending', 'retry', 'processing'])->min('received_at'),
+            'recent_failures'   => (clone $query)->whereIn('status', ['quarantined', 'retry'])->orderByDesc('received_at')->limit(10)->get(['uuid', 'status', 'source', 'received_at', 'applied', 'failed', 'error']),
+        ]);
+    }
+
+    public function replayTelemetryDelivery(string $id, string $delivery): JsonResponse
+    {
+        $telematic = $this->findTelematic($id);
+        $provider  = $this->registry->resolve($telematic->provider);
+        abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
+        $options = \Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration::options($provider);
+        $updated = \Illuminate\Support\Facades\DB::table('telematic_deliveries')->where('telematic_uuid', $telematic->uuid)->where('uuid', $delivery)->where('status', 'quarantined')
+            ->update(['status' => 'pending', 'attempts' => 0, 'retry_payload' => null, 'invalid_count' => 0, 'failed' => 0, 'applied' => 0, 'error' => null, 'available_at' => now(), 'processed_at' => null, 'updated_at' => now()]);
+        abort_unless($updated, 404);
+        try {
+            \Fleetbase\FleetOps\Support\Telematics\Telemetry\Queue::dispatch((new \Fleetbase\FleetOps\Jobs\ProcessTelematicDelivery($delivery))->onQueue($options['ingestion_queue'] ?? 'default'));
+        } catch (\Throwable) {
+            // The durable replay is recovered by the scheduled inbox drain.
+        }
+
+        return response()->json(['status' => 'queued'], 202);
+    }
+
     protected function findTelematic(string $id): Telematic
     {
         return Telematic::where(function ($query) use ($id) {

package/server/src/Http/Controllers/Public/PublicInspectionController.php

@@ -0,0 +1,243 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Public;
+
+use Fleetbase\FleetOps\Http\Resources\v1\InspectionForm as InspectionFormResource;
+use Fleetbase\FleetOps\Http\Resources\v1\InspectionSubmission as InspectionSubmissionResource;
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\FleetOps\Models\InspectionLink;
+use Fleetbase\FleetOps\Support\InspectionFileStore;
+use Fleetbase\FleetOps\Support\InspectionLinkPin;
+use Fleetbase\FleetOps\Support\InspectionSubmitter;
+use Fleetbase\Models\File;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\DB;
+
+class PublicInspectionController extends Controller
+{
+    /** The largest photo a link will take, in kilobytes: a phone camera's JPEG, with room. */
+    public const MAX_UPLOAD_KB = 10240;
+
+    /** How many files one link may upload, so a leaked link cannot fill the bucket. */
+    public const MAX_UPLOADS_PER_LINK = 40;
+
+    /** What a locked link says, wherever the lock is found. */
+    protected const LOCKED_MESSAGE = 'This link is locked after too many incorrect PINs. Ask whoever sent it for a new one.';
+
+    /** The extension each accepted image type is stored under. */
+    protected const EXTENSIONS = [
+        'image/jpeg' => 'jpg',
+        'image/png'  => 'png',
+        'image/webp' => 'webp',
+        'image/gif'  => 'gif',
+        'image/heic' => 'heic',
+        'image/heif' => 'heif',
+    ];
+
+    public function show(Request $request, string $id): JsonResponse
+    {
+        [$form, $link] = $this->resolvePublishedFormAndLink($request, $id);
+
+        $link->markViewed();
+
+        return response()->json([
+            'form'     => (new InspectionFormResource($form))->resolve(),
+            'identity' => $this->identityPayload($link),
+        ]);
+    }
+
+    public function submit(Request $request, string $id): JsonResponse
+    {
+        [$form, $link] = $this->resolvePublishedFormAndLink($request, $id);
+
+        $validated = $request->validate(InspectionSubmitter::rules());
+
+        // A link submits through its form's fields. The older flat checklist
+        // stores photo URLs exactly as given, which on a public link would let
+        // anyone put an arbitrary outside image on the record.
+        if (!empty($validated['item_results']) && empty($validated['custom_field_values'])) {
+            abort(response()->json(['error' => 'Submit this inspection through its form fields.'], 422));
+        }
+
+        // A single-use link is claimed before anything is written, inside the
+        // same transaction as the submission: a second submit at the same
+        // moment finds it already taken and writes nothing, and a submission
+        // that fails to save gives the link back.
+        $submission = DB::connection($link->getConnectionName())->transaction(function () use ($form, $link, $validated, $request) {
+            if ($link->single_use && !$link->claim($request->ip(), (string) $request->userAgent())) {
+                abort(response()->json(['error' => 'This inspection link has already been used.'], 409));
+            }
+
+            $submission = InspectionSubmitter::submit($form, $validated, [
+                'vehicle_uuid'      => $link->vehicle_uuid,
+                'driver_uuid'       => $link->driver_uuid,
+                // The person the link is for: its assignee, or the driver's
+                // account. What they typed as their name is kept beside it,
+                // with whether a PIN stood between the link and the form.
+                'submitted_by_uuid' => InspectionLinkPin::recipientFor($link)?->uuid,
+                'source'            => 'public_link',
+                'meta'              => [
+                    'inspection_link_uuid' => $link->uuid,
+                    'inspection_link_id'   => $link->public_id,
+                    'completed_by_name'    => data_get($validated, 'signature.name'),
+                    'pin_verified'         => $link->hasPin(),
+                ],
+            ]);
+
+            if (!$link->single_use) {
+                $link->markUsed($request->ip(), (string) $request->userAgent());
+            }
+
+            return $submission;
+        });
+
+        return response()->json([
+            'message'    => 'Inspection submitted.',
+            'submission' => (new InspectionSubmissionResource($submission->fresh(['form', 'vehicle', 'driver', 'itemResults', 'issue', 'workOrder'])))->resolve(),
+        ]);
+    }
+
+    /**
+     * Upload a photo or a signature through the link, before submitting.
+     *
+     * The console uploads through the platform's file endpoint, which needs a
+     * session; a link has none, so this is the link's own. It checks the link
+     * exactly as submitting does, takes images only, caps how many one link
+     * may send, and tags each file with the link it came through — a
+     * submission through a link may only reference files uploaded through
+     * that same link.
+     */
+    public function upload(Request $request, string $id): JsonResponse
+    {
+        [, $link] = $this->resolvePublishedFormAndLink($request, $id);
+
+        $request->validate([
+            'file' => 'required|file|mimetypes:image/jpeg,image/png,image/webp,image/gif,image/heic,image/heif|max:' . static::MAX_UPLOAD_KB,
+            'type' => 'nullable|in:' . InspectionFileStore::TYPE_PHOTO . ',' . InspectionFileStore::TYPE_SIGNATURE,
+        ]);
+
+        $already = File::query()
+            ->where('company_uuid', $link->company_uuid)
+            ->where('meta->inspection_link_uuid', $link->uuid)
+            ->count();
+
+        if ($already >= static::MAX_UPLOADS_PER_LINK) {
+            abort(response()->json(['error' => 'This inspection link has reached its upload limit.'], 422));
+        }
+
+        $upload = $request->file('file');
+        $disk   = config('filesystems.default');
+        $bucket = config('filesystems.disks.' . $disk . '.bucket', config('filesystems.disks.s3.bucket'));
+        // The stored name's extension comes from the type the server found in
+        // the bytes, never from the name the device sent. Validation checks the
+        // content, so an image that is also valid PHP, uploaded as `photo.php`,
+        // would pass it — and stored under that extension on a web-served local
+        // disk, it would be an invitation to run it.
+        $extension = static::EXTENSIONS[$upload->getMimeType()] ?? 'jpg';
+        $stored    = $upload->storeAs('inspections/links/' . $link->uuid, File::randomFileNameFromRequest($request, 'file', $extension), ['disk' => $disk]);
+
+        if ($stored === false) {
+            abort(response()->json(['error' => 'This photo could not be stored.'], 500));
+        }
+
+        // Built here rather than through File::createFromUpload(), which takes
+        // the company and uploader from the session — and a link has none.
+        // The type comes from the bytes the server received, not from the
+        // name the device gave the file.
+        $file = File::create([
+            'company_uuid'      => $link->company_uuid,
+            'uploader_uuid'     => InspectionLinkPin::recipientFor($link)?->uuid,
+            'original_filename' => $upload->getClientOriginalName(),
+            'content_type'      => $upload->getMimeType(),
+            'disk'              => $disk,
+            'path'              => $stored,
+            'bucket'            => $bucket,
+            'type'              => $request->input('type', InspectionFileStore::TYPE_PHOTO),
+            'file_size'         => $upload->getSize(),
+            'meta'              => ['inspection_link_uuid' => $link->uuid],
+        ]);
+
+        return response()->json([
+            'file' => [
+                'id'           => $file->public_id,
+                'url'          => $file->url,
+                'filename'     => $file->original_filename,
+                'content_type' => $file->content_type,
+            ],
+        ]);
+    }
+
+    protected function resolvePublishedFormAndLink(Request $request, string $id): array
+    {
+        $token = (string) $request->query('token', $request->input('token'));
+        if (empty($token)) {
+            abort(response()->json(['error' => 'Inspection token is required.'], 403));
+        }
+
+        $form = InspectionForm::where('uuid', $id)
+            ->orWhere('public_id', $id)
+            ->firstOrFail();
+
+        if (!$form->is_published) {
+            abort(response()->json(['error' => 'This inspection form is not available.'], 403));
+        }
+
+        $link = InspectionLink::where('inspection_form_uuid', $form->uuid)
+            ->where('token_hash', InspectionLink::hashToken($token))
+            ->first();
+
+        if (!$link) {
+            abort(response()->json(['error' => 'Inspection link is invalid.'], 403));
+        }
+
+        if ($link->status === 'locked') {
+            abort(response()->json(['error' => static::LOCKED_MESSAGE, 'locked' => true], 403));
+        }
+
+        if (!$link->isUsable()) {
+            abort(response()->json(['error' => 'Inspection link is expired, revoked, or already used.'], 403));
+        }
+
+        // A link with a PIN answers nothing, not even the form's name, until
+        // the PIN is given. Wrong guesses count against the link and lock it.
+        // Every refusal here is a 403, so the page handles them all one way.
+        // The page sends it as a header, so it stays out of URLs and the
+        // access logs that record them; a `pin` field is accepted as well.
+        switch ($link->verifyPin($request->header('X-Inspection-Pin') ?: $request->input('pin'))) {
+            case 'missing':
+                abort(response()->json(['error' => 'Enter the PIN you were given with this link.', 'pin_required' => true], 403));
+                // no break
+            case 'wrong':
+                abort(response()->json(['error' => 'That PIN is not right.', 'pin_required' => true, 'attempts_left' => $link->pinAttemptsLeft()], 403));
+                // no break
+            case 'locked':
+                abort(response()->json(['error' => static::LOCKED_MESSAGE, 'locked' => true], 403));
+        }
+
+        return [$form, $link];
+    }
+
+    protected function identityPayload(InspectionLink $link): array
+    {
+        return [
+            'assignee' => $link->assignee ? [
+                'id'   => $link->assignee->public_id,
+                'name' => $link->assignee->name,
+            ] : null,
+            // Name, not phone number: whoever holds the link needs to know who
+            // it is for, not how to reach them.
+            'driver' => $link->driver ? [
+                'id'   => $link->driver->public_id,
+                'name' => $link->driver->name,
+            ] : null,
+            'vehicle' => $link->vehicle ? [
+                'id'           => $link->vehicle->public_id,
+                'name'         => $link->vehicle->display_name ?? $link->vehicle->name,
+                'plate_number' => $link->vehicle->plate_number,
+            ] : null,
+            'expires_at' => $link->expires_at,
+        ];
+    }
+}

package/server/src/Http/Controllers/TelematicPositionWebhookController.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers;
+
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\DB;
+
+class TelematicPositionWebhookController extends Controller
+{
+    public function handle(Request $request, Inbox $inbox, string $providerKey): JsonResponse
+    {
+        if (!$request->isMethod('post')) {
+            return response()->json(['error' => 'POST required.'], 405);
+        }
+        $id    = $request->query('telematic');
+        $token = $request->query('key');
+        if (!is_string($id) || !is_string($token)) {
+            return response()->json(['error' => 'Invalid webhook credentials.'], 403);
+        }
+        $telematic = Telematic::withoutGlobalScopes()->where('provider', $providerKey)->where('public_id', $id)->first();
+        $stored    = $telematic ? DB::table('telematic_webhook_credentials')->where('telematic_uuid', $telematic->uuid)->value('token') : null;
+        if (!$stored || !hash_equals(Crypt::decryptString($stored), $token) || !Inbox::enabled($telematic)) {
+            return response()->json(['error' => 'Invalid webhook credentials.'], 403);
+        }
+        $options = Configuration::forConnection($telematic);
+        if (!($options['webhooks_enabled'] ?? false)) {
+            return response()->json(['error' => 'Webhook processing is disabled.'], 503);
+        }
+        $body = $request->getContent();
+        if (strlen($body) > ($options['max_payload_bytes'] ?? 2097152)) {
+            return response()->json(['error' => 'Payload too large.'], 413);
+        }
+        try {
+            $payload = json_decode($body, true, 64, JSON_THROW_ON_ERROR);
+            if (!is_array($payload)) {
+                throw new \InvalidArgumentException();
+            }
+        } catch (\Throwable) {
+            return response()->json(['error' => 'JSON object or array required.'], 422);
+        }
+        try {
+            // Per-connection pressure protection; The provider can retry after capacity recovers.
+            $pending = DB::table('telematic_deliveries')->where('telematic_uuid', $telematic->uuid)->whereIn('status', ['pending', 'processing', 'retry'])->count();
+            if ($pending >= ($options['max_pending_deliveries'] ?? 10000)) {
+                return response()->json(['error' => 'Ingestion capacity exceeded.'], 503);
+            }
+            $delivery = $inbox->accept($telematic, $payload, 'webhook');
+
+            return response()->json(['status' => 'accepted', 'delivery_id' => $delivery], 200);
+        } catch (\Throwable) {
+            return response()->json(['error' => 'Unable to persist delivery; retry required.'], 503);
+        }
+    }
+}

package/server/src/Http/Controllers/TelematicWebhookController.php

@@ -38,6 +38,9 @@ class TelematicWebhookController extends Controller
      */
     public function handle(Request $request, string $providerKey): JsonResponse
     {
+        if ($this->registry->resolve($providerKey) instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface) {
+            return app(TelematicPositionWebhookController::class)->handle($request, app(\Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox::class), $providerKey);
+        }
         $correlationId = Str::uuid()->toString();
 
         Log::info('Webhook received', [

package/server/src/Http/Filter/FuelProviderConnectionFilter.php

@@ -23,7 +23,7 @@ class FuelProviderConnectionFilter extends Filter
 
     public function status(?string $status)
     {
-        $this->builder->where('status', $status);
+        $this->builder->whereIn('status', explode(',', $status ?? ''));
     }
 
     public function environment(?string $environment)

package/server/src/Http/Middleware/ForceJsonResponse.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Middleware;
+
+use Illuminate\Http\Request;
+
+/**
+ * Makes a route answer in JSON whatever the client's Accept header says.
+ *
+ * Laravel decides how to answer a failed validation from `expectsJson()`: a
+ * request that does not ask for JSON is redirected back to the page it came
+ * from with its errors flashed to a session. The public inspection page has
+ * no session and cannot follow that redirect, and the platform's fetch
+ * service sends `Accept: *\/*`, so a refused submission reached the page as a
+ * bare 302 with its reasons lost.
+ */
+class ForceJsonResponse
+{
+    public function handle(Request $request, \Closure $next)
+    {
+        $request->headers->set('Accept', 'application/json');
+
+        return $next($request);
+    }
+}

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

@@ -0,0 +1,153 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionFormSync;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Models\Category;
+use Fleetbase\Models\CustomField;
+use Fleetbase\Support\Http;
+use Illuminate\Support\Str;
+
+class InspectionForm extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $internal = Http::isInternalRequest();
+
+        return $this->withCustomFields([
+            'id'             => $this->when($internal, $this->id, $this->public_id),
+            'uuid'           => $this->when($internal, $this->uuid),
+            'public_id'      => $this->when($internal, $this->public_id),
+            'company_uuid'   => $this->when($internal, $this->company_uuid),
+            'created_by_uuid'=> $this->when($internal, $this->created_by_uuid),
+            'updated_by_uuid'=> $this->when($internal, $this->updated_by_uuid),
+            'subject_uuid'   => $this->when($internal, $this->subject_uuid),
+            'subject_type'   => $this->when($internal, $this->subject_type ? Utils::toEmberResourceType($this->subject_type) : null),
+            'subject'        => $this->whenLoaded('subject', fn () => $this->setSubjectType($this->transformMorphResource($this->subject))),
+            'name'           => $this->name,
+            'description'    => $this->description,
+            'type'           => $this->type,
+            'status'         => $this->status,
+            'items'          => data_get($this, 'items', []),
+            'grouped_fields' => array_map(fn (Category $group) => static::groupToArray($group, $internal), $this->grouped_fields),
+            'field_groups'   => $this->whenLoaded('fieldGroups', fn () => $this->fieldGroups->map(fn (Category $group) => static::groupToArray($group, $internal, false))->values()->all()),
+            'fields'         => $this->whenLoaded('fields', fn () => $this->fields->map(fn (CustomField $field) => static::fieldToArray($field, $internal))->values()->all()),
+            'settings'       => data_get($this, 'settings', (object) []),
+            'meta'           => data_get($this, 'meta', (object) []),
+            'subject_name'   => $this->subject_name,
+            'item_count'     => $this->item_count,
+            'is_published'   => $this->is_published,
+            'published_at'   => $this->published_at,
+            'updated_at'     => $this->updated_at,
+            'created_at'     => $this->created_at,
+        ]);
+    }
+
+    /**
+     * A field group as the API answers it. The console gets the identifiers it
+     * addresses the category by; the driver gets what it renders.
+     */
+    public static function groupToArray(Category $group, bool $internal, bool $withFields = true): array
+    {
+        $data = [
+            'id'          => $internal ? $group->uuid : ($group->public_id ?? $group->uuid),
+            'uuid'        => $group->uuid,
+            'name'        => $group->name,
+            'description' => $group->description,
+            'order'       => $group->order === null ? null : (int) $group->order,
+            'meta'        => is_array($group->meta) && !empty($group->meta) ? $group->meta : (object) [],
+        ];
+
+        if ($internal) {
+            $data['public_id']    = $group->public_id;
+            $data['company_uuid'] = $group->company_uuid;
+            $data['owner_uuid']   = $group->owner_uuid;
+            $data['owner_type']   = $group->owner_type;
+            $data['for']          = $group->for;
+        }
+
+        if ($withFields) {
+            $fields         = $group->relationLoaded('fields') ? $group->getRelation('fields') : collect();
+            $data['fields'] = collect($fields)->map(fn (CustomField $field) => static::fieldToArray($field, $internal))->values()->all();
+        }
+
+        return $data;
+    }
+
+    /**
+     * A field as the API answers it.
+     *
+     * The id a consumer sees here is the id a submit names the field by, and
+     * the id that comes back on the submission's answers — the three have to
+     * agree, so this follows the groups above: the public id outside, the uuid
+     * on the console's own namespace.
+     */
+    public static function fieldToArray(CustomField $field, bool $internal): array
+    {
+        $data = [
+            'id'          => $internal ? $field->uuid : ($field->public_id ?? $field->uuid),
+            'name'        => $field->name,
+            'label'       => $field->label,
+            'description' => $field->description,
+            'help_text'   => $field->help_text,
+            'type'        => $field->type,
+            // A field written straight into the table — by a seed, or by an
+            // older builder — may carry no component. The type names its own.
+            'component'   => $field->component ?: InspectionFormSync::componentFor((string) $field->type),
+            'required'    => (bool) $field->required,
+            'editable'    => $field->editable === null ? true : (bool) $field->editable,
+            'options'     => is_array($field->options) ? array_values($field->options) : [],
+            'order'       => $field->order === null ? null : (int) $field->order,
+            'meta'        => is_array($field->meta) && !empty($field->meta) ? $field->meta : (object) [],
+        ];
+
+        if ($internal) {
+            $data['uuid']             = $field->uuid;
+            $data['company_uuid']     = $field->company_uuid;
+            $data['category_uuid']    = $field->category_uuid;
+            $data['subject_uuid']     = $field->subject_uuid;
+            $data['subject_type']     = $field->subject_type;
+            $data['for']              = $field->for;
+            $data['default_value']    = $field->default_value;
+            $data['validation_rules'] = $field->validation_rules;
+        }
+
+        return $data;
+    }
+
+    protected function setSubjectType(?array $resolved): ?array
+    {
+        if (empty($resolved)) {
+            return $resolved;
+        }
+
+        $bareSlug = Str::kebab(class_basename($this->subject_type ?? ''));
+
+        data_set($resolved, 'type', 'maintenance-subject-' . $bareSlug);
+        data_set($resolved, 'subject_type', 'maintenance-subject-' . $bareSlug);
+
+        return $resolved;
+    }
+
+    protected function transformMorphResource($model): ?array
+    {
+        if (!$model) {
+            return null;
+        }
+
+        // Always answers: a model with no resource of its own is served by the
+        // base FleetbaseResource, so there is no second fallback to keep here.
+        $resourceClass = \Fleetbase\Support\Find::httpResourceForModel($model);
+
+        return (new $resourceClass($model))->resolve();
+    }
+}

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

@@ -0,0 +1,77 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionFileStore;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Support\Http;
+
+class InspectionItemResult extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        return [
+            'id'                         => $this->when(Http::isInternalRequest(), $this->id, $this->uuid),
+            'uuid'                       => $this->when(Http::isInternalRequest(), $this->uuid),
+            'company_uuid'               => $this->when(Http::isInternalRequest(), $this->company_uuid),
+            'inspection_submission_uuid' => $this->when(Http::isInternalRequest(), $this->inspection_submission_uuid),
+            'issue_uuid'                 => $this->when(Http::isInternalRequest(), $this->issue_uuid),
+            'work_order_uuid'            => $this->when(Http::isInternalRequest(), $this->work_order_uuid),
+            'item_key'                   => $this->item_key,
+            'label'                      => $this->label,
+            'category'                   => $this->category,
+            'status'                     => $this->status,
+            'severity'                   => $this->severity,
+            'passed'                     => $this->passed,
+            'comments'                   => $this->comments,
+            'photos'                     => $this->projectPhotos(),
+            'meta'                       => $this->projectMeta(),
+            'submission_id'              => $this->submission_id,
+            'updated_at'                 => $this->updated_at,
+            'created_at'                 => $this->created_at,
+        ];
+    }
+
+    /**
+     * `custom_field_uuid` links a result back to the field it mirrors, which is
+     * the console's business. Outside, `item_key` already names the field, so
+     * the uuid is not something a consumer should have to see.
+     */
+    /**
+     * A result's photos are stored as `file:<uuid>` references, the same as the
+     * answer they mirror — and the answer hands back something fetchable, so
+     * this does too rather than leaking the uuid. A flat `item_results` submit
+     * stores no file, and `project()` hands those values straight back.
+     */
+    protected function projectPhotos(): array
+    {
+        $photos = data_get($this, 'photos', []);
+        if (!is_array($photos) || empty($photos)) {
+            return [];
+        }
+
+        return array_values(array_map(fn ($photo) => InspectionFileStore::project($photo), $photos));
+    }
+
+    protected function projectMeta(): mixed
+    {
+        $meta = data_get($this, 'meta');
+        if (!is_array($meta) || empty($meta)) {
+            return Utils::createObject();
+        }
+
+        if (!Http::isInternalRequest()) {
+            unset($meta['custom_field_uuid']);
+        }
+
+        return empty($meta) ? Utils::createObject() : $meta;
+    }
+}