@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Support/TrackingUpdate.php

@@ -0,0 +1,402 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\TrackingStatus;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Tracking\TrackingStop;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+
+/**
+ * The payload published to one customer's public tracking channel.
+ *
+ * It carries only what that customer may see: their own stops (status, ETA, timeline), whole-route
+ * counts, the driver's first name, the vehicle's label and online flag, and the vehicle's rounded
+ * position. It never carries another customer's stops, places, items or people, the driver's
+ * photo or phone, or free-text activity details. The driver and position are included only while
+ * the order is en route and this customer still has a stop to be served.
+ */
+final class TrackingUpdate
+{
+    public const EVENT_UPDATED = 'tracking.updated';
+
+    public const EVENT_LOCATION = 'tracking.location';
+
+    public const REASON_STATUS = 'status';
+
+    public const REASON_STOP = 'stop';
+
+    public const REASON_ASSIGNMENT = 'assignment';
+
+    public const REASON_ETA = 'eta';
+
+    public const REASON_LOCATION = 'location';
+
+    public const REASON_ROUTE = 'route';
+
+    /**
+     * Decimal places kept on published coordinates: 4 places is roughly 11 m.
+     */
+    public const COORDINATE_PRECISION = 4;
+
+    public const TERMINAL_STATUSES = ['completed', 'canceled'];
+
+    /**
+     * Most timeline entries published per tracking number.
+     */
+    public const TIMELINE_LIMIT = 20;
+
+    /**
+     * @var Collection<int, TrackingStop>
+     */
+    private Collection $stops;
+
+    /**
+     * @param iterable<TrackingStop>                  $stops     every stop of the order, in route order
+     * @param array<int, array>                       $etas      ETA per stop sequence: seconds, at, distance_m
+     * @param array<string, array<int, array>>        $timelines timeline entries per tracking number uuid
+     */
+    public function __construct(
+        private Order $order,
+        private TrackingScope $scope,
+        iterable $stops = [],
+        private array $etas = [],
+        private array $timelines = [],
+    ) {
+        $this->stops = collect($stops)->filter(fn ($stop) => $stop instanceof TrackingStop)->values();
+    }
+
+    /**
+     * Build the update for a scope from the order's stops and, optionally, a tracking intelligence result.
+     *
+     * @param iterable<TrackingStop> $stops
+     * @param array                  $tracker a TrackingIntelligenceService::track() result; its route legs give the ETAs
+     */
+    public static function for(Order $order, TrackingScope $scope, iterable $stops, array $tracker = []): self
+    {
+        $update = new self($order, $scope, $stops, static::etasFromTracker($tracker));
+
+        $update->timelines = static::loadTimelines($update->timelineTrackingNumbers(), $order->getConnectionName());
+
+        return $update;
+    }
+
+    /**
+     * The full update: order state, route counts, this customer's stops, driver and position.
+     */
+    public function toArray(string $reason = self::REASON_STATUS): array
+    {
+        return $this->envelope(self::EVENT_UPDATED, $reason, [
+            'order'    => $this->orderState(),
+            'route'    => $this->route(),
+            'stops'    => $this->ownStops()->map(fn (TrackingStop $stop) => $this->stop($stop))->values()->all(),
+            'driver'   => $this->driver(),
+            'location' => $this->location(),
+        ]);
+    }
+
+    /**
+     * The position-only update, or null when this customer may not see the vehicle right now.
+     */
+    public function locationPayload(): ?array
+    {
+        $location = $this->location();
+        if ($location === null) {
+            return null;
+        }
+
+        return $this->envelope(self::EVENT_LOCATION, self::REASON_LOCATION, [
+            'driver'   => $this->driver(),
+            'location' => $location,
+        ]);
+    }
+
+    /**
+     * This customer's stops.
+     *
+     * @return Collection<int, TrackingStop>
+     */
+    public function ownStops(): Collection
+    {
+        return $this->stops->filter(fn (TrackingStop $stop) => $this->scope->ownsStop($this->order, $stop->waypoint))->values();
+    }
+
+    public function isTerminal(): bool
+    {
+        return in_array(strtolower((string) $this->order->status), self::TERMINAL_STATUSES, true);
+    }
+
+    /**
+     * Whether the order is under way: started and not yet completed or canceled.
+     */
+    public function isEnRoute(): bool
+    {
+        if ($this->isTerminal()) {
+            return false;
+        }
+
+        return (bool) $this->order->started || !empty($this->order->started_at) || strtolower((string) $this->order->status) === 'started';
+    }
+
+    public function customerHasIncompleteStop(): bool
+    {
+        return $this->ownStops()->contains(fn (TrackingStop $stop) => !$stop->completed);
+    }
+
+    /**
+     * Whether the driver and the vehicle position may be shown to this customer now.
+     */
+    public function showsVehicle(): bool
+    {
+        return $this->isEnRoute() && $this->customerHasIncompleteStop();
+    }
+
+    /**
+     * Whole-route counts: stops in total, stops done, and stops still ahead of this customer's next one.
+     */
+    public function route(): array
+    {
+        $next = $this->ownStops()->first(fn (TrackingStop $stop) => !$stop->completed);
+
+        return [
+            'total_stops'     => $this->stops->count(),
+            'completed_stops' => $this->stops->filter(fn (TrackingStop $stop) => $stop->completed)->count(),
+            'stops_before'    => $next ? $this->stops->filter(fn (TrackingStop $stop) => !$stop->completed && (int) $stop->sequence < (int) $next->sequence)->count() : 0,
+        ];
+    }
+
+    /**
+     * The driver as this customer may see them: first name, vehicle label, online flag.
+     */
+    public function driver(): ?array
+    {
+        $driver = $this->assignedDriver();
+        if (!$driver || !$this->showsVehicle()) {
+            return null;
+        }
+
+        return [
+            'name'    => static::firstName($driver->name),
+            'vehicle' => $this->vehicleLabel(),
+            'online'  => (bool) $driver->online,
+        ];
+    }
+
+    /**
+     * The vehicle position rounded to ~10 m, its heading and when it was seen.
+     */
+    public function location(): ?array
+    {
+        if (!$this->showsVehicle()) {
+            return null;
+        }
+
+        $source = $this->locationSource();
+        if (!$source) {
+            return null;
+        }
+
+        [$subject, $point] = $source;
+
+        return [
+            'latitude'  => round($point->getLat(), self::COORDINATE_PRECISION),
+            'longitude' => round($point->getLng(), self::COORDINATE_PRECISION),
+            'heading'   => is_numeric($subject->heading) ? (int) round((float) $subject->heading) : null,
+            'seen_at'   => $subject->updated_at ? Carbon::parse($subject->updated_at)->toISOString() : null,
+        ];
+    }
+
+    /**
+     * Tracking numbers whose timeline this customer may read: their stops', plus the order's own for the order customer.
+     *
+     * @return array<int, string>
+     */
+    public function timelineTrackingNumbers(): array
+    {
+        $uuids = $this->ownStops()->map(fn (TrackingStop $stop) => $stop->trackingNumberUuid)->all();
+
+        if ($this->scope->isOrderCustomer($this->order)) {
+            $uuids[] = $this->order->tracking_number_uuid;
+        }
+
+        return array_values(array_unique(array_filter($uuids, fn ($uuid) => is_string($uuid) && $uuid !== '')));
+    }
+
+    /**
+     * ETAs keyed by stop sequence from a tracking intelligence result's route legs.
+     */
+    public static function etasFromTracker(array $tracker): array
+    {
+        $etas = [];
+        foreach ((array) data_get($tracker, 'route.legs', []) as $leg) {
+            $sequence = data_get($leg, 'stop.sequence');
+            if ($sequence === null) {
+                continue;
+            }
+
+            $etas[(int) $sequence] = [
+                'seconds'    => is_numeric(data_get($leg, 'eta_seconds')) ? (int) round((float) data_get($leg, 'eta_seconds')) : null,
+                'at'         => data_get($leg, 'eta_at'),
+                'distance_m' => is_numeric(data_get($leg, 'distance_m')) ? (int) round((float) data_get($leg, 'distance_m')) : null,
+            ];
+        }
+
+        return $etas;
+    }
+
+    /**
+     * Timeline entries per tracking number: status, code, complete and time only.
+     *
+     * @param array<int, string> $trackingNumberUuids
+     *
+     * @return array<string, array<int, array>>
+     */
+    public static function loadTimelines(array $trackingNumberUuids, ?string $connection = null): array
+    {
+        if ($trackingNumberUuids === []) {
+            return [];
+        }
+
+        return TrackingStatus::on($connection)
+            ->whereIn('tracking_number_uuid', $trackingNumberUuids)
+            ->orderBy('created_at')
+            ->get(['tracking_number_uuid', 'status', 'code', 'complete', 'created_at'])
+            ->groupBy('tracking_number_uuid')
+            ->map(fn (Collection $statuses) => $statuses->take(-self::TIMELINE_LIMIT)->map(fn (TrackingStatus $status) => static::timelineEntry($status))->values()->all())
+            ->all();
+    }
+
+    /**
+     * The first word of a name.
+     */
+    public static function firstName(?string $name): ?string
+    {
+        $name = trim((string) $name);
+
+        return $name === '' ? null : Str::before($name, ' ');
+    }
+
+    private function envelope(string $event, string $reason, array $data): array
+    {
+        return [
+            'event'   => $event,
+            'reason'  => $reason,
+            'sent_at' => Carbon::now()->toISOString(),
+            'data'    => $data,
+        ];
+    }
+
+    private function orderState(): array
+    {
+        $status = strtolower((string) $this->order->status);
+
+        return [
+            'status'    => $status !== '' ? $status : null,
+            'en_route'  => $this->isEnRoute(),
+            'completed' => $status === 'completed',
+            'canceled'  => $status === 'canceled',
+            'timeline'  => $this->scope->isOrderCustomer($this->order) ? $this->timeline($this->order->tracking_number_uuid) : [],
+        ];
+    }
+
+    private function stop(TrackingStop $stop): array
+    {
+        $eta = $stop->completed ? null : ($this->etas[(int) $stop->sequence] ?? null);
+
+        return [
+            'id'       => $stop->waypoint?->public_id,
+            'type'     => $stop->type,
+            'sequence' => $stop->sequence,
+            'status'   => $stop->status,
+            'complete' => $stop->completed,
+            'eta'      => $eta,
+            'timeline' => $this->timeline($stop->trackingNumberUuid),
+        ];
+    }
+
+    private function timeline(?string $trackingNumberUuid): array
+    {
+        return $trackingNumberUuid ? ($this->timelines[$trackingNumberUuid] ?? []) : [];
+    }
+
+    private static function timelineEntry(TrackingStatus $status): array
+    {
+        $createdAt = $status->getRawOriginal('created_at') ?? $status->created_at;
+
+        return [
+            'status'     => $status->status,
+            'code'       => $status->code !== null ? strtolower((string) $status->code) : null,
+            'complete'   => (bool) $status->complete,
+            'created_at' => $createdAt ? Carbon::parse($createdAt)->toISOString() : null,
+        ];
+    }
+
+    private function assignedDriver(): ?Driver
+    {
+        $driver = $this->order->driverAssigned;
+
+        return $driver instanceof Driver ? $driver : null;
+    }
+
+    private function assignedVehicle(): ?Vehicle
+    {
+        $vehicle = $this->order->vehicleAssigned ?? $this->assignedDriver()?->vehicle;
+
+        return $vehicle instanceof Vehicle ? $vehicle : null;
+    }
+
+    private function vehicleLabel(): ?string
+    {
+        $label = trim((string) $this->assignedVehicle()?->display_name);
+
+        return $label === '' ? null : $label;
+    }
+
+    /**
+     * The most recently updated of the driver and the vehicle that has a usable position.
+     *
+     * @return array{0: Driver|Vehicle, 1: \Fleetbase\LaravelMysqlSpatial\Types\Point}|null
+     */
+    private function locationSource(): ?array
+    {
+        $candidates = [];
+        foreach ([$this->assignedDriver(), $this->assignedVehicle()] as $subject) {
+            $point = $subject ? static::usablePoint($subject) : null;
+            if ($point) {
+                $candidates[] = [$subject, $point];
+            }
+        }
+
+        usort($candidates, fn (array $a, array $b) => static::seenAt($b[0]) <=> static::seenAt($a[0]));
+
+        return $candidates[0] ?? null;
+    }
+
+    private static function seenAt(Driver|Vehicle $subject): int
+    {
+        return $subject->updated_at ? Carbon::parse($subject->updated_at)->getTimestamp() : 0;
+    }
+
+    private static function usablePoint(Driver|Vehicle $subject)
+    {
+        try {
+            $point = $subject->location ? Utils::getPointFromMixed($subject->location) : null;
+        } catch (\Throwable) {
+            return null;
+        }
+
+        if (!$point) {
+            return null;
+        }
+
+        $lat = (float) $point->getLat();
+        $lng = (float) $point->getLng();
+        $valid = is_finite($lat) && is_finite($lng) && abs($lat) <= 90 && abs($lng) <= 180 && !(abs($lat) < 0.000001 && abs($lng) < 0.000001);
+
+        return $valid ? $point : null;
+    }
+}

package/server/src/Support/Utils.php

@@ -1220,8 +1220,8 @@ class Utils extends FleetbaseUtils
     {
         $latitude  = deg2rad($latitude);
         $longitude = deg2rad($longitude);
-        // convert meters to km
-        $radius = ($meters * 1000) / 6378137;
+        // angular radius: metres over the earth's equatorial radius in metres
+        $radius = $meters / 6378137;
         // create circle coordinates
         $coords = collect();
         // loop through the array and write path linestrings — stop short of 360
@@ -1231,7 +1231,8 @@ class Utils extends FleetbaseUtils
             $radial   = deg2rad($i);
             $lat_rad  = asin(sin($latitude) * cos($radius) + cos($latitude) * sin($radius) * cos($radial));
             $dlon_rad = atan2(sin($radial) * sin($radius) * cos($latitude), cos($radius) - sin($latitude) * sin($lat_rad));
-            $lon_rad  = fmod($longitude + $dlon_rad + M_PI, 2 * M_PI) - M_PI;
+            // shift by 3π, not π: fmod keeps the dividend's sign, so a negative sum would not wrap
+            $lon_rad  = fmod($longitude + $dlon_rad + 3 * M_PI, 2 * M_PI) - M_PI;
             $coords->push([rad2deg($lat_rad), rad2deg($lon_rad)]);
         }
 
@@ -1603,4 +1604,15 @@ class Utils extends FleetbaseUtils
 
         return $phone;
     }
+
+    /**
+     * Re-sign a URL stored as a string (e.g. a legacy `avatar_url` value) when it points into the
+     * private S3 media bucket, so it keeps working once the bucket stops allowing public reads.
+     * Other values pass through unchanged. Falls back to the raw value on core-api releases that
+     * predate File::signStoredUrl().
+     */
+    public static function signStoredFileUrl(?string $url): ?string
+    {
+        return method_exists(\Fleetbase\Models\File::class, 'signStoredUrl') ? \Fleetbase\Models\File::signStoredUrl($url) : $url;
+    }
 }

package/server/src/Traits/HasTrackingNumber.php

@@ -9,6 +9,7 @@ use Fleetbase\FleetOps\Models\TrackingNumber;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Support\ApiModelCache;
 use Fleetbase\Support\TemplateString;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\DB;
@@ -28,6 +29,7 @@ trait HasTrackingNumber
             ], $model);
 
             DB::table($model->getTable())->where('uuid', $model->uuid)->update(['tracking_number_uuid' => $trackingNumberId]);
+            ApiModelCache::invalidateModelCache($model, data_get($model, 'company_uuid', session('company')));
 
             if ($model->isFillable('tracking_number_uuid')) {
                 $model->tracking_number_uuid = $trackingNumberId;

package/server/src/routes.php

@@ -20,6 +20,23 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
         // limiter has its own prefix so the two do not share one counter.
         // Every answer is JSON, so a refused submission reaches the page with
         // its reasons instead of as a redirect back to it.
+        // The public customer tracking page. A tracking number alone gives a coarse status;
+        // a one-time code to the customer's own contact details unlocks their stops. Lookups
+        // are rate limited inside the controller, so a throttled lookup answers exactly like
+        // an unknown number; code sends and checks have limits of their own there too.
+        $router->prefix('public/track')->namespace('Public')->middleware([Fleetbase\FleetOps\Http\Middleware\ForceJsonResponse::class])->group(function ($router) {
+            $router->get('config', 'TrackingController@config');
+            $router->get('account/orders', 'TrackingController@accountOrders');
+            $router->delete('session', 'TrackingController@signOut');
+            $router->get('{number}', 'TrackingController@show');
+            $router->post('{number}/codes', 'TrackingController@sendCode');
+            $router->post('{number}/codes/verify', 'TrackingController@verifyCode');
+            $router->put('{number}/instructions', 'TrackingController@updateInstructions');
+            $router->get('{number}/proofs/{id}', 'TrackingController@proof');
+            $router->post('{number}/report', 'TrackingController@report');
+            $router->get('{number}/socket-token', 'TrackingController@socketToken');
+        });
+
         $router->prefix('public')->namespace('Public')->middleware([Fleetbase\FleetOps\Http\Middleware\ForceJsonResponse::class, 'throttle:60,1,inspection-public'])->group(function ($router) {
             $router->get('inspections/forms/{id}', 'PublicInspectionController@show');
             $router->post('inspections/forms/{id}/submit', 'PublicInspectionController@submit');
@@ -37,14 +54,16 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
             // drivers routes
             $router->group(['prefix' => 'drivers', 'middleware' => []], function () use ($router) {
                 $router->post('register-device', 'DriverController@registerDevice');
-                $router->post('login-with-sms', 'DriverController@loginWithPhone');
+                // Routes that send a text message carry a small per-address bucket on top
+                // of the API credential throttle; the SMS guard in core bounds the spend.
+                $router->post('login-with-sms', 'DriverController@loginWithPhone')->middleware('throttle:5,1,fleetops-sms');
                 $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('forgot-password', 'DriverController@forgotPassword')->middleware('throttle:5,1,fleetops-sms');
                 $router->post('reset-password', 'DriverController@resetPassword');
                 $router->post('{id}/change-password', 'DriverController@changePassword');
                 $router->post('{id}/simulate', 'DriverController@simulate');
@@ -80,12 +99,12 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
             //  - Authenticated endpoints: API key + `Customer-Token` header (Sanctum)
             $router->group(['prefix' => 'customers', 'middleware' => []], function () use ($router) {
                 // Public auth flows
-                $router->post('request-creation-code', 'CustomerController@requestCreationCode');
+                $router->post('request-creation-code', 'CustomerController@requestCreationCode')->middleware('throttle:5,1,fleetops-sms');
                 $router->post('/', 'CustomerController@create');
                 $router->post('login', 'CustomerController@login');
-                $router->post('login-with-sms', 'CustomerController@loginWithPhone');
+                $router->post('login-with-sms', 'CustomerController@loginWithPhone')->middleware('throttle:5,1,fleetops-sms');
                 $router->post('verify-code', 'CustomerController@verifyCode');
-                $router->post('forgot-password', 'CustomerController@forgotPassword');
+                $router->post('forgot-password', 'CustomerController@forgotPassword')->middleware('throttle:5,1,fleetops-sms');
                 $router->post('reset-password', 'CustomerController@resetPassword');
 
                 // Authenticated (require Customer-Token)
@@ -398,7 +417,10 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                 $router->group(
                     ['prefix' => 'v1/fleet-ops', 'namespace' => 'v1'],
                     function ($router) {
-                        $router->get('lookup', 'OrderController@lookup');
+                        // The public Track Order page: no session, the tracking number is
+                        // the credential. Rate limited per address so numbers cannot be
+                        // enumerated, on a limiter of its own.
+                        $router->get('lookup', 'OrderController@lookup')->middleware('throttle:30,1,tracking-lookup');
                     }
                 );
 
@@ -562,7 +584,12 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                                 $router->post('import', $controller('import'));
                             }
                         );
-                        $router->fleetbaseRoutes('proofs');
+                        $router->fleetbaseRoutes(
+                            'proofs',
+                            function ($router, $controller) {
+                                $router->get('recent', $controller('recent'));
+                            }
+                        );
                         $router->fleetbaseRoutes('purchase-rates');
                         $router->fleetbaseRoutes('routes');
                         $router->fleetbaseRoutes('positions', function ($router, $controller) {
@@ -806,6 +833,11 @@ Route::prefix(config('fleetops.api.routing.prefix'))->namespace('Fleetbase\Fleet
                                         $router->post('tracking-settings', 'SettingController@saveTrackingSettings');
                                         $router->get('admin-tracking-settings', 'SettingController@getAdminTrackingSettings');
                                         $router->post('admin-tracking-settings', 'SettingController@saveAdminTrackingSettings');
+                                        $router->get('tracking-page-settings', 'SettingController@getTrackingPageSettings');
+                                        $router->post('tracking-page-settings', 'SettingController@saveTrackingPageSettings');
+                                        $router->post('tracking-page-settings/validate-slug', 'SettingController@validateTrackingPageSlug');
+                                        $router->get('admin-tracking-page-settings', 'SettingController@getAdminTrackingPageSettings');
+                                        $router->post('admin-tracking-page-settings', 'SettingController@saveAdminTrackingPageSettings');
                                         $router->get('map', 'SettingController@getMapSettings');
                                         $router->post('map', 'SettingController@saveMapSettings');
                                         $router->get('admin-map', 'SettingController@getAdminMapSettings');

package/server/tests/ApiCustomerControllerContractsTest.php

@@ -1,5 +1,6 @@
 <?php
 
+use Fleetbase\Exceptions\SmsBlockedException;
 use Fleetbase\FleetOps\Exceptions\UserAlreadyExistsException;
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\CustomerController;
 use Fleetbase\FleetOps\Http\Requests\CreateCustomerOrderRequest;
@@ -14,6 +15,7 @@ use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\Models\User;
+use Fleetbase\Support\Sms\PhoneValidator;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Request;
 
@@ -56,6 +58,7 @@ class FleetOpsApiCustomerControllerProbe extends CustomerController
     public mixed $placesResult                                        = null;
     public bool $emailVerificationFails                               = false;
     public bool $smsVerificationFails                                 = false;
+    public ?Throwable $smsVerificationThrows                          = null;
     public bool $verificationExists                                   = true;
     public bool $passwordMatches                                      = true;
     public bool $findOrderFails                                       = false;
@@ -164,6 +167,9 @@ class FleetOpsApiCustomerControllerProbe extends CustomerController
 
     protected function generateSmsVerification(User $user, string $for, array $options): mixed
     {
+        if ($this->smsVerificationThrows) {
+            throw $this->smsVerificationThrows;
+        }
         if ($this->smsVerificationFails) {
             throw new RuntimeException('sms failed');
         }
@@ -692,12 +698,9 @@ test('api customer controller sends creation verification codes and updates stub
     ]));
 
     expect($created)->toBe(['status' => 'ok'])
-        ->and($controller->createdUsers[0])->toMatchArray([
-            'company_uuid' => 'company-uuid',
-            'name'         => 'Jane',
-            'email'        => 'jane@example.test',
-            'phone'        => '+15551234567',
-        ])
+        // Nothing is persisted for an unverified identity: the code's subject is an unsaved user.
+        ->and($controller->createdUsers)->toBe([])
+        ->and($controller->emailVerifications[0][0])->toBeNull()
         ->and($controller->emailVerifications[0][1])->toBe('fleetops_create_customer')
         ->and($updated)->toBe(['status' => 'ok'])
         ->and($stub->name)->toBe('Stub Name')
@@ -844,7 +847,6 @@ test('api customer controller resets forgotten passwords', function () {
         ->and(fleetopsApiCustomerJson($reset))->toBe(['status' => 'ok'])
         ->and($controller->genericUser->savedForTest)->toBeTrue()
         ->and($controller->genericUser->tokensDeleted)->toBeTrue()
-        ->and($controller->verificationCode->deleted)->toBeTrue()
         ->and(fleetopsApiCustomerJson($unknown->forgotPassword(Request::create('/v1/customers/forgot-password', 'POST', [
             'identity' => 'missing@example.test',
         ]))))->toBe(['status' => 'ok'])
@@ -982,6 +984,51 @@ test('api customer controller handles verification delivery fallbacks and profil
         ]))))->toBe(['error' => 'update failed']);
 });
 
+test('api customer controller answers an sms guard refusal with its status, not the generic error', function () {
+    // A paused organization: the sign-up code request answers 423 with the wait.
+    $paused                        = fleetopsApiCustomerController();
+    $paused->activeUser            = null;
+    $paused->smsVerificationThrows = SmsBlockedException::paused('company:company-uuid', 120);
+    $creation                      = $paused->requestCreationCode(new VerifyCreateCustomerRequest([
+        'mode'     => 'sms',
+        'identity' => '15550000000',
+    ]));
+
+    // Over budget with no email on file: the 429 and its Retry-After reach the app.
+    $limited                        = fleetopsApiCustomerController();
+    $limited->activeUser->email     = null;
+    $limited->smsVerificationThrows = SmsBlockedException::limited('company_per_hour', 45);
+    $login                          = $limited->loginWithPhone(Request::create('/v1/customers/login/phone', 'POST', [
+        'phone' => '15551234567',
+    ]));
+
+    // Over budget with an email on file: the code still goes by email.
+    $fallback                        = fleetopsApiCustomerController();
+    $fallback->smsVerificationThrows = SmsBlockedException::limited('company_per_hour', 45);
+    $fallback->activeUser->email     = 'jane@example.test';
+    $byEmail                         = $fallback->loginWithPhone(Request::create('/v1/customers/login/phone', 'POST', [
+        'phone' => '15551234567',
+    ]));
+
+    // A number that can never be texted: the reset request answers 422.
+    $invalid                        = fleetopsApiCustomerController();
+    $invalid->smsVerificationThrows = SmsBlockedException::invalidDestination(PhoneValidator::REASON_TYPE_NOT_ALLOWED);
+    $forgot                         = $invalid->forgotPassword(Request::create('/v1/customers/forgot-password', 'POST', [
+        'identity' => '15551234567',
+    ]));
+
+    expect($creation->getStatusCode())->toBe(423)
+        ->and($creation->headers->get('Retry-After'))->toBe('120')
+        ->and(fleetopsApiCustomerJson($creation))->toBe(['error' => 'Text messages are temporarily unavailable. Try again later.'])
+        ->and($login->getStatusCode())->toBe(429)
+        ->and($login->headers->get('Retry-After'))->toBe('45')
+        ->and(fleetopsApiCustomerJson($login))->toBe(['error' => 'Unable to send a verification code right now. Try again in a minute.'])
+        ->and(fleetopsApiCustomerJson($byEmail))->toBe(['status' => 'ok', 'method' => 'email'])
+        ->and($fallback->emailVerifications[0][1])->toBe('fleetops_customer_login')
+        ->and($forgot->getStatusCode())->toBe(422)
+        ->and(fleetopsApiCustomerJson($forgot))->toBe(['error' => 'The phone number provided cannot receive text messages.']);
+});
+
 /**
  * Run a callback with an app container that supports environment().
  *