pofsis-pay 0.1.0__tar.gz

pofsis_pay-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: pofsis-pay
+Version: 0.1.0
+Summary: Internal POFSIS client for IAM-authenticated POFPay integrations
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: boto3<2,>=1.35
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+
+# pofsis-pay
+
+Private Python SDK for IAM-authenticated POFPay machine requests and signed callback validation.
+
+```python
+from pofsis_pofpay import POFPayClient
+
+client = POFPayClient(
+    api_base_url="https://pofpay.example.com",
+    region="ap-southeast-1",
+)
+checkout = client.create_payment_request(snapshot, "tool:order-id")
+```
+
+Lambda uses the standard AWS credential chain, so no access key is stored in application
+configuration. Install the same pinned version locally and in the published Python 3.12 Layer.
+
+`buildspec-publish.yml` tests, builds, validates, and publishes an immutable package version to
+PyPI using a protected `PYPI_API_TOKEN`. `buildspec-layer.yml` installs that exact public version
+from `https://pypi.org/simple` and publishes the shared Lambda Layer. Runtime Lambdas need no PyPI
+credentials or package-registry access.
+
+The PyPI distribution is `pofsis-pay`; the Python import remains `pofsis_pofpay`.

pofsis_pay-0.1.0/README.md

@@ -0,0 +1,23 @@
+# pofsis-pay
+
+Private Python SDK for IAM-authenticated POFPay machine requests and signed callback validation.
+
+```python
+from pofsis_pofpay import POFPayClient
+
+client = POFPayClient(
+    api_base_url="https://pofpay.example.com",
+    region="ap-southeast-1",
+)
+checkout = client.create_payment_request(snapshot, "tool:order-id")
+```
+
+Lambda uses the standard AWS credential chain, so no access key is stored in application
+configuration. Install the same pinned version locally and in the published Python 3.12 Layer.
+
+`buildspec-publish.yml` tests, builds, validates, and publishes an immutable package version to
+PyPI using a protected `PYPI_API_TOKEN`. `buildspec-layer.yml` installs that exact public version
+from `https://pypi.org/simple` and publishes the shared Lambda Layer. Runtime Lambdas need no PyPI
+credentials or package-registry access.
+
+The PyPI distribution is `pofsis-pay`; the Python import remains `pofsis_pofpay`.

pofsis_pay-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pofsis-pay"
+version = "0.1.0"
+description = "Internal POFSIS client for IAM-authenticated POFPay integrations"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "boto3>=1.35,<2",
+  "httpx>=0.28,<1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<10"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

pofsis_pay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pofsis_pay-0.1.0/src/pofsis_pay.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: pofsis-pay
+Version: 0.1.0
+Summary: Internal POFSIS client for IAM-authenticated POFPay integrations
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: boto3<2,>=1.35
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+
+# pofsis-pay
+
+Private Python SDK for IAM-authenticated POFPay machine requests and signed callback validation.
+
+```python
+from pofsis_pofpay import POFPayClient
+
+client = POFPayClient(
+    api_base_url="https://pofpay.example.com",
+    region="ap-southeast-1",
+)
+checkout = client.create_payment_request(snapshot, "tool:order-id")
+```
+
+Lambda uses the standard AWS credential chain, so no access key is stored in application
+configuration. Install the same pinned version locally and in the published Python 3.12 Layer.
+
+`buildspec-publish.yml` tests, builds, validates, and publishes an immutable package version to
+PyPI using a protected `PYPI_API_TOKEN`. `buildspec-layer.yml` installs that exact public version
+from `https://pypi.org/simple` and publishes the shared Lambda Layer. Runtime Lambdas need no PyPI
+credentials or package-registry access.
+
+The PyPI distribution is `pofsis-pay`; the Python import remains `pofsis_pofpay`.

pofsis_pay-0.1.0/src/pofsis_pay.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/pofsis_pay.egg-info/PKG-INFO
+src/pofsis_pay.egg-info/SOURCES.txt
+src/pofsis_pay.egg-info/dependency_links.txt
+src/pofsis_pay.egg-info/requires.txt
+src/pofsis_pay.egg-info/top_level.txt
+src/pofsis_pofpay/__init__.py
+src/pofsis_pofpay/callbacks.py
+src/pofsis_pofpay/client.py
+src/pofsis_pofpay/errors.py
+src/pofsis_pofpay/models.py
+tests/test_sdk.py

pofsis_pay-0.1.0/src/pofsis_pay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pofsis_pay-0.1.0/src/pofsis_pay.egg-info/requires.txt

@@ -0,0 +1,5 @@
+boto3<2,>=1.35
+httpx<1,>=0.28
+
+[dev]
+pytest<10,>=8

pofsis_pay-0.1.0/src/pofsis_pay.egg-info/top_level.txt

@@ -0,0 +1 @@
+pofsis_pofpay

pofsis_pay-0.1.0/src/pofsis_pofpay/__init__.py

@@ -0,0 +1,15 @@
+from .callbacks import validate_payment_snapshot, verify_callback
+from .client import POFPayClient, derive_idempotency_key
+from .errors import POFPayError
+from .models import CallbackEvent, PaymentRequestCreated, PaymentRequestStatus
+
+__all__ = [
+    "CallbackEvent",
+    "POFPayClient",
+    "POFPayError",
+    "PaymentRequestCreated",
+    "PaymentRequestStatus",
+    "derive_idempotency_key",
+    "validate_payment_snapshot",
+    "verify_callback",
+]

pofsis_pay-0.1.0/src/pofsis_pofpay/callbacks.py

@@ -0,0 +1,98 @@
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import POFPayError
+from .models import CallbackEvent, PaymentRequestStatus
+
+
+def verify_callback(
+    raw_body: bytes,
+    headers: Mapping[str, str],
+    callback_secret: str,
+    tolerance_seconds: int = 300,
+    *,
+    now: int | None = None,
+) -> CallbackEvent:
+    if not callback_secret:
+        raise POFPayError(
+            "POFPay callback verification is not configured",
+            status_code=503,
+            code="POFPAY_CALLBACK_NOT_CONFIGURED",
+        )
+    normalized = {str(key).lower(): str(value) for key, value in headers.items()}
+    timestamp = normalized.get("pofpay-timestamp", "")
+    signature = normalized.get("pofpay-signature", "")
+    event_id = normalized.get("pofpay-event-id", "")
+    try:
+        issued_at = int(timestamp)
+    except ValueError as exc:
+        raise POFPayError(
+            "Invalid callback timestamp",
+            status_code=401,
+            code="INVALID_CALLBACK_SIGNATURE",
+        ) from exc
+    current_time = int(time.time()) if now is None else now
+    if abs(current_time - issued_at) > tolerance_seconds:
+        raise POFPayError(
+            "Expired callback timestamp",
+            status_code=401,
+            code="INVALID_CALLBACK_SIGNATURE",
+        )
+    supplied = signature.removeprefix("v1=")
+    expected = hmac.new(
+        callback_secret.encode(),
+        timestamp.encode() + b"." + raw_body,
+        hashlib.sha256,
+    ).hexdigest()
+    if not signature.startswith("v1=") or not hmac.compare_digest(expected, supplied):
+        raise POFPayError(
+            "Invalid callback signature",
+            status_code=401,
+            code="INVALID_CALLBACK_SIGNATURE",
+        )
+    try:
+        payload = json.loads(raw_body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise POFPayError(
+            "Invalid callback body",
+            status_code=400,
+            code="INVALID_CALLBACK_BODY",
+        ) from exc
+    if (
+        not isinstance(payload, dict)
+        or not isinstance(payload.get("data"), dict)
+        or not event_id
+        or payload.get("id") != event_id
+        or payload.get("type") != "payment_request.status_changed"
+    ):
+        raise POFPayError(
+            "Callback event does not match its headers",
+            status_code=400,
+            code="INVALID_CALLBACK_BODY",
+        )
+    return CallbackEvent(event_id=event_id, event_type=payload["type"], data=payload["data"])
+
+
+def validate_payment_snapshot(
+    received: PaymentRequestStatus | Mapping[str, Any],
+    expected: Mapping[str, Any],
+) -> None:
+    values = received.__dict__ if isinstance(received, PaymentRequestStatus) else received
+    fields = ("request_ref", "source_tool", "reference_type", "reference_id", "base_amount", "currency")
+    for field in fields:
+        actual = values.get(field)
+        wanted = expected.get(field)
+        if field in {"base_amount"} and actual is not None and wanted is not None:
+            actual, wanted = int(actual), int(wanted)
+        if field == "currency" and actual is not None and wanted is not None:
+            actual, wanted = str(actual).upper(), str(wanted).upper()
+        if actual != wanted:
+            raise POFPayError(
+                f"POFPay {field} does not match the local payment snapshot",
+                status_code=502,
+                code="POFPAY_SNAPSHOT_MISMATCH",
+            )

pofsis_pay-0.1.0/src/pofsis_pofpay/client.py

@@ -0,0 +1,159 @@
+import json
+import time
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+import boto3
+import httpx
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+
+from .errors import POFPayError
+from .models import PaymentRequestCreated, PaymentRequestStatus
+
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+class POFPayClient:
+    def __init__(
+        self,
+        api_base_url: str,
+        region: str = "ap-southeast-1",
+        timeout: float = 10.0,
+        *,
+        credential_provider: Any | None = None,
+        transport: httpx.BaseTransport | None = None,
+        max_attempts: int = 3,
+        backoff_seconds: float = 0.2,
+    ) -> None:
+        self.api_base_url = api_base_url.rstrip("/")
+        self.region = region
+        self.timeout = timeout
+        self.credential_provider = credential_provider or boto3.Session()
+        self.transport = transport
+        self.max_attempts = max(1, max_attempts)
+        self.backoff_seconds = max(0.0, backoff_seconds)
+
+    def _credentials(self):
+        credentials = self.credential_provider.get_credentials()
+        if credentials is None:
+            raise POFPayError(
+                "AWS credentials are unavailable",
+                status_code=503,
+                code="POFPAY_AUTH_UNAVAILABLE",
+            )
+        return credentials.get_frozen_credentials()
+
+    def _signed_headers(self, method: str, url: str, body: bytes, headers: dict[str, str]) -> dict[str, str]:
+        request = AWSRequest(method=method, url=url, data=body, headers=headers)
+        SigV4Auth(self._credentials(), "execute-api", self.region).add_auth(request)
+        return dict(request.headers.items())
+
+    @staticmethod
+    def _error(response: httpx.Response) -> POFPayError:
+        code = "POFPAY_REQUEST_REJECTED"
+        message = "POFPay rejected the request"
+        request_ref = None
+        try:
+            payload = response.json()
+            detail = payload.get("error") or payload.get("detail") or payload
+            if isinstance(detail, dict):
+                code = str(detail.get("code", code))
+                message = str(detail.get("message", message))
+                request_ref = detail.get("request_ref")
+        except ValueError:
+            pass
+        status = response.status_code if 400 <= response.status_code < 500 else 502
+        return POFPayError(message, status_code=status, code=code, request_ref=request_ref)
+
+    def _request(self, method: str, path: str, *, payload: dict[str, Any] | None = None, headers=None):
+        body = (
+            json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+            if payload is not None
+            else b""
+        )
+        url = f"{self.api_base_url}{path}"
+        base_headers = {"Accept": "application/json", **(headers or {})}
+        if payload is not None:
+            base_headers["Content-Type"] = "application/json"
+        last_error: Exception | None = None
+        for attempt in range(self.max_attempts):
+            signed_headers = self._signed_headers(method, url, body, base_headers)
+            try:
+                with httpx.Client(timeout=self.timeout, transport=self.transport) as client:
+                    response = client.request(method, url, content=body or None, headers=signed_headers)
+            except httpx.RequestError as exc:
+                last_error = exc
+                if attempt + 1 < self.max_attempts:
+                    time.sleep(self.backoff_seconds * (2**attempt))
+                    continue
+                raise POFPayError(
+                    "POFPay is temporarily unavailable",
+                    code="POFPAY_UNAVAILABLE",
+                ) from exc
+            if response.status_code in RETRYABLE_STATUS_CODES and attempt + 1 < self.max_attempts:
+                time.sleep(self.backoff_seconds * (2**attempt))
+                continue
+            if response.status_code >= 400:
+                raise self._error(response)
+            try:
+                data = response.json()
+            except ValueError as exc:
+                raise POFPayError(
+                    "POFPay returned an invalid response",
+                    code="POFPAY_INVALID_RESPONSE",
+                ) from exc
+            if not isinstance(data, dict):
+                raise POFPayError("POFPay returned an invalid response", code="POFPAY_INVALID_RESPONSE")
+            return data
+        raise POFPayError("POFPay is temporarily unavailable", code="POFPAY_UNAVAILABLE") from last_error
+
+    def create_payment_request(
+        self,
+        snapshot: dict[str, Any],
+        idempotency_key: str,
+    ) -> PaymentRequestCreated:
+        data = self._request(
+            "POST",
+            "/v1/payment-requests",
+            payload=snapshot,
+            headers={"Idempotency-Key": idempotency_key},
+        )
+        try:
+            return PaymentRequestCreated(
+                request_ref=str(data["request_ref"]),
+                status=str(data["status"]),
+                checkout_url=str(data["checkout_url"]),
+                checkout_expires_at=datetime.fromisoformat(
+                    str(data["checkout_expires_at"]).replace("Z", "+00:00")
+                ),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise POFPayError("POFPay returned an invalid checkout", code="POFPAY_INVALID_RESPONSE") from exc
+
+    def get_payment_request(self, request_ref: str) -> PaymentRequestStatus:
+        data = self._request("GET", f"/v1/payment-requests/{quote(request_ref, safe='')}")
+        try:
+            paid_at = data.get("paid_at")
+            return PaymentRequestStatus(
+                request_ref=str(data["request_ref"]),
+                source_tool=str(data["source_tool"]),
+                reference_type=str(data["reference_type"]),
+                reference_id=str(data["reference_id"]),
+                status=str(data["status"]),
+                base_amount=int(data["base_amount"]),
+                total_amount=int(data["total_amount"]),
+                currency=str(data["currency"]),
+                paid_at=datetime.fromisoformat(str(paid_at).replace("Z", "+00:00")) if paid_at else None,
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise POFPayError("POFPay returned an invalid status", code="POFPAY_INVALID_RESPONSE") from exc
+
+
+def derive_idempotency_key(source_tool: str, reference_id: str) -> str:
+    source = source_tool.strip().replace("_", "-")
+    reference = reference_id.strip()
+    if not source or not reference:
+        raise ValueError("source_tool and reference_id are required")
+    return f"{source}:{reference}"

pofsis_pay-0.1.0/src/pofsis_pofpay/errors.py

@@ -0,0 +1,13 @@
+class POFPayError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 502,
+        code: str = "POFPAY_ERROR",
+        request_ref: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_ref = request_ref

pofsis_pay-0.1.0/src/pofsis_pofpay/models.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PaymentRequestCreated:
+    request_ref: str
+    status: str
+    checkout_url: str
+    checkout_expires_at: datetime
+
+
+@dataclass(frozen=True)
+class PaymentRequestStatus:
+    request_ref: str
+    source_tool: str
+    reference_type: str
+    reference_id: str
+    status: str
+    base_amount: int
+    total_amount: int
+    currency: str
+    paid_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class CallbackEvent:
+    event_id: str
+    event_type: str
+    data: dict[str, Any]

pofsis_pay-0.1.0/tests/test_sdk.py

@@ -0,0 +1,81 @@
+import hashlib
+import hmac
+import json
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from botocore.credentials import Credentials
+
+from pofsis_pofpay import POFPayClient, POFPayError, verify_callback
+
+
+class CredentialsProvider:
+    def get_credentials(self):
+        return Credentials("access", "secret", "token")
+
+
+def test_client_sigv4_signs_payment_request():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["authorization"].startswith("AWS4-HMAC-SHA256 Credential=access/")
+        assert request.headers["x-amz-security-token"] == "token"
+        assert request.headers["idempotency-key"] == "orbit-store:purchase-1"
+        assert json.loads(request.content) == {"base_amount": 49900}
+        return httpx.Response(
+            201,
+            json={
+                "request_ref": "payreq_1",
+                "status": "OPEN",
+                "checkout_url": "https://pay.example.com/pay/token",
+                "checkout_expires_at": "2026-10-21T10:00:00Z",
+            },
+        )
+
+    client = POFPayClient(
+        "https://api.example.com",
+        credential_provider=CredentialsProvider(),
+        transport=httpx.MockTransport(handler),
+        backoff_seconds=0,
+    )
+
+    result = client.create_payment_request({"base_amount": 49900}, "orbit-store:purchase-1")
+    assert result.request_ref == "payreq_1"
+
+
+def test_callback_verifies_signature_event_and_raw_body():
+    body = b'{"id":"event-1","type":"payment_request.status_changed","data":{"status":"PAID"}}'
+    timestamp = "1000"
+    digest = hmac.new(b"secret", timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
+
+    event = verify_callback(
+        body,
+        {
+            "POFPay-Event-Id": "event-1",
+            "POFPay-Timestamp": timestamp,
+            "POFPay-Signature": f"v1={digest}",
+        },
+        "secret",
+        now=1000,
+    )
+
+    assert event.event_id == "event-1"
+    assert event.data["status"] == "PAID"
+
+
+def test_callback_rejects_header_body_event_mismatch():
+    body = b'{"id":"event-1","type":"payment_request.status_changed","data":{}}'
+    timestamp = "1000"
+    digest = hmac.new(b"secret", timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
+
+    with pytest.raises(POFPayError) as error:
+        verify_callback(
+            body,
+            {
+                "POFPay-Event-Id": "event-2",
+                "POFPay-Timestamp": timestamp,
+                "POFPay-Signature": f"v1={digest}",
+            },
+            "secret",
+            now=1000,
+        )
+    assert error.value.code == "INVALID_CALLBACK_BODY"