@fleetbase/fleetops-engine 0.6.58 → 0.6.60

package/server/tests/Unit/Support/Telematics/Providers/AfaqyProviderTransportTest.php

@@ -0,0 +1,138 @@
+<?php
+
+use Fleetbase\FleetOps\Exceptions\TelematicProviderException;
+use Fleetbase\FleetOps\Support\Telematics\Providers\AfaqyProvider;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Covers the AFAQY provider HTTP transport with faked responses:
+ * authentication success, failure and missing-token errors, authenticated
+ * posts with token-rejection refresh retries, exhausted retries without
+ * refresh credentials, failed requests, provider error context extraction,
+ * byte-count parsing, ignition and fuel extraction, and sensor identity
+ * resolution.
+ */
+class FleetOpsAfaqyTransportProbe extends AfaqyProvider
+{
+    public function setCredentialsForTest(array $credentials): void
+    {
+        $this->credentials = $credentials;
+        if (!empty($credentials['token'])) {
+            $this->setToken($credentials['token']);
+        }
+    }
+
+    public function callHelper(string $method, ...$arguments): mixed
+    {
+        return $this->{$method}(...$arguments);
+    }
+}
+
+function fleetopsAfaqyTransportBoot(): void
+{
+    app()->instance('log', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+}
+
+function fleetopsAfaqyTransportProbe(array $credentials = []): FleetOpsAfaqyTransportProbe
+{
+    $probe = new FleetOpsAfaqyTransportProbe();
+    $probe->setCredentialsForTest($credentials);
+
+    return $probe;
+}
+
+test('authentication resolves tokens and raises detailed failures', function () {
+    fleetopsAfaqyTransportBoot();
+
+    $missing = fleetopsAfaqyTransportProbe([]);
+    expect(fn () => $missing->callHelper('authenticate'))->toThrow(InvalidArgumentException::class);
+
+    Http::fake(['*/auth/login' => Http::response(['data' => ['token' => 'fresh-token']], 200)]);
+    $probe = fleetopsAfaqyTransportProbe(['username' => 'user', 'password' => 'secret']);
+    expect($probe->callHelper('authenticate'))->toBe('fresh-token');
+
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+    Http::fake(['*/auth/login' => Http::response(['message' => 'denied', 'code' => 'AUTH'], 500)]);
+    expect(fn () => $probe->callHelper('authenticate'))->toThrow(TelematicProviderException::class, 'authentication failed');
+
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+    Http::fake(['*/auth/login' => Http::response(['data' => []], 200)]);
+    expect(fn () => $probe->callHelper('authenticate'))->toThrow(TelematicProviderException::class, 'did not return a token');
+});
+
+test('authenticated posts refresh rejected tokens and propagate failures', function () {
+    fleetopsAfaqyTransportBoot();
+
+    // First call rejected, refresh logs in, retry succeeds
+    Http::fake([
+        '*/auth/login' => Http::response(['data' => ['token' => 'refreshed-token']], 200),
+        '*/units/list' => Http::sequence()
+            ->push(['message' => 'expired'], 401)
+            ->push(['data' => ['ok' => true]], 200),
+    ]);
+    $probe  = fleetopsAfaqyTransportProbe(['token' => 'stale-token', 'username' => 'user', 'password' => 'secret']);
+    $result = $probe->callHelper('afaqyPost', '/units/list', ['data' => []]);
+    expect($result['data']['ok'])->toBeTrue();
+
+    // Token rejected without refresh credentials raises immediately
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+    Http::fake(['*/units/list' => Http::response(['error' => ['message' => 'expired', 'code' => 401]], 401)]);
+    $tokenOnly = fleetopsAfaqyTransportProbe(['token' => 'stale-token']);
+    expect(fn () => $tokenOnly->callHelper('afaqyPost', '/units/list'))
+        ->toThrow(TelematicProviderException::class, 'credentials are required');
+
+    // Non-auth failures raise with provider context
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+    Http::fake(['*/units/list' => Http::response(['error_description' => 'boom'], 500)]);
+    try {
+        $tokenOnly->callHelper('afaqyPost', '/units/list');
+        expect(false)->toBeTrue();
+    } catch (TelematicProviderException $e) {
+        expect($e->getMessage())->toContain('failed with status 500');
+    }
+});
+
+test('transport errors and helper extractors resolve metadata', function () {
+    fleetopsAfaqyTransportBoot();
+
+    Http::fake(function () {
+        throw new Illuminate\Http\Client\ConnectionException('cURL error 28: Operation timed out with 512 bytes received');
+    });
+    $probe = fleetopsAfaqyTransportProbe(['token' => 'token-1']);
+    try {
+        $probe->callHelper('afaqyPost', '/units/list');
+        expect(false)->toBeTrue();
+    } catch (TelematicProviderException $e) {
+        expect($e->getMessage())->toContain('timed out');
+    }
+
+    expect($probe->callHelper('extractBytesReceived', 'Operation timed out with 512 bytes received'))->toBe(512)
+        ->and($probe->callHelper('extractBytesReceived', 'no byte info'))->toBeNull();
+
+    expect($probe->callHelper('extractIgnition', ['last_update' => ['params' => ['acc' => '1']]]))->toBeTrue()
+        ->and($probe->callHelper('extractIgnition', ['counters' => ['last_acc' => 0]]))->toBeFalse()
+        ->and($probe->callHelper('extractIgnition', []))->toBeNull();
+
+    expect($probe->callHelper('extractFuelLevel', ['fc' => ['level' => 55]]))->toBe(55)
+        ->and($probe->callHelper('extractFuelLevel', []))->toBeNull();
+
+    expect($probe->callHelper('resolveSensorIdentity', ['sensor_id' => 's-9']))->toBe('s-9')
+        ->and($probe->callHelper('resolveSensorIdentity', ['sensor' => ['name' => 'Temp']]))->toBe('Temp')
+        ->and($probe->callHelper('resolveSensorIdentity', []))->toBeNull();
+
+    expect($probe->callHelper('resolveSensorName', ['param' => 'fuel'], 'fallback'))->toBe('fuel')
+        ->and($probe->callHelper('resolveSensorName', [], 'fallback'))->toBe('fallback');
+});

package/server/tests/Unit/Support/Telematics/Providers/GeotabProviderTest.php

@@ -0,0 +1,329 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\Providers\GeotabProvider;
+use Illuminate\Support\Carbon;
+
+class FleetOpsGeotabProviderProbe extends GeotabProvider
+{
+    public array $calls     = [];
+    public array $responses = [];
+
+    public function queueResponse(array $response): void
+    {
+        $this->responses[] = $response;
+    }
+
+    public function setCredentialsForTest(array $credentials): void
+    {
+        $this->credentials = $credentials;
+    }
+
+    public function sessionIdForTest(): ?string
+    {
+        return $this->sessionId;
+    }
+
+    public function headersForTest(): array
+    {
+        return $this->headers;
+    }
+
+    public function prepareAuthenticationForTest(): void
+    {
+        $this->prepareAuthentication();
+    }
+
+    public function fetchLatestLogRecordsForTest(array $devices, array $options = []): array
+    {
+        return $this->fetchLatestLogRecords($devices, $options);
+    }
+
+    public function parseTimestampForTest($value): ?string
+    {
+        return $this->parseTimestamp($value);
+    }
+
+    protected function postGeotab(array $payload): ?array
+    {
+        $this->calls[] = $payload;
+
+        return array_shift($this->responses);
+    }
+}
+
+function fleetopsGeotabProvider(array $credentials = []): FleetOpsGeotabProviderProbe
+{
+    $provider = new FleetOpsGeotabProviderProbe();
+    $provider->setCredentialsForTest(array_merge([
+        'database' => 'fleetbase-db',
+        'username' => 'fleetbase-user',
+        'password' => 'fleetbase-secret',
+    ], $credentials));
+
+    return $provider;
+}
+
+test('geotab provider authenticates and masks session metadata', function () {
+    $provider = fleetopsGeotabProvider();
+    $provider->queueResponse([
+        'result' => [
+            'credentials' => [
+                'sessionId' => '0123456789abcdef',
+            ],
+        ],
+    ]);
+
+    expect($provider->testConnection([
+        'database' => 'fleetbase-db',
+        'username' => 'fleetbase-user',
+        'password' => 'fleetbase-secret',
+    ]))->toBe([
+        'success'  => true,
+        'message'  => 'Connection successful',
+        'metadata' => [
+            'session_id' => '0123456789...',
+        ],
+    ])
+        ->and($provider->sessionIdForTest())->toBe('0123456789abcdef')
+        ->and($provider->calls)->toBe([
+            [
+                'method' => 'Authenticate',
+                'params' => [
+                    'database' => 'fleetbase-db',
+                    'userName' => 'fleetbase-user',
+                    'password' => 'fleetbase-secret',
+                ],
+            ],
+        ]);
+});
+
+test('geotab provider reports authentication failures and prepares headers after connect', function () {
+    $failure = fleetopsGeotabProvider();
+    $failure->queueResponse(['result' => []]);
+
+    expect($failure->testConnection([
+        'database' => 'fleetbase-db',
+        'username' => 'fleetbase-user',
+        'password' => 'fleetbase-secret',
+    ]))->toBe([
+        'success'  => false,
+        'message'  => 'Geotab authentication failed',
+        'metadata' => [],
+    ]);
+
+    $telematic = new Telematic();
+    $telematic->setRawAttributes([
+        'uuid'        => 'telematic-geotab',
+        'credentials' => [
+            'database' => 'connected-db',
+            'username' => 'connected-user',
+            'password' => 'connected-secret',
+        ],
+    ], true);
+
+    $connected = new FleetOpsGeotabProviderProbe();
+    $connected->queueResponse([
+        'result' => [
+            'credentials' => [
+                'sessionId' => 'connected-session',
+            ],
+        ],
+    ]);
+
+    $connected->connect($telematic);
+
+    expect($connected->sessionIdForTest())->toBe('connected-session')
+        ->and($connected->headersForTest())->toBe(['Content-Type' => 'application/json'])
+        ->and($connected->calls[0]['params'])->toMatchArray([
+            'database' => 'connected-db',
+            'userName' => 'connected-user',
+            'password' => 'connected-secret',
+        ]);
+
+    $connected->prepareAuthenticationForTest();
+
+    expect($connected->calls)->toHaveCount(1);
+});
+
+test('geotab provider fetches devices details and latest log records through api calls', function () {
+    Carbon::setTestNow(Carbon::parse('2026-07-27 12:00:00'));
+
+    try {
+        $provider = fleetopsGeotabProvider();
+        $provider->queueResponse([
+            'result' => [
+                ['id' => 'device-1', 'name' => 'Truck 1'],
+                ['id'   => 'device-2', 'name' => 'Truck 2'],
+                ['name' => 'Unnamed missing id'],
+            ],
+        ]);
+        $provider->queueResponse([
+            'result' => [
+                ['id' => 'old-log', 'device' => ['id' => 'device-1'], 'dateTime' => '2026-07-27T08:00:00Z', 'latitude' => 1, 'longitude' => 2],
+                ['id' => 'new-log', 'device' => ['id' => 'device-1'], 'dateTime' => '2026-07-27T09:00:00Z', 'latitude' => 3, 'longitude' => 4],
+                ['id' => 'other-log', 'device' => ['id' => 'other-device'], 'dateTime' => '2026-07-27T10:00:00Z'],
+                ['id' => 'missing-device', 'dateTime' => '2026-07-27T10:00:00Z'],
+            ],
+        ]);
+        $provider->queueResponse([
+            'result' => [
+                ['id' => 'device-1', 'name' => 'Truck 1', 'serialNumber' => 'serial-1'],
+            ],
+        ]);
+
+        $devices = $provider->fetchDevices(['limit' => 3, 'from_date' => '2026-07-27T00:00:00Z']);
+        $details = $provider->fetchDeviceDetails('device-1');
+
+        expect($devices)->toMatchArray([
+            'next_cursor' => null,
+            'has_more'    => false,
+        ])
+            ->and($devices['devices'])->toHaveCount(3)
+            ->and($devices['devices'][0]['latest_log_record'])->toMatchArray([
+                'id'        => 'new-log',
+                'latitude'  => 3,
+                'longitude' => 4,
+            ])
+            ->and(array_key_exists('latest_log_record', $devices['devices'][1]))->toBeFalse()
+            ->and($details)->toBe([
+                'id'           => 'device-1',
+                'name'         => 'Truck 1',
+                'serialNumber' => 'serial-1',
+            ])
+            ->and($provider->calls)->toMatchArray([
+                [
+                    'method' => 'Get',
+                    'params' => [
+                        'typeName'     => 'Device',
+                        'resultsLimit' => 3,
+                        'credentials'  => [
+                            'database'  => 'fleetbase-db',
+                            'sessionId' => null,
+                        ],
+                    ],
+                ],
+                [
+                    'method' => 'Get',
+                    'params' => [
+                        'typeName'     => 'LogRecord',
+                        'search'       => ['fromDate' => '2026-07-27T00:00:00Z'],
+                        'resultsLimit' => 100,
+                        'credentials'  => [
+                            'database'  => 'fleetbase-db',
+                            'sessionId' => null,
+                        ],
+                    ],
+                ],
+                [
+                    'method' => 'Get',
+                    'params' => [
+                        'typeName'    => 'Device',
+                        'search'      => ['id' => 'device-1'],
+                        'credentials' => [
+                            'database'  => 'fleetbase-db',
+                            'sessionId' => null,
+                        ],
+                    ],
+                ],
+            ]);
+
+        $emptyLogs = $provider->fetchLatestLogRecordsForTest([
+            ['name' => 'No external id'],
+        ]);
+
+        expect($emptyLogs)->toBe([]);
+    } finally {
+        Carbon::setTestNow();
+    }
+});
+
+test('geotab provider normalizes fallback device event sensor and schema contracts', function () {
+    $provider = new GeotabProvider();
+
+    $device = $provider->normalizeDevice([
+        'id'         => 'device-3',
+        'activeFrom' => '2026-01-01',
+        'activeTo'   => '2026-12-31',
+        'groups'     => [['id' => 'group-1']],
+    ]);
+    $event = $provider->normalizeEvent([
+        'id'        => 'event-1',
+        'deviceId'  => 'device-3',
+        'type'      => 'fault',
+        'dateTime'  => '2026-07-27T11:30:00Z',
+        'latitude'  => 12.34,
+        'longitude' => 56.78,
+        'heading'   => 270,
+    ]);
+    $sensor = $provider->normalizeSensor([
+        'diagnosticType' => 'engine_temperature',
+        'data'           => 92,
+        'dateTime'       => '2026-07-27T11:31:00Z',
+    ]);
+
+    expect($device)->toMatchArray([
+        'device_id'    => 'device-3',
+        'name'         => 'Unknown Device',
+        'online'       => null,
+        'last_seen_at' => null,
+        'location'     => ['lat' => null, 'lng' => null],
+    ])
+        ->and($device['meta']['provider_status'])->toBe([
+            'active_from' => '2026-01-01',
+            'active_to'   => '2026-12-31',
+            'groups'      => [['id' => 'group-1']],
+            'has_log'     => false,
+        ])
+        ->and($event)->toMatchArray([
+            'external_id' => 'event-1',
+            'device_id'   => 'device-3',
+            'event_type'  => 'fault',
+            'occurred_at' => '2026-07-27 11:30:00',
+            'online'      => true,
+            'location'    => ['lat' => 12.34, 'lng' => 56.78],
+            'heading'     => 270,
+        ])
+        ->and($sensor)->toBe([
+            'sensor_type' => 'engine_temperature',
+            'value'       => 92,
+            'recorded_at' => '2026-07-27T11:31:00Z',
+            'meta'        => [
+                'diagnosticType' => 'engine_temperature',
+                'data'           => 92,
+                'dateTime'       => '2026-07-27T11:31:00Z',
+            ],
+        ])
+        ->and($provider->getCredentialSchema())->toBe([
+            [
+                '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,
+            ],
+        ])
+        ->and($provider->supportsWebhooks())->toBeFalse()
+        ->and($provider->getRateLimits()['requests_per_minute'])->toBe(50);
+});
+
+test('geotab provider parses nullable timestamps', function () {
+    $provider = fleetopsGeotabProvider();
+
+    expect($provider->parseTimestampForTest(null))->toBeNull()
+        ->and($provider->parseTimestampForTest('2026-07-27T11:45:00Z'))->toBe('2026-07-27 11:45:00');
+});

package/server/tests/Unit/Support/Telematics/Providers/ProviderTransportSeamsTest.php

@@ -0,0 +1,133 @@
+<?php
+
+use Fleetbase\FleetOps\Exceptions\TelematicProviderException;
+use Fleetbase\FleetOps\Support\Telematics\Providers\AfaqyProvider;
+use Fleetbase\FleetOps\Support\Telematics\Providers\GeotabProvider;
+use Fleetbase\FleetOps\Support\Telematics\Providers\SafeeProvider;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * The provider transport seams that behaviour tests replace with response
+ * queues, plus the two authentication arms that only a real response can reach.
+ *
+ * These live in their own file because `Http::fake()` state leaks between tests
+ * in the shared harness — the same reason `TelematicsHardeningTest` carries a
+ * skipped case.
+ */
+class FleetOpsProviderTransportGeotabProbe extends GeotabProvider
+{
+    public function setCredentialsForTest(array $credentials): void
+    {
+        $this->credentials = $credentials;
+    }
+
+    public function callHelper(string $method, ...$arguments): mixed
+    {
+        return $this->{$method}(...$arguments);
+    }
+}
+
+class FleetOpsProviderTransportAfaqyProbe extends AfaqyProvider
+{
+    public function setCredentialsForTest(array $credentials): void
+    {
+        $this->credentials = $credentials;
+        if (!empty($credentials['token'])) {
+            $this->setToken($credentials['token']);
+        }
+    }
+
+    public function callHelper(string $method, ...$arguments): mixed
+    {
+        return $this->{$method}(...$arguments);
+    }
+}
+
+class FleetOpsProviderTransportSafeeProbe extends SafeeProvider
+{
+    public function setCredentialsForTest(array $credentials): void
+    {
+        $this->credentials = $credentials;
+    }
+
+    public function callHelper(string $method, ...$arguments): mixed
+    {
+        return $this->{$method}(...$arguments);
+    }
+}
+
+function fleetopsProviderTransportBoot(): void
+{
+    app()->instance('log', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+    Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+
+    Http::clearResolvedInstances();
+    app()->forgetInstance(Illuminate\Http\Client\Factory::class);
+}
+
+test('the geotab transport posts the payload and returns the decoded body', function () {
+    fleetopsProviderTransportBoot();
+    $recorded = [];
+    Http::fake(function ($request) use (&$recorded) {
+        $recorded[] = $request;
+
+        return Http::response(['result' => ['id' => 'device-1']], 200);
+    });
+
+    $provider = new FleetOpsProviderTransportGeotabProbe();
+    $provider->setCredentialsForTest(['database' => 'fleetbase-db']);
+
+    // Behaviour tests override this seam with a canned response queue, so the
+    // real body only runs when it is invoked directly
+    $result = $provider->callHelper('postGeotab', ['method' => 'Get', 'params' => ['typeName' => 'Device']]);
+
+    expect($result)->toBe(['result' => ['id' => 'device-1']])
+        ->and($recorded)->toHaveCount(1)
+        ->and($recorded[0]->data())->toBe(['method' => 'Get', 'params' => ['typeName' => 'Device']]);
+});
+
+test('afaqy reports a rejected token differently once a refresh has already been spent', function () {
+    fleetopsProviderTransportBoot();
+    Http::fake(['*' => Http::response(['message' => 'unauthorized'], 401)]);
+
+    // Username and password are present, so the provider could refresh — but
+    // the retry has already been used, which is the arm being covered here
+    $probe = new FleetOpsProviderTransportAfaqyProbe();
+    $probe->setCredentialsForTest([
+        'token'    => 'stale-token',
+        'username' => 'user',
+        'password' => 'secret',
+    ]);
+
+    expect(fn () => $probe->callHelper('authenticatedPost', '/devices/list', [], false, false))
+        ->toThrow(TelematicProviderException::class, 'AFAQY token rejected after refresh with status 401');
+
+    // Without refresh credentials the message names the missing ones instead
+    $credentialless = new FleetOpsProviderTransportAfaqyProbe();
+    $credentialless->setCredentialsForTest(['token' => 'stale-token']);
+
+    expect(fn () => $credentialless->callHelper('authenticatedPost', '/devices/list', [], false, false))
+        ->toThrow(TelematicProviderException::class, 'username/password credentials are required');
+});
+
+test('safee authentication rejects a successful response that carries no token', function () {
+    fleetopsProviderTransportBoot();
+    Http::fake(['*' => Http::response(['expires_in' => 300], 200)]);
+
+    $probe = new FleetOpsProviderTransportSafeeProbe();
+    $probe->setCredentialsForTest([
+        'realm_id'      => 'fleetbase',
+        'client_id'     => 'client',
+        'client_secret' => 'secret',
+        'username'      => 'user',
+        'password'      => 'password',
+    ]);
+
+    expect(fn () => $probe->callHelper('authenticate'))
+        ->toThrow(RuntimeException::class, 'Safee authentication did not return an access token.');
+});