zenmoney-python 0.7.0__py3-none-any.whl

zenmoney_api/__init__.py

@@ -0,0 +1,11 @@
+"""Public ZenMoney HTTP API, independent of applications and banks."""
+from .client import Client, AsyncClient
+from .errors import ZenMoneyError, ClientClosedError, HTTPError, TransportError, ResponseError
+from .oauth import OAuthClient, AsyncOAuthClient, Token, authorization_url, callback_code
+from .protocol import Diff, KINDS, FORCE_FETCH, WRITABLE, DELETABLE, entity_key
+from . import models, transactions, entities
+
+__all__ = ['Client', 'AsyncClient', 'OAuthClient', 'AsyncOAuthClient', 'Token',
+    'authorization_url', 'callback_code', 'ZenMoneyError', 'HTTPError',
+    'TransportError', 'ResponseError', 'ClientClosedError', 'Diff', 'KINDS', 'FORCE_FETCH',
+    'WRITABLE', 'DELETABLE', 'entity_key', 'models', 'transactions', 'entities']

zenmoney_api/client.py

@@ -0,0 +1,167 @@
+"""Synchronous/asynchronous public API clients with explicit resource ownership."""
+from collections.abc import Callable, Mapping, Sequence
+from math import isfinite
+import time
+from typing import Any, Generic, Self, TypeVar, overload
+
+import httpx
+
+from .errors import ClientClosedError, HTTPError, ResponseError, TransportError
+from .protocol import Changes, Diff, EntityData, diff_payload, decode_diff, encode_json, suggest_payload, decode_suggestion
+
+BASE_URL = 'https://api.zenmoney.ru'
+ENDPOINT = BASE_URL + '/v8/diff/'
+Timeout = float | httpx.Timeout | None
+Transport = TypeVar('Transport', httpx.BaseTransport, httpx.AsyncBaseTransport)
+
+
+def validate_timeout(timeout: Timeout) -> None:
+    values = (timeout.connect, timeout.read, timeout.write, timeout.pool) if isinstance(timeout, httpx.Timeout) else (timeout,)
+    if any(value is not None and (type(value) not in (int, float) or not isfinite(value) or value <= 0) for value in values):
+        raise ValueError('Timeouts must be positive finite numbers or None')
+
+
+class _Config(Generic[Transport]):
+    def __init__(self, token: str, *, transport: Transport | None = None,
+                 timeout: Timeout = 60, max_response_bytes: int = 64*1024*1024,
+                 clock: Callable[[], float] = time.time):
+        if not isinstance(token, str) or not token or any(c.isspace() for c in token):
+            raise ValueError('A nonempty bearer token without whitespace is required')
+        if type(max_response_bytes) is not int or max_response_bytes <= 0:
+            raise ValueError('Response limit must be a positive integer')
+        validate_timeout(timeout)
+        self._token = token
+        self._transport: Transport | None = transport
+        self._timeout, self._limit, self._clock = timeout, max_response_bytes, clock
+        self._closed = False
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ClientClosedError('ZenMoney client is closed')
+
+    def _options(self) -> dict[str, Any]:
+        return dict(timeout=self._timeout, transport=self._transport, follow_redirects=False, trust_env=False)
+
+
+class Client(_Config[httpx.BaseTransport]):
+    _http: httpx.Client | None = None
+
+    def __enter__(self) -> Self:
+        self._check_open()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._http is not None:
+                self._http.close()
+                self._http = None
+
+    def _request(self, path: str, payload: Any) -> bytes:
+        self._check_open()
+        content = encode_json(payload)
+        try:
+            if self._http is None:
+                self._http = httpx.Client(**self._options())
+            with self._http.stream('POST', BASE_URL+path, headers={'Authorization': f'Bearer {self._token}', 'Content-Type': 'application/json'}, content=content) as response:
+                if response.status_code != 200:
+                    raise HTTPError(response.status_code)
+                body = bytearray()
+                for chunk in response.iter_bytes():
+                    if len(body)+len(chunk) > self._limit:
+                        raise ResponseError('ZenMoney response exceeds configured limit')
+                    body.extend(chunk)
+                return bytes(body)
+        except httpx.HTTPError:
+            raise TransportError('ZenMoney connection failed') from None
+
+    def diff(self, server_timestamp: int = 0, *, changes: Changes | None = None,
+             deletions: Sequence[Mapping[str, Any]] | None = None,
+             force_fetch: Sequence[str] | None = None) -> Diff:
+        """Exchange complete objects; persist the cursor only after storing returned data."""
+        payload = diff_payload(server_timestamp, int(self._clock()), changes, deletions, force_fetch)
+        return decode_diff(self._request('/v8/diff/', payload), server_timestamp)
+
+    def read_diff(self, server_timestamp: int = 0, *, force_fetch: Sequence[str] | None = None) -> Diff:
+        return self.diff(server_timestamp, force_fetch=force_fetch)
+
+    def upsert(self, kind: str, entities: Sequence[Mapping[str, Any]], server_timestamp: int = 0) -> Diff:
+        """Send complete objects; timestamps resolve conflicts on the server."""
+        return self.diff(server_timestamp, changes={kind: entities})
+
+    def delete(self, deletions: Sequence[Mapping[str, Any]], server_timestamp: int = 0) -> Diff:
+        return self.diff(server_timestamp, deletions=deletions)
+
+    @overload
+    def suggest(self, transactions: Mapping[str, Any]) -> EntityData: ...
+    @overload
+    def suggest(self, transactions: Sequence[Mapping[str, Any]]) -> list[EntityData]: ...
+    def suggest(self, transactions: Mapping[str, Any] | Sequence[Mapping[str, Any]]) -> EntityData | list[EntityData]:
+        payload = suggest_payload(transactions)
+        return decode_suggestion(self._request('/v8/suggest/', payload), payload)
+
+
+class AsyncClient(_Config[httpx.AsyncBaseTransport]):
+    _http: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> Self:
+        self._check_open()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._http is not None:
+                await self._http.aclose()
+                self._http = None
+
+    async def _request(self, path: str, payload: Any) -> bytes:
+        self._check_open()
+        content = encode_json(payload)
+        try:
+            if self._http is None:
+                self._http = httpx.AsyncClient(**self._options())
+            async with self._http.stream('POST', BASE_URL+path, headers={'Authorization': f'Bearer {self._token}', 'Content-Type': 'application/json'}, content=content) as response:
+                if response.status_code != 200:
+                    raise HTTPError(response.status_code)
+                body = bytearray()
+                async for chunk in response.aiter_bytes():
+                    if len(body)+len(chunk) > self._limit:
+                        raise ResponseError('ZenMoney response exceeds configured limit')
+                    body.extend(chunk)
+                return bytes(body)
+        except httpx.HTTPError:
+            raise TransportError('ZenMoney connection failed') from None
+
+    async def diff(self, server_timestamp: int = 0, *, changes: Changes | None = None,
+                   deletions: Sequence[Mapping[str, Any]] | None = None,
+                   force_fetch: Sequence[str] | None = None) -> Diff:
+        payload = diff_payload(server_timestamp, int(self._clock()), changes, deletions, force_fetch)
+        return decode_diff(await self._request('/v8/diff/', payload), server_timestamp)
+
+    async def read_diff(self, server_timestamp: int = 0, *, force_fetch: Sequence[str] | None = None) -> Diff:
+        return await self.diff(server_timestamp, force_fetch=force_fetch)
+
+    async def upsert(self, kind: str, entities: Sequence[Mapping[str, Any]], server_timestamp: int = 0) -> Diff:
+        return await self.diff(server_timestamp, changes={kind: entities})
+
+    async def delete(self, deletions: Sequence[Mapping[str, Any]], server_timestamp: int = 0) -> Diff:
+        return await self.diff(server_timestamp, deletions=deletions)
+
+    @overload
+    async def suggest(self, transactions: Mapping[str, Any]) -> EntityData: ...
+    @overload
+    async def suggest(self, transactions: Sequence[Mapping[str, Any]]) -> list[EntityData]: ...
+    async def suggest(self, transactions: Mapping[str, Any] | Sequence[Mapping[str, Any]]) -> EntityData | list[EntityData]:
+        payload = suggest_payload(transactions)
+        return decode_suggestion(await self._request('/v8/suggest/', payload), payload)

zenmoney_api/entities.py

@@ -0,0 +1,63 @@
+"""Complete catalog objects, including fields required by the current live API."""
+import time
+from copy import deepcopy
+from typing import Any, cast
+from uuid import uuid4
+
+from .models import Account, Tag, Merchant
+from .protocol import EntityData, encode_json, timestamp
+
+
+def _base(user: int, title: str, id: str | None, now: int | None) -> EntityData:
+    if type(user) is not int or user <= 0:
+        raise ValueError('Expected a positive user ID')
+    if not isinstance(title, str) or not title.strip():
+        raise ValueError('Expected a nonempty title')
+    if id is not None and (not isinstance(id, str) or not id):
+        raise ValueError('Expected a nonempty ID')
+    return dict(id=str(uuid4()) if id is None else id, user=user, title=title,
+                changed=timestamp(int(time.time()) if now is None else now))
+
+
+def _extend(result: EntityData, fields: EntityData) -> EntityData:
+    if any(k in fields for k in ('id', 'user', 'title', 'changed')):
+        raise ValueError('Identity fields must use the explicit constructor parameters')
+    result.update(deepcopy(fields))
+    encode_json(result)
+    return result
+
+
+def account(*, user: int, title: str, instrument: int, account_type: str = 'cash',
+            id: str | None = None, now: int | None = None, **fields: Any) -> Account:
+    if type(instrument) is not int or instrument <= 0:
+        raise ValueError('Expected a positive instrument ID')
+    if account_type not in ('cash', 'ccard', 'checking', 'loan', 'deposit', 'emoney'):
+        raise ValueError('Unsupported new account type; use the existing system debt account')
+    result = _base(user, title, id, now)
+    result.update(role=None, instrument=instrument, company=None, type=account_type,
+        syncID=None, balance=0, startBalance=0, creditLimit=None, inBalance=True,
+        savings=False, enableCorrection=False, enableSMS=False, archive=False,
+        private=False, balanceCorrectionType='request', capitalization=None,
+        percent=None, startDate=None, endDateOffset=None, endDateOffsetInterval=None,
+        payoffStep=None, payoffInterval=None)
+    result = _extend(result, fields)
+    if account_type in ('loan', 'deposit') and any(result.get(k) is None for k in
+            ('capitalization', 'percent', 'startDate', 'endDateOffset', 'endDateOffsetInterval')):
+        raise ValueError('Loan/deposit parameters are required')
+    return cast(Account, result)
+
+
+def tag(*, user: int, title: str, id: str | None = None,
+        now: int | None = None, **fields: Any) -> Tag:
+    result = _base(user, title, id, now)
+    result.update(parent=None, icon=None, picture=None, color=None, showIncome=True,
+        showOutcome=True, budgetIncome=True, budgetOutcome=True, required=False,
+        archive=False, staticId=None)
+    return cast(Tag, _extend(result, fields))
+
+
+def merchant(*, user: int, title: str, id: str | None = None,
+             now: int | None = None, **fields: Any) -> Merchant:
+    result = _base(user, title, id, now)
+    result['mcc'] = None
+    return cast(Merchant, _extend(result, fields))

zenmoney_api/errors.py

@@ -0,0 +1,21 @@
+"""Errors contain no response bodies, credentials or financial data."""
+class ZenMoneyError(Exception):
+    pass
+
+
+class TransportError(ZenMoneyError):
+    """The outcome of a write may be unknown. Do not automatically retry."""
+
+
+class ResponseError(ZenMoneyError):
+    pass
+
+
+class HTTPError(ZenMoneyError):
+    def __init__(self, status_code: int):
+        self.status_code = status_code
+        super().__init__(f'ZenMoney HTTP {status_code}')
+
+
+class ClientClosedError(ZenMoneyError):
+    """A closed client cannot be reopened; construct a new instance."""

zenmoney_api/models.py

@@ -0,0 +1,180 @@
+"""Wire field names match the public API. Reads retain all unknown server fields.
+
+TypedDicts help editors; low-level diff performs structural, not full schema validation.
+Use full fetched entities for updates; do not send partial TypedDicts as patches.
+"""
+from typing import TypedDict, Literal, Required
+from decimal import Decimal
+
+Number = int | float | Decimal
+
+class Instrument(TypedDict, total=False):
+    id: int
+    changed: int
+    title: str
+    shortTitle: str
+    symbol: str
+    rate: Number
+
+class Company(TypedDict, total=False):
+    id: int
+    changed: int
+    title: str
+    fullTitle: str | None
+    www: str | None
+    country: str | None
+
+class User(TypedDict, total=False):
+    id: int
+    changed: int
+    login: str | None
+    currency: int
+    parent: int | None
+
+class Entity(TypedDict, total=False):
+    id: str
+    changed: int
+    user: int
+
+class Account(Entity, total=False):
+    private: bool
+    balanceCorrectionType: str
+    role: int | None
+    instrument: int | None
+    company: int | None
+    type: Literal['cash', 'ccard', 'checking', 'loan', 'deposit', 'emoney', 'debt']
+    title: str
+    syncID: list[str] | None
+    balance: Number | None
+    startBalance: Number | None
+    creditLimit: Number | None
+    inBalance: bool
+    savings: bool | None
+    enableCorrection: bool
+    enableSMS: bool
+    archive: bool
+    capitalization: bool | None
+    percent: Number | None
+    startDate: str | None
+    endDateOffset: int | None
+    endDateOffsetInterval: Literal['day', 'week', 'month', 'year'] | None
+    payoffStep: int | None
+    payoffInterval: Literal['month', 'year'] | None
+
+class Tag(Entity, total=False):
+    archive: bool
+    staticId: str | None
+    title: str
+    parent: str | None
+    icon: str | None
+    picture: str | None
+    color: int | None
+    showIncome: bool
+    showOutcome: bool
+    budgetIncome: bool
+    budgetOutcome: bool
+    required: bool | None
+
+class Merchant(Entity, total=False):
+    mcc: int | None
+    title: str
+
+class Movement(Entity, total=False):
+    incomeInstrument: int
+    incomeAccount: str
+    income: Number
+    outcomeInstrument: int
+    outcomeAccount: str
+    outcome: Number
+    tag: list[str] | None
+    merchant: str | None
+    payee: str | None
+    comment: str | None
+
+class Transaction(Movement, total=False):
+    created: int
+    deleted: bool
+    hold: bool | None
+    originalPayee: str | None
+    date: str
+    mcc: int | None
+    reminderMarker: str | None
+    opIncome: Number | None
+    opIncomeInstrument: int | None
+    opOutcome: Number | None
+    opOutcomeInstrument: int | None
+    latitude: Number | None
+    longitude: Number | None
+    viewed: bool
+    qrCode: str | None
+    source: str | None
+    incomeBankID: str | None
+    outcomeBankID: str | None
+
+class Reminder(Movement, total=False):
+    interval: Literal['day', 'week', 'month', 'year'] | None
+    step: int | None
+    points: list[int] | None
+    startDate: str
+    endDate: str | None
+    notify: bool
+
+class ReminderMarker(Movement, total=False):
+    isForecast: bool
+    date: str
+    reminder: str
+    state: Literal['planned', 'processed', 'deleted']
+    notify: bool
+
+class Budget(TypedDict, total=False):
+    isIncomeForecast: bool
+    isOutcomeForecast: bool
+    changed: int
+    user: int
+    tag: str | None
+    date: str
+    income: Number
+    incomeLock: bool
+    outcome: Number
+    outcomeLock: bool
+
+class Deletion(TypedDict):
+    id: str
+    object: str
+    user: int
+    stamp: int
+
+
+class TransactionFields(TypedDict, total=False):
+    """Optional wire fields accepted by the transaction builder."""
+    originalPayee: str | None
+    reminderMarker: str | None
+    opIncome: Number | None
+    opIncomeInstrument: int | None
+    opOutcome: Number | None
+    opOutcomeInstrument: int | None
+    latitude: Number | None
+    longitude: Number | None
+    mcc: int | None
+    hold: bool | None
+    deleted: bool
+    viewed: bool
+    qrCode: str | None
+    source: str | None
+    incomeBankID: str | None
+    outcomeBankID: str | None
+
+
+class BaseTransactionOptions(TransactionFields, total=False):
+    """Shared keywords of all operation builders, excluding the counterparty."""
+    user: Required[int]
+    date: Required[str]
+    categories: list[str] | None
+    comment: str | None
+    merchant: str | None
+    id: str | None
+    now: int | None
+
+
+class TransactionOptions(BaseTransactionOptions, total=False):
+    payee: str | None

zenmoney_api/oauth.py

@@ -0,0 +1,169 @@
+"""Explicit OAuth code exchange/refresh; secrets and tokens have redacted reprs."""
+from dataclasses import dataclass, field
+from typing import Any, Generic, Self, TypeVar
+from urllib.parse import urlencode, urlsplit, parse_qs
+from hmac import compare_digest
+import httpx
+from .client import BASE_URL, Timeout, validate_timeout
+from .errors import ClientClosedError, HTTPError, TransportError, ResponseError
+from .protocol import decode_json
+
+
+def authorization_url(client_id: str, redirect_uri: str, *, state: str) -> str:
+    if not all(isinstance(v, str) and v for v in (client_id, redirect_uri, state)):
+        raise ValueError('client_id, redirect_uri and unpredictable state are required')
+    return BASE_URL + '/oauth2/authorize/?' + urlencode(dict(response_type='code', client_id=client_id, redirect_uri=redirect_uri, state=state))
+
+
+def callback_code(callback_url: str, *, expected_state: str) -> str:
+    if not isinstance(callback_url, str) or not isinstance(expected_state, str) or not expected_state:
+        raise ValueError('Callback URL and expected state are required')
+    query = parse_qs(urlsplit(callback_url).query, keep_blank_values=True)
+    states, codes = query.get('state', []), query.get('code', [])
+    if not expected_state or len(states) != 1 or not compare_digest(states[0].encode(), expected_state.encode()):
+        raise ValueError('OAuth state mismatch')
+    if 'error' in query or len(codes) != 1 or not codes[0]:
+        raise ResponseError('OAuth authorization was not completed')
+    return codes[0]
+
+
+@dataclass(frozen=True)
+class Token:
+    access_token: str = field(repr=False)
+    token_type: str = 'bearer'
+    expires_in: int | None = None
+    refresh_token: str | None = field(default=None, repr=False)
+
+
+def _token(raw: bytes) -> Token:
+    data = decode_json(raw)
+    if not isinstance(data, dict) or not isinstance(data.get('access_token'), str) or not data['access_token'] or any(c.isspace() for c in data['access_token']) or str(data.get('token_type', '')).lower() != 'bearer':
+        raise ResponseError('Invalid OAuth token response')
+    if data.get('expires_in') is not None and (type(data['expires_in']) is not int or data['expires_in'] < 0):
+        raise ResponseError('Invalid OAuth token lifetime')
+    if data.get('refresh_token') is not None and (not isinstance(data['refresh_token'], str) or not data['refresh_token']):
+        raise ResponseError('Invalid refresh token')
+    return Token(data['access_token'], 'bearer', data.get('expires_in'), data.get('refresh_token'))
+
+
+Transport = TypeVar('Transport', httpx.BaseTransport, httpx.AsyncBaseTransport)
+
+
+class _OAuthConfig(Generic[Transport]):
+    def __init__(self, client_id: str, client_secret: str, redirect_uri: str,
+                 *, transport: Transport | None = None, timeout: Timeout = 60):
+        if not all(isinstance(v, str) and v for v in (client_id, client_secret, redirect_uri)):
+            raise ValueError('OAuth application credentials are required')
+        validate_timeout(timeout)
+        self._id, self._secret, self._redirect = client_id, client_secret, redirect_uri
+        self._transport: Transport | None = transport
+        self._timeout = timeout
+        self._closed = False
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ClientClosedError('ZenMoney OAuth client is closed')
+
+    def authorization_url(self, *, state: str) -> str:
+        return authorization_url(self._id, self._redirect, state=state)
+
+    def _form(self, grant_type: str, value: str) -> dict[str, str]:
+        self._check_open()
+        if not isinstance(value, str) or not value:
+            raise ValueError('Nonempty code or refresh token required')
+        form = dict(grant_type=grant_type, client_id=self._id, client_secret=self._secret)
+        if grant_type == 'authorization_code':
+            form.update(code=value, redirect_uri=self._redirect)
+        else:
+            form['refresh_token'] = value
+        return form
+
+
+class OAuthClient(_OAuthConfig[httpx.BaseTransport]):
+    _http: httpx.Client | None = None
+
+    def __enter__(self) -> Self:
+        self._check_open()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._http is not None:
+                self._http.close()
+                self._http = None
+            elif self._transport is not None:
+                self._transport.close()
+
+    def _request(self, form: dict[str, str]) -> Token:
+        self._check_open()
+        try:
+            if self._http is None:
+                self._http = httpx.Client(transport=self._transport, timeout=self._timeout, trust_env=False, follow_redirects=False)
+            with self._http.stream('POST', BASE_URL+'/oauth2/token/', data=form) as response:
+                if response.status_code != 200:
+                    raise HTTPError(response.status_code)
+                body = bytearray()
+                for chunk in response.iter_bytes():
+                    if len(body)+len(chunk) > 1024*1024:
+                        raise ResponseError('OAuth response exceeds limit')
+                    body.extend(chunk)
+                return _token(bytes(body))
+        except httpx.HTTPError:
+            raise TransportError('OAuth connection failed') from None
+
+    def exchange_code(self, code: str) -> Token:
+        return self._request(self._form('authorization_code', code))
+
+    def refresh(self, refresh_token: str) -> Token:
+        return self._request(self._form('refresh_token', refresh_token))
+
+
+class AsyncOAuthClient(_OAuthConfig[httpx.AsyncBaseTransport]):
+    _http: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> Self:
+        self._check_open()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._http is not None:
+                await self._http.aclose()
+                self._http = None
+            elif self._transport is not None:
+                await self._transport.aclose()
+
+    async def _request(self, form: dict[str, str]) -> Token:
+        self._check_open()
+        try:
+            if self._http is None:
+                self._http = httpx.AsyncClient(transport=self._transport, timeout=self._timeout, trust_env=False, follow_redirects=False)
+            async with self._http.stream('POST', BASE_URL+'/oauth2/token/', data=form) as response:
+                if response.status_code != 200:
+                    raise HTTPError(response.status_code)
+                body = bytearray()
+                async for chunk in response.aiter_bytes():
+                    if len(body)+len(chunk) > 1024*1024:
+                        raise ResponseError('OAuth response exceeds limit')
+                    body.extend(chunk)
+                return _token(bytes(body))
+        except httpx.HTTPError:
+            raise TransportError('OAuth connection failed') from None
+
+    async def exchange_code(self, code: str) -> Token:
+        return await self._request(self._form('authorization_code', code))
+
+    async def refresh(self, refresh_token: str) -> Token:
+        return await self._request(self._form('refresh_token', refresh_token))

zenmoney_api/protocol.py

@@ -0,0 +1,219 @@
+"""Lossless wire protocol; accepts complete objects and preserves extensions."""
+from collections.abc import Iterable, Mapping, Sequence
+from copy import deepcopy
+from decimal import Decimal
+from math import isfinite
+from typing import Any, TypeAlias, cast
+
+import simplejson as json
+
+from .errors import ResponseError
+
+EntityData: TypeAlias = dict[str, Any]
+Changes: TypeAlias = Mapping[str, Sequence[Mapping[str, Any]]]
+KINDS = ('instrument', 'company', 'user', 'account', 'tag', 'merchant',
+         'budget', 'reminder', 'reminderMarker', 'transaction', 'country')
+FORCE_FETCH = tuple(kind for kind in KINDS if kind != 'country')
+WRITABLE = ('account', 'tag', 'merchant', 'budget', 'reminder', 'reminderMarker', 'transaction')
+DELETABLE = tuple(kind for kind in WRITABLE if kind != 'budget')
+
+
+class Diff(dict[str, Any]):
+    """Decoded entities, including unknown fields, and the unchanged UTF-8 response."""
+    def __init__(self, data: EntityData, raw_json: str):
+        super().__init__(data)
+        self.raw_json = raw_json
+
+    @property
+    def server_timestamp(self) -> int:
+        return int(self['serverTimestamp'])
+
+
+def entity_key(kind: str, item: Mapping[str, Any]) -> str:
+    if kind == 'budget':
+        if not all(k in item for k in ('user', 'date', 'tag')):
+            raise ResponseError('Invalid budget key')
+        if type(item['user']) is not int or item['user'] <= 0 or not isinstance(item['date'], str):
+            raise ResponseError('Invalid budget key')
+        if item['tag'] is not None and not isinstance(item['tag'], str):
+            raise ResponseError('Invalid budget key')
+        return str(json.dumps([item['user'], item['date'], item['tag']], separators=(',', ':')))
+    identifier = item.get('id')
+    if type(identifier) not in (str, int) or identifier == '':
+        raise ResponseError('Invalid entity identifier')
+    return str(identifier)
+
+
+def validate_diff(data: Any) -> None:
+    if not isinstance(data, dict) or type(data.get('serverTimestamp')) is not int or data['serverTimestamp'] < 0:
+        raise ResponseError('Invalid server timestamp')
+    if data.get('error'):
+        raise ResponseError('ZenMoney rejected diff')
+    for kind in KINDS:
+        rows = data.get(kind, [])
+        if not isinstance(rows, list):
+            raise ResponseError('Invalid entity collection')
+        for row in rows:
+            if not isinstance(row, dict):
+                raise ResponseError('Invalid entity')
+            entity_key(kind, row)
+    if not isinstance(data.get('deletion', []), list):
+        raise ResponseError('Invalid deletions')
+    for row in data.get('deletion', []):
+        if not isinstance(row, dict) or not isinstance(row.get('object'), str) or type(row.get('id')) not in (str, int):
+            raise ResponseError('Invalid deletion')
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> EntityData:
+    result: EntityData = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('Duplicate JSON key')
+        result[key] = value
+    return result
+
+
+def _validate_json(value: Any, seen: set[int] | None = None) -> None:
+    """Reject coercions, circular values and nonfinite Decimals before encoding."""
+    if value is None or type(value) in (str, int, bool):
+        return
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError('Expected a finite decimal')
+        return
+    if type(value) is float:
+        if not isfinite(value):
+            raise ValueError('Expected a finite number')
+        return
+    if isinstance(value, (dict, list, tuple)):
+        seen = set() if seen is None else seen
+        if id(value) in seen:
+            raise ValueError('Circular JSON value')
+        seen.add(id(value))
+        try:
+            values: Iterable[Any]
+            if isinstance(value, dict):
+                if not all(isinstance(key, str) for key in value):
+                    raise ValueError('JSON keys must be strings')
+                values = value.values()
+            else:
+                values = value
+            for item in values:
+                _validate_json(item, seen)
+        finally:
+            seen.remove(id(value))
+        return
+    raise ValueError('Unsupported JSON value')
+
+
+def decode_json(raw: bytes) -> Any:
+    try:
+        return json.loads(raw.decode('utf-8'), object_pairs_hook=_unique_object,
+                          use_decimal=True, allow_nan=False)
+    except (ValueError, UnicodeError, RecursionError):
+        raise ResponseError('Invalid ZenMoney JSON') from None
+
+
+def decode_diff(raw: bytes, cursor: int) -> Diff:
+    data = decode_json(raw)
+    validate_diff(data)
+    if data['serverTimestamp'] < cursor:
+        raise ResponseError('ZenMoney cursor moved backwards')
+    return Diff(data, raw.decode('utf-8'))
+
+
+def timestamp(value: Any) -> int:
+    if type(value) is not int or value < 0:
+        raise ValueError('Expected a nonnegative integer timestamp')
+    return int(value)
+
+
+def encode_json(value: Any) -> bytes:
+    try:
+        _validate_json(value)
+        return json.dumps(value, ensure_ascii=False, allow_nan=False,
+                          use_decimal=True).encode('utf-8')
+    except (ValueError, TypeError, UnicodeError, RecursionError):
+        raise ValueError('Expected finite JSON values with string keys') from None
+
+
+def _sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))
+
+
+def diff_payload(cursor: int, now: int, changes: Changes | None = None,
+                 deletions: Sequence[Mapping[str, Any]] | None = None,
+                 force_fetch: Sequence[str] | None = None) -> EntityData:
+    payload: EntityData = {'serverTimestamp': timestamp(cursor), 'currentClientTimestamp': timestamp(now)}
+    if force_fetch is not None:
+        if not _sequence(force_fetch) or any(not isinstance(k, str) or k not in FORCE_FETCH for k in force_fetch):
+            raise ValueError('Unsupported forceFetch collection')
+        payload['forceFetch'] = list(dict.fromkeys(force_fetch))
+    if changes is not None:
+        if not isinstance(changes, Mapping) or any(k not in WRITABLE for k in changes):
+            raise ValueError('Only user entity collections can be written')
+        for kind, rows in changes.items():
+            if not _sequence(rows):
+                raise ValueError('Expected an entity sequence')
+            keys = set()
+            copied = []
+            for row in rows:
+                if not isinstance(row, Mapping):
+                    raise ValueError('Expected an entity object')
+                try:
+                    key = entity_key(kind, row)
+                except ResponseError:
+                    raise ValueError('Invalid entity identity') from None
+                # User entity IDs are strings; budgets are keyed by user/date/tag.
+                if kind != 'budget' and not isinstance(row['id'], str):
+                    raise ValueError('Expected a string entity ID')
+                if key in keys:
+                    raise ValueError('Duplicate entity identity')
+                keys.add(key)
+                timestamp(row.get('changed'))
+                if type(row.get('user')) is not int or row['user'] <= 0:
+                    raise ValueError('Expected positive user ID')
+                copied.append(deepcopy(dict(row)))
+            payload[kind] = copied
+    if deletions is not None:
+        if not _sequence(deletions):
+            raise ValueError('Expected deletion sequence')
+        seen = set()
+        copied_deletions = []
+        for row in deletions:
+            if not isinstance(row, Mapping) or row.get('object') not in DELETABLE or not isinstance(row.get('id'), str) or not row['id']:
+                raise ValueError('Invalid deletion identity')
+            timestamp(row.get('stamp'))
+            if type(row.get('user')) is not int or row['user'] <= 0:
+                raise ValueError('Expected positive user ID')
+            deletion_key = (row['object'], row['id'])
+            if deletion_key in seen or any(t.get('id') == row['id'] for t in payload.get(row['object'], [])):
+                raise ValueError('Duplicate or conflicting deletion')
+            seen.add(deletion_key)
+            copied_deletions.append(deepcopy(dict(row)))
+        payload['deletion'] = copied_deletions
+    encode_json(payload)
+    return payload
+
+
+def suggest_payload(transactions: Mapping[str, Any] | Sequence[Mapping[str, Any]]) -> EntityData | list[EntityData]:
+    payload: EntityData | list[EntityData]
+    if isinstance(transactions, Mapping):
+        payload = deepcopy(dict(transactions))
+    elif _sequence(transactions) and transactions and all(isinstance(t, Mapping) for t in transactions):
+        payload = [deepcopy(dict(t)) for t in transactions]
+    else:
+        raise ValueError('Expected transaction object or nonempty sequence')
+    encode_json(payload)
+    return payload
+
+
+def decode_suggestion(raw: bytes, request: EntityData | list[EntityData]) -> EntityData | list[EntityData]:
+    result = decode_json(raw)
+    if isinstance(request, list):
+        valid = isinstance(result, list) and len(result) == len(request) and all(isinstance(t, dict) and not t.get('error') for t in result)
+    else:
+        valid = isinstance(result, dict) and not result.get('error')
+    if not valid:
+        raise ResponseError('Invalid suggestion response')
+    return cast(EntityData | list[EntityData], result)

zenmoney_api/transactions.py

@@ -0,0 +1,148 @@
+"""Builders produce full wire objects; they never send or persist anything."""
+import math
+import time
+from copy import deepcopy
+from datetime import date as Date
+from decimal import Decimal
+from typing import Any, Unpack, cast
+from collections.abc import Mapping
+from .models import Number, Transaction, TransactionOptions, TransactionFields, BaseTransactionOptions
+from .protocol import EntityData
+from uuid import uuid4
+from .protocol import DELETABLE, timestamp, encode_json
+
+CREATION_DEFAULTS: EntityData = {key: None for key in (
+    'merchant', 'originalPayee', 'reminderMarker', 'opIncome', 'opIncomeInstrument',
+    'opOutcome', 'opOutcomeInstrument', 'latitude', 'longitude', 'qrCode', 'source',
+    'incomeBankID', 'outcomeBankID')}
+CREATION_DEFAULTS['viewed'] = True
+
+
+def _finite_number(value: Any) -> bool:
+    if isinstance(value, Decimal):
+        return value.is_finite()
+    return type(value) is int or (type(value) is float and math.isfinite(value))
+
+
+def _amount(value: Number, *, positive: bool = False) -> Number:
+    if not _finite_number(value) or value < 0 or (positive and value == 0):
+        raise ValueError('Expected a finite nonnegative amount')
+    return value
+
+
+def _id(value: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError('Expected a nonempty account ID')
+    return value
+
+
+def _positive_int(value: int) -> int:
+    if type(value) is not int or value <= 0:
+        raise ValueError('Expected a positive integer ID')
+    return value
+
+
+def transaction(*, user: int, date: str, income_account: str, outcome_account: str,
+                income_instrument: int, outcome_instrument: int, income: Number,
+                outcome: Number, categories: list[str] | None = None,
+                payee: str | None = None, comment: str | None = None,
+                merchant: str | None = None, id: str | None = None,
+                now: int | None = None, **fields: Unpack[TransactionFields]) -> Transaction:
+    """Build a posted operation. IDs/timestamps can be supplied for deterministic drafts."""
+    if not isinstance(date, str) or Date.fromisoformat(date).isoformat() != date:
+        raise ValueError('Expected ISO calendar date')
+    stamp = timestamp(int(time.time()) if now is None else now)
+    if categories is not None and (not isinstance(categories, list) or not all(isinstance(t, str) and t for t in categories)):
+        raise ValueError('Expected category IDs or None')
+    for value in (payee, comment, merchant):
+        if value is not None and not isinstance(value, str):
+            raise ValueError('Expected optional text')
+    result: EntityData = {**CREATION_DEFAULTS, 'mcc': None, 'id': _id(id) if id is not None else str(uuid4()),
+        'created': stamp, 'changed': stamp, 'user': _positive_int(user), 'deleted': False, 'hold': False,
+        'date': date, 'incomeAccount': _id(income_account), 'outcomeAccount': _id(outcome_account),
+        'incomeInstrument': _positive_int(income_instrument), 'outcomeInstrument': _positive_int(outcome_instrument),
+        'income': _amount(income), 'outcome': _amount(outcome), 'tag': deepcopy(categories),
+        'payee': payee, 'comment': comment, 'merchant': merchant}
+    allowed = set(CREATION_DEFAULTS) | {'mcc', 'hold', 'deleted'}
+    if any(k not in allowed for k in fields):
+        raise ValueError('Unsupported optional transaction field')
+    result.update(fields)
+    for name in ('opIncome', 'opOutcome'):
+        if result[name] is not None:
+            _amount(result[name])
+        if (result[name] is None) != (result[name+'Instrument'] is None):
+            raise ValueError('Original amount and instrument must be supplied together')
+        if result[name+'Instrument'] is not None:
+            _positive_int(result[name+'Instrument'])
+    for name, limit in (('latitude', 90), ('longitude', 180)):
+        if result[name] is not None and (not _finite_number(result[name]) or not -limit <= result[name] <= limit):
+            raise ValueError('Invalid coordinates')
+    if type(result['deleted']) is not bool or (result['hold'] is not None and type(result['hold']) is not bool):
+        raise ValueError('Invalid transaction flags')
+    if type(result['viewed']) is not bool:
+        raise ValueError('Invalid viewed flag')
+    if result['mcc'] is not None and (type(result['mcc']) is not int or result['mcc'] < 0):
+        raise ValueError('Invalid MCC')
+    for name in ('originalPayee', 'reminderMarker', 'qrCode', 'source', 'incomeBankID', 'outcomeBankID'):
+        if result[name] is not None and not isinstance(result[name], str):
+            raise ValueError('Invalid optional transaction text')
+    encode_json(result)
+    return cast(Transaction, result)
+
+
+def expense(*, account: str, instrument: int, amount: Number, **kwargs: Unpack[TransactionOptions]) -> Transaction:
+    return transaction(income_account=account, outcome_account=account,
+        income_instrument=instrument, outcome_instrument=instrument,
+        income=0, outcome=_amount(amount, positive=True), **kwargs)
+
+
+def income(*, account: str, instrument: int, amount: Number, **kwargs: Unpack[TransactionOptions]) -> Transaction:
+    return transaction(income_account=account, outcome_account=account,
+        income_instrument=instrument, outcome_instrument=instrument,
+        income=_amount(amount, positive=True), outcome=0, **kwargs)
+
+
+def transfer(*, from_account: str, to_account: str, from_instrument: int,
+             to_instrument: int, amount_out: Number, amount_in: Number, **kwargs: Unpack[TransactionOptions]) -> Transaction:
+    if from_account == to_account:
+        raise ValueError('Transfer requires different accounts')
+    return transaction(income_account=to_account, outcome_account=from_account,
+        income_instrument=to_instrument, outcome_instrument=from_instrument,
+        income=_amount(amount_in, positive=True), outcome=_amount(amount_out, positive=True), **kwargs)
+
+
+def debt(*, action: str, account: str, debt_account: str, instrument: int,
+         amount: Number, payee: str, **kwargs: Unpack[BaseTransactionOptions]) -> Transaction:
+    """lend/repay: cash → debt; borrow/collect: debt → cash. Both use cash currency."""
+    if action not in ('lend', 'borrow', 'repay', 'collect'):
+        raise ValueError('Unknown debt action')
+    if not isinstance(payee, str) or not payee.strip():
+        raise ValueError('Debt requires a counterparty')
+    outgoing = action in ('lend', 'repay')
+    return transfer(from_account=account if outgoing else debt_account,
+        to_account=debt_account if outgoing else account,
+        from_instrument=instrument, to_instrument=instrument,
+        amount_out=amount, amount_in=amount, payee=payee, **kwargs)
+
+
+def update(entity: Mapping[str, Any], *, now: int | None = None, **fields: Any) -> EntityData:
+    """Copy a complete fetched entity, retaining unknown fields. Identity is immutable."""
+    if any(k in fields for k in ('id', 'user', 'created', 'changed')):
+        raise ValueError('Cannot replace identity or timestamps in an update')
+    result = deepcopy(dict(entity))
+    result.update(deepcopy(fields))
+    result['changed'] = timestamp(int(time.time()) if now is None else now)
+    encode_json(result)
+    return result
+
+
+def deletion(kind: str, id: str, *, user: int, now: int | None = None) -> EntityData:
+    if kind not in DELETABLE:
+        raise ValueError('This entity cannot be deleted by ID')
+    return {'object': kind, 'id': _id(id), 'user': _positive_int(user),
+            'stamp': timestamp(int(time.time()) if now is None else now)}
+
+
+def clear_budget(budget: Mapping[str, Any], *, now: int | None = None) -> EntityData:
+    """Budget has a composite identity; clear amounts/locks instead of deleting by ID."""
+    return update(budget, now=now, income=0, outcome=0, incomeLock=False, outcomeLock=False)

zenmoney_python-0.7.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+zenmoney_api/__init__.py,sha256=B02R0EPk-zCeaV7ZupXfxTKLt-d0uiY9TK2XjSCW_LA,747
+zenmoney_api/client.py,sha256=MQ1r021HduolE4sRPj4apYoZnYaoQzzAq6MWkB0W__Y,7943
+zenmoney_api/entities.py,sha256=bcoqVNQ-CP3513UJFFWcD-atew54TC0tExR0bmhEvfE,3074
+zenmoney_api/errors.py,sha256=ZWUTQXHXj4fN7yLTQQrRooBy8tdMyga80fMK_NrWDF0,562
+zenmoney_api/models.py,sha256=fccKs3BAK6g8K_zuBsAvGcATw6pzGEPnRwMelNupw1E,4426
+zenmoney_api/oauth.py,sha256=gX-0iajnur40FjZy-nWFccroumLwTEPL28HDSBWydhk,7448
+zenmoney_api/protocol.py,sha256=Kew5Mf12a03pLrBADhvtH3dcYFH4qkpErCW1BVYwsrw,9482
+zenmoney_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zenmoney_api/transactions.py,sha256=6NRTENjTReWwRZsxDe9QBAO9j084YOZ5Yl1SuPFRLiU,7857
+zenmoney_python-0.7.0.dist-info/licenses/LICENSE,sha256=GlIFmM7HXSAzMamaTXRQwkYmr1lyD9pCWT8lpVOhTMY,1071
+zenmoney_python-0.7.0.dist-info/METADATA,sha256=H6LfjBvC0rJx_6GY-9u3w024wEdoKTfSWOkKDbZKimM,15910
+zenmoney_python-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+zenmoney_python-0.7.0.dist-info/top_level.txt,sha256=HYVXmPnkDkPu47HG-rUgLoQFMMV4I89l-ePHwmJkFfY,13
+zenmoney_python-0.7.0.dist-info/RECORD,,

zenmoney_python-0.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zenmoney_python-0.7.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+zenmoney_api