@fleetbase/fleetops-engine 0.6.51 → 0.6.53

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

@@ -0,0 +1,98 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\FuelProviders\Providers;
+
+use Fleetbase\FleetOps\Contracts\FuelProvider;
+use Fleetbase\FleetOps\Models\FuelProviderConnection;
+use Illuminate\Http\Client\PendingRequest;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Str;
+
+abstract class AbstractFuelProvider implements FuelProvider
+{
+    public function authenticate(FuelProviderConnection $connection): array
+    {
+        return ['success' => true, 'message' => 'Authentication headers prepared.'];
+    }
+
+    public function listVehicles(FuelProviderConnection $connection, array $options = []): Collection
+    {
+        return collect();
+    }
+
+    public function listStations(FuelProviderConnection $connection, array $options = []): Collection
+    {
+        return collect();
+    }
+
+    public function pushTrip(FuelProviderConnection $connection, array $trip): array
+    {
+        return ['success' => false, 'message' => 'Provider does not support trip push.'];
+    }
+
+    public function syncVehicle(FuelProviderConnection $connection, array $vehicle): array
+    {
+        return ['success' => false, 'message' => 'Provider does not support vehicle sync.'];
+    }
+
+    public function webhookPayloadToTransaction(FuelProviderConnection $connection, array $payload): ?array
+    {
+        return null;
+    }
+
+    protected function client(FuelProviderConnection $connection): PendingRequest
+    {
+        $credentials = (array) $connection->credentials;
+
+        return Http::baseUrl($this->baseUrl($connection))
+            ->timeout((int) data_get($credentials, 'timeout', 30))
+            ->acceptJson()
+            ->withHeaders($this->headers($connection));
+    }
+
+    protected function baseUrl(FuelProviderConnection $connection): string
+    {
+        $credentials = (array) $connection->credentials;
+
+        return rtrim(data_get($credentials, 'base_url', ''), '/');
+    }
+
+    protected function headers(FuelProviderConnection $connection): array
+    {
+        return [];
+    }
+
+    protected function transactionHash(array $payload): string
+    {
+        return hash('sha256', json_encode($payload));
+    }
+
+    protected function minorCurrencyUnit($amount): ?int
+    {
+        if ($amount === null || $amount === '') {
+            return null;
+        }
+
+        return (int) round(((float) $amount) * 100);
+    }
+
+    protected function dateFrom($value): ?Carbon
+    {
+        if (empty($value)) {
+            return null;
+        }
+
+        return Carbon::parse($value);
+    }
+
+    protected function compactIdentifier($value): ?string
+    {
+        if (blank($value)) {
+            return null;
+        }
+
+        return Str::of($value)->replaceMatches('/\s+/', ' ')->trim()->toString();
+    }
+}

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

@@ -0,0 +1,167 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\FuelProviders\Providers;
+
+use Fleetbase\FleetOps\Models\FuelProviderConnection;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+
+class PetroAppFuelProvider extends AbstractFuelProvider
+{
+    public function key(): string
+    {
+        return 'petroapp';
+    }
+
+    public function name(): string
+    {
+        return 'PetroApp';
+    }
+
+    public function testConnection(FuelProviderConnection $connection): array
+    {
+        try {
+            $response = $this->client($connection)->get('vehicles', ['page' => 1]);
+
+            if (!$response->successful()) {
+                return [
+                    'success'  => false,
+                    'message'  => $response->json('message') ?? 'Unable to connect to PetroApp.',
+                    'metadata' => ['status' => $response->status()],
+                ];
+            }
+
+            return [
+                'success'  => true,
+                'message'  => 'PetroApp connection successful.',
+                'metadata' => [
+                    'total_vehicles' => $response->json('data.total'),
+                ],
+            ];
+        } catch (\Throwable $e) {
+            return ['success' => false, 'message' => $e->getMessage(), 'metadata' => []];
+        }
+    }
+
+    public function listVehicles(FuelProviderConnection $connection, array $options = []): Collection
+    {
+        return $this->paginatedGet($connection, 'vehicles', $options);
+    }
+
+    public function listStations(FuelProviderConnection $connection, array $options = []): Collection
+    {
+        return $this->paginatedGet($connection, 'petroapp_locations', $options, 'locs');
+    }
+
+    public function listTransactions(FuelProviderConnection $connection, Carbon $from, Carbon $to, array $options = []): Collection
+    {
+        $params = array_merge($options, [
+            'from' => $from->toDateString(),
+            'to'   => $to->toDateString(),
+            'lang' => data_get($options, 'lang', 'en'),
+        ]);
+
+        return $this->paginatedGet($connection, 'bills', $params)
+            ->map(fn ($payload) => $this->normalizeBill($payload));
+    }
+
+    protected function baseUrl(FuelProviderConnection $connection): string
+    {
+        $credentials = (array) $connection->credentials;
+
+        return rtrim(data_get($credentials, 'base_url', 'https://app-public.staging.petroapp.app/webservice'), '/');
+    }
+
+    protected function headers(FuelProviderConnection $connection): array
+    {
+        $credentials = (array) $connection->credentials;
+        $token       = data_get($credentials, 'api_token') ?? data_get($credentials, 'api_key');
+
+        if (data_get($credentials, 'auth_type') === 'ws_sk_header') {
+            return [
+                'WS-Version' => data_get($credentials, 'version', 'v2.0'),
+                'WS-SK'      => $token,
+            ];
+        }
+
+        return [
+            'WS-Version'    => data_get($credentials, 'version', 'v2.0'),
+            'Authorization' => 'Bearer ' . $token,
+        ];
+    }
+
+    protected function paginatedGet(FuelProviderConnection $connection, string $endpoint, array $params = [], ?string $dataKey = null): Collection
+    {
+        $page     = (int) data_get($params, 'page', 1);
+        $maxPages = (int) data_get($params, 'max_pages', 100);
+        unset($params['max_pages']);
+
+        $items = collect();
+
+        do {
+            $response = $this->client($connection)->get($endpoint, array_merge($params, ['page' => $page]));
+
+            if (!$response->successful()) {
+                throw new \RuntimeException($response->json('message') ?? "PetroApp {$endpoint} request failed.");
+            }
+
+            $payload = $response->json();
+            $data    = $dataKey ? data_get($payload, $dataKey, []) : data_get($payload, 'data.data', []);
+            $items   = $items->merge($data);
+
+            $lastPage = (int) data_get($payload, 'data.last_page', $page);
+            $hasMore  = data_get($payload, 'data.next_page_url') || $page < $lastPage;
+            $page++;
+        } while ($hasMore && $page <= $maxPages);
+
+        return $items;
+    }
+
+    protected function normalizeBill(array $bill): array
+    {
+        $transactionAt = $this->dateFrom($bill['bill_date'] ?? $bill['billDate'] ?? null);
+        $providerId    = $bill['id'] ?? $bill['bill_id'] ?? null;
+        $fallbackId    = $this->transactionHash([
+            $bill['bill_date'] ?? $bill['billDate'] ?? null,
+            $bill['trip_number'] ?? null,
+            $bill['internal_number'] ?? null,
+            $bill['structure_number'] ?? null,
+            $bill['plate_snum'] ?? null,
+            $bill['station_name'] ?? null,
+            $bill['num_of_liters'] ?? null,
+            $bill['cost'] ?? null,
+        ]);
+
+        return [
+            'provider'                => $this->key(),
+            'provider_transaction_id' => (string) ($providerId ?: $fallbackId),
+            'provider_vehicle_id'     => $this->compactIdentifier($bill['vehicle_id'] ?? null),
+            '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),
+            '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),
+            'trip_number'             => $this->compactIdentifier($bill['trip_number'] ?? null),
+            'station_name'            => $this->compactIdentifier($bill['station_name'] ?? null),
+            'station_latitude'        => $bill['station_lat'] ?? null,
+            'station_longitude'       => $bill['station_lng'] ?? null,
+            'transaction_at'          => $transactionAt,
+            'volume'                  => $bill['num_of_liters'] ?? null,
+            'metric_unit'             => 'l',
+            'amount'                  => $this->minorCurrencyUnit($bill['cost'] ?? null),
+            'currency'                => 'SAR',
+            'odometer'                => $bill['odometer'] ?? null,
+            'normalized_payload'      => [
+                'payment_method'      => $bill['payment_method'] ?? null,
+                'payment_method_text' => $bill['payment_method_text'] ?? null,
+                'branch_name'         => $bill['branch_name'] ?? null,
+                'city'                => $bill['city'] ?? null,
+                'district'            => $bill['district'] ?? null,
+                'delegate_name'       => $bill['delegate_name'] ?? null,
+            ],
+            'raw_payload' => $bill,
+        ];
+    }
+}

package/server/src/Support/Telematics/Providers/AbstractProvider.php

@@ -20,7 +20,7 @@ use Illuminate\Support\Str;
  */
 abstract class AbstractProvider implements TelematicProviderInterface
 {
-    protected Telematic $telematic;
+    protected ?Telematic $telematic  = null;
     protected array $credentials     = [];
     protected array $headers         = [];
     protected string $baseUrl        = '';
@@ -33,7 +33,7 @@ abstract class AbstractProvider implements TelematicProviderInterface
     public function connect(Telematic $telematic): void
     {
         $this->telematic   = $telematic;
-        $this->credentials = json_decode(Crypt::decryptString($telematic->credentials), true);
+        $this->credentials = $this->resolveCredentials($telematic);
         $this->prepareAuthentication();
     }
 
@@ -72,10 +72,9 @@ abstract class AbstractProvider implements TelematicProviderInterface
             Log::error('Provider API request failed', [
                 'correlation_id' => $correlationId,
                 'status'         => $response->status(),
-                'body'           => $response->body(),
             ]);
 
-            throw new \Exception('API request failed: ' . $response->body());
+            throw new \Exception('Provider API request failed with status ' . $response->status());
         }
 
         return $response->json();
@@ -88,7 +87,7 @@ abstract class AbstractProvider implements TelematicProviderInterface
      */
     protected function checkRateLimit(): void
     {
-        $key    = 'rate_limit:' . class_basename($this) . ':' . $this->telematic->uuid;
+        $key    = $this->rateLimitKey();
         $tokens = Cache::get($key, $this->burstSize);
 
         if ($tokens <= 0) {
@@ -103,7 +102,7 @@ abstract class AbstractProvider implements TelematicProviderInterface
      */
     protected function recordRequest(): void
     {
-        $key    = 'rate_limit:' . class_basename($this) . ':' . $this->telematic->uuid;
+        $key    = $this->rateLimitKey();
         $tokens = Cache::get($key, 0);
 
         // Refill tokens gradually
@@ -112,6 +111,28 @@ abstract class AbstractProvider implements TelematicProviderInterface
         }
     }
 
+    protected function rateLimitKey(): string
+    {
+        return 'rate_limit:' . class_basename($this) . ':' . ($this->telematic?->uuid ?? 'credential-test');
+    }
+
+    protected function resolveCredentials(Telematic $telematic): array
+    {
+        if (is_array($telematic->credentials)) {
+            return $telematic->credentials;
+        }
+
+        if (!$telematic->credentials) {
+            return [];
+        }
+
+        try {
+            return json_decode(Crypt::decryptString($telematic->credentials), true) ?? [];
+        } catch (\Throwable) {
+            return json_decode($telematic->credentials, true) ?? [];
+        }
+    }
+
     public function supportsWebhooks(): bool
     {
         return false;

package/server/src/Support/Telematics/Providers/AfaqyProvider.php

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Support\Telematics\Providers;
 
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
 
 /**
  * AFAQY telematics provider implementation.
@@ -23,8 +24,9 @@ class AfaqyProvider extends AbstractProvider
 
         $this->credentials['token'] = $token;
         $this->headers              = [
-            'Accept'       => 'application/json',
-            'Content-Type' => 'application/json',
+            'Accept'        => 'application/json',
+            'Content-Type'  => 'application/json',
+            'Authorization' => 'Bearer ' . $token,
         ];
     }
 
@@ -39,7 +41,7 @@ class AfaqyProvider extends AbstractProvider
                     'projection' => ['_id', 'name', 'imei', 'last_update'],
                     'filters'    => new \stdClass(),
                 ],
-            ]);
+            ], true);
 
             return [
                 'success'  => true,
@@ -60,13 +62,20 @@ class AfaqyProvider extends AbstractProvider
 
     public function fetchDevices(array $options = []): array
     {
-        $limit  = (int) ($options['limit'] ?? 100);
-        $offset = (int) ($options['cursor'] ?? 0);
+        $limit   = max(1, min((int) ($options['limit'] ?? 500), 500));
+        $offset  = (int) ($options['cursor'] ?? 0);
+        $filters = $options['filters'] ?? new \stdClass();
+
+        if (is_array($filters) && empty($filters)) {
+            $filters = new \stdClass();
+        }
 
         $response = $this->afaqyPost('/units/lists', [
             'data' => [
                 'address'    => $options['address'] ?? false,
-                'filters'    => $options['filters'] ?? new \stdClass(),
+                'filters'    => $filters,
+                'limit'      => $limit,
+                'offset'     => $offset,
                 'projection' => $options['projection'] ?? [
                     '_id',
                     'name',
@@ -78,23 +87,45 @@ class AfaqyProvider extends AbstractProvider
                     'last_update',
                     'counters',
                     'profile',
-                    'sensors',
                     'sensors_last_val',
                 ],
             ],
-            'limit'  => $limit,
-            'offset' => $offset,
+        ], true);
+
+        $devices     = $response['data'] ?? [];
+        $pagination  = $response['pagination'] ?? [];
+        $pageOffset  = (int) ($pagination['offset'] ?? $offset);
+        $pageLimit   = (int) ($pagination['limit'] ?? $limit);
+        $resultCount = (int) ($pagination['resultCount'] ?? count($devices));
+        $total       = (int) ($pagination['filtersCount'] ?? $pagination['allCount'] ?? count($devices));
+        $advanceBy   = $resultCount > 0 ? $resultCount : max($pageLimit, count($devices), 1);
+        $nextCursor  = ($pageOffset + $advanceBy) < $total ? $pageOffset + $advanceBy : null;
+
+        Log::info('AFAQY units page fetched', [
+            'telematic_uuid'        => $this->telematic?->uuid,
+            'requested_offset'      => $offset,
+            'requested_limit'       => $limit,
+            'provider_offset'       => $pageOffset,
+            'provider_limit'        => $pageLimit,
+            'provider_result_count' => $resultCount,
+            'result_count'          => count($devices),
+            'all_count'             => $pagination['allCount'] ?? null,
+            'filters_count'         => $pagination['filtersCount'] ?? null,
+            'next_cursor'           => $nextCursor,
+            'has_more'              => $nextCursor !== null,
         ]);
 
-        $devices    = $response['data'] ?? [];
-        $pagination = $response['pagination'] ?? [];
-        $total      = (int) ($pagination['filtersCount'] ?? $pagination['allCount'] ?? count($devices));
-        $nextCursor = ($offset + $limit) < $total ? $offset + $limit : null;
-
         return [
             'devices'     => $devices,
             'next_cursor' => $nextCursor,
             'has_more'    => $nextCursor !== null,
+            'pagination'  => [
+                'allCount'     => $pagination['allCount'] ?? null,
+                'filtersCount' => $pagination['filtersCount'] ?? null,
+                'resultCount'  => $resultCount,
+                'offset'       => $pageOffset,
+                'limit'        => $pageLimit,
+            ],
         ];
     }
 
@@ -110,26 +141,33 @@ class AfaqyProvider extends AbstractProvider
     public function normalizeDevice(array $payload): array
     {
         $lastUpdate = $payload['last_update'] ?? [];
+        $profile    = $payload['profile'] ?? [];
 
         return [
-            'external_id'     => $payload['_id'] ?? $payload['id'] ?? null,
-            'device_name'     => $payload['name'] ?? data_get($payload, 'profile.plate_number') ?? 'Unknown Unit',
-            'device_provider' => 'afaqy',
-            'device_model'    => data_get($payload, 'profile.model') ?? $payload['device'] ?? null,
-            'imei'            => $payload['imei'] ?? null,
-            'phone'           => $payload['sim_number'] ?? null,
-            'vin'             => data_get($payload, 'profile.vin'),
-            'status'          => ($payload['active'] ?? false) ? 'active' : 'inactive',
-            'location'        => [
+            'device_id'    => $payload['_id'] ?? $payload['id'] ?? null,
+            'name'         => $payload['name'] ?? data_get($payload, 'profile.plate_number') ?? 'Unknown Unit',
+            'provider'     => 'afaqy',
+            'model'        => data_get($payload, 'profile.model') ?? $payload['device'] ?? null,
+            'imei'         => $payload['imei'] ?? null,
+            'phone'        => $payload['sim_number'] ?? null,
+            'vin'          => data_get($payload, 'profile.vin'),
+            'status'       => ($payload['active'] ?? false) ? 'active' : 'inactive',
+            'online'       => $payload['active'] ?? null,
+            'last_seen_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
+            'location'     => [
                 'lat' => $lastUpdate['lat'] ?? null,
                 'lng' => $lastUpdate['lng'] ?? null,
             ],
             'meta' => [
-                'raw'          => $payload,
-                'plate_number' => data_get($payload, 'profile.plate_number'),
-                'driver_id'    => $payload['driver_id'] ?? null,
-                'last_update'  => $this->normalizeEvent($payload),
-                'capabilities' => [
+                'provider_unit_id' => $payload['_id'] ?? $payload['id'] ?? null,
+                'plate_number'     => data_get($profile, 'plate_number'),
+                'vehicle_type'     => data_get($profile, 'vehicle_type'),
+                'fuel_type'        => data_get($profile, 'fuel_type'),
+                'device_serial'    => $payload['device_serial'] ?? null,
+                'sim_number'       => $payload['sim_number'] ?? null,
+                'driver_id'        => $payload['driver_id'] ?? null,
+                'last_update'      => $this->compactLastUpdate($lastUpdate),
+                'capabilities'     => [
                     'tracking'       => isset($lastUpdate['lat'], $lastUpdate['lng']),
                     'odometer'       => data_get($payload, 'counters.odometer') !== null,
                     'fuel_level'     => $this->extractFuelLevel($payload) !== null,
@@ -145,7 +183,9 @@ class AfaqyProvider extends AbstractProvider
 
         return [
             'external_id' => $payload['_id'] ?? $payload['id'] ?? null,
+            'device_id'   => $payload['_id'] ?? $payload['id'] ?? null,
             'event_type'  => $payload['event'] ?? $payload['event_type'] ?? 'telemetry_update',
+            'message'     => $payload['message'] ?? $payload['event'] ?? null,
             'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
             'location'    => [
                 'lat' => $lastUpdate['lat'] ?? data_get($lastUpdate, 'loc.coordinates.1'),
@@ -175,12 +215,16 @@ class AfaqyProvider extends AbstractProvider
     {
         return [
             [
-                'name'        => 'base_url',
-                'label'       => 'Base URL',
-                'type'        => 'text',
-                'placeholder' => 'https://api.afaqy.sa',
-                'required'    => false,
-                'validation'  => 'nullable|url',
+                'name'          => 'base_url',
+                'label'         => 'Base URL',
+                'type'          => 'text',
+                'placeholder'   => 'https://api.afaqy.sa',
+                'required'      => false,
+                'advanced'      => true,
+                'is_endpoint'   => true,
+                'default_value' => 'https://api.afaqy.sa',
+                'help_text'     => 'Optional override. Leave blank to use the default AFAQY API host.',
+                'validation'    => 'nullable|url',
             ],
             [
                 'name'        => 'username',
@@ -227,7 +271,7 @@ class AfaqyProvider extends AbstractProvider
             ]);
 
         if ($response->failed()) {
-            throw new \RuntimeException('AFAQY authentication failed: ' . $response->body());
+            throw new \RuntimeException('AFAQY authentication failed with status ' . $response->status());
         }
 
         $token = data_get($response->json(), 'data.token');
@@ -239,19 +283,42 @@ class AfaqyProvider extends AbstractProvider
         return $token;
     }
 
-    protected function afaqyPost(string $endpoint, array $payload = []): array
+    protected function afaqyPost(string $endpoint, array $payload = [], bool $tokenInQuery = false): array
     {
+        $url  = $this->baseUrl . $endpoint;
+        $body = $tokenInQuery ? $payload : array_merge(['token' => $this->credentials['token']], $payload);
+
+        if ($tokenInQuery) {
+            $url .= (str_contains($url, '?') ? '&' : '?') . http_build_query(['token' => $this->credentials['token']]);
+        }
+
         $response = Http::withHeaders($this->headers)
             ->timeout(30)
-            ->post($this->baseUrl . $endpoint . '?token=' . urlencode($this->credentials['token']), $payload);
+            ->post($url, $body);
 
         if ($response->failed()) {
-            throw new \RuntimeException('AFAQY API request failed: ' . $response->body());
+            throw new \RuntimeException('AFAQY API request failed with status ' . $response->status());
         }
 
         return $response->json() ?? [];
     }
 
+    protected function compactLastUpdate(array $lastUpdate): array
+    {
+        $params = $lastUpdate['params'] ?? $lastUpdate['prms'] ?? [];
+
+        return array_filter([
+            'occurred_at' => $this->parseTimestamp($lastUpdate['dtt'] ?? $lastUpdate['dts'] ?? null),
+            'lat'         => $lastUpdate['lat'] ?? null,
+            'lng'         => $lastUpdate['lng'] ?? null,
+            'speed'       => $lastUpdate['speed'] ?? $lastUpdate['spd'] ?? null,
+            'heading'     => $lastUpdate['angle'] ?? $lastUpdate['ang'] ?? null,
+            'altitude'    => $lastUpdate['alt'] ?? null,
+            'satellites'  => $params['sat'] ?? null,
+            'protocol'    => $params['protocol'] ?? null,
+        ], fn ($value) => $value !== null);
+    }
+
     protected function parseTimestamp($value): ?string
     {
         if (!$value) {

package/server/src/Support/Telematics/Providers/FlespiProvider.php

@@ -97,6 +97,7 @@ class FlespiProvider extends AbstractProvider
     {
         return [
             'external_id' => $payload['id'] ?? null,
+            'device_id'   => $payload['device.id'] ?? null,
             'event_type'  => $payload['event.enum'] ?? 'telemetry_update',
             'occurred_at' => isset($payload['timestamp']) ? date('Y-m-d H:i:s', $payload['timestamp']) : now(),
             'location'    => [

package/server/src/Support/Telematics/Providers/GeotabProvider.php

@@ -131,6 +131,7 @@ class GeotabProvider extends AbstractProvider
     {
         return [
             'external_id' => $payload['id'] ?? null,
+            'device_id'   => $payload['device']['id'] ?? $payload['deviceId'] ?? null,
             'event_type'  => $payload['type'] ?? 'status_data',
             'occurred_at' => $payload['dateTime'] ?? now(),
             'meta'        => $payload,