@fleetbase/fleetops-engine 0.6.58 → 0.6.60

package/server/tests/Unit/Support/Analytics/OnTimeDeliveryAndTopDriversTest.php

@@ -0,0 +1,250 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Analytics\OnTimeDelivery;
+use Fleetbase\FleetOps\Support\Analytics\OrdersByStatus;
+use Fleetbase\FleetOps\Support\Analytics\RevenueTrend;
+use Fleetbase\FleetOps\Support\Analytics\TopDrivers;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Models\Company;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+
+/**
+ * Covers the on-time delivery and top-driver analytics against SQLite via
+ * the driver-aware datetime-difference SQL helpers: SLA bucketing with
+ * comparison windows, driver leaderboards with on-time sorting, and the
+ * portable SQL expression builders themselves.
+ */
+function fleetopsAnalyticsBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'orders'  => ['uuid', 'public_id', 'company_uuid', 'driver_assigned_uuid', 'transaction_uuid', 'status', 'scheduled_at', 'distance'],
+        'drivers' => ['uuid', 'public_id', 'company_uuid', 'user_uuid'],
+        'users'   => ['uuid', 'public_id', 'company_uuid', 'name', 'avatar_uuid'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1']);
+
+    return $connection;
+}
+
+function fleetopsAnalyticsCompany(): Company
+{
+    $company = new Company();
+    $company->setRawAttributes(['uuid' => 'company-1', 'public_id' => 'company_analytics', 'name' => 'Analytics Co'], true);
+
+    return $company;
+}
+
+test('sql datetime helpers emit driver specific expressions', function () {
+    fleetopsAnalyticsBoot();
+
+    expect(Utils::sqlSecondsDiff('a', 'b'))->toContain('julianday')
+        ->and(Utils::sqlMinutesDiff('a', 'b'))->toContain('1440')
+        ->and(Utils::sqlNow())->toBe("datetime('now')")
+        ->and(Utils::sqlLeast('x', 'y'))->toBe('MIN(x, y)');
+});
+
+test('on time delivery buckets completed orders against the sla window', function () {
+    $connection = fleetopsAnalyticsBoot();
+    Carbon::setTestNow(Carbon::parse('2026-07-20 12:00:00'));
+
+    $connection->table('orders')->insert([
+        // On time: completed 10 minutes after schedule
+        ['uuid' => 'order-ontime', 'company_uuid' => 'company-1', 'status' => 'completed', 'scheduled_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 10:10:00', 'created_at' => '2026-07-15 09:00:00'],
+        // Late: completed 2 hours after schedule
+        ['uuid' => 'order-late', 'company_uuid' => 'company-1', 'status' => 'completed', 'scheduled_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 12:00:00', 'created_at' => '2026-07-15 09:00:00'],
+        // Excluded: no schedule
+        ['uuid' => 'order-unscheduled', 'company_uuid' => 'company-1', 'status' => 'completed', 'scheduled_at' => null, 'updated_at' => '2026-07-15 12:00:00', 'created_at' => '2026-07-15 09:00:00'],
+    ]);
+
+    $result = OnTimeDelivery::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->slaMinutes(30)
+        ->get();
+
+    expect($result['on_time'])->toBe(1)
+        ->and($result['late'])->toBe(1)
+        ->and($result['total'])->toBe(2)
+        ->and($result['on_time_pct'])->toBe(50.0)
+        ->and($result['sla_minutes'])->toBe(30);
+
+    Carbon::setTestNow();
+});
+
+test('top drivers rank completions with on time ratios on sqlite', function () {
+    $connection = fleetopsAnalyticsBoot();
+    Carbon::setTestNow(Carbon::parse('2026-07-20 12:00:00'));
+
+    $connection->table('users')->insert([
+        ['uuid' => 'user-a', 'company_uuid' => 'company-1', 'name' => 'Driver A'],
+        ['uuid' => 'user-b', 'company_uuid' => 'company-1', 'name' => 'Driver B'],
+    ]);
+    $connection->table('drivers')->insert([
+        ['uuid' => 'driver-a', 'company_uuid' => 'company-1', 'user_uuid' => 'user-a'],
+        ['uuid' => 'driver-b', 'company_uuid' => 'company-1', 'user_uuid' => 'user-b'],
+    ]);
+    $connection->table('orders')->insert([
+        ['uuid' => 'order-a1', 'company_uuid' => 'company-1', 'driver_assigned_uuid' => 'driver-a', 'status' => 'completed', 'scheduled_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 10:10:00', 'created_at' => '2026-07-15 09:00:00', 'distance' => '5000'],
+        ['uuid' => 'order-a2', 'company_uuid' => 'company-1', 'driver_assigned_uuid' => 'driver-a', 'status' => 'completed', 'scheduled_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 13:00:00', 'created_at' => '2026-07-15 09:00:00', 'distance' => '4000'],
+        ['uuid' => 'order-b1', 'company_uuid' => 'company-1', 'driver_assigned_uuid' => 'driver-b', 'status' => 'completed', 'scheduled_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 10:05:00', 'created_at' => '2026-07-15 09:00:00', 'distance' => '9000'],
+    ]);
+
+    $byCompletions = TopDrivers::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->limit(5)
+        ->get();
+    expect($byCompletions)->not->toBeEmpty();
+
+    $byOnTime = TopDrivers::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->sortBy('on_time')
+        ->limit(5)
+        ->get();
+    expect($byOnTime)->not->toBeEmpty();
+
+    $byDistance = TopDrivers::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->sortBy('distance')
+        ->limit(5)
+        ->get();
+    expect($byDistance)->not->toBeEmpty();
+
+    Carbon::setTestNow();
+});
+
+test('hos duration and geofence dwell expressions build portable sql', function () {
+    fleetopsAnalyticsBoot();
+
+    $controller = new Fleetbase\FleetOps\Http\Controllers\Internal\v1\DriverController();
+    $reflection = new ReflectionMethod($controller, 'hosDurationExpression');
+    $reflection->setAccessible(true);
+    $expression = (string) $reflection->invoke($controller)->getValue(EloquentModel::resolveConnection('mysql')->getQueryGrammar());
+
+    expect($expression)->toContain('julianday')
+        ->and($expression)->toContain('MIN(');
+});
+
+test('orders by status buckets daily counts with the fixed palette', function () {
+    $connection = fleetopsAnalyticsBoot();
+    Carbon::setTestNow(Carbon::parse('2026-07-20 12:00:00'));
+
+    $connection->table('orders')->insert([
+        ['uuid' => 'order-s1', 'company_uuid' => 'company-1', 'status' => 'completed', 'created_at' => '2026-07-15 09:00:00', 'updated_at' => '2026-07-15 09:00:00'],
+        ['uuid' => 'order-s2', 'company_uuid' => 'company-1', 'status' => 'completed', 'created_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 10:00:00'],
+        ['uuid' => 'order-s3', 'company_uuid' => 'company-1', 'status' => 'canceled', 'created_at' => '2026-07-16 10:00:00', 'updated_at' => '2026-07-16 10:00:00'],
+        ['uuid' => 'order-s4', 'company_uuid' => 'company-1', 'status' => 'draft', 'created_at' => '2026-07-16 10:00:00', 'updated_at' => '2026-07-16 10:00:00'],
+    ]);
+
+    $result = OrdersByStatus::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-14 00:00:00'), Carbon::parse('2026-07-17 00:00:00'))
+        ->get();
+
+    expect($result['labels'])->toBe(['Jul 14', 'Jul 15', 'Jul 16', 'Jul 17']);
+    $byLabel = collect($result['datasets'])->keyBy('label');
+    expect($byLabel['Completed']['data'])->toBe([0, 2, 0, 0])
+        ->and($byLabel['Canceled']['data'])->toBe([0, 0, 1, 0])
+        ->and($byLabel['Failed']['data'])->toBe([0, 0, 0, 0]);
+
+    Carbon::setTestNow();
+});
+
+test('revenue trend buckets transactions with weekly grouping and deltas', function () {
+    $connection = fleetopsAnalyticsBoot();
+    app()->instance('db.schema', $connection->getSchemaBuilder());
+    Illuminate\Support\Facades\Schema::clearResolvedInstance('db.schema');
+    $connection->getPdo()->sqliteCreateFunction('DATE_FORMAT', function ($date, $format) {
+        $map = ['%Y' => 'Y', '%m' => 'm', '%d' => 'd', '%x' => 'o', '%v' => 'W'];
+
+        return date(strtr($format, $map), strtotime((string) $date));
+    });
+    Carbon::setTestNow(Carbon::parse('2026-07-20 12:00:00'));
+
+    $schema = $connection->getSchemaBuilder();
+    $schema->create('transactions', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach (['uuid', 'public_id', 'company_uuid', 'customer_uuid', 'customer_type', 'subject_uuid', 'subject_type', 'context_uuid', 'context_type', 'parent_transaction_uuid', 'amount', 'currency', 'direction', 'status', 'meta', '_key'] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamp('voided_at')->nullable();
+        $blueprint->timestamp('reversed_at')->nullable();
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    $connection->table('transactions')->insert([
+        ['uuid' => 'txn-1', 'company_uuid' => 'company-1', 'amount' => '1000', 'currency' => 'USD', 'direction' => 'credit', 'status' => 'success', 'created_at' => '2026-07-14 10:00:00', 'updated_at' => '2026-07-14 10:00:00'],
+        ['uuid' => 'txn-2', 'company_uuid' => 'company-1', 'amount' => '2500', 'currency' => 'USD', 'direction' => 'credit', 'status' => 'success', 'created_at' => '2026-07-15 10:00:00', 'updated_at' => '2026-07-15 10:00:00'],
+        ['uuid' => 'txn-prev', 'company_uuid' => 'company-1', 'amount' => '500', 'currency' => 'USD', 'direction' => 'credit', 'status' => 'success', 'created_at' => '2026-07-05 10:00:00', 'updated_at' => '2026-07-05 10:00:00'],
+    ]);
+
+    $result = RevenueTrend::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->groupBy('week')
+        ->get();
+
+    expect($result['labels'])->not->toBeEmpty()
+        ->and(collect($result['datasets'][0]['data'])->sum())->toBeGreaterThan(0)
+        ->and($result['summary'])->toHaveKey('delta_pct');
+
+    // Invalid group-by units fall back to daily buckets
+    $daily = RevenueTrend::forCompany(fleetopsAnalyticsCompany())
+        ->between(Carbon::parse('2026-07-10 00:00:00'), Carbon::parse('2026-07-19 00:00:00'))
+        ->groupBy('hourly')
+        ->get();
+    expect($daily['labels'])->not->toBeEmpty();
+
+    Carbon::setTestNow();
+});
+
+test('abstract analytics resolves every period shorthand and defaults', function () {
+    Carbon::setTestNow(Carbon::parse('2026-07-20 12:00:00'));
+
+    foreach (['7d' => 7, '14d' => 14, '30d' => 30, '90d' => 90, '180d' => 180, '365d' => 365] as $period => $days) {
+        [$start, $end] = Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics::resolvePeriod($period, null, null);
+        expect(Carbon::instance($start)->toDateString())->toBe(Carbon::parse('2026-07-20')->subDays($days)->toDateString());
+    }
+
+    // Unknown periods fall through to explicit dates, then the default window
+    [$start, $end] = Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics::resolvePeriod('fortnight', Carbon::parse('2026-06-01')->toDateTime(), Carbon::parse('2026-06-10')->toDateTime());
+    expect(Carbon::instance($start)->toDateString())->toBe('2026-06-01');
+
+    [$start, $end] = Fleetbase\FleetOps\Support\Analytics\AbstractAnalytics::resolvePeriod(null, null, null, 10);
+    expect(Carbon::instance($start)->toDateString())->toBe('2026-07-10');
+
+    Carbon::setTestNow();
+});

package/server/tests/Unit/Support/CreateOrderPreviewDraftingTest.php

@@ -0,0 +1,235 @@
+<?php
+
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+use Fleetbase\FleetOps\Support\Ai\Capabilities\CreateOrderPreviewCapability;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * Covers the CreateOrderPreviewCapability drafting helpers against SQLite:
+ * prompt-to-draft conversion with quoted, from-to and labeled address
+ * extraction, place resolution through saved-place search, dispatch,
+ * scheduling, notes and proof-of-delivery detection, order-config, driver
+ * and vehicle resolution, controller response helpers, and pod method
+ * normalization.
+ */
+function fleetopsOrderPreviewBoot(): SQLiteConnection
+{
+    $pdo = new PDO('sqlite::memory:');
+    $pdo->sqliteCreateFunction('ST_PointFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $pdo->sqliteCreateFunction('ST_GeomFromText', fn ($wkt, $srid = 0, $axisOrder = null) => $wkt);
+    $connection = new SQLiteConnection($pdo);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    app()->instance('redis', new class {
+        public function get($key)
+        {
+            return null;
+        }
+
+        public function set($key, $value)
+        {
+            return true;
+        }
+
+        public function connection($name = null)
+        {
+            return $this;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    Illuminate\Support\Facades\Redis::clearResolvedInstance('redis');
+
+    app()->instance('geocoder', new class {
+        public function geocode($query)
+        {
+            return $this;
+        }
+
+        public function get()
+        {
+            return collect();
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this;
+        }
+    });
+
+    $schema = $connection->getSchemaBuilder();
+    $tables = [
+        'users'         => ['uuid', 'public_id', 'company_uuid', 'name', 'type', 'status'],
+        'companies'     => ['uuid', 'public_id', 'name', 'country'],
+        'places'        => ['uuid', 'public_id', 'company_uuid', 'name', 'street1', 'street2', 'city', 'province', 'postal_code', 'country', 'location', 'meta', 'type', '_key'],
+        'order_configs' => ['uuid', 'public_id', 'company_uuid', 'name', 'key', 'namespace', 'flow', 'entities', 'meta', 'version', 'core_service', 'status', 'type', '_key'],
+        'drivers'       => ['uuid', 'public_id', 'company_uuid', 'user_uuid', 'vehicle_uuid', 'location', 'online', 'status'],
+        'vehicles'      => ['uuid', 'public_id', 'company_uuid', 'name', 'plate_number', 'year', 'make', 'model', 'location', 'online', 'status'],
+    ];
+    foreach ($tables as $table => $columns) {
+        $schema->create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                if (in_array($column, ['online', 'core_service'], true)) {
+                    $blueprint->integer($column)->nullable();
+                    continue;
+                }
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-1', 'user' => 'admin-1']);
+    $connection->table('companies')->insert(['uuid' => 'company-1', 'name' => 'Acme', 'country' => 'SG']);
+    $connection->table('users')->insert(['uuid' => 'admin-1', 'company_uuid' => 'company-1', 'name' => 'Admin', 'type' => 'admin']);
+    $connection->table('order_configs')->insert([
+        'uuid'         => '66666666-6666-4666-8666-666666666666', 'public_id' => 'order_config_preview', 'company_uuid' => 'company-1',
+        'name'         => 'Transport', 'key' => 'transport', 'namespace' => 'system:order-config:transport',
+        'core_service' => 1, 'status' => 'active', 'version' => '0.0.1', 'flow' => '{}',
+    ]);
+
+    return $connection;
+}
+
+function fleetopsOrderPreviewCall(CreateOrderPreviewCapability $capability, string $method, ...$arguments): mixed
+{
+    $reflection = new ReflectionMethod(CreateOrderPreviewCapability::class, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invoke($capability, ...$arguments);
+}
+
+function fleetopsOrderPreviewWkb(float $lat, float $lng): string
+{
+    return pack('V', 0) . pack('C', 1) . pack('V', 1) . pack('d', $lng) . pack('d', $lat);
+}
+
+test('draft from prompt extracts addresses schedule notes and pod flags', function () {
+    $connection = fleetopsOrderPreviewBoot();
+    $connection->table('places')->insert([
+        ['uuid' => '11111111-1111-4111-8111-111111111111', 'public_id' => 'place_preview1', 'company_uuid' => 'company-1', 'name' => 'Warehouse A', 'street1' => '1 Industrial Way', 'city' => 'Singapore', 'country' => 'SG', 'location' => fleetopsOrderPreviewWkb(1.30, 103.80)],
+        // Both ends of the prompt resolve to saved places, so the draft carries
+        // a dropoff uuid rather than only the query it was asked about
+        ['uuid' => '77777777-7777-4777-8777-777777777777', 'public_id' => 'place_preview3', 'company_uuid' => 'company-1', 'name' => 'Depot B', 'street1' => '3 Depot Loop', 'city' => 'Singapore', 'country' => 'SG', 'location' => fleetopsOrderPreviewWkb(1.32, 103.82)],
+    ]);
+
+    $capability = new CreateOrderPreviewCapability();
+    $draft      = fleetopsOrderPreviewCall($capability, 'draftFromPrompt', 'Create an order from "Warehouse A" to "Depot B" and dispatch it 2 days from now with signature proof of delivery, notes: handle with care');
+
+    expect($draft['order_config_uuid'])->toBe('66666666-6666-4666-8666-666666666666')
+        ->and($draft['type'])->toBe('transport')
+        ->and($draft['payload']['pickup_query'])->toBe('Warehouse A')
+        ->and($draft['payload']['pickup_uuid'])->toBe('11111111-1111-4111-8111-111111111111')
+        ->and($draft['payload']['dropoff_query'])->toBe('Depot B')
+        ->and($draft['payload']['dropoff_uuid'])->toBe('77777777-7777-4777-8777-777777777777')
+        ->and($draft['dispatched'])->toBeTrue()
+        ->and($draft['scheduled_at'])->toBeString()
+        ->and($draft['notes'])->toBe('handle with care')
+        ->and($draft['pod_required'])->toBeTrue()
+        ->and($draft['pod_method'])->toBe('signature');
+});
+
+test('address pairs resolve quoted from-to and labeled phrasings', function () {
+    fleetopsOrderPreviewBoot();
+    $capability = new CreateOrderPreviewCapability();
+
+    expect(fleetopsOrderPreviewCall($capability, 'addressPairFromPrompt', 'order from "Alpha St 1" to "Beta Ave 2"'))->toBe(['Alpha St 1', 'Beta Ave 2'])
+        ->and(fleetopsOrderPreviewCall($capability, 'addressPairFromPrompt', 'create order from Alpha Street 1 to Beta Avenue 2 with pod'))->toBe(['Alpha Street 1', 'Beta Avenue 2'])
+        ->and(fleetopsOrderPreviewCall($capability, 'addressPairFromPrompt', 'order with pickup at Central Depot and dropoff at North Hub'))->toBe(['Central Depot', 'North Hub'])
+        ->and(fleetopsOrderPreviewCall($capability, 'addressPairFromPrompt', 'just make me an order'))->toBe([null, null]);
+
+    expect(fleetopsOrderPreviewCall($capability, 'cleanAddress', '  , and  Alpha   St ,'))->toBe('Alpha St')
+        ->and(fleetopsOrderPreviewCall($capability, 'cleanAddress', '  '))->toBeNull();
+});
+
+test('place resolution returns serialized saved places or null', function () {
+    $connection = fleetopsOrderPreviewBoot();
+    $connection->table('places')->insert([
+        ['uuid' => '22222222-2222-4222-8222-222222222222', 'public_id' => 'place_preview2', 'company_uuid' => 'company-1', 'name' => 'Central Depot', 'street1' => '2 Central Rd', 'city' => 'Singapore', 'country' => 'SG', 'location' => fleetopsOrderPreviewWkb(1.35, 103.85)],
+    ]);
+
+    $capability = new CreateOrderPreviewCapability();
+
+    $resolved = fleetopsOrderPreviewCall($capability, 'resolvePlace', 'Central Depot');
+    expect($resolved['uuid'])->toBe('22222222-2222-4222-8222-222222222222')
+        ->and($resolved['latitude'])->not->toBeNull();
+
+    expect(fleetopsOrderPreviewCall($capability, 'resolvePlace', null))->toBeNull()
+        ->and(fleetopsOrderPreviewCall($capability, 'resolvePlace', 'Nowhere Special'))->toBeNull();
+
+    $provisional = fleetopsOrderPreviewCall($capability, 'provisionalPlace', 'Somewhere New');
+    expect($provisional['source'])->toBe('unresolved')
+        ->and($provisional['address'])->toBe('Somewhere New');
+});
+
+test('controller helpers detect failed responses and unwrap orders', function () {
+    fleetopsOrderPreviewBoot();
+    $capability = new CreateOrderPreviewCapability();
+
+    expect(fleetopsOrderPreviewCall($capability, 'orderController'))->toBeInstanceOf(Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrderController::class)
+        ->and(fleetopsOrderPreviewCall($capability, 'orderResponseFailed', new JsonResponse(['error' => 'nope'], 422)))->toBeTrue()
+        ->and(fleetopsOrderPreviewCall($capability, 'orderResponseFailed', new JsonResponse(['ok' => true], 200)))->toBeFalse()
+        ->and(fleetopsOrderPreviewCall($capability, 'orderFromResponse', ['order' => 'order-1']))->toBe('order-1');
+});
+
+test('order config driver and vehicle resolution match identifiers', function () {
+    $connection = fleetopsOrderPreviewBoot();
+    $connection->table('drivers')->insert(['uuid' => '33333333-3333-4333-8333-333333333333', 'public_id' => 'driver_preview1', 'company_uuid' => 'company-1', 'user_uuid' => 'admin-1']);
+    $connection->table('vehicles')->insert(['uuid' => '44444444-4444-4444-8444-444444444444', 'public_id' => 'vehicle_preview1', 'company_uuid' => 'company-1', 'name' => 'Van 12', 'plate_number' => 'SGX1234A']);
+
+    $capability = new CreateOrderPreviewCapability();
+
+    expect(fleetopsOrderPreviewCall($capability, 'resolveOrderConfig', ['order_config_uuid' => '66666666-6666-4666-8666-666666666666'])?->uuid)->toBe('66666666-6666-4666-8666-666666666666')
+        ->and(fleetopsOrderPreviewCall($capability, 'resolveOrderConfig', [])?->uuid)->toBe('66666666-6666-4666-8666-666666666666');
+
+    expect(fleetopsOrderPreviewCall($capability, 'resolveDriver', ['driver' => '33333333-3333-4333-8333-333333333333'])?->uuid)->toBe('33333333-3333-4333-8333-333333333333')
+        ->and(fleetopsOrderPreviewCall($capability, 'resolveDriver', ['driver_query' => 'Admin'])?->uuid)->toBe('33333333-3333-4333-8333-333333333333')
+        ->and(fleetopsOrderPreviewCall($capability, 'resolveDriver', []))->toBeNull();
+
+    expect(fleetopsOrderPreviewCall($capability, 'resolveVehicle', ['vehicle' => 'SGX1234'])?->uuid)->toBe('44444444-4444-4444-8444-444444444444')
+        ->and(fleetopsOrderPreviewCall($capability, 'resolveVehicle', []))->toBeNull();
+});
+
+test('pod methods normalize configured strings and arrays', function () {
+    fleetopsOrderPreviewBoot();
+    $capability = new CreateOrderPreviewCapability();
+
+    config()->set('fleetops.pod_methods', 'scan, photo, scan');
+    expect(fleetopsOrderPreviewCall($capability, 'podMethods'))->toBe(['scan', 'photo']);
+
+    config()->set('fleetops.pod_methods', ['signature']);
+    expect(fleetopsOrderPreviewCall($capability, 'podMethods'))->toBe(['signature']);
+});

package/server/tests/Unit/Support/CustomerAuthTest.php

@@ -0,0 +1,132 @@
+<?php
+
+use Fleetbase\FleetOps\Support\CustomerAuth;
+use Illuminate\Http\Request;
+
+if (!class_exists('Fleetbase\FleetOps\Models\Contact', false)) {
+    eval('namespace Fleetbase\FleetOps\Models; class Contact { public static mixed $query = null; public static array $whereCalls = []; public function __construct(public ?string $uuid = null) {} public static function where(...$arguments): mixed { self::$whereCalls[] = $arguments; return self::$query; } }');
+}
+
+if (!class_exists('Laravel\Sanctum\PersonalAccessToken', false)) {
+    eval('namespace Laravel\Sanctum; class PersonalAccessToken { public static mixed $token = null; public static array $lookups = []; public static function findToken($token): mixed { self::$lookups[] = $token; return self::$token; } }');
+}
+
+class FleetOpsCustomerAuthFallbackQueryFake
+{
+    public array $calls = [];
+
+    public function __construct(private ArrayObject $firstResults)
+    {
+    }
+
+    public function where(...$arguments): self
+    {
+        $this->calls[] = ['where', $arguments];
+
+        return $this;
+    }
+
+    public function first(): mixed
+    {
+        $this->calls[] = ['first'];
+
+        foreach ($this->firstResults as $result) {
+            return $result;
+        }
+
+        return null;
+    }
+
+    public function __clone()
+    {
+        $this->calls[] = ['clone'];
+        foreach ($this->firstResults as $key => $result) {
+            $this->firstResults->offsetUnset($key);
+
+            break;
+        }
+    }
+}
+
+afterEach(function () {
+    app()->forgetInstance(CustomerAuth::APP_BINDING);
+    Laravel\Sanctum\PersonalAccessToken::$lookups  = [];
+    Laravel\Sanctum\PersonalAccessToken::$token    = null;
+    Fleetbase\FleetOps\Models\Contact::$whereCalls = [];
+    Fleetbase\FleetOps\Models\Contact::$query      = null;
+    session([
+        'company'     => null,
+        'customer_id' => null,
+        'contact_id'  => null,
+    ]);
+});
+
+function fleetopsCustomerAuthRequest(string $token): Request
+{
+    return Request::create('/customers/me', 'GET', [], [], [], [
+        'HTTP_CUSTOMER_TOKEN' => $token,
+    ]);
+}
+
+test('customer auth returns null when the customer token cannot be resolved', function () {
+    Laravel\Sanctum\PersonalAccessToken::$token = null;
+
+    expect(CustomerAuth::resolveFromHeader(fleetopsCustomerAuthRequest('missing-token')))->toBeNull()
+        ->and(Laravel\Sanctum\PersonalAccessToken::$lookups)->toBe(['missing-token'])
+        ->and(Fleetbase\FleetOps\Models\Contact::$whereCalls)->toBe([]);
+});
+
+test('customer auth prefers the session company customer when token name does not resolve a contact', function () {
+    session(['company' => 'company-preferred']);
+
+    $companyContact = new Fleetbase\FleetOps\Models\Contact('22222222-2222-4222-8222-222222222222');
+    $query          = new FleetOpsCustomerAuthFallbackQueryFake(new ArrayObject([
+        null,
+        $companyContact,
+    ]));
+
+    Laravel\Sanctum\PersonalAccessToken::$token = (object) [
+        'name'      => '11111111-1111-4111-8111-111111111111',
+        'tokenable' => (object) ['uuid' => 'user-uuid'],
+    ];
+    Fleetbase\FleetOps\Models\Contact::$query = $query;
+
+    expect(CustomerAuth::resolveFromHeader(fleetopsCustomerAuthRequest('token-with-user')))->toBe($companyContact)
+        ->and(Fleetbase\FleetOps\Models\Contact::$whereCalls)->toContain(
+            ['uuid', '11111111-1111-4111-8111-111111111111'],
+            ['user_uuid', 'user-uuid']
+        )
+        ->and($query->calls)->toContain(['where', ['type', 'customer']]);
+});
+
+test('customer auth falls back to the first customer for the tokenable id', function () {
+    $fallbackContact = new Fleetbase\FleetOps\Models\Contact('33333333-3333-4333-8333-333333333333');
+    $query           = new FleetOpsCustomerAuthFallbackQueryFake(new ArrayObject([$fallbackContact]));
+
+    Laravel\Sanctum\PersonalAccessToken::$token = (object) [
+        'name'         => 'api-token',
+        'tokenable_id' => 'numeric-user-id',
+        'tokenable'    => null,
+    ];
+    Fleetbase\FleetOps\Models\Contact::$query = $query;
+
+    expect(CustomerAuth::resolveFromHeader(fleetopsCustomerAuthRequest('token-by-user-id')))->toBe($fallbackContact)
+        ->and(Fleetbase\FleetOps\Models\Contact::$whereCalls)->toBe([
+            ['user_uuid', 'numeric-user-id'],
+        ])
+        ->and($query->calls)->toContain(
+            ['where', ['type', 'customer']],
+            ['first']
+        );
+});
+
+test('customer auth returns null when a token has no tokenable identity', function () {
+    Laravel\Sanctum\PersonalAccessToken::$token = (object) [
+        'name'         => 'api-token',
+        'tokenable_id' => null,
+        'tokenable'    => null,
+    ];
+
+    expect(CustomerAuth::resolveFromHeader(fleetopsCustomerAuthRequest('token-without-user')))->toBeNull()
+        ->and(Fleetbase\FleetOps\Models\Contact::$whereCalls)->toBe([]);
+});