docs: update README with project overview

- Updated description and purpose
- Added key models documentation
- Added getting started instructions

Author: fulleni

README.md

@@ -1,149 +1,60 @@
-# ht_shared
+# 🛠️ ht_shared
 
 ![coverage: percentage](https://img.shields.io/badge/coverage-94-green)
 [![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis)
 [![License: PolyForm Free Trial](https://img.shields.io/badge/License-PolyForm%20Free%20Trial-blue)](https://polyformproject.org/licenses/free-trial/1.0.0)
 
-A shared Dart package containing core data models for news-related entities (like headlines, sources, categories, countries), pagination, standardized API response structures, **user content preferences**, and **application configuration**, used across the application ecosystem (Mobile App, Backend API, Web Dashboard).
-
-## Getting Started
-
-To use this package, add `ht_shared` as a dependency in your `pubspec.yaml` file.
-
-```yaml
-dependencies:
-  ht_shared:
-    git:
-      url: https://github.com/headlines-toolkit/ht-shared.git
-```
-
-Then, run `flutter pub get` or `dart pub get`.
-
-## Features
-
-This package provides the following core data models:
-
-*   **`Headline`**: Represents a news headline article, including ID, title, description, URLs, publication date, and optional associated `Source` and `Category`.
-*   **`Category`**: Represents a news category with an ID, name, and optional description and icon URL.
-*   **`Source`**: Represents a news source, including ID, name, description, URL, language, optional headquarters (`Country`), and a `SourceType` enum (e.g., `newsAgency`, `blog`).
-*   **`Country`**: Represents a country with an ID, ISO code, name, and flag URL.
-*   **`UserContentPreferences`**: Represents a collection of user-specific content preferences, including followed countries, sources, categories, and saved headlines. This model stores full objects for these items and is subject to tiered limits based on user role.
-*   **`AppConfig`**: Represents the overall application configuration. This model serves as a central container for various configuration settings, including user preference limits, and is designed to be fetched and managed via the `HtDataClient`.
-*   **`UserPreferenceLimits`**: Defines the maximum number of items a user can follow or save, tiered by user role (Guest, Authenticated, Premium). This model is part of the `AppConfig` and is used for backend enforcement and client-side UI/UX.
-*   **`UserAppSettings`**: Represents a collection of user-specific application settings, unifying display preferences (`DisplaySettings`) and language selection (`AppLanguage`). This model is designed for management via a generic data client (`HtDataClient`).
-*   **`User`**: Represents a user within the system, including their assigned `role`.
-*   **`PaginatedResponse<T>`**: A generic class for handling paginated API responses, containing a list of items (`items`), a `cursor` for the next page, and a `hasMore` flag.
-*   **`AuthSuccessResponse`**: Represents the successful result of an authentication operation, typically containing the authenticated user details and an access token.
-*   **`SuccessApiResponse<T>`**: A generic wrapper for successful API responses, containing the main `data` payload (of type `T`) and optional `ResponseMetadata`.
-*   **`ResponseMetadata`**: Contains optional metadata for API responses, such as a `requestId` and `timestamp`.
-*   **`HtHttpException` Hierarchy**: A standardized set of exception classes (`NetworkException`, `BadRequestException`, `AuthenticationException`, `InvalidInputException`, `NotFoundException`, `OperationFailedException`, `ConflictException`, etc.) intended to be used by data client implementations to provide a consistent error contract. See the documentation within `ht_http_exception.dart` and individual exception files for detailed usage patterns.
-
-## Usage
-
-Import the models barrel file (`package:ht_shared/ht_shared.dart`) and use the classes as needed.
-
-```dart
-import 'package:ht_shared/ht_shared.dart';
-
-void main() {
-  // Example: Creating a Source and a Headline
-  final source = Source(
-    id: 'tech-crunch',
-    name: 'TechCrunch',
-    type: SourceType.specializedPublisher,
-    url: 'https://techcrunch.com/',
-  );
-
-  final headline = Headline(
-    id: 'headline-1', // Added ID for clarity in preferences example
-    title: 'New Gadget Announced',
-    description: 'A revolutionary new device changes everything.',
-    url: 'https://techcrunch.com/news/new-gadget',
-    publishedAt: DateTime.now().subtract(const Duration(hours: 1)),
-    source: source,
-    category: Category(id: 'tech', name: 'Technology'),
-  );
-
-  print('Headline: ${headline.title} from ${headline.source?.name}');
-
-  // Example: Creating User Content Preferences
-  final userPreferences = UserContentPreferences(
-    id: 'user-abc',
-    followedCountries: [
-      Country(id: 'us', isoCode: 'US', name: 'United States', flagUrl: '...'),
-      Country(id: 'gb', isoCode: 'GB', name: 'United Kingdom', flagUrl: '...'),
-    ],
-    followedSources: [
-      source, // Using the source created above
-      Source(id: 'bbc', name: 'BBC News', type: SourceType.nationalNewsOutlet),
-    ],
-    followedCategories: [
-      Category(id: 'sports', name: 'Sports'),
-      Category(id: 'business', name: 'Business'),
-    ],
-    savedHeadlines: [
-      headline, // Saving the headline created above
-      Headline(id: 'headline-2', title: 'Another Saved Article'),
-    ],
-  );
-
-  print('\nUser ${userPreferences.id} follows ${userPreferences.followedSources.length} sources.');
-  print('User ${userPreferences.id} has ${userPreferences.savedHeadlines.length} saved headlines.');
-
-  // Example: Accessing Application Configuration and User Preference Limits
-  const appConfig = AppConfig(
-    id: 'app_config',
-    userPreferenceLimits: UserPreferenceLimits(
-      guestFollowedItemsLimit: 5,
-      guestSavedHeadlinesLimit: 10,
-      authenticatedFollowedItemsLimit: 15,
-      authenticatedSavedHeadlinesLimit: 30,
-      premiumFollowedItemsLimit: 30,
-      premiumSavedHeadlinesLimit: 100,
-    ),
-  );
-
-  print('\nApp Config ID: ${appConfig.id}');
-  print('Premium user saved headlines limit: ${appConfig.userPreferenceLimits.premiumSavedHeadlinesLimit}');
-
-  // Example: Representing a paginated response of Headlines
-
-  // Example: Representing a paginated response of Headlines
-  final response = PaginatedResponse<Headline>(
-    items: [headline],
-    cursor: 'nextPageToken123',
-    hasMore: true,
-  );
-
-  print('Fetched ${response.items.length} headlines. More available: ${response.hasMore}');
-
-  // Example: Wrapping a response in SuccessApiResponse
-  final apiResponse = SuccessApiResponse<PaginatedResponse<Headline>>(
-    data: response,
-    metadata: ResponseMetadata(
-      requestId: 'req-abc-123',
-      timestamp: DateTime.now(),
-    ),
-  );
-
-  print('API Response Request ID: ${apiResponse.metadata?.requestId}');
-  print('API Response Data Type: ${apiResponse.data.runtimeType}');
-
-  // Example: Catching a shared exception
-  try {
-    // Simulate an operation that might throw
-    throw NotFoundException("Item '123' could not be located.");
-  } on HtHttpException catch (e) {
-    // Handle any standard HT exception
-    print('Caught standard exception: $e');
-  } catch (e) {
-    // Handle other unexpected errors
-    print('Caught unexpected error: $e');
-  }
-}
-
-```
-
-## License
-
-This package is licensed under the [PolyForm Free Trial](LICENSE). Please review the terms before use.
+The essential shared Dart package providing the **Core Data Models** for the **Headlines Toolkit**. `ht_shared` ensures data consistency and accelerates development across our Flutter mobile app, web dashboard, and Dart Frog backend API.
+
+Think of it as the common language 🗣️ that all parts of your news application will speak!
+
+## ✨ Why `ht_shared` Matters
+
+*   **🧱 Unified Data Structure:** Guarantees that your `Headline`, `Source`, `User`, `FeedItem`, and configuration data are handled identically across the entire Headlines Toolkit.
+*   **🚀 Rapid Development:** Start building features faster with pre-defined, robust models for common news application needs. No reinventing the wheel!
+*   **🔗 Seamless Integration:** Enables the Flutter mobile app, web dashboard, and Dart Frog API to work together flawlessly.
+*   **🎯 Consistency by Design:** Reduces errors and simplifies maintenance by providing a single source of truth for core data definitions.
+*   **🌟 Foundation for Rich Features:** Includes models for user personalization (preferences, settings), dynamic feeds, and standardized API responses.
+
+## 🎁 Key Models Provided
+
+This package includes well-defined Dart classes for:
+
+*   📰 **News Content:** `Headline`, `Category`, `Source`, `Country`
+*   🧩 **Feed System:** `FeedItem` (and its subtypes like `Ad`, `SuggestedContent`, `EngagementContent`), `FeedItemAction`
+*   👤 **User Data:** `User`, `UserContentPreferences`, `UserPreferenceLimits`, `UserAppSettings`
+*   ⚙️ **Application Configuration:** `AppConfig`
+*   📡 **API Communication:** `PaginatedResponse`, `SuccessApiResponse`, and a comprehensive `HtHttpException` hierarchy for standardized error handling.
+
+## 🔑 Access and Licensing
+
+`ht_shared` is source-available as part of the Headlines Toolkit ecosystem.
+
+The source code for `ht_shared` is available for review as part of the Headlines
+Toolkit ecosystem. To acquire a commercial license for building unlimited news
+applications with the Headlines Toolkit repositories, please visit the
+[Headlines Toolkit GitHub organization page](https://github.com/headlines-toolkit)
+for more details.
+
+## 🚀 Getting Started 
+
+To integrate `ht_shared` into a Headlines Toolkit component (or your custom Dart/Flutter project):
+
+1.  Add `ht_shared` as a dependency in your `pubspec.yaml` file:
+
+    ```yaml
+    dependencies:
+      ht_shared:
+        git:
+          url: https://github.com/headlines-toolkit/ht-shared.git
+          # You might want to pin to a specific ref/tag in a real project:
+          # ref: main 
+    ```
+
+2.  Run `dart pub get` (or `flutter pub get` for Flutter projects).
+
+3.  Import `package:ht_shared/ht_shared.dart` to access all shared models and utilities.
+
+    ```dart
+    import 'package:ht_shared/ht_shared.dart';
+    ```

lib/src/models/feed/suggested_content.dart

@@ -1,10 +1,13 @@
-import 'package:ht_shared/ht_shared.dart' show Category, Country, Headline, Source;
+import 'package:ht_shared/ht_shared.dart'
+    show Category, Country, Headline, Source;
 import 'package:ht_shared/src/models/feed/feed_item.dart';
 import 'package:ht_shared/src/models/feed/feed_item_action.dart'
     show FeedItemAction, feedItemActionFromJson, feedItemActionToJson;
 import 'package:ht_shared/src/models/feed/suggested_content_display_type.dart';
-import 'package:ht_shared/src/models/models.dart' show Category, Country, Headline, Source;
-import 'package:ht_shared/src/models/news/news.dart' show Category, Country, Headline, Source;
+import 'package:ht_shared/src/models/models.dart'
+    show Category, Country, Headline, Source;
+import 'package:ht_shared/src/models/news/news.dart'
+    show Category, Country, Headline, Source;
 // Removed redundant imports for Category, Country, Headline, Source
 // as FeedItem itself will handle these.
 import 'package:json_annotation/json_annotation.dart';