notifyfork 0.1.2__py3-none-any.whl

notifyfork/core/infrastructure/migrations/0002_seed_templates.py

@@ -0,0 +1,116 @@
+"""
+Seed migration — inserts the default templates that ship with NotifyFork.
+
+These are starter templates. Edit them in the database or via Django admin
+to match your product's copy and branding.
+"""
+from django.db import migrations
+
+
+TEMPLATES = [
+    # SMS
+    {
+        "id": "otp_sms",
+        "body": "Your NotifyFork verification code is: $code. Valid for 10 minutes.",
+        "subject": None,
+        "mode": "local",
+        "variable_mapping": {},
+    },
+    {
+        "id": "payment_failed_sms",
+        "body": "Payment of $amount failed for order $order_id. Please update your payment method.",
+        "subject": None,
+        "mode": "local",
+        "variable_mapping": {},
+    },
+
+    # Email (local HTML)
+    {
+        "id": "email_verification",
+        "body": "<p>Hi $name,</p><p>Click <a href='$link'>here</a> to verify your email.</p>",
+        "subject": "Verify your email address",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+    {
+        "id": "order_confirmed",
+        "body": "<p>Hi $name,</p><p>Your order <strong>$order_id</strong> is confirmed. Total: $total</p>",
+        "subject": "Order $order_id confirmed",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+
+    # WhatsApp (Twilio external template)
+    # body = Twilio Content Template SID
+    # variable_mapping translates context keys to positional Twilio variables
+    {
+        "id": "order_shipped_wa",
+        "body": "REPLACE_WITH_YOUR_TWILIO_CONTENT_SID",
+        "subject": None,
+        "mode": "external",
+        "variable_mapping": {"name": "1", "tracking_code": "2", "carrier": "3"},
+    },
+
+    # Email (SendGrid external template)
+    # body = SendGrid Dynamic Template ID (d-xxxx)
+    {
+        "id": "order_confirmed_sg",
+        "body": "REPLACE_WITH_YOUR_SENDGRID_TEMPLATE_ID",
+        "subject": None,
+        "mode": "external",
+        "variable_mapping": {
+            "name": "customer_name",
+            "order_id": "order_id",
+            "total": "order_total",
+        },
+    },
+
+    # Push (Firebase, rendered locally)
+    {
+        "id": "flash_sale_push",
+        "body": "Hurry! $discount OFF everything. Ends in $expires_in.",
+        "subject": "Flash Sale — $discount OFF",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+    {
+        "id": "pickup_ready_push",
+        "body": "Your order $order_id is ready for pickup at $location.",
+        "subject": "Your order is ready!",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+
+    # Slack (rendered locally with Markdown)
+    {
+        "id": "system_error_slack",
+        "body": "*Service:* $service\n*Error:* $error\n*Environment:* $env",
+        "subject": "🚨 Error in $service",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+    {
+        "id": "deploy_done_slack",
+        "body": "*Service:* $service deployed successfully\n*Version:* $version\n*By:* $author",
+        "subject": "✅ Deploy completed — $service",
+        "mode": "local",
+        "variable_mapping": {},
+    },
+]
+
+
+def seed_templates(apps, schema_editor):
+    NotificationTemplateModel = apps.get_model("notifyfork", "NotificationTemplateModel")
+    for t in TEMPLATES:
+        NotificationTemplateModel.objects.get_or_create(id=t["id"], defaults=t)
+
+
+def unseed_templates(apps, schema_editor):
+    NotificationTemplateModel = apps.get_model("notifyfork", "NotificationTemplateModel")
+    ids = [t["id"] for t in TEMPLATES]
+    NotificationTemplateModel.objects.filter(id__in=ids).delete()
+
+
+class Migration(migrations.Migration):
+    dependencies = [("notifyfork", "0001_initial")]
+    operations = [migrations.RunPython(seed_templates, unseed_templates)]

notifyfork/core/infrastructure/migrations/0003_delivery_status.py

@@ -0,0 +1,50 @@
+"""
+Migration: adds DELIVERED and DELIVERY_FAILED statuses,
+plus provider_message_id and delivered_at fields.
+
+provider_message_id is indexed — webhook lookups query by this field.
+"""
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [("notifyfork", "0002_seed_templates")]
+
+    operations = [
+        migrations.AddField(
+            model_name="NotificationModel",
+            name="provider_message_id",
+            field=models.CharField(
+                max_length=255,
+                null=True,
+                blank=True,
+                db_index=True,   # indexed — webhook lookup by this field
+                help_text="External ID returned by provider at send time (e.g. Twilio MessageSid)",
+            ),
+        ),
+        migrations.AddField(
+            model_name="NotificationModel",
+            name="delivered_at",
+            field=models.DateTimeField(null=True, blank=True),
+        ),
+        # Update status choices to include new states
+        migrations.AlterField(
+            model_name="NotificationModel",
+            name="status",
+            field=models.CharField(
+                max_length=20,
+                default="pending",
+                db_index=True,
+                choices=[
+                    ("pending",          "Pending"),
+                    ("queued",           "Queued"),
+                    ("sent",             "Sent"),
+                    ("delivered",        "Delivered"),
+                    ("delivery_failed",  "Delivery Failed"),
+                    ("failed",           "Failed"),
+                    ("retrying",         "Retrying"),
+                ],
+            ),
+        ),
+    ]

notifyfork/core/infrastructure/models/__init__.py

@@ -0,0 +1,6 @@
+from notifyfork.core.infrastructure.models.notification_model import (
+    NotificationModel,
+    NotificationTemplateModel,
+)
+
+__all__ = ["NotificationModel", "NotificationTemplateModel"]

notifyfork/core/infrastructure/models/notification_model.py

@@ -0,0 +1,98 @@
+import uuid
+from django.db import models
+
+
+class NotificationModel(models.Model):
+    """
+    Django ORM model for persisting Notification state.
+
+    Intentionally separate from the domain entity —
+    the domain entity owns behavior, this model owns persistence.
+    """
+
+    class StatusChoices(models.TextChoices):
+        PENDING = "pending"
+        QUEUED = "queued"
+        SENT = "sent"
+        DELIVERED = "delivered"
+        DELIVERY_FAILED = "delivery_failed"
+        FAILED = "failed"
+        RETRYING = "retrying"
+
+    class ChannelChoices(models.TextChoices):
+        SMS = "sms"
+        EMAIL = "email"
+        PUSH = "push"
+        WHATSAPP = "whatsapp"
+        SLACK = "slack"
+
+    class TypeChoices(models.TextChoices):
+        TRANSACTIONAL = "transactional"
+        ALERT = "alert"
+        MARKETING = "marketing"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    recipient = models.CharField(max_length=255)
+    channel = models.CharField(max_length=20, choices=ChannelChoices.choices)
+    notification_type = models.CharField(max_length=20, choices=TypeChoices.choices)
+    template_id = models.CharField(max_length=100)
+    context = models.JSONField(default=dict)
+    status = models.CharField(
+        max_length=20, choices=StatusChoices.choices, default=StatusChoices.PENDING, db_index=True
+    )
+    provider_used = models.CharField(max_length=50, null=True, blank=True)
+    provider_message_id = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="External ID returned by provider at send time (e.g. Twilio MessageSid)",
+    )
+    attempts = models.PositiveSmallIntegerField(default=0)
+    max_attempts = models.PositiveSmallIntegerField(default=3)
+    error_detail = models.TextField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+    sent_at = models.DateTimeField(null=True, blank=True)
+    delivered_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        app_label = "notifyfork"
+        db_table = "notifyfork_notifications"
+        ordering = ["-created_at"]
+        indexes = [
+            # Most common query: retrying notifications for the sweep task
+            models.Index(fields=["status", "attempts"], name="idx_status_attempts"),
+        ]
+
+    def __str__(self) -> str:
+        return f"Notification({self.channel} → {self.recipient[:8]}*** [{self.status}])"
+
+
+class NotificationTemplateModel(models.Model):
+    """
+    Stores templates in the database.
+    Supports both LOCAL (body = content) and EXTERNAL (body = provider template ID) modes.
+    """
+
+    class ModeChoices(models.TextChoices):
+        LOCAL = "local"
+        EXTERNAL = "external"
+
+    id = models.CharField(max_length=100, primary_key=True)  # e.g. "otp_sms"
+    body = models.TextField()                                  # content or external template ID
+    subject = models.CharField(max_length=255, null=True, blank=True)
+    mode = models.CharField(max_length=10, choices=ModeChoices.choices, default=ModeChoices.LOCAL)
+    variable_mapping = models.JSONField(
+        default=dict,
+        help_text='Maps context keys to provider keys. e.g. {"name": "1", "code": "2"} for Twilio WA',
+    )
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        app_label = "notifyfork"
+        db_table = "notifyfork_templates"
+
+    def __str__(self) -> str:
+        return f"Template({self.id} [{self.mode}])"

notifyfork/core/infrastructure/providers/firebase_provider.py

@@ -0,0 +1,69 @@
+import logging
+from typing import Any
+
+import firebase_admin
+from firebase_admin import messaging
+from firebase_admin.exceptions import FirebaseError
+
+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 FirebasePushProvider(NotificationProvider):
+    """
+    Firebase Cloud Messaging provider for push notifications.
+
+    Recipient is expected to be a valid FCM device token.
+    """
+
+    @property
+    def name(self) -> str:
+        return "firebase_push"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "push" — generic, eligible for fallback if another push provider is
+        # registered. "firebase_push" (== self.name) — pins this exact vendor.
+        return [NotificationChannel.PUSH, 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)
+        return await self.send(recipient=recipient, body=body, subject=subject)
+
+    async def send(
+        self,
+        recipient: str,
+        body: str,
+        subject: str | None = None,
+        **kwargs,
+    ) -> ProviderResult:
+        try:
+            message = messaging.Message(
+                notification=messaging.Notification(
+                    title=subject or "Notification",
+                    body=body,
+                ),
+                token=recipient,
+            )
+            response = messaging.send(message)
+            return ProviderResult(
+                success=True,
+                provider_name=self.name,
+                external_id=response,
+            )
+        except FirebaseError as e:
+            logger.error("Firebase error", extra={"error": str(e)})
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=str(e),
+            )

notifyfork/core/infrastructure/providers/resend_provider.py

@@ -0,0 +1,83 @@
+import logging
+import httpx
+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__)
+
+RESEND_API_URL = "https://api.resend.com/emails"
+
+
+class ResendEmailProvider(NotificationProvider):
+    """
+    Resend email provider.
+
+    LOCAL mode only — renders body locally, sends as raw HTML. Resend
+    doesn't have a server-side dynamic template system like SendGrid; if
+    you need EXTERNAL mode, use SendGridEmailProvider instead.
+    """
+
+    def __init__(self, api_key: str, from_email: str, from_name: str = "") -> None:
+        self._api_key = api_key
+        self._from_email = from_email
+        self._from_name = from_name
+
+    @property
+    def name(self) -> str:
+        return "resend_email"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "email" — generic, eligible for fallback to sendgrid_email/smtp_email.
+        # "resend_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)"
+        sender = f"{self._from_name} <{self._from_email}>" if self._from_name else self._from_email
+
+        payload = {
+            "from": sender,
+            "to": [recipient],
+            "subject": subject,
+            "html": body,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(
+                    RESEND_API_URL,
+                    headers={
+                        "Authorization": f"Bearer {self._api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json=payload,
+                )
+
+            if response.status_code in (200, 201):
+                message_id = response.json().get("id")
+                logger.info("Email sent via Resend", extra={"message_id": message_id})
+                return ProviderResult(success=True, provider_name=self.name, external_id=message_id)
+
+            logger.error(
+                "Resend error",
+                extra={"status": response.status_code, "body": response.text},
+            )
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=f"Resend [{response.status_code}]: {response.text}",
+            )
+
+        except httpx.HTTPError as e:
+            logger.error("Resend HTTP error", extra={"error": str(e)})
+            return ProviderResult(success=False, provider_name=self.name, error=str(e))

notifyfork/core/infrastructure/providers/sendgrid_provider.py

@@ -0,0 +1,150 @@
+import logging
+import httpx
+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, TemplateMode
+
+logger = logging.getLogger(__name__)
+
+SENDGRID_API_URL = "https://api.sendgrid.com/v3/mail/send"
+
+
+class SendGridEmailProvider(NotificationProvider):
+    """
+    SendGrid email provider.
+
+    LOCAL mode  — renders body locally, sends as raw HTML.
+    EXTERNAL mode — uses a SendGrid Dynamic Template (d-xxxx).
+                    Variables are translated via VariableMapping
+                    and sent as `dynamic_template_data`.
+
+    SendGrid Dynamic Templates use Handlebars: {{name}}, {{order_id}}
+    Your context keys must match the template's variable names,
+    or use VariableMapping to translate them.
+
+    Example:
+        template = NotificationTemplate(
+            id="order_confirmed",
+            body="d-abc123def456",           # SendGrid template ID
+            mode=TemplateMode.EXTERNAL,
+            variable_mapping=VariableMapping({
+                "order_id": "order_id",       # same name — pass through
+                "total": "order_total",       # renamed to match SendGrid template
+                "name": "customer_name",
+            })
+        )
+        # context: {"order_id": "ORD-1", "total": "R$100", "name": "Mario"}
+        # sent to SendGrid as: {"order_id": "ORD-1", "order_total": "R$100", "customer_name": "Mario"}
+    """
+
+    def __init__(self, api_key: str, from_email: str, from_name: str = "") -> None:
+        self._api_key = api_key
+        self._from_email = from_email
+        self._from_name = from_name
+
+    @property
+    def name(self) -> str:
+        return "sendgrid_email"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # "email" — generic, eligible for fallback to resend_email/smtp_email
+        # (LOCAL-mode templates only). "sendgrid_email" (== self.name) — pins
+        # this vendor, required for EXTERNAL-mode templates (Dynamic Template ID).
+        return [NotificationChannel.EMAIL, self.name]
+
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        if template.mode == TemplateMode.EXTERNAL:
+            return await self._send_external(recipient, template, context)
+        return await self._send_local(recipient, template, context)
+
+    async def _send_external(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        """Uses a SendGrid Dynamic Template with Handlebars variables."""
+        translated = template.translate_variables(context)
+
+        payload = {
+            "from": {"email": self._from_email, "name": self._from_name},
+            "personalizations": [
+                {
+                    "to": [{"email": recipient}],
+                    "dynamic_template_data": translated,
+                }
+            ],
+            "template_id": template.external_template_id,
+        }
+
+        logger.info(
+            "Sending email via SendGrid external template",
+            extra={
+                "template_id": template.external_template_id,
+                "to": recipient,
+                "variables": list(translated.keys()),
+            },
+        )
+
+        return await self._post(payload)
+
+    async def _send_local(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        """Renders HTML locally, sends as raw content."""
+        body = template.render(context)
+        subject = template.render_subject(context) or "(no subject)"
+
+        payload = {
+            "from": {"email": self._from_email, "name": self._from_name},
+            "personalizations": [{"to": [{"email": recipient}]}],
+            "subject": subject,
+            "content": [{"type": "text/html", "value": body}],
+        }
+
+        return await self._post(payload)
+
+    async def _post(self, payload: dict) -> ProviderResult:
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(
+                    SENDGRID_API_URL,
+                    headers={
+                        "Authorization": f"Bearer {self._api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json=payload,
+                )
+
+            # SendGrid returns 202 on success, no body
+            if response.status_code == 202:
+                message_id = response.headers.get("X-Message-Id")
+                logger.info("Email sent via SendGrid", extra={"message_id": message_id})
+                return ProviderResult(
+                    success=True, provider_name=self.name, external_id=message_id
+                )
+
+            logger.error(
+                "SendGrid error",
+                extra={"status": response.status_code, "body": response.text},
+            )
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=f"SendGrid [{response.status_code}]: {response.text}",
+            )
+
+        except httpx.HTTPError as e:
+            logger.error("SendGrid HTTP error", extra={"error": str(e)})
+            return ProviderResult(success=False, provider_name=self.name, error=str(e))

notifyfork/core/infrastructure/providers/slack_provider.py

@@ -0,0 +1,108 @@
+import logging
+from typing import Any
+import httpx
+
+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__)
+
+SLACK_API_URL = "https://slack.com/api/chat.postMessage"
+
+
+class SlackProvider(NotificationProvider):
+    """
+    Slack provider via Web API.
+
+    Recipient is a Slack channel ID or user ID (e.g. C012AB3CD, U012AB3CD).
+    Bot token must have chat:write scope.
+
+    Use for: internal alerts, ops notifications, system events.
+    Not for end-user transactional messages.
+    """
+
+    def __init__(self, bot_token: str) -> None:
+        self._token = bot_token
+
+    @property
+    def name(self) -> str:
+        return "slack"
+
+    @property
+    def supported_channels(self) -> list[NotificationChannel]:
+        # self.name == "slack" == NotificationChannel.SLACK.value already —
+        # generic and vendor-specific channel are the same string here, so
+        # there's no second entry to add (unlike twilio_whatsapp, sendgrid_email...).
+        return [NotificationChannel.SLACK]
+
+    async def send_with_template(
+        self,
+        recipient: str,
+        template: NotificationTemplate,
+        context: dict[str, Any],
+    ) -> ProviderResult:
+        body = template.render(context)
+        subject = template.render_subject(context)
+        return await self.send(recipient=recipient, body=body, subject=subject)
+
+    async def send(
+        self,
+        recipient: str,
+        body: str,
+        subject: str | None = None,
+        **kwargs,
+    ) -> ProviderResult:
+        payload = {
+            "channel": recipient,
+            "text": body,
+        }
+
+        # Optional: rich block format when subject is provided
+        if subject:
+            payload["blocks"] = [
+                {
+                    "type": "header",
+                    "text": {"type": "plain_text", "text": subject},
+                },
+                {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": body},
+                },
+            ]
+
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.post(
+                    SLACK_API_URL,
+                    headers={"Authorization": f"Bearer {self._token}"},
+                    json=payload,
+                )
+                data = response.json()
+
+            if not data.get("ok"):
+                error = data.get("error", "unknown_error")
+                logger.error("Slack API error", extra={"error": error, "channel": recipient})
+                return ProviderResult(
+                    success=False,
+                    provider_name=self.name,
+                    error=f"Slack error: {error}",
+                )
+
+            logger.info(
+                "Slack message sent",
+                extra={"channel": recipient, "ts": data.get("ts")},
+            )
+            return ProviderResult(
+                success=True,
+                provider_name=self.name,
+                external_id=data.get("ts"),
+            )
+
+        except httpx.HTTPError as e:
+            logger.error("Slack HTTP error", extra={"error": str(e)})
+            return ProviderResult(
+                success=False,
+                provider_name=self.name,
+                error=f"HTTP error: {str(e)}",
+            )