@happyvertical/smrt-subscriptions 0.30.0

package/AGENTS.md

@@ -0,0 +1,26 @@
+# @happyvertical/smrt-subscriptions
+
+Tenant subscriptions, plan features, usage thresholds, and entitlement
+resolution for SMRT applications.
+
+## Validation
+
+```bash
+pnpm --filter @happyvertical/smrt-subscriptions test
+pnpm --filter @happyvertical/smrt-subscriptions typecheck
+pnpm --filter @happyvertical/smrt-subscriptions build
+```
+
+## Notes
+
+- Keep Stripe-specific fields as provider binding metadata. Runtime Stripe API
+  calls belong in the HappyVertical SDK accounting provider.
+- Thresholds are evaluated from tenant usage metrics and optional AI usage
+  summaries. Resolve multiple thresholds with the batch usage path where
+  available; do not bypass tenant context in application code.
+- Use `SubscriptionResolver.create()` or an explicitly injected
+  `SubscriptionResolver` once per request when resolving entitlements multiple
+  times. Load and pass `EntitlementResolutionContext` to avoid re-reading the
+  current subscription and plan.
+- Subscription UI components should stay provider-neutral and receive actions
+  from the host app.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.9.3"}

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/collections/SubscriptionPlanCollection.d.ts

@@ -0,0 +1,9 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SubscriptionPlan } from '../models/SubscriptionPlan.js';
+export declare class SubscriptionPlanCollection extends SmrtCollection<SubscriptionPlan> {
+    static readonly _itemClass: typeof SubscriptionPlan;
+    findByPlanKey(planKey: string): Promise<SubscriptionPlan | null>;
+    findActive(): Promise<SubscriptionPlan[]>;
+    findByStripePriceId(stripePriceId: string): Promise<SubscriptionPlan | null>;
+}
+//# sourceMappingURL=SubscriptionPlanCollection.d.ts.map

package/dist/collections/SubscriptionPlanCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubscriptionPlanCollection.d.ts","sourceRoot":"","sources":["../../src/collections/SubscriptionPlanCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,qBAAa,0BAA2B,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IAC9E,MAAM,CAAC,QAAQ,CAAC,UAAU,0BAAoB;IAExC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAKhE,UAAU,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAOzC,mBAAmB,CACvB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAIpC"}

package/dist/collections/TenantSubscriptionCollection.d.ts

@@ -0,0 +1,29 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { TenantSubscription } from '../models/TenantSubscription.js';
+import { Subscriber } from '../types.js';
+export declare class TenantSubscriptionCollection extends SmrtCollection<TenantSubscription> {
+    static readonly _itemClass: typeof TenantSubscription;
+    /**
+     * List subscriptions whose owning tenant scope is `tenantId`. Includes both
+     * `'tenant'`-kind (subscriber == owner) and `'external'`-kind (subscriber is
+     * an external identity scoped under this tenant) rows.
+     */
+    findByTenant(tenantId: string): Promise<TenantSubscription[]>;
+    /**
+     * Legacy single-tenant accessor: returns the current subscription where the
+     * tenant IS the subscriber (`subscriberKind = 'tenant'`). External-kind rows
+     * scoped under this tenant are intentionally excluded so existing callers
+     * are not surprised by buyer/agent subscriptions.
+     */
+    findCurrentForTenant(tenantId: string, now?: Date): Promise<TenantSubscription | null>;
+    /**
+     * Polymorphic current-subscription accessor.
+     *
+     * For `'tenant'` subscribers we match rows with `subscriberKind = 'tenant'`
+     * under the same `tenantId`. For `'external'` subscribers we match by
+     * `(tenantId, subscriberExternalId)` with `subscriberKind = 'external'`.
+     */
+    findCurrentForSubscriber(subscriber: Subscriber, now?: Date): Promise<TenantSubscription | null>;
+    findByStripeSubscriptionId(stripeSubscriptionId: string): Promise<TenantSubscription | null>;
+}
+//# sourceMappingURL=TenantSubscriptionCollection.d.ts.map

package/dist/collections/TenantSubscriptionCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantSubscriptionCollection.d.ts","sourceRoot":"","sources":["../../src/collections/TenantSubscriptionCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,qBAAa,4BAA6B,SAAQ,cAAc,CAAC,kBAAkB,CAAC;IAClF,MAAM,CAAC,QAAQ,CAAC,UAAU,4BAAsB;IAEhD;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOnE;;;;;OAKG;IACG,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,GAAG,OAAa,GACf,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAIrC;;;;;;OAMG;IACG,wBAAwB,CAC5B,UAAU,EAAE,UAAU,EACtB,GAAG,OAAa,GACf,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAoB/B,0BAA0B,CAC9B,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAOtC"}

package/dist/collections/TenantUsageMetricCollection.d.ts

@@ -0,0 +1,28 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { TenantUsageMetric } from '../models/TenantUsageMetric.js';
+import { AiUsageSummary, RecordUsageOptions, SummarizeAiUsageOptions, SummarizeUsageBatchOptions, SummarizeUsageOptions, UsageSummary } from '../types.js';
+export declare class TenantUsageMetricCollection extends SmrtCollection<TenantUsageMetric> {
+    static readonly _itemClass: typeof TenantUsageMetric;
+    recordUsage(options: RecordUsageOptions): Promise<TenantUsageMetric>;
+    /**
+     * Legacy accessor — finds metrics for `subscriberKind = 'tenant'` under the
+     * given tenant. External-kind rows scoped to the same tenant are excluded.
+     */
+    findByTenantAndMetric(tenantId: string, metricKey: string): Promise<TenantUsageMetric[]>;
+    summarizeUsage(options: SummarizeUsageOptions): Promise<UsageSummary>;
+    summarizeUsageBatch(options: SummarizeUsageBatchOptions): Promise<UsageSummary[]>;
+    /**
+     * Summarize persisted AI usage for a tenant within a window.
+     *
+     * Reads the framework `_smrt_ai_usage` system table via a raw aggregate
+     * query. This deliberately uses `this.db.query` rather than the inherited
+     * `query()`: those rows are framework usage records, not `TenantUsageMetric`
+     * instances, so model hydration would discard the aggregate columns. Tenant
+     * scoping is applied explicitly through the `tenant_id` filter.
+     *
+     * Named distinctly from the inherited `SmrtClass.summarizeAiUsage` (which
+     * returns grouped stats across all tenants) to avoid overriding it.
+     */
+    summarizeTenantAiUsage(options: SummarizeAiUsageOptions): Promise<AiUsageSummary>;
+}
+//# sourceMappingURL=TenantUsageMetricCollection.d.ts.map

package/dist/collections/TenantUsageMetricCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantUsageMetricCollection.d.ts","sourceRoot":"","sources":["../../src/collections/TenantUsageMetricCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,YAAY,EACb,MAAM,aAAa,CAAC;AAOrB,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;IAEzC,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsB1E;;;OAGG;IACG,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOzB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCrE,mBAAmB,CACvB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,YAAY,EAAE,CAAC;IAqE1B;;;;;;;;;;;OAWG;IACG,sBAAsB,CAC1B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,cAAc,CAAC;CA6B3B"}

package/dist/collections/index.d.ts

@@ -0,0 +1,4 @@
+export { SubscriptionPlanCollection } from './SubscriptionPlanCollection.js';
+export { TenantSubscriptionCollection } from './TenantSubscriptionCollection.js';
+export { TenantUsageMetricCollection } from './TenantUsageMetricCollection.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/collections/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { SubscriptionPlanCollection, TenantSubscriptionCollection, TenantUsageMetricCollection, } from './collections/index.js';
+export { SubscriptionPlan, TenantSubscription, TenantUsageMetric, } from './models/index.js';
+export { evaluateThreshold, evaluateThresholds, type SubscriptionPlanReader, SubscriptionResolver, type SubscriptionResolverReaders, type TenantSubscriptionReader, TenantUsageMeter, type UsageSummaryReader, } from './services/index.js';
+export type { AiUsageSummary, BillingInterval, EntitlementResolution, EntitlementResolutionContext, JsonObject, PlanFeatureGrant, PlanThreshold, RecordUsageOptions, Subscriber, SubscriberKind, SubscriptionPlanStatus, SubscriptionResolverOptions, SubscriptionStatus, SummarizeAiUsageOptions, SummarizeUsageBatchOptions, SummarizeUsageOptions, ThresholdEnforcement, ThresholdEvaluation, ThresholdWindow, UsageMeterOptions, UsageMetricRecord, UsageSummary, UsageWindow, } from './types.js';
+export { assertSubscriberInvariant, getWindowForThreshold, getWindowKey, isValidThreshold, normalizeFeatureGrants, normalizeSubscriber, subscriberToColumns, } from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,gBAAgB,EAChB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,4BAA4B,EAC5B,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}