vintasend-twilio 3.6.0__tar.gz

vintasend_twilio-3.6.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Vinta Serviços e Soluções Tecnológicas Ltda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vintasend_twilio-3.6.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: vintasend-twilio
+Version: 3.6.0
+Summary: Twilio SMS adapter for VintaSend
+License-Expression: MIT
+License-File: LICENSE.txt
+Author: Hugo bessa
+Author-email: hugo@vinta.com.br
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Requires-Dist: twilio (>=9.0.0,<10.0.0)
+Requires-Dist: vintasend (==3.6.0)
+Description-Content-Type: text/markdown
+
+# vintasend-twilio
+
+A [Twilio](https://www.twilio.com/) SMS adapter for
+[vintasend](https://github.com/vintasoftware/vintasend).
+
+VintaSend records every notification, renders it from a template at send time, and hands the
+result to an **adapter** for delivery. This package is an adapter for the `SMS` notification type:
+it renders the notification with any `BaseTemplatedSMSRenderer` and posts the body to Twilio's
+Messages API. Pair it with any vintasend backend and an SMS renderer (for example
+`vintasend-jinja`, or `vintasend-managed-templates`' `ManagedTemplateSMSRenderer`).
+
+Both service flavours are covered:
+
+| Class | For |
+|---|---|
+| `TwilioSMSNotificationAdapter` | `NotificationService` (sync) |
+| `TwilioAsyncIOSMSNotificationAdapter` | `AsyncIONotificationService` (awaits Twilio through its async HTTP client) |
+
+## Install
+
+```bash
+poetry add vintasend-twilio
+# or
+pip install vintasend-twilio
+```
+
+`twilio` comes as a dependency.
+
+## Usage
+
+```python
+from vintasend.services.notification_service import NotificationService
+from vintasend_twilio import TwilioSMSNotificationAdapter
+
+adapter = TwilioSMSNotificationAdapter(
+    my_sms_renderer,                      # any BaseTemplatedSMSRenderer
+    my_backend,                           # any vintasend backend
+    account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    auth_token="...",
+    from_phone_number="+15550001234",
+)
+
+service = NotificationService(notification_adapters=[adapter], notification_backend=my_backend)
+```
+
+Or let the service build it from settings. Every option below is an adapter keyword argument,
+so it goes in the kwargs half of a `NOTIFICATION_ADAPTERS` entry:
+
+```python
+NOTIFICATION_ADAPTERS = [
+    (
+        ("vintasend_twilio.TwilioSMSNotificationAdapter", {"from_phone_number": "+15550001234"}),
+        "vintasend_jinja.services.notification_template_renderers.jinja_template_renderer.JinjaTemplatedSMSRenderer",
+    ),
+]
+```
+
+With credentials left out of the kwargs, they are read from the environment (see below), which
+keeps the auth token out of your settings module.
+
+### Options
+
+| Keyword argument | Environment fallback | Meaning |
+|---|---|---|
+| `account_sid` | `TWILIO_ACCOUNT_SID` | Twilio account SID. Required unless `client` is given. |
+| `auth_token` | `TWILIO_AUTH_TOKEN` | Twilio auth token. Required unless `client` is given. |
+| `from_phone_number` | `TWILIO_FROM_PHONE_NUMBER` | E.164 number to send from. Exactly one of this and `messaging_service_sid` is required. |
+| `messaging_service_sid` | `TWILIO_MESSAGING_SERVICE_SID` | Twilio Messaging Service to send through instead of a fixed number. |
+| `phone_number_context_key` | — | Context key holding the recipient's number for regular notifications. Default `"phone_number"`. |
+| `status_callback` | — | URL Twilio calls with delivery status updates. |
+| `client` | — | A prebuilt `twilio.rest.Client`. Overrides `account_sid`, `auth_token` and `client_kwargs`. |
+| `client_kwargs` | — | Extra keyword arguments for `twilio.rest.Client` (`region`, `edge`, `http_client`, ...). |
+
+A missing sender or missing credentials raises `TwilioConfigurationError` when the adapter is
+constructed, not at the first send.
+
+### Where the recipient's number comes from
+
+- A **one-off notification** carries its destination on itself (`email_or_phone`), so nothing
+  else is needed.
+- A **regular notification** only knows the user, and vintasend's backend seam has no phone
+  lookup. The adapter reads the number from the context the notification's context generator
+  returns, under `phone_number_context_key` (default `phone_number`):
+
+  ```python
+  from vintasend.services.dataclasses import NotificationContextDict
+  from vintasend.services.notification_service import register_context
+
+  @register_context("sms_verification")
+  def sms_verification(user_id: str) -> NotificationContextDict:
+      user = get_user(user_id)
+      return {"phone_number": user.phone_number, "code": user.pending_code}
+  ```
+
+  A regular notification whose context has no non-empty number raises
+  `MissingRecipientPhoneNumberError` before anything is sent.
+
+Like the email adapters, the adapter also adds `base_url` to the context handed to the renderer
+(from `NOTIFICATION_DEFAULT_BASE_URL_PROTOCOL` and `NOTIFICATION_DEFAULT_BASE_URL_DOMAIN`), so an
+SMS template can build absolute links.
+
+### Errors
+
+Every exception derives from vintasend's `NotificationError`:
+
+- `TwilioConfigurationError` -- no usable sender or credentials, raised at construction.
+- `MissingRecipientPhoneNumberError` -- a regular notification's context has no number.
+- `TwilioSendError` -- Twilio rejected the message. It carries Twilio's HTTP `status` and
+  error `code`, names the notification id, and chains the original `TwilioRestException` as
+  `__cause__`. Its own message never includes the recipient's number.
+
+Both send errors subclass `NotificationSendError`, so the service marks the notification as
+failed the same way it does for any other adapter.
+
+### AsyncIO
+
+`TwilioAsyncIOSMSNotificationAdapter` takes the same options. Unless you inject a `client`, it
+builds Twilio's `Client` with `AsyncTwilioHttpClient` (aiohttp-backed) and awaits
+`messages.create_async`, so the request never blocks the event loop. The client is built on first
+send rather than in the constructor, because the aiohttp session needs a running event loop and
+`AsyncIONotificationService` instantiates its adapters synchronously. An injected `client` must
+have been built with an async `http_client`.
+
+### Injecting a client
+
+For a shared client, an API key instead of the auth token, a region or edge, or a custom HTTP
+client:
+
+```python
+from twilio.rest import Client
+
+client = Client(api_key_sid, api_key_secret, account_sid, region="ie1")
+TwilioSMSNotificationAdapter(renderer, backend, from_phone_number="+15550001234", client=client)
+```
+
+## Development
+
+```bash
+poetry install --with dev
+poetry run pytest
+poetry run ruff check .
+poetry run mypy
+poetry run tox        # the suite across Python 3.10-3.13
+```
+
+The tests drive the real adapter against a recording Twilio HTTP client, so nothing touches the
+network.
+

vintasend_twilio-3.6.0/README.md

@@ -0,0 +1,147 @@
+# vintasend-twilio
+
+A [Twilio](https://www.twilio.com/) SMS adapter for
+[vintasend](https://github.com/vintasoftware/vintasend).
+
+VintaSend records every notification, renders it from a template at send time, and hands the
+result to an **adapter** for delivery. This package is an adapter for the `SMS` notification type:
+it renders the notification with any `BaseTemplatedSMSRenderer` and posts the body to Twilio's
+Messages API. Pair it with any vintasend backend and an SMS renderer (for example
+`vintasend-jinja`, or `vintasend-managed-templates`' `ManagedTemplateSMSRenderer`).
+
+Both service flavours are covered:
+
+| Class | For |
+|---|---|
+| `TwilioSMSNotificationAdapter` | `NotificationService` (sync) |
+| `TwilioAsyncIOSMSNotificationAdapter` | `AsyncIONotificationService` (awaits Twilio through its async HTTP client) |
+
+## Install
+
+```bash
+poetry add vintasend-twilio
+# or
+pip install vintasend-twilio
+```
+
+`twilio` comes as a dependency.
+
+## Usage
+
+```python
+from vintasend.services.notification_service import NotificationService
+from vintasend_twilio import TwilioSMSNotificationAdapter
+
+adapter = TwilioSMSNotificationAdapter(
+    my_sms_renderer,                      # any BaseTemplatedSMSRenderer
+    my_backend,                           # any vintasend backend
+    account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    auth_token="...",
+    from_phone_number="+15550001234",
+)
+
+service = NotificationService(notification_adapters=[adapter], notification_backend=my_backend)
+```
+
+Or let the service build it from settings. Every option below is an adapter keyword argument,
+so it goes in the kwargs half of a `NOTIFICATION_ADAPTERS` entry:
+
+```python
+NOTIFICATION_ADAPTERS = [
+    (
+        ("vintasend_twilio.TwilioSMSNotificationAdapter", {"from_phone_number": "+15550001234"}),
+        "vintasend_jinja.services.notification_template_renderers.jinja_template_renderer.JinjaTemplatedSMSRenderer",
+    ),
+]
+```
+
+With credentials left out of the kwargs, they are read from the environment (see below), which
+keeps the auth token out of your settings module.
+
+### Options
+
+| Keyword argument | Environment fallback | Meaning |
+|---|---|---|
+| `account_sid` | `TWILIO_ACCOUNT_SID` | Twilio account SID. Required unless `client` is given. |
+| `auth_token` | `TWILIO_AUTH_TOKEN` | Twilio auth token. Required unless `client` is given. |
+| `from_phone_number` | `TWILIO_FROM_PHONE_NUMBER` | E.164 number to send from. Exactly one of this and `messaging_service_sid` is required. |
+| `messaging_service_sid` | `TWILIO_MESSAGING_SERVICE_SID` | Twilio Messaging Service to send through instead of a fixed number. |
+| `phone_number_context_key` | — | Context key holding the recipient's number for regular notifications. Default `"phone_number"`. |
+| `status_callback` | — | URL Twilio calls with delivery status updates. |
+| `client` | — | A prebuilt `twilio.rest.Client`. Overrides `account_sid`, `auth_token` and `client_kwargs`. |
+| `client_kwargs` | — | Extra keyword arguments for `twilio.rest.Client` (`region`, `edge`, `http_client`, ...). |
+
+A missing sender or missing credentials raises `TwilioConfigurationError` when the adapter is
+constructed, not at the first send.
+
+### Where the recipient's number comes from
+
+- A **one-off notification** carries its destination on itself (`email_or_phone`), so nothing
+  else is needed.
+- A **regular notification** only knows the user, and vintasend's backend seam has no phone
+  lookup. The adapter reads the number from the context the notification's context generator
+  returns, under `phone_number_context_key` (default `phone_number`):
+
+  ```python
+  from vintasend.services.dataclasses import NotificationContextDict
+  from vintasend.services.notification_service import register_context
+
+  @register_context("sms_verification")
+  def sms_verification(user_id: str) -> NotificationContextDict:
+      user = get_user(user_id)
+      return {"phone_number": user.phone_number, "code": user.pending_code}
+  ```
+
+  A regular notification whose context has no non-empty number raises
+  `MissingRecipientPhoneNumberError` before anything is sent.
+
+Like the email adapters, the adapter also adds `base_url` to the context handed to the renderer
+(from `NOTIFICATION_DEFAULT_BASE_URL_PROTOCOL` and `NOTIFICATION_DEFAULT_BASE_URL_DOMAIN`), so an
+SMS template can build absolute links.
+
+### Errors
+
+Every exception derives from vintasend's `NotificationError`:
+
+- `TwilioConfigurationError` -- no usable sender or credentials, raised at construction.
+- `MissingRecipientPhoneNumberError` -- a regular notification's context has no number.
+- `TwilioSendError` -- Twilio rejected the message. It carries Twilio's HTTP `status` and
+  error `code`, names the notification id, and chains the original `TwilioRestException` as
+  `__cause__`. Its own message never includes the recipient's number.
+
+Both send errors subclass `NotificationSendError`, so the service marks the notification as
+failed the same way it does for any other adapter.
+
+### AsyncIO
+
+`TwilioAsyncIOSMSNotificationAdapter` takes the same options. Unless you inject a `client`, it
+builds Twilio's `Client` with `AsyncTwilioHttpClient` (aiohttp-backed) and awaits
+`messages.create_async`, so the request never blocks the event loop. The client is built on first
+send rather than in the constructor, because the aiohttp session needs a running event loop and
+`AsyncIONotificationService` instantiates its adapters synchronously. An injected `client` must
+have been built with an async `http_client`.
+
+### Injecting a client
+
+For a shared client, an API key instead of the auth token, a region or edge, or a custom HTTP
+client:
+
+```python
+from twilio.rest import Client
+
+client = Client(api_key_sid, api_key_secret, account_sid, region="ie1")
+TwilioSMSNotificationAdapter(renderer, backend, from_phone_number="+15550001234", client=client)
+```
+
+## Development
+
+```bash
+poetry install --with dev
+poetry run pytest
+poetry run ruff check .
+poetry run mypy
+poetry run tox        # the suite across Python 3.10-3.13
+```
+
+The tests drive the real adapter against a recording Twilio HTTP client, so nothing touches the
+network.

vintasend_twilio-3.6.0/pyproject.toml

@@ -0,0 +1,135 @@
+[project]
+name = "vintasend-twilio"
+version = "3.6.0"
+description = "Twilio SMS adapter for VintaSend"
+authors = [{ name = "Hugo bessa", email = "hugo@vinta.com.br" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+# Constraints stay under [tool.poetry.dependencies] to keep caret syntax, which
+# is not valid PEP 621. 'dynamic' tells build tooling the real list lives there.
+dynamic = ["dependencies"]
+
+[tool.poetry]
+packages = [{ include = "vintasend_twilio" }]
+include = [
+  { path = "vintasend_twilio/py.typed", format = "wheel" }
+]
+
+[tool.poetry.dependencies]
+vintasend = "3.6.0"
+twilio = "^9.0.0"
+
+[tool.poetry.group.dev.dependencies]
+coverage = "^7.6.4"
+tox = "^4.23.2"
+# Makes the [gh] section in tox.ini effective: each CI job then runs only the
+# envs mapped to its interpreter instead of every env it can find one for.
+tox-gh = "^1.8.0"
+pytest = "^9.0.3"
+pytest-xdist = {version = "^3.6.1", extras=["psutil"]}
+pytest-cov = "^7.1.0"
+pytest-asyncio = "^1.4.0"
+ruff = "^0.17.3"
+mypy = "^2.3.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+# Must track the MINIMUM Python this package supports. Setting this higher lets
+# pyupgrade rewrite code into syntax that breaks older interpreters.
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pep8-naming
+    "N",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-bandit
+    "S",
+    # flake8-blind-except
+    "BLE",
+    # flake8-builtins
+    "A",
+    # isort
+    "I",
+    # flake8-logging-format
+    "G",
+    # flake8-no-pep420
+    "INP",
+    # Ruff-specific rules
+    "RUF",
+]
+ignore = [
+    # Disable Conflicting lint rules,
+    # see https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "W191",
+    "E501",
+    "E111",
+    "E117",
+    "D206",
+    "D300",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "COM812",
+    "COM819",
+    "ISC001",
+    "ISC002",
+    # Allow `except Exception`:
+    "BLE001",
+    # Disable unused `noqa` directive
+    "RUF100",
+]
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.pycodestyle]
+ignore-overlong-task-comments = true
+
+[tool.ruff.lint.isort]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+lines-after-imports = 2
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["E402", "F403", "F405"]
+"**/{tests,docs}/*" = ["E402", "F403", "F405", "S", "N802"]
+"**/*test*.py" = ["E402", "F403", "F405", "S", "N802"]
+
+[tool.pytest.ini_options]
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+addopts = "--dist=loadscope"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+files = ["vintasend_twilio", "tests"]
+# Must track the MINIMUM Python this package supports.
+python_version = "3.10"
+show_error_codes = true
+no_implicit_reexport = true
+strict_equality = true
+warn_no_return = true
+
+# twilio ships no py.typed marker, so its modules are treated as untyped rather than failing
+# the check.
+[[tool.mypy.overrides]]
+module = "twilio.*"
+ignore_missing_imports = true

vintasend_twilio-3.6.0/vintasend_twilio/__init__.py

@@ -0,0 +1,16 @@
+from vintasend_twilio.adapter import (
+    MissingRecipientPhoneNumberError,
+    TwilioAsyncIOSMSNotificationAdapter,
+    TwilioConfigurationError,
+    TwilioSendError,
+    TwilioSMSNotificationAdapter,
+)
+
+
+__all__ = [
+    "MissingRecipientPhoneNumberError",
+    "TwilioAsyncIOSMSNotificationAdapter",
+    "TwilioConfigurationError",
+    "TwilioSMSNotificationAdapter",
+    "TwilioSendError",
+]

vintasend_twilio-3.6.0/vintasend_twilio/adapter.py

@@ -0,0 +1,293 @@
+"""Twilio SMS delivery for VintaSend.
+
+Two adapters, one per service flavour:
+
+- ``TwilioSMSNotificationAdapter`` for ``NotificationService`` (sync).
+- ``TwilioAsyncIOSMSNotificationAdapter`` for ``AsyncIONotificationService``. It drives the same
+  Twilio ``Client`` through Twilio's own ``AsyncTwilioHttpClient`` and awaits ``create_async``.
+
+Both render the notification with a ``BaseTemplatedSMSRenderer`` and post the resulting body to
+Twilio's Messages API. See ``TwilioConfigMixin`` for how credentials, the sender, and the
+recipient are resolved.
+"""
+
+import os
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from twilio.base.exceptions import TwilioRestException
+from twilio.http.async_http_client import AsyncTwilioHttpClient
+from twilio.rest import Client
+from vintasend.app_settings import NotificationSettings
+from vintasend.constants import NotificationTypes
+from vintasend.exceptions import NotificationError, NotificationSendError
+from vintasend.services.dataclasses import Notification, OneOffNotification
+from vintasend.services.notification_adapters.asyncio_base import AsyncIOBaseNotificationAdapter
+from vintasend.services.notification_adapters.base import BaseNotificationAdapter
+from vintasend.services.notification_backends.asyncio_base import AsyncIOBaseNotificationBackend
+from vintasend.services.notification_backends.base import BaseNotificationBackend
+from vintasend.services.notification_template_renderers.base_templated_sms_renderer import (
+    BaseTemplatedSMSRenderer,
+    TemplatedSMS,
+)
+
+
+if TYPE_CHECKING:
+    from vintasend.services.dataclasses import NotificationContextDict
+
+
+B = TypeVar("B", bound=BaseNotificationBackend)
+BAIO = TypeVar("BAIO", bound=AsyncIOBaseNotificationBackend)
+T = TypeVar("T", bound=BaseTemplatedSMSRenderer)
+
+
+ACCOUNT_SID_ENV_VAR = "TWILIO_ACCOUNT_SID"
+AUTH_TOKEN_ENV_VAR = "TWILIO_AUTH_TOKEN"  # noqa: S105 -- the variable's name, not a secret
+FROM_PHONE_NUMBER_ENV_VAR = "TWILIO_FROM_PHONE_NUMBER"
+MESSAGING_SERVICE_SID_ENV_VAR = "TWILIO_MESSAGING_SERVICE_SID"
+
+DEFAULT_PHONE_NUMBER_CONTEXT_KEY = "phone_number"
+
+
+class TwilioConfigurationError(NotificationError):
+    """Raised at construction when the adapter has no usable sender or credentials."""
+
+
+class MissingRecipientPhoneNumberError(NotificationSendError):
+    """Raised when a regular notification's context carries no phone number to send to."""
+
+
+class TwilioSendError(NotificationSendError):
+    """Raised when Twilio rejects a message.
+
+    The message names the notification and Twilio's HTTP status and error code, never the
+    recipient's number. The original ``TwilioRestException`` is chained as ``__cause__``.
+    """
+
+    status: int | None
+    code: int | None
+
+    def __init__(self, message: str, status: int | None = None, code: int | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class TwilioConfigMixin:
+    """Configuration shared by the sync and AsyncIO adapters.
+
+    Every option is an adapter keyword argument, so it can be given either in code
+    (``TwilioSMSNotificationAdapter(renderer, backend, from_phone_number="+15550001234")``) or in
+    the ``NOTIFICATION_ADAPTERS`` setting as the kwargs half of a ``(dotted_path, kwargs)`` tuple.
+
+    :param account_sid: Twilio account SID. Falls back to ``TWILIO_ACCOUNT_SID``.
+    :param auth_token: Twilio auth token. Falls back to ``TWILIO_AUTH_TOKEN``.
+    :param from_phone_number: The E.164 number messages are sent from. Falls back to
+        ``TWILIO_FROM_PHONE_NUMBER``. Mutually exclusive with ``messaging_service_sid``.
+    :param messaging_service_sid: A Twilio Messaging Service to send through instead of a fixed
+        number. Falls back to ``TWILIO_MESSAGING_SERVICE_SID``.
+    :param phone_number_context_key: Which key of the rendered context holds the recipient's
+        number for a regular (non one-off) notification. Defaults to ``"phone_number"``.
+    :param status_callback: Optional URL Twilio calls with delivery status updates.
+    :param client: A prebuilt ``twilio.rest.Client`` to use instead of building one. When given,
+        ``account_sid``, ``auth_token`` and ``client_kwargs`` are ignored. The AsyncIO adapter
+        needs one built with an async ``http_client``.
+    :param client_kwargs: Extra keyword arguments for ``twilio.rest.Client`` (``region``,
+        ``edge``, ``http_client``, ...). Ignored when ``client`` is given.
+
+    The Twilio client is built on first use rather than in ``__init__``. Twilio's async HTTP
+    client opens an aiohttp session as it is constructed, which needs a running event loop, and
+    ``AsyncIONotificationService`` instantiates its adapters synchronously -- so an eager build
+    would fail for the AsyncIO adapter whenever it is configured through settings.
+    """
+
+    from_phone_number: str | None
+    messaging_service_sid: str | None
+    phone_number_context_key: str
+    status_callback: str | None
+
+    _client: Client | None
+    _account_sid: str | None
+    _auth_token: str | None
+    _client_kwargs: dict[str, Any]
+    _use_async_http_client: bool
+
+    def _configure_twilio(self, kwargs: dict[str, Any], *, use_async_http_client: bool) -> None:
+        self.from_phone_number = kwargs.get("from_phone_number") or os.environ.get(
+            FROM_PHONE_NUMBER_ENV_VAR
+        )
+        self.messaging_service_sid = kwargs.get("messaging_service_sid") or os.environ.get(
+            MESSAGING_SERVICE_SID_ENV_VAR
+        )
+        if self.from_phone_number and self.messaging_service_sid:
+            raise TwilioConfigurationError(
+                f"{type(self).__name__} takes either from_phone_number or messaging_service_sid, "
+                "not both."
+            )
+        if not self.from_phone_number and not self.messaging_service_sid:
+            raise TwilioConfigurationError(
+                f"{type(self).__name__} needs a sender: pass from_phone_number or "
+                f"messaging_service_sid, or set {FROM_PHONE_NUMBER_ENV_VAR} or "
+                f"{MESSAGING_SERVICE_SID_ENV_VAR}."
+            )
+
+        self.phone_number_context_key = (
+            kwargs.get("phone_number_context_key") or DEFAULT_PHONE_NUMBER_CONTEXT_KEY
+        )
+        self.status_callback = kwargs.get("status_callback")
+        self._use_async_http_client = use_async_http_client
+
+        client = kwargs.get("client")
+        if client is not None:
+            if not isinstance(client, Client):
+                raise TwilioConfigurationError(
+                    f"{type(self).__name__} expects `client` to be a twilio.rest.Client, "
+                    f"got {type(client).__name__}."
+                )
+            self._client = client
+            self._account_sid = None
+            self._auth_token = None
+            self._client_kwargs = {}
+            return
+
+        self._client = None
+        self._account_sid = kwargs.get("account_sid") or os.environ.get(ACCOUNT_SID_ENV_VAR)
+        self._auth_token = kwargs.get("auth_token") or os.environ.get(AUTH_TOKEN_ENV_VAR)
+        self._client_kwargs = dict(kwargs.get("client_kwargs") or {})
+        if not self._account_sid or not self._auth_token:
+            raise TwilioConfigurationError(
+                f"{type(self).__name__} needs Twilio credentials: pass account_sid and "
+                f"auth_token, or set {ACCOUNT_SID_ENV_VAR} and {AUTH_TOKEN_ENV_VAR}."
+            )
+
+    @property
+    def client(self) -> Client:
+        """The Twilio client, built on first access unless one was injected."""
+        if self._client is None:
+            client_kwargs = dict(self._client_kwargs)
+            if self._use_async_http_client:
+                client_kwargs.setdefault("http_client", AsyncTwilioHttpClient())
+            self._client = Client(self._account_sid, self._auth_token, **client_kwargs)
+        return self._client
+
+    def _recipient_phone_number(
+        self,
+        notification: "Notification | OneOffNotification",
+        context: "NotificationContextDict",
+    ) -> str:
+        """Resolve the destination number for either notification flavour.
+
+        A one-off notification carries the number on itself. A regular one only knows the user,
+        and the backend seam has no phone lookup, so the number has to come from the context the
+        notification's context generator produced -- under ``phone_number_context_key``.
+        """
+        if isinstance(notification, OneOffNotification):
+            return notification.email_or_phone
+        phone_number = context.get(self.phone_number_context_key)
+        if not isinstance(phone_number, str) or not phone_number.strip():
+            raise MissingRecipientPhoneNumberError(
+                f"Notification {notification.id} has no recipient phone number: its context has "
+                f"no non-empty {self.phone_number_context_key!r} key. Have its context generator "
+                "return one, or point phone_number_context_key at the key it does set."
+            )
+        return phone_number.strip()
+
+    def _message_kwargs(self, to: str, body: str) -> dict[str, Any]:
+        """The keyword arguments for ``client.messages.create`` / ``create_async``."""
+        message_kwargs: dict[str, Any] = {"to": to, "body": body}
+        if self.from_phone_number:
+            message_kwargs["from_"] = self.from_phone_number
+        else:
+            message_kwargs["messaging_service_sid"] = self.messaging_service_sid
+        if self.status_callback:
+            message_kwargs["status_callback"] = self.status_callback
+        return message_kwargs
+
+    def _context_with_base_url(
+        self, context: "NotificationContextDict"
+    ) -> "NotificationContextDict":
+        """Add ``base_url`` the way the email adapters do, so SMS templates can build links."""
+        notification_settings = NotificationSettings()
+        context_with_base_url: NotificationContextDict = context.copy()
+        context_with_base_url["base_url"] = (
+            f"{notification_settings.NOTIFICATION_DEFAULT_BASE_URL_PROTOCOL}://"
+            f"{notification_settings.NOTIFICATION_DEFAULT_BASE_URL_DOMAIN}"
+        )
+        return context_with_base_url
+
+    def _send_error(
+        self, notification: "Notification | OneOffNotification", exc: TwilioRestException
+    ) -> TwilioSendError:
+        return TwilioSendError(
+            f"Twilio rejected the SMS for notification {notification.id} "
+            f"(HTTP {exc.status}, Twilio error code {exc.code}).",
+            status=exc.status,
+            code=exc.code,
+        )
+
+
+class TwilioSMSNotificationAdapter(  # noqa: UP046
+    TwilioConfigMixin, Generic[B, T], BaseNotificationAdapter[B, T]
+):
+    """Sends SMS notifications through Twilio from a ``NotificationService``."""
+
+    notification_type = NotificationTypes.SMS
+    backend: B
+    template_renderer: T
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._configure_twilio(kwargs, use_async_http_client=False)
+
+    def send(
+        self, notification: "Notification | OneOffNotification", context: "NotificationContextDict"
+    ) -> TemplatedSMS:
+        """Render the notification and post it to Twilio's Messages API.
+
+        Returns the rendered SMS so the service can record which template version went out.
+
+        :raises MissingRecipientPhoneNumberError: a regular notification's context has no number.
+        :raises TwilioSendError: Twilio rejected the message.
+        """
+        to = self._recipient_phone_number(notification, context)
+        template = self.template_renderer.render(notification, self._context_with_base_url(context))
+        try:
+            self.client.messages.create(**self._message_kwargs(to, template.body))
+        except TwilioRestException as exc:
+            raise self._send_error(notification, exc) from exc
+        return template
+
+
+class TwilioAsyncIOSMSNotificationAdapter(  # noqa: UP046
+    TwilioConfigMixin, Generic[BAIO, T], AsyncIOBaseNotificationAdapter[BAIO, T]
+):
+    """Sends SMS notifications through Twilio from an ``AsyncIONotificationService``.
+
+    Unless a ``client`` is injected, the Twilio client is built with Twilio's
+    ``AsyncTwilioHttpClient`` so the request is awaited rather than blocking the event loop.
+    """
+
+    notification_type = NotificationTypes.SMS
+    backend: BAIO
+    template_renderer: T
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._configure_twilio(kwargs, use_async_http_client=True)
+
+    async def send(
+        self, notification: "Notification | OneOffNotification", context: "NotificationContextDict"
+    ) -> TemplatedSMS:
+        """Render the notification and post it to Twilio's Messages API.
+
+        Returns the rendered SMS so the service can record which template version went out.
+
+        :raises MissingRecipientPhoneNumberError: a regular notification's context has no number.
+        :raises TwilioSendError: Twilio rejected the message.
+        """
+        to = self._recipient_phone_number(notification, context)
+        template = self.template_renderer.render(notification, self._context_with_base_url(context))
+        try:
+            await self.client.messages.create_async(**self._message_kwargs(to, template.body))
+        except TwilioRestException as exc:
+            raise self._send_error(notification, exc) from exc
+        return template