voxcore-sdk 0.1.0__py3-none-any.whl

voxcore/__about__.py

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

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/_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")

voxcore/client.py

@@ -0,0 +1,130 @@
+"""
+The client: a key, an organization, and the collections underneath it.
+
+Every tenant-owned resource on this API is scoped to an organization, so the
+client holds one rather than making every call repeat it. A key belongs to
+exactly one organization anyway -- so passing an org id that is not the key's
+is not a thing this library should let you express, and it does not.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from . import errors, resources
+from ._http import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, Transport
+
+ENV_API_KEY = "VOXCORE_API_KEY"
+ENV_ORG = "VOXCORE_ORG"
+ENV_BASE_URL = "VOXCORE_BASE_URL"
+
+
+class Voxcore:
+    """
+    Talk to VOXCORE.
+
+        from voxcore import Voxcore
+
+        vox = Voxcore()                      # reads VOXCORE_API_KEY and VOXCORE_ORG
+        for contact in vox.contacts.iterate():
+            print(contact["display_name"])
+
+    The key and organization are read from the environment when not passed,
+    because the alternative is a key written into a file that ends up in a
+    commit. Nothing here ever writes a key anywhere.
+
+    Usable as a context manager, which closes the connection pool::
+
+        with Voxcore() as vox:
+            vox.agents.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        org: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get(ENV_API_KEY, "")
+        org = org or os.environ.get(ENV_ORG, "")
+        base_url = base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL
+
+        if not api_key:
+            raise errors.VoxcoreError(
+                "No API key. Pass Voxcore(api_key=...) or set "
+                f"{ENV_API_KEY} in the environment."
+            )
+        if not org:
+            raise errors.VoxcoreError(
+                "No organization. Pass Voxcore(org=...) or set "
+                f"{ENV_ORG}. It looks like 'org__...' and is in the URL of "
+                "your dashboard."
+            )
+        # Caught here rather than as a 401 three lines later, because the
+        # mistake it catches -- reaching for a publishable key on a server --
+        # produces an authentication error that reads like a bad key.
+        if api_key.startswith("vox_pk_"):
+            raise errors.VoxcoreError(
+                "That is a publishable key. It is safe in a browser and "
+                "cannot read this API. Use a secret key (vox_sk_...)."
+            )
+
+        self._transport = Transport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.org = org
+
+        self.agents = resources.Agents(self._transport, org)
+        self.calls = resources.Calls(self._transport, org)
+        self.campaigns = resources.Campaigns(self._transport, org)
+        self.chat_sessions = resources.ChatSessions(self._transport, org)
+        self.contacts = resources.Contacts(self._transport, org)
+        self.contact_batches = resources.ContactBatches(self._transport, org)
+        self.flows = resources.Flows(self._transport, org)
+        self.forms = resources.Forms(self._transport, org)
+        self.keys = resources.ApiKeys(self._transport, org)
+        self.meetings = resources.Meetings(self._transport, org)
+        self.meeting_types = resources.MeetingTypes(self._transport, org)
+        self.phone_numbers = resources.PhoneNumbers(self._transport, org)
+        self.threads = resources.Threads(self._transport, org)
+        self.widgets = resources.Widgets(self._transport, org)
+
+    # ---- escape hatch ----------------------------------------------------
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """
+        Call an endpoint this library does not wrap yet.
+
+        Deliberately public. An SDK that lags the API by one release is an SDK
+        that blocks people, and the honest answer is a documented way through
+        rather than a fork. ``path`` is joined to the base URL as given, so
+        pass the full "/api/v1/..." path.
+        """
+        return self._transport.request(method, path, **kwargs)
+
+    # ---- lifecycle -------------------------------------------------------
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Voxcore":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        # The key is never rendered, not even truncated. A repr goes into
+        # tracebacks, logs and bug reports.
+        return f"<Voxcore org={self.org!r}>"

voxcore/errors.py

@@ -0,0 +1,158 @@
+"""
+What went wrong, as types a caller can branch on.
+
+One exception per thing you would actually do differently. ``VoxcoreError`` is
+the base, so ``except VoxcoreError`` catches everything this library raises and
+nothing it does not -- a caller should never have to catch ``httpx`` types to
+use this.
+
+The distinction that earns its keep is ``AuthenticationError`` against
+``PermissionDenied``. The first means the key is wrong, expired or revoked, and
+retrying will never help; the second means the key is fine and lacks a scope,
+which is a fix in the dashboard rather than in the code. Collapsing them into
+one "not allowed" sends people to re-read their key when the key was correct.
+"""
+
+from __future__ import annotations
+
+
+class VoxcoreError(Exception):
+    """Base for everything this library raises."""
+
+
+class APIError(VoxcoreError):
+    """
+    The API answered, and the answer was an error.
+
+    ``code`` is VOXCORE's own machine-readable string when it sent one, which
+    is more stable than the HTTP status and much more stable than the message.
+    Branch on ``code``; show ``message``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str = "",
+        request_id: str = "",
+        body: object = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        # Echoed back on every response. Quote it in a support conversation --
+        # it is how a specific request is found in the logs.
+        self.request_id = request_id
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"[{self.code}]")
+        if self.request_id:
+            parts.append(f"(request {self.request_id})")
+        return " ".join(parts)
+
+
+class AuthenticationError(APIError):
+    """The key is missing, malformed, expired or revoked. 401."""
+
+
+class PermissionDenied(APIError):
+    """The key is valid and not allowed to do this. 403."""
+
+
+class NotFoundError(APIError):
+    """No such resource, or not one this key's organization can see. 404."""
+
+
+class ValidationError(APIError):
+    """
+    The request was refused as malformed. 400 or 422.
+
+    ``fields`` maps a field name to what was wrong with it, when the API said.
+    """
+
+    def __init__(self, message: str, *, fields: dict | None = None, **kwargs) -> None:
+        super().__init__(message, **kwargs)
+        self.fields = fields or {}
+
+
+class RateLimitError(APIError):
+    """
+    Too many requests. 429.
+
+    ``retry_after`` is seconds, from the header, when the API sent one. The
+    client already retries these; seeing one means the retries were exhausted.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    """Something broke on our side. 5xx. Safe to retry."""
+
+
+class ConnectionError(VoxcoreError):
+    """The request never reached the API, or the answer never came back."""
+
+
+def from_response(status: int, body: object, request_id: str = "") -> APIError:
+    """
+    Turn an error response into the narrowest exception that fits.
+
+    VOXCORE errors arrive as ``{"error": {"code": ..., "message": ...}}``. A
+    body that does not match -- a proxy's HTML error page, a gateway timeout --
+    still has to produce a usable exception, so the shape is probed rather
+    than assumed.
+    """
+    code = ""
+    message = ""
+    fields: dict = {}
+
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, dict):
+            code = str(error.get("code") or "")
+            message = str(error.get("message") or "")
+            found = error.get("fields")
+            if isinstance(found, dict):
+                fields = found
+        elif isinstance(error, str):
+            message = error
+        if not message:
+            # DRF's own shape, which some endpoints still return directly.
+            detail = body.get("detail")
+            if detail:
+                message = str(detail)
+            else:
+                fields = {
+                    key: value
+                    for key, value in body.items()
+                    if isinstance(value, (list, str))
+                }
+                if fields:
+                    message = "The request was refused as invalid."
+
+    if not message:
+        message = f"The API returned HTTP {status}."
+
+    shared = {"status": status, "code": code, "request_id": request_id, "body": body}
+
+    if status == 401:
+        return AuthenticationError(message, **shared)
+    if status == 403:
+        return PermissionDenied(message, **shared)
+    if status == 404:
+        return NotFoundError(message, **shared)
+    if status == 429:
+        return RateLimitError(message, **shared)
+    if status in (400, 422):
+        return ValidationError(message, fields=fields, **shared)
+    if status >= 500:
+        return ServerError(message, **shared)
+    return APIError(message, **shared)

voxcore/resources/__init__.py

@@ -0,0 +1,277 @@
+"""
+The collections a key can reach, one class each.
+
+Every one is a ``Resource`` subclass and most add nothing -- the API is uniform
+enough that a name is the whole definition. Where a resource has an endpoint of
+its own, it is a method with a docstring saying what it does that the five
+standard verbs do not.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator
+
+from ._base import Resource
+
+
+class Agents(Resource):
+    """The agents in this organization: what they say and how they sound."""
+
+    name = "agents"
+
+    def publish(self, agent_id: str, *, notes: str = "") -> dict:
+        """
+        Freeze the current configuration as a version and make it live.
+
+        Editing an agent is not publishing it. A live conversation pins the
+        agent's live version, so changes made through ``update`` do not reach
+        callers until this is called -- which is the single most common
+        surprise when driving an agent from a script.
+        """
+        return self._action(agent_id, "publish", json={"notes": notes})
+
+    def versions(self, agent_id: str) -> list[dict]:
+        """
+        Every published version of this agent, newest first.
+
+        Unwrapped here. The endpoint answers with the usual ``{"data": [...]}``
+        envelope, and returning that dict from a method annotated ``list[dict]``
+        meant iterating it yielded the string ``"data"`` -- which is not an
+        error anywhere, just a loop over one wrong thing.
+        """
+        payload = self._action(agent_id, "versions", method="GET")
+        if isinstance(payload, dict):
+            return payload.get("data") or []
+        return payload or []
+
+
+class Calls(Resource):
+    """
+    Calls, inbound and outbound.
+
+    Read-only in practice: a call is a record of something that happened, and
+    it is created by the phone ringing rather than by this library. To place
+    one, start a campaign.
+    """
+
+    name = "calls"
+
+    def transcript(self, call_id: str) -> dict:
+        """
+        What was said, if the transcript has not expired.
+
+        Retention is per organization and enforced by a deletion pass, so an
+        old call can legitimately have no transcript. That is a 404 and not a
+        failure of the call.
+        """
+        return self._action(call_id, "transcript", method="GET")
+
+
+class Contacts(Resource):
+    """
+    The people this organization talks to.
+
+    Consent fields are readable and NOT writable, deliberately: they record
+    what a customer said, and a field a script can set is not evidence that
+    they said it. The opt-out flags (``do_not_call``, ``do_not_message``) ARE
+    writable, because somebody ringing to ask to be removed has to be
+    recordable by whoever takes the call.
+    """
+
+    name = "contacts"
+
+    def find_by_phone(self, phone: str) -> dict | None:
+        """
+        The contact on this number, or None.
+
+        Searched with ``q``, which is the parameter the directory actually
+        reads. This used to pass ``phone=``, and the contact list IGNORES
+        parameters it does not know -- so the filter did nothing, the first
+        page of every contact came back, and the first row of it was returned
+        as the match. It never raised and it was almost never right.
+
+        The result is checked before it is handed back, because ``q`` is a
+        search and not a lookup: it matches a number by its last seven or more
+        digits, so "+18175550147" and "5550147" find each other. That is the
+        behaviour you want when a person types into a box and the wrong one to
+        trust silently, so anything whose number does not actually match is
+        dropped here rather than returned as a near miss.
+        """
+        digits = "".join(character for character in phone if character.isdigit())
+        for contact in self.list(q=phone):
+            found = "".join(c for c in (contact.get("phone") or "") if c.isdigit())
+            if found and digits and (found.endswith(digits) or digits.endswith(found)):
+                return contact
+        return None
+
+
+class ContactBatches(Resource):
+    """
+    Named audiences: a list somebody made, or a saved question.
+
+    A **static** batch is a list -- membership changes only when a person
+    changes it. A **dynamic** batch is a rule, answered against the contact
+    table whenever it is asked, so its membership moves as the contacts do.
+    ``kind`` cannot be changed after creation.
+    """
+
+    name = "contact-batches"
+
+    def members(self, batch_id: str, **filters: Any) -> Iterator[dict]:
+        """
+        Everybody in the batch, including anyone opted out.
+
+        For looking at, never for sending. Suppressed contacts are included
+        here on purpose so a preview can say "1,204 people, 37 of whom have
+        opted out" -- the API applies do-not-contact when a campaign resolves
+        the batch, and there is no way to switch that off.
+        """
+        return self._transport.paginate(
+            f"{self._detail(batch_id)}members/", params=filters
+        )
+
+    def add(self, batch_id: str, contact_ids: list[str]) -> dict:
+        """Pin contacts into a static batch. Refused on a dynamic one."""
+        return self._action(batch_id, "members", json={"contacts": contact_ids})
+
+    def exclude(
+        self, batch_id: str, contact_ids: list[str], *, reason: str = ""
+    ) -> dict:
+        """
+        Hold people out of this batch without touching them anywhere else.
+
+        The alternative to editing their tags, which changes every other batch
+        too, or setting do-not-call, which is a legal flag being used as a
+        filing device. An exclusion is local, reversible, and survives the next
+        import that would otherwise put them back.
+
+        **A POST, not a DELETE, and this was wrong in two ways at once.** It
+        sent ``{"contact": id}`` where the endpoint reads a ``contacts`` list,
+        so it was refused as malformed; and it sent DELETE, which REMOVES a
+        membership row rather than excluding anyone. Those are opposite
+        outcomes on a static batch. Removing somebody lets the next import put
+        them straight back, which is the precise failure an exclusion exists
+        to prevent.
+        """
+        return self._action(
+            batch_id,
+            "members",
+            json={"contacts": contact_ids, "state": "excluded", "reason": reason},
+        )
+
+    def remove(self, batch_id: str, contact_ids: list[str]) -> dict:
+        """
+        Take membership rows out of this batch entirely.
+
+        Not the same thing as ``exclude``. This forgets that the batch ever
+        had an opinion about these people, so a later import can add them
+        again. On a dynamic batch it lifts an existing exclusion, which can
+        put somebody back into the audience. Reach for ``exclude`` when you
+        mean "not these, from this list".
+        """
+        return self._action(
+            batch_id, "members", method="DELETE", json={"contacts": contact_ids}
+        )
+
+
+class Campaigns(Resource):
+    """
+    Outbound calling campaigns: a standing instruction to ring a batch.
+
+    Created in draft and dialling nobody. Starting one is a separate call,
+    because a campaign that began the moment it was saved is a campaign that
+    rings twenty thousand people before anybody read it back.
+    """
+
+    name = "campaigns"
+
+    def start(self, campaign_id: str) -> dict:
+        return self._action(campaign_id, "start")
+
+    def pause(self, campaign_id: str) -> dict:
+        return self._action(campaign_id, "pause")
+
+    def attempts(self, campaign_id: str, **filters: Any) -> Iterator[dict]:
+        """The dial ledger: one row per call this campaign put on a carrier."""
+        return self._transport.paginate(
+            f"{self._detail(campaign_id)}attempts/", params=filters
+        )
+
+
+class PhoneNumbers(Resource):
+    name = "phone-numbers"
+
+
+class Threads(Resource):
+    """Texting conversations, on SMS or iMessage."""
+
+    name = "threads"
+
+    def send(self, thread_id: str, text: str, *, idempotency_key: Any = True) -> dict:
+        """
+        Send a message into this thread.
+
+        Keyed by default. A dropped connection on an unkeyed send leaves you
+        unable to tell whether it went, and the honest recoveries are "text
+        them twice" or "never text them" -- so this one defaults to safe.
+        """
+        return self._action(
+            thread_id, "messages", json={"text": text}, idempotency_key=idempotency_key
+        )
+
+
+class ChatSessions(Resource):
+    name = "chat-sessions"
+
+
+class Widgets(Resource):
+    name = "widgets"
+
+
+class Forms(Resource):
+    name = "forms"
+
+
+class Flows(Resource):
+    """Messaging sequences. These do not run on a voice call."""
+
+    name = "flows"
+
+
+class Meetings(Resource):
+    name = "meetings"
+
+
+class MeetingTypes(Resource):
+    name = "meeting-types"
+
+
+class ApiKeys(Resource):
+    """
+    The keys for this organization.
+
+    A secret is returned exactly once, when it is created, and is never
+    stored -- only a hash and a display prefix. There is no way to read one
+    back, so a lost key is rotated rather than recovered.
+    """
+
+    name = "keys"
+
+
+__all__ = [
+    "Resource",
+    "Agents",
+    "ApiKeys",
+    "Calls",
+    "Campaigns",
+    "ChatSessions",
+    "ContactBatches",
+    "Contacts",
+    "Flows",
+    "Forms",
+    "Meetings",
+    "MeetingTypes",
+    "PhoneNumbers",
+    "Threads",
+    "Widgets",
+]

voxcore/resources/_base.py

@@ -0,0 +1,134 @@
+"""
+The shape every resource shares.
+
+VOXCORE's API is uniform -- every tenant-owned collection lives at
+``/api/v1/orgs/<org>/<name>``, lists through the same cursor envelope and
+returns the same error shape -- so the resources are a base class plus a
+string, rather than twenty near-copies that drift apart one endpoint at a time.
+
+Anything a resource does differently is written on that resource and nowhere
+else, which makes the exceptions easy to see.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, Mapping
+
+from .._http import Transport, new_idempotency_key
+
+
+class Resource:
+    """One collection under an organization."""
+
+    #: The path segment, e.g. "contacts". Set by each subclass.
+    name: str = ""
+
+    def __init__(self, transport: Transport, org_id: str) -> None:
+        self._transport = transport
+        self._org = org_id
+
+    # ---- paths -----------------------------------------------------------
+
+    # ---- Every path ends in a slash, and that is not cosmetic ----------
+    #
+    # The API runs Django with APPEND_SLASH on. Without the trailing slash:
+    #
+    #   GET  /contacts  -> 301 to /contacts/. httpx does not follow redirects
+    #                      by default, so the client read an empty body and
+    #                      returned an EMPTY LIST. Not an error. Just no
+    #                      contacts, quietly, forever.
+    #   POST /contacts  -> Django cannot redirect a POST without dropping the
+    #                      body, so it raises, and the caller gets a 500.
+    #
+    # Mocked tests cannot catch this: a mock transport answers whatever URL it
+    # is handed. It took one request against the real API.
+
+    @property
+    def _collection(self) -> str:
+        return f"/api/v1/orgs/{self._org}/{self.name}/"
+
+    def _detail(self, resource_id: str) -> str:
+        return f"{self._collection}{resource_id}/"
+
+    # ---- the five verbs --------------------------------------------------
+
+    def list(self, **filters: Any) -> list[dict]:
+        """
+        The first page only. Use ``iterate`` for everything.
+
+        Returning one page rather than silently fetching all of them is the
+        safer default: a tenant with forty thousand contacts should not
+        discover that ``list()`` makes sixteen hundred requests.
+        """
+        payload = self._transport.request("GET", self._collection, params=filters)
+        if isinstance(payload, dict):
+            return payload.get("data") or []
+        return payload or []
+
+    def iterate(self, **filters: Any) -> Iterator[dict]:
+        """Every item, following the cursor. Lazy -- stop and it stops."""
+        return self._transport.paginate(self._collection, params=filters)
+
+    def retrieve(self, resource_id: str) -> dict:
+        return self._transport.request("GET", self._detail(resource_id))
+
+    def create(self, *, idempotency_key: str | None = None, **fields: Any) -> dict:
+        """
+        Make one.
+
+        Pass ``idempotency_key`` to make the write safe to retry -- without it
+        a dropped connection leaves you unable to tell whether the thing was
+        created, and the transport will not repeat the request. ``True``
+        generates one for you.
+        """
+        return self._transport.request(
+            "POST",
+            self._collection,
+            json=fields,
+            idempotency_key=_resolve_key(idempotency_key),
+        )
+
+    def update(self, resource_id: str, **fields: Any) -> dict:
+        """Change some fields. A PATCH -- omitted fields are left alone."""
+        return self._transport.request(
+            "PATCH", self._detail(resource_id), json=fields
+        )
+
+    def delete(self, resource_id: str) -> None:
+        """
+        Remove it.
+
+        Most things here are soft-deleted by the API: a contact, a batch or an
+        agent that a call or a campaign refers to stays resolvable, because a
+        hard delete turns "who did we ring?" into an id that resolves to
+        nothing. What you get back is the same either way -- nothing.
+        """
+        self._transport.request("DELETE", self._detail(resource_id))
+
+    # ---- for subclasses --------------------------------------------------
+
+    def _action(
+        self,
+        resource_id: str,
+        action: str,
+        *,
+        method: str = "POST",
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        return self._transport.request(
+            method,
+            f"{self._detail(resource_id)}{action}/",
+            json=json,
+            params=params,
+            idempotency_key=_resolve_key(idempotency_key),
+        )
+
+
+def _resolve_key(value: str | bool | None) -> str | None:
+    if value is True:
+        return new_idempotency_key()
+    if value in (False, None):
+        return None
+    return str(value)

voxcore_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+voxcore/__about__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+voxcore/__init__.py,sha256=sb7tLHwxcbG8BGsyUEzOeRI8yMhc2bXtSrr83u8XRN8,861
+voxcore/_http.py,sha256=1FuoWYBgQQH4_3dpoprDkXAD_HZd7NeBq49tmDFHyPo,8847
+voxcore/client.py,sha256=Ii7E1MSIFMynNXP5hL7LWPcpjfYWPiOH9tv6NX2AAyQ,4858
+voxcore/errors.py,sha256=aQB4ztLEIRXOUejAcxWgt7Im8nwZMCwfPDqNEK_GB8I,5141
+voxcore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+voxcore/resources/__init__.py,sha256=mYhYjpxM0WYDSk1W9xEF20uzPZEoFLqSkTbzFcwtpU8,9739
+voxcore/resources/_base.py,sha256=_MRMYAeefZcjBbbYev9cK2oxgl43Wc_bd4v9QQf0IYU,5024
+voxcore_sdk-0.1.0.dist-info/METADATA,sha256=osHbZEiIiTFgPCuQns45CPdvN-2iWBn0kZyaOePqHWs,6667
+voxcore_sdk-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+voxcore_sdk-0.1.0.dist-info/RECORD,,

voxcore_sdk-0.1.0.dist-info/WHEEL

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