@fleetbase/fleetops-engine 0.6.60 → 0.6.62

package/server/src/Http/Resources/v1/OrderConfig.php

@@ -41,10 +41,25 @@ class OrderConfig extends FleetbaseResource
     }
 
     /**
-     * Project the flow JSON into an ordered list of activities, keeping only
-     * the public-safe per-activity fields. `code` and `status` (the label)
-     * are the contract; `complete`, `color`, `details`, `pod_method`, and
-     * `require_pod` are useful UI hints that can ride along.
+     * Project the flow JSON into a list of activities, keeping the public-safe
+     * per-activity fields.
+     *
+     * `code` and `status` (the label) are the contract; `complete`, `color`,
+     * `details`, `pod_method` and `require_pod` are useful UI hints that ride
+     * along.
+     *
+     * `activities`, `sequence` and `logic` describe the flow's *shape*, and are
+     * published because without them the list cannot be sequenced. The stored
+     * flow is a directed graph — `activities` names the codes an activity can
+     * transition to, `sequence` orders activities reachable from the same
+     * parent, and `logic` gates availability — which is precisely what
+     * `OrderConfig::nextActivity()` walks server-side. Projecting them away
+     * left consumers with an unordered set: a client rendering progress from
+     * array position marks a dispatched order complete whenever `completed`
+     * happens to be declared earlier, and can offer no next step at all.
+     *
+     * These are descriptions of the configured workflow, not internal state, so
+     * there is nothing here a consumer of the config should not see.
      */
     protected function projectFlow(): array
     {
@@ -66,9 +81,41 @@ class OrderConfig extends FleetbaseResource
                 'complete'    => (bool) ($activity['complete'] ?? false),
                 'pod_method'  => $activity['pod_method'] ?? null,
                 'require_pod' => (bool) ($activity['require_pod'] ?? false),
+                'sequence'    => isset($activity['sequence']) ? (int) $activity['sequence'] : null,
+                'activities'  => static::projectTransitions($activity),
+                'logic'       => $activity['logic'] ?? null,
             ];
         }
 
         return $activities;
     }
+
+    /**
+     * The codes an activity can transition to, as a list of strings.
+     *
+     * Stored flows have been written both ways over time: a bare list of codes,
+     * and a list of objects carrying a `code`. Normalising here means consumers
+     * do not each have to guess which one they were handed.
+     */
+    protected static function projectTransitions(array $activity): array
+    {
+        $transitions = $activity['activities'] ?? [];
+        if (!is_array($transitions)) {
+            return [];
+        }
+
+        $codes = [];
+        foreach ($transitions as $transition) {
+            if (is_string($transition)) {
+                $codes[] = $transition;
+                continue;
+            }
+
+            if (is_array($transition) && isset($transition['code']) && is_string($transition['code'])) {
+                $codes[] = $transition['code'];
+            }
+        }
+
+        return $codes;
+    }
 }

package/server/src/Http/Resources/v1/Vehicle.php

@@ -2,12 +2,16 @@
 
 namespace Fleetbase\FleetOps\Http\Resources\v1;
 
+use Fleetbase\FleetOps\Http\Resources\v1\Concerns\ResolvesPublicRelationFields;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Resources\FleetbaseResource;
 use Fleetbase\Support\Http;
+use Fleetbase\Support\Resolve;
 
 class Vehicle extends FleetbaseResource
 {
+    use ResolvesPublicRelationFields;
+
     /**
      * Transform the resource into an array.
      *
@@ -17,6 +21,12 @@ class Vehicle extends FleetbaseResource
      */
     public function toArray($request)
     {
+        $with = $this->requestedRelations($request);
+
+        if ($with !== []) {
+            $this->loadMissing($with);
+        }
+
         return $this->withCustomFields([
             // Identity
             'id'                     => $this->when(Http::isInternalRequest(), $this->id, $this->public_id),
@@ -39,10 +49,24 @@ class Vehicle extends FleetbaseResource
             'description'            => $this->description,
             'driver_name'            => $this->when(Http::isInternalRequest(), $this->driver_name),
             'vendor_name'            => $this->when(Http::isInternalRequest(), $this->vendor_name),
-            'assigned_orders_count'  => $this->when(Http::isInternalRequest(), $this->assignedOrdersCount()),
-            'current_order_reference'=> $this->when(Http::isInternalRequest(), $this->currentOrderReference()),
-            // Relationships
-            'driver'                 => $this->whenLoaded('driver', fn () => new Driver($this->driver)),
+            'assigned_orders_count'  => $this->when(Http::isInternalRequest(), fn () => $this->assignedOrdersCount()),
+            'current_order_reference'=> $this->when(Http::isInternalRequest(), fn () => $this->currentOrderReference()),
+            // Relationships. The identifier is additive and always present so a
+            // write can be read back; the object beside it keeps the shape it
+            // has always had — absent unless loaded, an object when it is.
+            'driver_id'              => $this->publicIdForRelation('driver', null),
+            'vendor_id'              => $this->publicIdForRelation('vendor', 'vendor_uuid'),
+            'category_id'            => $this->publicIdForRelation('category', 'category_uuid'),
+            'warranty_id'            => $this->publicIdForRelation('warranty', 'warranty_uuid'),
+            'photo_id'               => $this->publicIdForRelation('photo', 'photo_uuid'),
+            'driver'                 => $this->publicRelationObject('driver', $with, fn () => new Driver($this->driver)),
+            'vendor'                 => $this->publicRelationObject('vendor', $with, fn () => new Vendor($this->vendor)),
+            // Resolved through the repository's own resource resolver rather than
+            // a hardcoded class: Category and File live in core, and Warranty has
+            // no v1 resource of its own.
+            'category'               => $this->publicRelationObject('category', $with, fn () => Resolve::httpResourceForModel($this->category)),
+            'warranty'               => $this->publicRelationObject('warranty', $with, fn () => Resolve::httpResourceForModel($this->warranty)),
+            'photo'                  => $this->publicRelationObject('photo', $with, fn () => Resolve::httpResourceForModel($this->photo)),
             'devices'                => $this->whenLoaded('devices', fn () => $this->devices),
             // Vehicle identification
             'make'                   => $this->make,
@@ -139,6 +163,15 @@ class Vehicle extends FleetbaseResource
             'altitude'               => (int) data_get($this, 'altitude', 0),
             'speed'                  => (int) data_get($this, 'speed', 0),
             'telematics'             => data_get($this, 'telematics'),
+            // Orchestrator constraints
+            'skills'                   => data_get($this, 'skills'),
+            'payload_capacity_volume'  => $this->payload_capacity_volume,
+            'payload_capacity_pallets' => $this->payload_capacity_pallets,
+            'payload_capacity_parcels' => $this->payload_capacity_parcels,
+            'max_tasks'                => $this->max_tasks,
+            'time_window_start'        => $this->time_window_start,
+            'time_window_end'          => $this->time_window_end,
+            'return_to_depot'          => $this->return_to_depot,
             // Notes & meta
             'notes'                  => $this->notes,
             'meta'                   => data_get($this, 'meta', Utils::createObject()),
@@ -273,6 +306,15 @@ class Vehicle extends FleetbaseResource
             'vin_data'                    => data_get($this, 'vin_data', Utils::createObject()),
             'specs'                       => data_get($this, 'specs', Utils::createObject()),
             'details'                     => data_get($this, 'details', Utils::createObject()),
+            // Orchestrator constraints
+            'skills'                     => data_get($this, 'skills'),
+            'payload_capacity_volume'    => $this->payload_capacity_volume,
+            'payload_capacity_pallets'   => $this->payload_capacity_pallets,
+            'payload_capacity_parcels'   => $this->payload_capacity_parcels,
+            'max_tasks'                  => $this->max_tasks,
+            'time_window_start'          => $this->time_window_start,
+            'time_window_end'            => $this->time_window_end,
+            'return_to_depot'            => $this->return_to_depot,
             // Notes & meta
             'notes'                      => $this->notes,
             'meta'                       => data_get($this, 'meta', Utils::createObject()),

package/server/src/Models/Driver.php

@@ -110,7 +110,7 @@ class Driver extends Model
         'current_status',
         'slug',
         'status',
-        'meta,',
+        'meta',
         // Orchestrator
         'skills',
         'max_travel_time',
@@ -255,7 +255,7 @@ class Driver extends Model
      */
     public function user()
     {
-        return $this->belongsTo(User::class)->select(['uuid', 'company_uuid', 'public_id', 'avatar_uuid', 'name', 'phone', 'email', 'type', 'status', 'last_login'])->without(['driver'])->withTrashed();
+        return $this->belongsTo(User::class)->select(['uuid', 'company_uuid', 'public_id', 'avatar_uuid', 'name', 'phone', 'email', 'timezone', 'type', 'status', 'last_login'])->without(['driver'])->withTrashed();
     }
 
     /**

package/server/src/Models/Place.php

@@ -129,7 +129,7 @@ class Place extends Model
      *
      * @var array
      */
-    protected $filterParams = ['vendor', 'contact', 'vendor_uuid', 'vendor_name'];
+    protected $filterParams = ['vendor', 'contact', 'vendor_uuid', 'vendor_name', 'avatar_value', 'eta'];
 
     /**
      * @return \Illuminate\Database\Eloquent\Relations\MorphTo

package/server/src/routes.php

@@ -28,6 +28,13 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                 $router->post('login-with-sms', 'DriverController@loginWithPhone');
                 $router->post('verify-code', 'DriverController@verifyCode');
                 $router->post('login', 'DriverController@login');
+                // Password management. Deliberately separate from the driver
+                // update: changing a password requires proving the old one, and
+                // resetting it requires a code, neither of which a general PUT
+                // can express.
+                $router->post('forgot-password', 'DriverController@forgotPassword');
+                $router->post('reset-password', 'DriverController@resetPassword');
+                $router->post('{id}/change-password', 'DriverController@changePassword');
                 $router->post('{id}/simulate', 'DriverController@simulate');
                 $router->match(['put', 'patch', 'post'], '{id}/track', 'DriverController@track');
                 $router->post('{id}/register-device', 'DriverController@registerDevice');
@@ -37,6 +44,8 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                 $router->get('/', 'DriverController@query');
                 $router->get('{id}', 'DriverController@find');
                 $router->get('{id}/organizations', 'DriverController@listOrganizations');
+                // A driver's own routes for the day.
+                $router->get('{id}/manifests', 'ManifestController@forDriver');
                 $router->get('{id}/current-organization', 'DriverController@currentOrganization');
                 $router->put('{id}', 'DriverController@update');
                 $router->delete('{id}', 'DriverController@delete');
@@ -185,6 +194,18 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                 $router->delete('{id}', 'OrderController@delete');
                 $router->get('{id}/editable-entity-fields', 'OrderController@getEditableEntityFields');
             });
+            // manifests — a driver's route. Read and run only: creating,
+            // cancelling and deleting a manifest is dispatch work and stays on
+            // the internal namespace.
+            $router->group(['prefix' => 'manifests'], function () use ($router) {
+                $router->get('{id}', 'ManifestController@show');
+                $router->post('{id}/optimize', 'ManifestController@optimize');
+            });
+            $router->group(['prefix' => 'manifest-stops'], function () use ($router) {
+                $router->patch('{id}', 'ManifestController@updateStop');
+                $router->post('{id}', 'ManifestController@updateStop');
+            });
+
             // entities routes
             $router->group(['prefix' => 'entities'], function () use ($router) {
                 $router->post('/', 'EntityController@create');
@@ -281,6 +302,14 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
             $router->group(['prefix' => 'fleets'], function () use ($router) {
                 $router->post('/', 'FleetController@create');
                 $router->get('/', 'FleetController@query');
+                // Membership routes are declared ahead of the `{id}` routes so a
+                // literal `vehicles`/`drivers` segment can never be swallowed by
+                // the single-parameter patterns below. Both parameters are public
+                // ids; no internal uuid is ever accepted or returned here.
+                $router->post('{id}/vehicles/{vehicle}', 'FleetController@assignVehicle');
+                $router->delete('{id}/vehicles/{vehicle}', 'FleetController@removeVehicle');
+                $router->post('{id}/drivers/{driver}', 'FleetController@assignDriver');
+                $router->delete('{id}/drivers/{driver}', 'FleetController@removeDriver');
                 $router->get('{id}', 'FleetController@find');
                 $router->put('{id}', 'FleetController@update');
                 $router->delete('{id}', 'FleetController@delete');

package/server/tests/ApiDriverControllerContractsTest.php

@@ -4,7 +4,9 @@ use Fleetbase\FleetOps\Http\Controllers\Api\v1\DriverController;
 use Fleetbase\FleetOps\Http\Requests\CreateDriverRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateDriverRequest;
 use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
 use Fleetbase\Models\Company;
 use Fleetbase\Models\User;
@@ -29,6 +31,9 @@ class FleetOpsApiDriverControllerProbe extends DriverController
     public array $companyCalls              = [];
     public array $createdUsers              = [];
     public array $uuidLookups               = [];
+    public array $relationLookups           = [];
+    public array $relationCompanyScopes     = [];
+    public array $unresolvable              = [];
     public array $pointInputs               = [];
     public array $createdDrivers            = [];
     public array $resolvedFiles             = [];
@@ -76,6 +81,33 @@ class FleetOpsApiDriverControllerProbe extends DriverController
         return $table . '-uuid';
     }
 
+    /**
+     * Stand in for the company-scoped public-id lookup.
+     *
+     * Anything listed in `$unresolvable` behaves as a cross-company or missing
+     * identifier does in production.
+     */
+    protected function resolveUuid(string $modelClass, ?string $id, ?string $companyUuid = null): ?string
+    {
+        if (empty($id)) {
+            return null;
+        }
+
+        $this->relationLookups[]       = [$modelClass, $id];
+        $this->relationCompanyScopes[] = $companyUuid;
+
+        if (in_array($id, $this->unresolvable, true)) {
+            throw (new ModelNotFoundException())->setModel($modelClass, $id);
+        }
+
+        return strtolower(class_basename($modelClass)) . '-uuid';
+    }
+
+    public function inputForTest(Request $request): array
+    {
+        return $this->driverInputFromRequest($request);
+    }
+
     protected function pointFromCoordinates(array $coordinates): Point
     {
         $this->pointInputs[] = $coordinates;
@@ -343,21 +375,23 @@ test('api driver controller creates drivers with user company assignment and rel
         ->and($controller->user->assignedRoles)->toBe(['Driver'])
         ->and($controller->createdDrivers[0])->toMatchArray([
             'status'           => 'available',
-            'vehicle_uuid'     => 'vehicles-uuid',
-            'vendor_uuid'      => 'vendors-uuid',
-            'current_job_uuid' => 'orders-uuid',
+            'vehicle_uuid'     => 'vehicle-uuid',
+            'vendor_uuid'      => 'vendor-uuid',
+            'current_job_uuid' => 'order-uuid',
             'online'           => 0,
             'user_uuid'        => 'user-uuid',
             'company_uuid'     => 'company-uuid',
         ])
         ->and($controller->createdDrivers[0]['location'])->toBeInstanceOf(Point::class)
-        ->and($controller->uuidLookups)->toContain(
-            ['vehicles', ['public_id' => 'vehicle_public', 'company_uuid' => 'company-uuid'], []],
-            ['vendors', ['public_id' => 'vendor_public', 'company_uuid' => 'company-uuid'], []],
-            ['orders', ['public_id'  => 'order_public', 'company_uuid' => 'company-uuid'], []]
-        )
+        ->and($controller->relationLookups)->toBe([
+            [Vehicle::class, 'vehicle_public'],
+            [Vendor::class, 'vendor_public'],
+            [Order::class, 'order_public'],
+        ])
         ->and($controller->resolvedFiles)->toBe([['file_public', 'uploads/company-uuid/drivers']])
-        ->and($controller->user->updates)->toContain(['photo_uuid' => 'photo-file-uuid'])
+        // `photo_uuid` is not a column on users; the avatar lives in `avatar_uuid`
+        // and the old key was silently dropped by mass assignment.
+        ->and($controller->user->updates)->toContain(['avatar_uuid' => 'photo-file-uuid'])
         ->and($controller->driver->loaded)->toContain(['user', 'vehicle', 'vendor', 'currentJob']);
 });
 
@@ -411,14 +445,14 @@ test('api driver controller updates drivers user details assignments location an
         ])
         ->and($driver->updates[0])->toMatchArray([
             'status'           => 'busy',
-            'vehicle_uuid'     => 'vehicles-uuid',
-            'vendor_uuid'      => 'vendors-uuid',
-            'current_job_uuid' => 'orders-uuid',
+            'vehicle_uuid'     => 'vehicle-uuid',
+            'vendor_uuid'      => 'vendor-uuid',
+            'current_job_uuid' => 'order-uuid',
         ])
         ->and($driver->updates[0]['location'])->toBeInstanceOf(Point::class)
         ->and($driver->flushedForTest)->toBeTrue()
         ->and($controller->resolvedFiles)->toBe([['photo-input', 'uploads/session-company-uuid/drivers']])
-        ->and($user->updates)->toContain(['photo_uuid' => 'photo-file-uuid'])
+        ->and($user->updates)->toContain(['avatar_uuid' => 'photo-file-uuid'])
         ->and($driver->loaded)->toContain(['user', 'vehicle', 'vendor', 'currentJob']);
 });
 
@@ -601,3 +635,273 @@ test('api driver controller reports missing driver branches', function () {
             'status'   => 404,
         ]);
 });
+
+test('api driver controller refuses to set a password through a general update', function () {
+    /*
+     * Regression for a takeover path: `update()` passed `password` straight
+     * through to the user, so anyone holding a driver's token — or an unlocked
+     * handset — could set a new one without proving they knew the old one, and
+     * the account was theirs. A password change is an authorisation decision
+     * and now has its own endpoint that demands the current password.
+     */
+    $user = new FleetOpsApiDriverUserFake();
+    $user->setRawAttributes(['uuid' => 'user-uuid'], true);
+    $driver = new FleetOpsApiDriverFake();
+    $driver->setRawAttributes([
+        'uuid'      => 'driver-uuid',
+        'public_id' => 'driver_public',
+        'user_uuid' => 'user-uuid',
+    ], true);
+    $driver->userForTest = $user;
+    $driver->setRelation('user', $user);
+
+    $controller                     = new FleetOpsApiDriverControllerProbe();
+    $controller->driver             = $driver;
+    $controller->sessionCompanyUuid = 'session-company-uuid';
+
+    $controller->update('driver_public', new UpdateDriverRequest([
+        'name'     => 'Driver Updated',
+        'password' => 'attacker-chosen-password',
+    ]));
+
+    expect($user->updates)->not->toBeEmpty()
+        ->and($user->updates[0])->not->toHaveKey('password')
+        ->and($user->updates[0])->toHaveKey('name');
+});
+
+test('api driver controller accepts every safe driver field the model exposes', function () {
+    $payload = [
+        // Identity
+        'internal_id'    => 'DRV-9001', 'drivers_license_number' => 'S1234567A',
+        'license_expiry' => '2030-06-30',
+        // Operational
+        'country'        => 'SG', 'currency' => 'SGD', 'city' => 'Singapore', 'online' => true,
+        'current_status' => 'on_break', 'status' => 'available',
+        'heading'        => 180, 'bearing' => 90, 'altitude' => 15, 'speed' => 42,
+        // Structured / orchestrator
+        'meta'              => ['depot' => 'north'], 'skills' => ['hazmat'],
+        'max_travel_time'   => 28800, 'max_distance' => 250000,
+        'time_window_start' => '08:00', 'time_window_end' => '18:00',
+    ];
+
+    $controller = new FleetOpsApiDriverControllerProbe();
+    $input      = $controller->inputForTest(new Request($payload));
+
+    $missing = array_values(array_diff(array_keys($payload), array_keys($input)));
+
+    expect($missing)->toBe([])
+        ->and($input)->toMatchArray($payload);
+});
+
+test('api driver controller input excludes authentication tenancy and generated columns', function () {
+    // The projection used to be an `except()` blocklist, so anything nobody had
+    // thought to name reached Driver::create() intact — including the auth token.
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $input = $controller->inputForTest(new Request([
+        'internal_id'       => 'DRV-1',
+        'auth_token'        => 'forged',
+        'signup_token_used' => true,
+        'user_uuid'         => 'forged',
+        'company_uuid'      => 'someone-elses-company',
+        'vehicle_uuid'      => 'forged',
+        'vendor_uuid'       => 'forged',
+        'current_job_uuid'  => 'forged',
+        '_key'              => 'forged',
+        'uuid'              => 'forged',
+        'public_id'         => 'driver_forged',
+        'slug'              => 'forged',
+        'avatar_url'        => 'forged',
+    ]));
+
+    expect(array_keys($input))->toBe(['internal_id']);
+});
+
+test('api driver controller persists meta location and telemetry that the blocklist used to drop', function () {
+    // `location`, `heading`, `altitude`, `speed` and `meta` were all on the old
+    // `except()` list, so every write silently discarded them — and `meta` could
+    // not be mass assigned anyway because the model spelled it `meta,`.
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $input = $controller->inputForTest(new Request([
+        'meta'     => ['badge' => 'A12'],
+        'heading'  => 270,
+        'altitude' => 8,
+        'speed'    => 55,
+    ]));
+
+    expect($input)->toMatchArray([
+        'meta'     => ['badge' => 'A12'],
+        'heading'  => 270,
+        'altitude' => 8,
+        'speed'    => 55,
+    ])->and(in_array('meta', (new Driver())->getFillable(), true))->toBeTrue();
+});
+
+test('api driver controller creates an operational driver with no email or phone', function () {
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $response = $controller->create(new CreateDriverRequest([
+        'name'        => 'Yard Driver',
+        'internal_id' => 'DRV-7788',
+    ]));
+
+    // No invented address, no invented number: the user record simply carries
+    // neither, which the users table permits. The driver cannot sign in to
+    // Navigator until credentials are supplied.
+    expect($response)->toBe(['resource' => 'driver', 'driver' => $controller->driver])
+        ->and($controller->createdUsers[0])->toMatchArray(['name' => 'Yard Driver'])
+        ->and($controller->createdUsers[0]['email'] ?? null)->toBeNull()
+        ->and($controller->createdUsers[0]['phone'] ?? null)->toBeNull()
+        ->and($controller->createdDrivers[0])->toMatchArray([
+            'internal_id'  => 'DRV-7788',
+            'user_uuid'    => 'user-uuid',
+            'company_uuid' => 'company-uuid',
+            'status'       => 'available',
+        ])
+        // The Driver-to-User relationship, organization membership, user type
+        // and role are all preserved for a credential-less driver.
+        ->and($controller->user->assignedCompanies)->toBe(['company-uuid'])
+        ->and($controller->user->assignedTypes)->toBe(['driver'])
+        ->and($controller->user->assignedRoles)->toBe(['Driver']);
+});
+
+test('api driver controller creates a driver with only one contact method', function () {
+    $emailOnly = new FleetOpsApiDriverControllerProbe();
+    $emailOnly->create(new CreateDriverRequest([
+        'name'  => 'Email Only',
+        'email' => 'email.only@example.test',
+    ]));
+
+    $phoneOnly = new FleetOpsApiDriverControllerProbe();
+    $phoneOnly->create(new CreateDriverRequest([
+        'name'  => 'Phone Only',
+        'phone' => '+15550001111',
+    ]));
+
+    expect($emailOnly->createdUsers[0])->toMatchArray(['email' => 'email.only@example.test'])
+        ->and($emailOnly->createdUsers[0]['phone'] ?? null)->toBeNull()
+        ->and($phoneOnly->createdUsers[0])->toMatchArray(['phone' => '+15550001111'])
+        ->and($phoneOnly->createdUsers[0]['email'] ?? null)->toBeNull();
+});
+
+test('api driver controller rejects a relationship that belongs to another company', function () {
+    $controller               = new FleetOpsApiDriverControllerProbe();
+    $controller->unresolvable = ['vehicle_other_company'];
+
+    $created = $controller->create(new CreateDriverRequest([
+        'name'    => 'Driver One',
+        'vehicle' => 'vehicle_other_company',
+    ]));
+
+    $controller               = new FleetOpsApiDriverControllerProbe();
+    $controller->unresolvable = ['vendor_other_company'];
+
+    $updated = $controller->update('driver_public', new UpdateDriverRequest([
+        'vendor' => 'vendor_other_company',
+    ]));
+
+    expect($created)->toBe([
+        'json'   => ['error' => 'No vehicle resource found for the identifier provided.'],
+        'status' => 404,
+    ])->and($updated)->toBe([
+        'json'   => ['error' => 'No vendor resource found for the identifier provided.'],
+        'status' => 404,
+    ]);
+});
+
+test('api driver controller clears a relationship when the input is sent empty', function () {
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $input = $controller->inputForTest(new Request(['vehicle' => null, 'vendor' => '', 'job' => null]));
+
+    expect($input)->toMatchArray([
+        'vehicle_uuid'     => null,
+        'vendor_uuid'      => null,
+        'current_job_uuid' => null,
+    ])->and($controller->relationLookups)->toBe([]);
+});
+
+test('api driver controller resolves driver relationships inside the company the driver is created in', function () {
+    // A create request may name a company explicitly, and the relationships must
+    // be looked up in that company rather than in whatever the session holds.
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $controller->create(new CreateDriverRequest([
+        'company' => 'company_public',
+        'name'    => 'Driver One',
+        'vehicle' => 'vehicle_public',
+        'vendor'  => 'vendor_public',
+    ]));
+
+    expect($controller->relationCompanyScopes)->toBe(['company-uuid', 'company-uuid']);
+});
+
+test('api driver controller keeps every relationship the base contract returned', function () {
+    // The SDK stores what the API returns verbatim, and Navigator interpolates
+    // `driver.user` straight into a socket channel name — an object there would
+    // subscribe it to `user.[object Object]` and quietly stop delivering
+    // messages. These endpoints have always loaded user, vehicle, vendor and
+    // currentJob, so they must keep doing it without a `with` parameter.
+    $controller = new FleetOpsApiDriverControllerProbe();
+
+    $controller->create(new CreateDriverRequest([
+        'name'    => 'Driver One',
+        'vehicle' => 'vehicle_public',
+        'vendor'  => 'vendor_public',
+        'job'     => 'order_public',
+    ]));
+
+    expect($controller->driver->loaded)->toContain(['user', 'vehicle', 'vendor', 'currentJob']);
+
+    $updateController         = new FleetOpsApiDriverControllerProbe();
+    $updateController->update('driver_public', new UpdateDriverRequest(['name' => 'Renamed']));
+
+    expect($updateController->driver->loaded)->toContain(['user', 'vehicle', 'vendor', 'currentJob'])
+        ->and($updateController->findCalls)->toContain(['driver_public', ['user']]);
+});
+
+test('api driver controller copies timezone through to the linked user account', function () {
+    // `timezone` is documented and accepted on both create and update, but the
+    // update only ever copied name, email and phone — so the request validated,
+    // answered 200, and dropped it. The driver has no timezone column; the
+    // linked user does.
+    $create = new FleetOpsApiDriverControllerProbe();
+    $create->create(new CreateDriverRequest([
+        'name'     => 'Driver One',
+        'timezone' => 'Asia/Singapore',
+    ]));
+
+    $user = new FleetOpsApiDriverUserFake();
+    $user->setRawAttributes(['uuid' => 'user-uuid'], true);
+
+    $driver = new FleetOpsApiDriverFake();
+    $driver->setRawAttributes(['uuid' => 'driver-uuid', 'public_id' => 'driver_public', 'user_uuid' => 'user-uuid'], true);
+    $driver->userForTest = $user;
+    $driver->setRelation('user', $user);
+
+    $update         = new FleetOpsApiDriverControllerProbe();
+    $update->driver = $driver;
+    $update->update('driver_public', new UpdateDriverRequest([
+        'name'     => 'Driver One',
+        'timezone' => 'Europe/Amsterdam',
+    ]));
+
+    expect($create->createdUsers[0])->toMatchArray(['timezone' => 'Asia/Singapore'])
+        ->and($user->updates)->toContain([
+            'name'     => 'Driver One',
+            'timezone' => 'Europe/Amsterdam',
+        ]);
+});
+
+test('api driver controller only expands relationships the public contract allows', function () {
+    $controller = new FleetOpsApiDriverControllerProbe();
+    $request    = new CreateDriverRequest(['name' => 'Driver One', 'with' => ['vehicle', 'current_job', 'user', 'company', 'nope']]);
+
+    $controller->create($request);
+
+    // `user` and `company` are published as public-id strings. Expanding either
+    // would retype a released field, so neither is expandable at all; an unknown
+    // name is dropped rather than reaching Eloquent, where it would be a 500.
+    expect($request->input('with'))->toBe(['vehicle', 'currentJob']);
+});