wagtail-newsletter-django-backend 0.0.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

wagtail_newsletter_django_backend/__init__.py

@@ -3,4 +3,4 @@
 This is a simple, basic internal backend for wagtail-newsletter, allowing you to manage your mailing lists internally and send them out through Django's standard email capabilities.
 '''
 
-__version__ = '0.0.2'
+__version__ = '0.2.0'

wagtail_newsletter_django_backend/admin_viewsets.py

@@ -0,0 +1,58 @@
+from typing import final
+from wagtail.admin.viewsets.model import ModelViewSet, ModelViewSetGroup
+from .models import Audience, AudienceSegment, Subscriber, Campaign
+
+@final
+class AudienceViewSet(ModelViewSet):
+    model = Audience
+    form_fields = ['site', 'name', 'description', 'smtp_user', 'smtp_password', 'from_email_address', 'from_email_name']
+    list_display = ['site', 'name', 'description']  # pyright: ignore[reportAssignmentType]
+    icon = 'group'
+    add_to_admin_menu = False
+    copy_view_enabled = True
+    inspect_view_enabled = True
+
+@final
+class AudienceSegmentViewSet(ModelViewSet):
+    model = AudienceSegment
+    form_fields = ['name', 'audience', 'description']
+    list_display = ['name', 'audience', 'description']  # pyright: ignore[reportAssignmentType]
+    icon = 'tag'
+    add_to_admin_menu = False
+    copy_view_enabled = True
+    inspect_view_enabled = True
+
+@final
+class SubscriberViewSet(ModelViewSet):
+    model = Subscriber
+    form_fields = ['email_address', 'email_name', 'audience', 'audience_segments']
+    list_display = ['email_address', 'email_name', 'audience']  # pyright: ignore[reportAssignmentType]
+    icon = 'user'
+    add_to_admin_menu = False
+    copy_view_enabled = True
+    inspect_view_enabled = True
+
+@final
+class CampaignViewSet(ModelViewSet):
+    model = Campaign
+    form_fields = ['subject', 'audience_segment', 'send_at', 'sent_at', 'html']
+    list_display = ['subject', 'audience_segment']  # pyright: ignore[reportAssignmentType]
+    icon = 'mail'
+    add_to_admin_menu = False
+    copy_view_enabled = True
+    inspect_view_enabled = True
+
+@final
+class MailingListGroup(ModelViewSetGroup):
+    items = (
+        AudienceViewSet('audiences'),
+        AudienceSegmentViewSet('audience_segments'),
+        SubscriberViewSet('subscribers'),
+        CampaignViewSet('campaign'),
+    )
+    menu_icon = 'mail'
+    menu_label = 'Mailing List'  # pyright: ignore[reportAssignmentType]
+
+mailing_list_group = MailingListGroup()
+
+# Create your views here.

wagtail_newsletter_django_backend/apps.py

@@ -1,6 +1,8 @@
+from typing import final
 from django.apps import AppConfig
 
-
+@final
 class WagtailNewsletterDjangoBackendConfig(AppConfig):
     default_auto_field = 'django.db.models.BigAutoField'
     name = 'wagtail_newsletter_django_backend'
+    verbose_name = 'Wagtail Newsletter Django Backend'

wagtail_newsletter_django_backend/campaign_backend.py

@@ -0,0 +1,180 @@
+from datetime import datetime
+from typing import Any, cast, override
+from django.db import transaction
+from django.core.mail import send_mail
+from django.urls import reverse
+from django.utils import timezone
+from html2text import HTML2Text
+from django.core.mail import get_connection
+from django.core.mail.message import EmailMessage, EmailMultiAlternatives
+from wagtail_newsletter import campaign_backends as wncb, audiences as wna, models as wnm
+import re
+from . import models
+
+_unsubscribe_re = re.compile(r'\[\[unsubscribe\]\]|\\[\\[unsubscribe\\]\\]')
+_manage_re = re.compile(r'\[\[manage\]\]|\\[\\[manage\\]\\]')
+
+h2t = HTML2Text()
+class CampaignBackend(wncb.CampaignBackend):
+    name: str = 'Django Backend'
+
+    @override
+    def get_audiences(self) -> "list[wna.Audience]":
+        return [
+            wna.Audience(
+                id=str(audience.id),
+                pk=str(audience.pk),
+                name=audience.name,
+                member_count=audience.subscriber_set.count(),
+            )
+            for audience in models.Audience.objects.all()
+        ]
+
+    @override
+    def get_audience_segments(
+        self,
+        audience_id: str
+    ) -> "list[wna.AudienceSegment]":
+        audience = models.Audience.objects.get(id=int(audience_id))
+        return [
+            wna.AudienceSegment(
+                id=str(audience_segment.id),
+                pk=str(audience_segment.pk),
+                name=audience_segment.name,
+                member_count=audience_segment.subscribers.count(),
+            )
+            for audience_segment in audience.audience_segment_set.all()
+        ]
+
+    @override
+    def save_campaign(
+        self,
+        *,
+        campaign_id: str | None = None,
+        recipients: "wnm.NewsletterRecipientsBase | None",
+        subject: str,
+        html: str,
+    ) -> str:
+        audience_segment: models.AudienceSegment | None = None
+        if recipients is not None and recipients.segment:
+            audience_segment = models.AudienceSegment.objects.get(id=int(recipients.segment))
+
+        with transaction.atomic():
+            campaign: models.Campaign
+            if campaign_id:
+                campaign = models.Campaign.objects.get(id=int(campaign_id))
+                campaign.subject = subject
+                campaign.html = html.strip()
+                if audience_segment is not None:
+                    campaign.audience_segment = audience_segment
+                campaign.full_clean()
+                campaign.save()
+            else:
+                campaign = models.Campaign.objects.create(
+                    subject=subject,
+                    html=html.strip(),
+                    audience_segment=audience_segment,
+                )
+            return str(campaign.id)
+
+    @override
+    def get_campaign(self, campaign_id: str) -> wncb.Campaign | None:
+        return cast('wncb.Campaign | None', models.Campaign.objects.filter(id=int(campaign_id)).first())
+
+    @override
+    def send_test_email(self, *, campaign_id: str, email: str) -> None:
+        campaign = models.Campaign.objects.get(id=int(campaign_id))
+        audience = campaign.audience_segment.audience
+
+        from_address = audience.from_address()
+        user, password = audience.smtp_auth()
+
+        _ = send_mail(
+            subject=campaign.subject,
+            message=h2t.handle(campaign.html),
+            from_email=from_address,
+            recipient_list=[email],
+            html_message=campaign.html,
+            auth_user=user,
+            auth_password=password,
+        )
+
+    @override
+    def send_campaign(self, campaign_id: str) -> None:
+        with transaction.atomic():
+            campaign = models.Campaign.objects.get(id=int(campaign_id))
+            audience = campaign.audience_segment.audience
+
+            site = audience.site
+            hostname = site.hostname
+            match site.port:
+                case 80:
+                    url_base = f'http://{hostname}'
+                case 443:
+                    url_base = f'https://{hostname}'
+                case port:
+                    url_base = f'http://{hostname}:{port}'
+
+            from_address = audience.from_address()
+            user, password = audience.smtp_auth()
+
+            connection: Any = get_connection(  # pyright: ignore[reportAny]
+                username=user,
+                password=password,
+            )
+
+            def subscriber_message(subscriber: models.Subscriber) -> EmailMessage:
+                unsubscribe_url = url_base + reverse('newsletter_subscriber_unsubscribe', kwargs={'key': subscriber.key})
+                manage_url = url_base + reverse('newsletter_subscriber_manage', kwargs={'key': subscriber.key})
+                html = _manage_re.sub(manage_url, _unsubscribe_re.sub(unsubscribe_url, campaign.html))
+                message = h2t.handle(html)
+                mail = EmailMultiAlternatives(
+                    subject=campaign.subject,
+                    body=message,
+                    from_email=from_address,
+                    to=[subscriber.email()],
+                    connection=connection,  # pyright: ignore[reportAny]
+                    headers={
+                        "List-Unsubscribe": unsubscribe_url,
+                        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+                    },
+                )
+                mail.attach_alternative(html, "text/html")
+                return mail
+
+            messages = [
+                subscriber_message(subscriber)
+                for subscriber in campaign.audience_segment.subscribers.filter(verified=True)
+            ]
+
+            _ = connection.send_messages(messages)  # pyright: ignore[reportAny]
+            campaign.sent_at = timezone.now()
+            campaign.save()
+            _ = models.SentMessage.objects.bulk_create([
+                models.SentMessage(
+                    campaign=campaign,
+                    subscriber=subscriber,
+                    subscriber_hash=subscriber.pii_hash(),
+                )
+                for subscriber in campaign.audience_segment.subscribers.filter(verified=True)
+            ])
+
+    def send_scheduled_campaigns(self) -> None:
+        for campaign in models.Campaign.objects.filter(sent_at=None, send_at__gte=timezone.now()):
+            self.send_campaign(str(campaign.id))
+
+    @override
+    def schedule_campaign(self, campaign_id: str, schedule_time: datetime) -> None:
+        with transaction.atomic():
+            campaign = models.Campaign.objects.get(id=int(campaign_id))
+            campaign.send_at = schedule_time
+            campaign.full_clean()
+            campaign.save()
+
+    @override
+    def unschedule_campaign(self, campaign_id: str) -> None:
+        with transaction.atomic():
+            campaign = models.Campaign.objects.get(id=int(campaign_id))
+            campaign.send_at = None
+            campaign.full_clean()
+            campaign.save()

wagtail_newsletter_django_backend/forms.py

@@ -0,0 +1,97 @@
+from collections.abc import Collection, Iterable
+from typing import cast, override
+from django import forms
+from . import models
+
+class ManageForm(forms.ModelForm):
+    '''
+    Form for managing subscriptions.
+
+    This must be constructed with the relevant instance.  If the instance is
+    changed after the fact, the segments will not be correct.
+    '''
+    instance: models.Subscriber
+    audience_segments: forms.ModelMultipleChoiceField = forms.ModelMultipleChoiceField(
+        label='Categories',
+        queryset=None,  # pyright: ignore[reportArgumentType]
+        widget=forms.CheckboxSelectMultiple(),
+        required=False,
+    )
+    
+    class Meta:
+        model: type[models.Subscriber] = models.Subscriber
+        fields: Collection[str] = ('email_name', 'audience_segments')
+    
+    def __init__(self, *args, **kwargs):  # pyright: ignore[reportUnknownParameterType, reportMissingParameterType]
+        super().__init__(*args, **kwargs)  # pyright: ignore[reportUnknownArgumentType]
+        
+        # Filter audience_segments to only show those belonging to this subscriber's audience
+        if self.instance:
+            cast(
+                 forms.ModelMultipleChoiceField,
+                 self.fields['audience_segments'],
+             ).queryset = models.AudienceSegment.objects.filter(
+                audience=self.instance.audience
+            )
+    
+    @override
+    def save(self, commit: bool = True) -> models.Subscriber:
+        # Save the subscriber instance first
+        subscriber = cast(models.Subscriber, super().save(commit=commit))
+        
+        if commit:
+            # Clear existing subscriptions and create new ones based on selected segments
+            _ = models.Subscription.objects.filter(subscriber=subscriber).delete()
+            
+            for segment in cast(Iterable[models.AudienceSegment], self.cleaned_data['audience_segments']):
+                _ = models.Subscription.objects.create(
+                    subscriber=subscriber,
+                    audience_segment=segment
+                )
+        
+        return subscriber
+
+class SignupForm(forms.ModelForm):
+    '''
+    Form for creating subscriptions.
+    '''
+    instance: models.Subscriber
+    audience: forms.ModelChoiceField = forms.ModelChoiceField(
+        queryset=models.Audience.objects.all(),
+        widget=forms.HiddenInput(),
+    )
+    audience_segments: forms.ModelMultipleChoiceField = forms.ModelMultipleChoiceField(
+        label='Categories',
+        queryset=None,  # pyright: ignore[reportArgumentType]
+        widget=forms.CheckboxSelectMultiple(),
+        required=False,
+    )
+    
+    class Meta:
+        model: type[models.Subscriber] = models.Subscriber
+        fields: Collection[str] = ('email_name', 'email_address', 'audience', 'audience_segments')
+    
+    def __init__(self, *args, audience: models.Audience, **kwargs):  # pyright: ignore[reportUnknownParameterType, reportMissingParameterType]
+        super().__init__(*args, **kwargs)  # pyright: ignore[reportUnknownArgumentType]
+        # Filter audience_segments to only show those belonging to this subscriber's audience
+        cast(
+            forms.ModelMultipleChoiceField,
+            self.fields['audience_segments'],
+        ).queryset = audience.audience_segment_set.all()
+
+    @override
+    def save(self, commit: bool = True) -> models.Subscriber:
+        # Save the subscriber instance first
+        subscriber = cast(models.Subscriber, super().save(commit=commit))
+        
+        if commit:
+            # Clear existing subscriptions and create new ones based on selected segments
+            _ = models.Subscription.objects.filter(subscriber=subscriber).delete()
+            
+            for segment in cast(Iterable[models.AudienceSegment], self.cleaned_data['audience_segments']):
+                _ = models.Subscription.objects.create(
+                    subscriber=subscriber,
+                    audience_segment=segment
+                )
+        
+        return subscriber

wagtail_newsletter_django_backend/management/commands/send_scheduled_campaigns.py

@@ -0,0 +1,8 @@
+from django.core.management.base import BaseCommand, CommandError
+from wagtail_newsletter_django_backend.campaign_backend import CampaignBackend
+
+class Command(BaseCommand):
+    help = "Sends scheduled campaigns that are due"
+
+    def handle(self, *args, **options):
+        CampaignBackend().send_scheduled_campaigns()

wagtail_newsletter_django_backend/migrations/0001_initial.py

@@ -0,0 +1,291 @@
+# Generated by Django 5.2.5 on 2025-09-01 20:37
+
+import django.db.models.deletion
+import wagtail_newsletter_django_backend.models
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ("wagtailcore", "0095_groupsitepermission"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Audience",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("name", models.SlugField()),
+                ("description", models.TextField(blank=True)),
+                (
+                    "smtp_user",
+                    models.CharField(
+                        blank=True,
+                        default=None,
+                        help_text="The SMTP login user.  If absent, this will not be supplied to send_mail, and EMAIL_HOST_USER will be used instead",
+                        max_length=256,
+                        null=True,
+                    ),
+                ),
+                (
+                    "smtp_password",
+                    models.CharField(
+                        blank=True,
+                        default=None,
+                        help_text="The SMTP login password.  If absent, this will not be supplied to send_mail, and EMAIL_HOST_PASSWORD will be used instead",
+                        max_length=256,
+                        null=True,
+                    ),
+                ),
+                (
+                    "from_email_address",
+                    models.EmailField(
+                        blank=True,
+                        default=None,
+                        help_text="The From address for the email.  If not present, this will not be supplied to send_mail, and DEFAULT_FROM_EMAIL will be used instead",
+                        max_length=254,
+                        null=True,
+                    ),
+                ),
+                (
+                    "from_email_name",
+                    models.CharField(
+                        blank=True,
+                        default=None,
+                        help_text="The display name portion of the from email.  This will be wrapped around the from email address.",
+                        max_length=256,
+                        null=True,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "site",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtailcore.site",
+                    ),
+                ),
+            ],
+        ),
+        migrations.CreateModel(
+            name="AudienceSegment",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("name", models.SlugField(unique=True)),
+                ("description", models.TextField(blank=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "audience",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="audience_segment_set",
+                        related_query_name="audience_segment",
+                        to="wagtail_newsletter_django_backend.audience",
+                    ),
+                ),
+            ],
+        ),
+        migrations.CreateModel(
+            name="Campaign",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("send_at", models.DateTimeField(blank=True, default=None, null=True)),
+                ("sent_at", models.DateTimeField(blank=True, default=None, null=True)),
+                ("subject", models.TextField()),
+                ("html", models.TextField()),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "audience_segment",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtail_newsletter_django_backend.audiencesegment",
+                    ),
+                ),
+            ],
+        ),
+        migrations.CreateModel(
+            name="Subscriber",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "key",
+                    models.CharField(
+                        default=wagtail_newsletter_django_backend.models.generate_subscriber_key,
+                        help_text="The subscriber's lookup key for managing subscriptions",
+                        max_length=64,
+                        unique=True,
+                    ),
+                ),
+                ("email_address", models.EmailField(max_length=254)),
+                (
+                    "email_name",
+                    models.CharField(
+                        blank=True,
+                        default=None,
+                        help_text="The display name portion of the email address.",
+                        max_length=256,
+                        null=True,
+                    ),
+                ),
+                ("verified", models.BooleanField(default=False)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "audience",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtail_newsletter_django_backend.audience",
+                    ),
+                ),
+            ],
+        ),
+        migrations.CreateModel(
+            name="SentMessage",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("subscriber_hash", models.CharField(db_index=True, max_length=64)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "campaign",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="sent_message_set",
+                        related_query_name="sent_message",
+                        to="wagtail_newsletter_django_backend.campaign",
+                    ),
+                ),
+                (
+                    "subscriber",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="sent_message_set",
+                        related_query_name="sent_message",
+                        to="wagtail_newsletter_django_backend.subscriber",
+                    ),
+                ),
+            ],
+        ),
+        migrations.CreateModel(
+            name="Subscription",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "audience_segment",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtail_newsletter_django_backend.audiencesegment",
+                    ),
+                ),
+                (
+                    "subscriber",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to="wagtail_newsletter_django_backend.subscriber",
+                    ),
+                ),
+            ],
+        ),
+        migrations.AddField(
+            model_name="subscriber",
+            name="audience_segments",
+            field=models.ManyToManyField(
+                related_name="+",
+                through="wagtail_newsletter_django_backend.Subscription",
+                to="wagtail_newsletter_django_backend.audiencesegment",
+            ),
+        ),
+        migrations.AddField(
+            model_name="audiencesegment",
+            name="subscribers",
+            field=models.ManyToManyField(
+                related_name="+",
+                through="wagtail_newsletter_django_backend.Subscription",
+                to="wagtail_newsletter_django_backend.subscriber",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="audience",
+            constraint=models.UniqueConstraint(
+                fields=("site", "name"), name="unique_site_name"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="subscription",
+            constraint=models.UniqueConstraint(
+                fields=("audience_segment", "subscriber"),
+                name="unique_audience_segment_subscriber",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="subscriber",
+            constraint=models.UniqueConstraint(
+                fields=("audience", "email_address"),
+                name="unique_audience_email_address",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="audiencesegment",
+            constraint=models.UniqueConstraint(
+                fields=("audience", "name"), name="unique_audience_name"
+            ),
+        ),
+    ]

wagtail_newsletter_django_backend/models.py

@@ -1,3 +1,317 @@
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from functools import lru_cache
+import hashlib
+import hmac
+from typing import TYPE_CHECKING, Any, LiteralString, NotRequired, TypedDict, Unpack, override, cast
+from django.core.exceptions import ValidationError
+from django.urls import reverse
+from wagtail.models import Site
 from django.db import models
+from django.conf import settings
+from email.utils import parseaddr, formataddr
+import secrets
+import string
+from wagtail_newsletter import campaign_backends as wncb
 
-# Create your models here.
+if TYPE_CHECKING:
+    from django.db.models.manager import RelatedManager
+
+@lru_cache
+def _default_from_parts() -> tuple[str | None, str | None]:
+    email = cast(str | None, settings.DEFAULT_FROM_EMAIL)
+    name: str | None = None
+    if email:
+        name, email = parseaddr(email)
+        email = email or None
+        name = name or None
+    return name, email
+
+class SaveDict(TypedDict):
+    force_insert: NotRequired[bool]
+    force_update: NotRequired[bool]
+    using: NotRequired[str]
+    update_fields: NotRequired[Iterable[str]]
+
+def patch_blanks(record: models.Model, update_fields: Iterable[str] | None, keys: Iterable[str]) -> None:
+    '''Patch blank string fields to None.
+    '''
+    update_keys: Iterable[str]
+    if update_fields is None:
+        update_keys = keys
+    else:
+        update_keys = frozenset(update_fields) | frozenset(keys)
+
+    # Change all blank string fields to NULL
+    for key in update_keys:
+        if getattr(record, key) == '':
+            setattr(record, key, None)
+
+class Audience(models.Model):
+    pk: int
+    id: int  # pyright: ignore[reportUninitializedInstanceVariable]
+    audience_segment_set: 'RelatedManager[AudienceSegment]'  # pyright: ignore[reportUninitializedInstanceVariable]
+    subscriber_set: 'RelatedManager[Subscriber]'  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    site: 'models.ForeignKey[Site]' = models.ForeignKey(Site, blank=False, null=False, on_delete=models.CASCADE)
+    name: 'models.SlugField[str]' = models.SlugField(blank=False, null=False)
+    description: 'models.TextField[str]' = models.TextField(blank=True, null=False)
+    smtp_user: 'models.CharField[str | None]' = models.CharField(
+        max_length=256,
+        blank=True,
+        null=True,
+        default=None,
+        help_text='The SMTP login user.  If absent, this will not be supplied to send_mail, and EMAIL_HOST_USER will be used instead',
+    )
+    smtp_password: 'models.CharField[str | None]' = models.CharField(
+        max_length=256,
+        blank=True,
+        null=True,
+        default=None,
+        help_text='The SMTP login password.  If absent, this will not be supplied to send_mail, and EMAIL_HOST_PASSWORD will be used instead',
+    )
+    from_email_address: 'models.EmailField[str | None]' = models.EmailField(
+        blank=True,
+        null=True,
+        default=None,
+        help_text='The From address for the email.  If not present, this will not be supplied to send_mail, and DEFAULT_FROM_EMAIL will be used instead',
+    )
+    from_email_name: 'models.CharField[str | None]' = models.CharField(
+        max_length=256,
+        blank=True,
+        null=True,
+        default=None,
+        help_text='The display name portion of the from email.  This will be wrapped around the from email address.',
+    )
+
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints: Sequence[models.UniqueConstraint] = (
+            models.UniqueConstraint(
+                fields=('site', 'name'),
+                name='unique_site_name',
+            ),
+        )
+
+    @override
+    def __str__(self) -> str:
+        return self.name
+
+    _NULLABLE_FIELDS: Sequence[str] = ('smtp_user', 'smtp_password', 'from_email_address', 'from_email_name')
+
+    @override
+    def save(self, **kwargs: Unpack[SaveDict]) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
+        patch_blanks(self, kwargs.get('update_fields'), Audience._NULLABLE_FIELDS)
+        return super().save(**kwargs)
+
+    def from_address(self) -> str:
+        default_from_name, default_from_email = _default_from_parts()
+        from_email = self.from_email_address or default_from_email
+        if from_email is None:
+            raise RuntimeError('from email address must be set')
+        from_name = self.from_email_name or default_from_name
+        if from_name:
+            return formataddr((from_name, from_email))
+        else:
+            return from_email
+
+    def smtp_auth(self) -> tuple[str, str]:
+        smtp_user = self.smtp_user or cast(str | None, settings.EMAIL_HOST_USER)
+        smtp_password = self.smtp_password or cast(str | None, settings.EMAIL_HOST_PASSWORD)
+        if smtp_user is None:
+            raise RuntimeError('smtp_user must be set')
+
+        if smtp_password is None:
+            raise RuntimeError('smtp_password must be set')
+
+        return smtp_user, smtp_password
+
+class AudienceSegment(models.Model):
+    pk: int
+    id: int  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    audience: 'models.ForeignKey[Audience]' = models.ForeignKey(Audience, blank=False, null=False, on_delete=models.CASCADE, related_name='audience_segment_set', related_query_name='audience_segment')
+    name: 'models.SlugField[str]' = models.SlugField(blank=False, null=False, unique=True)
+    description: 'models.TextField[str]' = models.TextField(blank=True, null=False)
+    subscribers: 'models.ManyToManyField[Subscriber, Subscription]' = models.ManyToManyField(
+        'Subscriber',
+        through='Subscription',
+        related_name='+',
+    )
+
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints: Sequence[models.UniqueConstraint] = (
+            models.UniqueConstraint(
+                fields=('audience', 'name'),
+                name='unique_audience_name',
+            ),
+        )
+
+    @override
+    def __str__(self) -> str:
+        return self.name
+
+_SUBSCRIBER_KEY_CHARS: LiteralString = string.ascii_letters + string.digits
+
+def generate_subscriber_key() -> str:
+    return ''.join(secrets.choice(_SUBSCRIBER_KEY_CHARS) for _ in range(64))
+
+class Subscriber(models.Model):
+    key: models.CharField[str] = models.CharField(
+        max_length=64,
+        blank=False,
+        null=False,
+        default=generate_subscriber_key,
+        help_text="The subscriber's lookup key for managing subscriptions",
+        unique=True,
+    )
+    audience: 'models.ForeignKey[Audience]' = models.ForeignKey(Audience, blank=False, null=False, on_delete=models.CASCADE)
+    email_address: 'models.EmailField[str]' = models.EmailField(blank=False, null=False)
+    email_name: 'models.CharField[str | None]' = models.CharField(
+        max_length=256,
+        blank=True,
+        null=True,
+        default=None,
+        help_text='The display name portion of the email address.',
+    )
+    audience_segments: 'models.ManyToManyField[AudienceSegment, Subscription]' = models.ManyToManyField(
+        AudienceSegment,
+        through='Subscription',
+        related_name='+',
+    )
+    verified: models.BooleanField[bool] = models.BooleanField(blank=False, null=False, default=False)
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    sent_message_set: 'RelatedManager[SentMessage]'  # pyright: ignore[reportUninitializedInstanceVariable]
+
+    @override
+    def __str__(self) -> str:
+        return self.email()
+
+    def email(self) -> str:
+        if self.email_name:
+            return formataddr((self.email_name, self.email_address))
+        else:
+            return self.email_address
+
+    def pii_hash(self) -> str:
+        normalized = self.email_address.lower().strip().encode('utf-8')
+        key = cast(str, settings.PII_HASHING_SALT).encode('utf-8')
+        return hmac.new(key, normalized, hashlib.sha256).hexdigest()
+
+    class Meta:
+        constraints: Sequence[models.UniqueConstraint] = (
+            models.UniqueConstraint(
+                fields=('audience', 'email_address'),
+                name='unique_audience_email_address',
+            ),
+        )
+
+    _NULLABLE_FIELDS: Sequence[str] = ('email_name',)
+
+    @override
+    def save(self, **kwargs: Unpack[SaveDict]) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
+        patch_blanks(self, kwargs.get('update_fields'), Subscriber._NULLABLE_FIELDS)
+        return super().save(**kwargs)
+
+class Subscription(models.Model):
+    audience_segment: 'models.ForeignKey[AudienceSegment]' = models.ForeignKey(AudienceSegment, on_delete=models.CASCADE)
+    subscriber: 'models.ForeignKey[Subscriber]' = models.ForeignKey(Subscriber, on_delete=models.CASCADE)
+
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints: Sequence[models.UniqueConstraint] = (
+            models.UniqueConstraint(
+                fields=['audience_segment', 'subscriber'],
+                name='unique_audience_segment_subscriber',
+            ),
+        )
+
+    @override
+    def __str__(self) -> str:
+        return f'{self.subscriber} -> {self.audience_segment}'
+
+    @override
+    def clean(self) -> None:
+        if self.audience_segment.audience != self.subscriber.audience:
+            raise ValidationError('The audience_segment and subscriber must have the same audience')
+
+class Campaign(models.Model):
+    pk: int
+    id: int # pyright: ignore[reportUninitializedInstanceVariable]
+
+    send_at: 'models.DateTimeField[datetime | None]' = models.DateTimeField(blank=True, null=True, default=None)
+    sent_at: 'models.DateTimeField[datetime | None]' = models.DateTimeField(blank=True, null=True, default=None)
+    subject: 'models.TextField[str]' = models.TextField(blank=False, null=False)
+    html: 'models.TextField[str]' = models.TextField(blank=False, null=False)
+    audience_segment: models.ForeignKey[AudienceSegment] = models.ForeignKey(AudienceSegment, blank=False, null=False, on_delete=models.CASCADE)
+
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    @property
+    def is_sent(self) -> bool:
+        return self.sent_at is not None
+
+    @property
+    def is_scheduled(self) -> bool:
+        return self.sent_at is None and self.send_at is not None
+
+    @property
+    def url(self) -> str:
+        return reverse('campaign:edit', args=[self.pk])
+
+    @property
+    def status(self) -> str:
+        if self.sent_at is not None:
+            return 'Sent'
+        elif self.send_at is not None:
+            return 'Scheduled'
+        else:
+            return 'Saved'
+
+    def get_report(self) -> dict[str, Any]:
+        report = {
+            'id': self.id,
+            'emails_sent': SentMessage.objects.filter(campaign=self).count(),
+            'send_time': self.sent_at,
+            'bounces': 0,
+            'delivery_status': {
+                'status': 'poop',
+            },
+        }
+        if self.send_at is not None:
+            report['send_time'] = self.send_at
+        return report
+
+    @override
+    def __str__(self) -> str:
+        return self.subject
+
+_ = wncb.Campaign.register(Campaign)
+
+class SentMessage(models.Model):
+    pk: int
+    id: int # pyright: ignore[reportUninitializedInstanceVariable]
+
+    # Null if the subscriber has unsubscribed, deleting their email address
+    campaign: 'models.ForeignKey[Campaign]' = models.ForeignKey(Campaign, blank=False, null=False, on_delete=models.CASCADE, related_name='sent_message_set', related_query_name='sent_message')
+    subscriber: 'models.ForeignKey[Subscriber | None]' = models.ForeignKey(Subscriber, blank=True, null=True, on_delete=models.SET_NULL, related_name='sent_message_set', related_query_name='sent_message')
+    subscriber_hash: 'models.CharField[str]' = models.CharField(max_length = 64, null=False, blank=False, db_index=True)
+
+    created_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now_add=True)
+    updated_at: 'models.DateTimeField[datetime]' = models.DateTimeField(auto_now=True)
+
+    @override
+    def save(self, **kwargs: Unpack[SaveDict]) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
+        if self.subscriber is not None and self.subscriber_hash is None:  # pyright: ignore[reportUnnecessaryComparison]
+            self.subscriber_hash = self.subscriber.pii_hash()
+        super().save(**kwargs)

wagtail_newsletter_django_backend/templates/wagtail_newsletter_django_backend/manage.html

@@ -0,0 +1,16 @@
+<html>
+    <body>
+        {% if messages %}
+            {% for message in messages %}
+                <div class="alert alert-{{ message.tags }}">
+                    {{ message }}
+                </div>
+            {% endfor %}
+        {% endif %}
+        <p><a href="{% url 'newsletter_subscriber_unsubscribe' key=form.instance.key %}">Unsubscribe from all</a></p>
+        <form method="post">{% csrf_token %}
+            {{ form.as_p }}
+            <input type="submit" value="Save preferences">
+        </form>
+    </body>
+</html>

wagtail_newsletter_django_backend/templates/wagtail_newsletter_django_backend/unsubscribe.html

@@ -0,0 +1,22 @@
+<html>
+    <body>
+        {% if messages %}
+            {% for message in messages %}
+                <div class="alert alert-{{ message.tags }}">
+                    {{ message }}
+                </div>
+            {% endfor %}
+        {% endif %}
+        {% if subscriber %}
+        <p>Really unsubscribe for {{subscriber}}?</p>
+        <form method="post" action="{{ request.path }}">{% csrf_token %}
+            <input type="submit" value="Unsubscribe">
+        </form>
+        <p><a href="{% url 'newsletter_subscriber_manage' key=subscriber.key %}">Manage my preferences instead</a></p>
+        <p><a href="/">Go back to the main site</a></p>
+        {% else %}
+        <p>This subscriber does not exist</p>
+        <p><a href="/">Go back to the main site</a></p>
+        {% endif %}
+    </body>
+</html>

wagtail_newsletter_django_backend/urls.py

@@ -0,0 +1,17 @@
+# from django.contrib import admin
+# from django.urls import include, path
+# from wagtail.admin import urls as wagtailadmin_urls
+# from wagtail import urls as wagtail_urls
+# from wagtail.documents import urls as wagtaildocs_urls
+
+from django.urls import path
+from wagtail_newsletter_django_backend import views
+
+
+app_name = 'wagtail_newsletter_django_backend'
+urlpatterns = [
+    # The manage and verify route
+    path('manage/<str:key>/', views.ManageView.as_view(), name='newsletter_subscriber_manage'),
+    path('unsubscribe/<str:key>/', views.UnsubscribeView.as_view(), name='newsletter_subscriber_unsubscribe'),
+]
+

wagtail_newsletter_django_backend/views.py

@@ -1,3 +1,79 @@
-from django.shortcuts import render
+from contextlib import _RedirectStream
+from typing import Any, override
+from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
+from django.http.response import HttpResponseRedirectBase
+from django.urls import reverse
+from django.views.generic.edit import FormView
+from django.views.generic.base import TemplateView
+from .forms import ManageForm
+from django.shortcuts import get_object_or_404
+from django.contrib import messages
+from . import models
 
-# Create your views here.
+class ManageView(FormView):  # pyright: ignore[reportMissingTypeArgument]
+    template_name = 'wagtail_newsletter_django_backend/manage.html'
+    form_class = ManageForm
+
+    def get_object(self):
+        """Get the subscriber instance from the URL key parameter."""
+        key = self.kwargs['key']
+        return get_object_or_404(models.Subscriber, key=key)
+    
+    def get_form_kwargs(self):
+        """Add the subscriber instance to form kwargs."""
+        kwargs = super().get_form_kwargs()
+        kwargs['instance'] = self.get_object()
+        return kwargs
+    
+    def form_valid(self, form):
+        """Save the form and redirect on success."""
+        form.save()
+        messages.success(self.request, 'Your subscription preferences have been updated successfully!')
+
+        return super().form_valid(form)
+    
+    def get_success_url(self):
+        """Redirect back to the same page after successful form submission."""
+        return self.request.path
+
+    def get(self, request: HttpRequest, *args, **kwargs):
+        """Handle GET request and verify subscriber if needed."""
+        subscriber = self.get_object()
+        
+        # Verify the subscriber if not already verified
+        if not subscriber.verified:
+            subscriber.verified = True
+            subscriber.save(update_fields=['verified'])
+            messages.success(request, 'Your email address has been successfully verified!')
+        
+        return super().get(request, *args, **kwargs)
+
+class HttpResponseSeeOther(HttpResponseRedirectBase):
+    status_code: int = 303
+
+class UnsubscribeView(TemplateView):
+    template_name = 'wagtail_newsletter_django_backend/unsubscribe.html'
+    subscriber: models.Subscriber | None = None
+    method: str | None = None
+
+    @override
+    def setup(self, request: HttpRequest, key: str, *args, **kwargs) -> None:
+        super().setup(request, *args, **kwargs)
+        self.subscriber = models.Subscriber.objects.filter(key=key).first()
+        self.method = request.method
+
+    @override
+    def get_context_data(self, **kwargs: Any) -> dict[str, Any]:  # pyright: ignore[reportAny]
+        data = super().get_context_data(**kwargs)
+        data['subscriber'] = self.subscriber
+        if self.method:
+            data['method'] = self.method.lower()
+        return data
+
+    def post(self, request: HttpRequest, *args, **kwargs) -> HttpResponse:
+        if self.subscriber is not None:
+            _ = self.subscriber.delete()
+            self.subscriber = None
+        messages.success(request, 'This subscriber has been successfully deleted')
+        return HttpResponseSeeOther(reverse('newsletter_subscriber_unsubscribe', args=args, kwargs=kwargs))
+        

wagtail_newsletter_django_backend/wagtail_hooks.py

@@ -0,0 +1,7 @@
+from wagtail import hooks
+from .admin_viewsets import MailingListGroup, mailing_list_group
+
+@hooks.register('register_admin_viewset')  # pyright: ignore[reportOptionalCall, reportUntypedFunctionDecorator, reportUnknownMemberType]
+def register_viewset() -> MailingListGroup:
+    return mailing_list_group
+

{wagtail_newsletter_django_backend-0.0.2.dist-info → wagtail_newsletter_django_backend-0.2.0.dist-info}/METADATA

@@ -1,14 +1,16 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: wagtail-newsletter-django-backend
-Version: 0.0.2
+Version: 0.2.0
 Summary: An internal Django backend to wagtail-newsletter.
 Author-email: "Taylor C. Richberger" <taylor@axfive.net>
 Maintainer-email: "Taylor C. Richberger" <taylor@axfive.net>
 Requires-Python: >= 3.10
 Description-Content-Type: text/markdown
-Requires-Dist: Django>=5.2,<5.3
-Requires-Dist: wagtail>=7.1,<7.2
-Requires-Dist: wagtail-newsletter>=0.2.2,<0.3.0
+License-File: LICENSE
+Requires-Dist: Django >=5.2, <5.3
+Requires-Dist: wagtail >=7.1, <7.2
+Requires-Dist: wagtail-newsletter >=0.2.2, <0.3.0
+Requires-Dist: html2text >= 2025.4.15
 Project-URL: documentation, https://wagtail-newsletter-django-backend.readthedocs.io/en/latest/
 Project-URL: repository, https://forge.axfive.net/Taylor/wagtail-newsletter-django-backend
 

wagtail_newsletter_django_backend-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+wagtail_newsletter_django_backend/__init__.py,sha256=8MajxYquD2zP0KOr24i0Dvy40Dq9tor1oytBhpY0MyU,263
+wagtail_newsletter_django_backend/admin.py,sha256=suMo4x8I3JBxAFBVIdE-5qnqZ6JAZV0FESABHOSc-vg,63
+wagtail_newsletter_django_backend/admin_viewsets.py,sha256=JRUz8lRqZPGzlnorNr605OQzA9GmAuzSu_oe1tCoosc,2011
+wagtail_newsletter_django_backend/apps.py,sha256=fFm2QZzxZlpYBQTNRKzBXpzOUzjK5xbW2xCQdv5fNOA,281
+wagtail_newsletter_django_backend/campaign_backend.py,sha256=5GGPKfDZ5ecQBqzLM2I3FBXvlqv1GfaczA-DmjyQlJc,6929
+wagtail_newsletter_django_backend/forms.py,sha256=5UK_-Fd7KuOtRkPZW_uyHM9D6BU5_JANKcM3WhAnew0,4009
+wagtail_newsletter_django_backend/models.py,sha256=QjGIqSNn-uQ_T3hWchTx6K4XhcYhyze5mULoFXzftQk,12887
+wagtail_newsletter_django_backend/tests.py,sha256=mrbGGRNg5jwbTJtWWa7zSKdDyeB4vmgZCRc2nk6VY-g,60
+wagtail_newsletter_django_backend/urls.py,sha256=650q2IQKPOj6OSjVIB3QzxPl4n67M2MJwtFFEvJ3vOk,620
+wagtail_newsletter_django_backend/views.py,sha256=8xh-aOdy7CS0g8CeieB-_flOtHB7VZ8tr1syzcbYme4,3166
+wagtail_newsletter_django_backend/wagtail_hooks.py,sha256=3ll7lcwAKUMS9AoxUq9WuBjGAfHHgwGNJO6yt7r0Ra4,305
+wagtail_newsletter_django_backend/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wagtail_newsletter_django_backend/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wagtail_newsletter_django_backend/management/commands/send_scheduled_campaigns.py,sha256=YA6KLCUyHrHJqxc_qHP-JEBFh_U-0T2BPKiUeue8czA,320
+wagtail_newsletter_django_backend/migrations/0001_initial.py,sha256=DYuyU3MxhnhzKBPKlxZn2erP-lB9rGRUR4KngXRrBXw,11129
+wagtail_newsletter_django_backend/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wagtail_newsletter_django_backend/templates/wagtail_newsletter_django_backend/manage.html,sha256=ahu_XV6aKdrL7uj2VEC_ISdw7OFKsMsiamMOY_COZrA,535
+wagtail_newsletter_django_backend/templates/wagtail_newsletter_django_backend/unsubscribe.html,sha256=sg8AwxuoLiBV-6QazL8X1cd6vQp8arR1_Uj6Jep2Lwo,810
+wagtail_newsletter_django_backend-0.2.0.dist-info/licenses/LICENSE,sha256=mLNEGyMZ9q73ep-adKoMoTX06QDYEd949WxgTKhl93A,33970
+wagtail_newsletter_django_backend-0.2.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+wagtail_newsletter_django_backend-0.2.0.dist-info/METADATA,sha256=3uKZaGyM0g_LvsEkkhgQquEv9pqpebGKNIhQye3ofOk,836
+wagtail_newsletter_django_backend-0.2.0.dist-info/RECORD,,

{wagtail_newsletter_django_backend-0.0.2.dist-info → wagtail_newsletter_django_backend-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: flit 3.10.1
+Generator: flit 3.12.0
 Root-Is-Purelib: true
 Tag: py3-none-any

wagtail_newsletter_django_backend-0.0.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-wagtail_newsletter_django_backend/__init__.py,sha256=BC8UtHiLA2WiHnRKp4TssBot9Fpl8UjOYzgv2zIwwcU,263
-wagtail_newsletter_django_backend/admin.py,sha256=suMo4x8I3JBxAFBVIdE-5qnqZ6JAZV0FESABHOSc-vg,63
-wagtail_newsletter_django_backend/apps.py,sha256=HiQChXPqKrnPGTL5BX-dVcMEeMmY3qmXXz7NrSeX2YY,195
-wagtail_newsletter_django_backend/models.py,sha256=Vjc0p2XbAPgE6HyTF6vll98A4eDhA5AvaQqsc4kQ9AQ,57
-wagtail_newsletter_django_backend/tests.py,sha256=mrbGGRNg5jwbTJtWWa7zSKdDyeB4vmgZCRc2nk6VY-g,60
-wagtail_newsletter_django_backend/views.py,sha256=xc1IQHrsij7j33TUbo-_oewy3vs03pw_etpBWaMYJl0,63
-wagtail_newsletter_django_backend/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wagtail_newsletter_django_backend-0.0.2.dist-info/LICENSE,sha256=mLNEGyMZ9q73ep-adKoMoTX06QDYEd949WxgTKhl93A,33970
-wagtail_newsletter_django_backend-0.0.2.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-wagtail_newsletter_django_backend-0.0.2.dist-info/METADATA,sha256=dSDmfz_ML2iwkeDGnmH1Ws3ltl7LE3vnkVZZRsDmTPY,770
-wagtail_newsletter_django_backend-0.0.2.dist-info/RECORD,,