Merge pull request #14 from headlines-toolkit/refactor_sync_with_new_models_api

Refactor sync with new models api

Author: fulleni

README.md

@@ -17,28 +17,37 @@ management dashboard](https://github.com/headlines-toolkit/ht-dashboard).
 ## ✨ Key Capabilities
 
 *   🔒 **Flexible & Secure Authentication:** Provide seamless user access with
-    a unified system supporting passwordless sign-in, anonymous guest
-    accounts, and a secure, context-aware login flow for privileged dashboard
-    users (e.g., 'admin', 'publisher').
+    a unified system supporting passwordless email sign-in, anonymous guest
+    accounts, and a secure, role-aware login flow for privileged dashboard
+    users.
 
-*   ⚡️ **Flexible Role-Based Access Control (RBAC):** Implement granular
-    permissions with a flexible, multi-role system. Assign multiple roles to
-    users (e.g., 'admin', 'publisher', 'premium_user') to precisely control
-    access to different API features and data management capabilities.
+*   ⚡️ **Granular Role-Based Access Control (RBAC):** Implement precise
+    permissions with a dual-role system (`appRole` for application features,
+    `dashboardRole` for admin functions) to control access to API features
+    and data management capabilities.
 
 *   ⚙️ **Synchronized App Settings:** Ensure a consistent and personalized user
     experience across devices by effortlessly syncing application preferences
     like theme, language, font styles, and more.
 
 *   👤 **Personalized User Preferences:** Enable richer user interactions by
-    managing and syncing user-specific data such as saved headlines, followed sources, or other personalized content tailored to individual users.
+    managing and syncing user-specific data such as saved headlines, followed
+    sources, and followed topics tailored to individual users.
 
 *   💾 **Robust Data Management:** Securely manage core news data (headlines,
-    categories, sources) through a well-structured API that supports flexible
+    topics, sources) through a well-structured API that supports flexible
+    querying and sorting for dynamic content presentation.
+
+*   🌐 **Dynamic Remote Configuration:** Centrally manage application
+    behavior—including ad frequency, feature flags, and maintenance status—without
+    requiring a client-side update.
+
+*   💾 **Robust Data Management:** Securely manage core news data (headlines,
+    topics, sources) through a well-structured API that supports flexible
     querying and sorting for dynamic content presentation.
 
 *   📊 **Dynamic Dashboard Summary:** Access real-time, aggregated metrics on
-    key data points like total headlines, categories, and sources, providing
+    key data points like total headlines, topics, and sources, providing
     an at-a-glance overview for administrative dashboards.
 
 *   🔧 **Solid Technical Foundation:** Built with Dart and the high-performance

lib/src/config/app_dependencies.dart

@@ -38,24 +38,54 @@ class AppDependencies {
   final _completer = Completer<void>();
 
   // --- Repositories ---
+  /// A repository for managing [Headline] data.
   late final HtDataRepository<Headline> headlineRepository;
-  late final HtDataRepository<Category> categoryRepository;
+
+  /// A repository for managing [Topic] data.
+  late final HtDataRepository<Topic> topicRepository;
+
+  /// A repository for managing [Source] data.
   late final HtDataRepository<Source> sourceRepository;
+
+  /// A repository for managing [Country] data.
   late final HtDataRepository<Country> countryRepository;
+
+  /// A repository for managing [User] data.
   late final HtDataRepository<User> userRepository;
+
+  /// A repository for managing [UserAppSettings] data.
   late final HtDataRepository<UserAppSettings> userAppSettingsRepository;
+
+  /// A repository for managing [UserContentPreferences] data.
   late final HtDataRepository<UserContentPreferences>
   userContentPreferencesRepository;
-  late final HtDataRepository<AppConfig> appConfigRepository;
+
+  /// A repository for managing the global [RemoteConfig] data.
+  late final HtDataRepository<RemoteConfig> remoteConfigRepository;
 
   // --- Services ---
+  /// A service for sending emails.
   late final HtEmailRepository emailRepository;
+
+  /// A service for managing a blacklist of invalidated authentication tokens.
   late final TokenBlacklistService tokenBlacklistService;
+
+  /// A service for generating and validating authentication tokens.
   late final AuthTokenService authTokenService;
+
+  /// A service for storing and validating one-time verification codes.
   late final VerificationCodeStorageService verificationCodeStorageService;
+
+  /// A service that orchestrates authentication logic.
   late final AuthService authService;
+
+  /// A service for calculating and providing a summary for the dashboard.
   late final DashboardSummaryService dashboardSummaryService;
+
+  /// A service for checking user permissions.
   late final PermissionService permissionService;
+
+  /// A service for enforcing limits on user content preferences.
   late final UserPreferenceLimitService userPreferenceLimitService;
 
   /// Initializes all application dependencies.
@@ -100,189 +130,107 @@ class AppDependencies {
     headlineRepository = _createRepository(
       connection,
       'headlines',
-      (json) {
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        if (json['published_at'] is DateTime) {
-          json['published_at'] =
-              (json['published_at'] as DateTime).toIso8601String();
-        }
-        return Headline.fromJson(json);
-      },
-      (headline) {
-        final json = headline.toJson();
-        // The database expects source_id and category_id, not nested objects.
-        // We extract the IDs and remove the original objects to match the
-        // schema.
-        if (headline.source != null) {
-          json['source_id'] = headline.source!.id;
-        }
-        if (headline.category != null) {
-          json['category_id'] = headline.category!.id;
-        }
-        json.remove('source');
-        json.remove('category');
-        return json;
-      },
+      // The HtDataPostgresClient returns DateTime objects from TIMESTAMPTZ
+      // columns. The Headline.fromJson factory expects ISO 8601 strings.
+      // This handler converts them before deserialization.
+      (json) => Headline.fromJson(_convertTimestampsToString(json)),
+      (headline) => headline.toJson()
+        ..['source_id'] = headline.source.id
+        ..['topic_id'] = headline.topic.id
+        ..['event_country_id'] = headline.eventCountry.id
+        ..remove('source')
+        ..remove('topic')
+        ..remove('eventCountry'),
     );
-    categoryRepository = _createRepository(
+    topicRepository = _createRepository(
       connection,
-      'categories',
-      (json) {
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        return Category.fromJson(json);
-      },
-      (c) => c.toJson(),
+      'topics',
+      (json) => Topic.fromJson(_convertTimestampsToString(json)),
+      (topic) => topic.toJson(),
     );
     sourceRepository = _createRepository(
       connection,
       'sources',
-      (json) {
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        return Source.fromJson(json);
-      },
-      (source) {
-        final json = source.toJson();
-        // The database expects headquarters_country_id, not a nested object.
-        // We extract the ID and remove the original object to match the
-        // schema.
-        json['headquarters_country_id'] = source.headquarters?.id;
-        json.remove('headquarters');
-        return json;
-      },
+      (json) => Source.fromJson(_convertTimestampsToString(json)),
+      (source) => source.toJson()
+        ..['headquarters_country_id'] = source.headquarters.id
+        ..remove('headquarters'),
     );
     countryRepository = _createRepository(
       connection,
       'countries',
-      (json) {
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        return Country.fromJson(json);
-      },
-      (c) => c.toJson(),
+      (json) => Country.fromJson(_convertTimestampsToString(json)),
+      (country) => country.toJson(),
     );
     userRepository = _createRepository(
       connection,
       'users',
-      (json) {
-        // The postgres driver returns DateTime objects, but the model's
-        // fromJson expects ISO 8601 strings. We must convert them first.
-        if (json['created_at'] is DateTime) {
-          json['created_at'] = (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['last_engagement_shown_at'] is DateTime) {
-          json['last_engagement_shown_at'] =
-              (json['last_engagement_shown_at'] as DateTime).toIso8601String();
-        }
-        return User.fromJson(json);
-      },
+      (json) => User.fromJson(_convertTimestampsToString(json)),
       (user) {
-        // The `roles` field is a List<String>, but the database expects a
-        // JSONB array. We must explicitly encode it.
         final json = user.toJson();
-        json['roles'] = jsonEncode(json['roles']);
+        // Convert enums to their string names for the database.
+        json['app_role'] = user.appRole.name;
+        json['dashboard_role'] = user.dashboardRole.name;
+        // The `feed_action_status` map must be JSON encoded for the JSONB column.
+        json['feed_action_status'] = jsonEncode(json['feed_action_status']);
         return json;
       },
     );
     userAppSettingsRepository = _createRepository(
       connection,
       'user_app_settings',
-      (json) {
-        // The DB has created_at/updated_at, but the model doesn't.
-        // Remove them before deserialization to avoid CheckedFromJsonException.
-        json.remove('created_at');
-        json.remove('updated_at');
-        return UserAppSettings.fromJson(json);
-      },
+      UserAppSettings.fromJson,
       (settings) {
         final json = settings.toJson();
         // These fields are complex objects and must be JSON encoded for the DB.
         json['display_settings'] = jsonEncode(json['display_settings']);
         json['feed_preferences'] = jsonEncode(json['feed_preferences']);
-        json['engagement_shown_counts'] =
-            jsonEncode(json['engagement_shown_counts']);
-        json['engagement_last_shown_timestamps'] =
-            jsonEncode(json['engagement_last_shown_timestamps']);
         return json;
       },
     );
     userContentPreferencesRepository = _createRepository(
       connection,
       'user_content_preferences',
-      (json) {
-        // The postgres driver returns DateTime objects, but the model's
-        // fromJson expects ISO 8601 strings. We must convert them first.
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        return UserContentPreferences.fromJson(json);
-      },
+      UserContentPreferences.fromJson,
       (preferences) {
         final json = preferences.toJson();
-        json['followed_categories'] = jsonEncode(json['followed_categories']);
+        // These fields are lists of complex objects and must be JSON encoded.
+        json['followed_topics'] = jsonEncode(json['followed_topics']);
         json['followed_sources'] = jsonEncode(json['followed_sources']);
         json['followed_countries'] = jsonEncode(json['followed_countries']);
         json['saved_headlines'] = jsonEncode(json['saved_headlines']);
         return json;
       },
     );
-    appConfigRepository = _createRepository(
+    remoteConfigRepository = _createRepository(
       connection,
-      'app_config',
-      (json) {
-        if (json['created_at'] is DateTime) {
-          json['created_at'] =
-              (json['created_at'] as DateTime).toIso8601String();
-        }
-        if (json['updated_at'] is DateTime) {
-          json['updated_at'] =
-              (json['updated_at'] as DateTime).toIso8601String();
-        }
-        return AppConfig.fromJson(json);
+      'remote_config',
+      (json) => RemoteConfig.fromJson(_convertTimestampsToString(json)),
+      (config) {
+        final json = config.toJson();
+        // All nested config objects must be JSON encoded for JSONB columns.
+        json['user_preference_limits'] = jsonEncode(
+          json['user_preference_limits'],
+        );
+        json['ad_config'] = jsonEncode(json['ad_config']);
+        json['account_action_config'] = jsonEncode(
+          json['account_action_config'],
+        );
+        json['app_status'] = jsonEncode(json['app_status']);
+        return json;
       },
-      (c) => c.toJson(),
     );
 
     // 4. Initialize Services.
     emailRepository = const HtEmailRepository(
       emailClient: HtEmailInMemoryClient(),
     );
-    tokenBlacklistService = InMemoryTokenBlacklistService();
+    tokenBlacklistService = InMemoryTokenBlacklistService(log: _log);
     authTokenService = JwtAuthTokenService(
       userRepository: userRepository,
       blacklistService: tokenBlacklistService,
       uuidGenerator: const Uuid(),
+      log: _log,
     );
     verificationCodeStorageService = InMemoryVerificationCodeStorageService();
     authService = AuthService(
@@ -293,15 +241,17 @@ class AppDependencies {
       userAppSettingsRepository: userAppSettingsRepository,
       userContentPreferencesRepository: userContentPreferencesRepository,
       uuidGenerator: const Uuid(),
+      log: _log,
     );
     dashboardSummaryService = DashboardSummaryService(
       headlineRepository: headlineRepository,
-      categoryRepository: categoryRepository,
+      topicRepository: topicRepository,
       sourceRepository: sourceRepository,
     );
     permissionService = const PermissionService();
     userPreferenceLimitService = DefaultUserPreferenceLimitService(
-      appConfigRepository: appConfigRepository,
+      remoteConfigRepository: remoteConfigRepository,
+      log: _log,
     );
   }
 
@@ -321,4 +271,20 @@ class AppDependencies {
       ),
     );
   }
+
+  /// Converts DateTime values in a JSON map to ISO 8601 strings.
+  ///
+  /// The postgres driver returns DateTime objects for TIMESTAMPTZ columns,
+  /// but our models' `fromJson` factories expect ISO 8601 strings. This
+  /// utility function performs the conversion for known timestamp fields.
+  Map<String, dynamic> _convertTimestampsToString(Map<String, dynamic> json) {
+    const timestampKeys = {'created_at', 'updated_at'};
+    final newJson = Map<String, dynamic>.from(json);
+    for (final key in timestampKeys) {
+      if (newJson[key] is DateTime) {
+        newJson[key] = (newJson[key] as DateTime).toIso8601String();
+      }
+    }
+    return newJson;
+  }
 }