PolarSharp

A .NET 10 Native AOT-compatible SDK for Polar.sh — the open-source Merchant of Record payment and monetization platform.

v1.2.0+ — what started as a Polar.sh SDK has grown into a full multi-tenant SaaS toolkit. 31 packages cover everything from the raw API client to programmatic merchant onboarding, SQL-backed tenant + identity stores with row-level security, a local catalog with AI-translated product copy, hierarchical reporting, KeyCloak SSO, and bulk fake-data seeding. Pick the pieces you need; the v1.1.0 core SDK keeps working unchanged for hosts that don't.

What You Get

31 NuGet packages, every one AOT-safe, grouped into seven capability areas:

Capability area Packages What it does
Core SDK + webhooks + client isolation PolarSharp, PolarSharp.Webhooks, PolarSharp.MultiTenant, PolarSharp.Templates The v1.1.0 origin story. Full Polar.sh API client, HMAC-verified event handling, per-tenant HttpClient isolation with independent circuit breakers, dotnet new handler scaffolds.
Universal domain model PolarSharp.BaseEntities 15 abstract record bases that mirror Polar's webhook wire format byte-for-byte (Order, Customer, Product, Subscription, etc.) + 6 host-additive bases (Cart, Category, Department, Inventory, Sale). Inherit them in your own types and webhook payloads stop needing translation.
SQL-backed tenant store PolarSharp.MultiTenant.EntityFrameworkCore + .SqlServer / .Sqlite / .PostgreSQL When appsettings.json isn't enough. SQL Server + PostgreSQL get row-level security with an AppMasterAdmin bypass; SQLite gets one .db file per tenant for physical isolation. EF Core query filters + RLS = defense in depth.
Identity + SSO PolarSharp.MultiTenant.Identity + .SqlServer / .Sqlite / .PostgreSQL + .KeyCloak ASP.NET Core IdentityFramework with Guid IDs, M:N user↔tenant memberships, a site-level AppMasterAdmin tier orthogonal to tenant scope, five-layer cross-tenant safeguards, optional KeyCloak SSO via OIDC.
Tenant onboarding PolarSharp.Onboarding Single-call programmatic API (POST /v1/organizations/ + OAT + webhook endpoint) and a resumable wizard with persistent sessions for interactive UI flows. Encrypts in-flight translation API keys at rest. Auto-provisions a TenantAdmin on completion.
Local catalog + AI translation PolarSharp.EcommerceStoreManagement (+ EF Core + 3 providers) + .Translation.Anthropic / .OpenAI / .AzureOpenAI / .Gemini / .Grok Author products, variants, categories, tier groups, discounts, and checkout links locally; publish to Polar idempotently with variant + tier expansion. Three-tier translation provider resolution (per-tenant BYOK → master → disabled). Refund service, license validator, inventory sync, admin audit log.
Reporting PolarSharp.Reporting (+ EF Core + 3 providers) Aggregate KPI reports (revenue, MRR, churn, fulfillment latency) plus lazy three-level hierarchical drilldown — Customers → Orders → Order details. Pre-aggregated columns keep a 10k-customer top-level grid loading in <100ms. Optional snapshot service mirrors Polar to local SQL on a schedule.
Fake data for sandbox / QA PolarSharp.DataSeeding Bogus-backed bulk generators at Demo / QA / Stress scales. Every fake record is tagged IsFakeData=true and filtered by a global EF query predicate; flip a per-tenant toggle to sync fake data to/from Polar's sandbox.

Installation

The full list of 31 packages with version badges is in the GitHub repo README. Common install paths:

Core SDK (the only required package):

dotnet add package PolarSharp

Common opt-ins:

dotnet add package PolarSharp.Webhooks      # HMAC verification, toast notifications, background queues, reconciliation
dotnet add package PolarSharp.MultiTenant   # per-tenant HttpClient isolation with Finbuckle
dotnet new install PolarSharp.Templates     # dotnet new templates for scaffolding webhook handlers
dotnet add package PolarSharp.BaseEntities  # universal domain bases — Order, Customer, Product, etc.

SQL-backed tenant + identity stores (pick the provider that matches your DB):

dotnet add package PolarSharp.MultiTenant.EntityFrameworkCore.SqlServer       # or .Sqlite / .PostgreSQL
dotnet add package PolarSharp.MultiTenant.Identity.SqlServer                  # or .Sqlite / .PostgreSQL
dotnet add package PolarSharp.MultiTenant.Identity.KeyCloak                   # optional OIDC SSO add-on

Tenant onboarding and local catalog:

dotnet add package PolarSharp.Onboarding
dotnet add package PolarSharp.EcommerceStoreManagement.EntityFrameworkCore.SqlServer    # or .Sqlite / .PostgreSQL
dotnet add package PolarSharp.EcommerceStoreManagement.Translation.Anthropic            # or .OpenAI / .AzureOpenAI / .Gemini / .Grok

Reporting and data seeding:

dotnet add package PolarSharp.Reporting.EntityFrameworkCore.SqlServer    # or .Sqlite / .PostgreSQL
dotnet add package PolarSharp.DataSeeding                                # dev-time only; see Data Seeding article for AOT note

Every package depends transitively on the ones it needs — installing a provider package brings in its EF Core base and PolarSharp itself automatically. The packages are distributed via GitHub Packages; see NuGet Deployment for the NuGet.config + PAT setup.

Quick Start

// Program.cs
builder.Services
    .AddPolarInfrastructure(builder.Configuration);

// appsettings.json
{
  "PolarSharp": {
    "Mode": "Test",
    "AccessToken": "tok_sandbox_xxx"
  }
}

// Inject and call
app.MapGet("/orders", async (PolarClient polar, CancellationToken ct) =>
    (await polar.Orders.EmptyPathSegment.GetAsync(cancellationToken: ct))
        .Match(
            onSuccess: orders => Results.Ok(orders),
            onFailure: err    => err.ToHttpResult()));

For the full setup including webhook registration, multi-tenant configuration, identity bootstrap, and onboarding flows, see Getting Started.

Documentation

Every article is linked from the Articles menu in the top navigation. Highlights for the v1.2.0+ ecosystem:

  • Universal Domain Model (BaseEntities) — the 15 + 6 abstract record bases and how host inheritance eliminates webhook mapping
  • Identity and Authorization — 5-role RBAC + 22-permission ABAC, AppMasterAdmin tier, 5-layer cross-tenant safeguards
  • Tenant Onboarding — programmatic single-call API + resumable wizard with conditional next-steps
  • Ecommerce Store Management — local catalog with variants + tiers, 3-tier translation, idempotent publish to Polar
  • Reporting — aggregate KPI reports + hierarchical drilldown for Telerik/MudBlazor grids
  • EF Core Migrations — 12 migration sets, PolarMigrationRunner<TContext>, production checklist
  • Data Seeding — Bogus generators, scale presets, IsFakeData toggle, Polar sandbox sync

API Reference — use the API Reference link in the top navigation bar for the full XML-documented API surface across all 31 packages.

Features

Feature Description
31-package ecosystem Core SDK + 27 opt-in packages across 7 capability areas, all AOT-safe
Full API surface 25+ resource areas generated from the OpenAPI spec via Kiota
Native AOT Zero reflection in hot paths; publishes with dotnet publish -p:PublishAot=true
Resilience Retry, circuit breaker, timeout, hedging
Idempotency Automatic X-Idempotency-Key on mutating requests
API versioning Polar-Version date-pinned header; mismatch detection at startup
Test/Live mode Startup banner + token-prefix sanity check
Result monad Result<TValue, PolarError> — no exceptions on 4xx
Multi-tenant isolation Per-tenant HttpClient + circuit breaker + connection pool + EF Core query filters + database RLS
Identity + SSO ASP.NET Core IdentityFramework with M:N user↔tenant memberships; optional KeyCloak OIDC SSO
Health checks IHealthCheck integration; tags "polar" (core) and "polar-sql" (EF Core)
Observability ActivitySource + IMeterFactory metrics; structured logs with PII redaction
Localization Built-in en-US and es-MX; extensible via IPolarLocalizer
EF Core migrations 12 migration sets across 4 DbContexts × 3 SQL providers; PolarMigrationRunner<TContext> hosted service
Strong-named Assemblies signed; NuGet package signing in CI

License

MIT — View on GitHub

Notice: PolarSharp is an independent open-source project with no affiliation, partnership, or relationship of any kind with Polar.sh or its operators. This software is provided "as is" without warranty of any kind. Use is entirely at your own risk. See the full disclaimer for complete terms.

Edit this page