Harbor Project

Документация

HarborBot.py

Официальная документация для разработки ботов Harbor. HarborBot.py работает через bot token и Runtime API v1 без пользовательского JWT, email и пароля.

Быстрый старт Скачать 1.4.0
Безопасно Только bot token
API v1 Стабильные endpoint'ы
Python 3.10+ Package и portable-файл
Bot Token Единственный способ авторизации бота
API v1 /api/bot/v1
Python 3.10+ Современный runtime
Runtime API Polling, cursor, scopes

Структура документации

01 Быстрый старт

Установка, token и запуск первого бота.

 02 Авторизация и токены

Bot token, scopes и запрет пользовательского JWT.

 03 Чаты и сообщения

Отправка, чтение, cursor и обработчики.

 04 Открытые API

Runtime endpoint'ы, targets, scopes и headers.

 05 Ошибки

401, 403, 404, 409, 429 и повторные попытки.

 06 Шаблоны ботов

Чат, поддержка, посты и правила сообщества.

 07 Правила

Данные, токены, ID и ограничения платформы.

 08 Доставка и логи

At least once, idempotency и безопасная диагностика.

Быстрый старт

После публикации пакет можно установить напрямую из Python Package Index. pip install распакует библиотеку в site-packages, после чего импорт будет работать из любого проекта этого окружения. 

pip install harborbot

Если вы скачали wheel-файл с сайта Harbor, установите его по локальному пути: 

pip install C:\Users\You\Downloads\harborbot-1.4.0-py3-none-any.whl

Portable-вариант тоже доступен: скачайте HarborBot.py и положите файл рядом с main.py вашего бота.

HarborBot.py 1.4.0 · Python 3.10+ · Harbor Bot API v1 · SHA-256 wheel: e5d57740e9ade6ee8fcc52602b3c2074080b47dfc77a9a300fbde397bf65a4b7 · все суммы

Для приватного чата сообщества ID можно не вводить вручную: пригласите бота в комнату, примите pending invite через SDK и используйте возвращённый target для polling. 

from harborbot import FileCursorStore, HarborBot, HarborRouter

bot = HarborBot(token="YOUR_BOT_TOKEN")
router = HarborRouter()
target = bot.select_target(preferred_type="community")

# Для приватной комнаты можно принять invite:
# invite = bot.select_invite(preferred_type="community")
# target = bot.accept_invite(invite.target_id)

@router.command("start")
def start(context):
    context.reply(
        "Привет! Я бот Harbor",
        idempotency_key=context.operation_key("reply", "start"),
    )

@router.error_handler
def on_error(context, error):
    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()

Почему HarborBot.py

Только bot token Никаких пользовательских JWT, email, паролей и OAuth-потоков.
Безопасные scopes Бот получает только те права, которые были выбраны и одобрены.
Надёжный polling Checkpoint через afterMessageId, Retry-After и защита от потери сообщений при ошибке callback.
Понятные ошибки Отдельные исключения для авторизации, прав, конфликтов и rate limits.
Graceful shutdown Остановка через stop_event, SIGINT/SIGTERM и закрытие HTTP-сессии.
Handler policy @router.error_handler возвращает retry, skip или stop.
Structured logs Безопасные поля SDK без token, приватного текста и персональных данных.

Гарантия доставки

Polling работает по модели at least once: одно событие может быть доставлено повторно, если callback упал или процесс остановился до сохранения checkpoint. Обработчики должны быть идемпотентными. 

context.reply(
    "Готово",
    idempotency_key=context.operation_key("reply", "done"),
)

Безопасные логи

SDK добавляет structured-поля в LogRecord.extra: sdk_version, api_version, target_id_masked, message_id, attempt, status_code, retry_after, duration_ms и idempotency_key_masked.

Bot token, текст приватных сообщений и персональные данные не попадают в логи автоматически.

Компоненты API

HarborBot Основной клиент: token auth, targets, messages, polling и app loop.
Chat API Глобальные чаты и универсальные методы чтения и отправки сообщений.
Community API Комнаты сообщества, сообщения и доступ только через одобренные scopes.
Targets Автоопределение доступных чатов без ручного ввода ID, если target один.
Router Команды, текстовые обработчики, контекст ответа и игнор сообщений бота.
CommandContext Ответы, say/reply и operation_key для idempotency headers.
Exceptions Иерархия ошибок и обработка повторных попыток.

Открытые API

Что доступно разработчикам

Для внешней разработки Harbor публикует Bot Runtime API v1. Он работает только по bot token, проверяет выданные scopes и не требует пользовательского входа. Остальные клиентские механики приложения не считаются публичным API для ботов.

01 Авторизация

Каждый runtime-запрос отправляется с заголовком Authorization: Bot <token>. SDK также передаёт User-Agent, X-Harbor-SDK-Version и X-Harbor-API-Version.

02 Targets

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

03 Invites

GET /api/bot/v1/invites показывает pending-приглашения в личные комнаты сообщества, а POST /api/bot/v1/invites/{roomId}/accept превращает приглашение в активный target.

04 Универсальные сообщения

GET /api/bot/v1/messages и POST /api/bot/v1/messages подходят для ботов, которые работают с target из списка и не хотят отдельно собирать пути для global/community.

05 Глобальные чаты

Для прямой работы с глобальным чатом доступны GET /api/bot/v1/global-chats/{chatId}/messages и POST /api/bot/v1/global-chats/{chatId}/messages.

06 Чаты сообщества

Для комнаты сообщества используются GET /api/bot/v1/community-chat-rooms/{roomId}/messages и POST /api/bot/v1/community-chat-rooms/{roomId}/messages. Эти методы не дают скрытых прав управления пространством.

07 Cursor и polling

Чтение поддерживает take, beforeUtc, afterMessageId и cursor. В polling SDK хранит последний успешно обработанный message.id и продолжает чтение через afterMessageId.

08 Scopes

Сейчас публичный runtime сообщений проверяет chat:read и chat:write. Бот должен запрашивать только те права, которые нужны его сценарию.

09 Ошибки и лимиты

SDK различает 401, 403, 404, 409 и 429, соблюдает Retry-After, повторяет безопасные GET при временных сбоях и не повторяет POST автоматически. 

GET  /api/bot/v1/targets
GET  /api/bot/v1/invites
POST /api/bot/v1/invites/{roomId}/accept
GET  /api/bot/v1/messages?targetType=community&targetId=...&take=50&afterMessageId=...
POST /api/bot/v1/messages
GET  /api/bot/v1/global-chats/{chatId}/messages
POST /api/bot/v1/global-chats/{chatId}/messages
GET  /api/bot/v1/community-chat-rooms/{roomId}/messages
POST /api/bot/v1/community-chat-rooms/{roomId}/messages

Runtime API v1

Все runtime-запросы идут через /api/bot/v1. SDK отправляет Authorization: Bot ..., X-Harbor-SDK-Version и X-Harbor-API-Version. 

GET /api/bot/v1/targets
GET /api/bot/v1/invites
POST /api/bot/v1/invites/{roomId}/accept
GET /api/bot/v1/messages?targetType=community&targetId=...&afterMessageId=...
POST /api/bot/v1/messages

Ошибки и retry

GET-запросы повторяются при временных сетевых ошибках, 502, 503, 504 и 429 с учётом Retry-After. Поддерживается числовой формат и HTTP-date. POST не повторяется автоматически, чтобы не создавать дубли сообщений. 

except HarborBotRateLimitError as exc:
    print(exc.retry_after_seconds)
except HarborBotApiError as exc:
    print(exc.status_code, exc.code)

Шаблоны ботов

starter_bot/main.py Базовый запуск, config.py и handler.py.
chat_bot.py Команды и ответы в чате сообщества.
support_bot.py Первичная поддержка пользователей и маршрутизация вопросов.
community_rules_bot.py Подсказки по правилам и мягкие предупреждения.

Правила и безопасность

Запрещено передавать bot token, публиковать секреты, использовать пользовательскую авторизацию и распространять данные, полученные через API: ID чата, ID сообщества, ID участников и другие технические данные.

Разработчик может использовать сторонние библиотеки, собственные обёртки, внешний AI/API и вспомогательные инструменты, если бот соблюдает правила Harbor, scopes и rate limits.

Создайте своего бота в Harbor

Начните с token auth, выберите нужный target и подключайте полезные сценарии для чатов и сообществ.

Открыть быстрый старт