pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/channels/routes.py

@@ -0,0 +1,275 @@
+"""Which agent answers a number or a channel, per org and world: the routes table."""
+
+from dataclasses import dataclass
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.call import Route
+from pinecall.domain.names import Channel, Env, RouteOrigin
+from pinecall.postgres.pool import Pool, box_wide
+
+OF_ORG = """
+SELECT org, number, agent, channel, env, managed FROM routes
+WHERE org = %(org)s AND env = %(env)s
+ORDER BY added_at, number
+"""
+# One org holds a number (routes_number_held_once), so a number reads one row at most.
+AT = """
+SELECT org, number, agent, channel, env, managed FROM routes
+WHERE channel = %(channel)s AND number = %(number)s
+"""
+OF_NUMBER = """
+SELECT org, number, agent, channel, env, managed FROM routes
+WHERE org = %(org)s AND number = %(number)s
+"""
+# A number added again moves: its agent, channel, world and how it came are the newest said. One
+# written to wait (a hooked number, where the box asks for approval) is unapproved until the
+# operator approves it; one approved once stays approved however it comes again.
+PUT = """
+INSERT INTO routes (org, number, agent, channel, env, managed, account, networks, origin, via,
+                    approved_at)
+VALUES (%(org)s, %(number)s, %(agent)s, %(channel)s, %(env)s, %(managed)s, %(account)s,
+        %(networks)s, %(origin)s, %(via)s,
+        CASE WHEN %(waits)s THEN NULL ELSE now() END)
+ON CONFLICT (org, number) DO UPDATE SET agent = excluded.agent, channel = excluded.channel,
+    env = excluded.env, managed = excluded.managed, account = excluded.account,
+    networks = excluded.networks, origin = excluded.origin, via = excluded.via,
+    approved_at = COALESCE(routes.approved_at, excluded.approved_at)
+"""
+APPROVE = """
+UPDATE routes SET approved_at = now(), approved_by = %(by)s
+WHERE org = %(org)s AND number = %(number)s AND approved_at IS NULL
+RETURNING number
+"""
+WAITING = """
+SELECT 1 FROM routes WHERE org = %(org)s AND number = %(number)s AND approved_at IS NULL
+"""
+ELSEWHERE = "SELECT 1 FROM routes WHERE number = %(number)s AND org <> %(org)s"
+REMOVE = "DELETE FROM routes WHERE org = %(org)s AND number = %(number)s RETURNING number"
+MOVE = "UPDATE routes SET env = %(env)s WHERE org = %(org)s AND number = %(number)s RETURNING env"
+MANAGED = "SELECT count(*) AS bought FROM routes WHERE org = %(org)s AND env = %(env)s AND managed"
+# A number the target org already typed stays where it was: one row per number per org.
+WITH_AGENT = """
+UPDATE routes SET org = %(org)s
+WHERE agent = %(agent)s AND org <> %(org)s
+  AND NOT EXISTS (SELECT 1 FROM routes AS theirs WHERE theirs.org = %(org)s
+                  AND theirs.number = routes.number)
+RETURNING number
+"""
+STAYED = "SELECT number FROM routes WHERE agent = %(agent)s AND org <> %(org)s ORDER BY number"
+# A number rung all day is written once a minute, never once a call.
+CALLED = """
+UPDATE routes SET last_call_at = now()
+WHERE org = %(org)s AND number = %(number)s
+  AND (last_call_at IS NULL OR last_call_at < now() - interval '1 minute')
+"""
+# A row with what the table keeps beside it: how it was written, the kind of the account its
+# number lives in, and whether the operator approved it.
+RECORDS = """
+SELECT routes.org, routes.number, routes.agent, routes.channel, routes.env, routes.managed,
+       routes.origin, routes.via, routes.last_call_at, routes.account, routes.networks,
+       routes.approved_at IS NOT NULL AS approved,
+       carriers.kind AS carrier
+FROM routes LEFT JOIN carriers
+    ON carriers.org = routes.org AND carriers.account = routes.account
+"""
+
+
+@dataclass(frozen=True)
+class RouteWrite:
+    """What a row keeps beside its route: who wrote it, the account, the networks, the carrier."""
+
+    origin: RouteOrigin
+    account: str | None = None
+    # A number hooked from networks of the org's own, which the operator approves.
+    networks: tuple[str, ...] = ()
+    # The catalog carrier a number with no account comes through.
+    via: str | None = None
+    # Written unapproved: no call to it opens until the operator approves it.
+    waits: bool = False
+
+
+@dataclass(frozen=True)
+class RouteRecord:
+    """A route with how it was written, its account's kind, and whether it was approved."""
+
+    route: Route
+    origin: RouteOrigin
+    # None for a number no account of the org holds: bought by the box, hooked, typed, or an
+    # account since forgotten.
+    carrier: str | None
+    via: str | None = None
+    # When a call to the number last reached the box; None when none ever did.
+    last_call_at: float | None = None
+    # The org's account the number lives in, and a hooked number's own networks.
+    account: str | None = None
+    networks: tuple[str, ...] = ()
+    # False for a number the org hooked that the operator has not approved: no call to it opens.
+    approved: bool = True
+
+
+ON_THE_BOX = RECORDS + "ORDER BY routes.number, routes.channel, routes.added_at"
+OF_NUMBER_RECORD = RECORDS + "WHERE routes.org = %(org)s AND routes.number = %(number)s"
+PHONES_OF_ORG = (
+    RECORDS
+    + "WHERE routes.org = %(org)s AND routes.channel = 'phone' AND routes.number IS NOT NULL "
+    + "ORDER BY routes.added_at, routes.number"
+)
+OF_ORG_RECORDS = (
+    RECORDS
+    + "WHERE routes.org = %(org)s AND routes.env = %(env)s ORDER BY routes.added_at, routes.number"
+)
+
+
+async def of_org(pool: Pool, org: str, env: Env) -> list[Route]:
+    """The org's numbers in one world, oldest first."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OF_ORG, {"org": org, "env": env})).fetchall()
+    return [_route(row) for row in rows]
+
+
+async def at(pool: Pool, channel: Channel, number: str) -> Route | None:
+    """The route a call dialled to this number takes, whatever org holds it."""
+    params = {"channel": channel, "number": number}
+    with box_wide():
+        async with pool.connection() as connection:
+            row = await (await connection.execute(AT, params)).fetchone()
+    return None if row is None else _route(row)
+
+
+async def on_the_box(pool: Pool) -> list[RouteRecord]:
+    """Every route of every org and world, by number, and which of them answers each number."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(ON_THE_BOX)).fetchall()
+    return [_record(row) for row in rows]
+
+
+async def records_of(pool: Pool, org: str, env: Env) -> list[RouteRecord]:
+    """The org's routes in one world, oldest first, each with what the table keeps beside it."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OF_ORG_RECORDS, {"org": org, "env": env})).fetchall()
+    return [_record(row) for row in rows]
+
+
+async def phones_of(pool: Pool, org: str) -> list[RouteRecord]:
+    """The org's phone numbers in both worlds, oldest first, with what the table keeps."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(PHONES_OF_ORG, {"org": org})).fetchall()
+    return [_record(row) for row in rows]
+
+
+async def record_of(pool: Pool, org: str, number: str) -> RouteRecord | None:
+    """The org's route at this number, whatever world it is in, with what the table keeps."""
+    params = {"org": org, "number": number}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(OF_NUMBER_RECORD, params)).fetchone()
+    return None if row is None else _record(row)
+
+
+async def of_number(pool: Pool, org: str, number: str) -> Route | None:
+    """The org's route at this number, whatever world it is in."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(OF_NUMBER, {"org": org, "number": number})).fetchone()
+    return None if row is None else _route(row)
+
+
+async def put(pool: Pool, route: Route, written: RouteWrite) -> None:
+    """Keep the route, moving the number if the org had it, with how it was written."""
+    row = {
+        "org": route.org,
+        "number": route.number,
+        "agent": route.agent,
+        "channel": route.channel,
+        "env": route.env,
+        "managed": route.managed,
+        "account": written.account,
+        "networks": list(written.networks),
+        "origin": written.origin,
+        "via": written.via,
+        "waits": written.waits,
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT, row)
+
+
+async def called(pool: Pool, org: str, number: str) -> None:
+    """Note that a call to the org's number reached the box now."""
+    async with pool.connection() as connection:
+        await connection.execute(CALLED, {"org": org, "number": number})
+
+
+async def approve(pool: Pool, org: str, number: str, by: str) -> bool:
+    """The operator's word that the org's hooked number is the org's; whether one waited."""
+    async with pool.connection() as connection:
+        done = await connection.execute(APPROVE, {"org": org, "number": number, "by": by})
+        return await done.fetchone() is not None
+
+
+async def is_waiting(pool: Pool, org: str, number: str) -> bool:
+    """Whether the org's number is one it hooked that the operator has not approved."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(WAITING, {"org": org, "number": number})).fetchone()
+    return row is not None
+
+
+async def held_elsewhere(pool: Pool, org: str, number: str) -> bool:
+    """Whether another org holds the number on this box."""
+    with box_wide():
+        async with pool.connection() as connection:
+            found = await connection.execute(ELSEWHERE, {"org": org, "number": number})
+            return await found.fetchone() is not None
+
+
+async def remove(pool: Pool, org: str, number: str) -> bool:
+    """Forget the org's route at the number; whether there was one."""
+    async with pool.connection() as connection:
+        gone = await connection.execute(REMOVE, {"org": org, "number": number})
+        return await gone.fetchone() is not None
+
+
+async def moved(pool: Pool, org: str, number: str, env: Env) -> bool:
+    """Move the org's number into the world; whether it had it."""
+    async with pool.connection() as connection:
+        done = await connection.execute(MOVE, {"org": org, "number": number, "env": env})
+        return await done.fetchone() is not None
+
+
+async def moved_with_agent(pool: Pool, agent: str, org: str) -> tuple[list[str], list[str]]:
+    """Move the agent's numbers into the org; the numbers moved, and the ones that stayed."""
+    async with pool.connection() as connection, connection.transaction():
+        moved = await (
+            await connection.execute(WITH_AGENT, {"agent": agent, "org": org})
+        ).fetchall()
+        stayed = await (await connection.execute(STAYED, {"agent": agent, "org": org})).fetchall()
+    return sorted(str(row["number"]) for row in moved), [str(row["number"]) for row in stayed]
+
+
+async def managed_in(pool: Pool, org: str, env: Env) -> int:
+    """How many of the org's numbers in the world the box bought."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(MANAGED, {"org": org, "env": env})).fetchone()
+    return 0 if row is None else int(row["bought"])
+
+
+def _route(row: DictRow) -> Route:
+    return Route(
+        org=row["org"],
+        agent=row["agent"],
+        channel=row["channel"],
+        number=row["number"],
+        env=row["env"],
+        managed=row["managed"],
+    )
+
+
+def _record(row: DictRow) -> RouteRecord:
+    return RouteRecord(
+        route=_route(row),
+        origin=row["origin"],
+        carrier=row["carrier"],
+        via=row["via"],
+        last_call_at=None if row["last_call_at"] is None else row["last_call_at"].timestamp(),
+        account=row["account"],
+        networks=tuple(str(network) for network in row["networks"] or ()),
+        approved=bool(row["approved"]),
+    )

pinecall/channels/telephony/_twilio.py

@@ -0,0 +1,349 @@
+"""Twilio's REST API, written by hand: numbers, trunks, credential lists, the shop."""
+
+import logging
+
+import httpx
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    TypeAdapter,
+    ValidationError,
+)
+
+from pinecall.domain.errors import (
+    DeclarationRefused,
+    UpstreamFailed,
+)
+from pinecall.domain.names import Json
+from pinecall.tenancy.carriers import TwilioAccount
+
+logger = logging.getLogger(__name__)
+
+
+TRUNKING = "https://trunking.twilio.com/v1"
+
+
+ACCOUNTS = "https://api.twilio.com/2010-04-01"
+
+
+# Never on a call's path: an import or a purchase waits for Twilio, a call never does.
+TIMEOUT_S = 30.0
+
+
+# livekit-sip listens here, and the fence opens it to the carrier alone.
+SIP_PORT = 5060
+
+
+# Termination hosts are global across Twilio; the label is `[a-z0-9-]`. Twilio wants the whole
+# host in DomainName: a bare label is its error 21245.
+TWILIO_SAID = "Twilio: {message}"
+
+
+TERMINATION_SUFFIX = ".pstn.twilio.com"
+
+
+ROOM_PREFIX = "call-"
+
+
+_OBJECT: TypeAdapter[dict[str, Json]] = TypeAdapter(dict[str, Json])
+
+
+TWILIO_REFUSED = "Twilio refused these credentials for {account}"
+
+
+class TwilioNumber(BaseModel):
+    """A number an account owns, and the trunk it is attached to, if any."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    sid: str
+    phone_number: str
+    friendly_name: str = ""
+    trunk_sid: str | None = None
+
+
+class TwilioTrunk(BaseModel):
+    """A SIP trunk of an account."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    sid: str
+    friendly_name: str = ""
+    domain_name: str | None = None
+
+
+class _Origination(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    sid: str
+    sip_url: str
+
+
+class _Listed(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    sid: str
+    friendly_name: str = ""
+
+
+class _Credential(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    username: str
+
+
+class _ForSale(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    phone_number: str
+
+
+class _Meta(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    next_page_url: str | None = None
+
+
+# The Accounts API names the next page by a path, the Trunking API by a whole URL in `meta`.
+class _Page(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    next_page_uri: str | None = None
+    meta: _Meta | None = None
+
+
+class _Refusal(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    message: str = ""
+
+
+class Twilio:
+    """One Twilio account's REST API, over the box's HTTP client."""
+
+    def __init__(self, http: httpx.AsyncClient, account_sid: str, user: str, secret: str) -> None:
+        """The account and the pair it is asked with; nothing is asked yet."""
+        self.http = http
+        self.sid = account_sid
+        self.auth = httpx.BasicAuth(user, secret)
+        self.home = f"{ACCOUNTS}/Accounts/{account_sid}"
+
+    async def verified(self) -> bool:
+        """Whether the pair opens the account."""
+        answer = await self.http.get(f"{self.home}.json", auth=self.auth, timeout=TIMEOUT_S)
+        if answer.status_code in {httpx.codes.UNAUTHORIZED, httpx.codes.FORBIDDEN}:
+            return False
+        _answer_of(answer)
+        return True
+
+    async def numbers(self) -> list[TwilioNumber]:
+        """Every number the account owns, every page."""
+        listed = await self._every(
+            f"{self.home}/IncomingPhoneNumbers.json?PageSize=200", "incoming_phone_numbers"
+        )
+        return _NUMBERS.validate_python(listed)
+
+    async def number(self, number: str) -> TwilioNumber | None:
+        """The account's number, or None when it owns no such number."""
+        answer = await self._get(f"{self.home}/IncomingPhoneNumbers.json", {"PhoneNumber": number})
+        found = _NUMBERS.validate_python(answer.get("incoming_phone_numbers", []))
+        return found[0] if found else None
+
+    async def trunk_pointing_at(self, uri: str) -> TwilioTrunk | None:
+        """The account's trunk whose origination is this URI, whatever it is named."""
+        found = await self.trunks_pointing_at(uri)
+        return found[0] if found else None
+
+    async def trunks_pointing_at(self, uri: str) -> list[TwilioTrunk]:
+        """Every trunk of the account whose origination is this URI."""
+        trunks = _TRUNKS.validate_python(
+            await self._every(f"{TRUNKING}/Trunks?PageSize=50", "trunks")
+        )
+        return [
+            trunk
+            for trunk in trunks
+            if uri in {origination.sip_url for origination in await self._originations(trunk.sid)}
+        ]
+
+    async def repointed(self, trunk: str, was: str, now: str) -> None:
+        """The trunk's origination that is `was` sent to `now`, its weight and order kept."""
+        for origination in await self._originations(trunk):
+            if origination.sip_url == was:
+                url = f"{TRUNKING}/Trunks/{trunk}/OriginationUrls/{origination.sid}"
+                await self._post(url, {"SipUrl": now})
+
+    async def trunk(self, sid: str) -> TwilioTrunk:
+        """One trunk of the account."""
+        return TwilioTrunk.model_validate(await self._get(f"{TRUNKING}/Trunks/{sid}"))
+
+    async def originations(self, sid: str) -> list[str]:
+        """Where the trunk sends a call."""
+        return [origination.sip_url for origination in await self._originations(sid)]
+
+    async def trunk_made(self, name: str, uri: str) -> TwilioTrunk:
+        """A new trunk, sending its calls to the URI."""
+        made = TwilioTrunk.model_validate(
+            await self._post(f"{TRUNKING}/Trunks", {"FriendlyName": name})
+        )
+        form = {
+            "FriendlyName": name,
+            "SipUrl": uri,
+            "Weight": "10",
+            "Priority": "10",
+            "Enabled": "true",
+        }
+        await self._post(f"{TRUNKING}/Trunks/{made.sid}/OriginationUrls", form)
+        return made
+
+    async def attach(self, trunk: str, number: str) -> None:
+        """Attach the number to the trunk: its voice URL is then ignored."""
+        await self._post(f"{TRUNKING}/Trunks/{trunk}/PhoneNumbers", {"PhoneNumberSid": number})
+
+    async def detach(self, trunk: str, number: str) -> None:
+        """Take the number off a trunk."""
+        answer = await self.http.delete(
+            f"{TRUNKING}/Trunks/{trunk}/PhoneNumbers/{number}", auth=self.auth, timeout=TIMEOUT_S
+        )
+        if answer.is_error:
+            _answer_of(answer)
+
+    async def for_sale(self, country: str, area_code: str | None) -> str | None:
+        """One local voice number on sale in the country, or None."""
+        params = {"VoiceEnabled": "true", "PageSize": "1"} | (
+            {"AreaCode": area_code} if area_code else {}
+        )
+        answer = await self._get(
+            f"{self.home}/AvailablePhoneNumbers/{country.upper()}/Local.json", params
+        )
+        found = _FOR_SALE.validate_python(answer.get("available_phone_numbers", []))
+        return found[0].phone_number if found else None
+
+    async def bought(self, number: str) -> TwilioNumber:
+        """Buy the number onto the account: this costs money."""
+        answer = await self._post(f"{self.home}/IncomingPhoneNumbers.json", {"PhoneNumber": number})
+        return TwilioNumber.model_validate(answer)
+
+    async def terminated(self, trunk: str, host: str) -> None:
+        """Set where the box dials the trunk: <label>.pstn.twilio.com, the whole host."""
+        await self._post(f"{TRUNKING}/Trunks/{trunk}", {"DomainName": host})
+
+    async def credential_list(self, name: str) -> str | None:
+        """The account's credential list by name, or None."""
+        listed = _LISTS.validate_python(
+            await self._every(
+                f"{self.home}/SIP/CredentialLists.json?PageSize=50", "credential_lists"
+            )
+        )
+        return next((found.sid for found in listed if found.friendly_name == name), None)
+
+    async def credential_list_made(self, name: str) -> str:
+        """A new, empty credential list."""
+        made = _Listed.model_validate(
+            await self._post(f"{self.home}/SIP/CredentialLists.json", {"FriendlyName": name})
+        )
+        return made.sid
+
+    async def usernames_in(self, credential_list: str) -> list[str]:
+        """The usernames a credential list holds; never a password, which Twilio never shows."""
+        listed = await self._every(
+            f"{self.home}/SIP/CredentialLists/{credential_list}/Credentials.json", "credentials"
+        )
+        return [credential.username for credential in _CREDENTIALS.validate_python(listed)]
+
+    async def credential_added(self, credential_list: str, username: str, password: str) -> None:
+        """One more credential on the list; Twilio shows its password this once."""
+        form = {"Username": username, "Password": password}
+        await self._post(
+            f"{self.home}/SIP/CredentialLists/{credential_list}/Credentials.json", form
+        )
+
+    async def lists_on(self, trunk: str) -> list[str]:
+        """The credential lists the trunk asks the box for."""
+        listed = await self._every(f"{TRUNKING}/Trunks/{trunk}/CredentialLists", "credential_lists")
+        return [found.sid for found in _LISTS.validate_python(listed)]
+
+    async def list_attached(self, trunk: str, credential_list: str) -> None:
+        """Have the trunk ask the box for this credential."""
+        form = {"CredentialListSid": credential_list}
+        await self._post(f"{TRUNKING}/Trunks/{trunk}/CredentialLists", form)
+
+    async def _originations(self, trunk: str) -> list[_Origination]:
+        listed = await self._every(f"{TRUNKING}/Trunks/{trunk}/OriginationUrls", "origination_urls")
+        return _ORIGINATIONS.validate_python(listed)
+
+    # A listing past its first page silently lost the rest in v1; every page is read.
+    async def _every(self, url: str, key: str) -> list[Json]:
+        found: list[Json] = []
+        following: str | None = url
+        while following is not None:
+            answer = await self._get(following)
+            listed = answer.get(key)
+            found += listed if isinstance(listed, list) else []
+            page = _Page.model_validate(answer)
+            path = page.next_page_uri
+            following = (
+                f"https://{httpx.URL(url).host}{path}"
+                if path
+                else (page.meta.next_page_url if page.meta else None)
+            )
+        return found
+
+    async def _get(self, url: str, params: dict[str, str] | None = None) -> dict[str, Json]:
+        answer = await self.http.get(url, params=params, auth=self.auth, timeout=TIMEOUT_S)
+        return _answer_of(answer)
+
+    async def _post(self, url: str, form: dict[str, str]) -> dict[str, Json]:
+        answer = await self.http.post(url, data=form, auth=self.auth, timeout=TIMEOUT_S)
+        return _answer_of(answer)
+
+
+_NUMBERS: TypeAdapter[list[TwilioNumber]] = TypeAdapter(list[TwilioNumber])
+
+
+_TRUNKS: TypeAdapter[list[TwilioTrunk]] = TypeAdapter(list[TwilioTrunk])
+
+
+_ORIGINATIONS: TypeAdapter[list[_Origination]] = TypeAdapter(list[_Origination])
+
+
+_LISTS: TypeAdapter[list[_Listed]] = TypeAdapter(list[_Listed])
+
+
+_CREDENTIALS: TypeAdapter[list[_Credential]] = TypeAdapter(list[_Credential])
+
+
+_FOR_SALE: TypeAdapter[list[_ForSale]] = TypeAdapter(list[_ForSale])
+
+
+def origination_uri(domain: str) -> str:
+    """The SIP URI a Twilio trunk sends this box's calls to."""
+    return f"sip:{domain}:{SIP_PORT};transport=udp"
+
+
+def termination_host(domain: str, account: str) -> str:
+    """The host the box dials an account through: one per account per box, `[a-z0-9-]`."""
+    named = f"{domain}-{account[-8:]}".lower()
+    label = "".join(letter if letter.isalnum() else "-" for letter in named).strip("-")
+    return f"{label}{TERMINATION_SUFFIX}"
+
+
+def twilio_of(http: httpx.AsyncClient, account: TwilioAccount) -> Twilio:
+    """The account's REST API, asked with its pair."""
+    return Twilio(http, account.account_sid, account.user, account.secret)
+
+
+async def verify(http: httpx.AsyncClient, account: TwilioAccount) -> None:
+    """Refuse a pair Twilio does not open the account with, in our words."""
+    if not await twilio_of(http, account).verified():
+        raise DeclarationRefused(TWILIO_REFUSED.format(account=account.account_sid))
+
+
+# Twilio's own sentence reaches the person; the pair never does.
+def _answer_of(answer: httpx.Response) -> dict[str, Json]:
+    if answer.is_error:
+        try:
+            message = _Refusal.model_validate_json(answer.content).message
+        except ValidationError:
+            message = f"{answer.status_code}"
+        raise UpstreamFailed(TWILIO_SAID.format(message=message or answer.status_code))
+    return _OBJECT.validate_json(answer.content) if answer.content else {}