Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(notifications): queue-backed Notification Bus + email system

Juan Denisa661212d50a2
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 0c10b0c9..58967dcf 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -411,6 +411,10 @@ def create_app(config_name=None):
from app.queue_bus.consumers import start_webhook_consumer
start_webhook_consumer(app)
+ # Start queue-bus notification consumer (delivers in-app/email/chat)
+ from app.notifications.consumer import start_notification_consumer
+ start_notification_consumer(app)
+
# Start auto-sync scheduler for WordPress environments
_start_auto_sync_scheduler(app)
diff --git a/backend/app/api/notifications.py b/backend/app/api/notifications.py
index 1393ff06..29356b02 100644
--- a/backend/app/api/notifications.py
+++ b/backend/app/api/notifications.py
@@ -4,6 +4,8 @@ from app.middleware.rbac import admin_required
from app.models import User, NotificationPreferences
from app import db
from app.services.notification_service import NotificationService
+from app.notifications.service import NotificationBusService
+from app.notifications.providers import EmailProviderService, SUPPORTED as EMAIL_PROVIDERS
notifications_bp = Blueprint('notifications', __name__)
@@ -280,3 +282,143 @@ def test_user_notification():
'success': all_success,
'results': results
}), 200 if all_success else 207
+
+
+# ==========================================
+# IN-APP NOTIFICATION CENTER (the bell + history)
+# ==========================================
+
+@notifications_bp.route('/inbox', methods=['GET'])
+@jwt_required()
+def get_inbox():
+ """List the current user's in-app notifications, newest first."""
+ user_id = int(get_jwt_identity())
+ limit = min(request.args.get('limit', 20, type=int), 100)
+ offset = request.args.get('offset', 0, type=int)
+ unread_only = request.args.get('unread', '').lower() in ('1', 'true', 'yes')
+ items = NotificationBusService.inbox(user_id, limit=limit, offset=offset, unread_only=unread_only)
+ return jsonify({
+ 'items': items,
+ 'unread_count': NotificationBusService.unread_count(user_id),
+ }), 200
+
+
+@notifications_bp.route('/inbox/unread-count', methods=['GET'])
+@jwt_required()
+def get_unread_count():
+ """Lightweight unread count for the bell badge."""
+ user_id = int(get_jwt_identity())
+ return jsonify({'count': NotificationBusService.unread_count(user_id)}), 200
+
+
+@notifications_bp.route('/inbox/<int:delivery_id>/read', methods=['POST'])
+@jwt_required()
+def mark_inbox_read(delivery_id):
+ """Mark one in-app notification as read."""
+ user_id = int(get_jwt_identity())
+ if not NotificationBusService.mark_read(user_id, delivery_id):
+ return jsonify({'error': 'Notification not found'}), 404
+ return jsonify({'success': True, 'unread_count': NotificationBusService.unread_count(user_id)}), 200
+
+
+@notifications_bp.route('/inbox/read-all', methods=['POST'])
+@jwt_required()
+def mark_inbox_all_read():
+ """Mark all of the current user's in-app notifications as read."""
+ user_id = int(get_jwt_identity())
+ updated = NotificationBusService.mark_all_read(user_id)
+ return jsonify({'success': True, 'updated': updated, 'unread_count': 0}), 200
+
+
+# ==========================================
+# DELIVERY LOG / OPS (admin)
+# ==========================================
+
+@notifications_bp.route('/admin/deliveries', methods=['GET'])
+@jwt_required()
+@admin_required
+def admin_delivery_log():
+ """List recent deliveries across all users, with status/channel filters."""
+ status = request.args.get('status') or None
+ channel = request.args.get('channel') or None
+ limit = min(request.args.get('limit', 50, type=int), 200)
+ offset = request.args.get('offset', 0, type=int)
+ return jsonify({
+ 'deliveries': NotificationBusService.delivery_log(
+ status=status, channel=channel, limit=limit, offset=offset),
+ 'stats': NotificationBusService.delivery_stats(),
+ }), 200
+
+
+@notifications_bp.route('/admin/deliveries/<int:delivery_id>/retry', methods=['POST'])
+@jwt_required()
+@admin_required
+def admin_retry_delivery(delivery_id):
+ """Re-queue a failed delivery for another attempt."""
+ result = NotificationBusService.retry_delivery(delivery_id)
+ if result is None:
+ return jsonify({'error': 'Delivery not found'}), 404
+ return jsonify({'success': True, 'delivery': result}), 200
+
+
+# ==========================================
+# EMAIL PROVIDER INTEGRATIONS (admin)
+# ==========================================
+
+@notifications_bp.route('/admin/email-providers', methods=['GET'])
+@jwt_required()
+@admin_required
+def list_email_providers():
+ """List configured email providers + the catalog of supported types."""
+ catalog = {
+ key: {'name': spec['name'], 'fields': spec['fields'], 'secrets': spec['secrets']}
+ for key, spec in EMAIL_PROVIDERS.items()
+ }
+ return jsonify({
+ 'providers': [p.to_dict() for p in EmailProviderService.list_providers()],
+ 'supported': catalog,
+ }), 200
+
+
+@notifications_bp.route('/admin/email-providers', methods=['POST'])
+@jwt_required()
+@admin_required
+def add_email_provider():
+ """Add an email provider, then validate its credentials."""
+ data = request.get_json() or {}
+ try:
+ provider = EmailProviderService.add_provider(data, user_id=int(get_jwt_identity()))
+ except ValueError as exc:
+ return jsonify({'error': str(exc)}), 400
+ test = EmailProviderService.test_provider(provider.id)
+ return jsonify({'provider': provider.to_dict(), 'test': test}), 201
+
+
+@notifications_bp.route('/admin/email-providers/<int:provider_id>/test', methods=['POST'])
+@jwt_required()
+@admin_required
+def test_email_provider(provider_id):
+ """Validate a provider's credentials without sending."""
+ result = EmailProviderService.test_provider(provider_id)
+ return jsonify(result), 200 if result.get('success') else 400
+
+
+@notifications_bp.route('/admin/email-providers/<int:provider_id>/default', methods=['POST'])
+@jwt_required()
+@admin_required
+def set_default_email_provider(provider_id):
+ """Make a provider the default transport."""
+ row = EmailProviderService.set_default(provider_id)
+ if row is None:
+ return jsonify({'error': 'Provider not found'}), 404
+ return jsonify({'success': True, 'provider': row.to_dict()}), 200
+
+
+@notifications_bp.route('/admin/email-providers/<int:provider_id>', methods=['DELETE'])
+@jwt_required()
+@admin_required
+def delete_email_provider(provider_id):
+ """Remove an email provider."""
+ if not EmailProviderService.delete_provider(provider_id):
+ return jsonify({'error': 'Provider not found'}), 404
+ return jsonify({'success': True}), 200
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index e50fb1db..5660cda9 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -43,6 +43,8 @@ from app.models.secret_vault import SecretVault, Secret
from app.models.webhook_gateway import WebhookEndpoint, WebhookDelivery
from app.models.waf_policy import WafPolicy
from app.queue_bus.models import QueueGroup, Queue, QueueMessage
+from app.notifications.models import Notification, NotificationDelivery
+from app.models.email_provider import EmailProviderConnection
__all__ = [
'User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',
@@ -72,4 +74,6 @@ __all__ = [
'WebhookEndpoint', 'WebhookDelivery',
'WafPolicy',
'QueueGroup', 'Queue', 'QueueMessage',
+ 'Notification', 'NotificationDelivery',
+ 'EmailProviderConnection',
]
diff --git a/backend/app/models/email_provider.py b/backend/app/models/email_provider.py
new file mode 100644
index 00000000..fd032f48
--- /dev/null
+++ b/backend/app/models/email_provider.py
@@ -0,0 +1,69 @@
+"""Email provider connection for the Notification Bus.
+
+A configured outbound transport (SMTP or a native API: SendGrid / Postmark /
+Amazon SES / Mailgun) the email channel uses to actually send. Credentials are
+stored Fernet-encrypted (per-field) in ``credentials_json``; the public
+``to_dict`` never exposes them. Follows the Connections pattern used by DNS /
+cloud / registrar providers.
+"""
+import json
+from datetime import datetime
+
+from app import db
+from app.utils.crypto import decrypt_secret_safe
+
+
+class EmailProviderConnection(db.Model):
+ __tablename__ = 'email_provider_connections'
+
+ id = db.Column(db.Integer, primary_key=True)
+ provider = db.Column(db.String(40), nullable=False) # smtp|sendgrid|postmark|ses|mailgun
+ name = db.Column(db.String(120), nullable=False)
+
+ # JSON map of credential fields; secret fields are Fernet-encrypted at rest.
+ credentials_json = db.Column(db.Text)
+
+ from_address = db.Column(db.String(255))
+ from_name = db.Column(db.String(120), default='ServerKit')
+
+ is_default = db.Column(db.Boolean, default=False, index=True)
+ is_active = db.Column(db.Boolean, default=True)
+
+ created_by = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+ last_tested_at = db.Column(db.DateTime)
+ last_test_ok = db.Column(db.Boolean)
+
+ def raw_credentials(self):
+ try:
+ return json.loads(self.credentials_json) if self.credentials_json else {}
+ except (json.JSONDecodeError, TypeError):
+ return {}
+
+ def credentials(self):
+ """Decrypted credentials for use at send/test time (never serialized)."""
+ out = {}
+ for key, value in self.raw_credentials().items():
+ out[key] = decrypt_secret_safe(value) if isinstance(value, str) else value
+ return out
+
+ def to_dict(self):
+ creds = self.raw_credentials()
+ # Surface which non-secret fields are set / the masked tail — never secrets.
+ return {
+ 'id': self.id,
+ 'provider': self.provider,
+ 'name': self.name,
+ 'from_address': self.from_address,
+ 'from_name': self.from_name,
+ 'is_default': self.is_default,
+ 'is_active': self.is_active,
+ 'configured_fields': sorted(creds.keys()),
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'last_tested_at': self.last_tested_at.isoformat() if self.last_tested_at else None,
+ 'last_test_ok': self.last_test_ok,
+ }
+
+ def __repr__(self):
+ return f'<EmailProviderConnection {self.id} {self.provider} default={self.is_default}>'
diff --git a/backend/app/notifications/__init__.py b/backend/app/notifications/__init__.py
new file mode 100644
index 00000000..cb20f76e
--- /dev/null
+++ b/backend/app/notifications/__init__.py
@@ -0,0 +1,18 @@
+"""ServerKit Notification Bus.
+
+A reusable, queue-backed notification layer built on top of the Queue Bus.
+
+Any part of the app (or a plugin) emits an event:
+
+ from app.plugins_sdk import notify
+ notify.send('backup.completed', to='admins', data={'app': 'blog', 'size': '2.3 GB'})
+
+The call is non-blocking: it writes a durable ``Notification`` record plus one
+``NotificationDelivery`` per (recipient x channel), enqueues them on the Queue
+Bus, and returns. A background ``NotificationConsumer`` renders each delivery
+and hands it to the matching channel adapter (in-app, email, chat, ...).
+
+Submodules (``models``, ``service``, ``sdk``, ``consumer``, ``channels``,
+``rendering``, ``catalog``) are imported lazily by their consumers to keep
+model registration (``app.models.__init__``) free of heavy imports.
+"""
diff --git a/backend/app/notifications/branding.py b/backend/app/notifications/branding.py
new file mode 100644
index 00000000..1f33c77c
--- /dev/null
+++ b/backend/app/notifications/branding.py
@@ -0,0 +1,47 @@
+"""Brand tokens for rendered notifications.
+
+Single source of truth for the colors/wordmark used by email templates (and,
+later, any other rich channel). Mirrors the frontend SCSS design system
+(`frontend/src/styles/_variables.scss`) so email matches the app:
+
+ accent #6d7cff success #3ddc97 warning #f5b945 danger #fb6f6f
+
+The severity *tints* below are tuned for legibility on a light email canvas
+(emails render light-first; a dark-mode media query swaps the chrome).
+"""
+
+BRAND = {
+ 'name': 'ServerKit',
+ 'accent': '#6d7cff',
+ 'accent_hover': '#5a67e8',
+ # Light canvas
+ 'page_bg': '#eef0f6',
+ 'card_bg': '#ffffff',
+ 'border': '#e6e8f0',
+ 'ink': '#1b1e2b', # primary text
+ 'muted': '#646b7d', # secondary text
+ 'faint': '#9aa1b2', # footer / least important
+ 'code_bg': '#f3f4f9', # monospace value chips
+ # Dark canvas (used by the prefers-color-scheme media query)
+ 'dark_page_bg': '#0f1117',
+ 'dark_card_bg': '#171a23',
+ 'dark_border': '#272b38',
+ 'dark_ink': '#e9ebf2',
+ 'dark_muted': '#9aa1b2',
+ 'dark_code_bg': '#1f2330',
+}
+
+# Per-severity styling: a light tint background, a readable text color, and a
+# saturated dot — all solid hex so they survive every email client.
+SEVERITY_STYLES = {
+ 'critical': {'bg': '#fdecec', 'text': '#c0392b', 'dot': '#fb6f6f', 'label': 'Critical'},
+ 'warning': {'bg': '#fdf5e3', 'text': '#9a6a12', 'dot': '#f5b945', 'label': 'Warning'},
+ 'info': {'bg': '#eef0ff', 'text': '#454dc4', 'dot': '#6d7cff', 'label': 'Info'},
+ 'success': {'bg': '#e7f9f1', 'text': '#11784f', 'dot': '#3ddc97', 'label': 'Success'},
+ 'test': {'bg': '#f1f2f6', 'text': '#5b6170', 'dot': '#9aa1b2', 'label': 'Test'},
+}
+
+
+def style_for(severity):
+ """Return the tint/text/dot triple for a severity (falls back to info)."""
+ return SEVERITY_STYLES.get(severity, SEVERITY_STYLES['info'])
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
new file mode 100644
index 00000000..e0464526
--- /dev/null
+++ b/backend/app/notifications/catalog.py
@@ -0,0 +1,122 @@
+"""Event catalog for the Notification Bus.
+
+Maps an ``event_key`` (e.g. ``backup.completed``) to its presentation defaults:
+which template renders it, its default severity, its preference category, and a
+title template. Callers pass data; the catalog turns ``event_key`` + data into a
+title + routing metadata.
+
+Plugins extend the catalog with ``register(...)`` so a plugin event renders
+through the same pipeline as a core one.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+# category is one of: system | security | backups | apps (matches
+# NotificationPreferences.get_categories()). Title is a str.format template
+# applied to the event data (missing keys degrade gracefully — see resolve()).
+_CATALOG = {
+ # --- backups ---
+ 'backup.completed': {
+ 'title': 'Backup completed: {app}',
+ 'template': 'backup_completed',
+ 'severity': 'success',
+ 'category': 'backups',
+ },
+ 'backup.failed': {
+ 'title': 'Backup failed: {app}',
+ 'template': 'generic',
+ 'severity': 'critical',
+ 'category': 'backups',
+ },
+ # --- security ---
+ 'security.alert': {
+ 'title': 'Security alert: {alert_type}',
+ 'template': 'security_alert',
+ 'severity': 'critical',
+ 'category': 'security',
+ },
+ # --- apps / system ---
+ 'app.deployed': {
+ 'title': 'Deployed: {app}',
+ 'template': 'generic',
+ 'severity': 'success',
+ 'category': 'apps',
+ },
+ 'system.alert': {
+ 'title': 'System alert on {hostname}',
+ 'template': 'generic',
+ 'severity': 'warning',
+ 'category': 'system',
+ },
+ # Multi-alert monitoring digest (used by the legacy send_all path).
+ 'monitoring.alert': {
+ 'title': 'ServerKit alert',
+ 'template': 'monitoring_alert',
+ 'severity': 'warning',
+ 'category': 'system',
+ },
+ # --- account ---
+ 'user.welcome': {
+ 'title': 'Welcome to ServerKit',
+ 'template': 'welcome',
+ 'severity': 'info',
+ 'category': 'system',
+ },
+ 'user.invitation': {
+ 'title': "You've been invited to ServerKit",
+ 'template': 'invitation',
+ 'severity': 'info',
+ 'category': 'system',
+ },
+}
+
+# Used when an event_key has no catalog entry — still renders, via generic.html.
+DEFAULT_ENTRY = {
+ 'title': 'Notification',
+ 'template': 'generic',
+ 'severity': 'info',
+ 'category': 'system',
+}
+
+
+def register(event_key, title, template='generic', severity='info', category='system'):
+ """Register (or override) a catalog event. Safe to call at import time."""
+ _CATALOG[event_key] = {
+ 'title': title,
+ 'template': template,
+ 'severity': severity,
+ 'category': category,
+ }
+
+
+def _safe_format(template_str, data):
+ """str.format that won't explode on a missing/extra key."""
+ class _Default(dict):
+ def __missing__(self, key):
+ return '{' + key + '}'
+ try:
+ return template_str.format_map(_Default(data or {}))
+ except Exception:
+ return template_str
+
+
+def resolve(event_key, data=None, severity=None, title=None):
+ """Resolve an event into concrete presentation metadata.
+
+ Explicit ``severity``/``title`` args (from notify.send) win over catalog
+ defaults. Returns a dict: title, template, severity, category.
+ """
+ entry = _CATALOG.get(event_key, DEFAULT_ENTRY)
+ resolved_title = title or _safe_format(entry['title'], data)
+ return {
+ 'title': resolved_title,
+ 'template': entry['template'],
+ 'severity': severity or entry['severity'],
+ 'category': entry['category'],
+ }
+
+
+def get(event_key):
+ """Return the raw catalog entry for an event, or None."""
+ return _CATALOG.get(event_key)
diff --git a/backend/app/notifications/channels/__init__.py b/backend/app/notifications/channels/__init__.py
new file mode 100644
index 00000000..141b712a
--- /dev/null
+++ b/backend/app/notifications/channels/__init__.py
@@ -0,0 +1,49 @@
+"""Channel adapter registry.
+
+Maps a channel key -> adapter instance. ``register_adapter`` lets a plugin add
+a new channel (SMS, web-push, ...) that the consumer can then deliver, exactly
+like core channels.
+"""
+from app.notifications.channels.base import ChannelAdapter, DeliveryResult
+from app.notifications.channels.inapp import InAppAdapter
+from app.notifications.channels.email import EmailAdapter
+from app.notifications.channels.chat import ChatAdapter
+
+# Channels the bus knows how to deliver out of the box.
+_REGISTRY = {
+ 'inapp': InAppAdapter(),
+ 'email': EmailAdapter(),
+ 'discord': ChatAdapter('discord'),
+ 'slack': ChatAdapter('slack'),
+ 'telegram': ChatAdapter('telegram'),
+ 'webhook': ChatAdapter('webhook'),
+}
+
+# Channels that can be targeted per-user from a user's NotificationPreferences.
+# (Slack/generic-webhook are system-wide today, so they're not auto-selected for
+# individual recipients — but remain deliverable if a target is supplied.)
+PER_USER_CHANNELS = ('inapp', 'email', 'discord', 'telegram')
+
+
+def register_adapter(adapter):
+ """Register (or replace) a channel adapter. ``adapter.key`` is the channel."""
+ if not getattr(adapter, 'key', None):
+ raise ValueError('adapter must define a non-empty key')
+ _REGISTRY[adapter.key] = adapter
+ return adapter
+
+
+def get_adapter(channel):
+ """Return the adapter for a channel key, or None if unknown."""
+ return _REGISTRY.get(channel)
+
+
+def known_channels():
+ return sorted(_REGISTRY.keys())
+
+
+__all__ = [
+ 'ChannelAdapter', 'DeliveryResult',
+ 'register_adapter', 'get_adapter', 'known_channels',
+ 'PER_USER_CHANNELS',
+]
diff --git a/backend/app/notifications/channels/base.py b/backend/app/notifications/channels/base.py
new file mode 100644
index 00000000..cd43eb62
--- /dev/null
+++ b/backend/app/notifications/channels/base.py
@@ -0,0 +1,55 @@
+"""Channel adapter contract.
+
+Each channel (in-app, email, chat, ...) implements ``ChannelAdapter.deliver``
+and returns a ``DeliveryResult``. The consumer maps the result onto the
+delivery row + the queue (sent -> complete, failed -> retry/dead-letter,
+skipped -> complete without sending).
+
+Adapters render whatever they need themselves (email builds HTML, chat builds
+its own payload), so the interface stays a single method.
+"""
+
+
+class DeliveryResult:
+ SENT = 'sent'
+ FAILED = 'failed'
+ SKIPPED = 'skipped'
+
+ def __init__(self, status, message_id=None, error=None):
+ self.status = status
+ self.message_id = message_id
+ self.error = error
+
+ @property
+ def ok(self):
+ return self.status == self.SENT
+
+ @classmethod
+ def sent(cls, message_id=None):
+ return cls(cls.SENT, message_id=message_id)
+
+ @classmethod
+ def failed(cls, error):
+ return cls(cls.FAILED, error=str(error)[:1000] if error else None)
+
+ @classmethod
+ def skipped(cls, reason=None):
+ return cls(cls.SKIPPED, error=str(reason)[:1000] if reason else None)
+
+ def __repr__(self):
+ return f'<DeliveryResult {self.status}{" " + self.error if self.error else ""}>'
+
+
+class ChannelAdapter:
+ """Base class for a notification channel. Subclasses set ``key`` and
+ implement ``deliver``."""
+
+ key = None
+
+ def deliver(self, delivery, notification):
+ """Transmit ``notification`` to ``delivery.target`` for this channel.
+
+ Returns a DeliveryResult. May raise — the consumer treats an exception
+ the same as DeliveryResult.failed (so the queue retries).
+ """
+ raise NotImplementedError
diff --git a/backend/app/notifications/channels/chat.py b/backend/app/notifications/channels/chat.py
new file mode 100644
index 00000000..9e91844e
--- /dev/null
+++ b/backend/app/notifications/channels/chat.py
@@ -0,0 +1,73 @@
+"""Chat / webhook channels (Discord, Slack, Telegram, generic webhook).
+
+These delegate to the existing, working ``NotificationService`` formatters so we
+don't re-implement Discord embeds / Slack blocks / Telegram HTML. The bus sends
+to the *per-recipient* target (a user's personal Discord webhook or Telegram
+chat id), reusing only shared secrets (e.g. the system Telegram bot token) from
+the saved config. System-wide chat broadcast stays on the legacy path until
+Phase 6.
+"""
+import logging
+
+from app.notifications.channels.base import ChannelAdapter, DeliveryResult
+
+logger = logging.getLogger(__name__)
+
+
+class ChatAdapter(ChannelAdapter):
+ """One adapter class, instantiated per channel key."""
+
+ def __init__(self, key):
+ self.key = key
+
+ def _to_alert(self, notification):
+ data = notification.get_data()
+ return {
+ 'severity': notification.severity or 'info',
+ 'type': notification.event_key,
+ 'message': data.get('message') or notification.body or notification.title,
+ }
+
+ def _alerts_for(self, notification):
+ """Use the original multi-alert list for system broadcasts (so chat keeps
+ per-alert formatting); otherwise a single synthesized alert."""
+ alerts = notification.get_data().get('alerts')
+ if isinstance(alerts, list) and alerts:
+ return alerts
+ return [self._to_alert(notification)]
+
+ def deliver(self, delivery, notification):
+ target = (delivery.target or '').strip()
+ if not target:
+ return DeliveryResult.skipped(f'no {self.key} target')
+
+ from app.services.notification_service import NotificationService
+ saved = NotificationService.get_config()
+ sev = notification.severity or 'info'
+ alerts = self._alerts_for(notification)
+ # Let every alert through regardless of the saved channel's notify_on
+ # (gating already happened upstream in the bus).
+ notify_on = sorted({a.get('severity', sev) for a in alerts} | {sev})
+
+ if self.key == 'discord':
+ cfg = {**saved.get('discord', {}), 'enabled': True,
+ 'webhook_url': target, 'notify_on': notify_on}
+ result = NotificationService.send_discord(alerts, cfg)
+ elif self.key == 'slack':
+ cfg = {**saved.get('slack', {}), 'enabled': True,
+ 'webhook_url': target, 'notify_on': notify_on}
+ result = NotificationService.send_slack(alerts, cfg)
+ elif self.key == 'telegram':
+ cfg = {**saved.get('telegram', {}), 'enabled': True,
+ 'chat_id': target, 'notify_on': notify_on}
+ result = NotificationService.send_telegram(alerts, cfg)
+ elif self.key == 'webhook':
+ cfg = {**saved.get('generic_webhook', {}), 'enabled': True,
+ 'url': target, 'notify_on': notify_on}
+ result = NotificationService.send_generic_webhook(alerts, cfg)
+ else:
+ return DeliveryResult.skipped(f'unsupported chat channel {self.key}')
+
+ if result.get('success'):
+ return DeliveryResult.sent()
+ return DeliveryResult.failed(result.get('error') or 'send failed')
diff --git a/backend/app/notifications/channels/email.py b/backend/app/notifications/channels/email.py
new file mode 100644
index 00000000..d077a4a7
--- /dev/null
+++ b/backend/app/notifications/channels/email.py
@@ -0,0 +1,100 @@
+"""Email channel.
+
+Renders the event's Jinja template (HTML + text twin) and sends it. Transport
+selection:
+
+ 1. a configured ``EmailProviderConnection`` (SMTP / SendGrid / Postmark / SES /
+ Mailgun) if one exists — the Phase-5 path, with provider message-id capture;
+ 2. otherwise the legacy notifications.json SMTP config (back-compat).
+"""
+import logging
+import smtplib
+import ssl
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+from app.notifications import catalog, rendering
+from app.notifications.channels.base import ChannelAdapter, DeliveryResult
+
+logger = logging.getLogger(__name__)
+
+
+class EmailAdapter(ChannelAdapter):
+ key = 'email'
+
+ def _email_config(self):
+ from app.services.notification_service import NotificationService
+ return NotificationService.get_config().get('email', {})
+
+ def _render(self, delivery, notification):
+ data = notification.get_data()
+ meta = catalog.resolve(
+ notification.event_key, data,
+ severity=notification.severity, title=notification.title,
+ )
+ recipient = {}
+ if delivery.recipient is not None:
+ recipient = {
+ 'name': delivery.recipient.username or delivery.recipient.email,
+ 'email': delivery.target,
+ }
+ return rendering.render_email(
+ template=meta['template'],
+ subject=notification.title,
+ severity=notification.severity,
+ data=data,
+ recipient=recipient,
+ )
+
+ def deliver(self, delivery, notification):
+ to_addr = (delivery.target or '').strip()
+ if not to_addr:
+ return DeliveryResult.skipped('no email target')
+
+ rendered = self._render(delivery, notification)
+
+ # 1) A configured provider connection wins.
+ from app.notifications.providers import EmailProviderService
+ provider = EmailProviderService.default_provider()
+ if provider is not None:
+ result = EmailProviderService.send(
+ provider, to_addr, rendered['subject'], rendered['html'], rendered['text'])
+ if result.get('success'):
+ return DeliveryResult.sent(result.get('message_id'))
+ return DeliveryResult.failed(result.get('error') or 'email send failed')
+
+ # 2) Legacy notifications.json SMTP fallback.
+ return self._send_legacy_smtp(to_addr, rendered)
+
+ def _send_legacy_smtp(self, to_addr, rendered):
+ config = self._email_config()
+ if not config.get('enabled'):
+ return DeliveryResult.skipped('no email provider configured')
+ if not config.get('smtp_host') or not config.get('from_email'):
+ return DeliveryResult.skipped('email channel not configured')
+
+ msg = MIMEMultipart('alternative')
+ msg['Subject'] = rendered['subject']
+ msg['From'] = f"{config.get('from_name', 'ServerKit')} <{config['from_email']}>"
+ msg['To'] = to_addr
+ msg.attach(MIMEText(rendered['text'], 'plain', 'utf-8'))
+ msg.attach(MIMEText(rendered['html'], 'html', 'utf-8'))
+
+ host = config['smtp_host']
+ port = int(config.get('smtp_port', 587))
+ use_tls = config.get('smtp_tls', True)
+ try:
+ if use_tls:
+ server = smtplib.SMTP(host, port, timeout=20)
+ server.starttls(context=ssl.create_default_context())
+ else:
+ server = smtplib.SMTP_SSL(host, port, timeout=20, context=ssl.create_default_context())
+ with server:
+ if config.get('smtp_user') and config.get('smtp_password'):
+ server.login(config['smtp_user'], config['smtp_password'])
+ server.send_message(msg)
+ except smtplib.SMTPAuthenticationError as exc:
+ return DeliveryResult.failed(f'SMTP auth failed: {exc}')
+ except (smtplib.SMTPException, OSError) as exc:
+ return DeliveryResult.failed(f'SMTP error: {exc}')
+ return DeliveryResult.sent()
diff --git a/backend/app/notifications/channels/inapp.py b/backend/app/notifications/channels/inapp.py
new file mode 100644
index 00000000..0fdc1dd6
--- /dev/null
+++ b/backend/app/notifications/channels/inapp.py
@@ -0,0 +1,14 @@
+"""In-app channel.
+
+There is nothing to transmit: the ``NotificationDelivery`` row itself *is* the
+in-app notification (the bell reads `channel='inapp'` deliveries for the
+recipient, unread = ``read_at IS NULL``). Delivering just marks it sent.
+"""
+from app.notifications.channels.base import ChannelAdapter, DeliveryResult
+
+
+class InAppAdapter(ChannelAdapter):
+ key = 'inapp'
+
+ def deliver(self, delivery, notification):
+ return DeliveryResult.sent()
diff --git a/backend/app/notifications/consumer.py b/backend/app/notifications/consumer.py
new file mode 100644
index 00000000..d312916a
--- /dev/null
+++ b/backend/app/notifications/consumer.py
@@ -0,0 +1,163 @@
+"""Background consumer that delivers queued notifications.
+
+Mirrors ``queue_bus/consumers/webhook_consumer.py``: a daemon thread polls the
+``serverkit-system/notifications`` queue, loads each ``NotificationDelivery``,
+hands it to the matching channel adapter, and maps the result back onto the
+delivery row + the queue message. Retry, backoff, and dead-lettering are
+inherited from the Queue Bus.
+"""
+import logging
+import threading
+import time
+from datetime import datetime
+
+from app import db
+from app.notifications.channels import get_adapter
+from app.notifications.channels.base import DeliveryResult
+from app.notifications.models import NotificationDelivery
+from app.notifications.service import GROUP_SLUG, QUEUE_SLUG, QUEUE_CONFIG, NotificationBusService
+from app.queue_bus.service import QueueBusService
+
+logger = logging.getLogger(__name__)
+
+_notification_consumer_thread = None
+
+
+class NotificationConsumer:
+ """Polls the queue bus for notification deliveries and transmits them."""
+
+ def __init__(self, app=None):
+ self.app = app
+ self.running = False
+ self.poll_interval_seconds = 1
+
+ def start(self):
+ if self.running:
+ return
+ self.running = True
+ self._ensure_queue()
+ thread = threading.Thread(target=self._run, daemon=True, name='queue-bus-notification-consumer')
+ thread.start()
+ logger.info('Notification queue consumer started')
+
+ def stop(self):
+ self.running = False
+
+ def _ensure_queue(self):
+ with self.app.app_context():
+ QueueBusService.ensure_queue(GROUP_SLUG, QUEUE_SLUG, config=QUEUE_CONFIG)
+
+ def _run(self):
+ while self.running:
+ try:
+ with self.app.app_context():
+ self._process_batch()
+ except Exception as exc:
+ logger.error('Notification consumer error: %s', exc)
+ time.sleep(self.poll_interval_seconds)
+
+ def _process_batch(self):
+ messages = QueueBusService.receive(
+ GROUP_SLUG, QUEUE_SLUG, visibility_timeout_ms=60000, max_messages=10,
+ )
+ for message in messages:
+ try:
+ process_message(message)
+ except Exception as exc:
+ logger.error('Notification delivery failed for message %s: %s', message['id'], exc)
+ try:
+ QueueBusService.fail(GROUP_SLUG, QUEUE_SLUG, message['id'], error_message=str(exc)[:500])
+ except Exception as inner: # pragma: no cover - defensive
+ logger.error('Failed to mark notification message failed: %s', inner)
+
+
+def process_message(message):
+ """Deliver one queued message. Shared by the consumer and tests."""
+ payload = message.get('payload', {})
+ delivery_id = payload.get('delivery_id')
+ if not delivery_id:
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ delivery = NotificationDelivery.query.get(delivery_id)
+ if not delivery:
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ # Idempotency: a duplicate/retried message for an already-sent delivery.
+ if delivery.status == NotificationDelivery.STATUS_SENT:
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ adapter = get_adapter(delivery.channel)
+ delivery.attempts = (delivery.attempts or 0) + 1
+
+ # Unknown channel — don't retry forever; record and drop.
+ if adapter is None:
+ delivery.status = NotificationDelivery.STATUS_FAILED
+ delivery.error = f'no adapter for channel {delivery.channel}'
+ db.session.commit()
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ try:
+ result = adapter.deliver(delivery, delivery.notification)
+ except Exception as exc:
+ delivery.error = str(exc)[:1000]
+ db.session.commit()
+ _fail(message, str(exc)[:500], delivery)
+ return
+
+ if result.status == DeliveryResult.SENT:
+ delivery.status = NotificationDelivery.STATUS_SENT
+ delivery.sent_at = datetime.utcnow()
+ delivery.provider_message_id = result.message_id
+ delivery.error = None
+ db.session.commit()
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ elif result.status == DeliveryResult.SKIPPED:
+ delivery.status = NotificationDelivery.STATUS_SKIPPED
+ delivery.error = result.error
+ db.session.commit()
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ else: # FAILED — let the queue retry / dead-letter
+ delivery.error = result.error
+ db.session.commit()
+ _fail(message, result.error or 'delivery failed', delivery)
+
+
+def _fail(message, error_message, delivery):
+ """Fail the queue message; if the queue dead-letters it, mark the delivery
+ failed so the row reflects the terminal state."""
+ res = QueueBusService.fail(GROUP_SLUG, QUEUE_SLUG, message['id'], error_message=error_message)
+ if res and res.get('status') == 'dead_letter':
+ delivery.status = NotificationDelivery.STATUS_FAILED
+ db.session.commit()
+
+
+def start_notification_consumer(app):
+ """Start the singleton notification consumer thread.
+
+ Skipped in testing mode (like the webhook consumer) to avoid background
+ races against per-test databases.
+ """
+ global _notification_consumer_thread
+ if _notification_consumer_thread is not None:
+ return
+ if app.config.get('ENV') == 'testing' or app.config.get('TESTING'):
+ return
+ consumer = NotificationConsumer(app)
+ consumer.start()
+ _notification_consumer_thread = consumer
+
+
+def stop_notification_consumer():
+ global _notification_consumer_thread
+ if _notification_consumer_thread is not None:
+ _notification_consumer_thread.stop()
+ _notification_consumer_thread = None
+
+
+def enqueue_notification_delivery(delivery_id, priority=0):
+ """Enqueue a single delivery (parity helper; service.send does this itself)."""
+ return NotificationBusService._enqueue(delivery_id, priority=priority)
diff --git a/backend/app/notifications/models.py b/backend/app/notifications/models.py
new file mode 100644
index 00000000..deb19612
--- /dev/null
+++ b/backend/app/notifications/models.py
@@ -0,0 +1,148 @@
+"""ORM models for the ServerKit Notification Bus.
+
+``Notification`` — the durable record of *what happened* (one row per
+ emitted event). Powers the in-app notification
+ center / bell and the delivery history.
+
+``NotificationDelivery`` — one attempt to tell *one recipient* on *one
+ channel*. This is the per-channel tracking that the
+ legacy fire-and-forget sender never had: status,
+ attempts, error, provider message-id, sent/read time.
+"""
+import json
+from datetime import datetime
+
+from app import db
+
+
+class Notification(db.Model):
+ __tablename__ = 'notifications'
+
+ # Severity levels (shared vocabulary with NotificationPreferences/monitoring)
+ SEVERITY_CRITICAL = 'critical'
+ SEVERITY_WARNING = 'warning'
+ SEVERITY_INFO = 'info'
+ SEVERITY_SUCCESS = 'success'
+ SEVERITY_TEST = 'test'
+
+ id = db.Column(db.Integer, primary_key=True)
+
+ # Event identity — e.g. 'backup.completed', 'security.alert'. Selects the
+ # template via the catalog.
+ event_key = db.Column(db.String(120), nullable=False, index=True)
+
+ # Coarse bucket used for per-user opt-out: system | security | backups | apps
+ category = db.Column(db.String(40), default='system', index=True)
+ severity = db.Column(db.String(20), default='info', index=True)
+
+ # Rendered, channel-agnostic summary (the subject line / bell headline).
+ title = db.Column(db.String(255), nullable=False)
+ body = db.Column(db.Text) # short plain-text summary for the in-app list
+
+ # The context dict passed to notify.send(), used by templates. JSON-encoded.
+ data_json = db.Column(db.Text)
+
+ # Human-readable description of the intended audience, for debugging/audit
+ # (e.g. 'admins', 'user:42', '[email protected]'). Not used for routing.
+ audience = db.Column(db.String(255))
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+
+ deliveries = db.relationship(
+ 'NotificationDelivery',
+ backref='notification',
+ cascade='all, delete-orphan',
+ lazy='dynamic',
+ )
+
+ def set_data(self, data):
+ self.data_json = json.dumps(data or {})
+
+ def get_data(self):
+ try:
+ return json.loads(self.data_json) if self.data_json else {}
+ except (json.JSONDecodeError, TypeError):
+ return {}
+
+ def to_dict(self, include_data=False):
+ out = {
+ 'id': self.id,
+ 'event_key': self.event_key,
+ 'category': self.category,
+ 'severity': self.severity,
+ 'title': self.title,
+ 'body': self.body,
+ 'audience': self.audience,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
+ if include_data:
+ out['data'] = self.get_data()
+ return out
+
+ def __repr__(self):
+ return f'<Notification {self.id} {self.event_key} {self.severity}>'
+
+
+class NotificationDelivery(db.Model):
+ __tablename__ = 'notification_deliveries'
+
+ # Outcome of the delivery attempt (NOT read-state — that's read_at).
+ STATUS_PENDING = 'pending' # queued, not yet attempted
+ STATUS_SENT = 'sent' # handed to the channel successfully
+ STATUS_FAILED = 'failed' # exhausted retries (dead-letter on the queue)
+ STATUS_SKIPPED = 'skipped' # intentionally not sent (e.g. no target)
+
+ # Channels
+ CHANNEL_INAPP = 'inapp'
+ CHANNEL_EMAIL = 'email'
+ CHANNEL_SLACK = 'slack'
+ CHANNEL_DISCORD = 'discord'
+ CHANNEL_TELEGRAM = 'telegram'
+ CHANNEL_WEBHOOK = 'webhook'
+
+ id = db.Column(db.Integer, primary_key=True)
+ notification_id = db.Column(
+ db.Integer, db.ForeignKey('notifications.id'), nullable=False, index=True
+ )
+
+ # Recipient user (nullable: bare-email / global-webhook recipients have no user).
+ recipient_user_id = db.Column(
+ db.Integer, db.ForeignKey('users.id'), nullable=True, index=True
+ )
+
+ channel = db.Column(db.String(40), nullable=False, index=True)
+ # The concrete destination for this channel: email address, telegram chat id,
+ # webhook url, etc. Null for in-app (the user_id is the destination).
+ target = db.Column(db.String(512))
+
+ status = db.Column(db.String(20), default=STATUS_PENDING, index=True)
+ attempts = db.Column(db.Integer, default=0)
+ error = db.Column(db.Text)
+ # Provider-assigned id (SendGrid/Postmark/etc.) for later bounce correlation.
+ provider_message_id = db.Column(db.String(255))
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+ sent_at = db.Column(db.DateTime)
+ # In-app read-state. Null = unread (the bell's unread count counts these).
+ read_at = db.Column(db.DateTime)
+
+ recipient = db.relationship('User', foreign_keys=[recipient_user_id])
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'notification_id': self.notification_id,
+ 'recipient_user_id': self.recipient_user_id,
+ 'channel': self.channel,
+ 'target': self.target,
+ 'status': self.status,
+ 'attempts': self.attempts,
+ 'error': self.error,
+ 'provider_message_id': self.provider_message_id,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'sent_at': self.sent_at.isoformat() if self.sent_at else None,
+ 'read_at': self.read_at.isoformat() if self.read_at else None,
+ }
+
+ def __repr__(self):
+ return f'<NotificationDelivery {self.id} {self.channel} {self.status}>'
diff --git a/backend/app/notifications/providers.py b/backend/app/notifications/providers.py
new file mode 100644
index 00000000..409f87c8
--- /dev/null
+++ b/backend/app/notifications/providers.py
@@ -0,0 +1,361 @@
+"""Email provider service + transports for the Notification Bus.
+
+Manages ``EmailProviderConnection`` rows (add / list / test / set-default /
+delete) and sends a rendered email through the configured transport:
+
+ SMTP (any) · SendGrid · Postmark · Amazon SES · Mailgun
+
+Secrets are encrypted at rest (see the model). The email channel adapter calls
+``EmailProviderService.default_provider()`` then ``.send(...)``; if no provider
+is configured it falls back to the legacy notifications.json SMTP config.
+"""
+import json
+import logging
+import smtplib
+import ssl
+from datetime import datetime
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+import requests
+
+from app import db
+from app.models.email_provider import EmailProviderConnection
+from app.utils.crypto import encrypt_secret, is_encrypted
+
+logger = logging.getLogger(__name__)
+
+# Per-provider field set + which fields are secret (encrypted at rest).
+SUPPORTED = {
+ 'smtp': {
+ 'name': 'Custom SMTP',
+ 'fields': ['host', 'port', 'username', 'password', 'use_tls'],
+ 'secrets': ['password'],
+ },
+ 'sendgrid': {
+ 'name': 'SendGrid',
+ 'fields': ['api_key'],
+ 'secrets': ['api_key'],
+ },
+ 'postmark': {
+ 'name': 'Postmark',
+ 'fields': ['server_token'],
+ 'secrets': ['server_token'],
+ },
+ 'ses': {
+ 'name': 'Amazon SES',
+ 'fields': ['access_key', 'secret_key', 'region'],
+ 'secrets': ['secret_key'],
+ },
+ 'mailgun': {
+ 'name': 'Mailgun',
+ 'fields': ['api_key', 'domain'],
+ 'secrets': ['api_key'],
+ },
+}
+
+_TIMEOUT = 20
+
+
+class EmailProviderService:
+
+ # ------------------------------------------------------------------
+ # CRUD
+ # ------------------------------------------------------------------
+ @classmethod
+ def list_providers(cls):
+ return EmailProviderConnection.query.order_by(
+ EmailProviderConnection.is_default.desc(),
+ EmailProviderConnection.created_at.asc(),
+ ).all()
+
+ @staticmethod
+ def get_provider(provider_id):
+ return EmailProviderConnection.query.get(provider_id)
+
+ @classmethod
+ def default_provider(cls):
+ """The active default provider, or the first active one, or None."""
+ row = EmailProviderConnection.query.filter_by(is_default=True, is_active=True).first()
+ if row:
+ return row
+ return EmailProviderConnection.query.filter_by(is_active=True).order_by(
+ EmailProviderConnection.created_at.asc()
+ ).first()
+
+ @classmethod
+ def add_provider(cls, data, user_id=None):
+ provider = (data.get('provider') or '').lower().strip()
+ if provider not in SUPPORTED:
+ raise ValueError(f'Unsupported email provider: {provider}')
+
+ spec = SUPPORTED[provider]
+ creds = {}
+ for field in spec['fields']:
+ value = data.get(field)
+ if value in (None, ''):
+ continue
+ if field in spec['secrets'] and isinstance(value, str) and not is_encrypted(value):
+ value = encrypt_secret(value)
+ creds[field] = value
+
+ make_default = bool(data.get('is_default'))
+ # First provider is implicitly the default.
+ if EmailProviderConnection.query.count() == 0:
+ make_default = True
+ if make_default:
+ EmailProviderConnection.query.update({EmailProviderConnection.is_default: False})
+
+ row = EmailProviderConnection(
+ provider=provider,
+ name=data.get('name') or spec['name'],
+ credentials_json=json.dumps(creds),
+ from_address=(data.get('from_address') or '').strip() or None,
+ from_name=(data.get('from_name') or 'ServerKit').strip(),
+ is_default=make_default,
+ is_active=data.get('is_active', True),
+ created_by=user_id,
+ )
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+ @classmethod
+ def set_default(cls, provider_id):
+ row = cls.get_provider(provider_id)
+ if not row:
+ return None
+ EmailProviderConnection.query.update({EmailProviderConnection.is_default: False})
+ row.is_default = True
+ row.is_active = True
+ db.session.commit()
+ return row
+
+ @classmethod
+ def delete_provider(cls, provider_id):
+ row = cls.get_provider(provider_id)
+ if not row:
+ return False
+ was_default = row.is_default
+ db.session.delete(row)
+ db.session.commit()
+ # Promote another provider to default if we removed the default one.
+ if was_default:
+ nxt = EmailProviderConnection.query.order_by(
+ EmailProviderConnection.created_at.asc()).first()
+ if nxt:
+ nxt.is_default = True
+ db.session.commit()
+ return True
+
+ # ------------------------------------------------------------------
+ # Sending
+ # ------------------------------------------------------------------
+ @classmethod
+ def send(cls, provider, to_addr, subject, html, text):
+ """Send one email via ``provider``. Returns
+ {'success', 'message_id', 'error'}."""
+ creds = provider.credentials()
+ sender = provider.from_address or creds.get('username') or 'serverkit@localhost'
+ from_name = provider.from_name or 'ServerKit'
+ try:
+ if provider.provider == 'smtp':
+ return cls._send_smtp(creds, sender, from_name, to_addr, subject, html, text)
+ if provider.provider == 'sendgrid':
+ return cls._send_sendgrid(creds, sender, from_name, to_addr, subject, html, text)
+ if provider.provider == 'postmark':
+ return cls._send_postmark(creds, sender, from_name, to_addr, subject, html, text)
+ if provider.provider == 'ses':
+ return cls._send_ses(creds, sender, to_addr, subject, html, text)
+ if provider.provider == 'mailgun':
+ return cls._send_mailgun(creds, sender, from_name, to_addr, subject, html, text)
+ except Exception as exc: # transport-level failure
+ return {'success': False, 'message_id': None, 'error': str(exc)[:500]}
+ return {'success': False, 'message_id': None, 'error': 'unknown provider'}
+
+ @staticmethod
+ def _mime(sender, from_name, to_addr, subject, html, text):
+ msg = MIMEMultipart('alternative')
+ msg['Subject'] = subject
+ msg['From'] = f'{from_name} <{sender}>'
+ msg['To'] = to_addr
+ msg.attach(MIMEText(text, 'plain', 'utf-8'))
+ msg.attach(MIMEText(html, 'html', 'utf-8'))
+ return msg
+
+ @classmethod
+ def _send_smtp(cls, creds, sender, from_name, to_addr, subject, html, text):
+ host = creds.get('host')
+ port = int(creds.get('port') or 587)
+ use_tls = creds.get('use_tls', True)
+ if isinstance(use_tls, str):
+ use_tls = use_tls.lower() not in ('0', 'false', 'no')
+ msg = cls._mime(sender, from_name, to_addr, subject, html, text)
+ if use_tls:
+ server = smtplib.SMTP(host, port, timeout=_TIMEOUT)
+ server.starttls(context=ssl.create_default_context())
+ else:
+ server = smtplib.SMTP_SSL(host, port, timeout=_TIMEOUT, context=ssl.create_default_context())
+ with server:
+ if creds.get('username') and creds.get('password'):
+ server.login(creds['username'], creds['password'])
+ server.send_message(msg)
+ return {'success': True, 'message_id': None, 'error': None}
+
+ @classmethod
+ def _send_sendgrid(cls, creds, sender, from_name, to_addr, subject, html, text):
+ resp = requests.post(
+ 'https://api.sendgrid.com/v3/mail/send',
+ headers={'Authorization': f"Bearer {creds.get('api_key')}",
+ 'Content-Type': 'application/json'},
+ json={
+ 'personalizations': [{'to': [{'email': to_addr}]}],
+ 'from': {'email': sender, 'name': from_name},
+ 'subject': subject,
+ 'content': [
+ {'type': 'text/plain', 'value': text},
+ {'type': 'text/html', 'value': html},
+ ],
+ },
+ timeout=_TIMEOUT,
+ )
+ if resp.status_code in (200, 201, 202):
+ return {'success': True, 'message_id': resp.headers.get('X-Message-Id'), 'error': None}
+ return {'success': False, 'message_id': None, 'error': f'SendGrid HTTP {resp.status_code}: {resp.text[:200]}'}
+
+ @classmethod
+ def _send_postmark(cls, creds, sender, from_name, to_addr, subject, html, text):
+ resp = requests.post(
+ 'https://api.postmarkapp.com/email',
+ headers={'X-Postmark-Server-Token': creds.get('server_token') or '',
+ 'Accept': 'application/json', 'Content-Type': 'application/json'},
+ json={
+ 'From': f'{from_name} <{sender}>',
+ 'To': to_addr,
+ 'Subject': subject,
+ 'HtmlBody': html,
+ 'TextBody': text,
+ 'MessageStream': 'outbound',
+ },
+ timeout=_TIMEOUT,
+ )
+ body = resp.json() if resp.content else {}
+ if resp.status_code == 200 and body.get('ErrorCode', 0) == 0:
+ return {'success': True, 'message_id': body.get('MessageID'), 'error': None}
+ return {'success': False, 'message_id': None,
+ 'error': f"Postmark: {body.get('Message') or resp.status_code}"}
+
+ @classmethod
+ def _send_mailgun(cls, creds, sender, from_name, to_addr, subject, html, text):
+ domain = creds.get('domain')
+ resp = requests.post(
+ f'https://api.mailgun.net/v3/{domain}/messages',
+ auth=('api', creds.get('api_key') or ''),
+ data={
+ 'from': f'{from_name} <{sender}>',
+ 'to': to_addr,
+ 'subject': subject,
+ 'text': text,
+ 'html': html,
+ },
+ timeout=_TIMEOUT,
+ )
+ if resp.status_code == 200:
+ body = resp.json() if resp.content else {}
+ return {'success': True, 'message_id': body.get('id'), 'error': None}
+ return {'success': False, 'message_id': None, 'error': f'Mailgun HTTP {resp.status_code}: {resp.text[:200]}'}
+
+ @classmethod
+ def _send_ses(cls, creds, sender, to_addr, subject, html, text):
+ client = cls._ses_client(creds)
+ resp = client.send_email(
+ Source=sender,
+ Destination={'ToAddresses': [to_addr]},
+ Message={
+ 'Subject': {'Data': subject, 'Charset': 'UTF-8'},
+ 'Body': {
+ 'Text': {'Data': text, 'Charset': 'UTF-8'},
+ 'Html': {'Data': html, 'Charset': 'UTF-8'},
+ },
+ },
+ )
+ return {'success': True, 'message_id': resp.get('MessageId'), 'error': None}
+
+ @staticmethod
+ def _ses_client(creds):
+ import boto3
+ return boto3.client(
+ 'ses',
+ aws_access_key_id=creds.get('access_key'),
+ aws_secret_access_key=creds.get('secret_key'),
+ region_name=creds.get('region') or 'us-east-1',
+ )
+
+ # ------------------------------------------------------------------
+ # Testing (validate credentials without sending)
+ # ------------------------------------------------------------------
+ @classmethod
+ def test_provider(cls, provider_id):
+ provider = cls.get_provider(provider_id)
+ if not provider:
+ return {'success': False, 'error': 'Provider not found'}
+ creds = provider.credentials()
+ try:
+ result = cls._test(provider.provider, creds)
+ except Exception as exc:
+ result = {'success': False, 'error': str(exc)[:300]}
+ provider.last_tested_at = datetime.utcnow()
+ provider.last_test_ok = bool(result.get('success'))
+ db.session.commit()
+ return result
+
+ @classmethod
+ def _test(cls, provider, creds):
+ if provider == 'smtp':
+ host = creds.get('host')
+ port = int(creds.get('port') or 587)
+ use_tls = creds.get('use_tls', True)
+ if isinstance(use_tls, str):
+ use_tls = use_tls.lower() not in ('0', 'false', 'no')
+ if use_tls:
+ server = smtplib.SMTP(host, port, timeout=_TIMEOUT)
+ server.starttls(context=ssl.create_default_context())
+ else:
+ server = smtplib.SMTP_SSL(host, port, timeout=_TIMEOUT, context=ssl.create_default_context())
+ with server:
+ if creds.get('username') and creds.get('password'):
+ server.login(creds['username'], creds['password'])
+ return {'success': True, 'message': 'SMTP connection OK'}
+
+ if provider == 'sendgrid':
+ resp = requests.get('https://api.sendgrid.com/v3/scopes',
+ headers={'Authorization': f"Bearer {creds.get('api_key')}"},
+ timeout=_TIMEOUT)
+ ok = resp.status_code == 200
+ return {'success': ok, 'message': 'SendGrid key OK' if ok else None,
+ 'error': None if ok else f'HTTP {resp.status_code}'}
+
+ if provider == 'postmark':
+ resp = requests.get('https://api.postmarkapp.com/server',
+ headers={'X-Postmark-Server-Token': creds.get('server_token') or '',
+ 'Accept': 'application/json'},
+ timeout=_TIMEOUT)
+ ok = resp.status_code == 200
+ return {'success': ok, 'message': 'Postmark token OK' if ok else None,
+ 'error': None if ok else f'HTTP {resp.status_code}'}
+
+ if provider == 'mailgun':
+ domain = creds.get('domain')
+ resp = requests.get(f'https://api.mailgun.net/v3/{domain}',
+ auth=('api', creds.get('api_key') or ''),
+ timeout=_TIMEOUT)
+ ok = resp.status_code == 200
+ return {'success': ok, 'message': 'Mailgun key OK' if ok else None,
+ 'error': None if ok else f'HTTP {resp.status_code}'}
+
+ if provider == 'ses':
+ client = cls._ses_client(creds)
+ client.get_send_quota()
+ return {'success': True, 'message': 'SES credentials OK'}
+
+ return {'success': False, 'error': 'unknown provider'}
diff --git a/backend/app/notifications/rendering.py b/backend/app/notifications/rendering.py
new file mode 100644
index 00000000..b0552333
--- /dev/null
+++ b/backend/app/notifications/rendering.py
@@ -0,0 +1,117 @@
+"""Jinja2 rendering for notification emails.
+
+`render_email()` turns a template name + context into a `(subject, html, text)`
+bundle. HTML is authored as Jinja templates under ``templates/email/`` that
+extend ``base.html``; the plain-text twin is taken from an optional
+``<template>.txt`` or generated from the title/body/data as a fallback so every
+email always ships a text alternative.
+
+Autoescaping is on for HTML, so caller-supplied data is safe to interpolate.
+"""
+import logging
+import os
+from datetime import datetime
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from app.notifications.branding import BRAND, SEVERITY_STYLES, style_for
+
+logger = logging.getLogger(__name__)
+
+TEMPLATES_DIR = os.path.join(os.path.dirname(__file__), 'templates')
+
+_env = None
+
+
+def env():
+ """Lazily build the shared Jinja environment."""
+ global _env
+ if _env is None:
+ _env = Environment(
+ loader=FileSystemLoader(TEMPLATES_DIR),
+ autoescape=select_autoescape(['html', 'xml']),
+ trim_blocks=True,
+ lstrip_blocks=True,
+ )
+ return _env
+
+
+def _hostname():
+ try:
+ if hasattr(os, 'uname'):
+ return os.uname().nodename
+ import socket
+ return socket.gethostname()
+ except Exception:
+ return 'serverkit'
+
+
+def _build_context(subject, severity, data, recipient, urls, hostname):
+ palette = style_for(severity)
+ data = data or {}
+ urls = urls or {}
+ now = datetime.now()
+ return {
+ 'brand': BRAND,
+ 'palette': palette,
+ 'severity_styles': SEVERITY_STYLES,
+ 'severity': severity,
+ 'severity_label': palette['label'],
+ 'subject': subject,
+ 'title': subject,
+ 'preheader': data.get('preheader') or data.get('summary') or subject,
+ 'data': data,
+ 'recipient': recipient or {},
+ 'hostname': hostname or _hostname(),
+ 'now': now.strftime('%Y-%m-%d %H:%M'),
+ 'year': now.year,
+ 'manage_url': urls.get('manage'),
+ 'unsubscribe_url': urls.get('unsubscribe'),
+ 'action_url': data.get('action_url') or urls.get('action'),
+ 'action_label': data.get('action_label') or 'Open ServerKit',
+ }
+
+
+def _render_html(template, ctx):
+ name = f'email/{template}.html'
+ try:
+ return env().get_template(name).render(**ctx)
+ except Exception as exc:
+ # Never let a template bug swallow a notification — fall back to generic.
+ logger.warning('Email template %s failed (%s); using generic', name, exc)
+ return env().get_template('email/generic.html').render(**ctx)
+
+
+def _render_text(template, ctx):
+ # Prefer an explicit text twin if the author provided one.
+ try:
+ return env().get_template(f'email/{template}.txt').render(**ctx)
+ except Exception:
+ pass
+ # Otherwise synthesize a clean text alternative from the context.
+ lines = [ctx['subject'], '=' * min(len(ctx['subject']), 60), '']
+ summary = ctx['data'].get('summary') or ctx['data'].get('message')
+ if summary:
+ lines += [str(summary), '']
+ for key, value in (ctx['data'] or {}).items():
+ if key in ('summary', 'message', 'preheader', 'action_url', 'action_label'):
+ continue
+ if isinstance(value, (str, int, float, bool)):
+ lines.append(f'{key.replace("_", " ").title()}: {value}')
+ if ctx.get('action_url'):
+ lines += ['', f'{ctx["action_label"]}: {ctx["action_url"]}']
+ lines += ['', '-' * 40, f'Sent by {ctx["brand"]["name"]} ({ctx["hostname"]}) at {ctx["now"]}']
+ if ctx.get('manage_url'):
+ lines.append(f'Manage notifications: {ctx["manage_url"]}')
+ return '\n'.join(lines)
+
+
+def render_email(template, subject, severity='info', data=None,
+ recipient=None, urls=None, hostname=None):
+ """Render an email to ``{'subject', 'html', 'text'}``."""
+ ctx = _build_context(subject, severity, data, recipient, urls, hostname)
+ return {
+ 'subject': subject,
+ 'html': _render_html(template or 'generic', ctx),
+ 'text': _render_text(template or 'generic', ctx),
+ }
diff --git a/backend/app/notifications/sdk.py b/backend/app/notifications/sdk.py
new file mode 100644
index 00000000..59bde523
--- /dev/null
+++ b/backend/app/notifications/sdk.py
@@ -0,0 +1,34 @@
+"""Plugin/SDK surface for the Notification Bus.
+
+Stable façade so callers (core services and plugins) depend on this rather than
+the service internals:
+
+ from app.plugins_sdk import notify
+ notify.send('backup.completed', to='admins', data={'app': 'blog'})
+
+Plugins can also extend the bus:
+
+ notify.register_event('myplugin.thing_ready', 'Your thing is ready',
+ template='generic', severity='success', category='apps')
+ notify.register_channel(MySmsAdapter())
+"""
+from app.notifications.service import NotificationBusService
+
+
+class NotifySdk:
+ def send(self, event, to, data=None, channels=None, severity=None, title=None, category=None):
+ """Emit a notification (non-blocking). See NotificationBusService.send."""
+ return NotificationBusService.send(
+ event, to, data=data, channels=channels,
+ severity=severity, title=title, category=category,
+ )
+
+ def register_event(self, event_key, title, template='generic', severity='info', category='system'):
+ """Add/override a catalog event so it renders through the pipeline."""
+ from app.notifications import catalog
+ return catalog.register(event_key, title, template=template, severity=severity, category=category)
+
+ def register_channel(self, adapter):
+ """Register a new channel adapter (must define ``key`` + ``deliver``)."""
+ from app.notifications.channels import register_adapter
+ return register_adapter(adapter)
diff --git a/backend/app/notifications/service.py b/backend/app/notifications/service.py
new file mode 100644
index 00000000..a1c53936
--- /dev/null
+++ b/backend/app/notifications/service.py
@@ -0,0 +1,453 @@
+"""NotificationBusService — the producer side of the Notification Bus.
+
+``send()`` is the one entry point. It is non-blocking: it records the event,
+plans per-recipient deliveries (honoring each user's preferences), persists the
+delivery rows, and enqueues the non-instant ones on the Queue Bus. A background
+``NotificationConsumer`` then renders + transmits each delivery.
+
+ from app.notifications.service import NotificationBusService
+ NotificationBusService.send('backup.completed', to='admins',
+ data={'app': 'blog', 'size': '2.3 GB'})
+"""
+import logging
+from datetime import datetime, time
+
+from app import db
+from app.models.notification_preferences import NotificationPreferences
+from app.notifications import catalog
+from app.notifications.models import Notification, NotificationDelivery
+from app.queue_bus.service import QueueBusService
+
+logger = logging.getLogger(__name__)
+
+GROUP_SLUG = 'serverkit-system'
+QUEUE_SLUG = 'notifications'
+QUEUE_CONFIG = {'max_attempts': 4, 'visibility_timeout_ms': 60000}
+
+
+class NotificationBusService:
+
+ # ------------------------------------------------------------------
+ # Public API
+ # ------------------------------------------------------------------
+ @classmethod
+ def send(cls, event, to, data=None, channels=None, severity=None, title=None, category=None):
+ """Emit a notification.
+
+ event — catalog key, e.g. 'backup.completed' (unknown keys render
+ via the generic template).
+ to — User | user-id | email | 'admins' | 'all' | list of those.
+ data — context dict for templates (and the in-app body).
+ channels — None = preference-driven (honor each user's prefs/quiet
+ hours); an explicit list = directed transactional send
+ (e.g. ['email']) that bypasses preference gating.
+ severity — override the catalog default.
+ title — override the computed title/subject.
+ category — override the catalog category (system/security/backups/apps).
+
+ Returns {'notification_id', 'deliveries'} immediately.
+ """
+ data = data or {}
+ meta = catalog.resolve(event, data, severity=severity, title=title)
+ severity = meta['severity']
+ category = category or meta['category']
+
+ notification = Notification(
+ event_key=event,
+ category=category,
+ severity=severity,
+ title=meta['title'],
+ body=data.get('summary') or data.get('message'),
+ audience=cls._describe(to),
+ )
+ notification.set_data(data)
+ db.session.add(notification)
+ db.session.flush() # assign notification.id
+
+ seen = set()
+ to_enqueue = []
+ inapp_deliveries = []
+ now = datetime.utcnow()
+ for recipient in cls._resolve_recipients(to):
+ for channel, target in cls._plan(recipient, channels, severity, category):
+ user = recipient['user']
+ key = (user.id if user else None, channel, target)
+ if key in seen:
+ continue
+ seen.add(key)
+ delivery = NotificationDelivery(
+ notification_id=notification.id,
+ recipient_user_id=user.id if user else None,
+ channel=channel,
+ target=target,
+ )
+ # In-app has nothing to transmit — the row IS the notification.
+ # Mark it sent now so the bell is instant; skip the queue.
+ if channel == NotificationDelivery.CHANNEL_INAPP:
+ delivery.status = NotificationDelivery.STATUS_SENT
+ delivery.sent_at = now
+ inapp_deliveries.append((user.id, delivery))
+ else:
+ delivery.status = NotificationDelivery.STATUS_PENDING
+ to_enqueue.append(delivery)
+ db.session.add(delivery)
+
+ db.session.commit()
+
+ priority = 10 if severity == 'critical' else 0
+ for delivery in to_enqueue:
+ try:
+ cls._enqueue(delivery.id, priority=priority)
+ except Exception as exc: # pragma: no cover - defensive
+ logger.error('Failed to enqueue notification delivery %s: %s', delivery.id, exc)
+
+ # Push the in-app deliveries to any open tabs in real time.
+ for user_id, delivery in inapp_deliveries:
+ cls._emit_inapp(user_id, notification, delivery.id)
+
+ return {'notification_id': notification.id, 'deliveries': len(seen)}
+
+ @staticmethod
+ def _emit_inapp(user_id, notification, delivery_id):
+ """Best-effort Socket.IO push of a new in-app notification."""
+ try:
+ from app import socketio
+ payload = notification.to_dict()
+ payload['delivery_id'] = delivery_id
+ payload['read'] = False
+ socketio.emit('notification', payload, room=f'user_{user_id}')
+ except Exception as exc: # pragma: no cover - socket is best-effort
+ logger.debug('Socket emit for notification skipped: %s', exc)
+
+ # ------------------------------------------------------------------
+ # Legacy system broadcast (what NotificationService.send_all delegates to)
+ # ------------------------------------------------------------------
+ @classmethod
+ def broadcast_system(cls, alerts):
+ """Route a legacy system alert to the configured *system* channels (the
+ global notifications.json webhooks/email) through the bus — non-blocking,
+ recorded, retried. Recipients are unchanged; only the delivery path is."""
+ alerts = alerts or []
+ from app.services.notification_service import NotificationService
+ config = NotificationService.get_config()
+ hostname = NotificationService.get_hostname()
+
+ sevs = [a.get('severity', 'info') for a in alerts]
+ if 'critical' in sevs:
+ severity = Notification.SEVERITY_CRITICAL
+ elif 'warning' in sevs:
+ severity = Notification.SEVERITY_WARNING
+ elif 'test' in sevs:
+ severity = Notification.SEVERITY_TEST
+ else:
+ severity = Notification.SEVERITY_INFO
+ title = f"[{severity.upper()}] ServerKit: {len(alerts)} alert(s) on {hostname}"
+
+ notification = Notification(
+ event_key='monitoring.alert', category='system', severity=severity,
+ title=title, body=(alerts[0].get('message') if alerts else None),
+ audience='system channels',
+ )
+ notification.set_data({'alerts': alerts, 'hostname': hostname})
+ db.session.add(notification)
+ db.session.flush()
+
+ targets = []
+ email = config.get('email', {})
+ if email.get('enabled') and email.get('smtp_host') and cls._sys_allows(email, severity):
+ for addr in email.get('to_emails', []) or []:
+ targets.append((NotificationDelivery.CHANNEL_EMAIL, addr))
+ discord = config.get('discord', {})
+ if discord.get('enabled') and discord.get('webhook_url') and cls._sys_allows(discord, severity):
+ targets.append((NotificationDelivery.CHANNEL_DISCORD, discord['webhook_url']))
+ slack = config.get('slack', {})
+ if slack.get('enabled') and slack.get('webhook_url') and cls._sys_allows(slack, severity):
+ targets.append((NotificationDelivery.CHANNEL_SLACK, slack['webhook_url']))
+ telegram = config.get('telegram', {})
+ if telegram.get('enabled') and telegram.get('chat_id') and cls._sys_allows(telegram, severity):
+ targets.append((NotificationDelivery.CHANNEL_TELEGRAM, telegram['chat_id']))
+ webhook = config.get('generic_webhook', {})
+ if webhook.get('enabled') and webhook.get('url') and cls._sys_allows(webhook, severity):
+ targets.append((NotificationDelivery.CHANNEL_WEBHOOK, webhook['url']))
+
+ rows = []
+ for channel, target in targets:
+ delivery = NotificationDelivery(
+ notification_id=notification.id, recipient_user_id=None,
+ channel=channel, target=target, status=NotificationDelivery.STATUS_PENDING,
+ )
+ db.session.add(delivery)
+ rows.append(delivery)
+ db.session.commit()
+
+ priority = 10 if severity == Notification.SEVERITY_CRITICAL else 0
+ for delivery in rows:
+ try:
+ cls._enqueue(delivery.id, priority=priority)
+ except Exception as exc: # pragma: no cover - defensive
+ logger.error('Failed to enqueue system delivery %s: %s', delivery.id, exc)
+
+ return {'success': True, 'results': {}, 'queued': len(rows),
+ 'notification_id': notification.id}
+
+ @staticmethod
+ def _sys_allows(channel_cfg, severity):
+ notify_on = channel_cfg.get('notify_on', ['critical', 'warning'])
+ return severity in notify_on or severity == Notification.SEVERITY_TEST
+
+ # ------------------------------------------------------------------
+ # Queue plumbing
+ # ------------------------------------------------------------------
+ @classmethod
+ def _enqueue(cls, delivery_id, priority=0):
+ QueueBusService.ensure_queue(GROUP_SLUG, QUEUE_SLUG, config=QUEUE_CONFIG)
+ return QueueBusService.send(
+ GROUP_SLUG, QUEUE_SLUG, {'delivery_id': delivery_id}, priority=priority,
+ )
+
+ # ------------------------------------------------------------------
+ # Recipient resolution
+ # ------------------------------------------------------------------
+ @classmethod
+ def _resolve_recipients(cls, to):
+ """Normalize ``to`` into a list of {'user': User|None, 'email': str|None}."""
+ from app.models.user import User
+
+ if to is None:
+ return []
+ if isinstance(to, (list, tuple, set)):
+ out = []
+ for item in to:
+ out.extend(cls._resolve_recipients(item))
+ return out
+ if isinstance(to, User):
+ return [{'user': to, 'email': None}]
+ if isinstance(to, bool):
+ return []
+ if isinstance(to, int):
+ user = User.query.get(to)
+ return [{'user': user, 'email': None}] if user else []
+ if isinstance(to, str):
+ value = to.strip()
+ low = value.lower()
+ if low == 'admins':
+ return [{'user': u, 'email': None}
+ for u in User.query.filter_by(role='admin').all()]
+ if low in ('all', 'everyone'):
+ return [{'user': u, 'email': None} for u in User.query.all()]
+ if '@' in value:
+ return [{'user': None, 'email': value}]
+ user = User.query.filter_by(username=value).first()
+ return [{'user': user, 'email': None}] if user else []
+ return []
+
+ # ------------------------------------------------------------------
+ # Delivery planning
+ # ------------------------------------------------------------------
+ @classmethod
+ def _plan(cls, recipient, channels, severity, category):
+ """Return a list of (channel, target) for one recipient."""
+ user = recipient['user']
+ email = recipient['email']
+
+ # Bare email recipient — only the email channel applies.
+ if user is None:
+ if email and (channels is None or 'email' in channels):
+ return [(NotificationDelivery.CHANNEL_EMAIL, email)]
+ return []
+
+ prefs = NotificationPreferences.get_or_create(user.id)
+ directed = channels is not None
+
+ if directed:
+ wanted = list(channels)
+ else:
+ if not prefs.enabled:
+ return []
+ if not cls._severity_allowed(prefs, severity):
+ return []
+ if not cls._category_allowed(prefs, category):
+ return []
+ if cls._suppressed_by_quiet_hours(prefs, severity):
+ return []
+ # The in-app bell is always on for an enabled user.
+ wanted = list(set(prefs.get_channels()) | {NotificationDelivery.CHANNEL_INAPP})
+
+ plan = []
+ for channel in wanted:
+ target = cls._target_for(channel, user, prefs)
+ if channel != NotificationDelivery.CHANNEL_INAPP and not target:
+ continue # no destination for this channel/user
+ plan.append((channel, target))
+ return plan
+
+ @staticmethod
+ def _target_for(channel, user, prefs):
+ if channel == NotificationDelivery.CHANNEL_INAPP:
+ return None
+ if channel == NotificationDelivery.CHANNEL_EMAIL:
+ return (prefs.email if prefs else None) or user.email
+ if channel == NotificationDelivery.CHANNEL_DISCORD:
+ return prefs.discord_webhook if prefs else None
+ if channel == NotificationDelivery.CHANNEL_TELEGRAM:
+ return prefs.telegram_chat_id if prefs else None
+ # slack / generic webhook are system-wide today — no per-user target.
+ return None
+
+ # ------------------------------------------------------------------
+ # Preference gating
+ # ------------------------------------------------------------------
+ @staticmethod
+ def _severity_allowed(prefs, severity):
+ if severity == Notification.SEVERITY_CRITICAL:
+ return True # critical always reaches the user
+ return severity in prefs.get_severities()
+
+ @staticmethod
+ def _category_allowed(prefs, category):
+ return prefs.get_categories().get(category, True)
+
+ @staticmethod
+ def _suppressed_by_quiet_hours(prefs, severity):
+ if not prefs.quiet_hours_enabled or severity == Notification.SEVERITY_CRITICAL:
+ return False
+ try:
+ sh, sm = (int(x) for x in (prefs.quiet_hours_start or '22:00').split(':'))
+ eh, em = (int(x) for x in (prefs.quiet_hours_end or '08:00').split(':'))
+ except (ValueError, AttributeError):
+ return False
+ now = datetime.now().time()
+ start, end = time(sh, sm), time(eh, em)
+ if start <= end:
+ return start <= now <= end
+ return now >= start or now <= end # window wraps midnight
+
+ # ------------------------------------------------------------------
+ @staticmethod
+ def _describe(to):
+ if isinstance(to, str):
+ return to[:255]
+ if isinstance(to, int):
+ return f'user:{to}'
+ if isinstance(to, (list, tuple, set)):
+ return f'{len(to)} recipients'
+ user_id = getattr(to, 'id', None)
+ return f'user:{user_id}' if user_id is not None else 'recipients'
+
+ # ------------------------------------------------------------------
+ # In-app notification center (the bell + history)
+ # ------------------------------------------------------------------
+ @staticmethod
+ def _inbox_query(user_id):
+ return (
+ NotificationDelivery.query
+ .filter_by(recipient_user_id=user_id,
+ channel=NotificationDelivery.CHANNEL_INAPP)
+ )
+
+ @classmethod
+ def inbox(cls, user_id, limit=20, offset=0, unread_only=False):
+ """Return the current user's in-app notifications, newest first."""
+ query = cls._inbox_query(user_id)
+ if unread_only:
+ query = query.filter(NotificationDelivery.read_at.is_(None))
+ rows = (query.order_by(NotificationDelivery.created_at.desc())
+ .limit(limit).offset(offset).all())
+ items = []
+ for delivery in rows:
+ notification = delivery.notification
+ item = notification.to_dict() if notification else {}
+ item.update({
+ 'delivery_id': delivery.id,
+ 'read': delivery.read_at is not None,
+ 'created_at': (delivery.created_at.isoformat()
+ if delivery.created_at else item.get('created_at')),
+ })
+ items.append(item)
+ return items
+
+ @classmethod
+ def unread_count(cls, user_id):
+ return cls._inbox_query(user_id).filter(
+ NotificationDelivery.read_at.is_(None)
+ ).count()
+
+ @classmethod
+ def mark_read(cls, user_id, delivery_id):
+ """Mark one in-app notification read. Returns True if it changed."""
+ delivery = cls._inbox_query(user_id).filter_by(id=delivery_id).first()
+ if not delivery:
+ return False
+ if delivery.read_at is None:
+ delivery.read_at = datetime.utcnow()
+ db.session.commit()
+ return True
+
+ @classmethod
+ def mark_all_read(cls, user_id):
+ """Mark every unread in-app notification read. Returns the count."""
+ now = datetime.utcnow()
+ updated = (cls._inbox_query(user_id)
+ .filter(NotificationDelivery.read_at.is_(None))
+ .update({NotificationDelivery.read_at: now},
+ synchronize_session=False))
+ db.session.commit()
+ return updated
+
+ # ------------------------------------------------------------------
+ # Delivery log / ops (admin)
+ # ------------------------------------------------------------------
+ @classmethod
+ def delivery_log(cls, status=None, channel=None, limit=50, offset=0):
+ """Admin view: recent deliveries across all users, newest first."""
+ query = NotificationDelivery.query
+ if status:
+ query = query.filter_by(status=status)
+ if channel:
+ query = query.filter_by(channel=channel)
+ rows = (query.order_by(NotificationDelivery.created_at.desc())
+ .limit(limit).offset(offset).all())
+ out = []
+ for delivery in rows:
+ notification = delivery.notification
+ item = delivery.to_dict()
+ item['event_key'] = notification.event_key if notification else None
+ item['title'] = notification.title if notification else None
+ item['notif_severity'] = notification.severity if notification else None
+ out.append(item)
+ return out
+
+ @classmethod
+ def delivery_stats(cls):
+ from sqlalchemy import func
+ by_status = dict(
+ db.session.query(NotificationDelivery.status, func.count())
+ .group_by(NotificationDelivery.status).all()
+ )
+ by_channel = dict(
+ db.session.query(NotificationDelivery.channel, func.count())
+ .group_by(NotificationDelivery.channel).all()
+ )
+ return {
+ 'by_status': by_status,
+ 'by_channel': by_channel,
+ 'total': sum(by_status.values()),
+ }
+
+ @classmethod
+ def retry_delivery(cls, delivery_id):
+ """Re-queue a failed/skipped delivery. Returns the dict, or None."""
+ delivery = NotificationDelivery.query.get(delivery_id)
+ if not delivery:
+ return None
+ if delivery.channel == NotificationDelivery.CHANNEL_INAPP:
+ delivery.status = NotificationDelivery.STATUS_SENT
+ delivery.sent_at = datetime.utcnow()
+ delivery.error = None
+ db.session.commit()
+ return delivery.to_dict()
+ delivery.status = NotificationDelivery.STATUS_PENDING
+ delivery.error = None
+ db.session.commit()
+ cls._enqueue(delivery.id, priority=5)
+ return delivery.to_dict()
diff --git a/backend/app/notifications/templates/email/backup_completed.html b/backend/app/notifications/templates/email/backup_completed.html
new file mode 100644
index 00000000..6dcbc41b
--- /dev/null
+++ b/backend/app/notifications/templates/email/backup_completed.html
@@ -0,0 +1,14 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import button, metrics with context %}
+{% block content %}
+ <p style="margin:0 0 18px;">Your scheduled backup finished successfully{% if data.app %} for <strong class="sk-ink" style="color:{{ brand.ink }};">{{ data.app }}</strong>{% endif %}.</p>
+ {% set facts = [] %}
+ {% if data.size %}{% set _ = facts.append({'label': 'Size', 'value': data.size, 'mono': true}) %}{% endif %}
+ {% if data.duration %}{% set _ = facts.append({'label': 'Duration', 'value': data.duration, 'mono': true}) %}{% endif %}
+ {% if data.destination %}{% set _ = facts.append({'label': 'Destination', 'value': data.destination}) %}{% endif %}
+ {% if data.completed_at %}{% set _ = facts.append({'label': 'Completed', 'value': data.completed_at}) %}{% endif %}
+ {% if facts %}{{ metrics(facts) }}{% endif %}
+ {% if action_url %}
+ <div style="margin-top:26px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/notifications/templates/email/base.html b/backend/app/notifications/templates/email/base.html
new file mode 100644
index 00000000..b4b687c9
--- /dev/null
+++ b/backend/app/notifications/templates/email/base.html
@@ -0,0 +1,96 @@
+{% from 'email/partials/_macros.html' import status_pill with context %}
+<!DOCTYPE html>
+<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="x-apple-disable-message-reformatting">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<title>{{ subject }}</title>
+<style>
+ body { margin:0; padding:0; width:100% !important; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
+ table { border-collapse:collapse; }
+ img { border:0; line-height:100%; outline:none; text-decoration:none; }
+ a { color:{{ brand.accent }}; }
+ @media (prefers-color-scheme: dark) {
+ .sk-page { background:{{ brand.dark_page_bg }} !important; }
+ .sk-card { background:{{ brand.dark_card_bg }} !important; border-color:{{ brand.dark_border }} !important; }
+ .sk-ink { color:{{ brand.dark_ink }} !important; }
+ .sk-muted { color:{{ brand.dark_muted }} !important; }
+ .sk-faint { color:{{ brand.dark_muted }} !important; }
+ .sk-code { background:{{ brand.dark_code_bg }} !important; color:{{ brand.dark_ink }} !important; }
+ .sk-hr { border-color:{{ brand.dark_border }} !important; }
+ }
+ @media only screen and (max-width:620px) {
+ .sk-container { width:100% !important; }
+ .sk-pad { padding-left:22px !important; padding-right:22px !important; }
+ }
+</style>
+</head>
+<body class="sk-page" style="margin:0; padding:0; background:{{ brand.page_bg }};">
+ <div style="display:none; max-height:0; overflow:hidden; opacity:0; mso-hide:all; font-size:1px; line-height:1px; color:{{ brand.page_bg }};">{{ preheader }}</div>
+
+ <table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0" class="sk-page" style="background:{{ brand.page_bg }};">
+ <tr>
+ <td align="center" style="padding:34px 16px;">
+ <table role="presentation" width="600" border="0" cellpadding="0" cellspacing="0" class="sk-container" style="width:600px; max-width:600px;">
+
+ <!-- Masthead -->
+ <tr>
+ <td class="sk-pad" style="padding:2px 10px 18px;">
+ <table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr>
+ <td style="padding-right:11px;">
+ <table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr>
+ <td width="36" height="36" align="center" valign="middle" style="background:{{ brand.accent }}; border-radius:10px; font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif; font-size:18px; font-weight:700; line-height:36px; color:#ffffff;">S</td>
+ </tr></table>
+ </td>
+ <td valign="middle" class="sk-ink" style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif; font-size:18px; font-weight:700; letter-spacing:.2px; color:{{ brand.ink }};">ServerKit</td>
+ </tr></table>
+ </td>
+ </tr>
+
+ <!-- Card -->
+ <tr>
+ <td class="sk-card" style="background:{{ brand.card_bg }}; border:1px solid {{ brand.border }}; border-radius:14px;">
+ <table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td class="sk-pad" style="padding:30px 34px 0;">
+ {% block status %}{{ status_pill() }}{% endblock %}
+ </td>
+ </tr>
+ <tr>
+ <td class="sk-pad sk-ink" style="padding:16px 34px 0; font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif; font-size:22px; font-weight:700; line-height:1.3; color:{{ brand.ink }};">
+ {% block heading %}{{ title }}{% endblock %}
+ </td>
+ </tr>
+ <tr>
+ <td class="sk-pad" style="padding:12px 34px 32px;">
+ <div class="sk-muted" style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif; font-size:15px; line-height:1.65; color:{{ brand.muted }};">
+ {% block content %}{% endblock %}
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+
+ <!-- Footer -->
+ <tr>
+ <td class="sk-pad" style="padding:22px 26px 6px;">
+ <div class="sk-faint" style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif; font-size:12px; line-height:1.7; color:{{ brand.faint }};">
+ Sent by <span class="sk-muted" style="color:{{ brand.muted }};">ServerKit</span> &middot; {{ hostname }} &middot; {{ now }}<br>
+ {% if manage_url %}<a href="{{ manage_url }}" style="color:{{ brand.accent }}; text-decoration:none;">Manage notifications</a>{% endif %}
+ {% if manage_url and unsubscribe_url %}&nbsp;&middot;&nbsp;{% endif %}
+ {% if unsubscribe_url %}<a href="{{ unsubscribe_url }}" style="color:{{ brand.faint }}; text-decoration:underline;">Unsubscribe</a>{% endif %}
+ </div>
+ </td>
+ </tr>
+
+ </table>
+ </td>
+ </tr>
+ </table>
+</body>
+</html>
diff --git a/backend/app/notifications/templates/email/generic.html b/backend/app/notifications/templates/email/generic.html
new file mode 100644
index 00000000..59ab3a3b
--- /dev/null
+++ b/backend/app/notifications/templates/email/generic.html
@@ -0,0 +1,13 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import button, metrics with context %}
+{% block content %}
+ {% if data.summary or data.message %}
+ <p style="margin:0 0 18px;">{{ data.summary or data.message }}</p>
+ {% endif %}
+ {% if data.facts %}
+ {{ metrics(data.facts) }}
+ {% endif %}
+ {% if action_url %}
+ <div style="margin-top:26px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/notifications/templates/email/invitation.html b/backend/app/notifications/templates/email/invitation.html
new file mode 100644
index 00000000..19f518fd
--- /dev/null
+++ b/backend/app/notifications/templates/email/invitation.html
@@ -0,0 +1,14 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import button, metrics with context %}
+{% block content %}
+ <p style="margin:0 0 16px;">{% if data.inviter %}<strong class="sk-ink" style="color:{{ brand.ink }};">{{ data.inviter }}</strong> has invited you{% else %}You've been invited{% endif %} to join {% if data.workspace %}<strong class="sk-ink" style="color:{{ brand.ink }};">{{ data.workspace }}</strong> on {% endif %}ServerKit.</p>
+ {% if data.role %}
+ {{ metrics([{'label': 'Your role', 'value': data.role}]) }}
+ {% endif %}
+ {% if action_url %}
+ <div style="margin-top:24px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+ {% if data.expires %}
+ <p class="sk-faint" style="margin:18px 0 0; font-size:13px; color:{{ brand.faint }};">This invitation expires {{ data.expires }}.</p>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/notifications/templates/email/monitoring_alert.html b/backend/app/notifications/templates/email/monitoring_alert.html
new file mode 100644
index 00000000..bf2d2997
--- /dev/null
+++ b/backend/app/notifications/templates/email/monitoring_alert.html
@@ -0,0 +1,14 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import alert_card, button with context %}
+{% block heading %}{{ data.alerts|length }} alert{{ 's' if data.alerts|length != 1 else '' }} on {{ hostname }}{% endblock %}
+{% block content %}
+ {% if data.intro %}
+ <p style="margin:0 0 18px;">{{ data.intro }}</p>
+ {% endif %}
+ {% for alert in data.alerts %}
+ {{ alert_card(alert) }}
+ {% endfor %}
+ {% if action_url %}
+ <div style="margin-top:14px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/notifications/templates/email/monitoring_alert.txt b/backend/app/notifications/templates/email/monitoring_alert.txt
new file mode 100644
index 00000000..74abb7e9
--- /dev/null
+++ b/backend/app/notifications/templates/email/monitoring_alert.txt
@@ -0,0 +1,15 @@
+{{ subject }}
+========================================
+{{ data.alerts|length }} alert(s) on {{ hostname }}
+
+{% for alert in data.alerts %}
+[{{ alert.severity|upper }}] {{ alert.type or 'alert' }}
+{{ alert.message }}
+{% if 'value' in alert %} Current: {{ alert.value }}
+{% endif %}
+{% if 'threshold' in alert %} Threshold: {{ alert.threshold }}
+{% endif %}
+
+{% endfor %}
+----------------------------------------
+Sent by ServerKit ({{ hostname }}) at {{ now }}
diff --git a/backend/app/notifications/templates/email/partials/_macros.html b/backend/app/notifications/templates/email/partials/_macros.html
new file mode 100644
index 00000000..b6760203
--- /dev/null
+++ b/backend/app/notifications/templates/email/partials/_macros.html
@@ -0,0 +1,67 @@
+{# Reusable, email-client-safe building blocks. Import WITH CONTEXT so the
+ macros can read `brand` and `palette` from the render context:
+ {% from 'email/partials/_macros.html' import status_pill, button, metrics, chip with context %}
+#}
+
+{# A severity pill: tinted lozenge + leading dot, all solid colors. #}
+{% macro status_pill(label=None) -%}
+<table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr>
+<td style="background:{{ palette.bg }};border-radius:999px;padding:6px 13px;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:12px;font-weight:600;line-height:1;letter-spacing:.5px;text-transform:uppercase;color:{{ palette.text }};">
+&#9679;&nbsp; {{ label or palette.label }}
+</td>
+</tr></table>
+{%- endmacro %}
+
+{# Bulletproof CTA button. #}
+{% macro button(url, label) -%}
+<table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr>
+<td align="center" bgcolor="{{ brand.accent }}" style="border-radius:9px;">
+<a href="{{ url }}" target="_blank" style="display:inline-block;padding:13px 30px;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:15px;font-weight:600;line-height:1;color:#ffffff;text-decoration:none;border-radius:9px;">{{ label }}</a>
+</td>
+</tr></table>
+{%- endmacro %}
+
+{# Inline monospace value chip — for hostnames, sizes, ids, durations. #}
+{% macro chip(value) -%}
+<span class="sk-code" style="font-family:'SFMono-Regular',ui-monospace,Consolas,'Liberation Mono',Menlo,monospace;font-size:13px;background:{{ brand.code_bg }};color:{{ brand.ink }};padding:2px 7px;border-radius:5px;white-space:nowrap;">{{ value }}</span>
+{%- endmacro %}
+
+{# A facts table. rows = list of {label, value, mono?}. #}
+{% macro metrics(rows) -%}
+<table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0" style="margin:6px 0 2px;">
+{% for row in rows %}
+<tr>
+<td class="sk-muted" style="padding:9px 0;border-bottom:1px solid {{ brand.border }};font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:14px;color:{{ brand.muted }};">{{ row.label }}</td>
+<td align="right" class="sk-ink" style="padding:9px 0;border-bottom:1px solid {{ brand.border }};font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:14px;font-weight:600;color:{{ brand.ink }};">
+{% if row.mono %}{{ chip(row.value) }}{% else %}{{ row.value }}{% endif %}
+</td>
+</tr>
+{% endfor %}
+</table>
+{%- endmacro %}
+
+{# One alert in a multi-alert (monitoring) email — left-bordered, colored by
+ its own severity. ``severity_styles`` comes from the render context. #}
+{% macro alert_card(alert) -%}
+{% set st = severity_styles.get(alert.severity, severity_styles['info']) %}
+<table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0" style="margin-bottom:12px;"><tr>
+<td style="background:{{ st.bg }};border-left:4px solid {{ st.dot }};border-radius:8px;padding:14px 16px;">
+<div style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:11px;font-weight:700;letter-spacing:.5px;text-transform:uppercase;color:{{ st.text }};">{{ st.label }}{% if alert.type %} &middot; {{ alert.type }}{% endif %}</div>
+<div class="sk-ink" style="margin-top:6px;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:14px;line-height:1.5;color:{{ brand.ink }};">{{ alert.message }}</div>
+{% if 'value' in alert or 'threshold' in alert %}
+<div class="sk-muted" style="margin-top:8px;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:13px;color:{{ brand.muted }};">
+{% if 'value' in alert %}Current: <strong class="sk-ink" style="color:{{ brand.ink }};">{{ alert.value }}</strong>{% endif %}
+{% if 'value' in alert and 'threshold' in alert %}&nbsp;&nbsp;&middot;&nbsp;&nbsp;{% endif %}
+{% if 'threshold' in alert %}Threshold: <strong class="sk-ink" style="color:{{ brand.ink }};">{{ alert.threshold }}</strong>{% endif %}
+</div>
+{% endif %}
+</td>
+</tr></table>
+{%- endmacro %}
+
+{# Horizontal rule that respects dark mode. #}
+{% macro divider() -%}
+<table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0"><tr>
+<td class="sk-hr" style="border-top:1px solid {{ brand.border }};font-size:0;line-height:0;height:1px;">&nbsp;</td>
+</tr></table>
+{%- endmacro %}
diff --git a/backend/app/notifications/templates/email/security_alert.html b/backend/app/notifications/templates/email/security_alert.html
new file mode 100644
index 00000000..a6476a95
--- /dev/null
+++ b/backend/app/notifications/templates/email/security_alert.html
@@ -0,0 +1,14 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import button, metrics, chip with context %}
+{% block content %}
+ <p style="margin:0 0 16px;">{{ data.message or 'A security event was detected that may need your attention.' }}</p>
+ {% set facts = [] %}
+ {% if data.alert_type %}{% set _ = facts.append({'label': 'Type', 'value': data.alert_type}) %}{% endif %}
+ {% if data.source_ip %}{% set _ = facts.append({'label': 'Source IP', 'value': data.source_ip, 'mono': true}) %}{% endif %}
+ {% if data.identity %}{% set _ = facts.append({'label': 'Account', 'value': data.identity}) %}{% endif %}
+ {% set _ = facts.append({'label': 'Server', 'value': data.hostname or hostname, 'mono': true}) %}
+ {{ metrics(facts) }}
+ {% if action_url %}
+ <div style="margin-top:26px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/notifications/templates/email/welcome.html b/backend/app/notifications/templates/email/welcome.html
new file mode 100644
index 00000000..510aba94
--- /dev/null
+++ b/backend/app/notifications/templates/email/welcome.html
@@ -0,0 +1,13 @@
+{% extends 'email/base.html' %}
+{% from 'email/partials/_macros.html' import button with context %}
+{% block content %}
+ <p style="margin:0 0 16px;">Hi{% if recipient.name %} {{ recipient.name }}{% endif %}, welcome to ServerKit — your account is ready to go.</p>
+ {% if data.summary %}
+ <p style="margin:0 0 16px;">{{ data.summary }}</p>
+ {% else %}
+ <p style="margin:0 0 16px;">From here you can deploy apps, manage databases and domains, watch your servers in real time, and wire up automations — all from one panel.</p>
+ {% endif %}
+ {% if action_url %}
+ <div style="margin-top:24px;">{{ button(action_url, action_label) }}</div>
+ {% endif %}
+{% endblock %}
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.py
index 3ea1c41e..017cbfbb 100644
--- a/backend/app/plugins_sdk/__init__.py
+++ b/backend/app/plugins_sdk/__init__.py
@@ -89,8 +89,10 @@ def audit(action, target_type, target_id=None, details=None, user_id=None):
# lazily-safe: ai.py only depends on the AI tool registry, not on a running app.
from app.plugins_sdk import ai
from app.queue_bus.sdk import QueueBusSdk
+from app.notifications.sdk import NotifySdk
queue = QueueBusSdk()
+notify = NotifySdk()
__all__ = [
'db',
@@ -103,4 +105,5 @@ __all__ = [
'audit',
'ai',
'queue',
+ 'notify',
]
diff --git a/backend/app/services/connection_registry.py b/backend/app/services/connection_registry.py
index 08ff659b..715d7f8d 100644
--- a/backend/app/services/connection_registry.py
+++ b/backend/app/services/connection_registry.py
@@ -40,7 +40,7 @@ class ConnectionRegistry:
@classmethod
def list_all(cls, user_id=None):
out = []
- for fn in (cls._source, cls._dns, cls._infra, cls._registrar, cls._storage):
+ for fn in (cls._source, cls._dns, cls._infra, cls._registrar, cls._storage, cls._email):
try:
out += fn(user_id) if fn is cls._source else fn()
except Exception as e: # one failing store never breaks the whole list
@@ -91,6 +91,18 @@ class ConnectionRegistry:
for c in RegistrarConnection.query.all()
]
+ @staticmethod
+ def _email():
+ from app.models.email_provider import EmailProviderConnection
+ out = []
+ for c in EmailProviderConnection.query.all():
+ scope = 'SMTP' if c.provider == 'smtp' else 'API key'
+ if c.is_default:
+ scope += ' · default'
+ out.append(_entry('email', c.provider, c.name, id=c.id, scope=scope,
+ encrypted=True, created_at=c.created_at))
+ return out
+
@staticmethod
def _storage():
from app.services.storage_provider_service import StorageProviderService
diff --git a/backend/app/services/notification_service.py b/backend/app/services/notification_service.py
index 911659e4..355bdff2 100644
--- a/backend/app/services/notification_service.py
+++ b/backend/app/services/notification_service.py
@@ -396,118 +396,6 @@ class NotificationService:
# ==========================================
# EMAIL
# ==========================================
- @classmethod
- def _get_email_template(cls, alerts: List[Dict]) -> str:
- """Generate HTML email template for alerts."""
- hostname = cls.get_hostname()
- timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
-
- # Color mapping for severity
- severity_styles = {
- 'critical': {'bg': '#fef2f2', 'border': '#ef4444', 'text': '#dc2626'},
- 'warning': {'bg': '#fffbeb', 'border': '#f59e0b', 'text': '#d97706'},
- 'info': {'bg': '#eff6ff', 'border': '#3b82f6', 'text': '#2563eb'},
- 'success': {'bg': '#f0fdf4', 'border': '#22c55e', 'text': '#16a34a'},
- 'test': {'bg': '#f9fafb', 'border': '#6b7280', 'text': '#4b5563'}
- }
-
- alerts_html = ""
- for alert in alerts:
- severity = alert.get('severity', 'info')
- style = severity_styles.get(severity, severity_styles['info'])
-
- alert_html = f"""
- <div style="margin-bottom: 16px; padding: 16px; background-color: {style['bg']};
- border-left: 4px solid {style['border']}; border-radius: 4px;">
- <div style="color: {style['text']}; font-weight: 600; font-size: 14px;
- text-transform: uppercase; margin-bottom: 8px;">
- {severity}: {alert.get('type', 'Alert').upper()}
- </div>
- <div style="color: #374151; font-size: 14px;">
- {alert.get('message', 'No message')}
- </div>
- """
-
- if 'value' in alert or 'threshold' in alert:
- alert_html += '<div style="margin-top: 12px; font-size: 13px; color: #6b7280;">'
- if 'value' in alert:
- alert_html += f'<span style="margin-right: 16px;">Current: <strong>{alert["value"]}</strong></span>'
- if 'threshold' in alert:
- alert_html += f'<span>Threshold: <strong>{alert["threshold"]}</strong></span>'
- alert_html += '</div>'
-
- alert_html += '</div>'
- alerts_html += alert_html
-
- template = f"""
- <!DOCTYPE html>
- <html>
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- </head>
- <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
- line-height: 1.6; color: #374151; max-width: 600px; margin: 0 auto; padding: 20px;">
-
- <!-- Header -->
- <div style="text-align: center; padding: 24px 0; border-bottom: 1px solid #e5e7eb;">
- <h1 style="margin: 0; color: #111827; font-size: 24px;">
- ServerKit Alert
- </h1>
- <p style="margin: 8px 0 0 0; color: #6b7280; font-size: 14px;">
- {len(alerts)} alert(s) triggered on {hostname}
- </p>
- </div>
-
- <!-- Alerts -->
- <div style="padding: 24px 0;">
- {alerts_html}
- </div>
-
- <!-- Footer -->
- <div style="text-align: center; padding: 24px 0; border-top: 1px solid #e5e7eb;
- font-size: 12px; color: #9ca3af;">
- <p style="margin: 0;">
- Sent by ServerKit at {timestamp}
- </p>
- <p style="margin: 8px 0 0 0;">
- <a href="#" style="color: #6366f1; text-decoration: none;">Manage notification settings</a>
- </p>
- </div>
- </body>
- </html>
- """
- return template
-
- @classmethod
- def _get_plain_text_template(cls, alerts: List[Dict]) -> str:
- """Generate plain text email for alerts."""
- hostname = cls.get_hostname()
- timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
-
- lines = [
- "ServerKit Alert",
- "=" * 40,
- f"{len(alerts)} alert(s) triggered on {hostname}",
- ""
- ]
-
- for alert in alerts:
- severity = alert.get('severity', 'info').upper()
- alert_type = alert.get('type', 'Alert').upper()
- lines.append(f"[{severity}] {alert_type}")
- lines.append(alert.get('message', 'No message'))
- if 'value' in alert:
- lines.append(f" Current: {alert['value']}")
- if 'threshold' in alert:
- lines.append(f" Threshold: {alert['threshold']}")
- lines.append("")
-
- lines.append("-" * 40)
- lines.append(f"Sent by ServerKit at {timestamp}")
-
- return "\n".join(lines)
-
@classmethod
def send_email(cls, alerts: List[Dict], config: Dict = None) -> Dict:
"""
@@ -554,12 +442,17 @@ class NotificationService:
msg['From'] = f"{config.get('from_name', 'ServerKit')} <{config['from_email']}>"
msg['To'] = ', '.join(config['to_emails'])
- # Add plain text and HTML versions
- plain_text = cls._get_plain_text_template(alerts)
- html_content = cls._get_email_template(alerts)
-
- msg.attach(MIMEText(plain_text, 'plain'))
- msg.attach(MIMEText(html_content, 'html'))
+ # Render via the Notification Bus template system (Jinja2),
+ # so monitoring emails share the branded, dark-mode-aware layout.
+ from app.notifications import rendering
+ overall_severity = priority.lower()
+ rendered = rendering.render_email(
+ 'monitoring_alert', subject, severity=overall_severity,
+ data={'alerts': alerts, 'hostname': cls.get_hostname()},
+ hostname=cls.get_hostname(),
+ )
+ msg.attach(MIMEText(rendered['text'], 'plain', 'utf-8'))
+ msg.attach(MIMEText(rendered['html'], 'html', 'utf-8'))
# Send email
smtp_port = config.get('smtp_port', 587)
@@ -649,33 +542,21 @@ class NotificationService:
# ==========================================
@classmethod
def send_all(cls, alerts: List[Dict]) -> Dict:
+ """Send alerts to all configured system channels.
+
+ Now a thin, NON-BLOCKING shim over the Notification Bus: instead of
+ opening SMTP/HTTP connections synchronously on the caller's thread (with
+ no retry and no record), it records a Notification and enqueues a
+ per-channel delivery on the queue bus, which the NotificationConsumer
+ delivers with retry/backoff and logs in the delivery log. The system
+ channels and recipients are unchanged. Callers keep the same
+ {'success': bool, ...} contract.
"""
- Send alerts to all configured notification channels.
-
- Returns results for each channel.
- """
- config = cls.get_config()
- results = {}
-
- if config.get('discord', {}).get('enabled'):
- results['discord'] = cls.send_discord(alerts, config['discord'])
-
- if config.get('slack', {}).get('enabled'):
- results['slack'] = cls.send_slack(alerts, config['slack'])
-
- if config.get('telegram', {}).get('enabled'):
- results['telegram'] = cls.send_telegram(alerts, config['telegram'])
-
- if config.get('email', {}).get('enabled'):
- results['email'] = cls.send_email(alerts, config['email'])
-
- if config.get('generic_webhook', {}).get('enabled'):
- results['generic_webhook'] = cls.send_generic_webhook(alerts, config['generic_webhook'])
-
- return {
- 'success': all(r.get('success', False) for r in results.values()) if results else True,
- 'results': results
- }
+ try:
+ from app.notifications.service import NotificationBusService
+ return NotificationBusService.broadcast_system(alerts)
+ except Exception as e:
+ return {'success': False, 'error': str(e), 'results': {}}
# ==========================================
# TEST NOTIFICATIONS
diff --git a/backend/app/sockets.py b/backend/app/sockets.py
index ed75940f..d26bb4ce 100644
--- a/backend/app/sockets.py
+++ b/backend/app/sockets.py
@@ -105,6 +105,10 @@ def handle_connect(auth):
with _connected_clients_lock:
connected_clients[request.sid] = {'user_id': user.id, 'role': user.role}
+ # Join a per-user room so the Notification Bus can push in-app notifications
+ # to every tab/device this user has open.
+ join_room(f'user_{user.id}')
+
emit('connected', {'status': 'connected'})
diff --git a/backend/migrations/versions/023_notification_bus.py b/backend/migrations/versions/023_notification_bus.py
new file mode 100644
index 00000000..d9ebbb07
--- /dev/null
+++ b/backend/migrations/versions/023_notification_bus.py
@@ -0,0 +1,80 @@
+"""Notification Bus foundation.
+
+Adds:
+- notifications
+- notification_deliveries
+
+Idempotent: MigrationService runs db.create_all() on boot before Alembic,
+so guard on the live schema.
+
+Revision ID: 023_notification_bus
+Revises: 022_queue_bus
+Create Date: 2026-06-21
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '023_notification_bus'
+down_revision = '022_queue_bus'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ if 'notifications' not in tables:
+ op.create_table(
+ 'notifications',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('event_key', sa.String(120), nullable=False),
+ sa.Column('category', sa.String(40), nullable=True, server_default='system'),
+ sa.Column('severity', sa.String(20), nullable=True, server_default='info'),
+ sa.Column('title', sa.String(255), nullable=False),
+ sa.Column('body', sa.Text, nullable=True),
+ sa.Column('data_json', sa.Text, nullable=True),
+ sa.Column('audience', sa.String(255), nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ )
+ op.create_index('ix_notifications_event_key', 'notifications', ['event_key'])
+ op.create_index('ix_notifications_category', 'notifications', ['category'])
+ op.create_index('ix_notifications_severity', 'notifications', ['severity'])
+ op.create_index('ix_notifications_created_at', 'notifications', ['created_at'])
+
+ if 'notification_deliveries' not in tables:
+ op.create_table(
+ 'notification_deliveries',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('notification_id', sa.Integer, nullable=False),
+ sa.Column('recipient_user_id', sa.Integer, nullable=True),
+ sa.Column('channel', sa.String(40), nullable=False),
+ sa.Column('target', sa.String(512), nullable=True),
+ sa.Column('status', sa.String(20), nullable=True, server_default='pending'),
+ sa.Column('attempts', sa.Integer, nullable=True, server_default='0'),
+ sa.Column('error', sa.Text, nullable=True),
+ sa.Column('provider_message_id', sa.String(255), nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.Column('sent_at', sa.DateTime, nullable=True),
+ sa.Column('read_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['notification_id'], ['notifications.id']),
+ sa.ForeignKeyConstraint(['recipient_user_id'], ['users.id']),
+ )
+ op.create_index('ix_notification_deliveries_notification_id', 'notification_deliveries', ['notification_id'])
+ op.create_index('ix_notification_deliveries_recipient_user_id', 'notification_deliveries', ['recipient_user_id'])
+ op.create_index('ix_notification_deliveries_channel', 'notification_deliveries', ['channel'])
+ op.create_index('ix_notification_deliveries_status', 'notification_deliveries', ['status'])
+ op.create_index('ix_notification_deliveries_created_at', 'notification_deliveries', ['created_at'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ for table in ('notification_deliveries', 'notifications'):
+ if table in tables:
+ op.drop_table(table)
diff --git a/backend/migrations/versions/024_email_providers.py b/backend/migrations/versions/024_email_providers.py
new file mode 100644
index 00000000..3a239c2d
--- /dev/null
+++ b/backend/migrations/versions/024_email_providers.py
@@ -0,0 +1,55 @@
+"""Email provider connections (Notification Bus transports).
+
+Adds:
+- email_provider_connections
+
+Idempotent: MigrationService runs db.create_all() on boot before Alembic,
+so guard on the live schema.
+
+Revision ID: 024_email_providers
+Revises: 023_notification_bus
+Create Date: 2026-06-21
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '024_email_providers'
+down_revision = '023_notification_bus'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ if 'email_provider_connections' not in tables:
+ op.create_table(
+ 'email_provider_connections',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('provider', sa.String(40), nullable=False),
+ sa.Column('name', sa.String(120), nullable=False),
+ sa.Column('credentials_json', sa.Text, nullable=True),
+ sa.Column('from_address', sa.String(255), nullable=True),
+ sa.Column('from_name', sa.String(120), nullable=True),
+ sa.Column('is_default', sa.Boolean, nullable=True, server_default=sa.false()),
+ sa.Column('is_active', sa.Boolean, nullable=True, server_default=sa.true()),
+ sa.Column('created_by', sa.Integer, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.Column('updated_at', sa.DateTime, nullable=True),
+ sa.Column('last_tested_at', sa.DateTime, nullable=True),
+ sa.Column('last_test_ok', sa.Boolean, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['created_by'], ['users.id']),
+ )
+ op.create_index('ix_email_provider_connections_is_default',
+ 'email_provider_connections', ['is_default'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+ if 'email_provider_connections' in tables:
+ op.drop_table('email_provider_connections')
diff --git a/backend/tests/test_notification_bus.py b/backend/tests/test_notification_bus.py
new file mode 100644
index 00000000..6d8917a8
--- /dev/null
+++ b/backend/tests/test_notification_bus.py
@@ -0,0 +1,422 @@
+"""Tests for the Notification Bus (queue-backed, multi-channel).
+
+Proves the end-to-end spine: notify.send() records the event, plans per-recipient
+deliveries honoring preferences, enqueues them, and the consumer renders + marks
+them — plus the preference/quiet-hours/severity gating.
+"""
+from datetime import datetime, timedelta
+
+import pytest
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import User
+from app.models.notification_preferences import NotificationPreferences
+from app.notifications.channels import get_adapter, register_adapter
+from app.notifications.channels.base import ChannelAdapter, DeliveryResult
+from app.notifications.consumer import process_message
+from app.notifications.models import Notification, NotificationDelivery
+from app.notifications.service import GROUP_SLUG, QUEUE_SLUG, NotificationBusService
+from app.queue_bus.service import QueueBusService
+
+
[email protected](autouse=True)
+def reset_broker(app):
+ QueueBusService.reset_broker()
+
+
+class _CaptureEmail(ChannelAdapter):
+ """Stand-in email adapter: renders the real template (proving rendering
+ integrates) and records the result instead of opening SMTP."""
+
+ key = 'email'
+
+ def __init__(self):
+ self.sent = []
+
+ def deliver(self, delivery, notification):
+ from app.notifications import catalog, rendering
+ meta = catalog.resolve(
+ notification.event_key, notification.get_data(),
+ severity=notification.severity, title=notification.title,
+ )
+ rendered = rendering.render_email(
+ meta['template'], notification.title,
+ severity=notification.severity, data=notification.get_data(),
+ )
+ self.sent.append({
+ 'to': delivery.target,
+ 'subject': rendered['subject'],
+ 'html': rendered['html'],
+ 'text': rendered['text'],
+ })
+ return DeliveryResult.sent('captured-msg-id')
+
+
+def captured_email():
+ original = get_adapter('email')
+ cap = _CaptureEmail()
+ register_adapter(cap)
+ yield cap
+ register_adapter(original) # restore real adapter for other tests
+
+
+def _make_user(username='alice', email='[email protected]', role='developer'):
+ user = User(
+ email=email, username=username,
+ password_hash=generate_password_hash('x'),
+ role=role, is_active=True,
+ )
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _prefs(user, **fields):
+ prefs = NotificationPreferences.get_or_create(user.id)
+ for key, value in fields.items():
+ if key == 'channels':
+ prefs.set_channels(value)
+ elif key == 'severities':
+ prefs.set_severities(value)
+ elif key == 'categories':
+ prefs.set_categories(value)
+ else:
+ setattr(prefs, key, value)
+ db.session.commit()
+ return prefs
+
+
+def _drain():
+ msgs = QueueBusService.receive(GROUP_SLUG, QUEUE_SLUG, visibility_timeout_ms=60000, max_messages=100)
+ for message in msgs:
+ process_message(message)
+ return len(msgs)
+
+
+class TestSendAndDeliver:
+ def test_send_creates_notification_and_deliveries(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['critical', 'warning', 'success'])
+
+ result = NotificationBusService.send(
+ 'backup.completed', to=user,
+ data={'app': 'blog', 'size': '2.3 GB', 'duration': '41s'},
+ )
+
+ notif = Notification.query.get(result['notification_id'])
+ assert notif is not None
+ assert notif.event_key == 'backup.completed'
+ assert notif.severity == 'success'
+ assert notif.category == 'backups'
+ assert notif.title == 'Backup completed: blog'
+
+ deliveries = NotificationDelivery.query.filter_by(notification_id=notif.id).all()
+ channels = {d.channel for d in deliveries}
+ assert channels == {'inapp', 'email'}
+
+ def test_inapp_is_sent_immediately_email_is_queued(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['success'])
+
+ NotificationBusService.send('backup.completed', to=user, data={'app': 'blog'})
+
+ inapp = NotificationDelivery.query.filter_by(channel='inapp').one()
+ email = NotificationDelivery.query.filter_by(channel='email').one()
+ assert inapp.status == 'sent' and inapp.sent_at is not None
+ assert email.status == 'pending' # waits for the consumer
+
+ def test_consumer_delivers_and_renders_email(self, app, captured_email):
+ user = _make_user(email='[email protected]')
+ _prefs(user, channels=['email'], severities=['critical'])
+
+ NotificationBusService.send(
+ 'security.alert', to=user,
+ data={'message': '5 failed admin logins', 'alert_type': 'auth_failure',
+ 'source_ip': '203.0.113.7', 'identity': 'admin'},
+ )
+ drained = _drain()
+
+ assert drained == 1 # only the email was queued (inapp is instant)
+ assert len(captured_email.sent) == 1
+ sent = captured_email.sent[0]
+ assert sent['to'] == '[email protected]'
+ assert sent['subject'] == 'Security alert: auth_failure'
+ assert '203.0.113.7' in sent['html'] # rendered the fact
+ assert '<!DOCTYPE html>' in sent['html'] # full branded layout
+ assert '5 failed admin logins' in sent['text']
+
+ email = NotificationDelivery.query.filter_by(channel='email').one()
+ assert email.status == 'sent'
+ assert email.provider_message_id == 'captured-msg-id'
+ assert email.attempts == 1
+
+
+class TestGating:
+ def test_severity_below_preference_is_dropped(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['critical', 'warning'])
+
+ # 'info' is not in the user's severities -> nothing planned.
+ result = NotificationBusService.send('app.deployed', to=user, severity='info',
+ data={'app': 'blog'})
+ assert result['deliveries'] == 0
+ assert NotificationDelivery.query.count() == 0
+
+ def test_category_opt_out_is_respected(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['critical'],
+ categories={'system': True, 'security': False, 'backups': True, 'apps': True})
+
+ # critical bypasses severity gating, but the category opt-out still holds.
+ result = NotificationBusService.send('security.alert', to=user,
+ data={'message': 'x'})
+ assert result['deliveries'] == 0
+
+ def test_quiet_hours_suppress_non_critical_but_not_critical(self, app):
+ user = _make_user()
+ now = datetime.now()
+ start = (now - timedelta(minutes=3)).strftime('%H:%M')
+ end = (now + timedelta(minutes=3)).strftime('%H:%M')
+ _prefs(user, channels=['email'], severities=['critical', 'warning'],
+ quiet_hours_enabled=True, quiet_hours_start=start, quiet_hours_end=end)
+
+ quiet = NotificationBusService.send('system.alert', to=user, severity='warning',
+ data={'message': 'cpu high'})
+ assert quiet['deliveries'] == 0 # suppressed during quiet hours
+
+ loud = NotificationBusService.send('security.alert', to=user, severity='critical',
+ data={'message': 'breach'})
+ assert loud['deliveries'] >= 1 # critical pierces quiet hours
+
+ def test_disabled_user_gets_nothing_unless_directed(self, app):
+ user = _make_user()
+ _prefs(user, enabled=False, channels=['email'])
+
+ off = NotificationBusService.send('app.deployed', to=user, data={'app': 'blog'})
+ assert off['deliveries'] == 0
+
+ # A directed transactional send bypasses preference gating entirely.
+ directed = NotificationBusService.send('user.welcome', to=user,
+ channels=['email'], data={})
+ assert directed['deliveries'] == 1
+
+
+class TestRecipients:
+ def test_bare_email_recipient(self, app, captured_email):
+ NotificationBusService.send('user.invitation', to='[email protected]',
+ channels=['email'],
+ data={'summary': 'Join the team', 'action_url': 'https://x/y'})
+ _drain()
+ assert len(captured_email.sent) == 1
+ assert captured_email.sent[0]['to'] == '[email protected]'
+
+ delivery = NotificationDelivery.query.filter_by(channel='email').one()
+ assert delivery.recipient_user_id is None
+ assert delivery.status == 'sent'
+
+ def test_admins_audience_resolves_admin_users(self, app):
+ _make_user('admin1', '[email protected]', role=User.ROLE_ADMIN)
+ _make_user('admin2', '[email protected]', role=User.ROLE_ADMIN)
+ _make_user('dev', '[email protected]', role='developer')
+ for u in User.query.all():
+ _prefs(u, channels=['email'], severities=['critical'])
+
+ result = NotificationBusService.send('security.alert', to='admins',
+ data={'message': 'x'})
+ # 2 admins x (inapp + email) = 4 deliveries; the developer is excluded.
+ recipients = {d.recipient_user_id for d in NotificationDelivery.query.all()}
+ assert len(recipients) == 2
+ assert result['deliveries'] == 4
+
+ def test_sdk_facade_sends(self, app):
+ from app.plugins_sdk import notify
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['success'])
+ result = notify.send('backup.completed', to=user, data={'app': 'blog'})
+ assert result['notification_id'] is not None
+ assert result['deliveries'] == 2 # inapp + email
+
+
+class TestInbox:
+ def test_inbox_lists_inapp_and_unread_count(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['success'])
+ NotificationBusService.send('backup.completed', to=user, data={'app': 'blog'})
+
+ items = NotificationBusService.inbox(user.id)
+ assert len(items) == 1
+ assert items[0]['event_key'] == 'backup.completed'
+ assert items[0]['read'] is False
+ assert 'delivery_id' in items[0]
+ assert NotificationBusService.unread_count(user.id) == 1
+
+ def test_mark_read_and_mark_all(self, app):
+ user = _make_user()
+ _prefs(user, channels=[], severities=['critical']) # inapp only
+ NotificationBusService.send('security.alert', to=user, data={'message': 'x'})
+ NotificationBusService.send('security.alert', to=user, data={'message': 'y'})
+ assert NotificationBusService.unread_count(user.id) == 2
+
+ items = NotificationBusService.inbox(user.id)
+ assert NotificationBusService.mark_read(user.id, items[0]['delivery_id']) is True
+ assert NotificationBusService.unread_count(user.id) == 1
+ assert NotificationBusService.mark_all_read(user.id) == 1
+ assert NotificationBusService.unread_count(user.id) == 0
+
+ def test_inbox_api_roundtrip(self, app, client, auth_headers):
+ admin = User.query.filter_by(username='testadmin').first()
+ _prefs(admin, channels=[], severities=['critical'])
+ NotificationBusService.send('security.alert', to=admin, data={'message': 'x'})
+
+ resp = client.get('/api/v1/notifications/inbox', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['unread_count'] == 1
+ assert len(body['items']) == 1
+
+ delivery_id = body['items'][0]['delivery_id']
+ resp2 = client.post(f'/api/v1/notifications/inbox/{delivery_id}/read', headers=auth_headers)
+ assert resp2.status_code == 200
+ assert resp2.get_json()['unread_count'] == 0
+
+ resp3 = client.get('/api/v1/notifications/inbox/unread-count', headers=auth_headers)
+ assert resp3.get_json()['count'] == 0
+
+
+class TestDeliveryLog:
+ def test_delivery_log_and_stats(self, app, captured_email):
+ user = _make_user(email='[email protected]')
+ _prefs(user, channels=['email'], severities=['critical'])
+ NotificationBusService.send('security.alert', to=user, data={'message': 'x'})
+ _drain()
+
+ log = NotificationBusService.delivery_log()
+ assert len(log) == 2 # inapp + email
+ assert all('event_key' in d for d in log)
+
+ stats = NotificationBusService.delivery_stats()
+ assert stats['total'] == 2
+ assert stats['by_status'].get('sent') == 2
+ assert set(stats['by_channel'].keys()) == {'inapp', 'email'}
+
+ def test_retry_requeues_failed(self, app):
+ user = _make_user()
+ _prefs(user, channels=['email'], severities=['critical'])
+ NotificationBusService.send('security.alert', to=user, data={'message': 'x'})
+
+ email = NotificationDelivery.query.filter_by(channel='email').one()
+ email.status = 'failed'
+ email.error = 'boom'
+ db.session.commit()
+
+ result = NotificationBusService.retry_delivery(email.id)
+ assert result['status'] == 'pending'
+ db.session.refresh(email)
+ assert email.status == 'pending'
+ assert email.error is None
+
+ def test_admin_delivery_log_api(self, app, client, auth_headers):
+ admin = User.query.filter_by(username='testadmin').first()
+ _prefs(admin, channels=[], severities=['critical'])
+ NotificationBusService.send('security.alert', to=admin, data={'message': 'x'})
+
+ resp = client.get('/api/v1/notifications/admin/deliveries', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['stats']['total'] >= 1
+ assert any(d['channel'] == 'inapp' for d in body['deliveries'])
+
+
+class TestEmailProviders:
+ def test_add_encrypts_and_sets_default(self, app):
+ import json as _json
+ from app.notifications.providers import EmailProviderService
+
+ provider = EmailProviderService.add_provider({
+ 'provider': 'sendgrid', 'name': 'SG',
+ 'api_key': 'SG.supersecret', 'from_address': '[email protected]',
+ })
+ assert provider.is_default is True
+ # Encrypted at rest, but decrypts back, and never serialized.
+ assert provider.raw_credentials()['api_key'] != 'SG.supersecret'
+ assert provider.credentials()['api_key'] == 'SG.supersecret'
+ assert 'SG.supersecret' not in _json.dumps(provider.to_dict())
+ assert EmailProviderService.default_provider().id == provider.id
+
+ def test_adapter_prefers_provider(self, app, monkeypatch):
+ from app.notifications.providers import EmailProviderService
+
+ EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'S', 'host': 'localhost', 'port': '25',
+ 'username': 'u', 'password': 'p', 'from_address': '[email protected]',
+ })
+ captured = {}
+
+ def fake_send(provider, to_addr, subject, html, text):
+ captured.update({'to': to_addr, 'subject': subject})
+ return {'success': True, 'message_id': 'mid-123', 'error': None}
+ monkeypatch.setattr(EmailProviderService, 'send', staticmethod(fake_send))
+
+ user = _make_user(email='[email protected]')
+ _prefs(user, channels=['email'], severities=['critical'])
+ NotificationBusService.send('security.alert', to=user, data={'message': 'x'})
+ _drain()
+
+ email = NotificationDelivery.query.filter_by(channel='email').one()
+ assert email.status == 'sent'
+ assert email.provider_message_id == 'mid-123'
+ assert captured['to'] == '[email protected]'
+
+ def test_set_default_and_delete_promotes(self, app):
+ from app.notifications.providers import EmailProviderService
+
+ a = EmailProviderService.add_provider({'provider': 'sendgrid', 'name': 'A', 'api_key': 'k1'})
+ b = EmailProviderService.add_provider({'provider': 'postmark', 'name': 'B', 'server_token': 't1'})
+ assert a.is_default is True and b.is_default is False
+
+ EmailProviderService.set_default(b.id)
+ assert EmailProviderService.default_provider().id == b.id
+
+ EmailProviderService.delete_provider(b.id)
+ assert EmailProviderService.default_provider().id == a.id
+
+
+class TestSystemBroadcast:
+ def test_send_all_routes_through_bus(self, app, monkeypatch, captured_email):
+ from app.services.notification_service import NotificationService
+
+ cfg = {
+ 'email': {'enabled': True, 'smtp_host': 'smtp.x', 'from_email': 'a@x',
+ 'to_emails': ['[email protected]'], 'notify_on': ['critical', 'warning']},
+ 'discord': {'enabled': True, 'webhook_url': 'https://discord/hook',
+ 'notify_on': ['critical', 'warning']},
+ 'slack': {'enabled': False}, 'telegram': {'enabled': False},
+ 'generic_webhook': {'enabled': False},
+ }
+ monkeypatch.setattr(NotificationService, 'get_config', classmethod(lambda cls: cfg))
+ discord_seen = {}
+ monkeypatch.setattr(NotificationService, 'send_discord',
+ classmethod(lambda cls, alerts, c: discord_seen.update({'alerts': alerts}) or {'success': True}))
+
+ result = NotificationService.send_all([
+ {'severity': 'critical', 'type': 'disk', 'message': 'Disk full', 'value': '95%', 'threshold': '90%'},
+ ])
+ assert result['success'] is True
+
+ notif = Notification.query.filter_by(event_key='monitoring.alert').one()
+ deliveries = NotificationDelivery.query.filter_by(notification_id=notif.id).all()
+ assert {d.channel for d in deliveries} == {'email', 'discord'}
+ assert all(d.recipient_user_id is None for d in deliveries) # system, not per-user
+
+ _drain()
+ # Email rendered through the new monitoring template.
+ assert len(captured_email.sent) == 1
+ assert captured_email.sent[0]['to'] == '[email protected]'
+ assert 'Disk full' in captured_email.sent[0]['html']
+ # Chat kept the original per-alert list.
+ assert discord_seen['alerts'][0]['type'] == 'disk'
+ for d in deliveries:
+ db.session.refresh(d)
+ assert d.status == 'sent'