@saasicat/nest 1.0.0-rc.21 → 1.0.0-rc.22

package/dist/{tenant-billing.controller-DKbAqTbM.d.cts → tenant-billing.controller-BC6-S5cT.d.cts}

@@ -1,10 +1,10 @@
 import { CanActivate, ExecutionContext } from '@nestjs/common';
 import { d as AuthGuardList, a as TrialProjectionPort, P as PendingPlanQueryPort, T as TenantIdResolver, b as UserIdResolver, U as UserEmailResolver, A as AuditContextResolver } from './tenant-billing.tokens-G-1xOlMr.cjs';
-import { BillingCycle, CancellationNoticePeriods, SubscriptionUsagePort, UsageSnapshotPort, SelfServiceBlockedPlans, SubscriptionBundleRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleView, SubscriptionBundleRecord, PlanRepository, CatalogEntryRepository, SubscriptionUsageRecord, OnboardingSelectionResponse } from '@saasicat/core';
-import { c as EntitlementService, a as EffectiveLimitsSnapshot, t as toEffectiveLimitsSnapshot } from './aggregation-OpnhwzF5.cjs';
-import { d as ContractFreezePort, j as SelfServiceBlockedBundles } from './tenant-billing.module-ClbjzocC.cjs';
+import { BillingCycle, CancellationNoticePeriods, SubscriptionUsagePort, UsageSnapshotPort, SelfServiceBlockedPlans, SubscriptionBundleRepository, SubscriptionContractRepository, TenantSubscriptionWritePort, SubscriberLedgerRepository, SubscriberRepository, SubscriberChargeRecord, BundleRepository, SubscriptionBundleView, SubscriptionBundleRecord, PlanRepository, CatalogEntryRepository, SubscriptionUsageRecord, OnboardingSelectionResponse } from '@saasicat/core';
+import { d as EntitlementService, b as EffectiveLimitsSnapshot, t as toEffectiveLimitsSnapshot } from './aggregation-DjQUc7yd.cjs';
+import { d as ContractFreezePort, j as SelfServiceBlockedBundles } from './tenant-billing.module-C6MFfCKq.cjs';
 import { P as PlanCatalogSource } from './plan-catalog-source-DWe-BGY1.cjs';
-import { a as PromoCodesService } from './promo.service-BYBu6dy3.cjs';
+import { a as PromoCodesService } from './promo.service-BextPvx5.cjs';
 import { A as AdminAuditService } from './admin-audit.service-4P3Djdxk.cjs';
 
 interface CancellationInput {
@@ -119,7 +119,16 @@ declare class TenantAdminGuard implements CanActivate {
     canActivate(context: ExecutionContext): boolean;
 }
 
+/**
+ * How a charge relates to the period already paid.
+ *
+ * `difference` — the target runs inside it, and the price difference is
+ * charged for what is left. `newPeriod` — the target starts a period of its own
+ * today, charged in full less the unused remainder of the one it replaces.
+ */
+type ProrationBasis = 'difference' | 'newPeriod';
 interface ProrationDto {
+    basis: ProrationBasis;
     daysRemainingInPeriod: number;
     daysInPeriod: number;
     periodStart: Date;
@@ -153,6 +162,12 @@ interface ProrationDto {
      * them takes that back.
      */
     isFree: boolean;
+    /**
+     * What is left of the replaced period at its own price, net — the amount a
+     * `newPeriod` charge is reduced by. Zero on a `difference`, where the
+     * remainder is what the difference is taken over.
+     */
+    remainderNet: number;
 }
 interface ProrationInput {
     periodStart: Date;
@@ -163,6 +178,16 @@ interface ProrationInput {
     targetPriceNet: number;
 }
 declare function computeProration(input: ProrationInput): ProrationDto;
+/**
+ * The charge for a target that starts a period of its own today: its full
+ * price, less the unused remainder of the period it replaces.
+ *
+ * `periodStart`/`periodEnd` are the replaced period's, and `currentPriceNet`
+ * its price — the remainder is taken at the price that was paid for it. The
+ * remainder only reduces this charge: floored at zero like every other
+ * proration, it is never paid out.
+ */
+declare function computeNewPeriodCharge(input: ProrationInput): ProrationDto;
 
 type PlanChangeType = 'UPGRADE' | 'DOWNGRADE' | 'CYCLE_CHANGE' | 'NOOP';
 /** Where the target plan sits against the running one in the catalog order. */
@@ -294,7 +319,8 @@ declare class PlanChangePreviewService {
     private readonly blockedPlans;
     private readonly trialProjection;
     private readonly subscriptionBundles;
-    constructor(catalogs: PlanCatalogSource, entitlements: EntitlementService, subscriptions: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, blockedPlans?: SelfServiceBlockedPlans | null, trialProjection?: TrialProjectionPort | null, subscriptionBundles?: SubscriptionBundleRepository | null);
+    private readonly contracts;
+    constructor(catalogs: PlanCatalogSource, entitlements: EntitlementService, subscriptions: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, blockedPlans?: SelfServiceBlockedPlans | null, trialProjection?: TrialProjectionPort | null, subscriptionBundles?: SubscriptionBundleRepository | null, contracts?: SubscriptionContractRepository | null);
     preview(tenantId: string, targetPlan: string, targetCycle: string, now?: Date): Promise<PlanChangePreviewDto>;
     /** Like `preview`, but only the blocker list — for a server-side
      * pre-check before the `changePlan` mutation (defense-in-depth). */
@@ -323,6 +349,15 @@ declare class PlanChangePreviewService {
     private planRank;
     private resolveEffectiveAt;
     private computeProration;
+    /**
+     * The net price of the plan line in the contract in force, when it is for
+     * `plan` billed in `cycle` — what the customer pays for the period they are
+     * in. Null without contracts, or where the line is for another plan or
+     * rhythm: a freeze is optional and does not stop the change it follows when
+     * it fails, so the contract in force can still describe the plan before.
+     * The caller then prices from the catalogue.
+     */
+    private planPricePaid;
 }
 
 declare class PendingPlanMaterializationService {
@@ -338,6 +373,51 @@ declare class PendingPlanMaterializationService {
     private tryFreeze;
 }
 
+/**
+ * Keeps a subscriber's account up to date: the charges its contracts give rise
+ * to, one per contract line and period.
+ *
+ * The platform calls it where it writes a change itself — onboarding, an
+ * immediate plan change and an add-on booking. An application calls it where
+ * it writes one: when it activates a subscription, and from the job that renews
+ * periods. However often it runs, each charge is written once.
+ */
+declare class SubscriberChargeService {
+    private readonly ledger;
+    private readonly contracts;
+    private readonly subscribers;
+    private readonly subscriptions;
+    private readonly bookings;
+    private readonly freeze;
+    private readonly logger;
+    constructor(ledger: SubscriberLedgerRepository, contracts: SubscriptionContractRepository, subscribers: SubscriberRepository, subscriptions: SubscriptionUsagePort, bookings?: SubscriptionBundleRepository | null, freeze?: ContractFreezePort | null);
+    /**
+     * Writes every charge the tenant's records give rise to by `now` that is
+     * not written yet, and returns those.
+     *
+     * Nothing is charged without a contract (a charge points at a contract
+     * line), in a trial, before the plan's current window when the account is
+     * still empty, for a period that starts after `now`, or for one that
+     * starts on or after the date a cancellation takes effect.
+     *
+     * A window that moved on before anything charged it is not charged
+     * afterwards, so a job that renews periods calls this before it moves a
+     * window, and moves it only when the call succeeded.
+     */
+    recordDueCharges(tenantId: string, now?: Date): Promise<SubscriberChargeRecord[]>;
+    /**
+     * The tenant's contracts, written once more where the one in force misses
+     * a running booking.
+     *
+     * A booking writes its contract after it is saved, and a failure there does
+     * not undo the booking. The booking would then stay uncharged for good,
+     * since a charge points at a contract line — so the journal writes the
+     * contract the way the booking would have. A failure here is logged and the
+     * rest is charged: the next call tries again.
+     */
+    private contractsNamingEveryBooking;
+}
+
 declare class PreviewPlanChangeDto {
     plan: string;
     billingCycle: string;
@@ -487,7 +567,7 @@ declare class SubscriptionBundlesService {
      * number on the tenant's screen that nobody is charged, and on a yearly
      * booking it was out by whatever the yearly price is.
      */
-    listForSubscription(subscriptionId: string, planKey: string, planCycle: string): Promise<SubscriptionBundleView[]>;
+    listForSubscription(subscriptionId: string, planKey: string, planCycle: BillingCycle): Promise<SubscriptionBundleView[]>;
     /**
      * List prices for the given bundle versions, in both rhythms, resolved for
      * one plan.
@@ -546,8 +626,8 @@ interface SubscriptionBundlePreviewContext {
     subscriptionId: string;
     /** PlanKey of the current subscription (plan compatibility + redundancy source). */
     currentPlanKey: string;
-    /** 'MONTHLY' | 'YEARLY' (port convention). */
-    billingCycle: string;
+    /** The rhythm the plan is billed in. */
+    billingCycle: BillingCycle;
     /** Subscription status (TRIAL/ACTIVE/...). No proration during TRIAL. */
     status: string;
     startedAt: Date | null;
@@ -737,7 +817,8 @@ declare class TenantBillingController {
     private readonly contractFreeze;
     private readonly trialProjection;
     private readonly cancellationNoticeDays;
-    constructor(entitlements: EntitlementService, planPreview: PlanChangePreviewService, subscriptionUsage: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, subscriptionWrite: TenantSubscriptionWritePort, tenantIdResolver?: TenantIdResolver | null, userIdResolver?: UserIdResolver | null, blockedPlans?: SelfServiceBlockedPlans | null, promoCodes?: PromoCodesService | null, auditService?: AdminAuditService | null, userEmailResolver?: UserEmailResolver | null, auditContextResolver?: AuditContextResolver | null, subscriptionBundles?: SubscriptionBundlesService | null, contractFreeze?: ContractFreezePort | null, trialProjection?: TrialProjectionPort | null, cancellationNoticeDays?: CancellationNoticePeriods);
+    private readonly charges;
+    constructor(entitlements: EntitlementService, planPreview: PlanChangePreviewService, subscriptionUsage: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, subscriptionWrite: TenantSubscriptionWritePort, tenantIdResolver?: TenantIdResolver | null, userIdResolver?: UserIdResolver | null, blockedPlans?: SelfServiceBlockedPlans | null, promoCodes?: PromoCodesService | null, auditService?: AdminAuditService | null, userEmailResolver?: UserEmailResolver | null, auditContextResolver?: AuditContextResolver | null, subscriptionBundles?: SubscriptionBundlesService | null, contractFreeze?: ContractFreezePort | null, trialProjection?: TrialProjectionPort | null, cancellationNoticeDays?: CancellationNoticePeriods, charges?: SubscriberChargeService | null);
     private readonly logger;
     getEntitlement(req: RequestLike): Promise<EffectiveLimitsSnapshot>;
     getUsage(req: RequestLike): Promise<UsageResponse>;
@@ -809,4 +890,4 @@ declare class TenantBillingController {
     private auditLog;
 }
 
-export { type AddBundleToSubscriptionInput as A, type BundlePreviewSnapshot as B, type CancelBundleFromSubscriptionInput as C, clampToParent as D, computeProration as E, decideCancellation as F, decideCancellationFor as G, noticeDaysFor as H, resolveBundleCancelEffectiveAt as I, type LimitsCheckRow as L, NO_NOTICE_PERIOD as N, PendingPlanMaterializationService as P, type RedundantFeatureHint as R, type SubscriptionBundleAddPreviewDto as S, TenantAdminGuard as T, type UsageResponse as U, CancelSubscriptionDto as a, type CancellableSubscription as b, type CancellationDecision as c, type CancellationInput as d, ChangePlanDto as e, CompleteOnboardingSubscriptionDto as f, ComposedTenantAuthGuard as g, type CycleDirection as h, type PlanChangeContext as i, type PlanChangePreviewDto as j, type PlanChangePreviewIssue as k, PlanChangePreviewService as l, type PlanChangeType as m, type PlanDirection as n, type PlanSnapshotDto as o, PreviewPlanChangeDto as p, type ProrationDto as q, type ProrationInput as r, type SubscriptionBundleCancelPreviewDto as s, type SubscriptionBundleConfig as t, type SubscriptionBundlePreviewContext as u, type SubscriptionBundlePreviewIssue as v, SubscriptionBundlePreviewService as w, SubscriptionBundlesService as x, TenantBillingController as y, addMonths as z };
+export { type AddBundleToSubscriptionInput as A, type BundlePreviewSnapshot as B, type CancelBundleFromSubscriptionInput as C, TenantBillingController as D, addMonths as E, clampToParent as F, computeNewPeriodCharge as G, computeProration as H, decideCancellation as I, decideCancellationFor as J, noticeDaysFor as K, type LimitsCheckRow as L, resolveBundleCancelEffectiveAt as M, NO_NOTICE_PERIOD as N, PendingPlanMaterializationService as P, type RedundantFeatureHint as R, SubscriberChargeService as S, TenantAdminGuard as T, type UsageResponse as U, CancelSubscriptionDto as a, type CancellableSubscription as b, type CancellationDecision as c, type CancellationInput as d, ChangePlanDto as e, CompleteOnboardingSubscriptionDto as f, ComposedTenantAuthGuard as g, type CycleDirection as h, type PlanChangeContext as i, type PlanChangePreviewDto as j, type PlanChangePreviewIssue as k, PlanChangePreviewService as l, type PlanChangeType as m, type PlanDirection as n, type PlanSnapshotDto as o, PreviewPlanChangeDto as p, type ProrationBasis as q, type ProrationDto as r, type ProrationInput as s, type SubscriptionBundleAddPreviewDto as t, type SubscriptionBundleCancelPreviewDto as u, type SubscriptionBundleConfig as v, type SubscriptionBundlePreviewContext as w, type SubscriptionBundlePreviewIssue as x, SubscriptionBundlePreviewService as y, SubscriptionBundlesService as z };

package/dist/{tenant-billing.controller-BLqbsONe.d.ts → tenant-billing.controller-BuQDQ76i.d.ts}

@@ -1,10 +1,10 @@
 import { CanActivate, ExecutionContext } from '@nestjs/common';
 import { d as AuthGuardList, a as TrialProjectionPort, P as PendingPlanQueryPort, T as TenantIdResolver, b as UserIdResolver, U as UserEmailResolver, A as AuditContextResolver } from './tenant-billing.tokens-G-1xOlMr.js';
-import { BillingCycle, CancellationNoticePeriods, SubscriptionUsagePort, UsageSnapshotPort, SelfServiceBlockedPlans, SubscriptionBundleRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleView, SubscriptionBundleRecord, PlanRepository, CatalogEntryRepository, SubscriptionUsageRecord, OnboardingSelectionResponse } from '@saasicat/core';
-import { c as EntitlementService, a as EffectiveLimitsSnapshot, t as toEffectiveLimitsSnapshot } from './aggregation-ChpZDh0g.js';
-import { d as ContractFreezePort, j as SelfServiceBlockedBundles } from './tenant-billing.module-DohgJJ2m.js';
+import { BillingCycle, CancellationNoticePeriods, SubscriptionUsagePort, UsageSnapshotPort, SelfServiceBlockedPlans, SubscriptionBundleRepository, SubscriptionContractRepository, TenantSubscriptionWritePort, SubscriberLedgerRepository, SubscriberRepository, SubscriberChargeRecord, BundleRepository, SubscriptionBundleView, SubscriptionBundleRecord, PlanRepository, CatalogEntryRepository, SubscriptionUsageRecord, OnboardingSelectionResponse } from '@saasicat/core';
+import { d as EntitlementService, b as EffectiveLimitsSnapshot, t as toEffectiveLimitsSnapshot } from './aggregation-6fPkeV8i.js';
+import { d as ContractFreezePort, j as SelfServiceBlockedBundles } from './tenant-billing.module-CUCQL0-k.js';
 import { P as PlanCatalogSource } from './plan-catalog-source-DWe-BGY1.js';
-import { a as PromoCodesService } from './promo.service-CFjfF0Xm.js';
+import { a as PromoCodesService } from './promo.service-Dqqh0JXn.js';
 import { A as AdminAuditService } from './admin-audit.service-4P3Djdxk.js';
 
 interface CancellationInput {
@@ -119,7 +119,16 @@ declare class TenantAdminGuard implements CanActivate {
     canActivate(context: ExecutionContext): boolean;
 }
 
+/**
+ * How a charge relates to the period already paid.
+ *
+ * `difference` — the target runs inside it, and the price difference is
+ * charged for what is left. `newPeriod` — the target starts a period of its own
+ * today, charged in full less the unused remainder of the one it replaces.
+ */
+type ProrationBasis = 'difference' | 'newPeriod';
 interface ProrationDto {
+    basis: ProrationBasis;
     daysRemainingInPeriod: number;
     daysInPeriod: number;
     periodStart: Date;
@@ -153,6 +162,12 @@ interface ProrationDto {
      * them takes that back.
      */
     isFree: boolean;
+    /**
+     * What is left of the replaced period at its own price, net — the amount a
+     * `newPeriod` charge is reduced by. Zero on a `difference`, where the
+     * remainder is what the difference is taken over.
+     */
+    remainderNet: number;
 }
 interface ProrationInput {
     periodStart: Date;
@@ -163,6 +178,16 @@ interface ProrationInput {
     targetPriceNet: number;
 }
 declare function computeProration(input: ProrationInput): ProrationDto;
+/**
+ * The charge for a target that starts a period of its own today: its full
+ * price, less the unused remainder of the period it replaces.
+ *
+ * `periodStart`/`periodEnd` are the replaced period's, and `currentPriceNet`
+ * its price — the remainder is taken at the price that was paid for it. The
+ * remainder only reduces this charge: floored at zero like every other
+ * proration, it is never paid out.
+ */
+declare function computeNewPeriodCharge(input: ProrationInput): ProrationDto;
 
 type PlanChangeType = 'UPGRADE' | 'DOWNGRADE' | 'CYCLE_CHANGE' | 'NOOP';
 /** Where the target plan sits against the running one in the catalog order. */
@@ -294,7 +319,8 @@ declare class PlanChangePreviewService {
     private readonly blockedPlans;
     private readonly trialProjection;
     private readonly subscriptionBundles;
-    constructor(catalogs: PlanCatalogSource, entitlements: EntitlementService, subscriptions: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, blockedPlans?: SelfServiceBlockedPlans | null, trialProjection?: TrialProjectionPort | null, subscriptionBundles?: SubscriptionBundleRepository | null);
+    private readonly contracts;
+    constructor(catalogs: PlanCatalogSource, entitlements: EntitlementService, subscriptions: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, blockedPlans?: SelfServiceBlockedPlans | null, trialProjection?: TrialProjectionPort | null, subscriptionBundles?: SubscriptionBundleRepository | null, contracts?: SubscriptionContractRepository | null);
     preview(tenantId: string, targetPlan: string, targetCycle: string, now?: Date): Promise<PlanChangePreviewDto>;
     /** Like `preview`, but only the blocker list — for a server-side
      * pre-check before the `changePlan` mutation (defense-in-depth). */
@@ -323,6 +349,15 @@ declare class PlanChangePreviewService {
     private planRank;
     private resolveEffectiveAt;
     private computeProration;
+    /**
+     * The net price of the plan line in the contract in force, when it is for
+     * `plan` billed in `cycle` — what the customer pays for the period they are
+     * in. Null without contracts, or where the line is for another plan or
+     * rhythm: a freeze is optional and does not stop the change it follows when
+     * it fails, so the contract in force can still describe the plan before.
+     * The caller then prices from the catalogue.
+     */
+    private planPricePaid;
 }
 
 declare class PendingPlanMaterializationService {
@@ -338,6 +373,51 @@ declare class PendingPlanMaterializationService {
     private tryFreeze;
 }
 
+/**
+ * Keeps a subscriber's account up to date: the charges its contracts give rise
+ * to, one per contract line and period.
+ *
+ * The platform calls it where it writes a change itself — onboarding, an
+ * immediate plan change and an add-on booking. An application calls it where
+ * it writes one: when it activates a subscription, and from the job that renews
+ * periods. However often it runs, each charge is written once.
+ */
+declare class SubscriberChargeService {
+    private readonly ledger;
+    private readonly contracts;
+    private readonly subscribers;
+    private readonly subscriptions;
+    private readonly bookings;
+    private readonly freeze;
+    private readonly logger;
+    constructor(ledger: SubscriberLedgerRepository, contracts: SubscriptionContractRepository, subscribers: SubscriberRepository, subscriptions: SubscriptionUsagePort, bookings?: SubscriptionBundleRepository | null, freeze?: ContractFreezePort | null);
+    /**
+     * Writes every charge the tenant's records give rise to by `now` that is
+     * not written yet, and returns those.
+     *
+     * Nothing is charged without a contract (a charge points at a contract
+     * line), in a trial, before the plan's current window when the account is
+     * still empty, for a period that starts after `now`, or for one that
+     * starts on or after the date a cancellation takes effect.
+     *
+     * A window that moved on before anything charged it is not charged
+     * afterwards, so a job that renews periods calls this before it moves a
+     * window, and moves it only when the call succeeded.
+     */
+    recordDueCharges(tenantId: string, now?: Date): Promise<SubscriberChargeRecord[]>;
+    /**
+     * The tenant's contracts, written once more where the one in force misses
+     * a running booking.
+     *
+     * A booking writes its contract after it is saved, and a failure there does
+     * not undo the booking. The booking would then stay uncharged for good,
+     * since a charge points at a contract line — so the journal writes the
+     * contract the way the booking would have. A failure here is logged and the
+     * rest is charged: the next call tries again.
+     */
+    private contractsNamingEveryBooking;
+}
+
 declare class PreviewPlanChangeDto {
     plan: string;
     billingCycle: string;
@@ -487,7 +567,7 @@ declare class SubscriptionBundlesService {
      * number on the tenant's screen that nobody is charged, and on a yearly
      * booking it was out by whatever the yearly price is.
      */
-    listForSubscription(subscriptionId: string, planKey: string, planCycle: string): Promise<SubscriptionBundleView[]>;
+    listForSubscription(subscriptionId: string, planKey: string, planCycle: BillingCycle): Promise<SubscriptionBundleView[]>;
     /**
      * List prices for the given bundle versions, in both rhythms, resolved for
      * one plan.
@@ -546,8 +626,8 @@ interface SubscriptionBundlePreviewContext {
     subscriptionId: string;
     /** PlanKey of the current subscription (plan compatibility + redundancy source). */
     currentPlanKey: string;
-    /** 'MONTHLY' | 'YEARLY' (port convention). */
-    billingCycle: string;
+    /** The rhythm the plan is billed in. */
+    billingCycle: BillingCycle;
     /** Subscription status (TRIAL/ACTIVE/...). No proration during TRIAL. */
     status: string;
     startedAt: Date | null;
@@ -737,7 +817,8 @@ declare class TenantBillingController {
     private readonly contractFreeze;
     private readonly trialProjection;
     private readonly cancellationNoticeDays;
-    constructor(entitlements: EntitlementService, planPreview: PlanChangePreviewService, subscriptionUsage: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, subscriptionWrite: TenantSubscriptionWritePort, tenantIdResolver?: TenantIdResolver | null, userIdResolver?: UserIdResolver | null, blockedPlans?: SelfServiceBlockedPlans | null, promoCodes?: PromoCodesService | null, auditService?: AdminAuditService | null, userEmailResolver?: UserEmailResolver | null, auditContextResolver?: AuditContextResolver | null, subscriptionBundles?: SubscriptionBundlesService | null, contractFreeze?: ContractFreezePort | null, trialProjection?: TrialProjectionPort | null, cancellationNoticeDays?: CancellationNoticePeriods);
+    private readonly charges;
+    constructor(entitlements: EntitlementService, planPreview: PlanChangePreviewService, subscriptionUsage: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, subscriptionWrite: TenantSubscriptionWritePort, tenantIdResolver?: TenantIdResolver | null, userIdResolver?: UserIdResolver | null, blockedPlans?: SelfServiceBlockedPlans | null, promoCodes?: PromoCodesService | null, auditService?: AdminAuditService | null, userEmailResolver?: UserEmailResolver | null, auditContextResolver?: AuditContextResolver | null, subscriptionBundles?: SubscriptionBundlesService | null, contractFreeze?: ContractFreezePort | null, trialProjection?: TrialProjectionPort | null, cancellationNoticeDays?: CancellationNoticePeriods, charges?: SubscriberChargeService | null);
     private readonly logger;
     getEntitlement(req: RequestLike): Promise<EffectiveLimitsSnapshot>;
     getUsage(req: RequestLike): Promise<UsageResponse>;
@@ -809,4 +890,4 @@ declare class TenantBillingController {
     private auditLog;
 }
 
-export { type AddBundleToSubscriptionInput as A, type BundlePreviewSnapshot as B, type CancelBundleFromSubscriptionInput as C, clampToParent as D, computeProration as E, decideCancellation as F, decideCancellationFor as G, noticeDaysFor as H, resolveBundleCancelEffectiveAt as I, type LimitsCheckRow as L, NO_NOTICE_PERIOD as N, PendingPlanMaterializationService as P, type RedundantFeatureHint as R, type SubscriptionBundleAddPreviewDto as S, TenantAdminGuard as T, type UsageResponse as U, CancelSubscriptionDto as a, type CancellableSubscription as b, type CancellationDecision as c, type CancellationInput as d, ChangePlanDto as e, CompleteOnboardingSubscriptionDto as f, ComposedTenantAuthGuard as g, type CycleDirection as h, type PlanChangeContext as i, type PlanChangePreviewDto as j, type PlanChangePreviewIssue as k, PlanChangePreviewService as l, type PlanChangeType as m, type PlanDirection as n, type PlanSnapshotDto as o, PreviewPlanChangeDto as p, type ProrationDto as q, type ProrationInput as r, type SubscriptionBundleCancelPreviewDto as s, type SubscriptionBundleConfig as t, type SubscriptionBundlePreviewContext as u, type SubscriptionBundlePreviewIssue as v, SubscriptionBundlePreviewService as w, SubscriptionBundlesService as x, TenantBillingController as y, addMonths as z };
+export { type AddBundleToSubscriptionInput as A, type BundlePreviewSnapshot as B, type CancelBundleFromSubscriptionInput as C, TenantBillingController as D, addMonths as E, clampToParent as F, computeNewPeriodCharge as G, computeProration as H, decideCancellation as I, decideCancellationFor as J, noticeDaysFor as K, type LimitsCheckRow as L, resolveBundleCancelEffectiveAt as M, NO_NOTICE_PERIOD as N, PendingPlanMaterializationService as P, type RedundantFeatureHint as R, SubscriberChargeService as S, TenantAdminGuard as T, type UsageResponse as U, CancelSubscriptionDto as a, type CancellableSubscription as b, type CancellationDecision as c, type CancellationInput as d, ChangePlanDto as e, CompleteOnboardingSubscriptionDto as f, ComposedTenantAuthGuard as g, type CycleDirection as h, type PlanChangeContext as i, type PlanChangePreviewDto as j, type PlanChangePreviewIssue as k, PlanChangePreviewService as l, type PlanChangeType as m, type PlanDirection as n, type PlanSnapshotDto as o, PreviewPlanChangeDto as p, type ProrationBasis as q, type ProrationDto as r, type ProrationInput as s, type SubscriptionBundleAddPreviewDto as t, type SubscriptionBundleCancelPreviewDto as u, type SubscriptionBundleConfig as v, type SubscriptionBundlePreviewContext as w, type SubscriptionBundlePreviewIssue as x, SubscriptionBundlePreviewService as y, SubscriptionBundlesService as z };

package/dist/{tenant-billing.module-ClbjzocC.d.cts → tenant-billing.module-C6MFfCKq.d.cts}

@@ -1,4 +1,4 @@
-import { PlanCatalog, BillingCycle, PlanVersionRow, SubscriptionUsagePort, SubscriptionBundleRepository, BundleRepository, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriberRepository } from '@saasicat/core';
+import { PlanCatalog, BillingCycle, PlanVersionRow, SubscriptionUsagePort, SubscriptionBundleRepository, BundleRepository, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriberRepository, SubscriberLedgerRepository } from '@saasicat/core';
 import { Type, CanActivate, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
 import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
 import { T as TenantIdResolver, a as TrialProjectionPort, P as PendingPlanQueryPort, b as UserIdResolver, U as UserEmailResolver, A as AuditContextResolver } from './tenant-billing.tokens-G-1xOlMr.cjs';
@@ -198,12 +198,21 @@ interface ContractFreezeSourcePort {
      * The tenant's active (non-terminated) bundle bookings as line items,
      * priced in net. Apps without a bundle schema return empty lists.
      *
+     * A booking whose cancellation is declared is still active until its
+     * effective date, and it belongs here while it is billed. Its line does not
+     * put it into the contract's entitlements: the freeze leaves it out of the
+     * snapshot, and the booking grants its features and quotas until that date.
+     *
      * `cycle` is the **plan's** rhythm, not the bookings'. A tenant on a yearly
      * plan may hold monthly add-ons, so a source prices each booking in the
      * rhythm that booking was made in and says which one that is on the line's
      * own `billingCycle`. Pricing every line in the plan's rhythm puts a figure
      * on the contract that nobody is charged, and the contract is the evidence
      * of what was agreed.
+     *
+     * Each line names its booking's bundle version as `sourceVersionId`. The
+     * charge journal finds a booking's contract line by it, and a line without
+     * it leaves the booking uncharged.
      */
     loadBookedBundles(tenantId: string, cycle: 'monthly' | 'yearly'): Promise<ContractFreezeBundleSnapshot>;
 }
@@ -323,6 +332,20 @@ interface TenantBillingModuleOptions {
          */
         subscriberRepository: ProviderSpec<SubscriberRepository>;
     };
+    /**
+     * Optional journal of the charges each subscriber's contracts give rise to
+     * (`SubscriberChargeService`). Needs `contractFreeze`: a charge points at a
+     * contract line, and the contracts and subscribers come from there.
+     *
+     * The platform brings an account up to date after onboarding, an
+     * immediate plan change and an add-on booking; an application calls
+     * `recordDueCharges` where it writes a change itself — at activation and
+     * from its renewal job. `SubscriberAccountService` reads an account back
+     * for the operator.
+     */
+    chargeJournal?: {
+        ledgerRepository: ProviderSpec<SubscriberLedgerRepository>;
+    };
     /** Optional tenant ID resolver. Default: `req.user.tenantId`. */
     tenantIdResolver?: TenantIdResolver;
     /** Optional user ID resolver. Default: `req.user.sub ?? req.user.id`. */

package/dist/{tenant-billing.module-DohgJJ2m.d.ts → tenant-billing.module-CUCQL0-k.d.ts}

@@ -1,4 +1,4 @@
-import { PlanCatalog, BillingCycle, PlanVersionRow, SubscriptionUsagePort, SubscriptionBundleRepository, BundleRepository, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriberRepository } from '@saasicat/core';
+import { PlanCatalog, BillingCycle, PlanVersionRow, SubscriptionUsagePort, SubscriptionBundleRepository, BundleRepository, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriberRepository, SubscriberLedgerRepository } from '@saasicat/core';
 import { Type, CanActivate, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
 import { P as ProviderSpec } from './di-CcNeq9v-.js';
 import { T as TenantIdResolver, a as TrialProjectionPort, P as PendingPlanQueryPort, b as UserIdResolver, U as UserEmailResolver, A as AuditContextResolver } from './tenant-billing.tokens-G-1xOlMr.js';
@@ -198,12 +198,21 @@ interface ContractFreezeSourcePort {
      * The tenant's active (non-terminated) bundle bookings as line items,
      * priced in net. Apps without a bundle schema return empty lists.
      *
+     * A booking whose cancellation is declared is still active until its
+     * effective date, and it belongs here while it is billed. Its line does not
+     * put it into the contract's entitlements: the freeze leaves it out of the
+     * snapshot, and the booking grants its features and quotas until that date.
+     *
      * `cycle` is the **plan's** rhythm, not the bookings'. A tenant on a yearly
      * plan may hold monthly add-ons, so a source prices each booking in the
      * rhythm that booking was made in and says which one that is on the line's
      * own `billingCycle`. Pricing every line in the plan's rhythm puts a figure
      * on the contract that nobody is charged, and the contract is the evidence
      * of what was agreed.
+     *
+     * Each line names its booking's bundle version as `sourceVersionId`. The
+     * charge journal finds a booking's contract line by it, and a line without
+     * it leaves the booking uncharged.
      */
     loadBookedBundles(tenantId: string, cycle: 'monthly' | 'yearly'): Promise<ContractFreezeBundleSnapshot>;
 }
@@ -323,6 +332,20 @@ interface TenantBillingModuleOptions {
          */
         subscriberRepository: ProviderSpec<SubscriberRepository>;
     };
+    /**
+     * Optional journal of the charges each subscriber's contracts give rise to
+     * (`SubscriberChargeService`). Needs `contractFreeze`: a charge points at a
+     * contract line, and the contracts and subscribers come from there.
+     *
+     * The platform brings an account up to date after onboarding, an
+     * immediate plan change and an add-on booking; an application calls
+     * `recordDueCharges` where it writes a change itself — at activation and
+     * from its renewal job. `SubscriberAccountService` reads an account back
+     * for the operator.
+     */
+    chargeJournal?: {
+        ledgerRepository: ProviderSpec<SubscriberLedgerRepository>;
+    };
     /** Optional tenant ID resolver. Default: `req.user.tenantId`. */
     tenantIdResolver?: TenantIdResolver;
     /** Optional user ID resolver. Default: `req.user.sub ?? req.user.id`. */

package/dist/testing/index.d.cts

@@ -1,20 +1,20 @@
 import { BundleRepository, BundleRow, BundleVersionRow, BundleListFilter, CreateBundleData, UpdateBundleData, CreateBundleVersionDraftData, UpdateBundleVersionDraftData, VersionChange, MarketingProjectionRepository, MarketingProjectionRow, MarketingProjectionFilter, CreateMarketingProjectionData, UpdateMarketingProjectionData, PlanRepository, PlanRow, PlanVersionRow, PlanListFilter, CreatePlanData, UpdatePlanData, CreatePlanVersionDraftData, UpdatePlanVersionDraftData, PlanVersionRepository, PlanVersionRecord, TransactionContext, SubscriberRepository, CreateSubscriberData, SubscriberRecord, SubscriberContactChange, SubscriberCorrectionData, SubscriberCorrectionResult, SubscriberCorrectionRecord, SubscriptionBundleRepository, SubscriptionBundleRecord, CreateSubscriptionBundleData, CancelSubscriptionBundleData, SubscriptionContractRepository, SubscriptionContractFilter, SubscriptionContractRecord, NewSubscriptionContractData, TerminateSubscriptionContractData, RunningContractIssuers, SubscriptionRepository, SubscriptionRecord, TransactionRunner, PlanCatalog, QuotaProvider } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
-import { S as SaaSiCatAdapters } from '../module-options-qAOwinHR.cjs';
-export { P as PLAN_RESOLVER_PORT_TOKEN, a as StaticPlanResolver } from '../module-options-qAOwinHR.cjs';
-export { E as EnforceQuotaInterceptor, S as StaticEntitlementService, a as StaticFeatureGuard } from '../enforce-quota.interceptor-BFyVdWe8.cjs';
+import { S as SaaSiCatAdapters } from '../module-options-C4S_StYF.cjs';
+export { P as PLAN_RESOLVER_PORT_TOKEN, a as StaticPlanResolver } from '../module-options-C4S_StYF.cjs';
+export { E as EnforceQuotaInterceptor, S as StaticEntitlementService, a as StaticFeatureGuard } from '../enforce-quota.interceptor-B9UhCBXx.cjs';
 import '../di-CcNeq9v-.cjs';
 import '../admin-resources.module-B4XNvdH-.cjs';
 import '../admin-audit.service-4P3Djdxk.cjs';
-import '../tenant-billing.module-ClbjzocC.cjs';
+import '../tenant-billing.module-C6MFfCKq.cjs';
 import '../tenant-billing.tokens-G-1xOlMr.cjs';
 import '../contract-line-item-money-B0Z3Ogur.cjs';
 import '../catalog.module-T-I5Ricz.cjs';
 import '../discovery.scanner-DXKc6JkV.cjs';
 import '@nestjs/core';
 import '../plan-resolution-CwUy_OqC.cjs';
-import '../promo.module-CKkECmU8.cjs';
-import '../promo.service-BYBu6dy3.cjs';
+import '../promo.module-Ddx-swUV.cjs';
+import '../promo.service-BextPvx5.cjs';
 import '../plan-catalog-source-DWe-BGY1.cjs';
 import '../checkout-offer.module-DFhGy6JO.cjs';
 import '../payments.module-BdUq9ot_.cjs';

package/dist/testing/index.d.ts

@@ -1,20 +1,20 @@
 import { BundleRepository, BundleRow, BundleVersionRow, BundleListFilter, CreateBundleData, UpdateBundleData, CreateBundleVersionDraftData, UpdateBundleVersionDraftData, VersionChange, MarketingProjectionRepository, MarketingProjectionRow, MarketingProjectionFilter, CreateMarketingProjectionData, UpdateMarketingProjectionData, PlanRepository, PlanRow, PlanVersionRow, PlanListFilter, CreatePlanData, UpdatePlanData, CreatePlanVersionDraftData, UpdatePlanVersionDraftData, PlanVersionRepository, PlanVersionRecord, TransactionContext, SubscriberRepository, CreateSubscriberData, SubscriberRecord, SubscriberContactChange, SubscriberCorrectionData, SubscriberCorrectionResult, SubscriberCorrectionRecord, SubscriptionBundleRepository, SubscriptionBundleRecord, CreateSubscriptionBundleData, CancelSubscriptionBundleData, SubscriptionContractRepository, SubscriptionContractFilter, SubscriptionContractRecord, NewSubscriptionContractData, TerminateSubscriptionContractData, RunningContractIssuers, SubscriptionRepository, SubscriptionRecord, TransactionRunner, PlanCatalog, QuotaProvider } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
-import { S as SaaSiCatAdapters } from '../module-options-DmQ3G4sZ.js';
-export { P as PLAN_RESOLVER_PORT_TOKEN, a as StaticPlanResolver } from '../module-options-DmQ3G4sZ.js';
-export { E as EnforceQuotaInterceptor, S as StaticEntitlementService, a as StaticFeatureGuard } from '../enforce-quota.interceptor-GaBXboGx.js';
+import { S as SaaSiCatAdapters } from '../module-options-DxJI-1iH.js';
+export { P as PLAN_RESOLVER_PORT_TOKEN, a as StaticPlanResolver } from '../module-options-DxJI-1iH.js';
+export { E as EnforceQuotaInterceptor, S as StaticEntitlementService, a as StaticFeatureGuard } from '../enforce-quota.interceptor-CR2waXNA.js';
 import '../di-CcNeq9v-.js';
 import '../admin-resources.module-CWqdI9BV.js';
 import '../admin-audit.service-4P3Djdxk.js';
-import '../tenant-billing.module-DohgJJ2m.js';
+import '../tenant-billing.module-CUCQL0-k.js';
 import '../tenant-billing.tokens-G-1xOlMr.js';
 import '../contract-line-item-money-B0Z3Ogur.js';
 import '../catalog.module-C9O7BxRq.js';
 import '../discovery.scanner-DXKc6JkV.js';
 import '@nestjs/core';
 import '../plan-resolution-CwUy_OqC.js';
-import '../promo.module-DuIJdK3U.js';
-import '../promo.service-CFjfF0Xm.js';
+import '../promo.module-PsIvDcUp.js';
+import '../promo.service-Dqqh0JXn.js';
 import '../plan-catalog-source-DWe-BGY1.js';
 import '../checkout-offer.module-x7SP_dX4.js';
 import '../payments.module-CQGv_VG7.js';

package/dist/testing/index.js

@@ -5,32 +5,33 @@ import {
   StaticEntitlementService,
   StaticFeatureGuard,
   StaticPlanResolver
-} from "../chunk-AOS2JPDD.js";
-import "../chunk-4SDSYV4A.js";
-import "../chunk-XSSWYPP5.js";
-import "../chunk-LLYVYRGJ.js";
-import "../chunk-M47BNEY2.js";
+} from "../chunk-FJIOHAO5.js";
+import "../chunk-T6WXDGIU.js";
+import "../chunk-UMZCOCT5.js";
+import "../chunk-F2PF4IXB.js";
+import "../chunk-3YYLOYUT.js";
+import "../chunk-OSOP4KWL.js";
 import "../chunk-CQ2ZZMTD.js";
 import "../chunk-GZTL64QK.js";
 import "../chunk-34XVPR6P.js";
 import "../chunk-OOTEXP47.js";
-import "../chunk-TOEFN7DN.js";
-import "../chunk-55QEDAMX.js";
-import "../chunk-3RLWML2S.js";
-import "../chunk-NDLC5GYK.js";
+import "../chunk-FPMBQDW7.js";
+import "../chunk-WTAS2CLM.js";
+import "../chunk-QWKBOLBH.js";
+import "../chunk-EU4N5LET.js";
 import "../chunk-KPEMTBOP.js";
 import "../chunk-S33SO5XX.js";
 import "../chunk-JVAEKTJ4.js";
-import "../chunk-WHJSYKNC.js";
-import "../chunk-G6EZWECL.js";
+import "../chunk-3U4N5UYD.js";
+import "../chunk-B4YP7REK.js";
 import "../chunk-OUDSQ3PU.js";
 import "../chunk-TBBZWZQT.js";
 import "../chunk-VBRYPU7V.js";
 import "../chunk-6PJE7EWO.js";
 import "../chunk-3QVGA6JX.js";
 import "../chunk-QUZU2M33.js";
-import "../chunk-QPVDCKYS.js";
-import "../chunk-7NJKVC5X.js";
+import "../chunk-ESEWSAOV.js";
+import "../chunk-WQNOCOI2.js";
 import "../chunk-5CKC7O52.js";
 import "../chunk-GPQWGA6B.js";
 import "../chunk-SZ7RFPXA.js";
@@ -233,15 +234,7 @@ var FakeSubscriptionContractRepository = class {
       originalBundleVersionIds: [
         ...data.originalBundleVersionIds ?? []
       ],
-      entitlementSnapshot: data.entitlementSnapshot ? {
-        plan: data.entitlementSnapshot.plan,
-        quotas: {
-          ...data.entitlementSnapshot.quotas
-        },
-        features: [
-          ...data.entitlementSnapshot.features
-        ]
-      } : null,
+      entitlementSnapshot: data.entitlementSnapshot ? cloneEntitlementSnapshot(data.entitlementSnapshot) : null,
       priceSnapshot: {
         ...data.priceSnapshot
       },
@@ -322,15 +315,7 @@ var FakeSubscriptionContractRepository = class {
       originalBundleVersionIds: [
         ...row.originalBundleVersionIds
       ],
-      entitlementSnapshot: row.entitlementSnapshot ? {
-        plan: row.entitlementSnapshot.plan,
-        quotas: {
-          ...row.entitlementSnapshot.quotas
-        },
-        features: [
-          ...row.entitlementSnapshot.features
-        ]
-      } : null,
+      entitlementSnapshot: row.entitlementSnapshot ? cloneEntitlementSnapshot(row.entitlementSnapshot) : null,
       priceSnapshot: {
         ...row.priceSnapshot
       },
@@ -1069,6 +1054,23 @@ var FakePlanRepository = class {
     return updated;
   }
 };
+function cloneEntitlementSnapshot(snapshot) {
+  return {
+    plan: snapshot.plan,
+    quotas: {
+      ...snapshot.quotas
+    },
+    features: [
+      ...snapshot.features
+    ],
+    ...snapshot.leftOutBundleVersionIds ? {
+      leftOutBundleVersionIds: [
+        ...snapshot.leftOutBundleVersionIds
+      ]
+    } : {}
+  };
+}
+__name(cloneEntitlementSnapshot, "cloneEntitlementSnapshot");
 
 // src/testing/create-saasicat-test-module.ts
 import { Module } from "@nestjs/common";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/nest",
-  "version": "1.0.0-rc.21",
+  "version": "1.0.0-rc.22",
   "description": "NestJS implementation of SaaSiCat: capability discovery, catalog packaging, contracts, entitlement enforcement, billing and admin APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -158,8 +158,8 @@
     "js-yaml": "^4.3.2",
     "otplib": "^13.4.1",
     "qrcode": "^1.5.4",
-    "@saasicat/spec": "^1.0.0-rc.21",
-    "@saasicat/core": "^1.0.0-rc.21"
+    "@saasicat/spec": "^1.0.0-rc.22",
+    "@saasicat/core": "^1.0.0-rc.22"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",