# Настройка Yandex Search API

Для работы скилла нужен сервисный аккаунт в Яндекс.Облаке.

## Шаг 1: Создайте каталог в Яндекс.Облаке

1. Откройте https://console.yandex.cloud/
2. Если нет аккаунта — зарегистрируйтесь (нужен Яндекс ID)
3. Создайте **каталог** (folder) или используйте существующий
4. Скопируйте **ID каталога** — он понадобится дальше

> ID каталога выглядит так: `b1gabcdef12345678900`
> Найти его можно: Консоль → ваш каталог → кнопка "ID" справа от названия

## Шаг 2: Создайте сервисный аккаунт

1. В консоли откройте ваш каталог
2. Слева выберите **Сервисные аккаунты** (раздел IAM)
3. Нажмите **Создать сервисный аккаунт**
4. Имя: `search-api-sa` (или любое другое)
5. Нажмите **Создать**

## Шаг 3: Назначьте роль

Сервисному аккаунту нужна роль для доступа к Search API:

1. Откройте созданный сервисный аккаунт
2. Перейдите в раздел **Роли** (или назначьте через настройки каталога)
3. Нажмите **Назначить роль**
4. Найдите и выберите: `search-api.webSearch.user`
5. Сохраните

## Шаг 4: Создайте ключ авторизации

1. Откройте сервисный аккаунт
2. Перейдите на вкладку **Авторизованные ключи**
3. Нажмите **Создать авторизованный ключ**
4. Скачайте JSON-файл ключа
5. Переименуйте его в `service_account_key.json`
6. Положите в папку `config/` (рядом с этим README)

> Этот файл секретный! Не добавляйте его в git (он уже в .gitignore).

## Шаг 5: Создайте config.json

Скопируйте пример:

```bash
cp config/config.example.json config/config.json
```

Откройте `config.json` и замените `"b1g..."` на ваш ID каталога из Шага 1:

```json
{
  "yandex_cloud_folder_id": "b1gabcdef12345678900",
  "auth": {
    "service_account_key_file": "config/service_account_key.json"
  }
}
```

Остальные поля можно не менять — значения по умолчанию подходят для большинства случаев.

## Шаг 6: Проверьте

```bash
bash scripts/iam_token_get.sh
```

Если всё правильно — увидите "IAM token cached" и можно искать.

## Для пользователей macOS

На macOS вместо OpenSSL стоит LibreSSL, который не поддерживает нужный алгоритм подписи. Если при проверке видите ошибку про LibreSSL:

1. Установите OpenSSL:
   ```bash
   brew install openssl
   ```

2. Добавьте путь к OpenSSL в `config.json`:
   ```json
   {
     "yandex_cloud_folder_id": "b1g...",
     "auth": {
       "service_account_key_file": "config/service_account_key.json",
       "openssl_bin": "/opt/homebrew/bin/openssl"
     }
   }
   ```

> `/opt/homebrew/bin/openssl` — для Mac на Apple Silicon (M1/M2/M3/M4).
> Для Intel Mac путь: `/usr/local/opt/openssl/bin/openssl`.
> Узнать точный путь: `brew --prefix openssl`

## Частые проблемы

### "Error: LibreSSL detected"
macOS по умолчанию использует LibreSSL вместо OpenSSL. См. раздел выше "Для пользователей macOS".

### "Error: 403 Forbidden"
- Не назначена роль `search-api.webSearch.user` → назначьте (Шаг 3)
- Неправильный ID каталога → проверьте `yandex_cloud_folder_id`

### "Error: config.json not found"
Не создан файл конфигурации → выполните Шаг 5.

### "Error: openssl not found"
OpenSSL не установлен или не в PATH → установите через `brew install openssl` и укажите путь в конфиге.

## Лимиты и цены

- Бесплатный тариф: есть (проверяйте актуальные лимиты)
- Подробнее: https://yandex.cloud/ru/docs/search-api/pricing

## Настройки по умолчанию

Эти настройки можно менять в `config.json`, но для начала подойдут как есть:

| Настройка | Значение | Что это |
|-----------|----------|---------|
| Регион | Россия (225) | Откуда "смотрим" поиск |
| Тип поиска | Русскоязычный | Поиск по рунету |
| Фильтр контента | Умеренный | Фильтрует откровенный контент |
| Исправление опечаток | Включено | Яндекс сам исправляет опечатки |
| Результатов на странице | 10 | Сколько ссылок в ответе |

## Альтернатива: настройка через CLI

Если у вас установлен `yc` (Yandex Cloud CLI), можно сделать всё через командную строку:

```bash
# Создать сервисный аккаунт
yc iam service-account create --name search-api-sa

# Назначить роль (замените <FOLDER_ID> и <SA_ID>)
yc resource-manager folder add-access-binding <FOLDER_ID> \
  --role search-api.webSearch.user \
  --subject serviceAccount:<SA_ID>

# Создать ключ
yc iam key create --service-account-name search-api-sa \
  --output config/service_account_key.json
```