# GTM Router Python SDK

Official Python client for the [GTM Router API](https://gtmrouter.io) — email enrichment, phone finding, bulk operations, and more.

## Installation

```bash
pip install gtm-router
```

**Local development (from this repo):**

```bash
pip install -e packages/python-sdk
```

## Quick Start

```python
from gtm_router import GTMRouter

client = GTMRouter()  # reads GTM_ROUTER_API_KEY from env

# Find a single email
result = client.email.find(
    first_name="John",
    last_name="Doe",
    domain="acme.com"
)
print(result)

# Bulk email enrichment (auto-polls until done, fetches all results)
job = client.bulk.email_find(
    records=[
        {"first_name": "John", "last_name": "Doe", "domain": "acme.com"},
        {"first_name": "Jane", "last_name": "Smith", "domain": "example.com"},
    ],
    mode="fastest"
)

print(f"Status: {job.status}")
print(f"Total: {job.total_records}, Found: {job.completed_records}")

for r in job.results:
    output = r.get("output") or {}
    if r["status"] == "success" and output.get("found"):
        print(f"  {output['email']}")
```

## Configuration

```python
client = GTMRouter(
    api_key="sk_live_xxx",              # or set GTM_ROUTER_API_KEY env var
    base_url="http://localhost:3000/api/v1",  # or set GTM_ROUTER_API_URL env var
    timeout=30,                         # request timeout in seconds
    max_retries=2,                      # retry count for 5xx / connection errors
    poll_interval=3.0,                  # seconds between poll requests
    poll_timeout=300.0,                 # max seconds to wait for job completion
)
```

## Resources

### `client.email`
- `find(first_name, last_name, domain, mode="fastest", verify=False)`
- `verify(email, mode="fastest")`

### `client.phone`
- `find(email=None, linkedin_url=None, first_name=None, last_name=None, domain=None, mode="fastest")`

### `client.bulk`
- `email_find(records, mode="fastest")` — returns `BulkJob` with `.results`
- `email_verify(records, mode="fastest")` — returns `BulkJob` with `.results`
- `phone_find(records, mode="fastest")` — returns `BulkJob` with `.results`
- `get(job_id)` — get job status
- `get_results(job_id, limit=100, offset=0)` — paginated results
- `cancel(job_id)` — cancel a running job
- `list(status=None, limit=20, offset=0)` — list all jobs

### `client.account`
- `get()` — account info and balance

## Error Handling

```python
from gtm_router import GTMRouter, GTMRouterError, RateLimitError, InsufficientBalanceError

client = GTMRouter()

try:
    job = client.bulk.email_find(records=records, mode="fastest")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except InsufficientBalanceError:
    print("Not enough credits")
except GTMRouterError as e:
    print(f"API error: {e.code} — {e.message}")
```

## License

MIT
