using EntitlementDAL.DTOs;
using GB5Shared.DTO.Framework.Login;

namespace EntitlementBLL.Legal;

/// <summary>The P0 integration link for Legal/Contract Agreement Consent (tracker §50/§51) —
/// a stable boundary Entitlement's signup/onboarding flows call today, backed by
/// LocalAgreementConsentProvider (Phase 0's own minimal, Entitlement-owned schema). Once the
/// full "GoodBooks CLM" product ships (its own future, separately-scoped session per §51.3),
/// a new ClmAgreementConsentClient — an HTTP client following this codebase's own established
/// cross-module-client convention (ISqlWorkbenchClient, IPaySubscriptionClient) — replaces the
/// local implementation with zero change to any call site.</summary>
public interface IAgreementConsentProvider
{
    /// <summary>Resolves the currently-applicable, Published agreement-version bundle a caller
    /// should show a subject before letting them proceed — one version per requested type code,
    /// preferring a jurisdiction-specific override over the universal default.</summary>
    Task<AgreementBundleDTO> GetApplicableAgreementsAsync(
        string jurisdictionCode, string[] agreementTypeCodes, LoginDTO login, CancellationToken ct);

    /// <summary>The individual-user first-login gate (tracker §50.3): every currently-Published,
    /// RequiresIndividualAcceptance=1 agreement version this specific subject has NOT yet
    /// accepted (e.g. an Enterprise Clickwrap EULA) — one entry per still-unaccepted type. An
    /// empty result means the subject has nothing pending and may proceed. Independent of
    /// whether the subject's own organization already accepted the org-level ToS/DPA (those are
    /// unilateral broadcast documents with RequiresIndividualAcceptance=0, recorded once against
    /// the client, not the individual — see GetApplicableAgreementsAsync/RecordAcceptanceAsync
    /// used at signup).</summary>
    Task<int[]> GetPendingIndividualAgreementVersionIdsAsync(
        AgreementSubjectType subjectType, int subjectId, string jurisdictionCode, LoginDTO login, CancellationToken ct);

    /// <summary>Records that a subject accepted the exact agreement versions they were shown —
    /// re-validates each version is still Published before writing (a version can go stale
    /// between page-load and submit). Writes one append-only LAGREEMENTACCEPTANCE row per
    /// version, all sharing the same correlationKey.</summary>
    Task RecordAcceptanceAsync(
        AgreementSubjectType subjectType, int subjectId, int[] agreementVersionIds,
        string? ipAddress, string? userAgent, AgreementAcceptanceMethod method,
        string correlationKey, LoginDTO login, CancellationToken ct);
}