Subscrio Core API Reference

Complete documentation of all data structures and methods exposed by Subscrio Core (TypeScript: core.typescript, .NET: core.dotnet).

Main Class

Subscrio

import { Subscrio } from 'core.typescript';

const subscrio = new Subscrio({
  database: {
    connectionString: process.env.DATABASE_URL
  }
});

using Subscrio.Core;

var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig
    {
        ConnectionString = Environment.GetEnvironmentVariable("DATABASE_URL") ?? ""
    }
});

Method Catalog

Method Reference

Constructor

Description

Instantiates the core library, initializes the database connection, and wires every repository and service so callers can use Subscrio synchronously after construction.

Signature

new Subscrio(config: SubscrioConfig)

new Subscrio(SubscrioConfig config)

Inputs

Input Properties

• SubscrioConfig – high-level shape that includes the database, stripe, and logging objects defined later in this page.

Returns

Return Properties

Expected Results

• Initializes a Postgres database connection using config.database.
• Constructs repository instances and wires each service with its dependencies.
• Keeps a shared schema installer for schema management helpers.

Potential Errors

Example

const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! },
  adminPassphrase: process.env.ADMIN_PASSPHRASE
});

var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig { ConnectionString = Environment.GetEnvironmentVariable("DATABASE_URL")! },
    AdminPassphrase = Environment.GetEnvironmentVariable("ADMIN_PASSPHRASE")
});

Configuration object

Subscrio consumes a strongly typed config. Only database.connectionString (TypeScript) / Database.ConnectionString (.NET) is required; every other field is optional.

export interface SubscrioConfig {
  database: {
    connectionString: string;
    ssl?: boolean;
    poolSize?: number;
  };
  adminPassphrase?: string;
  stripe?: { secretKey: string };
  logging?: { level: 'debug' | 'info' | 'warn' | 'error' };
  initialConfig?: InitialConfigSync;  // { type: 'file', filePath: string } | { type: 'json', config: ConfigSyncDto }
}

public class SubscrioConfig
{
    public required DatabaseConfig Database { get; init; }
    public string? AdminPassphrase { get; init; }
    public StripeConfig? Stripe { get; init; }
    public LoggingConfig? Logging { get; init; }
    public InitialConfigOptions? InitialConfig { get; init; }  // FilePath and/or Config for config sync
}

public class DatabaseConfig
{
    public required string ConnectionString { get; init; }
    public bool Ssl { get; init; }
    public int PoolSize { get; init; } = 10;
}

database object

adminPassphrase

Optional override for the admin passphrase hash stored during installSchema() / InstallSchemaAsync(). If omitted you can pass the passphrase directly to the install method.

initialConfig / InitialConfig

Optional config sync input (same as used by ConfigSyncService): a file path or a ConfigSyncDto object. If set, call runInitialConfigSync() / RunInitialConfigSyncAsync() after construction (e.g. after installing or verifying the schema) to apply the configuration. When provided, that method runs the sync and returns the report; when omitted, it returns null.

stripe object

logging object

installSchema

Description

Creates every Subscrio database table, seeds configuration rows, and optionally writes the admin passphrase hash when setting up a fresh environment.

Signature

installSchema(adminPassphrase?: string): Promise<void>

Task InstallSchemaAsync(string? adminPassphrase = null)

Inputs

Input Properties

• adminPassphrase – plain text string that will be hashed before being stored in system_config.

Returns

Return Properties

Expected Results

• Runs the schema installer to create all tables, extensions, and seed configuration rows.
• Stores the admin passphrase hash when provided.

Potential Errors

Example

await subscrio.installSchema('super-secret-passphrase');

await subscrio.InstallSchemaAsync("super-secret-passphrase");

migrate

Description

Runs pending database migrations to update the schema to the latest version. Migrations are tracked via schema_version in the system_config table, so only pending migrations are applied.

Signature

migrate(): Promise<number>

Task<int> MigrateAsync()

Inputs

Input Properties

• None.

Returns

Return Properties

Expected Results

• Checks current schema version from system_config.
• Runs only pending migrations (those with version numbers greater than current).
• Updates schema_version in system_config after each migration.
• Returns count of migrations applied.

Potential Errors

Example

const migrationsApplied = await subscrio.migrate();
if (migrationsApplied > 0) {
  console.log(`Applied ${migrationsApplied} migration(s)`);
} else {
  console.log('Database is up to date');
}

var migrationsApplied = await subscrio.MigrateAsync();
if (migrationsApplied > 0)
{
    Console.WriteLine($"Applied {migrationsApplied} migration(s)");
}
else
{
    Console.WriteLine("Database is up to date");
}

verifySchema

Description

Confirms whether the Subscrio schema is already installed and returns the current schema version. Returns null if the schema is not installed, allowing callers to decide whether to run installSchema() or proceed with normal operations.

Signature

verifySchema(): Promise<string | null>

Task<string?> VerifySchemaAsync()

Inputs

Input Properties

• None.

Returns

Return Properties

Expected Results

• Executes lightweight checks on required tables and indexes via the schema installer.
• If schema exists, retrieves and returns the current schema version from system_config.
• Returns null if schema is not installed or version cannot be determined.

Potential Errors

Example

const version = await subscrio.verifySchema();
if (version === null) {
  console.warn('Subscrio schema missing – run installSchema() first.');
} else {
  console.log(`Schema version: ${version}`);
}

var version = await subscrio.VerifySchemaAsync();
if (version == null)
{
    Console.WriteLine("Subscrio schema missing – run InstallSchemaAsync() first.");
}
else
{
    Console.WriteLine($"Schema version: {version}");
}

dropSchema

Description

Removes every table created by Subscrio. Intended for local development resets or automated tests.

Signature

dropSchema(): Promise<void>

Task DropSchemaAsync()

Inputs

Input Properties

• None.

Returns

Return Properties

Expected Results

• Drops every Subscrio-owned table via the installer. This is destructive and meant for local resets/tests.

Potential Errors

Example

if (process.env.NODE_ENV === 'test') {
  await subscrio.dropSchema();
}

if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Testing")
{
    await subscrio.DropSchemaAsync();
}

close

Description

Closes the shared database connection pool so the process can exit cleanly.

Signature

close(): Promise<void>

void Dispose()

Inputs

Input Properties

• None.

Returns

Return Properties

Expected Results

• Closes database connections and releases resources.

Potential Errors

Example

await subscrio.close();

subscrio.Dispose();
// Or use: await using var subscrio = new Subscrio(config);

Service Reference Index

All service-level documentation now lives in dedicated markdown files so each method, DTO, error, and example can be described in depth. The following table shows where to find those references:

Every service doc follows a standard structure that standardizes sections for usage, inputs/outputs, DTOs, expected results, errors, and working examples.

Additional Reference Guides

• subscriptions.md covers CRUD APIs, DTOs, overrides, and lifecycle automation APIs.
• subscription-lifecycle.md fully documents how each status is calculated (with diagrams) and how transitions work.
• relationships.md centralizes the product/plan/feature/billing-cycle/customer relationships, the feature resolution hierarchy, and the customer key conventions.
• products.md, plans.md, features.md, and billing-cycles.md document CRUD flows, DTOs, and association helpers for each domain surface.
• feature-checker.md explains the subscription override → plan value → feature default resolution order in depth.
• customers.md details how caller-supplied customer keys map to internal IDs and where they are required.
• stripe-integration.md contains the full Stripe workflow, including where signature verification must happen before calling processStripeEvent().