beaconbox 0.1.0__py3-none-any.whl

beaconbox/__init__.py

@@ -0,0 +1,125 @@
+"""Official Python SDK for BeaconBox.
+
+BeaconBox is a private inbox where only businesses a customer has bought from can reach them, so
+shipping, tracking, payment and firmware updates never get lost to spam.
+
+.. code-block:: python
+
+    from beaconbox import BeaconBox
+
+    client = BeaconBox()  # reads BEACONBOX_API_KEY
+
+    result = client.messages.push(
+        recipient_email="buyer@example.com",
+        subject="Your order has shipped",
+        body="Tracking XY123456789EE. Estimated delivery Thursday.",
+    )
+    print(result.id)
+
+Everything is also available awaited, from :class:`AsyncBeaconBox`, with identical signatures.
+
+The two conventions this SDK exists to keep you from having to remember are on
+:class:`BeaconBox`: it supplies the idempotency key every write requires, and it never raises on
+a channel that was skipped.
+"""
+
+from ._logging import install_null_handler
+from ._version import __version__
+from .client import AsyncBeaconBox, BeaconBox
+from .enums import (
+    Channel,
+    ChannelSendStatus,
+    MessageKind,
+    MessageStatus,
+    RecipientStatus,
+    SkipReason,
+    WebhookEventType,
+    WhatsAppReplyForward,
+)
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BeaconBoxError,
+    ConflictError,
+    InvalidRequestError,
+    PermissionDeniedError,
+    RateLimitError,
+    ResourceMissingError,
+    ServerError,
+    WebhookVerificationError,
+)
+from .models import (
+    ApiKey,
+    BatchItemResult,
+    BatchResult,
+    CreditBalance,
+    DeliveryStatus,
+    Message,
+    MessagePage,
+    MessagePush,
+    MessagePushResult,
+    NewApiKey,
+    NewWebhookEndpoint,
+    RecipientSms,
+    RetractResult,
+    SmsDelivery,
+    SmsOutcome,
+    WebhookEndpoint,
+    WebhookEvent,
+    WhatsAppErasureReceipt,
+    WhatsAppOptInOutcome,
+    WhatsAppOutcome,
+)
+from .retry import RetryPolicy
+
+# A library must be silent until the application asks otherwise. See beaconbox._logging: this
+# attaches a NullHandler to the `beaconbox` logger and configures nothing else, so importing this
+# SDK never prints anything and never touches the root logger.
+install_null_handler()
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "ApiKey",
+    "AsyncBeaconBox",
+    "AuthenticationError",
+    "BatchItemResult",
+    "BatchResult",
+    "BeaconBox",
+    "BeaconBoxError",
+    "Channel",
+    "ChannelSendStatus",
+    "ConflictError",
+    "CreditBalance",
+    "DeliveryStatus",
+    "InvalidRequestError",
+    "Message",
+    "MessageKind",
+    "MessagePage",
+    "MessagePush",
+    "MessagePushResult",
+    "MessageStatus",
+    "NewApiKey",
+    "NewWebhookEndpoint",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RecipientSms",
+    "RecipientStatus",
+    "ResourceMissingError",
+    "RetractResult",
+    "RetryPolicy",
+    "ServerError",
+    "SkipReason",
+    "SmsDelivery",
+    "SmsOutcome",
+    "WebhookEndpoint",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookVerificationError",
+    "WhatsAppErasureReceipt",
+    "WhatsAppOptInOutcome",
+    "WhatsAppOutcome",
+    "WhatsAppReplyForward",
+    "__version__",
+]

beaconbox/_core.py

@@ -0,0 +1,248 @@
+"""The part of this SDK that has no idea HTTP exists.
+
+Everything here is a pure function of its inputs: turn a :class:`Call` into the bytes and headers
+that should go on the wire, and turn a status code plus a body back into a model or an exception.
+No sockets, no sleeping, no httpx import anywhere in this module.
+
+That line is what lets the sync client and the async client be the same client. Authentication,
+the idempotency key, URL construction, JSON encoding, error mapping and response parsing are
+written once here; :mod:`beaconbox._transport` adds only the two things that genuinely differ
+between them, which are how you send a request and how you wait.
+
+It is also what makes the SDK testable without a network: a test can build a ``Call``, prepare it
+and assert on the exact headers, or hand :func:`Core.interpret` a canned 429 and assert on the
+exception, with no server and no mocking library involved.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+from urllib.parse import quote, urlencode, urlsplit
+
+from ._version import __version__
+from .errors import APIError, error_class_for
+
+T = TypeVar("T")
+
+API_PREFIX = "/api/v1"
+DEFAULT_BASE_URL = "https://api.beaconbox.eu"
+
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+
+
+def new_idempotency_key() -> str:
+    """A fresh v4 UUID for the ``Idempotency-Key`` header.
+
+    Minted once per logical call and reused for every retry of it. See
+    :meth:`Core.prepare`, which is where that pairing is enforced.
+    """
+    return str(uuid.uuid4())
+
+
+@dataclass(frozen=True)
+class Call(Generic[T]):
+    """One API operation, described without reference to how it will be sent.
+
+    ``parse`` is carried alongside the request rather than looked up afterwards, so a resource
+    method's return type is fixed at the point the call is described and a transport cannot get
+    it wrong.
+    """
+
+    method: str
+    path: str
+    parse: Callable[[Any], T]
+    body: dict[str, Any] | None = None
+    params: Mapping[str, Any] = field(default_factory=dict)
+
+    route: str | None = None
+    """A templated, **log-safe** name for this operation, for example
+    ``/recipients/{email}/sms``.
+
+    Set it on every call whose path interpolates a value. ``path`` cannot be logged: a recipient's
+    email address is substituted straight into it, so logging the path would write personal data
+    into a merchant's log aggregator on every request. Query strings are never logged for the same
+    reason (``?recipient_email=``), and neither are bodies or headers.
+    """
+
+    @property
+    def log_name(self) -> str:
+        """What :mod:`beaconbox._transport` logs. Never the interpolated path."""
+        return f"{self.method} {self.route or self.path}"
+
+    @property
+    def needs_idempotency(self) -> bool:
+        """Every ``POST`` in this API requires an ``Idempotency-Key``, and nothing else does.
+
+        ``PUT`` and ``DELETE`` on a recipient's phone number are idempotent by construction:
+        setting a number twice leaves one number. Sending a message twice sends two messages and
+        charges two credits, which is the whole reason the header is mandatory on ``POST``.
+        """
+        return self.method == "POST"
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    """Exactly what should go on the wire. Built once, sent as many times as it takes."""
+
+    method: str
+    url: str
+    headers: dict[str, str]
+    content: bytes | None
+
+
+class Core:
+    """Request building and response interpretation, shared by both clients."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        user_agent_suffix: str | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError(
+                "BeaconBox: an API key is required. Pass api_key= or set BEACONBOX_API_KEY."
+            )
+        self._api_key = api_key.strip()
+        self.base_url = _validated_base_url(base_url)
+        suffix = f" {user_agent_suffix}" if user_agent_suffix else ""
+        self.user_agent = f"beaconbox-python/{__version__}{suffix}"
+
+    def __repr__(self) -> str:
+        """No key, ever. This object ends up inside client reprs, tracebacks and log lines."""
+        return f"Core(base_url={self.base_url!r})"
+
+    def prepare(self, call: Call[Any], idempotency_key: str | None = None) -> PreparedRequest:
+        """Build the request for ``call``.
+
+        **Call this once per logical operation, outside any retry loop.** The idempotency key is
+        minted here, so preparing again per attempt would mint a second key, and a second key is
+        what turns a retry into a duplicate message and a duplicate charge.
+        """
+        url = self.base_url + API_PREFIX + call.path
+        query = {k: _query_value(v) for k, v in call.params.items() if v is not None}
+        if query:
+            url += "?" + urlencode(query)
+
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        content: bytes | None = None
+        if call.body is not None:
+            headers["Content-Type"] = "application/json"
+            content = json.dumps(call.body, separators=(",", ":")).encode()
+        if call.needs_idempotency:
+            headers["Idempotency-Key"] = idempotency_key or new_idempotency_key()
+
+        return PreparedRequest(method=call.method, url=url, headers=headers, content=content)
+
+    def interpret(
+        self,
+        call: Call[T],
+        status_code: int,
+        headers: Mapping[str, str],
+        content: bytes,
+    ) -> T:
+        """Turn a response into a model, or raise the matching :class:`~beaconbox.errors.APIError`.
+
+        Only called for a response the transport has decided not to retry, so anything reaching
+        here with a 4xx or 5xx is final.
+        """
+        if status_code >= 400:
+            raise self._to_error(status_code, headers, content)
+        return call.parse(_decode(content))
+
+    def _to_error(self, status_code: int, headers: Mapping[str, str], content: bytes) -> APIError:
+        body = _decode(content)
+        body = body if isinstance(body, dict) else {"raw": body}
+        error_code = body.get("error_code") if isinstance(body.get("error_code"), str) else None
+        detail = body.get("detail")
+        summary = detail if isinstance(detail, str) else error_code or "request failed"
+        request_id = _header(headers, "x-request-id")
+        return error_class_for(status_code)(
+            f"BeaconBox: {summary} (HTTP {status_code})",
+            status_code=status_code,
+            error_code=error_code,
+            body=body,
+            request_id=request_id,
+            retry_after=retry_after_seconds(headers),
+        )
+
+
+def retry_after_seconds(headers: Mapping[str, str]) -> float | None:
+    """``Retry-After`` in seconds, when the server sent a sane one.
+
+    Only the delta-seconds form is honoured. The HTTP-date form is legal and essentially never
+    used by an API, and parsing it would mean trusting the caller's clock to agree with the
+    server's, which is the assumption that makes it worse than the SDK's own backoff.
+    """
+    value = _header(headers, "retry-after")
+    if value is None:
+        return None
+    try:
+        seconds = float(value.strip())
+    except ValueError:
+        return None
+    return seconds if seconds >= 0 else None
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    """Case-insensitive lookup, because a raw mapping in a test is not httpx's ``Headers``."""
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _decode(content: bytes) -> Any:
+    """Body to Python. A 204 has none, and a non-JSON body is preserved rather than swallowed."""
+    if not content or not content.strip():
+        return {}
+    try:
+        return json.loads(content)
+    except ValueError:
+        return {"raw": content.decode("utf-8", "replace")}
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _validated_base_url(base_url: str) -> str:
+    """Reject a base URL that would put an API key on the wire in clear.
+
+    ``http`` is allowed only for a loopback host, which is what the local development stack and
+    the SDK's own live tests run against. Anywhere else it means the bearer token, the recipient's
+    email address and the body of the message are readable by anything on the path, and an SDK
+    that shrugs at that is the reason it happens in production.
+    """
+    cleaned = base_url.strip().rstrip("/")
+    parts = urlsplit(cleaned)
+    if parts.scheme not in {"http", "https"}:
+        raise ValueError(f"BeaconBox: base_url must be http or https, got {base_url!r}")
+    if not parts.netloc:
+        raise ValueError(f"BeaconBox: base_url must include a host, got {base_url!r}")
+    if parts.scheme == "http" and (parts.hostname or "") not in _LOCAL_HOSTS:
+        raise ValueError(
+            f"BeaconBox: refusing to send an API key over plain http to {parts.hostname!r}. "
+            "Use https (http is permitted for localhost only)."
+        )
+    return cleaned
+
+
+def path_segment(value: str) -> str:
+    """Percent-encode one path segment.
+
+    ``safe=""`` so that an email address's ``@``, and above all a ``/``, cannot walk out of the
+    segment they were substituted into and address a different endpoint.
+    """
+    return quote(value, safe="")

beaconbox/_logging.py

@@ -0,0 +1,81 @@
+"""How this library logs, and the rules it will not break.
+
+A library's logging is not an application's logging. The rules below are the standard ones, and
+each is here because breaking it steals a decision from the person integrating this SDK:
+
+* **One logger per module, named after the module.** Everything lands under the ``beaconbox``
+  hierarchy, so an application silences or raises the whole SDK with one line:
+
+  .. code-block:: python
+
+      logging.getLogger("beaconbox").setLevel(logging.DEBUG)
+
+* **A** :class:`~logging.NullHandler` **on the root of that hierarchy, and nothing else.** Added in
+  :mod:`beaconbox.__init__`. It means importing this SDK produces no output, ever, until the
+  application asks for some.
+* **Never configure logging.** No ``basicConfig``, no handlers, no formatters, no level set on the
+  root logger. A library that calls ``basicConfig()`` at import silently hijacks the logging of
+  every application that imports it.
+* **Never log anything sensitive.** See :func:`safe_extra`. This is the rule with teeth: BeaconBox
+  requests carry an API key, a recipient's email address and the text of a message to a real
+  person. A log line is copied to an aggregator, retained for months and read by people who were
+  never meant to see any of that.
+
+What actually gets logged, all of it on the ``beaconbox._transport`` logger:
+
+===========  ===========================================================================
+``DEBUG``    every request, and every response, with its status and elapsed time
+``WARNING``  a retry, with the reason and the backoff
+===========  ===========================================================================
+
+Nothing is logged at ``INFO`` or above in normal operation. An SDK that chatters at ``INFO`` is an
+SDK whose users filter it out, which is how the ``WARNING`` that mattered gets filtered out too.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+LOGGER_NAME = "beaconbox"
+
+
+def get_logger(name: str) -> logging.Logger:
+    """The logger for a module inside this package. Always use this rather than a bare
+    ``getLogger``, so nothing accidentally logs outside the ``beaconbox`` hierarchy."""
+    return logging.getLogger(name)
+
+
+def install_null_handler() -> None:
+    """Attach a :class:`~logging.NullHandler` to ``beaconbox``, once.
+
+    Without it, a warning emitted before the application configures logging would either print
+    ``No handlers could be found`` or fall through to the root logger's ``lastResort`` handler and
+    appear on stderr, uninvited.
+    """
+    root = logging.getLogger(LOGGER_NAME)
+    if not any(isinstance(handler, logging.NullHandler) for handler in root.handlers):
+        root.addHandler(logging.NullHandler())
+
+
+def safe_extra(**fields: Any) -> dict[str, Any]:
+    """The allow-list for structured log fields.
+
+    Deliberately an allow-list rather than a redaction pass. Redaction is a list of things somebody
+    remembered to hide, and the field that gets added next year is not on it. This way a value has
+    to be named here to ever reach a log line.
+
+    **What is never logged, and why:**
+
+    * the API key, or any header (``Authorization`` is a header);
+    * the request or response body (a message body is text written to a named customer);
+    * the query string (``?recipient_email=buyer@example.com``);
+    * the interpolated URL path (``/recipients/buyer@example.com/sms``). The templated
+      :attr:`~beaconbox._core.Call.route` is logged instead;
+    * webhook secrets, and the payload of a webhook.
+
+    The idempotency key is logged, because it is a random value of the caller's choosing that
+    identifies one attempt, and correlating retries without it is guesswork. If a caller passes
+    something identifying as their own key, that is their value in their logs.
+    """
+    return {"beaconbox": fields}

beaconbox/_ops.py

@@ -0,0 +1,196 @@
+"""Every API operation, described once.
+
+A resource method on the sync client and its twin on the async client build the *same*
+:class:`~beaconbox._core.Call` from this module, so the URL, the body shape and the response type
+of an operation have exactly one definition. What differs between the two clients is the keyword
+``await``, and nothing else.
+
+The prose that teaches an operation lives on the resource methods, where an editor will show it.
+What lives here is the wire contract.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from ._core import Call, path_segment
+from .models import (
+    ApiKey,
+    BatchResult,
+    CreditBalance,
+    Message,
+    MessagePage,
+    MessagePushResult,
+    NewApiKey,
+    NewWebhookEndpoint,
+    RecipientSms,
+    RetractResult,
+    SmsOutcome,
+    WebhookEndpoint,
+    WhatsAppErasureReceipt,
+    WhatsAppOutcome,
+)
+
+Payload = dict[str, Any]
+
+
+def _nothing(_: Any) -> None:
+    """For a 204. The call succeeded and the body is empty by design."""
+    return None
+
+
+def _keys(body: Any) -> tuple[ApiKey, ...]:
+    items = body.get("items") if isinstance(body, dict) else None
+    return tuple(ApiKey.from_api(i) for i in (items or []) if isinstance(i, dict))
+
+
+def _endpoints(body: Any) -> tuple[WebhookEndpoint, ...]:
+    items = body.get("items") if isinstance(body, dict) else None
+    return tuple(WebhookEndpoint.from_api(i) for i in (items or []) if isinstance(i, dict))
+
+
+# --- Messages ---------------------------------------------------------------------------
+
+
+def push(body: Payload) -> Call[MessagePushResult]:
+    return Call("POST", "/messages", MessagePushResult.from_api, body=body)
+
+
+def push_batch(bodies: Sequence[Payload]) -> Call[BatchResult]:
+    # `items`, which is what the API's MessageBatchPush declares. The name matters: a batch sent
+    # under any other key is a 422 that only shows up against a real server.
+    return Call("POST", "/messages/batch", BatchResult.from_api, body={"items": list(bodies)})
+
+
+def get_message(public_id: str) -> Call[Message]:
+    return Call(
+        "GET", f"/messages/{path_segment(public_id)}", Message.from_api, route="/messages/{id}"
+    )
+
+
+def list_messages(
+    recipient_email: str | None, limit: int | None, cursor: str | None
+) -> Call[MessagePage]:
+    return Call(
+        "GET",
+        "/messages",
+        MessagePage.from_api,
+        params={"recipient_email": recipient_email, "limit": limit, "cursor": cursor},
+    )
+
+
+def resend_sms(public_id: str) -> Call[SmsOutcome]:
+    return Call(
+        "POST",
+        f"/messages/{path_segment(public_id)}/sms",
+        SmsOutcome.from_api,
+        route="/messages/{id}/sms",
+    )
+
+
+def resend_whatsapp(public_id: str) -> Call[WhatsAppOutcome]:
+    return Call(
+        "POST",
+        f"/messages/{path_segment(public_id)}/whatsapp",
+        WhatsAppOutcome.from_api,
+        route="/messages/{id}/whatsapp",
+    )
+
+
+def retract(public_id: str) -> Call[RetractResult]:
+    return Call(
+        "POST",
+        f"/messages/{path_segment(public_id)}/retract",
+        RetractResult.from_api,
+        route="/messages/{id}/retract",
+    )
+
+
+# --- Credits ----------------------------------------------------------------------------
+
+
+def credit_balance() -> Call[CreditBalance]:
+    return Call("GET", "/credits", CreditBalance.from_api)
+
+
+# --- Recipients -------------------------------------------------------------------------
+
+
+def recipient_sms(email: str) -> Call[RecipientSms]:
+    return Call(
+        "GET",
+        f"/recipients/{path_segment(email)}/sms",
+        RecipientSms.from_api,
+        route="/recipients/{email}/sms",
+    )
+
+
+def set_recipient_phone(email: str, phone: str) -> Call[RecipientSms]:
+    return Call(
+        "PUT",
+        f"/recipients/{path_segment(email)}/phone",
+        RecipientSms.from_api,
+        body={"phone": phone},
+        route="/recipients/{email}/phone",
+    )
+
+
+def clear_recipient_phone(email: str) -> Call[RecipientSms]:
+    return Call(
+        "DELETE",
+        f"/recipients/{path_segment(email)}/phone",
+        RecipientSms.from_api,
+        route="/recipients/{email}/phone",
+    )
+
+
+def erase_whatsapp(email: str) -> Call[WhatsAppErasureReceipt]:
+    return Call(
+        "POST",
+        f"/recipients/{path_segment(email)}/whatsapp/erase",
+        WhatsAppErasureReceipt.from_api,
+        route="/recipients/{email}/whatsapp/erase",
+    )
+
+
+# --- Keys -------------------------------------------------------------------------------
+
+
+def list_keys() -> Call[tuple[ApiKey, ...]]:
+    return Call("GET", "/keys", _keys)
+
+
+def create_key(name: str | None) -> Call[NewApiKey]:
+    return Call("POST", "/keys", NewApiKey.from_api, body={"name": name})
+
+
+def revoke_key(key_id: str) -> Call[None]:
+    return Call("DELETE", f"/keys/{path_segment(key_id)}", _nothing, route="/keys/{id}")
+
+
+# --- Webhook endpoints ------------------------------------------------------------------
+
+
+def list_webhook_endpoints() -> Call[tuple[WebhookEndpoint, ...]]:
+    return Call("GET", "/webhook-endpoints", _endpoints)
+
+
+def create_webhook_endpoint(
+    url: str, event_types: Sequence[str], description: str
+) -> Call[NewWebhookEndpoint]:
+    return Call(
+        "POST",
+        "/webhook-endpoints",
+        NewWebhookEndpoint.from_api,
+        body={"url": url, "event_types": list(event_types), "description": description},
+    )
+
+
+def delete_webhook_endpoint(public_id: str) -> Call[None]:
+    return Call(
+        "DELETE",
+        f"/webhook-endpoints/{path_segment(public_id)}",
+        _nothing,
+        route="/webhook-endpoints/{id}",
+    )