feat(notifications): add preferences heartbeat

Author: dahmeezy

docs/NOTIFICATION_SYSTEM_REFACTORING.md

@@ -115,6 +115,15 @@ Enhanced React hook with:
 - Improved preference validation
 - Better multi-channel delivery support
 - Enhanced analytics integration
+- Notification preference heartbeat state for liveness monitoring
+
+The notification preferences heartbeat runs from `useNotifications` after preferences load. It
+writes `notification_preferences_heartbeat_v1` to `localStorage` with the current `userId`,
+`lastBeatAt`, `intervalMs`, and `staleAfterMs`. Consumers can read
+`preferencesHeartbeat.status` (`online`, `stale`, or `offline`) and call
+`refreshPreferencesHeartbeat()` to re-check the stored heartbeat without waiting for the next
+interval. The preferences UI surfaces this as a compact sync status so users are not left guessing
+when preference persistence is delayed or unavailable.
 
 ## Migration Guide
 

src/app/components/notifications/UserPreferences.tsx

@@ -12,6 +12,7 @@ import {
   RotateCcw,
   Check,
   AlertCircle,
+  Activity,
 } from 'lucide-react';
 import { useNotifications } from '@/app/hooks/useNotifications';
 import RecommendationPanel from './RecommendationPanel';
@@ -65,10 +66,24 @@ const channelIcons: Record<NotificationChannel, React.ReactNode> = {
   sms: <MessageSquare size={16} />,
 };
 
+const heartbeatStatusStyles = {
+  online: 'bg-green-50 text-green-700 border-green-200',
+  stale: 'bg-amber-50 text-amber-700 border-amber-200',
+  offline: 'bg-red-50 text-red-700 border-red-200',
+};
+
+const heartbeatStatusLabels = {
+  online: 'Live',
+  stale: 'Sync delayed',
+  offline: 'Offline',
+};
+
 export default function UserPreferences({ userId, onSave }: UserPreferencesProps) {
   const {
     preferences,
+    preferencesHeartbeat,
     updatePreferences,
+    refreshPreferencesHeartbeat,
     isLoading,
     recommendations,
     applyRecommendation,
@@ -187,9 +202,22 @@ export default function UserPreferences({ userId, onSave }: UserPreferencesProps
     <div className="bg-white border rounded-lg shadow-lg overflow-hidden">
       {/* Header */}
       <div className="p-4 border-b bg-gray-50">
-        <div className="flex items-center gap-2">
-          <Settings size={20} className="text-gray-700" />
-          <h2 className="text-lg font-semibold text-gray-900">Notification Preferences</h2>
+        <div className="flex flex-wrap items-center gap-3">
+          <div className="flex items-center gap-2">
+            <Settings size={20} className="text-gray-700" />
+            <h2 className="text-lg font-semibold text-gray-900">Notification Preferences</h2>
+          </div>
+          <button
+            type="button"
+            onClick={refreshPreferencesHeartbeat}
+            aria-label="Refresh notification preference sync status"
+            className={`ml-auto inline-flex items-center gap-1.5 rounded-md border px-2 py-1 text-xs font-medium ${
+              heartbeatStatusStyles[preferencesHeartbeat.status]
+            }`}
+          >
+            <Activity size={14} aria-hidden="true" />
+            <span aria-live="polite">{heartbeatStatusLabels[preferencesHeartbeat.status]}</span>
+          </button>
         </div>
         <p className="text-sm text-gray-500 mt-1">
           Customize how and when you receive notifications

src/app/hooks/__tests__/useNotifications.test.ts

@@ -5,7 +5,7 @@
  * and basic hook behaviour.
  */
 import { renderHook, act } from '@testing-library/react';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { useNotifications } from '../useNotifications';
 import { useNotificationStore } from '@/app/store/notificationStore';
 import { AppNotification } from '@/lib/notifications/types';
@@ -37,10 +37,20 @@ function resetStore() {
   useNotificationStore.setState({ notifications: [] });
 }
 
+async function flushHookEffects() {
+  await act(async () => {});
+  await act(async () => {});
+}
+
 // ─── Tests ────────────────────────────────────────────────────────────────────
 
 describe('useNotifications', () => {
   beforeEach(resetStore);
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    resetStore();
+  });
 
   // ── clearNotification ──────────────────────────────────────────────────────
 
@@ -133,4 +143,122 @@ describe('useNotifications', () => {
 
     expect(result.current.unreadCount).toBe(0);
   });
+
+  // ── preferences heartbeat ─────────────────────────────────────────────────
+
+  it('starts a preferences heartbeat and persists the liveness payload', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-24T12:00:00.000Z'));
+
+    const { result } = renderHook(() =>
+      useNotifications({
+        userId: 'heartbeat-user',
+        preferencesHeartbeatIntervalMs: 1000,
+        preferencesHeartbeatStaleAfterMs: 3000,
+      }),
+    );
+
+    await flushHookEffects();
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.preferencesHeartbeat.status).toBe('online');
+    expect(result.current.preferencesHeartbeat.lastBeatAt).toBe('2026-06-24T12:00:00.000Z');
+
+    const stored = JSON.parse(
+      localStorageMock.getItem('notification_preferences_heartbeat_v1') ?? 'null',
+    );
+    expect(stored).toMatchObject({
+      userId: 'heartbeat-user',
+      lastBeatAt: '2026-06-24T12:00:00.000Z',
+      intervalMs: 1000,
+      staleAfterMs: 3000,
+    });
+
+    await act(async () => {
+      vi.advanceTimersByTime(1000);
+    });
+
+    expect(result.current.preferencesHeartbeat.lastBeatAt).toBe('2026-06-24T12:00:01.000Z');
+  });
+
+  it('marks an old preferences heartbeat as stale when refreshed', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-24T12:00:10.000Z'));
+
+    localStorageMock.setItem(
+      'notification_preferences_heartbeat_v1',
+      JSON.stringify({
+        userId: 'heartbeat-user',
+        lastBeatAt: '2026-06-24T12:00:00.000Z',
+        intervalMs: 1000,
+        staleAfterMs: 3000,
+      }),
+    );
+
+    const { result } = renderHook(() =>
+      useNotifications({
+        userId: 'heartbeat-user',
+        enablePreferencesHeartbeat: false,
+        preferencesHeartbeatIntervalMs: 1000,
+        preferencesHeartbeatStaleAfterMs: 3000,
+      }),
+    );
+
+    act(() => {
+      result.current.refreshPreferencesHeartbeat();
+    });
+
+    expect(result.current.preferencesHeartbeat.status).toBe('stale');
+    expect(result.current.preferencesHeartbeat.lastBeatAt).toBe('2026-06-24T12:00:00.000Z');
+  });
+
+  it('stops the preferences heartbeat interval on unmount', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-24T12:00:00.000Z'));
+
+    const { result, unmount } = renderHook(() =>
+      useNotifications({
+        userId: 'heartbeat-user',
+        preferencesHeartbeatIntervalMs: 1000,
+        preferencesHeartbeatStaleAfterMs: 3000,
+      }),
+    );
+
+    await flushHookEffects();
+
+    expect(result.current.preferencesHeartbeat.status).toBe('online');
+
+    unmount();
+
+    await act(async () => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    const stored = JSON.parse(
+      localStorageMock.getItem('notification_preferences_heartbeat_v1') ?? 'null',
+    );
+    expect(stored.lastBeatAt).toBe('2026-06-24T12:00:00.000Z');
+  });
+
+  it('reports the preferences heartbeat as offline when storage writes fail', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-24T12:00:00.000Z'));
+    vi.spyOn(localStorageMock, 'setItem').mockImplementation(() => {
+      throw new Error('storage unavailable');
+    });
+
+    const { result } = renderHook(() =>
+      useNotifications({
+        userId: 'heartbeat-user',
+        preferencesHeartbeatIntervalMs: 1000,
+        preferencesHeartbeatStaleAfterMs: 3000,
+      }),
+    );
+
+    await flushHookEffects();
+
+    expect(result.current.preferencesHeartbeat.status).toBe('offline');
+    expect(result.current.preferencesHeartbeat.storageAvailable).toBe(false);
+    expect(result.current.preferencesHeartbeat.failureCount).toBe(1);
+  });
 });