Build FCM Token Manager
epic-push-notification-delivery-ui-task-004 — Implement the FCMTokenManager infrastructure component that registers and refreshes Firebase Cloud Messaging device tokens, handles token rotation on app reinstall or token invalidation, persists the current token to Supabase user profile, and exposes a stream of the active token for downstream services.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use a Riverpod AsyncNotifier or StreamProvider to expose the active token. Initialise by calling FirebaseMessaging.instance.getToken() inside the provider's build method, then merge with the onTokenRefresh stream using StreamController or rx_dart's BehaviorSubject to replay the last value to new subscribers. Persist to Supabase using an upsert on a user_fcm_tokens table keyed by (user_id, platform) to support multi-device. Call FirebaseMessaging.instance.deleteToken() and null out the Supabase row in the sign-out hook.
Register the provider initialisation in main.dart after Supabase.initialize() and FirebaseApp.initialize(), before runApp(). Avoid storing the token in SharedPreferences as a primary source of truth — Supabase is authoritative; local cache is only for offline resilience.
Testing Requirements
Unit tests (flutter_test + mockito/mocktail): mock FirebaseMessaging to simulate getToken success/failure and onTokenRefresh events; mock Supabase client to assert upsert is called with correct payload; verify stream emits correct sequence (null → token → refreshed token). Integration test: verify FCMTokenManager initialises correctly in a widget test environment using a fake Supabase instance. Edge cases: test null token return from Firebase (permissions denied), Supabase 401 during upsert, rapid consecutive refresh events. Target 90%+ line coverage on FCMTokenManager class.
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.