notifyfork 0.1.2__py3-none-any.whl

notifyfork/core/infrastructure/providers/smtp_provider.py

@@ -0,0 +1,65 @@
+import logging
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+from notifyfork.core.application.interfaces.notification_provider import NotificationProvider, ProviderResult
+from notifyfork.core.domain.entities.notification import NotificationChannel
+from notifyfork.core.domain.value_objects.template import NotificationTemplate
+
+logger = logging.getLogger(__name__)
+
+
+class SMTPEmailProvider(NotificationProvider):
+    """
+    Generic SMTP email provider — renders templates locally.
+
+    Always LOCAL mode. Body is HTML rendered here before sending.
+    For external template rendering (SendGrid, Mailgun), use their
+    dedicated providers instead.
+    """
+
+    def __init__(self, host: str, port: int, username: str, password: str, from_email: str) -> None:
+        self._host = host
+        self._port = port
+        self._username = username
+        self._password = password
+        self._from_email = from_email
+
+    @property
+    def name(self) -> str:
+        return "smtp_email"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "email" — generic, eligible for fallback to sendgrid_email/resend_email.
+        # "smtp_email" (== self.name) — pins this exact vendor.
+        return [NotificationChannel.EMAIL, self.name]
+
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        body = template.render(context)
+        subject = template.render_subject(context) or "(no subject)"
+
+        try:
+            msg = MIMEMultipart("alternative")
+            msg["Subject"] = subject
+            msg["From"] = self._from_email
+            msg["To"] = recipient
+            msg.attach(MIMEText(body, "html"))
+
+            with smtplib.SMTP_SSL(self._host, self._port) as server:
+                server.login(self._username, self._password)
+                server.sendmail(self._from_email, recipient, msg.as_string())
+
+            logger.info("Email sent via SMTP", extra={"to": recipient, "subject": subject})
+            return ProviderResult(success=True, provider_name=self.name)
+
+        except smtplib.SMTPException as e:
+            logger.error("SMTP error", extra={"error": str(e)})
+            return ProviderResult(success=False, provider_name=self.name, error=str(e))

notifyfork/core/infrastructure/providers/twilio_provider.py

@@ -0,0 +1,57 @@
+import logging
+from typing import Any
+
+from twilio.rest import Client
+from twilio.base.exceptions import TwilioRestException
+
+from notifyfork.core.application.interfaces.notification_provider import NotificationProvider, ProviderResult
+from notifyfork.core.domain.entities.notification import NotificationChannel
+from notifyfork.core.domain.value_objects.template import NotificationTemplate, TemplateMode
+
+logger = logging.getLogger(__name__)
+
+
+class TwilioSMSProvider(NotificationProvider):
+    """
+    Twilio SMS provider.
+
+    LOCAL mode  — sends free-form text. Body is rendered locally.
+    EXTERNAL mode — not applicable for SMS (no template system).
+    """
+
+    def __init__(self, account_sid: str, auth_token: str, from_number: str) -> None:
+        self._client = Client(account_sid, auth_token)
+        self._from_number = from_number
+
+    @property
+    def name(self) -> str:
+        return "twilio_sms"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "sms" — generic, eligible for fallback if another SMS provider is
+        # registered. "twilio_sms" (== self.name) — pins this exact vendor.
+        return [NotificationChannel.SMS, self.name]
+
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        body = template.render(context)
+
+        try:
+            message = self._client.messages.create(
+                body=body,
+                from_=self._from_number,
+                to=recipient,
+            )
+            logger.info("SMS sent", extra={"sid": message.sid, "to": recipient[:6] + "***"})
+            return ProviderResult(success=True, provider_name=self.name, external_id=message.sid)
+
+        except TwilioRestException as e:
+            logger.error("Twilio SMS error", extra={"code": e.code, "msg": e.msg})
+            return ProviderResult(
+                success=False, provider_name=self.name, error=f"Twilio [{e.code}]: {e.msg}"
+            )

notifyfork/core/infrastructure/providers/whatsapp_provider.py

@@ -0,0 +1,135 @@
+import logging
+from typing import Any
+
+from twilio.rest import Client
+from twilio.base.exceptions import TwilioRestException
+
+from notifyfork.core.application.interfaces.notification_provider import NotificationProvider, ProviderResult
+from notifyfork.core.domain.entities.notification import NotificationChannel
+from notifyfork.core.domain.value_objects.template import NotificationTemplate, TemplateMode
+
+logger = logging.getLogger(__name__)
+
+# Current WhatsApp vendor: Twilio (via the official `twilio` SDK, hence no
+# hardcoded _API_URL like sendgrid_provider.py — the SDK's Client resolves
+# https://api.twilio.com internally).
+#
+# This is the only WhatsApp provider today, but not the only one planned —
+# e.g. Evolution API is a likely next candidate. Follow the SendGrid/SMTP
+# pattern for that: a new file (evolution_provider.py) with its own
+# EvolutionWhatsAppProvider class, registered for the same
+# NotificationChannel.WHATSAPP, ordered/failed-over via
+# NOTIFYFORK_PROVIDER_ORDER — not a branch inside this class.
+
+
+class TwilioWhatsAppProvider(NotificationProvider):
+    """
+    WhatsApp via Twilio.
+
+    LOCAL mode — sandbox/dev only. Sends free-form text.
+    EXTERNAL mode — production. Uses Meta-approved template SID + mapped variables.
+
+    channel="whatsapp" stays generic even with a second provider (e.g. a future
+    Evolution API integration) registered for the same NotificationChannel.WHATSAPP —
+    same pattern as SendGrid/SMTP on channel="email". But that automatic fallback is
+    only safe for LOCAL-mode templates. A template in EXTERNAL mode here holds a
+    Twilio Content SID, which only this provider understands — a LOCAL-only WhatsApp
+    provider (like SMTP is for email) can't fall back to it. Keep EXTERNAL templates
+    provider-specific; don't rely on channel fallback across template modes.
+
+    Twilio WhatsApp external templates use positional variables: "1", "2", "3"...
+    Use VariableMapping to translate your semantic context to positional keys:
+
+        VariableMapping({"name": "1", "code": "2"})
+
+    So context {"name": "Mario", "code": "847291"} becomes {"1": "Mario", "2": "847291"}
+    which is what Twilio's ContentTemplate API expects.
+    """
+
+    def __init__(self, account_sid: str, auth_token: str, from_number: str) -> None:
+        self._client = Client(account_sid, auth_token)
+        self._from_number = (
+            from_number if from_number.startswith("whatsapp:") else f"whatsapp:{from_number}"
+        )
+
+    @property
+    def name(self) -> str:
+        return "twilio_whatsapp"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "whatsapp" — generic, eligible for automatic fallback if another
+        # WhatsApp provider (e.g. Evolution) is registered later.
+        # "twilio_whatsapp" (== self.name) — pins this exact vendor, no fallback.
+        return [NotificationChannel.WHATSAPP, self.name]
+
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        to = recipient if recipient.startswith("whatsapp:") else f"whatsapp:{recipient}"
+
+        if template.mode == TemplateMode.EXTERNAL:
+            return await self._send_external(to, template, context)
+        return await self._send_local(to, template, context)
+
+    async def _send_external(
+        self,
+        to: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        """
+        Sends using a Meta-approved Twilio Content Template.
+        Variables are translated via VariableMapping before dispatch.
+        """
+        translated = template.translate_variables(context)
+
+        logger.info(
+            "Sending WhatsApp via external template",
+            extra={
+                "template_sid": template.external_template_id,
+                "to": to[:12] + "***",
+                "variables": list(translated.keys()),
+            },
+        )
+
+        try:
+            message = self._client.messages.create(
+                content_sid=template.external_template_id,
+                content_variables=str(translated),  # Twilio expects JSON string
+                from_=self._from_number,
+                to=to,
+            )
+            return ProviderResult(
+                success=True, provider_name=self.name, external_id=message.sid
+            )
+        except TwilioRestException as e:
+            logger.error("WhatsApp external template error", extra={"code": e.code, "msg": e.msg})
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=f"Twilio WhatsApp [{e.code}]: {e.msg}",
+            )
+
+    async def _send_local(
+        self,
+        to: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        """Free-form message — only valid in sandbox/dev."""
+        body = template.render(context)
+        try:
+            message = self._client.messages.create(body=body, from_=self._from_number, to=to)
+            return ProviderResult(
+                success=True, provider_name=self.name, external_id=message.sid
+            )
+        except TwilioRestException as e:
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=f"Twilio WhatsApp [{e.code}]: {e.msg}",
+            )

notifyfork/core/infrastructure/queue/tasks.py

@@ -0,0 +1,82 @@
+import logging
+from uuid import UUID
+
+from celery import shared_task
+from celery.utils.log import get_task_logger
+
+logger = get_task_logger(__name__)
+
+
+@shared_task(
+    bind=True,
+    max_retries=3,
+    default_retry_delay=60,        # 1 min first retry
+    retry_backoff=True,            # exponential: 1m, 2m, 4m
+    retry_backoff_max=600,         # cap at 10 minutes
+    acks_late=True,                # only ack after task completes — safe on worker crash
+    reject_on_worker_lost=True,
+)
+def dispatch_notification(self, payload: dict) -> dict:
+    """
+    Celery task that drives notification dispatch.
+
+    acks_late=True + reject_on_worker_lost=True ensures that if a
+    worker dies mid-execution, the task is re-queued instead of lost.
+
+    Retry strategy uses exponential backoff to avoid hammering
+    a provider that's temporarily down (thundering herd prevention).
+    """
+    from notifyfork.core.application.dtos.send_notification_dto import SendNotificationDTO
+    from notifyfork.core.infrastructure.container import Container
+
+    try:
+        dto = SendNotificationDTO(**payload)
+        use_case = Container.send_notification_use_case()
+
+        import asyncio
+        notification_id = asyncio.get_event_loop().run_until_complete(use_case.execute(dto))
+
+        logger.info("Task completed", extra={"notification_id": str(notification_id)})
+        return {"notification_id": str(notification_id), "status": "dispatched"}
+
+    except Exception as exc:
+        logger.warning(
+            "Task failed, scheduling retry",
+            extra={"attempt": self.request.retries + 1, "error": str(exc)},
+        )
+        raise self.retry(exc=exc)
+
+
+@shared_task
+def retry_pending_notifications() -> dict:
+    """
+    Periodic task (beat) that picks up notifications stuck in RETRYING state.
+
+    Prevents silent failures from getting lost if the worker
+    crashed before persisting the final status.
+
+    Schedule this via Celery Beat — e.g. every 5 minutes.
+    """
+    from notifyfork.core.infrastructure.container import Container
+
+    repository = Container.notification_repository()
+
+    import asyncio
+    pending = asyncio.get_event_loop().run_until_complete(
+        repository.get_pending_retries(limit=100)
+    )
+
+    queued = 0
+    for notification in pending:
+        if notification.can_retry:
+            dispatch_notification.delay({
+                "recipient": notification.recipient,
+                "channel": notification.channel,
+                "notification_type": notification.notification_type,
+                "template_id": notification.template_id,
+                "context": notification.context,
+            })
+            queued += 1
+
+    logger.info("Retry sweep complete", extra={"queued": queued})
+    return {"retried": queued}

notifyfork/core/infrastructure/repositories/notification_repository.py

@@ -0,0 +1,69 @@
+import logging
+from uuid import UUID
+
+from notifyfork.core.application.interfaces.notification_repository import NotificationRepository
+from notifyfork.core.domain.entities.notification import Notification, NotificationStatus
+
+logger = logging.getLogger(__name__)
+
+
+class DjangoNotificationRepository(NotificationRepository):
+
+    async def save(self, notification: Notification) -> None:
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+        await NotificationModel.objects.aupdate_or_create(
+            id=notification.id,
+            defaults={
+                "recipient": notification.recipient,
+                "channel": notification.channel,
+                "notification_type": notification.notification_type,
+                "template_id": notification.template_id,
+                "context": notification.context,
+                "status": notification.status.value,
+                "provider_used": notification.provider_used,
+                "attempts": notification.attempts,
+                "max_attempts": notification.max_attempts,
+                "error_detail": notification.error_detail,
+                "sent_at": notification.sent_at,
+            },
+        )
+
+    async def get_by_id(self, notification_id: UUID) -> Notification | None:
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+        try:
+            obj = await NotificationModel.objects.aget(id=notification_id)
+            return self._to_entity(obj)
+        except NotificationModel.DoesNotExist:
+            return None
+
+    async def get_pending_retries(self, limit: int = 100) -> list[Notification]:
+        """
+        Single bounded query — never loads all records then filters in Python.
+        N+1 safe: one query, one trip to the database.
+        """
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+        qs = (
+            NotificationModel.objects
+            .filter(status=NotificationModel.StatusChoices.RETRYING)
+            .order_by("created_at")[:limit]
+        )
+        return [self._to_entity(obj) async for obj in qs]
+
+    @staticmethod
+    def _to_entity(obj) -> Notification:
+        n = Notification(
+            recipient=obj.recipient,
+            channel=obj.channel,
+            notification_type=obj.notification_type,
+            template_id=obj.template_id,
+            context=obj.context,
+            id=obj.id,
+            attempts=obj.attempts,
+            max_attempts=obj.max_attempts,
+            error_detail=obj.error_detail,
+            created_at=obj.created_at,
+            sent_at=obj.sent_at,
+            provider_used=obj.provider_used,
+        )
+        n.status = NotificationStatus(obj.status)
+        return n

notifyfork/core/infrastructure/repositories/template_repository.py

@@ -0,0 +1,23 @@
+import logging
+from notifyfork.core.application.interfaces.template_repository import TemplateRepository
+from notifyfork.core.domain.value_objects.template import NotificationTemplate, TemplateMode, VariableMapping
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseTemplateRepository(TemplateRepository):
+
+    async def get_by_id(self, template_id: str) -> NotificationTemplate | None:
+        from notifyfork.core.infrastructure.models.notification_model import NotificationTemplateModel
+        try:
+            obj = await NotificationTemplateModel.objects.aget(id=template_id, is_active=True)
+            return NotificationTemplate(
+                id=obj.id,
+                body=obj.body,
+                subject=obj.subject,
+                mode=TemplateMode(obj.mode),
+                variable_mapping=VariableMapping(obj.variable_mapping or {}),
+            )
+        except NotificationTemplateModel.DoesNotExist:
+            logger.warning("Template not found", extra={"template_id": template_id})
+            return None

notifyfork/shared/exceptions/provider_exceptions.py

@@ -0,0 +1,21 @@
+class NotificationGatewayError(Exception):
+    """Base exception for the notification gateway domain."""
+
+
+class NoProviderAvailable(NotificationGatewayError):
+    def __init__(self, channel: str) -> None:
+        super().__init__(f"No provider registered for channel: {channel}")
+        self.channel = channel
+
+
+class TemplateNotFound(NotificationGatewayError):
+    def __init__(self, template_id: str) -> None:
+        super().__init__(f"Template not found: {template_id}")
+        self.template_id = template_id
+
+
+class ProviderDeliveryError(NotificationGatewayError):
+    def __init__(self, provider: str, reason: str) -> None:
+        super().__init__(f"Provider '{provider}' failed: {reason}")
+        self.provider = provider
+        self.reason = reason

notifyfork/shared/logging/setup.py

@@ -0,0 +1,38 @@
+import logging
+import sys
+from typing import Any
+import json
+
+
+class JSONFormatter(logging.Formatter):
+    """
+    Structured JSON logs — plays nicely with GCP Cloud Logging,
+    Datadog, and any log aggregator that parses JSON.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        log: dict[str, Any] = {
+            "severity": record.levelname,
+            "message": record.getMessage(),
+            "logger": record.name,
+            "timestamp": self.formatTime(record),
+        }
+
+        if hasattr(record, "__dict__"):
+            extras = {
+                k: v
+                for k, v in record.__dict__.items()
+                if k not in logging.LogRecord.__dict__ and not k.startswith("_")
+            }
+            log.update(extras)
+
+        if record.exc_info:
+            log["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log)
+
+
+def setup_logging(level: str = "INFO") -> None:
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(JSONFormatter())
+    logging.basicConfig(level=level, handlers=[handler])