@fleetbase/fleetops-engine 0.6.20 → 0.6.21

package/server/migrations/2025_10_27_171322_fix_device_column_names.php

@@ -0,0 +1,107 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        /**
+         * Devices: rename columns WITHOUT doctrine/dbal (MySQL 8+).
+         */
+        DB::statement('ALTER TABLE devices RENAME COLUMN device_name TO name');
+        DB::statement('ALTER TABLE devices RENAME COLUMN device_type TO type');
+        DB::statement('ALTER TABLE devices RENAME COLUMN device_location TO location');
+        DB::statement('ALTER TABLE devices RENAME COLUMN device_model TO model');
+        DB::statement('ALTER TABLE devices RENAME COLUMN device_provider TO provider');
+
+        /**
+         * Devices: add new scalar cols + spatial POINT (nullable first!).
+         */
+        Schema::table('devices', function (Blueprint $table) {
+            $table->string('internal_id')->nullable()->after('device_id');
+            $table->string('imei')->nullable()->after('device_id');
+            $table->string('imsi')->nullable()->after('device_id');
+            $table->string('firmware_version')->nullable()->after('device_id');
+
+            // must be nullable now; we'll backfill and then make NOT NULL
+            $table->point('last_position')->nullable()->after('serial_number');
+        });
+
+        // Backfill existing rows so NOT NULL will succeed
+        DB::statement('UPDATE devices SET last_position = ST_SRID(POINT(0, 0), 4326) WHERE last_position IS NULL');
+
+        // Make column NOT NULL (and optionally enforce SRID at column level)
+        // If you want to enforce SRID on the column itself, uncomment the SRID variant:
+        // DB::statement('ALTER TABLE devices MODIFY last_position POINT NOT NULL SRID 4326');
+        DB::statement('ALTER TABLE devices MODIFY last_position POINT NOT NULL');
+
+        // NOW add the spatial index (requires NOT NULL)
+        Schema::table('devices', function (Blueprint $table) {
+            $table->spatialIndex('last_position', 'devices_last_position_spx');
+        });
+
+        /**
+         * Sensors: drop legacy column, add fields + POINT (nullable), backfill, NOT NULL, index.
+         */
+        Schema::table('sensors', function (Blueprint $table) {
+            if (Schema::hasColumn('sensors', 'sensor_type')) {
+                $table->dropColumn('sensor_type');
+            }
+
+            $table->foreignUuid('telematic_uuid')->nullable()->after('company_uuid')->constrained('telematics', 'uuid')->nullOnDelete();
+            $table->string('firmware_version')->nullable()->after('name');
+            $table->string('imei')->nullable()->after('name');
+            $table->string('imsi')->nullable()->after('name');
+            $table->string('serial_number')->nullable()->after('name');
+            $table->string('internal_id')->nullable()->after('name');
+            $table->string('status')->nullable()->after('last_value');
+
+            $table->point('last_position')->nullable()->after('serial_number');
+        });
+
+        DB::statement('UPDATE sensors SET last_position = ST_SRID(POINT(0, 0), 4326) WHERE last_position IS NULL');
+        DB::statement('ALTER TABLE sensors MODIFY last_position POINT NOT NULL');
+
+        Schema::table('sensors', function (Blueprint $table) {
+            $table->spatialIndex('last_position', 'sensors_last_position_spx');
+        });
+    }
+
+    public function down(): void
+    {
+        /**
+         * Devices: drop spatial index then column, drop added scalars, rename back.
+         */
+        Schema::table('devices', function (Blueprint $table) {
+            // drop index BEFORE dropping column
+            $table->dropSpatialIndex('devices_last_position_spx');
+            $table->dropColumn('last_position');
+
+            $table->dropColumn(['internal_id', 'imei', 'imsi', 'firmware_version']);
+        });
+
+        DB::statement('ALTER TABLE devices RENAME COLUMN name TO device_name');
+        DB::statement('ALTER TABLE devices RENAME COLUMN type TO device_type');
+        DB::statement('ALTER TABLE devices RENAME COLUMN location TO device_location');
+        DB::statement('ALTER TABLE devices RENAME COLUMN model TO device_model');
+        DB::statement('ALTER TABLE devices RENAME COLUMN provider TO device_provider');
+
+        /**
+         * Sensors: drop spatial index/column, drop new fields, restore sensor_type.
+         */
+        Schema::table('sensors', function (Blueprint $table) {
+            $table->dropSpatialIndex('sensors_last_position_spx');
+            $table->dropColumn('last_position');
+
+            $table->dropForeign(['telematic_uuid']);
+            $table->dropColumn(['telematic_uuid']);
+
+            $table->dropColumn(['serial_number', 'internal_id', 'imei', 'imsi', 'firmware_version', 'status']);
+
+            $table->string('sensor_type')->nullable()->after('slug');
+        });
+    }
+};

package/server/migrations/2025_10_27_203023_add_company_uuid_to_device_events_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('device_events', function (Blueprint $table) {
+            $table->foreignUuid('company_uuid')->nullable()->after('_key')->constrained('companies', 'uuid')->nullOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('device_events', function (Blueprint $table) {
+            $table->dropForeign(['company_uuid']);
+            $table->dropColumn(['company_uuid']);
+        });
+    }
+};

package/server/src/Console/Commands/ReplayVehicleLocations.php

@@ -0,0 +1,225 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Carbon\Carbon;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\Support\SocketCluster\SocketClusterService;
+use Illuminate\Console\Command;
+
+class ReplayVehicleLocations extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'vehicle:replay-locations 
+                            {file : Path to the JSON file containing vehicle location data}
+                            {--speed=1 : Speed multiplier for replay (1 = real-time, 2 = 2x speed, 0.5 = half speed)}
+                            {--vehicle= : Filter by specific vehicle ID (optional)}
+                            {--limit= : Limit the number of events to process (optional)}
+                            {--sleep= : Set a manual sleep for replay (in seconds)}
+                            {--skip-sleep : Skip sleep delays and send all events immediately}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Replay vehicle location events from JSON file with timing simulation via SocketCluster';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle()
+    {
+        $filePath        = $this->argument('file');
+        $speedMultiplier = (float) $this->option('speed');
+        $vehicleFilter   = $this->option('vehicle');
+        $limit           = $this->option('limit') ? (int) $this->option('limit') : null;
+        $skipSleep       = $this->option('skip-sleep');
+        $sleep           = $this->option('sleep') ? (int) $this->option('sleep') : null;
+
+        // Validate file exists
+        if (!file_exists($filePath)) {
+            $this->error("File not found: {$filePath}");
+
+            return Command::FAILURE;
+        }
+
+        // Validate speed multiplier
+        if ($speedMultiplier <= 0) {
+            $this->error('Speed multiplier must be greater than 0');
+
+            return Command::FAILURE;
+        }
+
+        $this->info('Starting vehicle location replay...');
+        $this->info("File: {$filePath}");
+        $this->info("Speed: {$speedMultiplier}x");
+
+        if ($vehicleFilter) {
+            $this->info("Filtering for vehicle: {$vehicleFilter}");
+        }
+
+        if ($skipSleep) {
+            $this->warn('Sleep delays disabled - sending all events immediately');
+        }
+
+        // Load and parse JSON data
+        $this->info('Loading location data...');
+        $jsonContent    = file_get_contents($filePath);
+        $locationEvents = json_decode($jsonContent, true);
+
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            $this->error('Failed to parse JSON: ' . json_last_error_msg());
+
+            return Command::FAILURE;
+        }
+
+        if (!is_array($locationEvents) || empty($locationEvents)) {
+            $this->error('Invalid or empty location data');
+
+            return Command::FAILURE;
+        }
+
+        // Filter by vehicle if specified
+        if ($vehicleFilter) {
+            $locationEvents = array_filter($locationEvents, function ($event) use ($vehicleFilter) {
+                return isset($event['data']['id']) && $event['data']['id'] === $vehicleFilter;
+            });
+            $locationEvents = array_values($locationEvents); // Re-index array
+        }
+
+        $totalEvents = count($locationEvents);
+
+        if ($totalEvents === 0) {
+            $this->warn('No events found matching the criteria');
+
+            return Command::SUCCESS;
+        }
+
+        // Apply limit if specified
+        if ($limit && $limit < $totalEvents) {
+            $locationEvents = array_slice($locationEvents, 0, $limit);
+            $totalEvents    = $limit;
+        }
+
+        $this->info("Total events to process: {$totalEvents}");
+        $this->newLine();
+
+        // Initialize SocketCluster client
+        $socketClusterClient = new SocketClusterService();
+
+        // Statistics tracking
+        $successCount      = 0;
+        $errorCount        = 0;
+        $startTime         = microtime(true);
+        $previousTimestamp = null;
+
+        // Process each location event
+        foreach ($locationEvents as $index => $event) {
+            $eventNumber = $index + 1;
+            $vehicleId   = $event['data']['id'] ?? 'unknown';
+            $eventId     = $event['id'] ?? 'unknown';
+            $createdAt   = $event['created_at'] ?? null;
+
+            // Get vehicle record
+            $vehicle = Vehicle::where('public_id', $vehicleId)->first();
+            if (!$vehicle) {
+                continue;
+            }
+
+            // Calculate sleep duration based on timestamp difference
+            if (!$skipSleep && $previousTimestamp !== null && $createdAt !== null) {
+                try {
+                    $currentTime   = Carbon::parse($createdAt);
+                    $previousTime  = Carbon::parse($previousTimestamp);
+                    $diffInSeconds = $currentTime->diffInSeconds($previousTime);
+
+                    // Apply speed multiplier
+                    $sleepDuration = $diffInSeconds / $speedMultiplier;
+
+                    if ($sleep) {
+                        $this->info("[{$eventNumber}/{$totalEvents}] Waiting {$sleep}s (real: {$diffInSeconds}s)...");
+                        sleep((int) $sleep);
+                    } elseif ($sleepDuration > 0) {
+                        $this->info("[{$eventNumber}/{$totalEvents}] Waiting {$sleepDuration}s (real: {$diffInSeconds}s)...");
+                        sleep((int) $sleepDuration);
+
+                        // Handle fractional seconds
+                        $fractional = $sleepDuration - floor($sleepDuration);
+                        if ($fractional > 0) {
+                            usleep((int) ($fractional * 1000000));
+                        }
+                    }
+                } catch (\Exception $e) {
+                    $this->warn("Failed to calculate time difference: {$e->getMessage()}");
+                }
+            }
+
+            // Update previous timestamp
+            $previousTimestamp = $createdAt;
+
+            // Prepare channel names
+            $channels = ["vehicle.{$vehicleId}", "vehicle.{$vehicle->uuid}"];
+
+            foreach ($channels as $channel) {
+                // Send event via SocketCluster
+                try {
+                    $sent = $socketClusterClient->send($channel, $event);
+
+                    $location = $event['data']['location']['coordinates'] ?? ['N/A', 'N/A'];
+                    $speed    = $event['data']['speed'] ?? 'N/A';
+                    $heading  = $event['data']['heading'] ?? 'N/A';
+
+                    $this->line(sprintf(
+                        "[{$eventNumber}/{$totalEvents}] ✓ Sent event %s for vehicle %s | Channel: %s | Coords: [%.6f, %.6f] | Speed: %s | Heading: %s | Time: %s",
+                        $eventId,
+                        $vehicleId,
+                        $channel,
+                        $location[0],
+                        $location[1],
+                        $speed,
+                        $heading,
+                        $createdAt ?? 'N/A'
+                    ));
+
+                    $successCount++;
+                } catch (\WebSocket\ConnectionException $e) {
+                    $this->error("[{$eventNumber}/{$totalEvents}] ✗ Connection error for event {$eventId}: {$e->getMessage()}");
+                    $errorCount++;
+                } catch (\WebSocket\TimeoutException $e) {
+                    $this->error("[{$eventNumber}/{$totalEvents}] ✗ Timeout error for event {$eventId}: {$e->getMessage()}");
+                    $errorCount++;
+                } catch (\Throwable $e) {
+                    $this->error("[{$eventNumber}/{$totalEvents}] ✗ Error for event {$eventId}: {$e->getMessage()}");
+                    $errorCount++;
+                }
+            }
+        }
+
+        // Summary
+        $endTime  = microtime(true);
+        $duration = round($endTime - $startTime, 2);
+
+        $this->newLine();
+        $this->info('=== Replay Complete ===');
+        $this->info("Total events processed: {$totalEvents}");
+        $this->info("Successful: {$successCount}");
+
+        if ($errorCount > 0) {
+            $this->error("Failed: {$errorCount}");
+        } else {
+            $this->info("Failed: {$errorCount}");
+        }
+
+        $this->info("Duration: {$duration}s");
+        $this->info('Average rate: ' . round($totalEvents / max($duration, 0.001), 2) . ' events/second');
+
+        return $errorCount > 0 ? Command::FAILURE : Command::SUCCESS;
+    }
+}

package/server/src/Contracts/TelematicProviderDescriptor.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Fleetbase\FleetOps\Contracts;
+
+use Fleetbase\FleetOps\Support\Utils;
+
+/**
+ * Class TelematicProviderDescriptor.
+ *
+ * Data Transfer Object for provider metadata.
+ * Used by the ProviderRegistry to describe available providers.
+ */
+class TelematicProviderDescriptor
+{
+    public string $key;
+    public string $label;
+    public string $type; // 'native' or 'custom'
+    public ?string $driverClass;
+    public ?string $icon;
+    public ?string $description;
+    public ?string $docsUrl;
+    public array $requiredFields;
+    public bool $supportsWebhooks;
+    public bool $supportsDiscovery;
+    public array $metadata;
+
+    /**
+     * Create a new ProviderDescriptor instance.
+     */
+    public function __construct(array $data)
+    {
+        $this->key               = $data['key'];
+        $this->label             = $data['label'];
+        $this->type              = $data['type'] ?? 'native';
+        $this->driverClass       = $data['driver_class'] ?? null;
+        $this->icon              = $data['icon'] ?? null;
+        $this->description       = $data['description'] ?? null;
+        $this->docsUrl           = $data['docs_url'] ?? null;
+        $this->requiredFields    = $data['required_fields'] ?? [];
+        $this->supportsWebhooks  = $data['supports_webhooks'] ?? false;
+        $this->supportsDiscovery = $data['supports_discovery'] ?? false;
+        $this->metadata          = $data['metadata'] ?? [];
+    }
+
+    /**
+     * Convert to array for JSON serialization.
+     */
+    public function toArray(): array
+    {
+        return [
+            'key'                => $this->key,
+            'label'              => $this->label,
+            'type'               => $this->type,
+            'icon'               => $this->icon,
+            'description'        => $this->description,
+            'docs_url'           => $this->docsUrl,
+            'required_fields'    => $this->requiredFields,
+            'supports_webhooks'  => $this->supportsWebhooks,
+            'supports_discovery' => $this->supportsDiscovery,
+            'metadata'           => $this->metadata,
+            'webhook_url'        => Utils::apiUrl('webhooks/telematics/' . $this->key),
+        ];
+    }
+
+    /**
+     * Get JSON representation.
+     */
+    public function toJson(): string
+    {
+        return json_encode($this->toArray());
+    }
+}

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);
     }