clean pybotx

Author: p1p1daster

.github/workflows/python-app.yml

@@ -43,6 +43,7 @@ jobs:
 
       - name: Run linters
         run: |
+          poetry run python scripts/generate_botx_facets.py --check
           poetry run ./scripts/lint
 
   docs-lint:

README.md

@@ -232,12 +232,9 @@ collector = HandlerCollector()
 @collector.sync_smartapp_event
 async def handle_sync_smartapp_event(
     event: SmartAppEvent, bot: Bot,
-) -> BotAPISyncSmartAppEventResultResponse:
+) -> SyncSmartAppEventResult:
     print(f"Got sync smartapp event: {event}")
-    return BotAPISyncSmartAppEventResultResponse.from_domain(
-        data={},
-        files=[],
-    )
+    return SyncSmartAppEventResult(data={}, files=[])
 ```
 
 

docs/adapters.md

@@ -0,0 +1,46 @@
+# Веб-адаптеры
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from pybotx import Bot, wrap_asgi_app
+from pybotx.presentation.fastapi import FastAPIAdapter
+
+adapter = FastAPIAdapter(bot, verify_requests=True)
+app = FastAPI(title="Todo Bot")
+app.include_router(adapter.router)
+app = wrap_asgi_app(app, bot)
+```
+
+Если не используете `wrap_asgi_app`, подключите lifecycle вручную:
+
+```python
+app.add_event_handler("startup", bot.startup)
+app.add_event_handler("shutdown", bot.shutdown)
+```
+
+## aiohttp
+
+```python
+from aiohttp import web
+from pybotx.presentation.aiohttp import AiohttpAdapter
+
+adapter = AiohttpAdapter(bot, verify_requests=True)
+app = web.Application()
+app.add_routes(adapter.routes)
+```
+
+## Django Ninja (ASGI)
+
+```python
+from ninja import NinjaAPI
+from pybotx.presentation.django_ninja import DjangoNinjaAdapter
+
+api = NinjaAPI()
+adapter = DjangoNinjaAdapter(bot, verify_requests=True)
+api.add_router("/", adapter.router)
+```
+
+Для ASGI убедитесь, что `bot.startup()` и `bot.shutdown()` вызываются в lifecycle.
+

docs/architecture.md

@@ -0,0 +1,66 @@
+# Архитектура и слои
+
+## Модель слоёв
+
+Мы придерживаемся 4 слоёв и строгого направления зависимостей:
+
+1. Domain
+2. Application
+3. Infrastructure
+4. Presentation
+
+Зависимости направлены только сверху вниз. Domain не зависит ни от чего. Application зависит от Domain. Infrastructure и Presentation зависят от Application и Domain. Контракты разделены на inbound и outbound, чтобы убрать боковые зависимости.
+
+## Что где живёт
+
+### Domain
+
+- Чистые бизнес-модели и value objects
+- Доменные порты и ошибки
+- Модели и builders сообщений
+- Доменная логика виджетов
+- Утилиты для текста и упоминаний
+
+### Application
+
+- Фасад бота
+- Handler collectors
+- WidgetFactory и WidgetSession
+- Оркестрация use-cases
+
+### Infrastructure
+
+- HTTP клиенты и retry policy
+- Реализация BotX API
+- JWT encoder и verifier
+- Хранилища и adapters
+- AttachmentFactory implementation
+
+### Presentation
+
+- Web adapters
+- DTO для входящих payloads
+- Framework-specific роутинг и lifecycle
+
+## Контракты
+
+Контракты разделены на inbound и outbound, чтобы убрать зависимость domain от транспортных DTO.
+
+- Inbound: presentation payloads
+- Outbound: infrastructure API payloads
+
+## Порты и адаптеры
+
+Все внешние зависимости accessed через порты. Infrastructure реализует адаптеры этих портов.
+
+Примеры:
+
+- `WidgetStateStorePort` -> `InMemoryWidgetStateStore` / `RedisWidgetStateStore`
+- `JwtEncoderPort` -> `PyJwtEncoder`
+- `JwtVerifierPort` -> `PyJwtVerifier`
+- `HttpClientPort` -> `HttpxClientAdapter` / `AioHttpClientAdapter`
+
+## DI границы
+
+DI делается только в контейнерах. Все runtime настройки прокидываются в `container.config`.
+

docs/attachments.md

@@ -0,0 +1,39 @@
+# AttachmentFactory
+
+`AttachmentFactory` изолирует I/O и даёт удобные методы для создания `OutgoingAttachment`.
+
+## From bytes
+
+```python
+attachment = await attachment_factory.from_bytes(
+    b"hello",
+    filename="hello.txt",
+)
+```
+
+## From file path
+
+```python
+attachment = await attachment_factory.from_path("/path/to/file.txt")
+```
+
+## From file object
+
+```python
+from io import BytesIO
+
+buffer = BytesIO(b"content")
+attachment = await attachment_factory.from_file(buffer, filename="demo.txt")
+```
+
+## Использование с builder
+
+```python
+message = (
+    OutgoingMessageBuilder(bot_id=bot_id, chat_id=chat_id, body="file")
+    .with_file(attachment)
+    .build()
+)
+await bot.send(message=message)
+```
+

docs/bot.md

@@ -0,0 +1,59 @@
+# Bot API
+
+Основные методы `Bot` и ключевые изменения.
+
+## Reply и edit sugar
+
+Без contextvars и без ручного проброса ID.
+
+```python
+await bot.reply_to(
+    message,
+    body="Thanks!",
+)
+
+await bot.edit_from(
+    message,
+    body="Updated text",
+)
+```
+
+## Bulk операции
+
+### Bulk send
+
+```python
+messages = [
+    OutgoingMessageBuilder(...).build(),
+    OutgoingMessageBuilder(...).build(),
+]
+result = await bot.bulk_send(messages=messages, max_concurrency=5)
+```
+
+### Bulk reply
+
+```python
+messages = [
+    ReplyMessageBuilder.for_incoming_message(message, body="one").build(),
+    ReplyMessageBuilder.for_incoming_message(message, body="two").build(),
+]
+result = await bot.bulk_reply(messages=messages, max_concurrency=3)
+```
+
+### Bulk с общими MessageOptions
+
+Bulk операции принимают `options`. Значения в отдельных сообщениях имеют приоритет над общими.
+
+```python
+options = MessageOptions(silent_response=True, send_push=False)
+result = await bot.bulk_send(messages=messages, options=options)
+```
+
+## Request verification
+
+`RequestVerifier` доступен как публичный интерфейс и может быть заменён через DI.
+
+## Логирование
+
+Логгер можно инжектить через контейнер. Порт логгера поддерживает `enable()` и `disable()`.
+

docs/bot_command_link.md

@@ -0,0 +1,29 @@
+# Bot Command Link
+
+`build_bot_command_link` генерирует ссылку, которая открывает чат с ботом и
+отправляет ему команду. Это удобно для внешних UI, SmartApp или админ‑панелей.
+
+## Пример
+
+```python
+from pybotx import build_bot_command_link
+
+link = build_bot_command_link(
+    huid=bot_huid,
+    command="/start",
+    body="/start",
+)
+```
+
+## Параметры
+
+- `huid`: UUID бота (его HUID)
+- `command`: команда, например `/start` или `/help`
+- `body`: текст сообщения (если указан `command`, `body` обязателен)
+- `host`: по умолчанию `xlnk.ms`
+- `scheme`: по умолчанию `https`
+
+## Рекомендации
+
+- Храните ссылку в UI и показывайте пользователю только при необходимости.
+- Команда должна быть валидной BotX командой.

docs/botx_api.md

@@ -0,0 +1,15 @@
+# BotX API
+
+Высокоуровневый интерфейс представлен через `Bot`. Низкоуровневый API реализован в `HttpBotXApi` и строится через `BotXApiMethodFactory`.
+
+Рекомендуемый путь работы:
+
+- Использовать методы `Bot`
+- Использовать builders и bulk операции
+- Использовать `MessageOptions` для единообразного API
+
+Если нужны transport DTO:
+
+- Inbound contracts для входящих payloads
+- Outbound contracts для исходящих API payloads
+

docs/builders.md

@@ -0,0 +1,84 @@
+# Message Builders и Options
+
+## MessageOptions
+
+`MessageOptions` упаковывает delivery-опции в один объект.
+
+```python
+from pybotx import MessageOptions
+
+options = MessageOptions(
+    silent_response=True,
+    markup_auto_adjust=True,
+    stealth_mode=True,
+    send_push=False,
+    ignore_mute=True,
+)
+```
+
+## OutgoingMessageBuilder
+
+```python
+from pybotx import OutgoingMessageBuilder
+
+message = (
+    OutgoingMessageBuilder(bot_id=bot_id, chat_id=chat_id, body="Hi!")
+    .silent()
+    .auto_adjust_buttons()
+    .stealth()
+    .no_push()
+    .force_notification()
+    .build()
+)
+
+await bot.send(message=message)
+```
+
+`with_options` применяет `MessageOptions` к builder.
+
+```python
+message = OutgoingMessageBuilder(bot_id=bot_id, chat_id=chat_id, body="Hi")
+message = message.with_options(options).build()
+```
+
+## ReplyMessageBuilder
+
+### From incoming message
+
+```python
+builder = ReplyMessageBuilder.for_incoming_message(message, body="Reply text")
+reply = builder.with_options(options).build()
+await bot.reply(message=reply)
+```
+
+### Explicit sync_id
+
+```python
+builder = ReplyMessageBuilder.for_incoming(message, body="Reply", sync_id=sync_id)
+reply = builder.build()
+```
+
+## EditMessageBuilder
+
+### From source sync id
+
+```python
+builder = EditMessageBuilder.for_incoming_source_id(message)
+edit = builder.with_body("Updated text").build()
+await bot.edit(message=edit)
+```
+
+### Clear helpers
+
+```python
+edit = (
+    EditMessageBuilder.for_incoming_source_id(message)
+    .clear_body()
+    .clear_metadata()
+    .clear_bubbles()
+    .clear_keyboard()
+    .clear_file()
+    .build()
+)
+```
+