ahs-cti-api-sdk 0.1.0a1__tar.gz

ahs_cti_api_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,156 @@
+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.

ahs_cti_api_sdk-0.1.0a1/README.md

@@ -0,0 +1,142 @@
+# 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.

ahs_cti_api_sdk-0.1.0a1/ahs_cti/__init__.py

@@ -0,0 +1,24 @@
+"""AHS CTI Platform — Python SDK."""
+
+from .client import AsyncCtiClient, CtiClient
+from ._http import ClientConfig
+from .exceptions import CtiApiError, CtiAuthError, CtiError, CtiRetryExhaustedError
+from .models import DialResult, EndCallResult
+
+__version__ = "0.5.0"
+
+__all__ = [
+    # Clients
+    "CtiClient",
+    "AsyncCtiClient",
+    # Configuration
+    "ClientConfig",
+    # Models
+    "DialResult",
+    "EndCallResult",
+    # Exceptions
+    "CtiError",
+    "CtiAuthError",
+    "CtiApiError",
+    "CtiRetryExhaustedError",
+]

ahs_cti_api_sdk-0.1.0a1/ahs_cti/_auth.py

@@ -0,0 +1,236 @@
+"""Authentication strategies — sync and async, with shared-transport injection.
+
+Design
+------
+Auth strategies satisfy the ``SyncAuthStrategy`` / ``AsyncAuthStrategy``
+protocols — they expose only ``get_headers()``.  The HTTP transport is
+injected so that the same ``httpx.Client`` (and its ``verify`` / ``timeout``
+settings) is used for both login calls and regular API calls.
+
+Adding a new auth method (e.g. OAuth2) requires only implementing the
+protocol — no changes to ``_http.py`` or ``client.py``.
+"""
+
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+import httpx
+
+from .exceptions import CtiAuthError
+
+logger = logging.getLogger("ahs_cti.auth")
+
+_MIME_JSON = "application/json"
+_EXPIRY_BUFFER_SECS = 60
+_DEFAULT_TOKEN_TTL = 55 * 60
+
+
+# ---------------------------------------------------------------------------
+# Protocols (open for extension, no import of concrete classes needed)
+# ---------------------------------------------------------------------------
+
+
+class SyncAuthStrategy:
+    """Interface for synchronous authentication strategies.
+
+    Any class that implements ``get_headers() -> Dict[str, str]``
+    satisfies this interface and can be used with ``_HttpClient``.
+    """
+
+    def get_headers(self) -> Dict[str, str]:
+        raise NotImplementedError
+
+
+class AsyncAuthStrategy:
+    """Interface for asynchronous authentication strategies.
+
+    Any class that implements ``async get_headers() -> Dict[str, str]``
+    satisfies this interface and can be used with ``_AsyncHttpClient``.
+    """
+
+    async def get_headers(self) -> Dict[str, str]:
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_headers(auth_headers: Dict[str, str]) -> Dict[str, str]:
+    return {**auth_headers, "Content-Type": _MIME_JSON, "Accept": _MIME_JSON}
+
+
+def _parse_expiry(expiry_str: Optional[str]) -> float:
+    if expiry_str:
+        try:
+            dt = datetime.fromisoformat(expiry_str.replace("Z", "+00:00"))
+            return dt.astimezone(timezone.utc).timestamp()
+        except ValueError:
+            pass
+    return time.time() + _DEFAULT_TOKEN_TTL
+
+
+# ---------------------------------------------------------------------------
+# Sync strategies
+# ---------------------------------------------------------------------------
+
+
+class _ApiKeyAuth(SyncAuthStrategy):
+    """Static API-key auth. Headers are built in memory — no network calls."""
+
+    def __init__(self, api_key: str, tenant_id: Optional[int] = None) -> None:
+        self._api_key = api_key
+        self._tenant_id = tenant_id
+
+    def get_headers(self) -> Dict[str, str]:
+        auth: Dict[str, str] = {"X-API-Key": self._api_key}
+        if self._tenant_id is not None:
+            auth["X-Tenant-ID"] = str(self._tenant_id)
+        return _build_headers(auth)
+
+
+class _CredentialAuth(SyncAuthStrategy):
+    """Credential-based auth — lazy login, auto-refresh 60 s before expiry.
+
+    The caller injects the shared ``httpx.Client`` so that SSL and timeout
+    settings are consistent between the login call and regular API calls.
+
+    Args:
+        login_url: Full URL of the login endpoint.
+        user_id: Agent username.
+        password: Agent password.
+        http_client: Shared ``httpx.Client`` instance (borrowed, not owned).
+    """
+
+    def __init__(
+        self,
+        login_url: str,
+        user_id: str,
+        password: str,
+        http_client: httpx.Client,
+    ) -> None:
+        self._login_url = login_url
+        self._user_id = user_id
+        self._password = password
+        self._http_client = http_client
+        self._access_token: Optional[str] = None
+        self._token_expiry: float = 0.0
+
+    def get_headers(self) -> Dict[str, str]:
+        if not self._is_token_valid():
+            self._login()
+        return _build_headers({"Authorization": f"Bearer {self._access_token}"})
+
+    def _is_token_valid(self) -> bool:
+        return (
+            self._access_token is not None
+            and time.time() < self._token_expiry - _EXPIRY_BUFFER_SECS
+        )
+
+    def _login(self) -> None:
+        logger.debug("ahs_cti: acquiring token for user_id=%s", self._user_id)
+        try:
+            resp = self._http_client.post(
+                self._login_url,
+                json={"userId": self._user_id, "password": self._password},
+            )
+        except httpx.RequestError as exc:
+            raise CtiAuthError(f"Network error during login: {exc}") from exc
+        if resp.status_code != 200:
+            raise CtiAuthError(
+                f"Login failed (HTTP {resp.status_code}). "
+                "Verify user_id, password, and base_url."
+            )
+        data = resp.json()
+        token = data.get("accessToken")
+        if not token:
+            raise CtiAuthError("Login response did not contain an accessToken.")
+        self._access_token = token
+        self._token_expiry = _parse_expiry(data.get("expiration"))
+        logger.debug("ahs_cti: token acquired, expires at %s", self._token_expiry)
+
+
+# ---------------------------------------------------------------------------
+# Async strategies
+# ---------------------------------------------------------------------------
+
+
+class _AsyncApiKeyAuth(SyncAuthStrategy):
+    """API-key auth for use with the async client.
+
+    Satisfies ``SyncAuthStrategy`` — header building is pure in-memory,
+    so no coroutine is needed. ``_AsyncHttpClient`` resolves headers via
+    ``_resolve_headers()`` which handles both sync and async strategies.
+    """
+
+    def __init__(self, api_key: str, tenant_id: Optional[int] = None) -> None:
+        self._inner = _ApiKeyAuth(api_key=api_key, tenant_id=tenant_id)
+
+    def get_headers(self) -> Dict[str, str]:
+        return self._inner.get_headers()
+
+
+class _AsyncCredentialAuth(AsyncAuthStrategy):
+    """Async credential auth — lazy login with asyncio.Lock to prevent races.
+
+    Args:
+        login_url: Full URL of the login endpoint.
+        user_id: Agent username.
+        password: Agent password.
+        http_client: Shared ``httpx.AsyncClient`` instance (borrowed, not owned).
+    """
+
+    def __init__(
+        self,
+        login_url: str,
+        user_id: str,
+        password: str,
+        http_client: httpx.AsyncClient,
+    ) -> None:
+        self._login_url = login_url
+        self._user_id = user_id
+        self._password = password
+        self._http_client = http_client
+        self._access_token: Optional[str] = None
+        self._token_expiry: float = 0.0
+        self._lock: Optional["asyncio.Lock"] = None  # created lazily inside event loop
+
+    async def get_headers(self) -> Dict[str, str]:
+        import asyncio
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        async with self._lock:
+            if not self._is_token_valid():
+                await self._login()
+        return _build_headers({"Authorization": f"Bearer {self._access_token}"})
+
+    def _is_token_valid(self) -> bool:
+        return (
+            self._access_token is not None
+            and time.time() < self._token_expiry - _EXPIRY_BUFFER_SECS
+        )
+
+    async def _login(self) -> None:
+        logger.debug("ahs_cti: async acquiring token for user_id=%s", self._user_id)
+        try:
+            resp = await self._http_client.post(
+                self._login_url,
+                json={"userId": self._user_id, "password": self._password},
+            )
+        except httpx.RequestError as exc:
+            raise CtiAuthError(f"Network error during login: {exc}") from exc
+        if resp.status_code != 200:
+            raise CtiAuthError(
+                f"Login failed (HTTP {resp.status_code}). "
+                "Verify user_id, password, and base_url."
+            )
+        data = resp.json()
+        token = data.get("accessToken")
+        if not token:
+            raise CtiAuthError("Login response did not contain an accessToken.")
+        self._access_token = token
+        self._token_expiry = _parse_expiry(data.get("expiration"))
+        logger.debug("ahs_cti: async token acquired, expires at %s", self._token_expiry)

ahs_cti_api_sdk-0.1.0a1/ahs_cti/_endpoints.py

@@ -0,0 +1,56 @@
+"""Central API endpoint registry.
+
+All paths are versioned under API_VERSION. To upgrade the entire SDK
+to a new API version, change API_VERSION here — no other file needs editing.
+
+Usage::
+
+    from ._endpoints import Endpoints
+    self._http.post(Endpoints.DIAL, body)
+"""
+
+API_VERSION = "v1"
+_BASE = f"/api/{API_VERSION}/cti"
+
+
+class Endpoints:
+    """All CTI platform API endpoint paths."""
+
+    # ── Calls ─────────────────────────────────────────────────────────────────
+    DIAL            = f"{_BASE}/calls/dial"
+    HANGUP          = f"{_BASE}/calls/hangup"
+    ANSWER          = f"{_BASE}/calls/{{call_id}}/answer"
+    FETCH_DETAILS   = f"{_BASE}/calls/fetch-call-details"
+    ACTIVE_CALLS    = f"{_BASE}/calls/active"
+
+    # ── Hold / Mute / DTMF ───────────────────────────────────────────────────
+    HOLD            = f"{_BASE}/calls/hold"
+    MUTE            = f"{_BASE}/calls/mute"
+    DTMF            = f"{_BASE}/calls/{{call_id}}/dtmf"
+
+    # ── Transfer ──────────────────────────────────────────────────────────────
+    TRANSFER        = f"{_BASE}/calls/{{call_id}}/transfer"
+    TRANSFER_CALL   = f"{_BASE}/calls/transfer-call"
+    TRANSFER_CANCEL = f"{_BASE}/calls/transfer/cancel"
+    TRANSFER_COMPLETE = f"{_BASE}/calls/transfer/complete"
+
+    # ── Conference ────────────────────────────────────────────────────────────
+    CONFERENCE_ADD   = f"{_BASE}/calls/conference/add"
+    CONFERENCE_MERGE = f"{_BASE}/calls/conference/merge"
+
+    # ── Agent ─────────────────────────────────────────────────────────────────
+    AGENT_REGISTER   = f"{_BASE}/agent/register"
+    AGENT_UNREGISTER = f"{_BASE}/agent/unregister"
+    AGENT_CONFIG     = f"{_BASE}/agent/config"
+
+    # ── Supervisor ────────────────────────────────────────────────────────────
+    SUPERVISOR_LISTEN      = f"{_BASE}/supervisor/listen"
+    SUPERVISOR_LEAVE       = f"{_BASE}/supervisor/leave"
+    SUPERVISOR_MODE        = f"{_BASE}/supervisor/mode"
+
+    # ── Data / Lookup ─────────────────────────────────────────────────────────
+    DISPOSITIONS           = f"{_BASE}/calls/dispositions"
+    TRANSFER_TO_DETAILS    = f"{_BASE}/transfer-to-details"
+    USERS                  = f"{_BASE}/users"
+    HOSPITAL_SERVICES      = f"{_BASE}/hospital/services"
+    BREAKS                 = f"{_BASE}/breaks"