ANTOOZA-BACKEND/Application/Abstractions/Kyc/INiceAuthClient.cs

using SharedKernel.Results;

namespace Application.Abstractions.Kyc;

/// <summary>
/// NICE 통합인증 API 클라이언트. (token / url / result 3개 endpoint 호출 + 복호화)
///
/// 가이드: .claude/plan/nice-auth-integration.md
/// </summary>
public interface INiceAuthClient
{
    /// <summary>
    /// access_token 발급 (24시간 유효 — 내부에서 Redis 캐시).
    /// 운영자는 직접 호출할 일 거의 없음 — RequestAuthUrl/GetResult 가 내부에서 호출.
    /// </summary>
    Task<Result<NiceTokenInfo>> GetTokenAsync(CancellationToken ct);

    /// <summary>
    /// 표준창에 띄울 auth_url 발급. transaction_id 는 10분 유효.
    /// 가맹점은 응답의 (AuthUrl, TransactionId, RequestNo, Ticket, Iterators) 를 NiceAuthSession 에 저장.
    /// </summary>
    /// <param name="sessionToken">
    /// 가맹점 NiceAuthSession.SessionToken. NICE return_url path segment 로 embed 되어 callback 매칭에 사용.
    /// (Backend 가 NiceAuthOptions.ReturnUrl base 에 자동 append)
    /// </param>
    Task<Result<NiceUrlInfo>> RequestAuthUrlAsync(string sessionToken, CancellationToken ct);

    /// <summary>
    /// NICE 표준창 인증 완료 후 result 호출 + 복호화. 성공 시 사용자 정보 반환.
    ///
    /// ticket / iterators 는 <see cref="RequestAuthUrlAsync"/> 시점 token 발급의 값
    /// (NiceAuthSession 에 보관한 값) 을 그대로 전달해야 함.
    /// </summary>
    Task<Result<NiceUserInfo>> GetResultAsync(
        string requestNo,
        string transactionId,
        string webTransactionId,
        string ticket,
        int iterators,
        CancellationToken ct);
}