NotifySaaS.Client 1.2.0

NotifySaaS.Client - C# Integration SDK (.NET Standard 2.0)

A lightweight, high-performance C# Client SDK for integrating with the NotifySaaS Notification Platform. Built targetting .NET Standard 2.0 to ensure maximum compatibility across legacy .NET Framework applications, modern .NET Core, and .NET 6/7/8+ microservices.

Features

• Decoupled Contracts: Zero dependencies on internal domain databases or models.
• Typed HTTP Client: Uses HttpClientFactory patterns under the hood for optimal connection pooling.
• Dependency Injection: Seamless registration extensions using standard Microsoft DI interfaces.
• Type-safe Enums: Includes client-side mapping for message priorities and channels (Email, SMS, Push, SignalR).
• Webhook Signature Verification: Direct helper to validate X-Platform-Signature payload authenticity (HMAC-SHA256).
• SignalR Hub URL Builder: Utility helper to construct WebSocket URLs with access token parameters for instant client-side connections.

Installation

Install the package via NuGet CLI:

dotnet add package NotifySaaS.Client

Or using the Package Manager Console:

Install-Package NotifySaaS.Client

Getting Started

1. Register the Client in your Application Startup

Inject the client using the AddNotifySaaSClient extensions inside Program.cs or Startup.cs:

using NotificationService.Client;

var builder = WebApplication.CreateBuilder(args);

// Register the NotifySaaS client SDK
builder.Services.AddNotifySaaSClient(options =>
{
    options.BaseUrl = "http://notifysaas.runasp.net/"; // The address of the NotifySaaS platform
    options.TenantId = "acme-corp";                 // Your registered Tenant ID
    options.ApiKey = "ns_app_your_secret_api_key";  // The API key generated for your application
});

2. Inject and Use the Client

Inject INotifySaaSClient into your services, APIs, or controllers:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using NotificationService.Client;

public class BookingService
{
    private readonly INotifySaaSClient _notifyClient;

    // SDK client injected automatically
    public BookingService(INotifySaaSClient notifyClient)
    {
        _notifyClient = notifyClient;
    }

    public async Task ConfirmBookingAsync()
    {
        var request = new PublishNotificationRequest
        {
            EventName = "booking.created", // Map to the platform template event name
            Priority = NotificationPriority.Normal,
            RequestedBy = "booking-service-backend",
            
            // Context variables passed to the dynamic template placeholders
            Payload = new Dictionary<string, object?>
            {
                { "bookingId", "BKG-99201" },
                { "customerName", "Sara Ahmed" },
                { "venueName", "Rotana Hall" },
                { "bookingDate", "2026-08-15" }
            },
            
            // Define one or more recipients across different channels
            Recipients = new List<NotificationRecipientDto>
            {
                new()
                {
                    UserId = "customer-441",
                    TargetType = TargetType.Email,
                    Email = "sara.ahmed@example.com"
                },
                new()
                {
                    UserId = "customer-441",
                    TargetType = TargetType.Sms,
                    PhoneNumber = "+966500000000"
                }
            }
        };

        PublishNotificationResponse response = await _notifyClient.PublishAsync(request);

        if (response.Success)
        {
            Console.WriteLine($"Notification queued successfully. ID: {response.NotificationId}");
        }
        else
        {
            Console.WriteLine($"Error triggering notification: {response.ErrorMessage}");
        }
    }
}

3. Verify Webhook Signatures

To verify that webhooks received by your backend are authentic and originated from our servers, use the WebhookSecurity helper to validate the request's HMAC-SHA256 signature:

using NotificationService.Client;

// Get the raw request body string and the X-Platform-Signature header
string rawRequestBody = await new StreamReader(Request.Body).ReadToEndAsync();
string signatureHeader = Request.Headers["X-Platform-Signature"];
string secretToken = "your_webhook_subscription_secret_token";

bool isValid = WebhookSecurity.VerifySignature(rawRequestBody, signatureHeader, secretToken);

if (isValid)
{
    // Process the webhook delivery success or failure event
}

4. Build SignalR Connection Hub URLs

To connect your browser, desktop, or mobile frontend applications to receive real-time, in-app notifications directly via WebSockets, construct the authenticated hub URL using the SignalRHubHelper:

using NotificationService.Client;

string connectionHubUrl = SignalRHubHelper.BuildHubUrl(
    baseUrl: "http://notifysaas.runasp.net",
    apiKey: "ns_app_your_secret_api_key",
    new SignalRHubConnectionOptions
    {
        UserId = "user_12345",
        ApplicationId = Guid.Parse("11111111-2222-3333-4444-555555555555"),
        ApplicationTenantId = "branch-a",
        UserType = "Customer"
    }
);

// Output:
// http://notifysaas.runasp.net/hubs/notifications?access_token=...&userId=user_12345&applicationId=...&applicationTenantId=branch-a&userType=Customer

For browser apps, request permission and subscribe to the real-time event:

import * as signalR from "@microsoft/signalr";

async function connectNotifications(hubUrl) {
  if ("Notification" in window && Notification.permission === "default") {
    await Notification.requestPermission();
  }

  const connection = new signalR.HubConnectionBuilder()
    .withUrl(hubUrl)
    .withAutomaticReconnect()
    .build();

  connection.on("ReceiveNotification", (eventName, payload) => {
    if ("Notification" in window && Notification.permission === "granted") {
      new Notification(payload.title ?? eventName, {
        body: payload.message ?? "",
        data: payload
      });
    }
  });

  await connection.start();
  return connection;
}

Data Model Contracts

Enums

NotificationPriority

• Low (1) - Queue for non-urgent tasks.
• Normal (2) - Default queue processing.
• High (3) - Enqueues ahead of normal messages.
• Critical (4) - Bypasses rate-limits and sends immediately.

TargetType

• User (0) - Generic identifier mapping.
• Email (1) - Renders and sends via configured email gateway.
• Sms (2) - Dispatches SMS messages to mobile carriers.
• Push (3) - Sends FCM mobile notification payloads.
• SignalR (4) - Transmits web-socket push updates.

دليل الاستخدام السريع (باللغة العربية)

تم تصميم هذا الـ SDK لتسهيل ربط وتكامل تطبيقاتك البرمجية المبنية على بيئة .NET مع منصة إشعارات NotifySaaS دون تكبد عناء إنشاء طلبات HTTP يدوياً.

خطوات العمل:

1. قم بتثبيت الحزمة عبر موجه الأوامر: dotnet add package NotifySaaS.Client

2. قم بتهيئة الإعدادات في ملف Program.cs بتمرير معرف المستأجر ومفتاح التوثيق الخاص بتطبيقك:

   builder.Services.AddNotifySaaSClient(opt => {
       opt.BaseUrl = "http://notifysaas.runasp.net/";
       opt.TenantId = "معرف-المستأجر-الخاص-بك";
       opt.ApiKey = "مفتاح-اتصال-التطبيق-المولد";
   });
   

3. قم بحقن الواجهة INotifySaaSClient في أي خدمة برمجية واستدعاء دالة PublishAsync مع تمرير كائن الطلب والمستلمين.

4. التحقق من التوقيع الرقمي للويب هوك (Webhook HMAC Signature Verification): عند استلام حدث الويب هوك، قم بالتحقق من صحته ومصدره عبر الواجهة الأمنية الموفرة:

   bool isValid = WebhookSecurity.VerifySignature(rawBody, signatureHeader, secretToken);
   

5. توليد روابط الاتصال بـ SignalR للإشعارات اللحظية: لتسهيل الاتصال من واجهات العميل (مثل تطبيقات الويب والموبايل)، قم بتوليد رابط الاتصال المشفر:

   string url = SignalRHubHelper.BuildHubUrl("http://notifysaas.runasp.net", apiKey, userId);
   

License

This client SDK is licensed under the MIT License. Feel free to download, use, and fork.