benvo 1.0.0__tar.gz

benvo-1.0.0/LICENSE

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

benvo-1.0.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.1
+Name: benvo
+Version: 1.0.0
+Summary: Official Python library for the Benvo API
+Author: Coviola Group LLC
+Author-email: Coviola Group LLC <support@benvo.io>
+License: MIT
+Project-URL: Homepage, https://developers.benvo.io
+Project-URL: Documentation, https://developers.benvo.io
+Keywords: benvo,api,sdk,hospitality,restaurants,members clubs,reservations,webhooks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Benvo Python library
+
+The official Python library for the [Benvo API](https://developers.benvo.io). Typed resources, automatic pagination, idempotent writes, retries with backoff, webhook verification and request signing, using only the Python standard library.
+
+- Python 3.9 or later, no dependencies
+- Type hints included (`py.typed`)
+- Full reference: [developers.benvo.io](https://developers.benvo.io)
+
+## Install
+
+```bash
+pip install benvo
+```
+
+## Quickstart
+
+```python
+import os
+from benvo import Benvo
+
+client = Benvo(os.environ["BENVO_API_KEY"])
+
+ping = client.ping()
+print(ping["account"]["name"], ping["key"]["scopes"])
+
+person = client.people.create(first_name="Sophie", last_name="Tan", email="sophie.tan@example.com")
+print(person["id"], person.last_response["status"])
+```
+
+Objects come back as dictionaries (typed with `TypedDict`), so `person["id"]` works and they serialise with `json.dumps`. Each one also has `last_response` with `status`, `request_id`, `idempotent_replayed` and `headers`; `benvo.response_of(obj)` reads it with a type hint.
+
+Keep the key on your server. The API refuses requests from browsers.
+
+### Options
+
+```python
+client = Benvo(
+    api_key,
+    base_url="https://api.benvo.io",
+    timeout=30,
+    max_retries=2,
+    signing_secret=os.environ.get("BENVO_SIGNING_SECRET"),
+)
+```
+
+Every method also takes `request_options={"timeout": 5, "max_retries": 0, "headers": {...}}`, and writes take `idempotency_key`.
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.ping()` | Check the key, its account and scopes |
+| `client.people` | `list`, `retrieve`, `create`, `update` |
+| `client.members` | `list`, `retrieve` |
+| `client.membership_tiers` | `list` |
+| `client.leads` | `list`, `create` |
+| `client.reservations` | `list`, `retrieve`, `create`, `update`, `cancel` |
+| `client.availability` | `check` |
+| `client.events` | `list`, `retrieve` |
+| `client.rsvps` | `list(event_id)`, `create(event_id, ...)`, `update(event_id, rsvp_id, ...)` |
+| `client.orders` | `list`, `retrieve` |
+| `client.invoices` | `list`, `retrieve` |
+| `client.payments` | `list`, `retrieve` |
+| `client.menus` | `list`, `retrieve` |
+| `client.products` | `list` |
+| `client.meta` | `ip_ranges` (no key needed) |
+
+Writes take the body as keyword arguments, as a dictionary, or both:
+
+```python
+availability = client.availability.check(date="2026-11-12", party_size=4)
+slot = next((s for s in availability["slots"] if s["available"]), None)
+
+if slot:
+    reservation = client.reservations.create(
+        date=slot["date"],
+        time=slot["time"],
+        party_size=4,
+        guest={"name": "Sophie Tan", "email": "sophie.tan@example.com"},
+    )
+    client.reservations.update(reservation["id"], party_size=5)
+
+client.rsvps.create("evt_8Hk2QmZ4", {"member_id": "mem_3fJ9xL2p", "guests": [{"name": "Rachel Lim"}]})
+```
+
+On `update`, a value of `None` is sent as `null` and clears the field.
+
+Ids are opaque strings with a prefix per object (`per_`, `mem_`, `res_` and so on). Store them as strings and never parse them. Money is always `{"amount": 24860, "currency": "SGD"}` with `amount` in minor units. Every object carries `livemode`.
+
+Contact details and sensitive fields are only present when the key has the matching scope (`people:read_contact`, `people:read_sensitive`, `orders:read_spend`), so read them with `.get()`.
+
+## Pagination
+
+`list()` returns an iterator that fetches the next page with `starting_after` until `has_more` is false.
+
+```python
+for reservation in client.reservations.list(date_from="2026-11-01", date_to="2026-11-30", limit=100):
+    print(reservation["id"], reservation["status"])
+```
+
+One page at a time:
+
+```python
+page = client.people.list(limit=25).page()
+print(len(page["data"]), page["has_more"], page["next_cursor"])
+
+following = client.people.list(limit=25, starting_after=page["next_cursor"]).page()
+```
+
+Also available: `.pages()` and `.to_list(max_items)`. Timestamp filters such as `updated_since` accept a `datetime` (time zone aware values are sent in UTC) or an ISO 8601 string; date filters accept a `date`.
+
+## Idempotency
+
+Every create, update, cancel and RSVP write sends an `Idempotency-Key`. When you do not pass one, the library generates a uuid v4 and keeps the same key across its own retries, so a retried write never runs twice.
+
+Pass your own key to make a write safe across restarts of your process:
+
+```python
+client.leads.create(
+    email="marcus.wong@example.com",
+    message="Dinner for 30 in December",
+    idempotency_key=f"enquiry-{form_submission_id}",
+)
+```
+
+A replayed result has `last_response["idempotent_replayed"] == True`. Reusing a key with a different body fails with `idempotency_key_reused`.
+
+## Errors
+
+Every API error is a `BenvoError` subclass with `status`, `type`, `code`, `param`, `request_id`, `headers` and `raw`.
+
+| Exception | When |
+|---|---|
+| `BenvoAuthenticationError` | 401: missing, invalid, expired or revoked key |
+| `BenvoPermissionError` | 403: missing scope, module not enabled, account inactive, consent required |
+| `BenvoNotFoundError` | 404: no such record in this account |
+| `BenvoInvalidRequestError` | 400, 409, 413, 422: invalid parameters or a conflict such as `slot_unavailable` |
+| `BenvoRateLimitError` | 429 after the retries; `retry_after` holds the seconds to wait |
+| `BenvoApiError` | 5xx after the retries, or a response that is not JSON |
+| `BenvoConnectionError` | The API could not be reached; `timed_out` is true for timeouts |
+
+```python
+from benvo import BenvoInvalidRequestError
+
+try:
+    client.reservations.create(date="2026-11-12", time="19:00", party_size=4, guest={"name": "Sophie Tan", "email": "sophie.tan@example.com"})
+except BenvoInvalidRequestError as error:
+    if error.code != "slot_unavailable":
+        raise
+    print("That time was just taken.")
+```
+
+Quote `request_id` when you contact Benvo support.
+
+## Retries
+
+The library retries up to `max_retries` times (default 2) on:
+
+- 429 rate limits
+- 409 `idempotency_in_progress`
+- 5xx responses
+- network errors and timeouts
+
+It waits for `Retry-After` when the API sends it (up to 60 seconds) and otherwise backs off exponentially from 0.5 seconds up to 8 seconds with jitter. Set `max_retries=0` to turn retries off.
+
+## Webhooks
+
+Benvo signs every webhook with [Standard Webhooks](https://www.standardwebhooks.com) headers. Verify the raw body, before any JSON parsing:
+
+```python
+import os
+from flask import Flask, request
+from benvo import BenvoWebhookVerificationError, webhooks
+
+app = Flask(__name__)
+
+@app.post("/benvo/webhooks")
+def benvo_webhook():
+    try:
+        event = webhooks.verify(request.get_data(), request.headers, os.environ["BENVO_WEBHOOK_SECRET"])
+    except BenvoWebhookVerificationError:
+        return "", 400
+
+    if event["type"] == "reservation.created":
+        print("New booking", event["data"]["object"]["id"])
+    return "", 204
+```
+
+`webhooks.verify(payload, headers, secret, tolerance=300)` checks the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers, refuses timestamps more than `tolerance` seconds away from now, compares signatures in constant time and returns the parsed event. `headers` can be any mapping (header names in any case) or a list of pairs. Store `event["id"]` and skip ids you have already processed.
+
+Endpoints set to thin payloads receive only `id` and `object` in `data.object`; fetch the full object with your key.
+
+For your own tests, `webhooks.sign(body, secret, msg_id, timestamp=None)` returns signed headers.
+
+## Request signing
+
+Keys marked to require signatures must sign every request. Pass the key's signing secret and the library adds the header:
+
+```python
+client = Benvo(api_key, signing_secret=os.environ["BENVO_SIGNING_SECRET"])
+```
+
+```
+Benvo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.METHOD.path.body">
+```
+
+`path` is the path with its query string exactly as sent (for example `/v1/people?limit=25`) and `body` is the exact JSON sent, or empty for GET. A new signature is made for each retry. Requests older than 5 minutes are refused, so keep your server clock in sync. To sign by hand, use `benvo.sign_request(secret, method, path, body, timestamp=None)`.
+
+## Test keys and live keys
+
+| Key | Works on | `livemode` |
+|---|---|---|
+| `bvk_test_...` | Your sandbox account only, with fake data. Nothing reaches real guests | `False` |
+| `bvk_live_...` | The venue account it was issued for, after the venue owner approves it | `True` |
+
+The same code runs against both. `client.livemode` tells you which kind of key the client holds, and every object and webhook event carries `livemode`. Build and test with a test key, then swap in the live key.
+
+## Development
+
+Run from `packages/sdk-python`:
+
+```bash
+python3 -m unittest discover -s tests          # offline test suite
+python3 scripts/build_dist.py                  # dist/benvo-1.0.0.tar.gz and dist/benvo-1.0.0-py3-none-any.whl, standard library only
+python3 -m build                               # the same archives with the official builder, when the build package is installed
+```
+
+## Licence
+
+MIT. Copyright Coviola Group LLC.

benvo-1.0.0/README.md

@@ -0,0 +1,230 @@
+# Benvo Python library
+
+The official Python library for the [Benvo API](https://developers.benvo.io). Typed resources, automatic pagination, idempotent writes, retries with backoff, webhook verification and request signing, using only the Python standard library.
+
+- Python 3.9 or later, no dependencies
+- Type hints included (`py.typed`)
+- Full reference: [developers.benvo.io](https://developers.benvo.io)
+
+## Install
+
+```bash
+pip install benvo
+```
+
+## Quickstart
+
+```python
+import os
+from benvo import Benvo
+
+client = Benvo(os.environ["BENVO_API_KEY"])
+
+ping = client.ping()
+print(ping["account"]["name"], ping["key"]["scopes"])
+
+person = client.people.create(first_name="Sophie", last_name="Tan", email="sophie.tan@example.com")
+print(person["id"], person.last_response["status"])
+```
+
+Objects come back as dictionaries (typed with `TypedDict`), so `person["id"]` works and they serialise with `json.dumps`. Each one also has `last_response` with `status`, `request_id`, `idempotent_replayed` and `headers`; `benvo.response_of(obj)` reads it with a type hint.
+
+Keep the key on your server. The API refuses requests from browsers.
+
+### Options
+
+```python
+client = Benvo(
+    api_key,
+    base_url="https://api.benvo.io",
+    timeout=30,
+    max_retries=2,
+    signing_secret=os.environ.get("BENVO_SIGNING_SECRET"),
+)
+```
+
+Every method also takes `request_options={"timeout": 5, "max_retries": 0, "headers": {...}}`, and writes take `idempotency_key`.
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.ping()` | Check the key, its account and scopes |
+| `client.people` | `list`, `retrieve`, `create`, `update` |
+| `client.members` | `list`, `retrieve` |
+| `client.membership_tiers` | `list` |
+| `client.leads` | `list`, `create` |
+| `client.reservations` | `list`, `retrieve`, `create`, `update`, `cancel` |
+| `client.availability` | `check` |
+| `client.events` | `list`, `retrieve` |
+| `client.rsvps` | `list(event_id)`, `create(event_id, ...)`, `update(event_id, rsvp_id, ...)` |
+| `client.orders` | `list`, `retrieve` |
+| `client.invoices` | `list`, `retrieve` |
+| `client.payments` | `list`, `retrieve` |
+| `client.menus` | `list`, `retrieve` |
+| `client.products` | `list` |
+| `client.meta` | `ip_ranges` (no key needed) |
+
+Writes take the body as keyword arguments, as a dictionary, or both:
+
+```python
+availability = client.availability.check(date="2026-11-12", party_size=4)
+slot = next((s for s in availability["slots"] if s["available"]), None)
+
+if slot:
+    reservation = client.reservations.create(
+        date=slot["date"],
+        time=slot["time"],
+        party_size=4,
+        guest={"name": "Sophie Tan", "email": "sophie.tan@example.com"},
+    )
+    client.reservations.update(reservation["id"], party_size=5)
+
+client.rsvps.create("evt_8Hk2QmZ4", {"member_id": "mem_3fJ9xL2p", "guests": [{"name": "Rachel Lim"}]})
+```
+
+On `update`, a value of `None` is sent as `null` and clears the field.
+
+Ids are opaque strings with a prefix per object (`per_`, `mem_`, `res_` and so on). Store them as strings and never parse them. Money is always `{"amount": 24860, "currency": "SGD"}` with `amount` in minor units. Every object carries `livemode`.
+
+Contact details and sensitive fields are only present when the key has the matching scope (`people:read_contact`, `people:read_sensitive`, `orders:read_spend`), so read them with `.get()`.
+
+## Pagination
+
+`list()` returns an iterator that fetches the next page with `starting_after` until `has_more` is false.
+
+```python
+for reservation in client.reservations.list(date_from="2026-11-01", date_to="2026-11-30", limit=100):
+    print(reservation["id"], reservation["status"])
+```
+
+One page at a time:
+
+```python
+page = client.people.list(limit=25).page()
+print(len(page["data"]), page["has_more"], page["next_cursor"])
+
+following = client.people.list(limit=25, starting_after=page["next_cursor"]).page()
+```
+
+Also available: `.pages()` and `.to_list(max_items)`. Timestamp filters such as `updated_since` accept a `datetime` (time zone aware values are sent in UTC) or an ISO 8601 string; date filters accept a `date`.
+
+## Idempotency
+
+Every create, update, cancel and RSVP write sends an `Idempotency-Key`. When you do not pass one, the library generates a uuid v4 and keeps the same key across its own retries, so a retried write never runs twice.
+
+Pass your own key to make a write safe across restarts of your process:
+
+```python
+client.leads.create(
+    email="marcus.wong@example.com",
+    message="Dinner for 30 in December",
+    idempotency_key=f"enquiry-{form_submission_id}",
+)
+```
+
+A replayed result has `last_response["idempotent_replayed"] == True`. Reusing a key with a different body fails with `idempotency_key_reused`.
+
+## Errors
+
+Every API error is a `BenvoError` subclass with `status`, `type`, `code`, `param`, `request_id`, `headers` and `raw`.
+
+| Exception | When |
+|---|---|
+| `BenvoAuthenticationError` | 401: missing, invalid, expired or revoked key |
+| `BenvoPermissionError` | 403: missing scope, module not enabled, account inactive, consent required |
+| `BenvoNotFoundError` | 404: no such record in this account |
+| `BenvoInvalidRequestError` | 400, 409, 413, 422: invalid parameters or a conflict such as `slot_unavailable` |
+| `BenvoRateLimitError` | 429 after the retries; `retry_after` holds the seconds to wait |
+| `BenvoApiError` | 5xx after the retries, or a response that is not JSON |
+| `BenvoConnectionError` | The API could not be reached; `timed_out` is true for timeouts |
+
+```python
+from benvo import BenvoInvalidRequestError
+
+try:
+    client.reservations.create(date="2026-11-12", time="19:00", party_size=4, guest={"name": "Sophie Tan", "email": "sophie.tan@example.com"})
+except BenvoInvalidRequestError as error:
+    if error.code != "slot_unavailable":
+        raise
+    print("That time was just taken.")
+```
+
+Quote `request_id` when you contact Benvo support.
+
+## Retries
+
+The library retries up to `max_retries` times (default 2) on:
+
+- 429 rate limits
+- 409 `idempotency_in_progress`
+- 5xx responses
+- network errors and timeouts
+
+It waits for `Retry-After` when the API sends it (up to 60 seconds) and otherwise backs off exponentially from 0.5 seconds up to 8 seconds with jitter. Set `max_retries=0` to turn retries off.
+
+## Webhooks
+
+Benvo signs every webhook with [Standard Webhooks](https://www.standardwebhooks.com) headers. Verify the raw body, before any JSON parsing:
+
+```python
+import os
+from flask import Flask, request
+from benvo import BenvoWebhookVerificationError, webhooks
+
+app = Flask(__name__)
+
+@app.post("/benvo/webhooks")
+def benvo_webhook():
+    try:
+        event = webhooks.verify(request.get_data(), request.headers, os.environ["BENVO_WEBHOOK_SECRET"])
+    except BenvoWebhookVerificationError:
+        return "", 400
+
+    if event["type"] == "reservation.created":
+        print("New booking", event["data"]["object"]["id"])
+    return "", 204
+```
+
+`webhooks.verify(payload, headers, secret, tolerance=300)` checks the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers, refuses timestamps more than `tolerance` seconds away from now, compares signatures in constant time and returns the parsed event. `headers` can be any mapping (header names in any case) or a list of pairs. Store `event["id"]` and skip ids you have already processed.
+
+Endpoints set to thin payloads receive only `id` and `object` in `data.object`; fetch the full object with your key.
+
+For your own tests, `webhooks.sign(body, secret, msg_id, timestamp=None)` returns signed headers.
+
+## Request signing
+
+Keys marked to require signatures must sign every request. Pass the key's signing secret and the library adds the header:
+
+```python
+client = Benvo(api_key, signing_secret=os.environ["BENVO_SIGNING_SECRET"])
+```
+
+```
+Benvo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.METHOD.path.body">
+```
+
+`path` is the path with its query string exactly as sent (for example `/v1/people?limit=25`) and `body` is the exact JSON sent, or empty for GET. A new signature is made for each retry. Requests older than 5 minutes are refused, so keep your server clock in sync. To sign by hand, use `benvo.sign_request(secret, method, path, body, timestamp=None)`.
+
+## Test keys and live keys
+
+| Key | Works on | `livemode` |
+|---|---|---|
+| `bvk_test_...` | Your sandbox account only, with fake data. Nothing reaches real guests | `False` |
+| `bvk_live_...` | The venue account it was issued for, after the venue owner approves it | `True` |
+
+The same code runs against both. `client.livemode` tells you which kind of key the client holds, and every object and webhook event carries `livemode`. Build and test with a test key, then swap in the live key.
+
+## Development
+
+Run from `packages/sdk-python`:
+
+```bash
+python3 -m unittest discover -s tests          # offline test suite
+python3 scripts/build_dist.py                  # dist/benvo-1.0.0.tar.gz and dist/benvo-1.0.0-py3-none-any.whl, standard library only
+python3 -m build                               # the same archives with the official builder, when the build package is installed
+```
+
+## Licence
+
+MIT. Copyright Coviola Group LLC.

benvo-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "benvo"
+version = "1.0.0"
+description = "Official Python library for the Benvo API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Coviola Group LLC", email = "support@benvo.io" }]
+keywords = ["benvo", "api", "sdk", "hospitality", "restaurants", "members clubs", "reservations", "webhooks"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://developers.benvo.io"
+Documentation = "https://developers.benvo.io"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+benvo = ["py.typed"]

benvo-1.0.0/src/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-1.0.0/src/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)