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

package/dist/billing/index.d.ts

@@ -1,25 +1,76 @@
-import { BillingCycle, FeatureKey, UpsellOfferResolver, BundleRepository, CatalogEntryRepository, UpsellOffer, PlanCatalog, PlanCatalogReadSink, PlanCatalogReadSnapshot, PlanCatalogImportSink, PlanCatalogImportReport, PlanId, PlanDef, QuotaKey, MarketingTopFeature, FeatureUiRegistry, MarketingProjectionRepository, ConfiguratorSourcesLookup, ConfiguratorMarketingProvider, ConfiguratorCatalog } from '@saasicat/core';
-export { BundleVersionFields, ChangeDirection, DiffResult, PlanVersionFields, VersionChange, VersionChangeDirection, classifyBundleVersionDiff, classifyPlanDiff } from '@saasicat/core';
-import { F as FEATURE_GUARD_MARKER, f as ContractFreezePort, g as ContractFreezeSourcePort } from '../tenant-billing.module-wUbsQSFG.js';
-export { A as AUDIT_CONTEXT_RESOLVER_TOKEN, a as AuditContextResolver, b as AuthGuardList, C as CONTRACT_FREEZE_PORT_TOKEN, c as CONTRACT_FREEZE_PROJECT_KEY_TOKEN, d as CONTRACT_FREEZE_SOURCE_PORT_TOKEN, e as ContractFreezeBundleSnapshot, D as DuePendingPlanChange, M as MarkedFeatureGuard, P as PENDING_PLAN_QUERY_PORT_TOKEN, h as PendingPlanQueryPort, S as SELF_SERVICE_BLOCKED_BUNDLES_TOKEN, i as SELF_SERVICE_BLOCKED_PLANS_TOKEN, j as SUBSCRIPTION_USAGE_PORT_TOKEN, k as SUBSCRIPTION_WRITE_PORT_TOKEN, l as SelfServiceBlockedBundles, m as SelfServiceBlockedPlans, n as SubscriptionBundleControllerOptions, o as SubscriptionBundleModule, p as SubscriptionBundleModuleOptions, T as TENANT_AUTH_GUARDS_TOKEN, q as TENANT_ID_RESOLVER_TOKEN, r as TRIAL_PROJECTION_PORT_TOKEN, s as TenantBillingModule, t as TenantBillingModuleOptions, u as TenantIdResolver, v as TrialProjectionInput, w as TrialProjectionPort, U as USAGE_SNAPSHOT_PORT_TOKEN, x as USER_EMAIL_RESOLVER_TOKEN, y as USER_ID_RESOLVER_TOKEN, z as UserEmailResolver, B as UserIdResolver, E as isPlatformFeatureGuard } from '../tenant-billing.module-wUbsQSFG.js';
+import { BillingCycle, BundleVersionRow, FeatureKey, UpsellOfferResolver, BundleRepository, CatalogEntryRepository, UpsellOffer, PlanCatalogSettings, PlanCatalogReadSink, PlanCatalog, PlanCatalogReadSnapshot, PlanCatalogImportSink, PlanCatalogImportReport, PlanId, PlanDef, QuotaKey, MarketingTopFeature, FeatureUiRegistry, MarketingProjectionRepository, TenantSubscriptionWritePort, ConfiguratorSourcesLookup, ConfiguratorMarketingProvider, ConfiguratorCatalog } from '@saasicat/core';
+export { BundleVersionFields, CancellationNoticePeriods, ChangeDirection, DiffResult, PlanVersionFields, SelfServiceBlockedPlans, VersionChange, VersionChangeDirection, classifyBundleVersionDiff, classifyPlanDiff } from '@saasicat/core';
+export { A as AddBundleToSubscriptionInput, B as BundlePreviewSnapshot, C as CancelBundleFromSubscriptionInput, a as CancelSubscriptionDto, b as CancellableSubscription, c as CancellationDecision, d as CancellationInput, e as ChangePlanDto, f as CompleteOnboardingSubscriptionDto, g as ComposedTenantAuthGuard, h as CycleDirection, L as LimitsCheckRow, N as NO_NOTICE_PERIOD, P as PendingPlanMaterializationService, i as PlanChangeContext, j as PlanChangePreviewDto, k as PlanChangePreviewIssue, l as PlanChangePreviewService, m as PlanChangeType, n as PlanDirection, o as PlanSnapshotDto, p as PreviewPlanChangeDto, q as ProrationDto, r as ProrationInput, R as RedundantFeatureHint, S as SubscriptionBundleAddPreviewDto, s as SubscriptionBundleCancelPreviewDto, t as SubscriptionBundleConfig, u as SubscriptionBundlePreviewContext, v as SubscriptionBundlePreviewIssue, w as SubscriptionBundlePreviewService, x as SubscriptionBundlesService, T as TenantAdminGuard, y as TenantBillingController, U as UsageResponse, z as addMonths, D as clampToParent, E as computeProration, F as decideCancellation, G as decideCancellationFor, H as noticeDaysFor, I as resolveBundleCancelEffectiveAt } from '../tenant-billing.controller-BLqbsONe.js';
+import { F as FEATURE_GUARD_MARKER, d as ContractFreezePort, e as ContractFreezeSourcePort } from '../tenant-billing.module-DohgJJ2m.js';
+export { A as AjvErrorLike, C as CONTRACT_FREEZE_PORT_TOKEN, b as CONTRACT_FREEZE_SOURCE_PORT_TOKEN, c as ContractFreezeBundleSnapshot, E as EnvironmentVariables, f as LoadPlanCatalogFromStringOptions, L as LoadPlanCatalogOptions, M as MarkedFeatureGuard, P as PLAN_CATALOG_UNREADABLE_ERROR, g as PlanCatalogValidationError, h as SELF_SERVICE_BLOCKED_BUNDLES_TOKEN, i as SELF_SERVICE_BLOCKED_PLANS_TOKEN, j as SelfServiceBlockedBundles, a as SubscriptionBundleControllerOptions, k as SubscriptionBundleModule, S as SubscriptionBundleModuleOptions, l as TenantBillingModule, T as TenantBillingModuleOptions, m as catalogSource, n as isPlatformFeatureGuard, o as loadPlanCatalogFromFile, p as loadPlanCatalogFromString } from '../tenant-billing.module-DohgJJ2m.js';
 import * as _nestjs_common from '@nestjs/common';
 import { CanActivate, ExecutionContext, ArgumentsHost, Type, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
 export { Type as NestType } from '@nestjs/common';
 import { Reflector, BaseExceptionFilter } from '@nestjs/core';
-import { c as EntitlementService } from '../aggregation-BFzW07DE.js';
+import { c as EntitlementService } from '../aggregation-ChpZDh0g.js';
 import { P as ProviderSpec } from '../di-CcNeq9v-.js';
-export { A as AddBundleToSubscriptionInput, B as BundlePreviewSnapshot, C as CancelBundleFromSubscriptionInput, a as CancelSubscriptionDto, b as ChangePlanDto, c as CompleteOnboardingSubscriptionDto, d as ComposedTenantAuthGuard, L as LimitsCheckRow, P as PendingPlanMaterializationService, e as PlanChangeContext, f as PlanChangePreviewDto, g as PlanChangePreviewIssue, h as PlanChangePreviewService, i as PlanChangeType, j as PlanSnapshotDto, k as PreviewPlanChangeDto, l as ProrationDto, m as ProrationInput, R as RedundantFeatureHint, S as SubscriptionBundleAddPreviewDto, n as SubscriptionBundleCancelPreviewDto, o as SubscriptionBundleConfig, p as SubscriptionBundlePreviewContext, q as SubscriptionBundlePreviewIssue, r as SubscriptionBundlePreviewService, s as SubscriptionBundlesService, T as TenantAdminGuard, t as TenantBillingController, U as UsageResponse, u as addMonths, v as computeProration, w as resolveBundleCancelEffectiveAt, x as resolveBundlePriceNet } from '../tenant-billing.controller-BQ67mlmI.js';
-import { S as SubscriptionContractService } from '../subscription-contract.service-hD87MKyg.js';
-import '../plan-resolution-Cgo_TR1H.js';
-import '../promo.service-BJbKAmw3.js';
+import { P as PlanCatalogSource } from '../plan-catalog-source-DWe-BGY1.js';
+export { a as PlanCatalogOrigin, g as givenPlanCatalogSource } from '../plan-catalog-source-DWe-BGY1.js';
+import { d as AuthGuardList } from '../tenant-billing.tokens-G-1xOlMr.js';
+export { c as AUDIT_CONTEXT_RESOLVER_TOKEN, A as AuditContextResolver, B as BILLING_PERMISSION_GUARDS_TOKEN, C as CANCELLATION_NOTICE_DAYS_TOKEN, D as DuePendingPlanChange, e as PENDING_PLAN_QUERY_PORT_TOKEN, P as PendingPlanQueryPort, S as SUBSCRIPTION_USAGE_PORT_TOKEN, f as SUBSCRIPTION_WRITE_PORT_TOKEN, g as TENANT_AUTH_GUARDS_TOKEN, h as TENANT_ID_RESOLVER_TOKEN, i as TRIAL_PROJECTION_PORT_TOKEN, T as TenantIdResolver, j as TrialProjectionInput, a as TrialProjectionPort, k as USAGE_SNAPSHOT_PORT_TOKEN, l as USER_EMAIL_RESOLVER_TOKEN, m as USER_ID_RESOLVER_TOKEN, U as UserEmailResolver, b as UserIdResolver } from '../tenant-billing.tokens-G-1xOlMr.js';
+import { S as SubscriptionContractService } from '../subscription-contract.service-CPZrTM9C.js';
+import '../promo.service-CFjfF0Xm.js';
 import '../admin-audit.service-4P3Djdxk.js';
+import '../contract-line-item-money-B0Z3Ogur.js';
+import '../plan-resolution-CwUy_OqC.js';
+import '../subscriber.service-5W6Gi-1B.js';
 
+/**
+ * One period onwards, on `anchorDay` where the month has one.
+ *
+ * The anchor is the day the subscription is billed on, and it survives months
+ * that are too short for it. Without one, this function has to read the day
+ * from its own input — and its own input is the previous clamped result, so a
+ * February eats the anchor and never gives it back: 31 January became 28
+ * February and then 28 March, 28 April, 28 May, for the rest of the
+ * subscription's life. Three days lost once, invisibly, and every later date
+ * measured from the wrong one.
+ *
+ * Clamping applies to the step's OUTPUT, never to the next step's input. A
+ * subscription anchored on the 31st is billed on the 28th in February and on
+ * the 31st again in March; one anchored on the 30th is billed on the 30th in
+ * October, not the 31st. The anchor is a day number, not "the end of the
+ * month".
+ *
+ * Omitting it keeps the old reading — the day of `d` — which is right wherever
+ * a caller has only one step to take and `d` is itself the anchor.
+ */
+declare function advanceOneCycle(d: Date, cycle: BillingCycle, anchorDay?: number): Date;
+/**
+ * One period backwards, on `anchorDay` where the month has one.
+ *
+ * The mirror of `advanceOneCycle`, and it exists for one question: how long is
+ * the full period that ends here? A short first period is charged pro rata
+ * against a whole cycle, and a whole cycle is only measurable from both of its
+ * ends. Reading its length from the calendar month instead is wrong wherever
+ * the anchor is not the 1st — a period ending on 28 February with an anchor of
+ * 31 runs from 31 January, which is 28 days, not the 31 that February's
+ * neighbour would suggest.
+ *
+ * The same clamp rule applies, and applies to this step's output: from 31
+ * March backwards on anchor 31 is 28 February, and from there backwards again
+ * is 31 January, not 28 January. The anchor is never consumed.
+ */
+declare function retreatOneCycle(d: Date, cycle: BillingCycle, anchorDay?: number): Date;
+/**
+ * The day of the month a subscription is billed on.
+ *
+ * Read from whichever date opened the current run of periods — the start of the
+ * window, not the end of the last one, because the end has already been through
+ * a clamp.
+ */
+declare function billingAnchorDay(windowStart: Date): number;
 /**
  * Finds the next period boundary that lies strictly **after** `after`.
  * Iterates from `startedAt` (fallback: `after`) by +1 cycle each time, until
  * the result is greater than `after`.
  */
-declare function periodEndAfter(startedAt: Date | null, cycle: BillingCycle, after: Date): Date;
+declare function periodEndAfter(startedAt: Date | null, cycle: BillingCycle, after: Date, anchorDay?: number): Date;
 /**
  * Returns the initial period window for a subscription
  * (`currentPeriodStart`/`currentPeriodEnd`). `start` is `startedAt`,
@@ -42,7 +93,203 @@ declare function initialPeriodWindow(startedAt: Date, cycle: BillingCycle): {
  *
  * Spec: ROADMAP §2 no. 3 (advance-warning period), §6.1 (time-based selection).
  */
-declare function periodEndWithMinLead(startedAt: Date | null, cycle: BillingCycle, now: Date, minLeadDays?: number): Date;
+declare function periodEndWithMinLead(startedAt: Date | null, cycle: BillingCycle, now: Date, minLeadDays?: number, anchorDay?: number): Date;
+
+/** What a caller knows about the plan's billing rhythm, before resolving it. */
+interface PlanAnchorSource {
+    /** The stored anchor, where the subscription has one. */
+    billingAnchorDay?: number | null;
+    /** The date that opened the current run of periods. */
+    currentPeriodStart?: Date | null;
+    /** What opened it before the first window was written. */
+    startedAt?: Date | null;
+}
+/**
+ * The day of the month the plan is billed on, resolved once for everybody.
+ *
+ * Every caller that quotes a bundle and every caller that books one has to
+ * reach the same answer, or the preview describes a different contract from the
+ * one written — and this is the field that decides the difference. It happened:
+ * the preview derived the day from the window start while the booking left the
+ * value null and let the arithmetic read the window END, so for a 31 January to
+ * 28 February window the preview quoted a period ending on the 31st and the
+ * booking stored the 28th, after which the two renewed on different days
+ * forever.
+ *
+ * The order is authority, not convenience. The stored anchor is the answer
+ * where it exists. Failing that, the day that OPENED the current window —
+ * never the day that closed it, because a closing day has already been through
+ * a clamp and reading it is how a subscription billed on the 31st ends up
+ * billed on the 28th for the rest of its life.
+ */
+declare function resolvePlanAnchorDay(source: PlanAnchorSource): number | null;
+interface BundleFirstPeriodInput {
+    /** When the bundle was booked. */
+    startedAt: Date;
+    /** The bundle's own cycle — never longer than the plan's. */
+    cycle: BillingCycle;
+    /** When the plan's current period ends, if it has one. */
+    planPeriodEnd: Date | null;
+    /** The day of the month the plan is billed on, if it is known. */
+    planAnchorDay: number | null;
+}
+/**
+ * The end of a bundle's first period: short, and landing on the plan's day.
+ *
+ * Null where the plan has no period to align to — a trial, or a subscription
+ * still waiting for sales. A bundle booked there has no period of its own
+ * either, rather than one invented from the booking date.
+ */
+declare function bundleFirstPeriodEnd(input: BundleFirstPeriodInput): Date | null;
+/**
+ * The start of the full cycle that the first period is a part of.
+ *
+ * Not the booking date: the first period is short, and a short period is
+ * charged pro rata against a **whole** cycle. That whole cycle ends where the
+ * first period ends and begins one cycle before it — so a monthly bundle
+ * booked on 21 February against a plan anchored on the 31st is charged for
+ * 7 of the 28 days between 31 January and 28 February, not for 7 of 31, and
+ * not for the 160 days left of the plan's own yearly period.
+ *
+ * Prorating against the plan's period was the shape this used to have, and it
+ * is wrong by the width of the difference between the two cycles: a monthly
+ * bundle on a yearly plan was charged a fraction of a *year* at a monthly
+ * price.
+ */
+declare function bundleFirstPeriodStart(firstPeriodEnd: Date, cycle: BillingCycle, planAnchorDay: number | null): Date;
+/**
+ * The end of every period after the first: one cycle on, still on the plan's
+ * day.
+ */
+declare function bundleNextPeriodEnd(currentPeriodEnd: Date, cycle: BillingCycle, planAnchorDay: number | null): Date;
+/**
+ * Whether a bundle may be billed on `bundleCycle` beside a plan on `planCycle`.
+ *
+ * A bundle may run in a shorter rhythm than its plan, never a longer one. A
+ * yearly bundle on a monthly plan has no boundary to meet — the plan's periods
+ * end twelve times before the bundle's first one does, and every one of those
+ * ends is a moment the plan could stop and leave the bundle committed with
+ * nothing to grant.
+ *
+ * The shorter direction is fine and is the interesting case: a monthly bundle
+ * on a yearly plan simply lands on the plan's day every month, and on the
+ * plan's own boundary in the month the plan ends.
+ */
+/**
+ * How long a booking commits the tenant when nobody says otherwise: **not at
+ * all**.
+ *
+ * An add-on can be cancelled at any time up to the moment its next period
+ * begins, and the cancellation takes effect at the end of the period it is in.
+ * The tenant pays for the period they are in, it ends normally, and nothing
+ * has to be paid back — which is the whole reason the rule is shaped this way.
+ *
+ * It was 12 until 2026-08-27, applied to every booking without an operator
+ * doing anything, and it made that rule impossible: a cancellation lands at
+ * `max(currentPeriodEnd, minimumTermEndsAt)`, so a monthly add-on booked today
+ * could not be cancelled to next month. On a yearly plan the term even
+ * outlasted the bundle's own last period. An operator who wants a commitment
+ * configures one; nobody gets one by default.
+ */
+declare const DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS = 0;
+declare function bundleCycleFitsPlan(bundleCycle: BillingCycle, planCycle: BillingCycle): boolean;
+/** What a renewal job reads from a booking to decide whether to roll it on. */
+interface BundlePeriodRollInput {
+    /**
+     * Null in two different situations, and the difference decides everything:
+     * a booking made before these columns existed, and one whose plan had no
+     * period to align to yet — a trial, or a subscription awaiting sales.
+     *
+     * `billingCycle` is what tells them apart. The booking route always writes
+     * it, so a row that has one but no window is the second case and is waiting
+     * for a window; a row with neither is the first and is billed with the plan.
+     */
+    currentPeriodEnd: Date | null;
+    /** Null only on a booking made before bundles had a rhythm of their own. */
+    billingCycle: BillingCycle | null;
+    canceledAt: Date | null;
+    canceledEffectiveAt: Date | null;
+}
+/** The plan the booking hangs off, as the same job reads it. */
+interface BundlePlanContext {
+    billingCycle: BillingCycle;
+    billingAnchorDay: number | null;
+    /** When the plan ends, or null while it runs on. */
+    endsAt: Date | null;
+    /**
+     * The plan's own window, which a booking still waiting for one joins.
+     *
+     * Null while the plan has no paid period either — then there is nothing to
+     * align to and the booking keeps waiting.
+     */
+    currentPeriodStart?: Date | null;
+    currentPeriodEnd?: Date | null;
+}
+/** The window a roll opens. */
+interface BundlePeriodWindow {
+    currentPeriodStart: Date;
+    currentPeriodEnd: Date;
+}
+/**
+ * The window a booking should hold now, or `null` for nothing to do.
+ *
+ * The bundle counterpart of `computeNextPeriod`, and the same division of
+ * labour: the platform decides, the consumer's cron reads, writes and audits.
+ * Without it the columns written at booking would never move again, and "every
+ * period after the first runs anchor to anchor" would be a claim nothing keeps.
+ *
+ * It answers two questions the job cannot tell apart from the outside, because
+ * both look like a booking whose window is not current:
+ *
+ * - **Opening the first window.** A bundle booked while its plan had no period —
+ *   during a trial, or before sales finished — was stored without one, because
+ *   there was nothing to align to. Once the plan has a paid period the booking
+ *   joins it. Left undone, a monthly bundle on a yearly trial kept granting its
+ *   features and never acquired a window to bill them in.
+ * - **Rolling the next one.** The ordinary case, anchor to anchor.
+ *
+ * It declines in four:
+ *
+ * - **A booking billed with the plan** — written before these columns existed,
+ *   recognisable by having no rhythm of its own either. Giving it a window would
+ *   start billing it a second time.
+ * - **The plan has no paid period yet**, so there is still nothing to align to.
+ * - **The period is still running.** The job's filter should not have offered it.
+ * - **The booking's own cancellation has landed.** A declared one changes
+ *   nothing, exactly as for a subscription.
+ * - **The plan has ended, or ends before the new period could open.** This is
+ *   the rule the alignment exists for: the bundle ends with the plan, without a
+ *   cancellation of its own.
+ *
+ * Where the plan ends *inside* the new period — which only happens when someone
+ * ends it off-anchor — the window is cut back to the plan's end rather than
+ * allowed to outlive it. A bundle committed past its plan is the one state this
+ * whole arrangement is built to prevent.
+ */
+declare function computeNextBundlePeriod(booking: BundlePeriodRollInput, plan: BundlePlanContext, now: Date): BundlePeriodWindow | null;
+
+/**
+ * List price (net) for the billing cycle, including a plan-specific pricing
+ * override (`BundlePricingOverride` with `planId`).
+ *
+ * `null` means no price is maintained for that combination — not that the
+ * bundle is free. A published bundle always resolves *some* price, which the
+ * publish gate checks; what it cannot check is the combination, since that
+ * depends on the plan the tenant is on and the rhythm they are billed in.
+ */
+declare function resolveBundlePriceNet(bundleVersion: BundleVersionRow, planKey: string, billingCycle: string): number | null;
+/**
+ * The cycles a plan version is actually sold in.
+ *
+ * Derived from the prices it carries rather than from a list of cycles, so a
+ * plan priced monthly only is a monthly plan and nothing has to say so
+ * separately. A version with neither price is sold in no cycle at all — the
+ * plan's own publish gate refuses that, and here it simply asks nothing.
+ */
+declare function cyclesSoldFor(planVersion: {
+    monthlyNet?: string | null;
+    yearlyNet?: string | null;
+}): BillingCycle[];
 
 /** Generic shape of a PlanVersion snapshot for publish validation. */
 interface PublishablePlanVersion {
@@ -113,6 +360,16 @@ interface RenewalSubInput {
     pendingPlanVersionAccepted: boolean;
     /** `nonRegressive` from the referenced PlanVersion. */
     pendingPlanVersionNonRegressive: boolean;
+    /**
+     * The cancellation, read the same way `computeNextPeriod` reads it below.
+     *
+     * A version published before the customer cancelled still comes due
+     * afterwards, and rolling it forward rewrites the plan of a subscription
+     * whose term is over. Required, and required together, because a record
+     * that omits them answers "not cancelled" and goes ahead.
+     */
+    canceledAt: Date | null;
+    canceledEffectiveAt: Date | null;
 }
 /**
  * Decides what should happen to a subscription with a due pending version.
@@ -134,25 +391,66 @@ declare function clearPendingPlanVersionFields(): {
 };
 /** Input shape for `computeNextPeriod`. */
 interface PeriodRollInput {
+    /**
+     * The day of the month this subscription is billed on, or null on a row
+     * that predates the column. Null falls back to the day of the period end,
+     * which is the reading that drifts — so a consumer that stores the anchor
+     * gets the correct date and one that does not keeps today's behaviour.
+     */
+    billingAnchorDay?: number | null;
     /** Subscription.currentPeriodEnd. NULL → no period active → SKIP. */
     currentPeriodEnd: Date | null;
     billingCycle: BillingCycle;
+    /**
+     * When a cancellation was declared — and, on a row written before the two
+     * fields parted company, also when it lands.
+     *
+     * It used to stop the renewal on its own, which was right while it carried
+     * both meanings. Since they separated it is normally only "the customer
+     * said so": a subscription cancelled in month three of a year still runs,
+     * and stopping its renewal would end it nine months early.
+     *
+     * The exception is the row that predates the split. There `canceledAt`
+     * holds the period end the old code computed and `canceledEffectiveAt` is
+     * null, so reading only the second would roll a cancelled subscription into
+     * another paid term, and the next one, forever.
+     */
     canceledAt: Date | null;
+    /**
+     * When that cancellation lands. This is what stops the renewal.
+     *
+     * Null while none was declared. A period may still roll onto it: with a
+     * notice period configured, a late cancellation lands at the end of the
+     * FOLLOWING period, and that period has to exist to end.
+     */
+    canceledEffectiveAt: Date | null;
 }
 /** Result: the next period window or `null` (skip). */
 interface NextPeriodWindow {
     currentPeriodStart: Date;
     currentPeriodEnd: Date;
+    /**
+     * The renewed commitment, which is the period itself.
+     *
+     * The minimum term IS the chosen billing period (rule a), it starts at
+     * activation (rule c) and it renews with the period unless a cancellation
+     * was declared first (rule d). Written on every roll so nothing has to
+     * reconstruct it later from a start date and a cycle.
+     */
+    minimumTermUntil: Date;
 }
 /**
  * Computes the next period window. `null` means: no action
  * (either the period hasn't been reached yet, canceled, or NULL period).
  *
  * Logic (spec: SUPERADMIN_PLANS_DASHBOARD_TODO §2.2):
- *   - If `canceledAt` is set → SKIP.
+ *   - If a cancellation has LANDED → SKIP. A declared one has not, unless the
+ *     row predates the split and carries its effective date in `canceledAt`.
  *   - If `currentPeriodEnd === null` → SKIP (trial / PENDING_SALES).
  *   - If `currentPeriodEnd > now` → SKIP (period still active).
- *   - Otherwise → start := old `currentPeriodEnd`, end := periodEndAfter(start).
+ *   - If a cancellation has LANDED → SKIP. A declared one has not.
+ *   - Otherwise → start := old `currentPeriodEnd`, end := periodEndAfter(start),
+ *     and the minimum term renews with it.
  */
 declare function computeNextPeriod(sub: PeriodRollInput, now: Date): NextPeriodWindow | null;
 
@@ -230,10 +528,9 @@ declare const UPSELL_OFFER_CURRENCY_TOKEN: unique symbol;
 
 declare class CatalogBundleUpsellResolver implements UpsellOfferResolver {
     private readonly bundleRepo;
-    private readonly projectKey;
     private readonly catalogEntryRepo;
     private readonly currency;
-    constructor(bundleRepo: BundleRepository, projectKey: string, catalogEntryRepo?: CatalogEntryRepository | null, currency?: string | null);
+    constructor(bundleRepo: BundleRepository, catalogEntryRepo?: CatalogEntryRepository | null, currency?: string | null);
     resolveOffers(featureKeys: string[], tenantId: string): Promise<UpsellOffer[]>;
     /**
      * Uncovered dependencies of the missing features (#35) — feed into the
@@ -251,66 +548,18 @@ declare class LimitExceededFilter extends BaseExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
 }
 
+/** The settings of `config/saas.yaml` — a `PlanCatalogSettings`, fixed while the process runs. */
+declare const PLAN_CATALOG_SETTINGS_TOKEN: unique symbol;
+/** A `PlanCatalogSource`: the plans and features as they stand when an operation asks. */
+declare const PLAN_CATALOG_SOURCE_TOKEN: unique symbol;
+declare const PLAN_CATALOG_READ_SINK_TOKEN: unique symbol;
 /**
- * Schema validation error bundling all Ajv errors — one call returns
- * the full list, no round-trip editing needed.
- */
-interface AjvErrorLike {
-    instancePath?: string;
-    message?: string;
-    schemaPath?: string;
-}
-declare class PlanCatalogValidationError extends Error {
-    readonly source: string;
-    readonly errors: AjvErrorLike[];
-    constructor(source: string, errors: AjvErrorLike[]);
-}
-interface LoadPlanCatalogOptions {
-    /**
-     * Absolute path or relative path (resolved against CWD).
-     */
-    path: string;
-    /**
-     * Optional: additional cross-field validations that the JSON schema
-     * cannot cover. Default: enable all (see validateConsistency).
-     */
-    crossFieldChecks?: boolean;
-}
-/**
- * Loads + validates a saas.yaml file.
- *
- * Throws `PlanCatalogValidationError` on schema violations or
- * cross-field violations. Throws `Error` on IO/YAML parse errors.
- */
-declare function loadPlanCatalogFromFile(opts: LoadPlanCatalogOptions): PlanCatalog;
-/**
- * Variant for tests / in-memory loading: takes YAML content as a string,
- * `source` is only for error logging.
+ * Every settings block of `config/saas.yaml` — app identity, currency, VAT rate,
+ * tenant billing and the rest — beside the read sink the plans and features
+ * come from. The settings are handed on whole, so a block the schema gains
+ * reaches `PLAN_CATALOG_SETTINGS_TOKEN` without this module learning its name.
  */
-declare function loadPlanCatalogFromString(yamlContent: string, opts: {
-    source: string;
-    crossFieldChecks?: boolean;
-}): PlanCatalog;
-
-declare const PLAN_CATALOG_TOKEN: unique symbol;
-declare const PLAN_CATALOG_READ_SINK_TOKEN: unique symbol;
-interface PlanCatalogModuleOptions {
-    /** Build-time identity of the app. */
-    projectKey: string;
-    /**
-     * App-identity block (branding + version) from `config/saas.yaml#app`.
-     * Flows into `PLAN_CATALOG_TOKEN.app` and from there into the
-     * AdminPublicBoot endpoint + the AdminManifestConfig.
-     */
-    app?: PlanCatalog['app'];
-    currency: string;
-    vatRate: number;
-    /**
-     * App-wide marketing configuration — including the
-     * `availableLocales` pool. Flows into `PLAN_CATALOG_TOKEN.marketing`
-     * and from there into the admin manifest (`project.availableLocales`).
-     */
-    marketing?: PlanCatalog['marketing'];
+interface PlanCatalogModuleOptions extends PlanCatalogSettings {
     /** App-specific adapter for DB reads. */
     sink: ProviderSpec<PlanCatalogReadSink>;
     /** Modules that must be visible in the DI scope (analogous to CatalogModule). */
@@ -330,15 +579,12 @@ declare class PlanCatalogModule {
     }): DynamicModule;
 }
 
-interface PlanCatalogBuildSettings {
-    projectKey: string;
-    /** App identity (branding + version) from `config/saas.yaml#app`. Optional. */
-    app?: PlanCatalog['app'];
-    currency: string;
-    vatRate: number;
-    /** App-wide marketing configuration. Optional. */
-    marketing?: PlanCatalog['marketing'];
-}
+/**
+ * The settings a database catalogue runs on. The database carries plans and
+ * features, never the settings, so they can only come from the file — every
+ * block of it, which is why this is the settings type rather than a list.
+ */
+type PlanCatalogBuildSettings = PlanCatalogSettings;
 declare function buildPlanCatalogFromSnapshot(settings: PlanCatalogBuildSettings, snapshot: PlanCatalogReadSnapshot): PlanCatalog;
 
 declare const PLAN_CATALOG_IMPORT_SINK_TOKEN: unique symbol;
@@ -362,8 +608,10 @@ declare class PlanCatalogImporterService {
 interface PlanCatalogImporterControllerConfig {
     /**
      * Class-level guards for `/admin/billing/plan-catalog/import`. Required
-     * when `controller` is set — pass `[]` explicitly for auth-free
-     * (only sensible in tests).
+     * when `controller` is set. The import publishes the plans it creates, so
+     * the handler requires the second factor whatever this list holds, and
+     * `MfaService` has to be resolvable through `AdminModule`; with `[]`
+     * nothing establishes a caller and the import is refused.
      */
     guards: Array<Type<CanActivate>>;
 }
@@ -397,7 +645,7 @@ declare function getPlanOrThrow(catalog: PlanCatalog, planId: PlanId): PlanDef;
 /**
  * Returns all marketed plans (`marketed: true` or undefined). Order as in the
  * catalog. ENTERPRISE and other `marketed: false` plans are NOT included —
- * these can only be activated via `ahp paket apply` / special contract and do
+ * these are activated by a catalogue apply or a special contract, and do
  * not belong in self-service onboarding lists.
  */
 declare function getMarketedPlans(catalog: PlanCatalog): PlanDef[];
@@ -409,10 +657,31 @@ declare function getMarketedPlans(catalog: PlanCatalog): PlanDef[];
  *   - the plan has no price for the cycle (`monthlyNet`/`yearlyNet === null`)
  */
 declare function getPlanPriceNet(catalog: PlanCatalog, planId: PlanId, cycle: BillingCycle): number | null;
+/** The same rule for a plan already in hand, whichever version it describes. */
+declare function listPriceNet(plan: PlanDef, cycle: BillingCycle): number | null;
+/**
+ * Whether a plan on the list carries no price for a cycle, and so is not sold
+ * in it: a plan without a yearly price is a monthly plan, one without either is
+ * sold on request. A plan that is not marketed is sold under a special
+ * contract, whose price the catalogue does not hold, so this is never true of
+ * it.
+ */
+declare function isPlanNotSoldInCycle(plan: PlanDef, cycle: BillingCycle): boolean;
 /**
- * Gross list price from the catalog (net * (1 + vatRate/100)).
+ * The refusal for a plan that is not sold in a cycle — the same body for the
+ * plan change's blocker and for the contract, which would otherwise record the
+ * plan at 0.00.
+ */
+declare function planNotSoldInCycle(plan: PlanDef, cycle: BillingCycle): {
+    code: string;
+    message: string;
+    params: Record<string, string>;
+};
+/**
+ * Gross list price from the catalog, through `grossFromNet`.
  * `null` with the same rules as `getPlanPriceNet`. `vatRate` is optional;
- * default: `catalog.vatRate`.
+ * default: `catalog.vatRate`. A rate that is not a percentage is refused, as it
+ * is wherever a rate is stated.
  */
 declare function getPlanPriceGross(catalog: PlanCatalog, planId: PlanId, cycle: BillingCycle, vatRate?: number): number | null;
 /**
@@ -492,13 +761,12 @@ interface PublicBundleEntry {
     marketing?: MarketingFields;
 }
 declare class PublicCatalogController {
-    private readonly planCatalog;
+    private readonly planCatalogs;
     private readonly featureRegistry;
-    private readonly projectKey;
     private readonly marketingRepo;
     private readonly bundleRepo;
     private readonly catalogEntryRepo;
-    constructor(planCatalog: PlanCatalog, featureRegistry: FeatureUiRegistry, projectKey?: string | null, marketingRepo?: MarketingProjectionRepository | null, bundleRepo?: BundleRepository | null, catalogEntryRepo?: CatalogEntryRepository | null);
+    constructor(planCatalogs: PlanCatalogSource, featureRegistry: FeatureUiRegistry, marketingRepo?: MarketingProjectionRepository | null, bundleRepo?: BundleRepository | null, catalogEntryRepo?: CatalogEntryRepository | null);
     listPlans(lang?: string, localeParam?: string): Promise<PlanResponseEntry[]>;
     listFeatureRegistry(): Promise<FeatureUiRegistry>;
     /**
@@ -521,12 +789,6 @@ declare class PublicCatalogController {
 interface PublicCatalogModuleOptions {
     /** Required: consumer-specific FeatureUiRegistry. */
     featureUiRegistry: FeatureUiRegistry;
-    /**
-     * — app identity (e.g. "clubapp"). Used
-     * for marketing lookups + bundle filters.
-     * Optional; if omitted, the new endpoints return empty lists.
-     */
-    projectKey?: string;
     /**
      * Optional. When set, `/billing/bundles` is active.
      */
@@ -537,9 +799,9 @@ interface PublicCatalogModuleOptions {
      */
     marketingRepository?: ProviderSpec<MarketingProjectionRepository>;
     /**
-     * Optional (#13). When set (+ projectKey), `/billing/feature-registry`
-     * overlays the editable `FeatureCatalogEntry.icon` from the DB over the
-     * static registry.
+     * Optional (#13). When set, `/billing/feature-registry` overlays the
+     * editable `FeatureCatalogEntry.icon` from the DB over the static
+     * registry.
      */
     catalogEntryRepository?: ProviderSpec<CatalogEntryRepository>;
     /**
@@ -553,22 +815,101 @@ declare class PublicCatalogModule {
     static forRoot(options: PublicCatalogModuleOptions): DynamicModule;
 }
 
-declare const PUBLIC_CATALOG_PROJECT_KEY_TOKEN: unique symbol;
 declare const PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN: unique symbol;
 declare const PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN: unique symbol;
 
+/**
+ * The billing permission: who of a tenant's users may see and change what the
+ * subscriber pays with — and, as they arrive, its invoices and its account.
+ * The plan, the usage and a change's preview are not behind it.
+ *
+ * The application decides who holds it by passing guards
+ * (`payments.billingPermissionGuards`), so a role such as accounting can hold
+ * it without being the tenant's administrator. Without guards the tenant's
+ * administrator holds it. Runs after the tenant's authentication guards, so a
+ * user is on the request.
+ */
+declare class BillingPermissionGuard implements CanActivate {
+    private readonly guards;
+    constructor(guards?: AuthGuardList | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private holdsPermission;
+}
+
 declare class SubscriptionContractFreezeService implements ContractFreezePort {
-    private readonly catalog;
+    private readonly catalogs;
     private readonly entitlements;
     private readonly contracts;
-    private readonly projectKey;
     private readonly source;
-    constructor(catalog: PlanCatalog, entitlements: EntitlementService, contracts: SubscriptionContractService, projectKey: string, source: ContractFreezeSourcePort);
-    freezeOnPlanChange(tenantId: string, newPlan: string, billingCycle: BillingCycle, effectiveFrom: Date): Promise<void>;
+    constructor(catalogs: PlanCatalogSource, entitlements: EntitlementService, contracts: SubscriptionContractService, source: ContractFreezeSourcePort, writes?: TenantSubscriptionWritePort | null);
+    assertPartyFor(tenantId: string): Promise<void>;
+    endOnCancellation(tenantId: string, effectiveAt: Date): Promise<void>;
+    freezeOnPlanChange(tenantId: string, newPlan: string, billingCycle: BillingCycle, effectiveFrom: Date, endsAt?: Date | null): Promise<void>;
 }
 
 declare function computeCarriedTrialEndsAt(currentTrialDays: number, newTrialDays: number, currentTrialEndsAt: Date, now: Date): Date;
 
+declare class AddSubscriptionBundleDto {
+    bundleVersionId: string;
+    /**
+     * Optional — override for the minimum term (months). `0` = no
+     * minimum term. Default comes from the `SubscriptionBundleConfig`
+     * (platform = no commitment).
+     */
+    minimumTermMonths?: number;
+    /**
+     * The rhythm to bill this bundle in. Defaults to the plan's.
+     *
+     * A bundle may run in a shorter rhythm than its plan — monthly beside a
+     * yearly plan is the interesting case — but never a longer one. A yearly
+     * bundle on a monthly plan is refused rather than modelled: it has no
+     * boundary to meet, and every one of the plan's twelve period ends is a
+     * moment the plan could stop and leave the bundle committed with nothing to
+     * grant.
+     */
+    billingCycle?: 'MONTHLY' | 'YEARLY';
+}
+/**
+ * Body of `POST /billing/subscription-bundles/preview` (#37). Exactly one
+ * of `bundleVersionId` (add preview) or `subscriptionBundleId`
+ * (cancel preview) — the controller enforces this.
+ */
+declare class PreviewSubscriptionBundleDto {
+    /** Add preview: BundleVersion to be booked. */
+    bundleVersionId?: string;
+    /** Cancel preview: existing Bundle booking. */
+    subscriptionBundleId?: string;
+    /** Add preview only — override analogous to `AddSubscriptionBundleDto`. */
+    minimumTermMonths?: number;
+    /**
+     * Add preview only — the rhythm to quote, analogous to
+     * `AddSubscriptionBundleDto`. Defaults to the plan's.
+     *
+     * The booking has taken this since bundles gained a rhythm of their own.
+     * The preview not taking it meant a tenant asking for a monthly bundle on a
+     * yearly plan was quoted the yearly one and then charged the monthly one —
+     * a preview describing a different contract from the one written, which is
+     * the one thing a preview may never do.
+     */
+    billingCycle?: 'MONTHLY' | 'YEARLY';
+}
+declare class CancelSubscriptionBundleDto {
+    /**
+     * Optional — default = `new Date()` server-side. Format: ISO-8601
+     * (`YYYY-MM-DD` or full timestamp). Usually not set by the tenant
+     * self-service.
+     */
+    canceledAt?: string;
+}
+/** Which bundles the store is showing, so their prices can be resolved. */
+declare class BundlePriceLookupDto {
+    /**
+     * Capped rather than unbounded: the caller names what it is displaying, and
+     * a page shows a catalogue, not a database. Each id costs a lookup.
+     */
+    bundleVersionIds: string[];
+}
+
 /**
  * Builds the `ConfiguratorCatalog` (for onboarding step 3) from the
  * live `plan_versions` (SuperAdmin defines plans + prices) plus the
@@ -586,14 +927,13 @@ declare class ConfiguratorCatalogBuilder {
 }
 
 declare const SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN: unique symbol;
-/** Optional config token; default = 12 months minimum term. */
+/** Optional config token; without it a booking commits the tenant to nothing. */
 declare const SUBSCRIPTION_BUNDLE_CONFIG_TOKEN: unique symbol;
 
 /**
  * Factory analogous to `buildBundlesController` etc. — the consumer can pass
- * additional guards (e.g. RoleGuard) in addition to the platform default
- * `ComposedTenantAuthGuard`.
+ * additional guards (e.g. RoleGuard) in addition to the platform defaults.
  */
 declare function buildTenantSubscriptionBundlesController(extraGuards?: Array<Type<CanActivate>>): Type;
 
-export { type AjvErrorLike, BILLING_FEATURE_UI_REGISTRY_TOKEN, CatalogBundleUpsellResolver, ConfiguratorCatalogBuilder, ContractFreezePort, ContractFreezeSourcePort, FEATURE_GUARD_CONFIG_TOKEN, FEATURE_GUARD_MARKER, FeatureGuard, type FeatureGuardConfig, LimitExceededFilter, type LoadPlanCatalogOptions, type MarketingFields, type NextPeriodWindow, PLAN_CATALOG_IMPORT_SINK_TOKEN, PLAN_CATALOG_READ_SINK_TOKEN, PLAN_CATALOG_TOKEN, PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN, PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN, PUBLIC_CATALOG_PROJECT_KEY_TOKEN, type PeriodRollInput, type PlanCatalogBuildSettings, PlanCatalogImportDto, type PlanCatalogImporterControllerConfig, PlanCatalogImporterModule, type PlanCatalogImporterModuleOptions, PlanCatalogImporterService, PlanCatalogModule, type PlanCatalogModuleOptions, PlanCatalogValidationError, type PlanResponseEntry, type PublicBundleEntry, PublicCatalogController, PublicCatalogModule, type PublicCatalogModuleOptions, PublishValidationError, type PublishablePlanVersion, REQUIRE_FEATURE_KEY, type RenewalDecision, type RenewalSubInput, RequireFeature, SUBSCRIPTION_BUNDLE_CONFIG_TOKEN, SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN, SubscriptionContractFreezeService, UPSELL_OFFER_CURRENCY_TOKEN, UPSELL_OFFER_RESOLVER_TOKEN, assertBaseVersionFresh, assertChangeNote, assertDraftPublishable, assertOptimisticLockHeld, buildPlanCatalogFromSnapshot, buildPlanCatalogImporterController, buildTenantSubscriptionBundlesController, clearPendingPlanVersionFields, computeCarriedTrialEndsAt, computeNextPeriod, decideRenewal, findPlan, getActiveFeatureKeys, getMarketedPlans, getPlanOrThrow, getPlanPriceGross, getPlanPriceNet, getPlanQuota, initialPeriodWindow, isFeatureInPlan, isFeaturePlannedOnly, loadPlanCatalogFromFile, loadPlanCatalogFromString, periodEndAfter, periodEndWithMinLead };
+export { AddSubscriptionBundleDto, AuthGuardList, BILLING_FEATURE_UI_REGISTRY_TOKEN, BillingPermissionGuard, type BundleFirstPeriodInput, type BundlePeriodRollInput, type BundlePeriodWindow, type BundlePlanContext, BundlePriceLookupDto, CancelSubscriptionBundleDto, CatalogBundleUpsellResolver, ConfiguratorCatalogBuilder, ContractFreezePort, ContractFreezeSourcePort, DEFAULT_BUNDLE_MINIMUM_TERM_MONTHS, FEATURE_GUARD_CONFIG_TOKEN, FEATURE_GUARD_MARKER, FeatureGuard, type FeatureGuardConfig, LimitExceededFilter, type MarketingFields, type NextPeriodWindow, PLAN_CATALOG_IMPORT_SINK_TOKEN, PLAN_CATALOG_READ_SINK_TOKEN, PLAN_CATALOG_SETTINGS_TOKEN, PLAN_CATALOG_SOURCE_TOKEN, PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN, PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN, type PeriodRollInput, type PlanAnchorSource, type PlanCatalogBuildSettings, PlanCatalogImportDto, type PlanCatalogImporterControllerConfig, PlanCatalogImporterModule, type PlanCatalogImporterModuleOptions, PlanCatalogImporterService, PlanCatalogModule, type PlanCatalogModuleOptions, PlanCatalogSource, type PlanResponseEntry, PreviewSubscriptionBundleDto, type PublicBundleEntry, PublicCatalogController, PublicCatalogModule, type PublicCatalogModuleOptions, PublishValidationError, type PublishablePlanVersion, REQUIRE_FEATURE_KEY, type RenewalDecision, type RenewalSubInput, RequireFeature, SUBSCRIPTION_BUNDLE_CONFIG_TOKEN, SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN, SubscriptionContractFreezeService, UPSELL_OFFER_CURRENCY_TOKEN, UPSELL_OFFER_RESOLVER_TOKEN, advanceOneCycle, assertBaseVersionFresh, assertChangeNote, assertDraftPublishable, assertOptimisticLockHeld, billingAnchorDay, buildPlanCatalogFromSnapshot, buildPlanCatalogImporterController, buildTenantSubscriptionBundlesController, bundleCycleFitsPlan, bundleFirstPeriodEnd, bundleFirstPeriodStart, bundleNextPeriodEnd, clearPendingPlanVersionFields, computeCarriedTrialEndsAt, computeNextBundlePeriod, computeNextPeriod, cyclesSoldFor, decideRenewal, findPlan, getActiveFeatureKeys, getMarketedPlans, getPlanOrThrow, getPlanPriceGross, getPlanPriceNet, getPlanQuota, initialPeriodWindow, isFeatureInPlan, isFeaturePlannedOnly, isPlanNotSoldInCycle, listPriceNet, periodEndAfter, periodEndWithMinLead, planNotSoldInCycle, resolveBundlePriceNet, resolvePlanAnchorDay, retreatOneCycle };