norialabs-pay 0.1.0__tar.gz

norialabs_pay-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+coverage/
+
+sdks/php/vendor/
+sdks/php/composer.lock
+sdks/php/.phpstan-cache/
+sdks/php/.phpunit.cache/
+
+sdks/python/.coverage
+sdks/python/.venv/
+sdks/python/.pytest_cache/
+sdks/python/.ruff_cache/
+sdks/python/dist/
+**/__pycache__/
+
+apps/console/dist/
+*.tsbuildinfo
+packages/*/test/*.d.ts

norialabs_pay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noria Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

norialabs_pay-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: norialabs-pay
+Version: 0.1.0
+Summary: Python client for Noria Pay: collect, pay out and refund across M-PESA, SasaPay and Paystack through one internal service instead of wiring a provider into every product.
+Project-URL: Homepage, https://github.com/norialabs/pay
+Project-URL: Source, https://github.com/norialabs/pay
+Project-URL: Issues, https://github.com/norialabs/pay/issues
+Author-email: Joseph Gitonga <thekiharani@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: kenya,mpesa,noria,pay,payments,paystack,sasapay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# `norialabs-pay`
+
+Python client for **Noria Pay**. Collect, pay out and refund across M-PESA, SasaPay and
+Paystack through one internal service instead of wiring a provider into every product.
+
+Sync and async, typed, `httpx` the only dependency.
+
+```bash
+pip install norialabs-pay
+```
+
+## Collecting
+
+An idempotency key is a required argument, not an option you can forget. Use something your
+own system already owns — the invoice id plus the attempt — not a fresh uuid per call, or the
+key protects nothing.
+
+```python
+from noria_pay import Pay
+
+pay = Pay(api_key=os.environ["PAY_API_KEY"], base_url="https://pay.noria.co.ke")
+
+charge = pay.charges.create(
+    {
+        "amount_minor": 150_000,       # KES 1,500.00
+        "channel": "mpesa",
+        "reference": invoice.number,   # yours; the service never interprets it
+        "description": "April rent",
+        "payer_phone": customer.phone,
+        "metadata": {"invoice_id": str(invoice.id)},
+    },
+    f"invoice:{invoice.id}:{attempt}",
+)
+
+# charge["next_action"]["type"] is "await_payer" (the STK prompt is already sent)
+# or "redirect" (send them to ["url"]).
+```
+
+`AsyncPay` has the same surface with `await`, and both work as context managers.
+
+## The one error that is not like the others
+
+A `504` carrying `outcome_unknown` means the provider never answered. The payer **may already
+have been debited**. The client never retries it, and neither should you.
+
+```python
+from noria_pay import PayError
+
+try:
+    pay.charges.create(charge, key)
+except PayError as error:
+    if error.outcome_unknown:
+        settled = pay.wait_for_settlement(error.transaction_id)
+        # resolve against settled["status"], never by charging again
+    raise
+```
+
+## Receiving webhooks
+
+Verify against the **raw body**. A framework that hands you a parsed dict has already lost the
+byte order, and re-serialising it will not match the signature.
+
+```python
+from noria_pay import verify_webhook
+
+@app.post("/hooks/pay")
+async def hook(request: Request):
+    event = verify_webhook(
+        await request.body(),
+        request.headers["pay-signature"],
+        os.environ["PAY_WEBHOOK_SECRET"],
+    )
+
+    if event["type"] == "succeeded":
+        # settled_minor is what actually moved, which is not always amount_minor: a payer can
+        # underpay an STK prompt, and Paystack deducts its fee before settlement.
+        await settle(event["data"]["reference"], event["data"]["settled_minor"], event["data"]["fee_minor"])
+
+    return Response(status_code=204)
+```
+
+It raises on a bad signature, a wrong secret, or a timestamp outside the five-minute
+tolerance, so a replay cannot post twice.
+
+## Amounts
+
+Always minor units. The service rejects a KES amount that is not a whole number of shillings
+rather than rounding it, because the rails settle whole shillings and a silent round only
+surfaces in reconciliation.
+
+## Surfaces
+
+`pay.charges` · `payouts` · `refunds` · `transactions` · `payment_methods` · `payment_links` ·
+`webhooks`
+
+## This is not `noriapay`
+
+That package wraps the providers directly and this service uses it internally. This one talks
+to Noria Pay, which owns the persistence, the callbacks and the reconciliation that `noriapay`
+deliberately leaves to you.
+
+Events are not delivered in order. Delivery runs in parallel and retries, so a later event can
+arrive first; order on `created_at`, which is when the event happened rather than when the
+attempt went out. Every payload also carries the transaction's status as it stood at delivery,
+so acting on that is safe whatever order they arrive in.

norialabs_pay-0.1.0/README.md

@@ -0,0 +1,105 @@
+# `norialabs-pay`
+
+Python client for **Noria Pay**. Collect, pay out and refund across M-PESA, SasaPay and
+Paystack through one internal service instead of wiring a provider into every product.
+
+Sync and async, typed, `httpx` the only dependency.
+
+```bash
+pip install norialabs-pay
+```
+
+## Collecting
+
+An idempotency key is a required argument, not an option you can forget. Use something your
+own system already owns — the invoice id plus the attempt — not a fresh uuid per call, or the
+key protects nothing.
+
+```python
+from noria_pay import Pay
+
+pay = Pay(api_key=os.environ["PAY_API_KEY"], base_url="https://pay.noria.co.ke")
+
+charge = pay.charges.create(
+    {
+        "amount_minor": 150_000,       # KES 1,500.00
+        "channel": "mpesa",
+        "reference": invoice.number,   # yours; the service never interprets it
+        "description": "April rent",
+        "payer_phone": customer.phone,
+        "metadata": {"invoice_id": str(invoice.id)},
+    },
+    f"invoice:{invoice.id}:{attempt}",
+)
+
+# charge["next_action"]["type"] is "await_payer" (the STK prompt is already sent)
+# or "redirect" (send them to ["url"]).
+```
+
+`AsyncPay` has the same surface with `await`, and both work as context managers.
+
+## The one error that is not like the others
+
+A `504` carrying `outcome_unknown` means the provider never answered. The payer **may already
+have been debited**. The client never retries it, and neither should you.
+
+```python
+from noria_pay import PayError
+
+try:
+    pay.charges.create(charge, key)
+except PayError as error:
+    if error.outcome_unknown:
+        settled = pay.wait_for_settlement(error.transaction_id)
+        # resolve against settled["status"], never by charging again
+    raise
+```
+
+## Receiving webhooks
+
+Verify against the **raw body**. A framework that hands you a parsed dict has already lost the
+byte order, and re-serialising it will not match the signature.
+
+```python
+from noria_pay import verify_webhook
+
+@app.post("/hooks/pay")
+async def hook(request: Request):
+    event = verify_webhook(
+        await request.body(),
+        request.headers["pay-signature"],
+        os.environ["PAY_WEBHOOK_SECRET"],
+    )
+
+    if event["type"] == "succeeded":
+        # settled_minor is what actually moved, which is not always amount_minor: a payer can
+        # underpay an STK prompt, and Paystack deducts its fee before settlement.
+        await settle(event["data"]["reference"], event["data"]["settled_minor"], event["data"]["fee_minor"])
+
+    return Response(status_code=204)
+```
+
+It raises on a bad signature, a wrong secret, or a timestamp outside the five-minute
+tolerance, so a replay cannot post twice.
+
+## Amounts
+
+Always minor units. The service rejects a KES amount that is not a whole number of shillings
+rather than rounding it, because the rails settle whole shillings and a silent round only
+surfaces in reconciliation.
+
+## Surfaces
+
+`pay.charges` · `payouts` · `refunds` · `transactions` · `payment_methods` · `payment_links` ·
+`webhooks`
+
+## This is not `noriapay`
+
+That package wraps the providers directly and this service uses it internally. This one talks
+to Noria Pay, which owns the persistence, the callbacks and the reconciliation that `noriapay`
+deliberately leaves to you.
+
+Events are not delivered in order. Delivery runs in parallel and retries, so a later event can
+arrive first; order on `created_at`, which is when the event happened rather than when the
+attempt went out. Every payload also carries the transaction's status as it stood at delivery,
+so acting on that is safe whatever order they arrive in.

norialabs_pay-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "norialabs-pay"
+version = "0.1.0"
+description = "Python client for Noria Pay: collect, pay out and refund across M-PESA, SasaPay and Paystack through one internal service instead of wiring a provider into every product."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joseph Gitonga", email = "thekiharani@gmail.com" }]
+keywords = ["payments", "mpesa", "sasapay", "paystack", "kenya", "noria", "pay"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.28.1"]
+
+[project.urls]
+Homepage = "https://github.com/norialabs/pay"
+Source = "https://github.com/norialabs/pay"
+Issues = "https://github.com/norialabs/pay/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/noria_pay", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/noria_pay"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/noria_pay/py.typed" = "noria_pay/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q --tb=short --cov=noria_pay --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+line-length = 110
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

norialabs_pay-0.1.0/src/noria_pay/__init__.py

@@ -0,0 +1,31 @@
+from noria_pay.client import (
+    DEFAULT_BASE_URL,
+    AsyncPay,
+    Channel,
+    Charge,
+    Direction,
+    Pay,
+    PayError,
+    Payout,
+    Provider,
+    RecordedCharge,
+    Refund,
+    Status,
+)
+from noria_pay.webhooks import verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncPay",
+    "Channel",
+    "Charge",
+    "Direction",
+    "Pay",
+    "PayError",
+    "Payout",
+    "Provider",
+    "RecordedCharge",
+    "Refund",
+    "Status",
+    "verify_webhook",
+]

norialabs_pay-0.1.0/src/noria_pay/client.py

@@ -0,0 +1,466 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any, Literal, NotRequired, TypedDict
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://pay.noria.co.ke"
+RETRYABLE_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+
+# 409 is a conflict everywhere else and not worth another attempt. This one says the same key is
+# still in flight on another request, which resolves by waiting.
+IN_FLIGHT_CODE = "conflict"
+
+# 504 is retryable almost everywhere else. Here it means the provider never answered, the
+# charge is in `unknown`, and the money may already have moved, so it is polled and not re-sent.
+NON_RETRYABLE_CODES = frozenset(
+    {
+        "outcome_unknown",
+        "idempotency_mismatch",
+        "provider_rejected",
+        "provider_not_configured",
+        "duplicate_receipt",
+        "not_refundable",
+        "insufficient_balance",
+    }
+)
+TERMINAL_STATUSES = frozenset({"succeeded", "failed", "cancelled", "expired", "reversed", "unknown"})
+
+Json = dict[str, Any]
+Provider = Literal["daraja", "sasapay", "paystack", "kcb_buni", "manual"]
+Channel = Literal["mpesa", "airtel", "card", "bank", "wallet", "cash"]
+Direction = Literal["collection", "payout", "refund"]
+Status = Literal[
+    "pending", "processing", "succeeded", "failed", "cancelled", "expired", "reversed", "unknown"
+]
+
+
+class Charge(TypedDict):
+    amount_minor: int
+    channel: Channel
+    reference: str
+    description: str
+    currency: NotRequired[str]
+    provider: NotRequired[Provider]
+    mode: NotRequired[Literal["live", "sandbox"]]
+    payer_phone: NotRequired[str]
+    payer_email: NotRequired[str]
+    payer_name: NotRequired[str]
+    return_url: NotRequired[str]
+    expires_in_seconds: NotRequired[int]
+    metadata: NotRequired[dict[str, str]]
+
+
+class RecordedCharge(TypedDict):
+    amount_minor: int
+    channel: Channel
+    reference: str
+    description: str
+    currency: NotRequired[str]
+    receipt: NotRequired[str]
+    payer_phone: NotRequired[str]
+    payer_name: NotRequired[str]
+    paid_at: NotRequired[str]
+    note: NotRequired[str]
+    metadata: NotRequired[dict[str, str]]
+
+
+class Payout(TypedDict):
+    amount_minor: int
+    channel: Channel
+    reference: str
+    description: str
+    recipient_name: str
+    currency: NotRequired[str]
+    provider: NotRequired[Provider]
+    recipient_phone: NotRequired[str]
+    recipient_account: NotRequired[str]
+    recipient_channel_code: NotRequired[str]
+    metadata: NotRequired[dict[str, str]]
+
+
+class Refund(TypedDict):
+    transaction_id: str
+    reason: str
+    amount_minor: NotRequired[int]
+    metadata: NotRequired[dict[str, str]]
+
+
+class PayError(Exception):
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: str,
+        details: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.message = message
+        self.details = details
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return f"PayError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+    @classmethod
+    def from_response(cls, status: int, body: Any) -> PayError:
+        error = body.get("error") if isinstance(body, dict) else None
+        error = error if isinstance(error, dict) else {}
+        return cls(
+            code=error.get("code") or "internal_error",
+            status=status,
+            message=error.get("message") or f"Request failed with status {status}",
+            details=error.get("details"),
+            request_id=error.get("request_id"),
+        )
+
+    @property
+    def outcome_unknown(self) -> bool:
+        """The provider never answered. The payer may already have been debited."""
+        return self.code == "outcome_unknown"
+
+    @property
+    def transaction_id(self) -> str | None:
+        if isinstance(self.details, dict):
+            value = self.details.get("transaction_id")
+            return value if isinstance(value, str) else None
+        return None
+
+    @property
+    def retryable(self) -> bool:
+        if self.code in NON_RETRYABLE_CODES:
+            return False
+        if self.status == 409:
+            return self.code == IN_FLIGHT_CODE
+        return self.status == 0 or self.status in RETRYABLE_STATUSES
+
+
+def _query(**parameters: Any) -> Json:
+    return {key: value for key, value in parameters.items() if value not in (None, "")}
+
+
+def _backoff(attempt: int) -> float:
+    return min(2.0, 0.2 * 2 ** (attempt - 1)) * (0.5 + random.random())
+
+
+def _decode(response: httpx.Response) -> Json:
+    if response.status_code == 204 or not response.content:
+        return {}
+    try:
+        return response.json()
+    except ValueError:
+        # An ingress or proxy answering with HTML, which is what a caller sees exactly when
+        # the service is down. It must still arrive as a PayError like everything else.
+        if response.is_success:
+            raise PayError(
+                code="internal_error",
+                status=response.status_code,
+                message="The response was not JSON",
+            ) from None
+        return {}
+
+
+# quote() defaults to safe="/", which leaves slashes alone: an id of "../operator/projects" would
+# resolve to a different endpoint. Nothing that goes in a path segment may keep its slashes.
+def _segment(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _key(idempotency_key: str) -> dict[str, str]:
+    return {"idempotency-key": idempotency_key}
+
+
+class _Namespace:
+    def __init__(self, client: Pay | AsyncPay) -> None:
+        self._client = client
+
+
+class Charges(_Namespace):
+    def create(self, charge: Charge, idempotency_key: str) -> Any:
+        return self._client.request("POST", "/v1/charges", dict(charge), headers=_key(idempotency_key))
+
+    def record(self, charge: RecordedCharge, idempotency_key: str) -> Any:
+        return self._client.request("POST", "/v1/charges/record", dict(charge), headers=_key(idempotency_key))
+
+    def cancel(self, transaction_id: str) -> Any:
+        return self._client.request("POST", f"/v1/charges/{_segment(transaction_id)}/cancel")
+
+
+class Payouts(_Namespace):
+    def create(self, payout: Payout, idempotency_key: str) -> Any:
+        return self._client.request("POST", "/v1/payouts", dict(payout), headers=_key(idempotency_key))
+
+
+class Refunds(_Namespace):
+    def create(self, refund: Refund, idempotency_key: str) -> Any:
+        return self._client.request("POST", "/v1/refunds", dict(refund), headers=_key(idempotency_key))
+
+
+class Transactions(_Namespace):
+    def get(self, transaction_id: str) -> Any:
+        return self._client.request("GET", f"/v1/transactions/{_segment(transaction_id)}")
+
+    def list(
+        self,
+        direction: Direction | None = None,
+        status: Status | None = None,
+        provider: Provider | None = None,
+        channel: Channel | None = None,
+        reference: str | None = None,
+        receipt: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
+        return self._client.request(
+            "GET",
+            "/v1/transactions",
+            params=_query(
+                direction=direction,
+                status=status,
+                provider=provider,
+                channel=channel,
+                reference=reference,
+                receipt=receipt,
+                limit=limit,
+                cursor=cursor,
+            ),
+        )
+
+    def events(self, transaction_id: str, limit: int | None = None) -> Any:
+        return self._client.request(
+            "GET", f"/v1/transactions/{_segment(transaction_id)}/events", params=_query(limit=limit)
+        )
+
+
+class PaymentMethods(_Namespace):
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/payment-methods")
+
+    def set(self, provider: Provider, method: Json) -> Any:
+        return self._client.request("PUT", f"/v1/payment-methods/{_segment(provider)}", method)
+
+    def verify(self, provider: Provider) -> Any:
+        return self._client.request("POST", f"/v1/payment-methods/{_segment(provider)}/verify")
+
+    def remove(self, provider: Provider) -> Any:
+        return self._client.request("DELETE", f"/v1/payment-methods/{_segment(provider)}")
+
+
+class PaymentLinks(_Namespace):
+    def create(self, link: Json) -> Any:
+        return self._client.request("POST", "/v1/payment-links", link)
+
+    def get(self, link_id: str) -> Any:
+        return self._client.request("GET", f"/v1/payment-links/{_segment(link_id)}")
+
+    def list(self, limit: int | None = None, cursor: str | None = None) -> Any:
+        return self._client.request("GET", "/v1/payment-links", params=_query(limit=limit, cursor=cursor))
+
+    def update(self, link_id: str, link: Json) -> Any:
+        return self._client.request("PATCH", f"/v1/payment-links/{_segment(link_id)}", link)
+
+    def close(self, link_id: str) -> Any:
+        return self._client.request("DELETE", f"/v1/payment-links/{_segment(link_id)}")
+
+
+class Statements(_Namespace):
+    def import_(self, statement: Json) -> Any:
+        """Settle what matches and report the rest; the same rows twice replay the first result."""
+        return self._client.request("POST", "/v1/statements", statement)
+
+    def get(self, import_id: str) -> Any:
+        return self._client.request("GET", f"/v1/statements/{_segment(import_id)}")
+
+    def list(self, limit: int | None = None, cursor: str | None = None) -> Any:
+        return self._client.request("GET", "/v1/statements", params=_query(limit=limit, cursor=cursor))
+
+
+class Webhooks(_Namespace):
+    def create(self, url: str, event_types: list[str] | None = None, description: str | None = None) -> Any:
+        return self._client.request(
+            "POST",
+            "/v1/webhook-endpoints",
+            {"url": url, "event_types": event_types or [], "description": description},
+        )
+
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/webhook-endpoints")
+
+    def update(self, endpoint_id: str, changes: Json) -> Any:
+        return self._client.request("PATCH", f"/v1/webhook-endpoints/{_segment(endpoint_id)}", changes)
+
+    def remove(self, endpoint_id: str) -> Any:
+        return self._client.request("DELETE", f"/v1/webhook-endpoints/{_segment(endpoint_id)}")
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        retries: int = 2,
+    ) -> None:
+        if not api_key:
+            raise PayError("validation_error", 0, "A Noria Pay API key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+
+        self.charges = Charges(self)  # type: ignore[arg-type]
+        self.payouts = Payouts(self)  # type: ignore[arg-type]
+        self.refunds = Refunds(self)  # type: ignore[arg-type]
+        self.transactions = Transactions(self)  # type: ignore[arg-type]
+        self.payment_methods = PaymentMethods(self)  # type: ignore[arg-type]
+        self.payment_links = PaymentLinks(self)  # type: ignore[arg-type]
+        self.statements = Statements(self)  # type: ignore[arg-type]
+        self.webhooks = Webhooks(self)  # type: ignore[arg-type]
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"authorization": f"Bearer {self._api_key}", "accept": "application/json"}
+
+    # A write that moves money carries an Idempotency-Key, so repeating it after a dropped
+    # connection replays rather than charges again. Without one it is not safe to repeat.
+    def _may_repeat(self, method: str, headers: dict[str, str] | None) -> bool:
+        return method == "GET" or bool(headers and "idempotency-key" in headers)
+
+
+class Pay(_BaseClient):
+    def __init__(self, *args: Any, transport: httpx.BaseTransport | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.Client(timeout=self._timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Pay:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Json | None = None,
+        params: Json | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Json:
+        last: PayError | None = None
+
+        for attempt in range(1, self._retries + 2):
+            if attempt > 1:
+                time.sleep(_backoff(attempt - 1))
+
+            try:
+                response = self._http.request(
+                    method,
+                    f"{self._base_url}{path}",
+                    json=body,
+                    params=params,
+                    headers={**self._headers, **(headers or {})},
+                )
+            except httpx.HTTPError as exception:
+                last = PayError("network_error", 0, str(exception))
+                if not self._may_repeat(method, headers):
+                    raise last from exception
+                continue
+
+            if response.is_success:
+                return _decode(response)
+
+            last = PayError.from_response(response.status_code, _decode(response))
+            if not last.retryable:
+                raise last
+
+        raise last or PayError("network_error", 0, "Request failed")
+
+    def wait_for_settlement(
+        self, transaction_id: str, timeout_seconds: float = 120.0, interval_seconds: float = 3.0
+    ) -> Json:
+        """Poll a charge the payer is still answering, returning once it is terminal."""
+        deadline = time.monotonic() + timeout_seconds
+
+        while True:
+            transaction = self.transactions.get(transaction_id)
+            if transaction.get("status") in TERMINAL_STATUSES:
+                return transaction
+            if time.monotonic() + interval_seconds >= deadline:
+                return transaction
+            time.sleep(interval_seconds)
+
+
+class AsyncPay(_BaseClient):
+    def __init__(self, *args: Any, transport: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self._timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncPay:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Json | None = None,
+        params: Json | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Json:
+        last: PayError | None = None
+
+        for attempt in range(1, self._retries + 2):
+            if attempt > 1:
+                await asyncio.sleep(_backoff(attempt - 1))
+
+            try:
+                response = await self._http.request(
+                    method,
+                    f"{self._base_url}{path}",
+                    json=body,
+                    params=params,
+                    headers={**self._headers, **(headers or {})},
+                )
+            except httpx.HTTPError as exception:
+                last = PayError("network_error", 0, str(exception))
+                if not self._may_repeat(method, headers):
+                    raise last from exception
+                continue
+
+            if response.is_success:
+                return _decode(response)
+
+            last = PayError.from_response(response.status_code, _decode(response))
+            if not last.retryable:
+                raise last
+
+        raise last or PayError("network_error", 0, "Request failed")
+
+    async def wait_for_settlement(
+        self, transaction_id: str, timeout_seconds: float = 120.0, interval_seconds: float = 3.0
+    ) -> Json:
+        deadline = time.monotonic() + timeout_seconds
+
+        while True:
+            transaction = await self.transactions.get(transaction_id)
+            if transaction.get("status") in TERMINAL_STATUSES:
+                return transaction
+            if time.monotonic() + interval_seconds >= deadline:
+                return transaction
+            await asyncio.sleep(interval_seconds)

norialabs_pay-0.1.0/src/noria_pay/webhooks.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+from noria_pay.client import PayError
+
+
+def verify_webhook(
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> dict[str, Any]:
+    """Verify against the raw request body.
+
+    A framework that hands you a parsed object has already lost the byte order, and
+    re-serialising it will not match the signature.
+    """
+    timestamp, provided = _parse(signature)
+
+    if abs((now if now is not None else int(time.time())) - timestamp) > tolerance_seconds:
+        raise PayError("validation_error", 400, "Signature timestamp is outside the tolerance window")
+
+    body = payload.decode() if isinstance(payload, bytes) else payload
+    expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
+
+    if not hmac.compare_digest(expected, provided):
+        raise PayError("unauthorized", 401, "Invalid webhook signature")
+
+    event = json.loads(body)
+
+    if not isinstance(event, dict):
+        raise PayError("validation_error", 400, "Webhook payload is not a JSON object")
+
+    return event
+
+
+def _parse(signature: str) -> tuple[int, str]:
+    parts: dict[str, str] = {}
+
+    for pair in signature.split(","):
+        key, _, value = pair.strip().partition("=")
+        if value:
+            parts[key] = value
+
+    timestamp = parts.get("t", "")
+
+    if not timestamp.isdigit() or "v1" not in parts:
+        raise PayError("validation_error", 400, "Malformed pay-signature header")
+
+    return int(timestamp), parts["v1"]