manza 1.0.0__py3-none-any.whl

manza/__init__.py

@@ -0,0 +1,63 @@
+"""Manza Python SDK. Mirrors lib/manza.rb."""
+
+from . import transfer_authorization
+from ._version import __version__
+from .client import Manza
+from .errors import (
+    ManzaArgumentError,
+    ManzaAuthenticationError,
+    ManzaConfigurationError,
+    ManzaConflictError,
+    ManzaConnectionError,
+    ManzaError,
+    ManzaForbiddenError,
+    ManzaNotFoundError,
+    ManzaRateLimitError,
+    ManzaServerError,
+    ManzaValidationError,
+)
+from .page import MAX_PER_PAGE, Page
+from .resources.accounts import Accounts
+from .resources.beneficiaries import Beneficiaries
+from .resources.checkout_sessions import CheckoutSessions
+from .resources.customers import Customers
+from .resources.entity import Entity
+from .resources.invoices import Invoices
+from .resources.payee_trust_requests import PayeeTrustRequests
+from .resources.payment_links import PaymentLinks
+from .resources.transfer_drafts import TransferDrafts
+from .resources.webhook_endpoints import WebhookEndpoints
+from .response import ManzaResponse
+
+VERSION = __version__
+
+__all__ = [
+    "MAX_PER_PAGE",
+    "VERSION",
+    "Accounts",
+    "Beneficiaries",
+    "CheckoutSessions",
+    "Customers",
+    "Entity",
+    "Invoices",
+    "Manza",
+    "ManzaArgumentError",
+    "ManzaAuthenticationError",
+    "ManzaConfigurationError",
+    "ManzaConflictError",
+    "ManzaConnectionError",
+    "ManzaError",
+    "ManzaForbiddenError",
+    "ManzaNotFoundError",
+    "ManzaRateLimitError",
+    "ManzaResponse",
+    "ManzaServerError",
+    "ManzaValidationError",
+    "Page",
+    "PayeeTrustRequests",
+    "PaymentLinks",
+    "TransferDrafts",
+    "WebhookEndpoints",
+    "__version__",
+    "transfer_authorization",
+]

manza/_env.py

@@ -0,0 +1,39 @@
+"""Environment lookup: `MANZA_<NAME>` first, then the legacy `ZAZU_<NAME>`.
+
+The legacy name still works for all of 1.x and warns once per variable."""
+
+from __future__ import annotations
+
+import os
+import threading
+import warnings
+
+_warned: set[str] = set()
+_lock = threading.Lock()
+
+
+def get(name: str) -> str | None:
+    """Return `MANZA_<name>`, else `ZAZU_<name>` (warning once), else None."""
+    value = os.getenv(f"MANZA_{name}")
+    if value is not None:
+        return value
+    legacy = f"ZAZU_{name}"
+    value = os.getenv(legacy)
+    if value:
+        with _lock:
+            first = legacy not in _warned
+            _warned.add(legacy)
+        if first:
+            warnings.warn(
+                f"{legacy} is deprecated; set MANZA_{name} instead. "
+                "The ZAZU_* fallback will be removed in 2.0.",
+                FutureWarning,
+                stacklevel=3,
+            )
+        return value
+    return None
+
+
+def reset_warnings() -> None:
+    """Forget which legacy variables already warned (for tests)."""
+    _warned.clear()

manza/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

manza/client.py

@@ -0,0 +1,213 @@
+"""Mirrors lib/manza/client.rb. Sync HTTP entry point built on httpx."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from . import _env
+from ._version import __version__
+from .errors import (
+    ManzaAuthenticationError,
+    ManzaConfigurationError,
+    ManzaConflictError,
+    ManzaConnectionError,
+    ManzaError,
+    ManzaForbiddenError,
+    ManzaNotFoundError,
+    ManzaRateLimitError,
+    ManzaServerError,
+    ManzaValidationError,
+)
+from .page import MAX_PER_PAGE, Page
+from .resources.accounts import Accounts
+from .resources.beneficiaries import Beneficiaries
+from .resources.checkout_sessions import CheckoutSessions
+from .resources.customers import Customers
+from .resources.entity import Entity
+from .resources.invoices import Invoices
+from .resources.payee_trust_requests import PayeeTrustRequests
+from .resources.payment_links import PaymentLinks
+from .resources.transfer_drafts import TransferDrafts
+from .resources.webhook_endpoints import WebhookEndpoints
+from .response import ManzaResponse
+
+# Morocco production. South Africa is https://za.manza.finance.
+DEFAULT_BASE_URL = "https://ma.manza.finance"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = f"manza-python/{__version__}"
+
+
+class Manza:
+    """Top-level Manza client. Resources hang off it as attributes."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key = api_key or _env.get("API_KEY")
+        if not api_key:
+            raise ManzaConfigurationError(
+                "Missing api_key. Pass api_key= or set MANZA_API_KEY."
+            )
+        self.api_key = api_key
+        self.base_url = (base_url or _env.get("BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.api_version = api_version or _env.get("API_VERSION")
+        self.timeout = (
+            timeout if timeout is not None else _env_float("TIMEOUT", DEFAULT_TIMEOUT)
+        )
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+        self.accounts = Accounts(self)
+        self.beneficiaries = Beneficiaries(self)
+        self.checkout_sessions = CheckoutSessions(self)
+        self.customers = Customers(self)
+        self.entity = Entity(self)
+        self.invoices = Invoices(self)
+        self.payee_trust_requests = PayeeTrustRequests(self)
+        self.payment_links = PaymentLinks(self)
+        self.transfer_drafts = TransferDrafts(self)
+        self.webhook_endpoints = WebhookEndpoints(self)
+
+    def __enter__(self) -> Manza:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> ManzaResponse:
+        url = self._build_url(path, params)
+        request_headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+        if self.api_version:
+            request_headers["Manza-Version"] = self.api_version
+        if headers:
+            request_headers.update(headers)
+
+        request_kwargs: dict[str, Any] = {"headers": request_headers}
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+            # Compact, raw UTF-8: byte-identical to manza-ruby's JSON.generate.
+            request_kwargs["content"] = json.dumps(
+                body, separators=(",", ":"), ensure_ascii=False
+            ).encode()
+
+        try:
+            raw = self._http.request(method.upper(), url, **request_kwargs)
+        except httpx.TimeoutException as err:
+            raise ManzaConnectionError(f"Request timed out after {self.timeout}s") from err
+        except httpx.HTTPError as err:
+            raise ManzaConnectionError(f"Connection failed: {err}") from err
+
+        parsed = _parse_body(raw)
+        response = ManzaResponse(raw, parsed)
+        if response.success:
+            return response
+        raise _build_error(response)
+
+    def _build_url(self, path: str, params: dict[str, Any] | None) -> str:
+        trimmed = path.lstrip("/")
+        url = f"{self.base_url}/{trimmed}"
+        if params:
+            cleaned = {k: v for k, v in params.items() if v is not None}
+            if cleaned:
+                url = f"{url}?{urlencode(cleaned, doseq=True)}"
+        return url
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = _env.get(name)
+    if not raw:
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def _parse_body(raw: httpx.Response) -> Any:
+    content_type = raw.headers.get("content-type", "")
+    if "json" not in content_type:
+        return None
+    text = raw.text
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def _error_payload(body: Any) -> dict[str, Any]:
+    if not isinstance(body, dict):
+        return {}
+    err = body.get("error")
+    return err if isinstance(err, dict) else {}
+
+
+def _build_error(response: ManzaResponse) -> ManzaError:
+    payload = _error_payload(response.body)
+    message = payload.get("message")
+    opts: dict[str, Any] = {
+        "status": response.status,
+        "request_id": response.request_id,
+        "type": payload.get("type"),
+        "param": payload.get("param"),
+        "body": response.body,
+        "headers": response.headers,
+    }
+
+    status = response.status
+    if status == 401:
+        return ManzaAuthenticationError(message or "Authentication failed", **opts)
+    if status == 403:
+        return ManzaForbiddenError(message or "Forbidden", **opts)
+    if status == 404:
+        return ManzaNotFoundError(message or "Not found", **opts)
+    if status == 400:
+        return ManzaValidationError(message or "Bad request", **opts)
+    if status == 422:
+        return ManzaValidationError(message or "Validation failed", **opts)
+    if status == 409:
+        return ManzaConflictError(
+            message or "Conflict", payment_id=payload.get("payment_id"), **opts
+        )
+    if status == 429:
+        retry_after = response.headers.get("retry-after")
+        try:
+            retry_after_int = int(retry_after) if retry_after else None
+        except ValueError:
+            retry_after_int = None
+        return ManzaRateLimitError(
+            message or "Rate limited", retry_after=retry_after_int, **opts
+        )
+    if 500 <= status < 600:
+        return ManzaServerError(message or f"Server error ({status})", **opts)
+    return ManzaError(message or f"Unexpected status {status}", **opts)
+
+
+__all__ = ["MAX_PER_PAGE", "Manza", "Page"]

manza/errors.py

@@ -0,0 +1,84 @@
+"""Mirrors lib/manza/errors.rb. Ten-class hierarchy shared across SDKs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ManzaError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        request_id: str | None = None,
+        type: str | None = None,
+        param: str | None = None,
+        body: Any = None,
+        headers: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.type = type
+        self.param = param
+        self.body = body
+        self.headers = headers
+
+
+class ManzaArgumentError(ManzaError):
+    """Caller passed bad arguments before any HTTP request was made."""
+
+
+class ManzaConfigurationError(ManzaError):
+    """Missing or invalid client configuration (e.g. no API key)."""
+
+
+class ManzaConnectionError(ManzaError):
+    """The HTTP request failed before getting a response (timeout, DNS, refused)."""
+
+
+class ManzaAuthenticationError(ManzaError):
+    """HTTP 401."""
+
+
+class ManzaForbiddenError(ManzaError):
+    """HTTP 403."""
+
+
+class ManzaNotFoundError(ManzaError):
+    """HTTP 404."""
+
+
+class ManzaValidationError(ManzaError):
+    """HTTP 400 (malformed request, e.g. a bad `limit`/`cursor`) or 422 (rejected body).
+
+    `param` carries the offending field name when the API supplies it.
+    """
+
+
+class ManzaConflictError(ManzaError):
+    """HTTP 409. The request conflicts with an existing resource.
+
+    For a duplicate `client_reference` on a transfer draft (`type` is
+    "duplicate_client_reference"), `payment_id` names the draft that already holds it.
+    """
+
+    def __init__(self, message: str, *, payment_id: str | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.payment_id = payment_id
+
+
+class ManzaRateLimitError(ManzaError):
+    """HTTP 429. `retry_after` is the value of the Retry-After header in seconds, if present."""
+
+    def __init__(self, message: str, *, retry_after: int | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ManzaServerError(ManzaError):
+    """HTTP 5xx."""

manza/page.py

@@ -0,0 +1,54 @@
+"""Mirrors lib/manza/page.rb. Cursor-based pagination, hard cap of 100 items per page."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any, Generic, TypeVar
+
+from .response import ManzaResponse
+
+MAX_PER_PAGE = 100
+
+T = TypeVar("T")
+
+
+class Page(Generic[T]):
+    """A single page of results plus a fetcher to load the next page on demand."""
+
+    def __init__(
+        self,
+        response: ManzaResponse,
+        fetcher: Callable[[str | None], "Page[T]"],
+    ) -> None:
+        self.response = response
+        self._fetcher = fetcher
+        body = response.body if isinstance(response.body, dict) else {}
+        self.data: list[T] = list(body.get("data") or [])
+        self.has_more: bool = bool(body.get("has_more"))
+        self.next_cursor: str | None = body.get("next_cursor")
+
+    def next(self) -> Page[T] | None:
+        """Fetch the next page, or None if there are no more results."""
+        if not self.has_more or not self.next_cursor:
+            return None
+        return self._fetcher(self.next_cursor)
+
+    def auto_paging_iter(self) -> Iterator[T]:
+        """Yield every item across all pages by chasing cursors."""
+        page: Page[T] | None = self
+        while page is not None:
+            yield from page.data
+            page = page.next()
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        return f"Page(items={len(self.data)}, has_more={self.has_more})"
+
+
+PageBody = dict[str, Any]
+PageFetcher = Callable[[str | None], Page[Any]]

manza/resources/accounts.py

@@ -0,0 +1,64 @@
+"""Mirrors lib/manza/resources/accounts.rb."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from ..page import MAX_PER_PAGE, Page
+from ..response import ManzaResponse
+from .base import ResourceBase
+
+
+class Accounts(ResourceBase):
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        currency_code: str | None = None,
+        limit: int = MAX_PER_PAGE,
+        cursor: str | None = None,
+    ) -> Page[Any]:
+        return self.list_page(
+            "api/accounts",
+            {"status": status, "currency_code": currency_code},
+            limit=limit,
+            cursor=cursor,
+        )
+
+    def get(self, id: str) -> ManzaResponse:
+        return self.http_get(self.encode_path("api/accounts", id))
+
+    def list_transactions(
+        self,
+        account_id: str,
+        *,
+        operation: str | None = None,
+        posted_after: str | datetime | None = None,
+        posted_before: str | datetime | None = None,
+        limit: int = MAX_PER_PAGE,
+        cursor: str | None = None,
+    ) -> Page[Any]:
+        return self.list_page(
+            self.encode_path("api/accounts", account_id, "transactions"),
+            {
+                "operation": operation,
+                "posted_after": _serialize_time(posted_after),
+                "posted_before": _serialize_time(posted_before),
+            },
+            limit=limit,
+            cursor=cursor,
+        )
+
+    def get_transaction(self, account_id: str, transaction_id: str) -> ManzaResponse:
+        return self.http_get(
+            self.encode_path("api/accounts", account_id, "transactions", transaction_id)
+        )
+
+
+def _serialize_time(value: str | datetime | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return value.isoformat()

manza/resources/base.py

@@ -0,0 +1,89 @@
+"""Mirrors lib/manza/resources/base.rb."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from ..errors import ManzaArgumentError
+from ..page import MAX_PER_PAGE, Page
+from ..response import ManzaResponse
+
+if TYPE_CHECKING:
+    from ..client import Manza
+
+
+class ResourceBase:
+    def __init__(self, client: Manza) -> None:
+        self._client = client
+
+    @staticmethod
+    def encode_path(base: str, *segments: str) -> str:
+        """Build a request path by joining a literal base path with dynamic
+        segments. The base is appended verbatim; each dynamic segment is
+        percent-encoded so an ID containing `/` or other special characters
+        cannot escape the intended path.
+
+            encode_path("api/accounts", "acc_xyz")
+              # => "api/accounts/acc_xyz"
+            encode_path("api/accounts", "acc 1", "transactions", "tx 1")
+              # => "api/accounts/acc%201/transactions/tx%201"
+        """
+        encoded = []
+        for seg in segments:
+            text = str(seg)
+            # An empty segment would silently turn `/things/:id` into
+            # `/things/`, which on most APIs redispatches to the list
+            # endpoint. Surface it loudly.
+            if not text:
+                raise ManzaArgumentError("path segment cannot be blank")
+            encoded.append(quote(text, safe=""))
+        return "/".join([base, *encoded])
+
+    def http_get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> ManzaResponse:
+        return self._client.request("GET", path, params=params)
+
+    def http_post(
+        self,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> ManzaResponse:
+        return self._client.request("POST", path, body=body, params=params)
+
+    def http_patch(
+        self,
+        path: str,
+        *,
+        body: Any = None,
+    ) -> ManzaResponse:
+        return self._client.request("PATCH", path, body=body)
+
+    def http_delete(self, path: str) -> ManzaResponse:
+        return self._client.request("DELETE", path)
+
+    def list_page(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Page[Any]:
+        merged: dict[str, Any] = dict(params or {})
+        if limit is not None:
+            merged["limit"] = min(limit, MAX_PER_PAGE)
+        if cursor is not None:
+            merged["cursor"] = cursor
+
+        def fetch(next_cursor: str | None) -> Page[Any]:
+            return self.list_page(path, params, limit=limit, cursor=next_cursor)
+
+        response = self.http_get(path, params=merged)
+        return Page(response, fetch)

manza/resources/beneficiaries.py

@@ -0,0 +1,61 @@
+"""Mirrors lib/manza/resources/beneficiaries.rb.
+
+Saved transfer recipients. Each beneficiary embeds its bank accounts; the one
+flagged ``default`` is used when a transfer names only the beneficiary_id.
+There is no update or delete via the API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..page import MAX_PER_PAGE, Page
+from ..response import ManzaResponse
+from .base import ResourceBase
+
+
+class Beneficiaries(ResourceBase):
+    def list(self, *, limit: int = MAX_PER_PAGE, cursor: str | None = None) -> Page[Any]:
+        return self.list_page("api/beneficiaries", {}, limit=limit, cursor=cursor)
+
+    def get(self, id: str) -> ManzaResponse:
+        return self.http_get(self.encode_path("api/beneficiaries", id))
+
+    def create(self, **attributes: Any) -> ManzaResponse:
+        """POST /api/beneficiaries
+
+        Keys: beneficiary_type ("individual" | "business"; inferred from
+        person_name / company_name when omitted), person_name, company_name,
+        email, phone_number. Values must be strings. Shares a 10/minute limit
+        with ``create_external_account``.
+        """
+        return self.http_post("api/beneficiaries", body=attributes)
+
+    def list_external_accounts(
+        self, beneficiary_id: str, *, limit: int = MAX_PER_PAGE, cursor: str | None = None
+    ) -> Page[Any]:
+        """GET /api/beneficiaries/:beneficiary_id/external_accounts"""
+        return self.list_page(
+            self.encode_path("api/beneficiaries", beneficiary_id, "external_accounts"),
+            {},
+            limit=limit,
+            cursor=cursor,
+        )
+
+    def get_external_account(self, beneficiary_id: str, id: str) -> ManzaResponse:
+        """GET /api/beneficiaries/:beneficiary_id/external_accounts/:id"""
+        return self.http_get(
+            self.encode_path("api/beneficiaries", beneficiary_id, "external_accounts", id)
+        )
+
+    def create_external_account(self, beneficiary_id: str, **attributes: Any) -> ManzaResponse:
+        """POST /api/beneficiaries/:beneficiary_id/external_accounts
+
+        Required: account_number. Optional: name, country_code, currency_code,
+        account_type ("bank" only), bank_identifier (required in ZA, rejected in
+        MA, where it is derived from the RIB).
+        """
+        return self.http_post(
+            self.encode_path("api/beneficiaries", beneficiary_id, "external_accounts"),
+            body=attributes,
+        )