Subscrio.Core 1.0.3

Subscrio .NET Core Library

A .NET implementation of the Subscrio subscription management library for managing products, plans, features, customers, subscriptions, and billing cycles.

The entitlement engine that translates subscriptions into feature access.

See the main README for an overview of Subscrio's concepts, architecture, and features.

Installation

Add the NuGet package to your project:

<PackageReference Include="Subscrio.Core" Version="1.0.0" />

Or using the .NET CLI:

dotnet add package Subscrio.Core

Prerequisites:

• .NET 8.0 (LTS - supported until November 2026), .NET 9.0, or .NET 10.0
• PostgreSQL or SQL Server database

The library is multi-targeted: one NuGet package includes builds for all supported frameworks; the correct one is chosen by your project's target framework.

Database and connection

Creating the database

You need a database before using Subscrio. The library does not create the database itself; it only installs and updates schema inside an existing database.

PostgreSQL

• Create a database (e.g. subscrio) using psql, pgAdmin, or your host’s tooling.
• Example with psql:

  psql -U postgres -c "CREATE DATABASE subscrio;"
  

• Ensure the user in your connection string has rights to create tables and run migrations in that database.

SQL Server

• Create a database (e.g. Subscrio) in SQL Server Management Studio or with T-SQL:

  CREATE DATABASE Subscrio;
  

• The login in your connection string must have permission to create tables and run migrations in that database.

Setting the connection string

Set the connection string in one of these ways:

1. Environment variable (recommended for local and production)
   Set DATABASE_URL:

   • PostgreSQL: Host=localhost;Port=5432;Database=subscrio;Username=postgres;Password=yourpassword
   • SQL Server: Server=localhost;Database=Subscrio;User Id=sa;Password=yourpassword;TrustServerCertificate=true

2. ConfigLoader.Load()
ConfigLoader.Load() reads DATABASE_URL (and optionally DATABASE_TYPE, STRIPE_SECRET_KEY) from the process environment. Use this when you configure the app via env vars or launchSettings.

3. Explicit config in code
   Build a SubscrioConfig and set Database.ConnectionString and Database.DatabaseType (e.g. DatabaseType.PostgreSQL or DatabaseType.SqlServer). Use this for custom config sources (e.g. key vault, appsettings).

4. ASP.NET Core appsettings
   You can load connection strings from appsettings.json or other configuration and pass them into the constructor or into the object you use to build SubscrioConfig.

After the database exists and the connection string is set, use Database setup and migrations below to install or update the schema.

Building and testing

From the repo root or from core.dotnet:

cd core.dotnet
dotnet build Subscrio.Core.sln
dotnet test Subscrio.Core.sln

Tests expect a running PostgreSQL instance and use the connection string from the TEST_DATABASE_URL environment variable (or a default local connection string). See tests/README.md for test setup.

Quick Start

using Subscrio.Core;
using Subscrio.Core.Config;

// Load configuration
var config = ConfigLoader.Load();

// Initialize the library
var subscrio = new Subscrio(config);

// Install database schema (first time only)
await subscrio.InstallSchemaAsync("your-admin-passphrase");

// Create a product
var product = await subscrio.Products.CreateProductAsync(new CreateProductDto(
    Key: "my-saas",
    DisplayName: "My SaaS Product"
));

// Create a feature
var feature = await subscrio.Features.CreateFeatureAsync(new CreateFeatureDto(
    Key: "max-users",
    DisplayName: "Maximum Users",
    ValueType: FeatureValueType.Numeric,
    DefaultValue: "10"
));

// Associate feature with product (using keys, not IDs)
await subscrio.Products.AssociateFeatureAsync(product.Key, feature.Key);

// Create a plan (using productKey, not productId)
var plan = await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: product.Key,
    Key: "pro-plan",
    DisplayName: "Pro Plan"
));

// Set feature value on plan (using keys, not IDs)
await subscrio.Plans.SetFeatureValueAsync(plan.Key, feature.Key, "100");

// Create a billing cycle for the plan (required for subscriptions)
var billingCycle = await subscrio.BillingCycles.CreateBillingCycleAsync(new CreateBillingCycleDto(
    PlanKey: plan.Key,
    Key: "monthly",
    DisplayName: "Monthly",
    DurationValue: 1,
    DurationUnit: "months"
));

// Create a customer (using key, not externalId)
var customer = await subscrio.Customers.CreateCustomerAsync(new CreateCustomerDto(
    Key: "customer-123",
    DisplayName: "Acme Corp"
));

// Create a subscription (using keys and billingCycleKey, not IDs)
var subscription = await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "sub-001",
    CustomerKey: customer.Key,
    BillingCycleKey: billingCycle.Key
));

// Check feature access (requires customerKey, productKey, and featureKey)
var maxUsers = await subscrio.FeatureChecker.GetValueForCustomerAsync(
    customer.Key,
    product.Key,
    "max-users"
);
Console.WriteLine($"Customer can have {maxUsers} users"); // "100"

Dependency Injection

Subscrio supports dependency injection and can be registered in your DI container. This is the recommended approach for web applications and provides better lifetime management.

Quick setup (when you want to use DI)

1. Add the using for the extension: using Subscrio.Core.DependencyInjection;
   (You may also need using Microsoft.Extensions.DependencyInjection; for ServiceLifetime if not in scope.)

2. Register Subscrio in your host builder (e.g. in Program.cs):

   var config = ConfigLoader.Load(); // or build SubscrioConfig from appsettings/options
   builder.Services.AddSubscrio(config, ServiceLifetime.Scoped);
   

3. Inject Subscrio where you need it: constructor injection in controllers or services, or as a parameter in minimal API handlers (e.g. app.MapGet("/products", async (Subscrio subscrio) => ...)).

Config from appsettings (optional): You can build SubscrioConfig from your own config (e.g. builder.Configuration or IOptions) and pass it to AddSubscrio. The examples below use ConfigLoader.Load() for simplicity.

See the examples below for full ASP.NET Core, console, and controller usage.

Registration

ASP.NET Core Web API

using Subscrio.Core;
using Subscrio.Core.Config;
using Subscrio.Core.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Load configuration
var config = ConfigLoader.Load();

// Register Subscrio with Scoped lifetime (recommended for web apps)
builder.Services.AddSubscrio(config, ServiceLifetime.Scoped);

var app = builder.Build();

// Use in controllers
app.MapGet("/products", async (Subscrio subscrio) =>
{
    var products = await subscrio.Products.ListProductsAsync();
    return Results.Ok(products);
});

app.Run();

Console Application with DI

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Subscrio.Core;
using Subscrio.Core.Config;
using Subscrio.Core.DependencyInjection;

var config = ConfigLoader.Load();

var services = new ServiceCollection();
services.AddSubscrio(config, ServiceLifetime.Scoped);

var serviceProvider = services.BuildServiceProvider();

// Use scoped service
using var scope = serviceProvider.CreateScope();
var subscrio = scope.ServiceProvider.GetRequiredService<Subscrio>();

var products = await subscrio.Products.ListProductsAsync();

Controller Injection

using Microsoft.AspNetCore.Mvc;
using Subscrio.Core;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly Subscrio _subscrio;

    public ProductsController(Subscrio subscrio)
    {
        _subscrio = subscrio; // Injected by DI
    }

    [HttpGet]
    public async Task<ActionResult<List<ProductDto>>> GetProducts()
    {
        var products = await _subscrio.Products.ListProductsAsync();
        return Ok(products);
    }

    [HttpPost]
    public async Task<ActionResult<ProductDto>> CreateProduct(CreateProductDto dto)
    {
        var product = await _subscrio.Products.CreateProductAsync(dto);
        return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
    }
}

Service Lifetime Options

The AddSubscrio() method accepts a ServiceLifetime parameter:

Scoped (Recommended for Web Applications)

services.AddSubscrio(config, ServiceLifetime.Scoped);

• When to use: ASP.NET Core web applications
• Behavior: One Subscrio instance per HTTP request
• Benefits:
  • Each request gets a fresh Subscrio instance
  • Each instance creates its own DbContext
  • Change tracker is clean for each request
  • No tracking conflicts between requests
  • Proper resource cleanup after request completes

Transient

services.AddSubscrio(config, ServiceLifetime.Transient);

• When to use: Console applications, background services, or when you need a new instance each time
• Behavior: New Subscrio instance every time it's requested
• Benefits: Maximum isolation, each operation gets a fresh instance

Singleton

services.AddSubscrio(config, ServiceLifetime.Singleton);

• When to use: Rarely recommended - only if you want a single instance for the entire application lifetime
• Behavior: One Subscrio instance shared across the entire application
• Warning: Can cause EF Core tracking conflicts if multiple operations use the same instance
• Not recommended for web applications

How Subscrio Creates DbContext

Subscrio creates its own DbContext internally when instantiated. This means:

• With Scoped lifetime: Each scope (HTTP request) gets a new Subscrio → new DbContext → clean change tracker
• With Transient lifetime: Each request gets a new Subscrio → new DbContext → clean change tracker
• With Singleton lifetime: Single Subscrio → single DbContext → potential tracking conflicts

Best Practice: Use ServiceLifetime.Scoped for web applications to ensure proper isolation and resource management.

API Reference

Core Services

• subscrio.Products - Product management
• subscrio.Features - Feature flag management
• subscrio.Plans - Subscription plan management
• subscrio.BillingCycles - Billing cycle management
• subscrio.Customers - Customer management
• subscrio.Subscriptions - Subscription lifecycle
• subscrio.FeatureChecker - Feature access checking
• subscrio.Stripe - Stripe integration

Instance Methods

• InstallSchemaAsync(adminPassphrase) - Install database schema
• VerifySchemaAsync() - Check if schema is installed (returns version string or null)
• MigrateAsync() - Run database migrations
• Dispose() - Clean up resources (implements IDisposable)

Configuration

Configuration Structure

var config = new SubscrioConfig
{
    Database = new DatabaseConfig
    {
        ConnectionString = "Host=localhost;Port=5432;Database=subscrio;Username=postgres;Password=password",
        DatabaseType = DatabaseType.PostgreSQL, // or DatabaseType.SqlServer
        Ssl = false,
        PoolSize = 10
    },
    Stripe = new StripeConfig
    {
        SecretKey = "sk_test_..." // Optional
    }
};

Loading Configuration

From Environment Variables

var config = ConfigLoader.Load();

This reads from:

• DATABASE_URL - Database connection string
• DATABASE_TYPE - "PostgreSQL" or "SqlServer"
• STRIPE_SECRET_KEY - Stripe secret key (optional)

From Custom Source

var config = new SubscrioConfig
{
    Database = new DatabaseConfig
    {
        ConnectionString = "your-connection-string",
        DatabaseType = DatabaseType.PostgreSQL
    }
};

Database setup and migrations

Summary of how to get the database ready and keep it up to date:

First-time schema installation

var subscrio = new Subscrio(config);
await subscrio.InstallSchemaAsync("your-secure-admin-passphrase");

This creates every required table and stores the hashed admin passphrase. Run it once per database.

Checking if schema is installed

var version = await subscrio.VerifySchemaAsync();
if (version == null)
{
    await subscrio.InstallSchemaAsync("your-admin-passphrase");
}

Use this on startup if you want to install the schema only when it is missing.

Running migrations

After upgrading the Subscrio library, run migrations so the database schema stays in sync:

var migrationsApplied = await subscrio.MigrateAsync();
Console.WriteLine($"Applied {migrationsApplied} migrations");

Call MigrateAsync() during startup or as part of your deployment; it is safe to call when there are no pending migrations (it will apply zero and return 0).

Usage Examples

Create a Product with Features

// Create product
var product = await subscrio.Products.CreateProductAsync(new CreateProductDto(
    Key: "saas-platform",
    DisplayName: "SaaS Platform"
));

// Create features
var maxProjects = await subscrio.Features.CreateFeatureAsync(new CreateFeatureDto(
    Key: "max-projects",
    DisplayName: "Max Projects",
    ValueType: FeatureValueType.Numeric,
    DefaultValue: "10"
));

var ganttCharts = await subscrio.Features.CreateFeatureAsync(new CreateFeatureDto(
    Key: "gantt-charts",
    DisplayName: "Gantt Charts",
    ValueType: FeatureValueType.Toggle,
    DefaultValue: "false"
));

// Associate features with product
await subscrio.Products.AssociateFeatureAsync(product.Key, maxProjects.Key);
await subscrio.Products.AssociateFeatureAsync(product.Key, ganttCharts.Key);

Create Plans with Feature Values

// Create plan
var basicPlan = await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: product.Key,
    Key: "basic",
    DisplayName: "Basic Plan"
));

var proPlan = await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: product.Key,
    Key: "pro",
    DisplayName: "Pro Plan"
));

// Set feature values for plans
await subscrio.Plans.SetFeatureValueAsync(proPlan.Key, maxProjects.Key, "50");
await subscrio.Plans.SetFeatureValueAsync(proPlan.Key, ganttCharts.Key, "true");

Create Billing Cycles

// Create monthly billing cycle
var monthly = await subscrio.BillingCycles.CreateBillingCycleAsync(new CreateBillingCycleDto(
    PlanKey: proPlan.Key,
    Key: "pro-monthly",
    DisplayName: "Pro Monthly",
    DurationValue: 1,
    DurationUnit: "months"
));

// Create yearly billing cycle
var yearly = await subscrio.BillingCycles.CreateBillingCycleAsync(new CreateBillingCycleDto(
    PlanKey: proPlan.Key,
    Key: "pro-yearly",
    DisplayName: "Pro Yearly",
    DurationValue: 1,
    DurationUnit: "years"
));

Create Customers and Subscriptions

// Create customer
var customer = await subscrio.Customers.CreateCustomerAsync(new CreateCustomerDto(
    ExternalId: "customer-123",
    DisplayName: "John Doe"
));

// Create subscription
var subscription = await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "sub-001",
    CustomerKey: customer.Key,
    BillingCycleKey: monthly.Key
));

// Add feature override
await subscrio.Subscriptions.AddFeatureOverrideAsync(
    subscription.Key,
    maxProjects.Key,
    "100",
    OverrideType.Permanent
);

Check Feature Values

// Check if feature is enabled
var hasGanttCharts = await subscrio.FeatureChecker.IsEnabledAsync(
    customer.ExternalId,
    ganttCharts.Key
);

// Get feature value
var maxProjectsValue = await subscrio.FeatureChecker.GetValueAsync(
    customer.ExternalId,
    maxProjects.Key
);

// Get all features
var allFeatures = await subscrio.FeatureChecker.GetAllFeaturesAsync(customer.ExternalId);

Feature Resolution Hierarchy

Feature values are resolved using a smart hierarchy. See the main README for details.

Stripe Integration

Subscrio integrates with Stripe for payment processing. See the main README for an overview.

Important: Subscrio does NOT verify Stripe webhook signatures. You must verify signatures before passing events to Subscrio.

Process Stripe Webhooks

using Stripe;

// In your webhook endpoint (after verifying Stripe signature)
[HttpPost("webhooks/stripe")]
public async Task<IActionResult> HandleStripeWebhook()
{
    var json = await new StreamReader(Request.Body).ReadToEndAsync();
    var stripeSignature = Request.Headers["Stripe-Signature"].ToString();
    
    try
    {
        // Verify webhook signature
        var stripeEvent = EventUtility.ConstructEvent(
            json,
            stripeSignature,
            _configuration["Stripe:WebhookSecret"]
        );
        
        // Process verified event
        await _subscrio.Stripe.ProcessStripeEventAsync(stripeEvent);
        return Ok(new { received = true });
    }
    catch (StripeException ex)
    {
        return BadRequest(new { error = ex.Message });
    }
}

Create Stripe Subscription

var subscription = await subscrio.Stripe.CreateStripeSubscriptionAsync(
    customerExternalId: customer.ExternalId,
    planKey: proPlan.Key,
    renewalCycleKey: monthly.Key
);

.NET Support

Full .NET support with comprehensive type definitions and async/await patterns:

using Subscrio.Core;
using Subscrio.Core.Dtos;

// All APIs are fully typed
ProductDto product = await subscrio.Products.CreateProductAsync(new CreateProductDto(
    Key: "my-product",
    DisplayName: "My Product"
));

// DTOs are strongly typed
var feature = await subscrio.Features.CreateFeatureAsync(new CreateFeatureDto(
    Key: "max-projects",
    DisplayName: "Max Projects",
    ValueType: FeatureValueType.Numeric,
    DefaultValue: "10"
));

Key Concepts

Keys vs IDs: All public APIs use keys (string identifiers like "my-product") rather than internal IDs. Keys are:

• Human-readable and memorable
• Globally unique within their scope
• Immutable once created
• Used in all method calls and references

DTOs: All create/update operations use DTOs (Data Transfer Objects) with validation:

• CreateProductDto, CreateFeatureDto, CreatePlanDto, etc.
• All fields are validated before processing
• Type-safe with full C# type inference

Async/Await: All operations are asynchronous:

• All methods return Task<T> or Task
• Use await for all Subscrio operations
• Proper async/await patterns throughout

Dependency Injection: Recommended for web applications:

• Register with AddSubscrio() extension method
• Use ServiceLifetime.Scoped for web apps
• Automatic resource management

Best Practices

1. Use Dependency Injection - Register Subscrio with AddSubscrio() in web applications
2. Scoped Lifetime - Use ServiceLifetime.Scoped for web apps to avoid tracking conflicts
3. Schema Installation - Run InstallSchemaAsync() once during application startup
4. Error Handling - Handle ValidationException, NotFoundException, ConflictException appropriately
5. Feature Keys - Use lowercase alphanumeric keys with hyphens (e.g., max-projects)
6. Customer External IDs - Use your own customer identifiers for easy integration
7. Database Connections - Subscrio manages its own DbContext lifecycle based on service lifetime

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Support

• 📖 Main Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📚 Testing Guide
• 📋 Full Specifications