import { ApiProperty } from '@nestjs/swagger'; // Optional, for Swagger documentation
import { TokenResponseDto } from './token-response.dto';

/**
 * LoginResponseDto - Data Transfer Object for authentication response
 *
 * This DTO defines the structure of successful authentication responses.
 * It provides the user's identity, role information, authentication tokens,
 * and verification status in a standardized format.
 *
 * Used as the return type for login, registration, and token refresh endpoints
 * to ensure consistent API responses across all authentication flows.
 *
 * @example
 * // Successful login response
 * {
 *   "id": 12345,
 *   "role": "user",
 *   "role_id": 2,
 *   "data": {
 *     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "expires_in": 3600
 *   },
 *   "email_verified_at": "2024-01-15T10:30:00Z"
 * }
 *
 * @example
 * // Usage in controller
 * @Post('login')
 * @ApiResponse({ type: LoginResponseDto })
 * async login(@Body() loginDto: LoginRequestDto): Promise<LoginResponseDto> {
 *   return this.authService.login(loginDto);
 * }
 */
export class LoginResponseDto {
  /**
   * Unique user identifier
   *
   * The primary key or unique identifier for the authenticated user.
   * Used for subsequent API requests to identify the user.
   *
   * @example 12345
   * @example "550e8400-e29b-41d4-a716-446655440000"
   */
  @ApiProperty({
    description: 'Unique user identifier',
    example: 12345,
    type: Number,
  })
  id: number;

  /**
   * User's role name
   *
   * Human-readable name of the user's role for UI display and client logic.
   * Typically corresponds to a role in the application's permission system.
   *
   * Common values:
   * - 'user': Standard authenticated user
   * - 'admin': Administrator with elevated permissions
   * - 'moderator': Content moderator
   * - 'guest': Limited access user
   *
   * @example "user"
   * @example "admin"
   */
  @ApiProperty({
    description: 'User role name',
    example: 'user',
    type: String,
  })
  role: string;

  /**
   * User's role identifier
   *
   * Numeric identifier for the user's role, typically used for:
   * - Database foreign key relationships
   * - Permission checking in middleware/guards
   * - Role hierarchy comparisons
   *
   * @note Often corresponds to an enum or lookup table in the database
   * @example 2
   * @example 10
   */
  @ApiProperty({
    description: 'Role ID of the user',
    example: 2,
    type: Number,
  })
  role_id: number;

  /**
   * Authentication tokens
   *
   * Contains the JWT tokens and related metadata for maintaining
   * an authenticated session. Wrapped in a separate DTO for organization.
   *
   * @see TokenResponseDto for detailed structure
   *
   * @example
   * data: {
   *   access_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   *   refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   *   expires_in: 3600
   * }
   */
  @ApiProperty({
    description: 'Authentication tokens and metadata',
    type: TokenResponseDto,
  })
  data: TokenResponseDto;

  /**
   * Email verification timestamp
   *
   * ISO 8601 timestamp indicating when the user's email was verified.
   * Used to determine if the user has completed email verification.
   *
   * Possible values:
   * - ISO timestamp: Email verified at specific time
   * - null: Email not yet verified
   * - Empty string: Legacy representation of unverified email
   *
   * @note Consider using null for unverified emails for clearer semantics
   *
   * @example "2024-01-15T10:30:00Z"
   * @example null
   */
  @ApiProperty({
    description: 'Email verification timestamp (ISO 8601 format)',
    example: '2024-01-15T10:30:00Z',
    type: String,
    nullable: true,
  })
  email_verified_at: string;
}
