perata 0.1.0__py3-none-any.whl

perata/__init__.py

@@ -0,0 +1,52 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+"""Peráta's SDK for Python, generated from Peráta's API contract."""
+
+from ._client import Perata, Transport, urllib_transport
+from ._errors import PerataError
+from ._pagination import Page
+from ._services import CheckoutsService, CustomersService, OrdersService, PaymentMethodsService, PaymentsService, PricesService, ProductsService, RefundsService, SubscriptionsService
+from ._version import API_VERSION, DEFAULT_BASE_URL, VERSION
+from .models import Card, Checkout, Customer, Order, Pagination, Payment, PaymentMethod, PaymentMethodDetached, Price, Product, Refund, Subscription, CheckoutsCreateParams, CustomersCreateParams, PricesCreateParams, ProductsCreateParams, RefundsCreateParams, SubscriptionsCancelParams
+from .webhooks import WEBHOOK_TOLERANCE_SECONDS, WebhookEvent, WebhookVerificationError, verify_webhook
+
+__all__ = [
+    "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "VERSION",
+    "WEBHOOK_TOLERANCE_SECONDS",
+    "Page",
+    "Perata",
+    "PerataError",
+    "Transport",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "urllib_transport",
+    "verify_webhook",
+    "CheckoutsService",
+    "CustomersService",
+    "OrdersService",
+    "PaymentMethodsService",
+    "PaymentsService",
+    "PricesService",
+    "ProductsService",
+    "RefundsService",
+    "SubscriptionsService",
+    "Card",
+    "Checkout",
+    "Customer",
+    "Order",
+    "Pagination",
+    "Payment",
+    "PaymentMethod",
+    "PaymentMethodDetached",
+    "Price",
+    "Product",
+    "Refund",
+    "Subscription",
+    "CheckoutsCreateParams",
+    "CustomersCreateParams",
+    "PricesCreateParams",
+    "ProductsCreateParams",
+    "RefundsCreateParams",
+    "SubscriptionsCancelParams",
+]

perata/_client.py

@@ -0,0 +1,86 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlencode
+
+from ._errors import PerataError
+from ._services import CheckoutsService, CustomersService, OrdersService, PaymentMethodsService, PaymentsService, PricesService, ProductsService, RefundsService, SubscriptionsService
+from ._version import DEFAULT_BASE_URL, VERSION
+
+Transport = Callable[[str, str, dict[str, str], "bytes | None", float], "tuple[int, dict[str, str], bytes]"]
+"""Sends one request: (method, url, headers, body, timeout) -> (status, headers in lower case, body)."""
+
+
+def urllib_transport(method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> tuple[int, dict[str, str], bytes]:
+    """The standard library's HTTP, so the SDK depends on nothing."""
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, {key.lower(): value for key, value in response.headers.items()}, response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, {key.lower(): value for key, value in error.headers.items()}, error.read()
+
+
+class Perata:
+    """Peráta's API with one organization's API key.
+
+    The key says the organization and the environment: ``prk_test_…`` is the
+    test environment, ``prk_live_…`` the live one.
+
+        perata = Perata(os.environ["PERATA_API_KEY"])
+        product = perata.products.create({"name": "Curso"})
+        for product in perata.products.list_iter():
+            ...
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, transport: Transport | None = None) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._transport = transport or urllib_transport
+        self.checkouts = CheckoutsService(self)
+        self.customers = CustomersService(self)
+        self.orders = OrdersService(self)
+        self.payment_methods = PaymentMethodsService(self)
+        self.payments = PaymentsService(self)
+        self.prices = PricesService(self)
+        self.products = ProductsService(self)
+        self.refunds = RefundsService(self)
+        self.subscriptions = SubscriptionsService(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        idempotency_key: str | None = None,
+        api_key: str | None = None,
+    ) -> Any:
+        """Calls the API and answers what it wrapped in ``data``; a refusal raises PerataError."""
+        url = self._base_url + path
+        values = {name: str(value) for name, value in (query or {}).items() if value is not None and value != ""}
+        if values:
+            url += "?" + urlencode(values)
+        headers = {
+            "Authorization": f"Bearer {api_key or self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"perata-python/{VERSION}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        status, response_headers, raw = self._transport(method, url, headers, data, self._timeout)
+        if status >= 300:
+            raise PerataError.from_response(status, response_headers, raw)
+        return json.loads(raw)["data"]

perata/_core.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+from urllib.parse import quote
+
+
+class Requester(Protocol):
+    """What a service calls the API through."""
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        idempotency_key: str | None = None,
+        api_key: str | None = None,
+    ) -> Any: ...
+
+
+def segment(value: str) -> str:
+    """A path parameter, escaped."""
+    return quote(value, safe="")
+

perata/_errors.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+
+class PerataError(Exception):
+    """A request the API refused.
+
+    ``code`` is the API's: invalid_credential, forbidden, not_found,
+    invalid_request, conflict, idempotency_conflict, body_too_large or
+    unavailable. ``fields`` says, for invalid_request, what is wrong with each
+    field. ``retry_after`` is how many seconds to wait on a 429.
+    """
+
+    def __init__(self, status: int, code: str, message: str = "", fields: dict[str, list[str]] | None = None, retry_after: int | None = None) -> None:
+        super().__init__(f"perata: {status} {code}: {message}" if message else f"perata: {status} {code}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.fields = fields or {}
+        self.retry_after = retry_after
+
+    @classmethod
+    def from_response(cls, status: int, headers: Mapping[str, str], body: bytes) -> PerataError:
+        data: dict[str, Any] = {}
+        try:
+            loaded = json.loads(body or b"{}")
+            if isinstance(loaded, dict):
+                data = loaded
+        except ValueError:
+            pass  # A refusal without a JSON body is still a refusal.
+        retry_after = headers.get("retry-after", "")
+        return cls(status, data.get("error", ""), data.get("message", ""), data.get("fields") or {}, int(retry_after) if retry_after.isdigit() else None)

perata/_pagination.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from .models import Pagination
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """One page of a list, and where the list ends."""
+
+    items: list[T]
+    pagination: Pagination
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], item: Callable[[dict[str, Any]], T]) -> Page[T]:
+        return cls(items=[item(each) for each in data.get("items") or []], pagination=Pagination.from_dict(data["pagination"]))
+
+
+def iterate(fetch: Callable[[int], Page[T]], first: int | None = None) -> Iterator[T]:
+    """Walks pages from ``first`` until the last one, as Polar's SDKs do, yielding every item."""
+    page = max(first or 1, 1)
+    while True:
+        result = fetch(page)
+        yield from result.items
+        if page >= result.pagination.max_page:
+            return
+        page += 1

perata/_services.py

@@ -0,0 +1,191 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from . import models
+from ._core import Requester, segment
+from ._pagination import Page, iterate
+
+
+class CheckoutsService:
+    """The API's checkouts."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def create(self, params: models.CheckoutsCreateParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Checkout:
+        """Create a checkout address for one product and price."""
+        data = self._client.request("POST", "/api/v1/checkouts", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Checkout.from_dict(data)
+
+
+class CustomersService:
+    """The API's customers."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def create(self, params: models.CustomersCreateParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Customer:
+        """Create a customer."""
+        data = self._client.request("POST", "/api/v1/customers", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Customer.from_dict(data)
+
+    def get(self, customer: str, *, api_key: str | None = None) -> models.Customer:
+        """Read a customer."""
+        data = self._client.request("GET", f"/api/v1/customers/{segment(customer)}", api_key=api_key)
+        return models.Customer.from_dict(data)
+
+    def list(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Page[models.Customer]:
+        """List customers. One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/customers", query={"page": page, "limit": limit}, api_key=api_key)
+        return Page.from_dict(data, models.Customer.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Iterator[models.Customer]:
+        """Walks every page of customers:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, api_key=api_key), page)
+
+
+class OrdersService:
+    """The API's orders."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def list(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Page[models.Order]:
+        """List orders: paid checkouts. One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/orders", query={"page": page, "limit": limit}, api_key=api_key)
+        return Page.from_dict(data, models.Order.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Iterator[models.Order]:
+        """Walks every page of orders:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, api_key=api_key), page)
+
+
+class PaymentMethodsService:
+    """The API's payment_methods."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def detach(self, payment_method: str, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.PaymentMethodDetached:
+        """Stop charging a stored card; refused while an active subscription charges it."""
+        data = self._client.request("POST", f"/api/v1/payment_methods/{segment(payment_method)}/detach", idempotency_key=idempotency_key, api_key=api_key)
+        return models.PaymentMethodDetached.from_dict(data)
+
+    def list(self, customer: str, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Page[models.PaymentMethod]:
+        """List a customer's stored cards: brand, last four digits and expiry. One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", f"/api/v1/customers/{segment(customer)}/payment_methods", query={"page": page, "limit": limit}, api_key=api_key)
+        return Page.from_dict(data, models.PaymentMethod.from_dict)
+
+    def list_iter(self, customer: str, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Iterator[models.PaymentMethod]:
+        """Walks every page of payment_methods:list, item by item."""
+        return iterate(lambda at: self.list(customer, page=at, limit=limit, api_key=api_key), page)
+
+
+class PaymentsService:
+    """The API's payments."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def get(self, payment: str, *, api_key: str | None = None) -> models.Payment:
+        """Read a payment."""
+        data = self._client.request("GET", f"/api/v1/payments/{segment(payment)}", api_key=api_key)
+        return models.Payment.from_dict(data)
+
+    def list(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Page[models.Payment]:
+        """List payments. One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/payments", query={"page": page, "limit": limit}, api_key=api_key)
+        return Page.from_dict(data, models.Payment.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Iterator[models.Payment]:
+        """Walks every page of payments:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, api_key=api_key), page)
+
+
+class PricesService:
+    """The API's prices."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def create(self, params: models.PricesCreateParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Price:
+        """Create a BRL price, one-time or recurring."""
+        data = self._client.request("POST", "/api/v1/prices", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Price.from_dict(data)
+
+    def list(self, *, page: int | None = None, limit: int | None = None, product_id: str | None = None, api_key: str | None = None) -> Page[models.Price]:
+        """List prices, optionally of one product (product_id). One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/prices", query={"page": page, "limit": limit, "product_id": product_id}, api_key=api_key)
+        return Page.from_dict(data, models.Price.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, product_id: str | None = None, api_key: str | None = None) -> Iterator[models.Price]:
+        """Walks every page of prices:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, product_id=product_id, api_key=api_key), page)
+
+
+class ProductsService:
+    """The API's products."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def create(self, params: models.ProductsCreateParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Product:
+        """Create a product."""
+        data = self._client.request("POST", "/api/v1/products", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Product.from_dict(data)
+
+    def get(self, product: str, *, api_key: str | None = None) -> models.Product:
+        """Read a product."""
+        data = self._client.request("GET", f"/api/v1/products/{segment(product)}", api_key=api_key)
+        return models.Product.from_dict(data)
+
+    def list(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Page[models.Product]:
+        """List products. One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/products", query={"page": page, "limit": limit}, api_key=api_key)
+        return Page.from_dict(data, models.Product.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, api_key: str | None = None) -> Iterator[models.Product]:
+        """Walks every page of products:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, api_key=api_key), page)
+
+
+class RefundsService:
+    """The API's refunds."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def create(self, params: models.RefundsCreateParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Refund:
+        """Refund part or all of a payment."""
+        data = self._client.request("POST", "/api/v1/refunds", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Refund.from_dict(data)
+
+
+class SubscriptionsService:
+    """The API's subscriptions."""
+
+    def __init__(self, client: Requester) -> None:
+        self._client = client
+
+    def cancel(self, subscription: str, params: models.SubscriptionsCancelParams, *, idempotency_key: str | None = None, api_key: str | None = None) -> models.Subscription:
+        """Cancel a subscription, by default at the end of its period."""
+        data = self._client.request("POST", f"/api/v1/subscriptions/{segment(subscription)}/cancel", body=params, idempotency_key=idempotency_key, api_key=api_key)
+        return models.Subscription.from_dict(data)
+
+    def get(self, subscription: str, *, api_key: str | None = None) -> models.Subscription:
+        """Read a subscription."""
+        data = self._client.request("GET", f"/api/v1/subscriptions/{segment(subscription)}", api_key=api_key)
+        return models.Subscription.from_dict(data)
+
+    def list(self, *, page: int | None = None, limit: int | None = None, customer_id: str | None = None, api_key: str | None = None) -> Page[models.Subscription]:
+        """List subscriptions, optionally of one customer (customer_id). One page; ``list_iter`` walks every page."""
+        data = self._client.request("GET", "/api/v1/subscriptions", query={"page": page, "limit": limit, "customer_id": customer_id}, api_key=api_key)
+        return Page.from_dict(data, models.Subscription.from_dict)
+
+    def list_iter(self, *, page: int | None = None, limit: int | None = None, customer_id: str | None = None, api_key: str | None = None) -> Iterator[models.Subscription]:
+        """Walks every page of subscriptions:list, item by item."""
+        return iterate(lambda at: self.list(page=at, limit=limit, customer_id=customer_id, api_key=api_key), page)
+

perata/_version.py

@@ -0,0 +1,10 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+
+VERSION = "0.1.0"
+"""This SDK's version."""
+
+API_VERSION = "0.1.0"
+"""The contract this SDK was generated from."""
+
+DEFAULT_BASE_URL = "https://perata.sh"
+"""Peráta's API. The environment, test or live, is the API key's: prk_test_… or prk_live_…."""

perata/models.py

@@ -0,0 +1,329 @@
+# Code generated by sdk/generator. DO NOT EDIT.
+"""The resources Peráta's API answers and the bodies its writes take."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+@dataclass(frozen=True)
+class Card:
+    """Card is a resource of Peráta's API."""
+
+    brand: str
+    exp_month: int | None
+    exp_year: int | None
+    last4: str | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Card:
+        return cls(
+            brand=data["brand"],
+            exp_month=data.get("exp_month"),
+            exp_year=data.get("exp_year"),
+            last4=data.get("last4"),
+        )
+
+
+@dataclass(frozen=True)
+class Checkout:
+    """Checkout is a resource of Peráta's API."""
+
+    id: str
+    price_id: str
+    product_id: str
+    url: str
+    """Endereço para onde o comprador é enviado."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Checkout:
+        return cls(
+            id=data["id"],
+            price_id=data["price_id"],
+            product_id=data["product_id"],
+            url=data["url"],
+        )
+
+
+@dataclass(frozen=True)
+class Customer:
+    """Customer is a resource of Peráta's API."""
+
+    created_at: str
+    email: str
+    external_id: str
+    id: str
+    name: str
+    status: Literal["active", "archived"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Customer:
+        return cls(
+            created_at=data["created_at"],
+            email=data["email"],
+            external_id=data["external_id"],
+            id=data["id"],
+            name=data["name"],
+            status=data["status"],
+        )
+
+
+@dataclass(frozen=True)
+class Order:
+    """Order is a resource of Peráta's API."""
+
+    amount_cents: int
+    currency: Literal["BRL"]
+    customer_id: str
+    id: str
+    paid_at: str | None
+    price_id: str
+    product_id: str
+    status: Literal["open", "confirmed", "succeeded", "failed", "expired"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Order:
+        return cls(
+            amount_cents=data["amount_cents"],
+            currency=data["currency"],
+            customer_id=data["customer_id"],
+            id=data["id"],
+            paid_at=data.get("paid_at"),
+            price_id=data["price_id"],
+            product_id=data["product_id"],
+            status=data["status"],
+        )
+
+
+@dataclass(frozen=True)
+class Pagination:
+    """Pagination is a resource of Peráta's API."""
+
+    max_page: int
+    total_count: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Pagination:
+        return cls(
+            max_page=data["max_page"],
+            total_count=data["total_count"],
+        )
+
+
+@dataclass(frozen=True)
+class Payment:
+    """Payment is a resource of Peráta's API."""
+
+    amount_cents: int
+    captured_cents: int
+    checkout_id: str
+    created_at: str
+    currency: Literal["BRL"]
+    customer_id: str
+    id: str
+    method: Literal["card", "pix", "boleto"]
+    refunded_cents: int
+    state: Literal["unknown", "pending", "authorized", "captured", "refused", "canceled", "refunded", "partially_refunded"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Payment:
+        return cls(
+            amount_cents=data["amount_cents"],
+            captured_cents=data["captured_cents"],
+            checkout_id=data["checkout_id"],
+            created_at=data["created_at"],
+            currency=data["currency"],
+            customer_id=data["customer_id"],
+            id=data["id"],
+            method=data["method"],
+            refunded_cents=data["refunded_cents"],
+            state=data["state"],
+        )
+
+
+@dataclass(frozen=True)
+class PaymentMethod:
+    """PaymentMethod is a resource of Peráta's API."""
+
+    card: Card
+    created_at: str
+    customer_id: str
+    id: str
+    type: Literal["card"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PaymentMethod:
+        return cls(
+            card=Card.from_dict(data["card"]),
+            created_at=data["created_at"],
+            customer_id=data["customer_id"],
+            id=data["id"],
+            type=data["type"],
+        )
+
+
+@dataclass(frozen=True)
+class PaymentMethodDetached:
+    """PaymentMethodDetached is a resource of Peráta's API."""
+
+    detached: bool
+    id: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PaymentMethodDetached:
+        return cls(
+            detached=data["detached"],
+            id=data["id"],
+        )
+
+
+@dataclass(frozen=True)
+class Price:
+    """Price is a resource of Peráta's API."""
+
+    amount_cents: int
+    """Valor em centavos."""
+    currency: Literal["BRL"]
+    id: str
+    interval: Literal["none", "month", "year"]
+    product_id: str
+    status: Literal["active", "archived"]
+    type: Literal["one_time", "recurring"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Price:
+        return cls(
+            amount_cents=data["amount_cents"],
+            currency=data["currency"],
+            id=data["id"],
+            interval=data["interval"],
+            product_id=data["product_id"],
+            status=data["status"],
+            type=data["type"],
+        )
+
+
+@dataclass(frozen=True)
+class Product:
+    """Product is a resource of Peráta's API."""
+
+    created_at: str
+    description: str
+    id: str
+    name: str
+    status: Literal["active", "archived"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Product:
+        return cls(
+            created_at=data["created_at"],
+            description=data["description"],
+            id=data["id"],
+            name=data["name"],
+            status=data["status"],
+        )
+
+
+@dataclass(frozen=True)
+class Refund:
+    """Refund is a resource of Peráta's API."""
+
+    amount_cents: int
+    id: str
+    payment_id: str
+    status: Literal["requested", "pending", "unknown", "succeeded", "failed", "canceled"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Refund:
+        return cls(
+            amount_cents=data["amount_cents"],
+            id=data["id"],
+            payment_id=data["payment_id"],
+            status=data["status"],
+        )
+
+
+@dataclass(frozen=True)
+class Subscription:
+    """Subscription is a resource of Peráta's API."""
+
+    amount_cents: int
+    cancel_at_period_end: bool
+    currency: Literal["BRL"]
+    current_period_end: str
+    current_period_start: str
+    customer_id: str
+    id: str
+    interval: str
+    price_id: str
+    product_id: str
+    status: Literal["trialing", "active", "past_due", "paused", "canceled"]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Subscription:
+        return cls(
+            amount_cents=data["amount_cents"],
+            cancel_at_period_end=data["cancel_at_period_end"],
+            currency=data["currency"],
+            current_period_end=data["current_period_end"],
+            current_period_start=data["current_period_start"],
+            customer_id=data["customer_id"],
+            id=data["id"],
+            interval=data["interval"],
+            price_id=data["price_id"],
+            product_id=data["product_id"],
+            status=data["status"],
+        )
+
+
+class CheckoutsCreateParams(TypedDict):
+    """The body of checkouts:create."""
+
+    cancel_url: NotRequired[str]
+    label: NotRequired[str]
+    price_id: str
+    product_id: str
+    quantity: NotRequired[int]
+    success_url: NotRequired[str]
+
+
+class CustomersCreateParams(TypedDict):
+    """The body of customers:create."""
+
+    email: str
+    external_id: NotRequired[str]
+    name: str
+
+
+class PricesCreateParams(TypedDict):
+    """The body of prices:create."""
+
+    amount_cents: int
+    interval: NotRequired[Literal["month", "year"]]
+    product_id: str
+    type: Literal["one_time", "recurring"]
+
+
+class ProductsCreateParams(TypedDict):
+    """The body of products:create."""
+
+    description: NotRequired[str]
+    name: str
+
+
+class RefundsCreateParams(TypedDict):
+    """The body of refunds:create."""
+
+    amount_cents: int
+    note: NotRequired[str]
+    payment_id: str
+    reason: Literal["requested_by_customer", "duplicate", "fraudulent", "product_unavailable", "service_disruption", "other"]
+
+
+class SubscriptionsCancelParams(TypedDict):
+    """The body of subscriptions:cancel."""
+
+    at_period_end: NotRequired[bool]
+    reason: NotRequired[str]
+

perata/webhooks.py

@@ -0,0 +1,74 @@
+"""Verifying the webhooks Peráta sends, as Standard Webhooks signs them."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+WEBHOOK_TOLERANCE_SECONDS = 300
+"""How far from now a webhook's timestamp may be."""
+
+
+class WebhookVerificationError(Exception):
+    """A request Peráta did not sign, or signed too long ago."""
+
+    def __init__(self, message: str = "perata: webhook signature does not verify") -> None:
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class WebhookEvent:
+    """What Peráta posts to an endpoint."""
+
+    id: str
+    type: str
+    timestamp: str
+    data: dict[str, str]
+
+
+def _header(headers: Mapping[str, str], name: str) -> str:
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return ""
+
+
+def verify_webhook(secret: str, headers: Mapping[str, str], body: bytes | str, now: float | None = None) -> WebhookEvent:
+    """Checks a webhook Peráta sent and answers its event.
+
+    The signature is an HMAC-SHA256 of ``{webhook-id}.{webhook-timestamp}.{body}``
+    under the key the endpoint's ``whsec_`` secret encodes. Pass the body
+    exactly as it arrived, before parsing it.
+    """
+    try:
+        key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
+    except (binascii.Error, ValueError):
+        key = b""
+    if not key:
+        raise ValueError("perata: the webhook secret is whsec_ and a base64 key")
+    raw = body.encode() if isinstance(body, str) else body
+    webhook_id = _header(headers, "webhook-id")
+    stamp = _header(headers, "webhook-timestamp")
+    if not webhook_id or not stamp.isdigit():
+        raise WebhookVerificationError()
+    if abs((time.time() if now is None else now) - int(stamp)) > WEBHOOK_TOLERANCE_SECONDS:
+        raise WebhookVerificationError()
+    expected = hmac.new(key, f"{webhook_id}.{stamp}.".encode() + raw, hashlib.sha256).digest()
+    for signature in _header(headers, "webhook-signature").split():
+        version, _, encoded = signature.partition(",")
+        if version != "v1":
+            continue
+        try:
+            decoded = base64.b64decode(encoded, validate=True)
+        except (binascii.Error, ValueError):
+            continue
+        if hmac.compare_digest(decoded, expected):
+            event = json.loads(raw)
+            return WebhookEvent(id=event["id"], type=event["type"], timestamp=event["timestamp"], data=event.get("data") or {})
+    raise WebhookVerificationError()

perata-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: perata
+Version: 0.1.0
+Summary: Peráta's SDK for Python: products, customers, checkouts, payments, subscriptions and webhooks.
+Project-URL: Homepage, https://perata.sh
+Project-URL: Repository, https://github.com/perata-sh/sdk
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Peráta SDK para Python
+
+SDK oficial da API da Peráta para Python 3.11+, sem dependências. É gerado a partir do contrato da API (`openapi.json`, na raiz de [perata-sh/sdk](https://github.com/perata-sh/sdk)) por `generator/`. Não edite os arquivos desta pasta: regenere.
+
+```sh
+pip install perata
+```
+
+```python
+import os
+from perata import Perata
+
+perata = Perata(os.environ["PERATA_API_KEY"])  # prk_test_… ou prk_live_…
+
+product = perata.products.create({"name": "Curso"}, idempotency_key="produto-curso")
+
+for product in perata.products.list_iter():
+    print(product.name)
+```
+
+## Recursos
+
+| Serviço | Métodos |
+|---|---|
+| `perata.checkouts` | `create` |
+| `perata.customers` | `create`, `get`, `list`, `list_iter` |
+| `perata.orders` | `list`, `list_iter` |
+| `perata.payment_methods` | `detach`, `list`, `list_iter` |
+| `perata.payments` | `get`, `list`, `list_iter` |
+| `perata.prices` | `create`, `list`, `list_iter` |
+| `perata.products` | `create`, `get`, `list`, `list_iter` |
+| `perata.refunds` | `create` |
+| `perata.subscriptions` | `cancel`, `get`, `list`, `list_iter` |
+
+As escritas aceitam `idempotency_key=`, e todas aceitam `api_key=` para usar a chave de outra organização numa chamada.
+
+## Erros
+
+Uma recusa da API levanta `PerataError`, com `status`, `code` (`invalid_request`, `not_found`…), `fields` (o problema de cada campo) e, num 429, `retry_after` em segundos.
+
+## Webhooks
+
+```python
+from perata import verify_webhook
+
+event = verify_webhook(os.environ["PERATA_WEBHOOK_SECRET"], request.headers, request.get_data())
+```
+
+A assinatura é a do Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), com tolerância de 5 minutos. Passe o corpo cru, antes de interpretar.
+
+Versão do SDK: 0.1.0 · contrato da API: 0.1.0

perata-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+perata/__init__.py,sha256=0pulwotQuTc1Bc2kF3Sc9xpFBb5M0vTpzsZ9DsYgP70,1728
+perata/_client.py,sha256=HuQ5AuUXTCypRc4pwaWYS4GvJXoCx2egtSsY6EznUiI,3722
+perata/_core.py,sha256=fuZvnIK1XorCy-8XoRt7A5yUThXEFnIjcJNTUDaZ4qY,534
+perata/_errors.py,sha256=tUdEZv6dTzwxyTtenYnEMKVyi63V9kPbEls0p36VqE0,1468
+perata/_pagination.py,sha256=TDpNR2eLKDlWGVe8z1MwfsS4XNZEWNpSnwQf03qjKno,978
+perata/_services.py,sha256=_YHBKIBRU-ViH6p_M0Hdt9XAF-h2XPqPMaqZ_AVad0I,10442
+perata/_version.py,sha256=5trLUXAo5BHfa6Ok37Mvn8fmSfS9jlirY0FgLc4rIBY,304
+perata/models.py,sha256=963zxtFgY-hcF6HE-9313eVYwfs9bsOSZGstUYP_yMU,8383
+perata/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+perata/webhooks.py,sha256=mbXSaLrAXhbOa8WqyIkf4g9hisr1YjZaXBn2FlCA-Lk,2599
+perata-0.1.0.dist-info/METADATA,sha256=ZOixpUkGOCXSMbdyyba2PjhTc1iXxOzbmc7qK3jrcT8,2205
+perata-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+perata-0.1.0.dist-info/RECORD,,

perata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any