voxcore-sdk 0.1.0__tar.gz

voxcore_sdk-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Secrets. .env holds SECRET_KEY and the field-encryption key-ring; losing it
+# is bad, committing it is worse. .env.example is the template that IS tracked.
+.env
+.env.local
+.env*.local
+
+# The deployment env dumps. Same contents as .env and then some: PROD-ENV.txt
+# carries FIELD_ENCRYPTION_KEYS next to DB_PASSWORD, which together decrypt
+# every encrypted column in production, plus the Stripe, Telnyx, Sendblue and
+# model-provider keys. Matched by name anywhere in the tree rather than by path,
+# because the next copy of it will be somewhere else.
+PROD-ENV.txt
+prod-env.txt
+*prod-env*.txt
+*PROD-ENV*.txt
+
+# Python
+backend/venv/
+__pycache__/
+*.py[cod]
+backend/db.sqlite3
+# The test runner's database, left behind when a run is interrupted.
+backend/test_db.sqlite3
+*.sqlite3
+backend/staticfiles/
+backend/media/
+
+# Node
+node_modules/
+frontend/.next/
+frontend/out/
+frontend/.turbo/
+*.tsbuildinfo
+next-env.d.ts
+
+# Editors / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

voxcore_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: voxcore-sdk
+Version: 0.1.0
+Summary: The official Python client for VOXCORE — AI agents that answer your phone, text your customers, and talk to your website visitors.
+Project-URL: Homepage, https://voxcore.net
+Project-URL: Documentation, https://voxcore.net/docs
+Project-URL: Source, https://github.com/CodeCraftStudios/voxcore-python
+Author-email: CodeCraft Studios <support@voxcore.net>
+License-Expression: MIT
+Keywords: agents,ai,sms,telephony,voice,voxcore
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VOXCORE for Python
+
+The official Python client for [VOXCORE](https://voxcore.net) — AI agents that answer your phone, text your customers, and talk to visitors on your website.
+
+```bash
+pip install voxcore-sdk
+```
+
+The distribution is `voxcore-sdk`; what you import is `voxcore`.
+
+## Getting started
+
+You need a **secret key** and your **organization id**. Both come from your dashboard: keys under Settings → API keys, and the org id (`org__…`) from the URL.
+
+```python
+from voxcore import Voxcore
+
+vox = Voxcore(api_key="vox_sk_live_…", org="org__…")
+
+for contact in vox.contacts.iterate():
+    print(contact["display_name"])
+```
+
+Or leave them out and set `VOXCORE_API_KEY` and `VOXCORE_ORG` in the environment, which is where a key belongs — not in a file that ends up in a commit:
+
+```python
+vox = Voxcore()
+```
+
+The client holds a connection pool, so reuse one rather than making a new one per call. It works as a context manager if you want the pool closed:
+
+```python
+with Voxcore() as vox:
+    vox.agents.list()
+```
+
+## Listing things
+
+Every collection has the same five verbs — `list`, `iterate`, `retrieve`, `create`, `update`, `delete` — and two ways to read:
+
+```python
+vox.contacts.list(status="customer")      # the first page, as a list
+vox.contacts.iterate(status="customer")   # every page, as a lazy iterator
+```
+
+`list()` returns **one page**. That is deliberate: a tenant with forty thousand contacts should not discover that `list()` quietly made sixteen hundred requests. Use `iterate()` when you want all of them — it follows the API's cursor, so rows arriving while you read do not shift the pages under you.
+
+```python
+consented = [
+    c for c in vox.contacts.iterate()
+    if c["marketing_consent_message"]
+]
+```
+
+## Writing things
+
+```python
+contact = vox.contacts.create(
+    first_name="Dana",
+    phone="+18175550147",     # E.164, always
+    status="lead",
+)
+
+vox.contacts.update(contact["id"], status="customer")
+```
+
+### Retries and idempotency
+
+`GET`s are retried automatically on connection failures, 429s and 5xx, with backoff.
+
+**Writes are not**, unless you make them safe. Repeating a `POST` can create a second contact or place a second call, so the client will not do it on its own. Pass an idempotency key and it will:
+
+```python
+vox.contacts.create(first_name="Dana", idempotency_key=True)      # generated
+vox.contacts.create(first_name="Dana", idempotency_key="order-8127")  # yours
+```
+
+Use your own key when you have a natural one — an order id, a row id — because that is what makes the retry safe across process restarts too.
+
+Sending a text is keyed by default. Texting somebody twice is worse than the alternative:
+
+```python
+vox.threads.send("thr__…", "Your order is ready.")
+```
+
+## Errors
+
+Everything inherits from `VoxcoreError`, so one `except` catches everything this library raises and nothing it does not.
+
+```python
+from voxcore import Voxcore, AuthenticationError, PermissionDenied, RateLimitError
+
+try:
+    vox.contacts.list()
+except AuthenticationError:
+    ...   # the key is wrong, expired or revoked — retrying will never help
+except PermissionDenied:
+    ...   # the key is fine and lacks a scope — fix it in the dashboard
+except RateLimitError as e:
+    ...   # retries were already exhausted; e.retry_after is seconds
+```
+
+Every error carries `.code` (VOXCORE's machine-readable string — branch on this, it is more stable than the HTTP status), `.message`, `.status` and `.request_id`. Quote the request id in a support conversation; it is how a specific request is found in the logs.
+
+## What you can reach
+
+| | |
+|---|---|
+| `vox.agents` | Agents — what they say, how they sound. Also `.publish()` |
+| `vox.calls` | Calls in and out, and `.transcript()` |
+| `vox.campaigns` | Outbound calling campaigns. `.start()`, `.pause()`, `.attempts()` |
+| `vox.contacts` | The people you talk to. `.find_by_phone()` |
+| `vox.contact_batches` | Named audiences. `.members()`, `.add()`, `.exclude()` |
+| `vox.threads` | Texting conversations. `.send()` |
+| `vox.phone_numbers` | Your lines |
+| `vox.widgets`, `vox.forms`, `vox.flows` | Website widgets, forms, messaging sequences |
+| `vox.meetings`, `vox.meeting_types` | Booking |
+| `vox.keys` | API keys |
+
+Anything not wrapped yet is still reachable, and that is on purpose — an SDK that lags the API by a release is an SDK that blocks you:
+
+```python
+vox.request("GET", "/api/v1/orgs/org__…/something-new")
+```
+
+## Two things worth knowing
+
+**Consent is read-only.** `marketing_consent_call`, `marketing_consent_message` and `marketing_consent_email` can be read but never written through the API. They record what a customer actually said — with a timestamp, the call it came from, and a verbatim quote — and a field a script can set is not evidence that anybody said anything. The opt-out flags (`do_not_call`, `do_not_message`) *are* writable, because someone ringing to ask to be removed has to be recordable by whoever takes the call.
+
+**Publishing is not saving.** Updating an agent does not change what callers hear. A live conversation pins the agent's published version, so changes reach the phone only when you publish:
+
+```python
+vox.agents.update(agent_id, system_prompt="…")
+vox.agents.publish(agent_id, notes="new opening line")
+```
+
+## Requirements
+
+Python 3.9+. One dependency: `httpx`.
+
+## License
+
+MIT

voxcore_sdk-0.1.0/README.md

@@ -0,0 +1,143 @@
+# VOXCORE for Python
+
+The official Python client for [VOXCORE](https://voxcore.net) — AI agents that answer your phone, text your customers, and talk to visitors on your website.
+
+```bash
+pip install voxcore-sdk
+```
+
+The distribution is `voxcore-sdk`; what you import is `voxcore`.
+
+## Getting started
+
+You need a **secret key** and your **organization id**. Both come from your dashboard: keys under Settings → API keys, and the org id (`org__…`) from the URL.
+
+```python
+from voxcore import Voxcore
+
+vox = Voxcore(api_key="vox_sk_live_…", org="org__…")
+
+for contact in vox.contacts.iterate():
+    print(contact["display_name"])
+```
+
+Or leave them out and set `VOXCORE_API_KEY` and `VOXCORE_ORG` in the environment, which is where a key belongs — not in a file that ends up in a commit:
+
+```python
+vox = Voxcore()
+```
+
+The client holds a connection pool, so reuse one rather than making a new one per call. It works as a context manager if you want the pool closed:
+
+```python
+with Voxcore() as vox:
+    vox.agents.list()
+```
+
+## Listing things
+
+Every collection has the same five verbs — `list`, `iterate`, `retrieve`, `create`, `update`, `delete` — and two ways to read:
+
+```python
+vox.contacts.list(status="customer")      # the first page, as a list
+vox.contacts.iterate(status="customer")   # every page, as a lazy iterator
+```
+
+`list()` returns **one page**. That is deliberate: a tenant with forty thousand contacts should not discover that `list()` quietly made sixteen hundred requests. Use `iterate()` when you want all of them — it follows the API's cursor, so rows arriving while you read do not shift the pages under you.
+
+```python
+consented = [
+    c for c in vox.contacts.iterate()
+    if c["marketing_consent_message"]
+]
+```
+
+## Writing things
+
+```python
+contact = vox.contacts.create(
+    first_name="Dana",
+    phone="+18175550147",     # E.164, always
+    status="lead",
+)
+
+vox.contacts.update(contact["id"], status="customer")
+```
+
+### Retries and idempotency
+
+`GET`s are retried automatically on connection failures, 429s and 5xx, with backoff.
+
+**Writes are not**, unless you make them safe. Repeating a `POST` can create a second contact or place a second call, so the client will not do it on its own. Pass an idempotency key and it will:
+
+```python
+vox.contacts.create(first_name="Dana", idempotency_key=True)      # generated
+vox.contacts.create(first_name="Dana", idempotency_key="order-8127")  # yours
+```
+
+Use your own key when you have a natural one — an order id, a row id — because that is what makes the retry safe across process restarts too.
+
+Sending a text is keyed by default. Texting somebody twice is worse than the alternative:
+
+```python
+vox.threads.send("thr__…", "Your order is ready.")
+```
+
+## Errors
+
+Everything inherits from `VoxcoreError`, so one `except` catches everything this library raises and nothing it does not.
+
+```python
+from voxcore import Voxcore, AuthenticationError, PermissionDenied, RateLimitError
+
+try:
+    vox.contacts.list()
+except AuthenticationError:
+    ...   # the key is wrong, expired or revoked — retrying will never help
+except PermissionDenied:
+    ...   # the key is fine and lacks a scope — fix it in the dashboard
+except RateLimitError as e:
+    ...   # retries were already exhausted; e.retry_after is seconds
+```
+
+Every error carries `.code` (VOXCORE's machine-readable string — branch on this, it is more stable than the HTTP status), `.message`, `.status` and `.request_id`. Quote the request id in a support conversation; it is how a specific request is found in the logs.
+
+## What you can reach
+
+| | |
+|---|---|
+| `vox.agents` | Agents — what they say, how they sound. Also `.publish()` |
+| `vox.calls` | Calls in and out, and `.transcript()` |
+| `vox.campaigns` | Outbound calling campaigns. `.start()`, `.pause()`, `.attempts()` |
+| `vox.contacts` | The people you talk to. `.find_by_phone()` |
+| `vox.contact_batches` | Named audiences. `.members()`, `.add()`, `.exclude()` |
+| `vox.threads` | Texting conversations. `.send()` |
+| `vox.phone_numbers` | Your lines |
+| `vox.widgets`, `vox.forms`, `vox.flows` | Website widgets, forms, messaging sequences |
+| `vox.meetings`, `vox.meeting_types` | Booking |
+| `vox.keys` | API keys |
+
+Anything not wrapped yet is still reachable, and that is on purpose — an SDK that lags the API by a release is an SDK that blocks you:
+
+```python
+vox.request("GET", "/api/v1/orgs/org__…/something-new")
+```
+
+## Two things worth knowing
+
+**Consent is read-only.** `marketing_consent_call`, `marketing_consent_message` and `marketing_consent_email` can be read but never written through the API. They record what a customer actually said — with a timestamp, the call it came from, and a verbatim quote — and a field a script can set is not evidence that anybody said anything. The opt-out flags (`do_not_call`, `do_not_message`) *are* writable, because someone ringing to ask to be removed has to be recordable by whoever takes the call.
+
+**Publishing is not saving.** Updating an agent does not change what callers hear. A live conversation pins the agent's published version, so changes reach the phone only when you publish:
+
+```python
+vox.agents.update(agent_id, system_prompt="…")
+vox.agents.publish(agent_id, notes="new opening line")
+```
+
+## Requirements
+
+Python 3.9+. One dependency: `httpx`.
+
+## License
+
+MIT

voxcore_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# The distribution is "voxcore-sdk"; the import stays "voxcore".
+#
+# PyPI refused "voxcore": it normalises to the same name as "vox-core", which
+# is already registered to somebody else, so it is not available at any point
+# in the future either. The import name is ours regardless, which is the half
+# that appears in every line of code somebody writes. Same arrangement as
+# python-dateutil -> dateutil.
+name = "voxcore-sdk"
+dynamic = ["version"]
+description = "The official Python client for VOXCORE — AI agents that answer your phone, text your customers, and talk to your website visitors."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "CodeCraft Studios", email = "support@voxcore.net" }]
+keywords = ["voxcore", "voice", "ai", "telephony", "sms", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Telephony",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1"]
+
+[project.urls]
+Homepage = "https://voxcore.net"
+Documentation = "https://voxcore.net/docs"
+Source = "https://github.com/CodeCraftStudios/voxcore-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "respx>=0.20", "mypy>=1.5", "ruff>=0.5"]
+
+[tool.hatch.version]
+path = "src/voxcore/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voxcore"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

voxcore_sdk-0.1.0/src/voxcore/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

voxcore_sdk-0.1.0/src/voxcore/__init__.py

@@ -0,0 +1,41 @@
+"""
+VOXCORE for Python.
+
+    from voxcore import Voxcore
+
+    vox = Voxcore()
+    for contact in vox.contacts.iterate(status="customer"):
+        print(contact["display_name"])
+
+Everything is reached through ``Voxcore``. Errors all inherit from
+``VoxcoreError``, so one except clause catches everything this library raises
+and nothing it does not.
+"""
+
+from .__about__ import __version__
+from .client import Voxcore
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    PermissionDenied,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    VoxcoreError,
+)
+
+__all__ = [
+    "Voxcore",
+    "VoxcoreError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDenied",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "ConnectionError",
+    "__version__",
+]

voxcore_sdk-0.1.0/src/voxcore/_http.py

@@ -0,0 +1,242 @@
+"""
+The one place a request is made, and the only place retries are decided.
+
+Everything in ``resources/`` is a thin call into ``Transport.request``. That is
+deliberate: retry policy, error mapping, idempotency and the auth header are
+each the kind of rule that is correct once and then wrong at whichever call
+site forgot it, so no resource is allowed its own.
+
+**What is retried, and what is not.** A GET is safe to repeat, so connection
+failures, 429s and 5xx are retried with backoff. A POST is not -- repeating one
+can create a second contact or place a second call -- so it is retried only
+when the caller supplied an idempotency key, which is what makes the repeat
+safe on the server. Retrying an unkeyed POST is how one request becomes two
+phone calls to the same person.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+import uuid
+from typing import Any, Iterator, Mapping
+from urllib.parse import urlparse
+
+import httpx
+
+from . import errors
+from .__about__ import __version__
+
+DEFAULT_BASE_URL = "https://api.voxcore.net"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+# Repeated with backoff. 408 and 409 are absent on purpose: a timeout the
+# server reported may have completed, and a conflict is a state problem that a
+# second identical request cannot fix.
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+class Transport:
+    """HTTP, auth, retries and error mapping. Not part of the public API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise errors.VoxcoreError(
+                "An API key is required. Pass api_key=..., or set VOXCORE_API_KEY."
+            )
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max(0, int(max_retries))
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+    # ---- lifecycle -------------------------------------------------------
+
+    def close(self) -> None:
+        # Only what we opened. A caller who passed their own pooled client
+        # expects it to still work after this object goes away.
+        if self._owns_client:
+            self._client.close()
+
+    # ---- the request -----------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        url = path if path.startswith("http") else f"{self._base_url}{path}"
+        method = method.upper()
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"voxcore-python/{__version__}",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        # A keyed write is safe to repeat; an unkeyed one is not. See the
+        # module docstring -- this single line is the whole policy.
+        retryable = method in SAFE_METHODS or bool(idempotency_key)
+        attempts = self._max_retries + 1 if retryable else 1
+
+        last_error: Exception | None = None
+
+        for attempt in range(attempts):
+            if attempt:
+                time.sleep(self._backoff(attempt, last_error))
+
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    params=self._clean(params),
+                    json=json,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as failure:
+                last_error = errors.ConnectionError(
+                    f"The request to {url} timed out."
+                )
+                last_error.__cause__ = failure
+                continue
+            except httpx.HTTPError as failure:
+                last_error = errors.ConnectionError(f"Could not reach {url}: {failure}")
+                last_error.__cause__ = failure
+                continue
+
+            if response.status_code in RETRY_STATUSES and attempt < attempts - 1:
+                last_error = self._to_error(response)
+                continue
+
+            if response.status_code >= 400:
+                raise self._to_error(response)
+
+            if response.status_code == 204 or not response.content:
+                return None
+            try:
+                return response.json()
+            except ValueError as failure:
+                raise errors.APIError(
+                    "The API returned a response that was not JSON.",
+                    status=response.status_code,
+                    request_id=response.headers.get("X-Request-Id", ""),
+                    body=response.text[:500],
+                ) from failure
+
+        raise last_error or errors.ConnectionError(f"Could not reach {url}.")
+
+    # ---- pagination ------------------------------------------------------
+
+    def paginate(
+        self, path: str, *, params: Mapping[str, Any] | None = None
+    ) -> Iterator[dict]:
+        """
+        Every item across every page, one at a time.
+
+        Follows ``page.next``, which is a full URL the API builds, rather than
+        incrementing an offset. VOXCORE paginates on a cursor precisely because
+        an offset shifts when a row is added mid-read, and reconstructing the
+        next request here instead of following the given link would put that
+        bug back.
+        """
+        query: Mapping[str, Any] | None = params
+        url = path
+
+        while url:
+            payload = self.request("GET", url, params=query)
+            if not isinstance(payload, dict):
+                return
+
+            for item in payload.get("data") or []:
+                yield item
+
+            page = payload.get("page") or {}
+            url = page.get("next") or ""
+            # The next link already carries the cursor and the limit; sending
+            # the original params again would override the cursor with the
+            # first page's and loop forever.
+            query = None
+
+    # ---- helpers ---------------------------------------------------------
+
+    def _to_error(self, response: httpx.Response) -> errors.APIError:
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text[:500]
+
+        failure = errors.from_response(
+            response.status_code, body, response.headers.get("X-Request-Id", "")
+        )
+        if isinstance(failure, errors.RateLimitError):
+            header = response.headers.get("Retry-After")
+            if header:
+                try:
+                    failure.retry_after = float(header)
+                except ValueError:
+                    pass
+        return failure
+
+    def _backoff(self, attempt: int, last_error: Exception | None) -> float:
+        """
+        Exponential, with jitter, and the server's own number when it gave one.
+
+        The jitter is not decoration. Clients that back off on identical
+        schedules retry in lockstep and arrive together, which is how a service
+        that was recovering is knocked over by its own users.
+        """
+        if isinstance(last_error, errors.RateLimitError) and last_error.retry_after:
+            return min(float(last_error.retry_after), 60.0)
+        return min(0.5 * (2 ** (attempt - 1)), 8.0) * (1 + random.random() * 0.25)
+
+    @staticmethod
+    def _clean(params: Mapping[str, Any] | None) -> dict | None:
+        """
+        Drop None, and render booleans the way the API reads them.
+
+        ``None`` means "the caller did not pass this", and forwarding it as the
+        string "None" turns an omitted filter into a filter for the literal
+        word. Python's ``True`` would go over as "True", which Django's query
+        parsing does not read as true.
+        """
+        if not params:
+            return None
+        out = {}
+        for key, value in params.items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                out[key] = "true" if value else "false"
+            elif isinstance(value, (list, tuple)):
+                out[key] = ",".join(str(v) for v in value)
+            else:
+                out[key] = value
+        return out or None
+
+
+def new_idempotency_key() -> str:
+    """A key for a write the caller wants to be safe to retry."""
+    return f"vox-{uuid.uuid4()}"
+
+
+def looks_like_production(base_url: str) -> bool:
+    host = (urlparse(base_url).hostname or "").lower()
+    return host.endswith("voxcore.net")