@fleetbase/fleetops-engine 0.6.19 → 0.6.21

package/server/src/Models/Vehicle.php

@@ -8,6 +8,7 @@ use Fleetbase\FleetOps\Casts\Point;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\FleetOps\Support\VehicleData;
 use Fleetbase\LaravelMysqlSpatial\Eloquent\SpatialTrait;
+use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Fleetbase\Models\Category;
 use Fleetbase\Models\File;
 use Fleetbase\Models\Model;
@@ -23,6 +24,7 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\HasManyThrough;
 use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Database\Eloquent\Relations\MorphMany;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
 use Spatie\Activitylog\LogOptions;
 use Spatie\Activitylog\Traits\LogsActivity;
@@ -61,7 +63,7 @@ class Vehicle extends Model
      *
      * @var array
      */
-    protected $searchableColumns = ['make', 'model', 'year', 'plate_number', 'vin', 'public_id'];
+    protected $searchableColumns = ['name', 'description', 'make', 'model', 'trim', 'model_type', 'body_type', 'body_sub_type', 'year', 'plate_number', 'vin', 'call_sign', 'public_id'];
 
     /**
      * Attributes that is filterable on this model.
@@ -533,6 +535,31 @@ class Vehicle extends Model
         return ($isFirstPosition || $isPast50Meters) ? Position::create($positionData) : null;
     }
 
+    /**
+     * Creates a new position for the vehicle.
+     */
+    public function createPosition(array $attributes = [], Model|string|null $destination = null): ?Position
+    {
+        if (!isset($attributes['coordinates']) && isset($attributes['location'])) {
+            $attributes['coordinates'] = $attributes['location'];
+        }
+
+        if (!isset($attributes['coordinates']) && isset($attributes['latitude']) && isset($attributes['longitude'])) {
+            $attributes['coordinates'] = new SpatialPoint($attributes['latitude'], $attributes['longitude']);
+        }
+
+        // handle destination if set
+        $destinationUuid = Str::isUuid($destination) ? $destination : data_get($destination, 'uuid');
+
+        return Position::create([
+            ...Arr::only($attributes, ['coordinates', 'heading', 'bearing', 'speed', 'altitude', 'order_uuid']),
+            'subject_uuid'     => $this->uuid,
+            'subject_type'     => $this->getMorphClass(),
+            'company_uuid'     => $this->company_uuid,
+            'destination_uuid' => $destinationUuid,
+        ]);
+    }
+
     public static function createFromImport(array $row, bool $saveInstance = false): Vehicle
     {
         // Filter array for null key values
@@ -660,4 +687,80 @@ class Vehicle extends Model
 
         return $details;
     }
+
+    /**
+     * Set or update a single key/value pair in the `specs` JSON column.
+     *
+     * Uses Laravel's `data_set` helper to allow dot notation for nested keys.
+     *
+     * @param string|array $key   the key (or array path) to set within the specs
+     * @param mixed        $value the value to assign to the given key
+     *
+     * @return array the updated specs array
+     */
+    public function setSpec(string|array $key, mixed $value): array
+    {
+        $specs = is_array($this->specs) ? $this->specs : (array) $this->specs;
+        data_set($specs, $key, $value);
+        $this->specs = $specs;
+
+        return $specs;
+    }
+
+    /**
+     * Merge multiple values into the `specs` JSON column.
+     *
+     * By default this performs a shallow merge (overwrites duplicate keys).
+     * Use `array_replace_recursive` if you need nested merges.
+     *
+     * @param array $newSpecs key/value pairs to merge into specs
+     *
+     * @return array the updated specs array
+     */
+    public function setSpecs(array $newSpecs = []): array
+    {
+        $specs       = is_array($this->specs) ? $this->specs : (array) $this->specs;
+        $specs       = array_merge($specs, $newSpecs);
+        $this->specs = $specs;
+
+        return $specs;
+    }
+
+    /**
+     * Set or update a single key/value pair in the `vin_data` JSON column.
+     *
+     * Uses Laravel's `data_set` helper to allow dot notation for nested keys.
+     *
+     * @param string|array $key   the key (or array path) to set within the VIN data
+     * @param mixed        $value the value to assign to the given key
+     *
+     * @return array the updated vin_data array
+     */
+    public function setVinData(string|array $key, mixed $value): array
+    {
+        $vinData = is_array($this->vin_data) ? $this->vin_data : (array) $this->vin_data;
+        data_set($vinData, $key, $value);
+        $this->vin_data = $vinData;
+
+        return $vinData;
+    }
+
+    /**
+     * Merge multiple values into the `vin_data` JSON column.
+     *
+     * By default this performs a shallow merge (overwrites duplicate keys).
+     * Use `array_replace_recursive` if you need nested merges.
+     *
+     * @param array $newVinData key/value pairs to merge into vin_data
+     *
+     * @return array the updated vin_data array
+     */
+    public function setVinDatas(array $newVinData = []): array
+    {
+        $vinData        = is_array($this->vin_data) ? $this->vin_data : (array) $this->vin_data;
+        $vinData        = array_merge($vinData, $newVinData);
+        $this->vin_data = $vinData;
+
+        return $vinData;
+    }
 }

package/server/src/Providers/FleetOpsServiceProvider.php

@@ -59,6 +59,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         \Fleetbase\FleetOps\Console\Commands\DebugOrderTracker::class,
         \Fleetbase\FleetOps\Console\Commands\PurgeUnpurchasedServiceQuotes::class,
         \Fleetbase\FleetOps\Console\Commands\SendDriverNotification::class,
+        \Fleetbase\FleetOps\Console\Commands\ReplayVehicleLocations::class,
     ];
 
     /**
@@ -103,6 +104,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         $this->loadMigrationsFrom(__DIR__ . '/../../migrations');
         $this->loadViewsFrom(__DIR__ . '/../../resources/views', 'fleetops');
         $this->mergeConfigFrom(__DIR__ . '/../../config/fleetops.php', 'fleetops');
+        $this->mergeConfigFrom(__DIR__ . '/../../config/telematics.php', 'telematics');
         $this->mergeConfigFrom(__DIR__ . '/../../config/api.php', 'api');
         $this->mergeConfigFrom(__DIR__ . '/../../config/cache.stores.php', 'cache.stores');
         $this->mergeConfigFrom(__DIR__ . '/../../config/geocoder.php', 'geocoder');

package/server/src/Support/Telematics/Providers/AbstractProvider.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Providers;
+
+use Fleetbase\FleetOps\Contracts\TelematicProviderInterface;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Fleetbase\FleetOps\Models\Telematic;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+/**
+ * Class AbstractProvider.
+ *
+ * Base implementation for all telematics providers.
+ * Provides common functionality for HTTP requests, rate limiting,
+ * and credential management.
+ */
+abstract class AbstractProvider implements TelematicProviderInterface
+{
+    protected Telematic $telematic;
+    protected array $credentials     = [];
+    protected array $headers         = [];
+    protected string $baseUrl        = '';
+    protected int $requestsPerMinute = 60;
+    protected int $burstSize         = 10;
+
+    /**
+     * Connect to the provider.
+     */
+    public function connect(Telematic $telematic): void
+    {
+        $this->telematic   = $telematic;
+        $this->credentials = json_decode(Crypt::decryptString($telematic->credentials), true);
+        $this->prepareAuthentication();
+    }
+
+    /**
+     * Prepare authentication headers/tokens.
+     * Override this in provider implementations.
+     */
+    abstract protected function prepareAuthentication(): void;
+
+    /**
+     * Make an HTTP request to the provider API.
+     *
+     * @throws TelematicRateLimitExceededException
+     */
+    protected function request(string $method, string $endpoint, array $data = []): array
+    {
+        $this->checkRateLimit();
+
+        $url           = $this->baseUrl . $endpoint;
+        $correlationId = Str::uuid()->toString();
+
+        Log::info('Provider API request', [
+            'correlation_id' => $correlationId,
+            'provider'       => class_basename($this),
+            'method'         => $method,
+            'url'            => $url,
+        ]);
+
+        $response = Http::withHeaders($this->headers)
+            ->timeout(30)
+            ->{strtolower($method)}($url, $data);
+
+        $this->recordRequest();
+
+        if ($response->failed()) {
+            Log::error('Provider API request failed', [
+                'correlation_id' => $correlationId,
+                'status'         => $response->status(),
+                'body'           => $response->body(),
+            ]);
+
+            throw new \Exception('API request failed: ' . $response->body());
+        }
+
+        return $response->json();
+    }
+
+    /**
+     * Check rate limit using token bucket algorithm.
+     *
+     * @throws TelematicRateLimitExceededException
+     */
+    protected function checkRateLimit(): void
+    {
+        $key    = 'rate_limit:' . class_basename($this) . ':' . $this->telematic->uuid;
+        $tokens = Cache::get($key, $this->burstSize);
+
+        if ($tokens <= 0) {
+            throw new TelematicRateLimitExceededException('Rate limit exceeded for provider');
+        }
+
+        Cache::put($key, $tokens - 1, 60);
+    }
+
+    /**
+     * Record a request for metrics.
+     */
+    protected function recordRequest(): void
+    {
+        $key    = 'rate_limit:' . class_basename($this) . ':' . $this->telematic->uuid;
+        $tokens = Cache::get($key, 0);
+
+        // Refill tokens gradually
+        if ($tokens < $this->burstSize) {
+            Cache::put($key, min($tokens + 1, $this->burstSize), 60);
+        }
+    }
+
+    public function supportsWebhooks(): bool
+    {
+        return false;
+    }
+
+    public function supportsDiscovery(): bool
+    {
+        return true;
+    }
+
+    public function getRateLimits(): array
+    {
+        return [
+            'requests_per_minute' => $this->requestsPerMinute,
+            'burst_size'          => $this->burstSize,
+        ];
+    }
+
+    public function validateWebhookSignature(string $payload, string $signature, array $credentials): bool
+    {
+        return false;
+    }
+
+    public function processWebhook(array $payload, array $headers = []): array
+    {
+        return [
+            'devices' => [],
+            'events'  => [],
+            'sensors' => [],
+        ];
+    }
+
+    public function getCredentialSchema(): array
+    {
+        return [];
+    }
+}

package/server/src/Support/Telematics/Providers/FlespiProvider.php

@@ -0,0 +1,182 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Providers;
+
+/**
+ * Class FlespiProvider.
+ *
+ * Flespi telematics provider implementation.
+ * https://flespi.com/
+ */
+class FlespiProvider extends AbstractProvider
+{
+    protected string $baseUrl        = 'https://flespi.io/gw';
+    protected int $requestsPerMinute = 100;
+
+    protected function prepareAuthentication(): void
+    {
+        $this->headers = [
+            'Authorization' => 'FlespiToken ' . $this->credentials['token'],
+            'Accept'        => 'application/json',
+        ];
+    }
+
+    public function testConnection(array $credentials): array
+    {
+        try {
+            $this->credentials = $credentials;
+            $this->prepareAuthentication();
+
+            // Test by fetching channels
+            $response = $this->request('GET', '/channels/all');
+
+            return [
+                'success'  => true,
+                'message'  => 'Connection successful',
+                'metadata' => [
+                    'channels_count' => count($response['result'] ?? []),
+                ],
+            ];
+        } catch (\Exception $e) {
+            return [
+                'success'  => false,
+                'message'  => $e->getMessage(),
+                'metadata' => [],
+            ];
+        }
+    }
+
+    public function fetchDevices(array $options = []): array
+    {
+        $limit  = $options['limit'] ?? 100;
+        $cursor = $options['cursor'] ?? null;
+
+        $params = ['count' => $limit];
+        if ($cursor) {
+            $params['offset'] = $cursor;
+        }
+
+        $response = $this->request('GET', '/devices/all', $params);
+
+        $devices    = $response['result'] ?? [];
+        $nextCursor = count($devices) >= $limit ? ((int) ($cursor ?? 0) + $limit) : null;
+
+        return [
+            'devices'     => $devices,
+            'next_cursor' => $nextCursor,
+            'has_more'    => $nextCursor !== null,
+        ];
+    }
+
+    public function fetchDeviceDetails(string $externalId): array
+    {
+        $response = $this->request('GET', "/devices/{$externalId}");
+
+        return $response['result'][0] ?? [];
+    }
+
+    public function normalizeDevice(array $payload): array
+    {
+        return [
+            'external_id'     => $payload['id'],
+            'device_name'     => $payload['name'] ?? 'Unknown Device',
+            'device_provider' => 'flespi',
+            'device_model'    => $payload['device_type_id'] ?? null,
+            'imei'            => $payload['configuration']['ident'] ?? null,
+            'phone'           => $payload['configuration']['phone'] ?? null,
+            'status'          => isset($payload['telemetry']) ? 'active' : 'inactive',
+            'location'        => [
+                'lat' => $payload['telemetry']['position.latitude'] ?? null,
+                'lng' => $payload['telemetry']['position.longitude'] ?? null,
+            ],
+            'meta' => $payload,
+        ];
+    }
+
+    public function normalizeEvent(array $payload): array
+    {
+        return [
+            'external_id' => $payload['id'] ?? null,
+            'event_type'  => $payload['event.enum'] ?? 'telemetry_update',
+            'occurred_at' => isset($payload['timestamp']) ? date('Y-m-d H:i:s', $payload['timestamp']) : now(),
+            'location'    => [
+                'lat' => $payload['position.latitude'] ?? null,
+                'lng' => $payload['position.longitude'] ?? null,
+            ],
+            'meta' => $payload,
+        ];
+    }
+
+    public function normalizeSensor(array $payload): array
+    {
+        return [
+            'sensor_type' => $payload['sensor_type'] ?? 'generic',
+            'value'       => $payload['value'] ?? null,
+            'unit'        => $payload['unit'] ?? null,
+            'recorded_at' => isset($payload['timestamp']) ? date('Y-m-d H:i:s', $payload['timestamp']) : now(),
+            'meta'        => $payload,
+        ];
+    }
+
+    public function validateWebhookSignature(string $payload, string $signature, array $credentials): bool
+    {
+        if (!isset($credentials['webhook_secret'])) {
+            return true; // No secret configured, skip validation
+        }
+
+        $expectedSignature = hash_hmac('sha256', $payload, $credentials['webhook_secret']);
+
+        return hash_equals($expectedSignature, $signature);
+    }
+
+    public function processWebhook(array $payload, array $headers = []): array
+    {
+        $devices = [];
+        $events  = [];
+
+        // Flespi sends array of messages
+        foreach ($payload as $message) {
+            if (isset($message['device.id'])) {
+                $devices[] = $this->normalizeDevice([
+                    'id'        => $message['device.id'],
+                    'name'      => $message['device.name'] ?? null,
+                    'telemetry' => $message,
+                ]);
+
+                $events[] = $this->normalizeEvent($message);
+            }
+        }
+
+        return [
+            'devices' => $devices,
+            'events'  => $events,
+            'sensors' => [],
+        ];
+    }
+
+    public function getCredentialSchema(): array
+    {
+        return [
+            [
+                '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,
+            ],
+        ];
+    }
+
+    public function supportsWebhooks(): bool
+    {
+        return true;
+    }
+}

package/server/src/Support/Telematics/Providers/GeotabProvider.php

@@ -0,0 +1,181 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Providers;
+
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Class GeotabProvider.
+ *
+ * Geotab telematics provider implementation.
+ * https://www.geotab.com/
+ */
+class GeotabProvider extends AbstractProvider
+{
+    protected string $baseUrl        = 'https://my.geotab.com/apiv1';
+    protected int $requestsPerMinute = 50;
+    protected ?string $sessionId     = null;
+
+    protected function prepareAuthentication(): void
+    {
+        // Geotab uses session-based authentication
+        if (!$this->sessionId) {
+            $this->authenticate();
+        }
+
+        $this->headers = [
+            'Content-Type' => 'application/json',
+        ];
+    }
+
+    /**
+     * Authenticate with Geotab and get session ID.
+     */
+    protected function authenticate(): void
+    {
+        $response = Http::post($this->baseUrl, [
+            'method' => 'Authenticate',
+            'params' => [
+                'database' => $this->credentials['database'],
+                'userName' => $this->credentials['username'],
+                'password' => $this->credentials['password'],
+            ],
+        ])->json();
+
+        if (isset($response['result']['credentials']['sessionId'])) {
+            $this->sessionId = $response['result']['credentials']['sessionId'];
+        } else {
+            throw new \Exception('Geotab authentication failed');
+        }
+    }
+
+    public function testConnection(array $credentials): array
+    {
+        try {
+            $this->credentials = $credentials;
+            $this->authenticate();
+
+            return [
+                'success'  => true,
+                'message'  => 'Connection successful',
+                'metadata' => [
+                    'session_id' => substr($this->sessionId, 0, 10) . '...',
+                ],
+            ];
+        } catch (\Exception $e) {
+            return [
+                'success'  => false,
+                'message'  => $e->getMessage(),
+                'metadata' => [],
+            ];
+        }
+    }
+
+    public function fetchDevices(array $options = []): array
+    {
+        $limit = $options['limit'] ?? 100;
+
+        $response = Http::post($this->baseUrl, [
+            'method' => 'Get',
+            'params' => [
+                'credentials' => [
+                    'database'  => $this->credentials['database'],
+                    'sessionId' => $this->sessionId,
+                ],
+                'typeName'     => 'Device',
+                'resultsLimit' => $limit,
+            ],
+        ])->json();
+
+        $devices = $response['result'] ?? [];
+
+        return [
+            'devices'     => $devices,
+            'next_cursor' => null,
+            'has_more'    => false,
+        ];
+    }
+
+    public function fetchDeviceDetails(string $externalId): array
+    {
+        $response = Http::post($this->baseUrl, [
+            'method' => 'Get',
+            'params' => [
+                'credentials' => [
+                    'database'  => $this->credentials['database'],
+                    'sessionId' => $this->sessionId,
+                ],
+                'typeName' => 'Device',
+                'search'   => ['id' => $externalId],
+            ],
+        ])->json();
+
+        return $response['result'][0] ?? [];
+    }
+
+    public function normalizeDevice(array $payload): array
+    {
+        return [
+            'external_id'     => $payload['id'],
+            'device_name'     => $payload['name'] ?? 'Unknown Device',
+            'device_provider' => 'geotab',
+            'device_model'    => $payload['deviceType'] ?? null,
+            'imei'            => $payload['serialNumber'] ?? null,
+            'vin'             => $payload['vehicleIdentificationNumber'] ?? null,
+            'status'          => 'active',
+            'meta'            => $payload,
+        ];
+    }
+
+    public function normalizeEvent(array $payload): array
+    {
+        return [
+            'external_id' => $payload['id'] ?? null,
+            'event_type'  => $payload['type'] ?? 'status_data',
+            'occurred_at' => $payload['dateTime'] ?? now(),
+            'meta'        => $payload,
+        ];
+    }
+
+    public function normalizeSensor(array $payload): array
+    {
+        return [
+            'sensor_type' => $payload['diagnosticType'] ?? 'generic',
+            'value'       => $payload['data'] ?? null,
+            'recorded_at' => $payload['dateTime'] ?? now(),
+            'meta'        => $payload,
+        ];
+    }
+
+    public function getCredentialSchema(): array
+    {
+        return [
+            [
+                '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,
+            ],
+        ];
+    }
+
+    public function supportsWebhooks(): bool
+    {
+        return false;
+    }
+}