using System;
using System.Linq;
using xModels.Dtos;
using System.Threading;
using xIdentityModels.Dtos;
using System.Threading.Tasks;
using xIdentityModels.Models;
using System.Linq.Expressions;
using System.Collections.Generic;
using Microsoft.EntityFrameworkCore.Query;

namespace xIds.Interfaces
{
    /// <summary>
    /// a Service For Manage Security Applications and also Api Key(s) ...
    /// </summary>
    public interface IXApplicationProvider
    {
        //
        #region Application ...
        /// <summary>
        /// Add Specified Item ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> AddApplicationAsync(
            XApplicationDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Update Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> UpdateApplicationAsync(
            int id,
            XApplicationDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="softDelete"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> RemoveApplicationAsync(
            int id,
            bool softDelete = true,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve an Item by Providing it's ID ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> GetApplicationAsync(
            int id,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApplicationDto>> GetAllApplicationAsync(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApplication>, IOrderedQueryable<XApplication>> orderBuilder = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items as Async Enumerable ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<XApplicationDto> GetAllApplicationAsAsyncEnumerable(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApplication>, IOrderedQueryable<XApplication>> orderBuilder = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find an Item By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> FindOneApplicationAsync(
            Expression<Func<XApplication, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find a Collection of Items By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApplicationDto>> FindManyApplicationAsync(
            Expression<Func<XApplication, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApplication>, IOrderedQueryable<XApplication>> orderBuilder = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve Items based on XQuery Pagination Structure ...
        /// </summary>
        /// <param name="query"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="predicate"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XApplicationDto>> QueryApplicationAsync(
            XQuery query,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Expression<Func<XApplication, bool>> predicate = null,
            Func<IQueryable<XApplication>, IOrderedQueryable<XApplication>> orderBuilder = null,
            Func<IQueryable<XApplication>, IIncludableQueryable<XApplication, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region ApiKey ...
        /// <summary>
        /// Add Specified Item ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> AddApiKeyAsync(
            XApiKeyDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Update Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> UpdateApiKeyAsync(
            Guid id,
            XApiKeyDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="softDelete"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> RemoveApiKeyAsync(
            Guid id,
            bool softDelete = true,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve an Item by Providing it's ID ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> GetApiKeyAsync(
            Guid id,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyDto>> GetAllApiKeyAsync(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKey>, IOrderedQueryable<XApiKey>> orderBuilder = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items as Async Enumerable ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<XApiKeyDto> GetAllApiKeyAsAsyncEnumerable(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKey>, IOrderedQueryable<XApiKey>> orderBuilder = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find an Item By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> FindOneApiKeyAsync(
            Expression<Func<XApiKey, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find a Collection of Items By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyDto>> FindManyApiKeyAsync(
            Expression<Func<XApiKey, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKey>, IOrderedQueryable<XApiKey>> orderBuilder = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve Items based on XQuery Pagination Structure ...
        /// </summary>
        /// <param name="query"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="predicate"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XApiKeyDto>> QueryApiKeyAsync(
            XQuery query,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Expression<Func<XApiKey, bool>> predicate = null,
            Func<IQueryable<XApiKey>, IOrderedQueryable<XApiKey>> orderBuilder = null,
            Func<IQueryable<XApiKey>, IIncludableQueryable<XApiKey, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region ApiKeyUsage ...
        /// <summary>
        /// Add Specified Item ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> AddApiKeyUsageAsync(
            XApiKeyUsageDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Update Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="item"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> UpdateApiKeyUsageAsync(
            long id,
            XApiKeyUsageDto item,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove Specified Item ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="softDelete"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> RemoveApiKeyUsageAsync(
            long id,
            bool softDelete = true,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve an Item by Providing it's ID ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> GetApiKeyUsageAsync(
            long id,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyUsageDto>> GetAllApiKeyUsageAsync(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKeyUsage>, IOrderedQueryable<XApiKeyUsage>> orderBuilder = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Items as Async Enumerable ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        IAsyncEnumerable<XApiKeyUsageDto> GetAllApiKeyUsageAsAsyncEnumerable(
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKeyUsage>, IOrderedQueryable<XApiKeyUsage>> orderBuilder = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find an Item By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> FindOneApiKeyUsageAsync(
            Expression<Func<XApiKeyUsage, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Find a Collection of Items By Providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyUsageDto>> FindManyApiKeyUsageAsync(
            Expression<Func<XApiKeyUsage, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Func<IQueryable<XApiKeyUsage>, IOrderedQueryable<XApiKeyUsage>> orderBuilder = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve Items based on XQuery Pagination Structure ...
        /// </summary>
        /// <param name="query"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="userInfo"></param>
        /// <param name="predicate"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<XApiKeyUsageDto>> QueryApiKeyUsageAsync(
            XQuery query,
            bool ignoreSoftDeleteds = true,
            XUserClaimsInfoDto userInfo = null,
            Expression<Func<XApiKeyUsage, bool>> predicate = null,
            Func<IQueryable<XApiKeyUsage>, IOrderedQueryable<XApiKeyUsage>> orderBuilder = null,
            Func<IQueryable<XApiKeyUsage>, IIncludableQueryable<XApiKeyUsage, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Custom Actions ...
        /// <summary>
        /// Generate a New ApiKey and Add It to DB ...
        /// </summary>
        /// <param name="applicationId"></param>
        /// <param name="expiration"></param>
        /// <param name="scopes"></param>
        /// <param name="allowedIPs"></param>
        /// <param name="rateLimit"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> CreateApiKey(
            int applicationId,
            TimeSpan? expiration = null,
            IEnumerable<string> scopes = null,
            IEnumerable<string> allowedIPs = null,
            int? rateLimit = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Revoke Specified Api Key ...
        /// </summary>
        /// <param name="apiKeyId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> RevokeApiKey(
            Guid apiKeyId,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Renew Specified Api Key ...
        /// </summary>
        /// <param name="apiKeyId"></param>
        /// <param name="newExpiration"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> RotateApiKey(
            Guid apiKeyId,
            TimeSpan? newExpiration = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve All Api Keys for Specified Application ... 
        /// </summary>
        /// <param name="applicationId"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyDto>> GetApplicationApiKeys(
            int applicationId,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Validate Specified Api Key in based on ClientIP ...
        /// </summary>
        /// <param name="apiKey"></param>
        /// <param name="clientIP"></param>
        /// <param name="requiredScope"></param>
        /// <param name="userInfo"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyValidationResult> ValidateApiKey(
            string apiKey,
            string clientIP,
            string requiredScope = null,
            XUserClaimsInfoDto userInfo = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Enrichers ...
        /// <summary>
        /// Enrich Api Key ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> EnrichAsync(
            XApiKey source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich Api Key ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyDto> EnrichAsync(
            XApiKeyDto source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich Api Key Usage ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> EnrichAsync(
            XApiKeyUsage source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich Application ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> EnrichAsync(
            XApplication source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich Api Key Usage ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApiKeyUsageDto> EnrichAsync(
            XApiKeyUsageDto source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich Application ...
        /// </summary>
        /// <param name="source"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XApplicationDto> EnrichAsync(
            XApplicationDto source,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Api Key(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyDto>> EnrichRangeAsync(
            IEnumerable<XApiKey> sources,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Api Key(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyDto>> EnrichRangeAsync(
            IEnumerable<XApiKeyDto> sources,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Api Key Usage(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyUsageDto>> EnrichRangeAsync(
            IEnumerable<XApiKeyUsage> sources,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Application(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApplicationDto>> EnrichRangeAsync(
            IEnumerable<XApplication> sources,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Api Key Usage(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApiKeyUsageDto>> EnrichRangeAsync(
            IEnumerable<XApiKeyUsageDto> sources,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Enrich a Collection of Application(s) ...
        /// </summary>
        /// <param name="sources"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<XApplicationDto>> EnrichRangeAsync(
            IEnumerable<XApplicationDto> sources,
            CancellationToken cancellationToken = default
        );
        #endregion
    }
}