# Presa Python SDK — Cursor Rules

## Package Overview

`presa` is the official Python SDK for the Presa HTML-to-PDF API.

## Quick Start

```python
from presa import PDF

# Set PRESA_API_KEY env var, then:
result = PDF.generate(html="<h1>Hello World</h1>")
# result.buffer — bytes of the PDF
# result.size   — byte length
```

## API Reference

### Static Usage (recommended)

```python
from presa import PDF

result = PDF.generate(html="<h1>Hello</h1>")
```

### Client Instance

```python
from presa import Presa, PresaConfig, GenerateOptions, Margins

client = Presa(PresaConfig(
    api_key="your-api-key",                  # or set PRESA_API_KEY env var
    base_url="https://api.presa.dev",        # default
    timeout=30.0,                            # seconds, default
))

result = client.generate(GenerateOptions(
    html="<h1>Hello</h1>",
    format="A4",                             # "A4" | "Letter" | "Legal" | CustomFormat
    landscape=False,
    margins=Margins(top="1cm", right="1cm", bottom="1cm", left="1cm"),
    print_background=True,
    scale=1.0,                               # 0.1–2.0
))
```

### Error Handling

```python
from presa import PDF, ApiError, AuthenticationError

try:
    result = PDF.generate(html=html)
except AuthenticationError:
    # Missing or invalid API key
    pass
except ApiError as e:
    print(e.code)    # e.g., "QUOTA_EXCEEDED"
    print(e.status)  # e.g., 403
    print(str(e))    # human-readable message
```

## Architecture

- `src/presa/client.py` — `Presa` class with `generate()` method
- `src/presa/types.py` — All dataclass types and type aliases
- `src/presa/errors.py` — Error class hierarchy (PresaError → AuthenticationError, ApiError, TimeoutError)
- `src/presa/__init__.py` — Public exports + `PDF` convenience namespace

## Conventions

- Zero external dependencies (uses urllib from stdlib)
- Python 3.10+ (uses `X | Y` union syntax)
- PEP 561 compliant (`py.typed` marker)
- All options use snake_case (Pythonic), serialized to camelCase for the API
