Metadata-Version: 2.4
Name: sentry-bitrix24
Version: 0.3.0
Summary: Plugin for Sentry which allows sending notifications to Bitrix24 chat.
Home-page: https://github.com/zhiraff/sentry-bitrix24
Author: Pigolev Timofey
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: summary

# sentry-bitrix24

Плагин для [self-hosted Sentry](https://github.com/getsentry/self-hosted), который отправляет уведомления об ошибках в чат Bitrix24 через метод `imbot.message.add`.

Протестирован с Sentry **23.9.1**.

## Возможности

- Отправка уведомлений от имени чат-бота Bitrix24
- **Отдельная настройка для каждого проекта Sentry** — разные проекты могут слать в разные чаты
- Несколько чатов на один проект (по одному `DIALOG_ID` на строку)
- Настраиваемый шаблон сообщения с BB-кодами Bitrix24

## Установка

### 1. Скопировать плагин в папку `sentry`

При сборке Docker-образа Sentry в контейнер попадает только содержимое папки `sentry/` из репозитория [self-hosted](https://github.com/getsentry/self-hosted). Скопируйте **весь репозиторий плагина** (корень, где лежит `setup.py`) в эту папку:

```bash
# из корня репозитория self-hosted
cp -r /path/to/sentry-bitrix24 sentry/sentry_bitrix24
```

Итоговая структура:

```
self-hosted/
└── sentry/
    ├── Dockerfile
    ├── enhance-image.sh
    ├── sentry_bitrix24/      ← скопированный плагин
    │   ├── setup.py
    │   └── sentry_bitrix24/
    │       ├── __init__.py
    │       └── plugin.py
    └── ...
```

Важно: путь в `pip install` указывает на **корень с `setup.py`**, а не на `plugin.py`.

### 2. Добавить установку в `enhance-image.sh`

```bash
cp sentry/enhance-image.example.sh sentry/enhance-image.sh
```

В `sentry/enhance-image.sh`:

```bash
#!/bin/bash
set -euo pipefail

pip install /usr/src/sentry/sentry_bitrix24
```

### 3. Пересобрать образ и запустить Sentry

```bash
./install.sh
docker compose up -d
```

Проверка:

```bash
docker compose exec web pip show sentry-bitrix24
```

### Установка без пересборки образа

Если плагин уже скопирован в `sentry/sentry_bitrix24/` на хосте (папка смонтирована в контейнер как `/etc/sentry/`):

```bash
docker compose exec web pip install /etc/sentry/sentry_bitrix24
docker compose restart web worker post-process-forwarder-errors
```

После обновления кода плагина:

```bash
docker compose exec web pip install --force-reinstall /etc/sentry/sentry_bitrix24
docker compose restart web worker post-process-forwarder-errors
```

### Установка из PyPI

Если пакет опубликован на [pypi.org](https://pypi.org/), в `enhance-image.sh` достаточно:

```bash
pip install sentry-bitrix24
```

## Настройка Bitrix24

### 1. Входящий вебхук

В Bitrix24: **Разработчикам → Другое → Входящий вебхук**.

Выдайте права **«Создание и управление чат-ботами (imbot)»**.

Скопируйте базовый URL:

```
https://example.bitrix24.ru/rest/1/your-webhook-token/
```

### 2. Регистрация чат-бота

После регистрации бота Bitrix24 выдаёт:

| Параметр | Поле в плагине | Пример |
|----------|----------------|--------|
| `BOT_ID` | Bot ID | `123` |
| `CLIENT_ID` (код бота) | Client ID | `your-bot-client-id` |

### 3. Добавьте бота в чат

Бот должен быть участником чата. Для группового чата используйте `chat{id}`, например `chat12345`.

### Проверка вебхука

Рабочий запрос (GET):

```
https://example.bitrix24.ru/rest/1/your-webhook-token/imbot.message.add.json?BOT_ID=123&CLIENT_ID=your-bot-client-id&DIALOG_ID=chat12345&MESSAGE=Привет!
```

Или POST (так отправляет плагин):

```bash
curl -X POST 'https://example.bitrix24.ru/rest/1/your-webhook-token/imbot.message.add' \
  -H 'Content-Type: application/json' \
  -d '{
    "BOT_ID": "123",
    "CLIENT_ID": "your-bot-client-id",
    "DIALOG_ID": "chat12345",
    "MESSAGE": "Тест из Sentry"
  }'
```

## Настройка плагина в Sentry

Плагин настраивается **отдельно для каждого проекта**:

1. Откройте **Settings** нужного проекта.
2. Перейдите в **Legacy Integrations**.
3. Включите **Bitrix24 Notifications**.
4. На странице **Configure plugin** заполните поля:

| Поле | Пример |
|------|--------|
| **Bitrix24 webhook URL** | `https://example.bitrix24.ru/rest/1/your-webhook-token/` |
| **Bot ID** | `123` |
| **Client ID** | `your-bot-client-id` |
| **Dialog IDs** | `chat12345` |
| **Message Template** | (см. ниже) |

Для другого проекта Sentry повторите шаги 1–4 с другим `Dialog IDs`.

### Плейсхолдеры шаблона

| Плейсхолдер | Описание |
|-------------|----------|
| `{project_name}` | Название проекта |
| `{url}` | Ссылка на issue в Sentry |
| `{title}` | Заголовок issue |
| `{message}` | Текст ошибки |
| `{culprit}` | Culprit |
| `{tag[level]}` | Значение тега |

### Шаблон по умолчанию

```
[B][Sentry][/B] {project_name} {tag[level]}: [B]{title}[/B]
[CODE]{message}[/CODE]
[URL={url}]{url}[/URL]
```

## Примечания

- Используется метод `imbot.message.add` (не `imbot.v2`), так как Bitrix24 выдаёт `BOT_ID` + `CLIENT_ID`, а не `botToken`.
- Один бот и один вебхук могут обслуживать все проекты — меняется только `Dialog IDs` в настройках каждого проекта.
- Плагин использует legacy plugin API Sentry. Для Sentry 23.9.1 это должно работать.

## Лицензия

MIT
