### Basic Spond Setup and Group Retrieval

Source: https://github.com/olen/spond/blob/main/_autodocs/configuration.md

This example shows the basic setup for using the Spond SDK and retrieving groups. Remember to close the client session when done.

```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.com", password="secret")
    try:
        groups = await s.get_groups()
        print(f"Found {len(groups or [])} groups")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

--------------------------------

### Quick Example: Fetch and Display Group Information

Source: https://github.com/olen/spond/blob/main/_autodocs/README.md

This example demonstrates how to initialize the Spond client, fetch group data, and print the number of members in each group. Remember to close the client session after use.

```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.com", password="secret")
    try:
        groups = await s.get_groups()
        for g in groups or []:
            print(f"{g['name']}: {len(g['members'])} members")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

--------------------------------

### Constructor Parameters Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows initialization of the Spond client with necessary constructor parameters.

```python
from spond import Spond
spond = Spond(api_key='YOUR_API_KEY', user_id='YOUR_USER_ID')
```

--------------------------------

### Generate API Docs Locally with pdoc

Source: https://github.com/olen/spond/blob/main/README.md

Installs development dependencies and starts the pdoc development server to view API documentation locally. The `--docformat numpy` flag is used to parse NumPy-style docstrings.

```shell
poetry install
poetry run pdoc --docformat numpy ./spond
```

--------------------------------

### GET /transactions Request Example

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Demonstrates how to make a GET request to retrieve club transactions. Ensure you include the Authorization and X-Spond-Clubid headers.

```http
GET https://api.spond.com/club/v1/transactions?skip=0
Authorization: Bearer <token>
X-Spond-Clubid: CLUB123
Content-Type: application/json
```

--------------------------------

### Run attendance.py Example

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Generate a CSV of event attendees within a specified date range. Requires start and end dates.

```bash
python examples/attendance.py -f 2026-06-01 -t 2026-06-30 -a
```

--------------------------------

### Run groups.py Example

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Export all groups to individual JSON files.

```bash
python examples/groups.py
```

--------------------------------

### Example Datetime String

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

An example of a datetime string formatted according to the ISO 8601 standard with UTC.

```text
2026-06-27T00:00:00.000Z
```

--------------------------------

### Spond Client Example

Source: https://github.com/olen/spond/blob/main/_autodocs/README.md

Demonstrates how to initialize the Spond client and fetch group information.

```APIDOC
## Spond Client Initialization and Usage

### Description
This example shows how to create an instance of the `Spond` client, authenticate with username and password, retrieve a list of groups, and print their names and member counts. It also includes proper session closing.

### Method
Asynchronous Python function

### Endpoint
N/A (SDK usage)

### Parameters
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.com", password="secret")
    try:
        groups = await s.get_groups()
        for g in groups or []:
            print(f"{g['name']}: {len(g['members'])} members")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

### Response
#### Success Response
- **groups** (list of dict) - A list of dictionaries, where each dictionary represents a group and contains keys like 'name' and 'members'.

#### Response Example
```json
[
  {
    "name": "Example Group 1",
    "members": [{"id": "1", "name": "Alice"}, {"id": "2", "name": "Bob"}]
  },
  {
    "name": "Example Group 2",
    "members": [{"id": "3", "name": "Charlie"}]
  }
]
```
```

--------------------------------

### Pagination Settings Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates setting pagination limits for methods like fetching events or messages.

```python
events = await spond.get_events(limit=50)
chats = await spond.get_messages(max_chats=50)
```

--------------------------------

### Submodule Import Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to import specific components from submodules within the library.

```python
from spond.clients import Spond
from spond.errors import AuthenticationError
```

--------------------------------

### Direct Class Import Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates importing classes directly from the main package.

```python
from spond import Spond, SpondClub
```

--------------------------------

### GET /transactions Response Example

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

An example of a successful (200 OK) response when retrieving transactions. The response contains a list of transaction objects, each with details like ID, payment time, name, amount, currency, and status.

```json
[
  {
    "id": "TXN123",
    "paidAt": "2026-06-15T10:30:00Z",
    "paymentName": "Monthly Membership",
    "paidByName": "John Doe",
    "amount": "500.00",
    "currency": "NOK",
    "status": "completed"
  },
  {
    "id": "TXN124",
    "paidAt": "2026-06-16T14:15:00Z",
    "paymentName": "Equipment Fee",
    "paidByName": "Jane Smith",
    "amount": "250.00",
    "currency": "NOK",
    "status": "completed"
  }
]
```

--------------------------------

### Run ical.py Example

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Generate an iCalendar file of upcoming events.

```bash
python examples/ical.py
```

--------------------------------

### Install Spond SDK

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Install the Spond SDK using pip. Requires Python 3.11 or later.

```bash
pip install spond
```

--------------------------------

### Query Parameters Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates how query parameters might be structured for an API request.

```json
{
  "query_params": {
    "filter": "active",
    "sort_by": "created_at"
  }
}
```

--------------------------------

### HTTP Response Example (Conceptual)

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows a conceptual example of an HTTP response format, including status codes and data.

```json
{
  "status_code": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "data": "some data",
    "pagination": {
      "next_url": "/api/v1/resource?page=2"
    }
  }
}
```

--------------------------------

### Example Usage of _extract_access_token

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Provides an example of how to use the `_extract_access_token` method with both a successful login response and a malformed response to demonstrate error handling.

```python
from spond.base import _SpondBase
from spond.errors import AuthenticationError

# Simulated login response
response = {
    "accessToken": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiration": "2026-06-28T12:34:56Z"
    }
}

token = _SpondBase._extract_access_token(response)
# Returns: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Failure case
bad_response = {"error": "Invalid credentials"}
try:
    _SpondBase._extract_access_token(bad_response)
except AuthenticationError as e:
    print(f"Error: {e}")  # Prints: "Login failed. error: Invalid credentials"
```

--------------------------------

### HTTP Request Example (Conceptual)

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates a conceptual example of an HTTP request format, likely used internally or for API endpoint documentation.

```json
{
  "method": "POST",
  "url": "/api/v1/resource",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "body": {
    "key": "value"
  }
}
```

--------------------------------

### Package-Level Import Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows importing modules or components directly from the top-level package.

```python
import spond.config as spond_config
```

--------------------------------

### Run transactions.py Example

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Export club transactions to a CSV file, with an option to filter by a minimum amount.

```bash
python examples/transactions.py -m 500
```

--------------------------------

### Mixed Imports Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates a combination of submodule and direct class imports.

```python
from spond import Spond
from spond.utils import format_datetime
```

--------------------------------

### Status Codes and Error Handling Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Conceptual example showing different HTTP status codes and their potential meanings in an API response.

```json
{
  "status_code": 400,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The provided parameter 'limit' is out of range."
  }
}
```

--------------------------------

### Get User Profile - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Retrieves the user's profile information. No specific setup is required beyond initializing the Spond client.

```python
profile = await spond.get_profile()
```

--------------------------------

### Type Hinting for JSONDict

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Example demonstrating the use of type aliases, specifically for JSON dictionaries.

```python
from typing import Dict, Any
JSONDict = Dict[str, Any]

def process_data(data: JSONDict) -> None:
    print(data.get('key'))
```

--------------------------------

### Datetime Formatting Configuration

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of configuring datetime formatting, likely used for API requests or responses.

```python
spond = Spond(datetime_format='%Y-%m-%dT%H:%M:%S.%fZ')
```

--------------------------------

### Example Transaction Response

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

This is an example of the JSON response structure for a transaction. It includes the transaction ID, payment timestamp, payment name, and the name of the person who paid.

```python
{
    "id": "TXN123",
    "paidAt": "2026-06-15T10:30:00.000Z",
    "paymentName": "Monthly Membership",
    "paidByName": "John Doe"
}
```

--------------------------------

### Method-Level Filtering Example

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates applying filters directly within a method call, such as for events.

```python
filtered_events = await spond.get_events(group='group_uid', status='scheduled')
```

--------------------------------

### Event Filtering by Date Range

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of filtering events using a date range.

```python
events = await spond.get_events(since='2023-10-01', until='2023-10-31')
```

--------------------------------

### Example AuthenticationError Messages

Source: https://github.com/olen/spond/blob/main/_autodocs/errors.md

Illustrates various message formats for AuthenticationError based on different failure conditions.

```python
# Incorrect credentials
"Login failed. error: Invalid credentials"
```

```python
# 2FA required
"Login failed. errorKey: 2FA_REQUIRED"
```

```python
# Rate limit hit
"Login failed. errorKey: outOfLoginAttempts, errorCode: 429"
```

```python
# Unknown error
"Login failed. (no recognised diagnostic fields in response)"
```

--------------------------------

### Spond SDK Configuration

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Required configuration for running example scripts. Includes username, password, and optionally club ID for transactions.py.

```python
username = "your@email.com"
password = "your_password"
club_id = "YOUR_CLUB_ID"  # For transactions.py only
```

--------------------------------

### Handle AuthenticationError

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of catching and handling authentication failures. This error typically occurs during login attempts.

```python
try:
    await client.login(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
```

--------------------------------

### Club Transactions with Cache Clearing

Source: https://github.com/olen/spond/blob/main/_autodocs/configuration.md

This example demonstrates how to retrieve transactions for multiple clubs and clear the cache before fetching transactions for each club. Ensure the client session is closed.

```python
from spond.club import SpondClub

async def main():
    sc = SpondClub(username="me@example.com", password="secret")
    try:
        for club_id in ["CLUB_A", "CLUB_B", "CLUB_C"]:
            sc.transactions = None  # Clear cache before each club
            txs = await sc.get_transactions(club_id=club_id, max_items=500)
            print(f"Club {club_id}: {len(txs)} transactions")
    finally:
        await sc.clientsession.close()
```

--------------------------------

### Example Child Profile with Guardians

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

This structure shows a child profile, which includes optional fields for email and guardians.

```python
{
    "id": "CHILD123",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": None,
    "profile": {
        "id": "CHILDPROFILE123"
    },
    "guardians": [
        {
            "id": "GUARDIAN1",
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@example.com"
        }
    ]
}
```

--------------------------------

### Get Wall Posts - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Fetches wall posts, potentially with filters. Initialize the Spond client before use.

```python
posts = await spond.get_posts(group='group_uid', max_posts=20)
```

--------------------------------

### Implement Spond Finance API Subclass

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Example of subclassing _SpondBase to create a finance-specific API client. Sets the base URL for club/finance operations.

```python
# Finance API
class SpondClub(_SpondBase):
    _API_BASE_URL = "https://api.spond.com/club/v1/"
    def __init__(self, username: str, password: str) -> None:
        super().__init__(username, password, self._API_BASE_URL)
        # ... club-specific initialization
```

--------------------------------

### Example Group Response Structure

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

This is a typical JSON response for a group, showing its ID, name, and a list of its members.

```python
{
    "id": "GROUP123ABC",
    "name": "Football Club",
    "members": [
        {
            "id": "MEMBER1",
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@example.com"
        },
        {
            "id": "MEMBER2",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "jane@example.com"
        }
    ]
}
```

--------------------------------

### GET /profile

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Retrieve the authenticated user's profile. This is accessible via `await s.get_profile()` in the SDK.

```APIDOC
## GET /profile

### Description
Retrieve the authenticated user's profile.

### Method
GET

### Endpoint
https://api.spond.com/core/v1/profile

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200 OK)
- **id** (string) - The user's profile ID.
- **firstName** (string) - The user's first name.
- **lastName** (string) - The user's last name.
- **email** (string) - The user's email address.
- **phone** (string) - The user's phone number.
- **address** (string) - The user's address.
- **city** (string) - The user's city.
- **country** (string) - The user's country.

#### Response Example
```json
{
  "id": "PROFILE123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+47XXXXXXXX",
  "address": "123 Main St",
  "city": "Oslo",
  "country": "NO"
}
```

**Status Codes**: 200 OK, 401 Unauthorized, 403 Forbidden
```

--------------------------------

### Fetch Events with Parameters

Source: https://github.com/olen/spond/blob/main/_autodocs/README.md

Retrieve events for a specific group, specifying minimum start time and maximum number of events. All configuration is via constructor and method parameters.

```python
events = await s.get_events(
    group_id="GROUP123",
    min_start=datetime.now(),
    max_events=100
)
```

--------------------------------

### Example Person Response Structure

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

This JSON represents a standard person or member, including their ID, name, email, and an optional profile object.

```python
{
    "id": "MEMBER123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "profile": {
        "id": "PROFILE123"
    }
}
```

--------------------------------

### Instantiate Spond Client

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

The _SpondBase class is intended to be instantiated via its subclasses, such as Spond. This example shows how a Spond instance is created, which internally utilizes _SpondBase.

```python
from spond import spond

# Creates a _SpondBase instance via Spond.__init__
s = spond.Spond(username="me@example.invalid", password="secret")
```

--------------------------------

### Implement Spond Consumer API Subclass

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Example of subclassing _SpondBase to create a consumer-specific API client. Sets the base URL for consumer operations.

```python
# Consumer API
class Spond(_SpondBase):
    _API_BASE_URL = "https://api.spond.com/core/v1/"
    def __init__(self, username: str, password: str) -> None:
        super().__init__(username, password, self._API_BASE_URL)
        # ... consumer-specific initialization
```

--------------------------------

### Mixed Imports with Error Handling

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Combine imports of specific classes and exceptions. This example demonstrates importing a class and an exception for use in a try-except block.

```python
from spond import JSONDict, AuthenticationError
from spond.spond import Spond

s = Spond(username="...", password="...")

try:
    groups: JSONDict = await s.get_groups()
except AuthenticationError as e:
    print(f"Error: {e}")
```

--------------------------------

### Example Usage of JSONDict in Spond SDK

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

Demonstrates how to use JSONDict for fetching groups and updating events using the Spond SDK. Ensure the Spond client session is closed after use.

```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.invalid", password="secret")
    
    # get_groups returns list[JSONDict]
    groups: list[JSONDict] = await s.get_groups()
    
    # Each group is a JSONDict
    for group in groups or []:
        print(group["name"])  # JSONDict behaves like dict[str, Any]
    
    # update_event takes JSONDict
    updates: JSONDict = {
        "heading": "New Title",
        "description": "Updated description"
    }
    result = await s.update_event("EVENT_ID", updates)
    
    await s.clientsession.close()

asyncio.run(main())
```

--------------------------------

### Spond Base Class Inheritance Example

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Demonstrates that Spond and SpondClub classes inherit from the abstract base class _SpondBase and share common attributes like login and clientsession.

```python
from spond.base import _SpondBase
from spond.spond import Spond
from spond.club import SpondClub

# Both inherit from _SpondBase
assert issubclass(Spond, _SpondBase)
assert issubclass(SpondClub, _SpondBase)

# Both have login, auth_headers, clientsession
s = Spond(username="...", password="...")
assert hasattr(s, 'login')
assert hasattr(s, 'auth_headers')
assert hasattr(s, 'clientsession')
```

--------------------------------

### SDK Usage for get_transactions

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Example of how to use the Spond Club SDK to fetch transactions. The SDK handles pagination internally, allowing you to specify a maximum number of items to retrieve.

```python
await sc.get_transactions(club_id=club_id, max_items=100)
```

--------------------------------

### Make Async Calls and Close Session

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Demonstrates making an asynchronous call to get groups and ensuring the client session is closed. Wrap your code in an async function and use asyncio.run().

```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="your@email.com", password="your_password")
    try:
        groups = await s.get_groups()
        print(f"Found {len(groups or [])} groups")
        for g in groups or []:
            print(f"  - {g['name']}")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

```python
await s.clientsession.close()
```

--------------------------------

### Initialize and Use Spond Client

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Demonstrates how to initialize the Spond client with credentials, fetch groups and events, and retrieve the user profile. Ensure to close the client session after use.

```python
from spond.spond import Spond
import asyncio

async def main():
    s = Spond(username="me@example.com", password="secret")
    try:
        groups = await s.get_groups()
        events = await s.get_events()
        profile = await s.get_profile()
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

--------------------------------

### Importing and Instantiating Spond Consumer Client

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Demonstrates how to import and create an instance of the Spond consumer API client. Use the direct import for brevity.

```python
# Consumer API
from spond import spond
s = spond.Spond(username="...", password="...")
```

```python
# Or directly
from spond.spond import Spond
s = Spond(username="...", password="...")
```

--------------------------------

### Spond Client Initialization and Basic Usage

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Demonstrates how to initialize the Spond client with credentials and perform basic operations like fetching groups, events, and profile information. It also shows how to properly close the client session.

```APIDOC
## Example Usage

```python
from spond.spond import Spond
import asyncio

async def main():
    s = Spond(username="me@example.com", password="secret")
    try:
        groups = await s.get_groups()
        events = await s.get_events()
        profile = await s.get_profile()
    finally:
        await s.clientsession.close()

asyncio.run(main())
```
```

--------------------------------

### Send Message to Start New Chat

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Starts a new chat and sends a message to a recipient or group. Requires message text, type, recipient ID, and optionally group ID. Requires an X-Auth header.

```http
POST https://chat.spond.com/v1/messages
X-Auth: <chat_auth_token>
Content-Type: application/json

{
  "text": "Hello!",
  "type": "TEXT",
  "recipient": "PROFILE456",
  "groupId": "GROUP123"
}
```

```json
{
  "id": "MESSAGE123",
  "chatId": "CHAT123",
  "text": "Hello!",
  "sentAt": "2026-06-27T10:30:00Z"
}
```

--------------------------------

### Spond Initialization

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Demonstrates how to initialize the Spond client for consumer or finance API interactions.

```APIDOC
## Spond Initialization

### Description
Initializes the Spond client for either consumer or finance API interactions.

### Class Definition
```python
# Consumer API
class Spond(_SpondBase):
    _API_BASE_URL = "https://api.spond.com/core/v1/"
    def __init__(self, username: str, password: str) -> None:
        super().__init__(username, password, self._API_BASE_URL)
        # ... consumer-specific initialization

# Finance API
class SpondClub(_SpondBase):
    _API_BASE_URL = "https://api.spond.com/club/v1/"
    def __init__(self, username: str, password: str) -> None:
        super().__init__(username, password, self._API_BASE_URL)
        # ... club-specific initialization
```

### Parameters
- `username` (str): Spond account email address.
- `password` (str): Spond account password.

### Inheritance
Subclasses inherit lazy authentication, `login()` method, `auth_headers` property, credential storage, and session lifecycle management.
```

--------------------------------

### Instantiate SpondClub and Fetch Transactions

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/spondclub-client.md

Demonstrates how to instantiate the SpondClub client and retrieve transactions, including handling potential authentication errors.

```python
from spond import AuthenticationError, club

try:
    sc = club.SpondClub(username="...", password="...")
    txs = await sc.get_transactions(club_id="CLUB123")
except AuthenticationError as e:
    print(f"Login failed: {e}")
```

--------------------------------

### Importing and Instantiating Spond Club Finance Client

Source: https://github.com/olen/spond/blob/main/_autodocs/modules.md

Shows how to import and create an instance of the Spond Club finance API client. Direct import is also available.

```python
# Finance API
from spond import club
sc = club.SpondClub(username="...", password="...")
```

```python
# Or directly
from spond.club import SpondClub
sc = SpondClub(username="...", password="...")
```

--------------------------------

### Initialize Spond Client

Source: https://github.com/olen/spond/blob/main/_autodocs/configuration.md

Instantiate the Spond client by providing your username and password. These credentials are required for authentication.

```python
from spond import spond

s = spond.Spond(
    username="me@example.invalid",
    password="MySecurePassword123"
)
```

--------------------------------

### Initialize Spond Client and Fetch Groups

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/spond-client.md

Instantiates the Spond client with credentials and fetches a list of user groups. Ensure to close the client session after use to prevent warnings.

```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.invalid", password="secret")
    try:
        groups = await s.get_groups()
        print(f"Found {len(groups) if groups else 0} groups")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```

--------------------------------

### Initialize Spond Client

Source: https://github.com/olen/spond/blob/main/_autodocs/getting-started.md

Create an instance of the Spond client using your email and password. This can be done via the main spond module or direct import.

```python
from spond import spond

s = spond.Spond(username="your@email.com", password="your_password")
```

```python
from spond.spond import Spond

s = Spond(username="your@email.com", password="your_password")
```

--------------------------------

### Using Spond Client with Automatic Login

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Demonstrates how to instantiate and use the Spond client. The first call to a decorated method like `get_groups` will trigger an automatic login if no token is present.

```python
s = spond.Spond(username="...", password="...")

# First call triggers login automatically
groups = await s.get_groups()  # Calls login() internally

# Subsequent calls reuse the token
events = await s.get_events()  # No login needed
```

--------------------------------

### Initialize Spond with Environment Variables

Source: https://github.com/olen/spond/blob/main/_autodocs/configuration.md

Use this snippet to initialize the Spond client with credentials obtained from environment variables. Ensure SPOND_USERNAME and SPOND_PASSWORD are set.

```python
import os
from spond import spond

username = os.getenv("SPOND_USERNAME")
password = os.getenv("SPOND_PASSWORD")

if not username or not password:
    raise ValueError("SPOND_USERNAME and SPOND_PASSWORD env vars required")

s = spond.Spond(username=username, password=password)
```

--------------------------------

### Get Club Transactions - SpondClub

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Retrieves financial transactions for a club. Requires an initialized SpondClub client.

```python
transactions = await spond_club.get_transactions(club_id='club_uid', limit=25)
```

--------------------------------

### Spond Client Constructor

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/spond-client.md

Initializes the Spond client with user credentials and sets up an aiohttp session for API communication. Authentication is handled lazily.

```APIDOC
## Spond Constructor

### Description
Constructs a Spond client and initializes an underlying aiohttp session. Authentication occurs lazily on the first API call.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **username** (str) - Required - Spond account email address
- **password** (str) - Required - Spond account password. 2FA-enabled accounts are not currently supported.

### Returns
- `Spond`: A new client instance with an open aiohttp `ClientSession`.

### Behavior
- An aiohttp `ClientSession` is opened immediately upon construction.
- Credentials are stored on the instance for use on the first authenticated call.
- Must be closed explicitly: `await client.clientsession.close()` to avoid warnings.

### Example
```python
import asyncio
from spond import spond

async def main():
    s = spond.Spond(username="me@example.invalid", password="secret")
    try:
        groups = await s.get_groups()
        print(f"Found {len(groups) if groups else 0} groups")
    finally:
        await s.clientsession.close()

asyncio.run(main())
```
```

--------------------------------

### Get All Groups with Members - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Fetches all groups along with their members. Ensure the Spond client is initialized.

```python
groups = await spond.get_groups()
```

--------------------------------

### Initialize SpondClub Client

Source: https://github.com/olen/spond/blob/main/_autodocs/configuration.md

Instantiate the SpondClub client using your Spond account username and password. This client is used for club-specific operations.

```python
from spond.club import SpondClub

sc = SpondClub(
    username="me@example.invalid",
    password="MySecurePassword123"
)
```

--------------------------------

### GET {chat_url}/chats/

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Retrieve a user's chat threads. Supports limiting the number of chats returned.

```APIDOC
## GET {chat_url}/chats/

### Description
Retrieve user's chat threads. Supports limiting the number of chats returned.

### Method
GET

### Endpoint
{chat_url}/chats/

### Parameters
#### Query Parameters
- **max** (int) - Optional - Maximum chats to return

### Request Example
```http
GET https://chat.spond.com/v1/chats/?max=100
X-Auth: <chat_auth_token>
```

### Response
#### Success Response (200 OK)
- **id** (str) - Chat thread ID
- **participant** (object) - The other participant in the chat
  - **id** (str) - Participant ID
  - **firstName** (str) - Participant's first name
  - **lastName** (str) - Participant's last name
- **lastMessage** (str) - The last message sent in the chat
- **lastActivity** (str) - Timestamp of the last activity in the chat

#### Response Example
```json
[
  {
    "id": "CHAT123",
    "participant": {
      "id": "MEMBER1",
      "firstName": "John",
      "lastName": "Doe"
    },
    "lastMessage": "Last message text",
    "lastActivity": "2026-06-27T10:30:00Z"
  }
]
```

### SDK Usage
`await s.get_messages(max_chats=100)`

### Status Codes
- 200 OK
- 401 Unauthorized
```

--------------------------------

### Initialize _SpondBase

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

The constructor for _SpondBase initializes credentials and opens an aiohttp session. It is called by subclass constructors.

```python
def __init__(self, username: str, password: str, api_url: str) -> None
```

--------------------------------

### GET /groups/

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Retrieve all groups the user is a member of, including all members and guardians. Accessible via `await s.get_groups()` in the SDK.

```APIDOC
## GET /groups/

### Description
Retrieve all groups the user is a member of, including all members and guardians.

### Method
GET

### Endpoint
https://api.spond.com/core/v1/groups/

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200 OK)
- **id** (string) - The group ID.
- **name** (string) - The name of the group.
- **members** (array) - An array of group members.
  - **id** (string) - The member's ID.
  - **firstName** (string) - The member's first name.
  - **lastName** (string) - The member's last name.
  - **email** (string) - The member's email address.
  - **profile** (object) - The member's profile information.
    - **id** (string) - The profile ID.
  - **guardians** (array) - An array of guardians for the member.

#### Response Example
```json
[
  {
    "id": "GROUP123",
    "name": "Football Club",
    "members": [
      {
        "id": "MEMBER1",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "profile": {
          "id": "PROFILE1"
        },
        "guardians": []
      }
    ]
  }
]
```

**Status Codes**: 200 OK, 401 Unauthorized
```

--------------------------------

### Get Single Event by UID

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/spond-client.md

Retrieves a specific event by its unique ID from the cache. Handles cases where the event is not found.

```python
try:
    event = await s.get_event("EVENT123ABC")
    print(f"Event: {event['heading']}")
except KeyError:
    print("Event not found in cache")
```

--------------------------------

### Get Single Group - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Retrieves a specific group by its unique identifier (uid). The Spond client must be initialized.

```python
group = await spond.get_group(uid='group_uid')
```

--------------------------------

### Generate Static API Documentation HTML

Source: https://github.com/olen/spond/blob/main/README.md

Generates static HTML files for the API documentation. The output is saved to the 'docs/' directory. The `--docformat numpy` flag ensures proper parsing of docstrings.

```shell
poetry run pdoc --docformat numpy -o docs/ ./spond
```

--------------------------------

### Cache Invalidation on Error

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of invalidating the cache for groups when a KeyError occurs, ensuring subsequent calls fetch updated information.

```python
try:
    await spond.get_group(uid='some_group_id')
except KeyError:
    spond.clear_cache('groups')
```

--------------------------------

### Get Single Event - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Retrieves a specific event using its unique identifier (uid). The Spond client must be initialized.

```python
event = await spond.get_event(uid='event_uid')
```

--------------------------------

### SpondClub Constructor

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/spondclub-client.md

Initializes the SpondClub client with username and password for authentication. It establishes an aiohttp ClientSession for making API requests.

```APIDOC
## SpondClub(username: str, password: str)

### Description
Constructs a Spond Club client with the same authentication as the consumer API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```python
def __init__(self, username: str, password: str) -> None
```

### Parameters
- **username** (str) - Required - Spond account email address
- **password** (str) - Required - Spond account password

### Returns
`SpondClub`: A new client instance with an open aiohttp `ClientSession`.

### Authentication
- Uses the same email/password credentials as the consumer API (`Spond` class)
- The account must belong to at least one Spond Club organisation
- The `club_id` passed to methods must be one the account has access to
- `club_id` here is distinct from the consumer API's `groupId`

### Example
```python
import asyncio
from spond.club import SpondClub

async def main():
    sc = SpondClub(username="me@example.invalid", password="secret")
    try:
        txs = await sc.get_transactions(club_id="ABCD1234...", max_items=50)
        for t in txs:
            print(t["paidAt"], t["paymentName"], t["paidByName"])
    finally:
        await sc.clientsession.close()

asyncio.run(main())
```
```

--------------------------------

### Get Chat Threads - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Retrieves chat threads, with an option to limit the number of chats. Requires an initialized Spond client.

```python
chats = await spond.get_messages(max_chats=10)
```

--------------------------------

### Manual Cache Clearing

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates how to manually clear specific caches, such as for events, to ensure fresh data is fetched.

```python
client.clear_cache('events')
```

--------------------------------

### Get Member Information - Spond

Source: https://github.com/olen/spond/blob/main/_autodocs/DOCUMENTATION-SUMMARY.txt

Looks up a member's information using their user identifier. Requires an initialized Spond client.

```python
member = await spond.get_person(user='user_id')
```

--------------------------------

### _SpondBase Constructor

Source: https://github.com/olen/spond/blob/main/_autodocs/api-reference/base-client.md

Initializes the base client with credentials and opens an aiohttp session. This constructor is intended for internal use by subclasses like Spond and SpondClub.

```APIDOC
## _SpondBase Constructor

### Description
Initializes credentials and opens an aiohttp session. Called by subclass constructors.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **username** (str) - Required - Spond account email address
- **password** (str) - Required - Spond account password
- **api_url** (str) - Required - Base URL for the API family (consumer or club). Must end with a trailing slash for relative path concatenation.

### Request Example
```python
from spond import spond

# Creates a _SpondBase instance via Spond.__init__
s = spond.Spond(username="me@example.invalid", password="secret")
```

### Response
#### Success Response (200)
None (constructor does not return a value, but initializes instance attributes and opens a session)

#### Response Example
None
```

--------------------------------

### Example Event Response Structure

Source: https://github.com/olen/spond/blob/main/_autodocs/types.md

This JSON object represents a typical event response from the get_events() function, detailing all relevant event information.

```json
{
    "id": "EVENT123ABC",
    "heading": "Football Training",
    "description": "Weekly practice session",
    "spondType": "EVENT",
    "startTimestamp": "2026-06-27T18:00:00.000Z",
    "endTimestamp": "2026-06-27T19:30:00.000Z",
    "meetupTimestamp": "2026-06-27T17:45:00.000Z",
    "location": {
        "id": "LOC123",
        "feature": "Central Field",
        "address": "123 Main St",
        "latitude": "59.1234",
        "longitude": "10.5678"
    },
    "owners": [
        {
            "id": "COACH123",
            "response": "accepted"
        }
    ],
    "responses": {
        "acceptedIds": ["MEMBER1", "MEMBER2"],
        "declinedIds": ["MEMBER3"],
        "unansweredIds": ["MEMBER4", "MEMBER5"],
        "unconfirmedIds": [],
        "waitinglistIds": []
    },
    "cancelled": false,
    "updated": 1234567890,
    "commentsDisabled": false,
    "maxAccepted": 20,
    "visibility": "INVITEES",
    "participantsHidden": false,
    "autoReminderType": "DISABLED",
    "autoAccept": false,
    "payment": {},
    "attachments": [],
    "tasks": {
        "openTasks": [],
        "assignedTasks": []
    }
}
```

--------------------------------

### Initiate Chat Session

Source: https://github.com/olen/spond/blob/main/_autodocs/api-endpoints.md

Initiates a chat session by performing a secondary handshake with the chat server. Requires an Authorization header.

```http
POST https://api.spond.com/core/v1/chat
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "url": "https://chat.spond.com/v1/",
  "auth": "chat_auth_token_xyz"
}
```