zenmoney-python 0.7.0__tar.gz

zenmoney_python-0.7.0/.dockerignore

@@ -0,0 +1,21 @@
+*
+!pyproject.toml
+!README.md
+!CHANGELOG.md
+!LICENSE
+!MANIFEST.in
+!requirements.build.txt
+!docs/
+!docs/**
+!examples/
+!examples/**
+!src/
+!src/**
+!tests/
+!tests/**
+**/__pycache__
+!scripts/
+!scripts/*.py
+!scripts/*.sh
+!Dockerfile
+!.dockerignore

zenmoney_python-0.7.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Изменения
+
+## 0.7.0 — 17 октября 2026
+
+- Дистрибутив переименован в zenmoney-python; импорт zenmoney_api сохранён.
+- Добавлены wheel/sdist, проверка Twine, контроль содержимого и SHA256SUMS.
+- Подготовлен CI, который проверяет установленный пакет и сохраняет сборки.
+- Автоматической публикации, push и создания тегов нет.
+
+## 0.6.1 — 16 октября 2026 (подготовлено локально)
+
+- OAuthClient и AsyncOAuthClient сохраняют HTTPX-транспорт между обменом кода
+  и обновлением токена. Добавлены close/aclose, контекстные менеджеры и is_closed;
+  закрытый экземпляр отклоняет запросы с ClientClosedError.
+- Добавлены регрессии sync/async с транспортом, недоступным после закрытия,
+  и типизированные примеры управления OAuth-клиентом.
+- Docker-проверки: 260 тестов, строгий mypy, покрытие 99%. Настоящий API
+  не вызывался; пакет не опубликован.
+
+## Проверки 0.6.0 — 13 октября 2026
+
+- Подтверждены настоящим API 18 базовых операций, включая возвраты, разбиение
+  расхода, все направления долгов, переводы и суммы VND.
+- Добавлена проверка баланса после каждого шага, долговых движений и повторного
+  upsert одного UUID без дубля; документированы правила возвратов и переводов.
+- OAuth-регистрация исключена из обязательной приёмки с готовым Bearer-токеном.
+- Усилены локальные проверки сценариев приёмки, диагностики и очистки.
+
+## 0.6.0 — 13 октября 2026
+
+- Проведена живая приёмка на отдельном тестовом аккаунте; тестовые данные убраны.
+- Добавлены текущие поля Account, Tag, Merchant, Budget и ReminderMarker.
+- Добавлены полные формы каталога entities.account/tag/merchant, учитывающие
+  обязательные поля API, отсутствующие в старой wiki.
+- Добавлен явный Docker-сценарий приёмки с локальным журналом, привязкой пользователя,
+  остановкой после неподтверждённой записи и удалением только своих UUID.
+- Шаблон всех переменных тестового подключения; токен остаётся локально вне Git.
+
+## 0.5.0 — 13 октября 2026
+
+- Удалены namespace zenimport_zenmoney и тесты прикладных ограничений.
+- Дизайн SDK независим от требований совместимости ZenImport.
+- Decimal сериализуется точно как JSON-число и используется для десятичных ответов.
+- Явный lifecycle: закрытые клиенты не открываются повторно, есть is_closed.
+- AsyncOAuthClient больше не наследует синхронный OAuthClient.
+- Типизированные публичные методы и параметры builders; строгая проверка mypy.
+- Поддержка Mapping/Sequence, копирование запросов, предсказуемые ошибки JSON.
+- Реальный UTF-8 проверяется до разбора; бесконечные/circular значения запрещены.
+
+## 0.4.0 — 13 октября 2026
+
+- Выделен самостоятельный проект ZenMoneyAPI.
+- Добавлен namespace zenmoney_api: sync/async diff, CRUD через diff и suggest.
+- Добавлены типы всех документированных сущностей, builders переводов/долгов,
+  обновление полных объектов с сохранением неизвестных полей, удаления и бюджет.
+- OAuth code/refresh, state validation; явное управление токенами.
+- Совместимость zenimport_zenmoney сохранена для прежнего backend.
+- Автономная Docker-сборка wheel, контрактные и локальные HTTP-тесты.
+
+## Исходная версия 0.3.0
+
+Извлечена из ZenImport. Чтение diff, ограниченная запись категорий и обычных
+операций; полный набор nullable-полей создания, исправляющий HTTP 400.

zenmoney_python-0.7.0/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim-bookworm@sha256:54c85f3c47607a77f32adec749d3c81d1348bf25833671f512b26a9b6d778cb3 AS wheel
+WORKDIR /build
+COPY requirements.build.txt ./
+RUN python -m pip install --no-cache-dir -r requirements.build.txt
+# Allowlisted context: source/docs only, never local secrets or state.
+COPY . .
+ARG SOURCE_DATE_EPOCH=0
+ENV SOURCE_DATE_EPOCH=$SOURCE_DATE_EPOCH
+RUN python -m build --no-isolation --outdir /artifacts \
+    && python -m twine check --strict /artifacts/* \
+    && python scripts/release_artifacts.py /artifacts \
+    && python -m pip wheel --no-cache-dir --wheel-dir /wheels '.[test]' \
+    && cp /artifacts/*.whl /wheels/
+
+FROM scratch AS artifact
+COPY --from=wheel /artifacts/ /
+
+FROM python:3.12-slim-bookworm@sha256:54c85f3c47607a77f32adec749d3c81d1348bf25833671f512b26a9b6d778cb3 AS test
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 COVERAGE_FILE=/tmp/.coverage
+COPY --from=wheel /wheels /wheels
+RUN python -m pip install --no-cache-dir --no-index --find-links=/wheels 'zenmoney-python[test]' \
+    && python -m pip check && rm -r /wheels
+WORKDIR /tests
+COPY tests ./
+COPY scripts/live_validation.py scripts/live_basic.py scripts/live_categories.py /tools/
+USER 10001:10001
+CMD ["sh", "-c", "python -m mypy --strict --cache-dir=/tmp/mypy -p zenmoney_api && python -m mypy --strict --cache-dir=/tmp/mypy /tests/typing_contract.py && python -m pytest -q -p no:cacheprovider --cov=zenmoney_api --cov-report=term-missing /tests"]

zenmoney_python-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Vasilev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zenmoney_python-0.7.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md CHANGELOG.md
+include Dockerfile .dockerignore requirements.build.txt
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include scripts *.py *.sh
+global-exclude *.pyc
+global-exclude .env
+global-exclude .env.*
+prune .local
+prune .idea

zenmoney_python-0.7.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: zenmoney-python
+Version: 0.7.0
+Summary: Independent sync and async Python client for the public ZenMoney API
+License-Expression: MIT
+Project-URL: Repository, https://github.com/vaslv/zenmoney-python
+Project-URL: Issues, https://github.com/vaslv/zenmoney-python/issues
+Project-URL: Documentation, https://github.com/vaslv/zenmoney-python/blob/main/README.md
+Keywords: zenmoney,finance,api,asyncio
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: simplejson<4,>=3.19
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: pytest-cov<8,>=6; extra == "test"
+Requires-Dist: mypy<2,>=1.15; extra == "test"
+Requires-Dist: types-simplejson<4,>=3.19; extra == "test"
+Dynamic: license-file
+
+# zenmoney-python
+
+Самостоятельная Python-библиотека публичного HTTP API ZenMoney. Проект находится
+рядом с ZenImport и развивается независимо. Distribution: `zenmoney-python`,
+импорт: `zenmoney_api`, версия 0.7.0. Python 3.12+, HTTPX 0.28.x, simplejson для точных JSON-чисел.
+
+## Возможности
+
+- Синхронный и асинхронный клиент: полная и инкрементальная синхронизация diff,
+  forceFetch, создание/обновление/удаление пользовательских сущностей.
+- Счета, категории, получатели, операции, бюджеты, напоминания и планируемые
+  операции; чтение системных справочников. Типы полей для редактора в `models`.
+- Функции создания дохода, расхода, перевода, долговой операции; сохранение
+  оригинальных сумм/валют, нескольких категорий и неизвестных полей при обновлении.
+- Suggest: один объект или список; OAuth code exchange и явное обновление токена.
+- Без автоматических повторов записи, скрытого хранения данных или зависимости
+  от UI/банков. Единственный публичный namespace — `zenmoney_api`.
+
+Область покрытия и честные ограничения: [docs/coverage.md](docs/coverage.md).
+Сценарии расходов, возвратов, долгов и переводов: [docs/basic-operations.md](docs/basic-operations.md).
+
+## Установка
+
+Готовые wheel, sdist и SHA256SUMS доступны в [GitHub Releases](https://github.com/vaslv/zenmoney-python/releases).
+Установка версии 0.7.0 из GitHub (Python 3.12+):
+
+```sh
+python -m pip install "https://github.com/vaslv/zenmoney-python/releases/download/v0.7.0/zenmoney_python-0.7.0-py3-none-any.whl"
+```
+
+Пакет ещё не загружен в PyPI. Установка из исходников: `python -m pip install .`.
+Для собственной сборки выполните `sh scripts/build.sh`: в `dist/` появятся wheel,
+sdist и SHA256SUMS. Twine проверяет метаданные; wheel собирается из sdist.
+Имя репозитория и дистрибутива — `zenmoney-python`, Python-import — `zenmoney_api`.
+Прежнее локальное имя `zenmoney-api-client` больше не используется; перед
+переходом в существующем окружении удалите старый дистрибутив или создайте чистое
+окружение, чтобы два пакета не владели одним namespace.
+
+Порядок первого GitHub-релиза и интеграции приложений: [docs/publication.md](docs/publication.md).
+
+## Чтение
+
+```python
+import os
+from zenmoney_api import Client
+
+with Client(os.environ['ZENMONEY_TOKEN']) as api:
+    initial = api.read_diff()  # cursor=0 — первоначальная синхронизация
+    # Сначала атомарно сохраните сущности и удаления, затем курсор в своей БД.
+    cursor = initial['serverTimestamp']
+    changes = api.read_diff(cursor)
+    accounts = api.read_diff(cursor, force_fetch=['account'])
+```
+
+Клиент сохраняет неизвестные поля в словарях; `Diff.raw_json` содержит исходный
+ответ. Целые числа читаются как `int`, десятичные — как `Decimal`. Для денег
+используйте `Decimal('1.23')` или целые числа VND: при отправке они остаются
+JSON-числами без округления через float. `float` принимается, но уже возникшую
+в нём погрешность SDK исправить не может. NaN/Infinity и не-JSON объекты отклоняются
+до запроса. SDK не пересчитывает валюты. Обычный `json.dumps` не сериализует Decimal;
+для исходного ответа используйте `Diff.raw_json`, для подготовленных объектов —
+`zenmoney_api.protocol.encode_json`.
+
+```python
+from zenmoney_api import AsyncClient
+
+async def load(token):
+    async with AsyncClient(token) as api:
+        return await api.read_diff()
+```
+
+Используйте контекстный менеджер либо `close()` / `aclose()` для освобождения
+соединений. Закрытый клиент не используется повторно: он вызывает `ClientClosedError`;
+создайте новый экземпляр. `is_closed` показывает состояние. Один экземпляр
+асинхронного клиента используйте в одном event loop. Параметр `timeout` принимает
+секунды, `httpx.Timeout` или явно отключённый таймаут `None`.
+
+## Подготовка и отправка
+
+```python
+from zenmoney_api import transactions as tx
+
+operation = tx.expense(user=123, account='account-id', instrument=1,
+    amount=100000, date='2026-10-13', categories=['category-id'], payee='Shop')
+# Сохраните operation и его UUID до отправки. Повтор не должен создавать новый UUID.
+# Выполнить запись, когда вызывающее приложение готово:
+# result = api.upsert('transaction', [operation], cursor)
+# Затем повторно получите данные и проверьте наличие/содержимое операции.
+```
+
+`transaction(...)` формирует общий объект; `income`, `expense`, `transfer`, `debt`
+упрощают типовые случаи. Примеры: [examples/operations.py](examples/operations.py).
+`update(fetched_object, tag=[...])` копирует полный объект с сохранением полей.
+
+`api.diff(cursor, changes={'account': [...], 'tag': [...], 'transaction': [...]},
+deletions=[...])` позволяет передать несколько типов сущностей одним запросом.
+`upsert(kind, entities, cursor)` — удобная обёртка.
+Для новых объектов каталога есть полные формы с актуальными полями:
+`entities.account(user=..., title=..., instrument=...)`, `entities.tag(...)`,
+`entities.merchant(...)`. Полученный объект можно передать в upsert.
+Для loan/deposit задайте параметры срока и процентов; системный debt-счёт
+следует получать из diff, а не создавать повторно. **Передавайте полные сущности,
+не patch**. Низкоуровневый интерфейс проверяет структуру, идентификаторы, timestamps
+и JSON, но не подменяет серверную проверку всех полей. Ограничения/пакетирование
+определяет вызывающее приложение, скрытого лимита в 20 записей в общем SDK нет.
+
+`deletion(kind, id, user=..., now=...)` создаёт удаление по ID. Для бюджета с
+составным ключом используйте `clear_budget` и `upsert('budget', ...)`.
+Мягкое удаление операции — `update(operation, deleted=True)`.
+
+`api.suggest({'payee': 'Shop'})` или список объектов возвращает подсказки API,
+не изменяя записи.
+
+## OAuth (необязательно)
+
+Для diff/suggest достаточно готового Bearer-токена в Client/AsyncClient.
+Регистрация приложения и собственный OAuth не требуются для использования SDK.
+Методы ниже предназначены для владельцев уже выданных реквизитов приложения;
+их живая проверка не является условием приёмки основного API.
+
+
+```python
+import secrets
+from zenmoney_api import OAuthClient, callback_code
+
+with OAuthClient('registered-client-id', 'client-secret', 'https://your-app/callback') as oauth:
+    state = secrets.token_urlsafe(32)  # сохраните в сессии до открытия URL
+    url = oauth.authorization_url(state=state)
+    # code = callback_code(received_callback_url, expected_state=state)
+    # token = oauth.exchange_code(code)
+    # if token.refresh_token is not None:
+    #     refreshed = oauth.refresh(token.refresh_token)
+```
+
+Для async есть независимый `AsyncOAuthClient` с теми же аргументами:
+используйте `async with`, а `exchange_code` и `refresh` вызывайте с `await`.
+OAuth-клиенты переиспользуют HTTPX-клиент и переданный транспорт между запросами.
+При работе без контекстного менеджера вызовите `close()` / `await aclose()`.
+Оба способа освобождают открытый HTTPX-клиент и его транспорт; повторное закрытие
+безопасно. После закрытия `is_closed` равен `True`, а обмен кода, обновление токена
+и повторный вход в контекст вызывают `ClientClosedError`. Создайте новый экземпляр
+для следующего сеанса. `AsyncOAuthClient` используйте в рамках одного event loop.
+SDK не поднимает callback-сервер, не регистрирует приложение, не хранит токены
+и не обновляет их автоматически. Если refresh-ответ не содержит нового
+refresh_token, приложение сохраняет прежний. `Token.__repr__` скрывает токены.
+State проверяется до обмена code; привязка callback к сессии — задача приложения.
+
+## Ошибки и подтверждение записи
+
+`HTTPError.status_code`, `TransportError`, `ResponseError` не включают тело ответа
+и токен. HTTP 200 не гарантирует принятия всех изменений: более новый `changed`
+на сервере может победить. После записи требуется отдельное чтение и сверка;
+при неопределённом результате нельзя создавать другой UUID и слепо повторять.
+Синхронизация БД, пользовательское подтверждение, журнал отправок и reconciliation
+принадлежат приложению, а не SDK.
+
+## Разработка и Docker
+
+```sh
+sh scripts/test.sh
+sh scripts/build.sh
+```
+
+Тесты используют установленный wheel без дерева исходников, без сети и без
+настоящих токенов. Есть проверка реального HTTP на локальном тестовом сервере.
+Тестовый образ проверяет строгую типизацию mypy, типовые примеры использования
+публичного API и выводит покрытие. Сборка требует доступа к реестру образов и PyPI.
+
+## Переход с 0.4
+
+Версия 0.5 намеренно меняет контракт: `zenimport_zenmoney` удалён, десятичные
+числа ответа теперь Decimal, закрытый клиент не открывается повторно. Для записи
+используйте `diff`/`upsert`, для типовых объектов — `transactions`.
+Старые приложения следует адаптировать после приёмки SDK; их ограничения
+не определяют дизайн библиотеки.
+[Архитектура](docs/architecture.md) · [Покрытие API](docs/coverage.md) ·
+[Проверка на настоящем API](docs/live-validation.md) · [История](CHANGELOG.md).
+
+
+## Живая приёмка
+
+[Результаты проверки на тестовом аккаунте](docs/live-results.md).
+Для собственного отдельного тестового аккаунта скопируйте `.env.example` в `.env`
+и заполните ZENMONEY_TEST_TOKEN. Шаблон содержит также все необязательные переменные
+OAuth. Файл не попадает в Git и образ Docker.
+
+`sh scripts/live-check.sh` выполняет только чтение. `--write` явно включает запись
+искусственных данных и требует первоначально пустого отдельного аккаунта;
+`--soft-delete` и `--cleanup` работают только с UUID сохранённого тестового журнала.
+После ошибки автоматического повтора нет. `--resume` разрешает только повторную
+сверку и продолжение подтверждённых шагов, без повторения неизвестной записи.
+Завершённый очищенный журнал не используется для нового запуска.
+Для нового запуска задайте другой путь `--journal /state/new-run.json`.
+
+`--write --basic --journal /state/basic-run.json` проверяет согласованный базовый
+набор операций, баланс после каждого шага, долговые движения и отсутствие дубля
+при явной записи того же UUID. `--cleanup --journal /state/basic-run.json`
+убирает тестовые объекты; `--inspect` выводит только названия отличающихся полей.

zenmoney_python-0.7.0/README.md

@@ -0,0 +1,198 @@
+# zenmoney-python
+
+Самостоятельная Python-библиотека публичного HTTP API ZenMoney. Проект находится
+рядом с ZenImport и развивается независимо. Distribution: `zenmoney-python`,
+импорт: `zenmoney_api`, версия 0.7.0. Python 3.12+, HTTPX 0.28.x, simplejson для точных JSON-чисел.
+
+## Возможности
+
+- Синхронный и асинхронный клиент: полная и инкрементальная синхронизация diff,
+  forceFetch, создание/обновление/удаление пользовательских сущностей.
+- Счета, категории, получатели, операции, бюджеты, напоминания и планируемые
+  операции; чтение системных справочников. Типы полей для редактора в `models`.
+- Функции создания дохода, расхода, перевода, долговой операции; сохранение
+  оригинальных сумм/валют, нескольких категорий и неизвестных полей при обновлении.
+- Suggest: один объект или список; OAuth code exchange и явное обновление токена.
+- Без автоматических повторов записи, скрытого хранения данных или зависимости
+  от UI/банков. Единственный публичный namespace — `zenmoney_api`.
+
+Область покрытия и честные ограничения: [docs/coverage.md](docs/coverage.md).
+Сценарии расходов, возвратов, долгов и переводов: [docs/basic-operations.md](docs/basic-operations.md).
+
+## Установка
+
+Готовые wheel, sdist и SHA256SUMS доступны в [GitHub Releases](https://github.com/vaslv/zenmoney-python/releases).
+Установка версии 0.7.0 из GitHub (Python 3.12+):
+
+```sh
+python -m pip install "https://github.com/vaslv/zenmoney-python/releases/download/v0.7.0/zenmoney_python-0.7.0-py3-none-any.whl"
+```
+
+Пакет ещё не загружен в PyPI. Установка из исходников: `python -m pip install .`.
+Для собственной сборки выполните `sh scripts/build.sh`: в `dist/` появятся wheel,
+sdist и SHA256SUMS. Twine проверяет метаданные; wheel собирается из sdist.
+Имя репозитория и дистрибутива — `zenmoney-python`, Python-import — `zenmoney_api`.
+Прежнее локальное имя `zenmoney-api-client` больше не используется; перед
+переходом в существующем окружении удалите старый дистрибутив или создайте чистое
+окружение, чтобы два пакета не владели одним namespace.
+
+Порядок первого GitHub-релиза и интеграции приложений: [docs/publication.md](docs/publication.md).
+
+## Чтение
+
+```python
+import os
+from zenmoney_api import Client
+
+with Client(os.environ['ZENMONEY_TOKEN']) as api:
+    initial = api.read_diff()  # cursor=0 — первоначальная синхронизация
+    # Сначала атомарно сохраните сущности и удаления, затем курсор в своей БД.
+    cursor = initial['serverTimestamp']
+    changes = api.read_diff(cursor)
+    accounts = api.read_diff(cursor, force_fetch=['account'])
+```
+
+Клиент сохраняет неизвестные поля в словарях; `Diff.raw_json` содержит исходный
+ответ. Целые числа читаются как `int`, десятичные — как `Decimal`. Для денег
+используйте `Decimal('1.23')` или целые числа VND: при отправке они остаются
+JSON-числами без округления через float. `float` принимается, но уже возникшую
+в нём погрешность SDK исправить не может. NaN/Infinity и не-JSON объекты отклоняются
+до запроса. SDK не пересчитывает валюты. Обычный `json.dumps` не сериализует Decimal;
+для исходного ответа используйте `Diff.raw_json`, для подготовленных объектов —
+`zenmoney_api.protocol.encode_json`.
+
+```python
+from zenmoney_api import AsyncClient
+
+async def load(token):
+    async with AsyncClient(token) as api:
+        return await api.read_diff()
+```
+
+Используйте контекстный менеджер либо `close()` / `aclose()` для освобождения
+соединений. Закрытый клиент не используется повторно: он вызывает `ClientClosedError`;
+создайте новый экземпляр. `is_closed` показывает состояние. Один экземпляр
+асинхронного клиента используйте в одном event loop. Параметр `timeout` принимает
+секунды, `httpx.Timeout` или явно отключённый таймаут `None`.
+
+## Подготовка и отправка
+
+```python
+from zenmoney_api import transactions as tx
+
+operation = tx.expense(user=123, account='account-id', instrument=1,
+    amount=100000, date='2026-10-13', categories=['category-id'], payee='Shop')
+# Сохраните operation и его UUID до отправки. Повтор не должен создавать новый UUID.
+# Выполнить запись, когда вызывающее приложение готово:
+# result = api.upsert('transaction', [operation], cursor)
+# Затем повторно получите данные и проверьте наличие/содержимое операции.
+```
+
+`transaction(...)` формирует общий объект; `income`, `expense`, `transfer`, `debt`
+упрощают типовые случаи. Примеры: [examples/operations.py](examples/operations.py).
+`update(fetched_object, tag=[...])` копирует полный объект с сохранением полей.
+
+`api.diff(cursor, changes={'account': [...], 'tag': [...], 'transaction': [...]},
+deletions=[...])` позволяет передать несколько типов сущностей одним запросом.
+`upsert(kind, entities, cursor)` — удобная обёртка.
+Для новых объектов каталога есть полные формы с актуальными полями:
+`entities.account(user=..., title=..., instrument=...)`, `entities.tag(...)`,
+`entities.merchant(...)`. Полученный объект можно передать в upsert.
+Для loan/deposit задайте параметры срока и процентов; системный debt-счёт
+следует получать из diff, а не создавать повторно. **Передавайте полные сущности,
+не patch**. Низкоуровневый интерфейс проверяет структуру, идентификаторы, timestamps
+и JSON, но не подменяет серверную проверку всех полей. Ограничения/пакетирование
+определяет вызывающее приложение, скрытого лимита в 20 записей в общем SDK нет.
+
+`deletion(kind, id, user=..., now=...)` создаёт удаление по ID. Для бюджета с
+составным ключом используйте `clear_budget` и `upsert('budget', ...)`.
+Мягкое удаление операции — `update(operation, deleted=True)`.
+
+`api.suggest({'payee': 'Shop'})` или список объектов возвращает подсказки API,
+не изменяя записи.
+
+## OAuth (необязательно)
+
+Для diff/suggest достаточно готового Bearer-токена в Client/AsyncClient.
+Регистрация приложения и собственный OAuth не требуются для использования SDK.
+Методы ниже предназначены для владельцев уже выданных реквизитов приложения;
+их живая проверка не является условием приёмки основного API.
+
+
+```python
+import secrets
+from zenmoney_api import OAuthClient, callback_code
+
+with OAuthClient('registered-client-id', 'client-secret', 'https://your-app/callback') as oauth:
+    state = secrets.token_urlsafe(32)  # сохраните в сессии до открытия URL
+    url = oauth.authorization_url(state=state)
+    # code = callback_code(received_callback_url, expected_state=state)
+    # token = oauth.exchange_code(code)
+    # if token.refresh_token is not None:
+    #     refreshed = oauth.refresh(token.refresh_token)
+```
+
+Для async есть независимый `AsyncOAuthClient` с теми же аргументами:
+используйте `async with`, а `exchange_code` и `refresh` вызывайте с `await`.
+OAuth-клиенты переиспользуют HTTPX-клиент и переданный транспорт между запросами.
+При работе без контекстного менеджера вызовите `close()` / `await aclose()`.
+Оба способа освобождают открытый HTTPX-клиент и его транспорт; повторное закрытие
+безопасно. После закрытия `is_closed` равен `True`, а обмен кода, обновление токена
+и повторный вход в контекст вызывают `ClientClosedError`. Создайте новый экземпляр
+для следующего сеанса. `AsyncOAuthClient` используйте в рамках одного event loop.
+SDK не поднимает callback-сервер, не регистрирует приложение, не хранит токены
+и не обновляет их автоматически. Если refresh-ответ не содержит нового
+refresh_token, приложение сохраняет прежний. `Token.__repr__` скрывает токены.
+State проверяется до обмена code; привязка callback к сессии — задача приложения.
+
+## Ошибки и подтверждение записи
+
+`HTTPError.status_code`, `TransportError`, `ResponseError` не включают тело ответа
+и токен. HTTP 200 не гарантирует принятия всех изменений: более новый `changed`
+на сервере может победить. После записи требуется отдельное чтение и сверка;
+при неопределённом результате нельзя создавать другой UUID и слепо повторять.
+Синхронизация БД, пользовательское подтверждение, журнал отправок и reconciliation
+принадлежат приложению, а не SDK.
+
+## Разработка и Docker
+
+```sh
+sh scripts/test.sh
+sh scripts/build.sh
+```
+
+Тесты используют установленный wheel без дерева исходников, без сети и без
+настоящих токенов. Есть проверка реального HTTP на локальном тестовом сервере.
+Тестовый образ проверяет строгую типизацию mypy, типовые примеры использования
+публичного API и выводит покрытие. Сборка требует доступа к реестру образов и PyPI.
+
+## Переход с 0.4
+
+Версия 0.5 намеренно меняет контракт: `zenimport_zenmoney` удалён, десятичные
+числа ответа теперь Decimal, закрытый клиент не открывается повторно. Для записи
+используйте `diff`/`upsert`, для типовых объектов — `transactions`.
+Старые приложения следует адаптировать после приёмки SDK; их ограничения
+не определяют дизайн библиотеки.
+[Архитектура](docs/architecture.md) · [Покрытие API](docs/coverage.md) ·
+[Проверка на настоящем API](docs/live-validation.md) · [История](CHANGELOG.md).
+
+
+## Живая приёмка
+
+[Результаты проверки на тестовом аккаунте](docs/live-results.md).
+Для собственного отдельного тестового аккаунта скопируйте `.env.example` в `.env`
+и заполните ZENMONEY_TEST_TOKEN. Шаблон содержит также все необязательные переменные
+OAuth. Файл не попадает в Git и образ Docker.
+
+`sh scripts/live-check.sh` выполняет только чтение. `--write` явно включает запись
+искусственных данных и требует первоначально пустого отдельного аккаунта;
+`--soft-delete` и `--cleanup` работают только с UUID сохранённого тестового журнала.
+После ошибки автоматического повтора нет. `--resume` разрешает только повторную
+сверку и продолжение подтверждённых шагов, без повторения неизвестной записи.
+Завершённый очищенный журнал не используется для нового запуска.
+Для нового запуска задайте другой путь `--journal /state/new-run.json`.
+
+`--write --basic --journal /state/basic-run.json` проверяет согласованный базовый
+набор операций, баланс после каждого шага, долговые движения и отсутствие дубля
+при явной записи того же UUID. `--cleanup --journal /state/basic-run.json`
+убирает тестовые объекты; `--inspect` выводит только названия отличающихся полей.

zenmoney_python-0.7.0/docs/TASK.md

@@ -0,0 +1,63 @@
+# Задача и порядок работы
+
+Развивать самостоятельную универсальную Python-библиотеку всего документированного
+публичного API ZenMoney. Совместимость с прежним backend/Chrome не ограничивает
+дизайн. К рефакторингу основного проекта возвращаемся после приёмки SDK.
+
+## Реализовано
+
+- [x] Отдельный проект, локальный Git, wheel и независимые Docker-тесты.
+- [x] Единственный публичный namespace zenmoney_api; старый адаптер удалён.
+- [x] Diff всех сущностей, пользовательская запись/удаление и Suggest.
+- [x] Доходы/расходы, переводы, долги, несколько категорий, валютные поля.
+- [x] Sync/async клиенты, явное владение ресурсами, без скрытых повторов.
+- [x] Независимые sync/async OAuth code/refresh и проверка state.
+- [x] Decimal без потери точности; проверка конечных JSON-чисел.
+- [x] Сохранение дополнительных полей и самостоятельные типы аргументов/результатов.
+- [x] Структурная валидация, ошибки, лимиты ответа и реальный локальный HTTP.
+- [x] Строгая проверка типов установленного пакета и примеров клиента в Docker.
+
+## Проверка после код-ревью — 16 октября 2026
+
+- [x] Исправлено преждевременное закрытие OAuth-транспорта между code и refresh.
+- [x] Добавлены close/aclose, контекстные менеджеры и проверка закрытого состояния.
+- [x] Docker: 260 тестов, строгий mypy для пакета и публичных примеров, покрытие 99%.
+- [x] Версия повышена до 0.6.1 для отдельного wheel и обновления vendor backend.
+
+Проверки использовали искусственные ответы и локальный HTTP; настоящий API
+и пользовательские данные не затрагивались. Публикация и Git-теги не выполнялись.
+
+## Живая приёмка
+
+- OAuth code/refresh — необязательная возможность, проверенная локально.
+  Живая проверка без реквизитов приложения недоступна и исключена из обязательной
+  приёмки; готового Bearer-токена достаточно для основного API.
+- [x] Базовые виды записи на тестовом аккаунте: счета cash, категории, переводы,
+      долги, напоминания, бюджеты; повторное чтение и сверка результатов.
+- [x] Отдельная приёмка 18 базовых операций: полный/частичный возврат покупки,
+      разделение расхода, все направления долгов, переводы и VND; балансы,
+      долговые движения и повтор того же UUID без дубля.
+
+Результаты и оставшиеся границы: live-results.md.
+Подготовленный сценарий: live-validation.md. Проверки diff/suggest требуют только тестового
+аккаунта и готового токена; локальные тесты не заменяют их результат.
+
+## После приёмки
+
+Выбрать принятую версию SDK, затем рефакторить backend ZenImport под новый контракт,
+включая Decimal, управление ресурсами, сущности и обработку результатов записи.
+Переделывать SDK под ограничения старого приложения не требуется.
+Отдельное выделение Chrome/банковских адаптеров можно рассмотреть позже.
+
+## Подготовка первого GitHub-релиза — 17 октября 2026
+
+Имя дистрибутива приведено к имени созданного репозитория: `zenmoney-python`
+(по уточнению пользователя), версия 0.7.0, импорт `zenmoney_api` неизменен.
+Добавлены MIT из GitHub, метаданные, wheel/sdist/SHA256SUMS, Twine и CI без
+публикации. Команды и порядок первого релиза: [publication.md](publication.md).
+Origin настроен; push, теги и публикация требуют отдельного разрешения.
+
+Проверка 0.7.0 в Docker: 260 passed, mypy strict, покрытие 99%; wheel/sdist
+прошли Twine strict и проверку содержимого, лицензии и типов. Финансовый код SDK
+не менялся. Gitleaks 8.30.1 и отдельная проверка известных локальных токенов
+не нашли секретов в прежней Git-истории; токены не выводились.