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

/// <summary>
/// Seam for the Shahkar (شاهکار) phone↔national-id binding inquiry — confirms the login SIM is registered
/// to the nurse's own national id. The shared-SIM failure mode (a SIM owned by a family member) is an
/// explicit, handled state, never an undefined edge. The mock returns a deterministic result keyed off a
/// test phone/national-id; the real implementation calls a Finnotech/KYC vendor. No real Shahkar call and
/// no money moves through this seam.
/// </summary>
public interface IShahkarVerifier
{
    Task<ShahkarMatchResult> MatchAsync(string? phoneNumber, string? nationalId, CancellationToken cancellationToken = default);
}

/// <summary>Outcome of a <see cref="IShahkarVerifier"/> inquiry.</summary>
/// <param name="Matched">Whether the SIM is bound to the given national id.</param>
/// <param name="IsSharedSim">The explicit shared-SIM failure state (raises a support alert).</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 non-accusatory reason when <see cref="Matched"/> is false.</param>
public readonly record struct ShahkarMatchResult(
    bool Matched,
    bool IsSharedSim,
    string VendorRef,
    string ExternalResponseJson,
    string? FailureReason);
