lunipay 0.1.0__tar.gz

lunipay-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Node
+node_modules/
+dist/
+*.tgz
+.npm/
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.pytest_cache/
+*.egg-info/
+build/
+sdist/
+wheelhouse/
+
+# Editors & OS
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+
+# Env
+.env
+.env.local

lunipay-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: lunipay
+Version: 0.1.0
+Summary: The official LuniPay Python SDK.
+Project-URL: Homepage, https://lunipay.io/docs/sdks/python
+Project-URL: Documentation, https://lunipay.io/docs/sdks/python
+Project-URL: Repository, https://github.com/SammarieoBrown/lunipay-sdk
+Project-URL: Issues, https://github.com/SammarieoBrown/lunipay-sdk/issues
+Author: LuniPay
+License: MIT
+Keywords: api,caribbean,checkout,lunipay,payments,sdk,stripe-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.20
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# lunipay
+
+The official LuniPay Python SDK.
+
+```bash
+pip install lunipay
+```
+
+## Quick start
+
+```python
+import lunipay
+
+lunipay.api_key = "sk_test_YOUR_KEY"
+
+session = lunipay.CheckoutSession.create(
+    amount=5000,
+    currency="usd",
+    success_url="https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
+)
+
+print(session["url"])
+```
+
+## Resources
+
+Every LuniPay resource is a top-level class on the module:
+
+```python
+lunipay.Customer.create(email="ada@example.com", first_name="Ada", last_name="Lovelace")
+lunipay.Customer.retrieve("cus_01JRZK...")
+lunipay.Customer.modify("cus_01JRZK...", phone="+18765559999")
+lunipay.Customer.delete("cus_01JRZK...")
+
+for customer in lunipay.Customer.list().auto_paging_iter():
+    print(customer["email"])
+```
+
+Supported resources: `CheckoutSession`, `Customer`, `Invoice`, `Payment`, `PaymentLink`, `WebhookEndpoint`, `Event`.
+
+## Webhooks
+
+```python
+import lunipay
+
+@app.post("/webhook")
+def webhook():
+    payload = request.get_data()
+    sig = request.headers.get("LuniPay-Signature")
+    try:
+        event = lunipay.Webhook.construct_event(
+            payload=payload,
+            sig_header=sig,
+            secret="whsec_your_secret",
+        )
+    except lunipay.error.SignatureVerificationError:
+        return "bad signature", 400
+
+    if event["type"] == "checkout.session.completed":
+        # fulfill the order
+        pass
+
+    return "", 200
+```
+
+## Errors
+
+All LuniPay API errors raise subclasses of `lunipay.error.LuniPayError`:
+
+```python
+try:
+    lunipay.Customer.create(email="bad", first_name="x", last_name="y")
+except lunipay.error.InvalidRequestError as e:
+    print(e.code, e.param, str(e))
+```
+
+Subclasses: `AuthenticationError`, `PermissionError`, `InvalidRequestError`, `IdempotencyError`, `RateLimitError`, `APIError`, `APIConnectionError`.
+
+## Idempotency
+
+Pass `idempotency_key` to any mutating request:
+
+```python
+import uuid
+
+key = str(uuid.uuid4())
+session = lunipay.CheckoutSession.create(
+    amount=5000,
+    currency="usd",
+    success_url="https://example.com/thanks",
+    idempotency_key=key,
+)
+```
+
+## Full documentation
+
+See [lunipay.io/docs/sdks/python](https://lunipay.io/docs/sdks/python).
+
+## License
+
+MIT

lunipay-0.1.0/README.md

@@ -0,0 +1,101 @@
+# lunipay
+
+The official LuniPay Python SDK.
+
+```bash
+pip install lunipay
+```
+
+## Quick start
+
+```python
+import lunipay
+
+lunipay.api_key = "sk_test_YOUR_KEY"
+
+session = lunipay.CheckoutSession.create(
+    amount=5000,
+    currency="usd",
+    success_url="https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
+)
+
+print(session["url"])
+```
+
+## Resources
+
+Every LuniPay resource is a top-level class on the module:
+
+```python
+lunipay.Customer.create(email="ada@example.com", first_name="Ada", last_name="Lovelace")
+lunipay.Customer.retrieve("cus_01JRZK...")
+lunipay.Customer.modify("cus_01JRZK...", phone="+18765559999")
+lunipay.Customer.delete("cus_01JRZK...")
+
+for customer in lunipay.Customer.list().auto_paging_iter():
+    print(customer["email"])
+```
+
+Supported resources: `CheckoutSession`, `Customer`, `Invoice`, `Payment`, `PaymentLink`, `WebhookEndpoint`, `Event`.
+
+## Webhooks
+
+```python
+import lunipay
+
+@app.post("/webhook")
+def webhook():
+    payload = request.get_data()
+    sig = request.headers.get("LuniPay-Signature")
+    try:
+        event = lunipay.Webhook.construct_event(
+            payload=payload,
+            sig_header=sig,
+            secret="whsec_your_secret",
+        )
+    except lunipay.error.SignatureVerificationError:
+        return "bad signature", 400
+
+    if event["type"] == "checkout.session.completed":
+        # fulfill the order
+        pass
+
+    return "", 200
+```
+
+## Errors
+
+All LuniPay API errors raise subclasses of `lunipay.error.LuniPayError`:
+
+```python
+try:
+    lunipay.Customer.create(email="bad", first_name="x", last_name="y")
+except lunipay.error.InvalidRequestError as e:
+    print(e.code, e.param, str(e))
+```
+
+Subclasses: `AuthenticationError`, `PermissionError`, `InvalidRequestError`, `IdempotencyError`, `RateLimitError`, `APIError`, `APIConnectionError`.
+
+## Idempotency
+
+Pass `idempotency_key` to any mutating request:
+
+```python
+import uuid
+
+key = str(uuid.uuid4())
+session = lunipay.CheckoutSession.create(
+    amount=5000,
+    currency="usd",
+    success_url="https://example.com/thanks",
+    idempotency_key=key,
+)
+```
+
+## Full documentation
+
+See [lunipay.io/docs/sdks/python](https://lunipay.io/docs/sdks/python).
+
+## License
+
+MIT

lunipay-0.1.0/lunipay/__init__.py

@@ -0,0 +1,46 @@
+"""
+LuniPay Python SDK.
+
+    import lunipay
+    lunipay.api_key = "sk_test_..."
+    session = lunipay.CheckoutSession.create(amount=5000, currency="usd", ...)
+"""
+
+from typing import Optional
+
+api_key: Optional[str] = None
+api_base: str = "https://lunipay.io/api"
+api_version: str = "2026-04-14"
+
+__version__ = "0.1.0"
+
+# Resource classes
+from .api_resources.checkout_session import CheckoutSession  # noqa: E402
+from .api_resources.customer import Customer  # noqa: E402
+from .api_resources.invoice import Invoice  # noqa: E402
+from .api_resources.payment_link import PaymentLink  # noqa: E402
+from .api_resources.payment import Payment  # noqa: E402
+from .api_resources.webhook_endpoint import WebhookEndpoint  # noqa: E402
+from .api_resources.event import Event  # noqa: E402
+
+# Webhook helpers
+from .webhook import Webhook  # noqa: E402
+
+# Error namespace — users catch `lunipay.error.InvalidRequestError`, etc.
+from . import error  # noqa: E402
+
+__all__ = [
+    "api_key",
+    "api_base",
+    "api_version",
+    "__version__",
+    "CheckoutSession",
+    "Customer",
+    "Invoice",
+    "PaymentLink",
+    "Payment",
+    "WebhookEndpoint",
+    "Event",
+    "Webhook",
+    "error",
+]

lunipay-0.1.0/lunipay/_api_requestor.py

@@ -0,0 +1,131 @@
+"""
+Thin HTTP client wrapper for LuniPay API calls.
+
+All resource classes route through `APIRequestor.request()`, which
+handles auth headers, body serialization, error envelope parsing, and
+exception mapping.
+"""
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from . import error as err
+
+_USER_AGENT = "lunipay-python/0.1.0"
+_DEFAULT_TIMEOUT = 30  # seconds
+
+
+def request(
+    method: str,
+    url: str,
+    params: Optional[Dict[str, Any]] = None,
+    api_key: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+) -> Any:
+    """
+    Make an HTTP request to the LuniPay API.
+
+    Args:
+        method: 'get' | 'post' | 'patch' | 'delete'
+        url:    path only (e.g. '/v1/customers')
+        params: request body (POST/PATCH) or query params (GET/DELETE)
+        api_key: per-request override. Falls back to lunipay.api_key.
+        idempotency_key: optional Idempotency-Key header value.
+
+    Returns:
+        The parsed JSON response body.
+
+    Raises:
+        lunipay.error.AuthenticationError
+        lunipay.error.PermissionError
+        lunipay.error.RateLimitError
+        lunipay.error.InvalidRequestError
+        lunipay.error.IdempotencyError
+        lunipay.error.APIError
+        lunipay.error.APIConnectionError
+    """
+    # Late import so consumer `import lunipay` doesn't fail if the config
+    # is mutated after the module loads.
+    import lunipay
+
+    effective_key = api_key or lunipay.api_key
+    if not effective_key:
+        raise err.AuthenticationError(
+            "No API key provided. Set `lunipay.api_key` or pass `api_key=` "
+            "to the request."
+        )
+
+    full_url = lunipay.api_base.rstrip("/") + url
+
+    headers = {
+        "Authorization": f"Bearer {effective_key}",
+        "Accept": "application/json",
+        "User-Agent": _USER_AGENT,
+        "LuniPay-Version": lunipay.api_version,
+    }
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+
+    method_lower = method.lower()
+    json_body: Optional[Dict[str, Any]] = None
+    query: Optional[Dict[str, Any]] = None
+
+    if method_lower in ("get", "delete"):
+        query = params or None
+    else:
+        headers["Content-Type"] = "application/json"
+        json_body = params or {}
+
+    try:
+        resp = requests.request(
+            method_lower.upper(),
+            full_url,
+            headers=headers,
+            params=query,
+            json=json_body,
+            timeout=_DEFAULT_TIMEOUT,
+        )
+    except requests.exceptions.Timeout as e:
+        raise err.APIConnectionError(
+            f"Request timed out after {_DEFAULT_TIMEOUT}s: {e}"
+        )
+    except requests.exceptions.ConnectionError as e:
+        raise err.APIConnectionError(f"Failed to connect to LuniPay API: {e}")
+    except requests.exceptions.RequestException as e:
+        raise err.APIConnectionError(f"Request failed: {e}")
+
+    try:
+        body = resp.json() if resp.content else {}
+    except ValueError:
+        body = {}
+
+    if 200 <= resp.status_code < 300:
+        return body
+
+    _raise_for_error(resp.status_code, body)
+    return None  # unreachable — _raise_for_error always raises
+
+
+def _raise_for_error(status: int, body: Any) -> None:
+    envelope = body.get("error", {}) if isinstance(body, dict) else {}
+    message = envelope.get("message") or f"HTTP {status}"
+    err_type = envelope.get("type") or ""
+    code = envelope.get("code")
+    param = envelope.get("param")
+
+    if status == 401:
+        raise err.AuthenticationError(message, http_status=status, json_body=body)
+    if status == 403:
+        raise err.PermissionError(message, http_status=status, json_body=body)
+    if status == 429:
+        raise err.RateLimitError(message, http_status=status, json_body=body)
+    if status == 409 and err_type == "idempotency_error":
+        raise err.IdempotencyError(
+            message, param=param, code=code, http_status=status, json_body=body
+        )
+    if 400 <= status < 500:
+        raise err.InvalidRequestError(
+            message, param=param, code=code, http_status=status, json_body=body
+        )
+    raise err.APIError(message, http_status=status, json_body=body)

lunipay-0.1.0/lunipay/api_resources/__init__.py

@@ -0,0 +1 @@
+"""LuniPay API resource classes."""

lunipay-0.1.0/lunipay/api_resources/_abstract.py

@@ -0,0 +1,161 @@
+"""
+Resource base classes and mixins. Resource classes compose these to expose
+`create / retrieve / list / modify / delete` + custom actions.
+
+Mirrors Stripe's Python SDK pattern so developers migrating from Stripe
+feel immediately at home.
+"""
+
+from typing import Any, Dict, Iterator, Optional
+
+from .._api_requestor import request as _api_request
+
+
+class ListObject:
+    """
+    Cursor-paginated list response. Supports `auto_paging_iter()` for
+    seamless iteration across pages.
+
+        for customer in lunipay.Customer.list().auto_paging_iter():
+            print(customer["email"])
+    """
+
+    def __init__(
+        self,
+        data: list,
+        has_more: bool,
+        url: str,
+        resource_cls: type,
+        api_key: Optional[str],
+    ) -> None:
+        self.data = data
+        self.has_more = has_more
+        self.url = url
+        self._resource_cls = resource_cls
+        self._api_key = api_key
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def auto_paging_iter(self) -> Iterator[Any]:
+        page: "ListObject" = self
+        while True:
+            for item in page.data:
+                yield item
+            if not page.has_more or not page.data:
+                return
+            last = page.data[-1]
+            last_id = last.get("id") if isinstance(last, dict) else None
+            if not last_id:
+                return
+            page = self._resource_cls.list(
+                api_key=self._api_key, starting_after=last_id
+            )
+
+
+class APIResource:
+    """Base class for all API resources."""
+
+    OBJECT_NAME: str = ""
+    RESOURCE_URL: str = ""
+
+    @classmethod
+    def _static_request(
+        cls,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return _api_request(
+            method=method,
+            url=url,
+            params=params,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )
+
+    @classmethod
+    def retrieve(cls, id: str, api_key: Optional[str] = None) -> Any:
+        return cls._static_request(
+            "get", f"{cls.RESOURCE_URL}/{id}", api_key=api_key
+        )
+
+
+class CreateableResource:
+    """Mixin: POST {RESOURCE_URL} → create."""
+
+    @classmethod
+    def create(
+        cls,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        **params: Any,
+    ) -> Any:
+        return cls._static_request(  # type: ignore[attr-defined]
+            "post",
+            cls.RESOURCE_URL,  # type: ignore[attr-defined]
+            params=params,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )
+
+
+class ListableResource:
+    """Mixin: GET {RESOURCE_URL} → list with cursor pagination."""
+
+    @classmethod
+    def list(
+        cls,
+        api_key: Optional[str] = None,
+        **params: Any,
+    ) -> ListObject:
+        body = cls._static_request(  # type: ignore[attr-defined]
+            "get",
+            cls.RESOURCE_URL,  # type: ignore[attr-defined]
+            params=params,
+            api_key=api_key,
+        )
+        return ListObject(
+            data=body.get("data", []),
+            has_more=bool(body.get("has_more", False)),
+            url=body.get("url", cls.RESOURCE_URL),  # type: ignore[attr-defined]
+            resource_cls=cls,
+            api_key=api_key,
+        )
+
+
+class UpdateableResource:
+    """Mixin: PATCH {RESOURCE_URL}/{id} → modify."""
+
+    @classmethod
+    def modify(
+        cls,
+        id: str,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        **params: Any,
+    ) -> Any:
+        return cls._static_request(  # type: ignore[attr-defined]
+            "patch",
+            f"{cls.RESOURCE_URL}/{id}",  # type: ignore[attr-defined]
+            params=params,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )
+
+
+class DeleteableResource:
+    """Mixin: DELETE {RESOURCE_URL}/{id}."""
+
+    @classmethod
+    def delete(cls, id: str, api_key: Optional[str] = None) -> Any:
+        return cls._static_request(  # type: ignore[attr-defined]
+            "delete",
+            f"{cls.RESOURCE_URL}/{id}",  # type: ignore[attr-defined]
+            api_key=api_key,
+        )

lunipay-0.1.0/lunipay/api_resources/checkout_session.py

@@ -0,0 +1,22 @@
+from typing import Any, Optional
+
+from ._abstract import APIResource, CreateableResource, ListableResource
+
+
+class CheckoutSession(CreateableResource, ListableResource, APIResource):
+    OBJECT_NAME = "checkout_session"
+    RESOURCE_URL = "/v1/checkout/sessions"
+
+    @classmethod
+    def expire(
+        cls,
+        id: str,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return cls._static_request(
+            "post",
+            f"{cls.RESOURCE_URL}/{id}/expire",
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )

lunipay-0.1.0/lunipay/api_resources/customer.py

@@ -0,0 +1,18 @@
+from ._abstract import (
+    APIResource,
+    CreateableResource,
+    DeleteableResource,
+    ListableResource,
+    UpdateableResource,
+)
+
+
+class Customer(
+    CreateableResource,
+    ListableResource,
+    UpdateableResource,
+    DeleteableResource,
+    APIResource,
+):
+    OBJECT_NAME = "customer"
+    RESOURCE_URL = "/v1/customers"

lunipay-0.1.0/lunipay/api_resources/event.py

@@ -0,0 +1,6 @@
+from ._abstract import APIResource, ListableResource
+
+
+class Event(ListableResource, APIResource):
+    OBJECT_NAME = "event"
+    RESOURCE_URL = "/v1/events"

lunipay-0.1.0/lunipay/api_resources/invoice.py

@@ -0,0 +1,48 @@
+from typing import Any, Optional
+
+from ._abstract import (
+    APIResource,
+    CreateableResource,
+    DeleteableResource,
+    ListableResource,
+    UpdateableResource,
+)
+
+
+class Invoice(
+    CreateableResource,
+    ListableResource,
+    UpdateableResource,
+    DeleteableResource,
+    APIResource,
+):
+    OBJECT_NAME = "invoice"
+    RESOURCE_URL = "/v1/invoices"
+
+    @classmethod
+    def send(
+        cls,
+        id: str,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return cls._static_request(
+            "post",
+            f"{cls.RESOURCE_URL}/{id}/send",
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )
+
+    @classmethod
+    def void(
+        cls,
+        id: str,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return cls._static_request(
+            "post",
+            f"{cls.RESOURCE_URL}/{id}/void",
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )

lunipay-0.1.0/lunipay/api_resources/payment.py

@@ -0,0 +1,27 @@
+from typing import Any, Optional
+
+from ._abstract import APIResource, ListableResource
+
+
+class Payment(ListableResource, APIResource):
+    OBJECT_NAME = "payment"
+    RESOURCE_URL = "/v1/payments"
+
+    @classmethod
+    def refund(
+        cls,
+        id: str,
+        amount: Optional[int] = None,
+        api_key: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        params = {}
+        if amount is not None:
+            params["amount"] = amount
+        return cls._static_request(
+            "post",
+            f"{cls.RESOURCE_URL}/{id}/refund",
+            params=params,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+        )

lunipay-0.1.0/lunipay/api_resources/payment_link.py

@@ -0,0 +1,18 @@
+from ._abstract import (
+    APIResource,
+    CreateableResource,
+    DeleteableResource,
+    ListableResource,
+    UpdateableResource,
+)
+
+
+class PaymentLink(
+    CreateableResource,
+    ListableResource,
+    UpdateableResource,
+    DeleteableResource,
+    APIResource,
+):
+    OBJECT_NAME = "payment_link"
+    RESOURCE_URL = "/v1/payment-links"

lunipay-0.1.0/lunipay/api_resources/webhook_endpoint.py

@@ -0,0 +1,18 @@
+from ._abstract import (
+    APIResource,
+    CreateableResource,
+    DeleteableResource,
+    ListableResource,
+    UpdateableResource,
+)
+
+
+class WebhookEndpoint(
+    CreateableResource,
+    ListableResource,
+    UpdateableResource,
+    DeleteableResource,
+    APIResource,
+):
+    OBJECT_NAME = "webhook_endpoint"
+    RESOURCE_URL = "/v1/webhook-endpoints"

lunipay-0.1.0/lunipay/error.py

@@ -0,0 +1,75 @@
+"""
+LuniPay SDK exception hierarchy.
+
+    try:
+        lunipay.CheckoutSession.create(amount=-1, currency="usd", ...)
+    except lunipay.error.InvalidRequestError as e:
+        print(e.param, e.code, e.message)
+"""
+
+from typing import Any, Optional
+
+
+class LuniPayError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        http_status: Optional[int] = None,
+        json_body: Optional[Any] = None,
+    ) -> None:
+        self.message = message or "An unknown error occurred"
+        self.http_status = http_status
+        self.json_body = json_body
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class APIError(LuniPayError):
+    """Server-side (5xx) error from the LuniPay API."""
+
+
+class APIConnectionError(LuniPayError):
+    """Network-level error — timeout, DNS failure, TLS error, etc."""
+
+
+class AuthenticationError(LuniPayError):
+    """Invalid or missing API key."""
+
+
+class PermissionError(LuniPayError):  # noqa: A001 — intentionally shadowing built-in
+    """API key lacks permission (e.g., publishable key on server endpoint)."""
+
+
+class RateLimitError(LuniPayError):
+    """Rate limit exceeded (HTTP 429)."""
+
+
+class InvalidRequestError(LuniPayError):
+    """
+    Bad request — invalid params, resource not found, or invalid state
+    transition. Carries `param` and `code` from the API error envelope.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        param: Optional[str] = None,
+        code: Optional[str] = None,
+        http_status: Optional[int] = None,
+        json_body: Optional[Any] = None,
+    ) -> None:
+        self.param = param
+        self.code = code
+        super().__init__(message, http_status=http_status, json_body=json_body)
+
+
+class IdempotencyError(InvalidRequestError):
+    """Idempotency key reused with different request parameters (HTTP 409)."""
+
+
+class SignatureVerificationError(LuniPayError):
+    """Webhook signature verification failed."""

lunipay-0.1.0/lunipay/webhook.py

@@ -0,0 +1,120 @@
+"""
+Webhook signature verification.
+
+Mirrors the signing scheme in `src/lib/utils/crypto.ts`:
+
+    header = f"t={timestamp},v1={hex_hmac_sha256}"
+    signed = f"{timestamp}.{payload}"
+    hmac   = HMAC-SHA256(signed_with=secret).hex()
+
+Developers verify inbound webhook requests like so:
+
+    event = lunipay.Webhook.construct_event(
+        payload=request.get_data(),
+        sig_header=request.headers["LuniPay-Signature"],
+        secret="whsec_your_secret",
+    )
+"""
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, Union
+
+from .error import SignatureVerificationError
+
+DEFAULT_TOLERANCE_SECONDS = 300  # 5 minutes — matches the server default.
+
+
+class Webhook:
+    @staticmethod
+    def construct_event(
+        payload: Union[bytes, str],
+        sig_header: str,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    ) -> Any:
+        """
+        Verify a webhook signature and return the parsed event payload.
+
+        Args:
+            payload:    Raw request body, bytes or str — MUST be the exact
+                        bytes LuniPay sent. Do not re-serialize.
+            sig_header: Value of the `LuniPay-Signature` header.
+            secret:     The endpoint's signing secret (whsec_...).
+            tolerance:  Maximum age of the timestamp in seconds.
+
+        Returns:
+            The parsed JSON event dict (with `id`, `type`, `data`, etc.).
+
+        Raises:
+            lunipay.error.SignatureVerificationError on any failure.
+        """
+        if isinstance(payload, bytes):
+            payload_str = payload.decode("utf-8", errors="strict")
+        else:
+            payload_str = payload
+
+        if not sig_header:
+            raise SignatureVerificationError("Missing LuniPay-Signature header")
+
+        timestamp, signatures = _parse_header(sig_header)
+        if timestamp is None:
+            raise SignatureVerificationError(
+                "Unable to extract timestamp from LuniPay-Signature header"
+            )
+        if not signatures:
+            raise SignatureVerificationError(
+                "Unable to extract v1 signatures from LuniPay-Signature header"
+            )
+
+        signed = f"{timestamp}.{payload_str}"
+        expected = hmac.new(
+            secret.encode("utf-8"), signed.encode("utf-8"), hashlib.sha256
+        ).hexdigest()
+
+        if not any(hmac.compare_digest(expected, sig) for sig in signatures):
+            raise SignatureVerificationError(
+                "No valid signature found for the payload"
+            )
+
+        now = int(time.time())
+        if abs(now - timestamp) > tolerance:
+            raise SignatureVerificationError(
+                f"Timestamp outside tolerance window "
+                f"(tolerance={tolerance}s, drift={abs(now - timestamp)}s)"
+            )
+
+        try:
+            return json.loads(payload_str)
+        except json.JSONDecodeError as e:
+            raise SignatureVerificationError(f"Invalid JSON payload: {e}")
+
+
+def _parse_header(
+    header: str,
+) -> "tuple[int | None, list[str]]":
+    """Parse `t=<ts>,v1=<sig>[,v1=<sig2>...]` into (timestamp, [signatures])."""
+    timestamp: "int | None" = None
+    signatures: list[str] = []
+    for part in header.split(","):
+        part = part.strip()
+        if "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        k = k.strip()
+        v = v.strip()
+        if k == "t":
+            try:
+                timestamp = int(v)
+            except ValueError:
+                return None, []
+        elif k == "v1":
+            signatures.append(v)
+    return timestamp, signatures
+
+
+# Silence an unused-import warning under strict type checkers; Mapping is
+# imported for potential future typed-event support.
+_ = Mapping

lunipay-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lunipay"
+version = "0.1.0"
+description = "The official LuniPay Python SDK."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "LuniPay" }]
+dependencies = [
+    "requests>=2.20",
+    "typing_extensions>=4.0; python_version<'3.11'",
+]
+keywords = ["lunipay", "payments", "checkout", "stripe-alternative", "caribbean", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://lunipay.io/docs/sdks/python"
+Documentation = "https://lunipay.io/docs/sdks/python"
+Repository = "https://github.com/SammarieoBrown/lunipay-sdk"
+Issues = "https://github.com/SammarieoBrown/lunipay-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["lunipay"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "lunipay",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]