import { ApiProperty } from '@nestjs/swagger';
import { JoiSchema, JoiSchemaOptions } from 'nestjs-joi';
import * as Joi from 'joi';
import { IsEmail, IsNotEmpty } from 'class-validator';

/**
 * ForgotPasswordDto - Data Transfer Object for password reset initiation
 *
 * This DTO handles the initial step of the password reset process where users
 * provide their email address to receive password reset instructions.
 *
 * Security considerations:
 * - Always returns generic success message to prevent email enumeration
 * - Implements rate limiting to prevent abuse
 * - Validates email format to ensure proper delivery
 *
 * @example
 * // Request body
 * {
 *   "email": "user@example.com"
 * }
 *
 * @example
 * // Usage in controller
 * @Post('forgot-password')
 * async forgotPassword(@Body() forgotPasswordDto: ForgotPasswordDto) {
 *   return this.authService.initiatePasswordReset(forgotPasswordDto.email);
 * }
 *
 * @note Returns generic "If email exists, reset instructions sent" message
 */
@JoiSchemaOptions({
  /**
   * Strip unknown fields from the request payload
   * Removes any fields not defined in the schema for security
   */
  stripUnknown: true,

  /**
   * Abort validation on first error
   * Returns immediately when validation fails for better performance
   */
  abortEarly: true,
})
export class ForgotPasswordDto {
  /**
   * User's registered email address
   *
   * The email address associated with the account that needs password reset.
   * Used to:
   * - Look up user account in database
   * - Send password reset instructions via email
   * - Verify account ownership
   *
   * Security best practices:
   * - Validate email format to prevent malformed requests
   * - Never reveal if email exists in the system (return generic response)
   * - Implement rate limiting per email/IP address
   * - Use case-insensitive comparison for email lookup
   *
   * Validation rules:
   * - Required field
   * - Valid email format
   * - Trimmed to remove whitespace
   *
   * @example "user@example.com"
   * @example "john.doe@company.org"
   */
  @ApiProperty({
    description: 'The registered email address for password reset',
    example: 'user@example.com',
    required: true,
    format: 'email',
  })
  @IsNotEmpty({ message: 'Email is required' })
  @IsEmail({}, { message: 'Please provide a valid email address' })
  @JoiSchema(
    Joi.string()
      .trim() // Remove leading/trailing whitespace
      .email() // Validate email format
      .required() // Field is mandatory
      .messages({
        'string.email': 'Please provide a valid email address',
        'any.required': 'Email is required',
        'string.empty': 'Email cannot be empty',
      }),
  )
  email: string;
}
