@fleetbase/fleetops-engine 0.6.20 → 0.6.21

package/server/src/Models/Position.php

@@ -7,6 +7,8 @@ use Fleetbase\Models\Model;
 use Fleetbase\Traits\HasApiModelBehavior;
 use Fleetbase\Traits\HasUuid;
 use Fleetbase\Traits\TracksApiCredential;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 class Position extends Model
 {
@@ -48,7 +50,7 @@ class Position extends Model
      *
      * @var array
      */
-    protected $appends = [];
+    protected $appends = ['latitude', 'longitude'];
 
     /**
      * Get filter parameters for this model.
@@ -85,35 +87,33 @@ class Position extends Model
      */
     protected static $logName = 'position';
 
-    /**
-     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
-     */
-    public function company()
+    public function company(): BelongsTo
     {
         return $this->belongsTo(\Fleetbase\Models\Company::class);
     }
 
-    /**
-     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
-     */
-    public function order()
+    public function order(): BelongsTo
     {
         return $this->belongsTo(Order::class);
     }
 
-    /**
-     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
-     */
-    public function destination()
+    public function destination(): BelongsTo
     {
         return $this->belongsTo(Place::class);
     }
 
-    /**
-     * @return \Illuminate\Database\Eloquent\Relations\MorphTo
-     */
-    public function subject()
+    public function subject(): MorphTo
     {
         return $this->morphTo(__FUNCTION__, 'subject_type', 'subject_uuid')->withoutGlobalScopes();
     }
+
+    public function getLongitudeAttribute(): float
+    {
+        return $this->coordinates?->getLng() ?? 0;
+    }
+
+    public function getLatitudeAttribute(): float
+    {
+        return $this->coordinates?->getLat() ?? 0;
+    }
 }

package/server/src/Models/Sensor.php

@@ -3,7 +3,11 @@
 namespace Fleetbase\FleetOps\Models;
 
 use Fleetbase\Casts\Json;
+use Fleetbase\FleetOps\Casts\Point;
+use Fleetbase\LaravelMysqlSpatial\Eloquent\SpatialTrait;
+use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Fleetbase\Models\Alert;
+use Fleetbase\Models\File;
 use Fleetbase\Models\Model;
 use Fleetbase\Models\User;
 use Fleetbase\Traits\HasApiModelBehavior;
@@ -16,6 +20,8 @@ use Fleetbase\Traits\TracksApiCredential;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Str;
 use Spatie\Activitylog\LogOptions;
 use Spatie\Activitylog\Traits\LogsActivity;
 use Spatie\Sluggable\HasSlug;
@@ -39,6 +45,7 @@ class Sensor extends Model
     use HasMetaAttributes;
     use Searchable;
     use HasCustomFields;
+    use SpatialTrait;
 
     /**
      * The database table used by the model.
@@ -77,8 +84,16 @@ class Sensor extends Model
         'company_uuid',
         'device_uuid',
         'warranty_uuid',
+        'telematic_uuid',
+        'photo_uuid',
         'name',
-        'sensor_type',
+        'type',
+        'internal_id',
+        'imei',
+        'imsi',
+        'firmware_version',
+        'serial_number',
+        'last_position',
         'unit',
         'min_threshold',
         'max_threshold',
@@ -100,12 +115,9 @@ class Sensor extends Model
      * @var array
      */
     protected $appends = [
-        'device_name',
-        'warranty_name',
-        'attached_to_name',
         'is_active',
         'threshold_status',
-        'last_reading_formatted',
+        'photo_url',
     ];
 
     /**
@@ -113,7 +125,14 @@ class Sensor extends Model
      *
      * @var array
      */
-    protected $hidden = ['device', 'warranty', 'sensorable'];
+    protected $hidden = [];
+
+    /**
+     * The attributes that are spatial columns.
+     *
+     * @var array
+     */
+    protected $spatialFields = ['last_position'];
 
     /**
      * The attributes that should be cast to native types.
@@ -121,13 +140,14 @@ class Sensor extends Model
      * @var array
      */
     protected $casts = [
-        'min_threshold'        => 'float',
-        'max_threshold'        => 'float',
-        'threshold_inclusive'  => 'boolean',
-        'last_reading_at'      => 'datetime',
-        'report_frequency_sec' => 'integer',
-        'calibration'          => Json::class,
-        'meta'                 => Json::class,
+        'min_threshold'               => 'float',
+        'max_threshold'               => 'float',
+        'threshold_inclusive'         => 'boolean',
+        'last_reading_at'             => 'datetime',
+        'report_frequency_sec'        => 'integer',
+        'last_position'               => Point::class,
+        'calibration'                 => Json::class,
+        'meta'                        => Json::class,
     ];
 
     /**
@@ -169,6 +189,11 @@ class Sensor extends Model
         return LogOptions::defaults()->logAll();
     }
 
+    public function telematic(): BelongsTo
+    {
+        return $this->belongsTo(Telematic::class, 'telematic_uuid', 'uuid');
+    }
+
     public function device(): BelongsTo
     {
         return $this->belongsTo(Device::class, 'device_uuid', 'uuid');
@@ -194,12 +219,27 @@ class Sensor extends Model
         return $this->morphTo();
     }
 
+    public function photo(): BelongsTo
+    {
+        return $this->belongsTo(File::class);
+    }
+
     public function alerts(): HasMany
     {
         return $this->hasMany(Alert::class, 'subject_uuid', 'uuid')
             ->where('subject_type', static::class);
     }
 
+    /**
+     * Get photo URL attribute.
+     *
+     * @return string
+     */
+    public function getPhotoUrlAttribute()
+    {
+        return data_get($this, 'photo.url', 'https://flb-assets.s3.ap-southeast-1.amazonaws.com/static/image-file-icon.png');
+    }
+
     /**
      * Get the device name.
      */
@@ -507,4 +547,29 @@ class Sensor extends Model
             ],
         ];
     }
+
+    /**
+     * 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,
+        ]);
+    }
 }

package/server/src/Models/Telematic.php

@@ -3,6 +3,7 @@
 namespace Fleetbase\FleetOps\Models;
 
 use Fleetbase\Casts\Json;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
 use Fleetbase\Models\Model;
 use Fleetbase\Models\User;
 use Fleetbase\Traits\HasApiModelBehavior;
@@ -85,8 +86,8 @@ class Telematic extends Model
         'last_seen_at',
         'last_metrics',
         'config',
+        'credentials',
         'meta',
-        'slug',
     ];
 
     /**
@@ -94,7 +95,7 @@ class Telematic extends Model
      *
      * @var array
      */
-    protected $appends = ['warranty_name', 'is_online', 'signal_strength', 'last_location'];
+    protected $appends = ['warranty_name', 'is_online', 'signal_strength', 'last_location', 'provider_descriptor'];
 
     /**
      * The attributes excluded from the model's JSON form.
@@ -109,10 +110,97 @@ class Telematic extends Model
      * @var array
      */
     protected $casts = [
-        'last_seen_at' => 'datetime',
-        'last_metrics' => Json::class,
-        'config'       => Json::class,
-        'meta'         => Json::class,
+        'last_seen_at'      => 'datetime',
+        'last_metrics'      => Json::class,
+        'config'            => Json::class,
+        'credentials'       => Json::class,
+        'meta'              => Json::class,
+    ];
+
+    /**
+     * Telematic statuses.
+     *
+     * @var array
+     */
+    public static $statuses = [
+        [
+            'key'         => 'initialized',
+            'label'       => 'Initialized',
+            'description' => 'Provider entry has been created but not yet configured.',
+        ],
+        [
+            'key'         => 'configured',
+            'label'       => 'Configured',
+            'description' => 'Provider credentials and settings are valid but connection not yet tested.',
+        ],
+        [
+            'key'         => 'connecting',
+            'label'       => 'Connecting',
+            'description' => 'Attempting to establish a connection with provider API.',
+        ],
+        [
+            'key'         => 'connected',
+            'label'       => 'Connected',
+            'description' => 'Successfully authenticated and connected to provider API.',
+        ],
+        [
+            'key'         => 'synchronizing',
+            'label'       => 'Synchronizing',
+            'description' => 'Currently syncing data (devices, vehicles, positions, etc.) from provider.',
+        ],
+        [
+            'key'         => 'active',
+            'label'       => 'Active',
+            'description' => 'Integration is healthy and data syncs are occurring normally.',
+        ],
+        [
+            'key'         => 'degraded',
+            'label'       => 'Degraded',
+            'description' => 'Integration partially working; intermittent errors or missing data.',
+        ],
+        [
+            'key'         => 'disconnected',
+            'label'       => 'Disconnected',
+            'description' => 'Connection lost or failed authentication.',
+        ],
+        [
+            'key'         => 'error',
+            'label'       => 'Error',
+            'description' => 'Provider integration encountered a fatal issue.',
+        ],
+        [
+            'key'         => 'disabled',
+            'label'       => 'Disabled',
+            'description' => 'Manually disabled by the user.',
+        ],
+        [
+            'key'         => 'archived',
+            'label'       => 'Archived',
+            'description' => 'Deprecated or replaced integration, kept for record.',
+        ],
+    ];
+
+    /**
+     * Telematic health statuses.
+     *
+     * @var array
+     */
+    public static $healthStates = [
+        [
+            'key'         => 'healthy',
+            'label'       => 'Healthy',
+            'description' => 'Integration tested and stable.',
+        ],
+        [
+            'key'         => 'warning',
+            'label'       => 'Warning',
+            'description' => 'Minor issues detected (e.g., slow response, nearing quota).',
+        ],
+        [
+            'key'         => 'critical',
+            'label'       => 'Critical',
+            'description' => 'Persistent failure or no data received in X hours.',
+        ],
     ];
 
     /**
@@ -169,6 +257,20 @@ class Telematic extends Model
         return $this->hasMany(Asset::class, 'telematic_uuid', 'uuid');
     }
 
+    /**
+     * Get the provider config.
+     */
+    public function getProviderDescriptorAttribute(): array
+    {
+        $registry = app(TelematicProviderRegistry::class);
+        $provider = $registry->findByKey($this->provider);
+        if ($provider) {
+            return $provider->toArray();
+        }
+
+        return [];
+    }
+
     /**
      * Get the warranty name.
      */
@@ -333,4 +435,12 @@ class Telematic extends Model
 
         return true;
     }
+
+    /**
+     * Sets a default status if none input.
+     */
+    public function setStatusAttribute(?string $status = null): void
+    {
+        $this->attributes['status'] = $status ?? 'initialized';
+    }
 }

package/server/src/Models/Vehicle.php

@@ -536,10 +536,7 @@ class Vehicle extends Model
     }
 
     /**
-     * Creates a new position for the vehicle
-     *
-     * @param array $attributes
-     * @return Position|null
+     * Creates a new position for the vehicle.
      */
     public function createPosition(array $attributes = [], Model|string|null $destination = null): ?Position
     {
@@ -555,11 +552,11 @@ class Vehicle extends Model
         $destinationUuid = Str::isUuid($destination) ? $destination : data_get($destination, 'uuid');
 
         return Position::create([
-            ...Arr::only($attributes, ['coordinates', 'heading', 'bearing', 'speed', 'altitude']),
-            'subject_uuid' => $this->uuid,
-            'subject_type' => $this->getMorphClass(),
-            'company_uuid' => $this->company_uuid,
-            'destination_uuid' => $destinationUuid
+            ...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,
         ]);
     }
 
@@ -760,8 +757,8 @@ class Vehicle extends Model
      */
     public function setVinDatas(array $newVinData = []): array
     {
-        $vinData       = is_array($this->vin_data) ? $this->vin_data : (array) $this->vin_data;
-        $vinData       = array_merge($vinData, $newVinData);
+        $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 [];
+    }
+}