sub-amigo 0.1.0__py3-none-any.whl

sub_amigo/__init__.py

@@ -0,0 +1,8 @@
+from .adapters.base import BaseNotificationAdapter, NotificationPayload
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseNotificationAdapter",
+    "NotificationPayload",
+]

sub_amigo/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseNotificationAdapter, NotificationPayload
+
+__all__ = ["BaseNotificationAdapter", "NotificationPayload"]

sub_amigo/adapters/base.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class NotificationPayload:
+    """
+    Immutable value object passed to every notification adapter.
+
+    Attributes:
+        recipient:  Opaque string identifying the notification target
+                    (e.g. email address, Slack channel, user ID).
+                    The adapter implementation decides how to interpret it.
+        subject:    Short summary line suitable for email subjects or
+                    push notification titles.
+        message:    Fully-rendered body text.
+        metadata:   Arbitrary key/value bag for adapter-specific extras
+                    (e.g. subscription_id, billing_date).
+    """
+
+    recipient: str
+    subject: str
+    message: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseNotificationAdapter(ABC):
+    """
+    Contract that all notification adapters must satisfy.
+
+    The engine calls ``send()`` with a ``NotificationPayload`` and expects a
+    boolean result.  Concrete implementations must handle their own errors
+    internally and must not raise — return ``False`` instead.
+
+    Example implementation::
+
+        class EmailAdapter(BaseNotificationAdapter):
+            def send(self, payload: NotificationPayload) -> bool:
+                try:
+                    send_mail(
+                        subject=payload.subject,
+                        message=payload.message,
+                        from_email=settings.DEFAULT_FROM_EMAIL,
+                        recipient_list=[payload.recipient],
+                    )
+                    return True
+                except Exception:
+                    logger.exception("Email dispatch failed")
+                    return False
+    """
+
+    @abstractmethod
+    def send(self, payload: NotificationPayload) -> bool:
+        """
+        Dispatch the notification payload to the recipient.
+
+        Returns:
+            ``True`` if the notification was delivered successfully.
+            ``False`` if delivery failed for any reason.
+        """

sub_amigo/admin.py

@@ -0,0 +1,44 @@
+from django.contrib import admin
+
+from .models import NotificationLog, ReminderRule, Subscription
+
+
+class ReminderRuleInline(admin.TabularInline):
+    model = ReminderRule
+    extra = 0
+    fields = ("days_before", "message_template", "is_active")
+
+
+@admin.register(Subscription)
+class SubscriptionAdmin(admin.ModelAdmin):
+    list_display = ("name", "status", "billing_interval", "cost", "currency", "next_billing_date", "owner_ref")
+    list_filter = ("status", "billing_interval", "currency")
+    search_fields = ("name", "owner_ref", "recipient_ref")
+    ordering = ("next_billing_date",)
+    readonly_fields = ("id", "created_at", "updated_at")
+    inlines = [ReminderRuleInline]
+
+
+@admin.register(NotificationLog)
+class NotificationLogAdmin(admin.ModelAdmin):
+    list_display = ("subscription", "billing_cycle_date", "status", "triggered_at")
+    list_filter = ("status",)
+    search_fields = ("subscription__name", "recipient_ref")
+    ordering = ("-triggered_at",)
+    readonly_fields = (
+        "id",
+        "reminder_rule",
+        "subscription",
+        "billing_cycle_date",
+        "recipient_ref",
+        "rendered_message",
+        "status",
+        "error_detail",
+        "triggered_at",
+    )
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False

sub_amigo/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class SubAmigoConfig(AppConfig):
+    name = "sub_amigo"
+    verbose_name = "Sub-Amigo"
+    default_auto_field = "django.db.models.BigAutoField"

sub_amigo/engine/__init__.py

@@ -0,0 +1,3 @@
+from .reminder_engine import ProcessingResult, ReminderResult, SubscriptionReminderEngine
+
+__all__ = ["ProcessingResult", "ReminderResult", "SubscriptionReminderEngine"]

sub_amigo/engine/reminder_engine.py

@@ -0,0 +1,272 @@
+import logging
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from typing import Optional
+
+from ..adapters.base import BaseNotificationAdapter, NotificationPayload
+from ..exceptions import EngineConfigurationError, TemplateRenderError
+from ..models.notification_log import NotificationLog, NotificationStatus
+from ..models.reminder_rule import ReminderRule
+from ..models.subscription import Subscription, SubscriptionStatus
+from ..signals import reminder_failed, reminder_sent
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReminderResult:
+    rule_id: str
+    subscription_id: str
+    subscription_name: str
+    success: bool
+    skipped: bool = False
+    error: Optional[str] = None
+
+
+@dataclass
+class ProcessingResult:
+    run_date: date = field(default_factory=date.today)
+    processed: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    skipped: int = 0
+    results: list[ReminderResult] = field(default_factory=list)
+
+
+class SubscriptionReminderEngine:
+    """
+    Core processing engine. Finds all reminder rules due on a given date,
+    renders each rule's message template, dispatches notifications via the
+    injected adapter, and writes idempotency records to NotificationLog.
+
+    Usage::
+
+        engine = SubscriptionReminderEngine(adapter=MyEmailAdapter())
+        result = engine.process_daily_reminders()
+    """
+
+    _DEFAULT_SUBJECT = "Reminder: {subscription_name} renews on {next_billing_date}"
+
+    def __init__(self, adapter: BaseNotificationAdapter) -> None:
+        if not isinstance(adapter, BaseNotificationAdapter):
+            raise EngineConfigurationError(
+                f"adapter must subclass BaseNotificationAdapter, got {type(adapter).__name__!r}."
+            )
+        self._adapter = adapter
+
+    def process_daily_reminders(self, today: Optional[date] = None) -> ProcessingResult:
+        """
+        Entry point for scheduled execution (cron, Celery beat, management command).
+
+        For each active ReminderRule whose trigger date (next_billing_date - days_before)
+        equals ``today``, the engine:
+
+        1. Skips rules already logged for this billing cycle (idempotent).
+        2. Renders the message template.
+        3. Calls adapter.send().
+        4. Persists a NotificationLog entry.
+
+        The ``today`` parameter is intentionally injectable for deterministic testing.
+        """
+        run_date = today or date.today()
+        result = ProcessingResult(run_date=run_date)
+
+        due_rules = self._get_due_rules(run_date)
+
+        for rule in due_rules:
+            reminder_result = self._process_rule(rule, run_date)
+            result.processed += 1
+            result.results.append(reminder_result)
+
+            if reminder_result.skipped:
+                result.skipped += 1
+            elif reminder_result.success:
+                result.succeeded += 1
+            else:
+                result.failed += 1
+
+        logger.info(
+            "sub_amigo run_date=%s processed=%d succeeded=%d failed=%d skipped=%d",
+            run_date,
+            result.processed,
+            result.succeeded,
+            result.failed,
+            result.skipped,
+        )
+        return result
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_due_rules(self, run_date: date) -> list[ReminderRule]:
+        """
+        Return all active ReminderRules whose trigger date equals run_date,
+        excluding any already logged for their subscription's current billing cycle.
+
+        Strategy: fetch the distinct days_before values first (tiny query), then
+        issue one targeted query per unique offset. This avoids DB-side date
+        arithmetic and is portable across SQLite, PostgreSQL, and MySQL.
+        """
+        distinct_offsets: list[int] = list(
+            ReminderRule.objects.filter(
+                is_active=True,
+                subscription__status=SubscriptionStatus.ACTIVE,
+            )
+            .values_list("days_before", flat=True)
+            .distinct()
+        )
+
+        due_rules: list[ReminderRule] = []
+
+        for offset in distinct_offsets:
+            target_billing_date = run_date + timedelta(days=offset)
+
+            rules = (
+                ReminderRule.objects.filter(
+                    is_active=True,
+                    days_before=offset,
+                    subscription__status=SubscriptionStatus.ACTIVE,
+                    subscription__next_billing_date=target_billing_date,
+                )
+                .select_related("subscription")
+                .exclude(notification_logs__billing_cycle_date=target_billing_date)
+            )
+
+            due_rules.extend(rules)
+
+        return due_rules
+
+    def _process_rule(self, rule: ReminderRule, run_date: date) -> ReminderResult:
+        subscription: Subscription = rule.subscription
+        billing_date = subscription.next_billing_date
+
+        # Final idempotency guard against concurrent engine runs.
+        if NotificationLog.objects.filter(
+            reminder_rule=rule,
+            billing_cycle_date=billing_date,
+        ).exists():
+            logger.debug(
+                "sub_amigo skipping rule=%s subscription=%s billing_date=%s (already logged)",
+                rule.id,
+                subscription.id,
+                billing_date,
+            )
+            return ReminderResult(
+                rule_id=str(rule.id),
+                subscription_id=str(subscription.id),
+                subscription_name=subscription.name,
+                success=True,
+                skipped=True,
+            )
+
+        try:
+            rendered_message = self._render_template(rule, subscription)
+        except TemplateRenderError as exc:
+            logger.error("sub_amigo template error rule=%s: %s", rule.id, exc)
+            log = NotificationLog.objects.create(
+                reminder_rule=rule,
+                subscription=subscription,
+                billing_cycle_date=billing_date,
+                recipient_ref=subscription.recipient_ref,
+                rendered_message="",
+                status=NotificationStatus.FAILED,
+                error_detail=str(exc),
+            )
+            reminder_failed.send(
+                sender=self.__class__,
+                subscription=subscription,
+                rule=rule,
+                error=str(exc),
+                log=log,
+            )
+            return ReminderResult(
+                rule_id=str(rule.id),
+                subscription_id=str(subscription.id),
+                subscription_name=subscription.name,
+                success=False,
+                error=str(exc),
+            )
+
+        subject = self._DEFAULT_SUBJECT.format(
+            subscription_name=subscription.name,
+            next_billing_date=billing_date.isoformat(),
+        )
+        payload = NotificationPayload(
+            recipient=subscription.recipient_ref,
+            subject=subject,
+            message=rendered_message,
+            metadata={
+                "subscription_id": str(subscription.id),
+                "billing_date": billing_date.isoformat(),
+                "days_before": rule.days_before,
+                "currency": subscription.currency,
+                "cost": str(subscription.cost),
+            },
+        )
+
+        success = False
+        error_detail = ""
+
+        try:
+            success = self._adapter.send(payload)
+        except Exception as exc:
+            # Adapters should not raise, but we guard defensively.
+            error_detail = f"{type(exc).__name__}: {exc}"
+            logger.exception(
+                "sub_amigo adapter raised for rule=%s subscription=%s",
+                rule.id,
+                subscription.id,
+            )
+
+        log = NotificationLog.objects.create(
+            reminder_rule=rule,
+            subscription=subscription,
+            billing_cycle_date=billing_date,
+            recipient_ref=subscription.recipient_ref,
+            rendered_message=rendered_message,
+            status=NotificationStatus.SENT if success else NotificationStatus.FAILED,
+            error_detail=error_detail,
+        )
+
+        if success:
+            reminder_sent.send(
+                sender=self.__class__,
+                subscription=subscription,
+                rule=rule,
+                payload=payload,
+                log=log,
+            )
+        else:
+            reminder_failed.send(
+                sender=self.__class__,
+                subscription=subscription,
+                rule=rule,
+                error=error_detail,
+                log=log,
+            )
+
+        return ReminderResult(
+            rule_id=str(rule.id),
+            subscription_id=str(subscription.id),
+            subscription_name=subscription.name,
+            success=success,
+            error=error_detail or None,
+        )
+
+    @staticmethod
+    def _render_template(rule: ReminderRule, subscription: Subscription) -> str:
+        context = {
+            "subscription_name": subscription.name,
+            "cost": subscription.cost,
+            "currency": subscription.currency,
+            "next_billing_date": subscription.next_billing_date.isoformat(),
+            "days_before": rule.days_before,
+            "description": subscription.description,
+        }
+        try:
+            return rule.message_template.format_map(context)
+        except KeyError as exc:
+            raise TemplateRenderError(
+                f"Unknown template variable {exc} in ReminderRule {rule.id}."
+            ) from exc

sub_amigo/exceptions.py

@@ -0,0 +1,10 @@
+class SubAmigoError(Exception):
+    """Base exception for all sub-amigo errors."""
+
+
+class EngineConfigurationError(SubAmigoError):
+    """Raised when the engine is constructed with an invalid adapter."""
+
+
+class TemplateRenderError(SubAmigoError):
+    """Raised when a message template references an unknown variable."""

sub_amigo/management/commands/process_reminders.py

@@ -0,0 +1,67 @@
+import importlib
+from datetime import date
+
+from django.conf import settings
+from django.core.management.base import BaseCommand, CommandError
+
+from sub_amigo.adapters.base import BaseNotificationAdapter
+from sub_amigo.engine.reminder_engine import SubscriptionReminderEngine
+
+
+class Command(BaseCommand):
+    help = "Process subscription reminders due today (or a given date)."
+
+    def add_arguments(self, parser) -> None:
+        parser.add_argument(
+            "--date",
+            type=date.fromisoformat,
+            default=None,
+            metavar="YYYY-MM-DD",
+            help="Process reminders for this date instead of today.",
+        )
+
+    def handle(self, *args, **options) -> None:
+        adapter = self._load_adapter()
+        engine = SubscriptionReminderEngine(adapter=adapter)
+        result = engine.process_daily_reminders(today=options["date"])
+
+        self.stdout.write(
+            f"Processed {result.processed} reminder(s) for {result.run_date}: "
+            f"{result.succeeded} sent, {result.failed} failed, {result.skipped} skipped."
+        )
+
+        for r in result.results:
+            if not r.success and not r.skipped:
+                self.stderr.write(
+                    f"  FAILED  rule={r.rule_id} subscription={r.subscription_name!r}"
+                    + (f" — {r.error}" if r.error else "")
+                )
+
+        if result.failed:
+            raise CommandError(f"{result.failed} reminder(s) failed to send.")
+
+    @staticmethod
+    def _load_adapter() -> BaseNotificationAdapter:
+        dotted_path: str = getattr(settings, "SUB_AMIGO_ADAPTER", "")
+        if not dotted_path:
+            raise CommandError(
+                "SUB_AMIGO_ADAPTER is not configured. "
+                "Add it to your Django settings, e.g.:\n"
+                "  SUB_AMIGO_ADAPTER = 'myapp.adapters.EmailAdapter'"
+            )
+
+        module_path, class_name = dotted_path.rsplit(".", 1)
+        try:
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+        except (ImportError, AttributeError) as exc:
+            raise CommandError(
+                f"Could not import SUB_AMIGO_ADAPTER {dotted_path!r}: {exc}"
+            ) from exc
+
+        if not (isinstance(cls, type) and issubclass(cls, BaseNotificationAdapter)):
+            raise CommandError(
+                f"{dotted_path!r} must be a subclass of BaseNotificationAdapter."
+            )
+
+        return cls()