callaider 0.1.0__py3-none-any.whl

callaider/__init__.py

@@ -0,0 +1,27 @@
+from callaider._client import AsyncCallaider, Callaider
+from callaider.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    AuthenticationError,
+    CallaiderError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitError,
+)
+from callaider.webhooks import WebhookParsingError, Webhooks
+
+__all__ = [
+    "Callaider",
+    "AsyncCallaider",
+    "Webhooks",
+    "WebhookParsingError",
+    "CallaiderError",
+    "APIError",
+    "APIStatusError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+]

callaider/_base_client.py

@@ -0,0 +1,216 @@
+import asyncio
+import logging
+import time
+from typing import Any, Mapping
+import httpx
+
+from callaider._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, RAW_USER_AGENT
+from callaider.exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitError,
+)
+
+logger = logging.getLogger("callaider")
+
+
+def _make_status_error(
+    response: httpx.Response,
+    body: Any,
+) -> APIStatusError:
+    """Map HTTP status codes to specific exception types."""
+    status_code = response.status_code
+    message = f"Error code: {status_code}"
+    if isinstance(body, dict):
+        message = body.get("message") or body.get("detail") or str(body)
+    elif isinstance(body, str) and body:
+        message = body
+
+    if status_code in (401, 403):
+        return AuthenticationError(message, response=response, body=body)
+    if status_code == 404:
+        return NotFoundError(message, response=response, body=body)
+    if status_code == 429:
+        return RateLimitError(message, response=response, body=body)
+    if status_code >= 500:
+        return InternalServerError(message, response=response, body=body)
+    return APIStatusError(message, response=response, body=body)
+
+
+class SyncHttpxClientWrapper:
+    """Synchronous HTTP transport layer with automatic retry logic."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        custom_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": RAW_USER_AGENT,
+            "Accept": "application/json",
+            **(custom_headers or {}),
+        }
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Execute a synchronous HTTP request with exponential backoff retries."""
+        retries = self.max_retries
+        delay = 0.5
+
+        for attempt in range(retries + 1):
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json_data,
+                    headers=headers,
+                )
+                if response.is_success:
+                    return response.json() if response.content else None
+
+                # Attempt to parse response body for error messaging
+                try:
+                    body = response.json()
+                except Exception:
+                    body = response.text
+
+                # Retry on rate limits, timeouts, and server errors
+                if response.status_code in (408, 429, 500, 502, 503, 504) and attempt < retries:
+                    logger.warning(
+                        "Retrying request (%d/%d) due to status %d...",
+                        attempt + 1,
+                        retries,
+                        response.status_code,
+                    )
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+
+                raise _make_status_error(response, body)
+
+            except httpx.RequestError as exc:
+                if attempt < retries:
+                    logger.warning(
+                        "Retrying request (%d/%d) due to network error: %s",
+                        attempt + 1,
+                        retries,
+                        exc,
+                    )
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+                raise APIConnectionError(f"Connection error: {exc}") from exc
+
+    def close(self) -> None:
+        """Close the underlying HTTP client session."""
+        self._client.close()
+
+
+class AsyncHttpxClientWrapper:
+    """Asynchronous HTTP transport layer with automatic retry logic."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        custom_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": RAW_USER_AGENT,
+            "Accept": "application/json",
+            **(custom_headers or {}),
+        }
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Execute an asynchronous HTTP request with exponential backoff retries."""
+        retries = self.max_retries
+        delay = 0.5
+
+        for attempt in range(retries + 1):
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json_data,
+                    headers=headers,
+                )
+                if response.is_success:
+                    return response.json() if response.content else None
+
+                try:
+                    body = response.json()
+                except Exception:
+                    body = response.text
+
+                if response.status_code in (408, 429, 500, 502, 503, 504) and attempt < retries:
+                    logger.warning(
+                        "Retrying request (%d/%d) due to status %d...",
+                        attempt + 1,
+                        retries,
+                        response.status_code,
+                    )
+                    await asyncio.sleep(delay)
+                    delay *= 2
+                    continue
+
+                raise _make_status_error(response, body)
+
+            except httpx.RequestError as exc:
+                if attempt < retries:
+                    logger.warning(
+                        "Retrying request (%d/%d) due to network error: %s",
+                        attempt + 1,
+                        retries,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+                    delay *= 2
+                    continue
+                raise APIConnectionError(f"Connection error: {exc}") from exc
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client session."""
+        await self._client.aclose()

callaider/_client.py

@@ -0,0 +1,99 @@
+import os
+from typing import Mapping
+from callaider._base_client import AsyncHttpxClientWrapper, SyncHttpxClientWrapper
+from callaider.resources.assistants import AssistantsResource, AsyncAssistantsResource
+from callaider._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from callaider._models import HealthResponse
+from callaider.resources.ringing import AsyncRingingResource, RingingResource
+
+
+class Callaider:
+    """Synchronous client for the Callaider API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        resolved_key = api_key or os.getenv("CALLAIDER_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Missing API key. Pass `api_key` explicitly or set the `CALLAIDER_API_KEY` environment variable."
+            )
+
+        self._transport = SyncHttpxClientWrapper(
+            base_url=base_url,
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            custom_headers=default_headers,
+        )
+
+        # Resource namespaces
+        self.ringing = RingingResource(self)
+        self.assistants = AssistantsResource(self)
+
+    def health(self) -> HealthResponse:
+        """Check API service health status."""
+        data = self._transport.request("GET", "/v1/health")
+        return HealthResponse.model_validate(data or {})
+
+    def close(self) -> None:
+        """Close the active client session."""
+        self._transport.close()
+
+    def __enter__(self) -> "Callaider":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncCallaider:
+    """Asynchronous client for the Callaider API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        resolved_key = api_key or os.getenv("CALLAIDER_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Missing API key. Pass `api_key` explicitly or set the `CALLAIDER_API_KEY` environment variable."
+            )
+
+        self._transport = AsyncHttpxClientWrapper(
+            base_url=base_url,
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            custom_headers=default_headers,
+        )
+
+        # Resource namespaces
+        self.ringing = AsyncRingingResource(self)
+        self.assistants = AsyncAssistantsResource(self)
+
+    async def health(self) -> HealthResponse:
+        """Check API service health status asynchronously."""
+        data = await self._transport.request("GET", "/v1/health")
+        return HealthResponse.model_validate(data or {})
+
+    async def close(self) -> None:
+        """Close the active client session asynchronously."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncCallaider":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

callaider/_constants.py

@@ -0,0 +1,4 @@
+DEFAULT_BASE_URL = "https://api.callaider.ai"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+RAW_USER_AGENT = "callaider-python/0.1.0"

callaider/_models.py

@@ -0,0 +1,140 @@
+from enum import Enum
+from typing import Any
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseModelStrict(BaseModel):
+    """Base Pydantic model with extra field tolerance and alias support."""
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class HealthResponse(BaseModelStrict):
+    """API health status response."""
+    status: str = Field(default="ok")
+    timestamp: str | None = None
+
+
+# --- Ringing Enums & Sub-models ---
+
+class CampaignStatus(str, Enum):
+    DRAFT = "draft"
+    CREATED = "created"
+    IN_PROGRESS = "in_progress"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class CampaignRecipient(BaseModelStrict):
+    """Single recipient details."""
+    phone: str
+    name: str | None = None
+    variables: dict[str, Any] = Field(default_factory=dict)
+
+
+class Campaign(BaseModelStrict):
+    """Full campaign object representation."""
+    id: str | int
+    name: str | None = None
+    status: str | CampaignStatus
+    assistant_id: str | None = None
+    total_recipients: int | None = 0
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class CampaignStatistics(BaseModelStrict):
+    """Aggregated campaign performance statistics."""
+    campaign_id: str | int
+    total_calls: int = 0
+    completed_calls: int = 0
+    successful_calls: int = 0
+    failed_calls: int = 0
+    average_duration_seconds: float | None = None
+
+
+class CallRecord(BaseModelStrict):
+    """Single call details and outcome."""
+    id: str | int
+    campaign_id: str | int | None = None
+    phone: str
+    status: str
+    duration_seconds: int | None = 0
+    recording_url: str | None = None
+    transcript: str | None = None
+    post_analysis: dict[str, Any] | None = None
+    created_at: str | None = None
+
+
+class RecordingInfo(BaseModelStrict):
+    """Call audio recording metadata."""
+    call_id: str | int
+    recording_url: str
+    duration_seconds: int | None = None
+    format: str = "mp3"
+
+
+# --- Assistants / External Conversation Models ---
+
+class MessageItem(BaseModelStrict):
+    """Individual conversation message representation."""
+    role: str = "assistant"
+    content: str = ""
+    timestamp: str | None = None
+
+
+class ExternalConversationMessageRequest(BaseModelStrict):
+    """Request payload for sending messages to an external assistant conversation."""
+    message: str
+    external_conversation_id: str = Field(alias="externalConversationId")
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExternalConversationMessageResponse(BaseModelStrict):
+    """Response returned by the AI assistant conversation bridge."""
+    ok: bool = True
+    status: str | None = None
+    external_conversation_id: str | None = Field(default=None, alias="externalConversationId")
+    reply: str | None = None
+    messages: list[MessageItem] = Field(default_factory=list)
+    state: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def text(self) -> str:
+        """Convenience helper to extract the main assistant reply text."""
+        if self.reply:
+            return self.reply
+        if self.messages:
+            # Return content of the latest assistant message
+            for msg in reversed(self.messages):
+                if msg.role == "assistant" and msg.content:
+                    return msg.content
+            return self.messages[-1].content
+        return ""
+
+# --- Webhook Event Models ---
+
+class WebhookEventType(str, Enum):
+    CALL_STARTED = "call.started"
+    CALL_ANSWERED = "call.answered"
+    CALL_COMPLETED = "call.completed"
+    CALL_FAILED = "call.failed"
+    CAMPAIGN_FINISHED = "campaign.finished"
+
+
+class CallCompletedPayload(BaseModelStrict):
+    """Payload delivered when a call is finished."""
+    call_id: str | int
+    campaign_id: str | int | None = None
+    phone: str
+    duration_seconds: int = 0
+    recording_url: str | None = None
+    transcript: str | None = None
+    post_analysis: dict[str, Any] = Field(default_factory=dict)
+
+
+class WebhookEvent(BaseModelStrict):
+    """Generic incoming Callaider webhook event wrapper."""
+    event: str | WebhookEventType
+    timestamp: str | None = None
+    data: CallCompletedPayload | dict[str, Any]

callaider/_streaming.py

@@ -0,0 +1,117 @@
+from typing import Generic, TypeVar, Optional, TYPE_CHECKING
+
+import httpx2
+
+if TYPE_CHECKING:
+    from ._client import OpenAI, AsyncOpenAI
+    from ._models import FinalRequestOptions
+
+_T = TypeVar("_T")
+
+class Stream(Generic[_T]):
+    """Provides the core interface to iterate over a synchronous stream response."""
+
+    response: httpx2.Response
+    _options: Optional[FinalRequestOptions] = None
+    _decoder: SSEBytesDecoder
+
+    def __init__(
+        self,
+        *,
+        cast_to: type[_T],
+        response: httpx2.Response,
+        client: OpenAI,
+        options: Optional[FinalRequestOptions] = None,
+    ) -> None:
+        self.response = response
+        self._cast_to = cast_to
+        self._client = client
+        self._options = options
+        self._decoder = client._make_sse_decoder()
+        self._iterator = self.__stream__()
+
+    def __next__(self) -> _T:
+        return self._iterator.__next__()
+
+    def __iter__(self) -> Iterator[_T]:
+        for item in self._iterator:
+            yield item
+
+    def _iter_events(self) -> Iterator[ServerSentEvent]:
+        yield from self._decoder.iter_bytes(self.response.iter_bytes())
+
+    def __stream__(self) -> Iterator[_T]:
+        cast_to = cast(Any, self._cast_to)
+        response = self.response
+        process_data = self._client._process_response_data
+        iterator = self._iter_events()
+
+        try:
+            for sse in iterator:
+                if sse.data.startswith("[DONE]"):
+                    break
+
+                # we have to special case the Assistants `thread.` events since we won't have an "event" key in the data
+                if sse.event and sse.event.startswith("thread."):
+                    data = sse.json()
+
+                    if sse.event == "error" and is_mapping(data) and data.get("error"):
+                        message = None
+                        error = data.get("error")
+                        if is_mapping(error):
+                            message = error.get("message")
+                        if not message or not isinstance(message, str):
+                            message = "An error occurred during streaming"
+
+                        raise APIError(
+                            message=message,
+                            request=self.response.request,
+                            body=data["error"],
+                        )
+
+                    yield process_data(data={"data": data, "event": sse.event}, cast_to=cast_to, response=response)
+                else:
+                    data = sse.json()
+                    if is_mapping(data) and data.get("error"):
+                        message = None
+                        error = data.get("error")
+                        if is_mapping(error):
+                            message = error.get("message")
+                        if not message or not isinstance(message, str):
+                            message = "An error occurred during streaming"
+
+                        raise APIError(
+                            message=message,
+                            request=self.response.request,
+                            body=data["error"],
+                        )
+
+                    yield process_data(
+                        data={"data": data, "event": sse.event}
+                        if self._options is not None and self._options.synthesize_event_and_data
+                        else data,
+                        cast_to=cast_to,
+                        response=response,
+                    )
+        finally:
+            # Ensure the response is closed even if the consumer doesn't read all data
+            response.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """
+        Close the response and release the connection.
+
+        Automatically called if the response body is read to completion.
+        """
+        self.response.close()

callaider/exceptions.py

@@ -0,0 +1,55 @@
+from typing import Any
+import httpx
+
+
+class CallaiderError(Exception):
+    """Base exception for all Callaider SDK errors."""
+    pass
+
+
+class APIError(CallaiderError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request: httpx.Request | None = None,
+        response: httpx.Response | None = None,
+        body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.request = request
+        self.response = response
+        self.status_code = response.status_code if response else None
+        self.body = body
+
+
+class APIStatusError(APIError):
+    """Raised for non-2xx HTTP status codes."""
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    """Raised for 401 Unauthorized and 403 Forbidden errors."""
+    pass
+
+
+class NotFoundError(APIStatusError):
+    """Raised for 404 Not Found errors."""
+    pass
+
+
+class RateLimitError(APIStatusError):
+    """Raised for 429 Too Many Requests errors."""
+    pass
+
+
+class InternalServerError(APIStatusError):
+    """Raised for 5xx Server Errors."""
+    pass
+
+
+class APIConnectionError(APIError):
+    """Raised when a network connection error occurs (DNS, timeout, connection drop)."""
+    pass

callaider/resources/assistants.py

@@ -0,0 +1,96 @@
+from typing import Any, TYPE_CHECKING
+from callaider._models import (
+    ExternalConversationMessageRequest,
+    ExternalConversationMessageResponse,
+)
+
+if TYPE_CHECKING:
+    from callaider._client import AsyncCallaider, Callaider
+
+
+class AssistantsResource:
+    """Synchronous interface for conversational assistants and bridge integrations."""
+
+    def __init__(self, client: "Callaider") -> None:
+        self._client = client
+
+    def send_message(
+        self,
+        assistant_id: str | int,
+        *,
+        message: str,
+        external_conversation_id: str = "conv_default_123",
+        metadata: dict[str, Any] | None = None,
+    ) -> ExternalConversationMessageResponse:
+        """Send a message to an AI assistant and receive a contextual response.
+
+        :param assistant_id: Unique identifier of the assistant.
+        :param message: Text prompt/message from the user.
+        :param external_conversation_id: External session ID for conversation state.
+        :param metadata: Optional metadata dictionary.
+        """
+        request_model = ExternalConversationMessageRequest(
+            message=message,
+            externalConversationId=external_conversation_id,
+            metadata=metadata or {},
+        )
+
+        data = self._client._transport.request(
+            "POST",
+            f"/v1/assistants/{assistant_id}/external-conversations/messages",
+            json_data=request_model.model_dump(by_alias=True, exclude_none=True),
+        )
+        return ExternalConversationMessageResponse.model_validate(data)
+
+    def get_conversation_state(
+        self,
+        assistant_id: str | int,
+        external_conversation_id: str,
+    ) -> dict[str, Any]:
+        """Retrieve conversation state by external conversation ID."""
+        data = self._client._transport.request(
+            "GET",
+            f"/v1/assistants/{assistant_id}/external-conversations/{external_conversation_id}/state",
+        )
+        return data or {}
+
+
+class AsyncAssistantsResource:
+    """Asynchronous interface for conversational assistants and bridge integrations."""
+
+    def __init__(self, client: "AsyncCallaider") -> None:
+        self._client = client
+
+    async def send_message(
+        self,
+        assistant_id: str | int,
+        *,
+        message: str,
+        external_conversation_id: str = "conv_default_123",
+        metadata: dict[str, Any] | None = None,
+    ) -> ExternalConversationMessageResponse:
+        """Send a message to an AI assistant asynchronously."""
+        request_model = ExternalConversationMessageRequest(
+            message=message,
+            externalConversationId=external_conversation_id,
+            metadata=metadata or {},
+        )
+
+        data = await self._client._transport.request(
+            "POST",
+            f"/v1/assistants/{assistant_id}/external-conversations/messages",
+            json_data=request_model.model_dump(by_alias=True, exclude_none=True),
+        )
+        return ExternalConversationMessageResponse.model_validate(data)
+
+    async def get_conversation_state(
+        self,
+        assistant_id: str | int,
+        external_conversation_id: str,
+    ) -> dict[str, Any]:
+        """Retrieve conversation state asynchronously."""
+        data = await self._client._transport.request(
+            "GET",
+            f"/v1/assistants/{assistant_id}/external-conversations/{external_conversation_id}/state",
+        )
+        return data or {}

callaider/resources/ringing.py

@@ -0,0 +1,171 @@
+from typing import Any, TYPE_CHECKING
+from callaider._models import (
+    Campaign,
+    CampaignRecipient,
+    CampaignStatistics,
+    CallRecord,
+    RecordingInfo,
+)
+
+if TYPE_CHECKING:
+    from callaider._client import AsyncCallaider, Callaider
+
+
+class RingingResource:
+    """Synchronous client interface for the Ringing (outbound calls) module."""
+
+    def __init__(self, client: "Callaider") -> None:
+        self._client = client
+
+    def list_campaigns(self) -> list[Campaign]:
+        """Fetch all outbound campaigns."""
+        data = self._client._transport.request("GET", "/v1/ringing/campaigns")
+        items = data if isinstance(data, list) else data.get("data", [])
+        return [Campaign.model_validate(c) for c in items]
+
+    def create_campaign(
+        self,
+        *,
+        assistant_id: str,
+        recipients: list[CampaignRecipient | dict[str, Any]],
+        name: str | None = None,
+    ) -> Campaign:
+        """Create a new outbound call campaign."""
+        parsed_recipients = [
+            r.model_dump() if isinstance(r, CampaignRecipient) else r
+            for r in recipients
+        ]
+        payload: dict[str, Any] = {
+            "assistant_id": assistant_id,
+            "recipients": parsed_recipients,
+        }
+        if name:
+            payload["name"] = name
+
+        data = self._client._transport.request("POST", "/v1/ringing/campaigns", json_data=payload)
+        return Campaign.model_validate(data)
+
+    def get_campaign(self, campaign_id: str | int) -> Campaign:
+        """Retrieve details of a specific campaign."""
+        data = self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}")
+        return Campaign.model_validate(data)
+
+    def delete_campaign(self, campaign_id: str | int) -> None:
+        """Delete a campaign by ID."""
+        self._client._transport.request("DELETE", f"/v1/ringing/campaigns/{campaign_id}")
+
+    def launch_campaign(self, campaign_id: str | int) -> Campaign:
+        """Start or schedule execution of a campaign."""
+        data = self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/launch")
+        return Campaign.model_validate(data)
+
+    def pause_campaign(self, campaign_id: str | int) -> Campaign:
+        """Pause an active campaign."""
+        data = self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/pause")
+        return Campaign.model_validate(data)
+
+    def resume_campaign(self, campaign_id: str | int) -> Campaign:
+        """Resume a paused campaign."""
+        data = self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/resume")
+        return Campaign.model_validate(data)
+
+    def get_campaign_statistics(self, campaign_id: str | int) -> CampaignStatistics:
+        """Retrieve aggregated statistics for a specific campaign."""
+        data = self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}/statistics")
+        return CampaignStatistics.model_validate(data)
+
+    def list_campaign_calls(self, campaign_id: str | int) -> list[CallRecord]:
+        """Fetch all call records belonging to a campaign."""
+        data = self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}/calls")
+        items = data if isinstance(data, list) else data.get("data", [])
+        return [CallRecord.model_validate(item) for item in items]
+
+    def get_call(self, call_id: str | int) -> CallRecord:
+        """Retrieve details of an individual call record."""
+        data = self._client._transport.request("GET", f"/v1/ringing/calls/{call_id}")
+        return CallRecord.model_validate(data)
+
+    def get_call_recording(self, call_id: str | int) -> RecordingInfo:
+        """Retrieve the audio recording link and metadata for a specific call."""
+        data = self._client._transport.request("GET", f"/v1/ringing/calls/{call_id}/recording")
+        return RecordingInfo.model_validate(data)
+
+
+class AsyncRingingResource:
+    """Asynchronous client interface for the Ringing (outbound calls) module."""
+
+    def __init__(self, client: "AsyncCallaider") -> None:
+        self._client = client
+
+    async def list_campaigns(self) -> list[Campaign]:
+        """Fetch all outbound campaigns asynchronously."""
+        data = await self._client._transport.request("GET", "/v1/ringing/campaigns")
+        items = data if isinstance(data, list) else data.get("data", [])
+        return [Campaign.model_validate(c) for c in items]
+
+    async def create_campaign(
+        self,
+        *,
+        assistant_id: str,
+        recipients: list[CampaignRecipient | dict[str, Any]],
+        name: str | None = None,
+    ) -> Campaign:
+        """Create a new outbound call campaign asynchronously."""
+        parsed_recipients = [
+            r.model_dump() if isinstance(r, CampaignRecipient) else r
+            for r in recipients
+        ]
+        payload: dict[str, Any] = {
+            "assistant_id": assistant_id,
+            "recipients": parsed_recipients,
+        }
+        if name:
+            payload["name"] = name
+
+        data = await self._client._transport.request("POST", "/v1/ringing/campaigns", json_data=payload)
+        return Campaign.model_validate(data)
+
+    async def get_campaign(self, campaign_id: str | int) -> Campaign:
+        """Retrieve details of a specific campaign asynchronously."""
+        data = await self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}")
+        return Campaign.model_validate(data)
+
+    async def delete_campaign(self, campaign_id: str | int) -> None:
+        """Delete a campaign by ID asynchronously."""
+        await self._client._transport.request("DELETE", f"/v1/ringing/campaigns/{campaign_id}")
+
+    async def launch_campaign(self, campaign_id: str | int) -> Campaign:
+        """Start or schedule execution of a campaign asynchronously."""
+        data = await self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/launch")
+        return Campaign.model_validate(data)
+
+    async def pause_campaign(self, campaign_id: str | int) -> Campaign:
+        """Pause an active campaign asynchronously."""
+        data = await self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/pause")
+        return Campaign.model_validate(data)
+
+    async def resume_campaign(self, campaign_id: str | int) -> Campaign:
+        """Resume a paused campaign asynchronously."""
+        data = await self._client._transport.request("POST", f"/v1/ringing/campaigns/{campaign_id}/resume")
+        return Campaign.model_validate(data)
+
+    async def get_campaign_statistics(self, campaign_id: str | int) -> CampaignStatistics:
+        """Retrieve aggregated statistics for a specific campaign asynchronously."""
+        data = await self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}/statistics")
+        return CampaignStatistics.model_validate(data)
+
+    async def list_campaign_calls(self, campaign_id: str | int) -> list[CallRecord]:
+        """Fetch all call records belonging to a campaign asynchronously."""
+        data = await self._client._transport.request("GET", f"/v1/ringing/campaigns/{campaign_id}/calls")
+        items = data if isinstance(data, list) else data.get("data", [])
+        return [CallRecord.model_validate(item) for item in items]
+
+    async def get_call(self, call_id: str | int) -> CallRecord:
+        """Retrieve details of an individual call record asynchronously."""
+        data = await self._client._transport.request("GET", f"/v1/ringing/calls/{call_id}")
+        return CallRecord.model_validate(data)
+
+    async def get_call_recording(self, call_id: str | int) -> RecordingInfo:
+        """Retrieve the audio recording link and metadata for a specific call asynchronously."""
+        data = await self._client._transport.request("GET", f"/v1/ringing/calls/{call_id}/recording")
+        return RecordingInfo.model_validate(data)

callaider/webhooks.py

@@ -0,0 +1,40 @@
+import json
+from typing import Any, Union
+from callaider._models import WebhookEvent
+from callaider.exceptions import CallaiderError
+
+
+class WebhookParsingError(CallaiderError):
+    """Raised when an incoming webhook payload cannot be parsed."""
+    pass
+
+
+class Webhooks:
+    """Helper utilities for parsing and verifying Callaider webhooks."""
+
+    @staticmethod
+    def construct_event(
+        payload: Union[str, bytes, dict[str, Any]],
+        *,
+        secret: str | None = None,  # Reserved for signature verification if HMAC is used
+    ) -> WebhookEvent:
+        """Parse raw incoming HTTP payload into a strongly-typed WebhookEvent.
+
+        :param payload: Raw request body (bytes, str or parsed dict).
+        :param secret: Optional webhook signing secret.
+        :raises WebhookParsingError: If payload is invalid JSON or does not match schema.
+        :return: Validated WebhookEvent object.
+        """
+        try:
+            if isinstance(payload, (bytes, bytearray)):
+                data = json.loads(payload.decode("utf-8"))
+            elif isinstance(payload, str):
+                data = json.loads(payload)
+            elif isinstance(payload, dict):
+                data = payload
+            else:
+                raise WebhookParsingError(f"Unsupported payload type: {type(payload)}")
+
+            return WebhookEvent.model_validate(data)
+        except Exception as exc:
+            raise WebhookParsingError(f"Failed to parse webhook event: {exc}") from exc

callaider-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: callaider
+Version: 0.1.0
+Summary: Python SDK for Callaider AI Voice Platform
+Project-URL: Homepage, https://github.com/astatdeglebantiy/callaider-sdk-python
+Author-email: AstatdeGlebantiy <glebsh2chko@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest-asyncio>=0.23.0
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: respx>=0.21.0
+Description-Content-Type: text/markdown
+
+# Callaider Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/callaider.svg)](https://pypi.org/project/callaider/)
+[![Python versions](https://img.shields.io/pypi/pyversions/callaider.svg)](https://pypi.org/project/callaider/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python client library for the [Callaider](https://callaider.ai) AI voice calling and conversational platform.
+
+Built on top of the [Callaider OpenAPI 3.0.3 specification](https://github.com/NBM-Labs/callaider_openapi).
+
+---
+
+## Features
+
+- ⚡ **Sync & Async clients** built on modern `httpx`.
+- 🛡️ **Fully typed** request/response models with Pydantic v2.
+- 🔄 **Automatic retries** with exponential backoff on 429/5xx errors.
+- 📞 **Complete Ringing API support**: Campaigns, batch calls, recordings, and statistics.
+- 🤖 **External Conversation Bridge**: Direct AI assistant messaging integration (ideal for Telegram bots).
+- 🪝 **Built-in Webhooks parser**: Typed events parsing for callback handling.
+
+---
+
+## Installation
+
+```bash
+pip install callaider
+```
+
+Or using `uv`:
+
+```bash
+uv add callaider
+```
+
+---
+
+## Quickstart
+
+### Synchronous Usage
+
+```python
+from callaider import Callaider
+
+client = Callaider(api_key="your_api_key_here")
+
+# 1. Check API status
+health = client.health()
+print(f"API status: {health.status}")
+
+# 2. Create an automated call campaign
+campaign = client.ringing.create_campaign(
+    assistant_id="asst_sales_01",
+    recipients=[
+        {"phone": "+380501234567", "name": "Alex"}
+    ],
+    name="VIP Outreach Campaign"
+)
+print(f"Created campaign #{campaign.id} with status: {campaign.status}")
+
+# 3. Launch the campaign
+client.ringing.launch_campaign(campaign.id)
+```
+
+### Asynchronous Usage (FastAPI, Asyncio, Telegram Bots)
+
+```python
+import asyncio
+from callaider import AsyncCallaider
+
+async def main():
+    async with AsyncCallaider(api_key="your_api_key_here") as client:
+        # Send a message to AI assistant bridge
+        response = await client.assistants.send_message(
+            assistant_id="asst_support_01",
+            external_conversation_id="telegram_user_12345",
+            message="Hello! I need help with my order."
+        )
+        print("AI Response:", response.text)
+
+asyncio.run(main())
+```
+
+---
+
+## Webhooks Handling
+
+Easily parse incoming Callaider webhook payloads in FastAPI or Flask:
+
+```python
+from fastapi import FastAPI, Request
+from callaider import Webhooks
+
+app = FastAPI()
+
+@app.post("/webhooks/callaider")
+async def handle_webhook(request: Request):
+    payload = await request.body()
+    event = Webhooks.construct_event(payload)
+
+    if event.event == "call.completed":
+        print(f"Call {event.data.call_id} finished. Duration: {event.data.duration_seconds}s")
+        print(f"Audio recording: {event.data.recording_url}")
+
+    return {"status": "ok"}
+```
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/astatdeglebantiy/callaider-python.git
+cd callaider-python
+
+# Install dependencies with uv
+uv sync --all-extras
+
+# Run unit tests
+uv run pytest
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

callaider-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+callaider/__init__.py,sha256=4CUuEgT4EC6tfI8WAmZPZj7MwvU3r2VPEplv_lPebZ0,600
+callaider/_base_client.py,sha256=HN6ZHkWIJKi4ynnzKGh_G8PkvmCBVAjfdoKCHJnFBM8,7147
+callaider/_client.py,sha256=3nhI8-VLNcnuojZ2pG4bDKWTmtIzcODp7bVM6WPpvYU,3344
+callaider/_constants.py,sha256=ThJNLsxDcoCsqRuS_PclGE0w6euRtqrKMY5u5LA7SOw,134
+callaider/_models.py,sha256=5OeBqB0UukCkJicVh601W00m8-Z2MVoDKurln96wGkQ,4198
+callaider/_streaming.py,sha256=Fg5urQlLBlqPQCmcR1OEMPGE_uaCLToQW5qEqso6Gi4,4099
+callaider/exceptions.py,sha256=4eKAHoo5OuIJd1ybIsss7irxpCs6wSidWaz83dnnOXw,1256
+callaider/webhooks.py,sha256=nzHJNYcS7JOFUgmyrbG-tVG7Is8wH4-LYUHJsYtREuU,1492
+callaider/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+callaider/resources/assistants.py,sha256=SHGZXWhntMbMT6VEJSkSTU84_ay4wFSVl-Fpjx6GlB4,3443
+callaider/resources/ringing.py,sha256=nOvRiw0UYlDkCVNOyYj3lnj3B7GV0vpG5_zGomi97yY,7937
+callaider-0.1.0.dist-info/METADATA,sha256=ejzmdIoa-y12s2eab2qpwDP-I6tYq5JXX6_QvmSoLsQ,3761
+callaider-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+callaider-0.1.0.dist-info/licenses/LICENSE,sha256=KDKJENJgzihiZEqAmD8Bp59OY9Cyn0fA6toKkninS7g,1061
+callaider-0.1.0.dist-info/RECORD,,

callaider-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

callaider-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gleb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.