/*
 * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IPurchaseLogRepository.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Purchase log repository interface defining monetization-specific data access operations.
 *              Handles transaction tracking, chargeback protection, VIP progression, secret tier system,
 *              revenue analytics, fraud detection, and customer lifetime value analysis. Critical for
 *              financial integrity and anti-pay-to-win balance while maintaining sustainable revenue.
 * Last Edit Notes: Initial implementation with comprehensive monetization tracking, VIP systems, and financial security.
 */

using ShadowedRealms.Core.Models;
using ShadowedRealms.Core.Models.Purchase;
using System.Linq.Expressions;

namespace ShadowedRealms.Core.Interfaces.Repositories
{
    /// <summary>
    /// Repository interface for PurchaseLog entity operations, providing comprehensive monetization management,
    /// transaction tracking, chargeback protection, VIP progression, and revenue analytics.
    /// Balances sustainable revenue generation with anti-pay-to-win principles and player value delivery.
    /// </summary>
    public interface IPurchaseLogRepository : IRepository<PurchaseLog, int>
    {
        #region Transaction Processing and Validation

        /// <summary>
        /// Records a new purchase transaction with comprehensive validation, fraud detection, and VIP progression.
        /// Automatically calculates VIP points, milestone rewards, and applies purchase benefits while logging for audit.
        /// </summary>
        /// <param name="playerId">The player making the purchase</param>
        /// <param name="purchaseDetails">Complete purchase information including items, prices, and payment method</param>
        /// <param name="kingdomId">The kingdom context for the purchase</param>
        /// <param name="transactionId">External payment processor transaction ID</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Created purchase log with VIP progression and applied benefits</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or purchase violates policies</exception>
        /// <exception cref="InvalidOperationException">Thrown when purchase processing fails due to fraud detection</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<PurchaseLog> RecordPurchaseTransactionAsync(int playerId, object purchaseDetails, int kingdomId,
            string transactionId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates purchase eligibility based on player status, spending limits, cooldown periods,
        /// and fraud prevention rules. Prevents exploitation while ensuring legitimate purchases proceed smoothly.
        /// </summary>
        /// <param name="playerId">The player attempting the purchase</param>
        /// <param name="purchaseType">Type of purchase being attempted</param>
        /// <param name="purchaseAmount">Dollar amount of the purchase</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Purchase eligibility result with restrictions and spending limit information</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(bool IsEligible, string[] Restrictions, decimal RemainingSpendingLimit, TimeSpan? Cooldown)>
            ValidatePurchaseEligibilityAsync(int playerId, string purchaseType, decimal purchaseAmount, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Processes purchase refunds and reversals, handling VIP point adjustments, benefit revocation,
        /// and account status updates. Maintains financial integrity while supporting customer service.
        /// </summary>
        /// <param name="originalPurchaseId">The purchase being refunded</param>
        /// <param name="refundReason">Reason for refund (customer service, chargeback, etc.)</param>
        /// <param name="refundAmount">Amount being refunded (can be partial)</param>
        /// <param name="kingdomId">The kingdom context for the refund</param>
        /// <param name="authorizingAdminId">Admin authorizing the refund (if applicable)</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated purchase log with refund details and account adjustments</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or refund not allowed</exception>
        /// <exception cref="InvalidOperationException">Thrown when refund processing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<PurchaseLog> ProcessPurchaseRefundAsync(int originalPurchaseId, string refundReason, decimal refundAmount,
            int kingdomId, int? authorizingAdminId = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// Verifies purchase authenticity with external payment processors to prevent fraud and ensure
        /// transaction integrity. Cross-references with payment gateway records and validates receipt data.
        /// </summary>
        /// <param name="purchaseLogId">The purchase to verify</param>
        /// <param name="paymentProcessorData">Data from external payment processor for verification</param>
        /// <param name="kingdomId">The kingdom context for verification</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Verification result with authenticity confirmation and fraud risk assessment</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when verification fails or fraud detected</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(bool IsAuthentic, double FraudRiskScore, string[] VerificationFlags)> VerifyPurchaseAuthenticityAsync(
            int purchaseLogId, object paymentProcessorData, int kingdomId, CancellationToken cancellationToken = default);

        #endregion

        #region VIP System Integration

        /// <summary>
        /// Calculates VIP point awards for purchases based on spending amount, purchase type, promotional bonuses,
        /// and loyalty multipliers. Handles milestone detection and automatic VIP level progression.
        /// </summary>
        /// <param name="purchaseAmount">Dollar amount of purchase</param>
        /// <param name="purchaseType">Type of purchase for bonus calculations</param>
        /// <param name="playerId">Player for loyalty bonus calculations</param>
        /// <param name="kingdomId">The kingdom context for calculations</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>VIP point calculation with milestone progression and bonus details</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(int VipPoints, int NewVipLevel, bool MilestoneReached, object[] UnlockedBenefits)>
            CalculateVipPointsAsync(decimal purchaseAmount, string purchaseType, int playerId, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Processes VIP milestone rewards when players reach new VIP levels, including resource packages,
        /// exclusive items, permanent bonuses, and secret tier system progression tracking.
        /// </summary>
        /// <param name="playerId">The player reaching the milestone</param>
        /// <param name="newVipLevel">The VIP level just achieved</param>
        /// <param name="triggeringPurchaseId">The purchase that triggered the milestone</param>
        /// <param name="kingdomId">The kingdom context for reward processing</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Processed milestone rewards with secret tier progression</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or milestone already claimed</exception>
        /// <exception cref="InvalidOperationException">Thrown when milestone processing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ProcessVipMilestoneRewardsAsync(int playerId, int newVipLevel, int triggeringPurchaseId,
            int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players by VIP spending tier for targeted offers, customer service prioritization,
        /// and lifetime value analysis. Supports personalized monetization and retention strategies.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze</param>
        /// <param name="spendingTier">The spending tier to filter by (whale, dolphin, minnow, F2P)</param>
        /// <param name="timeframe">Time period for spending calculation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players in the specified spending tier with spending analytics</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<(object PlayerInfo, decimal TotalSpent, string SpendingPattern, double LTV)>>
            GetPlayersBySpendingTierAsync(int kingdomId, string spendingTier, TimeSpan timeframe,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Tracks secret tier system progression inspired by King of Avalon's hidden VIP benefits.
        /// Provides additional rewards and recognition for highest-tier spenders without publicizing exact thresholds.
        /// </summary>
        /// <param name="playerId">The player to track secret tier progression for</param>
        /// <param name="purchaseAmount">Recent purchase amount</param>
        /// <param name="kingdomId">The kingdom context for tracking</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Secret tier progression with unlocked benefits (if any)</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> TrackSecretTierProgressionAsync(int playerId, decimal purchaseAmount, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Chargeback Protection and Fraud Prevention

        /// <summary>
        /// Processes chargeback notifications from payment processors, automatically adjusting player accounts,
        /// revoking purchased benefits, and implementing protective measures against future fraud attempts.
        /// </summary>
        /// <param name="originalPurchaseId">The purchase being charged back</param>
        /// <param name="chargebackDetails">Details from payment processor about the chargeback</param>
        /// <param name="kingdomId">The kingdom context for chargeback processing</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Chargeback processing result with account adjustments and protective measures</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or purchase not found</exception>
        /// <exception cref="InvalidOperationException">Thrown when chargeback processing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ProcessChargebackAsync(int originalPurchaseId, object chargebackDetails, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Identifies high-risk purchase patterns that may indicate fraud, including rapid large purchases,
        /// unusual payment methods, geographic inconsistencies, and behavioral anomalies for fraud prevention.
        /// </summary>
        /// <param name="playerId">The player to analyze for risk patterns</param>
        /// <param name="recentPurchases">Recent purchase history for pattern analysis</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Fraud risk assessment with specific risk factors and recommended actions</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(double RiskScore, string[] RiskFactors, string[] RecommendedActions, bool RequiresReview)>
            AnalyzeFraudRiskPatternsAsync(int playerId, IEnumerable<object> recentPurchases, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Implements protective measures for accounts with chargeback history, including purchase restrictions,
        /// enhanced verification requirements, and monitoring protocols to prevent future losses.
        /// </summary>
        /// <param name="playerId">The player to implement protections for</param>
        /// <param name="protectionLevel">Level of protection based on chargeback severity</param>
        /// <param name="kingdomId">The kingdom context for protection implementation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Implemented protection measures with duration and review requirements</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when protection implementation fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ImplementChargebackProtectionAsync(int playerId, string protectionLevel, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets chargeback analytics for financial risk management including chargeback rates by payment method,
        /// geographic patterns, player behavior correlations, and financial impact assessment.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze (null for global analysis)</param>
        /// <param name="analysisTimeframe">Time period for chargeback analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive chargeback analytics with risk mitigation recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetChargebackAnalyticsAsync(int? kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region Revenue Analytics and Optimization

        /// <summary>
        /// Gets comprehensive revenue analytics including total revenue, average transaction size,
        /// conversion rates, player lifetime value, and revenue per user metrics for business intelligence.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze (null for global analysis)</param>
        /// <param name="analysisTimeframe">Time period for revenue analysis</param>
        /// <param name="segmentationCriteria">Player segmentation criteria for detailed analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Detailed revenue analytics with trends and optimization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetRevenueAnalyticsAsync(int? kingdomId, TimeSpan analysisTimeframe,
            object? segmentationCriteria = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// Analyzes purchase conversion funnels to identify optimization opportunities including offer timing,
        /// price points, product bundling effectiveness, and user experience friction points.
        /// </summary>
        /// <param name="conversionFunnelType">Type of conversion funnel to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for funnel analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Conversion funnel analysis with optimization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> AnalyzePurchaseConversionFunnelsAsync(string conversionFunnelType, int kingdomId,
            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets customer lifetime value predictions based on purchase history, engagement patterns,
        /// VIP progression, and behavioral indicators for targeted marketing and retention strategies.
        /// </summary>
        /// <param name="playerId">The player to calculate LTV for (null for cohort analysis)</param>
        /// <param name="kingdomId">The kingdom context for calculations</param>
        /// <param name="predictionHorizon">Time horizon for LTV prediction</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>LTV predictions with confidence intervals and contributing factors</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> CalculateCustomerLifetimeValueAsync(int? playerId, int kingdomId, TimeSpan predictionHorizon,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Identifies revenue optimization opportunities including underperforming products, pricing adjustments,
        /// bundle optimization, and promotional timing for maximizing sustainable revenue growth.
        /// </summary>
        /// <param name="optimizationFocus">Area to focus optimization on (pricing, products, timing, etc.)</param>
        /// <param name="kingdomId">The kingdom context for optimization</param>
        /// <param name="analysisTimeframe">Time period for optimization analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Revenue optimization recommendations with projected impact</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> IdentifyRevenueOptimizationOpportunitiesAsync(string optimizationFocus, int kingdomId,
            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);

        #endregion

        #region Player Spending Patterns and Behavior

        /// <summary>
        /// Gets detailed player spending history including purchase frequency, preferred products, spending triggers,
        /// and behavioral patterns for personalized offers and customer service optimization.
        /// </summary>
        /// <param name="playerId">The player to analyze spending patterns for</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for spending pattern analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive spending pattern analysis with personalization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPlayerSpendingPatternsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Identifies players at risk of churn based on spending pattern changes, engagement decline,
        /// and behavioral indicators for targeted retention campaigns and personalized re-engagement.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze for churn risk</param>
        /// <param name="riskThreshold">Risk threshold for churn prediction</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players at risk of churn with risk factors and retention recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<(object PlayerInfo, double ChurnRisk, string[] RiskFactors, object[] RetentionActions)>>
            IdentifyPlayersAtChurnRiskAsync(int kingdomId, double riskThreshold = 0.7,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Analyzes spending triggers and motivations to understand what drives purchase decisions,
        /// including competitive pressure, progression needs, social factors, and event participation.
        /// </summary>
        /// <param name="purchaseLogIds">Specific purchases to analyze triggers for</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Spending trigger analysis with motivation insights and optimization opportunities</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> AnalyzeSpendingTriggersAsync(IEnumerable<int> purchaseLogIds, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets cohort analysis of player spending behavior over time, tracking how spending patterns
        /// evolve based on registration date, first purchase timing, and progression milestones.
        /// </summary>
        /// <param name="cohortDefinition">How to define cohorts (registration month, first purchase, etc.)</param>
        /// <param name="kingdomId">The kingdom context for cohort analysis</param>
        /// <param name="analysisTimeframe">Time period for cohort tracking</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Cohort spending analysis with lifecycle insights and optimization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetSpendingCohortAnalysisAsync(string cohortDefinition, int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region Anti-Pay-to-Win Balance Monitoring

        /// <summary>
        /// Monitors purchase impact on game balance to ensure spending provides value without creating
        /// pay-to-win dominance. Tracks competitive balance metrics and player satisfaction indicators.
        /// </summary>
        /// <param name="kingdomId">The kingdom to monitor balance for</param>
        /// <param name="monitoringTimeframe">Time period for balance monitoring</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Game balance analysis with pay-to-win risk assessment and adjustment recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> MonitorPurchaseImpactOnGameBalanceAsync(int kingdomId, TimeSpan monitoringTimeframe,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Analyzes effectiveness of skill-based alternatives to premium features, ensuring free-to-play
        /// players can achieve competitive results through skill and time investment rather than spending.
        /// </summary>
        /// <param name="skillBasedFeature">The skill-based alternative to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for effectiveness analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Skill-based alternative effectiveness with balance recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> AnalyzeSkillBasedAlternativeEffectivenessAsync(string skillBasedFeature, int kingdomId,
            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets competitive balance metrics comparing performance of paying vs non-paying players
        /// to ensure spending enhances experience without creating unfair advantages or dominance.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze competitive balance for</param>
        /// <param name="competitiveMetric">The metric to analyze (power, progression, success rate, etc.)</param>
        /// <param name="analysisTimeframe">Time period for competitive analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Competitive balance analysis with fairness assessment and adjustment recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetCompetitiveBalanceMetricsAsync(int kingdomId, string competitiveMetric,
            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);

        #endregion

        #region Purchase History and Audit Trails

        /// <summary>
        /// Gets comprehensive purchase history for a player including all transactions, refunds, chargebacks,
        /// VIP progression, and account adjustments for customer service and audit purposes.
        /// </summary>
        /// <param name="playerId">The player to get purchase history for</param>
        /// <param name="kingdomId">The kingdom context for the history</param>
        /// <param name="includeRefunds">Whether to include refunded transactions</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Complete purchase history with transaction details and account impacts</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<object>> GetPlayerPurchaseHistoryAsync(int playerId, int kingdomId, bool includeRefunds = true,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets purchase audit trail for financial compliance and investigation purposes including
        /// all transaction modifications, admin actions, system adjustments, and verification records.
        /// </summary>
        /// <param name="purchaseLogId">The purchase to get audit trail for</param>
        /// <param name="kingdomId">The kingdom context for the audit</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Complete audit trail with chronological record of all purchase-related actions</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPurchaseAuditTrailAsync(int purchaseLogId, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Generates financial compliance reports for regulatory requirements, tax reporting,
        /// and internal audit purposes including revenue reconciliation and transaction verification.
        /// </summary>
        /// <param name="reportType">Type of compliance report to generate</param>
        /// <param name="reportingPeriod">Time period for the compliance report</param>
        /// <param name="jurisdictionRequirements">Specific regulatory requirements to address</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Compliance report with required financial data and verification</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GenerateComplianceReportAsync(string reportType, TimeSpan reportingPeriod,
            object? jurisdictionRequirements = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates purchase data integrity by cross-referencing internal records with external payment
        /// processor data, identifying discrepancies, and ensuring financial accuracy for audit purposes.
        /// </summary>
        /// <param name="validationTimeframe">Time period to validate purchase data for</param>
        /// <param name="paymentProcessorRecords">External records for cross-reference</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Data integrity validation results with discrepancy identification and resolution</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ValidatePurchaseDataIntegrityAsync(TimeSpan validationTimeframe,
            object? paymentProcessorRecords = null, CancellationToken cancellationToken = default);

        #endregion
    }
}