kasy-cli 1.2.1

package/templates/firebase/lib/core/states/components/maybe_ask_biometric_setup.dart

@@ -0,0 +1,88 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/components/kasy_button.dart';
+import 'package:kasy_kit/components/kasy_dialog.dart';
+import 'package:kasy_kit/core/data/models/user.dart';
+import 'package:kasy_kit/core/icons/kasy_icons.dart';
+import 'package:kasy_kit/core/security/biometric_preference_notifier.dart';
+import 'package:kasy_kit/core/security/biometric_service.dart';
+import 'package:kasy_kit/core/security/biometric_ui_bundle.dart';
+import 'package:kasy_kit/core/shared_preferences/shared_preferences.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';
+
+class MaybeAskBiometricSetup extends MaybeShowWithRef {
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (event is! OnAppStartEvent) return false;
+    if (kIsWeb) return false;
+
+    final prefs = ref.read(sharedPreferencesProvider);
+    if (prefs.getBiometricPromptShown()) return false;
+    if (prefs.getBiometricEnabled()) return false;
+
+    final user = ref.read(userStateNotifierProvider).user;
+    if (user is! AuthenticatedUserData) return false;
+
+    final service = ref.read(biometricServiceProvider);
+    if (!await service.isAvailable()) return false;
+
+    await Future.delayed(const Duration(milliseconds: 800));
+    if (!ref.context.mounted) return false;
+
+    final platform = Theme.of(ref.context).platform;
+    final slot = await ref.read(biometricCopySlotFamily(platform).future);
+    if (!ref.context.mounted) return false;
+    final bundle = BioBundle.fromSlot(ref.context, slot);
+
+    // ignore: use_build_context_synchronously
+    await _showPrompt(ref.context, ref, bundle);
+    await prefs.setBiometricPromptShown(true);
+    return true;
+  }
+
+  Future<void> _showPrompt(
+    BuildContext context,
+    WidgetRef ref,
+    BioBundle bundle,
+  ) async {
+    await showKasyBlurDialog<void>(
+      context: context,
+      barrierDismissible: false,
+      builder: (dialogContext) => KasyDialog(
+        leadingIcon: KasyIcons.fingerprint,
+        iconTone: KasyDialogIconTone.info,
+        title: bundle.promptTitle,
+        message: bundle.promptMessage,
+        showCloseButton: false,
+        actionsAxis: Axis.horizontal,
+        actions: [
+          KasyButton(
+            label: bundle.notNowLabel,
+            variant: KasyButtonVariant.outline,
+            expand: true,
+            onPressed: () => Navigator.of(dialogContext).pop(),
+          ),
+          KasyButton(
+            label: bundle.enableLabel,
+            expand: true,
+            onPressed: () async {
+              Navigator.of(dialogContext).pop();
+              final service = ref.read(biometricServiceProvider);
+              final authenticated = await service.authenticate(
+                localizedReason: bundle.enableReason,
+              );
+              if (authenticated) {
+                await ref
+                    .read(biometricPreferenceProvider.notifier)
+                    .setEnabled(true);
+              }
+            },
+          ),
+        ],
+      ),
+    );
+  }
+}

package/templates/firebase/lib/core/states/components/maybe_ask_rating.dart

@@ -0,0 +1,49 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/rating/api/rating_api.dart';
+import 'package:kasy_kit/core/rating/widgets/review_popup.dart';
+import 'package:kasy_kit/core/states/components/maybeshow_component.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+import 'package:logger/logger.dart';
+
+/// Directly shows the native rating dialog
+/// Caution : only use this if you are sure the user wants to rate the app
+/// APple API only allows to show the dialog a limited number of times
+class MaybeAskForRating implements MaybeShowWithRef {
+  MaybeAskForRating();
+
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (event is! UserActionEvent) {
+      return false;
+    }
+    if (kDebugMode) {
+      Logger().i("Rating skipped : We skip asking for review in debug mode");
+      return false;
+    }
+    await ref.read(ratingApiProvider).showRatingDialog();
+    return false;
+  }
+}
+
+/// CUstomize this to ask for a specific event for review
+class MaybeAskForReview implements MaybeShowWithRef {
+  MaybeAskForReview();
+
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (event is! UserActionEvent) {
+      return false;
+    }
+    if (kDebugMode) {
+      Logger().i("Review skipped : We skip asking for review in debug mode");
+      return false;
+    }
+    Logger().d("🧐 maybe ask for review ${event.action}");
+    await Future.delayed(const Duration(seconds: 1));
+    if (!ref.context.mounted) {
+      return false;
+    }
+    return showReviewDialog(ref.context, ref);
+  }
+}

package/templates/firebase/lib/core/states/components/maybe_show_update_bottom_sheet.dart

@@ -0,0 +1,86 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/data/models/user.dart';
+import 'package:kasy_kit/core/extensions/date.ext.dart';
+import 'package:kasy_kit/core/shared_preferences/shared_preferences.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/core/widgets/update_bottom_sheet.dart';
+import 'package:logger/logger.dart';
+import 'package:package_info_plus/package_info_plus.dart';
+import 'package:pub_semver/pub_semver.dart';
+
+/// MaybeShow implementation that shows update bottom sheet when app version changes
+class MaybeShowUpdateBottomSheet extends MaybeShowWithRef {
+  @override
+  Future<bool> handle(WidgetRef ref, AppEvent event) async {
+    if (event is! OnAppStartEvent) {
+      return false;
+    }
+    if (kIsWeb) return false;
+
+    final sharedPrefs = ref.read(sharedPreferencesProvider);
+
+    try {
+      final packageInfo = await PackageInfo.fromPlatform();
+      final currentAppVersion = Version.parse(packageInfo.version);
+
+      final lastSeenVersionStr = sharedPrefs.getLastSeenUpdateVersion();
+      final lastSeenVersion = lastSeenVersionStr != null
+          ? Version.parse(lastSeenVersionStr)
+          : null;
+      Logger().d(
+        "👉 currentAppVersion: $currentAppVersion (last seen version: $lastSeenVersion)",
+      );
+
+      // First run on this device (fresh install or reinstall) — just record the
+      // current version as baseline. Never show the sheet without a reference point.
+      if (lastSeenVersion == null) {
+        sharedPrefs.setLastSeenUpdateVersion(currentAppVersion.toString());
+        return false;
+      }
+
+      // Version hasn't changed since last run — nothing to show.
+      if (lastSeenVersion >= currentAppVersion) {
+        return false;
+      }
+
+      // Version increased. Skip for new users (account created today) to avoid
+      // showing "what's new" right after sign-up.
+      final userState = ref.watch(userStateNotifierProvider);
+      final userCreationDate = switch (userState.user) {
+        AuthenticatedUserData(:final creationDate) => creationDate,
+        AnonymousUserData(:final creationDate) => creationDate,
+        _ => null,
+      };
+
+      if (userCreationDate == null ||
+          userCreationDate.isSameDay(DateTime.now())) {
+        return false;
+      }
+
+      if (ref.context.mounted) {
+        sharedPrefs.setLastSeenUpdateVersion(currentAppVersion.toString());
+        // ignore: use_build_context_synchronously
+        await _showUpdateSheet(ref.context, currentAppVersion.toString());
+        return true;
+      }
+
+      return false;
+    } catch (e) {
+      // If there's an error getting version info, don't show the sheet
+      return false;
+    }
+  }
+
+  Future<void> _showUpdateSheet(BuildContext context, String version) async {
+    // Small delay to ensure the home page is fully loaded
+    await Future.delayed(const Duration(milliseconds: 500));
+
+    if (!context.mounted) return;
+
+    await showUpdateBottomSheet(context: context, version: version);
+  }
+}

package/templates/firebase/lib/core/states/components/maybeshow_component.dart

@@ -0,0 +1,110 @@
+import 'dart:async';
+
+import 'package:flutter/cupertino.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/states/events_dispatcher.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+
+/// A component that can show widgets conditionally based on events.
+/// THe first widget that returns true for its condition will be shown.
+/// Other will be ignored.
+/// This can be used to show modals, bottom sheets, pages, etc based on events.
+///
+/// Ex of usage:
+/// @override
+///  Widget build(BuildContext context) {
+///    final homeState = ref.watch(homeNotifierProvider);
+///    final userState = ref.watch(userStateNotifierProvider);
+///    // final translations = ref.watch(translationsProvider);
+///
+///    return ConditionalWidgetsEvents(
+///      eventWidgets: [
+///        MaybeShowPremiumPage(),
+///        MaybeShowNotificationPermission(),
+///        MaybeLevelUpBottomSheet(),
+///        MaybeAskForReview(),
+///        MaybeAskForRating(),
+///      ],
+///      child: Background.blue(
+///        child: SafeArea(...
+/// A widget that can be shown or not based on a condition.
+sealed class MaybeShow {}
+
+/// A widget that can be shown or not based on a condition.
+abstract class MaybeShowNoContext extends MaybeShow {
+  Future<bool> handle(AppEvent event);
+}
+
+/// A widget that can be shown or not based on a condition.
+abstract class MaybeShowWithContext extends MaybeShow {
+  Future<bool> handle(BuildContext context, AppEvent event);
+}
+
+abstract class MaybeShowWithRef extends MaybeShow {
+  Future<bool> handle(WidgetRef ref, AppEvent event);
+}
+
+/// Orchestrates a list of [MaybeShowWidget] and stops at the first one that
+class ConditionnalWidgetOrchestrator {
+  final List<MaybeShow> widgets;
+
+  ConditionnalWidgetOrchestrator(this.widgets);
+
+  Future<void> handle(WidgetRef ref, AppEvent event) async {
+    for (final widget in widgets) {
+      final shown = await switch (widget) {
+        MaybeShowNoContext() => widget.handle(event),
+        MaybeShowWithContext() => widget.handle(ref.context, event),
+        MaybeShowWithRef() => widget.handle(ref, event),
+      };
+      if (shown) {
+        return;
+      }
+    }
+  }
+}
+
+/// A wrapper
+class ConditionalWidgetsEvents extends ConsumerStatefulWidget {
+  final Widget child;
+  final List<MaybeShow> eventWidgets;
+
+  const ConditionalWidgetsEvents({
+    super.key,
+    required this.child,
+    required this.eventWidgets,
+  });
+
+  @override
+  ConsumerState<ConsumerStatefulWidget> createState() =>
+      _ConditionalWidgetsEventsState();
+}
+
+class _ConditionalWidgetsEventsState
+    extends ConsumerState<ConditionalWidgetsEvents> {
+  ConditionnalWidgetOrchestrator? orchestrator;
+  StreamSubscription<AppEvent?>? subscription;
+
+  @override
+  void initState() {
+    super.initState();
+    orchestrator = ConditionnalWidgetOrchestrator(widget.eventWidgets);
+    subscription = ref.appEventsDispatcher.stream.listen(_onEvent);
+  }
+
+  Future<void> _onEvent(AppEvent? event) async {
+    if (event == null) return;
+    await orchestrator?.handle(ref, event);
+  }
+
+  @override
+  void dispose() {
+    super.dispose();
+    subscription?.cancel();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return widget.child;
+  }
+}

package/templates/firebase/lib/core/states/events_dispatcher.dart

@@ -0,0 +1,103 @@
+import 'dart:async';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/core/states/models/event_model.dart';
+
+final appEventsDispatcherProvider = Provider((ref) => AppEventsDispatcher());
+
+/// Dispatches and manages app-wide events using a broadcast stream.
+///
+/// Features:
+/// - Type-safe event publishing and listening
+/// - Event history buffer for late subscribers
+/// - Typed event filtering with [on<T>()]
+class AppEventsDispatcher {
+  final StreamController<AppEvent> _controller;
+  late final Stream<AppEvent> _stream;
+
+  /// Buffer for recent events (useful for late subscribers)
+  final List<AppEvent> _eventHistory;
+  final int _maxHistorySize;
+
+  Stream<AppEvent> get stream => _stream;
+
+  /// Get all events from history (read-only)
+  List<AppEvent> get history => List.unmodifiable(_eventHistory);
+
+  AppEventsDispatcher({int maxHistorySize = 50})
+    : _eventHistory = [],
+      _maxHistorySize = maxHistorySize,
+      _controller = StreamController<AppEvent>() {
+    _stream = _controller.stream.asBroadcastStream(
+      onCancel: (c) => c.pause(),
+      onListen: (el) {
+        if (el.isPaused) el.resume();
+      },
+    );
+  }
+
+  void dispose() {
+    _eventHistory.clear();
+    _controller.close();
+  }
+
+  /// Publish an event to all listeners
+  void publish(AppEvent event) {
+    _addToHistory(event);
+    _controller.add(event);
+  }
+
+  void _addToHistory(AppEvent event) {
+    _eventHistory.add(event);
+    if (_eventHistory.length > _maxHistorySize) {
+      _eventHistory.removeAt(0);
+    }
+  }
+
+  /// Listen to only a specific type of event
+  Stream<T> on<T extends AppEvent>() {
+    return _stream.where((event) => event is T).cast<T>();
+  }
+
+  /// Get the last event of a specific type from history
+  T? lastEventOf<T extends AppEvent>() {
+    for (var i = _eventHistory.length - 1; i >= 0; i--) {
+      if (_eventHistory[i] is T) return _eventHistory[i] as T;
+    }
+    return null;
+  }
+
+  /// Get all events of a specific type from history
+  List<T> eventsOf<T extends AppEvent>() {
+    return _eventHistory.whereType<T>().toList();
+  }
+}
+
+extension AppEventsDispatcherExtension on WidgetRef {
+  AppEventsDispatcher get appEventsDispatcher =>
+      read(appEventsDispatcherProvider);
+
+  void publishAppEvent(AppEvent event) {
+    if (!context.mounted) return;
+    read(appEventsDispatcherProvider).publish(event);
+  }
+
+  /// Listen to specific event type
+  Stream<T> onAppEvent<T extends AppEvent>() {
+    return read(appEventsDispatcherProvider).on<T>();
+  }
+}
+
+extension AppEventDispatcherRefExtension on Ref {
+  AppEventsDispatcher get appEventsDispatcher =>
+      read(appEventsDispatcherProvider);
+
+  void publishAppEvent(AppEvent event) {
+    read(appEventsDispatcherProvider).publish(event);
+  }
+
+  /// Listen to specific event type
+  Stream<T> onAppEvent<T extends AppEvent>() {
+    return read(appEventsDispatcherProvider).on<T>();
+  }
+}

package/templates/firebase/lib/core/states/models/event_model.dart

@@ -0,0 +1,118 @@
+import 'package:flutter/foundation.dart';
+
+/// Base sealed class for all app events
+sealed class AppEvent {
+  /// Unique identifier for the event
+  final String id;
+
+  /// Timestamp when the event was created
+  final DateTime timestamp;
+
+  /// Optional payload data
+  final Map<String, dynamic>? metadata;
+
+  const AppEvent({required this.id, required this.timestamp, this.metadata});
+
+  /// Factory to create event with auto-generated id and timestamp
+  static T create<T extends AppEvent>(
+    T Function(String id, DateTime timestamp) factory,
+  ) {
+    return factory(UniqueKey().toString(), DateTime.now());
+  }
+}
+
+/// Navigation event for route changes
+final class NavigationEvent extends AppEvent {
+  final String route;
+  final Map<String, dynamic>? arguments;
+
+  const NavigationEvent({
+    required super.id,
+    required super.timestamp,
+    required this.route,
+    this.arguments,
+    super.metadata,
+  });
+
+  @override
+  String toString() => 'NavigationEvent(route: $route, arguments: $arguments)';
+
+  factory NavigationEvent.create(
+    String route, {
+    Map<String, dynamic>? arguments,
+  }) => AppEvent.create<NavigationEvent>(
+    (id, timestamp) => NavigationEvent(
+      id: id,
+      timestamp: timestamp,
+      route: route,
+      arguments: arguments,
+    ),
+  );
+}
+
+/// User action event for tracking user interactions
+final class UserActionEvent extends AppEvent {
+  final String action;
+  final String? target;
+
+  const UserActionEvent({
+    required super.id,
+    required super.timestamp,
+    required this.action,
+    this.target,
+    super.metadata,
+  });
+
+  factory UserActionEvent.create(String action, {String? target}) =>
+      AppEvent.create<UserActionEvent>(
+        (id, timestamp) => UserActionEvent(
+          id: id,
+          timestamp: timestamp,
+          action: action,
+          target: target,
+        ),
+      );
+}
+
+/// Event for app-wide start handling
+final class OnAppStartEvent extends AppEvent {
+
+  const OnAppStartEvent({
+    required super.id,
+    required super.timestamp,
+    super.metadata,
+  });
+
+  factory OnAppStartEvent.create() =>
+      AppEvent.create<OnAppStartEvent>(
+        (id, timestamp) => OnAppStartEvent(
+          id: id,
+          timestamp: timestamp,
+        ),
+      );
+}
+
+
+/// Error event for app-wide error handling
+final class ErrorEvent extends AppEvent {
+  final Object error;
+  final StackTrace? stackTrace;
+
+  const ErrorEvent({
+    required super.id,
+    required super.timestamp,
+    required this.error,
+    this.stackTrace,
+    super.metadata,
+  });
+
+  factory ErrorEvent.create(Object error, {StackTrace? stackTrace}) =>
+      AppEvent.create<ErrorEvent>(
+        (id, timestamp) => ErrorEvent(
+          id: id,
+          timestamp: timestamp,
+          error: error,
+          stackTrace: stackTrace,
+        ),
+      );
+}

package/templates/firebase/lib/core/states/models/user_state.dart

@@ -0,0 +1,22 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:kasy_kit/core/data/models/subscription.dart';
+import 'package:kasy_kit/core/data/models/user.dart';
+
+part 'user_state.freezed.dart';
+
+@freezed
+sealed class UserState with _$UserState {
+  const factory UserState({
+    required User user,
+  }) = UserStateData;
+
+  const UserState._();
+
+  /// The subscription will be null if we don't use the Subscrption module
+  /// Or the user is not loaded
+  Subscription? get subscription => switch(user) {
+    AuthenticatedUserData(:final subscription) => subscription,
+    AnonymousUserData(:final subscription) => subscription,
+    _ => null,
+  };
+}

package/templates/firebase/lib/core/states/notifications_dispatcher.dart

@@ -0,0 +1,81 @@
+import 'dart:async';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/features/notifications/providers/models/notification.dart';
+
+final notificationDipatcherProvider = Provider<NotificationDispatcher>((ref) {
+  final dispatcher = NotificationDispatcher();
+  ref.onDispose(() => dispatcher.dispose());
+  return dispatcher;
+});
+
+/// Use this when you want to publish a notification inside the app
+final notificationPublisherProvider = Provider<NotificationPublisher>((ref) {
+  return ref.watch(notificationDipatcherProvider);
+});
+
+/// use this if you want to listen to notifications anywhere in the app
+final notificationSubscriberProvider = Provider<NotificationSubscriber>((ref) {
+  return ref.watch(notificationDipatcherProvider);
+});
+
+abstract class NotificationPublisher {
+  void publish(Notification notification);
+}
+
+typedef OnNotificationEvent = void Function(Notification notification);
+
+abstract class NotificationSubscriber {
+  void subscribe(OnNotificationEvent onNotificationEvent);
+
+  void unsubscribe(OnNotificationEvent onNotificationEvent);
+}
+
+/// This class is responsible for dispatching notifications to the app
+/// It is also responsible for listening to notifications
+class NotificationDispatcher
+    implements NotificationPublisher, NotificationSubscriber {
+  final StreamController<Notification> _controller;
+  late final Stream<Notification> _stream;
+
+  Stream<Notification> get stream => _stream;
+
+  final List<OnNotificationEvent> _onNotificationEventsSubscriber;
+
+  NotificationDispatcher()
+      : _onNotificationEventsSubscriber = [],
+        _controller = StreamController() {
+    _stream = _controller.stream.asBroadcastStream();
+    start();
+  }
+
+  void start() {
+    stream.listen((event) async {
+      // You can also check the notification type and do something specific
+      for (final subscriber in _onNotificationEventsSubscriber) {
+        subscriber(event);
+      }
+      await event.show();
+    });
+  }
+
+  void dispose() {
+    _onNotificationEventsSubscriber.clear();
+    _controller.close();
+  }
+
+  @override
+  void unsubscribe(OnNotificationEvent subscriber) {
+    _onNotificationEventsSubscriber.remove(subscriber);
+  }
+
+  @override
+  void publish(Notification event) {
+    _controller.add(event);
+  }
+
+  @override
+  void subscribe(OnNotificationEvent onNotificationEvent) {
+    _onNotificationEventsSubscriber.add(onNotificationEvent);
+  }
+}

package/templates/firebase/lib/core/states/translations.dart

@@ -0,0 +1,11 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:kasy_kit/i18n/translations.g.dart';
+
+final translationsProvider = Provider<Translations>((ref) {
+  final current = LocaleSettings.currentLocale.translations;
+  return current;
+});
+
+final localeProvider = Provider<AppLocale>(
+  (ref) => LocaleSettings.currentLocale,
+);