pawpayments 2.0.0__tar.gz

pawpayments-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write  # required for PyPI Trusted Publishing (no token needed)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - run: pip install --no-cache-dir build
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+      - run: gh release create "$GITHUB_REF_NAME" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

pawpayments-2.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

pawpayments-2.0.0/LICENSE

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

pawpayments-2.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: pawpayments
+Version: 2.0.0
+Summary: Official Python SDK for the PawPayments Native V2 API
+Project-URL: Homepage, https://pawpayments.com
+Project-URL: Documentation, https://docs.pawpayments.com
+Project-URL: Source, https://github.com/pawpayments/python-sdk
+Author-email: PawPayments <support@pawpayments.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PawPayments — Python SDK
+
+Official Python SDK for the [PawPayments](https://pawpayments.com) Native V2 API.
+Ships both a synchronous client (`PawPayments`, built on `requests`) and an
+asynchronous one (`AsyncPawPayments`, built on `httpx`).
+
+## Install
+
+```bash
+pip install pawpayments
+```
+
+Requires Python **3.9+**.
+
+## Quickstart (sync)
+
+```python
+from pawpayments import PawPayments
+
+paw = PawPayments(api_key="…")
+
+invoice = paw.invoices.create(
+    amount=25,
+    fiat_currency="USD",
+    billing_type="STATIC",
+    asset="usdt_tron",
+    description="Pro plan, 1 month",
+    notify_url="https://example.com/paw/webhook",
+)
+print(invoice["payment_url"])
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from pawpayments import AsyncPawPayments
+
+
+async def main():
+    async with AsyncPawPayments(api_key="…") as paw:
+        invoice = await paw.invoices.create(
+            amount=25,
+            fiat_currency="USD",
+            billing_type="STATIC",
+            asset="usdt_tron",
+        )
+        print(invoice["payment_url"])
+
+
+asyncio.run(main())
+```
+
+## Resources
+
+| Group | Methods |
+|-------|---------|
+| `paw.assets` | `list()` |
+| `paw.rates` | `get(base=, assets=)` |
+| `paw.balance` | `get()` |
+| `paw.invoices` | `create(**)`, `get(id)`, `list(**)`, `notify(id)` |
+| `paw.payouts` | `create(**, uniq_id=)`, `get(id)`, `list(**)`, `batch(items, uniq_id=)` |
+| `paw.ledger` | `list(type=, ...)` |
+| `paw.notifications` | `list(**)`, `test(url=)` |
+| `paw.permanent` | `create(**)`, `get(id)`, `list(**)`, `deactivate(id)` |
+
+`payouts.create` and `payouts.batch` accept an optional `uniq_id` for explicit
+idempotency (UUIDv4). When omitted the SDK generates one with `uuid.uuid4()`.
+A repeated `uniq_id` within 2 hours yields a 409.
+
+## Webhook verification
+
+```python
+from flask import Flask, request, abort
+from pawpayments import Webhook
+
+app = Flask(__name__)
+
+
+@app.post("/paw/webhook")
+def webhook():
+    raw = request.get_data()
+    sig = request.headers.get("X-Paw-Signature", "")
+    if not Webhook.verify_raw_body(raw, sig, API_KEY):
+        abort(401)
+    payload = Webhook.parse_payload(raw)
+    # …handle the invoice update…
+    return "", 200
+```
+
+## Errors
+
+```python
+from pawpayments import PawPaymentsApiError
+
+try:
+    paw.invoices.create(...)
+except PawPaymentsApiError as exc:
+    print(exc.code, exc.http_status, str(exc), exc.details)
+```
+
+## Testing
+
+- `pytest tests/test_webhook.py` — signature unit tests + PHP-interop parity.
+- `PAW_API_KEY=… pytest tests/test_live.py tests/test_negative.py` — live happy-path + negative-case suites against `https://api.pawpayments.com`. Tests skip when `PAW_API_KEY` is absent.
+
+## License
+
+MIT

pawpayments-2.0.0/README.md

@@ -0,0 +1,109 @@
+# PawPayments — Python SDK
+
+Official Python SDK for the [PawPayments](https://pawpayments.com) Native V2 API.
+Ships both a synchronous client (`PawPayments`, built on `requests`) and an
+asynchronous one (`AsyncPawPayments`, built on `httpx`).
+
+## Install
+
+```bash
+pip install pawpayments
+```
+
+Requires Python **3.9+**.
+
+## Quickstart (sync)
+
+```python
+from pawpayments import PawPayments
+
+paw = PawPayments(api_key="…")
+
+invoice = paw.invoices.create(
+    amount=25,
+    fiat_currency="USD",
+    billing_type="STATIC",
+    asset="usdt_tron",
+    description="Pro plan, 1 month",
+    notify_url="https://example.com/paw/webhook",
+)
+print(invoice["payment_url"])
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from pawpayments import AsyncPawPayments
+
+
+async def main():
+    async with AsyncPawPayments(api_key="…") as paw:
+        invoice = await paw.invoices.create(
+            amount=25,
+            fiat_currency="USD",
+            billing_type="STATIC",
+            asset="usdt_tron",
+        )
+        print(invoice["payment_url"])
+
+
+asyncio.run(main())
+```
+
+## Resources
+
+| Group | Methods |
+|-------|---------|
+| `paw.assets` | `list()` |
+| `paw.rates` | `get(base=, assets=)` |
+| `paw.balance` | `get()` |
+| `paw.invoices` | `create(**)`, `get(id)`, `list(**)`, `notify(id)` |
+| `paw.payouts` | `create(**, uniq_id=)`, `get(id)`, `list(**)`, `batch(items, uniq_id=)` |
+| `paw.ledger` | `list(type=, ...)` |
+| `paw.notifications` | `list(**)`, `test(url=)` |
+| `paw.permanent` | `create(**)`, `get(id)`, `list(**)`, `deactivate(id)` |
+
+`payouts.create` and `payouts.batch` accept an optional `uniq_id` for explicit
+idempotency (UUIDv4). When omitted the SDK generates one with `uuid.uuid4()`.
+A repeated `uniq_id` within 2 hours yields a 409.
+
+## Webhook verification
+
+```python
+from flask import Flask, request, abort
+from pawpayments import Webhook
+
+app = Flask(__name__)
+
+
+@app.post("/paw/webhook")
+def webhook():
+    raw = request.get_data()
+    sig = request.headers.get("X-Paw-Signature", "")
+    if not Webhook.verify_raw_body(raw, sig, API_KEY):
+        abort(401)
+    payload = Webhook.parse_payload(raw)
+    # …handle the invoice update…
+    return "", 200
+```
+
+## Errors
+
+```python
+from pawpayments import PawPaymentsApiError
+
+try:
+    paw.invoices.create(...)
+except PawPaymentsApiError as exc:
+    print(exc.code, exc.http_status, str(exc), exc.details)
+```
+
+## Testing
+
+- `pytest tests/test_webhook.py` — signature unit tests + PHP-interop parity.
+- `PAW_API_KEY=… pytest tests/test_live.py tests/test_negative.py` — live happy-path + negative-case suites against `https://api.pawpayments.com`. Tests skip when `PAW_API_KEY` is absent.
+
+## License
+
+MIT

pawpayments-2.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pawpayments"
+version = "2.0.0"
+description = "Official Python SDK for the PawPayments Native V2 API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "PawPayments", email = "support@pawpayments.com" }]
+requires-python = ">=3.9"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+  "Typing :: Typed",
+]
+dependencies = [
+  "requests>=2.28",
+  "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://pawpayments.com"
+Documentation = "https://docs.pawpayments.com"
+Source = "https://github.com/pawpayments/python-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pawpayments"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

pawpayments-2.0.0/src/pawpayments/__init__.py

@@ -0,0 +1,17 @@
+"""Official PawPayments Python SDK."""
+from ._async_client import AsyncPawPayments
+from ._client import PawPayments
+from ._models import ListResult, Pagination
+from .errors import PawPaymentsApiError
+from .webhook import Webhook
+
+__all__ = [
+    "PawPayments",
+    "AsyncPawPayments",
+    "PawPaymentsApiError",
+    "Webhook",
+    "ListResult",
+    "Pagination",
+]
+
+__version__ = "0.1.0"

pawpayments-2.0.0/src/pawpayments/_async_client.py

@@ -0,0 +1,152 @@
+"""Asynchronous client built on `httpx.AsyncClient`."""
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Optional
+
+import httpx
+
+from . import _resources as R
+from ._http import base_headers, decode_envelope, unwrap_list, unwrap_result
+from ._models import ListResult
+from .errors import PawPaymentsApiError
+
+
+class _AsyncResource:
+    def __init__(self, client: "AsyncPawPayments") -> None:
+        self._client = client
+
+
+class _AsyncAssets(_AsyncResource):
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._client._dispatch(R.assets_list())
+
+
+class _AsyncRates(_AsyncResource):
+    async def get(self, *, base: str = "USD", assets: Optional[Iterable[str] | str] = None) -> dict[str, Any]:
+        return await self._client._dispatch(R.rates_get(base=base, assets=assets))
+
+
+class _AsyncBalance(_AsyncResource):
+    async def get(self) -> dict[str, Any]:
+        return await self._client._dispatch(R.balance_get())
+
+
+class _AsyncInvoices(_AsyncResource):
+    async def create(self, **params: Any) -> dict[str, Any]:
+        return await self._client._dispatch(R.invoices_create(params))
+
+    async def get(self, order_id: str) -> dict[str, Any]:
+        return await self._client._dispatch(R.invoices_get(order_id))
+
+    async def list(self, **params: Any) -> ListResult:
+        return await self._client._dispatch_list(R.invoices_list(**params))
+
+    async def notify(self, order_id: str) -> dict[str, Any]:
+        return await self._client._dispatch(R.invoices_notify(order_id))
+
+
+class _AsyncPayouts(_AsyncResource):
+    async def create(self, *, uniq_id: Optional[str] = None, **params: Any) -> dict[str, Any]:
+        return await self._client._dispatch(R.payouts_create(params, uniq_id=uniq_id))
+
+    async def batch(self, items: list[Mapping[str, Any]], *, uniq_id: Optional[str] = None) -> dict[str, Any]:
+        return await self._client._dispatch(R.payouts_batch(items, uniq_id=uniq_id))
+
+    async def get(self, payout_id: str) -> dict[str, Any]:
+        return await self._client._dispatch(R.payouts_get(payout_id))
+
+    async def list(self, **params: Any) -> ListResult:
+        return await self._client._dispatch_list(R.payouts_list(**params))
+
+
+class _AsyncLedger(_AsyncResource):
+    async def list(self, **params: Any) -> ListResult:
+        return await self._client._dispatch_list(R.ledger_list(**params))
+
+
+class _AsyncNotifications(_AsyncResource):
+    async def list(self, **params: Any) -> ListResult:
+        return await self._client._dispatch_list(R.notifications_list(**params))
+
+    async def test(self, url: Optional[str] = None) -> dict[str, Any]:
+        return await self._client._dispatch(R.notifications_test(url))
+
+
+class _AsyncPermanent(_AsyncResource):
+    async def create(self, **params: Any) -> dict[str, Any]:
+        return await self._client._dispatch(R.permanent_create(params))
+
+    async def get(self, address_id: str) -> dict[str, Any]:
+        return await self._client._dispatch(R.permanent_get(address_id))
+
+    async def list(self, **params: Any) -> ListResult:
+        return await self._client._dispatch_list(R.permanent_list(**params))
+
+    async def deactivate(self, address_id: str) -> dict[str, Any]:
+        return await self._client._dispatch(R.permanent_deactivate(address_id))
+
+
+class AsyncPawPayments:
+    """Asynchronous PawPayments client (built on `httpx.AsyncClient`)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.pawpayments.com",
+        timeout: float = 30.0,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+        self.assets = _AsyncAssets(self)
+        self.rates = _AsyncRates(self)
+        self.balance = _AsyncBalance(self)
+        self.invoices = _AsyncInvoices(self)
+        self.payouts = _AsyncPayouts(self)
+        self.ledger = _AsyncLedger(self)
+        self.notifications = _AsyncNotifications(self)
+        self.permanent = _AsyncPermanent(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncPawPayments":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def _dispatch(self, spec: R.RequestSpec) -> Any:
+        envelope = await self._send(spec)
+        return unwrap_result(envelope)
+
+    async def _dispatch_list(self, spec: R.RequestSpec) -> ListResult:
+        envelope = await self._send(spec)
+        return unwrap_list(envelope)  # type: ignore[return-value]
+
+    async def _send(self, spec: R.RequestSpec) -> dict[str, Any]:
+        url = self._base_url + spec.path
+        headers = base_headers(self._api_key, spec.uniq_id)
+        kwargs: dict[str, Any] = {"headers": headers, "timeout": self._timeout}
+        if spec.query:
+            kwargs["params"] = spec.query
+        if spec.body is not None:
+            kwargs["json"] = spec.body
+        try:
+            response = await self._client.request(spec.method, url, **kwargs)
+        except httpx.HTTPError as exc:
+            raise PawPaymentsApiError(
+                f"Network error: {exc}", "NETWORK_ERROR", None
+            ) from exc
+        return decode_envelope(response.status_code, response.content or b"")

pawpayments-2.0.0/src/pawpayments/_client.py

@@ -0,0 +1,152 @@
+"""Synchronous client built on `requests`."""
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Optional
+
+import requests
+
+from . import _resources as R
+from ._http import base_headers, decode_envelope, unwrap_list, unwrap_result
+from ._models import ListResult
+from .errors import PawPaymentsApiError
+
+
+class _Resource:
+    def __init__(self, client: "PawPayments") -> None:
+        self._client = client
+
+
+class _Assets(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._client._dispatch(R.assets_list())
+
+
+class _Rates(_Resource):
+    def get(self, *, base: str = "USD", assets: Optional[Iterable[str] | str] = None) -> dict[str, Any]:
+        return self._client._dispatch(R.rates_get(base=base, assets=assets))
+
+
+class _Balance(_Resource):
+    def get(self) -> dict[str, Any]:
+        return self._client._dispatch(R.balance_get())
+
+
+class _Invoices(_Resource):
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._client._dispatch(R.invoices_create(params))
+
+    def get(self, order_id: str) -> dict[str, Any]:
+        return self._client._dispatch(R.invoices_get(order_id))
+
+    def list(self, **params: Any) -> ListResult:
+        return self._client._dispatch_list(R.invoices_list(**params))
+
+    def notify(self, order_id: str) -> dict[str, Any]:
+        return self._client._dispatch(R.invoices_notify(order_id))
+
+
+class _Payouts(_Resource):
+    def create(self, *, uniq_id: Optional[str] = None, **params: Any) -> dict[str, Any]:
+        return self._client._dispatch(R.payouts_create(params, uniq_id=uniq_id))
+
+    def batch(self, items: list[Mapping[str, Any]], *, uniq_id: Optional[str] = None) -> dict[str, Any]:
+        return self._client._dispatch(R.payouts_batch(items, uniq_id=uniq_id))
+
+    def get(self, payout_id: str) -> dict[str, Any]:
+        return self._client._dispatch(R.payouts_get(payout_id))
+
+    def list(self, **params: Any) -> ListResult:
+        return self._client._dispatch_list(R.payouts_list(**params))
+
+
+class _Ledger(_Resource):
+    def list(self, **params: Any) -> ListResult:
+        return self._client._dispatch_list(R.ledger_list(**params))
+
+
+class _Notifications(_Resource):
+    def list(self, **params: Any) -> ListResult:
+        return self._client._dispatch_list(R.notifications_list(**params))
+
+    def test(self, url: Optional[str] = None) -> dict[str, Any]:
+        return self._client._dispatch(R.notifications_test(url))
+
+
+class _Permanent(_Resource):
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._client._dispatch(R.permanent_create(params))
+
+    def get(self, address_id: str) -> dict[str, Any]:
+        return self._client._dispatch(R.permanent_get(address_id))
+
+    def list(self, **params: Any) -> ListResult:
+        return self._client._dispatch_list(R.permanent_list(**params))
+
+    def deactivate(self, address_id: str) -> dict[str, Any]:
+        return self._client._dispatch(R.permanent_deactivate(address_id))
+
+
+class PawPayments:
+    """Synchronous PawPayments client (built on `requests`)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.pawpayments.com",
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = session or requests.Session()
+        self._owns_session = session is None
+
+        self.assets = _Assets(self)
+        self.rates = _Rates(self)
+        self.balance = _Balance(self)
+        self.invoices = _Invoices(self)
+        self.payouts = _Payouts(self)
+        self.ledger = _Ledger(self)
+        self.notifications = _Notifications(self)
+        self.permanent = _Permanent(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def close(self) -> None:
+        if self._owns_session:
+            self._session.close()
+
+    def __enter__(self) -> "PawPayments":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _dispatch(self, spec: R.RequestSpec) -> Any:
+        envelope = self._send(spec)
+        return unwrap_result(envelope)
+
+    def _dispatch_list(self, spec: R.RequestSpec) -> ListResult:
+        envelope = self._send(spec)
+        return unwrap_list(envelope)  # type: ignore[return-value]
+
+    def _send(self, spec: R.RequestSpec) -> dict[str, Any]:
+        url = self._base_url + spec.path
+        headers = base_headers(self._api_key, spec.uniq_id)
+        kwargs: dict[str, Any] = {"headers": headers, "timeout": self._timeout}
+        if spec.query:
+            kwargs["params"] = spec.query
+        if spec.body is not None:
+            kwargs["json"] = spec.body
+        try:
+            response = self._session.request(spec.method, url, **kwargs)
+        except requests.RequestException as exc:
+            raise PawPaymentsApiError(
+                f"Network error: {exc}", "NETWORK_ERROR", None
+            ) from exc
+        return decode_envelope(response.status_code, response.content or b"")

pawpayments-2.0.0/src/pawpayments/_http.py

@@ -0,0 +1,72 @@
+"""Shared envelope/error decoding used by both sync and async transports."""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from .errors import PawPaymentsApiError
+
+DEFAULT_USER_AGENT = "pawpayments-python-sdk/0.1.0"
+
+
+def base_headers(api_key: str, uniq_id: Optional[str] = None) -> dict[str, str]:
+    headers = {
+        "x-api-key": api_key,
+        "Accept": "application/json",
+        "User-Agent": DEFAULT_USER_AGENT,
+    }
+    if uniq_id:
+        headers["x-uniq-id"] = uniq_id
+    return headers
+
+
+def decode_envelope(status: int, raw: bytes) -> dict[str, Any]:
+    if not raw:
+        if status >= 400:
+            raise PawPaymentsApiError(f"HTTP {status}", "UNKNOWN", status)
+        return {}
+    try:
+        decoded = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise PawPaymentsApiError(
+            f"Invalid JSON response (HTTP {status})", "INVALID_RESPONSE", status
+        ) from exc
+    if not isinstance(decoded, dict):
+        raise PawPaymentsApiError(
+            f"Invalid JSON response (HTTP {status})", "INVALID_RESPONSE", status
+        )
+    if status >= 400 or decoded.get("ok") is False:
+        err = decoded.get("error")
+        if isinstance(err, dict):
+            code = str(err.get("code") or "UNKNOWN")
+            message = str(err.get("message") or f"HTTP {status}")
+            details = err.get("details") if isinstance(err.get("details"), list) else None
+        else:
+            code = str(decoded.get("code") or err or "UNKNOWN")
+            message = str(decoded.get("message") or err or f"HTTP {status}")
+            details = None
+        raise PawPaymentsApiError(message, code, status, details)
+    return decoded
+
+
+def unwrap_result(envelope: dict[str, Any]) -> Any:
+    if "result" in envelope:
+        return envelope["result"]
+    if "data" in envelope:
+        return envelope["data"]
+    return envelope
+
+
+def unwrap_list(envelope: dict[str, Any]) -> dict[str, Any]:
+    items = envelope.get("result")
+    if items is None:
+        items = envelope.get("data") or []
+    if not isinstance(items, list):
+        items = []
+    pagination = envelope.get("pagination") or {
+        "page": 1,
+        "per_page": len(items),
+        "total": len(items),
+        "pages": 1,
+    }
+    return {"items": items, "pagination": pagination}

pawpayments-2.0.0/src/pawpayments/_models.py

@@ -0,0 +1,21 @@
+"""Lightweight typed result wrappers.
+
+These are TypedDicts so the SDK can stay dependency-light (no pydantic).
+At runtime they are just plain dicts; the typing exists for editor
+support only.
+"""
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class Pagination(TypedDict):
+    page: int
+    per_page: int
+    total: int
+    pages: int
+
+
+class ListResult(TypedDict):
+    items: list[dict[str, Any]]
+    pagination: Pagination

pawpayments-2.0.0/src/pawpayments/_resources.py

@@ -0,0 +1,122 @@
+"""Route specifications shared between the sync and async clients.
+
+Each resource method builds a ``RequestSpec`` describing how to call the
+HTTP API. The two transport implementations (`_client.PawPayments` and
+`_async_client.AsyncPawPayments`) wire the spec into their respective
+HTTP libraries so we don't repeat URL/query/body wiring twice.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping, Optional
+
+
+@dataclass
+class RequestSpec:
+    method: str
+    path: str
+    query: dict[str, Any] = field(default_factory=dict)
+    body: Optional[Any] = None
+    uniq_id: Optional[str] = None
+    paginated: bool = False
+
+
+def _drop_none(d: Mapping[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _join(value: Any) -> Any:
+    if isinstance(value, (list, tuple, set)) and not isinstance(value, str):
+        return ",".join(str(v) for v in value)
+    return value
+
+
+def assets_list() -> RequestSpec:
+    return RequestSpec("GET", "/api/v2/assets")
+
+
+def rates_get(*, base: str = "USD", assets: Optional[Iterable[str] | str] = None) -> RequestSpec:
+    return RequestSpec(
+        "GET",
+        "/api/v2/rates",
+        query=_drop_none({"base": base, "assets": _join(assets) if assets else None}),
+    )
+
+
+def balance_get() -> RequestSpec:
+    return RequestSpec("GET", "/api/v2/balance")
+
+
+def invoices_create(params: Mapping[str, Any]) -> RequestSpec:
+    return RequestSpec("POST", "/api/v2/invoices", body=dict(params))
+
+
+def invoices_get(order_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"/api/v2/invoices/{order_id}")
+
+
+def invoices_list(**params: Any) -> RequestSpec:
+    if "order_ids" in params:
+        params["order_ids"] = _join(params["order_ids"])
+    return RequestSpec("GET", "/api/v2/invoices", query=_drop_none(params), paginated=True)
+
+
+def invoices_notify(order_id: str) -> RequestSpec:
+    return RequestSpec("POST", f"/api/v2/invoices/{order_id}/notify")
+
+
+def payouts_create(params: Mapping[str, Any], uniq_id: Optional[str] = None) -> RequestSpec:
+    return RequestSpec(
+        "POST",
+        "/api/v2/payouts",
+        body=dict(params),
+        uniq_id=uniq_id or str(uuid.uuid4()),
+    )
+
+
+def payouts_batch(items: list[Mapping[str, Any]], uniq_id: Optional[str] = None) -> RequestSpec:
+    return RequestSpec(
+        "POST",
+        "/api/v2/payouts/batch",
+        body={"items": [dict(i) for i in items]},
+        uniq_id=uniq_id or str(uuid.uuid4()),
+    )
+
+
+def payouts_get(payout_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"/api/v2/payouts/{payout_id}")
+
+
+def payouts_list(**params: Any) -> RequestSpec:
+    if "order_ids" in params:
+        params["order_ids"] = _join(params["order_ids"])
+    return RequestSpec("GET", "/api/v2/payouts", query=_drop_none(params), paginated=True)
+
+
+def ledger_list(**params: Any) -> RequestSpec:
+    return RequestSpec("GET", "/api/v2/ledger", query=_drop_none(params), paginated=True)
+
+
+def notifications_list(**params: Any) -> RequestSpec:
+    return RequestSpec("GET", "/api/v2/notifications", query=_drop_none(params), paginated=True)
+
+
+def notifications_test(url: Optional[str] = None) -> RequestSpec:
+    return RequestSpec("POST", "/api/v2/notifications/test", body={"url": url} if url else {})
+
+
+def permanent_create(params: Mapping[str, Any]) -> RequestSpec:
+    return RequestSpec("POST", "/api/v2/permanent", body=dict(params))
+
+
+def permanent_get(address_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"/api/v2/permanent/{address_id}")
+
+
+def permanent_list(**params: Any) -> RequestSpec:
+    return RequestSpec("GET", "/api/v2/permanent", query=_drop_none(params), paginated=True)
+
+
+def permanent_deactivate(address_id: str) -> RequestSpec:
+    return RequestSpec("DELETE", f"/api/v2/permanent/{address_id}")

pawpayments-2.0.0/src/pawpayments/errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class PawPaymentsApiError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: str = "UNKNOWN",
+        http_status: Optional[int] = None,
+        details: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status
+        self.details = details
+
+    def __repr__(self) -> str:
+        return (
+            f"PawPaymentsApiError(code={self.code!r}, http_status={self.http_status!r}, "
+            f"message={str(self)!r})"
+        )

pawpayments-2.0.0/src/pawpayments/py.typed

@@ -0,0 +1 @@
+

pawpayments-2.0.0/src/pawpayments/webhook.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Union
+
+_BodyT = Union[str, bytes, bytearray, memoryview]
+
+
+def _to_bytes(body: _BodyT) -> bytes:
+    if isinstance(body, (bytes, bytearray, memoryview)):
+        return bytes(body)
+    return body.encode("utf-8")
+
+
+class Webhook:
+    @staticmethod
+    def verify_raw_body(raw_body: _BodyT, header_signature: str, api_key: str) -> bool:
+        if not header_signature:
+            return False
+        expected = hmac.new(api_key.encode("utf-8"), _to_bytes(raw_body), hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, header_signature)
+
+    @staticmethod
+    def parse_payload(raw_body: _BodyT) -> dict[str, Any]:
+        try:
+            data = json.loads(_to_bytes(raw_body).decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ValueError("Invalid webhook payload: not valid JSON") from exc
+        if not isinstance(data, dict):
+            raise ValueError("Invalid webhook payload: not valid JSON")
+        return data

pawpayments-2.0.0/tests/test_live.py

@@ -0,0 +1,105 @@
+import os
+
+import pytest
+
+from pawpayments import AsyncPawPayments, PawPayments
+
+API_KEY = os.environ.get("PAW_API_KEY")
+BASE = os.environ.get("PAW_BASE", "https://api.pawpayments.com")
+
+pytestmark = pytest.mark.skipif(not API_KEY, reason="PAW_API_KEY not set")
+
+
+@pytest.fixture
+def client():
+    with PawPayments(api_key=API_KEY, base_url=BASE) as c:
+        yield c
+
+
+@pytest.fixture
+async def async_client():
+    async with AsyncPawPayments(api_key=API_KEY, base_url=BASE) as c:
+        yield c
+
+
+def test_assets_list(client):
+    assets = client.assets.list()
+    assert isinstance(assets, list)
+    assert assets
+    assert any(a.get("enabled", True) for a in assets)
+
+
+def test_rates_get(client):
+    rates = client.rates.get(base="USD")
+    assert rates["base"] == "USD"
+    assert isinstance(rates["rates"], dict)
+    assert rates["rates"]
+
+
+def test_balance_get(client):
+    balance = client.balance.get()
+    assert isinstance(balance, dict)
+
+
+def test_invoices_create_get_list(client):
+    invoice = client.invoices.create(
+        amount=25,
+        fiat_currency="USD",
+        billing_type="STATIC",
+        asset="usdt_tron",
+        description="Python SDK live test",
+        ttl=1800,
+    )
+    assert invoice["order_id"]
+    fetched = client.invoices.get(invoice["order_id"])
+    assert fetched["order_id"] == invoice["order_id"]
+    page = client.invoices.list(page=1, per_page=5)
+    assert page["pagination"]["page"] == 1
+    assert isinstance(page["items"], list)
+
+
+def test_payouts_list_readonly(client):
+    page = client.payouts.list(page=1, per_page=5)
+    assert page["pagination"]["page"] == 1
+    assert isinstance(page["items"], list)
+
+
+def test_ledger_list(client):
+    page = client.ledger.list(page=1, per_page=5)
+    assert page["pagination"]["page"] == 1
+
+
+def test_notifications_list(client):
+    page = client.notifications.list(page=1, per_page=5)
+    assert isinstance(page["items"], list)
+
+
+def test_notifications_test_probe(client):
+    probe = client.notifications.test("https://httpbin.org/status/200")
+    assert probe["url"] == "https://httpbin.org/status/200"
+    assert "delivered" in probe
+
+
+def test_permanent_list(client):
+    page = client.permanent.list(page=1, per_page=5)
+    assert page["pagination"]["page"] == 1
+
+
+async def test_async_assets_list(async_client):
+    assets = await async_client.assets.list()
+    assert isinstance(assets, list)
+    assert assets
+
+
+async def test_async_invoices_round_trip(async_client):
+    invoice = await async_client.invoices.create(
+        amount=15,
+        fiat_currency="USD",
+        billing_type="STATIC",
+        asset="usdt_tron",
+        description="Async Python SDK live test",
+        ttl=1800,
+    )
+    assert invoice["order_id"]
+    fetched = await async_client.invoices.get(invoice["order_id"])
+    assert fetched["order_id"] == invoice["order_id"]

pawpayments-2.0.0/tests/test_negative.py

@@ -0,0 +1,81 @@
+import os
+
+import pytest
+
+from pawpayments import PawPayments, PawPaymentsApiError
+
+API_KEY = os.environ.get("PAW_API_KEY")
+BASE = os.environ.get("PAW_BASE", "https://api.pawpayments.com")
+
+pytestmark = pytest.mark.skipif(not API_KEY, reason="PAW_API_KEY not set")
+
+
+@pytest.fixture
+def client():
+    with PawPayments(api_key=API_KEY, base_url=BASE) as c:
+        yield c
+
+
+def test_bad_api_key_returns_4xx():
+    with PawPayments(api_key="definitely-not-valid", base_url=BASE) as bad:
+        with pytest.raises(PawPaymentsApiError) as exc:
+            bad.balance.get()
+        assert exc.value.http_status is not None
+        assert 400 <= exc.value.http_status < 500
+
+
+def test_invoices_create_empty_body_rejected(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.invoices.create()
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_invoices_create_unknown_asset_rejected(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.invoices.create(
+            amount=5,
+            fiat_currency="USD",
+            billing_type="STATIC",
+            asset="doge_doge",
+        )
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_invoices_create_negative_amount_rejected(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.invoices.create(
+            amount=-1,
+            fiat_currency="USD",
+            billing_type="STATIC",
+            asset="usdt_tron",
+        )
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_invoices_get_unknown_id(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.invoices.get("ffffffffffffffffffffffff")
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_payout_without_balance_or_ip(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.payouts.create(
+            address="TTestAddress1234567890",
+            amount=10,
+            fiat_currency="USD",
+            asset="usdt_tron",
+        )
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_payouts_get_unknown_id(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.payouts.get("ffffffffffffffffffffffff")
+    assert 400 <= (exc.value.http_status or 0) < 500
+
+
+def test_permanent_create_bad_family(client):
+    with pytest.raises(PawPaymentsApiError) as exc:
+        client.permanent.create(user_id="live-test-user", family="not_a_family")
+    assert 400 <= (exc.value.http_status or 0) < 500

pawpayments-2.0.0/tests/test_webhook.py

@@ -0,0 +1,79 @@
+import hashlib
+import hmac
+import shutil
+import subprocess
+
+import pytest
+
+from pawpayments import Webhook
+
+API_KEY = "test_api_key_abc123"
+
+
+def _sig(message: bytes | str) -> str:
+    if isinstance(message, str):
+        message = message.encode()
+    return hmac.new(API_KEY.encode(), message, hashlib.sha256).hexdigest()
+
+
+def test_verify_raw_body_valid():
+    body = '{"order_id":"abc","status":"success"}'
+    assert Webhook.verify_raw_body(body, _sig(body), API_KEY) is True
+
+
+def test_verify_raw_body_bad_signature():
+    body = '{"order_id":"abc","status":"success"}'
+    assert Webhook.verify_raw_body(body, "deadbeef", API_KEY) is False
+
+
+def test_verify_raw_body_tampered():
+    body = '{"order_id":"abc","status":"success"}'
+    sig = _sig(body)
+    assert Webhook.verify_raw_body('{"order_id":"abc","status":"cancelled"}', sig, API_KEY) is False
+
+
+def test_verify_raw_body_bytes_input():
+    body = '{"order_id":"abc"}'
+    assert Webhook.verify_raw_body(body.encode(), _sig(body), API_KEY) is True
+
+
+def test_verify_raw_body_empty_signature():
+    assert Webhook.verify_raw_body("{}", "", API_KEY) is False
+
+
+def test_parse_payload_object():
+    body = '{"order_id":"abc","status":"success","amount":100.5}'
+    payload = Webhook.parse_payload(body)
+    assert payload["order_id"] == "abc"
+    assert payload["amount"] == 100.5
+
+
+def test_parse_payload_invalid_json():
+    with pytest.raises(ValueError):
+        Webhook.parse_payload("not json")
+
+
+def test_parse_payload_array_rejected():
+    with pytest.raises(ValueError):
+        Webhook.parse_payload("[1,2,3]")
+
+
+@pytest.mark.skipif(shutil.which("php") is None, reason="PHP not installed")
+def test_php_interop_round_trip(tmp_path):
+    """PHP `Webhook::verifyRawBody` from the official PHP SDK must accept
+    our Python-generated signature unchanged."""
+    body = '{"order_id":"abc","status":"success"}'
+    sig = _sig(body)
+    php_code = (
+        "$body = file_get_contents($argv[1]);"
+        "$expected = hash_hmac('sha256', $body, $argv[3]);"
+        "echo hash_equals($expected, $argv[2]) ? 'OK' : 'BAD';"
+    )
+    body_file = tmp_path / "body.json"
+    body_file.write_text(body)
+    proc = subprocess.run(
+        ["php", "-r", php_code, str(body_file), sig, API_KEY],
+        capture_output=True,
+        timeout=5,
+    )
+    assert proc.stdout.strip() == b"OK", proc.stdout + proc.stderr