@fleetbase/fleetops-engine 0.6.20 → 0.6.22

package/server/src/Contracts/TelematicProviderInterface.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Fleetbase\FleetOps\Contracts;
+
+use Fleetbase\FleetOps\Models\Telematic;
+
+/**
+ * Interface TelematicProviderInterface.
+ *
+ * Core contract that all telematics providers must implement.
+ * Defines the standard methods for authentication, device discovery,
+ * webhook handling, and data normalization.
+ */
+interface TelematicProviderInterface
+{
+    /**
+     * Connect to the provider using the given telematic configuration.
+     */
+    public function connect(Telematic $telematic): void;
+
+    /**
+     * Test the connection to the provider.
+     *
+     * @param array $credentials Provider credentials
+     *
+     * @return array ['success' => bool, 'message' => string, 'metadata' => array]
+     */
+    public function testConnection(array $credentials): array;
+
+    /**
+     * Fetch devices from the provider.
+     *
+     * @param array $options Options including limit, cursor, filters
+     *
+     * @return array ['devices' => array, 'next_cursor' => string|null, 'has_more' => bool]
+     */
+    public function fetchDevices(array $options = []): array;
+
+    /**
+     * Fetch detailed information for a specific device.
+     *
+     * @param string $externalId Provider's device identifier
+     *
+     * @return array Device details
+     */
+    public function fetchDeviceDetails(string $externalId): array;
+
+    /**
+     * Normalize a device payload from the provider into FleetOps format.
+     *
+     * @param array $payload Raw device data from provider
+     *
+     * @return array Normalized device data
+     */
+    public function normalizeDevice(array $payload): array;
+
+    /**
+     * Normalize an event payload from the provider into FleetOps format.
+     *
+     * @param array $payload Raw event data from provider
+     *
+     * @return array Normalized event data
+     */
+    public function normalizeEvent(array $payload): array;
+
+    /**
+     * Normalize sensor data from the provider into FleetOps format.
+     *
+     * @param array $payload Raw sensor data from provider
+     *
+     * @return array Normalized sensor data
+     */
+    public function normalizeSensor(array $payload): array;
+
+    /**
+     * Validate a webhook signature.
+     *
+     * @param string $payload     Raw webhook payload
+     * @param string $signature   Signature from webhook headers
+     * @param array  $credentials Provider credentials
+     *
+     * @return bool True if signature is valid
+     */
+    public function validateWebhookSignature(string $payload, string $signature, array $credentials): bool;
+
+    /**
+     * Process a webhook payload from the provider.
+     *
+     * @param array $payload Webhook payload
+     * @param array $headers Webhook headers
+     *
+     * @return array ['devices' => array, 'events' => array, 'sensors' => array]
+     */
+    public function processWebhook(array $payload, array $headers = []): array;
+
+    /**
+     * Get the provider's credential schema.
+     *
+     * @return array Array of field definitions
+     */
+    public function getCredentialSchema(): array;
+
+    /**
+     * Check if the provider supports webhooks.
+     */
+    public function supportsWebhooks(): bool;
+
+    /**
+     * Check if the provider supports device discovery.
+     */
+    public function supportsDiscovery(): bool;
+
+    /**
+     * Get rate limit information for the provider.
+     *
+     * @return array ['requests_per_minute' => int, 'burst_size' => int]
+     */
+    public function getRateLimits(): array;
+}

package/server/src/Exceptions/TelematicProviderException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exceptions;
+
+use Exception;
+
+/**
+ * Class TelematicProviderException.
+ *
+ * Base exception for provider-related errors.
+ */
+class TelematicProviderException extends \Exception
+{
+}

package/server/src/Exceptions/TelematicRateLimitExceededException.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exceptions;
+
+/**
+ * Class TelematicRateLimitExceededException.
+ *
+ * Exception thrown when provider rate limit is exceeded.
+ */
+class TelematicRateLimitExceededException extends ProviderException
+{
+}

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

@@ -343,23 +343,34 @@ class DriverController extends Controller
         // check if driver needs a geocoded update to set city and country they are currently in
         $isGeocodable = Carbon::parse($driver->updated_at)->diffInMinutes(Carbon::now(), false) > 10 || empty($driver->country) || empty($driver->city);
 
-        $driver->update([
-            'location' => new Point($latitude, $longitude),
-            'altitude' => $altitude,
-            'heading'  => $heading,
-            'speed'    => $speed,
-        ]);
+        $positionData = [
+            'location'  => new Point($latitude, $longitude),
+            'latitude'  => $latitude,
+            'longitude' => $longitude,
+            'altitude'  => $altitude,
+            'heading'   => $heading,
+            'speed'     => $speed,
+        ];
+
+        // Append current order to data if applicable
+        $order = $driver->getCurrentOrder();
+        if ($order) {
+            $positionData['order_uuid'] = $order->uuid;
+            // Get destination
+            $destination  = $order->payload?->getPickupOrCurrentWaypoint();
+            if ($destination) {
+                $positionData['destination_uuid'] = $destination->uuid;
+            }
+        }
+
+        $driver->update($positionData);
+        $driver->createPosition($positionData);
 
         // If vehicle is assigned to driver load it and sync position data
         $driver->loadMissing('vehicle');
         if ($driver->vehicle) {
-            $driver->vehicle->update([
-                'location' => new Point($latitude, $longitude),
-                'altitude' => $altitude,
-                'heading'  => $heading,
-                'speed'    => $speed,
-            ]);
-            $driver->vehicle->createPositionWithOrderContext();
+            $driver->vehicle->update($positionData);
+            $driver->vehicle->createPosition($positionData);
             broadcast(new VehicleLocationChanged($driver->vehicle, ['driver' => $driver->public_id]));
         }
 
@@ -376,7 +387,6 @@ class DriverController extends Controller
         }
 
         broadcast(new DriverLocationChanged($driver));
-        $driver->createPositionWithOrderContext();
 
         return new DriverResource($driver);
     }

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

@@ -235,15 +235,35 @@ class VehicleController extends Controller
             );
         }
 
-        $vehicle->update([
-            'location' => new Point($latitude, $longitude),
-            'altitude' => $altitude,
-            'heading'  => $heading,
-            'speed'    => $speed,
-        ]);
+        $positionData = [
+            'location'  => new Point($latitude, $longitude),
+            'latitude'  => $latitude,
+            'longitude' => $longitude,
+            'altitude'  => $altitude,
+            'heading'   => $heading,
+            'speed'     => $speed,
+        ];
+
+        // Get vehicle driver
+        $vehicle->loadMissing('driver');
+        $driver = $vehicle->driver;
+        if ($driver) {
+            // Append current order to data if applicable
+            $order = $driver->getCurrentOrder();
+            if ($order) {
+                $positionData['order_uuid'] = $order->uuid;
+                // Get destination
+                $destination  = $order->payload?->getPickupOrCurrentWaypoint();
+                if ($destination) {
+                    $positionData['destination_uuid'] = $destination->uuid;
+                }
+            }
+        }
+
+        $vehicle->update($positionData);
+        $vehicle->createPosition($positionData);
 
         broadcast(new VehicleLocationChanged($vehicle));
-        $vehicle->createPositionWithOrderContext();
 
         return new VehicleResource($vehicle);
     }

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

@@ -12,4 +12,26 @@ class DeviceController extends FleetOpsController
      * @var string
      */
     public $resource = 'device';
+
+    /**
+     * Query callback when querying record.
+     *
+     * @param \Illuminate\Database\Query\Builder $query
+     * @param Request                            $request
+     */
+    public static function onQueryRecord($query, $request): void
+    {
+        $query->with(['telematic', 'warranty']);
+    }
+
+    /**
+     * Query callback when finding record.
+     *
+     * @param \Illuminate\Database\Query\Builder $query
+     * @param Request                            $request
+     */
+    public static function onFindRecord($query, $request): void
+    {
+        $query->with(['telematic', 'warranty']);
+    }
 }

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

@@ -0,0 +1,240 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
+
+use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Jobs\ReplayPositions;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Support\Utils;
+use Illuminate\Http\Request;
+
+class PositionController extends FleetOpsController
+{
+    /**
+     * The resource to query.
+     *
+     * @var string
+     */
+    public $resource = 'position';
+
+    /**
+     * Replay positions on a custom channel.
+     *
+     * @return \Illuminate\Http\Response
+     */
+    public function replay(Request $request)
+    {
+        $positionIds = $request->input('position_ids', []);
+        $channelId   = $request->input('channel_id');
+        $speed       = max((float) $request->input('speed', 1), 0.1); // avoid division by zero
+        $subjectUuid = $request->input('subject_uuid');
+
+        if (!$channelId) {
+            return response()->error('Channel ID is required');
+        }
+
+        if (empty($positionIds)) {
+            return response()->error('Position IDs are required');
+        }
+
+        $positions = Position::whereIn('uuid', $positionIds)
+            ->where('company_uuid', session('company'))
+            ->orderBy('created_at')
+            ->get();
+
+        if ($positions->isEmpty()) {
+            return response()->error('No positions found');
+        }
+
+        // Dispatch async job (will handle replay logic)
+        ReplayPositions::dispatch($positions, $channelId, $speed, $subjectUuid);
+
+        return response()->json([
+            'status'          => 'ok',
+            'message'         => 'Replay started',
+            'channel_id'      => $channelId,
+            'total_positions' => $positions->count(),
+        ]);
+    }
+
+    /**
+     * Get position statistics/metrics.
+     *
+     * @return \Illuminate\Http\Response
+     */
+    public function metrics(Request $request)
+    {
+        $positionIds = $request->input('position_ids', []);
+
+        if (empty($positionIds)) {
+            return response()->error('Position IDs are required');
+        }
+
+        $positions = Position::whereIn('uuid', $positionIds)
+            ->where('company_uuid', session('company'))
+            ->orderBy('created_at', 'asc')
+            ->get();
+
+        if ($positions->isEmpty()) {
+            return response()->json([
+                'metrics' => [],
+            ]);
+        }
+
+        // Calculate metrics
+        $metrics = $this->calculateMetrics($positions);
+
+        return response()->json([
+            'metrics' => $metrics,
+        ]);
+    }
+
+    /**
+     * Calculate metrics from positions.
+     *
+     * @param \Illuminate\Support\Collection $positions
+     *
+     * @return array
+     */
+    private function calculateMetrics($positions)
+    {
+        $totalDistance         = 0;
+        $maxSpeed              = 0;
+        $avgSpeed              = 0;
+        $speedingEvents        = [];
+        $dwellTimes            = [];
+        $accelerationEvents    = [];
+        $speedLimit            = 100; // km/h - configurable
+        $dwellThreshold        = 300; // 5 minutes in seconds
+        $accelerationThreshold = 2.5; // m/s²
+
+        $previousPosition = null;
+        $previousSpeed    = null;
+        $dwellStart       = null;
+
+        foreach ($positions as $index => $position) {
+            $speed = $position->speed ?? 0;
+
+            // Track max speed
+            if ($speed > $maxSpeed) {
+                $maxSpeed = $speed;
+            }
+
+            // Check for speeding (convert m/s to km/h)
+            $speedKmh = $speed * 3.6;
+            if ($speedKmh > $speedLimit) {
+                $speedingEvents[] = [
+                    'position_uuid' => $position->uuid,
+                    'speed'         => round($speedKmh, 2),
+                    'timestamp'     => $position->created_at->toDateTimeString(),
+                ];
+            }
+
+            // Calculate distance and dwell time
+            if ($previousPosition) {
+                // Calculate distance using Haversine formula
+                // $distance = $this->calculateDistance($previousPosition, $position);
+                $distance = Utils::vincentyGreatCircleDistance($previousPosition->coordinates, $position->coordinates);
+                // dd($previousPosition, $position, $distance);
+                $totalDistance += $distance;
+
+                // Check for dwell (low speed or no movement)
+                if ($speed < 0.5) { // Less than 0.5 m/s
+                    if ($dwellStart === null) {
+                        $dwellStart = $previousPosition->created_at;
+                    }
+                } else {
+                    if ($dwellStart !== null) {
+                        $dwellDuration = $previousPosition->created_at->diffInSeconds($dwellStart);
+                        if ($dwellDuration >= $dwellThreshold) {
+                            $dwellTimes[] = [
+                                'start'    => $dwellStart->toDateTimeString(),
+                                'end'      => $previousPosition->created_at->toDateTimeString(),
+                                'duration' => $dwellDuration,
+                            ];
+                        }
+                        $dwellStart = null;
+                    }
+                }
+
+                // Calculate acceleration
+                if ($previousSpeed !== null) {
+                    $timeDiff = $position->created_at->diffInSeconds($previousPosition->created_at);
+                    if ($timeDiff > 0) {
+                        $acceleration = abs($speed - $previousSpeed) / $timeDiff;
+                        if ($acceleration > $accelerationThreshold) {
+                            $accelerationEvents[] = [
+                                'position_uuid' => $position->uuid,
+                                'acceleration'  => round($acceleration, 2),
+                                'type'          => $speed > $previousSpeed ? 'acceleration' : 'deceleration',
+                                'timestamp'     => $position->created_at->toDateTimeString(),
+                            ];
+                        }
+                    }
+                }
+            }
+
+            $previousPosition = $position;
+            $previousSpeed    = $speed;
+        }
+
+        // Calculate average speed
+        $speeds   = $positions->pluck('speed')->filter()->toArray();
+        $avgSpeed = count($speeds) > 0 ? array_sum($speeds) / count($speeds) : 0;
+
+        // Calculate total duration
+        $firstPosition = $positions->first();
+        $lastPosition  = $positions->last();
+        $totalDuration = $lastPosition->created_at->diffInSeconds($firstPosition->created_at);
+
+        return [
+            'total_distance'      => round($totalDistance / 1000, 2), // Convert to km
+            'total_duration'      => $totalDuration, // seconds
+            'max_speed'           => round($maxSpeed * 3.6, 2), // km/h
+            'avg_speed'           => round($avgSpeed * 3.6, 2), // km/h
+            'speeding_events'     => $speedingEvents,
+            'speeding_count'      => count($speedingEvents),
+            'dwell_times'         => $dwellTimes,
+            'dwell_count'         => count($dwellTimes),
+            'acceleration_events' => $accelerationEvents,
+            'acceleration_count'  => count($accelerationEvents),
+            'total_positions'     => $positions->count(),
+        ];
+    }
+
+    /**
+     * Calculate distance between two positions using Haversine formula.
+     *
+     * @param Position $pos1
+     * @param Position $pos2
+     *
+     * @return float Distance in meters
+     */
+    private function calculateDistance($pos1, $pos2)
+    {
+        $coords1 = [$pos1->latitude, $pos1->longitude];
+        $coords2 = [$pos2->latitude, $pos2->longitude];
+
+        if (!isset($coords1[0]) || !isset($coords2[0]) || !isset($coords1[1]) || !isset($coords2[1])) {
+            return 0;
+        }
+
+        $lat1 = deg2rad($coords1[0]);
+        $lon1 = deg2rad($coords1[1]);
+        $lat2 = deg2rad($coords2[0]);
+        $lon2 = deg2rad($coords2[1]);
+
+        $earthRadius = 6371000; // meters
+
+        $dLat = $lat2 - $lat1;
+        $dLon = $lon2 - $lon1;
+
+        $a = sin($dLat / 2) * sin($dLat / 2) +
+            cos($lat1) * cos($lat2) *
+            sin($dLon / 2) * sin($dLon / 2);
+
+        $c = 2 * atan2(sqrt($a), sqrt(1 - $a));
+
+        return $earthRadius * $c;
+    }
+}

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

@@ -12,4 +12,15 @@ class SensorController extends FleetOpsController
      * @var string
      */
     public $resource = 'sensor';
+
+    /**
+     * Query callback when querying record.
+     *
+     * @param \Illuminate\Database\Query\Builder $query
+     * @param Request                            $request
+     */
+    public static function onQueryRecord($query, $request): void
+    {
+        $query->with(['telematic', 'warranty']);
+    }
 }

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

@@ -3,6 +3,11 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+use Fleetbase\FleetOps\Support\Telematics\TelematicService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
 
 class TelematicController extends FleetOpsController
 {
@@ -12,4 +17,140 @@ class TelematicController extends FleetOpsController
      * @var string
      */
     public $resource = 'telematic';
+
+    protected TelematicService $telematicService;
+    protected TelematicProviderRegistry $registry;
+
+    public function __construct(TelematicService $service, TelematicProviderRegistry $registry)
+    {
+        parent::__construct();
+        $this->telematicService  = $service;
+        $this->registry          = $registry;
+    }
+
+    /**
+     * Query callback when querying record.
+     *
+     * @param \Illuminate\Database\Query\Builder $query
+     * @param Request                            $request
+     */
+    public static function onQueryRecord($query, $request): void
+    {
+        $query->with(['warranty']);
+    }
+
+    /**
+     * List available providers.
+     */
+    public function providers(): JsonResponse
+    {
+        $providers = $this->registry->all()->map(fn ($p) => $p->toArray());
+
+        return response()->json($providers->values());
+    }
+
+    /**
+     * Test connection to provider.
+     */
+    public function testConnection(Request $request, string $id): JsonResponse
+    {
+        $telematic = Telematic::where('uuid', $id)
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+
+        $async = $request->input('async', false);
+
+        $result = $this->telematicService->testConnection($telematic, $async);
+
+        if ($async) {
+            return response()->json($result, 202);
+        }
+
+        return response()->json($result);
+    }
+
+    /**
+     * Test connection to provider.
+     */
+    public function testCredentials(Request $request, string $key): JsonResponse
+    {
+        $credentials = $request->array('credentials', []);
+        $async       = $request->input('async', false);
+
+        try {
+            $provider = $this->registry->resolve($key);
+            if (!$provider) {
+                return response()->error('Unable to resolve telematic provider.');
+            }
+            $result   = $provider->testConnection($credentials);
+        } catch (\Exception $e) {
+            return response()->error($e->getMessage());
+        }
+
+        if ($async) {
+            return response()->json($result, 202);
+        }
+
+        return response()->json($result);
+    }
+
+    /**
+     * Discover devices from provider.
+     */
+    public function discover(Request $request, string $id): JsonResponse
+    {
+        $telematic = Telematic::where('uuid', $id)
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+
+        $jobId = $this->telematicService->discoverDevices($telematic, [
+            'limit'   => $request->input('limit', 100),
+            'filters' => $request->input('filters', []),
+        ]);
+
+        return response()->json([
+            'job_id'  => $jobId,
+            'message' => 'Device discovery initiated',
+        ], 202);
+    }
+
+    /**
+     * Get devices for a telematic.
+     */
+    public function devices(Request $request, string $id): JsonResponse
+    {
+        $telematic = Telematic::where('uuid', $id)
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+
+        $devices = $this->telematicService->getDevices($telematic, [
+            'status' => $request->input('status'),
+            'search' => $request->input('search'),
+        ]);
+
+        return response()->json([
+            'data' => $devices,
+        ]);
+    }
+
+    /**
+     * Link a device to a telematic.
+     */
+    public function linkDevice(Request $request, string $id): JsonResponse
+    {
+        $telematic = Telematic::where('uuid', $id)
+            ->where('company_uuid', session('company'))
+            ->firstOrFail();
+
+        $request->validate([
+            'external_id' => 'required|string',
+            'device_name' => 'required|string',
+        ]);
+
+        $device = $this->telematicService->linkDevice($telematic, $request->all());
+
+        return response()->json([
+            'device' => $device,
+        ], 201);
+    }
 }