Metadata-Version: 2.4
Name: ahs-cti-api-sdk
Version: 0.1.0a1
Summary: Python SDK for the AHS CTI Platform
License: Proprietary
Keywords: cti,telephony,contact-center,ahs
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"

# AHS CTI Python SDK

Python SDK for the AHS CTI Platform — initiate and control outbound calls via REST API.

**Requirements:** Python ≥ 3.9 · `httpx ≥ 0.25`

---

## Installation

```bash
pip install ahs-cti-api-sdk
```

---

## Quick Start

### API-Key Authentication (recommended for server integrations)

```python
from ahs_cti import CtiClient

with CtiClient(base_url="https://cti.example.com", api_key="ctsk_...", tenant_id=1) as client:
    result = client.calls.dial("+919876543210")
    print(result.call_id)   # save this for end_call

    end = client.calls.end_call(
        result.call_id,
        disposition="INTERESTED",
        list_comments="Customer wants a demo next week",
    )
    print(end.duration)
```

### Credential Authentication

```python
from ahs_cti import CtiClient

with CtiClient(base_url="https://cti.example.com", user_id="agent1", password="secret") as client:
    result = client.calls.dial("+919876543210", caller_id="AH2007C")
```

### Async Client

```python
import asyncio
from ahs_cti import AsyncCtiClient

async def main():
    async with AsyncCtiClient(base_url="https://cti.example.com", api_key="ctsk_...") as client:
        result = await client.calls.dial("+919876543210")
        print(result.call_id)

asyncio.run(main())
```

---

## ClientConfig Reference

For full control over transport settings, use `ClientConfig`:

```python
from ahs_cti import CtiClient, ClientConfig

config = ClientConfig(
    base_url="https://cti.example.com",
    timeout=15.0,
    verify_ssl=False,   # for self-signed certificates
    max_retries=5,
)

with CtiClient(config=config, api_key="ctsk_...") as client:
    result = client.calls.dial("+919876543210")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_url` | `str` | required | Root URL of the CTI platform |
| `timeout` | `float` | `30.0` | Request timeout in seconds |
| `verify_ssl` | `bool` | `True` | Set `False` for self-signed certs |
| `max_retries` | `int` | `3` | Retry attempts on 5xx / network errors |

---

## Error Handling

```python
from ahs_cti import CtiClient, CtiAuthError, CtiApiError, CtiRetryExhaustedError

with CtiClient(...) as client:
    try:
        result = client.calls.dial("+919876543210")
    except CtiAuthError:
        # Invalid or expired API key / credentials
        print("Authentication failed")
    except CtiRetryExhaustedError as e:
        # All retry attempts failed (5xx or network)
        print(f"Failed after {e.attempts} attempts: {e.last_exc}")
    except CtiApiError as e:
        # Any other API error (400, 404, 422 …)
        print(f"API error [{e.status_code}]: {e}")
```

### Exception Hierarchy

```
CtiError
├── CtiAuthError          — 401 / login failure
└── CtiApiError           — 4xx / 5xx from the platform
    └── CtiRetryExhaustedError  — all retries exhausted
```

---

## Retry Behaviour

The SDK automatically retries on `500`, `502`, `503`, `504` responses and transient
network errors (`ConnectError`, `TimeoutException`). Retries use exponential backoff:

| Attempt | Delay |
|---|---|
| 1st (initial) | none |
| 2nd retry | 2 s |
| 3rd retry | 4 s |
| 4th retry | 8 s |

Set `max_retries=0` in `ClientConfig` to disable retries entirely.

---

## Self-Signed Certificates

Internal / staging servers often use self-signed TLS certificates. Pass `verify_ssl=False`:

```python
client = CtiClient(base_url="https://192.168.1.10:8082", api_key="ctsk_...", verify_ssl=False)
```

> Do **not** disable SSL verification in production.
