notifyfork 0.1.2__py3-none-any.whl

notifyfork/core/application/use_cases/send_notification.py

@@ -0,0 +1,91 @@
+import logging
+from uuid import UUID
+
+from notifyfork.core.application.dtos.send_notification_dto import SendNotificationDTO
+from notifyfork.core.application.interfaces.notification_provider import NotificationProvider
+from notifyfork.core.application.interfaces.notification_repository import NotificationRepository
+from notifyfork.core.application.interfaces.template_repository import TemplateRepository
+from notifyfork.core.domain.entities.notification import Notification
+from notifyfork.shared.exceptions.provider_exceptions import NoProviderAvailable, TemplateNotFound
+
+logger = logging.getLogger(__name__)
+
+
+class SendNotificationUseCase:
+    """
+    Orchestrates notification dispatch.
+
+    Does not know whether templates are local or external —
+    that's the provider's responsibility.
+    Does not know how Twilio, SendGrid or Firebase work.
+    Knows only: get template, pick providers, persist state, deliver.
+
+    When more than one provider supports the channel, tries them in order
+    (see Container's provider ordering) and falls through to the next on
+    failure. notification.provider_used always records which one actually
+    sent it, and each fallback is logged as it happens.
+    """
+
+    def __init__(
+        self,
+        repository: NotificationRepository,
+        template_repository: TemplateRepository,
+        providers: list[NotificationProvider],
+    ) -> None:
+        self._repository = repository
+        self._template_repository = template_repository
+        self._providers = providers
+
+    async def execute(self, dto: SendNotificationDTO) -> UUID:
+        template = await self._template_repository.get_by_id(dto.template_id)
+        if not template:
+            raise TemplateNotFound(dto.template_id)
+
+        candidates = self._resolve_providers(dto.channel)
+
+        notification = Notification(
+            recipient=dto.recipient,
+            channel=dto.channel,
+            notification_type=dto.notification_type,
+            template_id=dto.template_id,
+            context=dto.context,
+            max_attempts=dto.max_attempts,
+        )
+
+        notification.mark_queued()
+        await self._repository.save(notification)
+
+        error = "Unknown provider error"
+        for index, provider in enumerate(candidates):
+            # Provider handles LOCAL vs EXTERNAL rendering internally
+            result = await provider.send_with_template(
+                recipient=dto.recipient,
+                template=template,
+                context=dto.context,
+            )
+            if result.success:
+                notification.mark_sent(provider.name)
+                break
+
+            error = result.error or "Unknown provider error"
+            has_fallback = index < len(candidates) - 1
+            logger.warning(
+                "Provider failed" + (", falling back to next provider" if has_fallback else ""),
+                extra={
+                    "provider": provider.name,
+                    "channel": dto.channel,
+                    "error": error,
+                    "fallback_available": has_fallback,
+                },
+            )
+        else:
+            notification.mark_failed(error)
+
+        await self._repository.save(notification)
+        return notification.id
+
+    def _resolve_providers(self, channel) -> list[NotificationProvider]:
+        candidates = [p for p in self._providers if p.supports(channel)]
+        if not candidates:
+            raise NoProviderAvailable(channel)
+        return candidates

notifyfork/core/domain/entities/notification.py

@@ -0,0 +1,141 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationStatus(str, Enum):
+    PENDING          = "pending"
+    QUEUED           = "queued"
+    SENT             = "sent"          # provider accepted — not yet confirmed delivered
+    DELIVERED        = "delivered"     # provider confirmed delivery to recipient
+    DELIVERY_FAILED  = "delivery_failed"  # provider confirmed it could NOT deliver
+    FAILED           = "failed"        # our system exhausted all retry attempts
+    RETRYING         = "retrying"
+
+
+class NotificationChannel(str, Enum):
+    SMS       = "sms"
+    EMAIL     = "email"
+    PUSH      = "push"
+    WHATSAPP  = "whatsapp"
+    SLACK     = "slack"
+
+
+class NotificationType(str, Enum):
+    TRANSACTIONAL = "transactional"
+    ALERT         = "alert"
+    MARKETING     = "marketing"
+
+
+@dataclass
+class Notification:
+    """
+    Core domain entity. Owns its own state machine.
+
+    State flow:
+        PENDING → QUEUED → SENT ──────────────→ DELIVERED        (confirmed by provider webhook)
+                               ↘ RETRYING →  ↗                   (retry succeeded)
+                                           → DELIVERY_FAILED      (provider confirmed failure)
+                               → FAILED                           (our retries exhausted)
+
+    SENT means "provider accepted" — not "recipient got it".
+    DELIVERED means the provider webhook confirmed actual delivery.
+    DELIVERY_FAILED means the provider confirmed it could not deliver
+    (bad number, full inbox, uninstalled app, etc).
+    """
+
+    recipient: str
+    channel: str
+    notification_type: str
+    template_id: str
+    context: dict[str, Any] = field(default_factory=dict)
+    id: UUID = field(default_factory=uuid4)
+    status: NotificationStatus = field(default=NotificationStatus.PENDING)
+    provider_used: str | None = None
+    provider_message_id: str | None = None   # external ID for webhook correlation
+    attempts: int = 0
+    max_attempts: int = 3
+    error_detail: str | None = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    sent_at: datetime | None = None
+    delivered_at: datetime | None = None
+
+    def mark_queued(self) -> None:
+        logger.info("Notification queued", extra={
+            "notification_id": str(self.id), "channel": self.channel,
+        })
+        self.status = NotificationStatus.QUEUED
+
+    def mark_sent(self, provider: str, provider_message_id: str | None = None) -> None:
+        self.status = NotificationStatus.SENT
+        self.provider_used = provider
+        self.provider_message_id = provider_message_id
+        self.sent_at = datetime.utcnow()
+        logger.info("Notification sent — awaiting delivery confirmation", extra={
+            "notification_id": str(self.id),
+            "provider": provider,
+            "provider_message_id": provider_message_id,
+            "channel": self.channel,
+        })
+
+    def mark_delivered(self) -> None:
+        """Called when provider webhook confirms delivery to recipient."""
+        if self.status != NotificationStatus.SENT:
+            logger.warning("mark_delivered called on non-SENT notification", extra={
+                "notification_id": str(self.id), "current_status": self.status,
+            })
+        self.status = NotificationStatus.DELIVERED
+        self.delivered_at = datetime.utcnow()
+        logger.info("Notification delivered", extra={
+            "notification_id": str(self.id),
+            "provider": self.provider_used,
+            "latency_ms": int((self.delivered_at - self.sent_at).total_seconds() * 1000)
+            if self.sent_at else None,
+        })
+
+    def mark_delivery_failed(self, reason: str) -> None:
+        """Called when provider webhook confirms it could NOT deliver."""
+        self.status = NotificationStatus.DELIVERY_FAILED
+        self.error_detail = reason
+        logger.error("Delivery failed (provider confirmed)", extra={
+            "notification_id": str(self.id),
+            "provider": self.provider_used,
+            "reason": reason,
+        })
+
+    def mark_failed(self, reason: str) -> None:
+        """Called when our retry logic gives up."""
+        self.attempts += 1
+        self.error_detail = reason
+        if self.attempts >= self.max_attempts:
+            self.status = NotificationStatus.FAILED
+            logger.error("Notification permanently failed", extra={
+                "notification_id": str(self.id),
+                "attempts": self.attempts,
+                "reason": reason,
+            })
+        else:
+            self.status = NotificationStatus.RETRYING
+            logger.warning("Notification failed, will retry", extra={
+                "notification_id": str(self.id),
+                "attempt": self.attempts,
+                "max_attempts": self.max_attempts,
+                "reason": reason,
+            })
+
+    @property
+    def can_retry(self) -> bool:
+        return self.attempts < self.max_attempts
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in (
+            NotificationStatus.DELIVERED,
+            NotificationStatus.DELIVERY_FAILED,
+            NotificationStatus.FAILED,
+        )

notifyfork/core/domain/events/notification_events.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class NotificationQueued:
+    notification_id: UUID
+    channel: str
+    recipient: str
+    occurred_at: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass(frozen=True)
+class NotificationSent:
+    notification_id: UUID
+    provider: str
+    occurred_at: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass(frozen=True)
+class NotificationFailed:
+    notification_id: UUID
+    reason: str
+    attempts: int
+    occurred_at: datetime = field(default_factory=datetime.utcnow)

notifyfork/core/domain/value_objects/template.py

@@ -0,0 +1,95 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from string import Template
+from typing import Any
+
+
+class TemplateMode(str, Enum):
+    LOCAL = "local"       # rendered here — body is the content
+    EXTERNAL = "external" # rendered by provider — body is the template ID
+
+
+@dataclass(frozen=True)
+class VariableMapping:
+    """
+    Maps our semantic variable names to provider-specific keys.
+
+    Twilio WhatsApp uses positional keys: {"name": "1", "code": "2"}
+    SendGrid uses named keys: {"name": "user_name", "code": "otp_code"}
+    Mailgun uses the same name: {"name": "name", "code": "code"}
+
+    This keeps your context payload consistent regardless of provider.
+    You always send {"name": "Mario", "code": "123"} and the mapping
+    translates to whatever the provider expects.
+    """
+    mappings: dict[str, str] = field(default_factory=dict)
+
+    def translate(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Translates context keys using the mapping.
+        Keys not in the mapping are passed through as-is.
+        """
+        if not self.mappings:
+            return context
+        return {
+            self.mappings.get(k, k): v
+            for k, v in context.items()
+        }
+
+
+@dataclass(frozen=True)
+class NotificationTemplate:
+    """
+    Unified template value object supporting local and external rendering.
+
+    LOCAL mode:
+        body is the actual content with $variable placeholders.
+        Rendered here using Python's string.Template.
+
+    EXTERNAL mode:
+        body is the external template ID (e.g. Twilio SID "HXabc123",
+        SendGrid ID "d-abc123", Mailgun template name "otp-email").
+        variable_mapping translates our context to provider-expected keys.
+        Provider receives the ID + translated variables — renders on their end.
+    """
+
+    id: str
+    body: str                                          # content OR external template ID
+    mode: TemplateMode = TemplateMode.LOCAL
+    subject: str | None = None                        # email subject (LOCAL mode)
+    variable_mapping: VariableMapping = field(default_factory=VariableMapping)
+
+    @property
+    def is_external(self) -> bool:
+        return self.mode == TemplateMode.EXTERNAL
+
+    @property
+    def external_template_id(self) -> str:
+        """Alias for clarity when in EXTERNAL mode."""
+        if not self.is_external:
+            raise ValueError("external_template_id is only valid in EXTERNAL mode")
+        return self.body
+
+    def render(self, context: dict[str, Any]) -> str:
+        """Render body locally. Only valid in LOCAL mode."""
+        if self.is_external:
+            raise ValueError(
+                "Cannot render locally — this template uses EXTERNAL mode. "
+                "Pass the template to the provider directly."
+            )
+        try:
+            return Template(self.body).substitute(context)
+        except KeyError as e:
+            raise ValueError(f"Missing template variable: {e}") from e
+
+    def render_subject(self, context: dict[str, Any]) -> str | None:
+        if not self.subject:
+            return None
+        try:
+            return Template(self.subject).substitute(context)
+        except KeyError as e:
+            raise ValueError(f"Missing subject variable: {e}") from e
+
+    def translate_variables(self, context: dict[str, Any]) -> dict[str, Any]:
+        """Translate context to provider-expected variable names."""
+        return self.variable_mapping.translate(context)

notifyfork/core/infrastructure/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class InfrastructureConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "notifyfork.core.infrastructure"
+    label = "notifyfork"

notifyfork/core/infrastructure/container/__init__.py

@@ -0,0 +1,3 @@
+from notifyfork.core.infrastructure.container.providers import Container
+
+__all__ = ["Container"]

notifyfork/core/infrastructure/container/providers.py

@@ -0,0 +1,218 @@
+"""
+Dependency container for NotifyFork.
+
+Reads environment variables and wires everything together.
+One place to look when adding a new provider or changing config.
+
+Usage:
+    from notifyfork.core.infrastructure.container.providers import Container
+
+    use_case = Container.send_notification_use_case()
+    await use_case.execute(dto)
+"""
+import os
+import logging
+from functools import lru_cache
+from typing import Any
+
+from notifyfork.core.application.interfaces.notification_provider import NotificationProvider
+from notifyfork.core.application.use_cases.send_notification import SendNotificationUseCase
+from notifyfork.core.infrastructure.repositories.notification_repository import DjangoNotificationRepository
+from notifyfork.core.infrastructure.repositories.template_repository import DatabaseTemplateRepository
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROVIDER_ORDER = [
+    "twilio_sms",
+    "twilio_whatsapp",
+    "sendgrid_email",
+    "resend_email",
+    "smtp_email",
+    "firebase_push",
+    "slack",
+]
+
+# Providers registered from outside the lib via @notifyfork.provider.
+# Duck-typed on purpose — no NotificationProvider subclassing required,
+# same as every built-in provider is only ever used through .name /
+# .send_with_template() / .supported_channels, never isinstance-checked.
+_extra_providers: list[Any] = []
+
+
+def _ordered(providers: list[NotificationProvider]) -> list[NotificationProvider]:
+    """
+    Orders providers for fallback. When more than one provider supports the
+    same channel (e.g. SendGrid + SMTP for email), SendNotificationUseCase
+    tries them in this order — first one that succeeds wins.
+
+    Override with NOTIFYFORK_PROVIDER_ORDER="sendgrid_email,smtp_email"
+    (comma-separated provider names). Anything registered but not listed
+    keeps its default position, appended after the ones you did list.
+    """
+    raw = os.environ.get("NOTIFYFORK_PROVIDER_ORDER")
+    order = [name.strip() for name in raw.split(",")] if raw else DEFAULT_PROVIDER_ORDER
+
+    by_name = {p.name: p for p in providers}
+    ordered = [by_name[name] for name in order if name in by_name]
+    remaining = [p for p in providers if p.name not in order]
+    return ordered + remaining
+
+
+def _build_providers() -> list[NotificationProvider]:
+    """
+    Instantiates only the providers that have credentials configured.
+    Missing credentials → provider is skipped with a warning.
+    This lets you run locally with only the providers you need.
+    """
+    providers = []
+
+    # Twilio SMS
+    twilio_sid = os.environ.get("TWILIO_ACCOUNT_SID")
+    twilio_token = os.environ.get("TWILIO_AUTH_TOKEN")
+    twilio_from = os.environ.get("TWILIO_FROM_NUMBER")
+
+    if all([twilio_sid, twilio_token, twilio_from]):
+        from notifyfork.core.infrastructure.providers.twilio_provider import TwilioSMSProvider
+        providers.append(TwilioSMSProvider(twilio_sid, twilio_token, twilio_from))
+        logger.info("Provider registered: twilio_sms")
+    else:
+        logger.warning("twilio_sms skipped — missing TWILIO_ACCOUNT_SID / AUTH_TOKEN / FROM_NUMBER")
+
+    # Twilio WhatsApp
+    twilio_wa_from = os.environ.get("TWILIO_WHATSAPP_FROM_NUMBER")
+
+    if all([twilio_sid, twilio_token, twilio_wa_from]):
+        from notifyfork.core.infrastructure.providers.whatsapp_provider import TwilioWhatsAppProvider
+        providers.append(TwilioWhatsAppProvider(twilio_sid, twilio_token, twilio_wa_from))
+        logger.info("Provider registered: twilio_whatsapp")
+    else:
+        logger.warning("twilio_whatsapp skipped — missing TWILIO_WHATSAPP_FROM_NUMBER")
+
+    # SendGrid Email
+    sendgrid_key = os.environ.get("SENDGRID_API_KEY")
+    sendgrid_from = os.environ.get("SENDGRID_FROM_EMAIL")
+    sendgrid_name = os.environ.get("SENDGRID_FROM_NAME", "NotifyFork")
+
+    if all([sendgrid_key, sendgrid_from]):
+        from notifyfork.core.infrastructure.providers.sendgrid_provider import SendGridEmailProvider
+        providers.append(SendGridEmailProvider(sendgrid_key, sendgrid_from, sendgrid_name))
+        logger.info("Provider registered: sendgrid_email")
+    else:
+        logger.warning("sendgrid_email skipped — missing SENDGRID_API_KEY / FROM_EMAIL")
+
+    # Resend Email
+    resend_key = os.environ.get("RESEND_API_KEY")
+    resend_from = os.environ.get("RESEND_FROM_EMAIL")
+    resend_name = os.environ.get("RESEND_FROM_NAME", "")
+
+    if all([resend_key, resend_from]):
+        from notifyfork.core.infrastructure.providers.resend_provider import ResendEmailProvider
+        providers.append(ResendEmailProvider(resend_key, resend_from, resend_name))
+        logger.info("Provider registered: resend_email")
+    else:
+        logger.warning("resend_email skipped — missing RESEND_API_KEY / FROM_EMAIL")
+
+    # SMTP Email (fallback)
+    smtp_host = os.environ.get("SMTP_HOST")
+    smtp_user = os.environ.get("SMTP_USERNAME")
+    smtp_pass = os.environ.get("SMTP_PASSWORD")
+    smtp_from = os.environ.get("SMTP_FROM_EMAIL")
+
+    if all([smtp_host, smtp_user, smtp_pass, smtp_from]):
+        from notifyfork.core.infrastructure.providers.smtp_provider import SMTPEmailProvider
+        providers.append(SMTPEmailProvider(
+            host=smtp_host,
+            port=int(os.environ.get("SMTP_PORT", "465")),
+            username=smtp_user,
+            password=smtp_pass,
+            from_email=smtp_from,
+        ))
+        logger.info("Provider registered: smtp_email")
+    else:
+        logger.warning("smtp_email skipped — missing SMTP_HOST / USERNAME / PASSWORD / FROM_EMAIL")
+
+    # Firebase Push
+    firebase_creds = os.environ.get("FIREBASE_CREDENTIALS_PATH")
+
+    if firebase_creds:
+        from notifyfork.core.infrastructure.providers.firebase_provider import FirebasePushProvider
+        providers.append(FirebasePushProvider())
+        logger.info("Provider registered: firebase_push")
+    else:
+        logger.warning("firebase_push skipped — missing FIREBASE_CREDENTIALS_PATH")
+
+    # Slack
+    slack_token = os.environ.get("SLACK_BOT_TOKEN")
+
+    if slack_token:
+        from notifyfork.core.infrastructure.providers.slack_provider import SlackProvider
+        providers.append(SlackProvider(bot_token=slack_token))
+        logger.info("Provider registered: slack")
+    else:
+        logger.warning("slack skipped — missing SLACK_BOT_TOKEN")
+
+    providers.extend(_extra_providers)
+
+    if not providers:
+        logger.error("No providers registered — check your environment variables")
+
+    return _ordered(providers)
+
+
+class Container:
+    """
+    Simple service locator. Not a full DI framework on purpose —
+    keeps the dependency graph explicit and easy to follow.
+    """
+
+    @staticmethod
+    @lru_cache(maxsize=1)
+    def providers() -> list[NotificationProvider]:
+        return _build_providers()
+
+    @staticmethod
+    def notification_repository() -> DjangoNotificationRepository:
+        return DjangoNotificationRepository()
+
+    @staticmethod
+    def template_repository() -> DatabaseTemplateRepository:
+        return DatabaseTemplateRepository()
+
+    @staticmethod
+    def send_notification_use_case() -> SendNotificationUseCase:
+        return SendNotificationUseCase(
+            repository=Container.notification_repository(),
+            template_repository=Container.template_repository(),
+            providers=Container.providers(),
+        )
+
+
+def provider(provider_cls: type) -> type:
+    """
+    Decorator that registers a custom provider from outside the lib.
+
+    No need to subclass NotificationProvider — duck-typing, same as every
+    built-in provider (the container only ever reads .name and calls
+    .send_with_template()). Just instantiate-and-go:
+
+        import notifyfork
+
+        @notifyfork.provider
+        class XptoProvider:
+            name = "xpto"
+            def send_with_template(self, recipient, template, context): ...
+
+    The class is instantiated with no arguments, so anything it needs
+    (API keys, clients, etc.) should be read in __init__ from the
+    environment, same as the built-in providers do in _build_providers().
+    """
+    instance = provider_cls()
+    _extra_providers.append(instance)
+
+    # Container.providers() is lru_cache'd — if something already read it
+    # before this decorator ran, drop the stale result so the new provider
+    # is picked up on the next call.
+    Container.providers.cache_clear()
+
+    logger.info("Provider registered: %s", getattr(instance, "name", provider_cls.__name__))
+    return provider_cls

notifyfork/core/infrastructure/migrations/0001_initial.py

@@ -0,0 +1,48 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="NotificationModel",
+            fields=[
+                ("id", models.UUIDField(primary_key=True, editable=False)),
+                ("recipient", models.CharField(max_length=255)),
+                ("channel", models.CharField(max_length=20)),
+                ("notification_type", models.CharField(max_length=20)),
+                ("template_id", models.CharField(max_length=100)),
+                ("context", models.JSONField(default=dict)),
+                ("status", models.CharField(max_length=20, default="pending", db_index=True)),
+                ("provider_used", models.CharField(max_length=50, null=True, blank=True)),
+                ("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)),
+            ],
+            options={"db_table": "notifyfork_notifications", "ordering": ["-created_at"]},
+        ),
+        migrations.AddIndex(
+            model_name="NotificationModel",
+            index=models.Index(fields=["status", "attempts"], name="idx_status_attempts"),
+        ),
+        migrations.CreateModel(
+            name="NotificationTemplateModel",
+            fields=[
+                ("id", models.CharField(max_length=100, primary_key=True)),
+                ("body", models.TextField()),
+                ("subject", models.CharField(max_length=255, null=True, blank=True)),
+                ("mode", models.CharField(max_length=10, default="local")),
+                ("variable_mapping", models.JSONField(default=dict)),
+                ("is_active", models.BooleanField(default=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={"db_table": "notifyfork_templates"},
+        ),
+    ]