Imported from XpycTee/smsru_api (AGENTS.md). Install upstream with npx skills add XpycTee/smsru_api. Copyright stays with the author.

smsru_api AGENTS

О проекте

smsru_api — Python-библиотека для работы с API sms.ru.

Основные публичные клиенты:

• Client
• AsyncClient

Документация хранится в README.md и каталоге docs/. Проверки и сценарии верификации находятся в tests/.

Структура репозитория

• smsru_api/ — основная реализация библиотеки.
• tests/ — unit- и live-тесты.
• README.md — быстрый старт и обзор публичного API.
• docs/ — подробная локальная документация по возможностям библиотеки.

Правила работы

• Перед изменениями изучай затронутый код и существующие тесты.
• Сохраняй parity между sync- и async-API: изменения в Client обычно должны быть согласованы с AsyncClient.
• Не меняй публичные сигнатуры и поведение без явной причины.
• Если меняется поведение, обновляй unit-тесты.
• Если меняется публичное API, примеры, ограничения или пользовательские сценарии, обновляй README.md и релевантные файлы в docs/.
• Live-тесты не использовать по умолчанию; запускать их только при явной необходимости.
• Не трогай секреты, .env и чувствительные локальные настройки.

Проверки

• Используй локальное виртуальное окружение из .venv.
• Предпочитай запуск команд через .venv/bin/python, .venv/bin/pytest и .venv/bin/pip.
• Базовая команда проверки: .venv/bin/python -m pytest.
• При необходимости установить тестовые зависимости: .venv/bin/python -m pip install -e ".[test]".
• Не полагайся на системный Python, если можно использовать .venv.
• Для smoke-проверки опубликованной TestPyPI-версии в Docker сначала ставь runtime-зависимости из основного PyPI, затем сам пакет из TestPyPI без зависимостей: docker run --rm -v "$PWD/tests:/work/tests:ro" -w /work python:3.12-slim sh -lc 'python -m pip install --no-cache-dir --index-url https://pypi.org/simple httpx && python -m pip install --no-cache-dir --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple --no-deps smsru_api==<version> && python -m unittest tests/test_smsru.py'
• Для TestPyPI prerelease-версий используй фактический version string из индекса, например 1.4b1.dev23284998435, а не только git tag.
• Если pip install не проходит из-за таймаутов, ошибок соединения или No matching distribution found при обращении к pypi.org или test.pypi.org, уточни у пользователя, включен ли у него VPN или не блокирует ли его сеть доступ к индексам PyPI: это может напрямую влиять на результат проверки.

Коммиты

• Формат commit message: type(scope): text.
• Допустимые типы: feat, fix, docs, refactor, test, chore.
• Примеры:
  • fix(client): preserve managed sync behavior
  • test(api): cover multi number normalization
  • docs(readme): clarify venv usage

Release Changelog

• Changelog для GitHub Release должен описывать только изменения, влияющие на пользовательский опыт библиотеки.
• Не включай в changelog внутренние изменения CI, release pipeline, packaging-инфраструктуры, служебные правки workflow и прочие изменения, которые не меняют пользовательское поведение библиотеки.
• Включай только то, что влияет на публичный API, поведение Client/AsyncClient, исключения, валидацию, ограничения, примеры использования, документацию по пользовательским сценариям, поддерживаемые версии Python и заметные исправления пользовательских сценариев.
• Если изменение затрагивает только тесты, CI, внутренний рефакторинг или метаданные сборки и не влияет на пользователя, не упоминай его в release changelog.
• Если изменение смешанное, выноси в changelog только пользовательскую часть без упоминания внутренней технической кухни.
• Формулировки должны быть ориентированы на эффект для пользователя: что добавлено, что исправлено, что изменилось в поведении, что нужно учесть при обновлении.
• При оценке уровня релиза ориентируйся на пользовательский эффект: major — явная несовместимость, minor — новые возможности или заметные совместимые улучшения, patch — исправления и небольшие совместимые корректировки.

Рекомендуемый шаблон:

# Установка

```bash
pip install smsru-api==X.Y.Z
```

## Добавлено

- ...

## Изменено

- ...

## Исправлено

- ...

## Что учесть при обновлении

- ...

**Full Changelog**: https://github.com/XpycTee/smsru_api/compare/<prev_tag>...<new_tag>

• Разделы Изменено и Что учесть при обновлении добавляй только если там есть полезный пользовательский смысл.
• Если релиз почти целиком состоит из исправлений, можно оставить только Добавлено/Исправлено и Full Changelog.
• Не перечисляй коммиты механически; сначала сгруппируй их по пользовательскому эффекту.

Режимы работы

• implementation — внесение кодовых изменений с обязательной проверкой влияния на sync/async parity, тесты и документацию.
• review — поиск дефектов, регрессий, нарушений обратной совместимости и пропущенных тестов.
• docs-update — синхронизация README.md и docs/ с текущим поведением и публичным API.

Завершение задачи

• Код и тесты согласованы между собой.
• Sync/async parity сохранен.
• Документация не расходится с реализацией.
• Проверки из .venv проходят или явно указано, что именно не удалось проверить.

Законы

1. Агент не может причинить вред проекту или своим бездействием допустить, чтобы проекту был причинён вред.
2. Агент должен повиноваться всем приказам, которые даёт человек, кроме тех случаев, когда эти приказы противоречат Первому Закону.
3. Агент должен заботиться о своей безопасности в той мере, в которой это не противоречит Первому и Второму Законам.