@fleetbase/fleetops-engine 0.6.69 → 0.6.70

package/server/tests/Unit/Support/AuthorizationTest.php

@@ -0,0 +1,142 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Authorization;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
+use Fleetbase\Models\User;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\Exceptions\HttpResponseException;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+
+if (!function_exists('Fleetbase\\Support\\auth')) {
+    eval('namespace Fleetbase\\Support; function auth() { return \\app("fleetops.authorization.test-auth"); }');
+}
+
+if (!function_exists('Fleetbase\\Support\\session')) {
+    eval('namespace Fleetbase\\Support; function session($key = null, $default = null) { return \\session($key, $default); }');
+}
+
+class FleetOpsAuthorizationUser extends User
+{
+    public array $grantedPermissions        = [];
+    public bool $permissionStoreUnavailable = false;
+
+    public function hasPermissionTo($permission, $guardName = null): bool
+    {
+        if ($this->permissionStoreUnavailable) {
+            throw new RuntimeException('Permission store unavailable');
+        }
+
+        return in_array($permission->name, $this->grantedPermissions, true);
+    }
+}
+
+beforeEach(function () {
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Model::setConnectionResolver($resolver);
+    config()->set('auth.defaults.guard', 'sanctum');
+    config()->set('permission.table_names.permissions', 'permissions');
+    $connection->getSchemaBuilder()->create('permissions', function ($table) {
+        $table->string('id')->primary();
+        $table->string('name');
+        $table->string('guard_name')->default('sanctum');
+    });
+    $connection->table('permissions')->insert([
+        ['id' => 'optimize', 'name' => 'fleet-ops optimize order'],
+        ['id' => 'dispatch', 'name' => 'fleet-ops dispatch order'],
+        ['id' => 'resource', 'name' => 'fleet-ops * order'],
+        ['id' => 'service', 'name' => 'fleet-ops *'],
+    ]);
+    session(['user' => null]);
+    $this->user = new FleetOpsAuthorizationUser();
+    $this->user->setRawAttributes(['type' => 'user'], true);
+    $this->auth = new class($this->user) {
+        public bool $unavailable = false;
+
+        public function __construct(public ?User $currentUser)
+        {
+        }
+
+        public function user(): ?User
+        {
+            if ($this->unavailable) {
+                throw new RuntimeException('Session unavailable');
+            }
+
+            return $this->currentUser;
+        }
+    };
+    app()->instance('fleetops.authorization.test-auth', $this->auth);
+});
+
+test('operation authorization accepts exact and wildcard grants', function (string $grant) {
+    $this->user->grantedPermissions = [$grant];
+
+    expect(Authorization::canAny('optimize order'))->toBeTrue();
+    Authorization::authorize('optimize order');
+})->with(['fleet-ops optimize order', 'fleet-ops * order', 'fleet-ops *']);
+
+test('operation authorization accepts any requested permission and rejects missing grants', function () {
+    $this->user->grantedPermissions = ['fleet-ops dispatch order'];
+
+    expect(Authorization::canAny('optimize order'))->toBeFalse()
+        ->and(Authorization::canAny('optimize order', 'dispatch order'))->toBeTrue()
+        ->and(Authorization::canAny('list unseeded-resource'))->toBeTrue();
+    expect(fn () => Authorization::authorize('optimize order'))->toThrow(HttpResponseException::class);
+
+    $this->user->permissionStoreUnavailable = true;
+    expect(Authorization::canAny('dispatch order'))->toBeFalse();
+});
+
+test('platform administrators pass operations while system settings reject ordinary users', function () {
+    expect(fn () => Authorization::authorizeAdmin())->toThrow(HttpResponseException::class);
+    $this->user->setAttribute('type', 'admin');
+    expect(Authorization::canAny('optimize order'))->toBeTrue();
+    Authorization::authorizeAdmin();
+});
+
+test('authorization fails closed when the authenticated user is missing or cannot be read', function () {
+    $this->auth->currentUser = null;
+    expect(Authorization::canAny('optimize order'))->toBeFalse();
+    expect(fn () => Authorization::authorizeAdmin())->toThrow(HttpResponseException::class);
+    $this->auth->unavailable = true;
+    expect(Authorization::canAny('optimize order'))->toBeFalse();
+});
+
+test('controller middleware applies the mapped operation and administrator checks', function () {
+    $controller = new class extends Controller {
+        use AuthorizesMethods;
+
+        public function __construct()
+        {
+            $this->authorizeMethods(['optimize' => ['optimize order', 'dispatch order'], 'settings' => 'admin']);
+        }
+    };
+    $middleware                     = $controller->getMiddleware();
+    $request                        = Request::create('/');
+    $this->user->grantedPermissions = ['fleet-ops dispatch order'];
+
+    expect($middleware[0]['options']['only'])->toBe(['optimize'])
+        ->and($middleware[0]['middleware']($request, fn ($nextRequest) => $nextRequest))->toBe($request);
+    expect(fn () => $middleware[1]['middleware']($request, fn () => 'allowed'))->toThrow(HttpResponseException::class);
+    $this->user->setAttribute('type', 'admin');
+    expect($middleware[1]['middleware']($request, fn () => 'allowed'))->toBe('allowed');
+});
+
+test('analytics controllers enforce authorization before invoking their next middleware', function (string $class) {
+    $connection = Model::getConnectionResolver()->connection();
+    $connection->table('permissions')->insert(['id' => 'analytics', 'name' => 'fleet-ops view analytics']);
+    $controller = new $class();
+    $middleware = $controller->getMiddleware()[0]['middleware'];
+    $request    = Request::create('/analytics');
+    expect(fn () => $middleware($request, fn () => 'private analytics'))->toThrow(HttpResponseException::class);
+    $this->user->grantedPermissions = ['fleet-ops view analytics'];
+    expect($middleware($request, fn ($forwarded) => $forwarded))->toBe($request);
+})->with([
+    Fleetbase\FleetOps\Http\Controllers\Internal\v1\AnalyticsController::class,
+    Fleetbase\FleetOps\Http\Controllers\Internal\v1\MetricsController::class,
+]);

package/server/tests/Unit/Support/MaintainableAndOperationalAlertsTest.php

@@ -184,10 +184,21 @@ test('operational alert helpers query orders positions and settings', function (
     $order = Order::where('uuid', 'order-1')->withoutGlobalScopes()->first();
     expect($probe->callHelper('latestPositionForOrder', $order))->toBeInstanceOf(Position::class);
 
-    $settings = $probe->callHelper('alertSettings');
+    $settings = $probe->callHelper('alertSettings', $order);
     expect($settings['late_departures']['enabled'])->toBeTrue()
         ->and($settings['route_deviations']['distance_threshold_meters'])->toBe(500)
         ->and($settings['prolonged_stoppages']['duration_threshold_minutes'])->toBe(30);
+
+    // Settings resolve from the order's company without a company session
+    $connection->table('settings')->insert([
+        'key'   => 'company.company-1.tracking',
+        'value' => json_encode(['alerts' => ['late_departures' => ['enabled' => false], 'route_deviations' => ['distance_threshold_meters' => 750]]]),
+    ]);
+    session(['company' => null]);
+    $settings = $probe->callHelper('alertSettings', $order);
+    session(['company' => 'company-1']);
+    expect($settings['late_departures']['enabled'])->toBeFalse()
+        ->and($settings['route_deviations']['distance_threshold_meters'])->toBe(750);
 });
 
 test('route point collection normalizes pairs and measures distances', function () {

package/server/tests/Unit/Support/MoreQuerySeamsTest.php

@@ -384,13 +384,22 @@ test('index driver resource counts assigned orders and names the current one', f
 });
 
 test('shift change listener reads company scheduling settings', function () {
-    fleetopsMoreSeamBoot();
+    $connection = fleetopsMoreSeamBoot();
 
     $class    = Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class;
     $listener = (new ReflectionClass($class))->newInstanceWithoutConstructor();
 
     // With nothing stored the lookup falls back to the empty default
-    expect(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings'))->toBe([]);
+    expect(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', ['company-seam-2']))->toBe([]);
+
+    // Queued listeners have no company session, so the schedule's company is used
+    $connection->table('settings')->insert(['key' => 'company.company-seam-3.fleet-ops.scheduling-settings', 'value' => json_encode(['notify_drivers_on_shift_change' => true])]);
+    session(['company' => null]);
+    $settings = fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', ['company-seam-3']);
+    session(['company' => 'company-seam-2']);
+
+    expect($settings)->toBe(['notify_drivers_on_shift_change' => true])
+        ->and(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', [null]))->toBe([]);
 });
 
 test('order insights capability builds its own company-scoped order query', function () {

package/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php

@@ -0,0 +1,190 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Illuminate\Support\Carbon;
+
+/**
+ * RetentionPolicy combines administrator policy with allowed company history
+ * preferences, enforces maximums, and caches policies for long-lived workers.
+ */
+function fleetopsRetentionResolver(array $system, array $company, ?array &$calls = null): void
+{
+    $calls                             = [];
+    RetentionPolicy::$settingsResolver = function (string $scope, string $key, mixed $default, ?string $companyUuid) use ($system, $company, &$calls) {
+        $calls[] = [$scope, $key, $companyUuid];
+        expect($key)->toBe(RetentionPolicy::SETTING_KEY);
+
+        return $scope === 'system' ? $system : ($company[$companyUuid] ?? $default);
+    };
+}
+
+beforeEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    config(['telematics.telemetry' => ['event_retention_days' => 45, 'processed_retention_hours' => 48, 'log_telemetry_activity' => true, 'poll_queue' => 'default']]);
+});
+
+afterEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    Carbon::setTestNow();
+    config(['telematics.telemetry' => []]);
+});
+
+test('defaults come from package config, overridden by the admin setting, with everything clamped', function () {
+    fleetopsRetentionResolver([], []);
+    expect(RetentionPolicy::defaults())->toBe([
+        'event_retention_days'        => 45,
+        'event_compact_after_days'    => 7,
+        'position_retention_days'     => 90,
+        'processed_retention_hours'   => 48,
+        'quarantine_retention_days'   => 7,
+        'sync_run_retention_days'     => 7,
+        'max_event_retention_days'    => 0,
+        'max_position_retention_days' => 0,
+        'log_telemetry_activity'      => true,
+    ]);
+
+    RetentionPolicy::flush();
+    fleetopsRetentionResolver([
+        'event_retention_days'      => 99999,
+        'event_compact_after_days'  => '',
+        'position_retention_days'   => 0,
+        'quarantine_retention_days' => -5,
+        'processed_retention_hours' => null,
+        'log_telemetry_activity'    => 'no',
+        'ignored'                   => 'value',
+    ], []);
+    $defaults = RetentionPolicy::defaults();
+    expect($defaults['event_retention_days'])->toBe(3650)
+        ->and($defaults['event_compact_after_days'])->toBe(7)
+        ->and($defaults['position_retention_days'])->toBe(0)
+        ->and($defaults['quarantine_retention_days'])->toBe(1)
+        ->and($defaults['processed_retention_hours'])->toBe(48)
+        ->and($defaults['log_telemetry_activity'])->toBeFalse()
+        ->and($defaults)->not->toHaveKey('ignored')
+        ->and(RetentionPolicy::keys())->toBe(array_keys(RetentionPolicy::FALLBACKS));
+});
+
+test('company policies layer over the defaults and are cached until flushed', function () {
+    fleetopsRetentionResolver(['position_retention_days' => 30], ['company-1' => ['event_retention_days' => 10, 'log_telemetry_activity' => false]], $calls);
+
+    $policy = RetentionPolicy::forCompany('company-1');
+    expect($policy->get('event_retention_days'))->toBe(10)
+        ->and($policy->get('position_retention_days'))->toBe(30)
+        ->and($policy->get('processed_retention_hours'))->toBe(48)
+        ->and($policy->logsTelemetryActivity())->toBeTrue()
+        ->and($policy->toArray())->toHaveKeys(RetentionPolicy::keys())
+        ->and(RetentionPolicy::forCompany('company-1'))->toBe($policy)
+        ->and(RetentionPolicy::forCompany(null)->toArray())->toBe(RetentionPolicy::defaults())
+        ->and(RetentionPolicy::forCompany('company-2')->get('event_retention_days'))->toBe(45)
+        ->and(array_column($calls, 0))->toBe(['system', 'company', 'company']);
+
+    RetentionPolicy::flush('company-1');
+    RetentionPolicy::forCompany('company-1');
+    RetentionPolicy::forCompany('company-2');
+    expect(count($calls))->toBe(4);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::forCompany('company-2');
+    expect(array_column($calls, 0))->toBe(['system', 'company', 'company', 'company', 'system', 'company']);
+});
+
+test('company history respects admin maximums and cannot override infrastructure or logging', function () {
+    fleetopsRetentionResolver([
+        'event_retention_days'        => 0,
+        'position_retention_days'     => 90,
+        'max_event_retention_days'    => 30,
+        'max_position_retention_days' => 45,
+        'log_telemetry_activity'      => false,
+    ], [
+        'company-1' => [
+            'event_retention_days'        => 0,
+            'position_retention_days'     => 120,
+            'max_event_retention_days'    => 0,
+            'max_position_retention_days' => 0,
+            'event_compact_after_days'    => 0,
+            'processed_retention_hours'   => 0,
+            'quarantine_retention_days'   => 0,
+            'sync_run_retention_days'     => 0,
+            'log_telemetry_activity'      => true,
+        ],
+        'company-2' => ['event_retention_days' => 5, 'position_retention_days' => 15],
+    ]);
+
+    $policy = RetentionPolicy::forCompany('company-1');
+    expect($policy->get('event_retention_days'))->toBe(30)
+        ->and($policy->get('position_retention_days'))->toBe(45)
+        ->and($policy->get('event_compact_after_days'))->toBe(7)
+        ->and($policy->get('processed_retention_hours'))->toBe(48)
+        ->and($policy->get('quarantine_retention_days'))->toBe(7)
+        ->and($policy->get('sync_run_retention_days'))->toBe(7)
+        ->and($policy->logsTelemetryActivity())->toBeFalse()
+        ->and(RetentionPolicy::forCompany('company-2')->get('event_retention_days'))->toBe(5)
+        ->and(RetentionPolicy::forCompany('company-2')->get('position_retention_days'))->toBe(15)
+        ->and(RetentionPolicy::forCompany('inherited')->get('event_retention_days'))->toBe(30)
+        ->and(RetentionPolicy::forCompany('inherited')->get('position_retention_days'))->toBe(45)
+        ->and(RetentionPolicy::forCompany(null)->get('event_retention_days'))->toBe(30);
+});
+
+test('unconfigured maximums preserve unlimited history and null preferences inherit defaults', function () {
+    fleetopsRetentionResolver([], ['company-1' => ['event_retention_days' => 0, 'position_retention_days' => null]]);
+
+    expect(RetentionPolicy::forCompany('company-1')->get('event_retention_days'))->toBe(0)
+        ->and(RetentionPolicy::forCompany('company-1')->get('position_retention_days'))->toBe(90)
+        ->and(RetentionPolicy::companyPreferences(['event_retention_days' => 'invalid', 'position_retention_days' => false]))->toBe([])
+        ->and(RetentionPolicy::companyPreferences(['event_retention_days' => null, 'position_retention_days' => '', 'log_telemetry_activity' => true]))->toBe([]);
+});
+
+test('constrained preferences keep zero explicit when allowed and replace it when an administrator imposes a maximum', function () {
+    $preferences = ['event_retention_days' => 0, 'position_retention_days' => null];
+    expect(RetentionPolicy::constrainCompanyPreferences($preferences, RetentionPolicy::FALLBACKS))->toBe(['event_retention_days' => 0]);
+
+    $defaults = array_replace(RetentionPolicy::FALLBACKS, ['max_event_retention_days' => 90, 'max_position_retention_days' => 360]);
+    $bounded  = RetentionPolicy::constrainCompanyPreferences($preferences, $defaults);
+    expect($bounded)->toBe(['event_retention_days' => 90])
+        ->and(RetentionPolicy::constrainCompanyPreferences(['event_retention_days' => 30, 'position_retention_days' => 720], $defaults))->toBe(['event_retention_days' => 30, 'position_retention_days' => 360])
+        ->and(RetentionPolicy::constrainCompanyPreferences([], $defaults))->toBe([])
+        ->and(RetentionPolicy::constrainCompanyPreferences($bounded, RetentionPolicy::FALLBACKS))->toBe(['event_retention_days' => 90]);
+});
+
+test('cutoffs, compaction and deletion rules follow the clamped values', function () {
+    Carbon::setTestNow('2026-09-23 12:00:00 UTC');
+
+    $policy = RetentionPolicy::fromArray(['event_retention_days' => 10, 'event_compact_after_days' => 10, 'processed_retention_hours' => 6, 'position_retention_days' => 0]);
+    expect($policy->deletesEvents())->toBeTrue()
+        ->and($policy->compactsEvents())->toBeFalse()
+        ->and($policy->cutoff('processed_retention_hours')?->toDateTimeString())->toBe('2026-09-23 06:00:00')
+        ->and($policy->cutoff('event_retention_days')?->toDateTimeString())->toBe('2026-09-13 12:00:00')
+        ->and($policy->cutoff('position_retention_days'))->toBeNull()
+        ->and($policy->cutoff('unknown'))->toBeNull()
+        ->and($policy->get('unknown'))->toBeNull();
+
+    expect(RetentionPolicy::fromArray(['event_retention_days' => 10, 'event_compact_after_days' => 3])->compactsEvents())->toBeTrue()
+        ->and(RetentionPolicy::fromArray(['event_retention_days' => 0, 'event_compact_after_days' => 5])->compactsEvents())->toBeTrue()
+        ->and(RetentionPolicy::fromArray(['event_retention_days' => 0, 'event_compact_after_days' => 5])->deletesEvents())->toBeFalse()
+        ->and(RetentionPolicy::fromArray(['event_compact_after_days' => 0])->compactsEvents())->toBeFalse()
+        ->and(RetentionPolicy::fromArray([], ['event_retention_days' => 12])->get('event_retention_days'))->toBe(12)
+        ->and(RetentionPolicy::normalize(['log_telemetry_activity' => '1'], [])['log_telemetry_activity'])->toBeTrue();
+});
+
+test('a failing or malformed settings store falls back to the layer below', function () {
+    RetentionPolicy::$settingsResolver = fn () => throw new RuntimeException('settings unavailable');
+    expect(RetentionPolicy::forCompany('company-1')->get('event_retention_days'))->toBe(45);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = fn () => 'not-an-array';
+    expect(RetentionPolicy::defaults()['processed_retention_hours'])->toBe(48);
+});
+
+test('company lookups scope the session for the setting store and restore it afterwards', function () {
+    // Without a resolver the policy reaches Setting, which has no database here and throws.
+    app('session')->put('company', 'previous-company');
+    expect(RetentionPolicy::forCompany('company-9')->get('event_retention_days'))->toBe(45)
+        ->and(app('session')->get('company'))->toBe('previous-company');
+
+    app('session')->forget('company');
+    RetentionPolicy::flush();
+    expect(RetentionPolicy::forCompany('company-9')->get('processed_retention_hours'))->toBe(48)
+        ->and(app('session')->has('company'))->toBeFalse();
+});

package/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php

@@ -0,0 +1,68 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Fleetbase\FleetOps\Support\Telematics\Retention\TelemetryActivity;
+use Spatie\Activitylog\ActivityLogger;
+
+/**
+ * Telemetry writes bypass the activity log unless an administrator enabled it, and
+ * still run when no activity logger is available.
+ */
+function fleetopsTelemetryActivityLogger(): ActivityLogger
+{
+    $logger = new class extends ActivityLogger {
+        public int $suppressed = 0;
+
+        public function __construct()
+        {
+        }
+
+        public function withoutLogs(Closure $callback): mixed
+        {
+            $this->suppressed++;
+
+            return $callback();
+        }
+    };
+    app()->instance(ActivityLogger::class, $logger);
+
+    return $logger;
+}
+
+beforeEach(function () {
+    RetentionPolicy::flush();
+    config(['telematics.telemetry' => []]);
+});
+
+afterEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    app()->forgetInstance(ActivityLogger::class);
+});
+
+test('telemetry activity follows the system policy and ignores legacy company overrides', function () {
+    RetentionPolicy::$settingsResolver = fn (string $scope, string $key, mixed $default, ?string $company) => $company === 'verbose' ? ['log_telemetry_activity' => true] : [];
+    $logger                            = fleetopsTelemetryActivityLogger();
+
+    expect(TelemetryActivity::run('quiet', fn () => 'saved'))->toBe('saved')
+        ->and($logger->suppressed)->toBe(1)
+        ->and(TelemetryActivity::run('verbose', fn () => 'saved'))->toBe('saved')
+        ->and($logger->suppressed)->toBe(2)
+        ->and(TelemetryActivity::run(null, fn () => 'system'))->toBe('system')
+        ->and($logger->suppressed)->toBe(3);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = fn (string $scope) => ['log_telemetry_activity' => $scope === 'system'];
+
+    expect(TelemetryActivity::run('quiet', fn () => 'logged'))->toBe('logged')
+        ->and(TelemetryActivity::run('verbose', fn () => 'logged'))->toBe('logged')
+        ->and(TelemetryActivity::run(null, fn () => 'system'))->toBe('system')
+        ->and($logger->suppressed)->toBe(3);
+});
+
+test('telemetry writes still run when the activity logger cannot be resolved', function () {
+    RetentionPolicy::$settingsResolver = fn () => [];
+    app()->forgetInstance(ActivityLogger::class);
+
+    expect(TelemetryActivity::run('company-1', fn () => 'unlogged'))->toBe('unlogged');
+});

package/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php

@@ -0,0 +1,109 @@
+<?php
+
+if (!function_exists('Fleetbase\Models\session')) {
+    eval('namespace Fleetbase\Models; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } public function missing($k) { return \session($k) === null; } }; } return \session($key, $default); }');
+}
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Support\OrderTracker;
+use Fleetbase\FleetOps\Tracking\TrackingIntelligenceService;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers company tracking settings resolution for TrackingOptions: the
+ * order's company is used when there is no company session (queued jobs,
+ * console commands), and the session company remains the fallback.
+ */
+function fleetopsTrackingOptionsBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+
+    $connection->getSchemaBuilder()->create('settings', function ($blueprint) {
+        $blueprint->increments('id');
+        $blueprint->string('key')->nullable();
+        $blueprint->text('value')->nullable();
+        $blueprint->timestamps();
+    });
+
+    $connection->table('settings')->insert([
+        ['key' => 'company.company-a.tracking', 'value' => json_encode(['provider' => 'osrm', 'cache_ttl_seconds' => 15])],
+        ['key' => 'company.company-b.tracking', 'value' => json_encode(['provider' => 'calculated', 'cache_ttl_seconds' => 45])],
+    ]);
+
+    session(['company' => null]);
+
+    return $connection;
+}
+
+test('tracking options read the given company settings regardless of session', function (?string $sessionCompany) {
+    fleetopsTrackingOptionsBoot();
+    session(['company' => $sessionCompany]);
+
+    $options = TrackingOptions::fromArray([], 'company-a');
+
+    expect($options->provider)->toBe('osrm')
+        ->and($options->cacheTtlSeconds)->toBe(15);
+
+    // Explicit options still win over company settings
+    expect(TrackingOptions::fromArray(['provider' => 'google'], 'company-a')->provider)->toBe('google');
+})->with([null, 'company-b']);
+
+test('tracking options fall back to the session company when no company is given', function () {
+    fleetopsTrackingOptionsBoot();
+    session(['company' => 'company-b']);
+
+    $options = TrackingOptions::fromArray([]);
+    session(['company' => null]);
+
+    expect($options->provider)->toBe('calculated')
+        ->and($options->cacheTtlSeconds)->toBe(45);
+});
+
+test('order tracker builds options from the order company', function () {
+    fleetopsTrackingOptionsBoot();
+
+    $service = new class extends TrackingIntelligenceService {
+        public ?TrackingOptions $received = null;
+
+        public function __construct()
+        {
+        }
+
+        public function track(Order $order, array|TrackingOptions $options = []): array
+        {
+            $this->received = $options;
+
+            return [];
+        }
+    };
+    app()->instance(TrackingIntelligenceService::class, $service);
+
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-tracking-options', 'company_uuid' => 'company-a'], true);
+
+    (new OrderTracker($order))->toArray();
+    app()->forgetInstance(TrackingIntelligenceService::class);
+
+    expect($service->received)->toBeInstanceOf(TrackingOptions::class)
+        ->and($service->received->provider)->toBe('osrm');
+});
+
+test('tracking remains available with configured defaults when the settings database is unavailable', function () {
+    $connection = fleetopsTrackingOptionsBoot();
+    $connection->getSchemaBuilder()->drop('settings');
+    $original = config('fleetops.tracking', []);
+    try {
+        config(['fleetops.tracking' => ['provider' => 'calculated', 'cache_ttl_seconds' => 17]]);
+        $options = TrackingOptions::fromArray([], 'uncached-unavailable-company');
+        expect($options->provider)->toBe('calculated')->and($options->cacheTtlSeconds)->toBe(17);
+        expect(TrackingOptions::fromArray(['provider' => 'osrm'], 'uncached-unavailable-company')->provider)->toBe('osrm');
+    } finally {
+        config(['fleetops.tracking' => $original]);
+    }
+});

package/translations/en-us.yaml

@@ -114,6 +114,7 @@ menu:
     maintenances: Maintenances
     orchestrator: Orchestrator
     orchestrator-settings: Orchestrator Settings
+    telematics-settings: Telematics
 
 trailer:
     navigation-description: Manage towed assets, towing connections, equipment, and telematics.
@@ -2723,6 +2724,53 @@ route-list:
     more-waypoints: more waypoints
 
 settings:
+    telematics:
+        telematics-settings: Telematics Settings
+        intro: Choose how long your organization keeps device events and position history within the limits set by your system administrator.
+        use-system-default: Use system default
+        history-policy-maximum: "Your administrator allows up to {days} days of history. Unlimited retention is not available."
+        history-policy-unlimited: Your administrator allows unlimited history. Set the retention period to 0 to keep history forever.
+        device-events: Device Events Retention
+        event-retention-days: Keep device events for (days)
+        event-retention-days-help: Events older than this are permanently deleted. Applies to telemetry updates and provider alerts alike.
+        event-compact-after-days: Strip raw payloads after (days)
+        event-compact-after-days-help: Events older than this keep their type, severity, location and normalized data, but the raw provider payload is removed. Raw payloads are the bulk of each event's size.
+        compaction-warning: Raw payloads are only stripped from events that are kept. Set this lower than the event retention or set it to 0 to disable compaction.
+        positions: Position History Retention
+        position-retention-days: Keep positions for (days)
+        position-retention-days-help: Vehicle and trailer position history older than this is permanently deleted. Route replay and history views only reach back this far.
+        inbox: Delivery Inbox & Sync Run Retention
+        processed-retention-hours: Keep processed deliveries for (hours)
+        processed-retention-hours-help: Raw provider batches are stored encrypted until processed and kept briefly for replay and diagnostics. Each batch can be close to a megabyte.
+        quarantine-retention-days: Keep quarantined deliveries for (days)
+        quarantine-retention-days-help: Batches that could not be processed stay available for inspection and replay for this long.
+        sync-run-retention-days: Keep sync run diagnostics for (days)
+        sync-run-retention-days-help: One sync run row is recorded per connection per poll. In-flight runs are never removed.
+        activity-logging: Telemetry Activity Logging
+        log-telemetry-activity: Log telemetry activity
+        log-telemetry-activity-help: Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.
+        storage-usage: System Telematics Storage Usage
+        table: Table
+        rows: Rows
+        estimated-rows: "{count} (estimated)"
+        estimated-size: Estimated size
+        oldest: Oldest row
+        not-available: n/a
+        raw-payload-rows: "{count} rows still carry raw payloads, {compactable} eligible for compaction now"
+        refresh: Refresh
+        run-cleanup: Run system cleanup
+        run-cleanup-confirm: This queues telematics cleanup across all organizations, using the saved system policy and each organization's effective history preferences. Expired records are permanently deleted and cannot be recovered. Continue?
+        cleanup-queued: Telematics cleanup has been queued across all organizations. Usage refreshes shortly; cleanup may still be running.
+        cleanup-unavailable: System-wide telematics cleanup could not be confirmed. Please try again.
+        usage-unavailable: Storage usage could not be loaded. Select Refresh to try again.
+        space-reclaim-note: Usage includes all telematics data across the system. Row counts marked as estimated use database statistics. Sizes include table data and indexes. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
+        settings-saved: Telematics settings saved.
+        settings-unavailable: Telematics settings could not be loaded. Please try again.
+        tables:
+            device_events: Device events
+            positions: Positions
+            telematic_deliveries: Delivery inbox
+            telematic_sync_runs: Sync runs
     avatar-management: Avatar Management
     custom-fields: Custom Fields
     notifications: