feat(notifications-kit): implement PushNotificationService for remote notifications

[husamettinarabaci]

Is your feature request related to a problem?

The PushNotificationService skeleton class exists in packages/notifications_kit/lib/push/push_notification_service.dart but needs full implementation to handle push notifications from Firebase Cloud Messaging (FCM) with background handling, tap actions, and data payloads.

Describe the solution you'd like

Implement a fully functional PushNotificationService class that manages push notifications with FCM integration, handles foreground and background messages, processes notification taps, and manages notification permissions.

What is PushNotificationService and why do we need it?

PushNotificationService is the central service for handling remote push notifications sent from a backend server via Firebase Cloud Messaging, enabling real-time user engagement and communication.

Why it's important:

• User Engagement: Re-engage users with timely notifications
• Real-Time Updates: Notify users of important events immediately
• Personalization: Targeted notifications based on user behavior
• Marketing: Campaign notifications and promotions
• Communication: Messages, alerts, and updates

Common use cases:

• New message notifications
• Order status updates
• Breaking news alerts
• Social activity notifications (likes, comments)
• Promotional campaigns
• System alerts and announcements

Required Deliverables

1. PushNotificationService implementation with:

   • Initialize FCM
   • Request notification permissions
   • Handle foreground messages
   • Handle background messages
   • Handle notification tap
   • Parse notification data payload
   • Integration with PushTokenManager
   • Deep link navigation from notification
   • Integration with firebase_messaging

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

   • FCM initialization demo
   • Permission request flow
   • Foreground message handling
   • Background message handling
   • Notification tap handling
   • Data payload parsing
   • Deep link navigation
   • Service inspector UI

3. SPDX headers in all source files

Key Implementation Specs

• initialize() sets up FCM
• requestPermission() asks for notification permission
• onMessageReceived callback for foreground
• onBackgroundMessage callback for background
• onNotificationTap callback with payload
• parsePayload(Map) extracts data
• Use firebase_messaging package
• Background message handler as top-level function
• Integration with DeepLinkHandler for navigation
• Integration with PushTokenManager

Acceptance Criteria

• PushNotificationService class implemented
• initialize() sets up FCM
• requestPermission() requests notification permission
• Foreground messages handled
• Background messages handled
• Notification tap handled
• Data payload parsing works
• Deep link navigation from notification
• Integration with PushTokenManager
• Integration with firebase_messaging
• All 6-8 Widgetbook stories created and functional
• SPDX headers present in all files
• Code follows STYLE_GUIDE.md standards
• Background handler registered correctly

Related Files

• packages/notifications_kit/lib/push/push_notification_service.dart (skeleton)
• packages/notifications_kit/lib/push/push_token_manager.dart (token management)
• packages/navigation_kit/lib/router/deep_link_handler.dart (navigation)
• widgetbook_kit/lib/stories/notifications_kit/push_notification_service_story.dart (Widgetbook)

---

Impact: Essential for user engagement; enables push notifications

Priority: High