callstorm 0.1.0__py3-none-any.whl

callstorm/__init__.py

@@ -0,0 +1,29 @@
+"""Official Python SDK for the Callstorm API.
+
+    from callstorm import Callstorm
+
+    client = Callstorm(api_key="vx_live_…")
+    for call in client.calls.list(campaign_id="cmp_…"):
+        print(call["phone"], call["disposition"])
+"""
+from .client import DEFAULT_BASE_URL, VERSION, Callstorm, RateLimit, Response, Transport, urllib_transport
+from .errors import (
+    ApiError, AuthenticationError, CallstormError, ConflictError, ForbiddenError, InsufficientCreditsError, NetworkError, NotFoundError,
+    PayloadTooLargeError, PreconditionError, ProcessingFailedError, RateLimitError, ServerError, ValidationError, WaitTimeoutError,
+    WebhookSignatureError, error_from_response,
+)
+from .pagination import Page, Paginator
+from .webhooks import (
+    DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, WEBHOOK_EVENTS, WebhookEvent, is_balance_low, is_campaign_status_changed, parse_event,
+    sign_payload, verify_signature,
+)
+
+__version__ = VERSION
+__all__ = [
+    "Callstorm", "DEFAULT_BASE_URL", "VERSION", "RateLimit", "Response", "Transport", "urllib_transport", "Page", "Paginator",
+    "ApiError", "AuthenticationError", "CallstormError", "ConflictError", "ForbiddenError", "InsufficientCreditsError", "NetworkError",
+    "NotFoundError", "PayloadTooLargeError", "PreconditionError", "ProcessingFailedError", "RateLimitError", "ServerError", "ValidationError",
+    "WaitTimeoutError", "WebhookSignatureError", "error_from_response",
+    "DELIVERY_HEADER", "EVENT_HEADER", "SIGNATURE_HEADER", "WEBHOOK_EVENTS", "WebhookEvent", "is_balance_low", "is_campaign_status_changed",
+    "parse_event", "sign_payload", "verify_signature",
+]

callstorm/client.py

@@ -0,0 +1,244 @@
+"""The HTTP client: authentication, JSON, timeouts, idempotency, rate-limit bookkeeping and retries."""
+from __future__ import annotations
+
+import json
+import platform
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Mapping, Optional, Sequence, Union
+
+from .errors import CallstormError, NetworkError, error_from_response
+from .resources.account import Account
+from .resources.agents import Agents
+from .resources.api_keys import ApiKeys
+from .resources.calls import Calls
+from .resources.campaigns import Campaigns
+from .resources.credits import Credits
+from .resources.dnc import Dnc
+from .resources.exports import Exports
+from .resources.files import Files
+from .resources.lead_lists import LeadLists
+from .resources.templates import Templates
+from .resources.webhooks import Webhooks
+
+VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://api.callstorm.ai/v1/ext"
+_MAX_429_WAIT = 60.0
+
+QueryValue = Union[str, int, float, bool, None, Sequence[Union[str, int]]]
+Query = Mapping[str, QueryValue]
+
+
+@dataclass
+class Response:
+    """What a transport returns: status, lower-cased headers and the raw body."""
+
+    status: int
+    headers: Dict[str, str]
+    body: bytes
+
+
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Response]
+"""``transport(method, url, headers, body, timeout) -> Response``; raises on network failure."""
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Response:
+    """Default transport on the standard library."""
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (https URLs only)
+            return Response(r.status, {k.lower(): v for k, v in r.headers.items()}, r.read())
+    except urllib.error.HTTPError as e:
+        return Response(e.code, {k.lower(): v for k, v in e.headers.items()}, e.read())
+
+
+@dataclass
+class RateLimit:
+    """Window of the key as the last answer reported it (``X-RateLimit-*``)."""
+
+    limit: int
+    remaining: int
+    reset_at: str
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.5 * (2 ** attempt), 8.0)
+
+
+def _parse_iso(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+class Callstorm:
+    """Client of the Callstorm API.
+
+    :param api_key: ``vx_live_…`` (production) or ``vx_test_…`` (sandbox).
+    :param base_url: defaults to ``https://api.callstorm.ai/v1/ext``.
+    :param timeout: per-request timeout in seconds (30).
+    :param max_retries: retries after a 429, a 502/503/504 or a network failure (2); writes retry only with an
+        idempotency key.
+    :param use_bearer: send the key as ``Authorization: Bearer`` instead of ``X-Api-Key``.
+    :param transport: alternative transport (tests, proxies).
+    """
+
+    def __init__(
+        self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, max_retries: int = 2, use_bearer: bool = False,
+        user_agent: Optional[str] = None, transport: Optional[Transport] = None, sleep: Callable[[float], None] = time.sleep,
+    ):
+        if not api_key:
+            raise CallstormError("api_key is required (vx_live_… or vx_test_…)")
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.use_bearer = use_bearer
+        self.user_agent = user_agent or f"callstorm-python/{VERSION} (python {platform.python_version()})"
+        self._transport = transport or urllib_transport
+        self._sleep = sleep
+        #: Rate-limit window of the key as of the last answer.
+        self.rate_limit: Optional[RateLimit] = None
+        #: True when the last answer was a replay of an earlier request with the same ``Idempotency-Key``.
+        self.last_replayed = False
+        self.last_response: Optional[Response] = None
+        self.campaigns = Campaigns(self)
+        self.templates = Templates(self)
+        self.lead_lists = LeadLists(self)
+        self.files = Files(self)
+        self.dnc = Dnc(self)
+        self.calls = Calls(self)
+        self.exports = Exports(self)
+        self.account = Account(self)
+        self.agents = Agents(self)
+        self.credits = Credits(self)
+        self.webhooks = Webhooks(self)
+        self.api_keys = ApiKeys(self)
+
+    # ---- shortcuts
+    def me(self) -> Dict[str, Any]:
+        """Who the key belongs to: ``{"user": …, "account": …}``."""
+        return self.get("/me")
+
+    def dashboard(self) -> Dict[str, Any]:
+        return self.get("/dashboard")
+
+    def get(self, path: str, query: Optional[Query] = None) -> Any:
+        return self.request("GET", path, query=query)
+
+    def post(self, path: str, body: Any = None, *, idempotency_key: Optional[str] = None, query: Optional[Query] = None) -> Any:
+        return self.request("POST", path, body=body, idempotency_key=idempotency_key, query=query)
+
+    def put(self, path: str, body: Any = None, *, idempotency_key: Optional[str] = None) -> Any:
+        return self.request("PUT", path, body=body, idempotency_key=idempotency_key)
+
+    def patch(self, path: str, body: Any = None, *, idempotency_key: Optional[str] = None) -> Any:
+        return self.request("PATCH", path, body=body, idempotency_key=idempotency_key)
+
+    def delete(self, path: str, *, idempotency_key: Optional[str] = None) -> Any:
+        return self.request("DELETE", path, idempotency_key=idempotency_key)
+
+    # ---- core
+    def request(
+        self, method: str, path: str, *, query: Optional[Query] = None, body: Any = None, idempotency_key: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """One API call with authentication, JSON, timeout, rate-limit bookkeeping and retries. Returns the parsed JSON (None on 204)."""
+        url = self.url(path, query)
+        data = None if method in ("GET", "DELETE") else json.dumps({} if body is None else body).encode("utf-8")
+        hdrs: Dict[str, str] = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if self.use_bearer:
+            hdrs["Authorization"] = f"Bearer {self._api_key}"
+        else:
+            hdrs["X-Api-Key"] = self._api_key
+        if data is not None:
+            hdrs["Content-Type"] = "application/json"
+        if idempotency_key:
+            hdrs["Idempotency-Key"] = idempotency_key
+        if headers:
+            hdrs.update(headers)
+        retriable = method == "GET" or bool(idempotency_key)
+        attempt = 0
+        while True:
+            try:
+                res = self._transport(method, url, hdrs, data, self.timeout)
+            except (urllib.error.URLError, socket.timeout, ssl.SSLError, ConnectionError, TimeoutError, OSError) as e:
+                if retriable and attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise NetworkError(f"{method} {path}: {e}") from e
+            self.last_response = res
+            self._read_rate_limit(res.headers)
+            self.last_replayed = res.headers.get("idempotent-replayed", "").lower() == "true"
+            if 200 <= res.status < 300:
+                if res.status == 204 or not res.body:
+                    return None
+                return json.loads(res.body.decode("utf-8"))
+            err_body = self._error_body(res.body)
+            if res.status == 429 and attempt < self.max_retries:
+                self._sleep(self._wait_for_429(err_body, res.headers))
+                attempt += 1
+                continue
+            if res.status in (502, 503, 504) and retriable and attempt < self.max_retries:
+                self._sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            raise error_from_response(res.status, err_body, self.last_replayed)
+
+    def upload(self, url: str, data: bytes, headers: Mapping[str, str], method: str = "PUT") -> None:
+        """Raw request outside the API (pre-signed S3 uploads)."""
+        try:
+            res = self._transport(method, url, dict(headers), data, max(self.timeout, 120.0))
+        except (urllib.error.URLError, socket.timeout, ssl.SSLError, ConnectionError, TimeoutError, OSError) as e:
+            raise NetworkError(f"upload: {e}") from e
+        if not 200 <= res.status < 300:
+            raise NetworkError(f"upload failed with HTTP {res.status}: {res.body[:300]!r}", status=res.status)
+
+    def url(self, path: str, query: Optional[Query] = None) -> str:
+        """``path`` joined to the base URL, with the query serialised the way the API reads it (lists comma-separated, blanks skipped)."""
+        params = []
+        for k, v in (query or {}).items():
+            if v is None or v == "" or (isinstance(v, (list, tuple)) and not v):
+                continue
+            if isinstance(v, bool):
+                params.append((k, "true" if v else "false"))
+            elif isinstance(v, (list, tuple)):
+                params.append((k, ",".join(str(x) for x in v)))
+            else:
+                params.append((k, str(v)))
+        qs = urllib.parse.urlencode(params)
+        return self.base_url + (path if path.startswith("/") else "/" + path) + (f"?{qs}" if qs else "")
+
+    # ---- helpers
+    def _read_rate_limit(self, h: Mapping[str, str]) -> None:
+        limit, remaining, reset_at = h.get("x-ratelimit-limit"), h.get("x-ratelimit-remaining"), h.get("x-ratelimit-reset")
+        if limit and remaining and reset_at:
+            try:
+                self.rate_limit = RateLimit(int(limit), int(remaining), reset_at)
+            except ValueError:
+                pass
+
+    @staticmethod
+    def _error_body(raw: bytes) -> Optional[Dict[str, Any]]:
+        try:
+            parsed = json.loads(raw.decode("utf-8"))
+            return parsed if isinstance(parsed, dict) else None
+        except ValueError:
+            text = raw.decode("utf-8", "replace").strip()
+            return {"code": "HTTP_ERROR", "message": text[:300]} if text else None
+
+    def _wait_for_429(self, body: Optional[Dict[str, Any]], headers: Mapping[str, str]) -> float:
+        details = body.get("details") if isinstance(body, dict) else None
+        at = _parse_iso((details or {}).get("resetAt") if isinstance(details, dict) else None) or _parse_iso(headers.get("x-ratelimit-reset"))
+        wait = (at - datetime.now(timezone.utc)).total_seconds() if at else 1.0
+        return min(max(wait, 0.0) + 0.1, _MAX_429_WAIT)

callstorm/errors.py

@@ -0,0 +1,123 @@
+"""Errors raised by the SDK. Every API failure maps by HTTP status to a class; `code` keeps the API's own code."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+def _parse_iso(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+class CallstormError(Exception):
+    """Base class of every error raised by the SDK."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None, details: Any = None, replayed: bool = False):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+        #: True when the answer was a replay of an earlier request with the same ``Idempotency-Key``.
+        self.replayed = replayed
+
+
+class ApiError(CallstormError):
+    """The API answered with an error status."""
+
+
+class ValidationError(ApiError):
+    """400: the request body or query is invalid; ``issues`` lists each field."""
+
+    @property
+    def issues(self) -> List[Dict[str, Any]]:
+        d = self.details
+        if isinstance(d, list):
+            return d
+        if isinstance(d, dict) and isinstance(d.get("issues"), list):
+            return d["issues"]
+        return []
+
+
+class AuthenticationError(ApiError):
+    """401: missing, invalid, revoked or expired API key."""
+
+
+class InsufficientCreditsError(ApiError):
+    """402: the account balance does not cover the operation (``details['balanceMicros']``)."""
+
+
+class ForbiddenError(ApiError):
+    """403: the key lacks the scope, or the account is suspended (``ACCOUNT_SUSPENDED``)."""
+
+
+class NotFoundError(ApiError):
+    """404: no such resource."""
+
+
+class ConflictError(ApiError):
+    """409: the resource is not in a state that allows the operation (``INVALID_TRANSITION``, ``NOT_DRAFT``, ``IN_USE``…)."""
+
+
+class PreconditionError(ApiError):
+    """412: the account misses a prerequisite (``CARRIER_NOT_CONFIGURED``, ``ELEVENLABS_NOT_CONFIGURED``)."""
+
+
+class PayloadTooLargeError(ApiError):
+    """413: the file exceeds the size allowed for its kind."""
+
+
+class RateLimitError(ApiError):
+    """429: the key's per-minute limit was exceeded; ``reset_at`` says when the window opens again."""
+
+    @property
+    def reset_at(self) -> Optional[datetime]:
+        d = self.details if isinstance(self.details, dict) else {}
+        return _parse_iso(d.get("resetAt"))
+
+    @property
+    def retry_after_seconds(self) -> float:
+        at = self.reset_at
+        if not at:
+            return 0.0
+        return max(0.0, (at - datetime.now(timezone.utc)).total_seconds())
+
+
+class ServerError(ApiError):
+    """5xx: the API or one of its providers failed; safe to retry reads and idempotent writes."""
+
+
+class NetworkError(CallstormError):
+    """The request never got an answer: DNS, TLS, connection reset or timeout."""
+
+
+class WaitTimeoutError(CallstormError):
+    """A ``wait_until_…`` helper gave up before the resource reached its final state."""
+
+
+class ProcessingFailedError(CallstormError):
+    """The resource ended in an error state while a ``wait_until_…`` helper was polling it."""
+
+
+class WebhookSignatureError(CallstormError):
+    """The ``X-Voxcore-Signature`` of a webhook delivery does not match the secret."""
+
+
+_BY_STATUS = {
+    400: ValidationError, 401: AuthenticationError, 402: InsufficientCreditsError, 403: ForbiddenError, 404: NotFoundError,
+    405: NotFoundError, 409: ConflictError, 412: PreconditionError, 413: PayloadTooLargeError, 429: RateLimitError,
+}
+
+
+def error_from_response(status: int, body: Optional[Dict[str, Any]], replayed: bool = False) -> ApiError:
+    """Builds the typed error for an API answer."""
+    body = body if isinstance(body, dict) else {}
+    code = body.get("code") or ("UNAUTHORIZED" if status == 401 else "HTTP_ERROR")
+    text = body.get("message")
+    message = f"{text} ({code}, HTTP {status})" if text else f"HTTP {status} ({code})"
+    cls = ServerError if status >= 500 else _BY_STATUS.get(status, ApiError)
+    return cls(message, status=status, code=code, details=body.get("details"), replayed=replayed)

callstorm/pagination.py

@@ -0,0 +1,51 @@
+"""Cursor pagination: iterate items, pages, or collect them."""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+Page = Dict[str, Any]
+"""One page: ``{"items": [...], "nextCursor": str | None, "total": int | None}``. ``nextCursor`` is absent on the last page."""
+
+
+class Paginator(Generic[T]):
+    """Lazy walker over a cursor-paginated endpoint.
+
+    Iterate it for items, call :meth:`pages` for pages or :meth:`all` to collect. Pages can be short or empty while a
+    cursor is still present (filters apply after the page is read), so the walker goes on until the API stops
+    returning a cursor.
+    """
+
+    def __init__(self, fetch_page: Callable[[Optional[str]], Page]):
+        self._fetch_page = fetch_page
+
+    def page(self, cursor: Optional[str] = None) -> Page:
+        """The first page, or the page after ``cursor``."""
+        return self._fetch_page(cursor)
+
+    def first_page(self) -> Page:
+        return self._fetch_page(None)
+
+    def pages(self) -> Iterator[Page]:
+        cursor: Optional[str] = None
+        while True:
+            page = self._fetch_page(cursor)
+            yield page
+            cursor = page.get("nextCursor") or None
+            if not cursor:
+                return
+
+    def __iter__(self) -> Iterator[T]:
+        for page in self.pages():
+            for item in page.get("items") or []:
+                yield item
+
+    def all(self, max_items: Optional[int] = None) -> List[T]:
+        """Every item, or at most ``max_items`` of them, in one list."""
+        out: List[T] = []
+        for item in self:
+            out.append(item)
+            if max_items is not None and len(out) >= max_items:
+                break
+        return out

callstorm/resources/__init__.py

@@ -0,0 +1,18 @@
+"""Resource classes; each wraps one part of the API and is reachable as an attribute of :class:`callstorm.Callstorm`."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..client import Callstorm
+
+
+def seg(value: str) -> str:
+    """One path segment, URL-encoded (``+`` of an E.164 number included)."""
+    return quote(str(value), safe="")
+
+
+class Resource:
+    def __init__(self, client: "Callstorm"):
+        self._client = client

callstorm/resources/account.py

@@ -0,0 +1,48 @@
+"""Telephony of the account: engine cells, SIP trunks and caller IDs (``settings:telephony`` for writes)."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from . import Resource, seg
+
+
+class Account(Resource):
+    def cells(self) -> List[Dict[str, Any]]:
+        """Engine cells with the public IPs to allow on the carrier."""
+        return self._client.get("/account/cells")
+
+    def trunks(self) -> List[Dict[str, Any]]:
+        return self._client.get("/account/trunks")
+
+    def create_trunk(self, trunk: Dict[str, Any], *, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """``{"name", "ip", "transport", "channels", "cps", "port"?, "domain"?, "sipUser"?, "sipPass"?, "prefix"?, "cellId"?}``."""
+        return self._client.post("/account/trunks", trunk, idempotency_key=idempotency_key)
+
+    def trunk(self, trunk_id: str) -> Dict[str, Any]:
+        return self._client.get(f"/account/trunks/{seg(trunk_id)}")
+
+    def update_trunk(self, trunk_id: str, trunk: Dict[str, Any]) -> Dict[str, Any]:
+        return self._client.put(f"/account/trunks/{seg(trunk_id)}", trunk)
+
+    def delete_trunk(self, trunk_id: str) -> None:
+        self._client.delete(f"/account/trunks/{seg(trunk_id)}")
+
+    def test_trunk(self, trunk_id: str) -> Dict[str, Any]:
+        """SIP OPTIONS round trip against the carrier: ``{"ok", "error"?, "latencyMs"?}``."""
+        return self._client.post(f"/account/trunks/{seg(trunk_id)}/test", {})
+
+    def caller_ids(self) -> List[Dict[str, Any]]:
+        return self._client.get("/account/caller-ids")
+
+    def create_caller_id(self, e164: str, country: str, trunk_id: str, *, label: Optional[str] = None, **extra: Any) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"e164": e164, "country": country, "trunkId": trunk_id, **extra}
+        if label:
+            body["label"] = label
+        return self._client.post("/account/caller-ids", body)
+
+    def update_caller_id(self, e164: str, changes: Dict[str, Any]) -> Dict[str, Any]:
+        """``{"trunkId", "label"?, "kind"?, "templateId"?}``."""
+        return self._client.put(f"/account/caller-ids/{seg(e164)}", changes)
+
+    def delete_caller_id(self, e164: str) -> None:
+        self._client.delete(f"/account/caller-ids/{seg(e164)}")

callstorm/resources/agents.py

@@ -0,0 +1,44 @@
+"""Human agents of the account (contact center) and the token that embeds their console in a CRM."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from . import Resource, seg
+
+
+class Agents(Resource):
+    def list(self) -> List[Dict[str, Any]]:
+        return self._client.get("/agents")
+
+    def get(self, agent_id: str) -> Dict[str, Any]:
+        return self._client.get(f"/agents/{seg(agent_id)}")
+
+    def create(self, name: str, email: str, *, extension: Optional[str] = None, cell_id: Optional[str] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "email": email}
+        if extension:
+            body["extension"] = extension
+        if cell_id:
+            body["cellId"] = cell_id
+        return self._client.post("/agents", body, idempotency_key=idempotency_key)
+
+    def update(self, agent_id: str, changes: Dict[str, Any]) -> Dict[str, Any]:
+        """``{"name"?, "extension"?, "cellId"?}``."""
+        return self._client.patch(f"/agents/{seg(agent_id)}", changes)
+
+    def delete(self, agent_id: str) -> None:
+        self._client.delete(f"/agents/{seg(agent_id)}")
+
+    def set_status(self, agent_id: str, status: str, *, pause_reason: Optional[str] = None) -> Dict[str, Any]:
+        """Forces the presence of an agent (supervisor action)."""
+        body: Dict[str, Any] = {"status": status}
+        if pause_reason:
+            body["pauseReason"] = pause_reason
+        return self._client.post(f"/agents/{seg(agent_id)}/status", body)
+
+    def sip_credentials(self, agent_id: str) -> Dict[str, Any]:
+        """SIP credentials of the agent's softphone on the cell's SBC."""
+        return self._client.post(f"/agents/{seg(agent_id)}/sip-credentials", {})
+
+    def session_token(self, agent_id: str, *, ttl_sec: Optional[int] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Short-lived token for the embedded console (``ttl_sec`` 300 to 43 200, default 8 h); hand ``embedUrl`` to the browser."""
+        return self._client.post(f"/agents/{seg(agent_id)}/session-token", {"ttlSec": ttl_sec} if ttl_sec else {}, idempotency_key=idempotency_key)

callstorm/resources/api_keys.py

@@ -0,0 +1,22 @@
+"""API keys of the account. Creating and revoking need a user session (the web app); an API key can only list them."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from . import Resource, seg
+
+
+class ApiKeys(Resource):
+    def list(self) -> List[Dict[str, Any]]:
+        return self._client.get("/account/api-keys")
+
+    def create(self, name: str, scopes: Sequence[str], *, expires_at: Optional[str] = None, rate_limit_per_min: Optional[int] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "scopes": list(scopes)}
+        if expires_at:
+            body["expiresAt"] = expires_at
+        if rate_limit_per_min:
+            body["rateLimitPerMin"] = rate_limit_per_min
+        return self._client.post("/account/api-keys", body)
+
+    def delete(self, key_id: str) -> None:
+        self._client.delete(f"/account/api-keys/{seg(key_id)}")

callstorm/resources/calls.py

@@ -0,0 +1,40 @@
+"""Calls made by the campaigns: list, aggregates and the detail with transcript and recording URLs."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence, Union
+
+from ..pagination import Paginator
+from . import Resource, seg
+
+
+def _filters(
+    campaign_id: Optional[str], type: Optional[str], direction: Optional[str], from_: Optional[str], to: Optional[str],
+    disposition: Union[str, Sequence[str], None], result_code: Union[str, Sequence[str], None], phone: Optional[str], q: Optional[str], agent_id: Optional[str],
+) -> Dict[str, Any]:
+    return {
+        "campaignId": campaign_id, "type": type, "direction": direction, "from": from_, "to": to, "disposition": disposition,
+        "resultCode": result_code, "phone": phone, "q": q, "agentId": agent_id,
+    }
+
+
+class Calls(Resource):
+    def list(
+        self, *, campaign_id: Optional[str] = None, type: Optional[str] = None, direction: Optional[str] = None, from_: Optional[str] = None,
+        to: Optional[str] = None, disposition: Union[str, Sequence[str], None] = None, result_code: Union[str, Sequence[str], None] = None,
+        phone: Optional[str] = None, q: Optional[str] = None, agent_id: Optional[str] = None, sort: Optional[str] = None, limit: Optional[int] = None,
+    ) -> Paginator[Dict[str, Any]]:
+        """``sort`` is ``startedAt|durationSec|attemptNo`` with ``:asc`` or ``:desc`` (default ``startedAt:desc``)."""
+        params = {**_filters(campaign_id, type, direction, from_, to, disposition, result_code, phone, q, agent_id), "sort": sort, "limit": limit}
+        return Paginator(lambda cursor: self._client.get("/calls", {**params, "cursor": cursor}))
+
+    def summary(
+        self, *, campaign_id: Optional[str] = None, type: Optional[str] = None, direction: Optional[str] = None, from_: Optional[str] = None,
+        to: Optional[str] = None, disposition: Union[str, Sequence[str], None] = None, result_code: Union[str, Sequence[str], None] = None,
+        phone: Optional[str] = None, q: Optional[str] = None, agent_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Totals by disposition and result code for the same filters as :meth:`list`."""
+        return self._client.get("/calls/summary", _filters(campaign_id, type, direction, from_, to, disposition, result_code, phone, q, agent_id))
+
+    def get(self, call_id: str) -> Dict[str, Any]:
+        """Detail with transcript, answers and pre-signed recording URLs valid for five minutes."""
+        return self._client.get(f"/calls/{seg(call_id)}")