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

/**
 * Data Transfer Object (DTO) for updating timezone settings.
 *
 * This DTO is used when users update their timezone preferences in the application.
 * It contains comprehensive timezone information including ID, name, UTC offset,
 * and associated country details.
 *
 * Timezone settings are important for:
 * - Displaying dates/times in the user's local timezone
 * - Scheduling events and reminders
 * - Generating timezone-aware reports
 * - Ensuring consistent datetime handling across the application
 *
 * @example
 * // Updating to US Eastern Time:
 * {
 *   "defaultSetBackendTimeZoneID": "America/New_York",
 *   "defaultSetBackendTimeZoneCountryID": "US",
 *   "defaultSetBackendTimeZoneName": "Eastern Time (ET)",
 *   "defaultSetBackendTimeZoneUtc": "-05:00",
 *   "defaultSetBackendTimeZoneCountryName": "United States"
 * }
 *
 * @example
 * // Updating to Indian Standard Time:
 * {
 *   "defaultSetBackendTimeZoneID": "Asia/Kolkata",
 *   "defaultSetBackendTimeZoneCountryID": "IN",
 *   "defaultSetBackendTimeZoneName": "India Standard Time (IST)",
 *   "defaultSetBackendTimeZoneUtc": "+05:30",
 *   "defaultSetBackendTimeZoneCountryName": "India"
 * }
 */
export class UpdateTimezoneDto {
  /**
   * IANA Time Zone Database identifier.
   * This is the standard timezone identifier used in most systems.
   *
   * @type {string}
   * @required
   * @example "America/New_York"
   * @example "Europe/London"
   * @example "Asia/Tokyo"
   *
   * @isString - Validation: Must be a string
   *   Error message: "defaultSetBackendTimeZoneID must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "defaultSetBackendTimeZoneID should not be empty"
   *
   * @note Should ideally be validated against a list of valid IANA timezone IDs
   */
  @ApiProperty({
    description:
      'IANA Time Zone Database identifier (e.g., "America/New_York")',
    example: 'America/New_York',
    type: String,
  })
  @IsNotEmpty({ message: 'Time zone ID is required' })
  @IsString({ message: 'Time zone ID must be a string' })
  defaultSetBackendTimeZoneID: string;

  /**
   * ISO 3166-1 alpha-2 country code where the timezone is primarily used.
   *
   * @type {string}
   * @required
   * @example "US" (United States)
   * @example "GB" (United Kingdom)
   * @example "IN" (India)
   *
   * @isString - Validation: Must be a string
   *   Error message: "defaultSetBackendTimeZoneCountryID must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "defaultSetBackendTimeZoneCountryID should not be empty"
   *
   * @note Consider adding @Length(2, 2) to ensure exactly 2 characters
   */
  @ApiProperty({
    description: 'ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "IN")',
    example: 'US',
    type: String,
  })
  @IsNotEmpty({ message: 'Country code is required' })
  @IsString({ message: 'Country code must be a string' })
  defaultSetBackendTimeZoneCountryID: string;

  /**
   * Human-readable name of the timezone.
   * Typically displayed in UI dropdowns and user settings.
   *
   * @type {string}
   * @required
   * @example "Eastern Time (ET)"
   * @example "Greenwich Mean Time (GMT)"
   * @example "India Standard Time (IST)"
   *
   * @isString - Validation: Must be a string
   *   Error message: "defaultSetBackendTimeZoneName must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "defaultSetBackendTimeZoneName should not be empty"
   */
  @ApiProperty({
    description: 'Human-readable timezone name for display',
    example: 'Eastern Time (ET)',
    type: String,
  })
  @IsNotEmpty({ message: 'Time zone name is required' })
  @IsString({ message: 'Time zone name must be a string' })
  defaultSetBackendTimeZoneName: string;

  /**
   * UTC offset in ±HH:mm format.
   * Represents the time difference from Coordinated Universal Time.
   *
   * @type {string}
   * @required
   * @example "-05:00" (Eastern Time during standard time)
   * @example "-04:00" (Eastern Time during daylight saving)
   * @example "+05:30" (India Standard Time)
   * @example "+00:00" (Greenwich Mean Time)
   *
   * @isString - Validation: Must be a string
   *   Error message: "defaultSetBackendTimeZoneUtc must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "defaultSetBackendTimeZoneUtc should not be empty"
   *
   * @note Consider adding regex validation: @Matches(/^[+-]\d{2}:\d{2}$/)
   */
  @ApiProperty({
    description: 'UTC offset in ±HH:mm format',
    example: '-05:00',
    type: String,
    pattern: '^[+-]\\d{2}:\\d{2}$',
  })
  @IsNotEmpty({ message: 'UTC offset is required' })
  @IsString({ message: 'UTC offset must be a string' })
  @Matches(/^[+-]\d{2}:\d{2}$/, {
    message: 'UTC offset must be in ±HH:mm format (e.g., -05:00, +05:30)',
  })
  defaultSetBackendTimeZoneUtc: string;

  /**
   * Full name of the country associated with the timezone.
   *
   * @type {string}
   * @required
   * @example "United States"
   * @example "United Kingdom"
   * @example "India"
   *
   * @isString - Validation: Must be a string
   *   Error message: "defaultSetBackendTimeZoneCountryName must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "defaultSetBackendTimeZoneCountryName should not be empty"
   */
  @ApiProperty({
    description: 'Full country name',
    example: 'United States',
    type: String,
  })
  @IsNotEmpty({ message: 'Country name is required' })
  @IsString({ message: 'Country name must be a string' })
  defaultSetBackendTimeZoneCountryName: string;
}
