/**
 * Типы и интерфейсы API сервиса поиска
 *
 * Этот модуль определяет основной интерфейс API сервиса и типы конфигурации,
 * используемые для взаимодействия с Barneo Search API.
 *
 * @module searchApi
 *
 */
import type {
  ApiResponse,
  CatalogSearchRequest,
  HistoryQueriesSearchRequest,
  TopQueriesSearchRequest,
  PopularProductsSearchRequest,
  ProductsUseRequest,
  HistoryQueriesDeleteRequest,
  HistoryQueriesDeleteAllRequest,
} from "./requests";
import type {
  CatalogSearchResponse,
  TopQueriesResponse,
  PopularProductsResponse,
} from "./responses";

/**
 * Основной интерфейс API сервиса для поисковых операций.
 * Предоставляет методы для всех поисковых API вызовов и управления данными.
 */
export interface SearchApiService {
  /**
   * Выполняет поиск по каталогу с предоставленными параметрами.
   * @param {Partial<CatalogSearchRequest>} params - Параметры поиска
   * @returns {Promise<ApiResponse<CatalogSearchResponse>>} Результаты поиска
   */
  searchCatalog(
    params: Partial<CatalogSearchRequest>
  ): Promise<ApiResponse<CatalogSearchResponse>>;

  /**
   * Получает исторические поисковые запросы пользователя.
   * @param {Partial<HistoryQueriesSearchRequest>} params - Параметры запроса истории
   * @returns {Promise<ApiResponse<string[]>>} Массив исторических запросов
   */
  getHistoryQueries(
    params: Partial<HistoryQueriesSearchRequest>
  ): Promise<ApiResponse<string[]>>;

  /**
   * Получает популярные поисковые запросы.
   * @param {Partial<TopQueriesSearchRequest>} params - Опциональные параметры для популярных запросов
   * @returns {Promise<ApiResponse<TopQueriesResponse>>} Данные популярных запросов
   */
  getTopQueries(
    params?: Partial<TopQueriesSearchRequest>
  ): Promise<ApiResponse<TopQueriesResponse>>;

  /**
   * Получает популярные товары для отображения.
   * @param {Partial<PopularProductsSearchRequest>} params - Опциональные параметры для популярных товаров
   * @returns {Promise<ApiResponse<PopularProductsResponse>>} Данные популярных товаров
   */
  getPopularProducts(
    params?: Partial<PopularProductsSearchRequest>
  ): Promise<ApiResponse<PopularProductsResponse>>;

  /**
   * Отслеживает использование поискового запроса для аналитики.
   * @param {string} query - Поисковый запрос для отслеживания
   * @returns {Promise<ApiResponse<any>>} Подтверждение отслеживания
   */
  trackQueryUse(query: string): Promise<ApiResponse<any>>;

  /**
   * Отслеживает использование конкретных поисковых функций для аналитики.
   * @param {string} functionName - Название используемой функции
   * @returns {Promise<ApiResponse<any>>} Подтверждение отслеживания
   */
  useSearchFunction(functionName: string): Promise<ApiResponse<any>>;

  /**
   * Отслеживает использование поисковой подсказки для аналитики.
   * @param {string} query - Исходный запрос
   * @param {string} hint - Использованная подсказка
   * @returns {Promise<ApiResponse<any>>} Подтверждение отслеживания
   */
  trackHintUse(query: string, hint: string): Promise<ApiResponse<any>>;

  /**
   * Отслеживает события конверсии товаров для аналитики.
   * @param {Partial<ProductsUseRequest>} params - Параметры конверсии товара
   * @returns {Promise<ApiResponse<any>>} Подтверждение отслеживания
   */
  trackProductConversion(
    params: Partial<ProductsUseRequest>
  ): Promise<ApiResponse<any>>;

  /**
   * Удаляет конкретный запрос из истории поиска.
   * @param {HistoryQueriesDeleteRequest} params - Параметры удаления запроса
   * @returns {Promise<ApiResponse<string[]>>} Обновленный массив истории
   */
  deleteHistoryQuery(
    params: HistoryQueriesDeleteRequest
  ): Promise<ApiResponse<string[]>>;

  /**
   * Удаляет все запросы из истории поиска.
   * @param {HistoryQueriesDeleteAllRequest} params - Параметры удаления истории
   * @returns {Promise<ApiResponse<null>>} Подтверждение удаления
   */
  deleteAllHistoryQueries(
    params: HistoryQueriesDeleteAllRequest
  ): Promise<ApiResponse<null>>;

  /**
   * Получает текущий ID клиента.
   * @returns {string} Идентификатор клиента
   */
  getCustomerId(): string;

  /**
   * Получает текущий ID локации.
   * @returns {string} Идентификатор локации
   */
  getLocationId(): string;
}

/**
 * Интерфейс конфигурации для API сервиса поиска.
 * Определяет параметры подключения и аутентификации.
 */
export interface SearchApiConfig {
  /**
   * Базовый URL для API поиска (например, https://api.search.ensi.cloud).
   * @required
   */
  baseUrl: string;
  /**
   * Токен аутентификации для доступа к API.
   * @required
   */
  token: string;
  /**
   * Идентификатор клиента для мультитенантных настроек.
   * @required
   */
  customerId: string;
  /**
   * Идентификатор локации для поиска, специфичного для местоположения.
   * @required
   */
  locationId: string;
  /**
   * Версия API для использования в запросах.
   * @defaultValue "v1"
   */
  apiVersion?: string;
}