Update README.md: Revamp contact and connection info

Removed the "Support & Contact" section and replaced it with a new "Stay Connected" section. This update includes links to watch the repository, follow the maintainer on GitHub, connect on LinkedIn, and access the changelog. The previous closing statement about collaboration was also removed, along with the "Built with Love & Passion for Clean Code" section.
Merge branch 'Dev' of https://github.com/dariemcarlosdev/SecureCleanApiWaf into Dev

Author: dariemcarlosdev

Core/Application/Common/Behaviors/CachingBehavior.cs

@@ -30,7 +30,7 @@ namespace SecureCleanApiWaf.Core.Application.Common.Behaviors
     ///
     /// In a CQRS (Command Query Responsibility Segregation) architecture, MediatR is often used to dispatch commands (for state changes)
     /// and queries (for data retrieval) to their respective handlers. This caching behavior is especially useful for queries, as it can
-    /// intercept query requests, check if the result is already cached, and return the cached data if available—reducing load on the system
+    /// intercept query requests, check if the result is already cached, and return the cached data if available�reducing load on the system
     /// and improving performance. For commands, which change state, caching is typically bypassed. This ensures that queries are fast and
     /// scalable, while commands remain consistent and reliable, fully supporting the separation of read and write concerns central to CQRS.
     /// </summary>
@@ -41,6 +41,13 @@ IDistributedCache cache
         : IPipelineBehavior<TRequest, TResponse>
         where TRequest : ICacheable
     {
+        /// <summary>
+        /// Intercepts cacheable requests to return a cached response when available or invoke the handler, cache its result, and return that response.
+        /// </summary>
+        /// <param name="request">The cacheable request that provides the cache key and controls behavior (set BypassCache to skip caching; may specify SlidingExpirationInMinutes and AbsoluteExpirationInMinutes).</param>
+        /// <param name="next">The handler delegate to execute when a cached response is not available or caching is bypassed.</param>
+        /// <param name="cancellationToken">Cancellation token used for cache operations and handler execution.</param>
+        /// <returns>The cached response if present for the request's CacheKey; otherwise the response produced by invoking the handler.</returns>
         public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
         {
             TResponse response;
@@ -98,4 +105,4 @@ async Task<TResponse> GetResponseAndAddToCache()
             return response;
         }
     }
-}
+}

Core/Application/Common/DTOs/TokenBlacklistStatusDto.cs

@@ -48,7 +48,14 @@ public class TokenBlacklistStatusDto
 
         /// <summary>
         /// Creates a blacklisted token status.
+        /// <summary>
+        /// Create a TokenBlacklistStatusDto representing a token that has been blacklisted.
         /// </summary>
+        /// <param name="tokenId">The token's JWT ID (jti), or null if unknown.</param>
+        /// <param name="blacklistedAt">The UTC time when the token was blacklisted, or null if not recorded.</param>
+        /// <param name="tokenExpiresAt">The token's natural expiration time, or null if unknown.</param>
+        /// <param name="fromCache">Whether the status was retrieved from cache.</param>
+        /// <returns>A TokenBlacklistStatusDto with IsBlacklisted set to `true`, Status set to "blacklisted", Details describing the blacklist, CheckedAt set to the current UTC time, and FromCache set to the provided value.</returns>
         public static TokenBlacklistStatusDto Blacklisted(
             string? tokenId, 
             DateTime? blacklistedAt, 
@@ -70,7 +77,13 @@ public static TokenBlacklistStatusDto Blacklisted(
 
         /// <summary>
         /// Creates a valid (not blacklisted) token status.
+        /// <summary>
+        /// Creates a TokenBlacklistStatusDto representing a valid (not blacklisted) token.
         /// </summary>
+        /// <param name="tokenId">The token's JWT ID (jti), or null if unavailable.</param>
+        /// <param name="tokenExpiresAt">The token's natural expiration time, or null if unknown.</param>
+        /// <param name="fromCache">Whether the result was retrieved from cache.</param>
+        /// <returns>A DTO indicating the token is valid; CheckedAt is set to the current UTC time.</returns>
         public static TokenBlacklistStatusDto Valid(
             string? tokenId, 
             DateTime? tokenExpiresAt, 
@@ -90,7 +103,11 @@ public static TokenBlacklistStatusDto Valid(
 
         /// <summary>
         /// Creates an invalid token status (malformed or expired).
+        /// <summary>
+        /// Create a TokenBlacklistStatusDto representing an invalid token status.
         /// </summary>
+        /// <param name="reason">Human-readable explanation for why the token is considered invalid.</param>
+        /// <returns>A TokenBlacklistStatusDto with IsBlacklisted set to false, Status set to "invalid", Details set to the provided reason, CheckedAt set to the current UTC time, and FromCache set to false.</returns>
         public static TokenBlacklistStatusDto Invalid(string reason)
         {
             return new TokenBlacklistStatusDto
@@ -103,4 +120,4 @@ public static TokenBlacklistStatusDto Invalid(string reason)
             };
         }
     }
-}
+}

Core/Application/Common/Interfaces/IApiDataItemRepository.cs

@@ -63,7 +63,11 @@ public interface IApiDataItemRepository
         /// </summary>
         /// <param name="id">The item's unique identifier.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
-        /// <returns>The item if found, null otherwise.</returns>
+        /// <summary>
+/// Retrieves an ApiDataItem by its unique identifier.
+/// </summary>
+/// <param name="id">The unique identifier of the ApiDataItem to retrieve.</param>
+/// <returns>The ApiDataItem with the specified id, or `null` if no matching item is found.</returns>
         Task<ApiDataItem?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -76,7 +80,11 @@ public interface IApiDataItemRepository
         /// Used to find existing items when synchronizing from external APIs.
         /// Prevents duplicate storage of the same external data.
         /// Should be optimized with database index on ExternalId.
-        /// </remarks>
+        /// <summary>
+/// Retrieves an <see cref="ApiDataItem"/> that matches the specified external system identifier.
+/// </summary>
+/// <param name="externalId">The identifier assigned to the item by an external system.</param>
+/// <returns>The matching <see cref="ApiDataItem"/>, or <c>null</c> if no match exists.</returns>
         Task<ApiDataItem?> GetByExternalIdAsync(string externalId, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -87,7 +95,10 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Returns only items with Active status.
         /// Used for serving fresh data to API consumers.
-        /// </remarks>
+        /// <summary>
+/// Retrieves all active API data items — items that are not marked as deleted and are not marked as stale.
+/// </summary>
+/// <returns>A read-only list of active <see cref="ApiDataItem"/> instances.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetActiveItemsAsync(CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -99,7 +110,10 @@ public interface IApiDataItemRepository
         /// Includes active, stale, and deleted items.
         /// Used for administrative purposes and full data exports.
         /// Consider pagination for large datasets.
-        /// </remarks>
+        /// <summary>
+/// Retrieves all API data items regardless of their status (including deleted or stale items).
+/// </summary>
+/// <returns>A read-only list containing every <see cref="ApiDataItem"/> in the repository.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetAllItemsAsync(CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -111,7 +125,12 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Useful for batch operations like refreshing stale items
         /// or cleaning up deleted items.
-        /// </remarks>
+        /// <summary>
+/// Retrieves all ApiDataItem instances that have the specified data status.
+/// </summary>
+/// <param name="status">The DataStatus value to filter items by.</param>
+/// <param name="cancellationToken">Token to observe while waiting for the task to complete.</param>
+/// <returns>A read-only list of ApiDataItem objects whose status equals the specified value.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetItemsByStatusAsync(DataStatus status, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -124,7 +143,11 @@ public interface IApiDataItemRepository
         /// Returns items where (UtcNow - LastSyncedAt) > maxAge.
         /// Used by background refresh jobs to identify stale data.
         /// Should be optimized with index on LastSyncedAt.
-        /// </remarks>
+        /// <summary>
+/// Finds API data items whose last synchronization time is older than the provided maximum age and therefore need refreshing.
+/// </summary>
+/// <param name="maxAge">The maximum allowed age since an item's LastSyncedAt; items older than this value are considered to need refresh.</param>
+/// <returns>A read-only list of ApiDataItem instances whose LastSyncedAt age exceeds <paramref name="maxAge"/>.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetItemsNeedingRefreshAsync(TimeSpan maxAge, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -136,7 +159,11 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Useful for managing data from multiple API sources.
         /// Enables source-specific refresh or cleanup operations.
-        /// </remarks>
+        /// <summary>
+/// Retrieves API data items that originate from the specified source URL.
+/// </summary>
+/// <param name="sourceUrl">The source URL to filter items by.</param>
+/// <returns>A read-only list of <see cref="ApiDataItem"/> instances that originate from the specified source URL.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetItemsBySourceUrlAsync(string sourceUrl, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -149,7 +176,11 @@ public interface IApiDataItemRepository
         /// Performs case-insensitive partial match on Name field.
         /// Useful for search functionality in API endpoints.
         /// Consider adding pagination for large result sets.
-        /// </remarks>
+        /// <summary>
+/// Finds ApiDataItem objects whose names match a case-insensitive partial search term.
+/// </summary>
+/// <param name="searchTerm">The substring to match against item names; matching is case-insensitive and treats the term as a partial search.</param>
+/// <returns>A read-only list of ApiDataItem instances whose names match the provided search term.</returns>
         Task<IReadOnlyList<ApiDataItem>> SearchByNameAsync(string searchTerm, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -162,7 +193,12 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Searches JSON metadata field for specific keys/values.
         /// Implementation depends on database JSON support.
-        /// </remarks>
+        /// <summary>
+/// Retrieves ApiDataItem entities that contain a specified metadata key, optionally filtered to a specific metadata value.
+/// </summary>
+/// <param name="metadataKey">The metadata key to match.</param>
+/// <param name="metadataValue">An optional metadata value to match; when null, items containing the key are returned regardless of the value.</param>
+/// <returns>A read-only list of ApiDataItem objects matching the metadata criteria.</returns>
         Task<IReadOnlyList<ApiDataItem>> GetItemsByMetadataAsync(string metadataKey, object? metadataValue = null, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -174,7 +210,11 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Used to prevent duplicate storage of external data.
         /// Should check against non-deleted items only.
-        /// </remarks>
+        /// <summary>
+/// Checks whether a non-deleted ApiDataItem with the specified external system identifier exists.
+/// </summary>
+/// <param name="externalId">The external system identifier to check for.</param>
+/// <returns>`true` if a non-deleted item with the given external ID exists, `false` otherwise.</returns>
         Task<bool> ExistsAsync(string externalId, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -186,7 +226,10 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Creates a new record in the database.
         /// Typically called after fetching data from external API.
-        /// </remarks>
+        /// <summary>
+/// Adds a new ApiDataItem to the repository.
+/// </summary>
+/// <param name="item">The ApiDataItem to add; must not be null. The item will be tracked and persisted when SaveChangesAsync is called.</param>
         Task AddAsync(ApiDataItem item, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -198,7 +241,11 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Optimized batch operation for bulk imports.
         /// More efficient than adding one by one.
-        /// </remarks>
+        /// <summary>
+/// Adds multiple ApiDataItem instances to the repository.
+/// </summary>
+/// <param name="items">The collection of ApiDataItem objects to add.</param>
+/// <param name="cancellationToken">A token to cancel the operation.</param>
         Task AddRangeAsync(IEnumerable<ApiDataItem> items, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -210,7 +257,11 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Updates item data, status, metadata, etc.
         /// Called after refreshing data from external API.
-        /// </remarks>
+        /// <summary>
+/// Applies the provided ApiDataItem's updated values to the repository state.
+/// </summary>
+/// <param name="item">The ApiDataItem containing the updated data to store.</param>
+/// <param name="cancellationToken">Token to cancel the operation.</param>
         Task UpdateAsync(ApiDataItem item, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -222,7 +273,12 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Optimized batch operation for bulk updates.
         /// Useful for background refresh jobs.
-        /// </remarks>
+        /// <summary>
+/// Updates multiple ApiDataItem entities in a single batch operation.
+/// </summary>
+/// <param name="items">The collection of items to update.</param>
+/// <param name="cancellationToken">Token to observe for cancellation.</param>
+/// <returns>The number of items updated.</returns>
         Task<int> UpdateRangeAsync(IEnumerable<ApiDataItem> items, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -234,7 +290,10 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Soft delete - marks item as deleted but preserves data.
         /// Use item.MarkAsDeleted() before calling this.
-        /// </remarks>
+        /// <summary>
+/// Marks the given ApiDataItem as deleted in the repository (soft delete) without removing its data.
+/// </summary>
+/// <param name="item">The ApiDataItem to soft-delete; the item is expected to be marked as deleted prior to calling this method.</param>
         Task DeleteAsync(ApiDataItem item, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -247,7 +306,12 @@ public interface IApiDataItemRepository
         /// Hard delete for cleanup of old deleted items.
         /// Should be used carefully, typically by scheduled cleanup jobs.
         /// Permanently removes data - cannot be recovered.
-        /// </remarks>
+        /// <summary>
+/// Permanently removes ApiDataItem records that were soft-deleted prior to the specified cutoff date.
+/// </summary>
+/// <param name="olderThan">Remove items soft-deleted before this date and time (UTC is recommended).</param>
+/// <param name="cancellationToken">Token to cancel the operation.</param>
+/// <returns>The number of items that were permanently removed.</returns>
         Task<int> PermanentlyDeleteOldItemsAsync(DateTime olderThan, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -259,7 +323,12 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Bulk operation to invalidate cache for an entire API source.
         /// Useful when external API structure changes.
-        /// </remarks>
+        /// <summary>
+/// Marks all ApiDataItem entities that originate from the specified source URL as stale.
+/// </summary>
+/// <param name="sourceUrl">The source URL whose items should be marked stale.</param>
+/// <param name="cancellationToken">A token to cancel the operation.</param>
+/// <returns>The number of items that were marked as stale.</returns>
         Task<int> MarkSourceAsStaleAsync(string sourceUrl, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -270,7 +339,10 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Provides insights for cache performance and data freshness monitoring.
         /// Returns counts by status, average age, etc.
-        /// </remarks>
+        /// <summary>
+/// Retrieves aggregated statistics for ApiDataItem entities such as counts by status, age metrics, and other summary telemetry.
+/// </summary>
+/// <returns>An <see cref="ApiDataStatisticsDto"/> containing counts, averages, and other summary metrics for ApiDataItem entities.</returns>
         Task<ApiDataStatisticsDto> GetStatisticsAsync(CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -281,7 +353,10 @@ public interface IApiDataItemRepository
         /// <remarks>
         /// Commits the unit of work transaction.
         /// Should be called after Add/Update/Delete operations.
-        /// </remarks>
+        /// <summary>
+/// Persists all pending changes tracked by the repository to the underlying data store.
+/// </summary>
+/// <returns>The number of state entries written to the underlying data store.</returns>
         Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
     }
-}
+}