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

package/dist/tenant-billing.controller-DKbAqTbM.d.cts

@@ -0,0 +1,812 @@
+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 { P as PlanCatalogSource } from './plan-catalog-source-DWe-BGY1.cjs';
+import { a as PromoCodesService } from './promo.service-BYBu6dy3.cjs';
+import { A as AdminAuditService } from './admin-audit.service-4P3Djdxk.cjs';
+
+interface CancellationInput {
+    /** When the customer declared it. */
+    now: Date;
+    /** End of the period they are in, if the subscription has one. */
+    currentPeriodEnd: Date | null;
+    /** End of what was committed to. Null on a subscription with no term. */
+    minimumTermUntil: Date | null;
+    /** Needed only to find the following period end when notice has passed. */
+    billingCycle: BillingCycle;
+    /** Days before the term end after which a cancellation is too late. */
+    noticePeriodDays: number;
+    /**
+     * The day of the month the subscription is billed on.
+     *
+     * Only the hard cut reads it, and only then does it matter — but there it
+     * matters in money. A declaration made after the notice window lands one
+     * period past the term end, and computing that step from the term end alone
+     * takes its day from a date that may already have been clamped: an
+     * anchor-31 subscription whose term ends 28 February was cut to 28 March
+     * rather than 31 March, three days short of the period the customer had
+     * just been charged for.
+     */
+    billingAnchorDay?: number | null;
+}
+interface CancellationDecision {
+    /** When the cancellation takes effect. */
+    effectiveAt: Date;
+    /** The term end it was measured against. */
+    termEndsAt: Date;
+    /** True when the notice window had already closed. */
+    afterNoticeDeadline: boolean;
+    /** The moment after which a cancellation lands one period later. */
+    noticeDeadline: Date | null;
+}
+/**
+ * Decides when a cancellation declared at `now` takes effect.
+ *
+ * Never returns a date in the past: a term that has already ended means the
+ * cancellation lands immediately, which is what a customer outside any
+ * commitment should get.
+ */
+declare function decideCancellation(input: CancellationInput): CancellationDecision;
+
+/**
+ * No notice at all, named so it is not a bare `{}` at a call site.
+ *
+ * Not a configuration default: `config/saas.yaml` requires both rhythms and an
+ * application that omits them does not boot. This is what lets a class be
+ * constructed directly — in a test that does not exercise a notice period —
+ * without restating a term. `TenantBillingModule` always provides the real one.
+ */
+declare const NO_NOTICE_PERIOD: CancellationNoticePeriods;
+/**
+ * The notice a subscription on `billingCycle` is owed.
+ *
+ * The two rhythms are read apart rather than one falling back to the other:
+ * they are separate numbers because real contracts set them apart, and
+ * inferring one from the other would be inventing a term.
+ *
+ * `config/saas.yaml` requires both, so there is nothing to default here. A
+ * number that is not written down is not a zero — it is a question the operator
+ * has to answer before the application starts.
+ */
+declare function noticeDaysFor(periods: CancellationNoticePeriods, billingCycle: string): number;
+/**
+ * The fields a cancellation is decided from. Narrow on purpose: this file
+ * decides dates and knows nothing about persistence.
+ */
+interface CancellableSubscription {
+    status: string;
+    billingCycle: BillingCycle;
+    currentPeriodEnd: Date | null;
+    minimumTermUntil: Date | null;
+    trialEndsAt: Date | null;
+    /** See `CancellationInput.billingAnchorDay`. */
+    billingAnchorDay?: number | null;
+}
+/**
+ * Decides a cancellation from a subscription, which is the only correct way to
+ * build the input above: reading the four date fields at a call site loses the
+ * fifth fact, and there is no type that notices.
+ *
+ * That fifth fact is whether the subscription commits to anything. A trial does
+ * not. It has a period end like every other subscription — the repository's own
+ * fixture sets one — and treating that as a term makes the two rules a customer
+ * meets disagree: a plan change during a trial takes effect at once because
+ * there is nothing to protect, while a cancellation was measured against a term
+ * that does not exist.
+ *
+ * The consequence was not a date a few weeks out. With a notice period
+ * configured, a trial ending in five days is already past its deadline, so the
+ * cancellation landed one BILLING CYCLE after the trial — a customer ending a
+ * yearly-cycle trial bought a year by cancelling it. The window exists so that a
+ * term cannot be left at the last moment; a trial has no term to leave.
+ *
+ * What a trial does have is an end, and the cancellation lands there: nothing is
+ * billed for the remainder and the customer keeps what they were given. Ending
+ * it on the spot would take the trial away as the price of saying they do not
+ * want to convert.
+ */
+declare function decideCancellationFor(sub: CancellableSubscription, now: Date, noticePeriodDays: number): CancellationDecision;
+
+declare class ComposedTenantAuthGuard implements CanActivate {
+    private readonly guards;
+    constructor(guards?: AuthGuardList | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+declare class TenantAdminGuard implements CanActivate {
+    canActivate(context: ExecutionContext): boolean;
+}
+
+interface ProrationDto {
+    daysRemainingInPeriod: number;
+    daysInPeriod: number;
+    periodStart: Date;
+    periodEnd: Date;
+    currentPriceNet: number;
+    targetPriceNet: number;
+    /**
+     * What the change costs for the rest of the period, never below zero.
+     *
+     * The raw arithmetic goes negative when the target is cheaper than what is
+     * running — after a price reduction, an upgrade can arrive at a negative
+     * number. That is not a credit: this platform does not pay money back, and
+     * a negative charge carried into an invoice is a refund nobody agreed to.
+     * It is a free upgrade, and `isFree` is how a page says so.
+     */
+    prorataDeltaNet: number;
+    /**
+     * The unclamped result, kept because the page has something to say about it.
+     *
+     * Dropping it would make "free" indistinguishable from "costs exactly
+     * nothing", and those read differently to someone deciding.
+     */
+    rawDeltaNet: number;
+    /**
+     * True when the arithmetic asked for less than nothing.
+     *
+     * Strictly less: a change that costs exactly zero — equal prices, or a
+     * remaining fraction that rounds the difference away — is not a free
+     * upgrade, it is a change with no price difference. `rawDeltaNet` exists
+     * above precisely so a page can tell those apart, and a flag that merges
+     * them takes that back.
+     */
+    isFree: boolean;
+}
+interface ProrationInput {
+    periodStart: Date;
+    periodEnd: Date;
+    now: Date;
+    /** Previous period price (bundle add: 0 — something is only added). */
+    currentPriceNet: number;
+    targetPriceNet: number;
+}
+declare function computeProration(input: ProrationInput): ProrationDto;
+
+type PlanChangeType = 'UPGRADE' | 'DOWNGRADE' | 'CYCLE_CHANGE' | 'NOOP';
+/** Where the target plan sits against the running one in the catalog order. */
+type PlanDirection = 'UP' | 'DOWN' | 'SAME';
+/**
+ * Whether the target billing period is longer, shorter or the same.
+ *
+ * Its own answer, deliberately. `changeType` collapses "a better plan" and "a
+ * shorter commitment" into one word, and the two have opposite consequences: a
+ * higher plan may start today, a shorter period may not — it would end a term
+ * the customer is still inside. Asked as one question, moving from a yearly
+ * STARTER to a monthly PRO reads as `UPGRADE`, applies immediately, and ends
+ * the yearly commitment early. That is the case this split exists for.
+ */
+type CycleDirection = 'LONGER' | 'SHORTER' | 'SAME';
+interface PlanSnapshotDto {
+    id: string;
+    name: string;
+    monthlyNet: number | null;
+    yearlyNet: number | null;
+    quotas: Record<string, number>;
+    features: string[];
+}
+interface LimitsCheckRow {
+    used: number;
+    currentMax: number;
+    targetMax: number;
+    exceeded: boolean;
+}
+interface PlanChangePreviewIssue {
+    code: string;
+    /**
+     * English display text, and the last rung of the ladder rather than the
+     * first: `resolveErrorMessage` prefers the reader's catalogue and reaches
+     * this only for a code nobody has translated. It stays on the wire because
+     * a blocker that renders as an empty line leaves someone with a disabled
+     * button and no reason.
+     */
+    message: string;
+    /**
+     * The values the sentence needs, beside it rather than inside it.
+     *
+     * Without these a client holding the code still cannot rebuild the
+     * sentence — it would have to parse English prose for the numbers. Every
+     * template in the shipped catalogues names only what appears here, and
+     * `preview-issues-are-translatable.test.js` holds that.
+     */
+    params?: Record<string, string | number>;
+}
+interface PlanChangePreviewDto {
+    changeType: PlanChangeType;
+    /**
+     * The two answers `changeType` collapses into one.
+     *
+     * A page needs them apart to explain a deferred upgrade: the plan went up,
+     * the period got shorter, and it is the second that decided the date.
+     */
+    planDirection: PlanDirection;
+    cycleDirection: CycleDirection;
+    current: {
+        plan: PlanSnapshotDto;
+        billingCycle: string;
+    };
+    target: {
+        plan: PlanSnapshotDto;
+        billingCycle: string;
+    };
+    /** For upgrade/NOOP: immediately (null). Otherwise period end. */
+    effectiveAt: Date | null;
+    isImmediate: boolean;
+    /**
+     * Projected new trial end after the change (app trial logic, e.g.
+     * carry-over of the remaining time). `null` if no TrialProjectionPort is
+     * configured, the subscription is not in a trial, or nothing changes.
+     * The wizard uses this to show "regular from the end of the trial".
+     */
+    projectedTrialEndsAt: Date | null;
+    proration: ProrationDto | null;
+    /** Map quotaKey → LimitsCheckRow across all quota dimensions from the current limit, target plan and usage. */
+    limitsCheck: Record<string, LimitsCheckRow>;
+    featuresLost: string[];
+    featuresGained: string[];
+    /** Hard prevention reasons — e.g. usage > target limit. */
+    blockers: PlanChangePreviewIssue[];
+    /** Non-blocking hints — e.g. feature loss. */
+    warnings: PlanChangePreviewIssue[];
+}
+interface PlanChangeContext {
+    /** Current period start time from the subscription, if present. */
+    currentPeriodStart: Date | null;
+    /** Current period end from the subscription, if present. */
+    currentPeriodEnd: Date | null;
+    /**
+     * End of what was committed to, which can outlast the period.
+     *
+     * They coincide until a notice period pushes one past the other. A change
+     * scheduled to the period end alone would then materialise inside the
+     * commitment this rule exists to protect — the customer keeps the plan they
+     * are bound to for eleven months and loses it in the twelfth.
+     */
+    minimumTermUntil: Date | null;
+    /** TRIAL end, if status === 'TRIAL'. */
+    trialEndsAt: Date | null;
+    /**
+     * The cancellation, because it decides what a change may still do.
+     *
+     * A cancellation was measured against the term of the cycle it was declared
+     * under, so that cycle cannot move while it is outstanding. The route
+     * refuses such a change; without the same answer here, a reader is walked
+     * through the whole wizard — the acknowledgement included — and meets the
+     * refusal only when they press confirm.
+     */
+    canceledAt: Date | null;
+    canceledEffectiveAt: Date | null;
+    /** Subscription status (TRIAL/ACTIVE/...). */
+    status: string;
+    /** Current cycle of the subscription (for cycle-change classification). */
+    currentBillingCycle: string;
+    /** Current plan of the subscription. */
+    currentPlan: string;
+    /** Subscription start, if present (for the periodEndAfter fallback). */
+    startedAt: Date | null;
+}
+declare class PlanChangePreviewService {
+    private readonly catalogs;
+    private readonly entitlements;
+    private readonly subscriptions;
+    private readonly usageSnapshot;
+    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);
+    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). */
+    assertChangeAllowed(tenantId: string, targetPlan: string, targetCycle: string, now?: Date): Promise<PlanChangePreviewIssue[]>;
+    /** Catalog order decides which plan is higher; equal keys are `SAME`. */
+    private planDirection;
+    /**
+     * YEARLY is the longer commitment; anything else is compared against it.
+     *
+     * Written as a comparison rather than a pair of equality checks so a third
+     * cycle — quarterly is the one that keeps being asked for — orders itself
+     * instead of falling into `SAME` and quietly becoming immediate.
+     */
+    private cycleDirection;
+    /**
+     * Active bookings whose own rhythm would not fit `targetCycle`.
+     *
+     * Reads the booking's stored rhythm, not the plan's: a booking with none
+     * follows the plan and therefore fits any plan by construction. Empty
+     * without the bundle module, which is a consumer that has no bookings at
+     * all rather than one whose bookings are being ignored.
+     */
+    private bookingsOutlastingCycle;
+    private classify;
+    /** Catalog order = rank. Non-marketed plans go to the end. */
+    private planRank;
+    private resolveEffectiveAt;
+    private computeProration;
+}
+
+declare class PendingPlanMaterializationService {
+    private readonly query;
+    private readonly subscriptionWrite;
+    private readonly entitlements;
+    private readonly contractFreeze;
+    private readonly logger;
+    constructor(query: PendingPlanQueryPort, subscriptionWrite: TenantSubscriptionWritePort, entitlements: EntitlementService, contractFreeze?: ContractFreezePort | null);
+    materializeDuePlanChanges(now?: Date): Promise<{
+        applied: number;
+    }>;
+    private tryFreeze;
+}
+
+declare class PreviewPlanChangeDto {
+    plan: string;
+    billingCycle: string;
+}
+/**
+ * A plan change carries what to change to, never when.
+ *
+ * It used to carry `effectiveImmediately`, and the route honoured it — so a
+ * direct call could take the immediate path and end a term the customer was
+ * inside. When a change lands follows from the plan direction, the cycle
+ * direction and the minimum term, all of which the server knows and the caller
+ * does not.
+ */
+declare class ChangePlanDto extends PreviewPlanChangeDto {
+}
+/**
+ * A cancellation carries nothing.
+ *
+ * It used to carry `immediately`, and honouring it let a tenant end a term they
+ * were still inside — the one thing this route may not do. A cancellation is a
+ * declaration; when it lands is decided from the minimum term and the notice
+ * period, not asked for. Ending a contract on the spot is an operator's act and
+ * goes through the operator's own path.
+ *
+ * Kept as an empty class rather than deleted so `whitelist` still strips a body
+ * from a client that has not been updated, instead of the field reaching a
+ * handler that would ignore it silently.
+ */
+declare class CancelSubscriptionDto {
+    /**
+     * The effective date the page showed before the customer confirmed.
+     *
+     * Optional, and checked rather than trusted: if the server's own decision
+     * differs, the request is refused with the new date so the page can ask
+     * again. The window is small and the consequence is not — a dialog opened
+     * before a notice deadline and confirmed after it promises January 2027 and
+     * would deliver January 2028.
+     *
+     * This is the caller telling the server what only the caller knows: what
+     * the human actually agreed to.
+     */
+    expectedEffectiveAt?: string;
+}
+
+declare class CompleteOnboardingSubscriptionDto {
+    plan: string;
+    billingCycle: string;
+    promoCode?: string;
+    /**
+     * Optional — UUIDs of the BundleVersions that should be booked
+     * together with the plan (P11.7.3). Per bundle, the platform
+     * default minimum term (none) is set. Bundles are added
+     * best-effort **after** the plan change — an error on an individual
+     * bundle (e.g. incompatible with the chosen plan) lands as a
+     * warning in the response, without rolling back the plan change.
+     */
+    bundleVersionIds?: string[];
+}
+
+interface SubscriptionBundleConfig {
+    /**
+     * Default minimum term in months on `add`. Default = 0 — no commitment,
+     * so an add-on can be cancelled to its own period end. An operator who
+     * wants one configures it.
+     */
+    defaultMinimumTermMonths?: number;
+}
+interface AddBundleToSubscriptionInput {
+    subscriptionId: string;
+    bundleVersionId: string;
+    /** PlanKey of the current subscription for the plan-compatibility check. */
+    currentPlanKey: string;
+    /** Default = now (service time). */
+    startedAt?: Date;
+    /**
+     * Override for the minimum term (months). Default = config or
+     * 12. `0` explicitly means "no minimum term"
+     * (`minimumTermEndsAt = null`).
+     */
+    minimumTermMonths?: number;
+    /**
+     * When the parent subscription ends, or null while it runs on.
+     *
+     * A bundle cannot commit past the subscription that pays for it. With a
+     * cancellation outstanding, a twelve-month default term on a subscription
+     * ending in three weeks binds a customer to something that has three weeks
+     * left to give — and once the parent ends, entitlement resolution grants
+     * nothing through it.
+     *
+     * Required rather than optional: a caller that omits it commits the
+     * customer for longer than the contract can deliver, and the omission is
+     * invisible.
+     */
+    parentEndsAt: Date | null;
+    /**
+     * The plan's rhythm, its current period end, and the day it is billed on.
+     *
+     * A bundle runs in step with the plan that pays for it: its periods end on
+     * the plan's day, and its first one is short. Aligned here, at booking,
+     * rather than trimmed when the plan ends — a trim means somebody was
+     * committed to more than they received, and then owed the difference.
+     *
+     * The plan's cycle is also the ceiling for the bundle's: a bundle may run
+     * in a shorter rhythm, never a longer one.
+     */
+    planCycle: BillingCycle;
+    planPeriodEnd: Date | null;
+    planAnchorDay: number | null;
+    /** The bundle's own rhythm. Defaults to the plan's. */
+    billingCycle?: BillingCycle;
+}
+interface CancelBundleFromSubscriptionInput {
+    subscriptionBundleId: string;
+    /** Default = now. */
+    canceledAt?: Date;
+    /**
+     * Period end of the subscription from which the cancellation could take effect.
+     * Effective date = `max(currentPeriodEnd, minimumTermEndsAt)`.
+     * If not set, `canceledAt` is interpreted as the period end
+     * (= immediate effect, provided the minimum term has already expired).
+     */
+    currentPeriodEnd?: Date;
+    /**
+     * When the parent subscription ends, or null while it runs on.
+     *
+     * A bundle cannot be held past the plan that pays for it, and the term was
+     * written at booking — before any cancellation declared since. Reading the
+     * boundary here is what makes that harmless: no clamp at insert time can
+     * see a cancellation that had not happened yet.
+     */
+    parentEndsAt: Date | null;
+}
+declare class SubscriptionBundlesService {
+    private readonly repo;
+    private readonly bundles;
+    private readonly blockedBundles;
+    private readonly defaultMinTermMonths;
+    constructor(repo: SubscriptionBundleRepository, bundles: BundleRepository, config?: SubscriptionBundleConfig, blockedBundles?: SelfServiceBlockedBundles | null);
+    /** All bundle bookings of a subscription (for the "My Bundles" page). */
+    /**
+     * The tenant's bookings, with the price each one is actually billed at.
+     *
+     * `planKey` is required because a price is not a property of a bundle
+     * alone: a `BundlePricingOverride` can set a different one per plan, and
+     * the rhythm decides which of the two figures applies. Returning the base
+     * monthly price regardless — which this did until 2026-08-27 — puts a
+     * 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[]>;
+    /**
+     * List prices for the given bundle versions, in both rhythms, resolved for
+     * one plan.
+     *
+     * The public catalogue cannot answer this: it has no tenant and therefore
+     * no plan, so it serves the base prices and a bundle priced only through an
+     * override reads as having no price at all. A tenant UI that treated those
+     * fields as final hid such a bundle behind "not available in this rhythm"
+     * while the booking would have gone through.
+     */
+    resolvePricesFor(planKey: string, bundleVersionIds: string[]): Promise<Record<string, {
+        monthlyNet: number | null;
+        yearlyNet: number | null;
+    }>>;
+    addBundleToSubscription(input: AddBundleToSubscriptionInput): Promise<SubscriptionBundleRecord>;
+    cancelBundleFromSubscription(input: CancelBundleFromSubscriptionInput): Promise<SubscriptionBundleRecord>;
+    /**
+     * "Undo cancellation" — only as long as the cancellation is not yet effective
+     * (the bundle runs until `canceledEffectiveAt`). After that, re-booking is the way.
+     */
+    reactivateBundle(subscriptionBundleId: string): Promise<SubscriptionBundleRecord>;
+}
+/**
+ * Effective date of a bundle cancellation:
+ * `max(currentPeriodEnd, minimumTermEndsAt)` — missing values fall back to
+ * `canceledAt` (= immediate effect). Shared between the
+ * cancellation mutation and the preview (#37).
+ */
+declare function resolveBundleCancelEffectiveAt(input: {
+    canceledAt: Date;
+    currentPeriodEnd: Date | null;
+    minimumTermEndsAt: Date | null;
+    /** When the parent subscription ends, or null while it runs on. */
+    parentEndsAt: Date | null;
+}): Date;
+/**
+ * Adds `months` to `date` and keeps the UTC day. Edge case
+ * 31.01 + 1 month → 28/29.02 (JS Date does this automatically by
+ * setMonth normalizing the day).
+ */
+declare function addMonths(date: Date, months: number): Date;
+declare function clampToParent(ownTermEndsAt: Date | null, parentEndsAt: Date | null): Date | null;
+
+interface SubscriptionBundlePreviewIssue {
+    code: string;
+    message: string;
+    /**
+     * The values the sentence names, beside it rather than inside it — the same
+     * contract `PlanChangePreviewIssue` carries, so one consumer mechanism
+     * resolves the issues of both previews.
+     */
+    params?: Record<string, string | number>;
+}
+/** Subscription context — the controller reads it from the SubscriptionUsagePort. */
+interface SubscriptionBundlePreviewContext {
+    subscriptionId: string;
+    /** PlanKey of the current subscription (plan compatibility + redundancy source). */
+    currentPlanKey: string;
+    /** 'MONTHLY' | 'YEARLY' (port convention). */
+    billingCycle: string;
+    /** Subscription status (TRIAL/ACTIVE/...). No proration during TRIAL. */
+    status: string;
+    startedAt: Date | null;
+    currentPeriodStart: Date | null;
+    currentPeriodEnd: Date | null;
+    /**
+     * When the parent subscription ends, or null while it runs on.
+     *
+     * The dialog states the date the booking will be committed to, and the
+     * mutation caps that date at the parent's end. A preview that does not cap
+     * it describes a different contract from the one that is written.
+     */
+    parentEndsAt: Date | null;
+    /**
+     * The day of the month the plan is billed on, where it is known.
+     *
+     * The bundle's periods land on this day, so the preview needs the same
+     * value the booking uses. Reading it from the plan's period end instead
+     * would hand on a date a short month has already clamped, and the quoted
+     * first period would then differ from the one written.
+     */
+    planAnchorDay?: number | null;
+}
+interface BundlePreviewSnapshot {
+    bundleKey: string;
+    label: string;
+    bundleVersionId: string;
+    features: string[];
+    quotas: Record<string, number>;
+}
+/** AK-13: feature is already paid for elsewhere — double-payment hint. */
+interface RedundantFeatureHint {
+    featureKey: string;
+    coveredBy: 'PLAN' | 'BUNDLE';
+    /** planKey or bundleKey of the covering source. */
+    coveredByKey: string;
+}
+interface SubscriptionBundleAddPreviewDto {
+    action: 'add';
+    bundle: BundlePreviewSnapshot;
+    billingCycle: string;
+    /**
+     * Prorated amount until period end. `null` during TRIAL (no paid
+     * period yet) or without a list price for the cycle.
+     */
+    proration: ProrationDto | null;
+    /** List price per follow-up period in the current cycle; null = no price maintained. */
+    nextPeriodPriceNet: number | null;
+    minimumTermMonths: number;
+    /** Projected minimum-term end from `now`; null = no minimum term. */
+    minimumTermEndsAt: Date | null;
+    /**
+     * End of the first billing period, on the plan's billing day.
+     *
+     * Shorter than a full cycle in the usual case, and charged pro rata for
+     * exactly that stretch (`proration`). Null where the plan has no period to
+     * align to — a trial, or a subscription not yet started.
+     */
+    firstPeriodEnd: Date | null;
+    /**
+     * The day the bundle ends because the plan does, or null while the plan
+     * runs on.
+     *
+     * Ending with the plan is not a cancellation: no notice is needed, and the
+     * period the bundle is in when it happens is not credited. The alignment
+     * exists so that day is a period boundary — this field is what remains
+     * when the plan is already ending on a day the bundle has been paid past.
+     */
+    endsWithPlanAt: Date | null;
+    redundantFeatures: RedundantFeatureHint[];
+    /**
+     * requires-features (#35) that neither the plan nor active bundles nor the
+     * bundle itself cover. Non-empty ⇒ blocker
+     * BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED.
+     */
+    missingRequires: string[];
+    blockers: SubscriptionBundlePreviewIssue[];
+    warnings: SubscriptionBundlePreviewIssue[];
+}
+interface SubscriptionBundleCancelPreviewDto {
+    action: 'cancel';
+    subscriptionBundleId: string;
+    bundle: BundlePreviewSnapshot;
+    billingCycle: string;
+    /** Effective date = max(currentPeriodEnd, minimumTermEndsAt). */
+    effectiveAt: Date;
+    /** Savings per period from the effective date; null = no price maintained. */
+    nextPeriodSavingsNet: number | null;
+    blockers: SubscriptionBundlePreviewIssue[];
+    warnings: SubscriptionBundlePreviewIssue[];
+}
+declare class SubscriptionBundlePreviewService {
+    private readonly subscriptionBundles;
+    private readonly bundles;
+    private readonly plans;
+    private readonly catalogEntries;
+    private readonly blockedBundles;
+    private readonly defaultMinTermMonths;
+    constructor(subscriptionBundles: SubscriptionBundleRepository, bundles: BundleRepository, plans?: PlanRepository | null, catalogEntries?: CatalogEntryRepository | null, blockedBundles?: SelfServiceBlockedBundles | null, config?: SubscriptionBundleConfig);
+    previewAdd(ctx: SubscriptionBundlePreviewContext, input: {
+        bundleVersionId: string;
+        minimumTermMonths?: number;
+        /** The bundle's own rhythm. Defaults to the plan's, as the booking does. */
+        billingCycle?: BillingCycle;
+    }, now?: Date): Promise<SubscriptionBundleAddPreviewDto>;
+    previewCancel(ctx: SubscriptionBundlePreviewContext, input: {
+        subscriptionBundleId: string;
+    }, now?: Date): Promise<SubscriptionBundleCancelPreviewDto>;
+    /** Bookability checks — same codes as `addBundleToSubscription` (422 path). */
+    private collectBookabilityBlockers;
+    /** Versions of the active bundle bookings (for redundancy + requires coverage). */
+    private loadActiveBundleVersions;
+    /** Features of the currently live PlanVersion state; empty without PlanRepository. */
+    private resolvePlanFeatures;
+    private collectRedundantFeatures;
+    /**
+     * requires of the new bundle that neither the bundle itself nor plan ∪
+     * active bundles cover (#35). Empty without CatalogEntryRepository.
+     */
+    private collectMissingRequires;
+}
+
+interface RequestLike {
+    user?: {
+        tenantId?: string;
+        sub?: string;
+        id?: string;
+    };
+}
+interface UsageResponse {
+    plan: string;
+    effectivePlan: string;
+    billingCycle: string;
+    status: string;
+    isPilot: boolean;
+    pilotEndsAt: Date | null;
+    trialEndsAt: Date | null;
+    startedAt: Date | null;
+    currentPeriodStart: Date | null;
+    currentPeriodEnd: Date | null;
+    pendingPlan: string | null;
+    pendingBillingCycle: string | null;
+    pendingEffectiveAt: Date | null;
+    planVersion: SubscriptionUsageRecord['planVersion'];
+    pendingPlanVersion: SubscriptionUsageRecord['pendingPlanVersion'];
+    pendingPlanVersionEffectiveAt: Date | null;
+    pendingPlanVersionAccepted: boolean;
+    pendingPlanVersionAcceptedAt: Date | null;
+    /** When a cancellation was declared. Null while none was. */
+    canceledAt: Date | null;
+    /** When it lands. A tenant keeps everything until then. */
+    canceledEffectiveAt: Date | null;
+    /**
+     * What cancelling right now would do — the date, and why it is that date.
+     *
+     * A projection, not a state: it is recomputed on every read, and it says
+     * nothing about whether a cancellation exists. `canceledEffectiveAt` above
+     * is the one that does.
+     */
+    cancellation: CancellationDecision;
+    limits: ReturnType<typeof toEffectiveLimitsSnapshot>;
+    usage: Record<string, number>;
+    /**
+     * P11.4: Frozen package snapshot from the
+     * `CheckoutOffer` that was activated during onboarding. Read-only
+     * for the tenant self-service UI. `null` for subscriptions without
+     * a CheckoutOffer origin.
+     */
+    packageSnapshot: unknown | null;
+    /** P11.4: Optional reference to the originating CheckoutOffer. */
+    checkoutOfferId: string | null;
+}
+declare class TenantBillingController {
+    private readonly entitlements;
+    private readonly planPreview;
+    private readonly subscriptionUsage;
+    private readonly usageSnapshot;
+    private readonly subscriptionWrite;
+    private readonly tenantIdResolver;
+    private readonly userIdResolver;
+    private readonly blockedPlans;
+    private readonly promoCodes;
+    private readonly auditService;
+    private readonly userEmailResolver;
+    private readonly auditContextResolver;
+    private readonly subscriptionBundles;
+    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 logger;
+    getEntitlement(req: RequestLike): Promise<EffectiveLimitsSnapshot>;
+    getUsage(req: RequestLike): Promise<UsageResponse>;
+    previewPlanChange(req: RequestLike, dto: PreviewPlanChangeDto): Promise<PlanChangePreviewDto>;
+    changePlan(req: RequestLike, dto: ChangePlanDto): Promise<{
+        plan: string;
+        billingCycle: string;
+        immediate: boolean;
+        pendingPlan?: undefined;
+        pendingBillingCycle?: undefined;
+        pendingEffectiveAt?: undefined;
+    } | {
+        plan: string;
+        billingCycle: string;
+        pendingPlan: string;
+        pendingBillingCycle: string;
+        pendingEffectiveAt: Date;
+        immediate: boolean;
+    }>;
+    completeOnboardingSubscription(req: RequestLike, dto: CompleteOnboardingSubscriptionDto): Promise<OnboardingSelectionResponse>;
+    acceptPendingPlanVersion(req: RequestLike): Promise<{
+        accepted: boolean;
+        acceptedAt: Date | null;
+        effectiveAt: Date | null;
+        idempotent: boolean;
+    }>;
+    cancelSubscription(req: RequestLike, dto: CancelSubscriptionDto): Promise<{
+        canceledAt: Date | null;
+        canceledEffectiveAt: Date | null;
+        status: string;
+        termEndsAt: null;
+        noticeDeadline: null;
+        afterNoticeDeadline: null;
+        alreadyCanceled: boolean;
+    } | {
+        canceledAt: Date | null;
+        canceledEffectiveAt: Date | null;
+        status: string;
+        termEndsAt: Date;
+        noticeDeadline: Date | null;
+        afterNoticeDeadline: boolean;
+        alreadyCanceled: boolean;
+    }>;
+    /**
+     * What a cancellation declared at `now` would do. One method, because the
+     * page states the date and this route applies it, and two constructions of
+     * the same input are two chances to disagree about a rule the customer
+     * meets once.
+     */
+    private projectCancellation;
+    private requireTenantId;
+    private requireUserId;
+    private buildActor;
+    private resolveUserEmail;
+    private toResponseRedemption;
+    private collectPromoSkipReasons;
+    /**
+     * #18: contract freeze after the plan change — non-fatal, only outside of
+     * the trial (during a trial the trial entitlements apply, not the booked plan;
+     * the freeze happens on the transition to ACTIVE, i.e. on materialization).
+     * Without a configured `contractFreeze` hook the call is a no-op.
+     */
+    private tryFreezeOnPlanChange;
+    /**
+     * Audit-log helper — writes best-effort, does not block the response path.
+     * If `AdminAuditService` is not injected (e.g. a minimal deploy without
+     * AdminModule), the call is silently discarded.
+     */
+    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 };