Feat/define shared notification models

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Upcoming
 
+- **feat**: add models/fixtures/tests for push notification system.
 - **BREAKING** feat!: Deprecate and remove `LocalAd` model and related fixtures.
 - **feat**: Add 10 new user fixtures, including publishers and standard users.
 - **chore**: Expand user-related fixtures with detailed settings and preferences.

README.md

@@ -5,60 +5,191 @@
 </div>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/coverage-99%25-green?style=for-the-badge" alt="coverage">
+  <img src="https://img.shields.io/badge/coverage-98%25-green?style=for-the-badge" alt="coverage">
   <a href="https://flutter-news-app-full-source-code.github.io/docs/"><img src="https://img.shields.io/badge/LIVE_DOCS-VIEW-slategray?style=for-the-badge" alt="Live Docs: View"></a>
   <a href="https://github.com/flutter-news-app-full-source-code"><img src="https://img.shields.io/badge/MAIN_PROJECT-BROWSE-purple?style=for-the-badge" alt="Main Project: Browse"></a>
 </p>
 
-This `core` package serves as the foundational shared library for the [**Flutter News App Full Source Code Toolkit**](https://github.com/flutter-news-app-full-source-code). It defines the common language and data structures—including models for news content, user data, and remote configurations—that ensure consistency and accelerate development across the Flutter mobile app, web dashboard, and Dart Frog backend API.
+This `core` package serves as the foundational shared library for the **Flutter News App Full Source Code Toolkit**. It defines the common language and data structures—including models for news content, user data, and remote configurations—that ensure consistency and accelerate development across the Flutter mobile app, web dashboard, and Dart Frog backend API.
 
 ## ⭐ Feature Showcase: The Foundation for a Robust News Platform
 
 This package provides the critical building blocks for a professional news application ecosystem.
 
 <details>
-<summary><strong>🧱 Unified Data Models</strong></summary>
+<summary><strong>🏗️ Foundational Data Architecture</strong></summary>
 
-### 📰 News & Content Entities
-- **`Headline`, `Topic`, `Source`, `Country`, `Language`:** Comprehensive models for all core news content, ensuring consistent representation across the entire toolkit.
-- **`FeedItem`:** An abstract base class for all items that can appear in a mixed content feed, supporting diverse content types like headlines, ads, and suggested content.
+---
 
-### 🔐 User & Authentication Data
-- **`User`, `AppUserRole`, `DashboardUserRole`, `Permission`:** Robust models for user profiles, roles, and permissions, enabling secure and personalized experiences.
-- **`UserContentPreferences`, `UserAppSettings`:** Detailed models for storing user-specific content preferences (e.g., followed topics, saved headlines) and application settings (e.g., theme, language).
+### 📰 Core Content Entities
 
-### 💾 User Presets
-- **`SavedFilter`:** A model for storing user-defined filter combinations.
+Provides comprehensive models for all core news content, ensuring consistent representation across the entire toolkit.
 
-### ⚙️ Application Configuration
-- **`RemoteConfig`:** A central container for all dynamic application settings, fetched from a remote source. This includes:
-    - **`AdConfig`:** Master configuration for all advertising, now featuring **highly flexible, role-based control** over ad visibility and frequency for feed, article, and interstitial ads. This allows for granular control over monetization strategies per user segment.
-    - **`UserPreferenceConfig`:** Defines user preference limits (e.g., max followed items, saved headlines) tiered by user role.
-    - **`AppStatus`:** Manages application-wide status, including maintenance mode and force update directives.
-    - **`FeedDecoratorConfig`:** Configures dynamic in-feed elements like calls-to-action and content collections, with role-based visibility.
+> **Your Advantage:** A unified and robust data schema that simplifies content management and ensures data integrity across all applications.
 
-### 📊 Dashboard & Analytics
-- **`DashboardSummary`:** Provides a model for aggregated statistics, useful for administrative dashboards.
+---
 
-### 🔍 Querying & API Communication
-- **`SortOption`, `PaginationOptions`:** Models for building flexible, server-side queries with sorting and pagination capabilities.
-- **`PaginatedResponse`, `SuccessApiResponse`:** Standardized response wrappers for consistent API communication.
-- **`HttpException` Hierarchy:** A comprehensive set of custom exceptions for predictable and standardized error handling across all layers of the application.
+### 🔄 Polymorphic Feed Items
 
-> **💡 Your Advantage:** You get a meticulously designed, production-quality data layer that forms the backbone of a scalable news platform. This package eliminates the need to define core data structures from scratch, saving months of development time and ensuring architectural consistency.
+Enables diverse content types (headlines, ads, suggested content) to coexist seamlessly within a single feed.
+
+> **Your Advantage:** Flexible feed construction that supports rich, mixed-content experiences without complex type handling.
+
+---
+
+### 📊 Querying & API Communication
+
+Offers models for building flexible, server-side queries with sorting and pagination capabilities.
+
+> **Your Advantage:** Efficient data retrieval and reduced backend load through optimized query parameters.
+
+---
+
+### ✅ Standardized API Responses
+
+Ensures consistent response wrappers for all API communication, guaranteeing predictable data structures.
+
+> **Your Advantage:** Simplified API client development and robust error handling due to a uniform response format.
+
+---
+
+### 🚨 Predictable Error Handling
+
+Includes a comprehensive set of custom exceptions for predictable and standardized error handling across all layers of the application.
+
+> **Your Advantage:** Clear, actionable error messages that streamline debugging and improve application stability.
+
+---
+
+### 📈 Dashboard Analytics Summary
+
+Provides a model for aggregated statistics, useful for administrative dashboards.
+
+> **Your Advantage:** Quick and easy access to key performance indicators for administrative oversight.
+
+</details>
+
+<details>
+<summary><strong>👤 User Identity & Personalization</strong></summary>
+
+---
+
+### 🔐 Secure User Management
+
+Offers robust models for user profiles, roles, and permissions, enabling secure and personalized experiences.
+
+> **Your Advantage:** A secure and flexible user authentication and authorization system that supports tiered access and custom permissions.
+
+---
+
+### ⚙️ User-Specific Settings
+
+Provides detailed models for storing user-specific content preferences (e.g., followed topics, saved headlines) and application settings (e.g., theme, language).
+
+> **Your Advantage:** Highly personalized user experiences through persistent storage of individual content interests and application configurations.
+
+---
+
+### 💾 Reusable Content Filters
+
+Enables users to store and quickly re-apply complex content filters.
+
+> **Your Advantage:** Enhanced user engagement and efficiency by enabling quick access to frequently used content filters.
+
+</details>
+
+<details>
+<summary><strong>🔔 Dynamic Push Notifications</strong></summary>
+
+---
+
+### 📩 User-Defined Subscriptions
+
+Allows users to create and manage their notification subscriptions, offering granular control over alert preferences.
+
+> **Your Advantage:** Empower users with precise control over the notifications they receive, reducing noise and increasing relevance.
+
+---
+
+### 📱 Device Registration & Management
+
+Manages user device registrations for push notifications, linking user accounts to specific device tokens.
+
+> **Your Advantage:** Reliable and targeted delivery of notifications to the correct user devices across different platforms.
+
+---
+
+### ✉️ Standardized Notification Payloads
+
+Defines a generic structure for push notification messages, ensuring consistent content delivery across various providers.
+
+> **Your Advantage:** Simplified development of notification sending logic with a clear, consistent payload structure for all alerts.
+
+---
+
+### 🌐 Global Push System Configuration
+
+Provides centralized management for the entire push notification system, including provider credentials and feature availability.
+
+> **Your Advantage:** Centralized control over your push notification infrastructure, allowing for dynamic adjustments and provider switching without code changes.
 
 </details>
 
 <details>
-<summary><strong>🧪 Sample Data & Fixtures</strong></summary>
+<summary><strong>⚙️ Remote Configuration & Monetization</strong></summary>
+
+---
+
+### ☁️ Centralized App Control
+
+Offers a central container for all dynamic application settings, fetched from a remote source, enabling real-time adjustments to app behavior.
+
+> **Your Advantage:** Agility in managing application features and behavior without requiring app store updates.
+
+---
+
+### 💰 Flexible Ad Monetization
+
+Provides master configuration for all advertising, featuring **highly flexible, role-based control** over ad visibility and frequency for various ad types.
+
+> **Your Advantage:** Granular control over monetization strategies, allowing optimization of ad revenue and user experience per user segment.
+
+---
+
+### 🎯 Tiered User Feature Limits
+
+Defines user preference limits (e.g., max followed items, saved headlines) tiered by user role.
+
+> **Your Advantage:** Effective feature differentiation across user tiers (guest, standard, premium) and robust backend enforcement of limits.
+
+---
+
+### 🚧 Application Status Management
+
+Manages application-wide status, including maintenance mode and force update directives.
+
+> **Your Advantage:** Proactive communication with users during maintenance and seamless enforcement of critical updates.
+
+---
+
+### 🎨 Dynamic In-Feed Elements
+
+Configures dynamic in-feed elements like calls-to-action and content collections, with role-based visibility.
+
+> **Your Advantage:** Enhanced user engagement and promotional capabilities through dynamically injected content within the news feed.
+
+</details>
+
+<details>
+<summary><strong>🧪 Development & Testing Accelerators</strong></summary>
+
+---
 
-To further accelerate development and provide immediate demonstration capabilities, `core` includes a set of **pre-defined, in-memory fixture data** for core models like `Headline`, `Topic`, `Source`, `Country`, and `RemoteConfig`. These fixtures are directly embedded as Dart constants, enabling:
+### ⚡ Ready-to-Use Sample Data
 
-*   **⚡ Instant Setup:** Quickly initialize in-memory data stores for testing or local development without needing a backend.
-*   **🧪 Reliable Testing:** Use consistent, realistic data for unit and integration tests.
-*   **🚀 Rapid Prototyping:** Jumpstart UI development and feature implementation with readily available sample content.
+Includes a set of pre-defined, in-memory fixture data for core models, facilitating rapid development and testing.
 
-> **💡 Your Advantage:** Leverage ready-to-use sample data for rapid prototyping, reliable testing, and instant setup of development environments, significantly accelerating your workflow.
+> **Your Advantage:** Rapid prototyping, reliable testing, and instant setup of development environments, significantly accelerating your workflow.
 
 </details>
 

lib/src/enums/device_platform.dart

@@ -0,0 +1,10 @@
+/// {@template device_platform}
+/// Identifies the mobile operating system of a user's device.
+/// {@endtemplate}
+enum DevicePlatform {
+  /// Apple iOS.
+  ios,
+
+  /// Google Android.
+  android,
+}

lib/src/enums/enums.dart

@@ -9,10 +9,13 @@ export 'banner_ad_shape.dart';
 export 'content_status.dart';
 export 'content_type.dart';
 export 'dashboard_user_role.dart';
+export 'device_platform.dart';
 export 'feed_decorator_category.dart';
 export 'feed_decorator_type.dart';
 export 'headline_density.dart';
 export 'headline_image_style.dart';
 export 'in_article_ad_slot_type.dart';
+export 'push_notification_provider.dart';
+export 'push_notification_subscription_delivery_type.dart';
 export 'sort_order.dart';
 export 'source_type.dart';

lib/src/enums/push_notification_provider.dart

@@ -0,0 +1,14 @@
+/// {@template push_notification_provider}
+/// Defines the available push notification service providers.
+///
+/// This allows the backend to select the appropriate client for sending a
+/// notification and allows devices to register themselves with the provider
+/// they are configured to use.
+/// {@endtemplate}
+enum PushNotificationProvider {
+  /// Firebase Cloud Messaging.
+  firebase,
+
+  /// OneSignal.
+  oneSignal,
+}

lib/src/enums/push_notification_subscription_delivery_type.dart

@@ -0,0 +1,19 @@
+/// {@template push_notification_subscription_delivery_type}
+/// Defines the types of notifications a user can receive for a subscription.
+///
+/// A user can opt into multiple delivery types for a single notification
+/// subscription, allowing for flexible alert configurations.
+/// {@endtemplate}
+enum PushNotificationSubscriptionDeliveryType {
+  /// Delivers a notification immediately only when a matching headline is
+  /// editorially marked as "breaking news".
+  breakingOnly,
+
+  /// Delivers a single, AI-powered summary of all matching headlines from the
+  /// past day, sent at a scheduled time.
+  dailyDigest,
+
+  /// Delivers a single, AI-powered summary of all matching headlines from the
+  /// past week, sent on a recurring day.
+  weeklyRoundup,
+}