feat(notifications-kit): implement PushTokenManager for FCM token management

[husamettinarabaci]

Is your feature request related to a problem?

The PushTokenManager skeleton class exists in packages/notifications_kit/lib/push/push_token_manager.dart but needs full implementation to manage FCM device tokens, handle token refresh, sync with backend, and track token registration state.

Describe the solution you'd like

Implement a fully functional PushTokenManager service that retrieves FCM tokens, monitors token refresh, syncs tokens with backend API, and manages token storage with proper error handling.

What is PushTokenManager and why do we need it?

PushTokenManager is a service that manages Firebase Cloud Messaging device tokens, ensuring the backend has the current token for sending push notifications and handling token refresh scenarios.

Why it's important:

• Backend Sync: Backend needs current token to send notifications
• Token Refresh: FCM tokens can change and need re-syncing
• Reliability: Ensures notifications always reach the device
• Multi-Device: Tracks tokens per user across devices
• Debugging: Helps troubleshoot notification delivery issues

Common use cases:

• Initial token retrieval on app start
• Token refresh handling
• Syncing token with backend on login
• Removing token from backend on logout
• Multi-device token management
• Token debugging and logging

Required Deliverables

1. PushTokenManager implementation with:

   • Get current FCM token
   • Monitor token refresh
   • Sync token with backend API
   • Remove token from backend
   • Store token locally
   • Token refresh stream
   • Error handling and retry
   • Integration with AuthService
   • Integration with ApiClient

2. Widgetbook stories (6-8 use cases):

   • Get token demo
   • Token refresh handling
   • Sync with backend
   • Token storage
   • Remove token on logout
   • Error handling
   • Token inspector UI
   • Multi-device token display

3. SPDX headers in all source files

Key Implementation Specs

• getToken() returns Future<String?>
• refreshToken() forces token refresh
• syncWithBackend() sends token to API
• removeToken() deletes token from backend
• tokenRefreshStream returns Stream
• Store token in local storage
• API endpoint: POST /api/device-tokens
• Retry logic for sync failures
• Integration with AuthService (user ID)
• Integration with ApiClient

Acceptance Criteria

• PushTokenManager class implemented
• getToken() retrieves FCM token
• refreshToken() forces token refresh
• syncWithBackend() sends token to API
• removeToken() deletes from backend
• tokenRefreshStream emits new tokens
• Token stored locally
• Retry logic for sync failures
• Error handling implemented
• Integration with AuthService
• Integration with ApiClient
• All 6-8 Widgetbook stories created and functional
• SPDX headers present in all files
• Code follows STYLE_GUIDE.md standards
• Unit tests cover token sync logic

Related Files

• packages/notifications_kit/lib/push/push_token_manager.dart (skeleton)
• packages/notifications_kit/lib/push/push_notification_service.dart (uses manager)
• packages/auth_kit/lib/services/auth_service.dart (user context)
• packages/data_kit/lib/http/api_client.dart (backend sync)
• widgetbook_kit/lib/stories/notifications_kit/push_token_manager_story.dart (Widgetbook)

---

Impact: Critical for push notification delivery; ensures backend has current tokens

Priority: High