qvard 0.1.0__py3-none-any.whl

qvard/__init__.py

@@ -0,0 +1,137 @@
+"""Qvard payments API client. See README.md."""
+import http.client
+import json
+import socket
+import urllib.error
+import urllib.request
+from types import SimpleNamespace
+from typing import Any, Callable, Dict, Optional, Tuple
+from urllib.parse import quote
+
+from . import webhooks
+from .errors import PAYOUT_UNKNOWN_RESULT, QvardError, QvardNetworkError, error_from_response, network_error
+
+__all__ = ['Qvard', 'QvardError', 'QvardNetworkError', 'convert_for_display', 'webhooks']
+__version__ = '0.1.0'
+
+# A 3xx is an error here, not a hop: a redirect could send the Authorization header to another host.
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _urllib_send(method: str, url: str, headers: Dict[str, str], data: Optional[bytes],
+                 timeout_ms: int) -> Tuple[int, str]:
+    # shortcut: timeout_ms bounds each socket operation, not the whole request (Node bounds the whole request),
+    # upgrade to a total deadline if a server that trickles bytes becomes a real case
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with _OPENER.open(request, timeout=timeout_ms / 1000) as res:
+            return res.status, res.read().decode('utf-8', 'replace')
+    except urllib.error.HTTPError as e:
+        with e:
+            return e.code, e.read().decode('utf-8', 'replace')
+
+
+def _parse_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None  # a proxy's HTML page, an empty body
+
+
+class Qvard:
+    """Client for the payments API.
+
+    `secret_key` is your secret key, `qvard_sk_...`. Never put it in browser code: `qvard_pk_` is the public key.
+    Raises ValueError on an empty key, a `qvard_pk_` key, and a key without the `qvard_sk_` prefix.
+    `transport` replaces the HTTP layer (tests): called as (method, url, headers, body_bytes_or_None, timeout_ms),
+    returns (status, text), raises OSError on a network failure.
+    """
+
+    def __init__(self, secret_key: str, base_url: str = 'https://api.qvard.com', timeout_ms: int = 30000,
+                 transport: Optional[Callable[..., Tuple[int, str]]] = None):
+        if not secret_key:
+            raise ValueError('Qvard: secret key is required')
+        if secret_key.startswith('qvard_pk_'):
+            raise ValueError('Qvard: publishable key (qvard_pk_) is for the browser only; use the secret key (qvard_sk_) on the server')
+        if not secret_key.startswith('qvard_sk_'):
+            raise ValueError('Qvard: legacy keys without the qvard_sk_ prefix are not supported; rotate the key in the cabinet')
+
+        self._secret_key = secret_key
+        self._base_url = base_url.rstrip('/')
+        self._timeout_ms = timeout_ms
+        self._transport = transport or _urllib_send
+
+        # Only the listed fields are sent: `publishable_key` cannot reach the server from this client.
+        self.payments = SimpleNamespace(create=self._payment_create, get=self._payment_get)
+        self.payouts = SimpleNamespace(create=self._payout_create)
+        self.methods = SimpleNamespace(info=self._method_info)
+        self.rates = SimpleNamespace(list=self._rates_list)
+        # Webhook signature checks. Needs no network, only the shop secret key.
+        self.webhooks = webhooks
+
+    def _payment_create(self, id: str, price: float, currency: Optional[str] = None,
+                        payment_system_id: Optional[int] = None) -> Dict[str, Any]:
+        """Create a payment. Returns the uuid and the page to send the payer to."""
+        return self._request('POST', '/api/v1/payment', {
+            'id': id, 'price': price, 'currency': currency, 'paymentSystemId': payment_system_id,
+        })
+
+    def _payment_get(self, id: str) -> Dict[str, Any]:
+        """One payment of your shop, by the uuid that `create` returned. Another shop's payment is `error.notfound`."""
+        return self._request('GET', f'/api/v1/payment/{quote(str(id), safe="")}')
+
+    def _payout_create(self, id: str, price: float, method_id: int, address: str,
+                       comment: Optional[str] = None) -> Any:
+        """Send money out. Not retried automatically. On a timeout, a network error, a 5xx or an answer that is not JSON
+        the result is unknown: the `friendly_message` says so. Repeat only with the same `id` (see README)."""
+        return self._request('POST', '/api/v1/payout', {
+            'id': id, 'price': price, 'methodId': method_id, 'comment': comment, 'address': address,
+        }, payout=True)
+
+    def _method_info(self, id: int) -> Dict[str, Any]:
+        """Status of a payment method of your shop, by its id from the cabinet."""
+        return self._request('GET', f'/api/v1/method/{quote(str(id), safe="")}/info')
+
+    def _rates_list(self) -> Dict[str, Any]:
+        """Current rates, for display only: the server computes the amount a payment costs."""
+        return self._request('GET', '/api/v1/rates')
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, payout: bool = False) -> Any:
+        headers = {'Authorization': f'Bearer {self._secret_key}', 'Content-Type': 'application/json'}
+        data = None
+        if body is not None:
+            data = json.dumps({k: v for k, v in body.items() if v is not None}).encode('utf-8')
+        try:
+            status, text = self._transport(method, self._base_url + path, headers, data, self._timeout_ms)
+        except (OSError, http.client.HTTPException) as e:
+            raise network_error(e, isinstance(getattr(e, 'reason', e), socket.timeout), payout) from e
+
+        parsed = _parse_json(text)
+        if payout and (status >= 500 or (200 <= status <= 299 and not isinstance(parsed, dict))):
+            # The answer is lost or unreadable: the payout may have been created.
+            err = error_from_response(status, parsed)
+            raise QvardError(status, err.message, err.errors, err.request_id, PAYOUT_UNKNOWN_RESULT)
+        if not 200 <= status <= 299:
+            raise error_from_response(status, parsed)
+
+        return parsed.get('data') if isinstance(parsed, dict) else None
+
+
+def convert_for_display(amount: float, from_: str, to: str, rates: Dict[str, float]) -> float:
+    """Display only: converts `amount` between two currencies with the rates from `rates.list()` (units per 1 USD).
+    The server computes the amount a payment actually costs; do not charge this number.
+    Raises ValueError when a currency has no rate (USD is always 1)."""
+    def per_usd(code: str) -> Optional[float]:
+        return 1 if code == 'USD' else rates.get(code)
+
+    from_rate = per_usd(from_)
+    to_rate = per_usd(to)
+    if not from_rate or not to_rate:
+        raise ValueError(f"Qvard: no rate for {to if from_rate else from_}")
+
+    return (amount / from_rate) * to_rate

qvard/errors.py

@@ -0,0 +1,67 @@
+"""Errors and the friendly-message dictionary. The dictionary is a copy of sdk/conformance/errors.json:
+the package ships without that folder, and tests/test_qvard.py fails if the two drift apart."""
+from typing import Any, Dict, Optional
+
+ERROR_MESSAGES: Dict[str, str] = {
+    'error.wrong.api.key': 'Invalid or missing API key',
+    'error.notfound': 'Not found in your shop',
+    'error.shop.not.active': 'Shop is not active',
+    'error.payment.duplicate_id': 'A payment with this id already exists and cannot be replaced (different amount, or already paid)',
+    'error.origin.not_allowed': "Request origin is not in the shop's allowed list",
+    'error.origin.not_configured': 'The shop has no allowed origins configured for this key',
+    'error.internal': "Internal error on Qvard's side; quote traceId to support",
+    'Error validation': 'Request validation failed; see errors for each field',
+    'unsupported_currency': 'Currency is not supported',
+    'invalid_amount_precision': 'Amount has more decimal places than this currency allows',
+    'rate_unavailable': 'No exchange rate is available for this currency right now',
+    'ThrottlerException: Too Many Requests': 'Too many requests, retry later',
+}
+
+# Shown instead of the generic network text for payouts: the money may already have moved.
+PAYOUT_UNKNOWN_RESULT = 'Result unknown: check whether the payout went through before retrying (reuse the same id).'
+
+
+class QvardError(Exception):
+    """An answer from the server. `message` is the raw key (`error.*`) or text, as the server sent it."""
+
+    def __init__(self, status: int, message: str, errors: Optional[Any] = None,
+                 request_id: Optional[str] = None, friendly_message: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.errors = errors
+        # The server's `traceId`; quote it to Qvard support.
+        self.request_id = request_id
+        self.friendly_message = ERROR_MESSAGES.get(message, message) if friendly_message is None else friendly_message
+
+
+class QvardNetworkError(QvardError):
+    """No answer arrived (DNS, connection, TLS) or the request timed out. `status` is 0."""
+
+    def __init__(self, message: str, friendly_message: str):
+        super().__init__(0, message, None, None, friendly_message)
+
+
+def error_from_response(status: int, body: Any) -> QvardError:
+    json_body = body if isinstance(body, dict) else {}
+    message = json_body.get('message')
+    errors = json_body.get('errors')
+    request_id = json_body.get('traceId')
+
+    return QvardError(
+        status,
+        message if isinstance(message, str) else f'HTTP {status}',
+        errors if isinstance(errors, (dict, list)) else None,
+        request_id if isinstance(request_id, str) else None,
+    )
+
+
+def network_error(cause: BaseException, timed_out: bool, payout: bool) -> QvardNetworkError:
+    if timed_out:
+        plain = 'Request timed out'
+        message = 'timeout'
+    else:
+        plain = 'Network error'
+        message = f'network: {cause}'
+
+    return QvardNetworkError(message, PAYOUT_UNKNOWN_RESULT if payout else plain)

qvard/webhooks.py

@@ -0,0 +1,51 @@
+"""Checks `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`: HMAC-SHA256 with the shop's secret key over `t + "." + rawBody`.
+Pass the RAW body (bytes or str, as received), not re-serialised JSON."""
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Optional, Union
+
+
+def verify(raw_body: Union[str, bytes], header: Optional[str], secret: str,
+           tolerance_sec: int = 300, now: Optional[int] = None) -> bool:
+    """Returns False for a bad, missing or stale signature; raises ValueError only when no secret is given.
+    `tolerance_sec` bounds |now - t| in both directions. Any `v1` may match (two while a key rotation is live).
+    `now` (unix seconds) overrides the clock; for tests."""
+    if not secret:
+        raise ValueError('Qvard: webhook secret is required')
+
+    t = None
+    v1 = []
+    for part in (header or '').split(','):
+        key, *rest = part.split('=')
+        value = '='.join(rest).strip()
+        if key.strip() == 't' and t is None:
+            t = value
+        elif key.strip() == 'v1':
+            v1.append(value)
+    if not t or not re.fullmatch(r'[0-9]+', t):
+        return False
+    if abs((int(time.time()) if now is None else now) - int(t)) > tolerance_sec:
+        return False
+
+    expected = hmac.new(secret.encode('utf-8'), t.encode('ascii') + b'.' + _bytes(raw_body), hashlib.sha256).hexdigest()
+
+    return any(
+        re.fullmatch(r'[0-9a-fA-F]{64}', hex_sig) is not None and hmac.compare_digest(expected, hex_sig.lower())
+        for hex_sig in v1
+    )
+
+
+def construct_event(raw_body: Union[str, bytes], header: Optional[str], secret: str,
+                    now: Optional[int] = None) -> Any:
+    """Verifies, then parses the raw body. Raises ValueError when the signature does not verify."""
+    if not verify(raw_body, header, secret, now=now):
+        raise ValueError('Qvard: invalid webhook signature, or timestamp outside the tolerance')
+
+    return json.loads(_bytes(raw_body).decode('utf-8'))
+
+
+def _bytes(raw_body: Union[str, bytes]) -> bytes:
+    return raw_body.encode('utf-8') if isinstance(raw_body, str) else raw_body

qvard-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: qvard
+Version: 0.1.0
+Summary: Qvard payments API client for Python: payments, payouts, rates and webhook signature checks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# qvard (Python)
+
+Python client for the Qvard payments API. Zero dependencies (standard library only), Python 3.9 or newer.
+
+## Install
+
+```sh
+pip install qvard
+```
+
+## Quick start
+
+```python
+import os
+from qvard import Qvard
+
+qvard = Qvard(os.environ['QVARD_SECRET_KEY'])  # qvard_sk_...
+
+payment = qvard.payments.create(id='order-1001', price=10, currency='EUR')
+# send the payer to payment['redirectUrl']
+
+info = qvard.payments.get(payment['id'])
+print(info['status'])  # wait | partial | completed | rejected
+```
+
+Options: `Qvard(secret_key, base_url='https://api.qvard.com', timeout_ms=30000)`. `timeout_ms` is in milliseconds.
+
+## Keys
+
+- Use the secret key `qvard_sk_...` on your server only. Never put it in browser or mobile code. A publishable key (`qvard_pk_...`) is rejected by the constructor because it is for the browser only.
+- Legacy keys without the `qvard_sk_` prefix are rejected by the constructor. Rotate the key in the cabinet (Shop settings → API keys) to get a `qvard_sk_...` key.
+- The SDK sends `Authorization: Bearer <key>`. It never sends `x-api-key`.
+
+## Methods
+
+| Call | Request | Returns |
+| --- | --- | --- |
+| `payments.create(id=, price=, currency=None, payment_system_id=None)` | `POST /api/v1/payment` | `{id, redirectUrl, telegramUrl?}` |
+| `payments.get(id)` | `GET /api/v1/payment/:id` | `{id, status, createdAt, paidAt, price, currency, paidAmount, token, expiresAt}` |
+| `payouts.create(id=, price=, method_id=, address=, comment=None)` | `POST /api/v1/payout` | `True` |
+| `methods.info(id)` | `GET /api/v1/method/:id/info` | `{server, isReady, isActive}` |
+| `rates.list()` | `GET /api/v1/rates` | `{base, updatedAt, rates}` |
+
+The results are the server's `data` as dictionaries, with the server's field names (camelCase).
+
+- `id` in `payments.create` is your own order id. The server requires it. The same id with the same amount and currency returns the existing payment. A different amount replaces an unpaid one, and the server answers `409` once money is on the way.
+- `payments.get` answers `error.notfound` for a payment of another shop, the same as for an unknown uuid.
+- `price` is sent as you give it. The server converts it to USD at the current rate and stores that rate with the payment. Unset optional arguments (`None`) are not sent.
+- `convert_for_display(amount, from_, to, rates)` is exported for showing prices only. Pass `qvard.rates.list()['rates']`. The total a payer pays is computed by the server; do not charge the value this function returns. It raises `ValueError` for a currency without a rate.
+
+## Payouts
+
+`payouts.create` sends money out of your balance. Read this before you call it.
+
+- The SDK never retries a payout.
+- The result is **unknown** on a timeout, a network error, a `5xx` answer (including `502`, `503` and `504` from a gateway), or a `2xx` answer whose body is not a JSON object (an array, a string, `null` or an empty body). The error's `friendly_message` says: `Result unknown: check whether the payout went through before retrying (reuse the same id).`. A payout may have been created. In that case the error's `status` is the HTTP status and `message` is the server's key, or `HTTP <status>` when there is none.
+- A `4xx` answer is a refusal: the payout was not created, and `message` is the reason (for example `Insufficient balance`).
+- To retry safely, send the same `id` and the same arguments as the first attempt. See the next section.
+
+### Payout idempotency
+
+What protects a payout from being paid twice is the `id` field of the request body, which is your payout id.
+
+- The server requires `id`: without it the answer is `400`.
+- The server stores `id` on the withdrawal as its idempotency key. Before it creates a withdrawal it looks for an existing withdrawal of your shop with the same method and the same key. If it finds one, it returns that one and creates nothing.
+- The lookup runs under a database lock for your shop and method, so two simultaneous requests with the same `id` cannot both create a payout.
+- Scope: the key is matched within your shop and the `method_id`. The same `id` on a different method creates a second payout. The same `id` in a different shop is independent.
+- A repeated request with the same `id` returns the original payout, and the API answers `True` exactly as it does for a new payout. The response does not say that it was a replay.
+- A repeated request with the same `id` but a different `price`, `address` or `comment` is not compared. The original payout stands and the new values are ignored.
+- The lookup finds only payouts that were created. A request that was rejected with `400` (for example `Insufficient balance`) created nothing, so sending it again with the same `id` is a new attempt.
+- After a key rotation the previous key is not accepted on `POST /api/v1/payout`, even during the 24-hour grace period.
+- v1 has no endpoint to look up a payout by your id. To check whether a payout from a timed-out call exists, look in the cabinet.
+
+## Webhooks
+
+Qvard calls your callback URL with a JSON body and the header `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`. The signature is HMAC-SHA256, keyed with your secret key, over `t + "." + body`. Two `v1` values are sent for 24 hours after a key rotation, and either one is valid.
+
+Verify the signature over the **raw** body, before any JSON parsing. Read the body as bytes from your framework (not from a parsed form or JSON object):
+
+```python
+import os
+from qvard import Qvard
+
+secret = os.environ['QVARD_SECRET_KEY']
+qvard = Qvard(secret)
+
+def handle_webhook(raw_body: bytes, signature_header: str) -> int:
+    """Returns the HTTP status to answer with."""
+    try:
+        event = qvard.webhooks.construct_event(raw_body, signature_header, secret)
+    except ValueError:
+        return 400
+    # event['id'] is YOUR order id (the one you passed to payments.create), not the payment uuid.
+    # Check event['amount'] and event['currency'] against your order before you fulfil it.
+    return 200
+```
+
+- `qvard.webhooks.verify(raw_body, header, secret, tolerance_sec=300)` returns `True` or `False`. It raises `ValueError` only when no secret is given.
+- `qvard.webhooks.construct_event(raw_body, header, secret)` returns the parsed event, or raises `ValueError` when the signature fails.
+- `raw_body` may be `bytes` or `str`. The check accepts a timestamp within `tolerance_sec` (300 seconds) of now, in either direction, and accepts any `v1` that matches. The comparison is constant-time.
+- The event body is `{id, status, paymentLink?, customerEmail?, amount, currency, amountUsd, rate}`. There is no event `type` field.
+- Answer `200`. Qvard treats any other status as a failed delivery and retries it.
+
+## Errors
+
+Every failed call raises `QvardError`:
+
+- `status`: the HTTP status.
+- `message` (also `str(error)`): the server's key, for example `error.wrong.api.key`, or the text it sent.
+- `friendly_message`: an English explanation from the shared dictionary (`sdk/conformance/errors.json`, copied into the package). An unknown key is returned as is.
+- `errors`: for a rejected request body, a map from each field to its first message.
+- `request_id`: the server's `traceId`. Quote it to Qvard support.
+
+A request that got no answer (connection error, DNS, timeout) raises `QvardNetworkError`, a subclass of `QvardError` with `status` 0.
+
+```python
+from qvard import QvardError, QvardNetworkError
+
+try:
+    qvard.payments.get(uuid)
+except QvardNetworkError as e:
+    print('no answer:', e.friendly_message)
+except QvardError as e:
+    print(e.status, e.message, e.friendly_message, e.request_id)
+```
+
+| `message` | Status | Meaning |
+| --- | --- | --- |
+| `error.wrong.api.key` | 401 | Missing or unknown key |
+| `error.notfound` | 404 | Not in your shop |
+| `error.shop.not.active` | 403 | Shop is not active |
+| `error.origin.not_allowed` | 403 | Origin not in the allowed list (publishable-key flow only) |
+| `error.origin.not_configured` | 403 | No allowed origins configured (publishable-key flow only) |
+| `error.payment.duplicate_id` | 409 | Same id, but a different amount, or the payment is already paid |
+| `Error validation` | 400 | Body rejected; see `errors` |
+| `unsupported_currency` | 422 | Currency not supported |
+| `invalid_amount_precision` | 422 | Too many decimal places for the currency |
+| `rate_unavailable` | 422 | No rate for the currency right now |
+| `ThrottlerException: Too Many Requests` | 429 | Rate limit |
+| `error.internal` | 500 | Failure inside Qvard; quote `request_id` |
+
+Payout rejections come back as plain English text, for example `Insufficient balance`, `Method not found` or `Invalid TRON withdrawal address`, with status 400. The dictionary does not list them; `friendly_message` equals `message` for them.
+
+## Differences from the Node.js package
+
+- Redirects are not followed. A `3xx` answer is raised as a `QvardError`, so the secret key is never sent to another host. (`@qvard-sdk/node` does the same.)
+- `timeout_ms` bounds each socket operation (connecting, each read), not the whole request.
+
+## Tests
+
+No test dependencies. From `sdk/python`:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+The tests read the shared fixtures from `../conformance`, so they run inside the `sdk/` folder.

qvard-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+qvard/__init__.py,sha256=TD6Wc2rb8wm1twrPbSOiC9mxihy7CNZpNynMkvE_Jr0,6945
+qvard/errors.py,sha256=dpcjh3vyx1MpmvGZ6QfJR-dbN3E18zLHAsJb8YIf8Mw,3153
+qvard/webhooks.py,sha256=C69LqnXChw9wQpm4JlyPlrdXhdpp7HqKIHjvt4c2XnM,2124
+qvard-0.1.0.dist-info/METADATA,sha256=IEFYJCvaD9dq0SOR19t4_aeuyja_GE_0hP1-RsR32HY,9494
+qvard-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+qvard-0.1.0.dist-info/top_level.txt,sha256=7DcNB7l1qX_fRfDIIrG1nIBJ6dDhIhNIB7fgTAWYnfI,6
+qvard-0.1.0.dist-info/RECORD,,

qvard-0.1.0.dist-info/WHEEL

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

qvard-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+qvard