cue-notify-client 0.1.0__py3-none-any.whl

cue_client/__init__.py

@@ -0,0 +1,16 @@
+"""Python client for Cue: send events and messages, and verify Cue's signed webhooks."""
+
+__version__ = "0.1.0"
+
+from cue_client.client import AsyncCue, Cue, CueError, Importance
+from cue_client.webhooks import SIGNATURE_HEADER, InvalidSignatureError, verify_webhook
+
+__all__ = [
+    "SIGNATURE_HEADER",
+    "AsyncCue",
+    "Cue",
+    "CueError",
+    "Importance",
+    "InvalidSignatureError",
+    "verify_webhook",
+]

cue_client/client.py

@@ -0,0 +1,333 @@
+"""Synchronous and asynchronous clients for Cue's HTTP API."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+from cue_client import __version__
+
+Importance = Literal["low", "normal", "high", "critical"]
+JSON = dict[str, Any]
+
+RETRY_STATUSES = frozenset({429, 502, 503, 504})
+
+
+class CueError(Exception):
+    """An error response from Cue (an RFC 9457 problem document)."""
+
+    def __init__(self, status: int, title: str, detail: str, errors: list[Any] | None) -> None:
+        super().__init__(f"{status} {title}: {detail}")
+        self.status = status
+        self.title = title
+        self.detail = detail
+        self.errors = errors or []
+
+
+def _raise_for_problem(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        problem: Mapping[str, Any] = response.json()
+    except ValueError:
+        problem = {}
+    raise CueError(
+        response.status_code,
+        str(problem.get("title", response.reason_phrase)),
+        str(problem.get("detail", response.text[:300])),
+        problem.get("errors"),
+    )
+
+
+def _drop_none(values: Mapping[str, Any]) -> JSON:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _iso(value: datetime | None) -> str | None:
+    return value.isoformat() if value is not None else None
+
+
+def _event(
+    name: str,
+    recipient: str | Mapping[str, Any],
+    data: Mapping[str, Any] | None,
+    idempotency_key: str | None,
+    occurred_at: datetime | None,
+) -> JSON:
+    return _drop_none(
+        {
+            "name": name,
+            "recipient": recipient,
+            "data": dict(data or {}),
+            "idempotency_key": idempotency_key,
+            "occurred_at": _iso(occurred_at),
+        }
+    )
+
+
+def _message(
+    recipient: str,
+    template: str,
+    channels: list[str],
+    data: Mapping[str, Any] | None,
+    category: str,
+    importance: Importance,
+    expires_at: datetime | None,
+    send_at: datetime | None,
+    idempotency_key: str | None,
+) -> JSON:
+    return _drop_none(
+        {
+            "recipient": recipient,
+            "template": template,
+            "channels": channels,
+            "data": dict(data or {}),
+            "category": category,
+            "importance": importance,
+            "expires_at": _iso(expires_at),
+            "send_at": _iso(send_at),
+            "idempotency_key": idempotency_key,
+        }
+    )
+
+
+def _profile(
+    locale: str | None,
+    timezone: str | None,
+    attributes: Mapping[str, Any] | None,
+    addresses: list[Mapping[str, str]] | None,
+) -> JSON:
+    return _drop_none(
+        {
+            "locale": locale,
+            "timezone": timezone,
+            "attributes": dict(attributes) if attributes is not None else None,
+            "addresses": [dict(a) for a in addresses] if addresses is not None else None,
+        }
+    )
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": f"cue-notify-client-python/{__version__}",
+    }
+
+
+class Cue:
+    """Client for Cue's API.
+
+    ``retries`` applies to rate limiting and gateway errors on requests that are safe to
+    repeat: reads, profile updates, and sends that carry an idempotency key.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://127.0.0.1:8000",
+        *,
+        timeout: float = 10.0,
+        retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = httpx.Client(
+            base_url=base_url, headers=_headers(api_key), timeout=timeout, transport=transport
+        )
+        self._retries = retries
+
+    def __enter__(self) -> Cue:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, *, safe: bool, **kwargs: Any) -> Any:
+        attempts = self._retries + 1 if safe else 1
+        response = self._http.request(method, path, **kwargs)
+        for attempt in range(1, attempts):
+            if response.status_code not in RETRY_STATUSES:
+                break
+            time.sleep(_backoff(response, attempt))
+            response = self._http.request(method, path, **kwargs)
+        _raise_for_problem(response)
+        return response.json() if response.content else None
+
+    def send_event(
+        self,
+        name: str,
+        recipient: str | Mapping[str, Any],
+        data: Mapping[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        occurred_at: datetime | None = None,
+    ) -> JSON:
+        """Report that something happened; Cue's rules decide what to send."""
+        body = _event(name, recipient, data, idempotency_key, occurred_at)
+        return self._request("POST", "/v1/events", json=body, safe=idempotency_key is not None)
+
+    def send_message(
+        self,
+        recipient: str,
+        template: str,
+        channels: list[str],
+        data: Mapping[str, Any] | None = None,
+        *,
+        category: str = "transactional",
+        importance: Importance = "normal",
+        expires_at: datetime | None = None,
+        send_at: datetime | None = None,
+        idempotency_key: str | None = None,
+    ) -> JSON:
+        """Send a template directly. Check ``status``: it may be ``suppressed``."""
+        body = _message(
+            recipient,
+            template,
+            channels,
+            data,
+            category,
+            importance,
+            expires_at,
+            send_at,
+            idempotency_key,
+        )
+        return self._request("POST", "/v1/messages", json=body, safe=idempotency_key is not None)
+
+    def upsert_recipient(
+        self,
+        external_id: str,
+        *,
+        locale: str | None = None,
+        timezone: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+        addresses: list[Mapping[str, str]] | None = None,
+    ) -> JSON:
+        body = _profile(locale, timezone, attributes, addresses)
+        return self._request("PUT", f"/v1/recipients/{_segment(external_id)}", json=body, safe=True)
+
+    def get_message(self, message_id: str) -> JSON:
+        return self._request("GET", f"/v1/messages/{_segment(message_id)}", safe=True)
+
+    def list_messages(self, **filters: str | int) -> JSON:
+        """Filters: ``recipient``, ``status``, ``event_id``, ``agent``, ``limit``, ``cursor``."""
+        return self._request("GET", "/v1/messages", params=filters, safe=True)
+
+
+class AsyncCue:
+    """The asynchronous twin of :class:`Cue`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://127.0.0.1:8000",
+        *,
+        timeout: float = 10.0,
+        retries: int = 2,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=base_url, headers=_headers(api_key), timeout=timeout, transport=transport
+        )
+        self._retries = retries
+
+    async def __aenter__(self) -> AsyncCue:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, *, safe: bool, **kwargs: Any) -> Any:
+        attempts = self._retries + 1 if safe else 1
+        response = await self._http.request(method, path, **kwargs)
+        for attempt in range(1, attempts):
+            if response.status_code not in RETRY_STATUSES:
+                break
+            await asyncio.sleep(_backoff(response, attempt))
+            response = await self._http.request(method, path, **kwargs)
+        _raise_for_problem(response)
+        return response.json() if response.content else None
+
+    async def send_event(
+        self,
+        name: str,
+        recipient: str | Mapping[str, Any],
+        data: Mapping[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        occurred_at: datetime | None = None,
+    ) -> JSON:
+        body = _event(name, recipient, data, idempotency_key, occurred_at)
+        return await self._request(
+            "POST", "/v1/events", json=body, safe=idempotency_key is not None
+        )
+
+    async def send_message(
+        self,
+        recipient: str,
+        template: str,
+        channels: list[str],
+        data: Mapping[str, Any] | None = None,
+        *,
+        category: str = "transactional",
+        importance: Importance = "normal",
+        expires_at: datetime | None = None,
+        send_at: datetime | None = None,
+        idempotency_key: str | None = None,
+    ) -> JSON:
+        body = _message(
+            recipient,
+            template,
+            channels,
+            data,
+            category,
+            importance,
+            expires_at,
+            send_at,
+            idempotency_key,
+        )
+        return await self._request(
+            "POST", "/v1/messages", json=body, safe=idempotency_key is not None
+        )
+
+    async def upsert_recipient(
+        self,
+        external_id: str,
+        *,
+        locale: str | None = None,
+        timezone: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+        addresses: list[Mapping[str, str]] | None = None,
+    ) -> JSON:
+        body = _profile(locale, timezone, attributes, addresses)
+        return await self._request(
+            "PUT", f"/v1/recipients/{_segment(external_id)}", json=body, safe=True
+        )
+
+    async def get_message(self, message_id: str) -> JSON:
+        return await self._request("GET", f"/v1/messages/{_segment(message_id)}", safe=True)
+
+    async def list_messages(self, **filters: str | int) -> JSON:
+        return await self._request("GET", "/v1/messages", params=filters, safe=True)
+
+
+def _segment(value: str) -> str:
+    """A path segment that cannot step into another endpoint."""
+    return quote(value, safe="")
+
+
+def _backoff(response: httpx.Response, attempt: int) -> float:
+    retry_after = response.headers.get("Retry-After")
+    if retry_after and retry_after.isdigit():
+        return min(float(retry_after), 30.0)
+    return min(0.5 * 2 ** (attempt - 1), 8.0)

cue_client/webhooks.py

@@ -0,0 +1,48 @@
+"""Verify the signature on requests Cue's webhook connector sends to your service.
+
+Cue signs the raw body: ``Cue-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of
+"<t>.<raw body>">``. Verify against the bytes you received, before parsing them, and
+reject old timestamps so a captured request cannot be replayed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+SIGNATURE_HEADER = "Cue-Signature"
+DEFAULT_TOLERANCE = 300
+
+
+class InvalidSignatureError(Exception):
+    """The request was not signed by Cue with this secret, or is too old."""
+
+
+def verify_webhook(
+    body: bytes,
+    signature: str | None,
+    secret: str,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: float | None = None,
+) -> None:
+    """Raise :class:`InvalidSignatureError` unless ``signature`` (the ``Cue-Signature``
+    header) is a valid, fresh signature of ``body``.
+
+    ``tolerance`` is the accepted clock difference in seconds.
+    """
+    if not signature:
+        raise InvalidSignatureError("missing Cue-Signature header")
+    parts = dict(part.split("=", 1) for part in signature.split(",") if "=" in part)
+    try:
+        timestamp = int(parts["t"])
+        candidate = parts["v1"]
+    except (KeyError, ValueError) as exc:
+        raise InvalidSignatureError("malformed Cue-Signature header") from exc
+    current = time.time() if now is None else now
+    if abs(current - timestamp) > tolerance:
+        raise InvalidSignatureError("signature timestamp is outside the tolerance")
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256)
+    if not hmac.compare_digest(expected.hexdigest(), candidate):
+        raise InvalidSignatureError("signature does not match")

cue_notify_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: cue-notify-client
+Version: 0.1.0
+Summary: Python client for Cue: send events and messages, and verify Cue's signed webhooks.
+Project-URL: Homepage, https://github.com/murtazox04/Cue/tree/main/sdks/python
+Project-URL: Documentation, https://murtazox04.github.io/Cue
+Author: Murtazo Xurramov
+License-Expression: MIT
+Keywords: cue,notifications,sdk,webhooks
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# cue-notify-client
+
+Python client for [Cue](https://github.com/murtazox04/Cue), the attention layer between
+software, AI agents and people. Its only dependency is `httpx`.
+
+```bash
+pip install cue-notify-client
+```
+
+The package is imported as `cue_client`.
+
+```python
+from cue_client import Cue
+
+with Cue(api_key="ck_…", base_url="https://cue.example.com") as cue:
+    cue.upsert_recipient(
+        "user-42",
+        timezone="Europe/Berlin",
+        addresses=[{"channel": "email", "value": "ann@example.com"}],
+    )
+    cue.send_event(
+        "order.shipped", "user-42", {"order_id": "1001"}, idempotency_key="order-1001-shipped"
+    )
+```
+
+`AsyncCue` has the same methods for `asyncio`. Errors raise `CueError` with the problem
+details Cue returns (`status`, `title`, `detail`, `errors`). Rate limits and gateway
+errors are retried automatically for requests that are safe to repeat: reads, profile
+updates, and sends with an idempotency key.
+
+## Verifying webhooks
+
+If Cue delivers to your service through its webhook connector, check every request
+before trusting it:
+
+```python
+from cue_client import InvalidSignatureError, verify_webhook
+
+
+def handle(request):
+    try:
+        verify_webhook(request.body, request.headers.get("Cue-Signature"), secret=WEBHOOK_SECRET)
+    except InvalidSignatureError:
+        return 401
+    message = json.loads(request.body)
+    ...
+```
+
+Verify the raw body bytes, before parsing them. Requests signed more than five minutes
+ago are rejected (`tolerance=` changes this).

cue_notify_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+cue_client/__init__.py,sha256=coalsqGvq4IyuVoUZUYY64TmzabDO7MAOgdZ-ETeoKo,418
+cue_client/client.py,sha256=7OKYADQ7mK6R1ed1AAkI6dGg-gPWoH_4iKHeMx7OGZI,10350
+cue_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cue_client/webhooks.py,sha256=vfr1Ns_9iV7uoLNt47xNGPa1XSIVbDx1s4pensb9NXQ,1728
+cue_notify_client-0.1.0.dist-info/METADATA,sha256=DzUx8Dt4imhvE20ZwqkMrtXGC_qKP9xh8bCQGtKLBvs,2114
+cue_notify_client-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+cue_notify_client-0.1.0.dist-info/RECORD,,

cue_notify_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any