dial-sdk 0.6.2__tar.gz

dial_sdk-0.6.2/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/

dial_sdk-0.6.2/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: dial-sdk
+Version: 0.6.2
+Summary: Official Dial SDK — phone numbers, SMS, WhatsApp, and voice calls for AI agents
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pubnub>=7
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# dial-sdk
+
+Official Python SDK for [Dial](https://getdial.ai) — phone numbers, SMS, WhatsApp, and voice calls for AI agents.
+
+## Install
+
+```bash
+pip install dial-sdk
+# or
+uv add dial-sdk
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+The client is async. Construct it with a `DialConfig`, then call its methods inside an `async with` block:
+
+```python
+import asyncio
+from dial_sdk import DialClient, DialConfig, SendMessageParams, MakeCallParams
+
+async def main():
+    async with DialClient(DialConfig(api_key="sk_live_...")) as dial:
+        # List your numbers
+        numbers = await dial.list_numbers()
+        from_id = numbers[0].id
+
+        # Send an SMS
+        await dial.send_message(SendMessageParams(
+            to="+15551234567",
+            from_number_id=from_id,
+            body="Hello from Dial",
+        ))
+
+        # Place an AI voice call
+        call = await dial.make_call(MakeCallParams(
+            to="+15551234567",
+            from_number_id=from_id,
+            outbound_instruction="You are a friendly assistant confirming an appointment.",
+        ))
+        print(call.id, call.status)
+
+asyncio.run(main())
+```
+
+`DialConfig.base_url` defaults to `https://getdial.ai`. Override it for local or self-hosted setups.
+
+## Live events
+
+Incoming messages and call transcripts stream via an async generator:
+
+```python
+async with DialClient(DialConfig(api_key="sk_live_...")) as dial:
+    async with dial.new_events_connection() as events:
+        async for event in events:
+            print(event)  # MessageEvent / CallEvent / CallTranscribed / ...
+```
+
+## Client methods
+
+| Method | Description |
+| --- | --- |
+| `list_numbers()` | List the phone numbers on your account |
+| `purchase_number(params)` | Buy a new number (`PurchaseNumberParams`) |
+| `set_number_properties(...)` | Update a number's nickname / inbound instruction |
+| `send_message(params)` | Send an SMS or WhatsApp message (`SendMessageParams`) |
+| `list_messages(...)` | List messages, optionally filtered |
+| `make_call(params)` | Place an outbound AI voice call (`MakeCallParams`) |
+| `list_calls(...)` | List calls, optionally filtered |
+| `get_call(call_id)` | Fetch a single call |
+| `new_events_connection()` | Open a live event stream |
+
+## Related
+
+- [`dial-langchain`](https://pypi.org/project/dial-langchain/) — these capabilities as LangChain tools.
+- [Documentation](https://docs.getdial.ai)

dial_sdk-0.6.2/README.md

@@ -0,0 +1,77 @@
+# dial-sdk
+
+Official Python SDK for [Dial](https://getdial.ai) — phone numbers, SMS, WhatsApp, and voice calls for AI agents.
+
+## Install
+
+```bash
+pip install dial-sdk
+# or
+uv add dial-sdk
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+The client is async. Construct it with a `DialConfig`, then call its methods inside an `async with` block:
+
+```python
+import asyncio
+from dial_sdk import DialClient, DialConfig, SendMessageParams, MakeCallParams
+
+async def main():
+    async with DialClient(DialConfig(api_key="sk_live_...")) as dial:
+        # List your numbers
+        numbers = await dial.list_numbers()
+        from_id = numbers[0].id
+
+        # Send an SMS
+        await dial.send_message(SendMessageParams(
+            to="+15551234567",
+            from_number_id=from_id,
+            body="Hello from Dial",
+        ))
+
+        # Place an AI voice call
+        call = await dial.make_call(MakeCallParams(
+            to="+15551234567",
+            from_number_id=from_id,
+            outbound_instruction="You are a friendly assistant confirming an appointment.",
+        ))
+        print(call.id, call.status)
+
+asyncio.run(main())
+```
+
+`DialConfig.base_url` defaults to `https://getdial.ai`. Override it for local or self-hosted setups.
+
+## Live events
+
+Incoming messages and call transcripts stream via an async generator:
+
+```python
+async with DialClient(DialConfig(api_key="sk_live_...")) as dial:
+    async with dial.new_events_connection() as events:
+        async for event in events:
+            print(event)  # MessageEvent / CallEvent / CallTranscribed / ...
+```
+
+## Client methods
+
+| Method | Description |
+| --- | --- |
+| `list_numbers()` | List the phone numbers on your account |
+| `purchase_number(params)` | Buy a new number (`PurchaseNumberParams`) |
+| `set_number_properties(...)` | Update a number's nickname / inbound instruction |
+| `send_message(params)` | Send an SMS or WhatsApp message (`SendMessageParams`) |
+| `list_messages(...)` | List messages, optionally filtered |
+| `make_call(params)` | Place an outbound AI voice call (`MakeCallParams`) |
+| `list_calls(...)` | List calls, optionally filtered |
+| `get_call(call_id)` | Fetch a single call |
+| `new_events_connection()` | Open a live event stream |
+
+## Related
+
+- [`dial-langchain`](https://pypi.org/project/dial-langchain/) — these capabilities as LangChain tools.
+- [Documentation](https://docs.getdial.ai)

dial_sdk-0.6.2/dial_sdk/__init__.py

@@ -0,0 +1,58 @@
+from .client import DialClient
+from .events import EventsConnection
+from .self_hosted import (
+    CallConnected,
+    Interrupt,
+    PingPong,
+    ReminderRequired,
+    Response,
+    ResponseRequired,
+    TranscriptItem,
+    TranscriptUpdate,
+    parse_dial_message,
+    serialize_server_message,
+    verify_dial_signature,
+)
+from .types import (
+    Call,
+    CallEvent,
+    CallStatus,
+    CallTranscribed,
+    DialConfig,
+    DialEvent,
+    MakeCallParams,
+    Message,
+    MessageEvent,
+    PhoneNumber,
+    PurchaseNumberParams,
+    SendMessageParams,
+)
+
+__all__ = [
+    "DialClient",
+    "EventsConnection",
+    "DialConfig",
+    "PurchaseNumberParams",
+    "SendMessageParams",
+    "MakeCallParams",
+    "PhoneNumber",
+    "Message",
+    "Call",
+    "CallStatus",
+    "CallEvent",
+    "MessageEvent",
+    "CallTranscribed",
+    "DialEvent",
+    # Self-Hosted protocol
+    "TranscriptItem",
+    "CallConnected",
+    "TranscriptUpdate",
+    "ResponseRequired",
+    "ReminderRequired",
+    "Response",
+    "Interrupt",
+    "PingPong",
+    "parse_dial_message",
+    "serialize_server_message",
+    "verify_dial_signature",
+]

dial_sdk-0.6.2/dial_sdk/client.py

@@ -0,0 +1,203 @@
+from typing import Any, Optional
+
+import httpx
+
+from .events import EventsConnection
+from .types import (
+    Call,
+    DialConfig,
+    MakeCallParams,
+    Message,
+    PhoneNumber,
+    PurchaseNumberParams,
+    SendMessageParams,
+)
+
+DEFAULT_BASE_URL = "https://getdial.ai"
+
+# Sentinel distinguishing "argument not provided" from None (which clears the field).
+_UNSET: Any = object()
+
+
+class DialClient:
+    def __init__(self, config: DialConfig):
+        self._base_url = config.base_url or DEFAULT_BASE_URL
+        self._api_key = config.api_key
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[dict] = None,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ):
+        response = await self._client.request(method, path, json=body, params=params, headers=headers)
+        if response.is_error:
+            raise Exception(f"Dial API error {response.status_code}: {response.text}")
+        return response.json()
+
+    @staticmethod
+    def _filters(number_id, direction, since) -> dict:
+        return {
+            k: v
+            for k, v in {"numberId": number_id, "direction": direction, "since": since}.items()
+            if v is not None
+        }
+
+    # ── Numbers ──────────────────────────────────────────────────
+
+    async def list_numbers(self) -> list[PhoneNumber]:
+        """`dial number list` — list the account's phone numbers."""
+        data = await self._request("GET", "/api/v1/numbers")
+        return [PhoneNumber.from_api(n) for n in data["numbers"]]
+
+    async def purchase_number(self, params: PurchaseNumberParams) -> PhoneNumber:
+        """`dial number purchase` — provision a new phone number."""
+        body: dict = {
+            "inboundInstruction": params.inbound_instruction,
+            "country": params.country,
+        }
+        if params.area_code:
+            body["areaCode"] = params.area_code
+        data = await self._request("POST", "/api/v1/numbers", body)
+        return PhoneNumber.from_api(data["number"])
+
+    async def set_number_properties(
+        self,
+        number_id: str,
+        *,
+        inbound_instruction: Optional[str] = None,
+        nickname: Optional[str] = _UNSET,
+    ) -> PhoneNumber:
+        """`dial number set` — update a number's properties (any subset; at least one).
+
+        ``nickname=None`` or ``nickname=""`` clears the nickname; omit the
+        argument to leave it unchanged.
+        """
+        body: dict = {}
+        if inbound_instruction is not None:
+            body["inboundInstruction"] = inbound_instruction
+        if nickname is not _UNSET:
+            body["nickname"] = nickname
+        if not body:
+            raise ValueError(
+                "Provide at least one property to update (inbound_instruction or nickname)."
+            )
+        data = await self._request("PATCH", f"/api/v1/numbers/{number_id}", body)
+        return PhoneNumber.from_api(data["number"])
+
+    async def set_inbound_instruction(
+        self, number_id: str, inbound_instruction: str
+    ) -> PhoneNumber:
+        """Deprecated: use :meth:`set_number_properties` instead."""
+        return await self.set_number_properties(
+            number_id, inbound_instruction=inbound_instruction
+        )
+
+    # ── Messages ─────────────────────────────────────────────────
+
+    async def send_message(self, params: SendMessageParams) -> Message:
+        """`dial message` — send an SMS."""
+        data = await self._request(
+            "POST",
+            "/api/v1/messages",
+            {
+                "to": params.to,
+                "fromNumberId": params.from_number_id,
+                "body": params.body,
+                "channel": params.channel,
+            },
+        )
+        return Message.from_api(data["message"])
+
+    async def list_messages(
+        self,
+        *,
+        number_id: Optional[str] = None,
+        direction: Optional[str] = None,
+        since: Optional[str] = None,
+    ) -> list[Message]:
+        """`dial message list` — list messages, optionally filtered."""
+        data = await self._request(
+            "GET", "/api/v1/messages", params=self._filters(number_id, direction, since)
+        )
+        return [Message.from_api(m) for m in data["messages"]]
+
+    # ── Calls ────────────────────────────────────────────────────
+
+    async def make_call(self, params: MakeCallParams) -> Call:
+        """`dial call` — place an outbound AI voice call."""
+        body = {
+            "to": params.to,
+            "fromNumberId": params.from_number_id,
+            "outboundInstruction": params.outbound_instruction,
+        }
+        # Omitted → the server auto-detects from the destination number's country.
+        if params.language is not None:
+            body["language"] = params.language
+        # Same key across retries → the server returns the already-placed call.
+        headers = (
+            {"Idempotency-Key": params.idempotency_key}
+            if params.idempotency_key is not None
+            else None
+        )
+        data = await self._request("POST", "/api/v1/calls", body, headers=headers)
+        return Call.from_api(data["call"])
+
+    async def list_calls(
+        self,
+        *,
+        number_id: Optional[str] = None,
+        direction: Optional[str] = None,
+        since: Optional[str] = None,
+    ) -> list[Call]:
+        """`dial call list` — list calls, optionally filtered."""
+        data = await self._request(
+            "GET", "/api/v1/calls", params=self._filters(number_id, direction, since)
+        )
+        return [Call.from_api(c) for c in data["calls"]]
+
+    async def get_call(self, call_id: str) -> Call:
+        """`dial call get <id>` — fetch a single call by id."""
+        data = await self._request("GET", f"/api/v1/calls/{call_id}")
+        return Call.from_api(data["call"])
+
+    # ── Events (wait-for) ────────────────────────────────────────
+
+    def new_events_connection(self) -> EventsConnection:
+        """Open a long-lived connection to the account's event stream.
+
+        SDK equivalent of ``dial wait-for``: rather than returning a single
+        event, it yields every ``message.received`` / ``call.ended`` /
+        ``call.transcribed`` event on the account channel. The PubNub token is
+        re-minted automatically before it expires. Every event shares one
+        envelope; read values from ``event["data"]``. No I/O happens until the
+        connection is entered::
+
+            async with client.new_events_connection() as conn:
+                async for event in conn:
+                    if event["type"] == "message.received":
+                        print(event["data"]["from"], event["data"]["body"])
+        """
+
+        async def _mint() -> dict:
+            return await self._request("POST", "/api/v1/listen/subscribe")
+
+        return EventsConnection(_mint)
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "DialClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()

dial_sdk-0.6.2/dial_sdk/events.py

@@ -0,0 +1,155 @@
+import asyncio
+import secrets
+from typing import AsyncIterator, Awaitable, Callable, Optional
+
+from pubnub.callbacks import SubscribeCallback
+from pubnub.pnconfiguration import PNConfiguration
+from pubnub.pubnub_asyncio import PubNubAsyncio
+
+from .types import DialEvent
+
+# A coroutine that calls POST /api/v1/listen/subscribe and returns the grant dict
+# ({ "subscribeKey", "channel", "token", "ttlSeconds" }). Called on open and again
+# before each TTL expiry.
+MintGrant = Callable[[], Awaitable[dict]]
+
+# Renew the token at this fraction of its TTL, leaving headroom before expiry.
+_RENEW_FRACTION = 0.8
+# On a failed renewal, retry this soon (seconds) rather than waiting a full TTL.
+_RENEW_RETRY_SECONDS = 5.0
+
+# Sentinel pushed onto the queue by close() to wake a parked consumer.
+_CLOSED = object()
+
+
+class _QueueListener(SubscribeCallback):
+    """Funnels PubNub messages on our channel into an asyncio.Queue."""
+
+    def __init__(self, queue: "asyncio.Queue", channel: str):
+        self._queue = queue
+        self._channel = channel
+
+    def message(self, pubnub, message):
+        if message.channel == self._channel:
+            self._queue.put_nowait(message.message)
+
+    def presence(self, pubnub, presence):
+        pass
+
+    def status(self, pubnub, status):
+        pass
+
+
+class EventsConnection:
+    """A long-lived subscription to the account's event stream, consumed as an
+    async iterator of event dicts.
+
+    This is the SDK's idiom for what the CLI does one-shot with ``dial wait-for``:
+    instead of returning a single event, it yields every ``message.received`` /
+    ``call.ended`` event on the account channel until the consumer stops iterating
+    or the connection is closed. The PubNub token is silently re-minted before it
+    expires, so a connection can stay open indefinitely. PubNub specifics
+    (subscribe key, channel, token, TTL) are never surfaced to the caller.
+
+    Usage::
+
+        async with client.new_events_connection() as conn:
+            async for event in conn:
+                handle(event)
+    """
+
+    def __init__(self, mint: MintGrant):
+        self._mint = mint
+        self._pubnub: Optional[PubNubAsyncio] = None
+        self._listener: Optional[_QueueListener] = None
+        self._channel = ""
+        self._queue: "asyncio.Queue" = asyncio.Queue()
+        self._renew_task: Optional["asyncio.Task"] = None
+        self._opened = False
+        self._closed = False
+
+    async def open(self) -> "EventsConnection":
+        """Mint the first token and establish the subscription. Idempotent."""
+        if self._opened:
+            return self
+        self._opened = True
+
+        grant = await self._mint()
+        self._channel = grant["channel"]
+
+        config = PNConfiguration()
+        config.subscribe_key = grant["subscribeKey"]
+        config.user_id = f"dial-sdk-{secrets.token_hex(8)}"
+        self._pubnub = PubNubAsyncio(config)
+        self._pubnub.set_token(grant["token"])
+
+        self._listener = _QueueListener(self._queue, self._channel)
+        self._pubnub.add_listener(self._listener)
+        self._pubnub.subscribe().channels([self._channel]).execute()
+
+        self._renew_task = asyncio.create_task(self._renew_loop(grant["ttlSeconds"]))
+        return self
+
+    async def _renew_loop(self, ttl_seconds: float) -> None:
+        try:
+            while not self._closed:
+                await asyncio.sleep(max(1.0, ttl_seconds * _RENEW_FRACTION))
+                if self._closed:
+                    return
+                try:
+                    grant = await self._mint()
+                    if self._pubnub:
+                        self._pubnub.set_token(grant["token"])
+                    ttl_seconds = grant["ttlSeconds"]
+                except Exception:
+                    # Transient mint failure — keep the (still-valid) token, retry soon.
+                    await asyncio.sleep(_RENEW_RETRY_SECONDS)
+        except asyncio.CancelledError:
+            pass
+
+    def __aiter__(self) -> AsyncIterator[DialEvent]:
+        return self
+
+    async def __anext__(self) -> DialEvent:
+        if self._closed and self._queue.empty():
+            raise StopAsyncIteration
+        item = await self._queue.get()
+        if item is _CLOSED:
+            raise StopAsyncIteration
+        return item
+
+    async def close(self) -> None:
+        """Tear down the subscription and end iteration. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+
+        if self._renew_task:
+            self._renew_task.cancel()
+            try:
+                await self._renew_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._renew_task = None
+
+        if self._pubnub:
+            if self._listener:
+                self._pubnub.remove_listener(self._listener)
+            try:
+                self._pubnub.unsubscribe_all()
+            except Exception:
+                pass
+            try:
+                await self._pubnub.stop()
+            except Exception:
+                pass
+            self._pubnub = None
+
+        # Wake any consumer parked in __anext__.
+        self._queue.put_nowait(_CLOSED)
+
+    async def __aenter__(self) -> "EventsConnection":
+        return await self.open()
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()