feat(push_notifications): add cleanup

Author: fulleni

lib/src/services/push_notification_service.dart

@@ -222,11 +222,24 @@ class DefaultPushNotificationService implements IPushNotificationService {
 
           if (userDeviceTokens.isNotEmpty) {
             // Add the send operation to the list of futures.
+            // The result of this future will contain information about which
+            // tokens succeeded and which failed.
             sendFutures.add(
-              client.sendBulkNotifications(
-                deviceTokens: userDeviceTokens,
-                payload: notification.payload,
-              ),
+              client
+                  .sendBulkNotifications(
+                    deviceTokens: userDeviceTokens,
+                    payload: notification.payload,
+                  )
+                  .then((result) {
+                    // After the send completes, trigger the cleanup process for
+                    // any failed tokens. This is a fire-and-forget operation.
+                    unawaited(
+                      _cleanupInvalidDevices(
+                        result.failedTokens,
+                        primaryProvider,
+                      ),
+                    );
+                  }),
             );
           }
         } catch (e, s) {
@@ -255,4 +268,50 @@ class DefaultPushNotificationService implements IPushNotificationService {
       );
     }
   }
+
+  /// Deletes device registrations associated with a list of invalid tokens.
+  ///
+  /// This method is called after a push notification send operation to prune
+  /// the database of tokens that the provider has identified as unregistered
+  /// or invalid (e.g., because the app was uninstalled).
+  ///
+  /// - [invalidTokens]: A list of device tokens that failed to be delivered.
+  /// - [provider]: The push notification provider that reported the tokens as
+  ///   invalid.
+  Future<void> _cleanupInvalidDevices(
+    List<String> invalidTokens,
+    PushNotificationProvider provider,
+  ) async {
+    if (invalidTokens.isEmpty) {
+      return; // Nothing to clean up.
+    }
+
+    _log.info(
+      'Cleaning up ${invalidTokens.length} invalid device tokens for provider "$provider".',
+    );
+
+    // Retrieve the list of devices that match the filter criteria.
+    final devicesToDelete = await _pushNotificationDeviceRepository.readAll(
+      filter: {
+        'providerTokens.${provider.name}': {r'$in': invalidTokens},
+      },
+    );
+
+    try {
+      // Delete the devices one by one.
+      // While this is less efficient than a bulk delete, it is necessary
+      // as `DataRepository` does not have a `deleteAll` method.
+      await Future.forEach<PushNotificationDevice>(devicesToDelete.items, (
+        device,
+      ) async {
+        await _pushNotificationDeviceRepository.delete(id: device.id);
+      });
+
+      _log.info('Successfully cleaned up invalid device tokens.');
+    } catch (e, s) {
+      _log.severe('Failed to clean up invalid device tokens.', e, s);
+      // We log the error but do not rethrow, as this is a background
+      // cleanup task and should not crash the main application flow.
+    }
+  }
 }