notifyfork 0.1.2__py3-none-any.whl

notifyfork/__init__.py

@@ -0,0 +1,4 @@
+from notifyfork.client import send
+from notifyfork.core.infrastructure.container.providers import provider
+
+__all__ = ["send", "provider"]

notifyfork/api/urls.py

@@ -0,0 +1,5 @@
+from django.urls import path, include
+
+urlpatterns = [
+    path("webhooks/", include("notifyfork.api.webhooks.urls")),
+]

notifyfork/api/webhooks/resend_webhook.py

@@ -0,0 +1,127 @@
+"""
+Resend delivery event webhook.
+
+Resend calls this endpoint when an email's status changes.
+Configure in Resend Dashboard → Webhooks → add endpoint:
+    https://yourdomain.com/api/v1/webhooks/resend/events/
+
+Resend sends one event per POST as JSON:
+    type          — email.sent | email.delivered | email.delivery_delayed
+                    | email.bounced | email.complained
+    data.email_id — the external ID we stored as provider_message_id
+
+Security: Resend signs every request using Svix (svix-id / svix-timestamp /
+svix-signature headers, HMAC-SHA256). We validate this before processing —
+rejects spoofed requests. See:
+    https://resend.com/docs/dashboard/webhooks/verify-webhooks-requests
+"""
+import base64
+import hashlib
+import hmac
+import logging
+
+from django.conf import settings
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from notifyfork.api.webhooks.tasks import process_delivery_update
+
+logger = logging.getLogger(__name__)
+
+RESEND_DELIVERED_EVENTS = {"email.delivered"}
+RESEND_FAILED_EVENTS = {"email.bounced", "email.complained", "email.delivery_delayed"}
+
+
+class ResendEventWebhookView(APIView):
+    """
+    POST /api/v1/webhooks/resend/events/
+
+    Resend sends one event per request, signed via Svix headers.
+    Responds 200 immediately, enqueues the update to Celery.
+    """
+
+    authentication_classes = []   # Resend uses signature, not token auth
+    permission_classes = []
+
+    def post(self, request: Request) -> Response:
+        if not self._validate_signature(request):
+            logger.warning("Invalid Resend signature — possible spoofed webhook", extra={
+                "ip": request.META.get("REMOTE_ADDR"),
+            })
+            return Response({"detail": "Invalid signature"}, status=status.HTTP_403_FORBIDDEN)
+
+        event_type = request.data.get("type", "")
+        data = request.data.get("data") or {}
+        email_id = data.get("email_id")
+
+        if not email_id:
+            return Response({"detail": "Missing data.email_id"}, status=status.HTTP_400_BAD_REQUEST)
+
+        logger.info("Resend webhook received", extra={"type": event_type, "email_id": email_id})
+
+        # Resend also sends intermediate events (sent, opened, clicked) —
+        # we only care about the final delivery outcome.
+        if event_type not in RESEND_DELIVERED_EVENTS | RESEND_FAILED_EVENTS:
+            return Response({"detail": "intermediate event, ignored"}, status=status.HTTP_200_OK)
+
+        notification_id = self._find_notification_id(email_id)
+        if not notification_id:
+            # Could be a message sent outside NotifyFork — not an error
+            logger.info("No notification found for email_id", extra={"email_id": email_id})
+            return Response({"detail": "unknown message"}, status=status.HTTP_200_OK)
+
+        delivered = event_type in RESEND_DELIVERED_EVENTS
+        reason = data.get("reason") if not delivered else None
+
+        process_delivery_update.delay(
+            notification_id=str(notification_id),
+            provider="resend_email",
+            delivered=delivered,
+            reason=reason,
+        )
+
+        return Response({"detail": "accepted"}, status=status.HTTP_200_OK)
+
+    @staticmethod
+    def _validate_signature(request: Request) -> bool:
+        secret = getattr(settings, "RESEND_WEBHOOK_SECRET", None)
+        if not secret:
+            logger.warning("RESEND_WEBHOOK_SECRET not configured — skipping signature validation")
+            return True  # dev mode only — never in production
+
+        svix_id = request.META.get("HTTP_SVIX_ID", "")
+        svix_timestamp = request.META.get("HTTP_SVIX_TIMESTAMP", "")
+        svix_signature = request.META.get("HTTP_SVIX_SIGNATURE", "")
+
+        if not all([svix_id, svix_timestamp, svix_signature]):
+            return False
+
+        secret_bytes = base64.b64decode(secret.removeprefix("whsec_"))
+        signed_content = f"{svix_id}.{svix_timestamp}.{request.body.decode()}"
+        expected = base64.b64encode(
+            hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
+        ).decode()
+
+        # svix-signature can carry multiple "v1,<sig>" pairs (key rotation) — accept any match
+        candidates = [part.split(",", 1)[1] for part in svix_signature.split() if "," in part]
+        return any(hmac.compare_digest(expected, candidate) for candidate in candidates)
+
+    @staticmethod
+    def _find_notification_id(email_id: str) -> str | None:
+        """
+        Looks up notification by the provider_message_id we stored at send time.
+        Single indexed query — provider_message_id should be indexed in production.
+        """
+        import asyncio
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+
+        async def _get():
+            try:
+                obj = await NotificationModel.objects.aget(provider_message_id=email_id)
+                return str(obj.id)
+            except NotificationModel.DoesNotExist:
+                return None
+
+        return asyncio.get_event_loop().run_until_complete(_get())

notifyfork/api/webhooks/sendgrid_webhook.py

@@ -0,0 +1,124 @@
+"""
+SendGrid delivery event webhook.
+
+SendGrid batches multiple events in one POST as a JSON array.
+Configure in SendGrid → Settings → Mail Settings → Event Webhook:
+    https://yourdomain.com/api/v1/webhooks/sendgrid/events/
+
+Each event in the array has:
+    event       — processed | delivered | bounce | dropped | spamreport | unsubscribe
+    sg_message_id — the external ID we stored as provider_message_id
+    reason      — present on bounce/drop events
+
+Security: SendGrid signs requests with a public key (Ed25519).
+We verify the signature using the public key from your SendGrid account.
+"""
+import json
+import logging
+
+from django.conf import settings
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from notifyfork.api.webhooks.tasks import process_delivery_update
+
+logger = logging.getLogger(__name__)
+
+SENDGRID_DELIVERED_EVENTS = {"delivered"}
+SENDGRID_FAILED_EVENTS    = {"bounce", "dropped", "spamreport"}
+
+
+class SendGridEventWebhookView(APIView):
+    """
+    POST /api/v1/webhooks/sendgrid/events/
+
+    SendGrid sends a JSON array of events — can be many at once.
+    We process each terminal event independently.
+    Responds 200 immediately, enqueues each update to Celery.
+    """
+
+    authentication_classes = []
+    permission_classes = []
+
+    def post(self, request: Request) -> Response:
+        if not self._validate_signature(request):
+            logger.warning("Invalid SendGrid signature", extra={
+                "ip": request.META.get("REMOTE_ADDR"),
+            })
+            return Response({"detail": "Invalid signature"}, status=status.HTTP_403_FORBIDDEN)
+
+        try:
+            events = request.data if isinstance(request.data, list) else json.loads(request.body)
+        except (ValueError, TypeError):
+            return Response({"detail": "Invalid JSON"}, status=status.HTTP_400_BAD_REQUEST)
+
+        queued = 0
+        for event in events:
+            event_type    = event.get("event", "").lower()
+            sg_message_id = event.get("sg_message_id", "").split(".")[0]  # strip suffix
+            reason        = event.get("reason") or event.get("type")
+
+            if event_type not in SENDGRID_DELIVERED_EVENTS | SENDGRID_FAILED_EVENTS:
+                continue  # intermediate events (open, click, etc) — skip
+
+            notification_id = self._find_notification_id(sg_message_id)
+            if not notification_id:
+                continue
+
+            logger.info("SendGrid event received", extra={
+                "event": event_type,
+                "sg_message_id": sg_message_id,
+                "notification_id": notification_id,
+            })
+
+            delivered = event_type in SENDGRID_DELIVERED_EVENTS
+            process_delivery_update.delay(
+                notification_id=notification_id,
+                provider="sendgrid_email",
+                delivered=delivered,
+                reason=reason,
+            )
+            queued += 1
+
+        return Response({"accepted": queued}, status=status.HTTP_200_OK)
+
+    @staticmethod
+    def _validate_signature(request: Request) -> bool:
+        """
+        Validates Ed25519 signature from SendGrid.
+        Public key is in SendGrid → Settings → Mail Settings → Event Webhook.
+        """
+        public_key = getattr(settings, "SENDGRID_WEBHOOK_PUBLIC_KEY", None)
+        if not public_key:
+            logger.warning("SENDGRID_WEBHOOK_PUBLIC_KEY not set — skipping validation (dev only)")
+            return True
+
+        try:
+            from sendgrid.helpers.eventwebhook import EventWebhook, EventWebhookHeader
+            ew = EventWebhook()
+            ec_public_key = ew.convert_public_key_to_ecdsa(public_key)
+            return ew.verify_signature(
+                ec_public_key,
+                request.body,
+                request.META.get(EventWebhookHeader.SIGNATURE, ""),
+                request.META.get(EventWebhookHeader.TIMESTAMP, ""),
+            )
+        except Exception as e:
+            logger.error("SendGrid signature validation error", extra={"error": str(e)})
+            return False
+
+    @staticmethod
+    def _find_notification_id(sg_message_id: str) -> str | None:
+        import asyncio
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+
+        async def _get():
+            try:
+                obj = await NotificationModel.objects.aget(provider_message_id=sg_message_id)
+                return str(obj.id)
+            except NotificationModel.DoesNotExist:
+                return None
+
+        return asyncio.get_event_loop().run_until_complete(_get())

notifyfork/api/webhooks/tasks.py

@@ -0,0 +1,74 @@
+"""
+Celery tasks for processing provider delivery callbacks.
+
+Design: webhook endpoints respond 200 immediately, then enqueue here.
+This prevents provider retries caused by slow processing, and keeps
+the webhook handler stateless and fast.
+"""
+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=10, acks_late=True)
+def process_delivery_update(
+    self,
+    notification_id: str,
+    provider: str,
+    delivered: bool,
+    reason: str | None = None,
+) -> dict:
+    """
+    Updates notification delivery status from provider webhook.
+
+    Runs async so the webhook endpoint can respond instantly.
+    Idempotent — safe to run twice if the provider retries the webhook.
+    """
+    from notifyfork.core.infrastructure.container.providers import Container
+    import asyncio
+
+    try:
+        repository = Container.notification_repository()
+        uid = UUID(notification_id)
+
+        notification = asyncio.get_event_loop().run_until_complete(
+            repository.get_by_id(uid)
+        )
+
+        if not notification:
+            logger.warning("Webhook for unknown notification", extra={
+                "notification_id": notification_id, "provider": provider,
+            })
+            return {"status": "not_found"}
+
+        # Idempotency — if already terminal, skip
+        if notification.is_terminal:
+            logger.info("Notification already terminal, skipping webhook", extra={
+                "notification_id": notification_id,
+                "current_status": notification.status,
+            })
+            return {"status": "already_terminal"}
+
+        if delivered:
+            notification.mark_delivered()
+        else:
+            notification.mark_delivery_failed(reason or "Provider reported delivery failure")
+
+        asyncio.get_event_loop().run_until_complete(repository.save(notification))
+
+        logger.info("Delivery status updated", extra={
+            "notification_id": notification_id,
+            "delivered": delivered,
+            "status": notification.status,
+        })
+        return {"status": notification.status}
+
+    except Exception as exc:
+        logger.error("Failed to process delivery update", extra={
+            "notification_id": notification_id, "error": str(exc),
+        })
+        raise self.retry(exc=exc)

notifyfork/api/webhooks/twilio_webhook.py

@@ -0,0 +1,121 @@
+"""
+Twilio delivery status webhook.
+
+Twilio calls this endpoint when a message status changes.
+Configure in Twilio Console → Phone Numbers → Status Callback URL:
+    https://yourdomain.com/api/v1/webhooks/twilio/status/
+
+Twilio sends form-data (not JSON) with these key fields:
+    MessageSid    — the external ID we stored as provider_message_id
+    MessageStatus — queued | sent | delivered | undelivered | failed
+
+Security: Twilio signs every request with X-Twilio-Signature.
+We validate this before processing — rejects spoofed requests.
+"""
+import logging
+
+from django.conf import settings
+from rest_framework import status
+from rest_framework.parsers import FormParser, MultiPartParser
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+from twilio.request_validator import RequestValidator
+
+from notifyfork.api.webhooks.tasks import process_delivery_update
+
+logger = logging.getLogger(__name__)
+
+# Twilio statuses that mean "delivered to handset"
+TWILIO_DELIVERED_STATUSES = {"delivered", "read"}
+
+# Twilio statuses that mean "provider confirmed failure"
+TWILIO_FAILED_STATUSES = {"failed", "undelivered"}
+
+
+class TwilioStatusWebhookView(APIView):
+    """
+    POST /api/v1/webhooks/twilio/status/
+
+    Validates Twilio signature, responds 200 immediately,
+    enqueues status update to Celery for async processing.
+    """
+
+    authentication_classes = []   # Twilio uses signature, not token auth
+    permission_classes = []
+    parser_classes = [FormParser, MultiPartParser]   # Twilio posts form-data, not JSON
+
+    def post(self, request: Request) -> Response:
+        if not self._validate_signature(request):
+            logger.warning("Invalid Twilio signature — possible spoofed webhook", extra={
+                "ip": request.META.get("REMOTE_ADDR"),
+            })
+            return Response({"detail": "Invalid signature"}, status=status.HTTP_403_FORBIDDEN)
+
+        message_sid    = request.data.get("MessageSid")
+        message_status = request.data.get("MessageStatus", "").lower()
+        error_code     = request.data.get("ErrorCode")
+        error_message  = request.data.get("ErrorMessage")
+
+        if not message_sid or not message_status:
+            return Response({"detail": "Missing MessageSid or MessageStatus"},
+                            status=status.HTTP_400_BAD_REQUEST)
+
+        logger.info("Twilio webhook received", extra={
+            "message_sid": message_sid,
+            "message_status": message_status,
+            "error_code": error_code,
+        })
+
+        # Twilio also sends intermediate statuses (queued, sending, sent) —
+        # we only care about the final delivery outcome.
+        if message_status not in TWILIO_DELIVERED_STATUSES | TWILIO_FAILED_STATUSES:
+            return Response({"detail": "intermediate status, ignored"}, status=status.HTTP_200_OK)
+
+        notification_id = self._find_notification_id(message_sid)
+        if not notification_id:
+            # Could be a message sent outside NotifyFork — not an error
+            logger.info("No notification found for MessageSid", extra={"message_sid": message_sid})
+            return Response({"detail": "unknown message"}, status=status.HTTP_200_OK)
+
+        delivered = message_status in TWILIO_DELIVERED_STATUSES
+        reason = f"Twilio [{error_code}]: {error_message}" if error_code else None
+
+        process_delivery_update.delay(
+            notification_id=str(notification_id),
+            provider="twilio_sms",
+            delivered=delivered,
+            reason=reason,
+        )
+
+        return Response({"detail": "accepted"}, status=status.HTTP_200_OK)
+
+    @staticmethod
+    def _validate_signature(request: Request) -> bool:
+        auth_token = getattr(settings, "TWILIO_AUTH_TOKEN", None)
+        if not auth_token:
+            logger.error("TWILIO_AUTH_TOKEN not configured — skipping signature validation")
+            return True  # dev mode only — never in production
+
+        validator = RequestValidator(auth_token)
+        signature = request.META.get("HTTP_X_TWILIO_SIGNATURE", "")
+        url = request.build_absolute_uri()
+        return validator.validate(url, request.data, signature)
+
+    @staticmethod
+    def _find_notification_id(message_sid: str) -> str | None:
+        """
+        Looks up notification by the provider_message_id we stored at send time.
+        Single indexed query — provider_message_id should be indexed in production.
+        """
+        import asyncio
+        from notifyfork.core.infrastructure.models.notification_model import NotificationModel
+
+        async def _get():
+            try:
+                obj = await NotificationModel.objects.aget(provider_message_id=message_sid)
+                return str(obj.id)
+            except NotificationModel.DoesNotExist:
+                return None
+
+        return asyncio.get_event_loop().run_until_complete(_get())

notifyfork/api/webhooks/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path
+from notifyfork.api.webhooks.twilio_webhook import TwilioStatusWebhookView
+from notifyfork.api.webhooks.sendgrid_webhook import SendGridEventWebhookView
+from notifyfork.api.webhooks.resend_webhook import ResendEventWebhookView
+
+urlpatterns = [
+    path("twilio/status/",    TwilioStatusWebhookView.as_view(),   name="webhook-twilio-status"),
+    path("sendgrid/events/",  SendGridEventWebhookView.as_view(),  name="webhook-sendgrid-events"),
+    path("resend/events/",    ResendEventWebhookView.as_view(),    name="webhook-resend-events"),
+]

notifyfork/client.py

@@ -0,0 +1,63 @@
+"""
+Python entry point for NotifyFork.
+
+Use this when the caller lives in the same project that has NotifyFork
+installed. For a different service to send events, expose your own
+authenticated view that calls this function — see the README.
+"""
+import logging
+from typing import Any
+
+from celery.result import AsyncResult
+
+from notifyfork.core.domain.entities.notification import NotificationChannel, NotificationType
+from notifyfork.core.infrastructure.queue.tasks import dispatch_notification
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["send"]
+
+
+def send(
+    recipient: str,
+    channel: NotificationChannel | str,
+    template_id: str,
+    notification_type: NotificationType | str,
+    context: dict[str, Any] | None = None,
+    max_attempts: int = 3,
+) -> AsyncResult:
+    """
+    Enqueues a notification for delivery.
+
+    You already know the channel and template you want, so this just
+    passes them straight to the queue — no routing table or event
+    catalog to register first.
+
+    Raises ValueError if recipient is blank or max_attempts is out of
+    range (1-5).
+    """
+    if not recipient or not recipient.strip():
+        raise ValueError("recipient cannot be blank")
+    if not 1 <= max_attempts <= 5:
+        raise ValueError("max_attempts must be between 1 and 5")
+
+    task = dispatch_notification.delay({
+        "recipient": recipient.strip(),
+        "channel": channel,
+        "notification_type": notification_type,
+        "template_id": template_id,
+        "context": context or {},
+        "max_attempts": max_attempts,
+    })
+
+    logger.info(
+        "Notification accepted and enqueued",
+        extra={
+            "channel": channel,
+            "template_id": template_id,
+            "task_id": task.id,
+            "recipient_hint": recipient[:6] + "***",  # never log full PII
+        },
+    )
+
+    return task

notifyfork/core/application/dtos/send_notification_dto.py

@@ -0,0 +1,25 @@
+from typing import Any
+from pydantic import BaseModel, field_validator
+
+
+class SendNotificationDTO(BaseModel):
+    recipient: str
+    channel: str
+    notification_type: str
+    template_id: str
+    context: dict[str, Any] = {}
+    max_attempts: int = 3
+
+    @field_validator("recipient")
+    @classmethod
+    def recipient_not_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Recipient cannot be empty")
+        return v.strip()
+
+    @field_validator("max_attempts")
+    @classmethod
+    def valid_attempts(cls, v: int) -> int:
+        if not 1 <= v <= 5:
+            raise ValueError("max_attempts must be between 1 and 5")
+        return v

notifyfork/core/application/interfaces/notification_provider.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+from notifyfork.core.domain.entities.notification import NotificationChannel
+from notifyfork.core.domain.value_objects.template import NotificationTemplate
+
+
+@dataclass
+class ProviderResult:
+    success: bool
+    provider_name: str
+    external_id: str | None = None
+    error: str | None = None
+
+
+class NotificationProvider(ABC):
+    """
+    Base contract every provider must implement.
+
+    send_with_template() is the unified entry point.
+    The provider decides internally whether to render locally
+    or delegate to an external template system.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def supported_channels(self) -> list[NotificationChannel | str]: ...
+
+    @abstractmethod
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult: ...
+
+    def supports(self, channel: NotificationChannel | str) -> bool:
+        return channel in self.supported_channels

notifyfork/core/application/interfaces/notification_repository.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from uuid import UUID
+
+from notifyfork.core.domain.entities.notification import Notification
+
+
+class NotificationRepository(ABC):
+    @abstractmethod
+    async def save(self, notification: Notification) -> None: ...
+
+    @abstractmethod
+    async def get_by_id(self, notification_id: UUID) -> Notification | None: ...
+
+    @abstractmethod
+    async def get_pending_retries(self, limit: int = 100) -> list[Notification]: ...

notifyfork/core/application/interfaces/template_repository.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+from notifyfork.core.domain.value_objects.template import NotificationTemplate
+
+
+class TemplateRepository(ABC):
+    @abstractmethod
+    async def get_by_id(self, template_id: str) -> NotificationTemplate | None: ...