ahs-cti-api-sdk 0.1.0a1__py3-none-any.whl

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/_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/_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"

ahs_cti/_http.py

@@ -0,0 +1,277 @@
+"""HTTP transport — sync and async, with retry and shared client injection.
+
+Design
+------
+- ``ClientConfig`` groups all transport settings in one immutable object.
+- Both ``_HttpClient`` and ``_AsyncHttpClient`` receive an externally created
+  ``httpx.Client`` / ``httpx.AsyncClient`` so that SSL and timeout settings
+  are consistent across login calls and regular API calls.
+- Retry uses exponential backoff on 5xx responses and transient network errors.
+  4xx responses are never retried (deterministic client errors).
+"""
+
+import asyncio
+import inspect
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from ._auth import AsyncAuthStrategy, SyncAuthStrategy
+from .exceptions import CtiApiError, CtiAuthError, CtiRetryExhaustedError
+
+logger = logging.getLogger("ahs_cti.http")
+
+_RETRYABLE_STATUS_CODES = frozenset({500, 502, 503, 504})
+_RETRYABLE_EXCEPTIONS = (
+    httpx.ConnectError,
+    httpx.TimeoutException,
+    httpx.RemoteProtocolError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Immutable transport configuration for ``CtiClient`` and ``AsyncCtiClient``.
+
+    Args:
+        base_url: Root URL of the CTI platform (no trailing slash).
+            Example: ``"https://cti.example.com"``
+        timeout: HTTP request timeout in seconds. Applied to all requests
+            including the auth login call. Defaults to ``30.0``.
+        verify_ssl: Whether to verify the server's TLS certificate.
+            Set to ``False`` for servers with self-signed certificates.
+            Defaults to ``True``.
+        max_retries: Maximum number of retries after the first attempt for
+            5xx responses and transient connection errors. ``0`` disables
+            retries entirely. Defaults to ``3``.
+    """
+
+    base_url: str
+    timeout: float = 30.0
+    verify_ssl: bool = True
+    max_retries: int = 3
+
+
+# ---------------------------------------------------------------------------
+# Response parsing
+# ---------------------------------------------------------------------------
+
+
+def _parse_response(resp: httpx.Response) -> Dict[str, Any]:
+    if resp.status_code == 401:
+        raise CtiAuthError(
+            "Unauthorized — the token or API key was rejected. "
+            "It may have been revoked or is expired."
+        )
+    if resp.status_code == 403:
+        raise CtiApiError(
+            "Forbidden — this account does not have permission for this action.",
+            status_code=403,
+        )
+    if resp.status_code >= 400:
+        try:
+            detail = resp.json()
+        except Exception:
+            detail = {"raw": resp.text}
+        raise CtiApiError(
+            "The platform returned an error.",
+            status_code=resp.status_code,
+            response=detail,
+        )
+    try:
+        return resp.json()
+    except Exception:
+        return {"raw": resp.text}
+
+
+# ---------------------------------------------------------------------------
+# Auth header resolution — handles both sync and async strategies
+# ---------------------------------------------------------------------------
+
+
+async def _resolve_headers(
+    auth: Union[SyncAuthStrategy, AsyncAuthStrategy],
+) -> Dict[str, str]:
+    """Call ``auth.get_headers()`` whether it is sync or async."""
+    result = auth.get_headers()
+    if inspect.isawaitable(result):
+        return await result
+    return result  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+
+class _HttpClient:
+    """Sync HTTP wrapper — injects auth, retries on transient failures.
+
+    Args:
+        config: Transport configuration.
+        auth: Authentication strategy (sync).
+        http_client: Shared ``httpx.Client`` instance to use for all requests.
+    """
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        auth: SyncAuthStrategy,
+        http_client: httpx.Client,
+    ) -> None:
+        self._config = config
+        self._auth = auth
+        self._client = http_client
+
+    def post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self._config.base_url.rstrip('/')}{path}"
+        logger.debug("ahs_cti: POST %s", path)
+        resp = self._execute_with_retry("post", url, json=body)
+        return _parse_response(resp)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = f"{self._config.base_url.rstrip('/')}{path}"
+        logger.debug("ahs_cti: GET %s", path)
+        resp = self._execute_with_retry("get", url, params=params or {})
+        return _parse_response(resp)
+
+    def _execute_with_retry(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._config.max_retries + 1):
+            if attempt > 0:
+                wait = min(2 ** attempt, 30)
+                logger.warning(
+                    "ahs_cti: retrying %s %s (attempt %d/%d) in %ds",
+                    method.upper(), url, attempt, self._config.max_retries, wait,
+                )
+                time.sleep(wait)
+            try:
+                headers = self._auth.get_headers()
+                resp = getattr(self._client, method)(url, headers=headers, **kwargs)
+                logger.debug("ahs_cti: %s %s → %d", method.upper(), url, resp.status_code)
+                if resp.status_code in _RETRYABLE_STATUS_CODES:
+                    last_exc = CtiApiError(
+                        f"Server error on {url}",
+                        status_code=resp.status_code,
+                    )
+                    continue
+                return resp
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_exc = exc
+                continue
+            except httpx.RequestError as exc:
+                raise CtiApiError(f"Network error calling {url}: {exc}") from exc
+
+        logger.error(
+            "ahs_cti: all %d attempts exhausted for %s %s",
+            self._config.max_retries + 1, method.upper(), url,
+        )
+        raise CtiRetryExhaustedError(
+            f"Request to {url} failed after {self._config.max_retries + 1} attempt(s).",
+            attempts=self._config.max_retries + 1,
+            last_exc=last_exc,
+        ) from last_exc
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "_HttpClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+
+class _AsyncHttpClient:
+    """Async HTTP wrapper — injects auth, retries on transient failures.
+
+    Args:
+        config: Transport configuration.
+        auth: Authentication strategy (sync or async).
+        http_client: Shared ``httpx.AsyncClient`` instance to use for all requests.
+    """
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        auth: Union[SyncAuthStrategy, AsyncAuthStrategy],
+        http_client: httpx.AsyncClient,
+    ) -> None:
+        self._config = config
+        self._auth = auth
+        self._client = http_client
+
+    async def post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self._config.base_url.rstrip('/')}{path}"
+        logger.debug("ahs_cti: async POST %s", path)
+        resp = await self._execute_with_retry("post", url, json=body)
+        return _parse_response(resp)
+
+    async def get(
+        self, path: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        url = f"{self._config.base_url.rstrip('/')}{path}"
+        logger.debug("ahs_cti: async GET %s", path)
+        resp = await self._execute_with_retry("get", url, params=params or {})
+        return _parse_response(resp)
+
+    async def _execute_with_retry(
+        self, method: str, url: str, **kwargs: Any
+    ) -> httpx.Response:
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._config.max_retries + 1):
+            if attempt > 0:
+                wait = min(2 ** attempt, 30)
+                logger.warning(
+                    "ahs_cti: retrying %s %s (attempt %d/%d) in %ds",
+                    method.upper(), url, attempt, self._config.max_retries, wait,
+                )
+                await asyncio.sleep(wait)
+            try:
+                headers = await _resolve_headers(self._auth)
+                resp = await getattr(self._client, method)(url, headers=headers, **kwargs)
+                logger.debug("ahs_cti: %s %s → %d", method.upper(), url, resp.status_code)
+                if resp.status_code in _RETRYABLE_STATUS_CODES:
+                    last_exc = CtiApiError(
+                        f"Server error on {url}",
+                        status_code=resp.status_code,
+                    )
+                    continue
+                return resp
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_exc = exc
+                continue
+            except httpx.RequestError as exc:
+                raise CtiApiError(f"Network error calling {url}: {exc}") from exc
+
+        logger.error(
+            "ahs_cti: all %d attempts exhausted for %s %s",
+            self._config.max_retries + 1, method.upper(), url,
+        )
+        raise CtiRetryExhaustedError(
+            f"Request to {url} failed after {self._config.max_retries + 1} attempt(s).",
+            attempts=self._config.max_retries + 1,
+            last_exc=last_exc,
+        ) from last_exc
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "_AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()