agentphone 0.1.0__py3-none-any.whl

agentphone/__init__.py

@@ -0,0 +1,78 @@
+"""
+AgentPhone Python SDK
+
+Give your AI agents phone numbers, SMS, and voice calls.
+
+Usage::
+
+    from agentphone import AgentPhone
+
+    client = AgentPhone(api_key="your-api-key")
+    number = client.numbers.buy(country="US")
+    call = client.calls.make_conversation(
+        agent_id="...",
+        to_number="+14155551234",
+        topic="You are a friendly assistant. Ask about their day.",
+    )
+"""
+
+from .async_client import AsyncAgentPhone
+from .client import AgentPhone
+from ._http import AgentPhoneError, AuthenticationError, NotFoundError, RateLimitError
+from .models import (
+    Agent,
+    AgentList,
+    AgentNumber,
+    Call,
+    CallList,
+    CallTranscript,
+    Conversation,
+    ConversationList,
+    ConversationMessage,
+    Message,
+    MessageList,
+    PhoneNumber,
+    PhoneNumberList,
+    Webhook,
+    WebhookDelivery,
+    WebhookEvent,
+    WebhookEventData,
+    WebhookHistoryItem,
+)
+from .webhook import WebhookVerificationError, construct_event, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "AgentPhone",
+    "AsyncAgentPhone",
+    # Errors
+    "AgentPhoneError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "WebhookVerificationError",
+    # Webhook helpers
+    "verify_webhook",
+    "construct_event",
+    # Models
+    "Agent",
+    "AgentList",
+    "AgentNumber",
+    "Call",
+    "CallList",
+    "CallTranscript",
+    "Conversation",
+    "ConversationList",
+    "ConversationMessage",
+    "Message",
+    "MessageList",
+    "PhoneNumber",
+    "PhoneNumberList",
+    "Webhook",
+    "WebhookDelivery",
+    "WebhookEvent",
+    "WebhookEventData",
+    "WebhookHistoryItem",
+]

agentphone/_http.py

@@ -0,0 +1,44 @@
+"""
+Shared HTTP logic for sync and async clients.
+"""
+
+from __future__ import annotations
+
+DEFAULT_BASE_URL = "https://api.agentphone.to"
+
+
+class AgentPhoneError(Exception):
+    """Raised when the AgentPhone API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"AgentPhone API error {status}: {message}")
+
+
+class AuthenticationError(AgentPhoneError):
+    pass
+
+
+class NotFoundError(AgentPhoneError):
+    pass
+
+
+class RateLimitError(AgentPhoneError):
+    pass
+
+
+def _raise_for_status(status: int, text: str) -> None:
+    try:
+        import json as _json
+        detail = _json.loads(text).get("detail") or _json.loads(text).get("message") or text
+    except Exception:
+        detail = text
+
+    if status == 401:
+        raise AuthenticationError(status, detail)
+    if status == 404:
+        raise NotFoundError(status, detail)
+    if status == 429:
+        raise RateLimitError(status, detail)
+    raise AgentPhoneError(status, detail)

agentphone/async_client.py

@@ -0,0 +1,210 @@
+"""
+Asynchronous AgentPhone client (requires httpx).
+"""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+from ._http import DEFAULT_BASE_URL, _raise_for_status
+from .models import (
+    Agent,
+    AgentList,
+    Call,
+    CallList,
+    Conversation,
+    ConversationList,
+    MessageList,
+    PhoneNumber,
+    PhoneNumberList,
+    Webhook,
+    WebhookDelivery,
+)
+
+
+class _AsyncResource:
+    def __init__(self, client: "AsyncAgentPhone") -> None:
+        self._client = client
+
+    async def _get(self, path: str, **params) -> dict:
+        return await self._client._request("GET", path, params=params or None)
+
+    async def _post(self, path: str, **body) -> dict:
+        return await self._client._request(
+            "POST", path, json={k: v for k, v in body.items() if v is not None}
+        )
+
+    async def _delete(self, path: str) -> dict:
+        return await self._client._request("DELETE", path)
+
+
+class AsyncNumbersResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> PhoneNumberList:
+        return PhoneNumberList.from_dict(await self._get("/v1/numbers", limit=limit, offset=offset))
+
+    async def buy(self, country: str = "US", agent_id: Optional[str] = None) -> PhoneNumber:
+        return PhoneNumber.from_dict(await self._post("/v1/numbers", country=country, agentId=agent_id))
+
+    async def release(self, number_id: str) -> dict:
+        return await self._delete(f"/v1/numbers/{number_id}")
+
+    async def get_messages(self, number_id: str, limit: int = 50) -> MessageList:
+        return MessageList.from_dict(await self._get(f"/v1/numbers/{number_id}/messages", limit=limit))
+
+
+class AsyncAgentsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> AgentList:
+        return AgentList.from_dict(await self._get("/v1/agents", limit=limit, offset=offset))
+
+    async def create(self, name: str, description: Optional[str] = None) -> Agent:
+        return Agent.from_dict(await self._post("/v1/agents", name=name, description=description))
+
+    async def get(self, agent_id: str) -> Agent:
+        return Agent.from_dict(await self._get(f"/v1/agents/{agent_id}"))
+
+    async def attach_number(self, agent_id: str, number_id: str) -> dict:
+        return await self._post(f"/v1/agents/{agent_id}/numbers", numberId=number_id)
+
+
+class AsyncCallsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> CallList:
+        return CallList.from_dict(await self._get("/v1/calls", limit=limit, offset=offset))
+
+    async def get(self, call_id: str) -> Call:
+        return Call.from_dict(await self._get(f"/v1/calls/{call_id}"))
+
+    async def make(
+        self,
+        agent_id: str,
+        to_number: str,
+        initial_greeting: Optional[str] = None,
+    ) -> Call:
+        return Call.from_dict(
+            await self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                initialGreeting=initial_greeting,
+            )
+        )
+
+    async def make_conversation(
+        self,
+        agent_id: str,
+        to_number: str,
+        topic: str,
+        initial_greeting: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> Call:
+        return Call.from_dict(
+            await self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                systemPrompt=topic,
+                initialGreeting=initial_greeting,
+                model=model,
+            )
+        )
+
+
+class AsyncConversationsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> ConversationList:
+        return ConversationList.from_dict(await self._get("/v1/conversations", limit=limit, offset=offset))
+
+    async def get(self, conversation_id: str, message_limit: int = 50) -> Conversation:
+        return Conversation.from_dict(
+            await self._get(f"/v1/conversations/{conversation_id}", message_limit=message_limit)
+        )
+
+
+class AsyncWebhooksResource(_AsyncResource):
+    async def get(self) -> Optional[Webhook]:
+        data = await self._get("/v1/webhooks")
+        return Webhook.from_dict(data) if data else None
+
+    async def set(self, url: str, context_limit: Optional[int] = None) -> Webhook:
+        return Webhook.from_dict(await self._post("/v1/webhooks", url=url, contextLimit=context_limit))
+
+    async def delete(self) -> dict:
+        return await self._delete("/v1/webhooks")
+
+    async def list_deliveries(self, limit: int = 50) -> list[WebhookDelivery]:
+        data = await self._get("/v1/webhooks/deliveries", limit=limit)
+        return [WebhookDelivery.from_dict(d) for d in data]
+
+    async def test(self) -> dict:
+        return await self._post("/v1/webhooks/test")
+
+
+class AsyncAgentPhone:
+    """
+    Asynchronous AgentPhone client.
+
+    Requires: pip install agentphone[async]
+
+    Example::
+
+        from agentphone import AsyncAgentPhone
+
+        async with AsyncAgentPhone(api_key="your-api-key") as client:
+            number = await client.numbers.buy(country="US")
+            call = await client.calls.make_conversation(
+                agent_id="...",
+                to_number="+14155551234",
+                topic="You are a friendly assistant.",
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError:
+            raise ImportError(
+                "The async client requires httpx. Install it with: pip install agentphone[async]"
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = _httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "agentphone-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+
+        self.numbers = AsyncNumbersResource(self)
+        self.agents = AsyncAgentsResource(self)
+        self.calls = AsyncCallsResource(self)
+        self.conversations = AsyncConversationsResource(self)
+        self.webhooks = AsyncWebhooksResource(self)
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:  # type: ignore[override]
+        url = f"{self.base_url}{path}"
+        resp = await self._client.request(method, url, **kwargs)
+
+        if not resp.is_success:
+            _raise_for_status(resp.status_code, resp.text)
+
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncAgentPhone":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

agentphone/client.py

@@ -0,0 +1,238 @@
+"""
+Synchronous AgentPhone client.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from ._http import DEFAULT_BASE_URL, _raise_for_status
+from .models import (
+    Agent,
+    AgentList,
+    Call,
+    CallList,
+    Conversation,
+    ConversationList,
+    MessageList,
+    PhoneNumber,
+    PhoneNumberList,
+    Webhook,
+    WebhookDelivery,
+)
+
+
+class _Resource:
+    def __init__(self, client: "AgentPhone") -> None:
+        self._client = client
+
+    def _get(self, path: str, **params) -> dict:
+        return self._client._request("GET", path, params=params or None)
+
+    def _post(self, path: str, **body) -> dict:
+        return self._client._request("POST", path, json={k: v for k, v in body.items() if v is not None})
+
+    def _delete(self, path: str) -> dict:
+        return self._client._request("DELETE", path)
+
+
+class NumbersResource(_Resource):
+    def list(self, limit: int = 20, offset: int = 0) -> PhoneNumberList:
+        """List all phone numbers."""
+        return PhoneNumberList.from_dict(self._get("/v1/numbers", limit=limit, offset=offset))
+
+    def buy(self, country: str = "US", area_code: Optional[str] = None, agent_id: Optional[str] = None) -> PhoneNumber:
+        """Purchase a new phone number. Optionally specify an area code (US/CA only)."""
+        return PhoneNumber.from_dict(self._post("/v1/numbers", country=country, areaCode=area_code, agentId=agent_id))
+
+    def release(self, number_id: str) -> dict:
+        """Release a phone number (irreversible)."""
+        return self._delete(f"/v1/numbers/{number_id}")
+
+    def get_messages(self, number_id: str, limit: int = 50) -> MessageList:
+        """Get SMS messages received on a number."""
+        return MessageList.from_dict(self._get(f"/v1/numbers/{number_id}/messages", limit=limit))
+
+
+class AgentsResource(_Resource):
+    def list(self, limit: int = 20, offset: int = 0) -> AgentList:
+        """List all agents."""
+        return AgentList.from_dict(self._get("/v1/agents", limit=limit, offset=offset))
+
+    def create(self, name: str, description: Optional[str] = None) -> Agent:
+        """Create a new agent."""
+        return Agent.from_dict(self._post("/v1/agents", name=name, description=description))
+
+    def get(self, agent_id: str) -> Agent:
+        """Get agent details including attached numbers."""
+        return Agent.from_dict(self._get(f"/v1/agents/{agent_id}"))
+
+    def attach_number(self, agent_id: str, number_id: str) -> dict:
+        """Attach a phone number to an agent."""
+        return self._post(f"/v1/agents/{agent_id}/numbers", numberId=number_id)
+
+
+class CallsResource(_Resource):
+    def list(self, limit: int = 20, offset: int = 0) -> CallList:
+        """List recent calls."""
+        return CallList.from_dict(self._get("/v1/calls", limit=limit, offset=offset))
+
+    def get(self, call_id: str) -> Call:
+        """Get call details and transcript."""
+        return Call.from_dict(self._get(f"/v1/calls/{call_id}"))
+
+    def make(
+        self,
+        agent_id: str,
+        to_number: str,
+        initial_greeting: Optional[str] = None,
+    ) -> Call:
+        """
+        Make an outbound call (webhook-based).
+
+        The agent must have a webhook configured to handle the conversation.
+        """
+        return Call.from_dict(
+            self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                initialGreeting=initial_greeting,
+            )
+        )
+
+    def make_conversation(
+        self,
+        agent_id: str,
+        to_number: str,
+        topic: str,
+        initial_greeting: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> Call:
+        """
+        Make an outbound call with a built-in LLM conversation.
+
+        No webhook required. The AI handles the full conversation
+        based on the topic/system prompt.
+        """
+        return Call.from_dict(
+            self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                systemPrompt=topic,
+                initialGreeting=initial_greeting,
+                model=model,
+            )
+        )
+
+
+class ConversationsResource(_Resource):
+    def list(self, limit: int = 20, offset: int = 0) -> ConversationList:
+        """List SMS conversations."""
+        return ConversationList.from_dict(self._get("/v1/conversations", limit=limit, offset=offset))
+
+    def get(self, conversation_id: str, message_limit: int = 50) -> Conversation:
+        """Get a conversation with full message history."""
+        return Conversation.from_dict(
+            self._get(f"/v1/conversations/{conversation_id}", message_limit=message_limit)
+        )
+
+
+class WebhooksResource(_Resource):
+    def get(self) -> Optional[Webhook]:
+        """Get the configured webhook endpoint."""
+        data = self._get("/v1/webhooks")
+        return Webhook.from_dict(data) if data else None
+
+    def set(self, url: str, context_limit: Optional[int] = None) -> Webhook:
+        """
+        Register or update the webhook URL.
+
+        Args:
+            url: Publicly accessible HTTPS URL.
+            context_limit: Number of recent messages to include in payloads (0-50).
+        """
+        return Webhook.from_dict(self._post("/v1/webhooks", url=url, contextLimit=context_limit))
+
+    def delete(self) -> dict:
+        """Remove the webhook configuration."""
+        return self._delete("/v1/webhooks")
+
+    def list_deliveries(self, limit: int = 50) -> list[WebhookDelivery]:
+        """Get recent webhook delivery attempts."""
+        data = self._get("/v1/webhooks/deliveries", limit=limit)
+        return [WebhookDelivery.from_dict(d) for d in data]
+
+    def test(self) -> dict:
+        """Send a test event to the configured webhook."""
+        return self._post("/v1/webhooks/test")
+
+
+class AgentPhone:
+    """
+    Synchronous AgentPhone client.
+
+    Example::
+
+        from agentphone import AgentPhone
+
+        client = AgentPhone(api_key="your-api-key")
+
+        # Buy a number
+        number = client.numbers.buy(country="US")
+
+        # Make a conversation call
+        call = client.calls.make_conversation(
+            agent_id="...",
+            to_number="+14155551234",
+            topic="You are a friendly assistant. Ask about their day.",
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "agentphone-python/0.1.0",
+            }
+        )
+
+        self.numbers = NumbersResource(self)
+        self.agents = AgentsResource(self)
+        self.calls = CallsResource(self)
+        self.conversations = ConversationsResource(self)
+        self.webhooks = WebhooksResource(self)
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self.base_url}{path}"
+        resp = self._session.request(method, url, timeout=self.timeout, **kwargs)
+
+        if not resp.ok:
+            _raise_for_status(resp.status_code, resp.text)
+
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "AgentPhone":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()

agentphone/models.py

@@ -0,0 +1,362 @@
+"""
+AgentPhone response models.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# --- Numbers ---
+
+@dataclass
+class PhoneNumber:
+    id: str
+    phone_number: str
+    country: str
+    status: str
+    agent_id: Optional[str]
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PhoneNumber":
+        return cls(
+            id=d["id"],
+            phone_number=d["phoneNumber"],
+            country=d["country"],
+            status=d["status"],
+            agent_id=d.get("agentId"),
+            created_at=d["createdAt"],
+        )
+
+
+@dataclass
+class PhoneNumberList:
+    data: list[PhoneNumber]
+    has_more: bool
+    total: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PhoneNumberList":
+        return cls(
+            data=[PhoneNumber.from_dict(n) for n in d["data"]],
+            has_more=d["hasMore"],
+            total=d["total"],
+        )
+
+
+# --- Messages ---
+
+@dataclass
+class Message:
+    id: str
+    from_number: str
+    to_number: str
+    body: str
+    received_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Message":
+        return cls(
+            id=d["id"],
+            from_number=d["from"],
+            to_number=d["to"],
+            body=d["body"],
+            received_at=d["receivedAt"],
+        )
+
+
+@dataclass
+class MessageList:
+    data: list[Message]
+    has_more: bool
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MessageList":
+        return cls(
+            data=[Message.from_dict(m) for m in d["data"]],
+            has_more=d["hasMore"],
+        )
+
+
+# --- Agents ---
+
+@dataclass
+class AgentNumber:
+    id: str
+    phone_number: str
+    status: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentNumber":
+        return cls(id=d["id"], phone_number=d["phoneNumber"], status=d["status"])
+
+
+@dataclass
+class Agent:
+    id: str
+    name: str
+    description: Optional[str]
+    created_at: str
+    numbers: list[AgentNumber] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Agent":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            description=d.get("description"),
+            created_at=d["createdAt"],
+            numbers=[AgentNumber.from_dict(n) for n in d.get("numbers", [])],
+        )
+
+
+@dataclass
+class AgentList:
+    data: list[Agent]
+    has_more: bool
+    total: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentList":
+        return cls(
+            data=[Agent.from_dict(a) for a in d["data"]],
+            has_more=d.get("hasMore", False),
+            total=d["total"],
+        )
+
+
+# --- Calls ---
+
+@dataclass
+class CallTranscript:
+    id: str
+    transcript: str
+    response: Optional[str]
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CallTranscript":
+        return cls(
+            id=d["id"],
+            transcript=d["transcript"],
+            response=d.get("response"),
+            created_at=d["createdAt"],
+        )
+
+
+@dataclass
+class Call:
+    id: str
+    from_number: str
+    to_number: str
+    direction: str
+    status: str
+    started_at: str
+    ended_at: Optional[str]
+    agent_id: Optional[str]
+    transcripts: list[CallTranscript] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Call":
+        return cls(
+            id=d["id"],
+            from_number=d["fromNumber"],
+            to_number=d["toNumber"],
+            direction=d["direction"],
+            status=d["status"],
+            started_at=d["startedAt"],
+            ended_at=d.get("endedAt"),
+            agent_id=d.get("agentId"),
+            transcripts=[CallTranscript.from_dict(t) for t in d.get("transcripts", [])],
+        )
+
+
+@dataclass
+class CallList:
+    data: list[Call]
+    has_more: bool
+    total: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CallList":
+        return cls(
+            data=[Call.from_dict(c) for c in d["data"]],
+            has_more=d["hasMore"],
+            total=d["total"],
+        )
+
+
+# --- Conversations ---
+
+@dataclass
+class ConversationMessage:
+    id: str
+    from_number: str
+    to_number: str
+    body: str
+    received_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ConversationMessage":
+        return cls(
+            id=d["id"],
+            from_number=d["from"],
+            to_number=d["to"],
+            body=d["body"],
+            received_at=d["receivedAt"],
+        )
+
+
+@dataclass
+class Conversation:
+    id: str
+    phone_number: str
+    participant: str
+    last_message_at: Optional[str]
+    message_count: int
+    agent_id: Optional[str]
+    messages: list[ConversationMessage] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Conversation":
+        return cls(
+            id=d["id"],
+            phone_number=d["phoneNumber"],
+            participant=d.get("participant") or d.get("contactNumber", ""),
+            last_message_at=d.get("lastMessageAt"),
+            message_count=d.get("messageCount", 0),
+            agent_id=d.get("agentId"),
+            messages=[ConversationMessage.from_dict(m) for m in d.get("messages", [])],
+        )
+
+
+@dataclass
+class ConversationList:
+    data: list[Conversation]
+    has_more: bool
+    total: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ConversationList":
+        return cls(
+            data=[Conversation.from_dict(c) for c in d["data"]],
+            has_more=d["hasMore"],
+            total=d["total"],
+        )
+
+
+# --- Webhooks ---
+
+@dataclass
+class Webhook:
+    id: str
+    url: str
+    secret: str
+    status: str
+    context_limit: int
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Webhook":
+        return cls(
+            id=d["id"],
+            url=d["url"],
+            secret=d["secret"],
+            status=d["status"],
+            context_limit=d["contextLimit"],
+            created_at=d["createdAt"],
+        )
+
+
+@dataclass
+class WebhookDelivery:
+    id: str
+    message_id: str
+    status: str
+    http_status: Optional[int]
+    error_message: Optional[str]
+    attempt_count: int
+    last_attempt_at: Optional[str]
+    next_retry_at: Optional[str]
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookDelivery":
+        return cls(
+            id=d["id"],
+            message_id=d["messageId"],
+            status=d["status"],
+            http_status=d.get("httpStatus"),
+            error_message=d.get("errorMessage"),
+            attempt_count=d["attemptCount"],
+            last_attempt_at=d.get("lastAttemptAt"),
+            next_retry_at=d.get("nextRetryAt"),
+            created_at=d["createdAt"],
+        )
+
+
+# --- Webhook event payload ---
+
+@dataclass
+class WebhookHistoryItem:
+    content: str
+    direction: str
+    channel: str
+    at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookHistoryItem":
+        return cls(
+            content=d["content"],
+            direction=d["direction"],
+            channel=d["channel"],
+            at=d["at"],
+        )
+
+
+@dataclass
+class WebhookEventData:
+    conversation_id: Optional[str]
+    number_id: Optional[str]
+    from_number: str
+    to_number: str
+    message: str
+    direction: str
+    received_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookEventData":
+        return cls(
+            conversation_id=d.get("conversationId"),
+            number_id=d.get("numberId"),
+            from_number=d["from"],
+            to_number=d["to"],
+            message=d["message"],
+            direction=d["direction"],
+            received_at=d["receivedAt"],
+        )
+
+
+@dataclass
+class WebhookEvent:
+    event: str
+    channel: str
+    timestamp: str
+    agent_id: Optional[str]
+    data: WebhookEventData
+    recent_history: list[WebhookHistoryItem] = field(default_factory=list)
+    conversation_state: Optional[dict] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookEvent":
+        return cls(
+            event=d["event"],
+            channel=d["channel"],
+            timestamp=d["timestamp"],
+            agent_id=d.get("agentId"),
+            data=WebhookEventData.from_dict(d["data"]),
+            recent_history=[WebhookHistoryItem.from_dict(h) for h in d.get("recentHistory", [])],
+            conversation_state=d.get("conversationState"),
+        )

agentphone/webhook.py

@@ -0,0 +1,81 @@
+"""
+Webhook signature verification.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Union
+
+from .models import WebhookEvent
+
+
+class WebhookVerificationError(Exception):
+    pass
+
+
+def verify_webhook(
+    payload: Union[bytes, str],
+    signature: str,
+    secret: str,
+) -> None:
+    """
+    Verify an incoming AgentPhone webhook signature.
+
+    Args:
+        payload: Raw request body (bytes or str).
+        signature: Value of the X-Webhook-Signature header (e.g. "sha256=abc123").
+        secret: Your webhook secret from client.webhooks.get().secret
+
+    Raises:
+        WebhookVerificationError: If the signature is invalid.
+
+    Example::
+
+        from agentphone import verify_webhook, WebhookVerificationError
+
+        @app.post("/webhook")
+        async def handle(request: Request):
+            body = await request.body()
+            sig = request.headers["X-Webhook-Signature"]
+            try:
+                verify_webhook(body, sig, secret="whsec_...")
+            except WebhookVerificationError:
+                return Response(status_code=403)
+            ...
+    """
+    if isinstance(payload, str):
+        payload = payload.encode()
+
+    expected = "sha256=" + hmac.new(
+        secret.encode(), payload, hashlib.sha256
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected, signature):
+        raise WebhookVerificationError("Invalid webhook signature")
+
+
+def construct_event(
+    payload: Union[bytes, str],
+    signature: str,
+    secret: str,
+) -> WebhookEvent:
+    """
+    Verify the webhook signature and parse the event payload.
+
+    Returns a WebhookEvent on success, raises WebhookVerificationError if invalid.
+
+    Example::
+
+        event = construct_event(body, sig, secret="whsec_...")
+        if event.event == "agent.message":
+            print(event.data.message)
+    """
+    verify_webhook(payload, signature, secret)
+
+    if isinstance(payload, bytes):
+        payload = payload.decode()
+
+    return WebhookEvent.from_dict(json.loads(payload))

agentphone-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: agentphone
+Version: 0.1.0
+Summary: AgentPhone Python SDK — give your AI agents phone numbers, SMS, and voice calls
+Project-URL: Homepage, https://agentphone.to
+Project-URL: Repository, https://github.com/AgentPhone-AI/agentphone-python
+Project-URL: Documentation, https://docs.agentphone.to
+Author-email: AgentPhone <hello@agentphone.to>
+License: MIT
+Keywords: agentphone,ai,phone,sms,telephony,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentPhone Python SDK
+
+Official Python SDK for [AgentPhone](https://agentphone.to) — give your AI agents real phone numbers, SMS, and voice calls.
+
+## Installation
+
+```bash
+pip install agentphone
+```
+
+For async support:
+
+```bash
+pip install agentphone[async]
+```
+
+## Quickstart
+
+```python
+from agentphone import AgentPhone
+
+client = AgentPhone(api_key="your-api-key")
+
+# Create an agent and buy a number
+agent = client.agents.create(name="My Agent")
+number = client.numbers.buy(country="US", agent_id=agent.id)
+
+# Make an AI conversation call — no webhook needed
+call = client.calls.make_conversation(
+    agent_id=agent.id,
+    to_number="+14155551234",
+    topic="You are a friendly assistant. Ask about their day.",
+    initial_greeting="Hey! This is an AI calling from AgentPhone.",
+)
+print(call.status)  # registered
+```
+
+## Async
+
+```python
+from agentphone import AsyncAgentPhone
+
+async with AsyncAgentPhone(api_key="your-api-key") as client:
+    numbers = await client.numbers.list()
+    call = await client.calls.make_conversation(...)
+```
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.numbers` | `list()`, `buy()`, `release()`, `get_messages()` |
+| `client.agents` | `list()`, `create()`, `get()`, `attach_number()` |
+| `client.calls` | `list()`, `get()`, `make()`, `make_conversation()` |
+| `client.conversations` | `list()`, `get()` |
+| `client.webhooks` | `get()`, `set()`, `delete()`, `list_deliveries()`, `test()` |
+
+## Webhook Verification
+
+```python
+from agentphone import construct_event, WebhookVerificationError
+
+@app.post("/webhook")
+async def handle(request: Request):
+    body = await request.body()
+    sig = request.headers["X-Webhook-Signature"]
+    try:
+        event = construct_event(body, sig, secret="whsec_...")
+    except WebhookVerificationError:
+        return Response(status_code=403)
+
+    if event.event == "agent.message":
+        print(f"SMS from {event.data.from_number}: {event.data.message}")
+```
+
+## Error Handling
+
+```python
+from agentphone import AgentPhoneError, AuthenticationError, NotFoundError
+
+try:
+    call = client.calls.get("bad-id")
+except NotFoundError:
+    print("Call not found")
+except AgentPhoneError as e:
+    print(f"API error {e.status}: {e.message}")
+```
+
+## Publishing to PyPI
+
+1. **Install build tools** (one-time):
+   ```bash
+   pip install hatch twine
+   ```
+
+2. **Build** the package:
+   ```bash
+   hatch build
+   ```
+   This creates a `dist/` folder with the `.tar.gz` and `.whl` files.
+
+3. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   You'll be prompted for your PyPI credentials. To use an API token instead:
+   ```bash
+   twine upload dist/* -u __token__ -p pypi-your-token-here
+   ```
+
+4. **Publishing a new version** — bump the version in `pyproject.toml` first:
+   ```toml
+   version = "0.1.1"
+   ```
+   Then rebuild and upload:
+   ```bash
+   hatch build && twine upload dist/*
+   ```
+
+## Requirements
+
+- Python 3.9+
+- `requests` (sync client)
+- `httpx` (async client, optional)
+
+## Links
+
+- [AgentPhone Dashboard](https://agentphone.to)
+- [MCP Server](https://github.com/AgentPhone-AI/agentphone-mcp)
+- [Node.js SDK](https://github.com/AgentPhone-AI/agentphone-node)

agentphone-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentphone/__init__.py,sha256=RbW0R7PMIuvu1CvSIxucuQmISdHiQn9sVZdkTBpmJyQ,1653
+agentphone/_http.py,sha256=MKxDv0UBuWxnJWtcr1Xyg5-jLq2pUxK0jNYbjg_eBFc,1059
+agentphone/async_client.py,sha256=bKs9CTmnJWnBDJV0wElPXklJy-VSJlw9R-pIYbfjmmM,6978
+agentphone/client.py,sha256=VvkrxZd52aTDNUJAg7iaSNKxneWwWPAcWNF1OPdlSaI,7705
+agentphone/models.py,sha256=6bNICQZThDoT3r8RK93bVo3lHrw4WH4t7bALpDPb5zI,8341
+agentphone/webhook.py,sha256=45Nig-cxKFOJorl1K7gK0njfIxMT4cdvoQ-QAUHee8Y,2041
+agentphone-0.1.0.dist-info/METADATA,sha256=42rZUpb2bLSXryDy2yYGi4T641Duv_mtNRgRDBpVYSo,4464
+agentphone-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentphone-0.1.0.dist-info/RECORD,,

agentphone-0.1.0.dist-info/WHEEL

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