benvo 1.0.0__py3-none-any.whl

benvo/__init__.py

@@ -0,0 +1,43 @@
+from . import webhooks
+from ._client import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, Benvo, response_of
+from ._endpoints import ENDPOINTS, Endpoint
+from ._pagination import ListIterator
+from ._transport import BenvoObject
+from ._version import __version__
+from .errors import (
+    BenvoApiError,
+    BenvoAuthenticationError,
+    BenvoConnectionError,
+    BenvoError,
+    BenvoInvalidRequestError,
+    BenvoNotFoundError,
+    BenvoPermissionError,
+    BenvoRateLimitError,
+    BenvoWebhookVerificationError,
+)
+from .signing import SIGNATURE_HEADER, sign_request
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT",
+    "ENDPOINTS",
+    "SIGNATURE_HEADER",
+    "Benvo",
+    "BenvoApiError",
+    "BenvoAuthenticationError",
+    "BenvoConnectionError",
+    "BenvoError",
+    "BenvoInvalidRequestError",
+    "BenvoNotFoundError",
+    "BenvoObject",
+    "BenvoPermissionError",
+    "BenvoRateLimitError",
+    "BenvoWebhookVerificationError",
+    "Endpoint",
+    "ListIterator",
+    "__version__",
+    "response_of",
+    "sign_request",
+    "webhooks",
+]

benvo/_client.py

@@ -0,0 +1,80 @@
+import re
+from typing import Any, Dict, Mapping, Optional
+
+from ._resources import (
+    AvailabilityResource,
+    Events,
+    Invoices,
+    Leads,
+    Members,
+    MembershipTiers,
+    Menus,
+    Meta,
+    Orders,
+    Payments,
+    People,
+    Products,
+    Reservations,
+    Rsvps,
+)
+from ._transport import Transport, default_user_agent
+from ._version import __version__
+from .types import Ping
+
+DEFAULT_BASE_URL = "https://api.benvo.io"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+class Benvo:
+    VERSION = __version__
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        signing_secret: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("A Benvo API key is required")
+        base = base_url.rstrip("/")
+        if not re.match(r"^https?://", base):
+            raise ValueError("base_url must start with https:// or http://")
+        self.base_url = base
+        self.livemode = not api_key.startswith("bvk_test_")
+        self._transport = Transport(
+            api_key=api_key,
+            base_url=base,
+            timeout=timeout,
+            max_retries=max_retries,
+            signing_secret=signing_secret,
+            user_agent=user_agent or default_user_agent(),
+        )
+        self.people = People(self._transport)
+        self.members = Members(self._transport)
+        self.membership_tiers = MembershipTiers(self._transport)
+        self.leads = Leads(self._transport)
+        self.reservations = Reservations(self._transport)
+        self.availability = AvailabilityResource(self._transport)
+        self.events = Events(self._transport)
+        self.rsvps = Rsvps(self._transport)
+        self.orders = Orders(self._transport)
+        self.invoices = Invoices(self._transport)
+        self.payments = Payments(self._transport)
+        self.menus = Menus(self._transport)
+        self.products = Products(self._transport)
+        self.meta = Meta(self._transport)
+
+    def ping(self, *, request_options: Optional[Mapping[str, Any]] = None) -> Ping:
+        return self._transport.call("ping", **dict(request_options or {}))
+
+    def __repr__(self) -> str:
+        return f"Benvo(base_url={self.base_url!r}, livemode={self.livemode!r})"
+
+
+def response_of(obj: Any) -> Optional[Dict[str, Any]]:
+    return getattr(obj, "last_response", None)

benvo/_endpoints.py

@@ -0,0 +1,59 @@
+import re
+from typing import Dict, NamedTuple, Optional
+from urllib.parse import quote
+
+
+class Endpoint(NamedTuple):
+    method: str
+    path: str
+    sdk: str
+    auth: bool = True
+
+
+ENDPOINTS: Dict[str, Endpoint] = {
+    "ping": Endpoint("GET", "/v1/ping", "ping"),
+    "ipRanges": Endpoint("GET", "/v1/meta/ip-ranges", "meta.ip_ranges", auth=False),
+    "listPeople": Endpoint("GET", "/v1/people", "people.list"),
+    "getPerson": Endpoint("GET", "/v1/people/{id}", "people.retrieve"),
+    "createPerson": Endpoint("POST", "/v1/people", "people.create"),
+    "updatePerson": Endpoint("PATCH", "/v1/people/{id}", "people.update"),
+    "listMembers": Endpoint("GET", "/v1/members", "members.list"),
+    "getMember": Endpoint("GET", "/v1/members/{id}", "members.retrieve"),
+    "listMembershipTiers": Endpoint("GET", "/v1/membership-tiers", "membership_tiers.list"),
+    "listLeads": Endpoint("GET", "/v1/leads", "leads.list"),
+    "createLead": Endpoint("POST", "/v1/leads", "leads.create"),
+    "listReservations": Endpoint("GET", "/v1/reservations", "reservations.list"),
+    "getReservation": Endpoint("GET", "/v1/reservations/{id}", "reservations.retrieve"),
+    "createReservation": Endpoint("POST", "/v1/reservations", "reservations.create"),
+    "updateReservation": Endpoint("PATCH", "/v1/reservations/{id}", "reservations.update"),
+    "cancelReservation": Endpoint("POST", "/v1/reservations/{id}/cancel", "reservations.cancel"),
+    "getAvailability": Endpoint("GET", "/v1/availability", "availability.check"),
+    "listEvents": Endpoint("GET", "/v1/events", "events.list"),
+    "getEvent": Endpoint("GET", "/v1/events/{id}", "events.retrieve"),
+    "listEventRsvps": Endpoint("GET", "/v1/events/{id}/rsvps", "rsvps.list"),
+    "createEventRsvp": Endpoint("POST", "/v1/events/{id}/rsvps", "rsvps.create"),
+    "updateEventRsvp": Endpoint("PATCH", "/v1/events/{id}/rsvps/{rsvp_id}", "rsvps.update"),
+    "listOrders": Endpoint("GET", "/v1/orders", "orders.list"),
+    "getOrder": Endpoint("GET", "/v1/orders/{id}", "orders.retrieve"),
+    "listInvoices": Endpoint("GET", "/v1/invoices", "invoices.list"),
+    "getInvoice": Endpoint("GET", "/v1/invoices/{id}", "invoices.retrieve"),
+    "listPayments": Endpoint("GET", "/v1/payments", "payments.list"),
+    "getPayment": Endpoint("GET", "/v1/payments/{id}", "payments.retrieve"),
+    "listMenus": Endpoint("GET", "/v1/menus", "menus.list"),
+    "getMenu": Endpoint("GET", "/v1/menus/{id}", "menus.retrieve"),
+    "listProducts": Endpoint("GET", "/v1/products", "products.list"),
+}
+
+_PARAM = re.compile(r"\{([a-z_]+)\}")
+
+
+def expand_path(template: str, params: Optional[Dict[str, str]] = None) -> str:
+    values = params or {}
+
+    def replace(match: "re.Match[str]") -> str:
+        value = values.get(match.group(1))
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"Missing path parameter {match.group(1)}")
+        return quote(value, safe="")
+
+    return _PARAM.sub(replace, template)

benvo/_pagination.py

@@ -0,0 +1,39 @@
+from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+PageFetcher = Callable[[Optional[str]], Dict[str, Any]]
+
+
+class ListIterator(Generic[T]):
+    def __init__(self, fetch_page: PageFetcher, starting_after: Optional[str] = None) -> None:
+        self._fetch = fetch_page
+        self._start = starting_after
+
+    def page(self) -> Dict[str, Any]:
+        return self._fetch(self._start)
+
+    def pages(self) -> Iterator[Dict[str, Any]]:
+        cursor = self._start
+        while True:
+            page = self._fetch(cursor)
+            yield page
+            next_cursor = page.get("next_cursor")
+            if not page.get("has_more") or not next_cursor or next_cursor == cursor:
+                return
+            cursor = next_cursor
+
+    def __iter__(self) -> Iterator[T]:
+        for page in self.pages():
+            for item in page.get("data", []):
+                yield item
+
+    def to_list(self, max_items: Optional[int] = None) -> List[T]:
+        out: List[T] = []
+        if max_items is not None and max_items <= 0:
+            return out
+        for item in self:
+            out.append(item)
+            if max_items is not None and len(out) >= max_items:
+                break
+        return out

benvo/_resources.py

@@ -0,0 +1,297 @@
+from typing import Any, Dict, Mapping, Optional, Union
+
+import datetime as _dt
+
+from ._pagination import ListIterator
+from ._transport import Transport
+from .types import (
+    Availability,
+    Event,
+    EventRsvp,
+    Invoice,
+    IpRanges,
+    Lead,
+    LeadCreateParams,
+    Member,
+    MembershipTier,
+    Menu,
+    Order,
+    Payment,
+    Person,
+    PersonCreateParams,
+    PersonUpdateParams,
+    Product,
+    Reservation,
+    ReservationCancelParams,
+    ReservationCreateParams,
+    ReservationUpdateParams,
+    RsvpCreateParams,
+    RsvpUpdateParams,
+)
+
+TimestampInput = Union[str, _dt.datetime]
+DateInput = Union[str, _dt.date]
+
+
+def _merge(params: Optional[Mapping[str, Any]], fields: Mapping[str, Any]) -> Dict[str, Any]:
+    body: Dict[str, Any] = dict(params or {})
+    body.update(fields)
+    return body
+
+
+class _Resource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+
+class People(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Person]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, email=email, phone=phone, **extra)
+        return self._t.list("listPeople", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Person:
+        return self._t.call("getPerson", params={"id": id}, **dict(request_options or {}))
+
+    def create(self, params: Optional[PersonCreateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Person:
+        return self._t.call("createPerson", body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+    def update(self, id: str, params: Optional[PersonUpdateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Person:
+        return self._t.call("updatePerson", params={"id": id}, body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+
+class Members(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        status: Optional[str] = None,
+        tier_id: Optional[str] = None,
+        email: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Member]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, status=status, tier_id=tier_id, email=email, **extra)
+        return self._t.list("listMembers", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Member:
+        return self._t.call("getMember", params={"id": id}, **dict(request_options or {}))
+
+
+class MembershipTiers(_Resource):
+    def list(self, *, request_options: Optional[Mapping[str, Any]] = None) -> ListIterator[MembershipTier]:
+        return self._t.list("listMembershipTiers", {}, **dict(request_options or {}))
+
+
+class Leads(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        status: Optional[str] = None,
+        stage: Optional[str] = None,
+        source: Optional[str] = None,
+        person_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Lead]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, status=status, stage=stage, source=source, person_id=person_id, **extra)
+        return self._t.list("listLeads", query, **dict(request_options or {}))
+
+    def create(self, params: Optional[LeadCreateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Lead:
+        return self._t.call("createLead", body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+
+class Reservations(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        date_from: Optional[DateInput] = None,
+        date_to: Optional[DateInput] = None,
+        status: Optional[str] = None,
+        member_id: Optional[str] = None,
+        person_id: Optional[str] = None,
+        venue_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Reservation]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, date_from=date_from, date_to=date_to, status=status, member_id=member_id, person_id=person_id, venue_id=venue_id, **extra)
+        return self._t.list("listReservations", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Reservation:
+        return self._t.call("getReservation", params={"id": id}, **dict(request_options or {}))
+
+    def create(self, params: Optional[ReservationCreateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Reservation:
+        return self._t.call("createReservation", body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+    def update(self, id: str, params: Optional[ReservationUpdateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Reservation:
+        return self._t.call("updateReservation", params={"id": id}, body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+    def cancel(self, id: str, params: Optional[ReservationCancelParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> Reservation:
+        return self._t.call("cancelReservation", params={"id": id}, body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+
+class AvailabilityResource(_Resource):
+    def check(
+        self,
+        *,
+        date: DateInput,
+        party_size: int,
+        venue_id: Optional[str] = None,
+        area: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> Availability:
+        query = dict(date=date, party_size=party_size, venue_id=venue_id, area=area, **extra)
+        return self._t.call("getAvailability", query=query, **dict(request_options or {}))
+
+
+class Events(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        starts_after: Optional[TimestampInput] = None,
+        starts_before: Optional[TimestampInput] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Event]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, starts_after=starts_after, starts_before=starts_before, **extra)
+        return self._t.list("listEvents", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Event:
+        return self._t.call("getEvent", params={"id": id}, **dict(request_options or {}))
+
+
+class Rsvps(_Resource):
+    def list(self, event_id: str, *, status: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **extra: Any) -> ListIterator[EventRsvp]:
+        return self._t.list("listEventRsvps", dict(status=status, **extra), {"id": event_id}, **dict(request_options or {}))
+
+    def create(self, event_id: str, params: Optional[RsvpCreateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> EventRsvp:
+        return self._t.call("createEventRsvp", params={"id": event_id}, body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+    def update(self, event_id: str, rsvp_id: str, params: Optional[RsvpUpdateParams] = None, *, idempotency_key: Optional[str] = None, request_options: Optional[Mapping[str, Any]] = None, **fields: Any) -> EventRsvp:
+        return self._t.call("updateEventRsvp", params={"id": event_id, "rsvp_id": rsvp_id}, body=_merge(params, fields), idempotency_key=idempotency_key, **dict(request_options or {}))
+
+
+class Orders(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        status: Optional[str] = None,
+        member_id: Optional[str] = None,
+        person_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Order]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, status=status, member_id=member_id, person_id=person_id, **extra)
+        return self._t.list("listOrders", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Order:
+        return self._t.call("getOrder", params={"id": id}, **dict(request_options or {}))
+
+
+class Invoices(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        status: Optional[str] = None,
+        member_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Invoice]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, status=status, member_id=member_id, **extra)
+        return self._t.list("listInvoices", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Invoice:
+        return self._t.call("getInvoice", params={"id": id}, **dict(request_options or {}))
+
+
+class Payments(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        created_since: Optional[TimestampInput] = None,
+        updated_since: Optional[TimestampInput] = None,
+        invoice_id: Optional[str] = None,
+        member_id: Optional[str] = None,
+        status: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Payment]:
+        query = dict(limit=limit, starting_after=starting_after, created_since=created_since, updated_since=updated_since, invoice_id=invoice_id, member_id=member_id, status=status, **extra)
+        return self._t.list("listPayments", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Payment:
+        return self._t.call("getPayment", params={"id": id}, **dict(request_options or {}))
+
+
+class Menus(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        updated_since: Optional[TimestampInput] = None,
+        venue_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Menu]:
+        query = dict(limit=limit, starting_after=starting_after, updated_since=updated_since, venue_id=venue_id, **extra)
+        return self._t.list("listMenus", query, **dict(request_options or {}))
+
+    def retrieve(self, id: str, *, request_options: Optional[Mapping[str, Any]] = None) -> Menu:
+        return self._t.call("getMenu", params={"id": id}, **dict(request_options or {}))
+
+
+class Products(_Resource):
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        updated_since: Optional[TimestampInput] = None,
+        menu_id: Optional[str] = None,
+        request_options: Optional[Mapping[str, Any]] = None,
+        **extra: Any,
+    ) -> ListIterator[Product]:
+        query = dict(limit=limit, starting_after=starting_after, updated_since=updated_since, menu_id=menu_id, **extra)
+        return self._t.list("listProducts", query, **dict(request_options or {}))
+
+
+class Meta(_Resource):
+    def ip_ranges(self, *, request_options: Optional[Mapping[str, Any]] = None) -> IpRanges:
+        return self._t.call("ipRanges", **dict(request_options or {}))