image-platform/apps/backend/src/internal-images/ensure-image-variant.dto.ts

import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger"
import type { ActualImageFormat, RequestedImageFormat, ResizeMode } from "@image-platform/image-config"

export class EnsureImageVariantRequestDto {
  @ApiProperty({ description: "Публичный идентификатор asset из Gateway URL.", example: "asset_123" })
  assetId!: string

  @ApiProperty({ description: "Версия source image из Gateway URL `v{version}`.", example: 4, minimum: 1 })
  version!: number

  @ApiProperty({ description: "Имя preset трансформации. Сейчас используется как часть variant key.", example: "card" })
  preset!: string

  @ApiPropertyOptional({ description: "Целевая ширина variant в пикселях. Обязательна для responsive presets и custom.", example: 640, minimum: 1 })
  width?: number

  @ApiPropertyOptional({ description: "Целевая высота variant в пикселях. `0` или отсутствие означает auto height.", example: 420, minimum: 0 })
  height?: number

  @ApiPropertyOptional({ description: "Качество сжатия для imgproxy. Если не передано, берётся из preset.", example: 80, minimum: 1 })
  quality?: number

  @ApiPropertyOptional({
    description: "Формат, который запросил клиент. Для `auto` Gateway выбирает фактический формат по `Accept` header.",
    enum: ["auto", "avif", "webp", "jpg", "png"],
    example: "auto",
  })
  requestedFormat?: RequestedImageFormat

  @ApiPropertyOptional({
    description: "Режим resize для custom transforms. Для обычных presets берётся из preset config.",
    enum: ["fit", "fill"],
    example: "fit",
  })
  resize?: ResizeMode

  @ApiProperty({
    description: "Фактический output format после negotiation. Именно этот формат попадает в S3 key и L1 cache key.",
    enum: ["avif", "webp", "jpg", "png"],
    example: "webp",
  })
  format!: ActualImageFormat
}