[feat] Add unsubscribe link to email notifications

.github/workflows/build.yml

@@ -5,10 +5,13 @@ on:
     branches:
       - master
       - dev
+      - gsoc24-rebased
   pull_request:
     branches:
       - master
       - dev
+      - gsoc24-rebased
+      - notification-preferences
 
 jobs:
 

docs/user/intro.rst

@@ -7,7 +7,8 @@ include:
 
 - :doc:`sending-notifications`
 - :ref:`notifications_web_notifications`
-- :ref:`notifications_email_notifications`
+- :ref:`notifications_email_notifications` and
+  :ref:`notifications_batches`
 - :doc:`notification-types`
 - :doc:`User notification preferences <notification-preferences>`
 - :ref:`Silencing notifications for specific objects temporarily or

docs/user/notification-preferences.rst

@@ -1,8 +1,8 @@
 Notification Preferences
 ========================
 
-.. image:: https://raw.githubusercontent.com/openwisp/openwisp-notifications/docs/docs/images/notification-settings.png
-    :target: https://raw.githubusercontent.com/openwisp/openwisp-notifications/docs/docs/images/notification-settings.png
+.. image:: https://i.imgur.com/lIGqry5.png
+    :target: https://i.imgur.com/lIGqry5.png
     :align: center
 
 OpenWISP Notifications enables users to customize their notification
@@ -12,6 +12,10 @@ organized by notification type and organization, allowing users to tailor
 their notification experience by opting to receive updates only from
 specific organizations or notification types.
 
+Users can access and manage their notification preferences by visiting the
+``/notification/preferences/``. Alternatively, this page can also be
+accessed directly from the notification widget.
+
 Notification settings are automatically generated for all notification
 types and organizations for every user. Superusers have the ability to
 manage notification settings for all users, including adding or deleting

docs/user/settings.rst

@@ -156,3 +156,34 @@ The default configuration is as follows:
         # Maximum interval after which the notification widget should get updated (in seconds)
         "max_allowed_backoff": 15,
     }
+
+.. _openwisp_notifications_email_batch_interval:
+
+``OPENWISP_NOTIFICATIONS_EMAIL_BATCH_INTERVAL``
+-----------------------------------------------
+
+======= =================================
+Type    ``int``
+Default ``1800`` (30 minutes, in seconds)
+======= =================================
+
+This setting determines the :ref:`interval of the email batching feature
+<notifications_batches>`.
+
+The interval is specified in seconds.
+
+To send email notifications immediately without batching, set this value
+to ``0``.
+
+.. _openwisp_notifications_email_batch_display_limit:
+
+``OPENWISP_NOTIFICATIONS_EMAIL_BATCH_DISPLAY_LIMIT``
+----------------------------------------------------
+
+======= =======
+Type    ``int``
+Default ``15``
+======= =======
+
+This setting specifies the maximum number of email notifications that can
+be included in a single :ref:`email batch <notifications_batches>`.

docs/user/web-email-notifications.rst

@@ -54,3 +54,38 @@ Email Notifications
 Along with web notifications OpenWISP Notifications also sends email
 notifications leveraging the :ref:`send_email feature of OpenWISP Utils
 <utils_send_email>`.
+
+.. _notifications_batches:
+
+Email Batches
+~~~~~~~~~~~~~
+
+.. figure:: https://i.imgur.com/W5P009W.png
+    :target: https://i.imgur.com/W5P009W.png
+    :align: center
+
+Batching email notifications helps manage the flow of emails sent to
+users, especially during periods of increased alert activity. By grouping
+emails into batches, the system minimizes the risk of emails being marked
+as spam and prevents inboxes from rejecting alerts due to high volumes.
+
+Key aspects of the batch email notification feature include:
+
+- When multiple emails are triggered for the same user within a short time
+  frame, subsequent emails are grouped into a summary.
+- The sending of individual emails is paused for a specified batch
+  interval when batching is enabled.
+
+.. note::
+
+    If new alerts are received while a batch is pending, they will be
+    added to the current summary without resetting the timer. The batched
+    email will be sent when the initial batch interval expires.
+
+You can customize the behavior of batch email notifications using the
+following settings:
+
+- :ref:`OPENWISP_NOTIFICATIONS_EMAIL_BATCH_INTERVAL
+  <openwisp_notifications_email_batch_interval>`.
+- :ref:`OPENWISP_NOTIFICATIONS_EMAIL_BATCH_DISPLAY_LIMIT
+  <openwisp_notifications_email_batch_display_limit>`.

openwisp_notifications/admin.py

@@ -1,25 +1,3 @@
-from django.contrib import admin
-
-from openwisp_notifications.base.admin import NotificationSettingAdminMixin
-from openwisp_notifications.swapper import load_model
 from openwisp_notifications.widgets import _add_object_notification_widget
-from openwisp_users.admin import UserAdmin
-from openwisp_utils.admin import AlwaysHasChangedMixin
-
-Notification = load_model('Notification')
-NotificationSetting = load_model('NotificationSetting')
-
-
-class NotificationSettingInline(
-    NotificationSettingAdminMixin, AlwaysHasChangedMixin, admin.TabularInline
-):
-    model = NotificationSetting
-    extra = 0
-
-    def has_change_permission(self, request, obj=None):
-        return request.user.is_superuser or request.user == obj
-
-
-UserAdmin.inlines = [NotificationSettingInline] + UserAdmin.inlines
 
 _add_object_notification_widget()

openwisp_notifications/api/filters.py

@@ -8,3 +8,8 @@ class NotificationSettingFilter(OrganizationMembershipFilter):
     class Meta(OrganizationMembershipFilter.Meta):
         model = NotificationSetting
         fields = OrganizationMembershipFilter.Meta.fields + ['type']
+
+    @property
+    def qs(self):
+        parent_qs = super().qs
+        return parent_qs.exclude(organization__isnull=True, type__isnull=True)

openwisp_notifications/api/permissions.py

@@ -0,0 +1,16 @@
+from rest_framework.permissions import BasePermission
+
+
+class PreferencesPermission(BasePermission):
+    """
+    Permission class for the notification preferences.
+
+    Permission is granted only in these two cases:
+    1. Superusers can change the notification preferences of any user.
+    2. Regular users can only change their own preferences.
+    """
+
+    def has_permission(self, request, view):
+        return request.user.is_superuser or request.user.id == view.kwargs.get(
+            'user_id'
+        )

openwisp_notifications/api/serializers.py

@@ -73,6 +73,11 @@ class Meta(NotificationSerializer.Meta):
 
 
 class NotificationSettingSerializer(serializers.ModelSerializer):
+    organization_name = serializers.CharField(
+        source='organization.name', read_only=True
+    )
+    type_label = serializers.CharField(source='get_type_display', read_only=True)
+
     class Meta:
         model = NotificationSetting
         exclude = ['user']
@@ -87,3 +92,14 @@ class Meta:
             'object_content_type',
             'object_id',
         ]
+
+
+class NotificationSettingUpdateSerializer(serializers.Serializer):
+    email = serializers.BooleanField()
+    web = serializers.BooleanField()
+
+    def update(self, instance, validated_data):
+        instance.email = validated_data.get('email', instance.email)
+        instance.web = validated_data.get('web', instance.web)
+        instance.save()
+        return instance

openwisp_notifications/api/urls.py

@@ -9,32 +9,61 @@ def get_api_urls(api_views=None):
     if not api_views:
         api_views = views
     return [
-        path('', views.notifications_list, name='notifications_list'),
-        path('read/', views.notifications_read_all, name='notifications_read_all'),
-        path('<uuid:pk>/', views.notification_detail, name='notification_detail'),
+        path('notification/', views.notifications_list, name='notifications_list'),
         path(
-            '<uuid:pk>/redirect/',
+            'notification/read/',
+            views.notifications_read_all,
+            name='notifications_read_all',
+        ),
+        path(
+            'notification/<uuid:pk>/',
+            views.notification_detail,
+            name='notification_detail',
+        ),
+        path(
+            'notification/<uuid:pk>/redirect/',
             views.notification_read_redirect,
             name='notification_read_redirect',
         ),
         path(
-            'user-setting/',
+            'user/<uuid:user_id>/user-setting/',
             views.notification_setting_list,
-            name='notification_setting_list',
+            name='user_notification_setting_list',
         ),
         path(
-            'user-setting/<uuid:pk>/',
+            'user/<uuid:user_id>/user-setting/<uuid:pk>/',
             views.notification_setting,
-            name='notification_setting',
+            name='user_notification_setting',
         ),
         path(
-            'ignore/',
+            'notification/ignore/',
             views.ignore_object_notification_list,
             name='ignore_object_notification_list',
         ),
         path(
-            'ignore/<str:app_label>/<str:model_name>/<uuid:object_id>/',
+            'notification/ignore/<str:app_label>/<str:model_name>/<uuid:object_id>/',
             views.ignore_object_notification,
             name='ignore_object_notification',
         ),
+        path(
+            'user/<uuid:user_id>/organization/<uuid:organization_id>/setting/',
+            views.organization_notification_setting,
+            name='organization_notification_setting',
+        ),
+        path(
+            'user/<uuid:user_id>/preference/',
+            views.notification_preference,
+            name='notification_preference',
+        ),
+        # DEPRECATED
+        path(
+            'user/user-setting/',
+            views.notification_setting_list,
+            name='notification_setting_list',
+        ),
+        path(
+            'user/user-setting/<uuid:pk>/',
+            views.notification_setting,
+            name='notification_setting',
+        ),
     ]

openwisp_notifications/api/views.py

@@ -15,11 +15,13 @@
 from rest_framework.permissions import IsAuthenticated
 from rest_framework.response import Response
 
+from openwisp_notifications.api.permissions import PreferencesPermission
 from openwisp_notifications.api.serializers import (
     IgnoreObjectNotificationSerializer,
     NotificationListSerializer,
     NotificationSerializer,
     NotificationSettingSerializer,
+    NotificationSettingUpdateSerializer,
 )
 from openwisp_notifications.swapper import load_model
 from openwisp_users.api.authentication import BearerAuthentication
@@ -114,11 +116,17 @@ class BaseNotificationSettingView(GenericAPIView):
     model = NotificationSetting
     serializer_class = NotificationSettingSerializer
     authentication_classes = [BearerAuthentication, SessionAuthentication]
-    permission_classes = [IsAuthenticated]
+    permission_classes = [PreferencesPermission]
 
     def get_queryset(self):
         if getattr(self, 'swagger_fake_view', False):
             return NotificationSetting.objects.none()  # pragma: no cover
+
+        user_id = self.kwargs.get('user_id')
+
+        if user_id:
+            return NotificationSetting.objects.filter(user_id=user_id)
+
         return NotificationSetting.objects.filter(user=self.request.user)
 
 
@@ -198,11 +206,64 @@ def perform_create(self, serializer):
         )
 
 
+class OrganizationNotificationSettingView(GenericAPIView):
+    permission_classes = [IsAuthenticated, PreferencesPermission]
+    serializer_class = NotificationSettingUpdateSerializer
+
+    def post(self, request, user_id, organization_id):
+        notification_settings = NotificationSetting.objects.filter(
+            organization_id=organization_id, user_id=user_id
+        )
+        serializer = self.get_serializer(data=request.data)
+        if serializer.is_valid():
+            for notification_setting in notification_settings:
+                serializer.update(notification_setting, serializer.validated_data)
+            return Response(status=status.HTTP_200_OK)
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
+class NotificationPreferenceView(GenericAPIView):
+    permission_classes = [IsAuthenticated, PreferencesPermission]
+    serializer_class = NotificationSettingUpdateSerializer
+
+    def get(self, request, user_id):
+        notification_settings, created = NotificationSetting.objects.get_or_create(
+            user_id=user_id,
+            organization=None,
+            type=None,
+            defaults={'email': True, 'web': True},
+        )
+        serializer = self.get_serializer(notification_settings)
+        return Response(serializer.data, status=status.HTTP_200_OK)
+
+    def post(self, request, user_id):
+        serializer = self.get_serializer(data=request.data)
+        if serializer.is_valid():
+            email = serializer.validated_data.get('email')
+            web = serializer.validated_data.get('web')
+            (
+                notification_settings,
+                created,
+            ) = NotificationSetting.objects.update_or_create(
+                user_id=user_id,
+                organization=None,
+                type=None,
+                defaults={'email': email, 'web': web},
+            )
+            NotificationSetting.objects.filter(user_id=user_id).update(
+                email=email, web=web
+            )
+            return Response(status=status.HTTP_200_OK)
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
 notifications_list = NotificationListView.as_view()
 notification_detail = NotificationDetailView.as_view()
 notifications_read_all = NotificationReadAllView.as_view()
 notification_read_redirect = NotificationReadRedirect.as_view()
 notification_setting_list = NotificationSettingListView.as_view()
 notification_setting = NotificationSettingView.as_view()
+organization_notification_setting = OrganizationNotificationSettingView.as_view()
 ignore_object_notification_list = IgnoreObjectNotificationListView.as_view()
 ignore_object_notification = IgnoreObjectNotificationView.as_view()
+notification_preference = NotificationPreferenceView.as_view()

openwisp_notifications/base/admin.py

@@ -26,12 +26,12 @@ def get_queryset(self, request):
             super()
             .get_queryset(request)
             .filter(deleted=False)
+            .exclude(organization=None)
             .prefetch_related('organization')
         )
 
     class Media:
         extends = True
         js = [
             'admin/js/jquery.init.js',
-            'openwisp-notifications/js/notification-settings.js',
         ]