@fleetbase/fleetops-engine 0.6.49 → 0.6.50

package/server/src/Http/Controllers/Api/v1/DriverController.php

@@ -50,7 +50,7 @@ class DriverController extends Controller
         $input = $request->except(['name', 'password', 'email', 'phone', 'location', 'altitude', 'heading', 'speed', 'meta']);
 
         // Add default status
-        $input['status'] = 'active';
+        $input['status'] = $request->input('status', 'available');
 
         // get user details for driver
         $userDetails                 = $request->only(['name', 'password', 'email', 'phone', 'timezone']);

package/server/src/Http/Controllers/Api/v1/OrderConfigController.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
+
+use Fleetbase\FleetOps\Http\Resources\v1\OrderConfig as OrderConfigResource;
+use Fleetbase\FleetOps\Models\OrderConfig;
+use Fleetbase\Http\Controllers\Controller;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Http\Request;
+
+/**
+ * Public, read-only API surface for OrderConfigs.
+ *
+ * The internal admin console manages the full OrderConfig lifecycle through
+ * `/int/v1/order-configs`. This public endpoint exposes the projected,
+ * non-sensitive subset (flow activities + metadata) that consumers like a
+ * customer portal need to render status filter chips, activity labels, and
+ * other UI driven by the active flow.
+ */
+class OrderConfigController extends Controller
+{
+    /**
+     * List the OrderConfigs for the company resolved from the API credential.
+     *
+     * @return \Illuminate\Http\Resources\Json\AnonymousResourceCollection
+     */
+    public function query(Request $request)
+    {
+        $results = OrderConfig::queryWithRequest($request);
+
+        return OrderConfigResource::collection($results);
+    }
+
+    /**
+     * Find a single OrderConfig. The `{id}` segment accepts any identifier
+     * supported by {@see OrderConfig::resolveFromIdentifier} — `uuid`,
+     * `public_id`, `namespace`, or short `key` (e.g. `transport`).
+     *
+     * @return OrderConfigResource|\Illuminate\Http\JsonResponse
+     */
+    public function find(string $id)
+    {
+        $orderConfig = OrderConfig::resolveFromIdentifier($id);
+        if (!$orderConfig) {
+            try {
+                $orderConfig = OrderConfig::findRecordOrFail($id);
+            } catch (ModelNotFoundException $e) {
+                return response()->apiError('Order config not found.', 404);
+            }
+        }
+
+        return new OrderConfigResource($orderConfig);
+    }
+}

package/server/src/Http/Controllers/Api/v1/OrderController.php

@@ -5,6 +5,7 @@ namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 use Fleetbase\FleetOps\Events\OrderDispatchFailed;
 use Fleetbase\FleetOps\Events\OrderReady;
 use Fleetbase\FleetOps\Events\OrderStarted;
+use Fleetbase\FleetOps\Exceptions\CustomerUserConflictException;
 use Fleetbase\FleetOps\Exceptions\UserAlreadyExistsException;
 use Fleetbase\FleetOps\Flow\Activity;
 use Fleetbase\FleetOps\Http\Requests\CreateOrderRequest;
@@ -23,6 +24,7 @@ use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Proof;
 use Fleetbase\FleetOps\Models\ServiceQuote;
 use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Http\Resources\Comment as CommentResource;
@@ -43,6 +45,8 @@ use Illuminate\Validation\ValidationException;
 
 class OrderController extends Controller
 {
+    use ResolvesOrderServiceStops;
+
     /**
      * Creates a new Fleetbase Order resource.
      *
@@ -251,6 +255,13 @@ class OrderController extends Controller
                 $customer = Arr::only($customer, ['internal_id', 'name', 'title', 'email', 'phone', 'meta']);
 
                 try {
+                    $customerCandidate = new Contact([
+                        ...$customer,
+                        'company_uuid' => session('company'),
+                        'type'         => 'customer',
+                    ]);
+                    $customerCandidate->assertCustomerIdentityIsAvailable();
+
                     $customer = Contact::firstOrCreate(
                         [
                             'company_uuid' => session('company'),
@@ -263,19 +274,12 @@ class OrderController extends Controller
                             'type'         => 'customer',
                         ]
                     );
+                } catch (CustomerUserConflictException $e) {
+                    return response()->apiError($e->getMessage());
+                } catch (UserAlreadyExistsException $e) {
+                    return response()->apiError($e->getMessage());
                 } catch (\Exception $e) {
                     return response()->apiError('Failed to find or create customer for order.');
-                } catch (UserAlreadyExistsException $e) {
-                    try {
-                        // If user already exist then assign user to this customer and the company
-                        $existingUser = $e->getUser();
-                        // Assign user to customer
-                        if ($existingUser && $customer) {
-                            $customer->assignUser($existingUser);
-                        }
-                    } catch (\Exception $e) {
-                        return response()->apiError('Failed to find or create customer for order.');
-                    }
                 }
 
                 if (Str::isUuid($customer)) {
@@ -1043,7 +1047,17 @@ class OrderController extends Controller
         // if string $id
         if (!$order) {
             try {
-                $order = Order::findRecordOrFail($id, ['driverAssigned', 'payload.entities', 'payload.currentWaypoint', 'payload.waypoints']);
+                $order = Order::findRecordOrFail($id, [
+                    'driverAssigned',
+                    'payload.entities',
+                    'payload.pickup',
+                    'payload.dropoff',
+                    'payload.return',
+                    'payload.currentWaypoint',
+                    'payload.waypoints',
+                    'payload.waypointMarkers.place',
+                    'payload.waypointMarkers.trackingNumber.status',
+                ]);
             } catch (ModelNotFoundException $exception) {
                 return response()->apiError('Order resource not found.', 404);
             }
@@ -1094,37 +1108,8 @@ class OrderController extends Controller
         /** @var \Fleetbase\LaravelMysqlSpatial\Types\Point */
         $location = $order->getLastLocation();
 
-        // Check if multiple waypoint order to update activity for
-        $isMultipleWaypointOrder = (bool) $order->payload->isMultipleDropOrder;
-
-        // if is multi drop order and no current destination set it
-        if ($isMultipleWaypointOrder && !$order->payload->current_waypoint_uuid) {
-            $order->payload->setFirstWaypoint($activity, $location);
-        }
-
-        // Handle multiple dropoff waypoint activity
-        if (Utils::isActivity($activity) && $activity->completesOrder() && $isMultipleWaypointOrder) {
-            // Check if every waypoint is completed
-            $isCompleted = $order->payload->waypointMarkers->every(function ($waypoint) {
-                return $waypoint->complete;
-            });
-
-            // only update activity for waypoint
-            if (!$isCompleted) {
-                $order->payload->updateWaypointActivity($activity, $location, $proof);
-                $order->payload->setNextWaypointDestination();
-                $order->payload->load('waypointMarkers');
-
-                // recheck if order is completed
-                $isFullyCompleted = $order->payload->waypointMarkers->every(function ($waypoint) {
-                    return $waypoint->complete;
-                });
-
-                if (!$isFullyCompleted) {
-                    return new OrderResource($order);
-                }
-            }
-        }
+        // Check if multiple waypoint order to update activity for.
+        $isMultipleWaypointOrder = $this->payloadHasWaypoints($order->payload);
 
         // also update for each order entities if not multiple drop order
         // all entities will share the same activity status as is one drop order
@@ -1136,23 +1121,48 @@ class OrderController extends Controller
             foreach ($order->payload->entities as $entity) {
                 $entity->insertActivity($activity, $location, $proof);
             }
-        } else {
-            // Update parent order when status is `dispatched` or `started`
-            if (in_array($activity->code, ['started', 'dispatched'])) {
-                $order->updateActivity($activity, $proof);
+            // Handle order completion
+            if (Utils::isActivity($activity) && $activity->completesOrder()) {
+                $order->driverAssigned?->unassignCurrentJob();
+                $order->complete($this->resolveProof($proof));
             }
 
-            $order->payload->updateWaypointActivity($activity, $location);
+            return new OrderResource($order);
+        }
+
+        if ($activity->is('started')) {
+            $order->updateActivity($activity, $proof);
+
+            $this->ensurePayloadCurrentServiceStop($order->payload);
+            if (!$this->payloadHasCurrentServiceStopActivity($order->payload, $activity)) {
+                $this->updateCurrentServiceStopActivity($order, $activity, $location, $proof);
+            }
+
+            return new OrderResource($order->refresh());
+        }
+
+        $currentStop               = $this->ensurePayloadCurrentServiceStop($order->payload);
+        $isCompletingCurrentStop   = Utils::isActivity($activity) && $activity->complete();
+
+        $this->updateCurrentServiceStopActivity($order, $activity, $location, $proof);
+
+        if (Utils::isActivity($activity) && $activity->is('canceled')) {
+            $order->driverAssigned?->unassignCurrentJob();
+            $order->cancel();
+
+            return new OrderResource($order->refresh());
         }
 
-        // Handle order completion
         if (Utils::isActivity($activity) && $activity->completesOrder()) {
-            // unset from driver current job
-            $order->driverAssigned->unassignCurrentJob();
-            $order->complete();
+            $nextStop = $isCompletingCurrentStop ? $this->advanceCurrentServiceStopDestination($order, $order->payload) : null;
+
+            if (!$nextStop || !$currentStop) {
+                $order->driverAssigned?->unassignCurrentJob();
+                $order->complete($this->resolveProof($proof));
+            }
         }
 
-        return new OrderResource($order);
+        return new OrderResource($order->refresh());
     }
 
     /**
@@ -1165,7 +1175,14 @@ class OrderController extends Controller
         $waypointId = $request->input('waypoint');
 
         try {
-            $order = Order::findRecordOrFail($id, ['payload']);
+            $order = Order::findRecordOrFail($id, [
+                'payload.pickup',
+                'payload.dropoff',
+                'payload.return',
+                'payload.waypoints',
+                'payload.waypointMarkers.place',
+                'payload.waypointMarkers.trackingNumber.status',
+            ]);
         } catch (ModelNotFoundException $exception) {
             return response()->json(
                 [
@@ -1175,19 +1192,16 @@ class OrderController extends Controller
             );
         }
 
-        // Get waypoint record if available
-        $waypoint = null;
+        $stop = null;
         if ($waypointId) {
-            $waypoint = Waypoint::where('payload_uuid', $order->payload_uuid)->whereHas('place', function ($query) use ($waypointId) {
-                $query->where('public_id', $waypointId);
-            })->first();
+            $stop = $this->resolveServiceStopFromKey($order->payload, $waypointId);
         }
 
         $orderConfig = $order->ensureOrderConfig();
         if (!$orderConfig) {
             return response()->apiError('No order config found for order.');
         }
-        $activities = $orderConfig->nextActivity($waypoint);
+        $activities = $stop ? $this->nextActivitiesForServiceStop($order, $order->payload, $stop) : $orderConfig->nextActivity();
 
         // If activity is to complete order add proof of delivery properties if required
         // This is a temporary fix until activity is updated to handle POD on it's own
@@ -1282,7 +1296,18 @@ class OrderController extends Controller
     public function setDestination(string $id, string $placeId)
     {
         try {
-            $order = Order::findRecordOrFail($id, ['payload.waypoints', 'payload.pickup', 'payload.dropoff', 'driverAssigned', 'vehicleAssigned', 'customer', 'facilitator']);
+            $order = Order::findRecordOrFail($id, [
+                'payload.pickup',
+                'payload.dropoff',
+                'payload.return',
+                'payload.waypoints',
+                'payload.waypointMarkers.place',
+                'payload.waypointMarkers.trackingNumber.status',
+                'driverAssigned',
+                'vehicleAssigned',
+                'customer',
+                'facilitator',
+            ]);
         } catch (ModelNotFoundException $exception) {
             return response()->apiError('Order resource not found.', 404);
         }
@@ -1290,17 +1315,13 @@ class OrderController extends Controller
         // Get the order payload
         $payload = $order->payload;
 
-        // Resolve the place
-        $place = $payload->waypoints->firstWhere('public_id', $placeId)
-            ?? (($payload->pickup && $payload->pickup->public_id === $placeId) ? $payload->pickup : null)
-            ?? (($payload->dropoff && $payload->dropoff->public_id === $placeId) ? $payload->dropoff : null);
-
-        if (!$place) {
+        $stop = $this->resolveServiceStopFromKey($payload, $placeId);
+        if (!$stop) {
             return response()->apiError('Place resource is not a valid destination.', 422);
         }
 
         // Persist destination choice
-        $payload->setCurrentWaypoint($place);
+        $this->setPayloadCurrentServiceStop($payload, $stop);
 
         return new OrderResource($order->refresh());
     }
@@ -1385,7 +1406,7 @@ class OrderController extends Controller
 
         // Load Order
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = Order::findRecordOrFail($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
         } catch (ModelNotFoundException $e) {
             return response()->apiError('Order resource not found.', 404);
         }
@@ -1580,7 +1601,7 @@ class OrderController extends Controller
 
         // Load Order
         try {
-            $order = Order::findRecordOrFail($id);
+            $order = Order::findRecordOrFail($id, ['payload.pickup', 'payload.dropoff', 'payload.return', 'payload.waypoints', 'payload.waypointMarkers.place']);
         } catch (ModelNotFoundException $e) {
             return response()->apiError('Order resource not found.', 404);
         }
@@ -1678,6 +1699,13 @@ class OrderController extends Controller
             return $order;
         }
 
+        if (in_array($type, ['place', 'waypoint'], true)) {
+            $stop = $this->resolveServiceStopFromKey($order->payload, $subjectId);
+            if ($stop) {
+                return ($stop['waypoint'] ?? null) instanceof Waypoint ? $stop['waypoint'] : ($stop['place'] ?? $order);
+            }
+        }
+
         return match ($type) {
             'place', 'waypoint' => Waypoint::withoutGlobalScopes()
                 ->where('payload_uuid', $order->payload_uuid)

package/server/src/Http/Controllers/Api/v1/ServiceAreaController.php

@@ -24,7 +24,7 @@ class ServiceAreaController extends Controller
     public function create(CreateServiceAreaRequest $request)
     {
         // get request input
-        $input = $request->only(['name', 'type', 'status', 'country', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
+        $input = $request->only(['name', 'type', 'status', 'country', 'border', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
 
         // get radius for creating service area border - default to 500 meters
         $radius = (int) $request->input('radius', 500);
@@ -99,7 +99,7 @@ class ServiceAreaController extends Controller
         }
 
         // get request input
-        $input = $request->only(['name', 'type', 'status', 'country', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
+        $input = $request->only(['name', 'type', 'status', 'country', 'border', 'color', 'stroke_color', 'trigger_on_entry', 'trigger_on_exit', 'dwell_threshold_minutes', 'speed_limit_kmh']);
 
         // get radius for creating service area border - default to 500 meters
         $radius = $request->input('radius', 500);

package/server/src/Http/Controllers/Api/v1/VehicleController.php

@@ -67,7 +67,7 @@ class VehicleController extends Controller
         $vehicle = Vehicle::create($input);
 
         // driver assignment
-        if ($request->has('driver')) {
+        if ($request->exists('driver') && !empty($request->input('driver'))) {
             // set this vehicle to the driver
             try {
                 $driver = Driver::findRecordOrFail($request->input('driver'));
@@ -80,8 +80,7 @@ class VehicleController extends Controller
                 );
             }
 
-            $driver->vehicle_uuid = $vehicle->uuid;
-            $driver->save();
+            $vehicle->assignDriver($driver);
         }
 
         // response the driver resource
@@ -150,6 +149,24 @@ class VehicleController extends Controller
         // save the update
         $vehicle->save();
 
+        if ($request->exists('driver')) {
+            if (empty($request->input('driver'))) {
+                $vehicle->unassignDriver();
+            } else {
+                try {
+                    $driver = Driver::findRecordOrFail($request->input('driver'));
+                    $vehicle->assignDriver($driver);
+                } catch (\Illuminate\Database\Eloquent\ModelNotFoundException $exception) {
+                    return response()->json(
+                        [
+                            'error' => 'The driver attempted to assign this vehicle was not found.',
+                        ],
+                        404
+                    );
+                }
+            }
+        }
+
         // get udpated vehicle
         $vehicle = $vehicle->refresh();
 

package/server/src/Http/Controllers/Internal/v1/ContactController.php

@@ -28,6 +28,7 @@ class ContactController extends FleetOpsController
     public function onBeforeCreate(Request $request, array &$input)
     {
         $this->resolveUserInput($request, $input);
+        $this->assertCustomerIdentityIsAvailable($input);
     }
 
     /**
@@ -40,6 +41,7 @@ class ContactController extends FleetOpsController
         }
 
         $this->resolveUserInput($request, $input);
+        $this->assertCustomerIdentityIsAvailable($input, $contact);
     }
 
     /**
@@ -146,4 +148,21 @@ class ContactController extends FleetOpsController
         $input['user_uuid'] = User::where('uuid', $user)->orWhere('public_id', $user)->value('uuid') ?? $user;
         unset($input['user']);
     }
+
+    private function assertCustomerIdentityIsAvailable(array $input, ?Contact $contact = null): void
+    {
+        $type = data_get($input, 'type', $contact?->type);
+        if ($type !== 'customer') {
+            return;
+        }
+
+        $customer = $contact ? $contact->replicate() : new Contact();
+        if ($contact) {
+            $customer->forceFill($contact->getAttributes());
+            $customer->exists = $contact->exists;
+        }
+
+        $customer->forceFill($input);
+        $customer->assertCustomerIdentityIsAvailable();
+    }
 }

package/server/src/Http/Controllers/Internal/v1/LiveController.php

@@ -22,6 +22,10 @@ use Illuminate\Http\Request;
  */
 class LiveController extends Controller
 {
+    protected const DEFAULT_VIEWPORT_LIMIT    = 500;
+    protected const MAX_VIEWPORT_LIMIT        = 1000;
+    protected const VIEWPORT_BOUNDS_PRECISION = 4;
+
     /**
      * Get coordinates for active orders.
      *
@@ -134,33 +138,19 @@ class LiveController extends Controller
      */
     public function drivers(Request $request)
     {
-        $bounds      = $request->input('bounds'); // Map viewport bounds: [south, west, north, east]
-        $cacheParams = ['bounds' => $bounds];
+        $bounds      = $this->normalizeLiveBounds($request);
+        $limit       = $this->normalizeLiveLimit($request);
+        $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
 
-        return LiveCacheService::remember('drivers', $cacheParams, function () use ($bounds) {
+        return LiveCacheService::remember('drivers', $cacheParams, function () use ($bounds, $limit) {
             $query = Driver::where(['company_uuid' => session('company')])
                 ->with(['user', 'vehicle'])
                 ->applyDirectivesForPermissions('fleet-ops list driver');
 
-            // Filter out drivers with invalid coordinates
-            $query->whereNotNull('location')
-                ->whereRaw('
-                    ST_Y(location) BETWEEN -90 AND 90
-                    AND ST_X(location) BETWEEN -180 AND 180
-                    AND NOT (ST_X(location) = 0 AND ST_Y(location) = 0)
-                ');
-
-            // Apply spatial filtering if bounds are provided
-            if ($bounds && is_array($bounds) && count($bounds) === 4) {
-                [$south, $west, $north, $east] = $bounds;
-
-                // Use MySQL spatial functions for POINT column
-                // ST_Within checks if location is within the bounding box
-                $query->whereRaw(
-                    'ST_Within(location, ST_MakeEnvelope(POINT(?, ?), POINT(?, ?)))',
-                    [$west, $south, $east, $north]
-                );
-            }
+            $this->applyLiveLocationGuards($query);
+            $this->applyLiveViewportBounds($query, $bounds);
+
+            $query->orderByDesc('updated_at')->orderByDesc('id')->limit($limit);
 
             $drivers = $query->get();
 
@@ -175,34 +165,20 @@ class LiveController extends Controller
      */
     public function vehicles(Request $request)
     {
-        $bounds      = $request->input('bounds'); // Map viewport bounds: [south, west, north, east]
-        $cacheParams = ['bounds' => $bounds];
+        $bounds      = $this->normalizeLiveBounds($request);
+        $limit       = $this->normalizeLiveLimit($request);
+        $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
 
-        return LiveCacheService::remember('vehicles', $cacheParams, function () use ($bounds) {
+        return LiveCacheService::remember('vehicles', $cacheParams, function () use ($bounds, $limit) {
             // Fetch vehicles that are online
             $query = Vehicle::where(['company_uuid' => session('company')])
                 ->with(['devices', 'driver'])
                 ->applyDirectivesForPermissions('fleet-ops list vehicle');
 
-            // Filter out vehicles with invalid coordinates
-            $query->whereNotNull('location')
-                ->whereRaw('
-                    ST_Y(location) BETWEEN -90 AND 90
-                    AND ST_X(location) BETWEEN -180 AND 180
-                    AND NOT (ST_X(location) = 0 AND ST_Y(location) = 0)
-                ');
-
-            // Apply spatial filtering if bounds are provided
-            if ($bounds && is_array($bounds) && count($bounds) === 4) {
-                [$south, $west, $north, $east] = $bounds;
-
-                // Use MySQL spatial functions for POINT column
-                // ST_Within checks if location is within the bounding box
-                $query->whereRaw(
-                    'ST_Within(location, ST_MakeEnvelope(POINT(?, ?), POINT(?, ?)))',
-                    [$west, $south, $east, $north]
-                );
-            }
+            $this->applyLiveLocationGuards($query);
+            $this->applyLiveViewportBounds($query, $bounds);
+
+            $query->orderByDesc('updated_at')->orderByDesc('id')->limit($limit);
 
             $vehicles = $query->get();
 
@@ -217,39 +193,98 @@ class LiveController extends Controller
      */
     public function places(Request $request)
     {
+        $bounds = $this->normalizeLiveBounds($request);
+        $limit  = $this->normalizeLiveLimit($request);
+
         // Cache key includes filter parameters
-        $cacheParams = $request->only(['query', 'type', 'country', 'limit', 'bounds']);
+        $cacheParams = array_merge($request->only(['query', 'type', 'country']), [
+            'bounds' => $bounds,
+            'limit'  => $limit,
+        ]);
 
-        return LiveCacheService::remember('places', $cacheParams, function () use ($request) {
+        return LiveCacheService::remember('places', $cacheParams, function () use ($request, $bounds, $limit) {
             // Query places based on filters
             $query = Place::where(['company_uuid' => session('company')])
                 ->filter(new PlaceFilter($request))
                 ->applyDirectivesForPermissions('fleet-ops list place');
 
-            // Filter out places with invalid coordinates
-            $query->whereNotNull('location')
-                ->whereRaw('
-                    ST_Y(location) BETWEEN -90 AND 90
-                    AND ST_X(location) BETWEEN -180 AND 180
-                    AND NOT (ST_X(location) = 0 AND ST_Y(location) = 0)
-                ');
-
-            // Apply spatial filtering if bounds are provided
-            $bounds = $request->input('bounds');
-            if ($bounds && is_array($bounds) && count($bounds) === 4) {
-                [$south, $west, $north, $east] = $bounds;
-
-                // Use MySQL spatial functions for POINT column
-                // ST_Within checks if location is within the bounding box
-                $query->whereRaw(
-                    'ST_Within(location, ST_MakeEnvelope(POINT(?, ?), POINT(?, ?)))',
-                    [$west, $south, $east, $north]
-                );
-            }
+            $this->applyLiveLocationGuards($query);
+            $this->applyLiveViewportBounds($query, $bounds);
+
+            $query->orderByDesc('updated_at')->orderByDesc('id')->limit($limit);
 
             $places = $query->get();
 
             return PlaceIndexResource::collection($places);
         });
     }
+
+    protected function normalizeLiveBounds(Request $request): ?array
+    {
+        $bounds = $request->input('bounds');
+
+        if (!is_array($bounds) || count($bounds) !== 4) {
+            return null;
+        }
+
+        $bounds = array_values($bounds);
+
+        if (array_filter($bounds, fn ($value) => !is_numeric($value))) {
+            return null;
+        }
+
+        [$south, $west, $north, $east] = array_map('floatval', $bounds);
+
+        if ($south < -90 || $south > 90 || $north < -90 || $north > 90) {
+            return null;
+        }
+
+        if ($west < -180 || $west > 180 || $east < -180 || $east > 180) {
+            return null;
+        }
+
+        if ($south > $north || $west > $east) {
+            return null;
+        }
+
+        return array_map(
+            fn ($value) => round($value, static::VIEWPORT_BOUNDS_PRECISION),
+            [$south, $west, $north, $east]
+        );
+    }
+
+    protected function normalizeLiveLimit(Request $request): int
+    {
+        $limit = (int) $request->input('limit', static::DEFAULT_VIEWPORT_LIMIT);
+
+        if ($limit < 1) {
+            return static::DEFAULT_VIEWPORT_LIMIT;
+        }
+
+        return min($limit, static::MAX_VIEWPORT_LIMIT);
+    }
+
+    protected function applyLiveLocationGuards($query): void
+    {
+        $query->whereNotNull('location')
+            ->whereRaw('
+                ST_Y(location) BETWEEN -90 AND 90
+                AND ST_X(location) BETWEEN -180 AND 180
+                AND NOT (ST_X(location) = 0 AND ST_Y(location) = 0)
+            ');
+    }
+
+    protected function applyLiveViewportBounds($query, ?array $bounds): void
+    {
+        if (!$bounds) {
+            return;
+        }
+
+        [$south, $west, $north, $east] = $bounds;
+
+        $query->whereRaw(
+            'ST_Y(location) BETWEEN ? AND ? AND ST_X(location) BETWEEN ? AND ?',
+            [$south, $north, $west, $east]
+        );
+    }
 }