python-myanmar-payments 4.0.0a1__py3-none-any.whl

python_myanmar_payments/_results.py

@@ -0,0 +1,265 @@
+"""What initiating a payment, checking a status and verifying a callback return."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from html import escape
+from typing import Any, ClassVar, Literal
+
+from ._status import PaymentFlow, PaymentStatus
+
+__all__ = [
+    "Acknowledgement",
+    "AppPayment",
+    "FormField",
+    "FormPayment",
+    "PaymentCallback",
+    "PaymentResult",
+    "PaymentStatusResult",
+    "QrPayment",
+    "RedirectPayment",
+]
+
+
+@dataclass(frozen=True, kw_only=True)
+class RedirectPayment:
+    """Send the customer's browser to ``url`` to complete the payment."""
+
+    flow: ClassVar[Literal[PaymentFlow.REDIRECT]] = PaymentFlow.REDIRECT
+    order_id: str
+    """Your order ID, as sent to the gateway."""
+    url: str
+    """The gateway page to redirect the customer to."""
+    gateway_reference: str | None = None
+    """The gateway's ID for this attempt (KBZ ``prepay_id``, Wave ``transaction_id``)."""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    """The gateway's response, for logging."""
+
+
+@dataclass(frozen=True)
+class FormField:
+    """One signed hidden field of a :class:`FormPayment`."""
+
+    name: str
+    value: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class FormPayment:
+    """POST ``fields`` to ``action`` from the customer's browser.
+
+    :meth:`to_html` renders a page that does this automatically.
+    """
+
+    flow: ClassVar[Literal[PaymentFlow.FORM]] = PaymentFlow.FORM
+    order_id: str
+    """Your order ID, as sent to the gateway."""
+    action: str
+    """The gateway URL the form posts to."""
+    fields: tuple[FormField, ...]
+    """The signed hidden fields, in signing order. Post them unchanged."""
+    enctype: str = "application/x-www-form-urlencoded"
+    """The encoding the gateway expects for the form."""
+
+    def field(self, name: str) -> str | None:
+        """The value of the named field, or ``None``."""
+        return next((item.value for item in self.fields if item.name == name), None)
+
+    def values(self) -> dict[str, str]:
+        """The fields as a dict, e.g. to render the form with your own template."""
+        return {item.name: item.value for item in self.fields}
+
+    def to_html(self) -> str:
+        """A complete HTML page that posts the form as soon as it loads.
+
+        Every value is escaped.
+        """
+        inputs = "".join(
+            f'<input type="hidden" name="{_escape(item.name)}" value="{_escape(item.value)}">'
+            for item in self.fields
+        )
+        return (
+            '<!DOCTYPE html><html><head><meta charset="utf-8">'
+            "<title>Redirecting to payment</title></head><body>"
+            f'<form id="payment-form" method="POST" action="{_escape(self.action)}" '
+            f'enctype="{_escape(self.enctype)}">'
+            f"{inputs}"
+            '<noscript><button type="submit">Continue to payment</button></noscript></form>'
+            '<script>document.getElementById("payment-form").submit();</script></body></html>'
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class QrPayment:
+    """Show a QR code for the customer to scan.
+
+    Gateways return either a payload to encode (``qr_string``) or a ready-made
+    image (``qr_image``).
+    """
+
+    flow: ClassVar[Literal[PaymentFlow.QR]] = PaymentFlow.QR
+    order_id: str
+    """Your order ID, as sent to the gateway."""
+    qr_string: str | None = None
+    """A QR payload to encode into an image yourself (KBZ Pay)."""
+    qr_image: str | None = None
+    """A base64 encoded image to display as is (Yoma MMQR)."""
+    expires_at: datetime | None = None
+    """When the QR stops being payable (UTC), when the gateway limits it."""
+    reference: str | None = None
+    """The gateway's ID for this QR, used to check its status (Yoma ``refLabel``, KBZ
+    ``prepay_id``)."""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    """The gateway's response, for logging."""
+
+    def qr_image_data_uri(self, mime_type: str = "image/png") -> str | None:
+        """The image as a data URI for an ``<img src>``, or ``None`` without an image."""
+        return None if self.qr_image is None else f"data:{mime_type};base64,{self.qr_image}"
+
+
+@dataclass(frozen=True, kw_only=True)
+class AppPayment:
+    """Pass these values to your mobile app, which hands them to the wallet's SDK.
+
+    :meth:`to_dict` returns ``orderId``, ``orderInfo``, ``sign`` and ``signType``.
+    """
+
+    flow: ClassVar[Literal[PaymentFlow.APP]] = PaymentFlow.APP
+    order_id: str
+    """Your order ID, as sent to the gateway."""
+    order_info: str
+    """The signed order string the SDK expects."""
+    sign: str
+    """The signature of ``order_info``."""
+    sign_type: str
+    """The signature algorithm, e.g. ``SHA256``."""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    """The gateway's response, for logging. Left out of :meth:`to_dict`."""
+
+    def to_dict(self) -> dict[str, str]:
+        """The values your app needs: ``orderId``, ``orderInfo``, ``sign`` and ``signType``."""
+        return {
+            "orderId": self.order_id,
+            "orderInfo": self.order_info,
+            "sign": self.sign,
+            "signType": self.sign_type,
+        }
+
+
+PaymentResult = RedirectPayment | FormPayment | QrPayment | AppPayment
+"""Returned when a payment is initiated. Each flow has its own class; check ``flow``."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class Acknowledgement:
+    """The HTTP response a gateway expects after it delivers a callback.
+
+    Gateways retry until they receive it.
+    """
+
+    status: int = 200
+    """The HTTP status, 200 unless a gateway documents another."""
+    body: str = ""
+    """The response body, e.g. KBZ Pay's plain ``success``."""
+    headers: Mapping[str, str] = field(default_factory=lambda: {"Content-Type": "text/plain"})
+    """The response headers."""
+
+    @classmethod
+    def default(cls) -> Acknowledgement:
+        """An empty ``200 text/plain`` response, which most gateways expect."""
+        return cls()
+
+
+class PaymentCallback:
+    """A gateway notification whose signature has been verified.
+
+    Always compare ``amount`` with your order before fulfilling it, and handle
+    duplicates: gateways retry.
+    """
+
+    __slots__ = (
+        "acknowledgement",
+        "amount",
+        "gateway_reference",
+        "gateway_status",
+        "order_id",
+        "raw",
+        "status",
+    )
+
+    order_id: str
+    """Your order ID."""
+    status: PaymentStatus
+    """The status mapped onto this package's statuses."""
+    gateway_status: str
+    """The gateway's own status value, unmapped."""
+    gateway_reference: str | None
+    """The gateway's ID for the payment, when it sends one."""
+    amount: str | None
+    """The amount the gateway reports, exactly as it sent it, when it sends one."""
+    raw: Mapping[str, Any]
+    """The verified payload."""
+    acknowledgement: Acknowledgement
+    """The response to send so the gateway stops retrying."""
+
+    def __init__(
+        self,
+        *,
+        order_id: str,
+        status: PaymentStatus,
+        gateway_status: str,
+        gateway_reference: str | None = None,
+        amount: str | None = None,
+        raw: Mapping[str, Any] | None = None,
+        acknowledgement: Acknowledgement | None = None,
+    ) -> None:
+        self.order_id = order_id
+        self.status = PaymentStatus(status)
+        self.gateway_status = gateway_status
+        self.gateway_reference = gateway_reference
+        self.amount = amount
+        self.raw = raw if raw is not None else {}
+        self.acknowledgement = acknowledgement or Acknowledgement.default()
+
+    def is_successful(self) -> bool:
+        """Whether the customer paid."""
+        return self.status is PaymentStatus.SUCCESSFUL
+
+    def __repr__(self) -> str:
+        return (
+            f"PaymentCallback(order_id={self.order_id!r}, status={self.status.value!r}, "
+            f"gateway_status={self.gateway_status!r}, "
+            f"gateway_reference={self.gateway_reference!r}, amount={self.amount!r})"
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class PaymentStatusResult:
+    """The state of a payment as reported by a gateway's status API."""
+
+    status: PaymentStatus
+    """The status mapped onto this package's statuses."""
+    gateway_status: str
+    """The gateway's own status value, unmapped."""
+    order_id: str | None = None
+    """Your order ID, when the gateway returns it."""
+    gateway_reference: str | None = None
+    """The gateway's ID for the payment, when it sends one."""
+    amount: str | None = None
+    """The amount the gateway reports, exactly as it sent it, when it sends one."""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    """The gateway's response, for logging."""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "status", PaymentStatus(self.status))
+
+    def is_successful(self) -> bool:
+        """Whether the customer paid."""
+        return self.status is PaymentStatus.SUCCESSFUL
+
+
+def _escape(value: str) -> str:
+    # Matches the Node SDK: &, <, >, " (as &#34;) and ' (as &#39;).
+    return escape(value, quote=True).replace("&quot;", "&#34;").replace("&#x27;", "&#39;")

python_myanmar_payments/_status.py

@@ -0,0 +1,66 @@
+"""Gateway-independent payment statuses and flows."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+
+__all__ = ["PaymentFlow", "PaymentStatus", "resolve_status"]
+
+
+class _StrEnum(str, Enum):
+    """A string enum whose ``str()`` and format are its value on every Python."""
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __format__(self, format_spec: str) -> str:
+        return format(str(self.value), format_spec)
+
+
+class PaymentStatus(_StrEnum):
+    """A gateway-independent payment status.
+
+    Every gateway's own status values are mapped onto these. Members are strings,
+    so ``callback.status == "successful"`` works too.
+    """
+
+    SUCCESSFUL = "successful"
+    """The customer paid. The only status that means money was collected."""
+    PENDING = "pending"
+    """The payment is still in progress or waiting on the customer."""
+    FAILED = "failed"
+    """The payment was attempted and failed or was rejected."""
+    CANCELED = "canceled"
+    """The payment or order was canceled or closed before completing."""
+    EXPIRED = "expired"
+    """The payment window ran out before the customer paid."""
+    UNKNOWN = "unknown"
+    """The gateway sent a status this package does not recognize. Inspect ``gateway_status``."""
+
+    def is_final(self) -> bool:
+        """Whether the status will not change any more: ``False`` for pending and unknown."""
+        return self not in (PaymentStatus.PENDING, PaymentStatus.UNKNOWN)
+
+
+class PaymentFlow(_StrEnum):
+    """How the customer completes a payment after it has been initiated."""
+
+    REDIRECT = "redirect"
+    """Send the customer's browser to a gateway-hosted URL."""
+    FORM = "form"
+    """POST a signed form from the customer's browser to the gateway."""
+    QR = "qr"
+    """Show a QR code the customer scans with their wallet app."""
+    APP = "app"
+    """Hand a signed payload to your mobile app, which opens the wallet SDK."""
+
+
+def resolve_status(
+    statuses: Mapping[str, PaymentStatus], gateway_status: str | None
+) -> PaymentStatus:
+    """Maps a gateway status onto a :class:`PaymentStatus`, trimming whitespace.
+
+    Statuses missing from the map resolve to ``PaymentStatus.UNKNOWN``.
+    """
+    return statuses.get((gateway_status or "").strip(), PaymentStatus.UNKNOWN)

python_myanmar_payments/_support.py

@@ -0,0 +1,172 @@
+"""Shared internals: hashing, time, environment variables and settings."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+import re
+import secrets
+import time
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any, TypeVar
+from urllib.parse import quote_plus
+
+from ._errors import ConfigurationError
+
+EnvSource = Mapping[str, str]
+"""Environment variables, e.g. ``os.environ``."""
+
+
+# --- Hashing -------------------------------------------------------------------
+
+
+def hmac_sha256_hex(key: str, message: str) -> str:
+    """HMAC-SHA256 of ``message``, hex encoded."""
+    return hmac.new(key.encode(), message.encode(), hashlib.sha256).hexdigest()
+
+
+def hmac_sha256_base64(key: str, message: str) -> str:
+    """HMAC-SHA256 of ``message``, base64 encoded."""
+    digest = hmac.new(key.encode(), message.encode(), hashlib.sha256).digest()
+    return base64.b64encode(digest).decode()
+
+
+def sha256_hex(message: str) -> str:
+    """SHA-256 of ``message``, hex encoded."""
+    return hashlib.sha256(message.encode()).hexdigest()
+
+
+def safe_equal(expected: str, actual: str) -> bool:
+    """Compares two strings in constant time (for equal lengths)."""
+    return hmac.compare_digest(expected.encode(), actual.encode())
+
+
+def random_hex(size: int = 16) -> str:
+    """``size`` random bytes, hex encoded."""
+    return secrets.token_hex(size)
+
+
+def query_escape(value: str) -> str:
+    """Escapes text like Go's ``url.QueryEscape``.
+
+    Everything except letters, digits and ``-_.~`` is percent-encoded and spaces
+    become ``+``.
+    """
+    return quote_plus(value, safe="")
+
+
+_BASE64 = re.compile(r"[A-Za-z0-9+/]+={0,2}")
+
+
+def decode_base64(value: str) -> str | None:
+    """Decodes standard base64 as UTF-8 text, or ``None``.
+
+    The padding is either complete or left out entirely; partial padding, other
+    alphabets, whitespace and bytes that are not UTF-8 are rejected.
+    """
+    if _BASE64.fullmatch(value) is None:
+        return None
+    if "=" in value:
+        if len(value) % 4 != 0:
+            return None
+    elif len(value) % 4 == 1:
+        return None
+    else:
+        value += "=" * (-len(value) % 4)
+    try:
+        return base64.b64decode(value, validate=True).decode("utf-8")
+    except ValueError:  # Invalid UTF-8 (UnicodeDecodeError is a ValueError).
+        return None
+
+
+# --- Time ----------------------------------------------------------------------
+
+
+def current_time() -> float:
+    """Seconds since the epoch. Tests replace it to freeze the clock."""
+    return time.time()
+
+
+def unix_time() -> int:
+    """Whole seconds since the epoch."""
+    return int(current_time())
+
+
+def utc_now() -> datetime:
+    """The current time as an aware UTC datetime."""
+    return datetime.fromtimestamp(current_time(), tz=timezone.utc)
+
+
+# --- Settings ------------------------------------------------------------------
+
+
+def default_env() -> EnvSource:
+    """The default environment: ``os.environ``."""
+    return os.environ
+
+
+def env_first(env: EnvSource, *keys: str) -> str:
+    """The first non-empty value among ``keys``, trimmed, or ``""``."""
+    for key in keys:
+        value = (env.get(key) or "").strip()
+        if value:
+            return value
+    return ""
+
+
+_FALSE = frozenset({"false", "0", "f", "no", "off"})
+
+
+def env_sandbox(env: EnvSource, key: str) -> bool:
+    """Reads a ``*_SANDBOX`` variable.
+
+    Only ``false``, ``0``, ``f``, ``no`` and ``off`` (any case) select production;
+    unset or unrecognized values mean sandbox.
+    """
+    return sandbox_flag(env.get(key) or "")
+
+
+def sandbox_flag(value: bool | str) -> bool:
+    """A ``sandbox`` setting: a bool, or text read like a ``*_SANDBOX`` variable."""
+    if isinstance(value, str):
+        return value.strip().lower() not in _FALSE
+    return bool(value)
+
+
+_C = TypeVar("_C")
+
+
+def config_of(config_class: type[_C], config: _C | Mapping[str, Any]) -> _C:
+    """``config`` itself, or a ``config_class`` built from a mapping of its arguments."""
+    if isinstance(config, config_class):
+        return config
+    return config_class(**config)  # type: ignore[arg-type]
+
+
+_INT = re.compile(r"[+-]?[0-9]+")
+
+
+def env_int(env: EnvSource, key: str) -> int | None:
+    """An integer variable, or ``None`` when unset or not an integer."""
+    value = (env.get(key) or "").strip()
+    return int(value) if _INT.fullmatch(value) else None
+
+
+def require_setting(gateway: str, key: str, value: object) -> str:
+    """The value, or raises a :class:`ConfigurationError` naming ``key``."""
+    if not isinstance(value, str) or value.strip() == "":
+        raise ConfigurationError(gateway, key)
+    return value
+
+
+def optional_setting(value: object) -> str | None:
+    """An optional string, ``None`` when blank."""
+    return value if isinstance(value, str) and value.strip() != "" else None
+
+
+def trim_url(url: str) -> str:
+    """Removes trailing slashes."""
+    return url.rstrip("/")

python_myanmar_payments/_validate.py

@@ -0,0 +1,157 @@
+"""Validates payment data against each gateway's documented limits."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from decimal import Decimal
+from urllib.parse import urlsplit
+
+from ._amount import Amount, to_amount
+from ._errors import InvalidPaymentDataError
+
+
+@dataclass(frozen=True)
+class AmountRule:
+    """What a gateway's documentation allows for an amount."""
+
+    gateway: str
+    """The gateway's display name, used in error messages."""
+    max_decimals: int | None
+    """The most fractional digits allowed: 0 means whole amounts only, None no limit."""
+    max_length: int | None = None
+    """Limits the amount's text length."""
+    allow_zero: bool = False
+    """Accepts an amount of 0."""
+
+
+def byte_length(value: str) -> int:
+    """UTF-8 byte length, matching the byte limits in the gateway documentation."""
+    return len(value.encode("utf-8", errors="surrogatepass"))
+
+
+def is_int(value: object) -> bool:
+    """Whether ``value`` is an ``int`` and not a ``bool``."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+class Validator:
+    """Collects one error per field (the first one wins) and raises them together."""
+
+    def __init__(self) -> None:
+        self._errors: dict[str, str] = {}
+
+    def required(self, field: str, value: object) -> Validator:
+        if not isinstance(value, str) or value.strip() == "":
+            self._fail(field, f"The {field} field is required.")
+        return self
+
+    def string(self, field: str, value: object) -> Validator:
+        """Fails when the value is set but not a string."""
+        if value is not None and not isinstance(value, str):
+            self._fail(field, f"The {field} field must be a string.")
+        return self
+
+    def length(self, field: str, value: object, minimum: int, maximum: int) -> Validator:
+        if isinstance(value, str) and value != "":
+            size = byte_length(value)
+            if size < minimum or size > maximum:
+                self._fail(
+                    field,
+                    f"The {field} field must be between {minimum} and {maximum} characters.",
+                )
+        return self
+
+    def max(self, field: str, value: object, maximum: int) -> Validator:
+        if isinstance(value, str) and byte_length(value) > maximum:
+            self._fail(field, f"The {field} field must not be greater than {maximum} characters.")
+        return self
+
+    def pattern(
+        self, field: str, value: object, pattern: re.Pattern[str], description: str
+    ) -> Validator:
+        if isinstance(value, str) and value != "" and pattern.fullmatch(value) is None:
+            self._fail(field, f"The {field} field may only contain {description}.")
+        return self
+
+    def between(self, field: str, value: object, minimum: int, maximum: int) -> Validator:
+        """Fails when a set value is not an integer within [minimum, maximum]."""
+        if value is not None and (
+            not is_int(value) or not minimum <= value <= maximum  # type: ignore[operator]
+        ):
+            self._fail(field, f"The {field} field must be between {minimum} and {maximum}.")
+        return self
+
+    def amount(self, field: str, value: object, rule: AmountRule) -> Validator:
+        if value is None:
+            return self._fail(field, f"The {field} field is required.")
+        if isinstance(value, float):
+            return self._fail(
+                field,
+                f"The {field} field must not be a float; use Amount.kyat(1000) or "
+                "Amount.parse('10.50').",
+            )
+        if not isinstance(value, (Amount, str, Decimal)) and not is_int(value):
+            return self._fail(
+                field,
+                f"The {field} field must be an Amount, e.g. Amount.kyat(1000) or "
+                "Amount.parse('1000.50').",
+            )
+        amount = to_amount(value)
+        if amount is None:
+            return self._fail(
+                field, f"The {field} field must be a non-negative number such as 1000 or 1000.50."
+            )
+        places = amount.decimal_places()
+        if rule.max_decimals == 0 and places > 0:
+            return self._fail(
+                field,
+                f"{rule.gateway} does not accept decimal amounts; "
+                f"the {field} field must be a whole number.",
+            )
+        if rule.max_decimals is not None and rule.max_decimals > 0 and places > rule.max_decimals:
+            return self._fail(
+                field,
+                f"{rule.gateway} accepts at most {rule.max_decimals} decimal places; "
+                f"the {field} field has {places}.",
+            )
+        if not rule.allow_zero and amount.is_zero():
+            return self._fail(field, f"The {field} field must be greater than 0.")
+        if rule.max_length is not None and len(str(amount)) > rule.max_length:
+            return self._fail(
+                field, f"The {field} field must not be greater than {rule.max_length} characters."
+            )
+        return self
+
+    def url(self, field: str, value: object) -> Validator:
+        """Fails when a set value is not an absolute http or https URL."""
+        if isinstance(value, str) and value != "" and not _is_http_url(value):
+            self._fail(field, f"The {field} field must be a valid http or https URL.")
+        return self
+
+    def when(self, condition: bool, field: str, message: str) -> Validator:
+        if condition:
+            self._fail(field, message)
+        return self
+
+    def failed(self) -> bool:
+        """Whether any check failed so far."""
+        return bool(self._errors)
+
+    def validate(self) -> None:
+        """Raises an :class:`InvalidPaymentDataError` when any check failed."""
+        if self._errors:
+            raise InvalidPaymentDataError(self._errors)
+
+    def _fail(self, field: str, message: str) -> Validator:
+        self._errors.setdefault(field, message)
+        return self
+
+
+def _is_http_url(value: str) -> bool:
+    try:
+        parts = urlsplit(value)
+        _ = parts.port  # Raises for an invalid port.
+    except ValueError:
+        return False
+    return parts.scheme.lower() in ("http", "https") and bool(parts.hostname)