xtr-notifier 5.0.0__py3-none-any.whl

xtr_notifier/.agents/skills/xtr-notifier/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: xtr-notifier
+description: How to send notifications with xtr-notifier — a notification sent to chat, SMS and push channels picked by the notification or by an importance policy, through provider transports configured by DSN, with failover and round robin, sent in-process or queued through xtr-messenger. Use when an application must alert a chat room or a phone, send an SMS code or a push message, configure a provider by DSN, fall over between providers, route notifications by importance, report failed queued messages to administrators, assert in a test what was notified, add NotifierBundle to an application, or write a provider library (a transport and its factory) for the notifier.
+---
+
+# xtr-notifier
+
+A notification says what happened and how much it matters; the notifier picks its channels and
+each channel sends a message through a transport chosen by a DSN. Providers are libraries of
+their own, found by their DSN scheme.
+
+## Quick reference
+
+- Notify — `await notifier.send(Notification(subject, content=..., importance=...,
+  channels=["chat/slack", "sms"]), *recipients)`; no recipients means `NoRecipient()`.
+- Channels — `ChatChannel`, `SmsChannel` (needs a recipient with a `phone`), `PushChannel`, each
+  built with a transport or a `message_bus=`. `"chat/slack"` sends on `chat` through `slack`.
+- Policy — `ChannelPolicy({"urgent": ["sms", "chat"]})` picks channels when a notification names
+  none; `Importance` is a `StrEnum` (`urgent`, `high`, `medium`, `low`).
+- Direct — `Chatter(transport).send(ChatMessage(...))`, `Texter(transport).send(SmsMessage(...))`;
+  with a bus they queue and return `None`.
+- Transports — `Transport(factories, discovery).from_string("a || b")` (failover) or
+  `"a && b"` (round robin); `from_strings({...})` gives named `Transports`.
+- Discovery — `TransportFactoryDiscovery(TransportFactoryDiscovery.CHATTER_GROUP |
+  TEXTER_GROUP, http_client=..., event_dispatcher=...)`; `null://null` is built in.
+- Messages are frozen: `with_transport`, `with_options`, `with_subject` return copies.
+- Bus — `xtr_notifier.messenger.MessageHandler(transport)`; importing `xtr_notifier.messenger`
+  declares the messages' wire names.
+- Every error derives from `NotifierError`.
+
+## Send a notification
+
+```python
+from xtr_notifier import Notifier, Transport
+from xtr_notifier.channel import ChannelPolicy, ChatChannel
+from xtr_notifier.notification import Importance, Notification
+from xtr_notifier.transport import TransportFactoryDiscovery
+
+discovery = TransportFactoryDiscovery(TransportFactoryDiscovery.CHATTER_GROUP)
+chat = Transport(discovery=discovery).from_strings({"ops": "null://null"})
+notifier = Notifier({"chat": ChatChannel(chat)}, ChannelPolicy({"urgent": ["chat/ops"]}))
+
+await notifier.send(Notification("Disk almost full", importance=Importance.URGENT))
+```
+
+Report an error with `Notification.from_exception(error, channels=["chat"])`; read an importance
+from a log level with `Notification.importance_from_level("error")`.
+
+## Render a channel's message yourself
+
+Implement `as_chat_message` (or `as_sms_message`, `as_push_message`) on a `Notification`
+subclass; return `None` to fall back to the default message:
+
+```python
+from xtr_notifier.message import ChatMessage, MessageOptions
+from xtr_notifier.notification import Notification
+
+
+class Deployed(Notification):
+    def as_chat_message(self, recipient, transport_name):
+        return ChatMessage(self.subject, MessageOptions("slack", "deploys", {"unfurl": False}))
+```
+
+`MessageOptions(kind, recipient_id, values)` holds JSON data only; a provider sends options
+only when `kind` is its own.
+
+## Configure providers by DSN
+
+A DSN is `scheme://user:password@host?options`; `host` is `default` for the provider's own API.
+Install the provider library (`uv add xtr-telegram-notifier`) and its scheme is served. A scheme
+nothing serves raises `UnsupportedSchemeError` naming the library to install.
+
+## Write a provider library
+
+See [references/bridges.md](references/bridges.md): an `AbstractTransport`, an
+`AbstractTransportFactory`, one entry point per scheme, and the `xtr_notifier.testing` cases.
+
+## Testing
+
+```python
+from xtr_notifier.event_listener import NotificationLoggerListener
+from xtr_notifier.testing import (
+    assert_notification_count,
+    assert_notification_subject_contains,
+    assert_queued_notification_count,
+)
+
+listener = NotificationLoggerListener()  # listen to MessageEvent with on_notification
+assert_notification_count(listener.events, 1, "ops")
+assert_queued_notification_count(listener.events, 0)
+assert_notification_subject_contains(listener.events.get_messages()[0], "Disk")
+```
+
+Use `null://null` to send nowhere; under the bundle a `NotificationLoggerListener` is registered
+when the event dispatcher bundle is active — get it from the container.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`NotifierBundle`, writes `<app>/config/notifier.py`, and `NOTIFIER_CHATTER_DSN` and
+`NOTIFIER_TEXTER_DSN` (both `null://null`) in `.env`. It prints the steps it cannot make.
+
+1. **Install** — `uv add "xtr-notifier[messenger]"` (or `xtr-notifier` alone); a provider
+   library per provider. xtr-http-client, xtr-event-dispatcher and xtr-messenger are used when
+   installed.
+2. **Activate** — `NotifierBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`
+   (`from xtr_notifier.bundle import NotifierBundle`).
+3. **Brings along** — the HTTP client, messenger and event dispatcher bundles, each when its
+   package is installed.
+4. **Configure** — `<app>/config/notifier.py`, a `@configure` function returning
+   `NotifierConfig`: `chatter_transports`, `texter_transports`, `channel_policy`,
+   `admin_recipients` (`AdminRecipientConfig`), `notification_on_failed_messages`, `http_client`.
+   With no transports there is no channel: sending raises `The "chat" channel does not exist.`
+5. **Queue** — route `ChatMessage`, `SmsMessage`, `PushMessage` in `<app>/config/messenger.py`;
+   an unrouted message is sent at once.
+6. **Environment** — `NOTIFIER_CHATTER_DSN`, `NOTIFIER_TEXTER_DSN`. **Ignore** — nothing.
+7. **Use** — inject `NotifierInterface`, `ChatterInterface` or `TexterInterface`.
+8. **Extend** — tag a factory `CHATTER_TRANSPORT_FACTORY_TAG` / `TEXTER_TRANSPORT_FACTORY_TAG`,
+   or a channel `CHANNEL_TAG` with `channel="<name>"`.
+9. **Check** — `debug:bundles` shows `notifier` active; `debug:config notifier`.
+10. **Remove** — drop the `BUNDLES` entry, delete `<app>/config/notifier.py` and the two
+    variables, then `uv remove xtr-notifier`.
+
+## Errors
+
+| Error | When |
+|---|---|
+| `LogicError` | No channel can be determined, a channel does not exist or cannot reach the recipient, no transport supports the message, failed-message reporting without its peer bundles |
+| `InvalidArgumentError` | Unreadable DSN, non-boolean option, unknown transport name, policy without the importance |
+| `IncompleteDsnError` / `MissingRequiredOptionError` | A DSN lacks a token or a required option |
+| `UnsupportedSchemeError` | No factory serves the scheme |
+| `UnsupportedMessageTypeError` | A transport got a message of another kind |
+| `TransportError` | The provider was unreachable or refused; the one error failover moves on from |
+| `NotifierRuntimeError` | Every transport of a failover or round robin failed |
+
+## Do not
+
+- Do not write a DSN with a token into code or configuration; read it with `env("...")`.
+- Do not mutate a message; use its `with_*` copies.
+- Do not put objects in `MessageOptions.values` — JSON data only, or the message will not cross
+  the bus.
+- Do not create an HTTP client inside a transport; it takes the application's.
+- Do not catch `TransportError` inside a transport to retry; failover and the bus do that.

xtr_notifier/.agents/skills/xtr-notifier/references/bridges.md

@@ -0,0 +1,200 @@
+# Writing a provider library
+
+A provider library — a *bridge* — teaches the notifier one provider: its transport, the factory
+that builds it from a DSN, and an options builder. It is a package of its own, named
+`xtr-<provider>-notifier` / `xtr_<provider>_notifier`, installed beside `xtr-notifier`.
+
+## Layout
+
+```
+packages/xtr-acme-notifier/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/xtr_acme_notifier/
+│   ├── __init__.py
+│   ├── py.typed
+│   ├── acme_transport.py
+│   ├── acme_transport_factory.py
+│   ├── acme_options.py
+│   ├── recipe/                  # manifest.toml: [env] ACME_DSN, a notes step
+│   └── .agents/skills/xtr-acme-notifier/SKILL.md
+└── tests/
+```
+
+Dependencies: `xtr-notifier`, `xtr-http-client-contracts`, `typing-extensions`. The dev group
+adds `xtr-http-client`, for `MockHttpClient`. A bridge ships no bundle.
+
+## Advertise the factory
+
+One entry point per scheme, in the chatter's group for a chat provider or the texter's for an
+SMS or push provider — both when it serves both:
+
+```toml
+[project.entry-points."xtr_notifier.chatter_transport_factories"]
+acme = "xtr_acme_notifier:AcmeTransportFactory"
+```
+
+The entry point names the factory **class**. Discovery builds it with
+`http_client=` and `event_dispatcher=` — the constructor of `AbstractTransportFactory`. A
+factory needing anything else cannot be discovered; such a bridge ships a bundle that registers
+it under `CHATTER_TRANSPORT_FACTORY_TAG` or `TEXTER_TRANSPORT_FACTORY_TAG`.
+
+## The transport
+
+```python
+from typing import ClassVar
+
+from typing_extensions import override
+from xtr_http_client_contracts.exception import TransportError as HttpTransportError
+
+from xtr_notifier.exception import TransportError, UnsupportedMessageTypeError
+from xtr_notifier.message import ChatMessage, MessageInterface, SentMessage
+from xtr_notifier.transport import AbstractTransport
+
+
+class AcmeTransport(AbstractTransport):
+    HOST: ClassVar[str] = "api.acme.test"
+
+    def __init__(self, token: str, channel: str, http_client, event_dispatcher=None) -> None:
+        super().__init__(http_client, event_dispatcher)
+        self._token = token
+        self._channel = channel
+
+    @override
+    def __str__(self) -> str:
+        return f"acme://{self._get_endpoint()}?channel={self._channel}"  # never the token
+
+    @override
+    def supports(self, message: MessageInterface) -> bool:
+        return isinstance(message, ChatMessage) and (
+            message.options is None or message.options.kind == "acme"
+        )
+
+    @override
+    async def _do_send(self, message: MessageInterface) -> SentMessage:
+        if not isinstance(message, ChatMessage):
+            raise UnsupportedMessageTypeError(str(self), "ChatMessage", message)
+        url = f"{self._get_http_scheme()}://{self._get_endpoint()}/post"
+        try:
+            response = await self._http_client.request("POST", url, json={"text": message.subject})
+        except HttpTransportError as error:
+            raise TransportError("Could not reach the remote Acme server.") from error
+        async with response:
+            answer = await response.to_array(throw=False)
+        if response.get_status_code() != 200:
+            raise TransportError(
+                f"Unable to post the Acme message: {answer.get('error')}.", response
+            )
+        return SentMessage(message, str(self), message_id=str(answer.get("id")))
+```
+
+- `send` is inherited: it announces the message, calls `_do_send`, and announces the outcome.
+- Raise `TransportError` for anything the provider refused or never answered — it is what
+  failover moves on from — and `UnsupportedMessageTypeError` for a message of another kind.
+  A provider that never answered leaves no response: the client raised its own
+  `TransportError`, which becomes the cause.
+- Read the answer inside `async with response`, so the connection and the kept body are let go.
+- A file to upload stays a path in the options; open it `"rb"` in `_do_send`, send the fields as
+  `body=` — the client sends a mapping holding a file as `multipart/form-data` — and close it
+  in a `finally`.
+- The string form names the endpoint and the options, never a credential.
+
+## The factory
+
+```python
+from collections.abc import Sequence
+
+from typing_extensions import override
+
+from xtr_notifier.exception import UnsupportedSchemeError
+from xtr_notifier.transport import AbstractTransportFactory, Dsn
+
+
+class AcmeTransportFactory(AbstractTransportFactory):
+    @override
+    def create(self, dsn: Dsn) -> AcmeTransport:
+        if not self.supports(dsn):
+            raise UnsupportedSchemeError(dsn.scheme, "acme", self._get_supported_schemes())
+        transport = AcmeTransport(
+            self._get_user(dsn),  # IncompleteDsnError when missing
+            dsn.get_required_option("channel"),  # MissingRequiredOptionError
+            self._http_client,
+            self._event_dispatcher,
+        )
+        host = None if dsn.host == "default" else dsn.host
+        return transport.set_host(host).set_port(dsn.port).set_ssl(self._get_ssl(dsn))
+
+    @override
+    def _get_supported_schemes(self) -> Sequence[str]:
+        return ("acme",)
+```
+
+## Options
+
+A builder implementing `MessageOptionsInterface` — a `recipient_id` property and
+`to_options()` — renders a frozen `MessageOptions("acme", recipient_id, values)`. Keep `values`
+JSON data, so a message carrying it crosses a message bus. The transport reads
+`message.options.values`.
+
+## Tests
+
+Hold the transport and the factory to what every provider owes:
+
+```python
+import pytest
+from xtr_http_client import MockHttpClient
+
+from xtr_notifier.message import ChatMessage, SmsMessage
+from xtr_notifier.testing import (
+    FactoryCases,
+    TransportCases,
+    assert_factory_cases,
+    assert_transport_cases,
+)
+
+
+def _transport() -> AcmeTransport:
+    return AcmeTransport("TOKEN", "ops", MockHttpClient())
+
+
+@pytest.mark.anyio
+async def test_the_transport_does_what_every_transport_owes() -> None:
+    await assert_transport_cases(
+        TransportCases(
+            create_transport=_transport,
+            to_string=[("acme://api.acme.test?channel=ops", _transport())],
+            supported=[ChatMessage("Hello")],
+            unsupported=[SmsMessage("+33", "Hello")],
+        )
+    )
+
+
+def test_the_factory_does_what_every_factory_owes() -> None:
+    assert_factory_cases(
+        FactoryCases(
+            create_factory=lambda: AcmeTransportFactory(MockHttpClient()),
+            supports=[(True, "acme://TOKEN@default"), (False, "other://TOKEN@default")],
+            create=[("acme://api.acme.test?channel=ops", "acme://TOKEN@default?channel=ops")],
+            unsupported_scheme=[("other://TOKEN@default?channel=ops", None)],
+            incomplete_dsn=[("acme://default?channel=ops", "User is not set.")],
+            missing_required_option=[("acme://TOKEN@default", 'The option "channel"')],
+        )
+    )
+```
+
+Then pin the exact request with a `MockHttpClient` whose callable checks the method, URL,
+headers and body, and every error the provider answers mapped to `TransportError`.
+
+## Outside the package
+
+- A row in the core's `UnsupportedSchemeError` table (`scheme` → distribution), so a missing
+  install is named.
+- The root `pyproject.toml` workspace source, `CREDITS.md`, the root README table and graph.
+- A recipe: `[env] ACME_DSN = "acme://TOKEN@default?channel=CHANNEL"` and a `notes.steps` line
+  adding `acme=env("ACME_DSN")` to `chatter_transports` in `config/notifier.py` — no `[bundles]`,
+  no `[files]` — advertised as `[project.entry-points."xtr_recipes"] acme =
+  "xtr_acme_notifier.recipe"`. The README's *Use in an application* lists Install, Recipe,
+  Configure, Environment, Remove and Check, and points to xtr-notifier's for the rest.
+
+xtr-telegram-notifier is a complete example of all of the above.

xtr_notifier/__init__.py

@@ -0,0 +1,28 @@
+"""Notifications sent to chat, SMS and push channels.
+
+A notification says what happened and how much it matters. The notifier picks the channels
+it goes to — from the notification itself or from a policy keyed by its importance — and each
+channel hands a message to a transport configured by DSN, or to a message bus.
+"""
+
+from __future__ import annotations
+
+from .admin_recipients_provider_interface import AdminRecipientsProviderInterface
+from .chatter import Chatter
+from .chatter_interface import ChatterInterface
+from .notifier import Notifier
+from .notifier_interface import NotifierInterface
+from .texter import Texter
+from .texter_interface import TexterInterface
+from .transport import Transport
+
+__all__ = [
+    "AdminRecipientsProviderInterface",
+    "Chatter",
+    "ChatterInterface",
+    "Notifier",
+    "NotifierInterface",
+    "Texter",
+    "TexterInterface",
+    "Transport",
+]

xtr_notifier/_message_sender.py

@@ -0,0 +1,64 @@
+"""What the chatter and the texter share: send now, or queue on a bus."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from xtr_notifier.event import MessageEvent
+
+if TYPE_CHECKING:
+    from xtr_event_dispatcher_contracts import EventDispatcherInterface
+    from xtr_messenger import MessageBusInterface
+
+    from xtr_notifier.message import MessageInterface, SentMessage
+    from xtr_notifier.transport import TransportInterface
+
+__all__ = ["MessageSender"]
+
+
+class MessageSender:
+    """Sends through a transport, or — given a message bus — queues on it instead.
+
+    With a bus the message is dispatched there and a handler sends it through
+    the same transport later, possibly in another process; ``send`` then
+    returns ``None``, since nothing was sent yet. The queued message is
+    announced as a :class:`~xtr_notifier.event.MessageEvent` with ``queued``
+    set, so a listener sees it once whichever way it leaves.
+
+    The bus is only ever called, so the messenger package is needed only by an
+    application that hands one over.
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_event_dispatcher", "_message_bus", "_transport")
+
+    def __init__(
+        self,
+        transport: TransportInterface,
+        message_bus: MessageBusInterface | None = None,
+        event_dispatcher: EventDispatcherInterface | None = None,
+    ) -> None:
+        """Send through ``transport``, or queue on ``message_bus`` when given one.
+
+        Args:
+            transport: What sends the messages, now or when the bus hands them back.
+            message_bus: Where messages are queued instead of sent now; ``None``
+                sends every message at once.
+            event_dispatcher: Where a queued message is announced; ``None``
+                announces nothing.
+        """
+        self._transport: TransportInterface = transport
+        self._message_bus: MessageBusInterface | None = message_bus
+        self._event_dispatcher: EventDispatcherInterface | None = event_dispatcher
+
+    def supports(self, message: MessageInterface) -> bool:
+        """Tell whether the transport sends ``message``."""
+        return self._transport.supports(message)
+
+    async def send(self, message: MessageInterface) -> SentMessage | None:
+        """Send ``message`` and report it, or queue it on the bus and return ``None``."""
+        if self._message_bus is None:
+            return await self._transport.send(message)
+        if self._event_dispatcher is not None:
+            _ = await self._event_dispatcher.dispatch(MessageEvent(message, queued=True))
+        _ = await self._message_bus.dispatch(message)
+        return None

xtr_notifier/admin_recipients_provider_interface.py

@@ -0,0 +1,26 @@
+"""Who to tell when something goes wrong."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from xtr_notifier.recipient import RecipientInterface
+
+__all__ = ["AdminRecipientsProviderInterface"]
+
+
+@runtime_checkable
+class AdminRecipientsProviderInterface(Protocol):
+    """Names the administrators of the application, to send its own failures to.
+
+    A failed queued message, for one, is reported to them; a notifier without
+    administrators reports it to nobody in particular.
+    """
+
+    @property
+    def admin_recipients(self) -> Sequence[RecipientInterface]:
+        """The administrators, in the order they were configured."""
+        ...

xtr_notifier/bundle/__init__.py

@@ -0,0 +1,21 @@
+"""The xtr-dependency-injection bundle for xtr-notifier."""
+
+from __future__ import annotations
+
+from .admin_recipient_config import AdminRecipientConfig
+from .notifier_bundle import (
+    CHANNEL_TAG,
+    CHATTER_TRANSPORT_FACTORY_TAG,
+    TEXTER_TRANSPORT_FACTORY_TAG,
+    NotifierBundle,
+)
+from .notifier_config import NotifierConfig
+
+__all__ = [
+    "CHANNEL_TAG",
+    "CHATTER_TRANSPORT_FACTORY_TAG",
+    "TEXTER_TRANSPORT_FACTORY_TAG",
+    "AdminRecipientConfig",
+    "NotifierBundle",
+    "NotifierConfig",
+]

xtr_notifier/bundle/_chat_message_handler.py

@@ -0,0 +1,34 @@
+"""Sends the chat messages queued on the bus through the chatter's transports.
+
+Scanned by the bundle only when the messenger bundle is active and chat
+transports are configured, so the bus never holds a handler it cannot build.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, final
+
+from xtr_dependency_injection import Target
+from xtr_messenger import as_message_handler
+
+from xtr_notifier.message import ChatMessage, SentMessage
+from xtr_notifier.messenger import MessageHandler
+from xtr_notifier.transport import Transports
+
+__all__ = ["ChatMessageHandler"]
+
+
+@as_message_handler(ChatMessage)
+@final
+class ChatMessageHandler:
+    """Hands each queued chat message to the chatter's transports."""
+
+    __slots__ = ("_handler",)
+
+    def __init__(self, transports: Annotated[Transports, Target("chatter")]) -> None:
+        """Send through ``transports``."""
+        self._handler = MessageHandler(transports)
+
+    async def __call__(self, message: ChatMessage) -> SentMessage:
+        """Send ``message``; a provider's refusal makes the bus retry it."""
+        return await self._handler(message)

xtr_notifier/bundle/_failed_messages.py

@@ -0,0 +1,15 @@
+"""The listener reporting failed messages, built only when the bus is there to fail them."""
+
+from __future__ import annotations
+
+from xtr_notifier.event_listener.send_failed_message_to_notifier_listener import (
+    SendFailedMessageToNotifierListener,
+)
+from xtr_notifier.notifier_interface import NotifierInterface
+
+__all__ = ["failed_message_listener"]
+
+
+def failed_message_listener(notifier: NotifierInterface) -> SendFailedMessageToNotifierListener:
+    """Report every message the bus gives up on through ``notifier``."""
+    return SendFailedMessageToNotifierListener(notifier)

xtr_notifier/bundle/_message_bus.py

@@ -0,0 +1,39 @@
+"""The bus side of the bundle: which messages are queued, and the bus they go to.
+
+Imported only when the messenger bundle is active.
+"""
+
+from __future__ import annotations
+
+from xtr_messenger import MessageBusConfig, MessageBusInterface
+
+from xtr_notifier.messenger import MESSAGE_NAMES
+
+from ._peers import MessageBusPeer
+
+__all__ = ["message_bus_peer", "routed"]
+
+_WILDCARD = "*"
+
+
+def message_bus_peer(message_bus: MessageBusInterface) -> MessageBusPeer:
+    """Hold the application's message bus."""
+    return MessageBusPeer(message_bus)
+
+
+def routed(config: MessageBusConfig, message_type: type) -> bool:
+    """Tell whether the bus does something with ``message_type`` when it is dispatched.
+
+    A message the routing names — by its class, its wire name or the ``*``
+    catch-all — goes to a transport; with ``handle_unrouted`` any message is
+    handled in-process. Anything else would be dropped quietly by the bus, so
+    it is sent at once instead: the behaviour stays the same until the
+    application routes the message.
+    """
+    if config.handle_unrouted:
+        return True
+    names = {_WILDCARD, MESSAGE_NAMES[message_type]}
+    return any(
+        key in names if isinstance(key, str) else issubclass(message_type, key)
+        for key in config.routing
+    )

xtr_notifier/bundle/_peer_factories.py

@@ -0,0 +1,46 @@
+"""The factories of the peer holders, registered only when their peer is active.
+
+Imported by the bundle only once the peer is known to be active, since each
+names a type of that peer's package.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from xtr_dependency_injection import Target
+from xtr_event_dispatcher_contracts import EventDispatcherInterface
+from xtr_http_client_contracts import HttpClientInterface
+
+from ._peers import EventDispatcherPeer, HttpClientPeer
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["event_dispatcher_peer", "http_client_peer"]
+
+
+def event_dispatcher_peer(event_dispatcher: EventDispatcherInterface) -> EventDispatcherPeer:
+    """Hold the application's default event dispatcher."""
+    return EventDispatcherPeer(event_dispatcher)
+
+
+def http_client_peer(qualifier: str | None) -> Callable[..., HttpClientPeer]:
+    """Return the factory holding the HTTP client ``qualifier`` names; ``None`` the default.
+
+    The qualifier is configuration, so the client's annotation is written onto
+    the factory at runtime rather than in its signature.
+    """
+
+    def build(http_client: HttpClientInterface) -> HttpClientPeer:
+        return HttpClientPeer(http_client)
+
+    build.__annotations__ = {
+        "http_client": (
+            HttpClientInterface
+            if qualifier is None
+            else Annotated[HttpClientInterface, Target(qualifier)]
+        ),
+        "return": HttpClientPeer,
+    }
+    return build