Metadata-Version: 2.4
Name: cohost-client
Version: 0.1.0
Summary: Python client library for the Cohost External API
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic[email]>=2.0
Provides-Extra: dev
Requires-Dist: click>=8.1; extra == 'dev'
Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: jinja2>=3.1; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# cohost-client

Python client library for the [Cohost External API](https://v2-staging.api.cohost.ai/external-docs).

## Installation

```bash
pip install cohost-client
```

## Quick Start

```python
from cohost_client import configure_client
from cohost_client.generated.api import customers, listings, bookings

# Configure once at startup
configure_client(api_key="your-api-key")

# List customers
result = customers.list_customers(page=1, page_size=20)
for customer in result.items:
    print(customer.email)

# Log in a customer and use their token
login_result = customers.customer_login(email="user@example.com", password="secret")
configure_client(bearer_token=login_result.access_token)

# Get listings
listing = listings.get_listing_detail(listing_id=123)
print(listing.name)
```

## Authentication

Two auth schemes are supported:

- **API Key** (`X-API-Key`): for all `/api/v1/external/*` endpoints — set via `configure_client(api_key=...)` or `set_api_key(...)`.
- **JWT Bearer**: for customer-facing endpoints — set via `configure_client(bearer_token=...)` or `set_bearer_token(...)`.

## Self-Update

The generated API code is built from the live OpenAPI spec. To regenerate when the backend changes:

```bash
# Check if the spec has changed (exits 1 if outdated)
cohost-update --check

# Fetch latest spec and regenerate all code
cohost-update
```

Or using Make:

```bash
make generate
```

## Development

### Prerequisites

- Python 3.10+ (use [pyenv](https://github.com/pyenv/pyenv) to manage versions)
- `make`

### First-time setup

```bash
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install the package and all dev dependencies
make install
```

> Do not use `pip install --target ./vendor`. The project uses a standard virtual environment — the `vendor/` directory is ignored by git.

### Common tasks

```bash
# Run the full code generation pipeline (fetch spec → clean → models → api)
make generate

# Run tests against your checkout (after `make install` — uses local `cohost_client/`)
make test

# Run tests against a built wheel only (no local package on PYTHONPATH)
make test-installed

# Optional: live tests against staging — put secrets in `.env` (gitignored)
cp .env.example .env
# Edit `.env` and set COHOST_API_KEY (and optionally COHOST_TEST_* for login)
pytest -m live

# Or export in the shell instead of `.env`
# export COHOST_API_KEY="your-staging-api-key"
# export COHOST_TEST_EMAIL="user@example.com"
# export COHOST_TEST_PASSWORD="your-password"

# Check if the remote spec has changed without regenerating (exits 1 if outdated)
make update-check

# Build the distribution packages (sdist + wheel)
make build
```

## How It Works

See [docs/plan.md](docs/plan.md) for full architecture details.

The library is structured as:

- `cohost_client/client.py` — HTTP layer (auth, error handling)
- `cohost_client/generated/models/` — Pydantic v2 models (auto-generated)
- `cohost_client/generated/api/` — Typed API functions grouped by tag (auto-generated)
- `cohost_client/cli.py` — `cohost-update` CLI for self-update
