codex-platform 0.1.0__py3-none-any.whl

codex_platform/__init__.py

@@ -0,0 +1 @@
+"""codex-platform: Infrastructure, background tasks (ARQ), and framework adapters."""

codex_platform/notifications/__init__.py

@@ -0,0 +1,48 @@
+"""
+codex_platform.notifications
+=============================
+Building blocks for notification delivery.
+
+    # Contracts / DTOs
+    from codex_platform.notifications import NotificationPayloadDTO, NotificationRecipient
+    from codex_platform.notifications import NotificationChannel
+
+    # Channel pipeline
+    from codex_platform.notifications import AsyncEmailClient
+    from codex_platform.notifications import BaseDeliveryOrchestrator, ChannelRegistry
+
+    # Delivery adapters (how payload gets to the pipeline)
+    from codex_platform.notifications.delivery import ArqNotificationAdapter
+    from codex_platform.notifications.delivery import DirectNotificationAdapter
+
+    # Template rendering (requires jinja2 — install separately)
+    from codex_platform.notifications.renderer import TemplateRenderer
+"""
+
+from .channels import NotificationChannel
+from .clients.smtp import AsyncEmailClient
+from .delivery import ArqNotificationAdapter, DirectNotificationAdapter, NotificationAdapter
+from .dto import NotificationPayloadDTO, NotificationRecipient, RenderedNotificationDTO, TemplateNotificationDTO
+from .interfaces import ContentCacheAdapter, ContentProvider
+from .orchestrator import BaseDeliveryOrchestrator, DeliveryChannel
+from .registry import ChannelRegistry
+
+__all__ = [
+    # Contracts
+    "NotificationChannel",
+    "NotificationPayloadDTO",
+    "TemplateNotificationDTO",
+    "RenderedNotificationDTO",
+    "NotificationRecipient",
+    "ContentProvider",
+    "ContentCacheAdapter",
+    "DeliveryChannel",
+    # Channel pipeline
+    "AsyncEmailClient",
+    "BaseDeliveryOrchestrator",
+    "ChannelRegistry",
+    # Delivery adapters
+    "NotificationAdapter",
+    "ArqNotificationAdapter",
+    "DirectNotificationAdapter",
+]

codex_platform/notifications/channels.py

@@ -0,0 +1,24 @@
+"""
+codex_platform.notifications.channels
+=======================================
+Enum of supported notification delivery channels.
+"""
+
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    # Fallback for Python 3.10
+    class StrEnum(str, Enum):
+        pass
+
+
+class NotificationChannel(StrEnum):
+    """Supported notification delivery channel identifiers."""
+
+    EMAIL = "email"
+    TELEGRAM = "telegram"
+    SMS = "sms"
+    WHATSAPP = "whatsapp"

codex_platform/notifications/clients/__init__.py

@@ -0,0 +1,3 @@
+from .smtp import AsyncEmailClient
+
+__all__ = ["AsyncEmailClient"]

codex_platform/notifications/clients/smtp.py

@@ -0,0 +1,134 @@
+"""
+codex_platform.workers.notifications.email
+========================================
+Async SMTP email client — implements ``DeliveryChannel``.
+
+Creates persistent SMTP connection config at init time.
+For multi-tenant: create separate instances with different settings.
+
+Requires: pip install codex-tools[notifications]
+"""
+
+import logging
+from email.message import EmailMessage
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+try:
+    import aiosmtplib
+
+    _AIOSMTP_AVAILABLE = True
+except ImportError as e:
+    if e.name == "aiosmtplib":
+        _AIOSMTP_AVAILABLE = False
+    else:
+        raise
+
+
+class AsyncEmailClient:
+    """
+    Async SMTP email sender. Implements ``DeliveryChannel``.
+
+    Usage:
+        client = AsyncEmailClient(
+            smtp_host="mail.example.com", smtp_port=465,
+            smtp_user="user", smtp_password="pass",  # pragma: allowlist secret
+            smtp_from_email="noreply@example.com",
+        )
+        success = await client.send(
+            to="user@example.com",
+            subject="Hello",
+            html_content="<b>Hi</b>",
+            text_content="Hi",
+        )
+    """
+
+    def __init__(
+        self,
+        smtp_host: str,
+        smtp_port: int,
+        smtp_user: str | None = None,
+        smtp_password: str | None = None,  # pragma: allowlist secret
+        smtp_from_email: str | None = None,
+        smtp_use_tls: bool = False,
+    ) -> None:
+        self.smtp_host = smtp_host
+        self.smtp_port = smtp_port
+        self.smtp_user = smtp_user
+        self.smtp_password = smtp_password
+        self.smtp_from_email = smtp_from_email
+        self.smtp_use_tls = smtp_use_tls
+
+    def is_available(self) -> bool:
+        """Returns True if the client is configured (non-localhost host)."""
+        return bool(self.smtp_host and self.smtp_host != "localhost")
+
+    async def send(
+        self,
+        to: str,
+        subject: str,
+        html_content: str | None,
+        text_content: str | None,
+        timeout: int = 15,
+    ) -> bool:
+        """
+        Send email via SMTP.
+
+        Args:
+            to: Recipient email address.
+            subject: Email subject line.
+            html_content: HTML body (preferred). Used as HTML part.
+            text_content: Plain-text body (fallback for HTML-disabled clients).
+                          If None and html_content is provided, a generic fallback
+                          is used.
+            timeout: SMTP connection timeout in seconds.
+
+        Returns:
+            True on success.
+
+        Raises:
+            RuntimeError: If aiosmtplib is not installed.
+            aiosmtplib.SMTPException: On SMTP delivery failure.
+        """
+        if not _AIOSMTP_AVAILABLE:
+            raise RuntimeError("aiosmtplib not installed. Run: pip install codex-tools[notifications]")
+        await self._send_smtp(to, subject, html_content, text_content, timeout)
+        log.info("AsyncEmailClient | sent to='%s'", to)
+        return True
+
+    async def _send_smtp(
+        self,
+        to: str,
+        subject: str,
+        html_content: str | None,
+        text_content: str | None,
+        timeout: int,
+    ) -> None:
+        message = EmailMessage()
+        message["From"] = self.smtp_from_email
+        message["To"] = to
+        message["Subject"] = subject
+
+        plain = text_content or "Please enable HTML to view this email."
+        message.set_content(plain)
+
+        if html_content:
+            message.add_alternative(html_content, subtype="html")
+
+        use_ssl = self.smtp_port == 465
+        start_tls = self.smtp_port == 587 or (self.smtp_use_tls and self.smtp_port != 465)
+
+        send_kwargs: dict[str, Any] = {
+            "hostname": self.smtp_host,
+            "port": self.smtp_port,
+            "use_tls": use_ssl,
+            "start_tls": start_tls,
+            "timeout": timeout,
+        }
+
+        if self.smtp_user and self.smtp_password:
+            send_kwargs["username"] = self.smtp_user
+            send_kwargs["password"] = self.smtp_password
+
+        await aiosmtplib.send(message, **send_kwargs)

codex_platform/notifications/delivery/__init__.py

@@ -0,0 +1,18 @@
+"""
+codex_platform.notifications.delivery
+=======================================
+Delivery adapters — the "how" of getting a notification to its destination.
+
+  - ``ArqNotificationAdapter``    → enqueues into Redis/ARQ queue
+  - ``DirectNotificationAdapter`` → delivers in-process (sync, no broker)
+"""
+
+from .arq import ArqNotificationAdapter
+from .base import NotificationAdapter
+from .direct import DirectNotificationAdapter
+
+__all__ = [
+    "NotificationAdapter",
+    "ArqNotificationAdapter",
+    "DirectNotificationAdapter",
+]

codex_platform/notifications/delivery/arq.py

@@ -0,0 +1,69 @@
+"""
+codex_platform.notifications.delivery.arq
+==========================================
+ARQ delivery adapter — enqueues notification tasks into Redis/ARQ queue.
+
+Example::
+
+    from arq.connections import create_pool, RedisSettings
+    from codex_platform.notifications.delivery.arq import ArqNotificationAdapter
+
+    pool = await create_pool(RedisSettings())
+    adapter = ArqNotificationAdapter(pool)
+
+    # Async context (preferred):
+    job_id = await adapter.enqueue_async("send_notification_task", payload)
+
+    # Sync context:
+    job_id = adapter.enqueue("send_notification_task", payload)
+"""
+
+import logging
+from typing import Any
+
+from arq.connections import ArqRedis
+
+from .base import NotificationAdapter
+
+log = logging.getLogger(__name__)
+
+
+class ArqNotificationAdapter(NotificationAdapter):
+    """
+    Notification adapter that enqueues tasks into an ARQ/Redis queue.
+
+    Args:
+        pool: ``ArqRedis`` connection pool from ``arq.connections.create_pool``.
+
+    Raises on infrastructure failures (Redis unavailable, serialization errors).
+    """
+
+    def __init__(self, pool: ArqRedis) -> None:
+        self.pool = pool
+
+    def enqueue(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """Sync enqueue — wraps async via asyncio. Use enqueue_async in async contexts."""
+        import asyncio
+
+        return asyncio.get_event_loop().run_until_complete(self.enqueue_async(task_name, payload))
+
+    async def enqueue_async(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """
+        Enqueue a notification task into the ARQ queue (async).
+
+        Args:
+            task_name: ARQ worker function name (e.g. ``'send_notification_task'``).
+            payload:   Serialized ``NotificationPayloadDTO``.
+
+        Returns:
+            Job ID string, or None if ARQ returned no handle.
+
+        Raises:
+            ConnectionError: Redis is unreachable.
+            Exception: Any ARQ/Redis infrastructure failure.
+        """
+        log.debug("ArqNotificationAdapter | enqueueing task=%s", task_name)
+        job = await self.pool.enqueue_job(task_name, payload_dict=payload)
+        job_id = getattr(job, "job_id", None)
+        log.info("ArqNotificationAdapter | task=%s job_id=%s", task_name, job_id)
+        return job_id

codex_platform/notifications/delivery/base.py

@@ -0,0 +1,39 @@
+"""
+codex_platform.notifications.delivery.base
+==========================================
+Protocol definition for notification delivery adapters.
+"""
+
+from typing import Any, Protocol
+
+
+class NotificationAdapter(Protocol):
+    """
+    Contract for notification delivery transport.
+
+    Allows the same business logic to work with ARQ, Celery, Direct calls,
+    or Django's built-in mail system.
+
+    Implementations MUST:
+        - Raise exceptions on infrastructure failures (network, broker, DB).
+        - Return a job/task ID (str) when the backend provides one.
+        - Return None for fire-and-forget transports with no tracking ID.
+    """
+
+    def enqueue(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """
+        Deliver or enqueue the notification.
+
+        Args:
+            task_name: Worker function name to execute.
+                       May be unused by adapters that deliver synchronously.
+            payload: Serialized ``NotificationPayloadDTO`` (via ``.model_dump(mode="json")``).
+
+        Returns:
+            str: Job/task identifier for tracking.
+            None: When the transport is fire-and-forget.
+
+        Raises:
+            Exception: Infrastructure errors MUST propagate — never swallow them.
+        """
+        ...

codex_platform/notifications/delivery/direct.py

@@ -0,0 +1,89 @@
+"""
+codex_platform.notifications.delivery.direct
+=============================================
+Direct delivery adapter — delivers notifications synchronously in-process.
+
+Uses the full channel pipeline (ChannelRegistry → BaseDeliveryOrchestrator)
+without a message broker.
+
+.. warning::
+
+    Calls ``asyncio.run()`` — MUST NOT be used inside a running event loop
+    (ASGI views, async handlers). Use ``ArqNotificationAdapter`` instead.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from .base import NotificationAdapter
+
+log = logging.getLogger(__name__)
+
+
+class DirectNotificationAdapter(NotificationAdapter):
+    """
+    Adapter for synchronous/monolithic notification delivery.
+
+    Injects a pre-built list of channels (via ``ChannelRegistry``) into
+    ``BaseDeliveryOrchestrator`` and runs the async pipeline synchronously.
+
+    Uses lazy imports to avoid circular dependencies.
+    """
+
+    def __init__(self, config: Any) -> None:
+        self.config = config
+
+    def enqueue(self, _task_name: str, payload: dict[str, Any]) -> str | None:
+        """
+        Deliver a notification synchronously via the orchestrator pipeline.
+
+        Args:
+            _task_name: Unused — direct delivery runs in-process.
+            payload:    Serialized ``NotificationPayloadDTO``.
+
+        Returns:
+            ``notification_id`` from payload on success, None if not present.
+
+        Raises:
+            RuntimeError: If called from within a running event loop.
+            Exception: Channel infrastructure failures propagate upward.
+        """
+        from codex_platform.notifications.dto import NotificationPayloadDTO
+        from codex_platform.notifications.orchestrator import BaseDeliveryOrchestrator
+        from codex_platform.notifications.registry import ChannelRegistry
+
+        log.debug("DirectNotificationAdapter | starting direct delivery")
+
+        registry = ChannelRegistry()
+        _register_default_channels(registry, self.config)
+        channels = registry.build_channels(self.config)
+        orchestrator = BaseDeliveryOrchestrator(channels=channels)
+
+        payload_dto = NotificationPayloadDTO(**payload)
+        asyncio.run(orchestrator.deliver(payload_dto))
+
+        notification_id = payload.get("notification_id")
+        log.info("DirectNotificationAdapter | delivered notification_id=%s", notification_id)
+        return notification_id
+
+
+def _register_default_channels(registry: Any, config: Any) -> None:
+    """Register default delivery channels from config. Override by calling registry.register() directly."""
+    try:
+        from codex_platform.notifications.clients.smtp import AsyncEmailClient
+
+        smtp_host = getattr(config, "SMTP_HOST", "")
+        if smtp_host:
+            registry.register(
+                "smtp",
+                lambda cfg: AsyncEmailClient(
+                    smtp_host=getattr(cfg, "SMTP_HOST", ""),
+                    smtp_port=getattr(cfg, "SMTP_PORT", 587),
+                    smtp_user=getattr(cfg, "SMTP_USER", None),
+                    smtp_password=getattr(cfg, "SMTP_PASSWORD", None),
+                    smtp_from_email=getattr(cfg, "SMTP_FROM_EMAIL", None),
+                ),
+            )
+    except ImportError:
+        pass

codex_platform/notifications/dto.py

@@ -0,0 +1,63 @@
+"""
+codex_platform.notifications.dto
+==================================
+Notification payload contracts.
+
+Three classes:
+
+  NotificationPayloadDTO     — base, always required fields
+  TemplateNotificationDTO    — Mode 1: workers fetches context from Redis, renders template
+  RenderedNotificationDTO    — Mode 2: pre-rendered HTML (e.g. from Django)
+"""
+
+from __future__ import annotations
+
+from codex_core.core import BaseDTO
+
+from .channels import NotificationChannel
+
+
+class NotificationRecipient(BaseDTO):  # type: ignore[misc]
+    """Recipient info. PII fields auto-masked in __repr__ via BaseDTO."""
+
+    email: str | None = None
+    phone: str | None = None
+
+
+class NotificationPayloadDTO(BaseDTO):  # type: ignore[misc]
+    """
+    Base notification payload — identification and routing only.
+
+    Do not use directly. Use TemplateNotificationDTO or RenderedNotificationDTO.
+    """
+
+    notification_id: str
+    recipient: NotificationRecipient
+    channels: list[NotificationChannel] = [NotificationChannel.EMAIL]
+    event_type: str | None = None
+    subject: str | None = None
+
+
+class TemplateNotificationDTO(NotificationPayloadDTO):
+    """
+    Mode 1 — Worker renders the template itself (requires Jinja2).
+
+    context_key: Redis key where context_data is stored (JSON).
+                 Allows updating data after enqueue (e.g. reschedule).
+    template_name: Relative template path (e.g. 'booking/bk_confirmation.html').
+    """
+
+    template_name: str
+    context_key: str
+
+
+class RenderedNotificationDTO(NotificationPayloadDTO):
+    """
+    Mode 2 — Pre-rendered HTML passed directly to the workers.
+
+    Use when Django (or another layer) renders the template
+    and the workers only needs to deliver.
+    """
+
+    html_content: str
+    text_content: str | None = None

codex_platform/notifications/interfaces.py

@@ -0,0 +1,30 @@
+"""
+codex_platform.core.interfaces
+============================
+Protocol contracts for core adapters.
+The library core relies only on these interfaces, not on concrete ORM models.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ContentProvider(Protocol):
+    """Provides translated template text by key."""
+
+    def get_text(self, key: str) -> str | None:
+        """Return translated text or None if not found."""
+        ...
+
+
+class ContentCacheAdapter(Protocol):
+    """Adapter for caching email/notification content (used by BaseEmailContentSelector)."""
+
+    def get_cached_value(self, key: str) -> str | None:
+        """Return cached string value or None if not found."""
+        ...
+
+    def set_cached_value(self, key: str, value: str, timeout: int) -> None:
+        """Store value in cache with given timeout (seconds)."""
+        ...

codex_platform/notifications/orchestrator.py

@@ -0,0 +1,116 @@
+"""
+codex_platform.workers.notifications.orchestrator
+===============================================
+Fallback delivery orchestrator.
+Tries channels in order; stops on first success.
+
+Usage:
+    registry = ChannelRegistry()
+    registry.register("smtp", lambda cfg: AsyncEmailClient(...))
+    channels = registry.build_channels(settings)
+
+    orchestrator = BaseDeliveryOrchestrator(channels=channels)
+    success = await orchestrator.deliver(payload_dto)
+"""
+
+import logging
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from codex_platform.notifications.dto import NotificationPayloadDTO
+
+log = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class DeliveryChannel(Protocol):
+    """
+    Contract for a single delivery method.
+
+    Implementors: AsyncEmailClient, DjangoMailChannel, TelegramChannel, etc.
+    """
+
+    async def send(
+        self,
+        to: str,
+        subject: str,
+        html_content: str | None,
+        text_content: str | None,
+    ) -> bool:
+        """
+        Attempt delivery. Return True on success, False on logical failure.
+        Raise on infrastructure errors (so the orchestrator can log and try next channel).
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """Return True if this channel is properly configured and ready."""
+        ...
+
+
+class BaseDeliveryOrchestrator:
+    """
+    Tries channels in order; stops on first success.
+
+    Channels are injected at construction time via Dependency Injection.
+    ``deliver()`` is a pure send operation with no side effects beyond delivery.
+    """
+
+    def __init__(self, channels: list[DeliveryChannel]) -> None:
+        """
+        Args:
+            channels: Ordered list of delivery channels to try.
+                      Use ``ChannelRegistry.build_channels()`` to build this list.
+        """
+        self.channels = channels
+
+    async def deliver(self, payload: "NotificationPayloadDTO") -> bool:
+        """
+        Deliver a notification payload through available channels.
+
+        Tries each channel in order; stops on first success.
+        If a channel raises, logs the exception and falls through to the next.
+
+        Args:
+            payload: ``NotificationPayloadDTO`` with ready-made html/text content.
+
+        Returns:
+            True if at least one channel succeeded, False if all exhausted.
+        """
+        to = payload.recipient.email or payload.recipient.phone or ""
+        subject = payload.subject or ""
+
+        if not to:
+            log.error(
+                "DeliveryOrchestrator | no recipient address, notification_id=%s",
+                payload.notification_id,
+            )
+            return False
+
+        for channel in self.channels:
+            if not channel.is_available():
+                continue
+            try:
+                if await channel.send(
+                    to=to,
+                    subject=subject,
+                    html_content=getattr(payload, "html_content", None),
+                    text_content=getattr(payload, "text_content", None),
+                ):
+                    log.info(
+                        "DeliveryOrchestrator | delivered via %s, notification_id=%s",
+                        type(channel).__name__,
+                        payload.notification_id,
+                    )
+                    return True
+            except Exception:
+                log.exception(
+                    "DeliveryOrchestrator | channel=%s failed, trying next",
+                    type(channel).__name__,
+                )
+
+        log.error(
+            "DeliveryOrchestrator | all channels exhausted, notification_id=%s",
+            payload.notification_id,
+        )
+        return False