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

/**
 * ForgotRequestDto - Data Transfer Object for password/account recovery requests
 *
 * This DTO handles requests for account recovery operations such as:
 * - Password reset requests
 * - Username/account lookup
 * - Account recovery initiation
 *
 * The 'flag' field determines the type of recovery operation to perform,
 * allowing a single endpoint to handle multiple recovery scenarios.
 *
 * @example
 * // For password reset request
 * {
 *   "flag": "dm",
 *   "email": "user@example.com"
 * }
 *
 * @example
 * // For account lookup/verification
 * {
 *   "flag": "guglu",
 *   "email": "user@example.com"
 * }
 *
 * @example
 * // Usage in controller
 * @Post('forgot')
 * forgotPassword(@Body() forgotRequestDto: ForgotRequestDto) {
 *   return this.authService.initiateRecovery(forgotRequestDto);
 * }
 */
export class ForgotRequestDto {
  /**
   * Recovery operation type flag
   *
   * Determines the specific recovery operation to perform:
   * - 'dm': Direct message/password reset (most common)
   * - 'guglu': Alternative recovery method or system-specific operation
   *
   * The flag allows the backend to:
   * - Route to different recovery workflows
   * - Apply different security policies
   * - Generate different types of recovery emails/notifications
   * - Track recovery method analytics
   *
   * @note Consider using an enum for better type safety:
   *   enum RecoveryFlag { 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: 'Recovery operation type flag',
    enum: ['dm', 'guglu'],
    examples: ['dm', 'guglu'],
    required: true,
  })
  flag: string;

  /**
   * Email address for account lookup and recovery
   *
   * The email address associated with the account that needs recovery.
   * This is used to:
   * - Look up the user account in the database
   * - Send recovery instructions to the registered email
   * - Verify account ownership
   * - Prevent account enumeration attacks
   *
   * Security considerations:
   * - Always return generic success messages to prevent email enumeration
   * - Implement rate limiting to prevent abuse
   * - Validate email format to prevent malformed requests
   * - Check if email exists in database (but don't reveal result to client)
   *
   * Validation rules:
   * - Must be a valid email format
   * - Cannot be empty/null/undefined
   *
   * @example "user@example.com"
   * @example "john.doe@company.org"
   */
  @IsEmail()
  @IsNotEmpty()
  @ApiProperty({
    description: 'Email address for account recovery',
    example: 'user@example.com',
    format: 'email',
    required: true,
  })
  email: string;
}
