heleket-sdk 0.3.0__py3-none-any.whl

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/_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())

heleket_sdk/_cli.py

@@ -0,0 +1,137 @@
+"""``heleket-webhook-inspect`` — verify a captured webhook payload.
+
+Usage::
+
+    # Preferred: pass the API key via env var so it doesn't land in shell
+    # history or appear in `ps` output.
+    export HELEKET_API_KEY=$HELEKET_PAYMENT_KEY
+    echo '{"type":"payment",...}' | heleket-webhook-inspect
+
+    # Or pass it explicitly (less safe — recorded in shell history).
+    heleket-webhook-inspect --key=$KEY --file=webhook.json
+    heleket-webhook-inspect --key=$KEY --type=payout --file=webhook.json
+
+Exit codes:
+
+* ``0`` — payload valid, signature verified
+* ``1`` — payload could not be parsed
+* ``2`` — signature does not match
+* ``3`` — missing arguments
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._errors import SignatureError
+from .webhook import WebhookVerifier
+
+_COLOR_RESET = "\x1b[0m"
+_COLOR_RED = "\x1b[31m"
+_COLOR_GREEN = "\x1b[32m"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="heleket-webhook-inspect",
+        description="Verify a captured Heleket webhook payload.",
+    )
+    parser.add_argument(
+        "--key",
+        required=False,
+        help=(
+            "API key used to sign the webhook. Falls back to the HELEKET_API_KEY "
+            "env var if omitted (preferred — keeps the key out of shell history)."
+        ),
+    )
+    parser.add_argument("--file", help="Path to a webhook JSON file. Defaults to stdin.")
+    parser.add_argument("--type", help="Expected payload type (payment | payout | wallet)")
+    args = parser.parse_args(argv)
+
+    api_key = args.key or os.environ.get("HELEKET_API_KEY", "")
+    if not api_key:
+        sys.stderr.write(
+            "Usage: heleket-webhook-inspect [--key=<api-key>] "
+            "[--file=<path>] [--type=payment|payout]\n"
+            "Set HELEKET_API_KEY in the environment to avoid passing the key on "
+            "the command line.\n"
+        )
+        return 3
+
+    body = Path(args.file).read_text(encoding="utf-8") if args.file else sys.stdin.read()
+
+    # Trim trailing newline added by shells / editors — Heleket signs the exact
+    # bytes it sends, which never have a trailing newline.
+    body = body.rstrip("\r\n")
+
+    if not body:
+        sys.stderr.write("No input received. Pipe a JSON payload to stdin or pass --file=<path>.\n")
+        return 1
+
+    try:
+        parsed: dict[str, Any] = json.loads(body)
+    except json.JSONDecodeError as error:
+        sys.stderr.write(f"Input is not valid JSON: {error}\n")
+        return 1
+
+    print("Heleket webhook inspector")
+    print("-" * 40)
+    for field in ("type", "uuid", "order_id", "status", "amount", "network", "txid"):
+        _print_field(field, parsed.get(field))
+
+    if "is_final" in parsed:
+        value = parsed["is_final"]
+        text = "yes" if value is True else "no" if value is False else str(value)
+        print(f"  {'is_final':<10} {text}")
+    else:
+        print(f"  {'is_final':<10} (missing)")
+
+    sign_value = parsed.get("sign")
+    if isinstance(sign_value, str):
+        truncated = sign_value if len(sign_value) <= 16 else sign_value[:16] + "…"
+        print(f"  {'sign':<10} {truncated}")
+    else:
+        print(f"  {'sign':<10} (missing)")
+
+    if args.type and parsed.get("type") and args.type != parsed["type"]:
+        sys.stderr.write(f"\nWarning: --type={args.type} but payload type is {parsed['type']}\n")
+
+    try:
+        WebhookVerifier(api_key).verify_raw(body)
+    except SignatureError as error:
+        print()
+        print(f"signature: {_COLOR_RED}INVALID{_COLOR_RESET} — {error.reason}")
+        print("Hints:")
+        print("  - Are you using the same API key that was configured when the webhook was sent?")
+        print(
+            "  - Payment webhooks sign with the payment key; "
+            "payout webhooks sign with the payout key."
+        )
+        print(
+            "  - If you re-serialised the payload before passing it here, "
+            "the slash escaping may have been lost."
+        )
+        return 2
+
+    print()
+    print(f"signature: {_COLOR_GREEN}valid{_COLOR_RESET}")
+    return 0
+
+
+def _print_field(name: str, value: Any) -> None:
+    label = f"  {name:<10}"
+    if value is None:
+        print(f"{label} (missing)")
+    elif isinstance(value, str):
+        print(f"{label} {value}")
+    else:
+        print(f"{label} {json.dumps(value)}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

heleket_sdk/_config.py

@@ -0,0 +1,43 @@
+"""Client options for :class:`HeleketPayment` / :class:`HeleketPayout`.
+
+:class:`ClientOptions` is a plain dataclass — not a Pydantic model — because
+it can hold non-serialisable values like a ``DebugSink`` callable or a
+custom transport.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ._debug import DebugSink, stderr_sink
+
+if TYPE_CHECKING:
+    from ._transport import Transport
+
+__all__ = ["ClientOptions", "DEFAULT_BASE_URL", "DEFAULT_TIMEOUT_SECONDS"]
+
+DEFAULT_BASE_URL = "https://api.heleket.com"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+@dataclass(slots=True)
+class ClientOptions:
+    """Optional settings passed to ``HeleketPayment`` / ``HeleketPayout``.
+
+    ``transport`` defaults to a fresh :class:`RequestsTransport` lazily, so
+    constructing ``ClientOptions()`` doesn't open a TCP socket pool.
+    """
+
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+    debug: bool = False
+    logger: DebugSink = field(default=stderr_sink)
+    transport: Transport | None = None
+
+    def __post_init__(self) -> None:
+        # Normalise the base URL (drop trailing slashes) so callers can pass
+        # either form interchangeably.
+        self.base_url = self.base_url.rstrip("/")
+        if self.timeout <= 0:
+            raise ValueError("timeout must be > 0")

heleket_sdk/_debug.py

@@ -0,0 +1,63 @@
+"""Debug logging for the Heleket SDK.
+
+A :class:`DebugSink` receives :class:`DebugEntry` objects when the client is
+constructed with ``debug=True``. The default sink writes one line per entry
+to ``stderr``; plug in your own to route to ``logging``, ``structlog``, or
+anywhere else.
+
+**Security:** entries never carry the API key or the ``sign`` header.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = ["DebugEntry", "DebugSink", "stderr_sink"]
+
+EntryKind = Literal["request", "response", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class DebugEntry:
+    """A single debug event.
+
+    Use the ``request``/``response``/``error`` classmethods rather than the
+    constructor when calling from your own code.
+    """
+
+    kind: EntryKind
+    method: str | None = None
+    url: str | None = None
+    body: str | None = None
+    status: int | None = None
+    message: str | None = None
+
+    @classmethod
+    def request(cls, method: str, url: str, body: str) -> DebugEntry:
+        return cls(kind="request", method=method, url=url, body=body)
+
+    @classmethod
+    def response(cls, status: int, body: str) -> DebugEntry:
+        return cls(kind="response", status=status, body=body)
+
+    @classmethod
+    def error(cls, message: str) -> DebugEntry:
+        return cls(kind="error", message=message)
+
+
+DebugSink = Callable[[DebugEntry], None]
+
+
+def stderr_sink(entry: DebugEntry) -> None:
+    """Default :class:`DebugSink`. Writes a one-line summary per entry to ``stderr``."""
+    if entry.kind == "request":
+        body = entry.body if entry.body else "(empty body)"
+        print(f"[heleket][→ {entry.method} {entry.url}] {body}", file=sys.stderr)
+    elif entry.kind == "response":
+        body = entry.body if entry.body else "(empty body)"
+        print(f"[heleket][← {entry.status}] {body}", file=sys.stderr)
+    elif entry.kind == "error":
+        print(f"[heleket][error] {entry.message}", file=sys.stderr)

heleket_sdk/_errors.py

@@ -0,0 +1,67 @@
+"""Exception hierarchy for the Heleket SDK.
+
+All exceptions extend :class:`HeleketError`, which is a plain ``Exception`` —
+they're unchecked in the Python sense. Catch the specific subclass you care
+about, or :class:`HeleketError` to handle the SDK's whole surface uniformly.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "HeleketError",
+    "ApiError",
+    "ValidationError",
+    "HttpError",
+    "SignatureError",
+]
+
+
+class HeleketError(Exception):
+    """Base class for every exception raised by the SDK."""
+
+
+class ApiError(HeleketError):
+    """Raised when Heleket responds with ``state != 0`` (business error).
+
+    Carries the HTTP status and raw response body so callers can log or
+    surface the exact server reply.
+    """
+
+    def __init__(self, message: str, http_status: int = 0, raw_body: str = "") -> None:
+        super().__init__(message)
+        self.http_status = http_status
+        self.raw_body = raw_body
+
+
+class ValidationError(ApiError):
+    """Raised on HTTP 422. Carries a ``fields`` dict mapping field → messages."""
+
+    def __init__(
+        self,
+        message: str,
+        http_status: int,
+        fields: dict[str, list[str]],
+        raw_body: str = "",
+    ) -> None:
+        super().__init__(message, http_status, raw_body)
+        self.fields = fields
+
+
+class HttpError(HeleketError):
+    """Raised when the HTTP transport itself fails.
+
+    DNS, TCP, TLS, timeout, broken pipe. The API was never reached, or no
+    response was received.
+    """
+
+
+class SignatureError(HeleketError):
+    """Raised by :class:`WebhookVerifier` when the signature does not match.
+
+    Treat as a hard security failure — never trust the payload contents in
+    this case.
+    """
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"heleket signature error: {reason}")
+        self.reason = reason

heleket_sdk/_signature.py

@@ -0,0 +1,46 @@
+"""Heleket request and webhook signature.
+
+Formula (per https://doc.heleket.com/general/request-format):
+
+    sign = md5( base64(json_body) + api_key )
+
+For requests with no parameters, pass an empty bytes object — base64-encoding it
+yields the empty string, so the hash collapses to ``md5(api_key)``.
+
+The body argument MUST be the exact bytes that will be sent over the wire.
+The same routine is used to produce outgoing request signatures and to verify
+incoming webhook signatures.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+
+__all__ = ["sign", "constant_time_equal"]
+
+
+def sign(body: bytes | str, api_key: str) -> str:
+    """Compute the Heleket signature for the given body and API key.
+
+    Both ``bytes`` and ``str`` bodies are accepted. Strings are UTF-8 encoded.
+    """
+    if isinstance(body, str):
+        body = body.encode("utf-8")
+    encoded = base64.b64encode(body).decode("ascii")
+    return hashlib.md5((encoded + api_key).encode("utf-8")).hexdigest()  # noqa: S324
+
+
+def constant_time_equal(expected: str | None, actual: str | None) -> bool:
+    """Constant-time equality check for hex signatures.
+
+    Returns ``False`` if either side is ``None`` or the strings differ in
+    length. Use this in webhook verification — equality with ``==`` would
+    leak timing information.
+    """
+    if expected is None or actual is None:
+        return False
+    if len(expected) != len(actual):
+        return False
+    return hmac.compare_digest(expected, actual)