Implement Notification Repository with Realtime
epic-push-notification-delivery-ui-task-002 — Build the NotificationRepository data layer that fetches paginated notification history from Supabase, supports mark-as-read and mark-all-read mutations, and provides a Supabase Realtime stream of the unread count integer. Implement cursor-based pagination for efficient loading of large notification histories.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use Supabase's .stream(primaryKey: ['id']) for Realtime, filtering with .eq('user_id', userId) and .eq('is_read', false), then map to a count via .listen((rows) => emit(rows.length)). For cursor pagination, add .lt('created_at', cursor) to the query when cursor is non-null, with .order('created_at', ascending: false).limit(pageSize). Store the Realtime channel reference in a final field and call supabase.removeChannel(channel) in the repository's dispose method. Expose unreadCountStream as a broadcast stream (StreamController.broadcast()) so multiple widgets can listen.
Use a RealtimeChannelConfig with event RealtimeListenTypes.postgresChanges targeting the notifications table INSERT and UPDATE events only.
Testing Requirements
Unit tests (flutter_test + Mockito): (1) first page fetch returns correct items; (2) cursor pagination returns next page excluding already-fetched items; (3) markAsRead triggers stream emission with decremented count; (4) markAllRead sets all items read in single call; (5) Realtime stream emits new count on simulated INSERT event; (6) channel is unsubscribed on dispose. Use StreamController
The notification badge widget depends on a persistent Supabase Realtime websocket subscription for live unread count updates. On mobile, network transitions (WiFi to cellular, background app state) can silently drop the websocket, resulting in a stale badge count that does not update until the next app foreground — reducing trust in the notification system.
Mitigation & Contingency
Mitigation: Implement connection lifecycle management in the badge widget's BLoC that re-subscribes on app foreground and on network reconnection events. Add a fallback polling query (every 60 seconds when app is foregrounded) to reconcile the badge count if the Realtime subscription is interrupted.
Contingency: If Realtime reliability proves insufficient in production, replace the live subscription with a polling approach using a configurable interval, accepting slightly delayed badge updates in exchange for reliability.
The notification list item widget requires merged semantics combining title, body, timestamp, read state, and role-context icon into a single VoiceOver/TalkBack announcement. Getting the merged semantics structure right for both iOS (VoiceOver) and Android (TalkBack) simultaneously is non-trivial and common to break silently when widgets are refactored.
Mitigation & Contingency
Mitigation: Use the project's existing semantics-wrapper-widget pattern with explicit Semantics widgets and excludeSemantics on decorative children. Write accessibility widget tests using Flutter's SemanticsController to assert the exact announcement string. Test on physical devices with VoiceOver and TalkBack enabled before release.
Contingency: If merged semantics cannot be achieved cleanly on both platforms, implement platform-specific semantic trees using defaultTargetPlatform branching, ensuring each platform receives an optimal announcement even if the implementation differs.