meezi/src/Meezi.Core/Interfaces/ISmsService.cs

namespace Meezi.Core.Interfaces;

public record KavenegarAccountInfo(long RemainCredit, string AccountType);

public record BulkSendResult(int SentCount, int FailedCount);

public interface ISmsService
{
    /// <summary>Send a one-time password via Kavenegar Verify/Lookup template.</summary>
    Task SendOtpAsync(string phone, string otp, CancellationToken cancellationToken = default);

    /// <summary>Send a plain-text message to a single recipient.</summary>
    Task SendMessageAsync(string phone, string message, CancellationToken cancellationToken = default);

    /// <summary>
    /// Send the same message to many recipients in batches of up to 200.
    /// Never throws — failures per batch are counted and returned.
    /// </summary>
    Task<BulkSendResult> SendBulkAsync(IReadOnlyList<string> phones, string message, CancellationToken cancellationToken = default);

    /// <summary>Returns credit balance from the Kavenegar account, or null if not configured.</summary>
    Task<KavenegarAccountInfo?> GetAccountInfoAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Bulk send using the CALLER's own provider credentials — marketing SMS is
    /// bring-your-own-provider (each café configures its own API key + sender line).
    /// Never throws — failures per batch are counted and returned.
    /// </summary>
    Task<BulkSendResult> SendBulkWithCredentialsAsync(
        string apiKey,
        string senderNumber,
        IReadOnlyList<string> phones,
        string message,
        CancellationToken cancellationToken = default);

    /// <summary>Credit balance for an EXPLICIT API key (a café's own account), or null on failure.</summary>
    Task<KavenegarAccountInfo?> GetAccountInfoAsync(string apiKey, CancellationToken cancellationToken = default);
}