Merge pull request #93 from flutter-news-app-full-source-code/feat/integrate-with-notification-service-provider

Feat/integrate with notification service provider

Author: fulleni

.env.example

@@ -56,3 +56,29 @@
 # OPTIONAL: The cache duration for the CountryQueryService, in minutes.
 # Defaults to 15 minutes if not specified.
 # COUNTRY_SERVICE_CACHE_MINUTES=15
+
+# CONDITIONALLY REQUIRED: The Firebase Project ID for push notifications.
+# The server will start without this, but it is required to use Firebase for notifications.
+# This is part of your Firebase service account credentials.
+# FIREBASE_PROJECT_ID="your-firebase-project-id"
+
+# CONDITIONALLY REQUIRED: The Firebase Client Email for push notifications.
+# The server will start without this, but it is required to use Firebase for notifications.
+# This is part of your Firebase service account credentials.
+# FIREBASE_CLIENT_EMAIL="your-firebase-client-email"
+
+# CONDITIONALLY REQUIRED: The Firebase Private Key for push notifications.
+# The server will start without this, but it is required to use Firebase for notifications.
+# This is part of your Firebase service account credentials.
+# Ensure this is stored securely and correctly formatted (e.g., replace newlines with \n if needed for single-line env var).
+# FIREBASE_PRIVATE_KEY="your-firebase-private-key"
+
+# CONDITIONALLY REQUIRED: The OneSignal App ID for push notifications.
+# The server will start without this, but it is required to use OneSignal for notifications.
+# This identifies your application within OneSignal.
+# ONESIGNAL_APP_ID="your-onesignal-app-id"
+
+# CONDITIONALLY REQUIRED: The OneSignal REST API Key for server-side push notifications.
+# The server will start without this, but it is required to use OneSignal for notifications.
+# This is used to authenticate with the OneSignal API.
+# ONESIGNAL_REST_API_KEY="your-onesignal-rest-api-key"

README.md

@@ -71,6 +71,16 @@ The data API is equipped with powerful querying capabilities, enabling rich, hig
 The API automatically validates the structure of all incoming data, ensuring that every request is well-formed before it's processed. This built-in mechanism catches missing fields, incorrect data types, and invalid enum values at the gateway, providing clear, immediate feedback to the client.
 > **Your Advantage:** This eliminates an entire class of runtime errors and saves you from writing tedious, repetitive validation code. Your data models remain consistent and your API stays resilient against malformed requests.
 
+---
+
+### 📲 Dynamic & Personalized Notifications
+A complete, multi-provider notification engine that empowers you to engage users with timely, relevant, and personalized alerts.
+- **Editorial-Driven Alerts:** Any piece of content can be designated as "breaking news" from the content dashboard, triggering immediate, high-priority alerts to subscribed users.
+- **User-Crafted Notification Streams:** Users can create and save persistent notification subscriptions based on any combination of content filters (such as topics, sources, or regions), allowing them to receive alerts only for the news they care about.
+- **Flexible Delivery Mechanisms:** The system is architected to support multiple notification types for each subscription, from immediate alerts to scheduled daily or weekly digests.
+- **Provider Agnostic:** The engine is built to be provider-agnostic, with out-of-the-box support for Firebase (FCM) and OneSignal. The active provider can be switched remotely without any code changes.
+> **Your Advantage:** You get a complete, secure, and scalable notification system that enhances user engagement and can be managed entirely from the web dashboard.
+
 </details>
 
 <details>

lib/src/config/app_dependencies.dart

@@ -1,6 +1,7 @@
 // ignore_for_file: public_member_api_docs
 
 import 'dart:async';
+
 import 'package:core/core.dart';
 import 'package:data_mongodb/data_mongodb.dart';
 import 'package:data_repository/data_repository.dart';
@@ -16,10 +17,15 @@ import 'package:flutter_news_app_api_server_full_source_code/src/services/dashbo
 import 'package:flutter_news_app_api_server_full_source_code/src/services/database_migration_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/database_seeding_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/default_user_preference_limit_service.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/services/firebase_authenticator.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/services/firebase_push_notification_client.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/jwt_auth_token_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/mongodb_rate_limit_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/mongodb_token_blacklist_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/mongodb_verification_code_storage_service.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/services/onesignal_push_notification_client.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/services/push_notification_client.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/services/push_notification_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/rate_limit_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/token_blacklist_service.dart';
 import 'package:flutter_news_app_api_server_full_source_code/src/services/user_preference_limit_service.dart';
@@ -62,6 +68,10 @@ class AppDependencies {
   late final DataRepository<UserAppSettings> userAppSettingsRepository;
   late final DataRepository<UserContentPreferences>
   userContentPreferencesRepository;
+  late final DataRepository<PushNotificationDevice>
+  pushNotificationDeviceRepository;
+  late final DataRepository<PushNotificationSubscription>
+  pushNotificationSubscriptionRepository;
   late final DataRepository<RemoteConfig> remoteConfigRepository;
   late final EmailRepository emailRepository;
 
@@ -76,6 +86,10 @@ class AppDependencies {
   late final UserPreferenceLimitService userPreferenceLimitService;
   late final RateLimitService rateLimitService;
   late final CountryQueryService countryQueryService;
+  late final IPushNotificationService pushNotificationService;
+  late final IFirebaseAuthenticator? firebaseAuthenticator;
+  late final IPushNotificationClient? firebasePushNotificationClient;
+  late final IPushNotificationClient? oneSignalPushNotificationClient;
 
   /// Initializes all application dependencies.
   ///
@@ -198,6 +212,91 @@ class AppDependencies {
         logger: Logger('DataMongodb<RemoteConfig>'),
       );
 
+      // Initialize Data Clients for Push Notifications
+      final pushNotificationDeviceClient = DataMongodb<PushNotificationDevice>(
+        connectionManager: _mongoDbConnectionManager,
+        modelName: 'push_notification_devices',
+        fromJson: PushNotificationDevice.fromJson,
+        toJson: (item) => item.toJson(),
+        logger: Logger('DataMongodb<PushNotificationDevice>'),
+      );
+      final pushNotificationSubscriptionClient =
+          DataMongodb<PushNotificationSubscription>(
+            connectionManager: _mongoDbConnectionManager,
+            modelName: 'push_notification_subscriptions',
+            fromJson: PushNotificationSubscription.fromJson,
+            toJson: (item) => item.toJson(),
+            logger: Logger('DataMongodb<PushNotificationSubscription>'),
+          );
+
+      // --- Conditionally Initialize Push Notification Clients ---
+
+      // Firebase
+      final fcmProjectId = EnvironmentConfig.firebaseProjectId;
+      final fcmClientEmail = EnvironmentConfig.firebaseClientEmail;
+      final fcmPrivateKey = EnvironmentConfig.firebasePrivateKey;
+
+      if (fcmProjectId != null &&
+          fcmClientEmail != null &&
+          fcmPrivateKey != null) {
+        _log.info('Firebase credentials found. Initializing Firebase client.');
+        firebaseAuthenticator = FirebaseAuthenticator(
+          log: Logger('FirebaseAuthenticator'),
+        );
+
+        final firebaseHttpClient = HttpClient(
+          baseUrl: 'https://fcm.googleapis.com/v1/projects/$fcmProjectId/',
+          tokenProvider: firebaseAuthenticator!.getAccessToken,
+          logger: Logger('FirebasePushNotificationClient'),
+        );
+
+        firebasePushNotificationClient = FirebasePushNotificationClient(
+          httpClient: firebaseHttpClient,
+          projectId: fcmProjectId,
+          log: Logger('FirebasePushNotificationClient'),
+        );
+      } else {
+        _log.warning(
+          'One or more Firebase credentials not found. Firebase push notifications will be disabled.',
+        );
+        firebaseAuthenticator = null;
+        firebasePushNotificationClient = null;
+      }
+
+      // OneSignal
+      final osAppId = EnvironmentConfig.oneSignalAppId;
+      final osApiKey = EnvironmentConfig.oneSignalRestApiKey;
+
+      if (osAppId != null && osApiKey != null) {
+        _log.info(
+          'OneSignal credentials found. Initializing OneSignal client.',
+        );
+        final oneSignalHttpClient = HttpClient(
+          baseUrl: 'https://onesignal.com/api/v1/',
+          tokenProvider: () async => null,
+          interceptors: [
+            InterceptorsWrapper(
+              onRequest: (options, handler) {
+                options.headers['Authorization'] = 'Basic $osApiKey';
+                return handler.next(options);
+              },
+            ),
+          ],
+          logger: Logger('OneSignalPushNotificationClient'),
+        );
+
+        oneSignalPushNotificationClient = OneSignalPushNotificationClient(
+          httpClient: oneSignalHttpClient,
+          appId: osAppId,
+          log: Logger('OneSignalPushNotificationClient'),
+        );
+      } else {
+        _log.warning(
+          'One or more OneSignal credentials not found. OneSignal push notifications will be disabled.',
+        );
+        oneSignalPushNotificationClient = null;
+      }
+
       // 4. Initialize Repositories
       headlineRepository = DataRepository(dataClient: headlineClient);
       topicRepository = DataRepository(dataClient: topicClient);
@@ -212,6 +311,12 @@ class AppDependencies {
         dataClient: userContentPreferencesClient,
       );
       remoteConfigRepository = DataRepository(dataClient: remoteConfigClient);
+      pushNotificationDeviceRepository = DataRepository(
+        dataClient: pushNotificationDeviceClient,
+      );
+      pushNotificationSubscriptionRepository = DataRepository(
+        dataClient: pushNotificationSubscriptionClient,
+      );
       // Configure the HTTP client for SendGrid.
       // The HttpClient's AuthInterceptor will use the tokenProvider to add
       // the 'Authorization: Bearer <SENDGRID_API_KEY>' header.
@@ -275,6 +380,15 @@ class AppDependencies {
         log: Logger('CountryQueryService'),
         cacheDuration: EnvironmentConfig.countryServiceCacheDuration,
       );
+      pushNotificationService = DefaultPushNotificationService(
+        pushNotificationDeviceRepository: pushNotificationDeviceRepository,
+        pushNotificationSubscriptionRepository:
+            pushNotificationSubscriptionRepository,
+        remoteConfigRepository: remoteConfigRepository,
+        firebaseClient: firebasePushNotificationClient,
+        oneSignalClient: oneSignalPushNotificationClient,
+        log: Logger('DefaultPushNotificationService'),
+      );
 
       _log.info('Application dependencies initialized successfully.');
       // Signal that initialization has completed successfully.

lib/src/config/environment_config.dart

@@ -60,12 +60,13 @@ abstract final class EnvironmentConfig {
     return env; // Return even if fallback
   }
 
-  static String _getRequiredEnv(String key) {
+  static String? _getEnv(String key) {
     final value = _env[key];
     if (value == null || value.isEmpty) {
-      _log.severe('$key not found in environment variables.');
-      throw StateError('FATAL: $key environment variable is not set.');
+      _log.warning('$key not found or is empty in environment variables.');
+      return null;
     }
+
     return value;
   }
 
@@ -75,7 +76,18 @@ abstract final class EnvironmentConfig {
   ///
   /// Throws a [StateError] if the `DATABASE_URL` environment variable is not
   /// set, as the application cannot function without it.
-  static String get databaseUrl => _getRequiredEnv('DATABASE_URL');
+  static String get databaseUrl => _getRequiredEnv(
+    'DATABASE_URL',
+  );
+
+  static String _getRequiredEnv(String key) {
+    final value = _env[key];
+    if (value == null || value.isEmpty) {
+      _log.severe('$key not found in environment variables.');
+      throw StateError('FATAL: $key environment variable is not set.');
+    }
+    return value;
+  }
 
   /// Retrieves the JWT secret key from the environment.
   ///
@@ -182,4 +194,29 @@ abstract final class EnvironmentConfig {
         int.tryParse(_env['COUNTRY_SERVICE_CACHE_MINUTES'] ?? '15') ?? 15;
     return Duration(minutes: minutes);
   }
+
+  /// Retrieves the Firebase Project ID from the environment.
+  ///
+  /// The value is read from the `FIREBASE_PROJECT_ID` environment variable, if available.
+  static String? get firebaseProjectId => _getEnv('FIREBASE_PROJECT_ID');
+
+  /// Retrieves the Firebase Client Email from the environment.
+  ///
+  /// The value is read from the `FIREBASE_CLIENT_EMAIL` environment variable, if available.
+  static String? get firebaseClientEmail => _getEnv('FIREBASE_CLIENT_EMAIL');
+
+  /// Retrieves the Firebase Private Key from the environment.
+  ///
+  /// The value is read from the `FIREBASE_PRIVATE_KEY` environment variable, if available.
+  static String? get firebasePrivateKey => _getEnv('FIREBASE_PRIVATE_KEY');
+
+  /// Retrieves the OneSignal App ID from the environment.
+  ///
+  /// The value is read from the `ONESIGNAL_APP_ID` environment variable, if available.
+  static String? get oneSignalAppId => _getEnv('ONESIGNAL_APP_ID');
+
+  /// Retrieves the OneSignal REST API Key from the environment.
+  ///
+  /// The value is read from the `ONESIGNAL_REST_API_KEY` environment variable, if available.
+  static String? get oneSignalRestApiKey => _getEnv('ONESIGNAL_REST_API_KEY');
 }

lib/src/database/migrations/20251107000000_add_is_breaking_to_headlines.dart

@@ -0,0 +1,51 @@
+import 'package:flutter_news_app_api_server_full_source_code/src/database/migration.dart';
+import 'package:logging/logging.dart';
+import 'package:mongo_dart/mongo_dart.dart';
+
+/// Migration to add the `isBreaking` field to existing `Headline` documents.
+///
+/// This migration ensures that all existing documents in the `headlines`
+/// collection have the `isBreaking` boolean field, defaulting to `false`
+/// if it does not already exist. This is crucial for schema consistency
+/// when introducing the breaking news feature.
+class AddIsBreakingToHeadlines extends Migration {
+  /// {@macro add_is_breaking_to_headlines}
+  AddIsBreakingToHeadlines()
+    : super(
+        prDate: '20251107000000',
+        prId: '71',
+        prSummary:
+            'Adds the isBreaking field to existing Headline documents, '
+            'defaulting to false.',
+      );
+
+  @override
+  Future<void> up(Db db, Logger log) async {
+    final collection = db.collection('headlines');
+
+    log.info(
+      'Attempting to add "isBreaking: false" to Headline documents '
+      'where the field is missing...',
+    );
+
+    // Update all documents in the 'headlines' collection that do not
+    // already have the 'isBreaking' field, setting it to false.
+    final updateResult = await collection.updateMany(
+      // Select documents where 'isBreaking' does not exist.
+      where.notExists('isBreaking'),
+      modify.set('isBreaking', false), // Set isBreaking to false
+    );
+
+    log.info(
+      'Added "isBreaking: false" to ${updateResult.nModified} Headline documents.',
+    );
+  }
+
+  @override
+  Future<void> down(Db db, Logger log) async {
+    log.warning(
+      'Reverting "AddIsBreakingToHeadlines" is not supported. '
+      'The "isBreaking" field would need to be manually removed if required.',
+    );
+  }
+}

lib/src/database/migrations/20251108103300_add_push_notification_config_to_remote_config.dart

@@ -0,0 +1,62 @@
+import 'package:core/core.dart';
+import 'package:flutter_news_app_api_server_full_source_code/src/database/migration.dart';
+import 'package:logging/logging.dart';
+import 'package:mongo_dart/mongo_dart.dart';
+
+/// {@template add_push_notification_config_to_remote_config}
+/// A database migration to add the `pushNotificationConfig` field to the
+/// `remote_configs` document.
+///
+/// This migration ensures that the `remote_configs` document contains the
+/// necessary structure for push notification settings, preventing errors when
+/// the application starts and tries to access this configuration. It is
+/// designed to be idempotent and safe to run multiple times.
+/// {@endtemplate}
+class AddPushNotificationConfigToRemoteConfig extends Migration {
+  /// {@macro add_push_notification_config_to_remote_config}
+  AddPushNotificationConfigToRemoteConfig()
+    : super(
+        prId: '71',
+        prSummary:
+            'Add pushNotificationConfig field to the remote_configs document.',
+        prDate: '20251108103300',
+      );
+
+  @override
+  Future<void> up(Db db, Logger log) async {
+    log.info('Running up migration: $prSummary');
+
+    final remoteConfigCollection = db.collection('remote_configs');
+    final remoteConfigId = ObjectId.fromHexString(kRemoteConfigId);
+
+    // Default structure for the push notification configuration.
+    final pushNotificationConfig =
+        remoteConfigsFixturesData.first.pushNotificationConfig;
+
+    // Use $set to add the field only if it doesn't exist.
+    // This is an idempotent operation.
+    await remoteConfigCollection.updateOne(
+      where
+          .id(remoteConfigId)
+          .and(
+            where.notExists('pushNotificationConfig'),
+          ),
+      modify.set('pushNotificationConfig', pushNotificationConfig.toJson()),
+    );
+
+    log.info('Successfully completed up migration for $prDate.');
+  }
+
+  @override
+  Future<void> down(Db db, Logger log) async {
+    log.info('Running down migration: $prSummary');
+    // This migration is additive. The `down` method will unset the field.
+    final remoteConfigCollection = db.collection('remote_configs');
+    final remoteConfigId = ObjectId.fromHexString(kRemoteConfigId);
+    await remoteConfigCollection.updateOne(
+      where.id(remoteConfigId),
+      modify.unset('pushNotificationConfig'),
+    );
+    log.info('Successfully completed down migration for $prDate.');
+  }
+}