#nullable enable
namespace Baya.Application.Contracts.Common;

/// <summary>
/// Seam for the identity KYC vendor — national-id validity + name match + photo/video liveness against the
/// civil-registry (ثبت احوال) record. On pass it yields the matched name used to populate the verified
/// identity and cross-check later credentials. Buy this, don't build it: the mock returns a deterministic
/// pass/fail keyed off a test national-id; the real implementation swaps in an Iranian e-KYC vendor
/// (Finnotech / U-ID / Jibbit / Farashensa / Verify / Kavoshak) by a registration change only.
/// </summary>
public interface IIdentityKycProvider
{
    Task<IdentityKycResult> VerifyAsync(string nationalId, string? livenessPayload, CancellationToken cancellationToken = default);
}

/// <summary>Outcome of an <see cref="IIdentityKycProvider"/> verification.</summary>
/// <param name="Passed">Whether identity + liveness passed.</param>
/// <param name="MatchedName">The full name the vendor matched (for the credential cross-check), when passed.</param>
/// <param name="VendorRef">The vendor transaction id, kept for audit.</param>
/// <param name="ExternalResponseJson">The raw vendor response blob, persisted for audit.</param>
/// <param name="FailureReason">A reason when <see cref="Passed"/> is false.</param>
public readonly record struct IdentityKycResult(
    bool Passed,
    string? MatchedName,
    string VendorRef,
    string ExternalResponseJson,
    string? FailureReason);
