heleket-sdk 0.3.0__tar.gz

heleket_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here. 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).
+
+## [0.3.0] - 2026-06-25
+
+### Added
+- `HeleketPayout.refund(request)` → `POST /v1/payment/refund`. Refunds are now
+  signed with the **payout** API key, so the method lives on `HeleketPayout`.
+
+### Removed
+- `HeleketPayment.refund()`. The Heleket API signs `/v1/payment/refund` with the
+  payout key, which a payment client does not hold, so it can no longer sign a
+  valid refund. Use `HeleketPayout.refund()` instead — e.g.
+  `HeleketPayout(merchant_id=merchant_id, api_key=payout_key).refund(request)`.
+  See [`UPGRADING.md`](UPGRADING.md).
+
+## [0.2.0] - 2026-06-25
+
+### Added
+- `HeleketPayment.get_aml_links(uuid=None, order_id=None)` → `POST
+  /v1/payment/aml-links`: AML/KYC/SoF questionnaire links for a blocked (locked)
+  payment, plus `AmlLinkStatus` with `is_final()` / `is_successful()` helpers.
+
+### Changed
+- `HeleketPayment.get_exchange_rates()` now issues a `GET` request (was `POST`).
+  The method signature and return type are unchanged.
+
+## [0.1.0]
+
+Initial reference implementation of the Heleket cryptocurrency payment API.
+
+### Added
+- `HeleketPayment` / `HeleketPayout` clients with typed Pydantic request/response
+  models.
+- Payments API: invoices, info, history, static wallets, QR codes, refunds,
+  webhook resend, test webhooks.
+- Payouts API: payouts, info, history, fee calculation, transfers, services.
+- Balance and exchange-rate endpoints.
+- Signed webhook verification (`WebhookVerifier`, `WebhookPayload`) with
+  constant-time comparison.
+- Swappable HTTP transport (`Transport`, `RequestsTransport`, plus `FakeTransport`
+  for offline tests).
+- Debug mode (`DebugSink`) and a webhook inspector CLI (`heleket-webhook-inspect`).
+- Status enums (`PaymentStatus`, `PayoutStatus`) with `is_final()` /
+  `is_successful()` helpers.

heleket_sdk-0.3.0/LICENSE

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

heleket_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: heleket-sdk
+Version: 0.3.0
+Summary: Reference Python SDK for the Heleket cryptocurrency payment API: payments, payouts, balance, exchange rates, and signed webhooks.
+License: MIT
+License-File: LICENSE
+Keywords: heleket,crypto,cryptocurrency,payments,payouts,sdk,api,webhooks
+Author: Heleket Reference SDK Authors
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic (>=2.5,<3.0)
+Requires-Dist: requests (>=2.31,<3.0)
+Project-URL: Bug Tracker, https://github.com/Heleket/python-sdk/issues
+Project-URL: Changelog, https://github.com/Heleket/python-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://doc.heleket.com/
+Project-URL: Homepage, https://heleket.com
+Project-URL: Repository, https://github.com/Heleket/python-sdk
+Description-Content-Type: text/markdown
+
+# Heleket Python integration (reference)
+
+A production-grade reference SDK for the [Heleket](https://heleket.com) cryptocurrency payment API. Written for **Python 3.11+**, published as `heleket-sdk` — works with FastAPI, Django, Flask, or plain scripts.
+
+Covers the full documented surface (payments, payouts, balance, services, exchange rates), ships with pytest tests, runnable examples, byte-fidelity webhook verification, debug mode wired into your choice of logger, a `heleket-webhook-inspect` CLI, and a Docker harness.
+
+Runtime dependencies: **Pydantic v2** (typed DTOs) and **requests** (HTTP). Everything else comes from the standard library.
+
+## Quickstart
+
+```python
+from heleket_sdk import HeleketPayment
+from heleket_sdk.types import CreateInvoiceRequest
+
+client = HeleketPayment(merchant_id=merchant_id, api_key=payment_key)
+
+invoice = client.create_invoice(
+    CreateInvoiceRequest(
+        amount="15.00",
+        currency="USD",
+        order_id="order-42",
+        lifetime=3600,
+    )
+)
+
+print(invoice.url)  # → https://pay.heleket.com/pay/<uuid>
+```
+
+## Install
+
+```bash
+poetry add heleket-sdk
+# or
+pip install heleket-sdk
+```
+
+Requirements: Python 3.11+ (StrEnum, Self type, better type hints). Tested with CPython 3.11 and 3.12.
+
+## Documentation
+
+Full reference lives in [`docs/`](docs/README.md):
+
+- [01 — Installation](docs/01-installation.md)
+- [02 — Configuration](docs/02-configuration.md)
+- [03 — Architecture](docs/03-architecture.md)
+- [04 — Payments API](docs/04-payments.md)
+- [05 — Payouts API](docs/05-payouts.md)
+- [06 — Webhooks](docs/06-webhooks.md) ⚑ critical reading
+- [07 — Debugging](docs/07-debugging.md)
+- [08 — Testing](docs/08-testing.md)
+- [09 — Error handling](docs/09-error-handling.md)
+- [10 — Reference (statuses, currencies, endpoints)](docs/10-reference.md)
+- [12 — Troubleshooting](docs/12-troubleshooting.md)
+
+## What's in the box
+
+```
+src/heleket_sdk/         Source — single source of truth
+src/heleket_sdk/webhook  Webhook signature verifier (byte-fidelity)
+tests/                   pytest suite + FakeTransport for offline testing
+examples/                Twelve runnable scripts covering every endpoint
+bin/                     heleket-webhook-inspect — CLI for verifying webhook payloads
+docker/                  Multi-stage Dockerfile (python:3.11-slim)
+docs/                    Full module documentation
+CHANGELOG.md             Notable changes per release
+UPGRADING.md             Migration notes between versions
+pyproject.toml           Poetry build + ruff + mypy + pytest config
+```
+
+## Common tasks
+
+```bash
+make install              # poetry install --with dev
+make test                 # pytest -q
+make lint                 # ruff check
+make fmt                  # ruff format
+make fmt-check            # ruff format --check
+make typecheck            # mypy in strict mode
+make qa                   # All quality gates
+make example-invoice      # Create a real invoice (needs .env)
+make example-webhook      # Run the webhook listener on :8000
+make webhook-inspect KEY=$K FILE=evt.json  # Inspect a captured webhook
+make docker-shell         # Drop into a containerized Python 3.11 shell
+make help                 # Full target list
+```
+
+## Security notes (read this)
+
+- **Use `verify_raw` for production webhooks.** `verify(decoded)` is convenience-only and lossy — it can't recover the PHP-style `\/` slash escapes that Heleket's server sends. See [docs/06-webhooks.md](docs/06-webhooks.md).
+- **De-duplicate replays.** Use a `(uuid, status)` key in your DB before doing side-effect work. SQLAlchemy and redis-py examples in [docs/06-webhooks.md](docs/06-webhooks.md#idempotency-and-replay-protection).
+- **Whitelist Heleket's webhook source IP `31.133.220.8`** at your reverse proxy or firewall.
+- **Two separate API keys** — payments and payouts. Mixing them breaks webhook verification. (One exception: `/v1/payment/refund` uses the **payout** key — call `HeleketPayout.refund()`.)
+- **The SDK never logs API keys.** Debug-mode entries include URL, method, body, and status — but the `sign` header and API key are explicitly excluded.
+
+## License
+
+MIT.
+

heleket_sdk-0.3.0/README.md

@@ -0,0 +1,97 @@
+# Heleket Python integration (reference)
+
+A production-grade reference SDK for the [Heleket](https://heleket.com) cryptocurrency payment API. Written for **Python 3.11+**, published as `heleket-sdk` — works with FastAPI, Django, Flask, or plain scripts.
+
+Covers the full documented surface (payments, payouts, balance, services, exchange rates), ships with pytest tests, runnable examples, byte-fidelity webhook verification, debug mode wired into your choice of logger, a `heleket-webhook-inspect` CLI, and a Docker harness.
+
+Runtime dependencies: **Pydantic v2** (typed DTOs) and **requests** (HTTP). Everything else comes from the standard library.
+
+## Quickstart
+
+```python
+from heleket_sdk import HeleketPayment
+from heleket_sdk.types import CreateInvoiceRequest
+
+client = HeleketPayment(merchant_id=merchant_id, api_key=payment_key)
+
+invoice = client.create_invoice(
+    CreateInvoiceRequest(
+        amount="15.00",
+        currency="USD",
+        order_id="order-42",
+        lifetime=3600,
+    )
+)
+
+print(invoice.url)  # → https://pay.heleket.com/pay/<uuid>
+```
+
+## Install
+
+```bash
+poetry add heleket-sdk
+# or
+pip install heleket-sdk
+```
+
+Requirements: Python 3.11+ (StrEnum, Self type, better type hints). Tested with CPython 3.11 and 3.12.
+
+## Documentation
+
+Full reference lives in [`docs/`](docs/README.md):
+
+- [01 — Installation](docs/01-installation.md)
+- [02 — Configuration](docs/02-configuration.md)
+- [03 — Architecture](docs/03-architecture.md)
+- [04 — Payments API](docs/04-payments.md)
+- [05 — Payouts API](docs/05-payouts.md)
+- [06 — Webhooks](docs/06-webhooks.md) ⚑ critical reading
+- [07 — Debugging](docs/07-debugging.md)
+- [08 — Testing](docs/08-testing.md)
+- [09 — Error handling](docs/09-error-handling.md)
+- [10 — Reference (statuses, currencies, endpoints)](docs/10-reference.md)
+- [12 — Troubleshooting](docs/12-troubleshooting.md)
+
+## What's in the box
+
+```
+src/heleket_sdk/         Source — single source of truth
+src/heleket_sdk/webhook  Webhook signature verifier (byte-fidelity)
+tests/                   pytest suite + FakeTransport for offline testing
+examples/                Twelve runnable scripts covering every endpoint
+bin/                     heleket-webhook-inspect — CLI for verifying webhook payloads
+docker/                  Multi-stage Dockerfile (python:3.11-slim)
+docs/                    Full module documentation
+CHANGELOG.md             Notable changes per release
+UPGRADING.md             Migration notes between versions
+pyproject.toml           Poetry build + ruff + mypy + pytest config
+```
+
+## Common tasks
+
+```bash
+make install              # poetry install --with dev
+make test                 # pytest -q
+make lint                 # ruff check
+make fmt                  # ruff format
+make fmt-check            # ruff format --check
+make typecheck            # mypy in strict mode
+make qa                   # All quality gates
+make example-invoice      # Create a real invoice (needs .env)
+make example-webhook      # Run the webhook listener on :8000
+make webhook-inspect KEY=$K FILE=evt.json  # Inspect a captured webhook
+make docker-shell         # Drop into a containerized Python 3.11 shell
+make help                 # Full target list
+```
+
+## Security notes (read this)
+
+- **Use `verify_raw` for production webhooks.** `verify(decoded)` is convenience-only and lossy — it can't recover the PHP-style `\/` slash escapes that Heleket's server sends. See [docs/06-webhooks.md](docs/06-webhooks.md).
+- **De-duplicate replays.** Use a `(uuid, status)` key in your DB before doing side-effect work. SQLAlchemy and redis-py examples in [docs/06-webhooks.md](docs/06-webhooks.md#idempotency-and-replay-protection).
+- **Whitelist Heleket's webhook source IP `31.133.220.8`** at your reverse proxy or firewall.
+- **Two separate API keys** — payments and payouts. Mixing them breaks webhook verification. (One exception: `/v1/payment/refund` uses the **payout** key — call `HeleketPayout.refund()`.)
+- **The SDK never logs API keys.** Debug-mode entries include URL, method, body, and status — but the `sign` header and API key are explicitly excluded.
+
+## License
+
+MIT.

heleket_sdk-0.3.0/UPGRADING.md

@@ -0,0 +1,36 @@
+# Upgrading
+
+## 0.2 → 0.3
+
+`refund` moved from `HeleketPayment` to `HeleketPayout`. The Heleket API now signs
+`POST /v1/payment/refund` with the **payout** API key, so a payment client can no
+longer produce a valid signature for it.
+
+`HeleketPayment` no longer exposes `refund()` — calling it raises `AttributeError`.
+Switch to `HeleketPayout.refund()`:
+
+```python
+from heleket_sdk import HeleketPayment, HeleketPayout
+from heleket_sdk.types import RefundRequest
+
+# Before (0.2 and earlier)
+payment = HeleketPayment(merchant_id=merchant_id, api_key=payment_key)
+payment.refund(RefundRequest(uuid=invoice_uuid, address=addr, is_subtract=True))
+
+# After (0.3)
+payout = HeleketPayout(merchant_id=merchant_id, api_key=payout_key)
+payout.refund(RefundRequest(uuid=invoice_uuid, address=addr, is_subtract=True))
+```
+
+Everything else is unchanged.
+
+## 0.1 → 0.2
+
+Purely additive — no caller changes required:
+
+- New `HeleketPayment.get_aml_links(uuid=None, order_id=None)` returns the
+  AML/KYC/SoF questionnaire links for a blocked (locked) payment, alongside a new
+  `AmlLinkStatus` enum with `is_final()` / `is_successful()` helpers.
+- `HeleketPayment.get_exchange_rates()` now issues a `GET` request instead of a
+  `POST`. The method signature and return type are identical, so existing code
+  keeps working.

heleket_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["poetry-core>=1.6.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "heleket-sdk"
+version = "0.3.0"
+description = "Reference Python SDK for the Heleket cryptocurrency payment API: payments, payouts, balance, exchange rates, and signed webhooks."
+authors = ["Heleket Reference SDK Authors"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://heleket.com"
+repository = "https://github.com/Heleket/python-sdk"
+documentation = "https://doc.heleket.com/"
+keywords = ["heleket", "crypto", "cryptocurrency", "payments", "payouts", "sdk", "api", "webhooks"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Office/Business :: Financial",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+packages = [{ include = "heleket_sdk", from = "src" }]
+include = [
+    { path = "CHANGELOG.md", format = "sdist" },
+    { path = "UPGRADING.md", format = "sdist" },
+]
+
+[tool.poetry.urls]
+Changelog = "https://github.com/Heleket/python-sdk/blob/main/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/Heleket/python-sdk/issues"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2.5"
+requests = "^2.31"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-cov = "^5.0"
+ruff = "^0.5"
+mypy = "^1.10"
+types-requests = "^2.31"
+
+[tool.poetry.scripts]
+heleket-webhook-inspect = "heleket_sdk._cli:main"
+
+# ---------- ruff ----------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests", "examples", "bin"]
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # bugbear
+  "UP",  # pyupgrade
+  "PL",  # pylint subset
+  "SIM", # simplifications
+]
+ignore = [
+  "PLR0913", # too many arguments — DTO constructors are intentionally wide
+  "PLR2004", # magic numbers — fine in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR2004", "S101"]
+"examples/*" = ["T201"]  # print() is the point in examples
+
+[tool.ruff.format]
+quote-style = "double"
+
+# ---------- mypy ----------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src/heleket_sdk"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = false
+init_typed = true
+warn_required_dynamic_aliases = true
+
+# ---------- pytest --------------------------------------------------------------
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"

heleket_sdk-0.3.0/src/heleket_sdk/__init__.py

@@ -0,0 +1,72 @@
+"""Heleket Python SDK.
+
+A reference implementation of the `Heleket <https://heleket.com>`_
+cryptocurrency payment API. Covers payments, payouts, balance, services,
+exchange rates, and webhook verification.
+
+Public entry points::
+
+    from heleket_sdk import HeleketPayment, HeleketPayout
+    from heleket_sdk import ClientOptions
+    from heleket_sdk import WebhookVerifier
+    from heleket_sdk import PaymentStatus, PayoutStatus
+    from heleket_sdk import HeleketError, ApiError, ValidationError, HttpError, SignatureError
+
+See ``docs/`` for the full reference.
+"""
+
+from __future__ import annotations
+
+from ._config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, ClientOptions
+from ._debug import DebugEntry, DebugSink, stderr_sink
+from ._errors import (
+    ApiError,
+    HeleketError,
+    HttpError,
+    SignatureError,
+    ValidationError,
+)
+from ._signature import constant_time_equal, sign
+from ._status import AmlLinkStatus, CourseSource, PaymentStatus, PayoutStatus
+from ._transport import RequestsTransport, Transport, TransportResponse
+from ._version import __version__
+from .payment import HeleketPayment
+from .payout import HeleketPayout
+from .webhook import WebhookPayload, WebhookVerifier
+
+__all__ = [
+    # Clients
+    "HeleketPayment",
+    "HeleketPayout",
+    # Configuration
+    "ClientOptions",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT_SECONDS",
+    # Webhook
+    "WebhookVerifier",
+    "WebhookPayload",
+    # Enums
+    "PaymentStatus",
+    "PayoutStatus",
+    "AmlLinkStatus",
+    "CourseSource",
+    # Errors
+    "HeleketError",
+    "ApiError",
+    "ValidationError",
+    "HttpError",
+    "SignatureError",
+    # Transport
+    "Transport",
+    "TransportResponse",
+    "RequestsTransport",
+    # Debug
+    "DebugEntry",
+    "DebugSink",
+    "stderr_sink",
+    # Low-level signature
+    "sign",
+    "constant_time_equal",
+    # Metadata
+    "__version__",
+]

heleket_sdk-0.3.0/src/heleket_sdk/_base_client.py

@@ -0,0 +1,157 @@
+"""Shared HTTP plumbing for :class:`HeleketPayment` and :class:`HeleketPayout`.
+
+Encodes the request, signs it, dispatches via the configured ``Transport``,
+dumps to the debug sink when enabled, and translates the response into either
+a typed result or an exception.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from ._config import ClientOptions
+from ._debug import DebugEntry
+from ._errors import ApiError, HttpError, ValidationError
+from ._signature import sign
+from ._transport import RequestsTransport, Transport
+from ._version import __version__
+
+__all__ = ["BaseClient"]
+
+_USER_AGENT = f"heleket-python-sdk/{__version__}"
+
+
+class BaseClient:
+    """Common base for the payment and payout clients.
+
+    Carries the merchant UUID, API key, and the resolved :class:`ClientOptions`.
+    Subclasses call :meth:`_post` with the path and request body.
+    """
+
+    def __init__(
+        self,
+        *,
+        merchant_id: str,
+        api_key: str,
+        options: ClientOptions | None = None,
+    ) -> None:
+        if not merchant_id or not merchant_id.strip():
+            raise ValueError("merchant_id must not be empty")
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key must not be empty")
+
+        self._merchant_id = merchant_id.strip()
+        self._api_key = api_key.strip()
+        self._options = options if options is not None else ClientOptions()
+        self._transport: Transport = self._options.transport or RequestsTransport()
+
+    # ------------------------------------------------------------------ #
+    # internal helpers
+    # ------------------------------------------------------------------ #
+
+    def _post(self, path: str, params: Any = None) -> Any:
+        """Send a signed POST request and return the decoded ``result`` field."""
+        return self._send("POST", path, self._encode_body(params))
+
+    def _get(self, path: str) -> Any:
+        """Send a signed GET request and return the decoded ``result`` field.
+
+        For read-only endpoints that carry all their input in the path (e.g.
+        exchange rates). There is no request body, so the signed bytes are the
+        empty string — exactly like a POST with no params: ``sign = md5(api_key)``.
+        """
+        return self._send("GET", path, "")
+
+    def _send(self, method: str, path: str, body: str) -> Any:
+        """Sign the exact body bytes, attach the auth headers, dispatch via the
+        transport, and translate the response.
+
+        Shared by :meth:`_post` and :meth:`_get` so the signing and error
+        handling live in exactly one place.
+        """
+        signature = sign(body, self._api_key)
+        url = self._options.base_url + path
+
+        headers = {
+            "merchant": self._merchant_id,
+            "sign": signature,
+            "Content-Type": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+
+        if self._options.debug:
+            self._options.logger(DebugEntry.request(method, url, body))
+
+        try:
+            response = self._transport.round_trip(method, url, headers, body, self._options.timeout)
+        except HttpError:
+            raise
+        except Exception as exc:  # noqa: BLE001 — wrap unexpected failures
+            raise HttpError(f"transport failed: {exc}") from exc
+
+        if self._options.debug:
+            self._options.logger(DebugEntry.response(response.status_code, response.body))
+
+        return self._parse_response(response.status_code, response.body)
+
+    @staticmethod
+    def _encode_body(params: Any) -> str:
+        """Encode params to JSON, returning ``""`` for null/empty payloads."""
+        if params is None:
+            return ""
+        if isinstance(params, BaseModel):
+            # by_alias=True so snake_case wire names beat the Pydantic field
+            # names; exclude_none=True so optional fields don't serialise.
+            data = params.model_dump(by_alias=True, exclude_none=True)
+        elif isinstance(params, dict):
+            data = {k: v for k, v in params.items() if v is not None}
+        else:
+            # Last-ditch — let json.dumps try.
+            data = params
+
+        if not data and not isinstance(data, int | float | bool):
+            return ""
+        return json.dumps(data, separators=(",", ":"))
+
+    @staticmethod
+    def _parse_response(status_code: int, body: str) -> Any:
+        envelope: dict[str, Any] | None
+        if body:
+            try:
+                envelope = json.loads(body)
+                if not isinstance(envelope, dict):
+                    envelope = None
+            except json.JSONDecodeError:
+                envelope = None
+        else:
+            envelope = None
+
+        if status_code == 422:
+            fields: dict[str, list[str]] = {}
+            if envelope and isinstance(envelope.get("errors"), dict):
+                for key, value in envelope["errors"].items():
+                    if isinstance(value, list):
+                        fields[key] = [str(v) for v in value]
+                    else:
+                        fields[key] = [str(value)]
+            summary = _summarise_fields(fields)
+            raise ValidationError(f"validation failed: {summary}", status_code, fields, body)
+
+        if envelope is None:
+            raise ApiError(f"non-JSON response (HTTP {status_code})", status_code, body)
+
+        state = envelope.get("state")
+        if state != 0:
+            message = envelope.get("message", f"api error (state={state})")
+            raise ApiError(str(message), status_code, body)
+
+        return envelope.get("result")
+
+
+def _summarise_fields(fields: dict[str, list[str]]) -> str:
+    if not fields:
+        return "(no field details)"
+    return "; ".join(f"{k} ({', '.join(v)})" for k, v in fields.items())