SMS API w C# / .NET 8: HttpClient, retry i webhooki

dotnet new web -n SmsDemo
cd SmsDemo
dotnet user-secrets init
dotnet user-secrets set "Przypominamy:ApiKey" "pk_test_..."

using System.Text.Json.Serialization;

namespace Przypominamy;

// Obiekt wiadomości zwracany przez API (HTTP 201). Nazwy pól mapuje SnakeCaseLower.
public sealed record SmsMessage(
    string Id,
    string Status,
    string To,
    string From,
    string Text,
    int Parts,
    int CostGrosze,
    string? Reference,
    DateTimeOffset? SendAt,
    DateTimeOffset? DeliveredAt,
    string? Error,
    DateTimeOffset CreatedAt,
    DateTimeOffset UpdatedAt);

// Ciało POST /v1/messages. To jest string albo tablica stringów (do 500 numerów).
public sealed record SendSmsRequest(
    object To,
    string Text,
    string? From = null,
    DateTimeOffset? SendAt = null,
    string? Reference = null);

// Koperta błędu: { "error": { code, message, param }, "request_id" }
public sealed record ApiErrorBody(string Code, string Message, string? Param);
public sealed record ApiErrorEnvelope(ApiErrorBody Error, string? RequestId);

public sealed class PrzypominamyException : Exception
{
    public int StatusCode { get; }
    public string Code { get; }
    public string? Param { get; }
    public string? RequestId { get; }
    public TimeSpan? RetryAfter { get; }

    public PrzypominamyException(int statusCode, string code, string message,
        string? param, string? requestId, TimeSpan? retryAfter)
        : base($"przypominamy: {code} ({statusCode}): {message} [request_id={requestId}]")
    {
        StatusCode = statusCode;
        Code = code;
        Param = param;
        RequestId = requestId;
        RetryAfter = retryAfter;
    }

    // 429 i 5xx warto ponowić; 400/401/402 nie.
    public bool IsRetryable => Code == "rate_limited" || StatusCode >= 500;
}

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

namespace Przypominamy;

public sealed class PrzypominamyClient
{
    private static readonly JsonSerializerOptions Json = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    };

    private readonly HttpClient _http;

    // HttpClient przychodzi z IHttpClientFactory: BaseAddress, Authorization i Timeout są już ustawione.
    public PrzypominamyClient(HttpClient http) => _http = http;

    public Task<SmsMessage> SendAsync(string to, string text, string? from = null,
        string? reference = null, string? idempotencyKey = null, CancellationToken ct = default)
        => PostAsync<SmsMessage>("messages", new SendSmsRequest(to, text, from, null, reference), idempotencyKey, ct);

    public Task<SmsMessage[]> SendManyAsync(IReadOnlyList<string> to, string text, string? from = null,
        string? reference = null, string? idempotencyKey = null, CancellationToken ct = default)
    {
        if (to.Count > 500) throw new ArgumentException("Maksymalnie 500 odbiorców w jednym żądaniu.", nameof(to));
        return PostAsync<SmsMessage[]>("messages", new SendSmsRequest(to, text, from, null, reference), idempotencyKey, ct);
    }

    public Task<SmsMessage> GetAsync(string id, CancellationToken ct = default)
        => SendCoreAsync<SmsMessage>(new HttpRequestMessage(HttpMethod.Get, $"messages/{id}"), ct);

    private Task<T> PostAsync<T>(string path, object body, string? idempotencyKey, CancellationToken ct)
    {
        var request = new HttpRequestMessage(HttpMethod.Post, path)
        {
            Content = JsonContent.Create(body, options: Json),
        };
        if (idempotencyKey is not null)
            request.Headers.Add("Idempotency-Key", idempotencyKey);
        return SendCoreAsync<T>(request, ct);
    }

    private async Task<T> SendCoreAsync<T>(HttpRequestMessage request, CancellationToken ct)
    {
        using var response = await _http.SendAsync(request, ct);
        if (!response.IsSuccessStatusCode)
            throw await ToExceptionAsync(response, ct);

        return await response.Content.ReadFromJsonAsync<T>(Json, ct)
               ?? throw new PrzypominamyException((int)response.StatusCode, "empty_response",
                   "Pusta odpowiedź API", null, null, null);
    }

    private static async Task<PrzypominamyException> ToExceptionAsync(HttpResponseMessage response, CancellationToken ct)
    {
        ApiErrorEnvelope? envelope = null;
        try { envelope = await response.Content.ReadFromJsonAsync<ApiErrorEnvelope>(Json, ct); }
        catch (JsonException) { /* body nie jest JSON-em, np. odpowiedź proxy */ }

        var status = (int)response.StatusCode;
        return new PrzypominamyException(
            status,
            envelope?.Error?.Code ?? $"http_{status}",
            envelope?.Error?.Message ?? response.ReasonPhrase ?? "Błąd HTTP",
            envelope?.Error?.Param,
            envelope?.RequestId,
            response.Headers.RetryAfter?.Delta);
    }
}

using System.Net.Http.Headers;
using Przypominamy;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient<PrzypominamyClient>(client =>
{
    client.BaseAddress = new Uri("https://api.przypominamy.com/v1/"); // ukośnik na końcu jest istotny
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", builder.Configuration["Przypominamy:ApiKey"]);
    client.Timeout = TimeSpan.FromSeconds(10);
});

var app = builder.Build();

app.MapPost("/wizyty/{id:int}/przypomnij", async (int id, PrzypominamyClient sms, CancellationToken ct) =>
{
    var msg = await sms.SendAsync(
        to: "+48600123456",
        text: "Przypominamy o wizycie jutro o 14:00.",
        reference: $"wizyta-{id}",
        idempotencyKey: $"wizyta-{id}-przypomnienie",
        ct: ct);

    return Results.Ok(new { msg.Id, msg.Status, msg.Parts, msg.CostGrosze }); // msg_… queued 1 15
});

app.Run();

var numery = new[] { "+48600123456", "+48600234567", "+48600345678" };

SmsMessage[] wyniki = await sms.SendManyAsync(
    numery,
    "Promocja -20% tylko do niedzieli. Kod: SMS20",
    from: "SKLEP",
    reference: "promo-2026-09",
    idempotencyKey: "promo-2026-09-batch-1");

foreach (var m in wyniki)
    Console.WriteLine($"{m.To} -> {m.Status} {m.Error}");

var koszt = wyniki.Sum(m => m.CostGrosze) / 100m;
Console.WriteLine($"Koszt: {koszt} zł");

var opcje = new ParallelOptions { MaxDegreeOfParallelism = 8, CancellationToken = ct };

await Parallel.ForEachAsync(wizyty, opcje, async (w, token) =>
{
    try
    {
        await sms.SendAsync(
            to: w.Telefon,
            text: $"Cześć {w.Imie}, wizyta jutro o {w.Godzina}. Potwierdź odpisując TAK.",
            reference: $"wizyta-{w.Id}",
            idempotencyKey: $"wizyta-{w.Id}-przypomnienie",
            ct: token);
    }
    catch (PrzypominamyException ex)
    {
        logger.LogWarning("Wizyta {Id}: {Code} {RequestId}", w.Id, ex.Code, ex.RequestId);
    }
});

namespace Przypominamy;

public static class PrzypominamyClientExtensions
{
    // Ponawia 429 i 5xx oraz błędy sieci, zawsze z tym samym idempotencyKey,
    // więc timeout po stronie klienta nie skończy się podwójnym SMS-em.
    public static async Task<SmsMessage> SendWithRetryAsync(this PrzypominamyClient client,
        string to, string text, string idempotencyKey, string? reference = null,
        int attempts = 3, CancellationToken ct = default)
    {
        for (var i = 0; ; i++)
        {
            try
            {
                return await client.SendAsync(to, text, reference: reference, idempotencyKey: idempotencyKey, ct: ct);
            }
            catch (PrzypominamyException ex) when (ex.IsRetryable && i < attempts - 1)
            {
                var delay = ex.RetryAfter ?? TimeSpan.FromSeconds(Math.Pow(2, i)); // 1 s, 2 s, 4 s…
                await Task.Delay(delay, ct);
            }
            catch (HttpRequestException) when (i < attempts - 1)
            {
                await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, i)), ct);
            }
            catch (TaskCanceledException) when (!ct.IsCancellationRequested && i < attempts - 1)
            {
                // timeout HttpClient (nie anulowanie przez wywołującego)
                await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, i)), ct);
            }
        }
    }
}

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

// Rejestracja w Program.cs:
// app.MapPost("/webhooks/sms", SmsWebhook.HandleAsync);

public static class SmsWebhook
{
    private static readonly JsonSerializerOptions Json = new() { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower };

    public sealed record WebhookMessage(string Id, string Status, string To, string? Reference, string? Error);
    public sealed record WebhookData(WebhookMessage Message);
    public sealed record WebhookEvent(string Id, string Type, DateTimeOffset CreatedAt, WebhookData Data);

    public static async Task<IResult> HandleAsync(HttpRequest req, IConfiguration cfg, ILogger<WebhookEvent> logger)
    {
        // Surowe body — podpis liczony jest z bajtów, nie ze sparsowanego JSON-a.
        using var reader = new StreamReader(req.Body, Encoding.UTF8);
        var raw = await reader.ReadToEndAsync();

        var secret = cfg["Przypominamy:WebhookSecret"] ?? throw new InvalidOperationException("Brak WebhookSecret");
        if (!VerifySignature(req.Headers["X-Przypominamy-Signature"].ToString(), raw, secret, tolerance: 300))
            return Results.StatusCode(StatusCodes.Status403Forbidden);

        var ev = JsonSerializer.Deserialize<WebhookEvent>(raw, Json);
        if (ev is null) return Results.BadRequest();

        // Odpowiedz 200 od razu; ciężką pracę oddaj do kolejki / IHostedService.
        logger.LogInformation("{Type} {Id} -> {Status} (ref={Reference})",
            ev.Type, ev.Data.Message.Id, ev.Data.Message.Status, ev.Data.Message.Reference);

        return Results.Ok();
    }

    public static bool VerifySignature(string header, string rawBody, string secret, int tolerance)
    {
        string? t = null, v1 = null;
        foreach (var part in header.Split(','))
        {
            var kv = part.Trim().Split('=', 2);
            if (kv.Length != 2) continue;
            if (kv[0] == "t") t = kv[1];
            else if (kv[0] == "v1") v1 = kv[1];
        }
        if (t is null || v1 is null || !long.TryParse(t, out var ts)) return false;

        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - ts) > tolerance) return false;

        byte[] expected = HMACSHA256.HashData(
            Encoding.UTF8.GetBytes(secret),
            Encoding.UTF8.GetBytes($"{t}.{rawBody}"));

        byte[] received;
        try { received = Convert.FromHexString(v1); }
        catch (FormatException) { return false; }

        return CryptographicOperations.FixedTimeEquals(received, expected); // porównanie w stałym czasie
    }
}