stapel-notifications 0.3.1__tar.gz

stapel_notifications-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usestapel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_notifications-0.3.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: stapel-notifications
+Version: 0.3.1
+Summary: Push and in-app notifications Django app for the Stapel framework
+License: MIT
+Keywords: django,stapel,notifications,push,firebase
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: firebase
+Requires-Dist: firebase-admin>=6.4; extra == "firebase"
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.3; extra == "kafka"
+Provides-Extra: all
+Requires-Dist: stapel-notifications[firebase,kafka]; extra == "all"
+Dynamic: license-file
+
+# stapel-notifications
+
+[![CI](https://github.com/usestapel/stapel-notifications/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-notifications/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-notifications/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-notifications)
+
+> Notifications — push (Firebase), email, SMS channels with delivery logging
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-notifications
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_notifications',
+]
+```
+
+## Bus events
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_notifications-0.3.1/README.md

@@ -0,0 +1,34 @@
+# stapel-notifications
+
+[![CI](https://github.com/usestapel/stapel-notifications/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-notifications/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-notifications/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-notifications)
+
+> Notifications — push (Firebase), email, SMS channels with delivery logging
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-notifications
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_notifications',
+]
+```
+
+## Bus events
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_notifications-0.3.1/__init__.py

@@ -0,0 +1,52 @@
+"""stapel-notifications — multi-channel notifications (email / SMS / push).
+
+Public API (lazily resolved, PEP 562 — importing this package pulls in
+no Django code until an attribute is actually accessed):
+
+    notifications_settings  — the ``STAPEL_NOTIFICATIONS`` settings namespace
+    request_notification    — publish a notification request to the bus
+    process_notification    — resolve language/contacts/templates and dispatch
+    get_channels            — channels configured for a notification type
+    get_group               — preference group of a notification type
+    get_email_template      — effective email template for a notification type
+    registered_types        — all known notification types (built-in + host)
+"""
+
+__all__ = [
+    "get_channels",
+    "get_email_template",
+    "get_group",
+    "notifications_settings",
+    "process_notification",
+    "registered_types",
+    "request_notification",
+]
+
+# name -> (module, attribute); relative modules resolve inside this package
+_EXPORTS = {
+    "notifications_settings": (".conf", "notifications_settings"),
+    "request_notification": ("stapel_core.notifications", "request_notification"),
+    "process_notification": (".services", "process_notification"),
+    "get_channels": (".routing", "get_channels"),
+    "get_group": (".routing", "get_group"),
+    "get_email_template": (".routing", "get_email_template"),
+    "registered_types": (".routing", "registered_types"),
+}
+
+
+def __getattr__(name):
+    try:
+        module_path, attr = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}"
+        ) from None
+    from importlib import import_module
+
+    value = getattr(import_module(module_path, __name__), attr)
+    globals()[name] = value  # cache: subsequent lookups skip __getattr__
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_notifications-0.3.1/actions.py

@@ -0,0 +1,70 @@
+"""Action subscriptions of the notifications module.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery).
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed."""
+    from .gdpr import NotificationsGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    NotificationsGDPRProvider().delete(user_id)
+    logger.info("notifications data erased for deleted user %s", user_id)
+
+
+@on_action("user.deletion_initiated")
+def handle_user_deletion_initiated(event):
+    """Account-closure grace period started: stop notifying the user.
+
+    Soft and reversible — the contact and the push tokens are only
+    deactivated, not erased (full erasure stays on ``user.deleted``).
+    Reactivation happens through the normal sync paths (contact-changed
+    events, device re-registration); there is currently no dedicated
+    "closure cancelled" event to subscribe to (see CHANGELOG).
+    """
+    from .models import DevicePushToken, UserContact
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error(
+            "user.deletion_initiated event without user_id: %s", event.event_id
+        )
+        return
+    contacts = UserContact.objects.filter(user_id=user_id).update(is_active=False)
+    tokens = DevicePushToken.objects.filter(user_id=user_id).update(is_active=False)
+    logger.info(
+        "deactivated %d contact(s) and %d push token(s) for user %s "
+        "(deletion grace period)", contacts, tokens, user_id,
+    )
+
+
+@on_action("translations.changed")
+def handle_translations_changed(event):
+    """Refresh cached ``notification.*`` translations on invalidation.
+
+    The event is a thin invalidation ({language, keys_changed}); the values
+    are pulled through the ``translate.resolve`` comm Function. Errors
+    propagate so at-least-once delivery retries the sync.
+    """
+    from .translations import resolve_and_cache
+
+    language = event.payload.get("language")
+    keys_changed = event.payload.get("keys_changed") or []
+    keys = [
+        k for k in keys_changed
+        if isinstance(k, str) and k.startswith("notification.")
+    ]
+    if not language or not keys:
+        return
+    resolve_and_cache(keys, language)

stapel_notifications-0.3.1/admin.py

@@ -0,0 +1,46 @@
+from django.contrib import admin
+from .models import (
+    UserNotificationSettings,
+    UserContact,
+    TranslationCache,
+    NotificationLog,
+    DevicePushToken,
+)
+
+
+@admin.register(UserNotificationSettings)
+class UserNotificationSettingsAdmin(admin.ModelAdmin):
+    list_display = ['user_id', 'language', 'email_messages', 'email_system', 'push_messages', 'push_system', 'updated_at']
+    search_fields = ['user_id']
+    readonly_fields = ['updated_at']
+
+
+@admin.register(UserContact)
+class UserContactAdmin(admin.ModelAdmin):
+    list_display = ['user_id', 'email', 'phone', 'updated_at']
+    search_fields = ['user_id', 'email', 'phone']
+    readonly_fields = ['updated_at']
+
+
+@admin.register(TranslationCache)
+class TranslationCacheAdmin(admin.ModelAdmin):
+    list_display = ['key', 'updated_at']
+    search_fields = ['key']
+    readonly_fields = ['updated_at']
+
+
+@admin.register(NotificationLog)
+class NotificationLogAdmin(admin.ModelAdmin):
+    list_display = ['id', 'notification_type', 'channel', 'status', 'recipient', 'language', 'created_at']
+    list_filter = ['status', 'channel', 'notification_type']
+    search_fields = ['user_id', 'recipient', 'notification_type']
+    readonly_fields = ['id', 'created_at']
+    ordering = ['-created_at']
+
+
+@admin.register(DevicePushToken)
+class DevicePushTokenAdmin(admin.ModelAdmin):
+    list_display = ['user_id', 'platform', 'is_active', 'created_at', 'updated_at']
+    list_filter = ['platform', 'is_active']
+    search_fields = ['user_id', 'token']
+    readonly_fields = ['created_at', 'updated_at']

stapel_notifications-0.3.1/apps.py

@@ -0,0 +1,17 @@
+from django.apps import AppConfig
+
+
+class NotificationsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "stapel_notifications"
+    label = 'notifications'
+    verbose_name = "Stapel Notifications"
+
+    def ready(self):
+        from stapel_core.gdpr import gdpr_registry
+        from .gdpr import NotificationsGDPRProvider
+        gdpr_registry.register(NotificationsGDPRProvider())
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM).
+        from . import actions  # noqa: F401

stapel_notifications-0.3.1/channels/email.py

@@ -0,0 +1,181 @@
+"""
+Email channel facade.
+
+Dispatches to the provider configured via EMAIL_PROVIDER setting:
+  resend   — Resend API (https://resend.com)
+  smtp     — Standard SMTP via Django email backend
+  mailgun  — Mailgun API (https://mailgun.com)
+  mock     — Log only, no real sending (default)
+
+Unknown values fall back to mock with a warning.
+"""
+
+import base64
+import logging
+import os
+
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+_logo_data: bytes | None = None
+LOGO_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    'static', 'notifications', 'logo.png',
+)
+
+
+def _get_logo_data() -> bytes | None:
+    global _logo_data
+    if _logo_data is None:
+        try:
+            with open(LOGO_PATH, 'rb') as f:
+                _logo_data = f.read()
+        except FileNotFoundError:
+            logger.warning("Logo file not found: %s", LOGO_PATH)
+    return _logo_data
+
+
+def _inline_logo_data() -> bytes | None:
+    """Logo bytes for the inline cid:logo attachment, or None when
+    STAPEL_NOTIFICATIONS['LOGO_URL'] is set (templates then reference the
+    URL directly and no attachment is needed)."""
+    from stapel_notifications.conf import notifications_settings
+
+    if notifications_settings.LOGO_URL:
+        return None
+    return _get_logo_data()
+
+
+# ──────────────────────────────────────────────────────────────────
+# Provider classes
+# ──────────────────────────────────────────────────────────────────
+
+class _MockEmailProvider:
+    def send(self, recipient: str, subject: str, html_body: str, headers: dict | None) -> None:
+        logger.info("[mock email] to=%s subject=%r", _mask(recipient), subject)
+
+
+class _ResendEmailProvider:
+    def send(self, recipient: str, subject: str, html_body: str, headers: dict | None) -> None:
+        import requests as _http
+
+        from stapel_notifications.conf import notifications_settings
+
+        api_key = notifications_settings.RESEND_API_KEY
+        if not api_key:
+            raise RuntimeError("EMAIL_PROVIDER=resend requires RESEND_API_KEY")
+
+        payload: dict = {
+            "from": settings.DEFAULT_FROM_EMAIL,
+            "to": [recipient],
+            "subject": subject,
+            "html": html_body,
+        }
+        logo = _inline_logo_data()
+        if logo:
+            payload["attachments"] = [{
+                "filename": "logo.png",
+                "content": base64.b64encode(logo).decode(),
+                "content_type": "image/png",
+                "content_id": "logo",
+            }]
+        if headers:
+            payload["headers"] = headers
+
+        resp = _http.post(
+            "https://api.resend.com/emails",
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+            json=payload,
+            timeout=15,
+        )
+        if not resp.ok:
+            raise RuntimeError(f"Resend API error {resp.status_code}: {resp.text}")
+        logger.info("Email sent to %s via Resend (id=%s)", _mask(recipient), resp.json().get("id"))
+
+
+class _SMTPEmailProvider:
+    def send(self, recipient: str, subject: str, html_body: str, headers: dict | None) -> None:
+        from email.mime.image import MIMEImage
+        from django.core.mail import EmailMessage
+
+        msg = EmailMessage(
+            subject=subject,
+            body=html_body,
+            from_email=settings.DEFAULT_FROM_EMAIL,
+            to=[recipient],
+            headers=headers or {},
+        )
+        msg.content_subtype = 'html'
+        logo = _inline_logo_data()
+        if logo:
+            logo_mime = MIMEImage(logo, _subtype='png')
+            logo_mime.add_header('Content-ID', '<logo>')
+            logo_mime.add_header('Content-Disposition', 'inline', filename='logo.png')
+            msg.attach(logo_mime)
+        msg.send(fail_silently=False)
+        logger.info("Email sent to %s via SMTP", _mask(recipient))
+
+
+class _MailgunEmailProvider:
+    def send(self, recipient: str, subject: str, html_body: str, headers: dict | None) -> None:
+        import requests as _http
+
+        from stapel_notifications.conf import notifications_settings
+
+        api_key = notifications_settings.MAILGUN_API_KEY
+        domain = notifications_settings.MAILGUN_DOMAIN
+        if not api_key or not domain:
+            raise RuntimeError("EMAIL_PROVIDER=mailgun requires MAILGUN_API_KEY and MAILGUN_DOMAIN")
+
+        resp = _http.post(
+            f"https://api.mailgun.net/v3/{domain}/messages",
+            auth=("api", api_key),
+            data={
+                "from": settings.DEFAULT_FROM_EMAIL,
+                "to": recipient,
+                "subject": subject,
+                "html": html_body,
+            },
+            timeout=15,
+        )
+        resp.raise_for_status()
+        logger.info("Email sent to %s via Mailgun", _mask(recipient))
+
+
+# ──────────────────────────────────────────────────────────────────
+# Registry + facade
+# ──────────────────────────────────────────────────────────────────
+
+_PROVIDERS: dict[str, type] = {
+    'resend':   _ResendEmailProvider,
+    'smtp':     _SMTPEmailProvider,
+    'mailgun':  _MailgunEmailProvider,
+    'mock':     _MockEmailProvider,
+}
+
+
+def _get_provider():
+    from stapel_notifications.channels.sms import _resolve_provider
+    from stapel_notifications.conf import notifications_settings
+
+    return _resolve_provider(
+        notifications_settings.EMAIL_PROVIDER, _PROVIDERS, _MockEmailProvider, "email"
+    )
+
+
+def send_email(
+    recipient: str,
+    subject: str,
+    html_body: str,
+    headers: dict | None = None,
+) -> None:
+    """Send an HTML email via the configured provider."""
+    _get_provider().send(recipient, subject, html_body, headers)
+
+
+def _mask(email: str) -> str:
+    if '@' not in email:
+        return '***'
+    local, domain = email.split('@', 1)
+    return f"{local[0]}***@{domain}" if local else f"***@{domain}"

stapel_notifications-0.3.1/channels/push.py

@@ -0,0 +1,157 @@
+"""
+Push notification channel.
+
+Dispatches to the provider configured via the ``PUSH_PROVIDER`` key of the
+``STAPEL_NOTIFICATIONS`` namespace (or the flat ``PUSH_PROVIDER`` setting /
+env var):
+
+  fcm   — Firebase Cloud Messaging (default)
+  mock  — Log only, no real sending
+
+Besides the short names, any dotted path to a provider class with a
+``send(user_id, title, body, data) -> int`` method is accepted — the same
+fork-free escape hatch as the email/SMS channels and captcha backends.
+"""
+
+import logging
+import threading
+
+
+from stapel_notifications.models import DevicePushToken
+
+logger = logging.getLogger(__name__)
+
+_firebase_lock = threading.Lock()
+_app_initialized = False
+
+
+def _ensure_firebase():
+    """Initialize Firebase app once (thread-safe)."""
+    global _app_initialized
+    if _app_initialized:
+        return True
+
+    with _firebase_lock:
+        # Double-check after acquiring lock
+        if _app_initialized:
+            return True
+        try:
+            import firebase_admin
+            from firebase_admin import credentials
+
+            from stapel_notifications.conf import notifications_settings
+
+            cred_path = notifications_settings.GOOGLE_APPLICATION_CREDENTIALS
+            if not cred_path:
+                logger.warning("GOOGLE_APPLICATION_CREDENTIALS not set, push disabled")
+                return False
+
+            if not firebase_admin._apps:
+                cred = credentials.Certificate(cred_path)
+                firebase_admin.initialize_app(cred)
+
+            _app_initialized = True
+            return True
+        except Exception as e:
+            logger.error("Firebase initialization failed: %s", e)
+            return False
+
+
+def _active_tokens(user_id: str):
+    return DevicePushToken.objects.filter(
+        user_id=user_id,
+        is_active=True,
+    ).values_list('token', 'platform')
+
+
+# ──────────────────────────────────────────────────────────────────
+# Provider classes
+# ──────────────────────────────────────────────────────────────────
+
+class _MockPushProvider:
+    def send(self, user_id: str, title: str, body: str, data: dict | None) -> int:
+        count = len(_active_tokens(user_id))
+        logger.info(
+            "[mock push] user=%s title=%r active_tokens=%d", user_id, title, count
+        )
+        return count
+
+
+class _FCMPushProvider:
+    def send(self, user_id: str, title: str, body: str, data: dict | None) -> int:
+        if not _ensure_firebase():
+            raise RuntimeError("Firebase not configured")
+
+        from firebase_admin import messaging
+
+        tokens = _active_tokens(user_id)
+
+        if not tokens:
+            logger.info("No active push tokens for user %s", user_id)
+            return 0
+
+        sent_count = 0
+        for token, platform in tokens:
+            try:
+                # Build platform-specific message
+                notification = messaging.Notification(title=title, body=body)
+                message = messaging.Message(
+                    notification=notification,
+                    token=token,
+                    data={k: str(v) for k, v in (data or {}).items()},
+                )
+
+                # iOS-specific: set badge and sound
+                if platform == 'ios':
+                    message.apns = messaging.APNSConfig(
+                        payload=messaging.APNSPayload(
+                            aps=messaging.Aps(sound='default'),
+                        ),
+                    )
+
+                messaging.send(message)
+                sent_count += 1
+
+            except messaging.UnregisteredError:
+                logger.info("Deactivating unregistered token for user %s", user_id)
+                DevicePushToken.objects.filter(token=token).update(is_active=False)
+
+            except Exception as e:
+                logger.error("Push failed for user %s token %s...: %s", user_id, token[:20], e)
+
+        return sent_count
+
+
+# ──────────────────────────────────────────────────────────────────
+# Registry + facade
+# ──────────────────────────────────────────────────────────────────
+
+_PROVIDERS: dict[str, type] = {
+    'fcm':  _FCMPushProvider,
+    'mock': _MockPushProvider,
+}
+
+
+def _get_provider():
+    from stapel_notifications.channels.sms import _resolve_provider
+    from stapel_notifications.conf import notifications_settings
+
+    return _resolve_provider(
+        notifications_settings.PUSH_PROVIDER, _PROVIDERS, _MockPushProvider, "push"
+    )
+
+
+def send_push(user_id: str, title: str, body: str, data: dict | None = None) -> int:
+    """
+    Send push notification to all active devices for a user.
+
+    Args:
+        user_id: Target user UUID
+        title: Notification title
+        body: Notification body
+        data: Optional data payload (deep links, etc.)
+
+    Returns:
+        Number of successfully sent messages.
+    """
+    return _get_provider().send(user_id, title, body, data)