import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsEnum, IsNumber, IsOptional, IsString } from 'class-validator';

/**
 * GetWebMediaDto - Data Transfer Object for filtering and querying web media content
 *
 * This DTO provides flexible filtering options for retrieving media content
 * from a web application. It supports multiple filtering dimensions including
 * media type, time ranges, search text, and contextual filters.
 *
 * All fields are optional to allow for flexible querying - when no filters
 * are provided, typically returns all or default media content.
 *
 * @example
 * // Get media from last week
 * {
 *   "upload_time": "week",
 *   "type": "1"
 * }
 *
 * @example
 * // Search for specific media
 * {
 *   "search_text": "travel guide",
 *   "countryId": 44
 * }
 *
 * @example
 * // Usage in controller
 * @Get('media')
 * getMedia(@Query() filters: GetWebMediaDto) {
 *   return this.mediaService.getFilteredMedia(filters);
 * }
 */
export class GetWebMediaDto {
  /**
   * Media type identifier
   *
   * Numeric or string identifier for different media categories/types.
   * Examples might include:
   * - "1": Images
   * - "2": Videos
   * - "3": Documents
   * - "4": Audio files
   *
   * @optional Filter by media type/category
   * @example "1"
   * @example "2"
   */
  @ApiPropertyOptional({
    description: 'Media type identifier (e.g. 1 for images, 2 for videos)',
    example: '1',
  })
  @IsOptional()
  @IsString()
  type?: string;

  /**
   * Page type context
   *
   * Specifies which section/page of the application is requesting media.
   * Can be used to return context-specific media content.
   *
   * Examples:
   * - "homepage": Media for the homepage carousel
   * - "gallery": Media for the gallery page
   * - "blog": Media for blog posts
   * - "product": Media for product pages
   *
   * @optional Contextual filter for page-specific media
   * @example "homepage"
   * @example "gallery"
   */
  @ApiPropertyOptional({
    description: 'Page/section type for contextual media filtering',
    example: 'homepage',
  })
  @IsOptional()
  @IsString()
  pageType?: string;

  /**
   * Upload time filter
   *
   * Filters media based on upload/creation timeframe.
   * Useful for showing recent content or time-bound collections.
   *
   * @optional Filter by upload timeframe
   * @example "week" // Last 7 days
   * @example "month" // Last 30 days
   */
  @ApiPropertyOptional({
    description: 'Upload time filter for recent media',
    enum: ['week', 'month', 'six_month', 'year', 'last_year'],
    example: 'month',
  })
  @IsOptional()
  @IsEnum(['week', 'month', 'six_month', 'year', 'last_year'])
  upload_time?: 'week' | 'month' | 'six_month' | 'year' | 'last_year';

  /**
   * Search text for media titles/descriptions
   *
   * Free-text search query to filter media by title, description,
   * or other searchable metadata.
   *
   * Implementation considerations:
   * - Should be case-insensitive
   * - May support partial matching
   * - Consider search indexing for performance
   * - Sanitize to prevent injection attacks
   *
   * @optional Text search filter
   * @example "travel guide"
   * @example "product demo"
   */
  @ApiPropertyOptional({
    description: 'Search text to filter media by title or description',
    example: 'travel guide',
  })
  @IsOptional()
  @IsString()
  search_text?: string;

  /**
   * Visa product country identifier
   *
   * Filters media related to specific countries for visa-related content.
   * Typically corresponds to country IDs in a visa products database.
   *
   * @optional Filter by country for visa-related media
   * @example 44 // United Kingdom
   * @example 1 // United States
   */
  @ApiPropertyOptional({
    description: 'Visa product country ID for country-specific media',
    example: 44,
    type: Number,
  })
  @IsOptional()
  @IsNumber()
  countryId?: number;

  /**
   * Test module identifier
   *
   * Filters media associated with specific test modules or assessments.
   * Used in educational or testing platforms.
   *
   * @optional Filter by test module
   * @example 101 // IELTS preparation module
   * @example 202 // TOEFL speaking test
   */
  @ApiPropertyOptional({
    description: 'Test module ID for educational/testing media',
    example: 101,
    type: Number,
  })
  @IsOptional()
  @IsNumber()
  test_module_id?: number;
}
