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);
     }
-}
+}