@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/tests/ApiDriverPasswordContractsTest.php

@@ -130,12 +130,13 @@ class FleetOpsPasswordDriverFake extends Driver
 
 class FleetOpsPasswordControllerProbe extends DriverController
 {
-    public static ?Driver $driver     = null;
-    public static bool $driverMissing = false;
-    public static ?User $identityUser = null;
-    public static mixed $resetCode    = null;
-    public static array $sentCodes    = [];
-    public static bool $sendThrows    = false;
+    public static ?Driver $driver         = null;
+    public static bool $driverMissing     = false;
+    public static ?User $identityUser     = null;
+    public static mixed $resetCode        = null;
+    public static array $sentCodes        = [];
+    public static bool $sendThrows        = false;
+    public static ?Throwable $sendRefusal = null;
 
     public function findDriver(string $id, array $with = []): Driver
     {
@@ -180,6 +181,9 @@ class FleetOpsPasswordControllerProbe extends DriverController
 
     protected static function sendResetCode(User $user, string $identity): void
     {
+        if (static::$sendRefusal) {
+            throw static::$sendRefusal;
+        }
         if (static::$sendThrows) {
             throw new RuntimeException('sms gateway down');
         }
@@ -205,6 +209,7 @@ beforeEach(function () {
     FleetOpsPasswordControllerProbe::$resetCode     = null;
     FleetOpsPasswordControllerProbe::$sentCodes     = [];
     FleetOpsPasswordControllerProbe::$sendThrows    = false;
+    FleetOpsPasswordControllerProbe::$sendRefusal   = null;
 });
 
 test('change password requires both the current and the new one', function () {
@@ -331,6 +336,16 @@ test('forgot password reports a delivery failure rather than pretending it sent'
     expect($response->getStatusCode())->toBe(400);
 });
 
+test('forgot password passes an sms guard refusal through with its status', function () {
+    FleetOpsPasswordControllerProbe::$identityUser = fleetopsPasswordUser();
+    FleetOpsPasswordControllerProbe::$sendRefusal  = Fleetbase\Exceptions\SmsBlockedException::limited('destination_cooldown', 30);
+
+    $response = (new FleetOpsPasswordControllerProbe())->forgotPassword(new Request(['identity' => '+6581000001']));
+
+    expect($response->getStatusCode())->toBe(429)
+        ->and($response->getData())->toBe(['error' => 'Unable to send a verification code right now. Try again in a minute.']);
+});
+
 test('reset password requires identity, code and a new password', function () {
     $response = (new FleetOpsPasswordControllerProbe())->resetPassword(new Request(['identity' => 'a@b.test']));
 
@@ -362,23 +377,13 @@ test('reset password gives one answer for an unknown identity and a bad code ali
         ->and($unknownIdentity->getData())->toBe($badCode->getData());
 });
 
-test('reset password sets the password, spends the code, and ends every session', function () {
+test('reset password sets the password and ends every session once the code verified', function () {
     $user                                          = fleetopsPasswordUser();
     FleetOpsPasswordControllerProbe::$identityUser = $user;
 
-    $deleted                                    = false;
-    FleetOpsPasswordControllerProbe::$resetCode = new class($deleted) {
-        public function __construct(public bool &$deleted)
-        {
-        }
-
-        public function delete(): bool
-        {
-            $this->deleted = true;
-
-            return true;
-        }
-    };
+    // findResetCode() hands back the code it verified and used up; nothing more is done
+    // to it here.
+    FleetOpsPasswordControllerProbe::$resetCode = (object) ['uuid' => 'reset-code'];
 
     $response = (new FleetOpsPasswordControllerProbe())->resetPassword(
         new Request(['identity' => 'driver@example.test', 'code' => '123456', 'password' => 'newpassword'])
@@ -386,7 +391,6 @@ test('reset password sets the password, spends the code, and ends every session'
 
     expect($response->getStatusCode())->toBe(200)
         ->and($user->saved)->toHaveCount(1)
-        ->and($deleted)->toBeTrue()
         // A reset is a recovery from losing control; nothing keeps working.
         ->and($user->tokensDeleted)->toBeTrue();
 });

package/server/tests/ApiEntityControllerContractsTest.php

@@ -4,8 +4,11 @@ use Fleetbase\FleetOps\Http\Controllers\Api\v1\EntityController;
 use Fleetbase\FleetOps\Http\Requests\CreateEntityRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdateEntityRequest;
 use Fleetbase\FleetOps\Models\Entity;
+use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Payload;
 use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Support\OrderEdit;
+use Fleetbase\FleetOps\Support\OrderEditPolicy;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
 
@@ -327,3 +330,84 @@ test('api entity controller returns not found responses for missing entities', f
         'status' => 404,
     ]);
 })->with(['update', 'find', 'delete']);
+
+/**
+ * Entities that belong to an order: the order's edit uses the real lock policy and records its commit.
+ */
+class FleetOpsApiEntityOrderControllerProbe extends FleetOpsApiEntityControllerProbe
+{
+    public ?Order $order = null;
+
+    public array $edits = [];
+
+    protected function orderEditForPayload(?string $payloadUuid): ?OrderEdit
+    {
+        if (!$this->order) {
+            return null;
+        }
+
+        return $this->edits[] = new FleetOpsApiEntityOrderEditFake($this->order);
+    }
+}
+
+class FleetOpsApiEntityOrderEditFake extends OrderEdit
+{
+    public int $commits = 0;
+
+    public function __construct(public Order $order)
+    {
+        $this->policy = OrderEditPolicy::for($order);
+    }
+
+    public function commit(array $extra = [], bool $notifyDriver = true): array
+    {
+        $this->commits++;
+
+        return ['items'];
+    }
+}
+
+function fleetopsApiEntityOrderController(string $status): FleetOpsApiEntityOrderControllerProbe
+{
+    $controller        = new FleetOpsApiEntityOrderControllerProbe();
+    $controller->order = new Order();
+    $controller->order->setRawAttributes(['uuid' => 'order-uuid', 'public_id' => 'order_entity', 'status' => $status], true);
+    $controller->entity = new FleetOpsApiEntityFake();
+    $controller->entity->setRawAttributes(['uuid' => 'entity-uuid', 'payload_uuid' => 'payload-uuid'], true);
+
+    return $controller;
+}
+
+test('api entity controller announces item edits on orders that allow them', function () {
+    $controller = fleetopsApiEntityOrderController('created');
+
+    $controller->create(new FleetOpsCreateEntityRequestFake(['name' => 'Latte', 'payload' => 'payload_public']));
+    $controller->update('entity_public', new FleetOpsUpdateEntityRequestFake(['name' => 'Iced Latte']));
+    $controller->delete('entity_public', new Request());
+
+    expect(array_map(fn ($edit) => $edit->commits, $controller->edits))->toBe([1, 1, 1])
+        ->and($controller->createdEntities)->toHaveCount(1)
+        ->and($controller->entity->deletedForTest)->toBeTrue();
+});
+
+test('api entity controller refuses item edits the order status locks', function () {
+    $dispatched = fleetopsApiEntityOrderController('dispatched');
+    $created    = $dispatched->create(new FleetOpsCreateEntityRequestFake(['name' => 'Latte', 'payload' => 'payload_public']));
+    $deleted    = $dispatched->delete('entity_public', new Request());
+
+    expect($created->getStatusCode())->toBe(422)
+        ->and($created->getData(true)['locked'])->toBe(['items' => 'Items cannot be changed once a driver has the order.'])
+        ->and($deleted->getStatusCode())->toBe(422)
+        ->and($dispatched->createdEntities)->toBe([])
+        ->and($dispatched->entity->deletedForTest)->toBeFalse();
+
+    // once ready, an item may be removed but not changed
+    $ready   = fleetopsApiEntityOrderController('ready');
+    $updated = $ready->update('entity_public', new FleetOpsUpdateEntityRequestFake(['name' => 'Iced Latte']));
+    $ready->delete('entity_public', new Request());
+
+    expect($updated->getStatusCode())->toBe(422)
+        ->and($updated->getData(true)['error'])->toBe('Once the order is ready, items can only be removed.')
+        ->and($ready->entity->updatedPayloads)->toBe([])
+        ->and($ready->entity->deletedForTest)->toBeTrue();
+});

package/server/tests/ApiOrderControllerContractsTest.php

@@ -1,5 +1,6 @@
 <?php
 
+use Fleetbase\FleetOps\Exceptions\OrderEditLockedException;
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\OrderController;
 use Fleetbase\FleetOps\Http\Requests\CreateOrderRequest;
 use Fleetbase\FleetOps\Http\Requests\ScheduleOrderRequest;
@@ -12,6 +13,8 @@ use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Proof;
 use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\OrderEdit;
+use Fleetbase\FleetOps\Support\OrderEditPolicy;
 use Fleetbase\FleetOps\Support\OrderTracker;
 use Fleetbase\Models\File;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
@@ -41,6 +44,8 @@ class FleetOpsApiOrderCrudControllerProbe extends OrderController
     public bool $missingOrderConfig              = false;
     public mixed $resolvedSubject                = null;
     public ?string $companyUuid                  = 'company-uuid';
+    public ?FleetOpsApiOrderEditFake $edit       = null;
+    public array $editLockedWith                 = [];
 
     protected function findOrder(string $id, array $with = [], array $withCount = []): Order
     {
@@ -54,6 +59,26 @@ class FleetOpsApiOrderCrudControllerProbe extends OrderController
         return $this->order;
     }
 
+    public ?FleetOpsApiOrderPayloadFake $switchedPayload = null;
+
+    protected function findPayloadByUuid(?string $uuid): ?Payload
+    {
+        return $this->switchedPayload;
+    }
+
+    protected function beginOrderEdit(Order $order): OrderEdit
+    {
+        $this->edit ??= new FleetOpsApiOrderEditFake($order);
+        $this->edit->lockWith = $this->editLockedWith;
+
+        return $this->edit;
+    }
+
+    protected function lockedEditResponse(OrderEditLockedException $exception)
+    {
+        return ['apiError' => $exception->getMessage(), 'status' => 422, 'locked' => $exception->locked];
+    }
+
     protected function drivingDistanceAndTime(mixed $origin, mixed $destination): mixed
     {
         return $this->matrix ?? (object) ['distance' => 1200, 'time' => 360];
@@ -244,6 +269,43 @@ class FleetOpsApiOrderCrudControllerProbe extends OrderController
     }
 }
 
+/**
+ * Records the edit guard and commit instead of reading and announcing through the database.
+ */
+class FleetOpsApiOrderEditFake extends OrderEdit
+{
+    public array $guarded  = [];
+    public array $lockWith = [];
+    public int $commits    = 0;
+
+    public function __construct(public Order $order)
+    {
+        $this->policy = OrderEditPolicy::for($order);
+    }
+
+    public function requestedChanges(array $input, string $entitiesMode = self::ENTITIES_APPEND): array
+    {
+        return ['input' => $input, 'entities_mode' => $entitiesMode];
+    }
+
+    public function guard(array $changes): static
+    {
+        $this->guarded[] = $changes;
+        if ($this->lockWith) {
+            throw new OrderEditLockedException($this->lockWith);
+        }
+
+        return $this;
+    }
+
+    public function commit(array $extra = [], bool $notifyDriver = true): array
+    {
+        $this->commits++;
+
+        return [];
+    }
+}
+
 class FleetOpsApiOrderCrudFake extends Order
 {
     public array $lookups                  = [];
@@ -383,6 +445,16 @@ class FleetOpsApiOrderCrudFake extends Order
         return $this;
     }
 
+    public ?string $cancelReasonForTest = null;
+
+    public function cancelWithReason(?string $reason = null)
+    {
+        $this->cancelledForTest    = true;
+        $this->cancelReasonForTest = $reason;
+
+        return $this;
+    }
+
     public function tracker(): OrderTracker
     {
         return $this->trackerFake;
@@ -447,6 +519,13 @@ class FleetOpsApiOrderPayloadFake extends Payload
         return $this;
     }
 
+    public function syncEntities($entities = []): array
+    {
+        $this->calls[] = ['sync-entities', $entities];
+
+        return ['created' => [], 'updated' => [], 'deleted' => []];
+    }
+
     public function setCurrentWaypoint(Place|Waypoint $destination, bool $save = true): Payload
     {
         $this->calls[] = ['current', $destination instanceof Place, $save];
@@ -753,6 +832,25 @@ test('api order controller updates by payload id and clears route waypoints', fu
         ->and($payload->removedWaypoints)->toBeTrue();
 });
 
+test('api order controller moves the cash to collect onto the payload it switches to by id', function () {
+    $order          = new FleetOpsApiOrderCrudFake();
+    $order->payload = new FleetOpsApiOrderPayloadFake();
+    $switched       = new FleetOpsApiOrderPayloadFake();
+
+    $controller                  = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order           = $order;
+    $controller->switchedPayload = $switched;
+
+    $controller->update('order-public', new FleetOpsApiOrderUpdateRequestFake([
+        'payload'    => 'payload_public',
+        'cod_amount' => '1800',
+    ]));
+
+    expect($order->updates[0])->toMatchArray(['payload_uuid' => 'payloads-uuid'])
+        ->and($switched->getAttributes()['cod_amount'])->toBe(1800)
+        ->and($switched->savedForTest)->toBeTrue();
+});
+
 test('api order controller finds deletes and updates distance matrices without database records', function () {
     $order              = new FleetOpsApiOrderCrudFake();
     $controller         = new FleetOpsApiOrderCrudControllerProbe();
@@ -1028,3 +1126,150 @@ test('api order controller captures QR proof payloads and validates error branch
         'status'   => 400,
     ]);
 });
+
+test('api order controller captures QR proof from tracking url codes and barcodes', function () {
+    session(['company' => 'company-uuid']);
+
+    $subject = (object) [
+        'uuid'           => 'subject-uuid',
+        'public_id'      => 'waypoint_subject',
+        'trackingNumber' => (object) ['tracking_number' => 'ACM1234567890SG'],
+    ];
+
+    // The url printed by current labels, from any host, and the Code 128 barcode.
+    foreach ([
+        'https://console.fleetbase.test/track-order?order=ACM1234567890SG&r=waypoint_subject&v=1',
+        'https://old-host.example/track-order?order=ACM1234567890SG&r=waypoint_subject&v=1',
+        'ACM1234567890SG',
+    ] as $code) {
+        $controller                  = new FleetOpsApiOrderCrudControllerProbe();
+        $controller->order           = new FleetOpsApiOrderCrudFake();
+        $controller->resolvedSubject = $subject;
+
+        expect($controller->captureQrScan(new Request(['code' => $code]), 'order-public', 'waypoint_subject')['resource'])->toBe('proof')
+            ->and($controller->createdProofs[0]['subject_uuid'])->toBe('subject-uuid');
+    }
+
+    // A scanner's whole result object, rather than its value, is refused as before
+    // instead of failing the request.
+    $controller                  = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order           = new FleetOpsApiOrderCrudFake();
+    $controller->resolvedSubject = $subject;
+
+    expect($controller->captureQrScan(new Request(['code' => ['type' => 'qr', 'value' => 'ACM1234567890SG']]), 'order-public', 'waypoint_subject'))->toBe([
+        'apiError' => 'Unable to validate QR code data.',
+        'status'   => 400,
+    ]);
+
+    // Another parcel's label is refused, whether it names another owner or, naming none,
+    // another tracking number.
+    foreach ([
+        'https://console.fleetbase.test/track-order?order=ACM1234567890SG&r=waypoint_other&v=1',
+        'https://console.fleetbase.test/track-order?order=ACM0000000000SG&v=1',
+    ] as $code) {
+        $controller                  = new FleetOpsApiOrderCrudControllerProbe();
+        $controller->order           = new FleetOpsApiOrderCrudFake();
+        $controller->resolvedSubject = $subject;
+
+        expect($controller->captureQrScan(new Request(['code' => $code]), 'order-public', 'waypoint_subject'))->toBe([
+            'apiError' => 'Unable to validate QR code data.',
+            'status'   => 400,
+        ])->and($controller->createdProofs)->toBe([]);
+    }
+});
+
+test('api order controller refuses order edits the status locks with a 422 and writes nothing', function () {
+    $order          = new FleetOpsApiOrderCrudFake(['status' => 'completed']);
+    $payload        = new FleetOpsApiOrderPayloadFake();
+    $order->payload = $payload;
+
+    $controller                 = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order          = $order;
+    $controller->editLockedWith = ['dropoff' => 'The order is completed and can no longer be changed.'];
+
+    $response = $controller->update('order-public', new FleetOpsApiOrderUpdateRequestFake([
+        'payload' => ['dropoff' => ['name' => 'Somewhere else']],
+    ]));
+
+    expect($response)->toBe([
+        'apiError' => 'The order is completed and can no longer be changed.',
+        'status'   => 422,
+        'locked'   => ['dropoff' => 'The order is completed and can no longer be changed.'],
+    ])
+        ->and($payload->calls)->toBe([])
+        ->and($payload->savedForTest)->toBeFalse()
+        ->and($order->updates)->toBe([])
+        ->and($controller->edit->commits)->toBe(0);
+});
+
+test('api order controller passes the edit to the guard, keeps cod 0, replaces entities and commits once', function () {
+    $order          = new FleetOpsApiOrderCrudFake(['status' => 'dispatched']);
+    $payload        = new FleetOpsApiOrderPayloadFake();
+    $order->payload = $payload;
+
+    $controller        = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order = $order;
+
+    $controller->update('order-public', new FleetOpsApiOrderUpdateRequestFake([
+        'payload' => [
+            'dropoff'       => ['name' => 'New drop'],
+            'entities'      => [['id' => 'entity_keep', 'name' => 'Latte']],
+            'entities_mode' => 'replace',
+            'cod_amount'    => 0,
+        ],
+        'notes'   => 'Leave at the door',
+    ]));
+
+    expect($controller->edit->guarded)->toBe([[
+        'input' => [
+            'dropoff'    => ['name' => 'New drop'],
+            'entities'   => [['id' => 'entity_keep', 'name' => 'Latte']],
+            'notes'      => 'Leave at the door',
+            'cod_amount' => 0,
+        ],
+        'entities_mode' => 'replace',
+    ]])
+        ->and($payload->calls)->toContain(['sync-entities', [['id' => 'entity_keep', 'name' => 'Latte']]])
+        ->and(collect($payload->calls)->where(0, 'entities')->all())->toBe([])
+        ->and($payload->getAttributes()['cod_amount'])->toBe(0)
+        ->and(collect($payload->calls)->where(0, 'current')->all())->toBe([])
+        ->and($controller->edit->commits)->toBe(1);
+});
+
+test('api order controller reads a top-level cod amount and appends entities by default', function () {
+    $order          = new FleetOpsApiOrderCrudFake();
+    $payload        = new FleetOpsApiOrderPayloadFake();
+    $order->payload = $payload;
+
+    $controller        = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order = $order;
+
+    $controller->update('order-public', new FleetOpsApiOrderUpdateRequestFake([
+        'entities'   => [['name' => 'Crate']],
+        'cod_amount' => '2500',
+    ]));
+
+    expect($payload->calls)->toContain(['entities', [['name' => 'Crate']]])
+        ->and($payload->getAttributes()['cod_amount'])->toBe(2500)
+        ->and($controller->edit->guarded[0]['input'])->toMatchArray(['cod_amount' => '2500'])
+        ->and($controller->edit->guarded[0]['entities_mode'])->toBe('append');
+});
+
+test('api order controller cancels with a reason when one is given', function () {
+    $order             = new FleetOpsApiOrderCrudFake();
+    $controller        = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order = $order;
+
+    $controller->cancelOrder('order-public', new Request(['reason' => '  Customer moved away  ']));
+
+    expect($order->cancelledForTest)->toBeTrue()
+        ->and($order->cancelReasonForTest)->toBe('Customer moved away');
+
+    $plain             = new FleetOpsApiOrderCrudFake();
+    $controller        = new FleetOpsApiOrderCrudControllerProbe();
+    $controller->order = $plain;
+    $controller->cancelOrder('order-public', new Request());
+
+    expect($plain->cancelledForTest)->toBeTrue()
+        ->and($plain->cancelReasonForTest)->toBeNull();
+});

package/server/tests/ApiPayloadControllerContractsTest.php

@@ -3,9 +3,12 @@
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\PayloadController;
 use Fleetbase\FleetOps\Http\Requests\CreatePayloadRequest;
 use Fleetbase\FleetOps\Http\Requests\UpdatePayloadRequest;
+use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Payload;
 use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\OrderEdit;
+use Fleetbase\FleetOps\Support\OrderEditPolicy;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
 
@@ -124,6 +127,15 @@ class FleetOpsApiPayloadEndpointFake extends Payload
         return $this;
     }
 
+    public array $entitySyncs = [];
+
+    public function syncEntities($entities = []): array
+    {
+        $this->entitySyncs[] = $entities;
+
+        return ['created' => [], 'updated' => [], 'deleted' => []];
+    }
+
     public function getPickupOrFirstWaypoint(): ?Place
     {
         return $this->firstWaypoint;
@@ -312,3 +324,112 @@ test('api payload controller returns not found responses for missing payloads',
         'status' => 404,
     ]);
 })->with(['update', 'find', 'delete']);
+
+/**
+ * A payload that belongs to an order: the order's edit is recorded instead of read from the database.
+ */
+class FleetOpsApiPayloadOrderControllerProbe extends FleetOpsApiPayloadControllerProbe
+{
+    public ?Order $order = null;
+
+    public ?FleetOpsApiPayloadOrderEditFake $edit = null;
+
+    protected function orderForPayload(Payload $payload): ?Order
+    {
+        return $this->order;
+    }
+
+    protected function beginOrderEdit(Order $order): OrderEdit
+    {
+        return $this->edit ??= new FleetOpsApiPayloadOrderEditFake($order);
+    }
+}
+
+class FleetOpsApiPayloadOrderEditFake extends OrderEdit
+{
+    public array $requested = [];
+    public int $commits     = 0;
+
+    public function __construct(public Order $order)
+    {
+        $this->policy = OrderEditPolicy::for($order);
+    }
+
+    public function requestedChanges(array $input, string $entitiesMode = self::ENTITIES_APPEND): array
+    {
+        $this->requested[] = [$input, $entitiesMode];
+
+        return parent::requestedChanges(array_diff_key($input, ['entities' => true, 'cod_amount' => true]), $entitiesMode)
+            + (isset($input['entities']) ? ['items' => ['adds' => $entitiesMode !== self::ENTITIES_REPLACE]] : []);
+    }
+
+    public function commit(array $extra = [], bool $notifyDriver = true): array
+    {
+        $this->commits++;
+
+        return [];
+    }
+}
+
+function fleetopsApiPayloadOrderController(string $status): FleetOpsApiPayloadOrderControllerProbe
+{
+    $controller                         = new FleetOpsApiPayloadOrderControllerProbe();
+    $controller->payload                = new FleetOpsApiPayloadEndpointFake();
+    $controller->payload->firstWaypoint = fleetopsApiPayloadPlace();
+    $controller->order                  = new Order();
+    $controller->order->setRawAttributes(['uuid' => 'order-uuid', 'public_id' => 'order_payload', 'status' => $status], true);
+
+    return $controller;
+}
+
+test('api payload controller keeps a cash to collect of zero and still skips empty values', function () {
+    $controller = fleetopsApiPayloadController();
+
+    $response = $controller->update('payload-public', fleetopsUpdatePayloadRequest([
+        'cod_amount' => 0,
+        'type'       => '',
+        'provider'   => null,
+    ]));
+
+    // the first fill is the model constructor's
+    expect(end($response['payload']->filledPayloads))->toBe(['cod_amount' => 0])
+        ->and($response['payload']->getAttributes()['cod_amount'])->toBe(0);
+});
+
+test('api payload controller edits an order payload through the order edit', function () {
+    $controller = fleetopsApiPayloadOrderController('dispatched');
+
+    $response = $controller->update('payload-public', fleetopsUpdatePayloadRequest([
+        'dropoff'    => ['public_id' => 'dropoff-public'],
+        'cod_amount' => 1500,
+    ]));
+
+    expect($response['payload']->dropoffAssignments)->toBe([['public_id' => 'dropoff-public']])
+        ->and($response['payload']->currentWaypointAssignments)->toBe([])
+        ->and($controller->edit->requested[0])->toBe([['dropoff' => ['public_id' => 'dropoff-public'], 'cod_amount' => 1500], 'append'])
+        ->and($controller->edit->commits)->toBe(1);
+});
+
+test('api payload controller replaces entities on request and refuses locked item edits', function () {
+    $controller = fleetopsApiPayloadOrderController('created');
+
+    $response = $controller->update('payload-public', fleetopsUpdatePayloadRequest([
+        'entities'      => [['id' => 'entity_keep']],
+        'entities_mode' => 'replace',
+    ]));
+
+    expect($response['payload']->entitySyncs)->toBe([[['id' => 'entity_keep']]])
+        ->and($response['payload']->entityAssignments)->toBe([]);
+
+    $locked   = fleetopsApiPayloadOrderController('dispatched');
+    $response = $locked->update('payload-public', fleetopsUpdatePayloadRequest([
+        'entities' => [['name' => 'Extra']],
+    ]));
+
+    expect($response->getStatusCode())->toBe(422)
+        ->and($response->getData(true)['error'])->toBe('Items cannot be changed once a driver has the order.')
+        ->and($response->getData(true)['locked'])->toBe(['items' => 'Items cannot be changed once a driver has the order.'])
+        ->and($locked->payload->entityAssignments)->toBe([])
+        ->and($locked->payload->savedForTest)->toBeFalse()
+        ->and($locked->edit->commits)->toBe(0);
+});

package/server/tests/ApiPlaceControllerContractsTest.php

@@ -537,5 +537,5 @@ test('api place controller returns not found errors for missing places', functio
         ? $controller->update('missing-place', fleetopsUpdatePlaceRequest([]))
         : $controller->{$method}('missing-place', new Request());
 
-    expect($response)->toBe(['apiError' => 'Place resource not found.', 'status' => 400]);
+    expect($response)->toBe(['apiError' => 'Place resource not found.', 'status' => 404]);
 })->with(['update', 'find', 'delete']);

package/server/tests/ApiTrackingNumberControllerContractsTest.php

@@ -68,9 +68,9 @@ class FleetOpsApiTrackingNumberControllerProbe extends TrackingNumberController
         return ['resource' => 'deleted-tracking-number', 'trackingNumber' => $trackingNumber];
     }
 
-    protected function findQrModel(array $tables, array $where)
+    protected function findQrModel(string $code)
     {
-        $this->qrLookups[] = [$tables, $where];
+        $this->qrLookups[] = $code;
 
         return $this->qrModel;
     }
@@ -206,15 +206,12 @@ test('api tracking number controller decodes qr models and reports missing value
     $controller          = new FleetOpsApiTrackingNumberControllerProbe();
     $controller->qrModel = $model;
 
-    $response = $controller->fromQR(fleetopsDecodeTrackingNumberQrRequest(['code' => 'order-uuid']));
+    $code     = 'https://console.fleetbase.test/track-order?order=ACM1234567890SG&r=order_public&v=1';
+    $response = $controller->fromQR(fleetopsDecodeTrackingNumberQrRequest(['code' => $code]));
 
+    // The raw scanned value goes to the resolver, which understands every format.
     expect($response)->toBe(['resource' => 'qr-model', 'model' => $model])
-        ->and($controller->qrLookups)->toBe([
-            [
-                ['entities', 'orders'],
-                ['uuid' => 'order-uuid'],
-            ],
-        ]);
+        ->and($controller->qrLookups)->toBe([$code]);
 
     $controller = new FleetOpsApiTrackingNumberControllerProbe();