@fleetbase/fleetops-engine 0.6.19 → 0.6.21

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

@@ -0,0 +1,177 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Providers;
+
+/**
+ * Class SamsaraProvider.
+ *
+ * Samsara telematics provider implementation.
+ * https://www.samsara.com/
+ */
+class SamsaraProvider extends AbstractProvider
+{
+    protected string $baseUrl        = 'https://api.samsara.com';
+    protected int $requestsPerMinute = 60;
+
+    protected function prepareAuthentication(): void
+    {
+        $this->headers = [
+            'Authorization' => 'Bearer ' . $this->credentials['api_token'],
+            'Accept'        => 'application/json',
+        ];
+    }
+
+    public function testConnection(array $credentials): array
+    {
+        try {
+            $this->credentials = $credentials;
+            $this->prepareAuthentication();
+
+            // Test by fetching user info
+            $response = $this->request('GET', '/fleet/users');
+
+            return [
+                'success'  => true,
+                'message'  => 'Connection successful',
+                'metadata' => [
+                    'users_count' => count($response['data'] ?? []),
+                ],
+            ];
+        } 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 = ['limit' => $limit];
+        if ($cursor) {
+            $params['after'] = $cursor;
+        }
+
+        $response = $this->request('GET', '/fleet/vehicles', $params);
+
+        $devices    = $response['data'] ?? [];
+        $nextCursor = $response['pagination']['endCursor'] ?? null;
+        $hasMore    = $response['pagination']['hasNextPage'] ?? false;
+
+        return [
+            'devices'     => $devices,
+            'next_cursor' => $hasMore ? $nextCursor : null,
+            'has_more'    => $hasMore,
+        ];
+    }
+
+    public function fetchDeviceDetails(string $externalId): array
+    {
+        $response = $this->request('GET', "/fleet/vehicles/{$externalId}");
+
+        return $response['data'] ?? [];
+    }
+
+    public function normalizeDevice(array $payload): array
+    {
+        return [
+            'external_id'     => $payload['id'],
+            'device_name'     => $payload['name'] ?? 'Unknown Device',
+            'device_provider' => 'samsara',
+            'device_model'    => $payload['make'] ?? null,
+            'vin'             => $payload['vin'] ?? null,
+            'license_plate'   => $payload['licensePlate'] ?? null,
+            'status'          => 'active',
+            'meta'            => $payload,
+        ];
+    }
+
+    public function normalizeEvent(array $payload): array
+    {
+        return [
+            'external_id' => $payload['id'] ?? null,
+            'event_type'  => $payload['eventType'] ?? 'vehicle_update',
+            'occurred_at' => $payload['time'] ?? now(),
+            'location'    => [
+                'lat' => $payload['location']['latitude'] ?? null,
+                'lng' => $payload['location']['longitude'] ?? null,
+            ],
+            'meta' => $payload,
+        ];
+    }
+
+    public function normalizeSensor(array $payload): array
+    {
+        return [
+            'sensor_type' => $payload['sensorType'] ?? 'generic',
+            'value'       => $payload['value'] ?? null,
+            'unit'        => $payload['unit'] ?? null,
+            'recorded_at' => $payload['time'] ?? now(),
+            'meta'        => $payload,
+        ];
+    }
+
+    public function validateWebhookSignature(string $payload, string $signature, array $credentials): bool
+    {
+        if (!isset($credentials['webhook_secret'])) {
+            return true;
+        }
+
+        $expectedSignature = hash_hmac('sha256', $payload, $credentials['webhook_secret']);
+
+        return hash_equals($expectedSignature, $signature);
+    }
+
+    public function processWebhook(array $payload, array $headers = []): array
+    {
+        $devices = [];
+        $events  = [];
+
+        // Samsara webhook structure
+        if (isset($payload['data'])) {
+            foreach ($payload['data'] as $item) {
+                if (isset($item['vehicle'])) {
+                    $devices[] = $this->normalizeDevice($item['vehicle']);
+                }
+
+                $events[] = $this->normalizeEvent($item);
+            }
+        }
+
+        return [
+            'devices' => $devices,
+            'events'  => $events,
+            'sensors' => [],
+        ];
+    }
+
+    public function getCredentialSchema(): array
+    {
+        return [
+            [
+                '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,
+            ],
+        ];
+    }
+
+    public function supportsWebhooks(): bool
+    {
+        return true;
+    }
+}

package/server/src/Support/Telematics/TelematicProviderRegistry.php

@@ -0,0 +1,147 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics;
+
+use Fleetbase\FleetOps\Contracts\TelematicProviderDescriptor;
+use Fleetbase\FleetOps\Contracts\TelematicProviderInterface;
+use Illuminate\Support\Collection;
+
+/**
+ * Class ProviderRegistry.
+ *
+ * Central registry for all telematics providers.
+ * Manages provider discovery, registration, and instantiation.
+ */
+class TelematicProviderRegistry
+{
+    /**
+     * @var Collection<TelematicProviderDescriptor>
+     */
+    protected Collection $providers;
+
+    /**
+     * Create a new ProviderRegistry instance.
+     */
+    public function __construct()
+    {
+        $this->providers = collect();
+        $this->loadNativeProviders();
+    }
+
+    /**
+     * Load native providers from configuration.
+     */
+    protected function loadNativeProviders(): void
+    {
+        $config = config('telematics.providers', []);
+
+        foreach ($config as $providerConfig) {
+            $descriptor = new TelematicProviderDescriptor($providerConfig);
+            $this->register($descriptor);
+        }
+    }
+
+    /**
+     * Register a provider.
+     */
+    public function register(TelematicProviderDescriptor $descriptor): void
+    {
+        $this->providers->put($descriptor->key, $descriptor);
+    }
+
+    /**
+     * Get all registered providers.
+     *
+     * @return Collection<TelematicProviderDescriptor>
+     */
+    public function all(): Collection
+    {
+        return $this->providers;
+    }
+
+    /**
+     * Find a provider by key.
+     */
+    public function findByKey(string $key): ?TelematicProviderDescriptor
+    {
+        return $this->providers->get($key);
+    }
+
+    /**
+     * Check if a provider exists.
+     */
+    public function has(string $key): bool
+    {
+        return $this->providers->has($key);
+    }
+
+    /**
+     * Resolve a provider instance by key.
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function resolve(string $key): TelematicProviderInterface
+    {
+        $descriptor = $this->findByKey($key);
+
+        if (!$descriptor) {
+            throw new \InvalidArgumentException("Provider '{$key}' not found in registry.");
+        }
+
+        if (!$descriptor->driverClass) {
+            throw new \InvalidArgumentException("Provider '{$key}' does not have a driver class.");
+        }
+
+        if (!class_exists($descriptor->driverClass)) {
+            throw new \InvalidArgumentException("Provider driver class '{$descriptor->driverClass}' does not exist.");
+        }
+
+        $provider = app($descriptor->driverClass);
+
+        if (!$provider instanceof TelematicProviderInterface) {
+            throw new \InvalidArgumentException('Provider driver class must implement TelematicProviderInterface.');
+        }
+
+        return $provider;
+    }
+
+    /**
+     * Get providers that support webhooks.
+     *
+     * @return Collection<TelematicProviderDescriptor>
+     */
+    public function getWebhookProviders(): Collection
+    {
+        return $this->providers->filter(fn ($p) => $p->supportsWebhooks);
+    }
+
+    /**
+     * Get providers that support discovery.
+     *
+     * @return Collection<TelematicProviderDescriptor>
+     */
+    public function getDiscoveryProviders(): Collection
+    {
+        return $this->providers->filter(fn ($p) => $p->supportsDiscovery);
+    }
+
+    /**
+     * Get native providers only.
+     *
+     * @return Collection<TelematicProviderDescriptor>
+     */
+    public function getNativeProviders(): Collection
+    {
+        return $this->providers->filter(fn ($p) => $p->type === 'native');
+    }
+
+    /**
+     * Get custom providers only.
+     *
+     * @return Collection<TelematicProviderDescriptor>
+     */
+    public function getCustomProviders(): Collection
+    {
+        return $this->providers->filter(fn ($p) => $p->type === 'custom');
+    }
+}

package/server/src/Support/Telematics/TelematicService.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics;
+
+use Fleetbase\FleetOps\Jobs\SyncDevicesJob;
+use Fleetbase\FleetOps\Jobs\TestConnectionJob;
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\Telematic;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Class TelematicService.
+ *
+ * Business logic for telematics management.
+ * Handles CRUD operations, connection testing, and device discovery.
+ */
+class TelematicService
+{
+    protected TelematicProviderRegistry $registry;
+
+    public function __construct(TelematicProviderRegistry $registry)
+    {
+        $this->registry = $registry;
+    }
+
+    /**
+     * Create a new telematic integration.
+     *
+     * @throws ValidationException
+     */
+    public function create(array $data): Telematic
+    {
+        // Validate provider exists
+        $providerKey = $data['provider_key'];
+        $descriptor  = $this->registry->findByKey($providerKey);
+
+        if (!$descriptor) {
+            throw ValidationException::withMessages(['provider_key' => ['Invalid provider key.']]);
+        }
+
+        // Validate credentials against provider schema
+        $this->validateCredentials($data['credentials'] ?? [], $descriptor->requiredFields);
+
+        // Test connection if requested
+        if ($data['test_connection'] ?? false) {
+            $provider = $this->registry->resolve($providerKey);
+            $result   = $provider->testConnection($data['credentials']);
+
+            if (!$result['success']) {
+                throw ValidationException::withMessages(['credentials' => [$result['message']]]);
+            }
+        }
+
+        // Create telematic record
+        $telematic               = new Telematic();
+        $telematic->company_uuid = session('company');
+        $telematic->name         = $data['name'];
+        $telematic->provider     = $providerKey;
+        $telematic->credentials  = Crypt::encryptString(json_encode($data['credentials']));
+        $telematic->status       = 'active';
+        $telematic->meta         = $data['meta'] ?? [];
+        $telematic->save();
+
+        return $telematic;
+    }
+
+    /**
+     * Update a telematic integration.
+     */
+    public function update(Telematic $telematic, array $data): Telematic
+    {
+        if (isset($data['name'])) {
+            $telematic->name = $data['name'];
+        }
+
+        if (isset($data['credentials'])) {
+            $descriptor = $this->registry->findByKey($telematic->provider);
+            $this->validateCredentials($data['credentials'], $descriptor->requiredFields);
+            $telematic->credentials = Crypt::encryptString(json_encode($data['credentials']));
+        }
+
+        if (isset($data['status'])) {
+            $telematic->status = $data['status'];
+        }
+
+        if (isset($data['meta'])) {
+            $telematic->meta = array_merge($telematic->meta ?? [], $data['meta']);
+        }
+
+        $telematic->save();
+
+        return $telematic;
+    }
+
+    /**
+     * Delete a telematic integration.
+     */
+    public function delete(Telematic $telematic): bool
+    {
+        return $telematic->delete();
+    }
+
+    /**
+     * Test connection to a provider.
+     *
+     * @return array|string
+     */
+    public function testConnection(Telematic $telematic, bool $async = false)
+    {
+        if ($async) {
+            $job = new TestConnectionJob($telematic);
+            dispatch($job);
+
+            return ['job_id' => $job->getJobId(), 'message' => 'Connection test queued'];
+        }
+
+        $provider = $this->registry->resolve($telematic->provider);
+        $provider->connect($telematic);
+
+        $credentials = json_decode(Crypt::decryptString($telematic->credentials), true);
+
+        return $provider->testConnection($credentials);
+    }
+
+    /**
+     * Discover devices from a provider.
+     *
+     * @return string Job ID
+     */
+    public function discoverDevices(Telematic $telematic, array $options = []): string
+    {
+        $job = new SyncDevicesJob($telematic, $options);
+        dispatch($job);
+
+        return $job->getJobId();
+    }
+
+    /**
+     * Link a device to a telematic.
+     */
+    public function linkDevice(Telematic $telematic, array $deviceData): Device
+    {
+        $device = Device::firstOrNew([
+            'telematic_uuid' => $telematic->uuid,
+            'external_id'    => $deviceData['external_id'],
+        ]);
+
+        $device->device_name     = $deviceData['device_name'] ?? 'Unknown Device';
+        $device->device_model    = $deviceData['device_model'] ?? null;
+        $device->device_provider = $telematic->provider;
+        $device->status          = $deviceData['status'] ?? 'active';
+        $device->meta            = array_merge($device->meta ?? [], $deviceData['meta'] ?? []);
+
+        $device->save();
+
+        return $device;
+    }
+
+    /**
+     * Get devices for a telematic.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
+    public function getDevices(Telematic $telematic, array $filters = [])
+    {
+        $query = Device::where('telematic_uuid', $telematic->uuid);
+
+        if (isset($filters['status'])) {
+            $query->where('status', $filters['status']);
+        }
+
+        if (isset($filters['search'])) {
+            $query->where(function ($q) use ($filters) {
+                $q->where('device_name', 'like', "%{$filters['search']}%")
+                  ->orWhere('external_id', 'like', "%{$filters['search']}%");
+            });
+        }
+
+        return $query->get();
+    }
+
+    /**
+     * Validate credentials against provider schema.
+     *
+     * @throws ValidationException
+     */
+    protected function validateCredentials(array $credentials, array $schema): void
+    {
+        $rules = [];
+
+        foreach ($schema as $field) {
+            $fieldRules = [];
+
+            if ($field['required'] ?? true) {
+                $fieldRules[] = 'required';
+            }
+
+            if (isset($field['validation'])) {
+                $fieldRules[] = $field['validation'];
+            } else {
+                $fieldRules[] = 'string';
+            }
+
+            $rules[$field['name']] = implode('|', $fieldRules);
+        }
+
+        $validator = Validator::make($credentials, $rules);
+
+        if ($validator->fails()) {
+            throw new ValidationException($validator);
+        }
+    }
+
+    /**
+     * Get decrypted credentials for a telematic.
+     */
+    public function getCredentials(Telematic $telematic): array
+    {
+        return json_decode(Crypt::decryptString($telematic->credentials), true);
+    }
+}

package/server/src/Support/Utils.php

@@ -908,7 +908,7 @@ class Utils extends FleetbaseUtils
 
     /**
      * Calculates the great-circle distance between two points, with
-     * the Vincenty formula. (Using over haversine tdue to antipodal point issues).
+     * the Vincenty formula. (Using over haversine due to antipodal point issues).
      *
      * https://en.wikipedia.org/wiki/Great-circle_distance#Formulas
      * https://en.wikipedia.org/wiki/Antipodal_point

package/server/src/routes.php

@@ -345,6 +345,10 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes('proofs');
                         $router->fleetbaseRoutes('purchase-rates');
                         $router->fleetbaseRoutes('routes');
+                        $router->fleetbaseRoutes('positions', function ($router, $controller) {
+                            $router->post('replay', $controller('replay'));
+                            $router->post('metrics', $controller('metrics'));
+                        });
                         $router->fleetbaseRoutes(
                             'service-areas',
                             function ($router, $controller) {
@@ -399,7 +403,14 @@ Route::prefix(config('fleetops.api.routing.prefix', null))->namespace('Fleetbase
                         $router->fleetbaseRoutes('devices');
                         $router->fleetbaseRoutes('device-events');
                         $router->fleetbaseRoutes('sensors');
-                        $router->fleetbaseRoutes('telematics');
+                        $router->fleetbaseRoutes('telematics', function ($router, $controller) {
+                            $router->get('providers', $controller('providers'));
+                            $router->get('devices', $controller('devices'));
+                            $router->post('link-device', $controller('linkDevice'));
+                            $router->post('discover', $controller('discover'));
+                            $router->post('{id}/test-connection', $controller('testConnection'));
+                            $router->post('{key}/test-credentials', $controller('testCredentials'));
+                        });
                         $router->fleetbaseRoutes('work-orders');
                         $router->fleetbaseRoutes('maintenance');
                         $router->fleetbaseRoutes('equipment');