import { IsString, MinLength, IsIn } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';
import { MatchPassword } from '../../decorators/match-password.decorator';

/**
 * ResetPasswordRequestDto - Data Transfer Object for password reset confirmation
 *
 * This DTO handles the final step of password reset process where users provide:
 * 1. A new password to replace their old password
 * 2. Confirmation of the new password to prevent typos
 * 3. A secure token to validate the reset request
 * 4. A flag indicating the reset method/system
 *
 * The token is typically sent via email/SMS during the forgot password flow
 * and must be validated before allowing password reset.
 *
 * @example
 * // Valid reset request
 * {
 *   "password": "NewSecurePass123!",
 *   "confirm_password": "NewSecurePass123!",
 *   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *   "flag": "dm"
 * }
 *
 * @example
 * // Usage in controller
 * @Post('reset-password')
 * resetPassword(@Body() resetPasswordDto: ResetPasswordRequestDto) {
 *   return this.authService.resetPassword(resetPasswordDto);
 * }
 */
export class ResetPasswordRequestDto {
  /**
   * New password to set
   *
   * The password that will replace the user's old password upon successful
   * token validation. Should meet security requirements.
   *
   * Security considerations:
   * - Minimum length validation (consider increasing from 3 to 8+)
   * - Should be checked against password policies
   * - Should be hashed before storage
   * - Should be checked against password breach databases
   *
   * Validation rules:
   * - Must be a string
   * - Minimum length of 3 characters (VERY WEAK - consider increasing)
   *
   * @warning Minimum length of 3 is extremely insecure.
   *          Consider @MinLength(8) or stronger requirements.
   *
   * @example "NewSecurePass123!"
   */
  @IsString()
  @MinLength(3)
  @ApiProperty({
    description: 'New password to set',
    example: 'NewSecurePass123!',
    minLength: 3,
    required: true,
  })
  password: string;

  /**
   * Password confirmation
   *
   * Confirms that the user correctly typed their new password.
   * This prevents typos that could lock users out of their accounts.
   *
   * The @MatchPassword decorator ensures this field exactly matches
   * the 'password' field value.
   *
   * Validation rules:
   * - Must be a string
   * - Must match the 'password' field exactly
   *
   * @example "NewSecurePass123!"
   */
  @IsString()
  @MatchPassword('password', {
    message: 'Confirm password must match password',
  })
  @ApiProperty({
    description: 'Confirmation of new password (must match password)',
    example: 'NewSecurePass123!',
    required: true,
  })
  confirm_password: string;

  /**
   * Password reset token
   *
   * A secure token that validates the password reset request.
   * Typically:
   * - Generated during the "forgot password" request
   * - Sent to the user via email or SMS
   * - Time-limited (expires after 15-60 minutes)
   * - Single-use (invalidated after successful reset)
   * - Cryptographically signed to prevent tampering
   *
   * Security considerations:
   * - Should be validated against stored/expected token
   * - Should check expiration time
   * - Should prevent token reuse
   * - Should be sufficiently random and unpredictable
   *
   * Validation rules:
   * - Must be a string
   *
   * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   * @example "abc123def456"
   */
  @IsString()
  @ApiProperty({
    description: 'Password reset validation token',
    example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    required: true,
  })
  token: string;

  /**
   * Reset method flag
   *
   * Indicates which password reset system/method is being used.
   * Allows supporting multiple reset workflows from a single endpoint.
   *
   * Common values:
   * - 'dm': Direct method (standard email reset)
   * - 'guglu': Alternative method (SMS, app-specific, etc.)
   *
   * Can trigger:
   * - Different token validation logic
   * - Different audit logging
   * - Different rate limiting rules
   * - Different success responses
   *
   * Validation rules:
   * - Must be a string
   * - Must be one of: 'dm' or 'guglu'
   *
   * @note Consider using an enum: ResetFlag { DM = 'dm', GUGLU = 'guglu' }
   *
   * @example "dm"
   * @example "guglu"
   */
  @IsString()
  @IsIn(['dm', 'guglu'])
  @ApiProperty({
    description: 'Reset method/system flag',
    enum: ['dm', 'guglu'],
    examples: ['dm', 'guglu'],
    required: true,
  })
  flag: string;
}
