NotificationHub.Sdk 1.0.0

NotificationHub.Sdk

Client SDK cho Notification Hub — gửi/tra cứu/huỷ notification + quản lý webhook, qua REST hoặc gRPC. Tự lo OAuth2 client_credentials (lấy + refresh access token) cho cả hai đường.

Xem docs/MULTITENANT.md trong repo chính để lấy client_id/client_secret trước khi dùng SDK này.

Cài đặt

dotnet add package NotificationHub.Sdk

Package publish thật trên nuget.org/packages/NotificationHub.Sdk — xem "Phát hành phiên bản mới" bên dưới để biết cách cắt release. Chưa publish phiên bản nào thì build .nupkg bằng dotnet pack src/NotificationHub.Sdk rồi trỏ dotnet nuget add source vào thư mục output, hoặc dùng ProjectReference/ghim vào local NuGet feed nội bộ.

Phát hành phiên bản mới (maintainer)

CI (.github/workflows/publish-sdk.yml) đóng gói + push lên NuGet.org bằng Trusted Publishing (OIDC) — KHÔNG dùng API key dài hạn lưu trong secret. Mỗi lần chạy, workflow tự xin GitHub cấp một OIDC token, đổi nó lấy API key NuGet sống đúng 1 giờ (qua action NuGet/login), dùng ngay cho lần push đó rồi bỏ — không có secret lâu dài nào để rò rỉ hay xoay vòng.

Chuẩn bị 1 lần (tài khoản NuGet.org của bạn):

1. Đăng nhập nuget.org → biểu tượng tài khoản → Trusted Publishing → thêm policy mới:
   • Repository Owner: lqviet45
   • Repository: notification-hub
   • Workflow File: publish-sdk.yml (CHỈ tên file, không kèm đường dẫn .github/workflows/)
   • Environment: nuget-publish (khớp environment: trong workflow — để trống nếu bỏ dòng đó)
2. Repo GitHub → Settings → Secrets and variables → Actions → New repository secret → tên NUGET_USER, value = username nuget.org của bạn (không phải email — action đọc field user từ secret này, xem publish-sdk.yml).
3. (Tuỳ chọn) Settings → Environments → tạo environment nuget-publish, bật "Required reviewers" nếu muốn có người duyệt tay trước mỗi lần publish thật.

Repo private thì policy mới tạo chỉ active tạm 7 ngày — phải publish thành công ít nhất 1 lần trong 7 ngày đó để NuGet khoá policy vĩnh viễn vào đúng repo (chống resurrection attack: xoá repo rồi tạo lại cùng tên để mạo danh). Hết hạn thì quay lại trang Trusted Publishing bấm restart, không cần tạo policy mới.

Mỗi lần release — 1 trong 2 cách:

# Cách 1: tag (đơn giản, gắn version vào lịch sử git)
git tag sdk-v0.2.0
git push origin sdk-v0.2.0

# Cách 2: workflow_dispatch từ tab Actions trên GitHub — không cần tag, nhập
# version thủ công. Dùng khi muốn thử publish bản beta không đại diện 1 commit cụ thể.

Cả hai cách đều: restore → chạy NotificationHub.Sdk.Tests (fail thì KHÔNG publish) → dotnet pack -p:Version=<version> → dotnet nuget push --skip-duplicate. Publish lại đúng version đã có trên NuGet.org sẽ bị bỏ qua thay vì lỗi (NuGet.org vốn cũng từ chối ghi đè version đã index — --skip-duplicate chỉ tránh CI báo lỗi vì việc đó).

Chọn đường: HTTP hay gRPC?

SendNotificationRequest/SendNotificationResult dùng CHUNG cho cả hai — đổi đường truyền không phải sửa chỗ gọi.

Dùng không cần DI

using NotificationHub.Sdk;
using NotificationHub.Sdk.Http;

var options = new NotificationHubOptions
{
    GatewayUrl = "https://api.notification-hub.example",
    ClientId = "app_xxx",
    ClientSecret = "xxx",
};

await using var client = new NotificationHubHttpClient(options);

var result = await client.SendAsync(new SendNotificationRequest(
    UserId: "11111111-1111-1111-1111-111111111111",
    Channel: "SMS",
    Priority: "HIGH",
    TemplateId: "template-id-cua-tenant-ban",
    Payload: new { otp_code = "123456" },
    Category: "otp"));

Console.WriteLine($"{result.Status} — notifId={result.NotifId}");

var status = await client.GetStatusAsync(Guid.Parse(result.NotifId));
Console.WriteLine(status.Status);

gRPC — cùng request/response type, khác client + cần GrpcEndpoint (không qua Kong):

using NotificationHub.Sdk.Grpc;

var options = new NotificationHubOptions
{
    GatewayUrl = "https://api.notification-hub.example",  // vẫn cần — lấy token qua đây
    GrpcEndpoint = "http://localhost:9090",                // dev; prod: https qua LB hỗ trợ gRPC
    ClientId = "app_xxx",
    ClientSecret = "xxx",
};

await using var grpc = new NotificationHubGrpcClient(options);
var result = await grpc.SendAsync(new SendNotificationRequest(
    UserId: "11111111-1111-1111-1111-111111111111",
    Channel: "SMS",
    TemplateId: "template-id-cua-tenant-ban",
    Payload: new { otp_code = "123456" }));

Dùng với DI (ASP.NET Core / generic host)

builder.Services.AddNotificationHubSdk(o =>
{
    o.GatewayUrl = builder.Configuration["NotificationHub:GatewayUrl"]!;
    o.GrpcEndpoint = builder.Configuration["NotificationHub:GrpcEndpoint"];
    o.ClientId = builder.Configuration["NotificationHub:ClientId"]!;
    o.ClientSecret = builder.Configuration["NotificationHub:ClientSecret"]!;
});

Rồi inject NotificationHubHttpClient hoặc NotificationHubGrpcClient (singleton, dùng chung 1 token — không tạo instance mới mỗi request). Không đặt GrpcEndpoint vẫn dùng HTTP client bình thường; gRPC client chỉ lỗi nếu có consumer nào đó thực sự inject nó mà thiếu endpoint.

Xử lý lỗi

Mọi lỗi nghiệp vụ (400/401/403/404/409/429 REST, hoặc RpcException phía gRPC) ném NotificationHubApiException với StatusCode (quy đổi cùng thang HTTP dù đường nào) + Code (SCOPE_REQUIRED, CHANNEL_NOT_ALLOWED, ...). Lỗi lấy token ném riêng NotificationHubAuthException.

try
{
    await client.SendAsync(request);
}
catch (NotificationHubApiException e) when (e.StatusCode == 429)
{
    // vượt quota tenant — chờ rồi thử lại, hoặc xin nâng hạn mức
}
catch (NotificationHubApiException e) when (e.Code == "CHANNEL_NOT_ALLOWED")
{
    // application chưa được cấp channel này — sửa allowedChannels qua Admin API/Console
}

Token rotation

SDK tự retry 1 lần khi server trả 401/UNAUTHENTICATED (kể cả khi cache token phía client còn hạn — vd client_secret vừa bị admin rotate). Không cần tự bắt lỗi này.