feat(auth): add role-based permissions

- Added Role model with json serialization
- Added Permission model with serialization
- Replaced isAdmin with role in User model

Author: fulleni

lib/ht_shared.dart

@@ -3,3 +3,5 @@ library;
 
 export 'src/exceptions/exceptions.dart';
 export 'src/models/models.dart';
+export 'src/models/permission.dart';
+export 'src/models/role.dart';

lib/src/models/permission.dart

@@ -0,0 +1,31 @@
+import 'package:equatable/equatable.dart';
+import 'package:json_annotation/json_annotation.dart';
+
+part 'permission.g.dart';
+
+/// {@template permission}
+/// Defines the available permissions in the system.
+///
+/// Permissions follow the format `resource.action`.
+/// {@endtemplate}
+@JsonSerializable()
+class Permission extends Equatable {
+  /// {@macro permission}
+  const Permission({required this.name});
+
+  /// Creates a Permission from JSON data.
+  factory Permission.fromJson(Map<String, dynamic> json) =>
+      _$PermissionFromJson(json);
+
+  /// The name of the permission (e.g., 'headline.read').
+  final String name;
+
+  /// Converts this Permission instance to JSON data.
+  Map<String, dynamic> toJson() => _$PermissionToJson(this);
+
+  @override
+  List<Object> get props => [name];
+
+  @override
+  String toString() => 'Permission(name: $name)';
+}

lib/src/models/permission.g.dart

@@ -0,0 +1,28 @@
+import 'package:equatable/equatable.dart';
+import 'package:json_annotation/json_annotation.dart';
+
+part 'role.g.dart';
+
+/// {@template role}
+/// Defines the available user roles in the system.
+/// {@endtemplate}
+@JsonSerializable()
+class Role extends Equatable {
+  /// {@macro role}
+  const Role({required this.name});
+
+  /// Creates a Role from JSON data.
+  factory Role.fromJson(Map<String, dynamic> json) => _$RoleFromJson(json);
+
+  /// The name of the role (e.g., 'admin', 'standard_user').
+  final String name;
+
+  /// Converts this Role instance to JSON data.
+  Map<String, dynamic> toJson() => _$RoleToJson(this);
+
+  @override
+  List<Object> get props => [name];
+
+  @override
+  String toString() => 'Role(name: $name)';
+}

lib/src/models/role.dart

@@ -13,13 +13,13 @@ part 'user.g.dart';
 class User extends Equatable {
   /// Creates a new [User] instance.
   ///
-  /// Requires a unique [id], an [isAnonymous] flag, and an [isAdmin] flag.
-  /// The [email] is optional and typically present only for non-anonymous
-  /// users who have verified their email address.
+/// Requires a unique [id], an [isAnonymous] flag, and a [role].
+/// The [email] is optional and typically present only for non-anonymous
+/// users who have verified their email address.
   const User({
     required this.id,
     required this.isAnonymous,
-    required this.isAdmin,
+    required this.role,
     this.email,
   });
 
@@ -41,17 +41,17 @@ class User extends Equatable {
   /// `false` otherwise.
   final bool isAnonymous;
 
-  /// Indicates whether the user has administrative privileges.
-  final bool isAdmin;
+  /// The role of the user (e.g., 'admin', 'standard_user').
+  final String role;
 
   /// Converts this User instance to JSON data.
   Map<String, dynamic> toJson() => _$UserToJson(this);
 
   @override
-  List<Object?> get props => [id, email, isAnonymous, isAdmin];
+  List<Object?> get props => [id, email, isAnonymous, role];
 
   @override
   String toString() {
-    return 'User(id: $id, email: $email, isAnonymous: $isAnonymous, isAdmin: $isAdmin)';
+    return 'User(id: $id, email: $email, isAnonymous: $isAnonymous, role: $role)';
   }
 }

lib/src/models/role.g.dart

@@ -8,7 +8,7 @@ void main() {
       id: 'user-123',
       email: 'test@example.com',
       isAnonymous: false,
-      isAdmin: false,
+      role: 'standard_user',
     );
     const testToken = 'sample-jwt-token';
 
@@ -96,7 +96,7 @@ void main() {
           id: 'user-456',
           email: 'updated@example.com',
           isAnonymous: true,
-          isAdmin: false,
+          role: 'standard_user',
         );
         final copiedResponse = authSuccessResponse.copyWith(user: updatedUser);
 
@@ -120,7 +120,7 @@ void main() {
         const updatedUser = User(
           id: 'user-789',
           isAnonymous: true,
-          isAdmin: false,
+          role: 'standard_user',
         );
         const updatedToken = 'another-token-xyz';
         final copiedResponse = authSuccessResponse.copyWith(
@@ -146,7 +146,7 @@ void main() {
         const differentUser = User(
           id: 'diff-user',
           isAnonymous: false,
-          isAdmin: false,
+          role: 'admin',
         );
         const response1 = AuthSuccessResponse(user: testUser, token: testToken);
         const response2 = AuthSuccessResponse(

lib/src/models/user.dart

@@ -8,50 +8,50 @@ void main() {
 
     test('supports value equality', () {
       expect(
-        const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+        const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         equals(
-          const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+          const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         ),
       );
       expect(
-        const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+        const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         isNot(
           equals(
             const User(
               id: 'other-id',
               email: email,
               isAnonymous: false,
-              isAdmin: false,
+              role: 'standard_user',
             ),
           ),
         ),
       );
       expect(
-        const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+        const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         isNot(
           equals(
             const User(
               id: id,
               email: 'other@example.com',
               isAnonymous: false,
-              isAdmin: false,
+              role: 'standard_user',
             ),
           ),
         ),
       );
       expect(
-        const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+        const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         isNot(
           equals(
-            const User(id: id, email: email, isAnonymous: true, isAdmin: false),
+            const User(id: id, email: email, isAnonymous: true, role: 'standard_user'),
           ),
         ),
       );
-      expect(
-        const User(id: id, email: email, isAnonymous: false, isAdmin: false),
+       expect(
+        const User(id: id, email: email, isAnonymous: false, role: 'standard_user'),
         isNot(
           equals(
-            const User(id: id, email: email, isAnonymous: false, isAdmin: true),
+            const User(id: id, email: email, isAnonymous: false, role: 'admin'),
           ),
         ),
       );
@@ -63,19 +63,19 @@ void main() {
           id: id,
           email: email,
           isAnonymous: false,
-          isAdmin: false,
+          role: 'standard_user',
         ).toString(),
         equals(
-          'User(id: $id, email: $email, isAnonymous: false, isAdmin: false)',
+          'User(id: $id, email: $email, isAnonymous: false, role: standard_user)',
         ),
       );
       expect(
-        const User(id: id, isAnonymous: true, isAdmin: false).toString(),
-        equals('User(id: $id, email: null, isAnonymous: true, isAdmin: false)'),
+        const User(id: id, isAnonymous: true, role: 'standard_user').toString(),
+        equals('User(id: $id, email: null, isAnonymous: true, role: standard_user)'),
       );
       expect(
-        const User(id: id, isAnonymous: false, isAdmin: true).toString(),
-        equals('User(id: $id, email: null, isAnonymous: false, isAdmin: true)'),
+        const User(id: id, isAnonymous: false, role: 'admin').toString(),
+        equals('User(id: $id, email: null, isAnonymous: false, role: admin)'),
       );
     });
 
@@ -85,13 +85,13 @@ void main() {
         id: id,
         email: email,
         isAnonymous: false,
-        isAdmin: false,
+        role: 'standard_user',
       );
       final json = user.toJson();
       final deserializedUser = User.fromJson(json);
       expect(deserializedUser, equals(user));
 
-      const anonUser = User(id: id, isAnonymous: true, isAdmin: false);
+      const anonUser = User(id: id, isAnonymous: true, role: 'standard_user');
       final anonJson = anonUser.toJson();
       final deserializedAnonUser = User.fromJson(anonJson);
       expect(deserializedAnonUser, equals(anonUser));
@@ -100,7 +100,7 @@ void main() {
         id: id,
         email: email,
         isAnonymous: false,
-        isAdmin: true,
+        role: 'admin',
       );
       final adminJson = adminUser.toJson();
       final deserializedAdminUser = User.fromJson(adminJson);