@happyvertical/smrt-subscriptions 0.51.21 → 0.51.25

package/AGENTS.md

@@ -20,7 +20,8 @@ that reverted to DECIMAL passes every SQLite suite.
 ## Money
 
 - **Money is integer minor units** (cents) — `$19.99` is `1999`.
-  `SubscriptionPlan.priceAmount`, `ClientCharge.amount`,
+  `SubscriptionPlan.priceAmount`, `ClientCharge.amount`, `RetailCharge.amount`,
+  `CreditGrant.amount`,
   `BillingAdjustment.amount` and `SpendingPolicy.limitAmount` all initialize
   `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER
   columns (BIGINT on fresh PostgreSQL/DuckDB databases; #2401, #2373). `ClientCharge.quantity` and `TenantUsageMetric.quantity` are
@@ -63,6 +64,33 @@ that reverted to DECIMAL passes every SQLite suite.
   are BIGINT, and hydration rejects values outside JavaScript's safe-integer
   range. Existing PostgreSQL `int4` columns require the explicit widening in #2424.
 
+## Reseller billing (#3059)
+
+- Billing ownership is consumed from `smrt-tenancy`'s
+  `BillingRelationshipService` (`BillingRelationshipReader`); never re-derive
+  parentage or owners here.
+- `ClientCharge` stays one row per usage event (`usage_event_id` unique) and
+  `tenantId` is always the payer. That uniqueness is the double-billing guard
+  across owner changes; do not widen its conflict key. The retail leg lives in
+  `RetailCharge` (also one per event), written in the same transaction.
+- Price-book rules are `PricingRule` rows with `priceBookId`; `price()` must
+  keep ignoring them, and `rateUsage()` only trusts rules whose tenant owns the
+  book.
+- Delegated `SpendingPolicy` rows (`setByTenantId`) are guarded in
+  `validateBeforeSave` and a `beforeDelete` hook, by id and by conflict key;
+  `CreditGrant` applies the same parent-only rule to delegated balances.
+  `PriceBookAssignmentCollection` is deliberately not a root export.
+- `ResellerBillingService` authorizes first, then writes in a system context
+  (parent writes land on child-owned rows). The wholesale leg is authorized by
+  the book's publisher and may never be published by the payer; whether a
+  publisher is a legitimate provider for the reseller is a host obligation
+  (the model records no upstream seller). Relationship reads precede
+  authorization and stay under smrt-tenancy's own read rules. The only
+  cross-tenant read in evaluation is the bounded `wholesale`-basis sum.
+- `balance` policies take their limit from `CreditGrant`s; `limitAmount` must
+  be 0, and currency and period are fixed once saved (the ledger is scoped to
+  them). Auto top-up is a host hook only — no payment provider calls.
+
 ## Notes
 
 - Keep Stripe-specific fields as provider binding metadata. Runtime Stripe API

package/README.md

@@ -52,6 +52,9 @@ subscription and plan.
   commercial evidence.
 - `SpendingPolicyEvaluator` applies scoped budget behavior without embedding a
   payment provider.
+- `PriceBook`, `PriceBookAssignment`, `RetailCharge`, and `CreditGrant` add
+  reseller pricing, the reseller's retail ledger, and prepaid credit (see
+  [Reseller billing](#reseller-billing)).
 
 Subscribers are polymorphic: tenant subscribers use a tenant ID, while external
 subscribers add a stable external discriminator. Utilities such as
@@ -68,6 +71,128 @@ 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.
 
+## Reseller billing
+
+Resellers buy a service at wholesale and resell it to their own child tenants.
+Parentage and the billing owner come from `smrt-tenancy`'s
+`BillingRelationshipService`; this package prices usage against it.
+
+- **Price books.** A `PriceBook` is published by one seller tenant and is
+  either `wholesale` (what a provider charges a reseller) or `retail` (what a
+  reseller charges its children). Its prices are ordinary `PricingRule` rows
+  carrying the book's `priceBookId`, one row per currency.
+- **Assignment per relationship.** `ResellerBillingService.assignPriceBooks()`
+  picks, for one child, the wholesale book and currency and (optionally) the
+  reseller's retail book and currency. An assignment made under one reseller
+  never applies after the child moves to another.
+- **Rating.** `CommercialUsageService.rateUsage()` resolves the child's
+  relationship and returns a `UsageRating`:
+  - self-billed or unrelated tenant: one direct `ClientCharge`, priced exactly
+    like `price()`;
+  - reseller-billed: a wholesale `ClientCharge` payable by the reseller
+    (`tenantId` = reseller, `usageTenantId` = child) and, with a retail book,
+    a `RetailCharge` the child owes the reseller, committed together.
+
+  A usage event is rated once. `ClientCharge` keeps exactly one row per usage
+  event, so a later billing-owner change returns the original rating instead
+  of charging a second payer.
+- **Delegated spending.** `setDelegatedSpendingPolicy()` writes a
+  `SpendingPolicy` on the child with `setByTenantId` = the parent. The ordinary
+  `SpendingPolicyEvaluator` enforces it (observe, warn, approval, block), and
+  the child cannot edit, delete, or overwrite it. Parents change or retire
+  (`active: false`) their policies through the same method. A policy's `basis` selects
+  what it counts: `billed` (what the tenant pays the provider, the default),
+  `retail` (what it owes its reseller), or `wholesale` (what the parent pays
+  for this child's usage).
+- **Prepaid credit.** A `period: 'balance'` policy's limit is the sum of its
+  `CreditGrant`s; spend accumulates from `balanceFrom`. Its currency and
+  period cannot change once saved; create a new balance instead. Grants are append-only (updates and deletes are refused)
+  and idempotent per `source`/`sourceId`. Pass `autoTopUp` to
+  `SpendingPolicyEvaluator.create()` to be called when a charge would exhaust a
+  balance; return a grant once the host has secured the funds. The evaluator
+  never calls a payment provider.
+
+```ts
+import { BillingRelationshipService } from '@happyvertical/smrt-tenancy';
+import {
+  CommercialUsageService,
+  ResellerBillingService,
+} from '@happyvertical/smrt-subscriptions';
+
+const relationships = await BillingRelationshipService.create({
+  db,
+  tenantExists,
+});
+const reseller = await ResellerBillingService.create({
+  db,
+  billingRelationships: relationships,
+});
+await reseller.definePrice({
+  priceBookId: retailBook.id,
+  ruleKey: 'tokens',
+  metricKey: 'ai.tokens',
+  strategy: 'fixed_unit',
+  prices: [
+    { currency: 'USD', terms: { unitPrice: 5 } },
+    { currency: 'EUR', terms: { unitPrice: 4.6 } },
+  ],
+});
+await reseller.assignPriceBooks({
+  childTenantId,
+  wholesale: { priceBookId: wholesaleBook.id, currency: 'USD' },
+  retail: { priceBookId: retailBook.id, currency: 'EUR' },
+});
+
+const rating = await commercial.rateUsage({
+  usageEventId,
+  billingRelationships: relationships,
+  approved: true,
+});
+```
+
+Mutations require a system context, a super-admin bypass, or a host
+`authorize` callback, like `BillingRelationshipService`; a seller may also
+define prices in its own book under its own tenant context. The callback
+receives the tenant whose authority the action exercises: the book's publisher
+for `define_prices` and `assign_wholesale_price_book`, the parent for
+`assign_retail_price_book` and `manage_child_spending`. Bind every decision to
+the caller, and never authorize a reseller for the wholesale leg that charges
+it. The package refuses a wholesale book published by the reseller or child it
+would charge, but whether a publisher is a legitimate provider for that
+reseller (`resellerTenantId` in the request) is the host's decision. The
+calls first read the child's relationship through `BillingRelationshipService`
+in the caller's context, so a provider assigning a wholesale leg also needs
+that service's `authorize` to grant it `read` for the child. Once
+authorized, the service writes in a system context, because a parent's writes
+land on rows the child owns.
+
+```ts
+const reseller = await ResellerBillingService.create({
+  db,
+  billingRelationships: relationships,
+  authorize: async ({ action, tenantId, resellerTenantId }) => {
+    const caller = currentTenantId();
+    if (caller !== tenantId || !(await isBillingAdmin(caller))) return false;
+    return action === 'assign_wholesale_price_book'
+      ? isProviderFor(caller, resellerTenantId)
+      : true;
+  },
+});
+```
+
+Rating reads a seller's books across tenants, so run it where the host's
+tenancy rules allow that (typically a system context). Spending evaluation can
+run in the child's own tenant context: a `wholesale`-basis policy reads only
+the sum of the parent's charges for that child's usage. Pass
+`billingRelationships` to `SpendingPolicyEvaluator.create()` so a former
+parent's delegated policies stop applying after the child changes reseller;
+without it they keep applying (fail closed), and the new parent may replace
+them by name. A delegated balance counts only credit granted by its current
+parent. A former parent's prepaid balance cannot be taken over by name; it
+keeps its credit ledger (reversible in a system context), and the new parent
+creates its own balance. A parent's `retail` cap counts only what the child owes that
+parent.
+
 ## Svelte entry point
 
 `@happyvertical/smrt-subscriptions/svelte` exports provider-neutral,
@@ -84,6 +209,7 @@ Hosts own data loading and mutation actions.
 
 ```bash
 pnpm --filter @happyvertical/smrt-subscriptions test
+pnpm --filter @happyvertical/smrt-subscriptions test:postgres
 pnpm --filter @happyvertical/smrt-subscriptions typecheck
 pnpm --filter @happyvertical/smrt-subscriptions build
 ```

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { SubscriptionPlanCollection, TenantSubscriptionCollection, TenantUsageMetricCollection, } from './collections/index.js';
 export { migrateSubscriptionsMoneyToMinorUnits, preflightSubscriptionsMoneyMinorUnits, SUBSCRIPTIONS_MONEY_COLUMNS, SUBSCRIPTIONS_MONEY_MINOR_UNITS_BACKFILL, } from './migrations/moneyMinorUnits.js';
-export type { PricingStrategy, SpendingPeriod, SpendingPolicyBehavior, } from './models/index.js';
-export { BillingAdjustment, BillingAdjustmentCollection, ClientCharge, ClientChargeCollection, PricingRule, PricingRuleCollection, SpendingPolicy, SpendingPolicyCollection, SubscriptionPlan, TenantSubscription, TenantUsageMetric, } from './models/index.js';
-export type { CommercialBillingStorage, CommercialUsageServiceOptions, CustomPricingContext, CustomPricingStrategy, PriceUsageOptions, SpendingDecision, } from './services/index.js';
-export { assertCommercialBillingStorageSupported, CommercialBillingStorageConfigurationError, CommercialUsageService, evaluateThreshold, evaluateThresholds, SpendingPolicyEvaluator, type SubscriptionPlanReader, SubscriptionResolver, type SubscriptionResolverReaders, type TenantSubscriptionReader, TenantUsageMeter, UnsupportedCommercialBillingStorageError, type UsageSummaryReader, } from './services/index.js';
+export type { PriceBookKind, PricingStrategy, SpendingBasis, SpendingPeriod, SpendingPolicyBehavior, } from './models/index.js';
+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 { 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,eAAe,EACf,cAAc,EACd,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uCAAuC,EACvC,0CAA0C,EAC1C,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,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,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"}