/// Represents an authenticated user of the Kell Creations platform.
///
/// This is a lightweight identity model — it carries the user's display
/// information and role but does not hold credentials or tokens directly.
/// Credentials are managed separately by [CredentialStore].
class KcUser {
  /// Unique identifier for this user (e.g. a UUID or username).
  final String id;

  /// Human-readable display name.
  final String displayName;

  /// Email address (used as the primary login identifier).
  final String email;

  /// The role assigned to this user, controlling what actions they may perform.
  final KcUserRole role;

  const KcUser({
    required this.id,
    required this.displayName,
    required this.email,
    required this.role,
  });

  /// Returns a copy of this user with the given fields replaced.
  KcUser copyWith({String? id, String? displayName, String? email, KcUserRole? role}) {
    return KcUser(
      id: id ?? this.id,
      displayName: displayName ?? this.displayName,
      email: email ?? this.email,
      role: role ?? this.role,
    );
  }

  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is KcUser &&
          id == other.id &&
          displayName == other.displayName &&
          email == other.email &&
          role == other.role;

  @override
  int get hashCode => Object.hash(id, displayName, email, role);

  @override
  String toString() =>
      'KcUser(id: $id, displayName: $displayName, email: $email, role: ${role.name})';
}

/// The role assigned to a [KcUser], controlling access to platform features.
enum KcUserRole {
  /// Full access to all platform features including configuration.
  admin,

  /// Standard operator access — can manage products, orders, and inventory.
  operator,

  /// Read-only access — can view but not modify data.
  viewer,
}
