itd-chatbot-sdk 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- itd_chatbot_sdk-1.0.0/.github/assets/banner.png +0 -0
- itd_chatbot_sdk-1.0.0/.github/assets/refresh-token.jpeg +0 -0
- itd_chatbot_sdk-1.0.0/AGENTS.md +46 -0
- itd_chatbot_sdk-1.0.0/CHANGELOG.md +9 -0
- itd_chatbot_sdk-1.0.0/CLAUDE.md +1 -0
- itd_chatbot_sdk-1.0.0/CONTRIBUTING.md +9 -0
- itd_chatbot_sdk-1.0.0/GIT_WORKFLOW.md +24 -0
- itd_chatbot_sdk-1.0.0/LICENSE +23 -0
- itd_chatbot_sdk-1.0.0/MANIFEST.in +8 -0
- itd_chatbot_sdk-1.0.0/PKG-INFO +123 -0
- itd_chatbot_sdk-1.0.0/README.md +91 -0
- itd_chatbot_sdk-1.0.0/RELEASING.md +56 -0
- itd_chatbot_sdk-1.0.0/SECURITY.md +7 -0
- itd_chatbot_sdk-1.0.0/dev.md +52 -0
- itd_chatbot_sdk-1.0.0/docs/API_REFERENCE.md +61 -0
- itd_chatbot_sdk-1.0.0/docs/AUTH.md +39 -0
- itd_chatbot_sdk-1.0.0/docs/GETTING_STARTED.md +111 -0
- itd_chatbot_sdk-1.0.0/docs/PUBLISHING.md +109 -0
- itd_chatbot_sdk-1.0.0/docs/ROUTE_INVENTORY.md +239 -0
- itd_chatbot_sdk-1.0.0/docs/USAGE.md +170 -0
- itd_chatbot_sdk-1.0.0/examples/commands.py +22 -0
- itd_chatbot_sdk-1.0.0/examples/echo.py +34 -0
- itd_chatbot_sdk-1.0.0/examples/refresh_test_bot.py +97 -0
- itd_chatbot_sdk-1.0.0/examples/test_bot.py +210 -0
- itd_chatbot_sdk-1.0.0/itd_bot/__init__.py +17 -0
- itd_chatbot_sdk-1.0.0/itd_bot/auth.py +254 -0
- itd_chatbot_sdk-1.0.0/itd_bot/client.py +825 -0
- itd_chatbot_sdk-1.0.0/itd_bot/dispatcher.py +197 -0
- itd_chatbot_sdk-1.0.0/itd_bot/errors.py +62 -0
- itd_chatbot_sdk-1.0.0/itd_bot/formatting.py +73 -0
- itd_chatbot_sdk-1.0.0/itd_bot/rate_limits.py +119 -0
- itd_chatbot_sdk-1.0.0/itd_chatbot_sdk.egg-info/PKG-INFO +123 -0
- itd_chatbot_sdk-1.0.0/itd_chatbot_sdk.egg-info/SOURCES.txt +46 -0
- itd_chatbot_sdk-1.0.0/itd_chatbot_sdk.egg-info/dependency_links.txt +1 -0
- itd_chatbot_sdk-1.0.0/itd_chatbot_sdk.egg-info/requires.txt +17 -0
- itd_chatbot_sdk-1.0.0/itd_chatbot_sdk.egg-info/top_level.txt +1 -0
- itd_chatbot_sdk-1.0.0/pyproject.toml +63 -0
- itd_chatbot_sdk-1.0.0/setup.cfg +4 -0
- itd_chatbot_sdk-1.0.0/tests/test_client.py +116 -0
- itd_chatbot_sdk-1.0.0/tests/test_download_read.py +136 -0
- itd_chatbot_sdk-1.0.0/tests/test_files_and_commands.py +181 -0
- itd_chatbot_sdk-1.0.0/tests/test_formatting.py +48 -0
- itd_chatbot_sdk-1.0.0/tests/test_rate_limits.py +139 -0
- itd_chatbot_sdk-1.0.0/tests/test_refresh_bot.py +106 -0
- itd_chatbot_sdk-1.0.0/tests/test_refresh_session.py +391 -0
- itd_chatbot_sdk-1.0.0/tests/test_release_workflow.py +150 -0
- itd_chatbot_sdk-1.0.0/tests/test_test_bot.py +68 -0
- itd_chatbot_sdk-1.0.0/tests/test_typing_reactions.py +95 -0
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Работа с ITD ChatBot SDK
|
|
2
|
+
|
|
3
|
+
Эти инструкции предназначены агентам и разработчикам репозитория. Уточнения и прямые просьбы пользователя важнее общих правил ниже. Если пользователь не программист, самостоятельно выполните доступные проверки и объясните результат простыми словами, включая ограничения и необходимые ему действия.
|
|
4
|
+
|
|
5
|
+
## Перед началом работы
|
|
6
|
+
|
|
7
|
+
1. Прочитайте этот файл, условия задачи и относящиеся к ней файлы. Сохраните существующие изменения пользователя; не перезаписывайте их и не меняйте документы, которые он попросил сохранить.
|
|
8
|
+
2. Для процесса разработки и чеклиста прочитайте `dev.md`; правила веток, PR и коммитов находятся в `GIT_WORKFLOW.md`, выпуск и публикация - в `RELEASING.md` и `docs/PUBLISHING.md`. `CLAUDE.md` ссылается на этот файл.
|
|
9
|
+
3. `README.md` и `docs/GETTING_STARTED.md` описывают установку и первого бота, `docs/USAGE.md` и `docs/API_REFERENCE.md` - интерфейс, `docs/AUTH.md` - сессию, `docs/ROUTE_INVENTORY.md` - инвентаризация API. При несоответствии проверяйте код и исходный бандл, не предполагайте, что документация или серверная спецификация безошибочны.
|
|
10
|
+
4. Учитывайте расположение репозитория и действующие разрешения окружения. Не создавайте новую копию или ветку без необходимости; проверяйте состояние Git до любых изменений истории.
|
|
11
|
+
|
|
12
|
+
## Устройство и границы проекта
|
|
13
|
+
|
|
14
|
+
- `itd_bot/client.py` содержит синхронный HTTP-клиент `Bot`, методы API, получение событий и передачу файлов. `auth.py` отвечает за обновление access-токена и сохранение ротируемой refresh-cookie. `dispatcher.py` маршрутизирует команды и события, `formatting.py` строит сущности форматирования, `errors.py` и `rate_limits.py` отвечают за ошибки и паузы. Сверяйте актуальную структуру с файлами, она может меняться.
|
|
15
|
+
- `examples/` содержит примеры, `tests/` - автономные проверки с подменой HTTP-транспорта, `.github/workflows/` - CI и релизы, `pyproject.toml` - зависимости и версия.
|
|
16
|
+
- SDK основан на клиентском бандле ИТД и работает от имени пользовательского аккаунта. Наблюдаемое в бандле поведение не является полной спецификацией сервера. Не выдумывайте маршруты, квоты, гарантии доставки, схему полей или идемпотентность; явно сообщайте, что не проверено.
|
|
17
|
+
- При изменениях сохраняйте публичную совместимость, исходные поля JSON и безопасность произвольных путей. Учитывайте обработку 401 и ротацию сессии, блокировки 429, потоковую загрузку файлов, UTF-16 в форматировании, отметку прочтения до обработчика, typing и повторную доставку событий. Курсор сохраняется только после успешной обработки пакета; `ResetRequired` нельзя скрывать.
|
|
18
|
+
- Не повторяйте автоматически операции записи без подтверждённой сервером идемпотентности. Ошибка сети может означать как неудачу, так и выполненную запись. Пауза после 429 не означает знания фактических квот сервера. Разные процессы не координируют локальные ограничения или refresh-сессию.
|
|
19
|
+
- Пишите понятный код с типами и небольшими функциями. Комментарии в коде допустимы только краткие и по делу в неочевидном месте; публичное поведение объясняйте через docstring и документацию по задаче.
|
|
20
|
+
|
|
21
|
+
## Секреты и данные
|
|
22
|
+
|
|
23
|
+
Не публикуйте токены, cookie, заголовки авторизации, файлы сессий, курсоры, личные сообщения, локальные окружения и содержимое `.bundle`. Не выводите секреты в логи или результаты проверок. Тесты и примеры используют только вымышленные значения. Не удаляйте локальные сессии и данные пользователя при уборке. Изменяя `.gitignore` или упаковку, отдельно проверяйте состав Git и архивов; игнорирование само по себе не удаляет секрет из уже существующей истории.
|
|
24
|
+
|
|
25
|
+
## Проверки
|
|
26
|
+
|
|
27
|
+
В установленном окружении проекта выполните проверки, соответствующие изменениям:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
python -m ruff check itd_bot examples tests
|
|
31
|
+
python -m ruff format --check itd_bot examples tests
|
|
32
|
+
python -m pytest -q
|
|
33
|
+
python -m build
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Для упаковки дополнительно проверьте wheel и sdist через `python -m twine check dist/*`, их содержимое и актуальную версию. При изменении API добавляйте значимые автономные тесты: успешный запрос, форму ответа и соответствующие ошибки, включая 401, 429 и сетевой сбой. Реальные запросы и длительные проверки выполняйте только в рамках задачи и с предоставленной пользователем сессией. Сообщайте о неработающих или непройденных проверках, не выдавайте локальные тесты за проверку сервера.
|
|
37
|
+
|
|
38
|
+
## Git и выпуск
|
|
39
|
+
|
|
40
|
+
Основная ветка - `main`; рабочие ветки и Conventional Commits описаны в `GIT_WORKFLOW.md`. Объединение через PR и проверку CI рекомендуется, но правила GitHub настраиваются отдельно. Не создавайте коммиты, теги, релизы и не отправляйте изменения во внешний репозиторий без разрешения пользователя; не используйте принудительный push или переписывание чужой истории. Перед добавлением файлов проверяйте содержимое и секреты.
|
|
41
|
+
|
|
42
|
+
Версия находится в `pyproject.toml`; выпуск делает Python Semantic Release по истории тегов. Первый выпуск без тегов в workflow явно выбирает major 1.0.0. Последующие версии определяются тегом и Conventional Commits, поэтому перед выпуском проверяйте preview, версию пакета, changelog и артефакты. GitHub Release и публикация в PyPI - отдельные действия, требующие настройки владельцем и его явного запроса.
|
|
43
|
+
|
|
44
|
+
## Завершение
|
|
45
|
+
|
|
46
|
+
Расскажите, что изменено и зачем, какие проверки прошли и что осталось неизвестным. Обновляйте примеры и документацию, когда это входит в разрешённый объём задачи; уважайте явный запрет пользователя на их изменение. Не обещайте полной поддержки сервера только по наблюдениям фронтенда.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Участие в разработке
|
|
2
|
+
|
|
3
|
+
Спасибо за интерес к проекту. Начните с [настройки окружения и чеклиста](dev.md), затем прочитайте [правила веток и коммитов](GIT_WORKFLOW.md).
|
|
4
|
+
|
|
5
|
+
Для ошибки зарегистрируйте отдельный [Issue](https://github.com/itd-social/CHATBOT-SDK/issues), укажите версию Python и SDK, шаги воспроизведения, ожидаемый и фактический результат. Для новой возможности опишите задачу, API веб-клиента, на котором основано изменение, и возможные ограничения.
|
|
6
|
+
|
|
7
|
+
Перед pull request запустите Ruff, pytest и сборку из `dev.md`. Добавьте тесты на существенное поведение и обновите документацию. Если проверяли изменение на ИТД, отдельно укажите, что именно проверено на живом сервере.
|
|
8
|
+
|
|
9
|
+
Не размещайте в issue, PR и логах JWT и refresh-токены, файлы сессий, cookie, личные сообщения и содержимое пользовательского бандла. Для проблем безопасности используйте [SECURITY.md](SECURITY.md).
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Git workflow
|
|
2
|
+
|
|
3
|
+
## Ветки и pull request
|
|
4
|
+
|
|
5
|
+
1. Обновите локальную `main` из `origin`, создайте рабочую ветку от актуального состояния: `feat/command-router`, `fix/session-refresh` или `docs/getting-started`.
|
|
6
|
+
2. Вносите связанные изменения и добавляйте тесты и документацию вместе с кодом. Не включайте токены, локальные сессии, архив бандла или собранные файлы.
|
|
7
|
+
3. Запустите проверки из [dev.md](dev.md) и откройте pull request в `main`. В описании укажите проблему, итоговое поведение, проверки и ограничения.
|
|
8
|
+
4. Дождитесь успешного CI и проверки изменений. Рекомендуемый способ объединения — squash merge; итоговый заголовок должен соответствовать Conventional Commits.
|
|
9
|
+
5. После объединения удалите рабочую ветку. Релиз — отдельный шаг по [RELEASING.md](RELEASING.md).
|
|
10
|
+
|
|
11
|
+
Правила защиты `main`, обязательные проверки и права на объединение настраиваются в GitHub: один файл в репозитории их не включает.
|
|
12
|
+
|
|
13
|
+
## Коммиты
|
|
14
|
+
|
|
15
|
+
Формат: `<type>(<scope>): <описание>`. Scope необязателен. Используйте повелительную или описательную форму и объясняйте причину в теле, если она неочевидна.
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
feat(messages): добавить пересылку сообщений
|
|
19
|
+
fix(auth): сохранить ротированную cookie
|
|
20
|
+
docs: добавить пример обработки команд
|
|
21
|
+
chore(deps): обновить httpx
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`feat` и `feature` повышают minor, `fix`, `perf`, `refactor` и `revert` — patch; `!` после типа или `BREAKING CHANGE:` в теле обозначает несовместимое изменение. Пока версия `0.x`, настроен переход на следующий minor для breaking change. Остальные типы могут попасть в changelog, но не обязательно создают новый релиз. Точный результат перед выпуском показывает dry-run.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
Boost Software License - Version 1.0 - August 17th, 2003
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person or organization
|
|
4
|
+
obtaining a copy of the software and accompanying documentation covered by
|
|
5
|
+
this license (the "Software") to use, reproduce, display, distribute,
|
|
6
|
+
execute, and transmit the Software, and to prepare derivative works of the
|
|
7
|
+
Software, and to permit third-parties to whom the Software is furnished to
|
|
8
|
+
do so, all subject to the following:
|
|
9
|
+
|
|
10
|
+
The copyright notices in the Software and this entire statement, including
|
|
11
|
+
the above license grant, this restriction and the following disclaimer,
|
|
12
|
+
must be included in all copies of the Software, in whole or in part, and
|
|
13
|
+
all derivative works of the Software, unless such copies or derivative
|
|
14
|
+
works are solely in the form of machine-executable object code generated by
|
|
15
|
+
a source language processor.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
|
|
20
|
+
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
|
|
21
|
+
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
|
|
22
|
+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
23
|
+
DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
include AGENTS.md CLAUDE.md CHANGELOG.md CONTRIBUTING.md GIT_WORKFLOW.md RELEASING.md SECURITY.md dev.md
|
|
2
|
+
graft docs
|
|
3
|
+
graft examples
|
|
4
|
+
graft .github/assets
|
|
5
|
+
prune .bundle
|
|
6
|
+
prune .venv
|
|
7
|
+
global-exclude __pycache__ *.py[cod] .env .env.*
|
|
8
|
+
global-exclude .itd-session.json .itd-session-* .itd-refresh-session.json .itd-refresh-test-cursor*
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: itd-chatbot-sdk
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Unofficial Python SDK for the ITD messenger
|
|
5
|
+
License-Expression: BSL-1.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/itd-social/CHATBOT-SDK
|
|
7
|
+
Project-URL: Repository, https://github.com/itd-social/CHATBOT-SDK
|
|
8
|
+
Project-URL: Issues, https://github.com/itd-social/CHATBOT-SDK/issues
|
|
9
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: httpx<1,>=0.25
|
|
19
|
+
Provides-Extra: test
|
|
20
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
21
|
+
Provides-Extra: websocket
|
|
22
|
+
Requires-Dist: websocket-client<2,>=1.8; extra == "websocket"
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
25
|
+
Requires-Dist: ruff==0.17.5; extra == "dev"
|
|
26
|
+
Requires-Dist: build<2,>=1; extra == "dev"
|
|
27
|
+
Requires-Dist: websocket-client<2,>=1.8; extra == "dev"
|
|
28
|
+
Provides-Extra: release
|
|
29
|
+
Requires-Dist: python-semantic-release==10.7.0; extra == "release"
|
|
30
|
+
Requires-Dist: build<2,>=1; extra == "release"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
<p align="center">
|
|
36
|
+
<img src="https://img.shields.io/badge/Python-3.10%2B-3776ab" alt="Python 3.10 и новее">
|
|
37
|
+
<img src="https://img.shields.io/badge/version-1.0.0-3776ab" alt="Версия 1.0.0">
|
|
38
|
+
<img src="https://img.shields.io/badge/license-BSL--1.0-blue" alt="Boost Software License 1.0">
|
|
39
|
+
</p>
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
Python SDK для создания чат-ботов в мессенджере ИТД.
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
## Что умеет SDK
|
|
46
|
+
|
|
47
|
+
- Получать сообщения и события, обрабатывать команды `/start` и другие.
|
|
48
|
+
- Отмечать входящие сообщения прочитанными и показывать "печатает" во время обработки.
|
|
49
|
+
- Отправлять и редактировать сообщения, работать с форматированием, реакциями и файлами.
|
|
50
|
+
- Поддерживать сессию через refresh-cookie с автоматическим обновлением access-токена.
|
|
51
|
+
|
|
52
|
+
SDK использует API веб-клиента ИТД и работает от имени пользовательского аккаунта. Это неофициальный проект: права, ограничения и формат событий определяются сервером ИТД. Возможности и ограничения описаны в [документации](docs/USAGE.md).
|
|
53
|
+
|
|
54
|
+
## Установка
|
|
55
|
+
|
|
56
|
+
Python 3.10 или новее:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
python -m pip install itd-chatbot-sdk
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Для работы с WebSocket:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
python -m pip install "itd-chatbot-sdk[websocket]"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Быстрый старт
|
|
69
|
+
|
|
70
|
+
Сначала получите cookie `refresh_token` аккаунта бота и задайте её в переменной `ITD_REFRESH_TOKEN`. [Как получить токен?](docs/AUTH.md#как-получить-refresh_token)
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import os
|
|
74
|
+
|
|
75
|
+
from itd_bot import Bot, Dispatcher
|
|
76
|
+
|
|
77
|
+
with Bot.from_refresh_token(os.environ["ITD_REFRESH_TOKEN"]) as bot:
|
|
78
|
+
profile = bot.api_request("GET", "/api/users/me")
|
|
79
|
+
router = Dispatcher(bot, self_user_id=profile["id"])
|
|
80
|
+
|
|
81
|
+
@router.command("start")
|
|
82
|
+
def start(ctx):
|
|
83
|
+
ctx.reply("Привет! Напишите /echo и текст.")
|
|
84
|
+
|
|
85
|
+
@router.command("echo")
|
|
86
|
+
def echo(ctx):
|
|
87
|
+
ctx.reply(ctx.args or "Добавьте текст после команды")
|
|
88
|
+
|
|
89
|
+
cursor = bot.get_chats(limit=1)["event_seq"]
|
|
90
|
+
router.run_polling(since=cursor)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Этот пример начинает с текущего события и пропускает старые сообщения. Он не сохраняет курсор между запусками. Для настоящего бота сохраняйте курсор после успешной обработки пакета и учитывайте повторную доставку: [пошаговый пример](docs/GETTING_STARTED.md).
|
|
94
|
+
|
|
95
|
+
`Bot.from_refresh_token` по умолчанию сохраняет актуальный токен в `.itd-session.json`. Файл содержит секрет в открытом виде — защитите его и не добавляйте в Git. Сессия может истечь или быть отозвана; [подробнее об авторизации](docs/AUTH.md).
|
|
96
|
+
|
|
97
|
+
## Документация
|
|
98
|
+
|
|
99
|
+
| Раздел | Что внутри |
|
|
100
|
+
|---|---|
|
|
101
|
+
| [Первый бот](docs/GETTING_STARTED.md) | Установка, команды, получение ID и сохранение курсора |
|
|
102
|
+
| [Авторизация](docs/AUTH.md) | Получение refresh-cookie, ротация и восстановление сессии |
|
|
103
|
+
| [Руководство](docs/USAGE.md) | Сообщения, события, файлы, реакции и форматирование |
|
|
104
|
+
| [Справочник API](docs/API_REFERENCE.md) | Методы клиента, обработчики и ошибки |
|
|
105
|
+
| [Примеры](examples/) | Эхо-бот, команды и тестовые боты |
|
|
106
|
+
| [История изменений](CHANGELOG.md) | Изменения по выпущенным версиям |
|
|
107
|
+
| [Публикация в PyPI](docs/PUBLISHING.md) | Как выпустить пакет для установки через pip |
|
|
108
|
+
|
|
109
|
+
## Разработка
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
python -m pip install -e ".[dev]"
|
|
113
|
+
python -m ruff check itd_bot examples tests
|
|
114
|
+
python -m ruff format --check itd_bot examples tests
|
|
115
|
+
python -m pytest -q
|
|
116
|
+
python -m build
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Тесты выполняются без настоящих токенов и подключения к ИТД. Процесс разработки и чеклист — в [dev.md](dev.md), ветки и коммиты — в [GIT_WORKFLOW.md](GIT_WORKFLOW.md), выпуск версии — в [RELEASING.md](RELEASING.md).
|
|
120
|
+
|
|
121
|
+
## Лицензия
|
|
122
|
+
|
|
123
|
+
[Boost Software License 1.0](LICENSE). Лицензия разрешает использовать, изменять и распространять проект, в том числе создавать форки, на условиях, указанных в файле лицензии.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+

|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="https://img.shields.io/badge/Python-3.10%2B-3776ab" alt="Python 3.10 и новее">
|
|
5
|
+
<img src="https://img.shields.io/badge/version-1.0.0-3776ab" alt="Версия 1.0.0">
|
|
6
|
+
<img src="https://img.shields.io/badge/license-BSL--1.0-blue" alt="Boost Software License 1.0">
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
Python SDK для создания чат-ботов в мессенджере ИТД.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
## Что умеет SDK
|
|
14
|
+
|
|
15
|
+
- Получать сообщения и события, обрабатывать команды `/start` и другие.
|
|
16
|
+
- Отмечать входящие сообщения прочитанными и показывать "печатает" во время обработки.
|
|
17
|
+
- Отправлять и редактировать сообщения, работать с форматированием, реакциями и файлами.
|
|
18
|
+
- Поддерживать сессию через refresh-cookie с автоматическим обновлением access-токена.
|
|
19
|
+
|
|
20
|
+
SDK использует API веб-клиента ИТД и работает от имени пользовательского аккаунта. Это неофициальный проект: права, ограничения и формат событий определяются сервером ИТД. Возможности и ограничения описаны в [документации](docs/USAGE.md).
|
|
21
|
+
|
|
22
|
+
## Установка
|
|
23
|
+
|
|
24
|
+
Python 3.10 или новее:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
python -m pip install itd-chatbot-sdk
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Для работы с WebSocket:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
python -m pip install "itd-chatbot-sdk[websocket]"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Быстрый старт
|
|
37
|
+
|
|
38
|
+
Сначала получите cookie `refresh_token` аккаунта бота и задайте её в переменной `ITD_REFRESH_TOKEN`. [Как получить токен?](docs/AUTH.md#как-получить-refresh_token)
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import os
|
|
42
|
+
|
|
43
|
+
from itd_bot import Bot, Dispatcher
|
|
44
|
+
|
|
45
|
+
with Bot.from_refresh_token(os.environ["ITD_REFRESH_TOKEN"]) as bot:
|
|
46
|
+
profile = bot.api_request("GET", "/api/users/me")
|
|
47
|
+
router = Dispatcher(bot, self_user_id=profile["id"])
|
|
48
|
+
|
|
49
|
+
@router.command("start")
|
|
50
|
+
def start(ctx):
|
|
51
|
+
ctx.reply("Привет! Напишите /echo и текст.")
|
|
52
|
+
|
|
53
|
+
@router.command("echo")
|
|
54
|
+
def echo(ctx):
|
|
55
|
+
ctx.reply(ctx.args or "Добавьте текст после команды")
|
|
56
|
+
|
|
57
|
+
cursor = bot.get_chats(limit=1)["event_seq"]
|
|
58
|
+
router.run_polling(since=cursor)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Этот пример начинает с текущего события и пропускает старые сообщения. Он не сохраняет курсор между запусками. Для настоящего бота сохраняйте курсор после успешной обработки пакета и учитывайте повторную доставку: [пошаговый пример](docs/GETTING_STARTED.md).
|
|
62
|
+
|
|
63
|
+
`Bot.from_refresh_token` по умолчанию сохраняет актуальный токен в `.itd-session.json`. Файл содержит секрет в открытом виде — защитите его и не добавляйте в Git. Сессия может истечь или быть отозвана; [подробнее об авторизации](docs/AUTH.md).
|
|
64
|
+
|
|
65
|
+
## Документация
|
|
66
|
+
|
|
67
|
+
| Раздел | Что внутри |
|
|
68
|
+
|---|---|
|
|
69
|
+
| [Первый бот](docs/GETTING_STARTED.md) | Установка, команды, получение ID и сохранение курсора |
|
|
70
|
+
| [Авторизация](docs/AUTH.md) | Получение refresh-cookie, ротация и восстановление сессии |
|
|
71
|
+
| [Руководство](docs/USAGE.md) | Сообщения, события, файлы, реакции и форматирование |
|
|
72
|
+
| [Справочник API](docs/API_REFERENCE.md) | Методы клиента, обработчики и ошибки |
|
|
73
|
+
| [Примеры](examples/) | Эхо-бот, команды и тестовые боты |
|
|
74
|
+
| [История изменений](CHANGELOG.md) | Изменения по выпущенным версиям |
|
|
75
|
+
| [Публикация в PyPI](docs/PUBLISHING.md) | Как выпустить пакет для установки через pip |
|
|
76
|
+
|
|
77
|
+
## Разработка
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
python -m pip install -e ".[dev]"
|
|
81
|
+
python -m ruff check itd_bot examples tests
|
|
82
|
+
python -m ruff format --check itd_bot examples tests
|
|
83
|
+
python -m pytest -q
|
|
84
|
+
python -m build
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Тесты выполняются без настоящих токенов и подключения к ИТД. Процесс разработки и чеклист — в [dev.md](dev.md), ветки и коммиты — в [GIT_WORKFLOW.md](GIT_WORKFLOW.md), выпуск версии — в [RELEASING.md](RELEASING.md).
|
|
88
|
+
|
|
89
|
+
## Лицензия
|
|
90
|
+
|
|
91
|
+
[Boost Software License 1.0](LICENSE). Лицензия разрешает использовать, изменять и распространять проект, в том числе создавать форки, на условиях, указанных в файле лицензии.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Релизный процесс ITD ChatBot SDK
|
|
2
|
+
|
|
3
|
+
Версия хранится в `pyproject.toml`. Для Python-проекта используется [Python Semantic Release](https://python-semantic-release.readthedocs.io/) — аналог release-it, который вычисляет версию из Conventional Commits, обновляет `CHANGELOG.md`, создаёт коммит и тег, собирает пакет и создаёт GitHub Release. Настройки находятся в `pyproject.toml`.
|
|
4
|
+
|
|
5
|
+
## До релиза
|
|
6
|
+
|
|
7
|
+
- Рабочая ветка `main`, актуальный `origin/main`, нет незакоммиченных изменений.
|
|
8
|
+
- Изменения прошли PR и CI; [чеклист разработки](dev.md#чеклист-изменения-sdk) выполнен.
|
|
9
|
+
- В Git нет refresh-токенов, файлов сессий, личных сообщений и бандла.
|
|
10
|
+
- Репозиторий имеет доступный remote `origin`, полную историю и теги. GitHub Actions должна иметь право создавать релизы и отправлять коммиты и теги; правила защиты `main` могут запрещать прямой push для `GITHUB_TOKEN`.
|
|
11
|
+
- Версия пакета в `pyproject.toml` и история тегов согласованы. Это особенно важно перед первым релизом: инструмент определяет предыдущую версию по тегам, а не только по полю `project.version`.
|
|
12
|
+
|
|
13
|
+
Установите инструменты и проверьте проект:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
python -m pip install -e ".[dev,release]"
|
|
17
|
+
python -m ruff check itd_bot examples tests
|
|
18
|
+
python -m ruff format --check itd_bot examples tests
|
|
19
|
+
python -m pytest -q
|
|
20
|
+
python -m build
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Просмотр
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
semantic-release --noop version
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Команда показывает план без изменения файлов, коммитов, тегов и удалённого репозитория. Она требует Git-репозиторий и его историю. Проверьте итоговую версию, список изменений и данные будущего релиза. В Windows для корректной обработки русских текстов перед локальными командами релиза задайте `$env:PYTHONUTF8 = "1"` в PowerShell или `set PYTHONUTF8=1` в cmd.
|
|
30
|
+
|
|
31
|
+
В GitHub можно запустить workflow **Release** вручную на `main`. При `publish=false` (значение по умолчанию) он только запускает проверки и dry-run. При `publish=true` он создаёт релиз: workflow выполняется с `contents: write`, создаёт коммит `chore(release): vX.Y.Z`, тег `vX.Y.Z`, отправляет их в `origin/main`, создаёт GitHub Release и прикрепляет wheel и sdist. Автоматического выпуска при каждом push нет.
|
|
32
|
+
|
|
33
|
+
Если защита ветки не позволяет `GITHUB_TOKEN` отправить релизный коммит, настройте разрешённый для проекта способ выпуска или выполняйте согласованный релизный процесс с нужными правами. Не отключайте защиту ради обхода ошибки.
|
|
34
|
+
|
|
35
|
+
## Версионирование и changelog
|
|
36
|
+
|
|
37
|
+
- `feat` и `feature` - minor; `fix`, `perf`, `refactor` и `revert` - patch. Используйте формат `revert: ...`: стандартное сообщение `Revert ...` само по себе не является Conventional Commit.
|
|
38
|
+
- `!` или `BREAKING CHANGE:` - несовместимое изменение. До `1.0.0` настройка `major_on_zero = false` переводит его на следующий minor.
|
|
39
|
+
- Changelog создаётся на основе коммитов после предыдущего тега. Маркер `<!-- version list -->` в `CHANGELOG.md` нужен инструменту для вставки новых версий.
|
|
40
|
+
|
|
41
|
+
## После выпуска
|
|
42
|
+
|
|
43
|
+
Проверьте GitHub Release, тег, номера версий и оба файла из `dist/`. При ошибке не переписывайте опубликованный тег и не используйте принудительный push: согласуйте исправляющий релиз с командой.
|
|
44
|
+
|
|
45
|
+
## Публикация в PyPI
|
|
46
|
+
|
|
47
|
+
PyPI не вызывается автоматически после GitHub Release. Для отдельного выпуска предусмотрен ручной workflow **Publish to PyPI**. Перед первым запуском:
|
|
48
|
+
|
|
49
|
+
1. Подтвердите, что имя `itd-chatbot-sdk` доступно в PyPI и закреплено за вашим аккаунтом. Лицензия проекта - BSL-1.0.
|
|
50
|
+
2. Настройте в PyPI Trusted Publisher для этого GitHub-репозитория: workflow `publish-pypi.yml`, environment `pypi`. При необходимости задайте в GitHub для environment `pypi` обязательное подтверждение владельца.
|
|
51
|
+
3. Создайте обычный опубликованный GitHub Release с тегом вида `v0.1.0`. Версия в теге должна совпадать с `project.version` в этом коммите.
|
|
52
|
+
4. Запустите **Publish to PyPI** вручную, указав тег. Workflow проверяет опубликованный GitHub Release и совпадение версии, запускает тесты, собирает пакет, выполняет `twine check` и публикует через OIDC. Только стабильные теги `vX.Y.Z` поддерживаются этим workflow.
|
|
53
|
+
|
|
54
|
+
Права доступа к PyPI и настройки Trusted Publisher в данном репозитории не создаются. До их настройки публикация завершится ошибкой. Пакет, выпущенный в PyPI, нельзя считать удаляемым или заменяемым; при ошибке подготовьте исправляющую версию.
|
|
55
|
+
|
|
56
|
+
Пошаговая инструкция с точными параметрами репозитория: [Публикация в PyPI](docs/PUBLISHING.md).
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Безопасность
|
|
2
|
+
|
|
3
|
+
Refresh-cookie и файлы сессий дают доступ к аккаунту. Не прикладывайте их к публичным issue, pull request или журналам CI. Если токен попал в публичный доступ, отзовите соответствующую сессию средствами ИТД и создайте новую.
|
|
4
|
+
|
|
5
|
+
Для сообщения об уязвимости используйте приватное сообщение [автору репозитория](https://itdsocial.com/@itdStatus) или приватное сообщение об уязвимости GitHub, если оно включено в разделе Security. До согласования исправления не раскрывайте подробности публично.
|
|
6
|
+
|
|
7
|
+
SDK хранит refresh-cookie в локальном JSON-файле открытым текстом, если указан `session_path` или используется путь по умолчанию. Меры защиты и ограничения описаны в [документации по авторизации](docs/AUTH.md#хранение-и-ротация).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Разработка ITD ChatBot SDK
|
|
2
|
+
|
|
3
|
+
## Подготовка окружения
|
|
4
|
+
|
|
5
|
+
Нужны Git и Python 3.10+. Клонируйте [репозиторий](https://github.com/itd-social/CHATBOT-SDK) и выполните из его корня:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
python -m venv .venv
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Активируйте окружение: в PowerShell — `.venv\Scripts\Activate.ps1`, в cmd — `.venv\Scripts\activate.bat`, в Linux/macOS — `source .venv/bin/activate`. Затем:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
python -m pip install -e ".[dev,release]"
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Если активация недоступна, вызывайте Python окружения напрямую, например `.venv\Scripts\python.exe -m pytest -q` в Windows.
|
|
18
|
+
|
|
19
|
+
## Структура проекта
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
itd_bot/ HTTP-клиент, авторизация, диспетчер и форматирование
|
|
23
|
+
examples/ рабочие примеры ботов
|
|
24
|
+
examples/refresh_test_bot.py длительная проверка сессии
|
|
25
|
+
tests/ локальные тесты с подменой транспорта
|
|
26
|
+
docs/ руководство, справочник и анализ веб-клиента
|
|
27
|
+
.github/ CI, релиз, Dependabot и изображения
|
|
28
|
+
pyproject.toml зависимости, инструменты и версия пакета
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Проверки перед PR
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
python -m ruff check itd_bot examples tests
|
|
35
|
+
python -m ruff format --check itd_bot examples tests
|
|
36
|
+
python -m pytest -q
|
|
37
|
+
python -m build
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Автоформатирование: `python -m ruff format itd_bot examples tests`. Для конкретного теста используйте `python -m pytest tests/test_refresh_session.py -q`. Тесты запускаются без подключения к ИТД. Для новой серверной операции используйте `httpx.MockTransport` и проверяйте URL, тело, ошибки и состояние после сбоя, а не только успешный ответ.
|
|
41
|
+
|
|
42
|
+
## Чеклист изменения SDK
|
|
43
|
+
|
|
44
|
+
- [ ] Поведение подтверждено бандлом или проверкой с указанием её границ.
|
|
45
|
+
- [ ] Публичная сигнатура и имена полей описаны; совместимость учтена.
|
|
46
|
+
- [ ] При необходимости проверены 401, 429, таймаут, ротация cookie и повторная доставка.
|
|
47
|
+
- [ ] Входящие сообщения отмечаются прочитанными до обработчика; курсор сохраняется после успешного пакета.
|
|
48
|
+
- [ ] Нет токенов, реальных идентификаторов пользователей и содержимого частных сообщений.
|
|
49
|
+
- [ ] Добавлены полезные тесты и обновлены документация с примером.
|
|
50
|
+
- [ ] Ruff, pytest и сборка проходят локально и в CI.
|
|
51
|
+
|
|
52
|
+
Про ветки и Conventional Commits см. [GIT_WORKFLOW.md](GIT_WORKFLOW.md), про версии — [RELEASING.md](RELEASING.md).
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Справочник SDK
|
|
2
|
+
|
|
3
|
+
См. [руководство](USAGE.md) для готовых примеров. Ответы методов — исходные JSON-значения ИТД; стабильность всех полей не гарантируется. `Any` означает, что SDK не преобразует ответ в отдельную модель.
|
|
4
|
+
|
|
5
|
+
## Клиент и ошибки
|
|
6
|
+
|
|
7
|
+
`Bot(token, *, base_url="https://xn--d1ah4a.com", timeout=30.0, client=None)` принимает токен без префикса `Bearer`. Используйте `with Bot(...) as bot:` или вызовите `close()`. Переданный `httpx.Client` остаётся во владении вызывающего кода. `set_token(token)` заменяет access-токен. `Bot.from_refresh_token(refresh_token, session_path=".itd-session.json")` включает автоматическое обновление и сохранение ротаций; `session_path=None` хранит их только в памяти. `refresh_count` — число успешных обновлений в этом экземпляре. Подробнее: [авторизация](AUTH.md).
|
|
8
|
+
|
|
9
|
+
`APIError` содержит `status`, `code`, `errors`, `retry_after`. Ошибки транспорта и таймауты исходят от `httpx`; `ProtocolError` означает неподходящий ответ. `ResetRequired` наследует `ProtocolError` и содержит `response`. В режиме refresh SDK может повторить запрос после HTTP 401 один раз; подробности и ограничения описаны в [авторизации](AUTH.md).
|
|
10
|
+
|
|
11
|
+
## Чаты и сообщения
|
|
12
|
+
|
|
13
|
+
| Метод | Назначение |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `get_chats(limit=None, before=None)` | Страница чатов и курсор событий. |
|
|
16
|
+
| `get_chat(chat_id)`, `get_unread_count()` | Сведения о чате, количество непрочитанных. |
|
|
17
|
+
| `create_direct_chat(user_id)`, `accept_chat(chat_id)` | Создать личный чат, принять запрос. |
|
|
18
|
+
| `set_pinned(chat_id, pinned)`, `set_muted(chat_id, muted)`, `mark_unread(chat_id, unread=True)` | Настройки чата. |
|
|
19
|
+
| `delete_chat(chat_id, for_everyone=False)`, `clear_history(chat_id, for_everyone=False)` | Удаление чата или очистка истории. |
|
|
20
|
+
| `get_messages(chat_id, limit=None, before=None)` | Страница истории сообщений. |
|
|
21
|
+
| `get_messages_around(chat_id, message_id, limit=40)` | История вокруг сообщения. |
|
|
22
|
+
| `send_message(chat_id, text, reply_to_id=None, attachments=None, entities=None, client_message_id=None)` | Отправить сообщение. |
|
|
23
|
+
| `send_message_to_user(user_id, text, attachments=None, entities=None, client_message_id=None)` | Отправить сообщение пользователю. |
|
|
24
|
+
| `send_formatted(chat_id, content, **kwargs)` | Отправить содержимое конструктора `Text`. |
|
|
25
|
+
| `edit_message(chat_id, message_id, text, attachments=None, entities=None)` | Изменить сообщение. |
|
|
26
|
+
| `delete_messages(chat_id, message_ids, for_everyone=False)` | Удалить сообщения. |
|
|
27
|
+
| `forward_messages(chat_id, source_chat_id, message_ids, client_message_ids=None)` | Переслать сообщения. |
|
|
28
|
+
| `mark_read(chat_id, message_id)` | Отметить сообщения прочитанными до указанного. |
|
|
29
|
+
| `send_action(chat_id, action="typing", progress=None)` | Отправить действие; `progress` доступен для `upload_*`, от 0 до 1. |
|
|
30
|
+
| `get_presence(user_id)`, `get_presence_many(user_ids)` | Запросить присутствие. |
|
|
31
|
+
| `mark_voice_heard(chat_id, message_id)`, `get_heard_messages(chat_id, message_ids)` | Работа с отметками прослушивания. |
|
|
32
|
+
|
|
33
|
+
## Файлы
|
|
34
|
+
|
|
35
|
+
- `upload_file(source, filename=None, mime=None, metadata=None, on_progress=None)` загружает путь или `bytes` и возвращает ответ с `fileId`. Максимум клиента — 2 ГиБ, нулевой размер не допускается.
|
|
36
|
+
- `send_file(chat_id, source, text="", filename=None, mime=None, reply_to_id=None, client_message_id=None, metadata=None, on_progress=None)` загружает файл и отправляет его.
|
|
37
|
+
- `get_media(chat_id, category, before=None, limit=None)` и `get_file_links(chat_id, file_ids)` запрашивают сведения о вложениях.
|
|
38
|
+
- `create_file_session()` создаёт файловую сессию в cookie-контейнере клиента.
|
|
39
|
+
- `download_file(chat_id, file_id, destination=None)` получает ссылку и файловую сессию. Без `destination` возвращает `bytes`; при переданном пути записывает данные потоком в новый файл и возвращает `Path`. Существующий файл не перезаписывается. Допускаются ссылки `/v1/chat-files/{uuid}` на настроенном сервере.
|
|
40
|
+
|
|
41
|
+
## Реакции
|
|
42
|
+
|
|
43
|
+
`get_reaction_catalog()` и `get_reactions(chat_id, message_id)` возвращают каталог и состояние. `add_reaction(chat_id, message_id, emoji)` добавляет реакцию к выбранным аккаунтом, предварительно запрашивая состояние. `set_reactions(chat_id, message_id, reactions, *, expected_version, operation_id)` заменяет выбранный набор целиком. При конфликте версии сервер может вернуть 409; автоматического повтора нет.
|
|
44
|
+
|
|
45
|
+
## События и обработчики
|
|
46
|
+
|
|
47
|
+
- `get_updates(since, limit=None)` возвращает пакет событий. При `reset_required` вызывает `ResetRequired`; приложение должно восстановить своё состояние.
|
|
48
|
+
- `poll(since, handler, interval=2.0, on_checkpoint=None)` обрабатывает события последовательно, после полного пакета передаёт новый курсор в `on_checkpoint`. Исключение обработчика прерывает цикл.
|
|
49
|
+
- `websocket_events()` возвращает генератор событий; требуется дополнительная зависимость `[websocket]`. Автоматическое переподключение и восстановление пропусков не реализованы.
|
|
50
|
+
- `Dispatcher(bot, *, self_user_id, username=None, auto_typing=True, typing_interval=4.0)` регистрирует функции через `command(name)`, `on_message` и `on_event(event_type)`. `handle(event)` обрабатывает одно событие, `run_polling(since, **kwargs)` запускает цикл. Сначала отправляется отметка о прочтении входящего сообщения. При ошибке отметки обработчик не вызывается.
|
|
51
|
+
- `CommandContext` предоставляет `bot`, `event`, `message`, `command`, `args`, `chat_id`, а также `reply(text, **kwargs)` и `reply_formatted(content, **kwargs)`.
|
|
52
|
+
|
|
53
|
+
Обработка пакетов и сохранение курсора не являются транзакцией с побочными эффектами: при сбое события могут быть повторены. Текущий typing действует только в зарегистрированных обработчиках Dispatcher.
|
|
54
|
+
|
|
55
|
+
## Форматирование
|
|
56
|
+
|
|
57
|
+
`Text(text="")` строит сообщение. Доступны `add(text, styles=(), url=None)`, `bold`, `italic`, `underline`, `strike`, `code`, `spoiler`, `link`. `build()` возвращает пару `(text, entities)`. `utf16_length(text)` считает длину в единицах UTF-16. Синтаксис Markdown не обрабатывается.
|
|
58
|
+
|
|
59
|
+
## Низкоуровневые запросы
|
|
60
|
+
|
|
61
|
+
`request(method, path, params=None, json=None)` отправляет запрос к `/api/v1/messenger`. `api_request(method, path, params=None, json=None, content=None, files=None, headers=None, raw=False)` обращается к путям `/api/` и `/v1/` настроенного сервера. Только один из `json`, `content`, `files` можно указать одновременно. `raw=True` возвращает успешный `httpx.Response`; перенаправления отключены. Вызывающий код отвечает за корректность экспериментальных запросов.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Длительная сессия через refresh-cookie
|
|
2
|
+
|
|
3
|
+
SDK может работать с refresh-cookie аккаунта и автоматически получать короткоживущий access-токен. На тестовом аккаунте бот отвечал на сообщения, а access-токен обновился несколько раз. Сессия всё равно может закончиться или быть отозвана; тогда понадобится новая cookie.
|
|
4
|
+
|
|
5
|
+
## Как получить refresh_token
|
|
6
|
+
|
|
7
|
+
1. Откройте отдельное окно браузера в режиме инкогнито и войдите в аккаунт бота.
|
|
8
|
+
2. Откройте инструменты разработчика браузера и найдите cookies сайта ИТД (обычно раздел Application / Storage / Cookies). Скопируйте **значение** cookie `refresh_token`, без имени и знака `=`.
|
|
9
|
+
3. После копирования не переходите по страницам и не нажимайте на сайте другие элементы; закройте окно инкогнито, не выходя из аккаунта. Это уменьшает риск, что браузер обновит сессию и скопированное значение устареет. Фоновое обновление тоже возможно, поэтому способ не гарантирует сохранность токена.
|
|
10
|
+
4. Храните значение как секрет. Предпочтительно задать его в переменной окружения `ITD_REFRESH_TOKEN`; не публикуйте токен и не отправляйте его в журнал или репозиторий.
|
|
11
|
+
|
|
12
|
+
Вкладка Network может помочь найти название cookie в заголовках запроса `/api/v1/auth/refresh`:
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
Заголовки уже выполненного запроса могут содержать **старое** значение, если сервер после него обновил cookie. Для запуска копируйте актуальное значение из хранилища cookies браузера; не запускайте новый `/refresh` только ради поиска токена.
|
|
17
|
+
|
|
18
|
+
## SDK
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
import os
|
|
22
|
+
from itd_bot import Bot
|
|
23
|
+
|
|
24
|
+
with Bot.from_refresh_token(os.environ["ITD_REFRESH_TOKEN"], session_path=".itd-session.json") as bot:
|
|
25
|
+
profile = bot.api_request("GET", "/api/users/me")
|
|
26
|
+
print(profile["id"])
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Первый запрос получает access-токен. SDK заранее обновляет его, когда до указанного в JWT срока действия остаётся не более 30 секунд, а при HTTP 401 выполняет refresh и один раз повторяет исходный запрос. При 401 multipart-запрос не повторяется, поскольку его поток может быть уже прочитан. Сетевые ошибки и ответы 429/5xx не приводят к автоматическому повтору запроса SDK. JWT разбирается для срока действия и проверки неизменности `sub`, но SDK не проверяет подпись: он не предназначен для принятия решений об авторизации пользователя.
|
|
30
|
+
|
|
31
|
+
Запрос после 401 повторяется и для операций записи, как в веб-клиенте. Это не гарантия идемпотентности; после обрыва соединения результат операции может быть неизвестен, и такой запрос автоматически не повторяется. Данные загрузки файлов отправляются частями и проходят через тот же механизм обновления. Для скачивания при 401 SDK повторно создаёт файловую сессию. `websocket_events()` получает актуальный токен при подключении, но не переподключается самостоятельно при окончании сессии.
|
|
32
|
+
|
|
33
|
+
## Хранение и ротация
|
|
34
|
+
|
|
35
|
+
По умолчанию SDK создаёт `.itd-session.json` в текущем каталоге и записывает туда актуальное значение refresh-cookie, включая новое значение, если сервер присылает его в `Set-Cookie`. При следующем запуске указывайте ту же исходную переменную `ITD_REFRESH_TOKEN` и тот же путь: SDK использует сохранённое актуальное значение. Если токен другой, используйте отдельный путь; несовпадение приводит к `SessionStorageError`. Файл нельзя отправлять другим или добавлять в Git. Стандартные имена исключены через `.gitignore`, для произвольного пути настройте исключение самостоятельно.
|
|
36
|
+
|
|
37
|
+
Файл содержит **секрет в открытом виде**. На POSIX временный файл создаётся с правами только для владельца; в Windows права зависят от ACL каталога. Разместите файл в защищённой папке. Для хранения только в памяти передайте `session_path=None`; тогда после остановки при ротации первоначальное значение может перестать работать. Ошибка сохранения приводит к `SessionStorageError`; если сервер уже сменил cookie и процесс завершится до сохранения, сессию может понадобиться получить заново.
|
|
38
|
+
|
|
39
|
+
Один объект SDK синхронизирует параллельные обновления потоков; межпроцессной блокировки нет. Не запускайте несколько ботов с одной refresh-сессией или одним файлом одновременно. Не открывайте в браузере тот же токен параллельно с ботом. При сетевом обрыве в момент refresh сервер мог обновить токен, а ответ мог потеряться: восстановление не гарантировано.
|