iil-platform-notifications 0.1.0__tar.gz

iil_platform_notifications-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*\.class
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+# Django
+*.log
+db.sqlite3
+media/
+staticfiles/
+# Environment
+.env
+.env.local
+.env.prod
+
+# Secrets (ADR-045) — NEVER commit plaintext
+secrets.env
+!secrets.enc.env
+# IDE
+.idea/
+.vscode/
+*.swp
+# OS
+.DS_Store
+Thumbs.db
+# Large files
+*.sqlite3
+*.log
+output_batch/
+app_backup/
+docs_legacy/
+# Sphinx build output
+docs/_build/
+*:Zone.Identifier
+# Local Windsurf/MCP config — machine-specific, never commit
+.windsurf/mcp_config.json
+# Local infra plaintext secrets — NEVER commit
+infra/*.env
+infra/*.key
+# Validate-ports CI draft (not yet integrated)
+.github/workflows/validate-ports.yml
+# Markdownlint local config override
+.markdownlint.json
+# Concept review drafts (local working copies, not for VCS)
+docs/concepts/REVIEW-*
+env_loader.py

iil_platform_notifications-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: iil-platform-notifications
+Version: 0.1.0
+Summary: Platform-wide multi-channel notification registry (ADR-088)
+Author: Achim Dehnert
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: celery>=5.3
+Requires-Dist: django>=4.2
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-django>=4.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: sms
+Requires-Dist: twilio>=8.0; extra == 'sms'
+Description-Content-Type: text/markdown
+
+# platform-notifications
+
+> Platform-wide multi-channel notification registry (ADR-088)
+
+## Overview
+
+Unified notification system with channel abstraction, Celery-First
+async delivery, audit logging, and thread-safe registry pattern.
+
+## Installation
+
+```bash
+pip install -e packages/platform-notifications
+pip install -e "packages/platform-notifications[sms]"  # for Twilio SMS
+```
+
+## Usage
+
+```python
+from platform_notifications.service import NotificationService, Notification
+
+NotificationService.send(Notification(
+    tenant_id=request.tenant_id,
+    channel="email",
+    recipient="user@example.com",
+    subject="Welcome",
+    body="Hello from the platform!",
+    source_app="wedding-hub",
+    source_event="rsvp_confirmation",
+))
+```
+
+## Built-in Channels
+
+- **email** — Django `send_mail`
+- **sms** — Twilio (requires `twilio` extra)
+- **webhook** — Generic HTTPS POST via `httpx`
+
+## Configuration
+
+```python
+# config/settings/base.py
+PLATFORM_NOTIFICATIONS = {
+    "DEFAULT_CHANNELS": ["email"],
+    "RETRY_MAX": 3,
+    "RETRY_BACKOFF": True,
+    "RETRY_BACKOFF_MAX": 300,
+    "LOG_RETENTION_DAYS": 90,
+}
+```
+
+## Database
+
+Run: `python manage.py migrate platform_notifications`
+
+## Related ADRs
+
+- **ADR-088**: Notification Registry
+- **ADR-045**: Secret Management (Twilio, Discord, Telegram)
+- **ADR-072**: Schema Isolation (Row-Level deviation documented)

iil_platform_notifications-0.1.0/README.md

@@ -0,0 +1,60 @@
+# platform-notifications
+
+> Platform-wide multi-channel notification registry (ADR-088)
+
+## Overview
+
+Unified notification system with channel abstraction, Celery-First
+async delivery, audit logging, and thread-safe registry pattern.
+
+## Installation
+
+```bash
+pip install -e packages/platform-notifications
+pip install -e "packages/platform-notifications[sms]"  # for Twilio SMS
+```
+
+## Usage
+
+```python
+from platform_notifications.service import NotificationService, Notification
+
+NotificationService.send(Notification(
+    tenant_id=request.tenant_id,
+    channel="email",
+    recipient="user@example.com",
+    subject="Welcome",
+    body="Hello from the platform!",
+    source_app="wedding-hub",
+    source_event="rsvp_confirmation",
+))
+```
+
+## Built-in Channels
+
+- **email** — Django `send_mail`
+- **sms** — Twilio (requires `twilio` extra)
+- **webhook** — Generic HTTPS POST via `httpx`
+
+## Configuration
+
+```python
+# config/settings/base.py
+PLATFORM_NOTIFICATIONS = {
+    "DEFAULT_CHANNELS": ["email"],
+    "RETRY_MAX": 3,
+    "RETRY_BACKOFF": True,
+    "RETRY_BACKOFF_MAX": 300,
+    "LOG_RETENTION_DAYS": 90,
+}
+```
+
+## Database
+
+Run: `python manage.py migrate platform_notifications`
+
+## Related ADRs
+
+- **ADR-088**: Notification Registry
+- **ADR-045**: Secret Management (Twilio, Discord, Telegram)
+- **ADR-072**: Schema Isolation (Row-Level deviation documented)

iil_platform_notifications-0.1.0/platform_notifications/__init__.py

@@ -0,0 +1,7 @@
+"""Platform-wide multi-channel notification registry (ADR-088).
+
+Provides unified notification API with channel abstraction,
+Celery-First async delivery, and audit logging.
+"""
+
+__version__ = "0.1.0"

iil_platform_notifications-0.1.0/platform_notifications/apps.py

@@ -0,0 +1,33 @@
+"""Django app configuration for platform-notifications."""
+
+from django.apps import AppConfig
+
+
+class PlatformNotificationsConfig(AppConfig):
+    """Platform Notifications app config."""
+
+    name = "platform_notifications"
+    verbose_name = "Platform Notifications"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        """Register built-in channels on app startup."""
+        from platform_notifications.channels.email import EmailChannel
+        from platform_notifications.channels.webhook import WebhookChannel
+        from platform_notifications.registry import ChannelRegistry
+
+        registry = ChannelRegistry.get_instance()
+        registry.register(EmailChannel())
+        registry.register(WebhookChannel())
+
+        try:
+            from platform_notifications.channels.sms import SmsChannel
+            registry.register(SmsChannel())
+        except ImportError:
+            pass
+
+        from platform_notifications.channels.discord import DiscordChannel
+        from platform_notifications.channels.telegram import TelegramChannel
+
+        registry.register(DiscordChannel())
+        registry.register(TelegramChannel())

iil_platform_notifications-0.1.0/platform_notifications/channels/__init__.py

@@ -0,0 +1 @@
+"""Notification channel implementations."""

iil_platform_notifications-0.1.0/platform_notifications/channels/base.py

@@ -0,0 +1,58 @@
+"""Base channel interface for notification channels (ADR-088)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ChannelConfig(BaseModel):
+    """Configuration for a notification channel."""
+
+    model_config = ConfigDict(frozen=True)
+
+    max_retries: int = Field(
+        default=3, description="Max delivery retries"
+    )
+    retry_backoff: bool = Field(
+        default=True, description="Exponential backoff"
+    )
+    retry_backoff_max: int = Field(
+        default=300, description="Max backoff seconds"
+    )
+    timeout: int = Field(
+        default=30, description="Delivery timeout seconds"
+    )
+
+
+class BaseChannel(ABC):
+    """Abstract base for notification channels."""
+
+    name: str
+    config: ChannelConfig
+
+    def __init__(
+        self, config: ChannelConfig | None = None
+    ) -> None:
+        self.config = config or ChannelConfig()
+
+    @abstractmethod
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """Deliver notification. Returns True on success."""
+        ...
+
+    @abstractmethod
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate recipient format."""
+        ...
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Check channel connectivity."""
+        return {"healthy": True, "channel": self.name}

iil_platform_notifications-0.1.0/platform_notifications/channels/discord.py

@@ -0,0 +1,64 @@
+"""Discord webhook notification channel (ADR-088).
+
+Requires: DISCORD_WEBHOOK_URL in Django settings (ADR-045).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from platform_notifications.channels.base import BaseChannel
+
+logger = logging.getLogger(__name__)
+
+
+class DiscordChannel(BaseChannel):
+    """Discord notifications via webhook URL."""
+
+    name = "discord"
+
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """Post message to Discord webhook.
+
+        recipient = webhook URL (per-channel or per-tenant).
+        """
+        content = f"**{subject}**\n{body}" if subject else body
+        with httpx.Client(timeout=self.config.timeout) as client:
+            response = client.post(
+                recipient,
+                json={"content": content[:2000]},
+            )
+            response.raise_for_status()
+        return True
+
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate Discord webhook URL format."""
+        return (
+            recipient.startswith("https://discord.com/api/webhooks/")
+            or recipient.startswith("https://discordapp.com/api/webhooks/")
+        )
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Check Discord webhook URL is configured."""
+        try:
+            from django.conf import settings
+
+            url = getattr(settings, "DISCORD_WEBHOOK_URL", "")
+            return {
+                "healthy": bool(url),
+                "channel": self.name,
+            }
+        except Exception as exc:
+            return {
+                "healthy": False,
+                "channel": self.name,
+                "error": str(exc),
+            }

iil_platform_notifications-0.1.0/platform_notifications/channels/email.py

@@ -0,0 +1,49 @@
+"""Email notification channel (ADR-088)."""
+
+from __future__ import annotations
+
+from platform_notifications.channels.base import BaseChannel
+
+
+class EmailChannel(BaseChannel):
+    """Email channel via Django send_mail."""
+
+    name = "email"
+
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """Send email via Django mail backend."""
+        from django.core.mail import send_mail
+
+        send_mail(
+            subject,
+            body,
+            None,
+            [recipient],
+            fail_silently=False,
+        )
+        return True
+
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate email address format."""
+        from django.core.validators import validate_email
+
+        try:
+            validate_email(recipient)
+            return True
+        except Exception:
+            return False
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Check Django email backend is configured."""
+        from django.conf import settings
+
+        has_backend = bool(
+            getattr(settings, "EMAIL_BACKEND", None)
+        )
+        return {"healthy": has_backend, "channel": self.name}

iil_platform_notifications-0.1.0/platform_notifications/channels/sms.py

@@ -0,0 +1,68 @@
+"""SMS notification channel via Twilio (ADR-088).
+
+Requires: pip install platform-notifications[sms]
+Secrets: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER (ADR-045)
+"""
+
+from __future__ import annotations
+
+import re
+
+from platform_notifications.channels.base import BaseChannel
+
+E164_PATTERN = re.compile(r"^\+[1-9]\d{1,14}$")
+
+
+class SmsChannel(BaseChannel):
+    """SMS via Twilio. Replaces wedding-hub direct Twilio calls."""
+
+    name = "sms"
+
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """Send SMS via Twilio API."""
+        from twilio.rest import Client  # type: ignore[import-untyped]
+
+        client = Client(
+            self._get_account_sid(),
+            self._get_auth_token(),
+        )
+        client.messages.create(
+            body=body,
+            from_=self._get_from_number(),
+            to=recipient,
+        )
+        return True
+
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate E.164 phone number format."""
+        return bool(E164_PATTERN.match(recipient))
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Check Twilio credentials are configured."""
+        try:
+            self._get_account_sid()
+            return {"healthy": True, "channel": self.name}
+        except Exception as exc:
+            return {
+                "healthy": False,
+                "channel": self.name,
+                "error": str(exc),
+            }
+
+    def _get_account_sid(self) -> str:
+        from django.conf import settings
+        return settings.TWILIO_ACCOUNT_SID  # type: ignore[attr-defined]
+
+    def _get_auth_token(self) -> str:
+        from django.conf import settings
+        return settings.TWILIO_AUTH_TOKEN  # type: ignore[attr-defined]
+
+    def _get_from_number(self) -> str:
+        from django.conf import settings
+        return settings.TWILIO_FROM_NUMBER  # type: ignore[attr-defined]

iil_platform_notifications-0.1.0/platform_notifications/channels/telegram.py

@@ -0,0 +1,74 @@
+"""Telegram Bot notification channel (ADR-088).
+
+Requires: TELEGRAM_BOT_TOKEN in Django settings (ADR-045).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from platform_notifications.channels.base import BaseChannel
+
+logger = logging.getLogger(__name__)
+
+TELEGRAM_API_BASE = "https://api.telegram.org/bot"
+
+
+class TelegramChannel(BaseChannel):
+    """Telegram notifications via Bot API.
+
+    recipient = chat_id (string or numeric).
+    """
+
+    name = "telegram"
+
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """Send message via Telegram Bot API."""
+        token = self._get_bot_token()
+        text = f"*{subject}*\n{body}" if subject else body
+        url = f"{TELEGRAM_API_BASE}{token}/sendMessage"
+
+        with httpx.Client(timeout=self.config.timeout) as client:
+            response = client.post(
+                url,
+                json={
+                    "chat_id": recipient,
+                    "text": text[:4096],
+                    "parse_mode": "Markdown",
+                },
+            )
+            response.raise_for_status()
+        return True
+
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate Telegram chat_id (numeric string, optionally negative)."""
+        cleaned = recipient.lstrip("-")
+        return cleaned.isdigit() and len(cleaned) <= 20
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Check Telegram bot token is configured."""
+        try:
+            self._get_bot_token()
+            return {"healthy": True, "channel": self.name}
+        except Exception as exc:
+            return {
+                "healthy": False,
+                "channel": self.name,
+                "error": str(exc),
+            }
+
+    def _get_bot_token(self) -> str:
+        from django.conf import settings
+
+        token = getattr(settings, "TELEGRAM_BOT_TOKEN", "")
+        if not token:
+            raise ValueError("TELEGRAM_BOT_TOKEN not configured")
+        return token

iil_platform_notifications-0.1.0/platform_notifications/channels/webhook.py

@@ -0,0 +1,41 @@
+"""Generic webhook notification channel (ADR-088)."""
+
+from __future__ import annotations
+
+import httpx
+
+from platform_notifications.channels.base import BaseChannel
+
+
+class WebhookChannel(BaseChannel):
+    """Generic HTTPS webhook channel."""
+
+    name = "webhook"
+
+    def deliver(
+        self,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs: object,
+    ) -> bool:
+        """POST notification payload to webhook URL."""
+        with httpx.Client(timeout=self.config.timeout) as client:
+            response = client.post(
+                recipient,
+                json={
+                    "subject": subject,
+                    "body": body,
+                    **kwargs,
+                },
+            )
+            response.raise_for_status()
+        return True
+
+    def validate_recipient(self, recipient: str) -> bool:
+        """Validate HTTPS URL."""
+        return recipient.startswith("https://")
+
+    def health_check(self) -> dict[str, bool | str]:
+        """Webhook health is always true (no persistent connection)."""
+        return {"healthy": True, "channel": self.name}