Metadata-Version: 2.4
Name: harborbot
Version: 1.4.0
Summary: Official Python runtime client for Harbor bots.
Author-email: Harbor Project <harborproject@mail.ru>
License-Expression: MIT
Project-URL: Homepage, https://harborproject.ru/landing
Project-URL: Documentation, https://harborproject.ru/static/landing/docs.html
Project-URL: Changelog, https://harborproject.ru/static/landing/docs.html
Keywords: harbor,harborbot,bot,runtime,chat
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

﻿# Harbor Bot Development

Официальный набор материалов для разработки ботов Harbor.

Главная библиотека для Python называется `HarborBot.py`. Она работает только с bot token и runtime API `/api/bot/v1/...`. Библиотека не поддерживает вход по почте, паролю, пользовательский JWT или автоматизацию обычного аккаунта.

## Что входит в комплект

- [HarborBot.py](HarborBot.py) - совместимый portable-файл для runtime API.
- [harborbot/](harborbot/) - пакетный импорт `from harborbot import HarborBot`.
- [pyproject.toml](pyproject.toml) - описание pip-пакета `harborbot`.
- [START_HERE.md](START_HERE.md) - быстрый старт от токена до первого сообщения.
- [API_REFERENCE.md](API_REFERENCE.md) - структурное описание этапов API.
- [HARBORBOT_PY.md](HARBORBOT_PY.md) - справочник по Python-библиотеке.
- [BOT_PATTERNS.md](BOT_PATTERNS.md) - шаблоны для чат-бота, поддержки, постов и правил сообщества.
- [BOT_RULES.md](BOT_RULES.md) - правила использования сервиса ботов.
- [SECURITY.md](SECURITY.md) - безопасность токенов и данных.
- [CHANGELOG.md](CHANGELOG.md) - изменения релизов SDK.
- [examples/](examples/) - чистые примеры без пользовательской авторизации.
- [LICENSE](LICENSE) - условия использования материалов и библиотеки.

## Коротко о модели доступа

Бот Harbor - это отдельный bot-профиль, а не обычный аккаунт пользователя. Он получает доступ к действиям только после одобрения, выдачи bot token и подключения к нужному месту работы.

Для runtime-запросов используется только такой заголовок:

```http
Authorization: Bot <hbr_bot_live_...>
```

Пользовательский JWT, email, пароль и другие данные аккаунта не должны использоваться для работы бота.

## Быстрый запуск примера

После публикации официальный пакет устанавливается так:

```bash
pip install harborbot
```

Для локальной разработки можно установить библиотеку как pip-пакет из этой папки:

```bash
pip install .
```

После установки импорт остаётся таким же:

```python
from harborbot import HarborBot, HarborRouter
```

Для установки из готового wheel-файла, скачанного с сайта:

```bash
pip install harborbot-1.4.0-py3-none-any.whl
```

Контрольные суммы релиза лежат рядом с файлами загрузки в `SHA256SUMS.txt`.

Собрать wheel и source distribution локально:

```bash
python -m build --no-isolation
```

```bash
python -m venv .venv
pip install -r examples/python/requirements.txt
```

Задайте переменные окружения:

```bash
export HARBOR_BOT_TOKEN="hbr_bot_live_..."
export HARBOR_CHAT_TYPE="community"
```

`HARBOR_CHAT_ID` можно не задавать, если у бота ровно один подходящий target: библиотека получит доступные чаты через `/api/bot/v1/targets` и выберет его автоматически. Если доступных чатов несколько, укажите `HARBOR_CHAT_ID`, `target_id` или `community_id`, чтобы бот не выбрал неверное место работы.

Для приватных чатов сообщества можно не вписывать ID вручную: пригласите бота в нужную комнату, получите pending invite через `bot.get_invites()` и примите его через `bot.accept_invite(invite.target_id)`. После принятия invite сервер создаст активный target для этой комнаты.

Запустите отправку сообщения:

```bash
python examples/python/send_message.py
```

Для Windows PowerShell используйте те же относительные пути:

```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install -r examples\python\requirements.txt
$env:HARBOR_BOT_TOKEN = "hbr_bot_live_..."
$env:HARBOR_CHAT_TYPE = "community"
.\.venv\Scripts\python examples\python\send_message.py
```

## Основные ограничения

- Bot token показывается один раз при создании. Сохраните его безопасно.
- `HarborBot.py` маскирует token в `repr()` и API-ошибках, но token всё равно нельзя выводить в логи вручную.
- Production-token `hbr_bot_live_...` отправляется только на официальный HTTPS-домен Harbor. Для локальных стендов используйте тестовый token `hbr_bot_test_...` и явный параметр `allow_unsafe_base_url=True`.
- Бот может читать и писать только там, где у него есть активный доступ.
- Для чата сообщества нужен доступ к сообществу и к конкретному чату.
- Runtime-методы проверяют scopes. Сейчас для сообщений используются `chat:read` и `chat:write`.
- Polling работает по модели at least once: SDK хранит последний успешно обработанный `message.id` как checkpoint и продолжает чтение через `afterMessageId`. Одно событие может быть доставлено повторно, поэтому ответы и внешние действия лучше делать идемпотентными.
- Для сохранения checkpoint между перезапусками используйте `FileCursorStore` или `SQLiteCursorStore`.
- `run_forever(...)` корректно останавливается через `stop_event`, SIGINT/SIGTERM и закрывает HTTP-сессию.
- Ошибки обработчиков можно направлять через `@router.error_handler` с политикой `retry`, `skip` или `stop`.
- SDK пишет безопасные structured logs через стандартный `logging`: `sdk_version`, `api_version`, `target_type`, `target_id_masked`, `message_id`, `attempt`, `status_code`, `retry_after`, `duration_ms`, `idempotency_key_masked`. Token, текст сообщений и персональные данные не добавляются в логи автоматически.
- Покупки и доступ к наборам стикеров проверяются сервером. Локальное состояние клиента не считается источником прав.
- Передача токенов, ID чатов, ID сообществ, ID участников и других данных третьим лицам запрещена правилами сервиса.

## Минимальный код

```python
from harborbot import FileCursorStore, HarborBot, HarborRouter

bot = HarborBot(
    token="hbr_bot_live_...",
    base_url="https://harborproject.ru",
)

router = HarborRouter()
target = bot.select_target(preferred_type="community")  # если target один


@router.command("ping")
def ping(context):
    context.reply("Pong!", idempotency_key=context.operation_key("reply", "ping"))


@router.error_handler
def on_handler_error(context, error):
    # retry - обработать сообщение снова; skip - подтвердить и перейти дальше; stop - остановить polling
    return "retry"


bot.app(
    target_type=target.runtime_type,
    target_id=target.target_id,
    router=router,
    cursor_store=FileCursorStore("runtime/harborbot-cursors.json"),
).run_forever()
```

Пример для приватной комнаты сообщества по приглашению:

```python
invite = bot.select_invite(preferred_type="community")
target = bot.accept_invite(invite.target_id)
```

Для отладки можно включить стандартный logger:

```python
import logging

logging.basicConfig(level=logging.INFO)
bot = HarborBot("hbr_bot_live_...", logger=logging.getLogger("HarborBot"))
```

Старый portable-импорт `from HarborBot import HarborBot` остаётся рабочим для
проектов, которые кладут одиночный файл `HarborBot.py` рядом с ботом.

## Что читать дальше

Начните с [START_HERE.md](START_HERE.md), затем откройте [HARBORBOT_PY.md](HARBORBOT_PY.md), [BOT_PATTERNS.md](BOT_PATTERNS.md) и [API_REFERENCE.md](API_REFERENCE.md).
