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

/**
 * SocialLoginRequestDto - Data Transfer Object for social authentication requests
 *
 * This DTO handles authentication via third-party social providers (OAuth/OpenID Connect).
 * It validates the provider, authentication token, and system flag for social login flows.
 *
 * The DTO supports multiple social providers and allows for different authentication
 * system configurations via the flag parameter.
 *
 * @example
 * // Google OAuth login
 * {
 *   "flag": "dm",
 *   "provider": "google",
 *   "token": "ya29.a0AfH6SMB..."
 * }
 *
 * @example
 * // Apple Sign-In
 * {
 *   "flag": "guglu",
 *   "provider": "apple",
 *   "token": "eyJraWQiOiJ..."
 * }
 *
 * @example
 * // Usage in controller
 * @Post('social-login')
 * socialLogin(@Body() socialLoginDto: SocialLoginRequestDto) {
 *   return this.authService.authenticateWithSocial(socialLoginDto);
 * }
 */
export class SocialLoginRequestDto {
  /**
   * System/authentication flag
   *
   * Indicates the authentication system or configuration to use.
   * Allows supporting different social login implementations or environments.
   *
   * Common values:
   * - 'dm': Direct method (standard social authentication)
   * - 'guglu': Alternative method (custom configuration, testing, etc.)
   *
   * Can affect:
   * - Token validation endpoints
   * - Client IDs/secrets used
   * - User data mapping
   * - Error handling strategies
   *
   * Validation rules:
   * - Must be a non-empty string
   * - Must be one of: 'dm' or 'guglu'
   *
   * @note Consider using an enum: AuthFlag { DM = 'dm', GUGLU = 'guglu' }
   *
   * @example "dm"
   * @example "guglu"
   */
  @IsString()
  @IsNotEmpty()
  @IsIn(['dm', 'guglu'])
  @ApiProperty({
    description: 'Authentication system flag',
    enum: ['dm', 'guglu'],
    examples: ['dm', 'guglu'],
    required: true,
  })
  flag: string;

  /**
   * Social identity provider
   *
   * The third-party social platform used for authentication.
   * Determines which OAuth/OpenID Connect flow to use.
   *
   * Supported providers:
   * - 'google': Google OAuth 2.0/OpenID Connect
   * - 'apple': Apple Sign-In (Sign in with Apple)
   *
   * Common additional providers to consider:
   * - 'facebook': Facebook Login
   * - 'github': GitHub OAuth
   * - 'microsoft': Microsoft Identity Platform
   * - 'twitter': Twitter OAuth (now X)
   *
   * Validation rules:
   * - Must be a non-empty string
   * - Must be one of: 'google' or 'apple'
   *
   * @note Consider using an enum for better type safety
   *   enum SocialProvider { GOOGLE = 'google', APPLE = 'apple' }
   *
   * @example "google"
   * @example "apple"
   */
  @IsString()
  @IsNotEmpty()
  @IsIn(['google', 'apple'])
  @ApiProperty({
    description: 'Social identity provider',
    enum: ['google', 'apple'],
    examples: ['google', 'apple'],
    required: true,
  })
  provider: string;

  /**
   * Authentication token
   *
   * The token provided by the social provider after successful authentication.
   * The type and validation of this token depends on the provider:
   *
   * For Google:
   * - Typically an ID token (JWT) or access token
   * - Should be validated via Google's tokeninfo endpoint or JWT verification
   *
   * For Apple:
   * - Typically an identity token (JWT)
   * - Should be validated using Apple's public keys
   *
   * Security considerations:
   * - Always validate tokens server-side (never trust client-only validation)
   * - Verify token audience, issuer, and expiration
   * - Implement proper error handling for invalid/expired tokens
   * - Consider token exchange for long-lived session tokens
   *
   * Validation rules:
   * - Must be a non-empty string
   *
   * @example "ya29.a0AfH6SMB..." // Google ID token
   * @example "eyJraWQiOiJ..." // Apple identity token
   */
  @IsString()
  @IsNotEmpty()
  @ApiProperty({
    description: 'Authentication token from social provider',
    example: 'ya29.a0AfH6SMB...',
    required: true,
  })
  token: string;
}
