@happyvertical/smrt-subscriptions 0.57.1 → 0.57.3

package/README.md

@@ -41,9 +41,28 @@ subscription and plan.
 
 ## Core model
 
-- `SubscriptionPlan` stores versioned feature grants and thresholds.
+- `SubscriptionPlan` is tenant-scoped by `(tenantId, planKey)` and stores
+  feature grants, thresholds, and a `free`, `fixed`, or `pay_what_you_can`
+  pricing mode. Amounts (`priceAmount`, `minimumAmount`, and
+  `suggestedAmount`) are integer minor units. Provider bindings are optional
+  metadata (`externalProvider`, `providerProductId`, `providerPriceId`).
 - `TenantSubscription` binds a tenant or external subscriber to a plan over an
-  effective period.
+  effective period and records its chosen `agreedAmount` in integer minor
+  units for pay-what-you-can plans. Such subscriptions require an amount at
+  least the plan minimum; free/fixed subscriptions must leave it null.
+  Free and pay-what-you-can plans require `priceAmount: 0`; fixed plans use
+  `priceAmount`. Monthly commerce period-close bills tenant subscribers using
+  their agreed amount for pay-what-you-can, never the suggested amount, and
+  skips free plans. External subscriber invoice routing remains host-owned. Pricing
+  mode and minimum are immutable after the plan is saved; create a
+  new plan instead (effective-dated transitions are tracked in #4032).
+  Invalid legacy pricing fails only its payer group at period close and reports
+  the subscription ID while other payer groups continue. Ordinary subscription
+  writes resolve only their own tenant's plans or legacy global plans; trusted
+  system-context billing can link a seller's plan to its child tenant.
+  Entitlement resolution validates plan ownership on both reader and supplied
+  context paths; trusted seller-to-child resolution requires explicit system
+  context too.
 - `TenantUsageMetric` is immutable, idempotent usage evidence.
 - `SubscriptionResolver` combines current subscription, plan, and batched usage
   summaries into one entitlement decision.
@@ -61,6 +80,31 @@ subscribers add a stable external discriminator. Utilities such as
 `normalizeSubscriber()` and `assertSubscriberInvariant()` keep that identity
 coherent.
 
+## Upgrade note
+
+`SubscriptionPlanCollection.findByPlanKey` now requires `(tenantId, planKey)`;
+pass `null` explicitly for legacy global plans. Update callers from the old
+single-argument signature. Pricing mode and minimum cannot be edited after
+persistence, even before the first subscriber, so a concurrent signup cannot
+observe terms that change mode underneath it. Existing fixed-price edits and
+current-period entitlement versioning remain separate work in #4032; this
+foundation does not provide immutable period snapshots. Concurrent first creates
+for one `(tenantId, planKey)` use a strict insert: one succeeds and a collision
+fails without changing the winner. Retry by reading the existing plan; a
+sequential create with matching mode/minimum retains natural-key upsert behavior.
+Retrying different pricing mode/minimum is rejected. The provider-neutral price
+lookup falls back to legacy Stripe IDs when the binding is Stripe or unspecified;
+explicit bindings to other providers do not use that fallback. PlanPicker accepts
+optional pricing mode, minimum and suggested amounts, labeling free plans and
+PWYC terms explicitly instead of displaying them as zero fixed-price plans.
+
+Existing databases created before #3829 may retain the global
+`_smrt_subscription_plans_plan_key_idx` on older migration runners. Run
+`scripts/migrate-3829-drop-legacy-plan-key-index.ts` after the ordinary manifest
+migration so different tenants can reuse a plan key. The script supports SQLite
+and PostgreSQL and refuses DuckDB, whose inline unique constraint needs a
+reviewed table rebuild.
+
 ## Thresholds and spending
 
 Thresholds define a metric key, time window, limit, and enforcement behavior.

package/dist/collections/SubscriptionPlanCollection.d.ts

@@ -2,8 +2,10 @@ 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>;
+    findByPlanKey(tenantId: string | null, planKey: string): Promise<SubscriptionPlan | null>;
     findActive(): Promise<SubscriptionPlan[]>;
+    findByProviderPriceId(providerPriceId: string): Promise<SubscriptionPlan | null>;
+    /** @deprecated Provider-neutral integrations should use findByProviderPriceId. */
     findByStripePriceId(stripePriceId: string): Promise<SubscriptionPlan | null>;
 }
 //# sourceMappingURL=SubscriptionPlanCollection.d.ts.map

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

@@ -1 +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"}
+{"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,CACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAK7B,UAAU,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAOzC,qBAAqB,CACzB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAanC,kFAAkF;IAC5E,mBAAmB,CACvB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAIpC"}

package/dist/index.d.ts

@@ -13,6 +13,6 @@ export type { PriceBookKind, PricingStrategy, SpendingBasis, SpendingPeriod, Spe
 export { BillingAdjustment, BillingAdjustmentCollection, ClientCharge, ClientChargeCollection, CreditGrant, CreditGrantCollection, isCurrencyCode, isPriceBookKind, PriceBook, PriceBookAssignment, PriceBookCollection, PricingRule, PricingRuleCollection, RetailCharge, RetailChargeCollection, SpendingPolicy, SpendingPolicyCollection, SubscriptionPlan, TenantSubscription, TenantUsageMetric, } from './models/index.js';
 export type { AssignPriceBooksInput, AutoTopUpGrant, AutoTopUpHook, AutoTopUpRequest, BillingRelationshipReader, CommercialBillingStorage, CommercialUsageServiceOptions, CustomPricingContext, CustomPricingStrategy, DefinePriceBookPriceInput, DelegatedSpendingPolicyInput, GrantChildCreditInput, GrantCreditInput, PriceBookAssignmentView, PriceBookLeg, PriceUsageOptions, RateUsageOptions, ResellerBillingAction, ResellerBillingErrorCode, ResellerBillingServiceOptions, SpendingDecision, SpendingEvaluationInput, SpendingPolicyEvaluatorExtensions, SpendingPolicyEvaluatorOptions, UsageRating, } from './services/index.js';
 export { assertCommercialBillingStorageSupported, CommercialBillingStorageConfigurationError, CommercialUsageService, evaluateThreshold, evaluateThresholds, ResellerBillingError, ResellerBillingService, SpendingPolicyEvaluator, type SubscriptionPlanReader, SubscriptionResolver, type SubscriptionResolverReaders, type TenantSubscriptionReader, TenantUsageMeter, UnsupportedCommercialBillingStorageError, 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 type { AiUsageSummary, BillingInterval, EntitlementResolution, EntitlementResolutionContext, JsonObject, PlanFeatureGrant, PlanThreshold, PricingMode, 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

@@ -1 +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;AAEhC,OAAO,EACL,qCAAqC,EACrC,qCAAqC,EACrC,2BAA2B,EAC3B,wCAAwC,GACzC,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,aAAa,EACb,eAAe,EACf,aAAa,EACb,cAAc,EACd,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,6BAA6B,EAC7B,gBAAgB,EAChB,uBAAuB,EACvB,iCAAiC,EACjC,8BAA8B,EAC9B,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uCAAuC,EACvC,0CAA0C,EAC1C,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,gBAAgB,EAChB,wCAAwC,EACxC,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"}
+{"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;AAEhC,OAAO,EACL,qCAAqC,EACrC,qCAAqC,EACrC,2BAA2B,EAC3B,wCAAwC,GACzC,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,aAAa,EACb,eAAe,EACf,aAAa,EACb,cAAc,EACd,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,6BAA6B,EAC7B,gBAAgB,EAChB,uBAAuB,EACvB,iCAAiC,EACjC,8BAA8B,EAC9B,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uCAAuC,EACvC,0CAA0C,EAC1C,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,gBAAgB,EAChB,wCAAwC,EACxC,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,4BAA4B,EAC5B,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,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"}