VwV.Sms.DependencyInjection 1.0.0

VwV.Sms

Built by Vira Web Vorna (VwV) — virawebvorna.ir · arvindev1400@gmail.com. Licensed under MIT.

Independent SMS packages for .NET 8 and .NET 10. No ASP.NET, EF Core, identity model, tenant middleware, database or application dependency. Console, worker, ASP.NET and server-side MAUI/Blazor hosts can use the same contracts. Credentials belong on trusted servers, never browser/WASM/mobile distributed clients.

Installation from NuGet.org

The first public release is 1.0.0, with assemblies for both .NET 8 and .NET 10. It has no Bit dependency. After public upload, install on your trusted server:

dotnet add YourApp.Server package VwV.Sms.DependencyInjection --version 1.0.0

DependencyInjection includes the core and Kavenegar packages transitively. Install VwV.Sms alone for provider-neutral interfaces, or VwV.Sms.Kavenegar for direct construction without the registration helpers. With central package management, add a PackageVersion in Directory.Packages.props and a versionless PackageReference in your project. Keep all three versions aligned.

No GitHub token or private source is required for NuGet.org. Remove old source mappings that force VwV.Sms* to GitHub. Before public upload, download the three .nupkg files attached to the GitHub release and use their directory as a local NuGet source. A GitHub release does not certify NuGet.org publication. The source repository may remain private.

Register a single account

using VwV.Sms;
using VwV.Sms.DependencyInjection;
services.AddVwVSms(configuration).AddKavenegarSmsProvider();
var factory = provider.GetRequiredService<ISmsClientFactory>();
var client = await factory.CreateAsync(cancellationToken: token);
var result = await client.SendAsync(new(["09123456789"], "Your message", Sender: "YOUR_LINE"), token);

{
  "Sms": {
    "MultiTenant": false,
    "DefaultProfile": "primary",
    "Profiles": {
      "primary": {
        "Provider": "kavenegar",
        "Settings": { "ApiKey": "", "VerificationTemplate": "", "TimeoutSeconds": "10" }
      }
    }
  }
}

Supply Sms__Profiles__primary__Settings__ApiKey from protected server environment/secret manager. Empty/invalid credentials fail before transport. An OTP template is required only for configured-default-template verification; other operations do not require one. Sender lines, account permissions, provider template approvals, rate limits, costs and delivery remain vendor responsibilities. All methods are async with cancellation. The low-level IKavenegarService is available to adapters that already have Kavenegar-shaped contracts.

Without Microsoft DI, construct KavenegarTransport, KavenegarConfiguration(new KavenegarOptions(...)), KavenegarService(..., NullLogger.Instance) and KavenegarSmsClient directly. Keep the transport long-lived; the host disposes it. A custom handler is a trusted extension and must not add redirects, unsafe retries or sensitive logging.

Multi-tenant routing

Set Sms:MultiTenant=true and configure explicit Sms:Tenants:north=primary mappings. CreateAsync("north", token) resolves the mapped account. Missing, blank, malformed or unknown tenant IDs fail closed; null never means all tenants or fallback to DefaultProfile. In single-tenant mode, passing a tenant ID is rejected. Profile names permit ASCII letters/digits/hyphen/underscore; configuration tenant keys additionally permit dots (up to 128 characters).

The host must authorize the tenant using authenticated identity or a trusted job payload before calling the factory. The library does not trust HTTP headers or perform application authorization. Register a custom singleton/thread-safe ISmsProfileResolver before AddVwVSms to retrieve secrets asynchronously from a vault/database. Custom resolvers may implement their own tenant-ID format. They must throw SmsConfigurationException for unbound tenants and must not return another tenant's profile. A returned SmsProfile defensively snapshots settings. A created client retains its account snapshot; create a new client after credential rotation. No ambient mutable tenant, cross-tenant cache or provider fallback exists. Background jobs must carry and reauthorize the explicit tenant; do not persist credentials in jobs.

Add an ISmsProvider implementation and register it before AddVwVSms to support another provider without modifying contracts or Kavenegar. Provider names must be unique (case-insensitive); duplicate registrations fail rather than silently select one. Unsupported vendor facilities should fail explicitly. Microsoft DI registration is idempotent and preserves custom transport/resolver/factory registrations.

Operations and delivery semantics

Typed common APIs: SendAsync, SendBatchAsync (up to 200 explicit items, no hidden chunking), VerifyAsync (token/token2/token3/token10/token20, sms/call), StatusAsync and AccountInfoAsync. Scheduling uses DateTimeOffset converted to Unix seconds. Normalized per-message states retain the raw provider status and cost. Succeeded means the API envelope succeeded; inspect every message status separately. In particular, a successful request may contain failed/unknown delivery entries. ProviderData contains sensitive vendor JSON and must be projected/authorized before crossing an API boundary. Do not log or serialize whole request/profile/result objects; redacted ToString is only diagnostic protection, not permission to export their properties.

Cast a capable client to ISmsProviderOperations for all vendor facilities, using KavenegarOperations constants and vendor parameters: send/sendarray/cancel; status/by-receptor/by-local-ID; select/outbox/latest/count; receive/paged inbox/count; account info/config; voice TTS; OTP/template list/details/create/copy/update/delete; media upload/list/details/delete; blocked-line list/add/exists/remove. Receive operations may mark inbox messages as read. Administrative mutation authorization belongs to the host. ExecuteAsync also supports future validated fixed-origin endpoint paths; it does not guarantee that the vendor supports every possible path. Media uses bounded JPEG/GIF/MP4 binary multipart, not caller paths or filenames.

No automatic retry or provider fallback is installed. LocalId is a vendor correlation ID, not an exactly-once guarantee. Timeout, transport failure or malformed response after submission can mean an accepted message with an unknown outcome; OutcomeUncertain indicates reconciliation is required. Persist a host-owned submission/outbox and check vendor status before any deliberate resend. Durable idempotency, quotas, tenant billing, scheduling workers, circuit-breaking policy and delivery webhook verification are host responsibilities. This avoids hiding business/database choices inside a reusable transport. TourismPlatform retains its existing durable attempts, authorization, projections and OTP-proof checks.

Requests use fixed HTTPS api.kavenegar.com, no redirects/cookies/factory URI loggers, a pooled handler and bounded 1–30 second timeout. Responses are limited to 1 MiB and JSON depth 16. OpenTelemetry request instrumentation is suppressed because the vendor places API keys in URL paths. Host-installed packet/EventSource/custom-handler diagnostics must also exclude sensitive vendor URLs; suppression cannot control every external diagnostic collector. Provider messages, keys, recipients and OTP bodies are absent from library logs. Validation is bounded; the provider still validates account-specific limits and supported parameters.

Official reference: https://kavenegar.com/rest.html and https://github.com/kavenegar/kavenegar-dotnet. This adapter preserves the existing consumer's guarded implementation rather than relying on an SDK retry policy.

Playground and validation

Run dotnet run --project VwV.Sms.Playground and open http://127.0.0.1:5291. The Persian/RTL operator UI supports all 31 Kavenegar operations, independent tenant settings, simulation by default, server-memory write-only keys and explicit per-request live confirmation. It includes media progress/manual retry and masked send/delivery reports with CSV/JSON export. See the playground guide for consent, security, ephemeral session limits and delivery semantics. Do not expose this loopback-only developer tool as a production administration portal.

Run dotnet run --project VwV.Sms.Playground.Tests for deterministic consent/tenant/upload/report tests without paid SMS. Existing package tests remain dotnet run --project VwV.Sms.Tests -f net8.0 and -f net10.0; they cover concurrent routing, rotation, malformed responses, cancellation, vendor methods, redaction and provider extension. CI validates isolated package-only consumers for both target frameworks before release. Public publication verifies the registry payload after signing.

HTTP failure diagnostics (preview.2)

An HTTP-level failure now retains its numeric status in ProviderStatus. Failure remains Http with OutcomeUncertain, no automatic retry and no untrusted response-body export. This is diagnostic evidence, not a delivery guarantee or permission to resend. Playground reports show that code instead of losing it. Synthetic 406/407/418/503 tests verify status projection and one transport call.

Public releases and support

See the release guide and changelog. Windows/Linux CI runs synthetic tests and an isolated consumer installed from the built packages. Publication is a separate explicit workflow operation that downloads and verifies the existing GitHub release assets; it does not rebuild packages. Configure a scoped NUGET_API_KEY secret or NUGET_USER with NuGet Trusted Publishing before uploading to NuGet.org. Symbols remain in internal workflow artifacts.

Copyright (c) 2026 Vira Web Vorna (VwV). MIT license. Website: virawebvorna.ir. Email: arvindev1400@gmail.com. Third-party dependency licenses are recorded in consumer-proof.json attached to the release.