@fleetbase/fleetops-engine 0.6.48 → 0.6.50

package/server/src/Support/Analytics/OnTimeDelivery.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+/**
+ * Percentage of completed orders that finished within the SLA window
+ * (scheduled_at + sla_minutes). Orders without a scheduled_at are excluded
+ * — you can't be on-time against an undefined target.
+ */
+class OnTimeDelivery extends AbstractAnalytics
+{
+    protected int $slaMinutes = 30;
+
+    public function slaMinutes(int $minutes): self
+    {
+        $this->slaMinutes = max(0, $minutes);
+
+        return $this;
+    }
+
+    public function get(): array
+    {
+        $start = $this->start ?? Carbon::now()->subDays(30)->toDateTime();
+        $end   = $this->end ?? Carbon::now()->toDateTime();
+
+        [$onTime, $late, $total] = $this->bucketCounts($start, $end);
+
+        $duration            = $end->getTimestamp() - $start->getTimestamp();
+        $compareEnd          = clone $start;
+        $compareStart        = (new \DateTime())->setTimestamp($start->getTimestamp() - $duration);
+        [, , $prevTotal]     = $this->bucketCounts($compareStart, $compareEnd);
+        $prevOnTime          = $this->bucketCounts($compareStart, $compareEnd)[0];
+        $prevPct             = $prevTotal > 0 ? ($prevOnTime / $prevTotal) * 100 : 0;
+        $currentPct          = $total > 0 ? ($onTime / $total) * 100 : 0;
+        $deltaPct            = round($currentPct - $prevPct, 1);
+
+        return [
+            'on_time_pct'   => round($currentPct, 1),
+            'on_time'       => $onTime,
+            'late'          => $late,
+            'total'         => $total,
+            'sla_minutes'   => $this->slaMinutes,
+            'delta_pct'     => $deltaPct,
+        ];
+    }
+
+    /** @return array{0:int,1:int,2:int} [onTime, late, total] */
+    private function bucketCounts(\DateTimeInterface $start, \DateTimeInterface $end): array
+    {
+        $slaSeconds = $this->slaMinutes * 60;
+
+        $orders = Order::where('company_uuid', $this->company->uuid)
+            ->where('status', 'completed')
+            ->whereNotNull('scheduled_at')
+            ->whereNotNull('updated_at')
+            ->whereBetween('updated_at', [$start, $end])
+            ->selectRaw('TIMESTAMPDIFF(SECOND, scheduled_at, updated_at) as drift_seconds')
+            ->get();
+
+        $onTime = 0;
+        $late   = 0;
+        foreach ($orders as $row) {
+            if ((int) $row->drift_seconds <= $slaSeconds) {
+                $onTime++;
+            } else {
+                $late++;
+            }
+        }
+
+        return [$onTime, $late, $onTime + $late];
+    }
+}

package/server/src/Support/Analytics/OperationsPulse.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Issue;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Metrics\OrdersInProgressMetric;
+use Illuminate\Support\Carbon;
+
+/**
+ * Real-time operational snapshot. Returns a small map of tile data + deltas
+ * vs the same window 24 hours ago for the rate-of-change indicators.
+ */
+class OperationsPulse extends AbstractAnalytics
+{
+    public function get(): array
+    {
+        $companyUuid = $this->company->uuid;
+
+        $activeOrders        = Order::where('company_uuid', $companyUuid)
+            ->whereIn('status', OrdersInProgressMetric::IN_PROGRESS_STATUSES)
+            ->count();
+
+        $driversOnline       = Driver::where('company_uuid', $companyUuid)
+            ->where('online', true)
+            ->whereNotNull('current_job_uuid')
+            ->count();
+
+        $totalDrivers        = Driver::where('company_uuid', $companyUuid)->count();
+
+        $vehiclesDeployed    = Vehicle::where('company_uuid', $companyUuid)
+            ->whereHas('driver', fn ($q) => $q->whereNotNull('current_job_uuid'))
+            ->count();
+
+        $totalVehicles       = Vehicle::where('company_uuid', $companyUuid)->count();
+
+        $issuesOpen          = Issue::where('company_uuid', $companyUuid)
+            ->where('status', 'pending')
+            ->count();
+
+        $todayStart          = Carbon::today();
+        $yesterdayStart      = Carbon::yesterday();
+        $todaySoFar          = Carbon::now();
+        $yesterdaySamePoint  = $yesterdayStart->copy()->setTime($todaySoFar->hour, $todaySoFar->minute);
+
+        $completedToday      = Order::where('company_uuid', $companyUuid)
+            ->where('status', 'completed')
+            ->whereBetween('updated_at', [$todayStart, $todaySoFar])
+            ->count();
+
+        $completedYesterdayToTime = Order::where('company_uuid', $companyUuid)
+            ->where('status', 'completed')
+            ->whereBetween('updated_at', [$yesterdayStart, $yesterdaySamePoint])
+            ->count();
+
+        return [
+            'active_orders'     => ['value' => $activeOrders, 'delta_pct' => null],
+            'completed_today'   => [
+                'value'     => $completedToday,
+                'delta_pct' => $this->deltaPct($completedToday, $completedYesterdayToTime),
+            ],
+            'drivers_online'    => [
+                'value'      => $driversOnline,
+                'of'         => $totalDrivers,
+                'pct_of_max' => $totalDrivers > 0 ? round(($driversOnline / $totalDrivers) * 100, 1) : 0.0,
+            ],
+            'vehicles_deployed' => [
+                'value'      => $vehiclesDeployed,
+                'of'         => $totalVehicles,
+                'pct_of_max' => $totalVehicles > 0 ? round(($vehiclesDeployed / $totalVehicles) * 100, 1) : 0.0,
+            ],
+            'issues_open'       => ['value' => $issuesOpen, 'delta_pct' => null],
+        ];
+    }
+
+    private function deltaPct(int $current, int $previous): ?float
+    {
+        if ($previous === 0) {
+            return $current > 0 ? 100.0 : null;
+        }
+
+        return round((($current - $previous) / $previous) * 100, 1);
+    }
+}

package/server/src/Support/Analytics/OrdersByStatus.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+/**
+ * Daily count of orders bucketed by status. One stacked bar per day, with
+ * a fixed status palette so the colour coding stays consistent over time.
+ */
+class OrdersByStatus extends AbstractAnalytics
+{
+    /** Status → display label + colour for stacked bars. */
+    private const STATUS_PALETTE = [
+        'completed'   => ['label' => 'Completed',   'color' => '#22c55e'],
+        'in_progress' => ['label' => 'In Progress', 'color' => '#3485e2'],
+        'dispatched'  => ['label' => 'Dispatched',  'color' => '#8b5cf6'],
+        'canceled'    => ['label' => 'Canceled',    'color' => '#ef4444'],
+        'failed'      => ['label' => 'Failed',      'color' => '#f59e0b'],
+    ];
+
+    public function get(): array
+    {
+        $start = $this->start ?? Carbon::now()->subDays(14)->toDateTime();
+        $end   = $this->end ?? Carbon::now()->toDateTime();
+
+        $rows = Order::where('company_uuid', $this->company->uuid)
+            ->whereBetween('created_at', [$start, $end])
+            ->whereIn('status', array_keys(self::STATUS_PALETTE))
+            ->selectRaw('DATE(created_at) as bucket, status, COUNT(*) as total')
+            ->groupBy('bucket', 'status')
+            ->orderBy('bucket')
+            ->get();
+
+        $cursor    = Carbon::instance($start)->startOfDay();
+        $endDay    = Carbon::instance($end)->startOfDay();
+        $labels    = [];
+        $byStatus  = array_fill_keys(array_keys(self::STATUS_PALETTE), []);
+
+        while ($cursor <= $endDay) {
+            $labels[] = $cursor->format('M j');
+            foreach (array_keys(self::STATUS_PALETTE) as $status) {
+                $match               = $rows->first(fn ($r) => $r->bucket === $cursor->format('Y-m-d') && $r->status === $status);
+                $byStatus[$status][] = $match ? (int) $match->total : 0;
+            }
+            $cursor->addDay();
+        }
+
+        $datasets = [];
+        foreach (self::STATUS_PALETTE as $status => $cfg) {
+            $datasets[] = [
+                'label'           => $cfg['label'],
+                'data'            => $byStatus[$status],
+                'backgroundColor' => $cfg['color'],
+            ];
+        }
+
+        return [
+            'labels'   => $labels,
+            'datasets' => $datasets,
+        ];
+    }
+}

package/server/src/Support/Analytics/RevenueTrend.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\Models\Transaction;
+use Illuminate\Support\Carbon;
+
+/**
+ * Time-series of revenue (sum of transactions) per bucket, filtered to the
+ * company's primary currency. Returns Chart.js-shaped { labels, datasets, summary }.
+ */
+class RevenueTrend extends AbstractAnalytics
+{
+    protected string $groupBy = 'day';
+
+    public function groupBy(string $unit): self
+    {
+        $this->groupBy = in_array($unit, ['day', 'week', 'month'], true) ? $unit : 'day';
+
+        return $this;
+    }
+
+    public function get(): array
+    {
+        $currency  = $this->companyCurrency();
+        $start     = $this->start ?? Carbon::now()->subDays(30)->toDateTime();
+        $end       = $this->end ?? Carbon::now()->toDateTime();
+
+        $format    = match ($this->groupBy) {
+            'week'  => '%x-W%v',
+            'month' => '%Y-%m',
+            default => '%Y-%m-%d',
+        };
+
+        $rows = Transaction::where('company_uuid', $this->company->uuid)
+            ->where('currency', $currency)
+            ->whereBetween('created_at', [$start, $end])
+            ->selectRaw('DATE_FORMAT(created_at, ?) as bucket, SUM(amount) as total', [$format])
+            ->groupBy('bucket')
+            ->orderBy('bucket')
+            ->get();
+
+        $labels = $rows->pluck('bucket')->all();
+        $data   = $rows->pluck('total')->map(fn ($v) => (float) $v)->all();
+        $total  = array_sum($data);
+
+        $duration       = $end->getTimestamp() - $start->getTimestamp();
+        $compareStart   = (clone $start);
+        $compareStart   = (new \DateTime())->setTimestamp($start->getTimestamp() - $duration);
+        $previousTotal  = (float) Transaction::where('company_uuid', $this->company->uuid)
+            ->where('currency', $currency)
+            ->whereBetween('created_at', [$compareStart, $start])
+            ->sum('amount');
+
+        $deltaPct = $previousTotal > 0
+            ? round((($total - $previousTotal) / $previousTotal) * 100, 1)
+            : ($total > 0 ? 100.0 : 0.0);
+
+        return [
+            'labels'   => $labels,
+            'datasets' => [
+                [
+                    'label'           => 'Revenue',
+                    'data'            => $data,
+                    'borderColor'     => '#3485e2',
+                    'backgroundColor' => 'rgba(52, 133, 226, 0.1)',
+                    'fill'            => true,
+                    'tension'         => 0.3,
+                ],
+            ],
+            'summary' => [
+                'total'     => round($total, 2),
+                'currency'  => $currency,
+                'delta_pct' => $deltaPct,
+            ],
+        ];
+    }
+}

package/server/src/Support/Analytics/TopDrivers.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Analytics;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Illuminate\Support\Carbon;
+
+/**
+ * Ranked driver leaderboard. Single GROUP BY join on orders → drivers so this
+ * scales without N+1 even on large fleets.
+ */
+class TopDrivers extends AbstractAnalytics
+{
+    protected int $limit     = 10;
+    protected string $sortBy = 'orders_completed';
+
+    public function limit(int $limit): self
+    {
+        $this->limit = max(1, min(50, $limit));
+
+        return $this;
+    }
+
+    public function sortBy(string $key): self
+    {
+        $this->sortBy = in_array($key, ['orders_completed', 'distance', 'on_time'], true)
+            ? $key
+            : 'orders_completed';
+
+        return $this;
+    }
+
+    public function get(): array
+    {
+        $start = $this->start ?? Carbon::now()->subDays(30)->toDateTime();
+        $end   = $this->end ?? Carbon::now()->toDateTime();
+
+        $sortColumn = match ($this->sortBy) {
+            'distance' => 'distance_m',
+            'on_time'  => 'on_time_pct',
+            default    => 'orders_completed',
+        };
+
+        // `drivers.name` and `drivers.photo_uuid` aren't real columns — they're
+        // virtual attributes that resolve via the related users row. Join users
+        // explicitly so we can SELECT them at the SQL level.
+        $rows = Order::where('orders.company_uuid', $this->company->uuid)
+            ->where('orders.status', 'completed')
+            ->whereNotNull('orders.driver_assigned_uuid')
+            ->whereBetween('orders.updated_at', [$start, $end])
+            ->join('drivers', 'drivers.uuid', '=', 'orders.driver_assigned_uuid')
+            ->join('users', 'users.uuid', '=', 'drivers.user_uuid')
+            ->groupBy('drivers.uuid', 'users.name', 'users.avatar_uuid')
+            ->selectRaw('
+                drivers.uuid as driver_uuid,
+                users.name as name,
+                users.avatar_uuid as avatar_uuid,
+                COUNT(orders.uuid) as orders_completed,
+                COALESCE(SUM(orders.distance), 0) as distance_m,
+                SUM(CASE
+                    WHEN orders.scheduled_at IS NOT NULL
+                     AND TIMESTAMPDIFF(SECOND, orders.scheduled_at, orders.updated_at) <= 1800
+                    THEN 1 ELSE 0 END) as on_time_count,
+                SUM(CASE WHEN orders.scheduled_at IS NOT NULL THEN 1 ELSE 0 END) as scheduled_count
+            ')
+            ->orderByRaw("{$sortColumn} DESC")
+            ->limit($this->limit)
+            ->get();
+
+        $result = $rows->map(function ($r) {
+            $scheduled = (int) $r->scheduled_count;
+            $onTimePct = $scheduled > 0
+                ? round(((int) $r->on_time_count / $scheduled) * 100, 1)
+                : null;
+
+            return [
+                'driver_uuid'      => $r->driver_uuid,
+                'name'             => $r->name,
+                'avatar_uuid'      => $r->avatar_uuid,
+                'orders_completed' => (int) $r->orders_completed,
+                'distance_m'       => (float) $r->distance_m,
+                'on_time_pct'      => $onTimePct,
+            ];
+        })->all();
+
+        return [
+            'rows'    => $result,
+            'sort_by' => $this->sortBy,
+        ];
+    }
+}

package/server/src/Support/CustomerAuth.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Laravel\Sanctum\PersonalAccessToken;
+
+/**
+ * Helper for resolving the authenticated customer from a request.
+ *
+ * The customer token is issued by `CustomerController` as a Sanctum
+ * `PersonalAccessToken` whose `name` column carries the owning Contact's UUID.
+ * Mirrors {@see \Fleetbase\Storefront\Support\Storefront::getCustomerFromToken}
+ * but with no Storefront-specific session.
+ */
+class CustomerAuth
+{
+    public const HEADER = 'Customer-Token';
+
+    public const APP_BINDING = 'currentCustomer';
+
+    /**
+     * Resolve the Contact represented by the `Customer-Token` header.
+     *
+     * Preference order when a User has more than one customer-type Contact:
+     *   1. Contact whose UUID matches the token's `name` column (Storefront convention).
+     *   2. Contact in the same company as the resolved API credential (`session('company')`).
+     *   3. The first remaining customer-type Contact for the token's User.
+     */
+    public static function resolveFromHeader(?Request $request = null): ?Contact
+    {
+        $request = $request ?? request();
+        $token   = $request->header(self::HEADER);
+        if (!$token) {
+            return null;
+        }
+
+        $accessToken = PersonalAccessToken::findToken($token);
+        if (!$accessToken) {
+            return null;
+        }
+
+        // Storefront convention: token name = Contact UUID.
+        if (is_string($accessToken->name) && Str::isUuid($accessToken->name)) {
+            $contact = Contact::where('uuid', $accessToken->name)
+                ->where('type', 'customer')
+                ->first();
+            if ($contact) {
+                return $contact;
+            }
+        }
+
+        // Fallback: pick the customer Contact bound to the token's user, preferring
+        // the same company as the API credential when available.
+        $userId         = $accessToken->tokenable_id ?? null;
+        $userIdentifier = $accessToken->tokenable->uuid ?? $userId;
+        if (!$userIdentifier) {
+            return null;
+        }
+
+        $contactQuery = Contact::where('user_uuid', $userIdentifier)
+            ->where('type', 'customer');
+
+        $sessionCompany = session('company');
+        if ($sessionCompany) {
+            $companyPreferred = (clone $contactQuery)
+                ->where('company_uuid', $sessionCompany)
+                ->first();
+            if ($companyPreferred) {
+                return $companyPreferred;
+            }
+        }
+
+        return $contactQuery->first();
+    }
+
+    /**
+     * Return the currently-bound customer (set by AuthenticateCustomerToken middleware).
+     */
+    public static function current(): ?Contact
+    {
+        return app()->bound(self::APP_BINDING) ? app(self::APP_BINDING) : null;
+    }
+
+    /**
+     * Bind the resolved customer for the current request lifecycle.
+     */
+    public static function setCurrent(Contact $contact): void
+    {
+        app()->instance(self::APP_BINDING, $contact);
+        session([
+            'customer_id' => $contact->uuid,
+            'contact_id'  => $contact->uuid,
+        ]);
+    }
+}

package/server/src/Support/LabelPdf.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Barryvdh\DomPDF\Facade\Pdf;
+
+class LabelPdf
+{
+    /**
+     * Create a PDF instance for FleetOps labels with UTF-8 and embedded-font
+     * options applied consistently across order, waypoint, and entity labels.
+     */
+    public static function fromHtml(string $html)
+    {
+        $pdf = Pdf::loadHTML($html, 'UTF-8');
+
+        if (method_exists($pdf, 'setOptions')) {
+            $pdf->setOptions(static::options());
+        }
+
+        if (method_exists($pdf, 'getDomPDF')) {
+            $dompdf = $pdf->getDomPDF();
+            foreach (static::dompdfOptions() as $key => $value) {
+                if (method_exists($dompdf, 'set_option')) {
+                    $dompdf->set_option($key, $value);
+                }
+            }
+        }
+
+        return $pdf;
+    }
+
+    public static function options(): array
+    {
+        return [
+            'defaultFont'             => 'DejaVu Sans',
+            'isHtml5ParserEnabled'    => true,
+            'isFontSubsettingEnabled' => true,
+            'isRemoteEnabled'         => false,
+        ];
+    }
+
+    public static function dompdfOptions(): array
+    {
+        return [
+            'defaultFont'             => 'DejaVu Sans',
+            'isHtml5ParserEnabled'    => true,
+            'isFontSubsettingEnabled' => true,
+            'isRemoteEnabled'         => false,
+        ];
+    }
+}