goatnotify-core 0.1.0__tar.gz

goatnotify_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+
+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.

goatnotify_core-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: goatnotify-core
+Version: 0.1.0
+Summary: Framework-agnostic core of GoatNotify: notifications, channels, transports and retries.
+Keywords: notifications,email,smtp,webhooks,asyncio,typed
+Author: Louis Midson LAJEANTY
+Author-email: Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/goatlabshq/goatnotify
+Project-URL: Documentation, https://goatlabshq.github.io/goatnotify/
+Project-URL: Issues, https://github.com/goatlabshq/goatnotify/issues
+Description-Content-Type: text/markdown
+
+# goatnotify-core
+
+Framework-agnostic core of GoatNotify: notifications, channels, transports and retries.
+
+```bash
+pip install goatnotify-core
+```
+
+Documentation: <https://goatlabshq.github.io/goatnotify/>

goatnotify_core-0.1.0/README.md

@@ -0,0 +1,9 @@
+# goatnotify-core
+
+Framework-agnostic core of GoatNotify: notifications, channels, transports and retries.
+
+```bash
+pip install goatnotify-core
+```
+
+Documentation: <https://goatlabshq.github.io/goatnotify/>

goatnotify_core-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "goatnotify-core"
+version = "0.1.0"
+description = "Framework-agnostic core of GoatNotify: notifications, channels, transports and retries."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = [
+    "notifications",
+    "email",
+    "smtp",
+    "webhooks",
+    "asyncio",
+    "typed",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Louis Midson LAJEANTY"
+email = "midsonlajeanty@proton.me"
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatnotify"
+Documentation = "https://goatlabshq.github.io/goatnotify/"
+Issues = "https://github.com/goatlabshq/goatnotify/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatnotify.core"

goatnotify_core-0.1.0/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "goatnotify-core"
+version = "0.1.0" # x-release-please-version
+description = "Framework-agnostic core of GoatNotify: notifications, channels, transports and retries."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Louis Midson LAJEANTY", email = "midsonlajeanty@proton.me" }]
+requires-python = ">=3.14"
+keywords = ["notifications", "email", "smtp", "webhooks", "asyncio", "typed"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatnotify"
+Documentation = "https://goatlabshq.github.io/goatnotify/"
+Issues = "https://github.com/goatlabshq/goatnotify/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatnotify.core"

goatnotify_core-0.1.0/src/goatnotify/core/__init__.py

@@ -0,0 +1,86 @@
+from goatnotify.core import events
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.channels.database import (
+    DatabaseChannel,
+    DatabaseMessage,
+    NotificationStore,
+    StoredNotification,
+)
+from goatnotify.core.channels.email import EmailChannel
+from goatnotify.core.channels.webhook import WebhookChannel, WebhookMessage
+from goatnotify.core.errors import (
+    ConfigurationError,
+    DeliveryError,
+    DeliveryFailed,
+    InvalidMessageError,
+    NotificationError,
+    PermanentError,
+    RetryableError,
+    SkipDelivery,
+)
+from goatnotify.core.events import Event, Hook
+from goatnotify.core.http import HttpRequest, HttpResponse, HttpTransport, UrllibTransport
+from goatnotify.core.mail.mailable import Mailable
+from goatnotify.core.mail.mailer import Mailer
+from goatnotify.core.mail.message import Address, Attachment, EmailMessage
+from goatnotify.core.mail.mime import to_mime
+from goatnotify.core.mail.smtp import SmtpTransport
+from goatnotify.core.mail.transport import EmailTransport
+from goatnotify.core.notification import Message, Notifiable, Notification
+from goatnotify.core.notifier import Notifier
+from goatnotify.core.queue import AsyncioQueue, DrainableQueue, NotificationJob, Queue
+from goatnotify.core.results import DeliveryResult, DeliveryStatus, NotificationResult
+from goatnotify.core.retry import NO_RETRY, Backoff, ExponentialBackoff, RetryPolicy
+from goatnotify.core.templates import TemplateRenderer
+
+__all__ = [
+    "NO_RETRY",
+    "Address",
+    "AsyncioQueue",
+    "Attachment",
+    "Backoff",
+    "Channel",
+    "ConfigurationError",
+    "DatabaseChannel",
+    "DatabaseMessage",
+    "DeliveryError",
+    "DeliveryFailed",
+    "DeliveryResult",
+    "DeliveryStatus",
+    "DrainableQueue",
+    "EmailChannel",
+    "EmailMessage",
+    "EmailTransport",
+    "Event",
+    "ExponentialBackoff",
+    "Hook",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpTransport",
+    "InvalidMessageError",
+    "JsonValue",
+    "Mailable",
+    "Mailer",
+    "Message",
+    "Notifiable",
+    "Notification",
+    "NotificationError",
+    "NotificationJob",
+    "NotificationResult",
+    "NotificationStore",
+    "Notifier",
+    "PermanentError",
+    "Queue",
+    "RetryPolicy",
+    "RetryableError",
+    "SkipDelivery",
+    "SmtpTransport",
+    "StoredNotification",
+    "TemplateRenderer",
+    "UrllibTransport",
+    "WebhookChannel",
+    "WebhookMessage",
+    "events",
+    "to_mime",
+]

goatnotify_core-0.1.0/src/goatnotify/core/_json.py

@@ -0,0 +1 @@
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None

goatnotify_core-0.1.0/src/goatnotify/core/channel.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+class Channel[M: Message](ABC):
+    name: str
+    message_type: type[M]
+    retry: RetryPolicy | None = None
+
+    @abstractmethod
+    async def send(self, notifiable: Notifiable, message: M) -> str | None: ...

goatnotify_core-0.1.0/src/goatnotify/core/channels/database.py

@@ -0,0 +1,55 @@
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Protocol
+from uuid import UUID, uuid4
+
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseMessage(Message):
+    kind: str
+    data: Mapping[str, JsonValue]
+
+
+@dataclass(frozen=True, slots=True)
+class StoredNotification:
+    id: UUID
+    kind: str
+    data: Mapping[str, JsonValue]
+    created_at: datetime
+
+
+class NotificationStore(Protocol):
+    async def store(self, notifiable: Notifiable, record: StoredNotification) -> None: ...
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class DatabaseChannel(Channel[DatabaseMessage]):
+    name = "database"
+    message_type = DatabaseMessage
+
+    def __init__(
+        self,
+        store: NotificationStore,
+        *,
+        retry: RetryPolicy | None = None,
+        clock: Callable[[], datetime] = utc_now,
+    ) -> None:
+        self._store = store
+        self._clock = clock
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: DatabaseMessage) -> str | None:
+        record = StoredNotification(
+            id=uuid4(), kind=message.kind, data=message.data, created_at=self._clock()
+        )
+        await self._store.store(notifiable, record)
+        return str(record.id)

goatnotify_core-0.1.0/src/goatnotify/core/channels/email.py

@@ -0,0 +1,23 @@
+from goatnotify.core.channel import Channel
+from goatnotify.core.errors import SkipDelivery
+from goatnotify.core.mail.mailable import Mailable
+from goatnotify.core.mail.mailer import Mailer
+from goatnotify.core.notification import Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+class EmailChannel(Channel[Mailable]):
+    name = "email"
+    message_type = Mailable
+
+    def __init__(self, mailer: Mailer, *, retry: RetryPolicy | None = None) -> None:
+        self._mailer = mailer
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: Mailable) -> str | None:
+        if message.to:
+            return await self._mailer.send(message)
+        route = notifiable.route_notification(self.name)
+        if route is None:
+            raise SkipDelivery(f"{type(notifiable).__qualname__} has no email route")
+        return await self._mailer.send(message, to=[route])

goatnotify_core-0.1.0/src/goatnotify/core/channels/webhook.py

@@ -0,0 +1,104 @@
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Final, Literal
+from urllib.parse import urlsplit
+
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.errors import DeliveryError, PermanentError, RetryableError, SkipDelivery
+from goatnotify.core.http import (
+    HttpRequest,
+    HttpResponse,
+    HttpTransport,
+    UrllibTransport,
+    require_http_url,
+)
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+SIGNATURE_HEADER: Final = "X-GoatNotify-Signature"
+TIMESTAMP_HEADER: Final = "X-GoatNotify-Timestamp"
+MAX_RETRY_AFTER: Final = 300.0
+RETRYABLE_STATUSES: Final = frozenset({408, 429})
+ERROR_BODY_LIMIT: Final = 200
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookMessage(Message):
+    payload: JsonValue
+    url: str | None = None
+    headers: Mapping[str, str] = field(default_factory=dict[str, str])
+    method: Literal["POST", "PUT"] = "POST"
+
+
+class WebhookChannel(Channel[WebhookMessage]):
+    name = "webhook"
+    message_type = WebhookMessage
+
+    def __init__(
+        self,
+        transport: HttpTransport | None = None,
+        *,
+        secret: str | None = None,
+        timeout: float = 10.0,
+        retry: RetryPolicy | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._transport = transport or UrllibTransport()
+        self._secret = secret
+        self._timeout = timeout
+        self._clock = clock
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: WebhookMessage) -> str | None:
+        url = message.url or notifiable.route_notification(self.name)
+        if url is None:
+            raise SkipDelivery(f"{type(notifiable).__qualname__} has no webhook route")
+        require_http_url(url)
+        body = json.dumps(message.payload, separators=(",", ":"), ensure_ascii=False).encode()
+        headers = {"Content-Type": "application/json", **message.headers, **self._sign(body)}
+        host = urlsplit(url).netloc
+        try:
+            response = await self._transport.send(
+                HttpRequest(message.method, url, headers, body, self._timeout)
+            )
+        except DeliveryError:
+            raise
+        # "from None": transport errors often quote the full URL, which may embed a token.
+        except OSError as error:
+            detail = f"Webhook request to {host} failed: {type(error).__name__}"
+            raise RetryableError(detail) from None
+        except Exception as error:
+            detail = f"Webhook request to {host} failed: {type(error).__name__}"
+            raise PermanentError(detail) from None
+        _raise_for_status(response, host)
+        return None
+
+    def _sign(self, body: bytes) -> dict[str, str]:
+        if self._secret is None:
+            return {}
+        timestamp = str(int(self._clock()))
+        digest = hmac.new(
+            self._secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256
+        ).hexdigest()
+        return {TIMESTAMP_HEADER: timestamp, SIGNATURE_HEADER: f"sha256={digest}"}
+
+
+def _raise_for_status(response: HttpResponse, host: str) -> None:
+    if 200 <= response.status < 300:
+        return
+    detail = f"Webhook {host} answered {response.status}: {response.body[:ERROR_BODY_LIMIT]!r}"
+    if response.status in RETRYABLE_STATUSES or response.status >= 500:
+        raise RetryableError(detail, retry_after=_retry_after(response))
+    raise PermanentError(detail)
+
+
+def _retry_after(response: HttpResponse) -> float | None:
+    value = (response.header("Retry-After") or "").strip()
+    if not (value.isascii() and value.isdecimal()):
+        return None
+    return min(float(value), MAX_RETRY_AFTER)

goatnotify_core-0.1.0/src/goatnotify/core/errors.py

@@ -0,0 +1,47 @@
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from goatnotify.core.results import NotificationResult
+
+
+class NotificationError(Exception):
+    pass
+
+
+class ConfigurationError(NotificationError):
+    pass
+
+
+class DeliveryError(NotificationError):
+    pass
+
+
+class RetryableError(DeliveryError):
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class PermanentError(DeliveryError):
+    pass
+
+
+class InvalidMessageError(PermanentError):
+    pass
+
+
+class SkipDelivery(DeliveryError):  # noqa: N818 (a control-flow signal, not an error)
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class DeliveryFailed(ExceptionGroup[Exception]):
+    result: NotificationResult
+
+    @classmethod
+    def from_result(cls, result: NotificationResult) -> Self:
+        errors = [delivery.error for delivery in result.deliveries if delivery.error is not None]
+        group = cls(f"{len(errors)} of {len(result.deliveries)} deliveries failed", errors)
+        group.result = result
+        return group

goatnotify_core-0.1.0/src/goatnotify/core/events.py

@@ -0,0 +1,51 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal
+from uuid import UUID
+
+from goatnotify.core.errors import RetryableError
+from goatnotify.core.notification import Message, Notifiable, Notification
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _DeliveryEvent:
+    notification_id: UUID
+    notification: Notification[Any]
+    notifiable: Notifiable
+    channel: str
+    message: Message
+    attempt: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Sending(_DeliveryEvent):
+    name: ClassVar[Literal["notification.sending"]] = "notification.sending"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Retrying(_DeliveryEvent):
+    name: ClassVar[Literal["notification.retrying"]] = "notification.retrying"
+    delay: float
+    error: RetryableError
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Sent(_DeliveryEvent):
+    name: ClassVar[Literal["notification.sent"]] = "notification.sent"
+    provider_id: str | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Failed(_DeliveryEvent):
+    name: ClassVar[Literal["notification.failed"]] = "notification.failed"
+    error: Exception
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Skipped(_DeliveryEvent):
+    name: ClassVar[Literal["notification.skipped"]] = "notification.skipped"
+    reason: str
+
+
+type Event = Sending | Retrying | Sent | Failed | Skipped
+type Hook = Callable[[Event], Awaitable[None] | None]

goatnotify_core-0.1.0/src/goatnotify/core/http.py

@@ -0,0 +1,102 @@
+import asyncio
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from email.message import Message
+from importlib.metadata import PackageNotFoundError, version
+from typing import IO, Protocol, override
+from urllib.parse import urlsplit
+
+from goatnotify.core.errors import InvalidMessageError
+
+
+def _distribution_version() -> str:
+    try:
+        return version("goatnotify-core")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+USER_AGENT = f"goatnotify/{_distribution_version()}"
+ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+def require_http_url(url: str) -> None:
+    parts = urlsplit(url)
+    if parts.scheme not in ALLOWED_SCHEMES or not parts.netloc:
+        raise InvalidMessageError("Only absolute http and https URLs are allowed")
+    if not url.isascii() or not url.isprintable() or " " in url:
+        raise InvalidMessageError("URLs must be percent-encoded ASCII without spaces")
+
+
+@dataclass(frozen=True, slots=True)
+class HttpRequest:
+    method: str
+    url: str
+    headers: Mapping[str, str]
+    body: bytes
+    timeout: float
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    def header(self, name: str) -> str | None:
+        wanted = name.lower()
+        return next((v for k, v in self.headers.items() if k.lower() == wanted), None)
+
+
+class HttpTransport(Protocol):
+    async def send(self, request: HttpRequest) -> HttpResponse: ...
+
+
+def _with_user_agent(headers: Mapping[str, str]) -> dict[str, str]:
+    # urllib's default "Python-urllib" agent is rejected by some bot-protected endpoints.
+    if any(name.lower() == "user-agent" for name in headers):
+        return dict(headers)
+    return {**headers, "User-Agent": USER_AGENT}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # urllib would replay a POST as a bodiless GET and forward signature headers to any host.
+    @override
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: IO[bytes],
+        code: int,
+        msg: str,
+        headers: Message,
+        newurl: str,
+    ) -> None:
+        return None
+
+
+class UrllibTransport:
+    def __init__(self) -> None:
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    async def send(self, request: HttpRequest) -> HttpResponse:
+        require_http_url(request.url)
+        return await asyncio.to_thread(self._send, request)
+
+    def _send(self, request: HttpRequest) -> HttpResponse:
+        prepared = urllib.request.Request(  # noqa: S310 (scheme checked by require_http_url)
+            request.url,
+            data=request.body,
+            headers=_with_user_agent(request.headers),
+            method=request.method,
+        )
+        try:
+            # Safe: send() has already restricted the URL to http and https.
+            with self._opener.open(prepared, timeout=request.timeout) as response:  # nosemgrep
+                return HttpResponse(
+                    response.status, dict(response.headers.items()), response.read()
+                )
+        except urllib.error.HTTPError as error:
+            with error:
+                return HttpResponse(error.code, dict(error.headers.items()), error.read())

goatnotify_core-0.1.0/src/goatnotify/core/mail/mailable.py

@@ -0,0 +1,36 @@
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+
+from goatnotify.core.mail.message import AddressLike, Attachment
+from goatnotify.core.notification import Message
+
+_EMPTY: MappingProxyType[str, str] = MappingProxyType({})
+
+
+class Mailable(Message):
+    subject: str = ""
+    sender: AddressLike | None = None
+    to: Sequence[AddressLike] = ()
+    cc: Sequence[AddressLike] = ()
+    bcc: Sequence[AddressLike] = ()
+    reply_to: Sequence[AddressLike] = ()
+    headers: Mapping[str, str] = _EMPTY
+    metadata: Mapping[str, str] = _EMPTY
+
+    def attachments(self) -> Sequence[Attachment]:
+        return ()
+
+    def html(self) -> str | None:
+        return None
+
+    def text(self) -> str | None:
+        return None
+
+    def template(self) -> str | None:
+        return None
+
+    def text_template(self) -> str | None:
+        return None
+
+    def context(self) -> Mapping[str, object]:
+        return _EMPTY