inflowpay 0.1.0__py3-none-any.whl

inflowpay/__init__.py

@@ -0,0 +1,10 @@
+"""InFlow Python SDK."""
+
+from importlib.metadata import version
+
+from .errors import InflowApiError
+from .options import ClientOptions
+
+__version__ = version("inflowpay")
+
+__all__ = ["ClientOptions", "InflowApiError", "__version__"]

inflowpay/_runtime.py

@@ -0,0 +1,271 @@
+import asyncio
+import json
+import math
+import random
+from collections.abc import Awaitable, Callable, Mapping
+from types import TracebackType
+from typing import Self, TypeVar
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from .errors import InflowApiError
+from .options import ClientOptions
+
+_RETRY_STATUSES = {429, 502, 503, 504}
+_SENSITIVE = {
+    "authorization",
+    "proxyauthorization",
+    "cookie",
+    "setcookie",
+    "xapikey",
+    "apikey",
+    "accesstoken",
+    "refreshtoken",
+    "privatekey",
+    "secretkey",
+    "password",
+    "credential",
+    "signature",
+    "paymentsignature",
+    "xpayment",
+}
+_T = TypeVar("_T")
+
+
+def _sensitive(key: str) -> bool:
+    return key.lower().replace("-", "").replace("_", "") in _SENSITIVE
+
+
+def _redact(value: object, secrets: tuple[str, ...]) -> object:
+    if isinstance(value, str):
+        for secret in secrets:
+            value = value.replace(secret, "[REDACTED]")
+        return value
+    if isinstance(value, dict):
+        return {
+            key: "[REDACTED]" if _sensitive(key) else _redact(item, secrets)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact(item, secrets) for item in value]
+    return value
+
+
+def _text(body: Mapping[str, object], key: str, fallback: str) -> str:
+    value = body.get(key)
+    return value if isinstance(value, str) and value else fallback
+
+
+def _error(path: str, response: httpx.Response, secrets: tuple[str, ...]) -> InflowApiError:
+    body = _redact(_parse(response), secrets)
+    code, message = "UNEXPECTED_ERROR", "request failed"
+    if isinstance(body, dict):
+        code = _text(body, "code", code)
+        message = _text(body, "message", message)
+        entries = body.get("errors")
+        if isinstance(entries, list) and entries and isinstance(entries[0], dict):
+            code = _text(entries[0], "code", code)
+            message = _text(entries[0], "message", message)
+        message = _text(body, "detail", message)
+    headers = {
+        key: str(_redact(value, secrets))
+        for key, value in response.headers.items()
+        if not _sensitive(key)
+    }
+    return InflowApiError(
+        message,
+        code=code,
+        http_status=response.status_code,
+        endpoint=path,
+        body=body,
+        headers=headers,
+    )
+
+
+def _parse(response: httpx.Response) -> object:
+    if not response.content:
+        return None
+    try:
+        return json.loads(response.content)
+    except (ValueError, UnicodeDecodeError):
+        return response.text
+
+
+def _positive(value: float) -> None:
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError("timeout and poll interval must be finite and positive")
+
+
+def _credential(value: str) -> None:
+    if not value or any(ord(char) <= 32 or ord(char) >= 127 for char in value):
+        raise ValueError(
+            "credentials must be nonempty ASCII without whitespace or control characters"
+        )
+
+
+class Client:
+    def __init__(self, options: ClientOptions) -> None:
+        if options.environment not in ("production", "sandbox"):
+            raise ValueError("unknown InFlow environment")
+        base = options.base_url or (
+            "https://api.inflowpay.ai"
+            if options.environment == "production"
+            else "https://sandbox.inflowpay.ai"
+        )
+        parsed = urlsplit(base)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or "?" in base
+            or "#" in base
+        ):
+            raise ValueError(
+                "base URL must be HTTP or HTTPS without credentials, query, or fragment"
+            )
+        if options.api_key is not None:
+            _credential(options.api_key)
+            if options.access_token is not None:
+                raise ValueError("API key and access token provider are mutually exclusive")
+        _positive(options.timeout)
+        self.base_url = base.rstrip("/")
+        self._options = options
+        self._http = httpx.AsyncClient(
+            transport=options.transport,
+            follow_redirects=False,
+            timeout=None,
+        )
+
+    async def __aenter__(self) -> Self:
+        await self._http.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: object = None,
+        headers: Mapping[str, str] | None = None,
+        retries: int = 0,
+    ) -> object:
+        # Retry permission belongs to the protocol operation, not the HTTP method.
+        if not path.startswith("/") or path.startswith("//") or "#" in path:
+            raise ValueError("expected an InFlow API path beginning with one slash")
+        if retries < 0:
+            raise ValueError("retries must not be negative")
+        extra = dict(headers or {})
+        if any(key.lower() in ("authorization", "x-api-key", "cookie") for key in extra):
+            raise ValueError("request headers must not override authentication")
+        content = None if body is None else json.dumps(body, allow_nan=False).encode()
+        attempt = 0
+        while True:
+            error = await self._attempt(method, path, content, extra)
+            if not isinstance(error, InflowApiError):
+                return error
+            if attempt >= min(retries, 3) or (
+                error.http_status not in _RETRY_STATUSES and error.http_status != 0
+            ):
+                raise error
+            await asyncio.sleep(0.2 * 2**attempt * (1 + random.random() / 4))
+            attempt += 1
+
+    async def _attempt(
+        self,
+        method: str,
+        path: str,
+        content: bytes | None,
+        extra: dict[str, str],
+    ) -> object:
+        await asyncio.sleep(0)
+        token = self._options.api_key
+        # Provider failures are application errors, not retryable transport failures.
+        if self._options.access_token is not None:
+            token = await self._options.access_token()
+            _credential(token)
+            # A provider can request cancellation without yielding before it returns.
+            await asyncio.sleep(0)
+        headers = httpx.Headers(extra)
+        headers["Accept"] = "application/json"
+        headers["User-Agent"] = "inflowpay (python)"
+        if content is not None:
+            headers["Content-Type"] = "application/json"
+        if token is not None:
+            if self._options.api_key is not None:
+                headers["X-API-KEY"] = token
+            else:
+                headers["Authorization"] = f"Bearer {token}"
+        # A directly constructed Request does not inherit the HTTPX client's cookie jar.
+        request = httpx.Request(method, self.base_url + path, content=content, headers=headers)
+        try:
+            async with asyncio.timeout(self._options.timeout):
+                response = await self._http.send(request, follow_redirects=False)
+                task = asyncio.current_task()
+                assert task is not None
+                if task.cancelling():
+                    await asyncio.sleep(0)
+        except (TimeoutError, httpx.TimeoutException):
+            return InflowApiError(
+                "request timed out",
+                code="TIMEOUT",
+                http_status=0,
+                endpoint=path,
+            )
+        except (httpx.TransportError, httpx.DecodingError):
+            return InflowApiError(
+                "network request failed",
+                code="NETWORK_ERROR",
+                http_status=0,
+                endpoint=path,
+            )
+        if response.is_success:
+            return _parse(response)
+        return _error(path, response, (token,) if token else ())
+
+    async def cancel_approval(self, approval_id: str) -> None:
+        async def cancel() -> None:
+            try:
+                async with asyncio.timeout(5):
+                    await self.request(
+                        "POST", f"/v1/approvals/{quote(approval_id, safe='')}/cancel"
+                    )
+            except Exception:
+                # Cleanup must not replace the payment flow's original failure.
+                pass
+
+        # Unlike Node fire-and-forget, await bounded cleanup before the application exits.
+        task = asyncio.create_task(cancel())
+        cancelled = False
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError:
+                cancelled = True
+        if cancelled:
+            raise asyncio.CancelledError
+
+
+async def poll(read: Callable[[], Awaitable[tuple[_T, bool, float]]], *, timeout: float) -> _T:
+    _positive(timeout)
+    # Protocol code interprets states and chooses which read failures may be retried.
+    async with asyncio.timeout(timeout):
+        while True:
+            value, done, interval = await read()
+            if done:
+                return value
+            if not math.isfinite(interval) or interval < 0:
+                raise ValueError("poll interval must be finite and nonnegative")
+            await asyncio.sleep(interval)

inflowpay/errors.py

@@ -0,0 +1,21 @@
+from collections.abc import Mapping
+
+
+class InflowApiError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        http_status: int,
+        endpoint: str,
+        body: object = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status
+        self.endpoint = endpoint
+        self.body = body
+        self.headers = dict(headers or {})
+        self.request_id = self.headers.get("x-request-id")

inflowpay/mpp/__init__.py

@@ -0,0 +1,35 @@
+"""InFlow MPP wire codecs. Decoding does not authenticate or settle a payment."""
+
+from ._pympp import from_pympp_challenge, to_pympp_challenge
+from ._requests import validate_payload, validate_request
+from ._wire import (
+    JsonValue,
+    MppCodecError,
+    WireObject,
+    canonicalize,
+    decode,
+    decode_credential,
+    decode_receipt,
+    encode,
+    parse_challenge_header,
+    parse_challenge_headers,
+    render_challenge_header,
+)
+
+__all__ = [
+    "JsonValue",
+    "MppCodecError",
+    "WireObject",
+    "canonicalize",
+    "decode",
+    "decode_credential",
+    "decode_receipt",
+    "encode",
+    "from_pympp_challenge",
+    "parse_challenge_header",
+    "parse_challenge_headers",
+    "render_challenge_header",
+    "to_pympp_challenge",
+    "validate_payload",
+    "validate_request",
+]

inflowpay/mpp/_pympp.py

@@ -0,0 +1,60 @@
+from copy import deepcopy
+from dataclasses import dataclass, field, fields, replace
+
+from mpp import Challenge, ChallengeEcho
+
+from ._wire import (
+    MppCodecError,
+    WireObject,
+    decode,
+    object_value,
+    render_challenge_header,
+    string,
+    validate_challenge,
+)
+
+
+@dataclass(frozen=True)
+class _WireChallenge(Challenge):
+    _wire: WireObject = field(default_factory=dict, repr=False, compare=False)
+
+    def to_echo(self) -> ChallengeEcho:
+        if "opaque" not in self._wire:
+            return super().to_echo()
+        opaque = string(self._wire["opaque"])
+        if decode(opaque) != self.opaque:
+            raise MppCodecError("pympp opaque data differs from its encoded value")
+        # pympp otherwise re-encodes opaque. Keep the original challenge-bound bytes.
+        return replace(super().to_echo(), opaque=opaque)
+
+
+def to_pympp_challenge(value: WireObject) -> Challenge:
+    # Parse only at this boundary; the wire object retains extensions that pympp cannot represent.
+    validate_challenge(value)
+    parsed = Challenge.from_www_authenticate(render_challenge_header(value))
+    return _WireChallenge(
+        **{item.name: getattr(parsed, item.name) for item in fields(parsed)}, _wire=deepcopy(value)
+    )
+
+
+def from_pympp_challenge(value: Challenge) -> WireObject:
+    # request_b64 is signed input. Re-encoding the decoded request can invalidate its binding.
+    result: WireObject = {
+        **(deepcopy(value._wire) if isinstance(value, _WireChallenge) else {}),
+        "id": value.id,
+        "realm": value.realm,
+        "method": value.method,
+        "intent": value.intent,
+        "request": value.request_b64,
+    }
+    for name in ("expires", "description", "digest", "header"):
+        item = getattr(value, name)
+        if item is not None:
+            result[name] = item
+    if value.opaque is not None:
+        # Converted challenges retain raw opaque bytes; native pympp challenges expose its echo.
+        result["opaque"] = value.to_echo().opaque
+    validate_challenge(result)
+    if object_value(decode(value.request_b64)) != value.request:
+        raise ValueError("pympp challenge request differs from its encoded request")
+    return deepcopy(result)

inflowpay/mpp/_requests.py

@@ -0,0 +1,105 @@
+import math
+import re
+from copy import deepcopy
+
+from ._wire import MppCodecError, WireObject, object_value, string, timestamp
+
+_UUID = r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}"
+_ADDRESS = r"0x[0-9a-fA-F]{40}"
+_MEMO = r"0x[0-9a-fA-F]{64}"
+_INTEGER = r"(?:0|[1-9][0-9]*)"
+
+
+def _match(value: object, pattern: str) -> str:
+    result = string(value)
+    if not re.fullmatch(pattern, result):
+        raise MppCodecError("Invalid payment field format")
+    return result
+
+
+def _optional_strings(data: WireObject, fields: tuple[str, ...], pattern: str = r"[\s\S]+") -> None:
+    for field in fields:
+        if field in data:
+            _match(data[field], pattern)
+
+
+def validate_request(method: str, intent: str, value: object) -> WireObject:
+    request = object_value(value)
+    if method == "inflow" and intent in ("charge", "subscription"):
+        amount = _match(request.get("amount"), r"-?[0-9]+(?:\.[0-9]+)?")
+        string(request.get("currency"))
+        _optional_strings(request, ("recipient",), _UUID)
+        if "methodDetails" in request:
+            details = object_value(request["methodDetails"])
+            if "rail" in details and details["rail"] not in ("balance", "instrument"):
+                raise MppCodecError("Unsupported InFlow rail")
+            _optional_strings(details, ("instrumentId",), _UUID)
+        if intent == "subscription":
+            if amount.startswith("-") or not re.search("[1-9]", amount):
+                raise MppCodecError("Subscription amount must be positive")
+            unit, count = request.get("periodUnit"), request.get("periodCount")
+            if unit not in ("minute", "hour", "day", "week", "month", "quarter", "year"):
+                raise MppCodecError("Unsupported subscription period")
+            if (
+                isinstance(count, bool)
+                or not isinstance(count, (int, float))
+                or not 1 <= count <= 9007199254740991
+                or count % 1 != 0
+            ):
+                raise MppCodecError("periodCount must be a positive safe integer")
+            if unit == "minute" and count < 5:
+                raise MppCodecError("Minute subscriptions require periodCount of at least five")
+            timestamp(request.get("subscriptionExpires"))
+            if "externalId" in request:
+                external = string(request["externalId"])
+                if not external.strip() or len(external.encode("utf-16-le")) // 2 > 128:
+                    raise MppCodecError("externalId must contain 1 to 128 characters")
+    elif method == "tempo" and intent == "charge":
+        _match(request.get("amount"), _INTEGER)
+        _optional_strings(request, ("currency", "recipient"), _ADDRESS)
+        _optional_strings(request, ("description", "externalId"))
+        if "methodDetails" in request:
+            details = object_value(request["methodDetails"])
+            if "chainId" in details:
+                chain = details["chainId"]
+                if (
+                    isinstance(chain, bool)
+                    or not isinstance(chain, (int, float))
+                    or (isinstance(chain, float) and not math.isfinite(chain))
+                ):
+                    raise MppCodecError("chainId must be a finite number")
+            if "feePayer" in details and type(details["feePayer"]) is not bool:
+                raise MppCodecError("feePayer must be a boolean")
+            _optional_strings(details, ("memo",), _MEMO)
+            if "supportedModes" in details:
+                modes = details["supportedModes"]
+                if not isinstance(modes, list) or any(
+                    mode not in ("pull", "push") for mode in modes
+                ):
+                    raise MppCodecError("Unsupported Tempo submission mode")
+            if "splits" in details:
+                splits = details["splits"]
+                if not isinstance(splits, list):
+                    raise MppCodecError("splits must be an array")
+                for value in splits:
+                    split = object_value(value)
+                    _match(split.get("amount"), _INTEGER)
+                    _match(split.get("recipient"), _ADDRESS)
+                    _optional_strings(split, ("memo",), _MEMO)
+    else:
+        raise MppCodecError("Unsupported payment method or intent")
+    return deepcopy(request)
+
+
+def validate_payload(method: str, value: object) -> WireObject:
+    payload = object_value(value)
+    if method == "tempo":
+        _optional_strings(payload, ("hash", "signature"), r"0x[0-9a-fA-F]+")
+        _optional_strings(payload, ("transactionId",))
+        kind = payload.get("type")
+        if kind not in ("hash", "transaction", "proof"):
+            raise MppCodecError("Unsupported Tempo credential type")
+        string(payload.get("hash" if kind == "hash" else "signature"))
+    elif method != "inflow":
+        raise MppCodecError("Unsupported payment method")
+    return deepcopy(payload)