# Edupaid

A Python client for the Edupaid API.

## Installation

```bash
pip install edupaid
```

## Quick Start

```python
from edupaid import Edupaid

# Initialize the client (uses environment variables)
client = Edupaid()

# Or pass credentials directly
client = Edupaid(
    api_key="your-api-key",
    provider_id="your-provider-id",
    jwt_secret="your-jwt-secret",
)

# Access API methods via the service
# result = client.service.get_app_authorization(...)
```

## Configuration

### Environment Variables

The client reads configuration from environment variables. Add these to your `.env` file or set them in your environment:

| Variable | Required | Description |
|----------|----------|-------------|
| `EDUPAID_API_KEY` | Yes | API key for authentication (sent as `x-api-key` header) |
| `EDUPAID_PROVIDER_ID` | Yes | Your provider identifier |
| `EDUPAID_JWT_SECRET` | Yes | Secret for JWT/webhook signature verification |
| `EDUPAID_ENVIRONMENT` | No | `production` (default) or `staging` |

### Example `.env` file

```env
EDUPAID_API_KEY=your-api-key-here
EDUPAID_PROVIDER_ID=your-provider-id-here
EDUPAID_JWT_SECRET=your-jwt-secret-here
```

### Django Integration

For Django projects, ensure your environment variables are loaded before using the client:

```python
# settings.py
import environ

env = environ.Env()
environ.Env.read_env()  # Loads .env file

# In your views/services
from edupaid import Edupaid

client = Edupaid()  # Env vars are already loaded
```

## Error Handling

The client raises typed exceptions for different error scenarios:

```python
from edupaid import Edupaid
from edupaid.errors import (
    ConfigurationError,  # Missing/invalid configuration
    AuthError,           # 401 Unauthorized
    ValidationError,     # 400 Bad Request
    NotFoundError,       # 404 Not Found
    RateLimitError,      # 429 Too Many Requests
    ServerError,         # 5xx Server Errors
    RequestError,        # Other HTTP errors
)

try:
    client = Edupaid()
    # result = client.service.some_method(...)
except ConfigurationError as e:
    print(f"Configuration issue: {e}")
except AuthError as e:
    print(f"Authentication failed: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except ValidationError as e:
    print(f"Invalid request: {e}")
```

All API errors include the error message from the API response:

```python
try:
    # ...
except NotFoundError as e:
    # Access the raw error dict from the API
    if e.error_details:
        api_message = e.error_details.get("error")
```

## API Reference

### Available Methods

The following API endpoints are available via `client.service`:

| Method | Description |
|--------|-------------|
| `get_app_authorization()` | Get learning track authorization for a student |
| `list_app_authorizations()` | List all learning track authorizations for a student |
| `batch_get_app_authorization()` | Get authorizations for multiple students |
| `submit_token()` | Submit a learning token |
| `generate_parent_token()` | Generate parent portal access URL |

*Note: Method implementations are in progress.*

## Requirements

- Python >= 3.10
- httpx
- pydantic >= 2.0

## License

MIT
