/**
 * AuthenticatedUser - Class representing an authenticated user's core identity
 *
 * This class encapsulates the minimal essential information about an
 * authenticated user that is typically extracted from JWT tokens or
 * session data. It's commonly used to type the `req.user` object in
 * NestJS applications after successful authentication.
 *
 * Fields correspond to standard JWT claims (RFC 7519) with additional
 * application-specific claims:
 * - sub (subject): Typically the user's unique identifier (user_id)
 * - role: Application-specific role/privilege level
 * - email: User's email address for identification and communication
 *
 * @example
 * // After JWT validation, request.user contains AuthenticatedUser data
 * @Get('profile')
 * getProfile(@Request() req) {
 *   const user: AuthenticatedUser = req.user;
 *   return this.userService.getProfile(user.sub);
 * }
 *
 * @example
 * // JWT payload typically includes these fields
 * const payload = {
 *   sub: 12345,
 *   role: 2,
 *   email: 'user@example.com',
 *   iat: 1610000000,
 *   exp: 1610003600
 * };
 *
 * @see https://tools.ietf.org/html/rfc7519#section-4.1 - JWT Claims
 */
export class AuthenticatedUser {
  /**
   * Subject - User identifier
   *
   * Standard JWT claim "sub" (subject) representing the principal
   * that is the subject of the JWT. Typically the user's unique
   * identifier (database user_id).
   *
   * Common uses:
   * - Database lookups for user-specific data
   * - Audit logging of user actions
   * - Permission checking for resources owned by user
   *
   * @optional May be undefined for certain authentication flows
   * @example 12345
   */
  sub?: number; // user_id

  /**
   * User role identifier
   *
   * Application-specific claim representing the user's role or
   * privilege level. Typically corresponds to a role in the
   * application's authorization system.
   *
   * Common patterns:
   * - Numeric role IDs (1: admin, 2: user, 3: guest)
   * - String role names ('admin', 'user', 'moderator')
   * - Bitmask permissions (0b001: read, 0b010: write, 0b100: delete)
   *
   * @optional May be undefined for minimal authentication tokens
   * @example 2
   * @example 'admin'
   */
  role?: number;

  /**
   * User email address
   *
   * User's email address for identification and communication.
   * Often included in tokens for:
   * - Display purposes in UI
   * - Email-based operations
   * - Audit trail enrichment
   *
   * Security considerations:
   * - Email may be considered PII (Personally Identifiable Information)
   * - Consider privacy regulations (GDPR, CCPA)
   * - May be omitted from tokens for privacy reasons
   *
   * @optional May be undefined for privacy or token size concerns
   * @example 'user@example.com'
   */
  email?: string;
}
