TypeScript quickstart
Entitlements and plan-based feature gating for TypeScript.
The subscrio npm package is an open source MIT-licensed entitlement library for TypeScript applications.
Install and connect
Create the engine with a PostgreSQL connection.
Pass the database connection used by your application to the constructor. SSL, pool, Stripe, and logging settings are available when your application needs them.
npm install subscrio
import { Subscrio } from 'subscrio';
const subscrio = new Subscrio({
database: {
connectionString: process.env.DATABASE_URL!
}
});Schema
Install the schema once.
installSchema() creates the required tables inside an existing PostgreSQL database. Use verifySchema() when your startup or deployment flow needs to check whether installation has happened.
Close the library during graceful process shutdown so its database connections can be released.
if (await subscrio.verifySchema() === null) {
await subscrio.installSchema(process.env.ADMIN_PASSPHRASE);
}
process.on('SIGTERM', async () => {
await subscrio.close();
});Catalog configuration
Define the catalog in JSON or build it in TypeScript.
Products, features, plans, billing cycles, and plan values can live in one version-controlled JSON file. Sync it during deployment or a guarded startup path so each environment receives the same catalog.
For catalogs that depend on application settings or other runtime data, build a typed ConfigSyncDto and pass it to the same sync service. Both paths return a report of what was created, updated, archived, or ignored.
import type { ConfigSyncDto } from 'subscrio';
// Sync a version-controlled JSON file.
const fileReport = await subscrio.configSync.syncFromFile(
'./subscrio.config.json'
);
// Or build the same catalog in TypeScript.
const catalog: ConfigSyncDto = buildEntitlementCatalog();
const codeReport = await subscrio.configSync.syncFromJson(catalog);Feature check
Resolve the feature by customer, product, and feature keys.
Ask for the value type you need and supply a fallback. Here, a missing assignment or feature returns a numeric seat limit of zero. The Express handler is one example; the same check works in other kinds of TypeScript applications.
app.post('/accounts/:customerKey/reports', async (req, res) => {
const allowed = await subscrio.featureChecker.isEnabledForCustomer(
req.params.customerKey, 'analytics', 'advanced-reporting'
);
if (!allowed) return res.sendStatus(403);
const seatLimit = await subscrio.featureChecker.getValueForCustomer<number>(
req.params.customerKey, 'analytics', 'seat-limit', 0
);
return res.json({ seatLimit });
});Catalog setup
Use stable keys to connect catalog entities.
Create the product and feature, then associate the feature with that product. Once associated, a plan can assign the feature a value.
const product = await subscrio.products.createProduct({
key: 'analytics',
displayName: 'Analytics'
});
const feature = await subscrio.features.createFeature({
key: 'seat-limit',
displayName: 'Seat limit',
valueType: 'numeric',
defaultValue: '5'
});
await subscrio.products.associateFeature(product.key, feature.key);A focused test
Test the value returned by the library.
The package uses Vitest internally, but your application can use any test runner. Seed a small catalog and test the value that product code depends on.
it('resolves Acme\'s seat override', async () => {
const seatLimit = await subscrio.featureChecker.getValueForCustomer<number>(
'acme', 'analytics', 'seat-limit', 0
);
expect(seatLimit).toBe(40);
});Where it runs
Use Subscrio in the application that performs the protected work.
Subscrio is embedded directly in your application. It reads entitlement data from PostgreSQL and can be used by any application that owns that connection.
Application types
- Web applications and APIs.
- Desktop software.
- Background services and scheduled jobs.
- Command-line tools and internal operations clients.
When the interface runs elsewhere
- Keep database credentials with the application that owns the connection.
- Give the interface only the access facts it needs.
- Do not treat a hidden control as an access check.
- Check access again before performing the protected operation.
Next: follow the plan-based feature gating guide, review the entitlement data model, or see what the optional Web Admin adds.
Common questions
Questions about TypeScript entitlement integration
How do I add plan-based feature gating to a TypeScript application?
Install the subscrio package, connect PostgreSQL, define or sync the entitlement catalog, and resolve stable feature keys for the current customer. The same model supports toggle access, limits, and subscription overrides.
Where can the TypeScript library be used?
Use it in the application that owns the feature check and database connection. That can be a web app, desktop application, background service, command-line tool, or internal operations client.
Which database does the TypeScript library support?
The current TypeScript package uses PostgreSQL through Drizzle ORM.
Can I use the package in an application with a browser interface?
Yes. Keep Subscrio and its database credentials in the part of the application that owns the database connection, and give the interface only the access result it needs.
How are customer-specific limits represented?
Add a feature override to the customer's subscription. It takes precedence over the plan value and feature default.
Can I configure Subscrio with JSON or TypeScript?
Yes. Define products, features, plans, billing cycles, and plan values in a version-controlled JSON file and sync it with syncFromFile. You can also build a typed ConfigSyncDto and pass it to syncFromJson.
Next step
Install the package and run the first check in your application.
Use the complete TypeScript documentation for schema setup, migrations, service APIs, hooks, testing, and Stripe integration.