# a3api

Official Python client for the [A3 Age Assurance API](https://www.a3api.io).

Typed, async-ready, with built-in retries — supports Python 3.9+.

## Installation

```bash
pip install a3api
```

## Quick Start

```python
from a3api import A3Client, AssessAgeRequest, OsSignal

client = A3Client(api_key="your-api-key")

response = client.assess_age(AssessAgeRequest(
    os_signal=OsSignal.AGE_18_PLUS,
    user_country_code="US",
))

print(response.verdict)           # CONSISTENT
print(response.confidence_score)  # 0.95
print(response.verification_token)
```

### Async

```python
from a3api import AsyncA3Client, AssessAgeRequest, OsSignal

async with AsyncA3Client(api_key="your-api-key") as client:
    response = await client.assess_age(AssessAgeRequest(
        os_signal=OsSignal.AGE_18_PLUS,
        user_country_code="US",
    ))
```

### With Behavioral Signals

```python
from a3api import (
    A3Client, AssessAgeRequest, OsSignal,
    BehavioralMetrics, DeviceContext,
)

client = A3Client(api_key="your-api-key")

response = client.assess_age(AssessAgeRequest(
    os_signal=OsSignal.AGE_13_15,
    user_country_code="US",
    behavioral_metrics=BehavioralMetrics(
        avg_touch_precision=0.82,
        scroll_velocity=340.0,
        form_completion_time_ms=12000.0,
    ),
    device_context=DeviceContext(
        os_version="iOS 17.2",
        device_model="iPhone 15",
        is_high_contrast_enabled=False,
        screen_scale_factor=3.0,
    ),
))
```

## Error Handling

```python
from a3api import (
    A3Client, A3AuthenticationError,
    A3RateLimitError, A3ValidationError, A3ConnectionError,
)

try:
    response = client.assess_age(request)
except A3AuthenticationError:
    # Invalid or missing API key (401)
    pass
except A3RateLimitError as e:
    # Too many requests (429) — e.retry_after has the wait time
    pass
except A3ValidationError as e:
    # Bad request (400) — e.validation_errors has details
    pass
except A3ConnectionError:
    # Network or timeout error
    pass
```

## Configuration

```python
client = A3Client(
    api_key="your-api-key",
    base_url="https://api.a3api.io",  # default
    timeout=30.0,                      # seconds, default
    max_retries=2,                     # default
)
```

## License

MIT
