Merge pull request #520 from sjefferson99/514-add-notification-about-availabliity-of-installable-app

feat(notifications): add mobile app install notification for new users

Author: sjefferson99

server/alembic/versions/034_add_mobile_app_notification.py

@@ -0,0 +1,65 @@
+"""Add mobile/desktop app install notification.
+
+Revision ID: 034
+Revises: 033
+Create Date: 2026-08-05
+
+"""
+from alembic import op
+from sqlalchemy import text as sa_text
+
+
+# revision identifiers, used by Alembic.
+revision = '034'
+down_revision = '033'
+branch_labels = None
+depends_on = None
+
+SUBJECT = 'Install AFT as an app'
+
+MESSAGE = (
+    "AFT can be installed as an app on your phone, tablet, Mac or PC for a "
+    "full-screen, home-screen experience with no browser address bar. "
+    "Mac/PC (Chrome or Edge): open AFT, then click the install icon in the "
+    "address bar, or the browser menu > Install AFT. "
+    "Android (Chrome): open AFT, tap the menu (three dots) > Install app, "
+    "or use the Install App button in AFT Settings. "
+    "iPhone/iPad (Safari): open AFT, tap the Share icon, then Add to Home "
+    "Screen. See AFT Settings for step-by-step help."
+)
+
+ACTION_TITLE = 'Open Settings'
+ACTION_URL = '/settings.html'
+
+
+def upgrade():
+    """Notify all active, approved users about the installable app."""
+    conn = op.get_bind()
+    conn.execute(
+        sa_text("""
+            INSERT INTO notifications (subject, message, unread, created_at, action_title, action_url, user_id)
+            SELECT :subject, :message, 1, NOW(), :action_title, :action_url, u.id
+            FROM users u
+            WHERE u.is_active = 1
+              AND u.is_approved = 1
+              AND NOT EXISTS (
+                  SELECT 1 FROM notifications n
+                  WHERE n.user_id = u.id AND n.subject = :subject
+              )
+        """),
+        {
+            'subject': SUBJECT,
+            'message': MESSAGE,
+            'action_title': ACTION_TITLE,
+            'action_url': ACTION_URL,
+        },
+    )
+
+
+def downgrade():
+    """Remove the mobile/desktop app install notification."""
+    conn = op.get_bind()
+    conn.execute(
+        sa_text("DELETE FROM notifications WHERE subject = :subject"),
+        {'subject': SUBJECT},
+    )

server/auth.py

@@ -946,9 +946,12 @@ def register():
             create_default_user_settings(user.id, db)
 
             db.commit()
-            
+
             logger.info(f"New user registered: {user.email} (ID: {user.id})")
-            
+
+            from notification_utils import create_mobile_app_notification
+            create_mobile_app_notification(user.id)
+
             # Don't auto-login - user needs admin approval
             # Return success but explain approval is needed
             user_data = {
@@ -1335,9 +1338,12 @@ def ensure_administrator_role(target_user):
                 ensure_administrator_role(existing_admin)
 
                 db.commit()
-                
+
                 user = existing_admin
                 logger.info(f"Updated default admin user: {user.email} (ID: {user.id})")
+
+                from notification_utils import create_mobile_app_notification
+                create_mobile_app_notification(user.id)
             else:
                 # Create new admin user
                 user = User(
@@ -1362,9 +1368,12 @@ def ensure_administrator_role(target_user):
                 ensure_administrator_role(user)
 
                 db.commit()
-                
+
                 logger.info(f"Created first admin user: {user.email} (ID: {user.id})")
-            
+
+                from notification_utils import create_mobile_app_notification
+                create_mobile_app_notification(user.id)
+
             # Auto-login after setup
             session['user_id'] = user.id
             session['user_email_hash'] = hashlib.sha256(user.email.encode()).hexdigest()[:16]

server/notification_utils.py

@@ -6,6 +6,32 @@
 
 logger = logging.getLogger(__name__)
 
+# Shared with alembic/versions/034_add_mobile_app_notification.py - keep both in sync.
+MOBILE_APP_NOTIFICATION_SUBJECT = 'Install AFT as an app'
+MOBILE_APP_NOTIFICATION_MESSAGE = (
+    "AFT can be installed as an app on your phone, tablet, Mac or PC for a "
+    "full-screen, home-screen experience with no browser address bar. "
+    "Mac/PC (Chrome or Edge): open AFT, then click the install icon in the "
+    "address bar, or the browser menu > Install AFT. "
+    "Android (Chrome): open AFT, tap the menu (three dots) > Install app, "
+    "or use the Install App button in AFT Settings. "
+    "iPhone/iPad (Safari): open AFT, tap the Share icon, then Add to Home "
+    "Screen. See AFT Settings for step-by-step help."
+)
+MOBILE_APP_NOTIFICATION_ACTION_TITLE = 'Open Settings'
+MOBILE_APP_NOTIFICATION_ACTION_URL = '/settings.html'
+
+
+def create_mobile_app_notification(user_id: int) -> bool:
+    """Create the 'install AFT as an app' notification for a single new user."""
+    return create_notification(
+        subject=MOBILE_APP_NOTIFICATION_SUBJECT,
+        message=MOBILE_APP_NOTIFICATION_MESSAGE,
+        action_title=MOBILE_APP_NOTIFICATION_ACTION_TITLE,
+        action_url=MOBILE_APP_NOTIFICATION_ACTION_URL,
+        user_id=user_id,
+    )
+
 
 def _resolve_recipient_user_ids(db, explicit_user_id=None):
     """Resolve recipient user IDs for internal notifications.

server/tests/test_api_notifications.py

@@ -1224,9 +1224,14 @@ def test_mark_all_read_only_affects_own_notifications(
         })
         assert b_create.status_code == 201
 
+        b_before = second_user_session.get(f'{api_client}/api/notifications')
+        b_unread_count = sum(1 for n in b_before.json()['notifications'] if n['unread'])
+
         mark_resp = second_user_session.put(f'{api_client}/api/notifications/mark-all-read')
         assert mark_resp.status_code == 200
-        assert mark_resp.json()['count'] == 1, "Expected exactly User B's 1 notification to be updated"
+        assert mark_resp.json()['count'] == b_unread_count, (
+            "Expected exactly User B's own unread notifications to be updated"
+        )
 
         check = authenticated_session.get(f'{api_client}/api/notifications')
         notifs = check.json()['notifications']
@@ -1255,9 +1260,15 @@ def test_delete_all_only_affects_own_notifications(
             'subject': 'User B to delete',
             'message': 'User B notification',
         })
+
+        b_before = second_user_session.get(f'{api_client}/api/notifications')
+        b_notif_count = len(b_before.json()['notifications'])
+
         delete_resp = second_user_session.delete(f'{api_client}/api/notifications/delete-all')
         assert delete_resp.status_code == 200
-        assert delete_resp.json()['count'] == 1, "Expected exactly User B's 1 notification to be deleted"
+        assert delete_resp.json()['count'] == b_notif_count, (
+            "Expected exactly User B's own notifications to be deleted"
+        )
 
         check = authenticated_session.get(f'{api_client}/api/notifications')
         notifs = check.json()['notifications']
@@ -1266,6 +1277,29 @@ def test_delete_all_only_affects_own_notifications(
         )
 
 
+@pytest.mark.api
+class TestMobileAppInstallNotification:
+    """Regression test for Issue 514: new users get a mobile app install notification."""
+
+    def test_new_user_receives_mobile_app_install_notification(
+        self, api_client, second_user_session
+    ):
+        """A freshly registered user should have the 'Install AFT as an app' notification."""
+        response = second_user_session.get(f'{api_client}/api/notifications')
+        assert response.status_code == 200
+
+        notifications = response.json()['notifications']
+        install_notif = next(
+            (n for n in notifications if n['subject'] == 'Install AFT as an app'), None
+        )
+        assert install_notif is not None, (
+            f"Expected an 'Install AFT as an app' notification for a new user, "
+            f"but found subjects: {[n.get('subject') for n in notifications]}"
+        )
+        assert install_notif['unread'] is True
+        assert install_notif['action_url'] == '/settings.html'
+
+
 @pytest.mark.api
 class TestNotificationMultiUserCreation:
     """Test cases for admin creating notifications for all users."""