moy-nalog-api 1.0.4__tar.gz

moy_nalog_api-1.0.4/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Environment
+.env
+.env.local
+session.json
+*.pkl
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+test_output/
+
+# Misc
+*.log
+Thumbs.db
+uv.lock
+/.serena/
+/.cursor/
+/.claude/

moy_nalog_api-1.0.4/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.4] - 2026-01-16
+
+### Added
+- New `device_id` property on both `MoyNalogClient` and `MoyNalogClientSync` for accessing the device identifier
+- New `download_receipt_raw()` method for downloading receipt as raw bytes with retry support
+- New `user_agent` parameter to customize User-Agent header in requests
+
+### Changed
+- Improved sync client cleanup with `__del__` method and `_closed` flag to prevent resource leaks
+- Better error handling: safe JSON parsing, UUID validation for receipt IDs
+- Internal refactoring: extracted `_normalize_phone`, `_parse_datetime`, `_validate_receipt_uuid` helper methods
+
+## [1.0.3] - 2025-12-26
+
+### Fixed
+- `is_token_expired` now returns `True` when token expiration time is unknown (previously returned `False`, which could cause `TokenExpiredError` on requests with stale tokens)
+- Added automatic retry with token refresh on 401 responses - if server returns 401, client will attempt to refresh the token and retry the request once before raising `TokenExpiredError`
+
+### Changed
+- Token refresh is now more aggressive: tokens with unknown expiration time are treated as expired to ensure proactive refresh
+
+## [1.0.2] - 2025-12-15
+
+### Added
+- Proxy server support for all API requests
+  - HTTP/HTTPS proxy (works out of the box)
+  - SOCKS4/SOCKS5 proxy (requires `pip install moy-nalog-api[socks]`)
+  - Proxy authentication support (user:password in URL)
+- New `proxy` parameter in `MoyNalogClient` and `MoyNalogClientSync`
+- New optional dependency `[socks]` for SOCKS proxy support (httpx-socks)
+
+## [1.0.1] - 2025-12-14
+
+### Fixed
+- README cross-links for PyPI display
+- Missing properties and methods in sync client
+
+## [1.0.0] - 2025-12-14
+
+### Added
+- Initial release
+- Async client (`MoyNalogClient`) with httpx
+- Sync wrapper (`MoyNalogClientSync`) for non-async code
+- Password authentication via nalog.ru credentials
+- SMS authentication (request code + verify)
+- Automatic token refresh before expiration
+- Session persistence to JSON file
+- Retry with exponential backoff
+- Full Pydantic v2 validation
+- Receipt creation (single and multiple items)
+- Receipt cancellation with reason (refund/mistake)
+- Income list with pagination and filtering
+- User profile retrieval
+- All client types support (individual, legal entity, foreign)
+- Payment types (cash, wire transfer)
+- Complete type hints (mypy compatible)
+- Comprehensive documentation in English and Russian

moy_nalog_api-1.0.4/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Python client library for the Russian self-employed tax service API (lknpd.nalog.ru / "Moy Nalog"). Provides async and sync interfaces for authentication, receipt creation, and income management.
+
+## Commands
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run single test file
+pytest tests/test_client.py
+
+# Run with coverage
+pytest --cov=moy_nalog
+
+# Linting
+ruff check .
+
+# Type checking
+mypy moy_nalog
+
+# Build package
+python -m build
+```
+
+## Architecture
+
+### Module Structure (`moy_nalog/`)
+
+- `client.py` - Main `MoyNalogClient` (async) and `MoyNalogClientSync` (sync wrapper) classes. Contains all API interaction logic, authentication, session management, and retry logic with exponential backoff.
+- `models.py` - Pydantic v2 models for API requests/responses (`ServiceItem`, `Client`, `Receipt`, `UserProfile`, `IncomeList`, `SessionData`, etc.)
+- `exceptions.py` - Typed exception hierarchy rooted at `MoyNalogError`
+- `enums.py` - `IncomeType`, `PaymentType`, `CancelReason` enums
+
+### Key Design Patterns
+
+**Dual Client Architecture**: `MoyNalogClientSync` wraps `MoyNalogClient` by creating its own event loop and delegating all async methods via `run_until_complete()`.
+
+**Session Persistence**: Optional JSON file-based session storage. Tokens are saved on `close()` and loaded on client initialization when `session_file` is provided.
+
+**Auto Token Refresh**: Before authenticated requests, checks `is_token_expired` (with 60s margin) and auto-refreshes via `_do_refresh_token()`.
+
+**Proxy Support**: HTTP/HTTPS proxies via native httpx, SOCKS proxies via optional `httpx-socks` dependency.
+
+### API Endpoints
+
+The client interacts with two API versions:
+- `API_URL_V1 = "https://lknpd.nalog.ru/api/v1"` - most endpoints
+- `API_URL_V2 = "https://lknpd.nalog.ru/api/v2"` - SMS start endpoint only
+
+### Test Configuration
+
+Tests use `pytest-asyncio` with `asyncio_mode = "auto"` in pyproject.toml. The `tests/test_models.py` tests Pydantic model validation; `tests/test_client.py` tests client initialization and validation without making real API calls.

moy_nalog_api-1.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kirill Nikulin
+
+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.