@fleetbase/fleetops-engine 0.6.50 → 0.6.52

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/GettingStarted.php

@@ -0,0 +1,144 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\TrackingStatus;
+use Fleetbase\Models\Company;
+
+class GettingStarted
+{
+    protected Company $company;
+
+    public static function forCompany(Company $company): static
+    {
+        return new static($company);
+    }
+
+    public function __construct(Company $company)
+    {
+        $this->company = $company;
+    }
+
+    public function get(): array
+    {
+        $steps       = $this->steps();
+        $completed   = collect($steps)->filter(fn ($step) => $step['completed'])->count();
+        $total       = count($steps);
+        $nextStep    = collect($steps)->first(fn ($step) => !$step['completed']);
+        $isCompleted = $completed === $total;
+
+        return [
+            'profile_source'  => 'generic',
+            'profile'         => null,
+            'is_completed'    => $isCompleted,
+            'progress'        => [
+                'completed' => $completed,
+                'total'     => $total,
+                'percent'   => $total > 0 ? (int) round(($completed / $total) * 100) : 0,
+            ],
+            'next_step'       => $nextStep['key'] ?? null,
+            'steps'           => $steps,
+            'recommendations' => $this->recommendations(),
+        ];
+    }
+
+    protected function steps(): array
+    {
+        $companyUuid = $this->company->uuid;
+
+        $hasDriver = Driver::where('company_uuid', $companyUuid)->exists();
+        $hasOrder  = Order::where('company_uuid', $companyUuid)->exists();
+
+        $hasAssignedOrder = Order::where('company_uuid', $companyUuid)
+            ->whereNotNull('driver_assigned_uuid')
+            ->exists();
+
+        $hasOrderActivity = TrackingStatus::where('tracking_statuses.company_uuid', $companyUuid)
+            ->whereNotNull('tracking_statuses.tracking_number_uuid')
+            ->whereNotIn('tracking_statuses.code', ['CREATED', 'ORDER_CREATED'])
+            ->exists();
+
+        return [
+            [
+                'key'         => 'add_driver',
+                'title'       => 'Add a driver',
+                'description' => 'Create your first driver profile so work can be assigned.',
+                'estimate'    => '2 min',
+                'completed'   => $hasDriver,
+                'icon'        => 'id-card',
+                'route'       => 'console.fleet-ops.management.drivers.index.new',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/drivers',
+            ],
+            [
+                'key'         => 'create_order',
+                'title'       => 'Create an order',
+                'description' => 'Add a delivery or service order to start dispatching.',
+                'estimate'    => '3 min',
+                'completed'   => $hasOrder,
+                'icon'        => 'box',
+                'route'       => 'console.fleet-ops.operations.orders.index.new',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/orders',
+            ],
+            [
+                'key'         => 'assign_driver',
+                'title'       => 'Assign driver to order',
+                'description' => 'Connect the order to a driver for execution.',
+                'estimate'    => '1 min',
+                'completed'   => $hasAssignedOrder,
+                'icon'        => 'user-check',
+                'route'       => 'console.fleet-ops.operations.orders.index',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/dispatch',
+            ],
+            [
+                'key'         => 'update_activity',
+                'title'       => 'Update order activity',
+                'description' => 'Move the order through its workflow and capture progress.',
+                'estimate'    => '2 min',
+                'completed'   => $hasOrderActivity,
+                'icon'        => 'route',
+                'route'       => 'console.fleet-ops.operations.orders.index',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/tracking',
+            ],
+        ];
+    }
+
+    protected function recommendations(): array
+    {
+        return [
+            [
+                'key'         => 'route_optimization',
+                'title'       => 'Route Optimization',
+                'description' => 'Plan efficient multi-stop routes and reduce time on the road.',
+                'icon'        => 'route',
+                'accent'      => 'blue',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/orchestrator',
+            ],
+            [
+                'key'         => 'live_fleet',
+                'title'       => 'Live Fleet Map',
+                'description' => 'Watch active drivers, vehicles, and orders in real time.',
+                'icon'        => 'map-location-dot',
+                'accent'      => 'green',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/live-map',
+            ],
+            [
+                'key'         => 'service_rates',
+                'title'       => 'Service Rates',
+                'description' => 'Create pricing rules for deliveries, zones, and service areas.',
+                'icon'        => 'receipt',
+                'accent'      => 'amber',
+                'docs_url'    => 'https://www.fleetbase.io/docs/fleet-ops/service-rates',
+            ],
+            [
+                'key'         => 'customer_portal',
+                'title'       => 'Customer Portal',
+                'description' => 'Let customers submit orders and track deliveries from a branded portal.',
+                'icon'        => 'store',
+                'accent'      => 'purple',
+                'docs_url'    => 'https://www.fleetbase.io/docs/customer-portal',
+            ],
+        ];
+    }
+}

package/server/src/Support/PlaceSearch.php

@@ -0,0 +1,282 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Geocoder\Laravel\Facades\Geocoder;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+
+class PlaceSearch
+{
+    public static function search(Builder $query, ?string $searchQuery = null, array $options = []): Collection
+    {
+        $searchQuery  = static::normalizeSearchQuery($searchQuery);
+        $limit        = (int) data_get($options, 'limit', 30);
+        $geo          = filter_var(data_get($options, 'geo', false), FILTER_VALIDATE_BOOLEAN);
+        $latitude     = data_get($options, 'latitude');
+        $longitude    = data_get($options, 'longitude');
+        $noQueryOrder = data_get($options, 'no_query_order', 'name_desc');
+
+        static::applySavedPlaceSearch($query, $searchQuery, $latitude, $longitude, $noQueryOrder);
+
+        if ($limit > 0) {
+            $query->limit($limit);
+        }
+
+        $savedPlaces = $query->get();
+        $geoPlaces   = $geo ? static::geocode($searchQuery, $latitude, $longitude) : collect();
+
+        return static::mergeResults($geoPlaces, $savedPlaces, $searchQuery);
+    }
+
+    public static function geocode(?string $searchQuery = null, $latitude = null, $longitude = null): Collection
+    {
+        $searchQuery = static::normalizeSearchQuery($searchQuery);
+
+        if (!$searchQuery && (!$latitude || !$longitude)) {
+            return collect();
+        }
+
+        try {
+            if (Geocoding::canGoogleGeocode()) {
+                $results = collect();
+
+                try {
+                    if ($searchQuery) {
+                        $results = $results->merge(Geocoding::geocode($searchQuery, $latitude, $longitude));
+                    } elseif ($latitude && $longitude) {
+                        $results = $results->merge(Geocoding::reverseFromCoordinates($latitude, $longitude));
+                    }
+                } catch (\Throwable) {
+                    // Fall through to any nearby results already collected.
+                }
+
+                if ($searchQuery && $latitude && $longitude) {
+                    try {
+                        $results = $results->merge(Geocoding::reverseFromQuery($searchQuery, $latitude, $longitude));
+                    } catch (\Throwable) {
+                        // Text geocoding results should still be usable if nearby lookup fails.
+                    }
+                }
+
+                return static::rankPlacesByQuery(static::uniquePlaces($results), $searchQuery);
+            }
+
+            if (!$searchQuery) {
+                return collect();
+            }
+
+            $results = Geocoder::geocode($searchQuery)
+                ->get()
+                ->map(fn ($googleAddress) => Place::createFromGoogleAddress($googleAddress))
+                ->values();
+
+            return static::rankPlacesByQuery($results, $searchQuery);
+        } catch (\Throwable) {
+            return collect();
+        }
+    }
+
+    protected static function applySavedPlaceSearch(Builder $query, ?string $searchQuery, $latitude = null, $longitude = null, string $noQueryOrder = 'name_desc'): void
+    {
+        $query->addSelect('places.*');
+
+        if ($searchQuery) {
+            $query->where(function ($query) use ($searchQuery) {
+                $contains = '%' . $searchQuery . '%';
+
+                $query->orWhereRaw('LOWER(COALESCE(places.name, "")) LIKE ?', [$contains])
+                    ->orWhereRaw('LOWER(COALESCE(places.street1, "")) LIKE ?', [$contains])
+                    ->orWhereRaw('LOWER(COALESCE(places.street2, "")) LIKE ?', [$contains])
+                    ->orWhereRaw('LOWER(COALESCE(places.city, "")) LIKE ?', [$contains])
+                    ->orWhereRaw('LOWER(COALESCE(places.province, "")) LIKE ?', [$contains])
+                    ->orWhereRaw('LOWER(COALESCE(places.postal_code, "")) LIKE ?', [$contains]);
+            });
+
+            $prefix   = $searchQuery . '%';
+            $contains = '%' . $searchQuery . '%';
+
+            $query->selectRaw(
+                'CASE
+                    WHEN LOWER(COALESCE(places.name, "")) = ? OR LOWER(COALESCE(places.street1, "")) = ? OR LOWER(COALESCE(places.postal_code, "")) = ? THEN 0
+                    WHEN LOWER(COALESCE(places.name, "")) LIKE ? OR LOWER(COALESCE(places.street1, "")) LIKE ? OR LOWER(COALESCE(places.postal_code, "")) LIKE ? THEN 1
+                    WHEN LOWER(COALESCE(places.name, "")) LIKE ? OR LOWER(COALESCE(places.street1, "")) LIKE ? OR LOWER(COALESCE(places.street2, "")) LIKE ? OR LOWER(COALESCE(places.city, "")) LIKE ? OR LOWER(COALESCE(places.province, "")) LIKE ? OR LOWER(COALESCE(places.postal_code, "")) LIKE ? THEN 2
+                    ELSE 3
+                END AS place_search_relevance',
+                [$searchQuery, $searchQuery, $searchQuery, $prefix, $prefix, $prefix, $contains, $contains, $contains, $contains, $contains, $contains]
+            );
+            $query->orderBy('place_search_relevance', 'asc');
+        }
+
+        if ($latitude && $longitude) {
+            $point = new Point($latitude, $longitude);
+
+            $query->whereNotNull('places.location')->whereRaw('
+                ST_Y(places.location) BETWEEN -90 AND 90
+                AND ST_X(places.location) BETWEEN -180 AND 180
+                AND NOT (ST_X(places.location) = 0 AND ST_Y(places.location) = 0)
+            ');
+            $query->orderByDistanceSphere('location', $point, 'asc');
+        } elseif (!$searchQuery && $noQueryOrder === 'latest') {
+            $query->orderBy('places.created_at', 'desc');
+        } else {
+            $query->orderBy('places.name', 'desc');
+        }
+    }
+
+    protected static function mergeResults(Collection $geoPlaces, Collection $savedPlaces, ?string $searchQuery = null): Collection
+    {
+        $merged  = [];
+        $indexes = [];
+
+        foreach ($geoPlaces as $place) {
+            static::pushUniquePlace($merged, $indexes, $place);
+        }
+
+        foreach ($savedPlaces as $place) {
+            $key = static::placeKey($place);
+
+            if ($key && isset($indexes[$key])) {
+                if (static::isStrongSavedMatch($place, $searchQuery)) {
+                    $merged[$indexes[$key]] = $place;
+                }
+
+                continue;
+            }
+
+            static::pushUniquePlace($merged, $indexes, $place);
+        }
+
+        return collect($merged)->values();
+    }
+
+    protected static function pushUniquePlace(array &$merged, array &$indexes, ?Place $place): void
+    {
+        if (!$place instanceof Place) {
+            return;
+        }
+
+        $key = static::placeKey($place);
+
+        if ($key && isset($indexes[$key])) {
+            return;
+        }
+
+        if ($key) {
+            $indexes[$key] = count($merged);
+        }
+
+        $merged[] = $place;
+    }
+
+    protected static function uniquePlaces(Collection $places): Collection
+    {
+        $merged  = [];
+        $indexes = [];
+
+        foreach ($places as $place) {
+            static::pushUniquePlace($merged, $indexes, $place);
+        }
+
+        return collect($merged)->values();
+    }
+
+    protected static function rankPlacesByQuery(Collection $places, ?string $searchQuery = null): Collection
+    {
+        if (!$searchQuery) {
+            return $places->values();
+        }
+
+        return $places
+            ->values()
+            ->map(fn ($place, $index) => [
+                'place' => $place,
+                'rank'  => static::placeQueryRank($place, $searchQuery),
+                'index' => $index,
+            ])
+            ->sortBy([
+                ['rank', 'asc'],
+                ['index', 'asc'],
+            ])
+            ->pluck('place')
+            ->values();
+    }
+
+    protected static function placeQueryRank(Place $place, ?string $searchQuery = null): int
+    {
+        if (!$searchQuery) {
+            return 4;
+        }
+
+        $query  = static::normalizeSearchQuery($searchQuery);
+        $values = collect([
+            $place->name,
+            $place->street1,
+            $place->postal_code,
+            $place->toAddressString(['name']),
+            $place->address,
+        ])
+            ->filter()
+            ->map(fn ($value) => static::normalizeSearchQuery($value));
+
+        if ($values->contains($query)) {
+            return 0;
+        }
+
+        if ($values->contains(fn ($value) => Str::startsWith($value, $query))) {
+            return 1;
+        }
+
+        if ($values->contains(fn ($value) => Str::contains($value, $query))) {
+            return 2;
+        }
+
+        return 3;
+    }
+
+    protected static function isStrongSavedMatch(Place $place, ?string $searchQuery = null): bool
+    {
+        if (!$searchQuery) {
+            return false;
+        }
+
+        $query = static::normalizeSearchQuery($searchQuery);
+
+        return collect([$place->name, $place->street1, $place->postal_code])
+            ->filter()
+            ->map(fn ($value) => static::normalizeSearchQuery($value))
+            ->contains($query);
+    }
+
+    protected static function placeKey(Place $place): ?string
+    {
+        $address = static::normalizeSearchQuery($place->toAddressString(['name']) ?: $place->address ?: $place->street1 ?: $place->name);
+        $lat     = data_get($place, 'latitude');
+        $lng     = data_get($place, 'longitude');
+
+        if (!$lat && $place->location && method_exists($place->location, 'getLat')) {
+            $lat = $place->location->getLat();
+            $lng = $place->location->getLng();
+        }
+
+        $coordinates = $lat && $lng ? round((float) $lat, 5) . ',' . round((float) $lng, 5) : null;
+
+        if (!$address && !$coordinates) {
+            return null;
+        }
+
+        return trim($address . '|' . $coordinates, '|');
+    }
+
+    protected static function normalizeSearchQuery(?string $searchQuery): ?string
+    {
+        if (!is_string($searchQuery)) {
+            return null;
+        }
+
+        return (string) Str::of($searchQuery)->lower()->squish();
+    }
+}

package/server/src/Support/ResolvesOrderServiceStops.php

@@ -32,6 +32,28 @@ trait ResolvesOrderServiceStops
         return $payload->waypoints->isNotEmpty();
     }
 
+    protected function payloadHasWaypointMarkers(?Payload $payload): bool
+    {
+        if (!$payload) {
+            return false;
+        }
+
+        $payload->loadMissing('waypointMarkers');
+
+        return $payload->waypointMarkers->isNotEmpty();
+    }
+
+    protected function payloadUsesServiceStopActivity(?Payload $payload): bool
+    {
+        if (!$payload) {
+            return false;
+        }
+
+        return $this->payloadHasWaypointMarkers($payload)
+            || $this->payloadHasWaypoints($payload)
+            || $this->payloadServiceStops($payload)->count() > 2;
+    }
+
     protected function resolveProof($proof): ?Proof
     {
         if ($proof instanceof Proof) {
@@ -54,7 +76,6 @@ trait ResolvesOrderServiceStops
         $payload->loadMissing([
             'pickup',
             'dropoff',
-            'return',
             'waypoints',
             'waypointMarkers.place',
             'waypointMarkers.trackingNumber.status',
@@ -112,16 +133,6 @@ trait ResolvesOrderServiceStops
             ]);
         }
 
-        if ($payload->return instanceof Place) {
-            $stops->push([
-                'type'                 => 'return',
-                'place'                => $payload->return,
-                'waypoint'             => null,
-                'tracking_number_uuid' => $payload->return_tracking_number_uuid,
-                'sequence'             => ++$sequence,
-            ]);
-        }
-
         return $stops->values();
     }
 
@@ -340,7 +351,6 @@ trait ResolvesOrderServiceStops
         return match ($type) {
             'pickup'  => 'pickup_tracking_number_uuid',
             'dropoff' => 'dropoff_tracking_number_uuid',
-            'return'  => 'return_tracking_number_uuid',
             default   => null,
         };
     }