@fleetbase/fleetops-engine 0.6.47 → 0.6.49

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

@@ -0,0 +1,64 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrchestrationController as InternalOrchestrationController;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Public consumable API for FleetOps orchestration.
+ *
+ * This controller delegates orchestration behavior to the internal workbench
+ * controller and only changes the public API serialization boundary.
+ */
+class OrchestrationController extends InternalOrchestrationController
+{
+    public function run(Request $request): JsonResponse
+    {
+        return $this->publicResponse(parent::run($request));
+    }
+
+    public function commit(Request $request): JsonResponse
+    {
+        return $this->publicResponse(parent::commit($request));
+    }
+
+    protected function publicResponse(JsonResponse $response): JsonResponse
+    {
+        return response()->json(
+            $this->sanitizePublicPayload($response->getData(true)),
+            $response->getStatusCode()
+        );
+    }
+
+    /**
+     * Recursively remove internal identifiers from public orchestrator payloads.
+     */
+    protected function sanitizePublicPayload(mixed $payload): mixed
+    {
+        if (!is_array($payload)) {
+            return $payload;
+        }
+
+        $sanitized = [];
+
+        foreach ($payload as $key => $value) {
+            if (is_string($key) && $this->isInternalIdentifierKey($key)) {
+                continue;
+            }
+
+            $sanitized[$key] = $this->sanitizePublicPayload($value);
+        }
+
+        return $sanitized;
+    }
+
+    protected function isInternalIdentifierKey(string $key): bool
+    {
+        return $key === 'uuid'
+            || str_ends_with($key, '_uuid')
+            || $key === 'internal_id'
+            || $key === 'company_uuid';
+    }
+}

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

@@ -93,17 +93,17 @@ class OrderController extends Controller
 
         // create payload
         if ($request->has('payload') && $request->isArray('payload')) {
-            $payload      = new Payload();
-            $payloadInput = $request->input('payload');
-            $entities     = data_get($payloadInput, 'entities', []);
-            $waypoints    = data_get($payloadInput, 'waypoints', []);
-            $pickup       = data_get($payloadInput, 'pickup');
-            $dropoff      = data_get($payloadInput, 'dropoff');
-            $return       = data_get($payloadInput, 'return');
-            $hasPickupField = array_key_exists('pickup', $payloadInput);
-            $hasDropoffField = array_key_exists('dropoff', $payloadInput);
-            $hasReturnField = array_key_exists('return', $payloadInput);
-            $hasWaypointsField = array_key_exists('waypoints', $payloadInput);
+            $payload                = new Payload();
+            $payloadInput           = $request->input('payload');
+            $entities               = data_get($payloadInput, 'entities', []);
+            $waypoints              = data_get($payloadInput, 'waypoints', []);
+            $pickup                 = data_get($payloadInput, 'pickup');
+            $dropoff                = data_get($payloadInput, 'dropoff');
+            $return                 = data_get($payloadInput, 'return');
+            $hasPickupField         = array_key_exists('pickup', $payloadInput);
+            $hasDropoffField        = array_key_exists('dropoff', $payloadInput);
+            $hasReturnField         = array_key_exists('return', $payloadInput);
+            $hasWaypointsField      = array_key_exists('waypoints', $payloadInput);
             $hasRouteEndpointFields = $hasPickupField || $hasDropoffField || $hasReturnField;
 
             if ($pickup) {
@@ -445,17 +445,17 @@ class OrderController extends Controller
 
         // create a payload if missing payload[] but has pickup/dropoff/etc
         if ($request->missing('payload')) {
-            $payload      = data_get($order, 'payload', new Payload());
-            $payloadInput = $request->only(['pickup', 'dropoff', 'return', 'waypoints', 'entities']);
-            $entities     = data_get($payloadInput, 'entities', []);
-            $waypoints    = data_get($payloadInput, 'waypoints', []);
-            $pickup       = data_get($payloadInput, 'pickup');
-            $dropoff      = data_get($payloadInput, 'dropoff');
-            $return       = data_get($payloadInput, 'return');
-            $hasPickupField = $request->exists('pickup');
-            $hasDropoffField = $request->exists('dropoff');
-            $hasReturnField = $request->exists('return');
-            $hasWaypointsField = $request->exists('waypoints');
+            $payload                = data_get($order, 'payload', new Payload());
+            $payloadInput           = $request->only(['pickup', 'dropoff', 'return', 'waypoints', 'entities']);
+            $entities               = data_get($payloadInput, 'entities', []);
+            $waypoints              = data_get($payloadInput, 'waypoints', []);
+            $pickup                 = data_get($payloadInput, 'pickup');
+            $dropoff                = data_get($payloadInput, 'dropoff');
+            $return                 = data_get($payloadInput, 'return');
+            $hasPickupField         = $request->exists('pickup');
+            $hasDropoffField        = $request->exists('dropoff');
+            $hasReturnField         = $request->exists('return');
+            $hasWaypointsField      = $request->exists('waypoints');
             $hasRouteEndpointFields = $hasPickupField || $hasDropoffField || $hasReturnField;
 
             // if no pickup and dropoff extract from waypoints
@@ -1328,13 +1328,13 @@ class OrderController extends Controller
      *
      * @return \Illuminate\Http\Response
      */
-    public function trackerData(string $id)
+    public function trackerData(Request $request, string $id)
     {
         set_time_limit(280);
 
         try {
             $order = Order::findRecordOrFail($id);
-            $data  = $order->tracker()->toArray();
+            $data  = $order->tracker()->toArray($request->only(['provider', 'fallbacks', 'traffic_enabled']));
 
             return response()->json($data);
         } catch (ModelNotFoundException $e) {
@@ -1351,11 +1351,11 @@ class OrderController extends Controller
      *
      * @return \Illuminate\Http\Response
      */
-    public function etaData(string $id)
+    public function etaData(Request $request, string $id)
     {
         try {
             $order = Order::findRecordOrFail($id);
-            $data  = $order->tracker()->eta();
+            $data  = $order->tracker()->eta($request->only(['provider', 'fallbacks', 'traffic_enabled']));
 
             return response()->json($data);
         } catch (ModelNotFoundException $e) {

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

@@ -25,16 +25,16 @@ class PayloadController extends Controller
      */
     public function create(CreatePayloadRequest $request)
     {
-        $input     = $request->all();
-        $entities  = data_get($input, 'entities', []);
-        $waypoints = data_get($input, 'waypoints', []);
-        $pickup    = data_get($input, 'pickup');
-        $dropoff   = data_get($input, 'dropoff');
-        $return    = data_get($input, 'return');
-        $hasPickupField = array_key_exists('pickup', $input);
-        $hasDropoffField = array_key_exists('dropoff', $input);
-        $hasReturnField = array_key_exists('return', $input);
-        $hasWaypointsField = array_key_exists('waypoints', $input);
+        $input                  = $request->all();
+        $entities               = data_get($input, 'entities', []);
+        $waypoints              = data_get($input, 'waypoints', []);
+        $pickup                 = data_get($input, 'pickup');
+        $dropoff                = data_get($input, 'dropoff');
+        $return                 = data_get($input, 'return');
+        $hasPickupField         = array_key_exists('pickup', $input);
+        $hasDropoffField        = array_key_exists('dropoff', $input);
+        $hasReturnField         = array_key_exists('return', $input);
+        $hasWaypointsField      = array_key_exists('waypoints', $input);
         $hasRouteEndpointFields = $hasPickupField || $hasDropoffField || $hasReturnField;
 
         // make sure company is set

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

@@ -231,7 +231,7 @@ class ServiceQuoteController extends Controller
         $entities  = collect($entities)->mapInto(Entity::class);
 
         // should all be Place like
-        $waypoints = collect([$pickup, ...$waypoints, $dropoff])->filter();
+        $waypoints     = collect([$pickup, ...$waypoints, $dropoff])->filter();
         $endpointCount = (int) ($pickup instanceof Place) + (int) ($dropoff instanceof Place);
 
         // if facilitator is an integrated partner resolve service quotes from bridge

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

@@ -0,0 +1,119 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
+
+use Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics;
+use Fleetbase\FleetOps\Support\Analytics\FuelEfficiency;
+use Fleetbase\FleetOps\Support\Analytics\GeofenceViolations;
+use Fleetbase\FleetOps\Support\Analytics\IssuesInsights;
+use Fleetbase\FleetOps\Support\Analytics\LiveFleet;
+use Fleetbase\FleetOps\Support\Analytics\MaintenanceOverview;
+use Fleetbase\FleetOps\Support\Analytics\OnTimeDelivery;
+use Fleetbase\FleetOps\Support\Analytics\OperationsPulse;
+use Fleetbase\FleetOps\Support\Analytics\OrdersByStatus;
+use Fleetbase\FleetOps\Support\Analytics\RevenueTrend;
+use Fleetbase\FleetOps\Support\Analytics\TopDrivers;
+use Fleetbase\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+/**
+ * One public method per dashboard widget. Each method:
+ *   - Resolves a period from ?period=7d|30d|... or explicit start/end
+ *   - Constructs the corresponding Support\Analytics\* helper
+ *   - Returns the helper's JSON payload (Chart.js datasets, ranked rows,
+ *     scalar tiles, etc. — shape is widget-specific)
+ *
+ * Cache headers are set per-widget by the route middleware in routes.php.
+ */
+class AnalyticsController extends Controller
+{
+    public function operationsPulse(Request $request)
+    {
+        return $this->run($request, OperationsPulse::class);
+    }
+
+    public function revenueTrend(Request $request)
+    {
+        return $this->run($request, RevenueTrend::class, function (RevenueTrend $a) use ($request) {
+            $a->groupBy($request->string('group_by', 'day')->toString());
+        });
+    }
+
+    public function ordersByStatus(Request $request)
+    {
+        return $this->run($request, OrdersByStatus::class, defaultDays: 14);
+    }
+
+    public function onTimeDelivery(Request $request)
+    {
+        return $this->run($request, OnTimeDelivery::class, function (OnTimeDelivery $a) use ($request) {
+            $a->slaMinutes((int) $request->input('sla_minutes', 30));
+        });
+    }
+
+    public function topDrivers(Request $request)
+    {
+        return $this->run($request, TopDrivers::class, function (TopDrivers $a) use ($request) {
+            $a->limit((int) $request->input('limit', 10));
+            $a->sortBy($request->string('sort_by', 'orders_completed')->toString());
+        });
+    }
+
+    public function fuelEfficiency(Request $request)
+    {
+        return $this->run($request, FuelEfficiency::class, defaultDays: 90);
+    }
+
+    public function issuesInsights(Request $request)
+    {
+        return $this->run($request, IssuesInsights::class);
+    }
+
+    public function maintenanceOverview(Request $request)
+    {
+        return $this->run($request, MaintenanceOverview::class);
+    }
+
+    public function geofenceViolations(Request $request)
+    {
+        return $this->run($request, GeofenceViolations::class, defaultDays: 7);
+    }
+
+    public function liveFleet(Request $request)
+    {
+        return $this->run($request, LiveFleet::class);
+    }
+
+    /**
+     * Shared boilerplate: period parsing + helper construction + JSON response.
+     *
+     * @param class-string<AbstractAnalytics> $class
+     */
+    private function run(Request $request, string $class, ?callable $configure = null, int $defaultDays = 30)
+    {
+        [$start, $end] = AbstractAnalytics::resolvePeriod(
+            $request->string('period')->toString() ?: null,
+            $request->date('start'),
+            $request->date('end'),
+            $defaultDays,
+        );
+
+        try {
+            /** @var AbstractAnalytics $analytics */
+            $analytics = $class::forCompany($request->user()->company)->between($start, $end);
+
+            if ($configure !== null) {
+                $configure($analytics);
+            }
+
+            return response()->json($analytics->get());
+        } catch (\Throwable $e) {
+            report($e);
+
+            return response()->json([
+                'error'   => $e->getMessage(),
+                'widget'  => $class,
+            ], 500);
+        }
+    }
+}

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

@@ -8,6 +8,7 @@ use Fleetbase\FleetOps\Imports\ContactImport;
 use Fleetbase\FleetOps\Models\Contact;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
+use Fleetbase\Models\User;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
 use Maatwebsite\Excel\Facades\Excel;
@@ -21,11 +22,35 @@ class ContactController extends FleetOpsController
      */
     public $resource = 'contact';
 
+    /**
+     * Handle pre-create transactions.
+     */
+    public function onBeforeCreate(Request $request, array &$input)
+    {
+        $this->resolveUserInput($request, $input);
+    }
+
+    /**
+     * Handle pre-update transactions.
+     */
+    public function onBeforeUpdate(Request $request, Contact $contact, array &$input)
+    {
+        if ($contact->type === 'customer' && isset($input['type']) && $input['type'] !== 'customer') {
+            throw new \Exception('Customer contact type cannot be changed.');
+        }
+
+        $this->resolveUserInput($request, $input);
+    }
+
     /**
      * Handle post save transactions.
      */
     public function afterSave(Request $request, Contact $contact)
     {
+        if ($contact->type === 'customer') {
+            $contact->normalizeCustomerUser();
+        }
+
         $customFieldValues = $request->array('contact.custom_field_values');
         if ($customFieldValues) {
             $contact->syncCustomFieldValues($customFieldValues);
@@ -105,4 +130,20 @@ class ContactController extends FleetOpsController
 
         return response()->json(['status' => 'ok', 'message' => 'Import completed', 'imported' => $importedCount]);
     }
+
+    private function resolveUserInput(Request $request, array &$input): void
+    {
+        $user = data_get($input, 'user_uuid') ?? data_get($input, 'user') ?? $request->input('contact.user_uuid') ?? $request->input('contact.user');
+
+        if (is_array($user)) {
+            $user = data_get($user, 'uuid') ?? data_get($user, 'id');
+        }
+
+        if (!$user) {
+            return;
+        }
+
+        $input['user_uuid'] = User::where('uuid', $user)->orWhere('public_id', $user)->value('uuid') ?? $user;
+        unset($input['user']);
+    }
 }

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

@@ -13,6 +13,7 @@ use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Route;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Support\LiveCacheService;
+use Fleetbase\FleetOps\Support\LiveOrderQuery;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\Request;
 
@@ -110,50 +111,13 @@ class LiveController extends Controller
         ];
 
         return LiveCacheService::remember('orders', $cacheParams, function () use ($exclude, $active, $unassigned) {
-            $query = Order::where('company_uuid', session('company'))
-            ->whereHas('payload', function ($query) {
-                $query->where(
-                    function ($q) {
-                        $q->whereHas('waypoints');
-                        $q->orWhereHas('pickup');
-                        $q->orWhereHas('dropoff');
-                    }
-                );
-            })
-            ->whereNotIn('status', ['canceled', 'completed', 'expired'])
-            ->whereHas('trackingNumber')
-            ->whereHas('trackingStatuses')
-            ->whereNotIn('public_id', $exclude)
-            ->whereNull('deleted_at')
-            ->applyDirectivesForPermissions('fleet-ops list order')
-            ->with([
-                'payload.entities',
-                'payload.dropoff',
-                'payload.pickup',
-                'payload.return',
-                'payload.firstWaypointMarker.place',
-                'payload.lastWaypointMarker.place',
-                'trackingNumber',
-                'trackingStatuses',
-                'driverAssigned' => function ($query) {
-                    $query->without(['jobs', 'currentJob']);
-                },
-                'vehicleAssigned' => function ($query) {
-                    $query->without(['fleets', 'vendor']);
-                },
-                'customer',
-                'facilitator',
+            $query = LiveOrderQuery::make(session('company'), [
+                'exclude'        => $exclude,
+                'active'         => $active,
+                'unassigned'     => $unassigned,
+                'with_relations' => true,
             ]);
 
-            if ($active) {
-                $query->whereHas('driverAssigned');
-                $query->whereNotIn('status', ['created', 'completed', 'expired', 'order_canceled', 'canceled', 'pending']);
-            }
-
-            if ($unassigned) {
-                $query->whereNull('driver_assigned_uuid');
-            }
-
             $query->limit(60); // max 60 latest
             $query->latest();
 

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

@@ -3,15 +3,17 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Support\Metrics;
+use Fleetbase\FleetOps\Support\Metrics\Registry;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
 
 class MetricsController extends Controller
 {
     /**
-     * Gets all key metrics for the current session.
-     *
-     * @return \Illuminate\Http\Response
+     * Legacy bulk endpoint. Returns a flat map of slug → scalar value for the
+     * requested period. Preserved for backward compat; the dashboard widgets
+     * now prefer per-slug GET /metrics/{slug}.
      */
     public function all(Request $request)
     {
@@ -27,4 +29,81 @@ class MetricsController extends Controller
 
         return response()->json($data);
     }
+
+    /**
+     * Per-metric endpoint backing <Widget::KpiTile>.
+     *
+     * Accepts:
+     *   ?period=7d|30d|90d  OR  ?start=ISO&end=ISO
+     *   ?sparkline=true     to include a per-day mini-chart series
+     *   ?compare=true       to include period-over-period delta (default: true)
+     *
+     * Returns: { slug, value, format, currency?, delta_pct?, sparkline? }
+     */
+    public function show(Request $request, string $slug)
+    {
+        $class = Registry::resolve($slug);
+        if ($class === null) {
+            return response()->json(['error' => "Unknown metric: {$slug}"], 404);
+        }
+
+        [$start, $end] = $this->resolvePeriod($request);
+
+        $metric = $class::forCompany($request->user()->company)->between($start, $end);
+
+        if ($request->boolean('compare', true)) {
+            $duration     = $end->getTimestamp() - $start->getTimestamp();
+            $compareEnd   = (clone $start);
+            $compareStart = (clone $start)->modify("-{$duration} seconds");
+            $metric->compareTo($compareStart, $compareEnd);
+        }
+
+        if ($request->boolean('sparkline')) {
+            $buckets = (int) $request->input('sparkline_buckets', 14);
+            $metric->withSparkline($buckets, 'day');
+        }
+
+        return response()->json($metric->get());
+    }
+
+    /**
+     * Parse ?period=7d/30d/90d into a [start, end] pair, falling back to
+     * explicit ?start=&end= ISO dates, then to a 30-day default.
+     */
+    private function resolvePeriod(Request $request): array
+    {
+        $period = $request->string('period')->toString();
+
+        if ($period !== '') {
+            $days = match ($period) {
+                '7d'    => 7,
+                '14d'   => 14,
+                '30d'   => 30,
+                '90d'   => 90,
+                '180d'  => 180,
+                '365d'  => 365,
+                default => null,
+            };
+
+            if ($days !== null) {
+                $end   = Carbon::now()->toDateTime();
+                $start = Carbon::now()->subDays($days)->toDateTime();
+
+                return [$start, $end];
+            }
+        }
+
+        $start = $request->date('start') ?? Carbon::now()->subDays(30)->toDateTime();
+        $end   = $request->date('end') ?? Carbon::now()->toDateTime();
+
+        if (!$start instanceof \DateTime) {
+            $start = Carbon::parse($start)->toDateTime();
+        }
+
+        if (!$end instanceof \DateTime) {
+            $end = Carbon::parse($end)->toDateTime();
+        }
+
+        return [$start, $end];
+    }
 }

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

@@ -573,7 +573,7 @@ class OrchestrationController extends Controller
                 $isMulti   = $orderType === 'multi_waypoint';
 
                 // ── Resolve OrderConfig ───────────────────────────────────────
-                $orderConfigUuid = null;
+                $orderConfigUuid     = null;
                 $resolvedOrderConfig = null;
                 if (!empty($firstRow['type'])) {
                     $resolvedOrderConfig = OrderConfig::resolveFromIdentifier($firstRow['type']);