feat(push_notification_client): add PushNotificationResult and update method return types

- Introduce PushNotificationResult class to encapsulate the result of bulk push notification send operations
- Update sendNotification and sendBulkNotifications methods to return PushNotificationResult instead of void
- These changes allow for better error handling and cleanup of invalid device tokens

Author: fulleni

lib/src/services/push_notification_client.dart

@@ -1,4 +1,32 @@
 import 'package:core/core.dart';
+import 'package:equatable/equatable.dart';
+import 'package:meta/meta.dart';
+
+/// {@template push_notification_result}
+/// Encapsulates the result of a bulk push notification send operation.
+///
+/// This class provides structured feedback on which notifications were sent
+/// successfully and which ones failed, including the specific device tokens
+/// for each category. This is crucial for implementing self-healing mechanisms,
+/// such as cleaning up invalid or unregistered device tokens from the database.
+/// {@endtemplate}
+@immutable
+class PushNotificationResult extends Equatable {
+  /// {@macro push_notification_result}
+  const PushNotificationResult({
+    this.sentTokens = const [],
+    this.failedTokens = const [],
+  });
+
+  /// A list of device tokens to which the notification was successfully sent.
+  final List<String> sentTokens;
+
+  /// A list of device tokens to which the notification failed to be sent.
+  final List<String> failedTokens;
+
+  @override
+  List<Object> get props => [sentTokens, failedTokens];
+}
 
 /// An abstract interface for push notification clients.
 ///
@@ -9,7 +37,7 @@ abstract class IPushNotificationClient {
   ///
   /// [deviceToken]: The unique token identifying the target device.
   /// [payload]: The data payload to be sent with the notification.
-  Future<void> sendNotification({
+  Future<PushNotificationResult> sendNotification({
     required String deviceToken,
     required PushNotificationPayload payload,
   });
@@ -21,7 +49,7 @@ abstract class IPushNotificationClient {
   ///
   /// [deviceTokens]: A list of unique tokens identifying the target devices.
   /// [payload]: The data payload to be sent with the notification.
-  Future<void> sendBulkNotifications({
+  Future<PushNotificationResult> sendBulkNotifications({
     required List<String> deviceTokens,
     required PushNotificationPayload payload,
   });