kasy-cli 1.2.1

package/templates/firebase/lib/features/notifications/repositories/background_notification_handler.dart

@@ -0,0 +1,13 @@
+import 'package:firebase_messaging/firebase_messaging.dart';
+
+/// Background message handler — runs in a separate Dart isolate.
+///
+/// When the app is in background or terminated and a FCM message arrives with
+/// a `notification` payload, the OS/FCM SDK displays the banner automatically
+/// WITHOUT any Flutter code. This handler is only needed for *data-only*
+/// messages (message.notification == null) that require custom processing.
+@pragma('vm:entry-point')
+Future<void> onBackgroundMessage(RemoteMessage message) async {
+  // Nothing to do: FCM auto-shows notification banners in background/terminated.
+  // Add data-only message handling here if needed (message.notification == null).
+}

package/templates/firebase/lib/features/notifications/repositories/device_repository.dart

@@ -0,0 +1,137 @@
+import 'dart:convert';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/shared_preferences/shared_preferences.dart';
+import 'package:kasy_kit/features/notifications/api/device_api.dart';
+import 'package:kasy_kit/features/notifications/api/entities/device_entity.dart';
+import 'package:kasy_kit/features/notifications/providers/models/device.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+final deviceRepositoryProvider = Provider<DeviceRepository>(
+  (ref) {
+    final prefsLoader = ref.watch(sharedPreferencesProvider);
+    return DeviceRepository(
+      prefs: prefsLoader.prefs,
+      deviceApi: ref.watch(deviceApiProvider),
+    );
+  },
+);
+
+const _devicePrefsKey = 'device';
+const _deviceUserIdPrefsKey = 'device_user_id';
+
+typedef OnTokenRefreshCallback = void Function(Device device);
+
+/// This repository is responsible for the device registration
+/// You need to register the device in your backend to be able to send notifications
+/// You can also unregister the device
+/// The device is also stored in the shared preferences to prevent spamming the backend
+/// The token is updated when the token is refreshed
+/// Optionnaly you can also add the user id to the methods
+class DeviceRepository {
+  final DeviceApi _deviceApi;
+  final SharedPreferences _prefs;
+
+  DeviceRepository({
+    required DeviceApi deviceApi,
+    required SharedPreferences prefs,
+  })  : _deviceApi = deviceApi,
+        _prefs = prefs;
+
+  Future<Device?> get() async {
+    final deviceEntity = await _getFromPrefs();
+    if (deviceEntity == null) {
+      return null;
+    }
+    return Device.fromEntity(deviceEntity);
+  }
+
+  Future<void> register(String userId) async {
+    final device = await _getFromPrefs();
+    final newDevice = await _deviceApi.get();
+    final cachedUserId = _prefs.getString(_deviceUserIdPrefsKey);
+    // Only skip re-registration if BOTH the token AND the user haven't changed.
+    // Without the userId check, a new anonymous user (same device token) would
+    // reuse the cached prefs and never register in the database.
+    if (device != null && device.token == newDevice.token && cachedUserId == userId) {
+      return;
+    }
+    // Include device properties so the welcome notification fires in the correct locale.
+    final extraData = await _deviceApi.fetchDeviceProperties();
+    final deviceWithLocale = newDevice.copyWith(extraData: extraData);
+    final response = await _deviceApi.register(userId, deviceWithLocale);
+    await _saveInPrefs(response);
+    await _prefs.setString(_deviceUserIdPrefsKey, userId);
+  }
+
+  Future<void> unregister(String userId) async {
+    final device = await _getFromPrefs();
+    if (device == null) {
+      return;
+    }
+    await _deviceApi.unregister(userId, device.installationId);
+    await _removeFromPrefs();
+    await _prefs.remove(_deviceUserIdPrefsKey);
+  }
+
+  void onTokenUpdate(OnTokenRefreshCallback onTokenRefresh) {
+    _deviceApi.onTokenRefresh((token) async {
+      final device = await _getFromPrefs();
+      if (device == null) {
+        return;
+      }
+      final updatedDevice = device.copyWith(token: token);
+      onTokenRefresh(Device.fromEntity(updatedDevice));
+    });
+  }
+
+  void removeTokenUpdateListener() {
+    _deviceApi.removeOnTokenRefreshListener();
+  }
+
+  Future<void> updateToken(String token) async {
+    final device = await _getFromPrefs();
+    if (device == null) return;
+    final userId = _prefs.getString(_deviceUserIdPrefsKey);
+    if (userId == null) return;
+    final updatedDevice = device.copyWith(token: token);
+    await _deviceApi.update(userId, updatedDevice);
+    await _saveInPrefs(updatedDevice);
+  }
+
+  Future<void> refreshExtraData() async {
+    final device = await _getFromPrefs();
+    if (device == null) return;
+    final userId = _prefs.getString(_deviceUserIdPrefsKey);
+    if (userId == null) return;
+    final extraData = await _deviceApi.fetchDeviceProperties();
+    if (device.extraData.toString() == extraData.toString()) return;
+    final updatedDevice = device.copyWith(extraData: extraData);
+    await _deviceApi.update(userId, updatedDevice);
+    await _saveInPrefs(updatedDevice);
+  }
+  
+  
+  /// ------------------------------
+  /// PRIVATES
+  /// ------------------------------
+
+  Future<void> _saveInPrefs(DeviceEntity device) async {
+    final json = device.toJsonForPrefs();
+    final data = jsonEncode(json);
+    await _prefs.setString(_devicePrefsKey, data);
+  }
+
+  Future<DeviceEntity?> _getFromPrefs() async {
+    final deviceJson = _prefs.getString(_devicePrefsKey);
+    if (deviceJson != null) {
+      final deviceMap = jsonDecode(deviceJson) as Map<String, dynamic>;
+      return DeviceEntity.fromPrefs(deviceMap);
+    }
+    return null;
+  }
+
+  Future<void> _removeFromPrefs() async {
+    await _prefs.remove(_devicePrefsKey);
+  }
+}

package/templates/firebase/lib/features/notifications/repositories/notifications_repository.dart

@@ -0,0 +1,214 @@
+import 'package:firebase_messaging/firebase_messaging.dart' show RemoteMessage;
+import 'package:flutter/foundation.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/data/api/tracking_api.dart';
+import 'package:kasy_kit/core/initializer/onstart_service.dart';
+import 'package:kasy_kit/core/states/notifications_dispatcher.dart';
+import 'package:kasy_kit/features/notifications/api/local_notifier.dart';
+import 'package:kasy_kit/features/notifications/api/notifications_api.dart';
+import 'package:kasy_kit/features/notifications/providers/models/notification.dart';
+import 'package:kasy_kit/features/notifications/repositories/background_notification_handler.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
+import 'package:kasy_kit/router.dart';
+import 'package:logger/logger.dart';
+import 'package:permission_handler/permission_handler.dart';
+
+abstract class NotificationsRepository implements OnStartService {
+  // this method is used to get the notifications from the server
+  Future<List<Notification>> get(
+    String userId, {
+    int pageSize = 20,
+    DateTime? startDate,
+    int page = 0,
+  });
+
+  // mark a notification as read
+  Future<Notification> read(String userId, Notification notification);
+
+  // listen to the unread notifications count
+  Stream<int> listenToUnreadNotificationsCount(String userId);
+
+  // return the permission status
+  Future<NotificationPermission> getPermissionStatus();
+}
+
+final notificationRepositoryProvider = Provider<NotificationsRepository>(
+  (ref) => AppNotificationsRepository(
+    notificationsApi: ref.watch(notificationsApiProvider),
+    notificationPublisher: ref.watch(notificationPublisherProvider),
+    localNotifier: ref.watch(localNotifierProvider),
+    notificationSettings: ref.watch(notificationsSettingsProvider),
+    facebookEventApi: ref.watch(facebookEventApiProvider),
+  ),
+);
+
+class AppNotificationsRepository implements NotificationsRepository {
+  final NotificationsApi _notificationsApi;
+  final NotificationPublisher _notificationPublisher;
+  final LocalNotifier _localNotifier;
+  final NotificationSettings _notificationSettings;
+  final FacebookEventApi _facebookEventApi;
+
+  AppNotificationsRepository({
+    required NotificationsApi notificationsApi,
+    required NotificationPublisher notificationPublisher,
+    required LocalNotifier localNotifier,
+    required NotificationSettings notificationSettings,
+    required FacebookEventApi facebookEventApi,
+  })  : _notificationsApi = notificationsApi,
+        _localNotifier = localNotifier,
+        _notificationSettings = notificationSettings,
+        _facebookEventApi = facebookEventApi,
+        _notificationPublisher = notificationPublisher;
+
+  @override
+  Future<void> init() async {
+    final permission = await getPermissionStatus();
+    if (permission is NotificationPermissionGranted) {
+      await _notificationSettings.init();
+
+      _notificationsApi.setForegroundHandler(_onMessage);
+      _notificationsApi.setBackgroundHandler(onBackgroundMessage);
+      _notificationsApi.setOnOpenNotificationHandler(_onOpenMessage);
+
+      // Subscribe to topics doesn't work on web
+      if (kIsWeb) {
+        return;
+      }
+      /// If you want to subscribe to a specific topic
+      _notificationsApi.registerTopic('general');
+
+      /// If you want to subscribe to a specific topic based on the user language
+      final locale = LocaleSettings.instance.currentLocale.languageCode;
+      final langChannel = "general-$locale";
+      _notificationsApi.registerTopic(langChannel);
+
+      /// we register a test topic in debug mode
+      if (kDebugMode) {
+        debugPrint('Registering to test topic');
+        _notificationsApi.registerTopic('test');
+      }
+    }
+    
+  }
+
+  Future<void> _onMessage(RemoteMessage message) async {
+    if (message.notification == null) {
+      
+      Logger().i('[NOTIFICATIONS REPOSITORY] 🔥 -> Notification push only with data');
+      switch (message.data['type']) {
+        case 'SUBSCRIPTION_TRIAL' when message.data.containsKey('price') && message.data.containsKey('currency') && message.data.containsKey('subscription_id'):
+          _facebookEventApi.logMetaStartTrial(
+            message.data['subscription_id'] as String, 
+            double.tryParse(message.data['price'] as String) ?? 0.0, 
+            message.data['currency'] as String,
+          );
+        case 'SUBSCRIPTION_PURCHASE' when message.data.containsKey('price') && message.data.containsKey('currency') && message.data.containsKey('subscription_id'):
+          _facebookEventApi.logMetaSubscribe(
+            message.data['subscription_id'] as String,
+            double.tryParse(message.data['price'] as String) ?? 0.0, 
+            message.data['currency'] as String,
+          );
+        default:
+          break;
+      }
+      
+      return;
+    }
+    final notification = Notification.from(
+      message.notification!.toMap(),
+      data: message.data,
+      notifierApi: _localNotifier,
+      notifierSettings: _notificationSettings,
+    );
+    _notificationPublisher.publish(notification);
+  }
+
+  Future<void> _onOpenMessage(RemoteMessage message) async {
+    if (message.notification == null) {
+      return;
+    }
+    if (navigatorKey.currentContext == null) {
+      return;
+    }
+    final notification = Notification.from(
+      message.notification!.toMap(),
+      data: message.data,
+      notifierApi: _localNotifier,
+      notifierSettings: _notificationSettings,
+    );
+    await notification.onTap();
+  }
+
+  @override
+  Future<NotificationPermission> getPermissionStatus() async {
+    final systemStatus = await _notificationsApi.getPermissionStatus();
+    switch (systemStatus) {
+      case PermissionStatus.granted:
+        return NotificationPermissionGranted(
+          notificationSettings: _notificationSettings,
+          repository: this,
+        );
+      case PermissionStatus.denied:
+        return NotificationPermissionDenied(
+          notificationSettings: _notificationSettings,
+          repository: this,
+        );
+      case PermissionStatus.permanentlyDenied:
+        return NotificationPermissionDenied(
+          notificationSettings: _notificationSettings,
+          repository: this,
+        );
+      default:
+        return NotificationPermissionWaiting(
+          notificationSettings: _notificationSettings,
+          repository: this,
+        );
+    }
+  }
+
+  @override
+  Future<List<Notification>> get(
+    String userId, {
+    int pageSize = 20,
+    DateTime? startDate,
+    int page = 0,
+  }) async {
+    final notificationEntities = await _notificationsApi.get(
+      userId,
+      limit: pageSize,
+      startDate: startDate,
+    );
+    final notifications = notificationEntities
+        .map(
+          (e) => Notification.withData(
+            id: e.id,
+            title: e.title,
+            body: e.body,
+            createdAt: e.creationDate,
+            readAt: e.readDate,
+            imageUrl: e.imageUrl,
+            type: e.type,
+            data: e.data,
+            notifier: _localNotifier,
+            notifierSettings: _notificationSettings,
+          ),
+        )
+        .toList();
+    return notifications;
+  }
+
+  @override
+  Future<Notification> read(String userId, Notification notification) async {
+    if (notification.id == null) {
+      throw Exception('A notification without id cannot be read');
+    }
+    await _notificationsApi.read(userId, notification.id!);
+    return notification.copyWith(readAt: DateTime.now());
+  }
+
+  @override
+  Stream<int> listenToUnreadNotificationsCount(String userId) {
+    return _notificationsApi.unreadNotifications(userId);
+  }
+}

package/templates/firebase/lib/features/notifications/shared/att_permission.dart

@@ -0,0 +1,75 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/components/components.dart';
+import 'package:kasy_kit/core/data/api/tracking_api.dart';
+import 'package:kasy_kit/core/icons/kasy_icons.dart';
+import 'package:kasy_kit/core/states/components/maybeshow_component.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+import 'package:kasy_kit/core/states/user_state_notifier.dart';
+import 'package:kasy_kit/features/subscription/repositories/subscription_repository.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
+import 'package:permission_handler/permission_handler.dart';
+
+/// Requests App Tracking Transparency (ATT) on iOS if not yet determined.
+///
+/// This handler always returns `false` so the event chain continues and
+/// [MaybeShowNotificationPermission] can still run in the same app-start cycle.
+///
+/// Placement: add it to [ConditionalWidgetsEvents] immediately before the
+/// notification-permission handler.
+///
+/// To remove: delete this file and remove [MaybeShowAttPermission] from
+/// [HomePage]'s event list.
+class MaybeShowAttPermission implements MaybeShowWithRef {
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (kIsWeb) return false;
+    if (defaultTargetPlatform != TargetPlatform.iOS) return false;
+    if (event is! OnAppStartEvent) return false;
+
+    final status = await Permission.appTrackingTransparency.status;
+    // `denied` in permission_handler maps to iOS "notDetermined" — never asked.
+    if (!status.isDenied) return false;
+
+    if (!ref.context.mounted) return false;
+
+    final confirmed = await _showExplanationDialog(ref.context);
+    if (!confirmed) return false;
+
+    await Permission.appTrackingTransparency.request();
+
+    final userId = ref.read(userStateNotifierProvider).user.idOrNull;
+    if (userId != null) {
+      ref.read(subscriptionRepositoryProvider).initUser(userId).ignore();
+      ref.read(facebookEventApiProvider).initUser(userId).ignore();
+    }
+
+    // Return false so MaybeShowNotificationPermission also runs.
+    return false;
+  }
+
+  Future<bool> _showExplanationDialog(BuildContext context) async {
+    final confirmed = await showKasyBlurDialog<bool>(
+      context: context,
+      builder: (dialogContext) {
+        final t = Translations.of(dialogContext).onboarding.att;
+        return KasyDialog(
+          leadingIcon: KasyIcons.privacy,
+          iconTone: KasyDialogIconTone.info,
+          title: t.title,
+          message: t.description,
+          showCloseButton: false,
+          actions: [
+            KasyButton(
+              label: t.continue_button,
+              expand: true,
+              onPressed: () => Navigator.of(dialogContext).pop(true),
+            ),
+          ],
+        );
+      },
+    );
+    return confirmed ?? false;
+  }
+}

package/templates/firebase/lib/features/notifications/shared/notification_permission_bottom_sheet.dart

@@ -0,0 +1,144 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/components/components.dart';
+import 'package:kasy_kit/core/icons/kasy_icons.dart';
+import 'package:kasy_kit/core/states/components/maybeshow_component.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+import 'package:kasy_kit/features/notifications/api/local_notifier.dart';
+import 'package:kasy_kit/features/notifications/repositories/notifications_repository.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
+import 'package:logger/logger.dart';
+import 'package:permission_handler/permission_handler.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+/// This widget is used to show the notification permission dialog
+/// if user didn't grant permission, we will show the dialog again
+/// if user granted permission, we will not show the dialog again
+/// customize the trigger condition to your needs
+class MaybeShowNotificationPermission extends MaybeShowWithContext {
+  @override
+  Future<bool> handle(BuildContext context, AppEvent? event) async {
+    if (event == null) return false;
+    return switch (event) {
+      OnAppStartEvent() => showNotificationPermissionSheetIfNeeded(context),
+      _ => false,
+    };
+  }
+}
+
+Future<bool> showNotificationPermissionSheetIfNeeded(
+  BuildContext context, {
+  bool force = false,
+}) async {
+  if (kIsWeb) return false;
+  Logger().d("🔔 [MaybeShowNotificationPermission] checking permission status");
+  final permissionStatus = await Permission.notification.status;
+  if (permissionStatus.isGranted && !force) {
+    debugPrint('🔔 [MaybeShowNotificationPermission] permission is granted ✅');
+    return false;
+  }
+  if (context.mounted) {
+    await showKasyBlurDialog<void>(
+      context: context,
+      builder: (dialogContext) => const _NotificationPermissionDialog(),
+    );
+  }
+  return true;
+}
+
+class _NotificationPermissionDialog extends ConsumerWidget {
+  const _NotificationPermissionDialog();
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final translations = Translations.of(
+      context,
+    ).request_notification_permission;
+    final notificationSettings = ref.read(notificationsSettingsProvider);
+    final notificationRepository = ref.read(notificationRepositoryProvider);
+
+    return KasyDialog(
+      leadingIcon: KasyIcons.notificationAdd,
+      iconTone: KasyDialogIconTone.info,
+      title: translations.title,
+      message: translations.description,
+      showCloseButton: false,
+      actions: [
+        KasyButton(
+          label: translations.continue_button,
+          expand: true,
+          onPressed: () => _requestNotificationPermission(
+            context,
+            notificationSettings,
+            notificationRepository,
+          ),
+        ),
+      ],
+    );
+  }
+
+  Future<void> _requestNotificationPermission(
+    BuildContext context,
+    NotificationSettings notificationSettings,
+    NotificationsRepository notificationRepository,
+  ) async {
+    try {
+      final permissionStatus = await Permission.notification.status;
+
+      if (permissionStatus.isPermanentlyDenied) {
+        if (!context.mounted) return;
+        await _showPermissionDeniedDialog(context);
+        if (!context.mounted) return;
+        Navigator.of(context).pop();
+        return;
+      }
+
+      if (permissionStatus.isDenied) {
+        final granted = await notificationSettings.askPermission();
+        if (!context.mounted) return;
+        Navigator.of(context).pop();
+        if (granted) {
+          notificationRepository.init();
+        } else {
+          await _showPermissionDeniedDialog(context);
+        }
+        return;
+      }
+
+      final notificationsEnabled =
+          await notificationSettings.areNotificationsEnabled();
+      if (!context.mounted) return;
+      if (notificationsEnabled) {
+        await notificationRepository.init();
+        if (!context.mounted) return;
+        Navigator.of(context).pop();
+        return;
+      }
+      await _showPermissionDeniedDialog(context);
+      if (!context.mounted) return;
+      Navigator.of(context).pop();
+    } catch (e, stackTrace) {
+      if (!context.mounted) return;
+      debugPrint('🔔 [NotificationPermissionDialog] error: $e');
+      Sentry.captureException(e, stackTrace: stackTrace);
+      Navigator.of(context).pop();
+    }
+  }
+
+  Future<void> _showPermissionDeniedDialog(BuildContext context) {
+    final t = Translations.of(context).notification_permission_denied;
+    return showKasyConfirmDialog(
+      context,
+      title: t.title,
+      message: t.description,
+      cancelLabel: t.cancel_button,
+      confirmLabel: t.open_settings_button,
+      onCancel: () => Navigator.of(context).pop(),
+      onConfirm: () {
+        Navigator.of(context).pop();
+        openAppSettings();
+      },
+    );
+  }
+}