@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/server/migrations/2026_09_10_000002_add_token_to_inspection_links.php

@@ -0,0 +1,39 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Keep the inspection link itself, not only its fingerprint.
+ *
+ * A link was stored as `token_hash` alone, which is right for looking one up
+ * and wrong for everything an operator needs afterwards. Once the modal that
+ * minted it closed, nobody could see the link again: not to send it a second
+ * time, not to check which vehicle it was for, not to tell an expired link
+ * from a live one. The only recourse was to mint another.
+ *
+ * So the token is kept alongside its hash, encrypted at rest with the
+ * application key. It is a capability URL — it grants filling in one published
+ * form, once, for one vehicle, until it expires — not a credential, and being
+ * able to re-read one is how every share link behaves.
+ *
+ * `token_hash` stays exactly as it is: it is the unique index a public request
+ * is resolved through, and nothing about the lookup path changes. Links minted
+ * before this migration keep a null token and are shown without their URL.
+ */
+return new class extends Migration {
+    public function up()
+    {
+        Schema::table('inspection_links', function (Blueprint $table) {
+            $table->text('token')->nullable()->after('token_hash');
+        });
+    }
+
+    public function down()
+    {
+        Schema::table('inspection_links', function (Blueprint $table) {
+            $table->dropColumn('token');
+        });
+    }
+};

package/server/migrations/2026_09_11_000001_add_assignee_and_pin_to_inspection_links.php

@@ -0,0 +1,39 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Let an inspection link be meant for anyone, and protect it with a PIN.
+ *
+ * A link could name a driver, and nobody else. Inspections are completed by
+ * anyone in the organisation, so a link can now be assigned to any user;
+ * the driver and vehicle stay as optional details of the inspection itself.
+ *
+ * A link now carries a PIN: a second thing to know alongside the link, which
+ * can be sent to the assignee by email or SMS, or read out. It is kept hashed
+ * for checking and encrypted so the console can show it again, and wrong
+ * guesses are counted so the link locks after a few.
+ */
+return new class extends Migration {
+    public function up()
+    {
+        Schema::table('inspection_links', function (Blueprint $table) {
+            $table->foreignUuid('assignee_uuid')->nullable()->after('vehicle_uuid')->constrained('users', 'uuid')->nullOnDelete();
+            $table->string('pin_hash')->nullable()->after('token');
+            $table->text('pin')->nullable()->after('pin_hash');
+            $table->unsignedSmallInteger('pin_attempts')->default(0)->after('pin');
+            $table->string('pin_sent_via', 20)->nullable()->after('pin_attempts');
+            $table->timestamp('pin_sent_at')->nullable()->after('pin_sent_via');
+        });
+    }
+
+    public function down()
+    {
+        Schema::table('inspection_links', function (Blueprint $table) {
+            $table->dropConstrainedForeignId('assignee_uuid');
+            $table->dropColumn(['pin_hash', 'pin', 'pin_attempts', 'pin_sent_via', 'pin_sent_at']);
+        });
+    }
+};

package/server/migrations/2026_09_15_000001_create_telematic_telemetry_tables.php

@@ -0,0 +1,62 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('devices', fn (Blueprint $table) => $table->index(['company_uuid', 'telematic_uuid', 'device_id'], 'devices_telematic_lookup'));
+        Schema::create('telematic_sync_runs', function (Blueprint $table) {
+            $table->uuid('uuid')->primary();
+            $table->uuid('telematic_uuid')->index();
+            $table->string('status')->default('fetching')->index();
+            $table->unsignedInteger('pages')->default(0);
+            $table->unsignedInteger('units')->default(0);
+            $table->unsignedInteger('applied')->default(0);
+            $table->unsignedInteger('failed')->default(0);
+            $table->text('error')->nullable();
+            $table->timestamps();
+        });
+        Schema::create('telematic_deliveries', function (Blueprint $table) {
+            $table->uuid('uuid')->primary();
+            $table->uuid('telematic_uuid')->index();
+            $table->uuid('run_uuid')->nullable()->index();
+            $table->string('source', 16);
+            $table->string('status', 24)->default('pending');
+            $table->char('payload_hash', 64);
+            $table->longText('payload');
+            $table->longText('retry_payload')->nullable();
+            $table->unsignedInteger('invalid_count')->default(0);
+            $table->unsignedInteger('attempts')->default(0);
+            $table->unsignedInteger('queue_delay_seconds')->nullable();
+            $table->unsignedInteger('source_delay_seconds')->nullable();
+            $table->unsignedInteger('applied')->default(0);
+            $table->unsignedInteger('failed')->default(0);
+            $table->text('error')->nullable();
+            $table->timestamp('received_at');
+            $table->timestamp('available_at')->nullable();
+            $table->timestamp('processed_at')->nullable();
+            $table->timestamps();
+            $table->index(['status', 'available_at']);
+            $table->index(['status', 'updated_at']);
+            $table->index(['telematic_uuid', 'status']);
+            $table->index(['telematic_uuid', 'received_at']);
+            $table->index(['telematic_uuid', 'source', 'received_at']);
+        });
+        Schema::create('telematic_webhook_credentials', function (Blueprint $table) {
+            $table->uuid('telematic_uuid')->primary();
+            $table->text('token');
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('devices', fn (Blueprint $table) => $table->dropIndex('devices_telematic_lookup'));
+        Schema::dropIfExists('telematic_webhook_credentials');
+        Schema::dropIfExists('telematic_deliveries');
+        Schema::dropIfExists('telematic_sync_runs');
+    }
+};

package/server/migrations/2026_09_15_000002_scope_fuel_transactions_to_connection.php

@@ -0,0 +1,25 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+            $table->unique(['company_uuid', 'fuel_provider_connection_uuid', 'provider', 'active_provider_transaction_id'], 'fuel_provider_txn_connection_unique');
+            $table->dropUnique('fuel_provider_txn_company_provider_unique');
+        });
+    }
+
+    public function down(): void
+    {
+        // Restore the tighter constraint first; rollback must fail rather than
+        // silently discard distinct sandbox and production transactions.
+        Schema::table('fuel_provider_transactions', function (Blueprint $table) {
+            $table->unique(['company_uuid', 'provider', 'active_provider_transaction_id'], 'fuel_provider_txn_company_provider_unique');
+            $table->dropUnique('fuel_provider_txn_connection_unique');
+        });
+    }
+};

package/server/migrations/2026_09_16_000001_add_public_id_to_alerts_table.php

@@ -0,0 +1,45 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Give the core `alerts` table the `public_id` its model writes.
+     *
+     * `Fleetbase\Models\Alert` uses `HasPublicId`, whose creating hook checks
+     * `alerts.public_id` for a collision before assigning one, but the core
+     * migration never created the column. Every alert insert therefore fails
+     * with "Unknown column 'public_id'": Radar's acknowledge and snooze (which
+     * create a state row on first use), and the low-stock, sensor and device
+     * event alerts FleetOps already raises.
+     *
+     * Guarded, so it is a no-op wherever core-api adds the column itself.
+     */
+    public function up(): void
+    {
+        if (!Schema::hasTable('alerts') || Schema::hasColumn('alerts', 'public_id')) {
+            return;
+        }
+
+        Schema::table('alerts', function (Blueprint $table) {
+            $table->string('public_id', 191)->nullable()->unique()->after('uuid');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        if (!Schema::hasTable('alerts') || !Schema::hasColumn('alerts', 'public_id')) {
+            return;
+        }
+
+        Schema::table('alerts', function (Blueprint $table) {
+            $table->dropUnique(['public_id']);
+            $table->dropColumn('public_id');
+        });
+    }
+};

package/server/resources/views/mail/inspection-link-pin.blade.php

@@ -0,0 +1,34 @@
+@php
+    // Strings are built here, not inline: Blade only reads `@` as a directive
+    // when it does not follow a word character, so `inspection@if(...)` would
+    // stay literal text while its `@endif` compiled and broke the view.
+    $formName    = $form?->name ?: 'inspection';
+    $vehicleName = $vehicle ? ($vehicle->display_name ?? $vehicle->name) : null;
+    $forVehicle  = $vehicleName ? ' for ' . $vehicleName : '';
+    $senderLine  = $sender?->name ? $sender->name . ' has asked you to complete this inspection.' : 'You have been asked to complete this inspection.';
+@endphp
+<x-mail-layout>
+<h2 style="font-size: 18px; font-weight: 600;">Complete the {{ $formName }} inspection</h2>
+
+@if($recipient && $recipient->name)
+<p>Hi {{ $recipient->name }},</p>
+@endif
+
+<p>{{ $senderLine }} It is the <strong>{{ $formName }}</strong> inspection{{ $forVehicle }}.</p>
+
+@if($url)
+<p style="margin: 24px 0;"><a href="{{ $url }}" style="display: inline-block; background-color: #2563eb; color: #ffffff; text-decoration: none; font-weight: 600; padding: 10px 18px; border-radius: 6px;">Open the inspection</a></p>
+@endif
+
+<p>When it asks, enter this PIN:</p>
+
+<p style="font-size: 28px; font-weight: 700; letter-spacing: 6px; font-family: ui-monospace, Menlo, Consolas, monospace; margin: 16px 0 20px;">{{ $pin }}</p>
+
+<p>The link locks after {{ $maxAttempts }} incorrect PINs.@if($expiresAt) It expires on {{ $expiresAt->format('j M Y, H:i T') }}.@endif</p>
+
+@if($url)
+<p style="color: #6b7280; font-size: 13px;">If the button does not work, copy this address into your browser:<br><span style="word-break: break-all;">{{ $url }}</span></p>
+@endif
+
+<p style="color: #6b7280; font-size: 13px;">If you were not expecting this, you can ignore it. Do not forward this email: anyone with it can open the inspection.</p>
+</x-mail-layout>

package/server/src/Auth/Schemas/FleetOps.php

@@ -61,6 +61,10 @@ class FleetOps
             'name'    => 'vehicle',
             'actions' => ['assign-driver-for', 'export', 'import'],
         ],
+        [
+            'name'    => 'trailer',
+            'actions' => ['export', 'import', 'attach-vehicle-for', 'detach-vehicle-for', 'attach-device-for', 'detach-device-for', 'attach-equipment-for', 'detach-equipment-for'],
+        ],
         [
             'name'    => 'fleet',
             'actions' => ['assign-driver-for', 'assign-vehicle-for', 'remove-driver-for', 'remove-vehicle-for', 'export', 'import'],
@@ -121,6 +125,14 @@ class FleetOps
             'name'    => 'work-order',
             'actions' => ['export', 'import'],
         ],
+        [
+            'name'    => 'inspection-form',
+            'actions' => ['publish', 'archive'],
+        ],
+        [
+            'name'    => 'inspection-submission',
+            'actions' => ['submit', 'create-issue', 'create-work-order', 'resolve'],
+        ],
         [
             'name'    => 'equipment',
             'actions' => ['export', 'import'],
@@ -217,6 +229,7 @@ class FleetOps
                 '* fleet',
                 '* driver',
                 '* vehicle',
+                '* trailer',
             ],
         ],
         [
@@ -292,8 +305,11 @@ class FleetOps
                 'see extension',
                 '* maintenance',
                 '* work-order',
+                '* inspection-form',
+                '* inspection-submission',
                 '* equipment',
                 '* part',
+                '* trailer',
                 'see vehicle',
                 'list vehicle',
                 'view vehicle',
@@ -316,8 +332,11 @@ class FleetOps
                 '* place',
                 '* maintenance',
                 '* work-order',
+                '* inspection-form',
+                '* inspection-submission',
                 '* equipment',
                 '* part',
+                '* trailer',
             ],
         ],
         [

package/server/src/Console/Commands/DrainTelematicInbox.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Fleetbase\FleetOps\Contracts\TelemetryProviderInterface;
+use Fleetbase\FleetOps\Jobs\ProcessTelematicDelivery;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Queue;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+class DrainTelematicInbox extends Command
+{
+    protected $signature   = 'fleetops:drain-telematic-inbox';
+    protected $description = 'Recover pending telematic deliveries and expire retained payloads.';
+
+    public function handle(): int
+    {
+        $registry         = app(TelematicProviderRegistry::class);
+        $webhookProviders = [];
+        foreach ($registry->all() as $descriptor) {
+            if (!data_get($descriptor->metadata, 'telemetry.durable_ingestion', false)) {
+                continue;
+            }
+            try {
+                $provider = $registry->resolve($descriptor->key);
+                if ($provider instanceof TelemetryProviderInterface
+                    && (Configuration::options($provider)['webhooks_enabled'] ?? false)) {
+                    $webhookProviders[] = $descriptor->key;
+                }
+            } catch (\Throwable $e) {
+                Log::warning('Telemetry provider configuration unavailable during inbox recovery.', ['provider' => $descriptor->key, 'exception' => class_basename($e)]);
+            }
+        }
+        // Exclude paused webhook sources before applying the dispatch limit, so
+        // one paused integration cannot starve polling or other providers.
+        $pending = DB::table('telematic_deliveries')->leftJoin('telematics', 'telematics.uuid', '=', 'telematic_deliveries.telematic_uuid')
+            ->whereIn('telematic_deliveries.status', ['pending', 'retry', 'processing'])
+            ->where('available_at', '<=', now())
+            ->where(function ($query) use ($webhookProviders) {
+                $query->where('source', '!=', 'webhook')->orWhereIn('telematics.provider', $webhookProviders)->orWhereNull('telematics.uuid');
+            });
+        $optionsByConnection = [];
+        foreach ($pending->orderBy('available_at')->limit(1000)->get(['telematic_deliveries.uuid', 'telematic_deliveries.telematic_uuid']) as $row) {
+            try {
+                if (!isset($optionsByConnection[$row->telematic_uuid])) {
+                    $connection                                = Telematic::withoutGlobalScopes()->where('uuid', $row->telematic_uuid)->first();
+                    $optionsByConnection[$row->telematic_uuid] = $connection ? Configuration::forConnection($connection) : [];
+                }
+            } catch (\InvalidArgumentException) {
+                DB::table('telematic_deliveries')->where('uuid', $row->uuid)->update(['status' => 'quarantined', 'error' => 'Provider configuration unavailable; inspect and replay.', 'updated_at' => now()]);
+                continue;
+            }
+            try {
+                Queue::dispatch((new ProcessTelematicDelivery($row->uuid))->onQueue($optionsByConnection[$row->telematic_uuid]['ingestion_queue'] ?? 'default'));
+            } catch (\Throwable) {
+                // A broker outage must not prevent retention cleanup; retry the next minute.
+                break;
+            }
+        }
+        // Bound deletes so retention cleanup cannot monopolize the inbox table.
+        foreach (['processed' => now()->subHours(config('telematics.telemetry.processed_retention_hours', 24)), 'quarantined' => now()->subDays(config('telematics.telemetry.quarantine_retention_days', 7))] as $status => $cutoff) {
+            for ($batch = 0; $batch < 20; $batch++) {
+                $ids = DB::table('telematic_deliveries')->where('status', $status)->where('updated_at', '<', $cutoff)->limit(1000)->pluck('uuid');
+                if ($ids->isEmpty()) {
+                    break;
+                }
+                DB::table('telematic_deliveries')->whereIn('uuid', $ids)->delete();
+            }
+        }
+        DB::table('telematic_sync_runs')->where('status', 'fetching')->where('updated_at', '<', now()->subMinutes(5))
+            ->update(['status' => 'incomplete', 'error' => 'Worker interrupted; next scheduled sweep will recover.']);
+        DB::table('telematic_sync_runs')->where('status', 'ingesting')->get(['uuid'])->each(fn ($run) => Inbox::finishRun($run->uuid));
+        DB::table('telematic_sync_runs')->where('updated_at', '<', now()->subDays(7))->delete();
+
+        return self::SUCCESS;
+    }
+}

package/server/src/Console/Commands/ProcessMaintenanceTriggers.php

@@ -93,7 +93,10 @@ class ProcessMaintenanceTriggers extends Command
                     'company_uuid'    => $schedule->company_uuid,
                     'schedule_uuid'   => $schedule->uuid,
                     'subject'         => $schedule->name,
-                    'category'        => 'preventive_maintenance',
+                    // An inspection schedule produces an inspection request,
+                    // not preventive maintenance, so the work order reads as
+                    // what it is.
+                    'category'        => $schedule->type === 'inspection' ? 'inspection_request' : 'preventive_maintenance',
                     'code'            => $woCode,
                     'status'          => 'open',
                     'priority'        => $schedule->default_priority ?? 'normal',

package/server/src/Console/Commands/SyncTelematics.php

@@ -40,7 +40,37 @@ class SyncTelematics extends Command
                 return self::SUCCESS;
             }
 
-            $query = Telematic::withoutGlobalScopes()
+            $telemetryProviders = [];
+            foreach ($providerKeys as $key) {
+                if (!data_get($registry->findByKey($key)?->metadata, 'telemetry.durable_ingestion', false)) {
+                    continue;
+                }
+                $provider = $registry->resolve($key);
+                if (!$provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface) {
+                    continue;
+                }
+                $options = \Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration::options($provider);
+                if (!($options['polling_enabled'] ?? false)) {
+                    continue;
+                }
+                $telemetryProviders[] = $key;
+                Telematic::withoutGlobalScopes()->where('provider', $key)->whereIn('status', ['active', 'connected', 'error', 'synchronizing'])
+                    ->whereNotNull('company_uuid')->orderBy('id')->chunkById(100, function ($connections) use ($options) {
+                        foreach ($connections as $connection) {
+                            if (\Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox::enabled($connection)) {
+                                try {
+                                    \Fleetbase\FleetOps\Support\Telematics\Telemetry\Queue::dispatch((new \Fleetbase\FleetOps\Jobs\PollTelematicTelemetry($connection->uuid))
+                                        ->onQueue($options['poll_queue'] ?? 'default')
+                                        ->delay(now()->addSeconds(abs(crc32($connection->uuid)) % 10)));
+                                } catch (\Throwable) {
+                                    \Illuminate\Support\Facades\Log::warning('Telemetry polling dispatch failed; next tick will retry.', ['telematic_uuid' => $connection->uuid]);
+                                }
+                            }
+                        }
+                    });
+            }
+            $providerKeys = array_values(array_diff($providerKeys, $telemetryProviders));
+            $query        = Telematic::withoutGlobalScopes()
                 ->whereIn('provider', $providerKeys)
                 ->whereIn('status', ['active', 'connected'])
                 ->whereNotNull('company_uuid');
@@ -80,7 +110,7 @@ class SyncTelematics extends Command
                     return false;
                 }
 
-                return !$excludeWebhookProviders || !$descriptor->supportsWebhooks;
+                return data_get($descriptor->metadata, 'telemetry.reconciliation', false) || !$excludeWebhookProviders || !$descriptor->supportsWebhooks;
             })
             ->keys()
             ->values()

package/server/src/Contracts/TelemetryProviderInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Fleetbase\FleetOps\Contracts;
+
+/** Optional extension: existing integrations need not change their provider contract. */
+interface TelemetryProviderInterface extends TelematicProviderInterface
+{
+    /** Runtime switches and protocol-specific limits; must not authenticate. */
+    public function telemetryOptions(): array;
+
+    /** Split a provider delivery into raw position samples; reject unsupported envelopes. */
+    public function telemetryUnits(array $payload): array;
+
+    /**
+     * Normalize one raw sample without network access using existing device/event/sensor fields.
+     *
+     * device.device_id and event.device_id identify the same unit within this connection.
+     * event includes event_type, occurred_at (device time), last_seen_at (contact time),
+     * location {lat, lng}, and optional meta.telemetry.provider_at. Missing/invalid
+     * timestamps or coordinates must remain null; never replace them with receipt time.
+     * Each sensor includes recorded_at in UTC and its existing normalized identity fields.
+     * Preserve omissions in partial messages, rather than synthesizing metadata defaults.
+     *
+     * @return array{device: array, event: array, sensors?: array}
+     */
+    public function normalizeTelemetrySnapshot(array $payload): array;
+}

package/server/src/Events/DeviceTelemetryUpdated.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\Device;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+
+class DeviceTelemetryUpdated implements ShouldBroadcast
+{
+    public bool $afterCommit = true;
+    public string $companyUuid;
+    public string $deviceUuid;
+    public array $data;
+
+    public function __construct(Device $device)
+    {
+        $this->companyUuid = $device->company_uuid;
+        $this->deviceUuid  = $device->uuid;
+        $this->data        = ['id' => $device->uuid, 'device_id' => $device->public_id, 'telemetry' => data_get($device->meta, 'telemetry', [])];
+    }
+
+    public function broadcastOn(): array
+    {
+        return [new Channel('company.' . $this->companyUuid), new Channel('device.' . $this->deviceUuid)];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'device.telemetry_updated';
+    }
+
+    public function broadcastWith(): array
+    {
+        return ['event' => $this->broadcastAs(), 'data' => $this->data];
+    }
+}

package/server/src/Events/TrailerLocationChanged.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Fleetbase\FleetOps\Events;
+
+use Fleetbase\FleetOps\Models\Trailer;
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class TrailerLocationChanged implements ShouldBroadcast
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    public string $eventId;
+    public string $sentAt;
+    public string $companyUuid;
+    public string $trailerUuid;
+    public string $trailerId;
+    public mixed $location;
+    public mixed $altitude;
+    public mixed $heading;
+    public mixed $speed;
+    public array $additionalData;
+
+    public function __construct(Trailer $trailer, array $additionalData = [])
+    {
+        $this->eventId        = uniqid('event_');
+        $this->sentAt         = now()->toDateTimeString();
+        $this->companyUuid    = $trailer->company_uuid;
+        $this->trailerUuid    = $trailer->uuid;
+        $this->trailerId      = $trailer->public_id;
+        $this->location       = $trailer->location;
+        $this->altitude       = $trailer->altitude;
+        $this->heading        = $trailer->heading;
+        $this->speed          = $trailer->speed;
+        $this->additionalData = $additionalData;
+    }
+
+    public function broadcastOn(): array
+    {
+        return [new Channel('company.' . $this->companyUuid), new Channel('trailer.' . $this->trailerId), new Channel('trailer.' . $this->trailerUuid)];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'trailer.location_changed';
+    }
+
+    public function broadcastWith(): array
+    {
+        return [
+            'id'          => $this->eventId,
+            'api_version' => config('api.version'),
+            'event'       => $this->broadcastAs(),
+            'created_at'  => $this->sentAt,
+            'data'        => [
+                'id'             => $this->trailerId,
+                'location'       => $this->location,
+                'altitude'       => $this->altitude,
+                'heading'        => $this->heading,
+                'speed'          => $this->speed,
+                'additionalData' => $this->additionalData,
+            ],
+        ];
+    }
+}

package/server/src/Events/VehicleLocationChanged.php

@@ -22,6 +22,8 @@ class VehicleLocationChanged implements ShouldBroadcast
      * @var string
      */
     public $eventId;
+    public ?string $companyUuid;
+    public ?string $apiCredentialUuid;
 
     /**
      * The datetime instance the broadcast ws triggered.
@@ -100,6 +102,8 @@ class VehicleLocationChanged implements ShouldBroadcast
      */
     public function __construct(Vehicle $vehicle, array $additionalData = [])
     {
+        $this->companyUuid        = $vehicle->company_uuid;
+        $this->apiCredentialUuid  = session('api_credential');
         $this->eventId            = uniqid('event_');
         $this->sentAt             = Carbon::now()->toDateTimeString();
         $this->additionalData     = $additionalData;
@@ -120,12 +124,12 @@ class VehicleLocationChanged implements ShouldBroadcast
      */
     public function broadcastOn()
     {
-        return [
-            new Channel('company.' . session('company')),
-            new Channel('api.' . session('api_credential')),
+        return array_values(array_filter([
+            $this->companyUuid ? new Channel('company.' . $this->companyUuid) : null,
+            $this->apiCredentialUuid ? new Channel('api.' . $this->apiCredentialUuid) : null,
             new Channel('vehicle.' . $this->vehicleId),
             new Channel('vehicle.' . $this->vehicleUuid),
-        ];
+        ]));
     }
 
     /**

package/server/src/Exceptions/DeviceAlreadyAttachedException.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Fleetbase\FleetOps\Exceptions;
+
+/**
+ * Thrown when a device that is already installed on one asset is attached to another
+ * without being detached first. Attaching silently used to re-home the device, which
+ * let an operator "steal" a tracker from a vehicle with no feedback.
+ */
+class DeviceAlreadyAttachedException extends \DomainException
+{
+    public static function for(?string $attachedToName): self
+    {
+        $target = $attachedToName ? ' to ' . $attachedToName : ' to another asset';
+
+        return new self('Device is already attached' . $target . '. Detach it before attaching it elsewhere.');
+    }
+}