norialabs-send 0.1.0__tar.gz

norialabs_send-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+coverage/
+
+sdks/php/vendor/
+sdks/php/composer.lock
+sdks/php/.phpstan-cache/
+sdks/php/.phpunit.cache/
+
+sdks/python/.venv/
+sdks/python/.pytest_cache/
+sdks/python/.ruff_cache/
+sdks/python/dist/
+**/__pycache__/
+
+apps/console/dist/
+apps/console/tsconfig.tsbuildinfo

norialabs_send-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noria Labs
+
+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.

norialabs_send-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: norialabs-send
+Version: 0.1.0
+Summary: Python client for Noria Send: send transactional email and SMS through one internal service instead of wiring a provider into every product.
+Project-URL: Homepage, https://github.com/norialabs/send
+Project-URL: Source, https://github.com/norialabs/send
+Project-URL: Issues, https://github.com/norialabs/send/issues
+Author-email: Joseph Gitonga <thekiharani@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,noria,onfon,send,ses,sms,transactional
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# norialabs-send
+
+Python client for [Noria Send](https://github.com/norialabs/send): transactional email and
+SMS through one internal service. Sync and async, typed, no dependency beyond `httpx`.
+
+```bash
+pip install norialabs-send      # or: uv add norialabs-send
+```
+
+```python
+from noria_send import Send
+
+send = Send(api_key=os.environ["NORIA_SEND_KEY"])
+
+send.emails.send({
+    "from_": "Noria <hello@norialabs.com>",
+    "to": "founder@example.com",
+    "subject": "Welcome",
+    "html": "<p>Hi there</p>",
+})
+
+send.sms.send({"from_": "NORIA", "to": "0712345678", "text": "Your code is 482913"})
+```
+
+`base_url` defaults to `https://send.noria.co.ke`; pass it to reach a local service or another
+instance.
+
+`from_` carries the trailing underscore because `from` is a keyword; it is sent as `from`.
+Every other field is exactly what goes on the wire.
+
+## Async
+
+The same surface, for FastAPI and anything else on asyncio.
+
+```python
+from noria_send import AsyncSend
+
+async with AsyncSend(api_key=key, base_url=url) as send:
+    await send.emails.send({"to": "a@example.com", "subject": "Hi", "text": "there"})
+    await send.sms.send({"to": "0712345678", "text": "Your code is 482913"})
+```
+
+## Sending
+
+```python
+send.emails.send(email, idempotency_key=f"signin-{token.id}")
+send.emails.send_batch([email, email])
+
+send.sms.send(message, idempotency_key=f"otp-{token.id}")
+send.sms.send_batch([message, message])
+```
+
+Both also take `template` and `variables` instead of a body, `scheduled_at` for a future send
+and `tags`. Email adds `attachments` as base64, plus `cc`, `bcc`, `reply_to` and `headers`.
+
+An SMS takes one recipient, because one row carries one provider message id and that is what a
+delivery receipt is matched against. Use `send_batch` for many.
+
+## Reading what was sent
+
+One ledger covers every channel:
+
+```python
+send.messages.list(channel="sms", status="failed", limit=50)
+send.messages.get(message_id)
+send.messages.events(message_id)
+send.messages.cancel(message_id)
+send.messages.requeue(message_id)
+```
+
+## Domains, senders, templates, suppressions, webhooks
+
+```python
+send.domains.create("norialabs.com")          # returns the DNS records to publish
+send.senders.create("NORIA")                  # registered pending approval
+send.templates.upsert("welcome", subject="Hi {{name}}", html=html)
+send.templates.upsert("otp", channel="sms", text="Code {{code}}")
+send.suppressions.add("0712345678", channel="sms", reason="unsubscribe")
+send.is_suppressed("0712345678", "sms")
+send.webhooks.create("https://app.example.com/hooks/send", ["delivered", "bounced"])
+```
+
+A slug is unique per channel, so an `otp` email template and an `otp` SMS template can coexist.
+
+## Errors
+
+Failures raise `SendError` with `code`, `status`, `details` and `request_id`, plus
+`suppressed`, `over_quota` and `retryable` for the common branches. The client retries 408,
+429 and 5xx with backoff and never retries `quota_exceeded`, `suppressed_recipient`,
+`domain_not_verified`, `sender_not_approved` or `message_too_long`.
+
+```python
+try:
+    send.sms.send(message)
+except SendError as error:
+    if error.suppressed:
+        return
+    raise
+```
+
+## Webhooks
+
+```python
+from noria_send import verify_webhook
+
+event = verify_webhook(
+    payload=await request.body(),
+    signature=request.headers["noria-signature"],
+    secret=os.environ["NORIA_SEND_WEBHOOK_SECRET"],
+)
+```
+
+HMAC-SHA256 over `<timestamp>.<raw body>`, compared in constant time, with a five minute
+tolerance against replay. `event["data"]["channel"]` says which channel the event came from.
+
+## Tests
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```

norialabs_send-0.1.0/README.md

@@ -0,0 +1,122 @@
+# norialabs-send
+
+Python client for [Noria Send](https://github.com/norialabs/send): transactional email and
+SMS through one internal service. Sync and async, typed, no dependency beyond `httpx`.
+
+```bash
+pip install norialabs-send      # or: uv add norialabs-send
+```
+
+```python
+from noria_send import Send
+
+send = Send(api_key=os.environ["NORIA_SEND_KEY"])
+
+send.emails.send({
+    "from_": "Noria <hello@norialabs.com>",
+    "to": "founder@example.com",
+    "subject": "Welcome",
+    "html": "<p>Hi there</p>",
+})
+
+send.sms.send({"from_": "NORIA", "to": "0712345678", "text": "Your code is 482913"})
+```
+
+`base_url` defaults to `https://send.noria.co.ke`; pass it to reach a local service or another
+instance.
+
+`from_` carries the trailing underscore because `from` is a keyword; it is sent as `from`.
+Every other field is exactly what goes on the wire.
+
+## Async
+
+The same surface, for FastAPI and anything else on asyncio.
+
+```python
+from noria_send import AsyncSend
+
+async with AsyncSend(api_key=key, base_url=url) as send:
+    await send.emails.send({"to": "a@example.com", "subject": "Hi", "text": "there"})
+    await send.sms.send({"to": "0712345678", "text": "Your code is 482913"})
+```
+
+## Sending
+
+```python
+send.emails.send(email, idempotency_key=f"signin-{token.id}")
+send.emails.send_batch([email, email])
+
+send.sms.send(message, idempotency_key=f"otp-{token.id}")
+send.sms.send_batch([message, message])
+```
+
+Both also take `template` and `variables` instead of a body, `scheduled_at` for a future send
+and `tags`. Email adds `attachments` as base64, plus `cc`, `bcc`, `reply_to` and `headers`.
+
+An SMS takes one recipient, because one row carries one provider message id and that is what a
+delivery receipt is matched against. Use `send_batch` for many.
+
+## Reading what was sent
+
+One ledger covers every channel:
+
+```python
+send.messages.list(channel="sms", status="failed", limit=50)
+send.messages.get(message_id)
+send.messages.events(message_id)
+send.messages.cancel(message_id)
+send.messages.requeue(message_id)
+```
+
+## Domains, senders, templates, suppressions, webhooks
+
+```python
+send.domains.create("norialabs.com")          # returns the DNS records to publish
+send.senders.create("NORIA")                  # registered pending approval
+send.templates.upsert("welcome", subject="Hi {{name}}", html=html)
+send.templates.upsert("otp", channel="sms", text="Code {{code}}")
+send.suppressions.add("0712345678", channel="sms", reason="unsubscribe")
+send.is_suppressed("0712345678", "sms")
+send.webhooks.create("https://app.example.com/hooks/send", ["delivered", "bounced"])
+```
+
+A slug is unique per channel, so an `otp` email template and an `otp` SMS template can coexist.
+
+## Errors
+
+Failures raise `SendError` with `code`, `status`, `details` and `request_id`, plus
+`suppressed`, `over_quota` and `retryable` for the common branches. The client retries 408,
+429 and 5xx with backoff and never retries `quota_exceeded`, `suppressed_recipient`,
+`domain_not_verified`, `sender_not_approved` or `message_too_long`.
+
+```python
+try:
+    send.sms.send(message)
+except SendError as error:
+    if error.suppressed:
+        return
+    raise
+```
+
+## Webhooks
+
+```python
+from noria_send import verify_webhook
+
+event = verify_webhook(
+    payload=await request.body(),
+    signature=request.headers["noria-signature"],
+    secret=os.environ["NORIA_SEND_WEBHOOK_SECRET"],
+)
+```
+
+HMAC-SHA256 over `<timestamp>.<raw body>`, compared in constant time, with a five minute
+tolerance against replay. `event["data"]["channel"]` says which channel the event came from.
+
+## Tests
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```

norialabs_send-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "norialabs-send"
+version = "0.1.0"
+description = "Python client for Noria Send: send transactional email and SMS through one internal service instead of wiring a provider into every product."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joseph Gitonga", email = "thekiharani@gmail.com" }]
+keywords = ["email", "sms", "transactional", "ses", "onfon", "noria", "send"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Topic :: Communications :: Telephony",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.28.1"]
+
+[project.urls]
+Homepage = "https://github.com/norialabs/send"
+Source = "https://github.com/norialabs/send"
+Issues = "https://github.com/norialabs/send/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/noria_send", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/noria_send"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/noria_send/py.typed" = "noria_send/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q --tb=short"
+
+[tool.ruff]
+line-length = 110
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

norialabs_send-0.1.0/src/noria_send/__init__.py

@@ -0,0 +1,4 @@
+from noria_send.client import AsyncSend, Send, SendError
+from noria_send.webhooks import verify_webhook
+
+__all__ = ["AsyncSend", "Send", "SendError", "verify_webhook"]

norialabs_send-0.1.0/src/noria_send/client.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Literal, NotRequired, TypedDict
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://send.noria.co.ke"
+RETRYABLE_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+NON_RETRYABLE_CODES = frozenset(
+    {
+        "quota_exceeded",
+        "suppressed_recipient",
+        "domain_not_verified",
+        "sender_not_approved",
+        "message_too_long",
+    }
+)
+
+Json = dict[str, Any]
+Channel = Literal["email", "sms"]
+Reason = Literal["bounce", "complaint", "manual", "unsubscribe"]
+Status = Literal["queued", "sending", "sent", "failed", "canceled"]
+
+
+class Attachment(TypedDict):
+    filename: str
+    content: str
+    content_type: NotRequired[str]
+    content_id: NotRequired[str]
+    disposition: NotRequired[Literal["attachment", "inline"]]
+
+
+class SendEmail(TypedDict):
+    from_: NotRequired[str]
+    to: str | list[str]
+    cc: NotRequired[str | list[str]]
+    bcc: NotRequired[str | list[str]]
+    reply_to: NotRequired[str | list[str]]
+    subject: NotRequired[str]
+    html: NotRequired[str]
+    text: NotRequired[str]
+    template: NotRequired[str]
+    variables: NotRequired[Json]
+    headers: NotRequired[dict[str, str]]
+    tags: NotRequired[dict[str, str]]
+    attachments: NotRequired[list[Attachment]]
+    scheduled_at: NotRequired[str]
+
+
+class SendSms(TypedDict):
+    from_: NotRequired[str]
+    to: str
+    text: NotRequired[str]
+    template: NotRequired[str]
+    variables: NotRequired[Json]
+    tags: NotRequired[dict[str, str]]
+    scheduled_at: NotRequired[str]
+
+
+class SendError(Exception):
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: str,
+        details: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.message = message
+        self.details = details
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return f"SendError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+    @classmethod
+    def from_response(cls, status: int, body: Any) -> SendError:
+        error = body.get("error") if isinstance(body, dict) else None
+        error = error if isinstance(error, dict) else {}
+        return cls(
+            code=error.get("code") or "internal_error",
+            status=status,
+            message=error.get("message") or f"Request failed with status {status}",
+            details=error.get("details"),
+            request_id=error.get("request_id"),
+        )
+
+    @property
+    def suppressed(self) -> bool:
+        return self.code == "suppressed_recipient"
+
+    @property
+    def over_quota(self) -> bool:
+        return self.code in {"quota_exceeded", "rate_limited"}
+
+    @property
+    def retryable(self) -> bool:
+        if self.code in NON_RETRYABLE_CODES:
+            return False
+        return self.status == 0 or self.status in RETRYABLE_STATUSES
+
+
+def _payload(message: SendEmail | SendSms) -> Json:
+    body: Json = {key: value for key, value in message.items() if key != "from_"}
+    if "from_" in message:
+        body["from"] = message["from_"]
+    return body
+
+
+def _query(**parameters: Any) -> Json:
+    return {key: value for key, value in parameters.items() if value not in (None, "")}
+
+
+def _backoff(attempt: int) -> float:
+    return min(2.0, 0.2 * 2 ** (attempt - 1)) * (0.5 + random.random())
+
+
+def _decode(response: httpx.Response) -> Json:
+    if response.status_code == 204 or not response.content:
+        return {}
+    return response.json()
+
+
+class _Namespace:
+    def __init__(self, client: Send | AsyncSend) -> None:
+        self._client = client
+
+
+class Emails(_Namespace):
+    def send(self, email: SendEmail, idempotency_key: str | None = None) -> Any:
+        headers = {"idempotency-key": idempotency_key} if idempotency_key else None
+        return self._client.request("POST", "/v1/emails", _payload(email), headers=headers)
+
+    def send_batch(self, emails: list[SendEmail]) -> Any:
+        return self._client.request("POST", "/v1/emails/batch", {"emails": [_payload(e) for e in emails]})
+
+
+class Sms(_Namespace):
+    def send(self, message: SendSms, idempotency_key: str | None = None) -> Any:
+        headers = {"idempotency-key": idempotency_key} if idempotency_key else None
+        return self._client.request("POST", "/v1/sms", _payload(message), headers=headers)
+
+    def send_batch(self, messages: list[SendSms]) -> Any:
+        return self._client.request("POST", "/v1/sms/batch", {"messages": [_payload(m) for m in messages]})
+
+
+class Messages(_Namespace):
+    def get(self, message_id: str) -> Any:
+        return self._client.request("GET", f"/v1/messages/{quote(message_id)}")
+
+    def list(
+        self,
+        status: Status | None = None,
+        channel: Channel | None = None,
+        to: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
+        return self._client.request(
+            "GET",
+            "/v1/messages",
+            params=_query(status=status, channel=channel, to=to, limit=limit, cursor=cursor),
+        )
+
+    def events(self, message_id: str) -> Any:
+        return self._client.request("GET", f"/v1/messages/{quote(message_id)}/events")
+
+    def cancel(self, message_id: str) -> Any:
+        return self._client.request("POST", f"/v1/messages/{quote(message_id)}/cancel")
+
+    def requeue(self, message_id: str) -> Any:
+        return self._client.request("POST", f"/v1/messages/{quote(message_id)}/requeue")
+
+
+class Domains(_Namespace):
+    def create(self, name: str, custom_return_path: bool = True) -> Any:
+        return self._client.request(
+            "POST", "/v1/domains", {"name": name, "custom_return_path": custom_return_path}
+        )
+
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/domains")
+
+    def get(self, domain_id: str) -> Any:
+        return self._client.request("GET", f"/v1/domains/{quote(domain_id)}")
+
+    def verify(self, domain_id: str) -> Any:
+        return self._client.request("POST", f"/v1/domains/{quote(domain_id)}/verify")
+
+    def remove(self, domain_id: str) -> Any:
+        return self._client.request("DELETE", f"/v1/domains/{quote(domain_id)}")
+
+
+class Senders(_Namespace):
+    def create(self, sender_id: str, channel: Channel = "sms") -> Any:
+        return self._client.request("POST", "/v1/senders", {"sender_id": sender_id, "channel": channel})
+
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/senders")
+
+    def get(self, sender_row_id: str) -> Any:
+        return self._client.request("GET", f"/v1/senders/{quote(sender_row_id)}")
+
+    def remove(self, sender_row_id: str) -> Any:
+        return self._client.request("DELETE", f"/v1/senders/{quote(sender_row_id)}")
+
+
+class Templates(_Namespace):
+    def upsert(
+        self,
+        slug: str,
+        subject: str | None = None,
+        html: str | None = None,
+        text: str | None = None,
+        channel: Channel = "email",
+    ) -> Any:
+        return self._client.request(
+            "POST", "/v1/templates", _query(slug=slug, channel=channel, subject=subject, html=html, text=text)
+        )
+
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/templates")
+
+    def get(self, slug: str, channel: Channel = "email") -> Any:
+        return self._client.request("GET", f"/v1/templates/{quote(slug)}", params={"channel": channel})
+
+    def remove(self, slug: str, channel: Channel = "email") -> Any:
+        return self._client.request("DELETE", f"/v1/templates/{quote(slug)}", params={"channel": channel})
+
+
+class Suppressions(_Namespace):
+    def add(
+        self,
+        destination: str,
+        channel: Channel = "email",
+        reason: Reason = "manual",
+        detail: str | None = None,
+    ) -> Any:
+        return self._client.request(
+            "POST",
+            "/v1/suppressions",
+            _query(destination=destination, channel=channel, reason=reason, detail=detail),
+        )
+
+    def list(self, destination: str | None = None, channel: Channel | None = None) -> Any:
+        return self._client.request(
+            "GET", "/v1/suppressions", params=_query(destination=destination, channel=channel)
+        )
+
+    def remove(self, destination: str, channel: Channel = "email") -> Any:
+        return self._client.request(
+            "DELETE", f"/v1/suppressions/{quote(destination)}", params={"channel": channel}
+        )
+
+
+class Webhooks(_Namespace):
+    def create(self, url: str, event_types: list[str] | None = None, description: str | None = None) -> Any:
+        return self._client.request(
+            "POST",
+            "/v1/webhook-endpoints",
+            _query(url=url, event_types=event_types or [], description=description),
+        )
+
+    def list(self) -> Any:
+        return self._client.request("GET", "/v1/webhook-endpoints")
+
+    def remove(self, endpoint_id: str) -> Any:
+        return self._client.request("DELETE", f"/v1/webhook-endpoints/{quote(endpoint_id)}")
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        retries: int = 2,
+    ) -> None:
+        if not api_key:
+            raise SendError("validation_error", 0, "A Noria Send API key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+
+        self.emails = Emails(self)  # type: ignore[arg-type]
+        self.sms = Sms(self)  # type: ignore[arg-type]
+        self.messages = Messages(self)  # type: ignore[arg-type]
+        self.domains = Domains(self)  # type: ignore[arg-type]
+        self.senders = Senders(self)  # type: ignore[arg-type]
+        self.templates = Templates(self)  # type: ignore[arg-type]
+        self.suppressions = Suppressions(self)  # type: ignore[arg-type]
+        self.webhooks = Webhooks(self)  # type: ignore[arg-type]
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"authorization": f"Bearer {self._api_key}", "accept": "application/json"}
+
+
+class Send(_BaseClient):
+    def __init__(self, *args: Any, transport: httpx.BaseTransport | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.Client(timeout=self._timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Send:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Json | None = None,
+        params: Json | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Json:
+        last: SendError | None = None
+
+        for attempt in range(1, self._retries + 2):
+            if attempt > 1:
+                time.sleep(_backoff(attempt - 1))
+
+            try:
+                response = self._http.request(
+                    method,
+                    f"{self._base_url}{path}",
+                    json=body,
+                    params=params,
+                    headers={**self._headers, **(headers or {})},
+                )
+            except httpx.HTTPError as exception:
+                last = SendError("network_error", 0, str(exception))
+                continue
+
+            if response.is_success:
+                return _decode(response)
+
+            last = SendError.from_response(response.status_code, _decode(response))
+            if not last.retryable:
+                raise last
+
+        raise last or SendError("network_error", 0, "Request failed")
+
+    def is_suppressed(self, destination: str, channel: Channel = "email") -> bool:
+        return bool(self.suppressions.list(destination, channel).get("data"))
+
+
+class AsyncSend(_BaseClient):
+    def __init__(self, *args: Any, transport: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self._timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSend:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Json | None = None,
+        params: Json | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Json:
+        import asyncio
+
+        last: SendError | None = None
+
+        for attempt in range(1, self._retries + 2):
+            if attempt > 1:
+                await asyncio.sleep(_backoff(attempt - 1))
+
+            try:
+                response = await self._http.request(
+                    method,
+                    f"{self._base_url}{path}",
+                    json=body,
+                    params=params,
+                    headers={**self._headers, **(headers or {})},
+                )
+            except httpx.HTTPError as exception:
+                last = SendError("network_error", 0, str(exception))
+                continue
+
+            if response.is_success:
+                return _decode(response)
+
+            last = SendError.from_response(response.status_code, _decode(response))
+            if not last.retryable:
+                raise last
+
+        raise last or SendError("network_error", 0, "Request failed")
+
+    async def is_suppressed(self, destination: str, channel: Channel = "email") -> bool:
+        return bool((await self.suppressions.list(destination, channel)).get("data"))

norialabs_send-0.1.0/src/noria_send/webhooks.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+from noria_send.client import SendError
+
+
+def verify_webhook(
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> dict[str, Any]:
+    timestamp, provided = _parse(signature)
+
+    if abs((now if now is not None else int(time.time())) - timestamp) > tolerance_seconds:
+        raise SendError("validation_error", 400, "Signature timestamp is outside the tolerance window")
+
+    body = payload.decode() if isinstance(payload, bytes) else payload
+    expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
+
+    if not hmac.compare_digest(expected, provided):
+        raise SendError("unauthorized", 401, "Invalid webhook signature")
+
+    event = json.loads(body)
+
+    if not isinstance(event, dict):
+        raise SendError("validation_error", 400, "Webhook payload is not a JSON object")
+
+    return event
+
+
+def _parse(signature: str) -> tuple[int, str]:
+    parts: dict[str, str] = {}
+
+    for pair in signature.split(","):
+        key, _, value = pair.strip().partition("=")
+        if value:
+            parts[key] = value
+
+    timestamp = parts.get("t", "")
+
+    if not timestamp.isdigit() or "v1" not in parts:
+        raise SendError("validation_error", 400, "Malformed Noria-Signature header")
+
+    return int(timestamp), parts["v1"]