BaseClient.cs

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

namespace Mediumart.MobileMoney;

/// <summary>
/// Abstract base client for all MTN Mobile Money API services.
/// Integrates the shared API methods (token, balance, userinfo, etc.) and user data management.
/// </summary>
public abstract class BaseClient
{
    private readonly HttpClient _client;
    private string _baseUrl;

    // User data storage (equivalent to PHP HasUserData trait)
    private string? _userId;
    private string? _apiKey;
    private string? _subscriptionKey;

    /// <summary>
    /// Gets or sets the user reference ID.
    /// </summary>
    public string? UserId
    {
        get => _userId;
        set => _userId = value;
    }

    /// <summary>
    /// Gets or sets the API key.
    /// </summary>
    public string? ApiKey
    {
        get => _apiKey;
        set => _apiKey = value;
    }

    /// <summary>
    /// Gets or sets the subscription key.
    /// </summary>
    public string? SubscriptionKey
    {
        get => _subscriptionKey;
        set => _subscriptionKey = value;
    }

    /// <summary>
    /// Initializes a new instance of <see cref="BaseClient"/>.
    /// </summary>
    /// <param name="client">The HTTP client to use for requests.</param>
    /// <param name="baseUrl">The base URL for the API endpoints.</param>
    protected BaseClient(HttpClient client, string baseUrl)
    {
        _client = client;
        _baseUrl = baseUrl;
    }

    /// <summary>
    /// Sets the base URL for this client.
    /// </summary>
    /// <param name="baseUrl">The new base URL.</param>
    public void SetBaseUrl(string baseUrl)
    {
        _baseUrl = baseUrl;
    }

    /// <summary>
    /// Gets the current base URL for this client.
    /// </summary>
    /// <returns>The base URL string.</returns>
    public string GetBaseUrl() => _baseUrl;

    /// <summary>
    /// Sets user data from a <see cref="User"/> instance.
    /// </summary>
    /// <param name="user">The user whose credentials to store.</param>
    /// <returns>This client instance for method chaining.</returns>
    public BaseClient WithUser(User user)
    {
        ArgumentNullException.ThrowIfNull(user);
        _userId = user.UserId;
        _apiKey = user.ApiKey;
        _subscriptionKey = user.SubscriptionKey;
        return this;
    }

    /// <summary>
    /// Gets the underlying HTTP client.
    /// </summary>
    protected HttpClient Client => _client;

    /// <summary>
    /// Gets the current base URL.
    /// </summary>
    protected string BaseUrl => _baseUrl;

    // ========================================================================
    // SharedApi methods (equivalent to PHP SharedApi trait)
    // ========================================================================

    /// <summary>
    /// Creates an access token using Basic authentication.
    /// </summary>
    /// <param name="subscriptionKey">The product subscription key.</param>
    /// <param name="userReferenceId">The user reference ID.</param>
    /// <param name="apiKey">The API key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> CreateAccessTokenAsync(
        string subscriptionKey,
        string userReferenceId,
        string apiKey,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Post, $"{_baseUrl}/token/");
        var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{userReferenceId}:{apiKey}"));
        request.Headers.Authorization = new AuthenticationHeaderValue("Basic", credentials);
        request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Checks if an account holder is registered and active in the system.
    /// </summary>
    /// <param name="accountHolderId">The account holder identifier.</param>
    /// <param name="accountHolderIdType">The type of the party ID. Allowed values: msisdn, email, party_code.</param>
    /// <param name="subscriptionKey">The product subscription key.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="token">The bearer token.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> ValidateAccountHolderStatusAsync(
        string accountHolderId,
        string accountHolderIdType,
        string subscriptionKey,
        string targetEnv,
        string token,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Get,
            $"{_baseUrl}/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/active");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);
        request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Gets the account balance.
    /// </summary>
    /// <param name="subscriptionKey">The product subscription key.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="token">The bearer token.</param>
    /// <param name="currency">Optional currency code to get balance for a specific currency.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> GetAccountBalanceAsync(
        string subscriptionKey,
        string targetEnv,
        string token,
        string? currency = null,
        CancellationToken cancellationToken = default)
    {
        var path = currency != null
            ? $"/v1_0/account/balance/{currency}"
            : "/v1_0/account/balance";

        var request = new HttpRequestMessage(HttpMethod.Get, $"{_baseUrl}{path}");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);
        request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Returns personal information of the account holder.
    /// The operation does not need any consent by the account holder.
    /// </summary>
    /// <param name="msisdn">The phone number (MSISDN).</param>
    /// <param name="subscriptionKey">The product subscription key.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="token">The bearer token.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> GetBasicUserInfoAsync(
        string msisdn,
        string subscriptionKey,
        string targetEnv,
        string token,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Get,
            $"{_baseUrl}/v1_0/accountholder/msisdn/{msisdn}/basicuserinfo");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);
        request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Sends an additional notification to an end user.
    /// </summary>
    /// <param name="message">The notification message (max 160 characters).</param>
    /// <param name="subscriptionKey">The product subscription key.</param>
    /// <param name="requestId">The reference ID of the request to pay.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="token">The bearer token.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    /// <exception cref="ArgumentException">Thrown when the message exceeds 160 characters.</exception>
    public async Task<HttpResponseMessage> RequestToPayDeliveryNotificationAsync(
        string message,
        string subscriptionKey,
        string requestId,
        string targetEnv,
        string token,
        CancellationToken cancellationToken = default)
    {
        if (message.Length > 160)
        {
            throw new ArgumentException("Notification message should be 160 characters max.", nameof(message));
        }

        var request = new HttpRequestMessage(HttpMethod.Post,
            $"{_baseUrl}/v1_0/requesttopay/{requestId}/deliverynotification");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("notificationMessage", message);
        request.Headers.Add("X-Target-Environment", targetEnv);
        request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        var body = JsonSerializer.Serialize(new { notificationMessage = message });
        request.Content = new StringContent(body, Encoding.UTF8, "application/json");

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Creates an OAuth2 token.
    /// </summary>
    /// <param name="token">The bearer token.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> CreateOauth2TokenAsync(
        string token,
        string targetEnv,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Post, $"{_baseUrl}/oauth2/token/");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Claims a consent by the account holder for the requested scopes (bc-authorize).
    /// </summary>
    /// <param name="token">The bearer token.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="callbackUrl">Optional callback URL.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> BcAuthorizeAsync(
        string token,
        string targetEnv,
        string? callbackUrl = null,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Post, $"{_baseUrl}/v1_0/bc-authorize");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);

        if (!string.IsNullOrEmpty(callbackUrl))
        {
            request.Headers.Add("X-Callback-Url", callbackUrl);
        }

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }

    /// <summary>
    /// Gets user info with consent (OAuth2 userinfo endpoint).
    /// </summary>
    /// <param name="token">The bearer token.</param>
    /// <param name="targetEnv">The target environment.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The HTTP response.</returns>
    public async Task<HttpResponseMessage> GetUserInfoWithConsentAsync(
        string token,
        string targetEnv,
        CancellationToken cancellationToken = default)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, $"{_baseUrl}/oauth2/v1_0/userinfo");
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Target-Environment", targetEnv);

        return await _client.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}