@fleetbase/fleetops-engine 0.6.58 → 0.6.59

package/server/tests/TelematicProviderRegistryTest.php

@@ -0,0 +1,167 @@
+<?php
+
+use Fleetbase\FleetOps\Contracts\TelematicProviderDescriptor;
+use Fleetbase\FleetOps\Contracts\TelematicProviderInterface;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\Providers\AbstractProvider;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+
+class TestTelematicProviderForRegistry extends AbstractProvider
+{
+    public function exposedCredentials(): array
+    {
+        return $this->credentials;
+    }
+
+    public function exposedRateLimitKey(): string
+    {
+        return $this->rateLimitKey();
+    }
+
+    protected function prepareAuthentication(): void
+    {
+        $this->headers['Authorization'] = 'Bearer ' . ($this->credentials['token'] ?? 'missing');
+    }
+
+    public function testConnection(array $credentials): array
+    {
+        return ['success' => true, 'message' => 'ok', 'metadata' => $credentials];
+    }
+
+    public function fetchDevices(array $options = []): array
+    {
+        return ['devices' => [], 'next_cursor' => null, 'has_more' => false];
+    }
+
+    public function fetchDeviceDetails(string $externalId): array
+    {
+        return ['external_id' => $externalId];
+    }
+
+    public function normalizeDevice(array $payload): array
+    {
+        return $payload;
+    }
+
+    public function normalizeEvent(array $payload): array
+    {
+        return $payload;
+    }
+
+    public function normalizeSensor(array $payload): array
+    {
+        return $payload;
+    }
+}
+
+test('telematic provider registry stores filters and resolves provider drivers', function () {
+    $registry = new TelematicProviderRegistry();
+
+    $native = new TelematicProviderDescriptor([
+        'key'                => 'native_provider',
+        'label'              => 'Native Provider',
+        'driver_class'       => TestTelematicProviderForRegistry::class,
+        'supports_webhooks'  => true,
+        'supports_discovery' => true,
+    ]);
+    $custom = new TelematicProviderDescriptor([
+        'key'                => 'custom_provider',
+        'label'              => 'Custom Provider',
+        'type'               => 'custom',
+        'driver_class'       => TestTelematicProviderForRegistry::class,
+        'supports_webhooks'  => false,
+        'supports_discovery' => false,
+    ]);
+
+    $registry->register($native);
+    $registry->register($custom);
+
+    expect($registry->has('native_provider'))->toBeTrue()
+        ->and($registry->findByKey('native_provider'))->toBe($native)
+        ->and($registry->all()->only(['native_provider', 'custom_provider'])->all())->toBe([
+            'native_provider' => $native,
+            'custom_provider' => $custom,
+        ])
+        ->and($registry->getWebhookProviders()->keys()->all())->toContain('native_provider')
+        ->and($registry->getDiscoveryProviders()->keys()->all())->toContain('native_provider')
+        ->and($registry->getNativeProviders()->keys()->all())->toContain('native_provider')
+        ->and($registry->getCustomProviders()->keys()->all())->toContain('custom_provider')
+        ->and($registry->resolve('native_provider'))->toBeInstanceOf(TestTelematicProviderForRegistry::class);
+});
+
+test('telematic provider registry reports invalid resolve states clearly', function () {
+    $registry = new TelematicProviderRegistry();
+    $registry->register(new TelematicProviderDescriptor([
+        'key'   => 'missing_driver',
+        'label' => 'Missing Driver',
+    ]));
+    $registry->register(new TelematicProviderDescriptor([
+        'key'          => 'unknown_class',
+        'label'        => 'Unknown Class',
+        'driver_class' => 'Fleetbase\\FleetOps\\Tests\\MissingTelematicProvider',
+    ]));
+    $registry->register(new TelematicProviderDescriptor([
+        'key'          => 'wrong_contract',
+        'label'        => 'Wrong Contract',
+        'driver_class' => stdClass::class,
+    ]));
+
+    expect(fn () => $registry->resolve('not_registered'))
+        ->toThrow(InvalidArgumentException::class, "Provider 'not_registered' not found in registry.")
+        ->and(fn () => $registry->resolve('missing_driver'))
+        ->toThrow(InvalidArgumentException::class, "Provider 'missing_driver' does not have a driver class.")
+        ->and(fn () => $registry->resolve('unknown_class'))
+        ->toThrow(InvalidArgumentException::class, "Provider driver class 'Fleetbase\\FleetOps\\Tests\\MissingTelematicProvider' does not exist.")
+        ->and(fn () => $registry->resolve('wrong_contract'))
+        ->toThrow(InvalidArgumentException::class, 'Provider driver class must implement TelematicProviderInterface.');
+});
+
+test('abstract telematic provider resolves array and json credentials', function () {
+    $arrayTelematic = new Telematic();
+    $arrayTelematic->setRawAttributes([
+        'uuid'        => 'telematic-array',
+        'credentials' => ['token' => 'array-token'],
+    ], true);
+
+    $jsonTelematic = new Telematic();
+    $jsonTelematic->setRawAttributes([
+        'uuid'        => 'telematic-json',
+        'credentials' => json_encode(['token' => 'json-token']),
+    ], true);
+
+    $emptyTelematic = new Telematic();
+    $emptyTelematic->setRawAttributes([
+        'uuid'        => 'telematic-empty',
+        'credentials' => null,
+    ], true);
+
+    $provider = new TestTelematicProviderForRegistry();
+    $provider->connect($arrayTelematic);
+    expect($provider->exposedCredentials())->toBe(['token' => 'array-token'])
+        ->and($provider->exposedRateLimitKey())->toBe('rate_limit:TestTelematicProviderForRegistry:telematic-array');
+
+    $provider->connect($jsonTelematic);
+    expect($provider->exposedCredentials())->toBe(['token' => 'json-token']);
+
+    $provider->connect($emptyTelematic);
+    expect($provider->exposedCredentials())->toBe([]);
+});
+
+test('abstract telematic provider exposes conservative default capabilities', function () {
+    $provider = new TestTelematicProviderForRegistry();
+
+    expect($provider)->toBeInstanceOf(TelematicProviderInterface::class)
+        ->and($provider->supportsWebhooks())->toBeFalse()
+        ->and($provider->supportsDiscovery())->toBeTrue()
+        ->and($provider->getRateLimits())->toBe([
+            'requests_per_minute' => 60,
+            'burst_size'          => 10,
+        ])
+        ->and($provider->validateWebhookSignature('payload', 'signature', []))->toBeFalse()
+        ->and($provider->processWebhook(['event' => 'test']))->toBe([
+            'devices' => [],
+            'events'  => [],
+            'sensors' => [],
+        ])
+        ->and($provider->getCredentialSchema())->toBe([]);
+});

package/server/tests/TelematicServiceHelperContractsTest.php

@@ -0,0 +1,315 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\DeviceEvent;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+use Fleetbase\FleetOps\Support\Telematics\TelematicService;
+use Illuminate\Support\Carbon;
+
+class FleetOpsTelematicServiceDeviceFake extends Device
+{
+    public int $saveCount          = 0;
+    public array $loadMissingCalls = [];
+
+    public function __construct(array $attributes = [])
+    {
+        $this->attributes = $attributes;
+    }
+
+    public function getAttribute($key)
+    {
+        return $this->attributes[$key] ?? null;
+    }
+
+    public function setAttribute($key, $value)
+    {
+        $this->attributes[$key] = $value;
+
+        return $this;
+    }
+
+    public function save(array $options = [])
+    {
+        $this->saveCount++;
+        $this->exists = true;
+
+        return true;
+    }
+
+    public function loadMissing($relations)
+    {
+        $this->loadMissingCalls[] = $relations;
+
+        return $this;
+    }
+}
+
+class FleetOpsTelematicServiceEventFake extends DeviceEvent
+{
+    public array $positions = [];
+
+    public function __construct(array $attributes = [])
+    {
+        $this->attributes = $attributes;
+    }
+
+    public function createPosition(array $positionData = []): ?Position
+    {
+        $this->positions[] = $positionData;
+
+        return null;
+    }
+}
+
+function fleetOpsTelematicServiceInvoke(TelematicService $service, string $method, array $arguments = []): mixed
+{
+    $reflection = new ReflectionMethod($service, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invokeArgs($service, $arguments);
+}
+
+function fleetOpsTelematicService(): TelematicService
+{
+    return new TelematicService(new TelematicProviderRegistry());
+}
+
+test('telematic service normalizes identity account location sensor and event helper values', function () {
+    $service   = fleetOpsTelematicService();
+    $telematic = new Telematic();
+    $telematic->setRawAttributes([
+        'uuid'      => 'telematic-uuid',
+        'public_id' => 'telematic_public',
+        'provider'  => 'flespi',
+    ], true);
+
+    $device = new Device();
+    $device->setRawAttributes([
+        'uuid'      => 'device-uuid',
+        'device_id' => 'device-1',
+    ], true);
+
+    expect(fleetOpsTelematicServiceInvoke($service, 'resolveExternalId', [['device_id' => 'device-1']]))->toBe('device-1')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveExternalId', [['external_id' => 'external-1']]))->toBe('external-1')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveExternalId', [['device_id' => '']]))->toBeNull()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveProviderAccountId', [[], ['x-provider-account' => ['acct-header']]]))->toBe('acct-header')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveProviderAccountId', [['organization' => ['id' => 'org-1']], []]))->toBe('org-1')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'normalizeLocation', [['lat' => '1.25', 'lng' => '103.75']]))->toBe([
+            'latitude'  => 1.25,
+            'longitude' => 103.75,
+        ])
+        ->and(fleetOpsTelematicServiceInvoke($service, 'normalizeLocation', [['latitude' => '2.5', 'longitude' => '104.5']]))->toBe([
+            'latitude'  => 2.5,
+            'longitude' => 104.5,
+        ])
+        ->and(fleetOpsTelematicServiceInvoke($service, 'normalizeLocation', [['lat' => '1.25']]))->toBeNull()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'defaultLocation'))->toBe(['latitude' => 0, 'longitude' => 0])
+        ->and(fleetOpsTelematicServiceInvoke($service, 'makePositionData', [
+            ['latitude' => 1.25, 'longitude' => 103.75],
+            ['heading' => 90, 'speed' => 35, 'altitude' => 12],
+        ]))->toBe([
+            'latitude'  => 1.25,
+            'longitude' => 103.75,
+            'heading'   => 90,
+            'bearing'   => 90,
+            'speed'     => 35,
+            'altitude'  => 12,
+        ]);
+
+    $eventKey = fleetOpsTelematicServiceInvoke($service, 'makeEventKey', [$telematic, [
+        'device_id'   => 'device-1',
+        'event_id'    => 'event-1',
+        'event_type'  => 'ignition',
+        'occurred_at' => '2026-07-23 10:00:00',
+    ], $device]);
+
+    expect($eventKey)->toBe(sha1('flespi|telematic_public|device-1|event-1|ignition|2026-07-23 10:00:00'))
+        ->and(fleetOpsTelematicServiceInvoke($service, 'makeEventKey', [$telematic, ['device_id' => 'device-1'], $device]))->toBeNull()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'makeSensorIdentity', [['type' => 'fuel', 'name' => 'Tank'], $device]))
+        ->toBe(sha1('device-uuid|fuel|Tank'));
+
+    expect(fleetOpsTelematicServiceInvoke($service, 'normalizeRawSensorList', [[
+        'fuel' => 88,
+        'temp' => ['value' => 20, 'unit' => 'C'],
+    ]]))->toBe([
+        ['sensor_key' => 'fuel', 'name' => 'fuel', 'type' => 'fuel', 'value' => 88],
+        ['sensor_key' => 'temp', 'name' => 'temp', 'value' => 20, 'unit' => 'C'],
+    ]);
+});
+
+test('telematic service resolves timestamps online flags status windows and event signals', function () {
+    Carbon::setTestNow(Carbon::parse('2026-07-23 12:00:00'));
+    $service = fleetOpsTelematicService();
+    $device  = new Device();
+
+    expect(fleetOpsTelematicServiceInvoke($service, 'resolveTelemetryTimestamp', [['timestamp' => '2026-07-23 11:55:00']])?->toDateTimeString())
+        ->toBe('2026-07-23 11:55:00')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveTelemetryTimestamp', [['timestamp' => 'not-a-date']]))->toBeNull()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveReportedOnline', [['online' => 'true']]))->toBeTrue()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveReportedOnline', [['is_online' => 'false']]))->toBeFalse()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'resolveReportedOnline', [[]]))->toBeNull()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, null, true]))->toBe('online')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, null, null]))->toBe('never_connected')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, Carbon::parse('2026-07-23 11:55:00'), null]))->toBe('online')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, Carbon::parse('2026-07-23 11:30:00'), null]))->toBe('recently_offline')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, Carbon::parse('2026-07-23 05:00:00'), null]))->toBe('offline')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'connectionStatusForDevice', [$device, Carbon::parse('2026-07-21 05:00:00'), null]))->toBe('long_offline')
+        ->and(fleetOpsTelematicServiceInvoke($service, 'isProtectedDeviceStatus', ['maintenance']))->toBeTrue()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'isProtectedDeviceStatus', ['active']))->toBeFalse()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'hasEventSignal', [['location' => ['lat' => 1.25]]]))->toBeTrue()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'hasEventSignal', [['speed' => 0]]))->toBeTrue()
+        ->and(fleetOpsTelematicServiceInvoke($service, 'hasEventSignal', [[]]))->toBeFalse();
+
+    Carbon::setTestNow();
+});
+
+test('telematic service reconciles device telemetry without overwriting protected statuses', function () {
+    Carbon::setTestNow(Carbon::parse('2026-07-23 12:00:00'));
+    $service = fleetOpsTelematicService();
+
+    $telematic = new Telematic();
+    $telematic->setRawAttributes([
+        'uuid'         => 'telematic-uuid',
+        'public_id'    => 'telematic_public',
+        'company_uuid' => 'company-uuid',
+        'provider'     => 'flespi',
+    ], true);
+
+    $device         = new FleetOpsTelematicServiceDeviceFake([
+        'status' => 'maintenance',
+        'meta'   => ['existing' => 'kept'],
+    ]);
+    $device->exists = false;
+
+    fleetOpsTelematicServiceInvoke($service, 'reconcileDeviceTelemetry', [$device, $telematic, [
+        'device_id'          => 'device-1',
+        'name'               => 'Truck Device',
+        'model'              => 'FMB920',
+        'provider'           => 'flespi',
+        'imei'               => '123456789',
+        'serial_number'      => 'SER-1',
+        'firmware_version'   => '1.0.0',
+        'location'           => ['lat' => 1.25, 'lng' => 103.75],
+        'last_seen_at'       => '2026-07-23 11:59:00',
+        'online'             => true,
+        'speed'              => 42,
+        'heading'            => 180,
+        'altitude'           => 15,
+        'odometer'           => 12345,
+        'ignition'           => true,
+        'fuel_level'         => 67,
+        'meta'               => ['provider_label' => 'primary'],
+    ]]);
+
+    expect($device->company_uuid)->toBe('company-uuid')
+        ->and($device->name)->toBe('Truck Device')
+        ->and($device->model)->toBe('FMB920')
+        ->and($device->provider)->toBe('flespi')
+        ->and($device->internal_id)->toBe('device-1')
+        ->and($device->imei)->toBe('123456789')
+        ->and($device->serial_number)->toBe('SER-1')
+        ->and($device->firmware_version)->toBe('1.0.0')
+        ->and($device->last_position)->toBe(['latitude' => 1.25, 'longitude' => 103.75])
+        ->and($device->last_online_at?->toDateTimeString())->toBe('2026-07-23 11:59:00')
+        ->and($device->online)->toBeTrue()
+        ->and($device->status)->toBe('maintenance')
+        ->and($device->meta['existing'])->toBe('kept')
+        ->and($device->meta['external_id'])->toBe('device-1')
+        ->and($device->meta['provider_status'])->toBe(['online' => true])
+        ->and($device->meta['telemetry_summary'])->toMatchArray([
+            'last_seen_at' => '2026-07-23 11:59:00',
+            'status'       => 'online',
+            'speed'        => 42,
+            'heading'      => 180,
+            'altitude'     => 15,
+            'odometer'     => 12345,
+            'ignition'     => true,
+            'fuel_level'   => 67,
+        ])
+        ->and($device->meta['provider_label'])->toBe('primary');
+
+    $emptyDevice         = new FleetOpsTelematicServiceDeviceFake();
+    $emptyDevice->exists = false;
+    fleetOpsTelematicServiceInvoke($service, 'reconcileDeviceTelemetry', [$emptyDevice, $telematic, [
+        'device_id' => 'device-2',
+    ]]);
+
+    expect($emptyDevice->name)->toBe('Unknown Device')
+        ->and($emptyDevice->last_position)->toBe(['latitude' => 0, 'longitude' => 0])
+        ->and($emptyDevice->status)->toBe('never_connected')
+        ->and($emptyDevice->online)->toBeFalse();
+
+    Carbon::setTestNow();
+});
+
+test('telematic service applies device event telemetry to devices and positions', function () {
+    Carbon::setTestNow(Carbon::parse('2026-07-23 12:00:00'));
+
+    $service   = fleetOpsTelematicService();
+    $telematic = new Telematic();
+    $telematic->setRawAttributes([
+        'uuid'         => 'telematic-uuid',
+        'public_id'    => 'telematic_public',
+        'company_uuid' => 'company-uuid',
+        'provider'     => 'flespi',
+    ], true);
+
+    $device         = new FleetOpsTelematicServiceDeviceFake([
+        'uuid'      => 'device-uuid',
+        'device_id' => 'device-1',
+        'status'    => 'active',
+        'meta'      => ['device_meta' => 'kept'],
+    ]);
+    $device->exists = true;
+
+    $event = new FleetOpsTelematicServiceEventFake([
+        'uuid'        => 'event-uuid',
+        'public_id'   => 'event_public',
+        'device_uuid' => 'device-uuid',
+        'event_type'  => 'ignition_on',
+        'provider'    => 'flespi',
+        'occurred_at' => Carbon::parse('2026-07-23 11:59:00'),
+    ]);
+
+    fleetOpsTelematicServiceInvoke($service, 'applyDeviceEventTelemetry', [$event, [
+        'device_id'    => 'device-1',
+        'location'     => ['latitude' => 1.25, 'longitude' => 103.75],
+        'online'       => false,
+        'speed'        => 38,
+        'heading'      => 90,
+        'altitude'     => 15,
+        'odometer'     => 12345,
+        'ignition'     => true,
+        'fuel_level'   => 66,
+        'occurred_at'  => '2026-07-23 11:59:00',
+    ], $device, true, $telematic]);
+
+    expect($device->saveCount)->toBe(1)
+        ->and($device->loadMissingCalls)->toBe(['attachable'])
+        ->and($device->last_position)->toBe(['latitude' => 1.25, 'longitude' => 103.75])
+        ->and($device->online)->toBeTrue()
+        ->and($device->status)->toBe('online')
+        ->and($device->meta['device_meta'])->toBe('kept')
+        ->and($device->meta['telemetry_summary'])->toMatchArray([
+            'last_seen_at' => '2026-07-23 11:59:00',
+            'status'       => 'online',
+            'speed'        => 38,
+            'heading'      => 90,
+            'altitude'     => 15,
+            'odometer'     => 12345,
+            'ignition'     => true,
+            'fuel_level'   => 66,
+        ])
+        ->and($event->positions)->toBe([[
+            'latitude'  => 1.25,
+            'longitude' => 103.75,
+            'heading'   => 90,
+            'bearing'   => 90,
+            'speed'     => 38,
+            'altitude'  => 15,
+        ]]);
+
+    Carbon::setTestNow();
+});