/**
 * DTO used for searching and filtering bonus payment records.
 *
 * Inherits pagination and sorting capabilities from PaginationDto.
 * Supports advanced filtering, CSV export, and date-range queries.
 */
import { ApiPropertyOptional } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import {
  IsArray,
  IsBoolean,
  IsOptional,
  IsString,
  ValidateNested,
} from 'class-validator';
import { DateRangeDto } from 'src/utils/datetime/dateRangeDto';
import { PaginationDto } from 'src/config/pagination/paginationDto';

export class SearchBonusPaidDto extends PaginationDto {
  /**
   * Global search keyword.
   *
   * Used to search across text-based fields
   * such as remarks, transaction ID, or reference numbers.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsString()
  search_title?: string;

  /**
   * Filter by creator user IDs.
   *
   * Allows fetching bonus records created by
   * specific users.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  created_by?: string[];

  /**
   * Filter by last updated user IDs.
   *
   * Returns bonus records updated by
   * specific users.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  updated_by?: string[];

  /**
   * Filter by associate (sub-agent) IDs.
   *
   * Used to fetch bonus payments
   * related to specific associates.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  associate_id?: string[];

  /**
   * Filter by payment mode IDs.
   *
   * Examples:
   * - Bank Transfer
   * - Cash
   * - UPI
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  payment_mode_id?: string[];

  /**
   * Filter by source bank account IDs.
   *
   * Represents company or system accounts
   * from which payments were made.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  from_bank_account_id?: number[];

  /**
   * Filter by destination bank account IDs.
   *
   * Represents associate bank accounts
   * receiving the payment.
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsArray()
  to_bank_account_id?: number[];

  /**
   * CSV export flag.
   *
   * When true:
   * - Returns full dataset
   * - Pagination is typically ignored
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsBoolean()
  is_csv?: boolean = false;

  /**
   * Created date range filter.
   *
   * Filters bonus payments based on
   * creation date.
   */
  @ApiPropertyOptional({ type: DateRangeDto })
  @IsOptional()
  @ValidateNested()
  @Type(() => DateRangeDto)
  created_on?: DateRangeDto;

  /**
   * Updated date range filter.
   *
   * Filters bonus payments based on
   * last update date.
   */
  @ApiPropertyOptional({ type: DateRangeDto })
  @IsOptional()
  @ValidateNested()
  @Type(() => DateRangeDto)
  updated_on?: DateRangeDto;
}
