import { ApiProperty } from '@nestjs/swagger';
import { TokenResponseDto } from './token-response.dto';

/**
 * SignUpResponseDto - Data Transfer Object for user registration responses
 *
 * This DTO defines the structure of successful user registration responses.
 * It provides immediate authentication tokens while indicating that email
 * verification is still pending, following the "verify later" pattern.
 *
 * The response allows users to start using the application immediately
 * while maintaining security through pending email verification.
 *
 * @example
 * // Successful registration response
 * {
 *   "message": "Please verify your email address. Verification code sent.",
 *   "role": "user",
 *   "role_id": 2,
 *   "data": {
 *     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "expires_in": 3600
 *   }
 * }
 *
 * @example
 * // Usage in controller
 * @Post('signup')
 * @ApiResponse({ type: SignUpResponseDto })
 * async signUp(@Body() signUpDto: SignUpRequestDto): Promise<SignUpResponseDto> {
 *   return this.authService.register(signUpDto);
 * }
 */
export class SignUpResponseDto {
  /**
   * Registration status message
   *
   * Informative message guiding the user on next steps for email verification.
   * Typically indicates that a verification email has been sent and prompts
   * the user to complete the verification process.
   *
   * Message examples:
   * - "Please verify your email address. Verification code sent."
   * - "Registration successful! Check your email to verify your account."
   * - "Account created. Please verify your email within 24 hours."
   *
   * Security considerations:
   * - Avoid revealing whether the email actually exists in the system
   * - Use generic messages to prevent email enumeration attacks
   * - Include clear instructions for verification process
   *
   * @example "Please verify your email address. Verification code sent."
   */
  @ApiProperty({
    description: 'Message indicating email verification code sent',
    example: 'Please verify your email address. Verification code sent.',
    type: String,
  })
  message: string;

  /**
   * User's assigned role name
   *
   * Human-readable name of the default role assigned to the new user.
   * Typically the lowest privilege role for new registrations.
   *
   * Common values:
   * - 'user': Standard registered user
   * - 'member': Basic membership level
   * - 'trial': Trial period user
   * - 'guest': Limited functionality until verification
   *
   * @note Role may be upgraded after email verification or other conditions
   *
   * @example "user"
   * @example "member"
   */
  @ApiProperty({
    description: 'User role name',
    example: 'user',
    type: String,
  })
  role: string;

  /**
   * User's role identifier
   *
   * Numeric identifier for the assigned role, used for:
   * - Database relationships and queries
   * - Permission checks in middleware/guards
   * - Role upgrades after verification
   *
   * @note Should correspond to the lowest privilege role for new users
   *
   * @example 2
   */
  @ApiProperty({
    description: 'Role ID of the user',
    example: 2,
    type: Number,
  })
  role_id: number;

  /**
   * Authentication tokens
   *
   * Contains JWT tokens allowing immediate but potentially limited access
   * to the application while email verification is pending.
   *
   * Security considerations:
   * - Tokens may have limited permissions until email verification
   * - Consider shorter expiration for unverified accounts
   * - May restrict certain sensitive operations
   *
   * @see TokenResponseDto for detailed token structure
   *
   * @example
   * data: {
   *   access_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   *   refresh_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   *   expires_in: 3600
   * }
   */
  @ApiProperty({
    description: 'Authentication tokens for immediate access',
    type: TokenResponseDto,
  })
  data: TokenResponseDto;
}
