@fleetbase/fleetops-engine 0.6.20 → 0.6.22

package/server/config/telematics.php

@@ -0,0 +1,111 @@
+<?php
+
+return [
+    'providers' => [
+        [
+            'key' => 'flespi',
+            'label' => 'Flespi',
+            'type' => 'native',
+            'driver_class' => \Fleetbase\FleetOps\Support\Telematics\Providers\FlespiProvider::class,
+            'icon' => 'https://flespi.com/favicon.ico',
+            'description' => 'Flespi is a robust telematics platform offering device management, data processing, and API integration.',
+            'docs_url' => 'https://flespi.com/docs',
+            'required_fields' => [
+                [
+                    'name' => 'token',
+                    'label' => 'Flespi Token',
+                    'type' => 'password',
+                    'placeholder' => 'Enter your Flespi API token',
+                    'required' => true,
+                    'validation' => 'required|string|min:20',
+                ],
+                [
+                    'name' => 'webhook_secret',
+                    'label' => 'Webhook Secret (Optional)',
+                    'type' => 'password',
+                    'placeholder' => 'Enter webhook secret for signature validation',
+                    'required' => false,
+                ],
+            ],
+            'supports_webhooks' => true,
+            'supports_discovery' => true,
+            'metadata' => [
+                'rate_limit' => 100,
+                'pagination' => 'offset',
+            ],
+        ],
+
+        [
+            'key' => 'geotab',
+            'label' => 'Geotab',
+            'type' => 'native',
+            'driver_class' => \Fleetbase\FleetOps\Support\Telematics\Providers\GeotabProvider::class,
+            'icon' => 'https://www.geotab.com/favicon.ico',
+            'description' => 'Geotab provides fleet management solutions with GPS tracking, driver safety, and compliance features.',
+            'docs_url' => 'https://developers.geotab.com/',
+            'required_fields' => [
+                [
+                    'name' => 'database',
+                    'label' => 'Database Name',
+                    'type' => 'text',
+                    'placeholder' => 'Enter your Geotab database name',
+                    'required' => true,
+                ],
+                [
+                    'name' => 'username',
+                    'label' => 'Username',
+                    'type' => 'text',
+                    'placeholder' => 'Enter your Geotab username',
+                    'required' => true,
+                ],
+                [
+                    'name' => 'password',
+                    'label' => 'Password',
+                    'type' => 'password',
+                    'placeholder' => 'Enter your Geotab password',
+                    'required' => true,
+                ],
+            ],
+            'supports_webhooks' => false,
+            'supports_discovery' => true,
+            'metadata' => [
+                'rate_limit' => 50,
+                'auth_type' => 'session',
+            ],
+        ],
+
+        [
+            'key' => 'samsara',
+            'label' => 'Samsara',
+            'type' => 'native',
+            'driver_class' => \Fleetbase\FleetOps\Support\Telematics\Providers\SamsaraProvider::class,
+            'icon' => 'https://www.samsara.com/favicon.ico',
+            'description' => 'Samsara offers IoT solutions for fleet operations, including GPS tracking, dashcams, and asset monitoring.',
+            'docs_url' => 'https://developers.samsara.com/',
+            'required_fields' => [
+                [
+                    'name' => 'api_token',
+                    'label' => 'API Token',
+                    'type' => 'password',
+                    'placeholder' => 'Enter your Samsara API token',
+                    'required' => true,
+                    'validation' => 'required|string|min:20',
+                ],
+                [
+                    'name' => 'webhook_secret',
+                    'label' => 'Webhook Secret (Optional)',
+                    'type' => 'password',
+                    'placeholder' => 'Enter webhook secret for signature validation',
+                    'required' => false,
+                ],
+            ],
+            'supports_webhooks' => true,
+            'supports_discovery' => true,
+            'metadata' => [
+                'rate_limit' => 60,
+                'pagination' => 'cursor',
+            ],
+        ],
+    ]
+];
+

package/server/migrations/2025_10_27_000001_add_telematics_integration_fields.php

@@ -0,0 +1,70 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        // Update telematics table
+        Schema::table('telematics', function (Blueprint $table) {
+            $table->json('credentials')->after('config');
+            $table->string('public_id')->after('uuid')->nullable()->index();
+        });
+
+        // Update devices table
+        Schema::table('devices', function (Blueprint $table) {
+            $table->string('public_id')->after('uuid')->nullable()->index();
+            $table->foreignUuid('company_uuid')->nullable()->after('_key')->constrained('companies', 'uuid')->nullOnDelete();
+            $table->foreignUuid('photo_uuid')->nullable()->after('telematic_uuid')->constrained('files', 'uuid')->nullOnDelete();
+        });
+
+        // Update sensors table
+        Schema::table('sensors', function (Blueprint $table) {
+            $table->string('public_id')->after('uuid')->nullable()->index();
+            $table->foreignUuid('photo_uuid')->nullable()->after('company_uuid')->constrained('files', 'uuid')->nullOnDelete();
+        });
+
+        // Update device events table
+        Schema::table('device_events', function (Blueprint $table) {
+            $table->string('public_id')->after('uuid')->nullable()->index();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        // Remove columns from telematics
+        Schema::table('telematics', function (Blueprint $table) {
+            $table->dropColumn(['credentials', 'public_id']);
+        });
+
+        // Remove columns from devices
+        Schema::table('devices', function (Blueprint $table) {
+            $table->dropForeign(['company_uuid']);
+            $table->dropForeign(['photo_uuid']);
+            $table->dropColumn(['public_id', 'photo_uuid', 'company_uuid']);
+        });
+
+        // Remove columns from sensors
+        Schema::table('sensors', function (Blueprint $table) {
+            $table->dropForeign(['photo_uuid']);
+            $table->dropColumn(['public_id', 'photo_uuid']);
+        });
+
+        // Remove columns from device events
+        Schema::table('device_events', function (Blueprint $table) {
+            $table->dropColumn(['public_id']);
+        });
+    }
+};

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