Metadata-Version: 2.4
Name: botix-cli
Version: 1.0.0
Summary: Командная строка для BOTIX Public API
Project-URL: Homepage, https://botix.pro
Project-URL: Documentation, https://botix.pro/docs
Project-URL: Repository, https://github.com/BOTIX-pro/cli
Project-URL: Issues, https://github.com/BOTIX-pro/cli/issues
Author-email: BOTIX <info@botix.pro>
License: MIT
License-File: LICENSE
Keywords: api,botix,chatbot,cli,messaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: botix>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Description-Content-Type: text/markdown

# botix-cli

**Командная строка для BOTIX Public API.** Делает то же, что веб-кабинет
[app.botix.pro](https://app.botix.pro), но из терминала: создание ключей,
управление подписками webhook, list контактов, отправка сообщений, тестовые
доставки. Аналоги — `stripe-cli`, `gh`, `aws-cli`.

## Требования

- Python 3.9+
- Действующий API-ключ BOTIX (получается в кабинете в разделе
  «Настройки → API-ключи»)

## Установка

```bash
pip install botix-cli
```

После установки команда `botix` доступна глобально.

Проверка:

```bash
botix --version
```

## Первый запуск

```bash
botix login
# API-ключ (btx_live_... или btx_test_...): ********
# ✓ Профиль default сохранён (project_id=42).
```

Ключ кладётся в `~/.botix/config.yaml` с правами **600** (читает только владелец).

Проверка авторизации:

```bash
botix whoami
```

## Команды

### Профили (auth)

| Команда                       | Что делает                                    |
| ----------------------------- | --------------------------------------------- |
| `botix login`                 | Сохранить API-ключ. Проверяет через `GET /me` |
| `botix login --name staging`  | Создать дополнительный профиль                |
| `botix logout`                | Удалить весь конфиг                           |
| `botix logout --name staging` | Удалить один профиль                          |
| `botix whoami`                | project_id, scopes, тариф активного ключа     |

### Контакты

```bash
botix contacts list --tag VIP --channel telegram --limit 50
botix contacts get 42
botix contacts create --first-name "Иван" --phone "+79991112233" --tag VIP
botix contacts delete 42 --yes
```

### Сообщения

```bash
botix messages send --contact-id 42 --channel telegram --text "Привет!"
botix messages list --contact-id 42 --limit 50
```

`messages send` автоматически использует `Idempotency-Key` — повтор той же
команды не отправит сообщение второй раз.

### Webhooks

```bash
botix webhooks list
botix webhooks create \
  --url https://example.com/hook \
  --events contact.created,message.received
botix webhooks test 7              # отправить тестовое событие
botix webhooks tail                # live-лента доставок (аналог `stripe listen`)
botix webhooks delete 7 --yes
```

`webhooks tail` опрашивает `/api/v1/webhook-deliveries` раз в 2 секунды
(можно настроить флагом `--interval`) и печатает новые доставки в реальном
времени. Прерывается через `Ctrl+C`.

### API-ключи

```bash
botix keys list
botix keys create --name "Production" --scopes contacts:read,messages:send
botix keys revoke 12 --yes
```

> Управление ключами — внутренняя возможность кабинета. Если ваш ключ
> не имеет прав `keys:manage`, CLI попросит создать ключ через
> [app.botix.pro/settings?tab=api-keys](https://app.botix.pro/settings?tab=api-keys).

## Профили

Несколько профилей живут в одном `~/.botix/config.yaml`:

```yaml
default_profile: production
profiles:
  production:
    api_key: btx_live_...
    base_url: https://api.botix.pro
  staging:
    api_key: btx_test_...
    base_url: https://api.botix.pro
```

Выбрать профиль на конкретный вызов:

```bash
botix --profile staging contacts list
```

## Переменные окружения

| Переменная        | Эффект                                                      |
| ----------------- | ----------------------------------------------------------- |
| `BOTIX_API_KEY`   | Полностью обходит конфиг — удобно для CI                    |
| `BOTIX_BASE_URL`  | Базовый URL API (по умолчанию `https://api.botix.pro`)      |
| `BOTIX_PROFILE`   | Имя профиля по умолчанию (эквивалент `--profile`)           |
| `BOTIX_CONFIG_DIR`| Каталог конфигурации (для тестов и изолированных сред)      |

Пример использования в GitHub Actions:

```yaml
- name: Отправить уведомление через BOTIX
  env:
    BOTIX_API_KEY: ${{ secrets.BOTIX_API_KEY }}
  run: |
    botix messages send --contact-id 42 --text "Деплой прошёл успешно"
```

## Machine-readable вывод

Любая команда поддерживает флаг `--json` — печатает JSON вместо таблиц:

```bash
botix --json contacts list | jq '.[] | select(.tags | index("VIP"))'
```

Полезно для интеграций и скриптов.

## FAQ

**Где хранится ключ?**
`~/.botix/config.yaml`, права `600` (читает только владелец).

**Как удалить ключ полностью?**
`botix logout --yes` (удаляет весь файл) или
`botix logout --name production --yes` (один профиль).

**Можно ли использовать в CI без `~/.botix`?**
Да, передайте `BOTIX_API_KEY` через переменные окружения.
`login` тогда не нужен.

**Что делать если 401 Unauthorized?**
1. Проверьте `botix whoami` — что ключ корректный.
2. Проверьте scopes ключа в кабинете
   `app.botix.pro/settings?tab=api-keys` — у разных команд CLI разные требования
   (`contacts:read` для list, `messages:send` для send и т.д.).

**`botix webhooks tail` ничего не показывает.**
Доставки появляются только при работе webhook. Запустите рядом
`botix webhooks test <id>` — должна сразу появиться доставка.

## Разработка

```bash
git clone https://github.com/BOTIX-pro/cli.git
cd cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

CI прогоняет тесты на Python 3.9 — 3.12 (см. `.github/workflows/test.yml`).

## Лицензия

MIT — см. [LICENSE](./LICENSE).

## Ссылки

- Сайт: [botix.pro](https://botix.pro)
- Документация API: [botix.pro/docs](https://botix.pro/docs)
- SDK (Python): [github.com/BOTIX-pro/sdk-python](https://github.com/BOTIX-pro/sdk-python)
- Issues: [github.com/BOTIX-pro/cli/issues](https://github.com/BOTIX-pro/cli/issues)
