import {
  IsEmail,
  IsIn,
  IsNotEmpty,
  IsNumber,
  IsOptional,
  IsString,
  MinLength,
} from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

/**
 * LoginRequestDto - Data Transfer Object for user authentication requests
 *
 * This DTO handles user login requests with support for different authentication
 * methods and optional administrative access control. It validates credentials
 * and provides metadata about the type of login being requested.
 *
 * The 'flag' field enables different authentication workflows, allowing the
 * same endpoint to support multiple login methods (standard, SSO, etc.)
 *
 * @example
 * // Standard user login
 * {
 *   "flag": "dm",
 *   "email": "user@example.com",
 *   "password": "SecurePass123!",
 *   "is_admin": 0
 * }
 *
 * @example
 * // Admin login attempt
 * {
 *   "flag": "guglu",
 *   "email": "admin@example.com",
 *   "password": "AdminPass456!",
 *   "is_admin": 1
 * }
 *
 * @example
 * // Usage in controller
 * @Post('login')
 * login(@Body() loginRequestDto: LoginRequestDto) {
 *   return this.authService.authenticate(loginRequestDto);
 * }
 */
export class LoginRequestDto {
  /**
   * Authentication method flag
   *
   * Specifies the authentication method or system to use:
   * - 'dm': Direct method (standard email/password authentication)
   * - 'guglu': Alternative authentication method (could be SSO, legacy system, etc.)
   *
   * This allows:
   * - Routing to different authentication providers
   * - Supporting multiple login workflows
   * - Maintaining backward compatibility
   * - Different rate limiting or security policies per method
   *
   * @note Consider using an enum for better type safety:
   *   enum AuthFlag { DM = 'dm', GUGLU = 'guglu' }
   *
   * Validation rules:
   * - Must be a string
   * - Cannot be empty/null/undefined
   * - Must be one of the allowed values: 'dm' or 'guglu'
   *
   * @example "dm"
   * @example "guglu"
   */
  @IsString()
  @IsNotEmpty()
  @IsIn(['dm', 'guglu'])
  @ApiProperty({
    description: 'Authentication method flag',
    enum: ['dm', 'guglu'],
    examples: ['dm', 'guglu'],
    required: true,
  })
  flag: string;

  /**
   * User's email address
   *
   * The email address used for account identification. This serves as the
   * username in most email/password authentication systems.
   *
   * Security considerations:
   * - Validate email format to prevent injection attacks
   * - Consider case-insensitive comparison (most email systems are)
   * - Implement rate limiting on failed attempts
   * - Never reveal if email exists in error messages
   *
   * Validation rules:
   * - Must be a valid email format
   * - Cannot be empty/null/undefined
   *
   * @example "user@example.com"
   * @example "admin@organization.org"
   */
  @IsEmail()
  @IsNotEmpty()
  @ApiProperty({
    description: 'User email address for authentication',
    example: 'user@example.com',
    format: 'email',
    required: true,
  })
  email: string;

  /**
   * User's password
   *
   * The password for authentication. Should meet minimum security requirements
   * and be compared against a securely hashed version in the database.
   *
   * Security best practices:
   * - Minimum 8 characters (consider 12+ for better security)
   * - Store using strong hashing algorithms (bcrypt, Argon2, scrypt)
   * - Implement account lockout after multiple failed attempts
   * - Support password complexity requirements
   *
   * Validation rules:
   * - Must be a string
   * - Minimum length of 8 characters
   * - Cannot be empty/null/undefined
   *
   * @example "SecurePass123!"
   * @example "VeryStrongPassword456!"
   */
  @IsString()
  @MinLength(8)
  @IsNotEmpty()
  @ApiProperty({
    description: 'User password (minimum 8 characters)',
    example: 'SecurePass123!',
    minLength: 8,
    required: true,
  })
  password: string;

  /**
   * Administrative access flag
   *
   * Optional flag indicating if the login is for administrative access.
   * This can trigger:
   * - Additional authentication factors (2FA)
   * - Different session timeouts
   * - Access to admin-only endpoints
   * - More detailed audit logging
   *
   * Typical values:
   * - 0: Standard user access
   * - 1: Administrative access
   *
   * Security considerations:
   * - Should not override actual user permissions
   * - Should be validated against user's actual role
   * - Consider removing this field and determining admin status server-side
   *
   * Validation rules:
   * - Optional field (can be omitted)
   * - If provided, must be a number
   *
   * @example 0
   * @example 1
   */
  @IsOptional()
  @IsNumber()
  @ApiProperty({
    description: 'Flag indicating administrative access request',
    example: 0,
    default: 0,
    required: false,
  })
  is_admin: number;
}
