@fleetbase/fleetops-engine 0.6.65 → 0.6.66

package/server/src/Support/FuelProviders/FuelProviderService.php

@@ -87,14 +87,14 @@ class FuelProviderService
 
     public function syncTransactions(FuelProviderConnection $connection, ?Carbon $from = null, ?Carbon $to = null, array $options = [], ?FuelProviderSyncRun $syncRun = null): array
     {
-        $settings = (array) $connection->sync_settings;
-        $from ??= Carbon::parse(data_get($settings, 'from', $connection->last_synced_at?->copy()->subDay() ?? now()->subDays((int) data_get($settings, 'window_days', 7))));
-        $to ??= Carbon::parse(data_get($settings, 'to', now()));
+        [$from, $to] = $this->syncWindow($connection, $from ?? $syncRun?->from, $to ?? $syncRun?->to);
 
         $syncRun ??= $this->createSyncRun($connection, $from, $to, 'running');
-        $syncRun->update(['status' => 'running', 'started_at' => now(), 'error' => null]);
+        $syncRun->update(['status' => 'running', 'from' => $from, 'to' => $to, 'started_at' => now(), 'error' => null]);
 
         $summary = [
+            'received'             => 0,
+            'updated'              => 0,
             'imported'             => 0,
             'matched'              => 0,
             'unmatched'            => 0,
@@ -109,22 +109,23 @@ class FuelProviderService
 
             foreach ($payloads as $payload) {
                 $transaction = $this->ingestTransaction($connection, $payload);
-                $summary['imported']++;
+                $summary['received']++;
+                $summary[$transaction->wasRecentlyCreated ? 'imported' : 'updated']++;
                 $summary['liters'] += (float) $transaction->volume;
                 $summary['amount'] += (int) $transaction->amount;
 
                 if ($transaction->sync_status === 'matched') {
                     $summary['matched']++;
-                } else {
+                } elseif ($transaction->sync_status === 'unmatched') {
                     $summary['unmatched']++;
                 }
 
-                if ($transaction->fuel_report_uuid) {
+                if ($transaction->fuel_report_uuid && $transaction->createdFuelReport) {
                     $summary['fuel_reports_created']++;
                 }
             }
         } catch (\Throwable $e) {
-            $syncRun->update(['status' => 'error', 'finished_at' => now(), 'error' => $e->getMessage(), 'summary' => $summary]);
+            $syncRun->update(array_merge(collect($summary)->only(['imported', 'matched', 'unmatched', 'fuel_reports_created', 'liters', 'amount'])->all(), ['status' => 'error', 'finished_at' => now(), 'error' => $e->getMessage(), 'summary' => $summary]));
             $connection->update(['status' => 'error', 'last_error' => $e->getMessage()]);
             throw $e;
         }
@@ -158,6 +159,8 @@ class FuelProviderService
 
     public function createSyncRun(FuelProviderConnection $connection, ?Carbon $from = null, ?Carbon $to = null, string $status = 'queued'): FuelProviderSyncRun
     {
+        [$from, $to] = $this->syncWindow($connection, $from, $to);
+
         return FuelProviderSyncRun::create([
             'company_uuid'                   => $connection->company_uuid,
             'fuel_provider_connection_uuid'  => $connection->uuid,
@@ -168,29 +171,42 @@ class FuelProviderService
         ]);
     }
 
+    public function syncWindow(FuelProviderConnection $connection, ?Carbon $from = null, ?Carbon $to = null): array
+    {
+        $settings = (array) $connection->sync_settings;
+        $from ??= Carbon::parse(data_get($settings, 'from') ?: now()->subDays(max(1, (int) data_get($settings, 'window_days', 7))))->startOfDay();
+        $to ??= Carbon::parse(data_get($settings, 'to') ?: now())->endOfDay();
+        if ($from->gt($to)) {
+            throw new \InvalidArgumentException('The sync start date must be on or before the end date.');
+        }
+
+        return [$from, $to];
+    }
+
     public function ingestTransaction(FuelProviderConnection $connection, array $payload): FuelProviderTransaction
     {
         return DB::transaction(function () use ($connection, $payload) {
             $provider              = $payload['provider'] ?? $connection->provider;
             $providerTransactionId = $payload['provider_transaction_id'];
-            // The match must include company_uuid. Provider transaction ids are only
-            // unique within the account they were issued for, so keying on
-            // (provider, provider_transaction_id) alone let one company's sync find
-            // and overwrite another company's transaction — reassigning its
-            // company_uuid. Mirrors fuel_provider_txn_company_provider_unique.
+            // Provider IDs are scoped to the connected account/environment.
             $transaction           = FuelProviderTransaction::updateOrCreate(
                 [
-                    'company_uuid'            => $connection->company_uuid,
-                    'provider'                => $provider,
-                    'provider_transaction_id' => $providerTransactionId,
+                    'company_uuid'                  => $connection->company_uuid,
+                    'fuel_provider_connection_uuid' => $connection->uuid,
+                    'provider'                      => $provider,
+                    'provider_transaction_id'       => $providerTransactionId,
                 ],
                 array_merge($payload, [
                     'company_uuid'                  => $connection->company_uuid,
                     'fuel_provider_connection_uuid' => $connection->uuid,
-                    'sync_status'                   => 'imported',
                 ])
             );
 
+            $created   = $transaction->wasRecentlyCreated;
+            $hadReport = (bool) $transaction->fuel_report_uuid;
+            if (!$created && in_array($transaction->sync_status, ['reviewed', 'ignored'], true)) {
+                return $transaction;
+            }
             event(new FuelProviderTransactionImported($transaction));
 
             $this->matchTransaction($transaction, $connection);
@@ -211,7 +227,11 @@ class FuelProviderService
                 event(new FuelProviderTransactionUnmatched($transaction));
             }
 
-            return $transaction->fresh(['vehicle', 'driver', 'fuelReport']);
+            $result                     = $transaction->fresh(['vehicle', 'driver', 'fuelReport']);
+            $result->wasRecentlyCreated = $created;
+            $result->createdFuelReport  = !$hadReport && (bool) $result->fuel_report_uuid;
+
+            return $result;
         });
     }
 
@@ -228,7 +248,9 @@ class FuelProviderService
         $transaction->sync_status  = 'matched';
         $transaction->matched_at ??= now();
         $transaction->save();
-        $this->ensureFuelReport($transaction);
+        if (!$transaction->connection || $this->shouldCreateFuelReport($transaction->connection)) {
+            $this->ensureFuelReport($transaction);
+        }
 
         event(new FuelProviderTransactionMatched($transaction));
 
@@ -257,7 +279,9 @@ class FuelProviderService
 
         $this->matchTransaction($transaction, $transaction->connection);
         if ($transaction->vehicle_uuid) {
-            $this->ensureFuelReport($transaction);
+            if (!$transaction->connection || $this->shouldCreateFuelReport($transaction->connection)) {
+                $this->ensureFuelReport($transaction);
+            }
             $transaction->sync_status = 'matched';
             $transaction->matched_at ??= now();
             event(new FuelProviderTransactionMatched($transaction));
@@ -313,7 +337,11 @@ class FuelProviderService
 
     protected function matchingOrder(?FuelProviderConnection $connection = null): Collection
     {
-        $configuredFields = collect(data_get((array) $connection?->sync_settings, 'matching_order', []))->filter()->values();
+        $settings = (array) $connection?->sync_settings;
+        if (array_key_exists('matching_order', $settings) && $settings['matching_order'] === []) {
+            return collect();
+        }
+        $configuredFields = collect(data_get($settings, 'matching_order', []))->filter()->values();
 
         if ($configuredFields->all() === self::LEGACY_DEFAULT_MATCHING_ORDER) {
             return collect(self::DEFAULT_MATCHING_ORDER);
@@ -334,14 +362,16 @@ class FuelProviderService
 
     protected function resolveOrder(FuelProviderTransaction $transaction): ?Order
     {
-        return Order::where('company_uuid', $transaction->company_uuid)
+        $matches = Order::where('company_uuid', $transaction->company_uuid)
             ->where(function ($query) use ($transaction) {
                 $query->where('public_id', $transaction->trip_number)
                     ->orWhere('internal_id', $transaction->trip_number)
                     ->orWhereHas('trackingNumber', function ($trackingNumberQuery) use ($transaction) {
                         $trackingNumberQuery->where('tracking_number', $transaction->trip_number);
                     });
-            })->first();
+            })->limit(2)->get();
+
+        return $matches->count() === 1 ? $matches->first() : null;
     }
 
     protected function resolveVehicle(FuelProviderTransaction $transaction, string $field): ?Vehicle
@@ -373,14 +403,16 @@ class FuelProviderService
 
         $normalized = $this->normalizeIdentifier($identifier);
 
-        return Vehicle::where('company_uuid', $transaction->company_uuid)
+        $matches = Vehicle::where('company_uuid', $transaction->company_uuid)
             ->where(function ($query) use ($identifier, $normalized, $vehicleFields) {
                 foreach ($vehicleFields as $vehicleField) {
                     $query->orWhere($vehicleField, $identifier)
                         ->orWhereRaw("REPLACE(REPLACE(UPPER({$vehicleField}), ' ', ''), '-', '') = ?", [$normalized]);
                 }
             })
-            ->first();
+            ->limit(2)->get();
+
+        return $matches->count() === 1 ? $matches->first() : null;
     }
 
     protected function resolveVehicleByProviderId(FuelProviderTransaction $transaction): ?Vehicle
@@ -389,12 +421,14 @@ class FuelProviderService
             return null;
         }
 
-        return Vehicle::where('company_uuid', $transaction->company_uuid)
+        $matches = Vehicle::where('company_uuid', $transaction->company_uuid)
             ->where(function ($query) use ($transaction) {
                 $query->where('meta->fuel_provider_vehicle_id', $transaction->provider_vehicle_id)
                     ->orWhere("meta->fuel_provider_ids->{$transaction->provider}", $transaction->provider_vehicle_id);
             })
-            ->first();
+            ->limit(2)->get();
+
+        return $matches->count() === 1 ? $matches->first() : null;
     }
 
     protected function normalizeMatchingField(string $field): string
@@ -433,12 +467,15 @@ class FuelProviderService
                 'source'                         => 'fuel_provider',
                 'provider'                       => $transaction->provider,
                 'fuel_provider_transaction_uuid' => $transaction->uuid,
+                'fuel_provider_connection_uuid'  => $transaction->fuel_provider_connection_uuid,
+                'transaction_at'                 => $transaction->transaction_at?->toIso8601String(),
                 'station_name'                   => $transaction->station_name,
                 'trip_number'                    => $transaction->trip_number,
             ],
         ]);
 
         $transaction->fuel_report_uuid = $fuelReport->uuid;
+        $transaction->save();
         event(new FuelReportCreatedFromProvider($transaction, $fuelReport));
 
         return $fuelReport;

package/server/src/Support/FuelProviders/Providers/PetroAppFuelProvider.php

@@ -3,11 +3,17 @@
 namespace Fleetbase\FleetOps\Support\FuelProviders\Providers;
 
 use Fleetbase\FleetOps\Models\FuelProviderConnection;
+use Illuminate\Http\Client\Response;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Collection;
 
 class PetroAppFuelProvider extends AbstractFuelProvider
 {
+    public const BASE_URLS = [
+        'sandbox'    => 'https://app-public.staging.petroapp.app/webservice',
+        'production' => 'https://app.petroapp.com.sa/webservice',
+    ];
+
     public function key(): string
     {
         return 'petroapp';
@@ -21,22 +27,28 @@ class PetroAppFuelProvider extends AbstractFuelProvider
     public function testConnection(FuelProviderConnection $connection): array
     {
         try {
-            $response = $this->client($connection)->get('vehicles', ['page' => 1]);
+            [$response, $authType] = $this->getResponse($connection, 'vehicles', ['page' => 1]);
+            $metadata              = [
+                'environment' => $connection->environment ?? 'production',
+                'host'        => parse_url($this->baseUrl($connection), PHP_URL_HOST),
+                'auth_type'   => $authType,
+                'status'      => $response->status(),
+            ];
 
-            if (!$response->successful()) {
+            if (!$this->successfulResponse($response) || !is_array($response->json('data.data'))) {
                 return [
                     'success'  => false,
                     'message'  => $response->json('message') ?? 'Unable to connect to PetroApp.',
-                    'metadata' => ['status' => $response->status()],
+                    'metadata' => $metadata,
                 ];
             }
 
             return [
                 'success'  => true,
                 'message'  => 'PetroApp connection successful.',
-                'metadata' => [
-                    'total_vehicles' => $response->json('data.total'),
-                ],
+                'metadata' => array_merge($metadata, [
+                    'total_vehicles' => $response->json('data.total') ?? $response->json('data.meta.total'),
+                ]),
             ];
         } catch (\Throwable $e) {
             return ['success' => false, 'message' => $e->getMessage(), 'metadata' => []];
@@ -69,13 +81,15 @@ class PetroAppFuelProvider extends AbstractFuelProvider
     {
         $credentials = (array) $connection->credentials;
 
-        return rtrim(data_get($credentials, 'base_url', 'https://app-public.staging.petroapp.app/webservice'), '/');
+        $override = trim((string) data_get($credentials, 'base_url', ''));
+
+        return rtrim($override ?: self::BASE_URLS[$connection->environment ?? 'production'], '/');
     }
 
     protected function headers(FuelProviderConnection $connection): array
     {
         $credentials = (array) $connection->credentials;
-        $token       = data_get($credentials, 'api_token') ?? data_get($credentials, 'api_key');
+        $token       = trim((string) (data_get($credentials, 'api_token') ?? data_get($credentials, 'api_key')));
 
         if (data_get($credentials, 'auth_type') === 'ws_sk_header') {
             return [
@@ -99,28 +113,80 @@ class PetroAppFuelProvider extends AbstractFuelProvider
         $items = collect();
 
         do {
-            $response = $this->client($connection)->get($endpoint, array_merge($params, ['page' => $page]));
+            [$response] = $this->getResponse($connection, $endpoint, array_merge($params, ['page' => $page]));
 
-            if (!$response->successful()) {
+            if (!$this->successfulResponse($response)) {
                 throw new \RuntimeException($response->json('message') ?? "PetroApp {$endpoint} request failed.");
             }
 
             $payload = $response->json();
-            $data    = $dataKey ? data_get($payload, $dataKey, []) : data_get($payload, 'data.data', []);
+            $data    = $dataKey ? data_get($payload, $dataKey) : data_get($payload, 'data.data');
+            if (!is_array($data)) {
+                throw new \RuntimeException("PetroApp {$endpoint} returned an invalid response.");
+            }
             $items   = $items->merge($data);
 
-            $lastPage = (int) data_get($payload, 'data.last_page', $page);
-            $hasMore  = data_get($payload, 'data.next_page_url') || $page < $lastPage;
+            $lastPage = (int) data_get($payload, 'data.last_page', data_get($payload, 'data.meta.last_page', $page));
+            $hasMore  = data_get($payload, 'data.next_page_url') || data_get($payload, 'data.links.next') || $page < $lastPage;
             $page++;
         } while ($hasMore && $page <= $maxPages);
 
+        if ($hasMore) {
+            throw new \RuntimeException('PetroApp returned more pages than the sync limit. Choose a shorter date range and retry; the import was not marked complete.');
+        }
+
         return $items;
     }
 
+    protected function getResponse(FuelProviderConnection $connection, string $endpoint, array $params): array
+    {
+        $credentials = (array) $connection->credentials;
+        $authType    = data_get($credentials, 'auth_type') ?: 'bearer_token';
+        $response    = $this->client($connection)->get($endpoint, $params);
+
+        // Older forms supplied only api_token. Preserve working Bearer tokens,
+        // but support WS-SK tokens when PetroApp explicitly requests a secret key.
+        if (blank(data_get($credentials, 'auth_type')) && $response->json('message') === 'Secret key is not found') {
+            $retryConnection              = clone $connection;
+            $retryConnection->credentials = array_merge($credentials, ['auth_type' => 'ws_sk_header']);
+            $response                     = $this->client($retryConnection)->get($endpoint, $params);
+            $authType                     = 'ws_sk_header';
+        }
+
+        return [$response, $authType];
+    }
+
+    protected function successfulResponse(Response $response): bool
+    {
+        $payload = $response->json();
+        if (!$response->successful() || !is_array($payload)) {
+            return false;
+        }
+
+        foreach (['success', 'status'] as $key) {
+            if (array_key_exists($key, $payload) && in_array($payload[$key], [false, 0, '0', 'false', 'error'], true)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    protected function billPlate(array $bill): ?string
+    {
+        $number  = $this->compactIdentifier($bill['plate_snum'] ?? null);
+        $letters = $this->compactIdentifier($bill['plate_letter'] ?? null);
+        if (!$letters || !$number || str_contains($number, $letters)) {
+            return $number;
+        }
+
+        return $this->compactIdentifier($letters . ' ' . $number);
+    }
+
     protected function normalizeBill(array $bill): array
     {
         $transactionAt = $this->dateFrom($bill['bill_date'] ?? $bill['billDate'] ?? null);
-        $providerId    = $bill['id'] ?? $bill['bill_id'] ?? null;
+        $providerId    = $bill['id'] ?? $bill['bill_id'] ?? $bill['bill_number'] ?? null;
         $fallbackId    = $this->transactionHash([
             $bill['bill_date'] ?? $bill['billDate'] ?? null,
             $bill['trip_number'] ?? null,
@@ -139,7 +205,7 @@ class PetroAppFuelProvider extends AbstractFuelProvider
             'vehicle_card_id'         => $this->compactIdentifier($bill['vehicle_card_id'] ?? $bill['fuel_card_number'] ?? $bill['card_number'] ?? null),
             'internal_number'         => $this->compactIdentifier($bill['internal_number'] ?? null),
             'structure_number'        => $this->compactIdentifier($bill['structure_number'] ?? null),
-            'plate_number'            => $this->compactIdentifier($bill['plate_snum'] ?? null),
+            'plate_number'            => $this->billPlate($bill),
             'vin'                     => $this->compactIdentifier($bill['vin'] ?? $bill['vin_number'] ?? null),
             'serial_number'           => $this->compactIdentifier($bill['serial_number'] ?? null),
             'call_sign'               => $this->compactIdentifier($bill['call_sign'] ?? null),

package/server/src/Support/InspectionFileStore.php

@@ -0,0 +1,268 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\InspectionSubmission;
+use Fleetbase\Models\File;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Turns what a driver sends for a photo or a signature into a platform file.
+ *
+ * The app is offline-first: it cannot upload a photo and then reference it,
+ * so a photo arrives inside the submit body as base64. The platform's own
+ * convention for a file held in a custom-field value is `file:<uuid>`, which
+ * is what every value leaves here as — a URL, or a reference to a file that
+ * already exists, is kept as it came.
+ *
+ * A reference is only ever kept for a file the submission may use: one that
+ * belongs to the submission's own company. A submission through a public
+ * link may go further than that only in one direction — it may reference
+ * nothing but files uploaded through that same link, and it may not use an
+ * outside URL as a photo at all.
+ */
+class InspectionFileStore
+{
+    public const TYPE_PHOTO     = 'inspection_photo';
+    public const TYPE_SIGNATURE = 'inspection_signature';
+
+    /**
+     * Normalizes one file value. Returns the value unchanged when it is not a
+     * string, is empty, or is something other than base64 or a file reference.
+     */
+    public static function normalize(mixed $value, InspectionSubmission $submission, string $type = self::TYPE_PHOTO, ?string $uploaderUuid = null): mixed
+    {
+        if (!is_string($value) || trim($value) === '') {
+            return $value;
+        }
+
+        $value = trim($value);
+
+        $linkUuid = static::linkUuidOf($submission);
+
+        // A reference to a file that already exists — `file:<uuid>`, a bare
+        // uuid, or the public id an upload answers with — is kept only for a
+        // file the submission may use.
+        if (Str::startsWith($value, 'file:') || Str::isUuid($value) || Str::startsWith($value, 'file_')) {
+            return static::ownedReference($value, $submission, $linkUuid);
+        }
+
+        if (static::isUrl($value)) {
+            if ($linkUuid) {
+                throw ValidationException::withMessages(['photos' => 'A photo on an inspection link must be uploaded through the link.']);
+            }
+
+            return $value;
+        }
+
+        if (static::isBase64($value)) {
+            $file = static::store($value, $submission, $type, $uploaderUuid);
+
+            return $file ? 'file:' . $file->uuid : $value;
+        }
+
+        return $value;
+    }
+
+    /**
+     * Stores a base64 payload — bare or as a data URI — as a file that belongs
+     * to the submission, under `inspections/<submission uuid>/`.
+     */
+    public static function store(string $base64, InspectionSubmission $submission, string $type = self::TYPE_PHOTO, ?string $uploaderUuid = null): ?File
+    {
+        $contentType = null;
+        $data        = $base64;
+
+        if (preg_match('/^data:(?<content_type>[^;]+);base64,(?<data>.+)$/s', $base64, $matches)) {
+            $contentType = $matches['content_type'];
+            $data        = $matches['data'];
+        }
+
+        $data        = preg_replace('/\s+/', '', $data);
+        $contentType = $contentType ?? static::sniffContentType($data);
+        $extension   = static::extensionFor($contentType);
+        $fileName    = Str::lower(Str::random(20)) . '.' . $extension;
+
+        $file = File::createFromBase64($data, $fileName, 'inspections/' . $submission->uuid, $type, $contentType);
+        if (!$file instanceof File) {
+            return null;
+        }
+
+        $file->company_uuid  = $submission->company_uuid;
+        $file->uploader_uuid = $uploaderUuid ?? $submission->submitted_by_uuid ?? $file->uploader_uuid;
+        $file->setSubject($submission, $type);
+
+        return $file;
+    }
+
+    /**
+     * Files referenced by `file:<uuid>` values that were uploaded before the
+     * submission existed — the console uploads a photo as soon as it is picked
+     * — are claimed by the submission so its Photos panel lists them.
+     *
+     * @param string[] $uuids
+     */
+    public static function attachReferenced(InspectionSubmission $submission, array $uuids): int
+    {
+        $uuids = array_values(array_unique(array_filter($uuids, 'is_string')));
+        if (empty($uuids)) {
+            return 0;
+        }
+
+        // Only the submission's own company's files, and — for a submission
+        // through a public link — only files uploaded through that link. This
+        // claim was unscoped: any unattached file anywhere whose uuid appeared
+        // in an answer was taken.
+        $query = File::query()
+            ->whereIn('uuid', $uuids)
+            ->where('company_uuid', $submission->company_uuid)
+            ->whereNull('subject_uuid');
+
+        if ($linkUuid = static::linkUuidOf($submission)) {
+            $query->where('meta->inspection_link_uuid', $linkUuid);
+        }
+
+        return $query->update(['subject_uuid' => $submission->uuid, 'subject_type' => $submission->getMorphClass()]);
+    }
+
+    /**
+     * The inspection link a submission came through, or null when it came
+     * through the console or the driver app.
+     */
+    protected static function linkUuidOf(InspectionSubmission $submission): ?string
+    {
+        if ($submission->source !== 'public_link') {
+            return null;
+        }
+
+        $uuid = data_get($submission->meta, 'inspection_link_uuid');
+
+        return is_string($uuid) && $uuid !== '' ? $uuid : null;
+    }
+
+    /**
+     * A reference to an existing file, as `file:<uuid>`, kept only when the
+     * file is the submission's to use.
+     *
+     * The lookup used to be unscoped, so a submission that named another
+     * company's file — by uuid or public id — kept the reference, the file was
+     * attached to it, and the submission resource then handed out that file's
+     * URL. It is now scoped to the submission's company; a submission through
+     * a public link must also have uploaded the file through that link, and is
+     * refused outright rather than silently losing a photo it named.
+     */
+    protected static function ownedReference(string $value, InspectionSubmission $submission, ?string $linkUuid): ?string
+    {
+        $reference = Str::startsWith($value, 'file:') ? substr($value, 5) : $value;
+
+        $file = File::query()
+            ->where('company_uuid', $submission->company_uuid)
+            ->where(Str::isUuid($reference) ? 'uuid' : 'public_id', $reference)
+            ->first();
+
+        if ($file && (!$linkUuid || data_get($file->meta, 'inspection_link_uuid') === $linkUuid)) {
+            return 'file:' . $file->uuid;
+        }
+
+        if ($linkUuid) {
+            throw ValidationException::withMessages(['photos' => 'A photo on an inspection link must be uploaded through the link.']);
+        }
+
+        return null;
+    }
+
+    /** The uuid a `file:<uuid>` value points at, or null for anything else. */
+    public static function referencedUuid(mixed $value): ?string
+    {
+        if (!is_string($value) || !Str::startsWith($value, 'file:')) {
+            return null;
+        }
+
+        $uuid = substr($value, 5);
+
+        return Str::isUuid($uuid) ? $uuid : null;
+    }
+
+    /** Resolves a `file:<uuid>` value to its file, or null. */
+    public static function resolve(mixed $value): ?File
+    {
+        $uuid = static::referencedUuid($value);
+
+        return $uuid ? File::query()->where('uuid', $uuid)->first() : null;
+    }
+
+    /**
+     * What the driver API answers for a file value: the file's id and where to
+     * fetch it, or the value as it was stored when it is a URL.
+     */
+    public static function project(mixed $value): mixed
+    {
+        $file = static::resolve($value);
+        if (!$file) {
+            return $value;
+        }
+
+        return [
+            'id'           => $file->public_id,
+            'url'          => $file->url,
+            'filename'     => $file->original_filename,
+            'content_type' => $file->content_type,
+        ];
+    }
+
+    public static function isUrl(string $value): bool
+    {
+        return (bool) preg_match('#^https?://#i', $value);
+    }
+
+    /** Bare base64 of at least a few bytes: long enough not to be a word, and only base64 characters. */
+    public static function isBase64(string $value): bool
+    {
+        if (Str::startsWith($value, 'data:')) {
+            return (bool) preg_match('/^data:[^;]+;base64,[A-Za-z0-9+\/=\s]+$/s', $value);
+        }
+
+        $stripped = preg_replace('/\s+/', '', $value);
+
+        return strlen($stripped) >= 16
+            && strlen($stripped) % 4 === 0
+            && (bool) preg_match('/^[A-Za-z0-9+\/]+={0,2}$/', $stripped);
+    }
+
+    /** The image type from the decoded bytes' signature; PNG when it is not a known image. */
+    public static function sniffContentType(string $base64): string
+    {
+        $bytes = (string) base64_decode(substr($base64, 0, 32), true);
+
+        if (str_starts_with($bytes, "\xFF\xD8\xFF")) {
+            return 'image/jpeg';
+        }
+
+        if (str_starts_with($bytes, 'GIF8')) {
+            return 'image/gif';
+        }
+
+        if (str_starts_with($bytes, 'RIFF') && substr($bytes, 8, 4) === 'WEBP') {
+            return 'image/webp';
+        }
+
+        if (str_starts_with($bytes, '%PDF')) {
+            return 'application/pdf';
+        }
+
+        return 'image/png';
+    }
+
+    public static function extensionFor(string $contentType): string
+    {
+        return match (strtolower($contentType)) {
+            'image/jpeg', 'image/jpg' => 'jpg',
+            'image/gif'               => 'gif',
+            'image/webp'              => 'webp',
+            'application/pdf'         => 'pdf',
+            'image/svg+xml'           => 'svg',
+            default                   => 'png',
+        };
+    }
+}