thunderphone 0.1.0__tar.gz

thunderphone-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autophonix, LLC
+
+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.

thunderphone-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: thunderphone
+Version: 0.1.0
+Summary: Official typed ThunderPhone API client
+Author: ThunderPhone
+License-Expression: MIT
+Project-URL: Documentation, https://thunderphone.com/docs/api-reference/sdks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: attrs>=23.2
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: typing-extensions>=4.10
+Dynamic: license-file
+
+# ThunderPhone Python SDK
+
+Python 3.10+. Install `pip install thunderphone`. Set `THUNDERPHONE_API_KEY` in your
+environment, or pass `api_key=` to `ThunderPhone`. Optional `base_url` defaults to
+`https://api.thunderphone.com` (do not append `/v1`).
+
+```python
+import os
+from thunderphone import ThunderPhone, AgentRequest, PlaceCallRequest
+
+with ThunderPhone() as api:
+    agent = api.agents.create(AgentRequest(
+        name="Reception",
+        prompt="Help callers with scheduling and business information.",
+        voice=os.environ["THUNDERPHONE_VOICE"],
+    ))
+    call = api.calls.place(PlaceCallRequest(
+        agent_id=agent.id,
+        from_number=os.environ["FROM_NUMBER"],
+        to_number=os.environ["TO_NUMBER"],
+        idempotency_key="appointment-123",
+    ))
+    done = api.calls.wait_for_completion(
+        call.call_id, timeout=300, poll_interval=1,
+    )
+    if done.status == "failed":
+        raise RuntimeError(done.end_reason)
+    print(api.calls.transcript(call.call_id).transcripts)
+```
+
+Choose a voice from `GET /v1/voices`. Outbound calls require an outbound-capable
+carrier number, sufficient balance, and the organization's outbound confirmation.
+Polling returns both completed and failed calls. A polling deadline raises
+`TimeoutError`; HTTP timeouts and transport errors propagate. Writes are never
+retried automatically. Reuse an idempotency key only for the same request.
+
+Every operation has generated synchronous and asynchronous functions and typed
+request/response models under `thunderphone.generated`. For example:
+
+```python
+from thunderphone.generated.api.calls import calls_list
+
+with ThunderPhone() as api:
+    page = calls_list.sync(client=api.client, limit=20, offset=0)
+```
+
+Generated functions offer `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`
+where the operation has a response body. Detailed variants retain status and headers;
+undocumented errors return `parsed=None` unless `raise_on_unexpected_status` is enabled
+on the generated client. Helpers raise `ThunderPhoneError` with `status` and `body`.
+The client sends `X-ThunderPhone-Client: sdk-python/0.1.0`. Use a context manager or
+`close()` for the facade; close generated async clients with their async context manager.
+
+[API reference](https://thunderphone.com/docs/api-reference/sdks) ·
+[OpenAPI](https://thunderphone.com/openapi.json)
+
+Development: `pip install -e .`, `python -m unittest discover -s tests -v`,
+`python -m build`. Regenerate from the repository root using
+`scripts/generate-sdks.sh`; never edit `thunderphone/generated/` by hand.

thunderphone-0.1.0/README.md

@@ -0,0 +1,59 @@
+# ThunderPhone Python SDK
+
+Python 3.10+. Install `pip install thunderphone`. Set `THUNDERPHONE_API_KEY` in your
+environment, or pass `api_key=` to `ThunderPhone`. Optional `base_url` defaults to
+`https://api.thunderphone.com` (do not append `/v1`).
+
+```python
+import os
+from thunderphone import ThunderPhone, AgentRequest, PlaceCallRequest
+
+with ThunderPhone() as api:
+    agent = api.agents.create(AgentRequest(
+        name="Reception",
+        prompt="Help callers with scheduling and business information.",
+        voice=os.environ["THUNDERPHONE_VOICE"],
+    ))
+    call = api.calls.place(PlaceCallRequest(
+        agent_id=agent.id,
+        from_number=os.environ["FROM_NUMBER"],
+        to_number=os.environ["TO_NUMBER"],
+        idempotency_key="appointment-123",
+    ))
+    done = api.calls.wait_for_completion(
+        call.call_id, timeout=300, poll_interval=1,
+    )
+    if done.status == "failed":
+        raise RuntimeError(done.end_reason)
+    print(api.calls.transcript(call.call_id).transcripts)
+```
+
+Choose a voice from `GET /v1/voices`. Outbound calls require an outbound-capable
+carrier number, sufficient balance, and the organization's outbound confirmation.
+Polling returns both completed and failed calls. A polling deadline raises
+`TimeoutError`; HTTP timeouts and transport errors propagate. Writes are never
+retried automatically. Reuse an idempotency key only for the same request.
+
+Every operation has generated synchronous and asynchronous functions and typed
+request/response models under `thunderphone.generated`. For example:
+
+```python
+from thunderphone.generated.api.calls import calls_list
+
+with ThunderPhone() as api:
+    page = calls_list.sync(client=api.client, limit=20, offset=0)
+```
+
+Generated functions offer `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`
+where the operation has a response body. Detailed variants retain status and headers;
+undocumented errors return `parsed=None` unless `raise_on_unexpected_status` is enabled
+on the generated client. Helpers raise `ThunderPhoneError` with `status` and `body`.
+The client sends `X-ThunderPhone-Client: sdk-python/0.1.0`. Use a context manager or
+`close()` for the facade; close generated async clients with their async context manager.
+
+[API reference](https://thunderphone.com/docs/api-reference/sdks) ·
+[OpenAPI](https://thunderphone.com/openapi.json)
+
+Development: `pip install -e .`, `python -m unittest discover -s tests -v`,
+`python -m build`. Regenerate from the repository root using
+`scripts/generate-sdks.sh`; never edit `thunderphone/generated/` by hand.

thunderphone-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thunderphone"
+version = "0.1.0"
+description = "Official typed ThunderPhone API client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "ThunderPhone"}]
+dependencies = ["httpx>=0.27,<0.29", "attrs>=23.2", "python-dateutil>=2.8.2", "typing-extensions>=4.10"]
+
+[project.urls]
+Documentation = "https://thunderphone.com/docs/api-reference/sdks"
+
+[tool.setuptools.packages.find]
+include = ["thunderphone*"]
+
+[tool.setuptools.package-data]
+thunderphone = ["py.typed"]

thunderphone-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thunderphone-0.1.0/tests/test_client.py

@@ -0,0 +1,211 @@
+import importlib
+import json
+import os
+import pkgutil
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from unittest.mock import patch
+
+from thunderphone import AgentRequest, PlaceCallRequest, ThunderPhone, ThunderPhoneError
+from thunderphone import generated
+
+FIXTURES = Path(__file__).resolve().parents[2] / "fixtures"
+AGENT = json.loads((FIXTURES / "agent.json").read_text())
+CALL = json.loads((FIXTURES / "call.json").read_text())
+
+
+class ClientTests(unittest.TestCase):
+    def setUp(self):
+        self.requests = []
+        self.statuses = ["in_progress", "completed"]
+        self.failure = None
+        owner = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *_args):
+                pass
+
+            def do_GET(self):
+                self.respond()
+
+            def do_POST(self):
+                self.respond()
+
+            def respond(self):
+                raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
+                owner.requests.append(
+                    (
+                        self.command,
+                        self.path,
+                        dict(self.headers),
+                        json.loads(raw) if raw else None,
+                    )
+                )
+                status = 200
+                if owner.failure:
+                    status, payload = owner.failure, {"detail": "declined"}
+                elif self.path == "/v1/agents":
+                    status, payload = 201, AGENT
+                elif self.path == "/v1/call":
+                    status, payload = 201, {"call_id": 1001, "status": "initiated"}
+                elif self.path.endswith("/transcript"):
+                    payload = {
+                        "call_id": 1001,
+                        "transcripts": [{"role": "agent", "content": "Hello"}],
+                    }
+                else:
+                    state = (
+                        owner.statuses.pop(0)
+                        if len(owner.statuses) > 1
+                        else owner.statuses[0]
+                    )
+                    payload = {**CALL, "status": state}
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(json.dumps(payload).encode())
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+        self.api = ThunderPhone(
+            "test-placeholder", base_url=f"http://127.0.0.1:{self.server.server_port}/"
+        )
+
+    def tearDown(self):
+        self.api.close()
+        self.server.shutdown()
+        self.server.server_close()
+        self.thread.join()
+
+    def test_create_place_poll_transcript(self):
+        agent = self.api.agents.create(
+            AgentRequest(name="Reception", prompt="Help callers.", voice="olivia")
+        )
+        self.assertEqual(agent.id, 12)
+        placed = self.api.calls.place(
+            PlaceCallRequest(
+                from_number=CALL["from_number"],
+                to_number=CALL["to_number"],
+                agent_id=12,
+                idempotency_key="one",
+            )
+        )
+        self.assertEqual(placed.call_id, 1001)
+        self.assertEqual(
+            self.api.calls.wait_for_completion(1001, poll_interval=0.001).status,
+            "completed",
+        )
+        self.assertEqual(
+            self.api.calls.transcript(1001).transcripts[0].content, "Hello"
+        )
+        self.assertEqual(self.requests[1][3]["idempotency_key"], "one")
+        for _, path, headers, _ in self.requests:
+            self.assertEqual(headers["Authorization"], "Bearer test-placeholder")
+            self.assertEqual(headers["X-ThunderPhone-Client"], "sdk-python/0.1.0")
+            self.assertNotIn("/v1/v1/", path)
+
+    def test_failed_timeout_and_bad_interval(self):
+        self.statuses = ["failed"]
+        self.assertEqual(self.api.calls.wait_for_completion(1001).status, "failed")
+        self.statuses = ["in_progress"]
+        with self.assertRaises(TimeoutError):
+            self.api.calls.wait_for_completion(1001, timeout=0.025, poll_interval=0.001)
+        with self.assertRaises(ValueError):
+            self.api.calls.wait_for_completion(1001, poll_interval=0)
+
+    def test_errors_do_not_retry_mutations(self):
+        self.failure = 402
+        with self.assertRaises(ThunderPhoneError) as caught:
+            self.api.calls.place(PlaceCallRequest(from_number="a", to_number="b"))
+        self.assertEqual(caught.exception.status, 402)
+        self.assertEqual(len(self.requests), 1)
+
+    def test_environment_and_base_url(self):
+        with patch.dict(os.environ, {}, clear=True):
+            with self.assertRaises(ValueError):
+                ThunderPhone()
+        with patch.dict(os.environ, {"THUNDERPHONE_API_KEY": "test-placeholder"}):
+            with ThunderPhone() as api:
+                self.assertIsNotNone(api.client)
+        with self.assertRaises(ValueError):
+            ThunderPhone("test-placeholder", base_url="ftp://example.com")
+
+    def test_generated_multipart_has_boundary_and_repeated_file_fields(self):
+        from io import BytesIO
+        from thunderphone.generated.api.knowledge import knowledge_documents_create
+        from thunderphone.generated.models.document_batch_upload_request import (
+            DocumentBatchUploadRequest,
+        )
+        from thunderphone.generated.types import File
+
+        body = DocumentBatchUploadRequest(
+            files=[
+                File(
+                    payload=BytesIO(b"first document"),
+                    file_name="first.txt",
+                    mime_type="text/plain",
+                ),
+                File(
+                    payload=BytesIO(b"second document"),
+                    file_name="second.txt",
+                    mime_type="text/plain",
+                ),
+            ]
+        )
+        kwargs = knowledge_documents_create._get_kwargs(body=body)
+        request = self.api.client.get_httpx_client().build_request(**kwargs)
+        self.assertIn("boundary=", request.headers["Content-Type"])
+        wire = request.read()
+        self.assertEqual(wire.count(b'name="files[]"'), 2)
+        self.assertIn(b"first document", wire)
+        self.assertIn(b"second document", wire)
+
+    def test_campaign_contacts_accept_wrapped_json_raw_json_and_csv(self):
+        from io import BytesIO
+        from uuid import UUID
+        from thunderphone.generated.api.campaigns import campaigns_contacts
+        from thunderphone.generated.models.campaign_contact_input_request import (
+            CampaignContactInputRequest,
+        )
+        from thunderphone.generated.models.campaign_contacts_request import (
+            CampaignContactsRequest,
+        )
+        from thunderphone.generated.models.campaign_contacts_upload_request import (
+            CampaignContactsUploadRequest,
+        )
+        from thunderphone.generated.types import File
+
+        contact = CampaignContactInputRequest(phone="+14155550101")
+        campaign_id = UUID("11111111-1111-4111-8111-111111111111")
+        for body, expected in [
+            ([contact], [{"phone": "+14155550101"}]),
+            (
+                CampaignContactsRequest(contacts=[contact]),
+                {"contacts": [{"phone": "+14155550101"}]},
+            ),
+        ]:
+            self.assertEqual(
+                campaigns_contacts._get_kwargs(campaign_id, body=body)["json"], expected
+            )
+        kwargs = campaigns_contacts._get_kwargs(
+            campaign_id,
+            body=CampaignContactsUploadRequest(
+                file=File(
+                    payload=BytesIO(b"phone\n+14155550101"),
+                    file_name="contacts.csv",
+                    mime_type="text/csv",
+                ),
+            ),
+        )
+        request = self.api.client.get_httpx_client().build_request(**kwargs)
+        self.assertIn("boundary=", request.headers["Content-Type"])
+        self.assertIn(b"contacts.csv", request.read())
+
+    def test_every_generated_module_imports(self):
+        for module in pkgutil.walk_packages(
+            generated.__path__, generated.__name__ + "."
+        ):
+            importlib.import_module(module.name)

thunderphone-0.1.0/thunderphone/__init__.py

@@ -0,0 +1,6 @@
+"""Official ThunderPhone client and common request types."""
+from .facade import ThunderPhone, ThunderPhoneError
+from .generated.models.agent_request import AgentRequest
+from .generated.models.place_call_request import PlaceCallRequest
+
+__all__ = ["ThunderPhone", "ThunderPhoneError", "AgentRequest", "PlaceCallRequest"]

thunderphone-0.1.0/thunderphone/facade.py

@@ -0,0 +1,137 @@
+"""Small synchronous facade; every endpoint also has generated sync/async clients."""
+
+from __future__ import annotations
+
+import math
+import os
+import time
+from typing import TypeVar
+from urllib.parse import urlsplit
+
+import httpx
+
+from .generated.api.agents import agents_create
+from .generated.api.calls import calls_place, calls_retrieve, calls_transcript_list
+from .generated.client import AuthenticatedClient
+from .generated.models.agent import Agent
+from .generated.models.agent_request import AgentRequest
+from .generated.models.call import Call
+from .generated.models.call_transcript import CallTranscript
+from .generated.models.place_call_request import PlaceCallRequest
+from .generated.models.place_call_response import PlaceCallResponse
+from .generated.types import Response
+
+T = TypeVar("T")
+
+
+class ThunderPhoneError(Exception):
+    def __init__(self, status: int, body: bytes):
+        self.status = status
+        self.body = body
+        super().__init__(f"ThunderPhone API returned HTTP {status}")
+
+
+def _unwrap(response: Response[T]) -> T:
+    if not 200 <= response.status_code < 300:
+        raise ThunderPhoneError(response.status_code, response.content)
+    if response.parsed is None:
+        raise ValueError("ThunderPhone returned an empty success response")
+    return response.parsed
+
+
+class _Agents:
+    def __init__(self, client: AuthenticatedClient):
+        self._client = client
+
+    def create(self, body: AgentRequest) -> Agent:
+        return _unwrap(agents_create.sync_detailed(client=self._client, body=body))
+
+
+class _Calls:
+    def __init__(self, client: AuthenticatedClient):
+        self._client = client
+
+    def place(self, body: PlaceCallRequest) -> PlaceCallResponse:
+        return _unwrap(calls_place.sync_detailed(client=self._client, body=body))
+
+    def get(self, call_id: int) -> Call:
+        return _unwrap(calls_retrieve.sync_detailed(call_id, client=self._client))
+
+    def transcript(self, call_id: int) -> CallTranscript:
+        return _unwrap(
+            calls_transcript_list.sync_detailed(call_id, client=self._client)
+        )
+
+    def wait_for_completion(
+        self, call_id: int, *, timeout: float = 300, poll_interval: float = 1
+    ) -> Call:
+        """Poll completed/failed states. Never retries a mutating request.
+
+        timeout bounds polling; individual HTTP operations have a timeout no
+        larger than the remaining budget. Network timeout errors propagate.
+        """
+        if (
+            not math.isfinite(timeout)
+            or timeout <= 0
+            or not math.isfinite(poll_interval)
+            or poll_interval <= 0
+        ):
+            raise ValueError(
+                "timeout and poll_interval must be positive finite numbers"
+            )
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"Timed out waiting for call {call_id}")
+            response = self._client.get_httpx_client().get(
+                f"/v1/calls/{call_id}", timeout=min(30, remaining)
+            )
+            if not response.is_success:
+                raise ThunderPhoneError(response.status_code, response.content)
+            call = Call.from_dict(response.json())
+            if call.status in {"completed", "failed"}:
+                return call
+            time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+
+
+class ThunderPhone:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://api.thunderphone.com",
+        timeout: float = 30,
+    ):
+        key = api_key if api_key is not None else os.environ.get("THUNDERPHONE_API_KEY")
+        if not key or not key.strip():
+            raise ValueError("Set THUNDERPHONE_API_KEY or provide api_key")
+        parsed = urlsplit(base_url)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.netloc
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError(
+                "base_url must be an HTTP(S) URL without credentials, query, or fragment"
+            )
+        self.client = AuthenticatedClient(
+            base_url=base_url.rstrip("/"),
+            token=key,
+            headers={"X-ThunderPhone-Client": "sdk-python/0.1.0"},
+            timeout=httpx.Timeout(timeout),
+        )
+        self.agents = _Agents(self.client)
+        self.calls = _Calls(self.client)
+
+    def close(self) -> None:
+        self.client.get_httpx_client().close()
+
+    def __enter__(self) -> ThunderPhone:
+        return self
+
+    def __exit__(self, *_args) -> None:
+        self.close()

thunderphone-0.1.0/thunderphone/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing ThunderPhone API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

thunderphone-0.1.0/thunderphone/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

thunderphone-0.1.0/thunderphone/generated/api/agent_imports/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""