tinker-payments 0.3.0__py3-none-any.whl

tinker/__init__.py

@@ -0,0 +1,13 @@
+from . import lifecycle
+from .api import PayoutManager, TransactionManager
+from .client import TinkerClient, TinkerPayments
+from .managed_checkout import ManagedCheckout
+
+__all__ = [
+    "ManagedCheckout",
+    "PayoutManager",
+    "TinkerClient",
+    "TinkerPayments",
+    "TransactionManager",
+    "lifecycle",
+]

tinker/__version__.py

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

tinker/api.py

@@ -0,0 +1,339 @@
+"""API managers for transactions and subscriptions."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, cast
+from urllib.parse import quote, urlencode
+
+from . import endpoints
+from . import lifecycle as lc
+from .auth import AuthenticationManager
+from .configuration import Configuration
+from .exceptions import ApiError, NetworkError
+from .lifecycle_helpers import idempotency_headers, payment_path, positive_amount
+from .managed_checkout import ManagedCheckout
+from .models import ApiMeta, Transaction
+
+requests: Any
+try:
+    import requests
+except ModuleNotFoundError:  # pragma: no cover
+    requests = None
+
+
+class BaseManager:
+    def __init__(
+        self,
+        config: Configuration,
+        auth_manager: AuthenticationManager,
+        session: Any | None = None,
+    ) -> None:
+        self._config = config
+        self._auth_manager = auth_manager
+        if session is not None:
+            self._session = session
+        elif requests is not None:
+            self._session = requests.Session()
+        else:
+            raise NetworkError(
+                "requests is required unless a custom session is provided"
+            )
+        self._last_meta: ApiMeta | None = None
+
+    def get_last_meta(self) -> ApiMeta | None:
+        return self._last_meta
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        base_url = self._config.base_url.rstrip("/")
+        url = f"{base_url}/{endpoint.lstrip('/')}"
+        token = self._auth_manager.get_token()
+
+        try:
+            response = self._session.request(
+                method=method,
+                url=url,
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                    **(headers or {}),
+                },
+                json=data if data else None,
+                timeout=30,
+            )
+            try:
+                result = response.json() if response.text else {}
+            except ValueError:
+                if response.status_code < 400:
+                    raise
+                result = {}
+
+            if response.status_code >= 400:
+                raise self._api_error(response, result)
+
+            if isinstance(result, dict) and "success" in result:
+                self._last_meta = ApiMeta.from_dict(
+                    result.get("meta") if isinstance(result.get("meta"), dict) else {}
+                )
+
+                if result.get("success") is False:
+                    raise self._api_error(response, result)
+
+                payload = result.get("data")
+                if isinstance(payload, (dict, list)):
+                    return payload
+                return {"value": payload}
+
+            return result if isinstance(result, (dict, list)) else {}
+        except ApiError:
+            raise
+        except Exception as exc:
+            raise NetworkError(f"Failed to communicate with Tinker API: {exc}") from exc
+
+    def _api_error(self, response: Any, result: Any) -> ApiError:
+        return ApiError(
+            self._extract_error_message(result),
+            http_status=response.status_code,
+            details=result,
+            headers=getattr(response, "headers", {}),
+        )
+
+    @staticmethod
+    def _extract_error_message(result: Any) -> str:
+        if isinstance(result, dict):
+            if isinstance(result.get("error"), dict):
+                error = result["error"]
+                return str(error.get("message") or error.get("code") or "Unknown error")
+            if "message" in result:
+                return str(result["message"])
+
+        return "Unknown error"
+
+
+class TransactionManager(BaseManager):
+    def initiate(self, payload: dict[str, Any]) -> Transaction:
+        response = self._request("POST", endpoints.PAYMENT_INITIATE_PATH, payload)
+        if not isinstance(response, dict):
+            response = {"value": response}
+        return Transaction.from_dict(response)
+
+    def query(self, payload: dict[str, Any]) -> Transaction:
+        response = self._request("POST", endpoints.PAYMENT_QUERY_PATH, payload)
+        if not isinstance(response, dict):
+            response = {"value": response}
+        return Transaction.from_dict(response)
+
+    def refund(
+        self, payment_id: str, payload: lc.RefundRequest, key: str
+    ) -> lc.RefundResult:
+        if "amount" in payload:
+            positive_amount(payload["amount"])
+        return cast(
+            lc.RefundResult,
+            self._request(
+                "POST",
+                payment_path(payment_id) + "/refund",
+                dict(payload),
+                idempotency_headers(key),
+            ),
+        )
+
+    def refunds(self, payment_id: str) -> lc.RefundHistory:
+        return cast(
+            lc.RefundHistory,
+            self._request("GET", payment_path(payment_id) + "/refunds"),
+        )
+
+    def get_refund(self, payment_id: str, refund_id: str) -> lc.Refund:
+        return cast(
+            lc.Refund,
+            self._request(
+                "GET",
+                payment_path(payment_id) + "/refunds/" + quote(refund_id, safe=""),
+            ),
+        )
+
+    def cancel_checkout(
+        self, payment_id: str, payload: lc.CancellationRequest, key: str
+    ) -> lc.CancellationResult:
+        return cast(
+            lc.CancellationResult,
+            self._request(
+                "POST",
+                payment_path(payment_id) + "/cancellations",
+                dict(payload),
+                idempotency_headers(key),
+            ),
+        )
+
+    def cancellations(self, payment_id: str) -> lc.CancellationHistory:
+        return cast(
+            lc.CancellationHistory,
+            self._request("GET", payment_path(payment_id) + "/cancellations"),
+        )
+
+    def get_cancellation(self, payment_id: str, request_id: str) -> lc.Cancellation:
+        return cast(
+            lc.Cancellation,
+            self._request(
+                "GET",
+                payment_path(payment_id)
+                + "/cancellations/"
+                + quote(request_id, safe=""),
+            ),
+        )
+
+
+class PayoutManager(BaseManager):
+    """Merchant wallet withdrawals to the merchant's verified destinations."""
+
+    def methods(self) -> list[lc.PayoutMethod]:
+        return cast(
+            list[lc.PayoutMethod], self._request("GET", "merchant/payout-methods")
+        )
+
+    def quote(self, payload: lc.PayoutQuoteRequest) -> lc.PayoutQuote:
+        positive_amount(payload["amount"])
+        return cast(
+            lc.PayoutQuote,
+            self._request("GET", "merchant/payouts/quote?" + urlencode(payload)),
+        )
+
+    def request_payout(self, payload: lc.PayoutRequest, key: str) -> lc.PayoutResult:
+        positive_amount(payload["amount"])
+        if (
+            not math.isfinite(payload["expected_fee_amount"])
+            or payload["expected_fee_amount"] < 0
+        ):
+            raise ValueError("expected_fee_amount must be finite and non-negative")
+        return cast(
+            lc.PayoutResult,
+            self._request(
+                "POST", "merchant/payouts", dict(payload), idempotency_headers(key)
+            ),
+        )
+
+    def list(self, filters: lc.PayoutFilters | None = None) -> lc.PayoutPage:
+        query = "?" + urlencode(filters) if filters else ""
+        return cast(lc.PayoutPage, self._request("GET", "merchant/payouts" + query))
+
+    def get(self, payout_id: str) -> lc.Payout:
+        return cast(
+            lc.Payout,
+            self._request("GET", "merchant/payouts/" + quote(payout_id, safe="")),
+        )
+
+
+class SubscriptionManager(BaseManager):
+    def create_plan(self, payload: dict[str, Any]) -> dict[str, Any]:
+        response = self._request("POST", endpoints.SUBSCRIPTION_PLANS_PATH, payload)
+        return response if isinstance(response, dict) else {"value": response}
+
+    def list_plans(self) -> list[dict[str, Any]]:
+        response = self._request("GET", endpoints.SUBSCRIPTION_PLANS_PATH)
+        return response if isinstance(response, list) else []
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        response = self._request("POST", endpoints.SUBSCRIPTION_BASE_PATH, payload)
+        return response if isinstance(response, dict) else {"value": response}
+
+    def list(
+        self,
+        plan_id: str | None = None,
+        external_customer_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params = []
+        if plan_id and plan_id.strip():
+            params.append(f"plan_id={plan_id}")
+        if external_customer_id and external_customer_id.strip():
+            params.append(f"external_customer_id={external_customer_id}")
+
+        endpoint = endpoints.SUBSCRIPTION_BASE_PATH
+        if params:
+            endpoint = f"{endpoint}?{'&'.join(params)}"
+
+        response = self._request("GET", endpoint)
+        return response if isinstance(response, list) else []
+
+    def cancel(self, subscription_id: str) -> dict[str, Any]:
+        endpoint = f"{endpoints.SUBSCRIPTION_BASE_PATH}/{subscription_id}/cancel"
+        response = self._request("POST", endpoint)
+        return response if isinstance(response, dict) else {"value": response}
+
+    def checkout(self, request: ManagedCheckout) -> dict[str, Any]:
+        return self._request("POST", "merchant/billing/checkout", request.to_dict())
+
+    def billing_resource(self, resource_id: str) -> dict[str, Any]:
+        return self._request("GET", self._billing_resource_path(resource_id))
+
+    def change_quantity(
+        self, resource_id: str, quantity: int, key: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            self._billing_resource_path(resource_id) + "/quantity",
+            {"quantity": quantity, "idempotency_key": key},
+        )
+
+    def schedule_quantity(
+        self, resource_id: str, quantity: int, key: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            self._billing_resource_path(resource_id) + "/schedule",
+            {"quantity": quantity, "idempotency_key": key},
+        )
+
+    def clear_scheduled_quantity(self, resource_id: str, key: str) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            self._billing_resource_path(resource_id) + "/unschedule",
+            {"idempotency_key": key},
+        )
+
+    def set_cancel_at_renewal(
+        self, resource_id: str, cancel: bool, key: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            self._billing_resource_path(resource_id) + "/cancel",
+            {"cancel": cancel, "idempotency_key": key},
+        )
+
+    def billing_operation(self, key: str) -> dict[str, Any]:
+        return self._request(
+            "GET", "merchant/billing/operations/" + quote(key, safe="")
+        )
+
+    def payment_method_portal(
+        self, resource_id: str, return_url: str, key: str
+    ) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            self._billing_resource_path(resource_id) + "/payment-method",
+            {"return_url": return_url, "idempotency_key": key},
+        )
+
+    def billing_payment_history(
+        self, resource_id: str, cursor: str = "", snapshot: int = 0
+    ) -> dict[str, Any]:
+        params = {}
+        if cursor:
+            params["starting_after"] = cursor
+        if snapshot > 0:
+            params["snapshot"] = str(snapshot)
+        endpoint = self._billing_resource_path(resource_id) + "/payment-history"
+        if params:
+            endpoint += "?" + urlencode(params)
+        return self._request("GET", endpoint)
+
+    @staticmethod
+    def _billing_resource_path(resource_id: str) -> str:
+        return "merchant/billing/resources/" + quote(resource_id, safe="")

tinker/auth.py

@@ -0,0 +1,107 @@
+"""Authentication manager for token fetching/caching."""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Any
+
+from .configuration import Configuration
+from .exceptions import ApiError, NetworkError
+from .models import ApiMeta
+
+requests: Any
+try:
+    import requests
+except ModuleNotFoundError:  # pragma: no cover
+    requests = None
+
+
+class AuthenticationManager:
+    def __init__(self, config: Configuration, session: Any | None = None) -> None:
+        self._config = config
+        if session is not None:
+            self._session = session
+        elif requests is not None:
+            self._session = requests.Session()
+        else:
+            raise NetworkError(
+                "requests is required unless a custom session is provided"
+            )
+        self._token: str | None = None
+        self._expires_at: int | None = None
+        self._last_meta: ApiMeta | None = None
+
+    def get_token(self) -> str:
+        if self._is_token_valid():
+            return self._token or ""
+        return self._fetch_token()
+
+    def get_last_meta(self) -> ApiMeta | None:
+        return self._last_meta
+
+    def _is_token_valid(self) -> bool:
+        if self._token is None or self._expires_at is None:
+            return False
+        return int(time.time()) < self._expires_at - 60
+
+    def _fetch_token(self) -> str:
+        credentials = base64.b64encode(
+            f"{self._config.api_public_key}:{self._config.api_secret_key}".encode()
+        ).decode("utf-8")
+
+        try:
+            response = self._session.post(
+                self._config.auth_url,
+                data={"credentials": credentials},
+                headers={
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Accept": "application/json",
+                },
+                timeout=30,
+            )
+            result = response.json() if response.text else {}
+            auth_data = self._extract_auth_data(result)
+
+            if response.status_code >= 400:
+                raise ApiError(self._extract_error_message(result))
+
+            token = auth_data.get("token")
+            if not token:
+                raise ApiError("Invalid authentication response: token missing")
+
+            self._token = str(token)
+            expires_in = int(auth_data.get("expires_in", 3600))
+            self._expires_at = int(time.time()) + expires_in
+            return self._token
+        except ApiError:
+            raise
+        except Exception as exc:
+            raise NetworkError(f"Failed to authenticate: {exc}") from exc
+
+    def _extract_auth_data(self, result: Any) -> dict[str, Any]:
+        if isinstance(result, dict) and "success" in result:
+            self._last_meta = ApiMeta.from_dict(
+                result.get("meta") if isinstance(result.get("meta"), dict) else {}
+            )
+
+            if result.get("success") is False:
+                raise ApiError(self._extract_error_message(result))
+
+            data = result.get("data", {})
+            return data if isinstance(data, dict) else {}
+
+        return result if isinstance(result, dict) else {}
+
+    def _extract_error_message(self, result: Any) -> str:
+        if isinstance(result, dict):
+            if isinstance(result.get("error"), dict):
+                error = result["error"]
+                return str(
+                    error.get("message") or error.get("code") or "Authentication failed"
+                )
+
+            if "message" in result:
+                return str(result["message"])
+
+        return "Authentication failed"

tinker/client.py

@@ -0,0 +1,76 @@
+"""Public SDK client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .api import PayoutManager, SubscriptionManager, TransactionManager
+from .auth import AuthenticationManager
+from .configuration import Configuration
+from .models import ApiMeta
+from .webhook import WebhookHandler
+
+try:
+    import requests
+except ModuleNotFoundError:  # pragma: no cover
+    requests = None
+
+
+class TinkerClient:
+    def __init__(
+        self,
+        api_public_key: str,
+        api_secret_key: str,
+        base_url: str | None = None,
+        session: Any | None = None,
+    ) -> None:
+        self._config = Configuration.create(api_public_key, api_secret_key, base_url)
+        if session is not None:
+            self._session = session
+        elif requests is not None:
+            self._session = requests.Session()
+        else:
+            raise RuntimeError(
+                "requests is required unless a custom session is provided"
+            )
+        self._auth_manager = AuthenticationManager(self._config, self._session)
+        self._payouts: PayoutManager | None = None
+        self._transactions: TransactionManager | None = None
+        self._subscriptions: SubscriptionManager | None = None
+        self._webhooks: WebhookHandler | None = None
+
+    @property
+    def config(self) -> Configuration:
+        return self._config
+
+    def transactions(self) -> TransactionManager:
+        if self._transactions is None:
+            self._transactions = TransactionManager(
+                self._config, self._auth_manager, self._session
+            )
+        return self._transactions
+
+    def subscriptions(self) -> SubscriptionManager:
+        if self._subscriptions is None:
+            self._subscriptions = SubscriptionManager(
+                self._config, self._auth_manager, self._session
+            )
+        return self._subscriptions
+
+    def payouts(self) -> PayoutManager:
+        if self._payouts is None:
+            self._payouts = PayoutManager(
+                self._config, self._auth_manager, self._session
+            )
+        return self._payouts
+
+    def webhooks(self) -> WebhookHandler:
+        if self._webhooks is None:
+            self._webhooks = WebhookHandler()
+        return self._webhooks
+
+    def get_last_auth_meta(self) -> ApiMeta | None:
+        return self._auth_manager.get_last_meta()
+
+
+TinkerPayments = TinkerClient

tinker/client.pyi

@@ -0,0 +1,24 @@
+from typing import Any
+
+from .api import PayoutManager, SubscriptionManager, TransactionManager
+from .configuration import Configuration
+from .models import ApiMeta
+from .webhook import WebhookHandler
+
+class TinkerClient:
+    @property
+    def config(self) -> Configuration: ...
+    def __init__(
+        self,
+        api_public_key: str,
+        api_secret_key: str,
+        base_url: str | None = None,
+        session: Any | None = None,
+    ) -> None: ...
+    def transactions(self) -> TransactionManager: ...
+    def subscriptions(self) -> SubscriptionManager: ...
+    def payouts(self) -> PayoutManager: ...
+    def webhooks(self) -> WebhookHandler: ...
+    def get_last_auth_meta(self) -> ApiMeta | None: ...
+
+TinkerPayments = TinkerClient

tinker/configuration.py

@@ -0,0 +1,45 @@
+"""SDK configuration and environment resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import endpoints
+
+
+@dataclass(frozen=True)
+class Configuration:
+    api_public_key: str
+    api_secret_key: str
+    base_url: str
+    auth_url: str
+
+    @classmethod
+    def create(
+        cls,
+        api_public_key: str,
+        api_secret_key: str,
+        base_url: str | None = None,
+    ) -> Configuration:
+        resolved_base_url = base_url
+        if resolved_base_url is None or not resolved_base_url.strip():
+            resolved_base_url = (
+                endpoints.SANDBOX_BASE_URL
+                if api_public_key.startswith("pk_test_")
+                or api_secret_key.startswith("sk_test_")
+                else endpoints.PRODUCTION_BASE_URL
+            )
+
+        resolved_base_url = resolved_base_url.rstrip("/")
+        if not resolved_base_url.endswith(endpoints.API_VERSION_PATH):
+            resolved_base_url = f"{resolved_base_url}{endpoints.API_VERSION_PATH}"
+
+        normalized_base_url = f"{resolved_base_url}/"
+        auth_url = f"{resolved_base_url}{endpoints.AUTH_TOKEN_PATH}"
+
+        return cls(
+            api_public_key=api_public_key,
+            api_secret_key=api_secret_key,
+            base_url=normalized_base_url,
+            auth_url=auth_url,
+        )

tinker/endpoints.py

@@ -0,0 +1,10 @@
+"""API endpoint constants."""
+
+PRODUCTION_BASE_URL = "https://api.tinkerpayments.com"
+SANDBOX_BASE_URL = "https://sandbox-api.tinkerpayments.com"
+API_VERSION_PATH = "/v1"
+AUTH_TOKEN_PATH = "/auth/token"
+PAYMENT_INITIATE_PATH = "/merchant/payment/initiate"
+PAYMENT_QUERY_PATH = "/merchant/payment/query"
+SUBSCRIPTION_BASE_PATH = "/merchant/subscriptions"
+SUBSCRIPTION_PLANS_PATH = "/merchant/subscriptions/plans"

tinker/exceptions.py

@@ -0,0 +1,42 @@
+"""SDK exception types."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class TinkerError(Exception):
+    """Base SDK exception."""
+
+
+class ApiError(TinkerError):
+    """API failure. Only outcome == 'not_applied' confirms no mutation."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        http_status: int | None = None,
+        details: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.http_status = http_status
+        self.details = details
+        error = details.get("error") if isinstance(details, dict) else None
+        error = error if isinstance(error, dict) else {}
+        headers = {str(k).lower(): v for k, v in (headers or {}).items()}
+        self.error_code = error.get("code")
+        self.provider_code = error.get("provider_code")
+        self.request_id = error.get("request_id") or headers.get("x-request-id")
+        self.retry_after = headers.get("retry-after")
+        self.outcome = error.get("outcome")
+
+
+class NetworkError(TinkerError):
+    """Raised when request transport fails."""
+
+
+class InvalidPayloadError(TinkerError):
+    """Raised when payload parsing or shape validation fails."""