virtuagym 1.0.0__tar.gz

virtuagym-1.0.0/.env.example

@@ -0,0 +1,5 @@
+VIRTUAGYM_API_KEY=
+VIRTUAGYM_CLUB_ID=
+VIRTUAGYM_CLUB_SECRET=
+VIRTUAGYM_CLIENT_ID=
+VIRTUAGYM_CLIENT_SECRET=

virtuagym-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.12', '3.14']
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      # Unit tests only — smoke tests need live credentials and are run locally.
+      - run: pytest

virtuagym-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      # Required for PyPI trusted publishing (OIDC).
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: pip install -e .[dev] build
+      - run: ruff check .
+      - run: mypy
+      # Unit tests only — smoke tests need live credentials and are run locally.
+      - run: pytest
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

virtuagym-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

virtuagym-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gold Development
+
+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.

virtuagym-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: virtuagym
+Version: 1.0.0
+Summary: Typed Python client for the Virtuagym API (v1 + v3), sync + async
+Project-URL: Homepage, https://github.com/gold-development/virtuagym-python
+Project-URL: Issues, https://github.com/gold-development/virtuagym-python/issues
+Author-email: Gold Development <admin@gold-development.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,client,fitness,virtuagym
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-dotenv>=1; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# virtuagym
+
+[![CI](https://github.com/gold-development/virtuagym-python/actions/workflows/ci.yml/badge.svg)](https://github.com/gold-development/virtuagym-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/virtuagym)](https://pypi.org/project/virtuagym/)
+
+A typed Python client for the [Virtuagym API](https://github.com/virtuagym/api-documentation) — v1 (api key + club secret) and v3 (OAuth client credentials) — with sync and async clients.
+
+- **Typed models** — every response is validated onto frozen [pydantic](https://docs.pydantic.dev) models: responses that don't match the schema fail loudly instead of corrupting your data.
+- **Battle-tested against the live API** — the behavior of every endpoint (pagination cursors, envelope quirks, type inconsistencies) was verified live; see [API-FINDINGS](https://github.com/gold-development/virtuagym-node/blob/main/API-FINDINGS.md) for everything the docs don't tell you.
+- **Pagination handled** — iterate lazily page by page, or fetch everything with one call. Duplicate rows caused by the API's inclusive cursors are deduplicated for you.
+- **Sync and async** — `VirtuaGymClientV1`/`VirtuaGymClientV3` on httpx's sync client, `AsyncVirtuaGymClientV1`/`AsyncVirtuaGymClientV3` on its async client, identical method surfaces.
+- Sibling packages: [Node.js/TypeScript](https://github.com/gold-development/virtuagym-node) and [PHP](https://github.com/gold-development/virtuagym-php).
+
+## Installation
+
+```bash
+pip install virtuagym
+```
+
+Requires Python 3.10+.
+
+## API v1 (api key + club secret)
+
+You need three values, all found in Virtuagym under **Business settings → Business Info → Advanced**: your API key, the "Club Key" (club secret), and your club id.
+
+```python
+from virtuagym import VirtuaGymClientV1
+
+client = VirtuaGymClientV1(
+    api_key="...",
+    club_secret="...",
+    club_id=12345,
+)
+
+# Lazily, page by page — each HTTP request only happens when you ask for the next page
+for page in client.members():
+    print(f"received {len(page)} members")
+
+# Or collect every page into a single list
+members = client.all_members()
+
+# Incremental sync (timestamp in ms)
+changed = client.all_members(sync_from=last_sync_timestamp)
+
+# Single member with membership instances embedded
+member = client.member(7302399, with_="memberships")
+
+# Mutations re-fetch and return the canonical record
+created = client.create_member(
+    {"firstname": "John", "lastname": "Doe", "email": "john@example.com"}
+)
+updated = client.update_member(created.member_id, {"gender": "f"})
+upserted = client.create_or_update_member(
+    {"external_id": "1ABC234567", "firstname": "John", "lastname": "Doe"}
+)
+```
+
+The full v1 surface: `employees`, `members`, `activate_user`, `events`, `membership_instances` / `membership_definitions` / `create_membership_instance`, `event_participants` (bookings), `club_taxes`, `income_categories`, `invoices`, `visits`, `member_notes`, `member_credits` / `add_member_credits`, `assign_workout`, `bodymetrics`. Every list endpoint has a lazy iterator (`members()`) and a collector (`all_members()`). Mutation payloads are plain dicts with the API's wire-format keys.
+
+Worth knowing (all verified live): single-resource GETs 404 with statuscode **420**; the notes endpoint is capped at the newest 500 rows; notes and credits use **seconds** for `sync_from` while most endpoints use milliseconds; credits rows have no unique id and page-boundary duplicates are deduplicated for you.
+
+## API v3 (OAuth)
+
+The v3 API is a separate stack behind `gateway.services.virtuagym.com`, authenticated with OAuth client credentials ([register via api@virtuagym.com](https://github.com/virtuagym/api-documentation/blob/master/V3_AUTHENTICATION.md)). Tokens are requested and renewed automatically (club-bound, ~30 min lifetime). Which v3 resources you can reach depends on the scopes Virtuagym registered for your client — without the right scope the API answers a misleading 401 `Token not valid.`.
+
+```python
+import time
+
+from virtuagym import VirtuaGymClientV3
+
+client = VirtuaGymClientV3(
+    client_id="...",
+    client_secret="...",
+    club_id=12345,
+)
+
+# Leads — the live API serializes EVERY lead field as a string
+leads = client.all_leads()
+lead = client.lead(751563)
+created = client.create_lead({"firstname": "Jane", "lastname": "Doe", "email": "jane@example.com"})
+client.update_lead(created.lead_id, {"status_id": 12})  # Closed won
+
+# Schedule (requires the schedule_public_api_club_<club_id> scope)
+now = int(time.time() * 1000)
+week = 7 * 24 * 3600 * 1000
+
+events = client.all_events(date_start=now, date_end=now + week, event_type="appointment")
+bookings = client.all_event_bookings(date_start=now, date_end=now + week, member_id=42)
+
+result = client.create_booking(events[0].event_id, {"member_id": 42})
+# Inspect result.bookings[0].reason — see BOOKING_REASON_CODES in
+# virtuagym.v3.models. NOTE: a member without the required credit type is
+# booked UNPAID rather than rejected — check payment_info if payment matters.
+client.update_booking(events[0].event_id, {"member_id": 42, "presence": True})
+client.cancel_booking(events[0].event_id, member_id=42, refund=False)
+```
+
+Note: occurrences of a recurring event **share the same `event_id`** and differ only in `datetime_start` — use `event_id` + `datetime_start` as the occurrence key.
+
+## Async
+
+Both clients have async twins with identical surfaces:
+
+```python
+from virtuagym import AsyncVirtuaGymClientV1
+
+client = AsyncVirtuaGymClientV1(api_key="...", club_secret="...", club_id=12345)
+
+async for page in client.members():
+    ...
+members = await client.all_members()
+```
+
+## Error handling
+
+```python
+from virtuagym import VirtuaGymApiError, VirtuaGymV3ApiError
+
+try:
+    client.member(999)
+except VirtuaGymApiError as e:
+    # v1: in-band API errors (reported with HTTP 200), real-HTTP-status
+    # errors, and envelope failures.
+    print(e.statuscode, e.statusmessage)  # e.g. 420 'Not found.'
+```
+
+- **`VirtuaGymApiError`** (v1) — `statuscode`, `statusmessage`, optional `errors` payload.
+- **`VirtuaGymV3ApiError`** (v3) — real HTTP status in `http_status`, invalid field names in `fields`. On a 401 the client refreshes the token and retries once before raising.
+- **`pydantic.ValidationError`** — the response did not match the documented schema, naming the exact offending field.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest               # unit tests (offline, mocked HTTP)
+ruff check . && ruff format --check . && mypy
+
+# Smoke tests against the live API (read-only):
+cp .env.example .env  # then fill in your credentials
+pytest -m smoke
+```
+
+## License
+
+[MIT](LICENSE)

virtuagym-1.0.0/README.md

@@ -0,0 +1,145 @@
+# virtuagym
+
+[![CI](https://github.com/gold-development/virtuagym-python/actions/workflows/ci.yml/badge.svg)](https://github.com/gold-development/virtuagym-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/virtuagym)](https://pypi.org/project/virtuagym/)
+
+A typed Python client for the [Virtuagym API](https://github.com/virtuagym/api-documentation) — v1 (api key + club secret) and v3 (OAuth client credentials) — with sync and async clients.
+
+- **Typed models** — every response is validated onto frozen [pydantic](https://docs.pydantic.dev) models: responses that don't match the schema fail loudly instead of corrupting your data.
+- **Battle-tested against the live API** — the behavior of every endpoint (pagination cursors, envelope quirks, type inconsistencies) was verified live; see [API-FINDINGS](https://github.com/gold-development/virtuagym-node/blob/main/API-FINDINGS.md) for everything the docs don't tell you.
+- **Pagination handled** — iterate lazily page by page, or fetch everything with one call. Duplicate rows caused by the API's inclusive cursors are deduplicated for you.
+- **Sync and async** — `VirtuaGymClientV1`/`VirtuaGymClientV3` on httpx's sync client, `AsyncVirtuaGymClientV1`/`AsyncVirtuaGymClientV3` on its async client, identical method surfaces.
+- Sibling packages: [Node.js/TypeScript](https://github.com/gold-development/virtuagym-node) and [PHP](https://github.com/gold-development/virtuagym-php).
+
+## Installation
+
+```bash
+pip install virtuagym
+```
+
+Requires Python 3.10+.
+
+## API v1 (api key + club secret)
+
+You need three values, all found in Virtuagym under **Business settings → Business Info → Advanced**: your API key, the "Club Key" (club secret), and your club id.
+
+```python
+from virtuagym import VirtuaGymClientV1
+
+client = VirtuaGymClientV1(
+    api_key="...",
+    club_secret="...",
+    club_id=12345,
+)
+
+# Lazily, page by page — each HTTP request only happens when you ask for the next page
+for page in client.members():
+    print(f"received {len(page)} members")
+
+# Or collect every page into a single list
+members = client.all_members()
+
+# Incremental sync (timestamp in ms)
+changed = client.all_members(sync_from=last_sync_timestamp)
+
+# Single member with membership instances embedded
+member = client.member(7302399, with_="memberships")
+
+# Mutations re-fetch and return the canonical record
+created = client.create_member(
+    {"firstname": "John", "lastname": "Doe", "email": "john@example.com"}
+)
+updated = client.update_member(created.member_id, {"gender": "f"})
+upserted = client.create_or_update_member(
+    {"external_id": "1ABC234567", "firstname": "John", "lastname": "Doe"}
+)
+```
+
+The full v1 surface: `employees`, `members`, `activate_user`, `events`, `membership_instances` / `membership_definitions` / `create_membership_instance`, `event_participants` (bookings), `club_taxes`, `income_categories`, `invoices`, `visits`, `member_notes`, `member_credits` / `add_member_credits`, `assign_workout`, `bodymetrics`. Every list endpoint has a lazy iterator (`members()`) and a collector (`all_members()`). Mutation payloads are plain dicts with the API's wire-format keys.
+
+Worth knowing (all verified live): single-resource GETs 404 with statuscode **420**; the notes endpoint is capped at the newest 500 rows; notes and credits use **seconds** for `sync_from` while most endpoints use milliseconds; credits rows have no unique id and page-boundary duplicates are deduplicated for you.
+
+## API v3 (OAuth)
+
+The v3 API is a separate stack behind `gateway.services.virtuagym.com`, authenticated with OAuth client credentials ([register via api@virtuagym.com](https://github.com/virtuagym/api-documentation/blob/master/V3_AUTHENTICATION.md)). Tokens are requested and renewed automatically (club-bound, ~30 min lifetime). Which v3 resources you can reach depends on the scopes Virtuagym registered for your client — without the right scope the API answers a misleading 401 `Token not valid.`.
+
+```python
+import time
+
+from virtuagym import VirtuaGymClientV3
+
+client = VirtuaGymClientV3(
+    client_id="...",
+    client_secret="...",
+    club_id=12345,
+)
+
+# Leads — the live API serializes EVERY lead field as a string
+leads = client.all_leads()
+lead = client.lead(751563)
+created = client.create_lead({"firstname": "Jane", "lastname": "Doe", "email": "jane@example.com"})
+client.update_lead(created.lead_id, {"status_id": 12})  # Closed won
+
+# Schedule (requires the schedule_public_api_club_<club_id> scope)
+now = int(time.time() * 1000)
+week = 7 * 24 * 3600 * 1000
+
+events = client.all_events(date_start=now, date_end=now + week, event_type="appointment")
+bookings = client.all_event_bookings(date_start=now, date_end=now + week, member_id=42)
+
+result = client.create_booking(events[0].event_id, {"member_id": 42})
+# Inspect result.bookings[0].reason — see BOOKING_REASON_CODES in
+# virtuagym.v3.models. NOTE: a member without the required credit type is
+# booked UNPAID rather than rejected — check payment_info if payment matters.
+client.update_booking(events[0].event_id, {"member_id": 42, "presence": True})
+client.cancel_booking(events[0].event_id, member_id=42, refund=False)
+```
+
+Note: occurrences of a recurring event **share the same `event_id`** and differ only in `datetime_start` — use `event_id` + `datetime_start` as the occurrence key.
+
+## Async
+
+Both clients have async twins with identical surfaces:
+
+```python
+from virtuagym import AsyncVirtuaGymClientV1
+
+client = AsyncVirtuaGymClientV1(api_key="...", club_secret="...", club_id=12345)
+
+async for page in client.members():
+    ...
+members = await client.all_members()
+```
+
+## Error handling
+
+```python
+from virtuagym import VirtuaGymApiError, VirtuaGymV3ApiError
+
+try:
+    client.member(999)
+except VirtuaGymApiError as e:
+    # v1: in-band API errors (reported with HTTP 200), real-HTTP-status
+    # errors, and envelope failures.
+    print(e.statuscode, e.statusmessage)  # e.g. 420 'Not found.'
+```
+
+- **`VirtuaGymApiError`** (v1) — `statuscode`, `statusmessage`, optional `errors` payload.
+- **`VirtuaGymV3ApiError`** (v3) — real HTTP status in `http_status`, invalid field names in `fields`. On a 401 the client refreshes the token and retries once before raising.
+- **`pydantic.ValidationError`** — the response did not match the documented schema, naming the exact offending field.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest               # unit tests (offline, mocked HTTP)
+ruff check . && ruff format --check . && mypy
+
+# Smoke tests against the live API (read-only):
+cp .env.example .env  # then fill in your credentials
+pytest -m smoke
+```
+
+## License
+
+[MIT](LICENSE)

virtuagym-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "virtuagym"
+version = "1.0.0"
+description = "Typed Python client for the Virtuagym API (v1 + v3), sync + async"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Gold Development", email = "admin@gold-development.nl" }]
+keywords = ["virtuagym", "api", "client", "fitness"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/gold-development/virtuagym-python"
+Issues = "https://github.com/gold-development/virtuagym-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.14",
+    "pytest>=8",
+    "pytest-asyncio>=0.25",
+    "python-dotenv>=1",
+    "respx>=0.22",
+    "ruff>=0.9",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["virtuagym"]
+
+[tool.pytest.ini_options]
+# Smoke tests hit the live API; run them explicitly with `pytest -m smoke`.
+addopts = "-m 'not smoke'"
+markers = ["smoke: tests against the live Virtuagym API (need .env credentials)"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["virtuagym"]

virtuagym-1.0.0/tests/conftest.py

@@ -0,0 +1,19 @@
+import os
+from pathlib import Path
+
+import pytest
+from dotenv import load_dotenv
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+
+def require_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise RuntimeError(f"Missing environment variable {name} — add it to your .env file")
+    return value
+
+
+@pytest.fixture()
+def club_id() -> int:
+    return int(require_env("VIRTUAGYM_CLUB_ID"))

virtuagym-1.0.0/tests/test_smoke.py

@@ -0,0 +1,181 @@
+"""Read-only smoke tests against the live Virtuagym API.
+
+Run with ``pytest -m smoke``; requires credentials in ``.env``.
+"""
+
+import time
+
+import pytest
+from conftest import require_env
+
+from virtuagym import AsyncVirtuaGymClientV3, VirtuaGymClientV1, VirtuaGymClientV3
+
+pytestmark = pytest.mark.smoke
+
+
+@pytest.fixture()
+def v1() -> VirtuaGymClientV1:
+    return VirtuaGymClientV1(
+        api_key=require_env("VIRTUAGYM_API_KEY"),
+        club_secret=require_env("VIRTUAGYM_CLUB_SECRET"),
+        club_id=int(require_env("VIRTUAGYM_CLUB_ID")),
+    )
+
+
+@pytest.fixture()
+def v3() -> VirtuaGymClientV3:
+    return VirtuaGymClientV3(
+        client_id=require_env("VIRTUAGYM_CLIENT_ID"),
+        client_secret=require_env("VIRTUAGYM_CLIENT_SECRET"),
+        club_id=int(require_env("VIRTUAGYM_CLUB_ID")),
+    )
+
+
+def test_retrieves_employees(v1: VirtuaGymClientV1) -> None:
+    for employee in v1.all_employees():
+        assert employee.member_id > 0
+        assert employee.firstname
+
+
+def test_retrieves_all_members_without_duplicates(v1: VirtuaGymClientV1) -> None:
+    members = v1.all_members()
+
+    assert members
+    ids = [m.member_id for m in members]
+    assert len(set(ids)) == len(ids)
+
+
+def test_retrieves_single_member_with_memberships(v1: VirtuaGymClientV1) -> None:
+    first = next(iter(v1.members()))[0]
+
+    single = v1.member(first.member_id, with_="memberships")
+
+    assert single.member_id == first.member_id
+    assert isinstance(single.memberships, list)
+
+
+def test_retrieves_membership_instances_without_duplicates(v1: VirtuaGymClientV1) -> None:
+    instances = v1.all_membership_instances()
+
+    ids = [i.instance_id for i in instances]
+    assert len(set(ids)) == len(ids)
+    assert all(isinstance(i.active, bool) for i in instances)
+
+
+def test_retrieves_membership_definitions_without_duplicates(v1: VirtuaGymClientV1) -> None:
+    definitions = v1.all_membership_definitions()
+
+    ids = [d.membership_id for d in definitions]
+    assert len(set(ids)) == len(ids)
+
+
+def test_retrieves_event_participants(v1: VirtuaGymClientV1) -> None:
+    # Default window: (today - 1 month) .. (today + 1 month).
+    assert isinstance(v1.all_event_participants(), list)
+
+
+def test_retrieves_club_taxes_and_income_categories(v1: VirtuaGymClientV1) -> None:
+    for tax in v1.club_taxes():
+        assert isinstance(tax.tax_id, str)
+    for category in v1.income_categories():
+        assert isinstance(category.income_category_id, str)
+
+
+def test_retrieves_first_page_of_invoices(v1: VirtuaGymClientV1) -> None:
+    page = next(iter(v1.invoices()), [])
+    for invoice in page:
+        assert invoice.guid
+        assert isinstance(invoice.rows, list)
+
+
+def test_retrieves_member_credits_without_duplicates(v1: VirtuaGymClientV1) -> None:
+    credits = v1.all_member_credits()
+
+    keys = [f"{c.member_id}|{c.service_type}" for c in credits]
+    assert len(set(keys)) == len(keys)
+
+
+def test_retrieves_visits(v1: VirtuaGymClientV1) -> None:
+    assert isinstance(v1.all_visits(), list)
+
+
+def test_retrieves_member_notes(v1: VirtuaGymClientV1) -> None:
+    for note in v1.member_notes():
+        assert note.note_id > 0
+
+
+def test_retrieves_all_leads_without_duplicates(v3: VirtuaGymClientV3) -> None:
+    leads = v3.all_leads()
+
+    assert leads
+    ids = [lead.lead_id for lead in leads]
+    assert len(set(ids)) == len(ids)
+
+
+def test_paginates_leads_consistently(v3: VirtuaGymClientV3) -> None:
+    by_default = sorted(lead.lead_id for lead in v3.all_leads())
+    by_small_pages = sorted(lead.lead_id for lead in v3.all_leads(limit=10))
+
+    assert by_small_pages == by_default
+
+
+def test_retrieves_single_lead(v3: VirtuaGymClientV3) -> None:
+    first = next(iter(v3.leads(limit=1)))[0]
+
+    single = v3.lead(first.lead_id)
+
+    assert single.lead_id == first.lead_id
+    assert single.lead_guid == first.lead_guid
+
+
+# The schedule tests require the schedule integration scope
+# (schedule_public_api_club_<club_id>) on the OAuth client.
+
+
+def _window() -> tuple[int, int]:
+    now = int(time.time() * 1000)
+    week = 7 * 24 * 3600 * 1000
+    return now - week, now + week
+
+
+def test_retrieves_schedule_events_without_duplicate_occurrences(v3: VirtuaGymClientV3) -> None:
+    date_start, date_end = _window()
+
+    events = v3.all_events(date_start=date_start, date_end=date_end)
+
+    assert events
+    # event_id repeats for occurrences of recurring events; the occurrence
+    # (event_id + start time) must be unique.
+    keys = [f"{e.event_id}|{e.datetime_start}" for e in events]
+    assert len(set(keys)) == len(keys)
+
+
+def test_retrieves_single_schedule_event(v3: VirtuaGymClientV3) -> None:
+    date_start, date_end = _window()
+    first = next(iter(v3.events(date_start=date_start, date_end=date_end)))[0]
+
+    single = v3.event(first.event_id)
+
+    assert single.event_id == first.event_id
+
+
+def test_retrieves_event_bookings(v3: VirtuaGymClientV3) -> None:
+    date_start, date_end = _window()
+
+    # A 204 (no bookings) yields an empty list; both are valid.
+    for event in v3.all_event_bookings(date_start=date_start, date_end=date_end):
+        assert event.event_id
+        for participant in event.participants or []:
+            assert participant.member_id > 0
+
+
+async def test_async_v3_client_against_live_api() -> None:
+    client = AsyncVirtuaGymClientV3(
+        client_id=require_env("VIRTUAGYM_CLIENT_ID"),
+        client_secret=require_env("VIRTUAGYM_CLIENT_SECRET"),
+        club_id=int(require_env("VIRTUAGYM_CLUB_ID")),
+    )
+
+    leads = await client.all_leads()
+
+    assert leads