Skip to main content

@happyvertical/smrt-subscriptions

Tenant subscriptions, feature grants, immutable usage evidence, thresholds, effective-dated client pricing, spending policies, and entitlement resolution for s-m-r-t applications.

The package is provider-neutral. Stripe or another billing provider may be recorded as binding metadata, but provider API calls belong in an injected SDK accounting adapter.

Installation​

pnpm add @happyvertical/smrt-subscriptions

Add svelte for the optional plan, subscription, and threshold components.

Resolve entitlements​

import { SubscriptionResolver } from '@happyvertical/smrt-subscriptions';

const resolver = await SubscriptionResolver.create({ db: 'app.db' });
const context = await resolver.loadEntitlementContext('tenant-1');

const result = await resolver.resolveTenantEntitlements('tenant-1', {
  context,
});

if (!result.allowed) {
  throw new Error('Subscription thresholds do not allow this operation');
}

console.log(result.planKey, result.featureKeys, result.thresholdEvaluations);

Create one resolver per request or application unit of work and reuse the loaded EntitlementResolutionContext when several checks need the same subscription and plan.

Core model​

  • SubscriptionPlan stores versioned feature grants and thresholds.
  • TenantSubscription binds a tenant or external subscriber to a plan over an effective period.
  • TenantUsageMetric is immutable, idempotent usage evidence.
  • SubscriptionResolver combines current subscription, plan, and batched usage summaries into one entitlement decision.
  • TenantUsageMeter records and summarizes ordinary and AI usage.
  • PricingRule, ClientCharge, and BillingAdjustment model effective-dated commercial evidence.
  • SpendingPolicyEvaluator applies scoped budget behavior without embedding a payment provider.

Subscribers are polymorphic: tenant subscribers use a tenant ID, while external subscribers add a stable external discriminator. Utilities such as normalizeSubscriber() and assertSubscriberInvariant() keep that identity coherent.

Thresholds and spending​

Thresholds define a metric key, time window, limit, and enforcement behavior. The resolver batches metric reads when possible. Do not bypass tenant context or repeatedly construct a new resolver inside one request.

Commercial usage records client-facing prices separately from usage evidence. Spending policy decisions can allow, warn, require approval, or deny based on the configured behavior and scope.

Svelte entry point​

@happyvertical/smrt-subscriptions/svelte exports provider-neutral, presentational components:

  • PlanPicker
  • SubscriptionSummary
  • UsageThresholds
  • CommercialOverview

Hosts own data loading and mutation actions.

Development​

pnpm --filter @happyvertical/smrt-subscriptions test
pnpm --filter @happyvertical/smrt-subscriptions typecheck
pnpm --filter @happyvertical/smrt-subscriptions build

See AGENTS.md for provider, threshold, and resolver guidance.