refactor: store invite role_uuid in meta JSON via HasMetaAttributes

Instead of a dedicated role_uuid column, use a generic meta JSON column
on the invites table. This keeps the schema clean and extensible — any
future invite-time data (e.g. custom permissions, onboarding flags) can
be stored in meta without additional migrations.

Changes:
- Migration: adds nullable json 'meta' column instead of char 'role_uuid'
- Invite model: uses HasMetaAttributes trait; 'meta' added to fillable
  and cast via Json::class
- UserController: Invite::create() now passes meta => ['role_uuid' => ...]
  (array_filter drops it when no role is selected); acceptCompanyInvite()
  reads the role via $invite->getMeta('role_uuid', 'Administrator')

Author: Ronald A Richardson

migrations/2026_04_21_000001_add_role_uuid_to_invites_table.php

@@ -8,16 +8,17 @@
     /**
      * Run the migrations.
      *
-     * Adds a nullable `role_uuid` column to the `invites` table so that the
-     * intended role for an invited user can be stored on the invite record and
-     * applied when the user accepts the invitation.
+     * Adds a nullable JSON `meta` column to the `invites` table so that
+     * arbitrary key-value data (e.g. role_uuid for user invitations) can be
+     * stored on an invite record without requiring dedicated columns for each
+     * use-case. The HasMetaAttributes trait is used to read and write values.
      *
      * @return void
      */
     public function up()
     {
         Schema::table('invites', function (Blueprint $table) {
-            $table->char('role_uuid', 36)->nullable()->after('reason');
+            $table->json('meta')->nullable()->after('reason');
         });
     }
 
@@ -29,7 +30,7 @@ public function up()
     public function down()
     {
         Schema::table('invites', function (Blueprint $table) {
-            $table->dropColumn('role_uuid');
+            $table->dropColumn('meta');
         });
     }
 };

src/Http/Controllers/Internal/v1/UserController.php

@@ -346,7 +346,7 @@ public function inviteUser(InviteUserRequest $request)
             'protocol'        => 'email',
             'recipients'      => [$user->email],
             'reason'          => 'join_company',
-            'role_uuid'       => $request->input('user.role_uuid') ?? $request->input('user.role'),
+            'meta'            => array_filter(['role_uuid' => $request->input('user.role_uuid') ?? $request->input('user.role')]),
         ]);
 
         $user->notify(new UserInvited($invitation));
@@ -389,7 +389,7 @@ private function inviteExistingUser(User $user, Request $request): \Illuminate\H
             'protocol'        => 'email',
             'recipients'      => [$user->email],
             'reason'          => 'join_company',
-            'role_uuid'       => $request->input('user.role_uuid') ?? $request->input('user.role'),
+            'meta'            => array_filter(['role_uuid' => $request->input('user.role_uuid') ?? $request->input('user.role')]),
         ]);
 
         $user->notify(new UserInvited($invitation));
@@ -470,18 +470,19 @@ public function acceptCompanyInvite(AcceptCompanyInvite $request)
 
         if (!$alreadyMember) {
             // Use Company::addUser() so that role assignment is handled in
-            // one place. The role stored on the invite takes precedence;
+            // one place. The role stored in the invite meta takes precedence;
             // if none was set the default 'Administrator' role is used.
-            $roleIdentifier = $invite->role_uuid ?? 'Administrator';
+            $roleIdentifier = $invite->getMeta('role_uuid', 'Administrator');
             $companyUser    = $company->addUser($user, $roleIdentifier);
             $user->setRelation('companyUser', $companyUser);
         } else {
             // User is already a member — ensure the companyUser relation is
             // loaded so that role assignment below can still be applied if
             // the invite carries a role (e.g. re-sent invite with a new role).
             $user->loadCompanyUser();
-            if ($user->companyUser && $invite->role_uuid) {
-                $user->companyUser->assignSingleRole($invite->role_uuid);
+            $roleUuid = $invite->getMeta('role_uuid');
+            if ($user->companyUser && $roleUuid) {
+                $user->companyUser->assignSingleRole($roleUuid);
             }
         }
 

src/Models/Invite.php

@@ -5,6 +5,7 @@
 use Fleetbase\Casts\Json;
 use Fleetbase\Traits\Expirable;
 use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasMetaAttributes;
 use Fleetbase\Traits\HasPublicId;
 use Fleetbase\Traits\HasUuid;
 use Illuminate\Support\Carbon;
@@ -16,6 +17,7 @@ class Invite extends Model
     use HasPublicId;
     use Expirable;
     use HasApiModelBehavior;
+    use HasMetaAttributes;
 
     /**
      * The database table used by the model.
@@ -81,7 +83,7 @@ public function getConnectionName(): string
         'protocol',
         'recipients',
         'reason',
-        'role_uuid',
+        'meta',
     ];
 
     /**
@@ -105,6 +107,7 @@ public function getConnectionName(): string
      */
     protected $casts = [
         'recipients' => Json::class,
+        'meta'       => Json::class,
     ];
 
     /**