@saasicat/nest 0.2.0

package/dist/billing/index.d.cts

@@ -0,0 +1,1326 @@
+import { BillingCycle, FeatureKey, UpsellOfferResolver, BundleRepository, CatalogEntryRepository, UpsellOffer, PlanCatalog, PlanCatalogReadSink, PlanCatalogReadSnapshot, PlanCatalogImportSink, PlanCatalogImportReport, PlanId, PlanDef, QuotaKey, MarketingTopFeature, FeatureUiRegistry, MarketingProjectionRepository, BusinessTypeRepository, SubscriptionUsagePort, UsageSnapshotPort, NewContractLineItemData, TenantSubscriptionWritePort, SubscriptionBundleRepository, SubscriptionBundleView, SubscriptionBundleRecord, SubscriptionUsageRecord, OnboardingSelectionResponse, SubscriptionContractRepository, ConfiguratorSourcesLookup, ConfiguratorMarketingProvider, ConfiguratorCatalog, PlanRepository, BundleVersionRow } from '@saasicat/types';
+export { BundleVersionFields, ChangeDirection, DiffResult, PlanVersionFields, VersionChange, VersionChangeDirection, classifyBundleVersionDiff, classifyPlanDiff } from '@saasicat/types';
+import * as _nestjs_common from '@nestjs/common';
+import { CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost, Type, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
+export { Type as NestType } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { d as EntitlementService, L as LimitExceededError, b as EffectiveLimitsSnapshot, t as toEffectiveLimitsSnapshot } from '../aggregation-CJ3qQf92.cjs';
+import { P as ProviderSpec } from '../di-CcNeq9v-.cjs';
+import { S as SubscriptionContractService } from '../subscription-contract.service--cm47ZJJ.cjs';
+import { f as PromoCodesService } from '../service-DX8KbGXl.cjs';
+import { A as AdminAuditService } from '../admin-audit.service-9IqXMlZm.cjs';
+import '../plan-resolution-CFCoUkrE.cjs';
+
+/**
+ * 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;
+/**
+ * Returns the initial period window for a subscription
+ * (`currentPeriodStart`/`currentPeriodEnd`). `start` is `startedAt`,
+ * `end = start + 1 cycle`. We deliberately do not iterate — on a
+ * plan change / renewal cron run the value is actively reset.
+ */
+declare function initialPeriodWindow(startedAt: Date, cycle: BillingCycle): {
+    start: Date;
+    end: Date;
+};
+/**
+ * Finds the earliest period boundary that lies **at least `minLeadDays` days**
+ * in the future. Used by the notification cron to determine the effective
+ * period for upcoming version changes:
+ *
+ *  - `BillingCycle = YEARLY` with `currentPeriodEnd ∈ [+42d, +43d)`: trivial,
+ *    effective date = currentPeriodEnd.
+ *  - `BillingCycle = MONTHLY` with `currentPeriodEnd in 16d`: 16d < 42d → the
+ *    function jumps to the period after next (≥ 42d lead time).
+ *
+ * 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;
+
+/** Generic shape of a PlanVersion snapshot for publish validation. */
+interface PublishablePlanVersion {
+    id: string;
+    publishedAt: Date | null;
+    supersededAt: Date | null;
+    baseVersionId: string | null;
+}
+/**
+ * Structured publish error — the consumer maps it to the appropriate HTTP
+ * status code (NestJS: 400 / 404 / 409).
+ */
+declare class PublishValidationError extends Error {
+    readonly code: 'CHANGE_NOTE_REQUIRED' | 'NOT_FOUND' | 'ALREADY_PUBLISHED' | 'NO_BASE_VERSION' | 'BASE_NOT_FOUND' | 'BASE_SUPERSEDED' | 'OPTIMISTIC_LOCK_CONFLICT';
+    constructor(code: 'CHANGE_NOTE_REQUIRED' | 'NOT_FOUND' | 'ALREADY_PUBLISHED' | 'NO_BASE_VERSION' | 'BASE_NOT_FOUND' | 'BASE_SUPERSEDED' | 'OPTIMISTIC_LOCK_CONFLICT', message: string);
+}
+/**
+ * Checks the `changeNote` requirement. Throws `CHANGE_NOTE_REQUIRED` if empty /
+ * only whitespace.
+ */
+declare function assertChangeNote(changeNote: string | null | undefined): string;
+/**
+ * Checks the preconditions a draft must satisfy before it may be published:
+ *
+ *   - Exists (otherwise NOT_FOUND)
+ *   - `publishedAt` is null (otherwise ALREADY_PUBLISHED)
+ *   - `baseVersionId` is set (otherwise NO_BASE_VERSION)
+ *
+ * If `base` is passed, it additionally checks:
+ *   - `base.supersededAt` is null (otherwise BASE_SUPERSEDED)
+ *
+ * `null` for `base` means "base lookup performed separately but not
+ * found" → BASE_NOT_FOUND.
+ */
+declare function assertDraftPublishable(draft: PublishablePlanVersion | null, draftId: string): asserts draft is PublishablePlanVersion;
+/**
+ * Checks that the base version the draft diffs against is still
+ * available (not superseded).
+ */
+declare function assertBaseVersionFresh(base: PublishablePlanVersion | null, baseId: string, planContext: string): asserts base is PublishablePlanVersion;
+/**
+ * Checks the result of the optimistic-lock update (`updateMany WHERE
+ * publishedAt IS NULL`): exactly 1 row expected. Otherwise a
+ * concurrent admin has already published the draft.
+ */
+declare function assertOptimisticLockHeld(updateCount: number, draftId: string): void;
+
+/**
+ * What the renewal cron should do with a subscription whose
+ * `pendingPlanVersionEffectiveAt` has been reached.
+ *
+ *   - `ROLL_FORWARD`: pending becomes the new live version. Happens when
+ *     either `nonRegressive=true` (platform guarantee: no regression)
+ *     or `accepted=true` (the tenant has agreed to the change).
+ *   - `CLEAR_PENDING`: pending is discarded. Happens when the
+ *     pending version is regressive AND the tenant has **not** agreed
+ *     by the effective date (variant B from roadmap §6.2: opt-in
+ *     missed → no change).
+ *   - `SKIP`: the sub has no pending version or the effective date is
+ *     still in the future. (Should normally not be found by the cron
+ *     filter at all — caught defensively here.)
+ */
+type RenewalDecision = 'ROLL_FORWARD' | 'CLEAR_PENDING' | 'SKIP';
+/** Input shape for `decideRenewal` (what the cron reads from the sub). */
+interface RenewalSubInput {
+    pendingPlanVersionId: string | null;
+    pendingPlanVersionEffectiveAt: Date | null;
+    pendingPlanVersionAccepted: boolean;
+    /** `nonRegressive` from the referenced PlanVersion. */
+    pendingPlanVersionNonRegressive: boolean;
+}
+/**
+ * Decides what should happen to a subscription with a due pending version.
+ */
+declare function decideRenewal(sub: RenewalSubInput, now: Date): RenewalDecision;
+/**
+ * Returns the fields that must be reset in the subscription update after a
+ * `ROLL_FORWARD` or `CLEAR_PENDING`. The consumer inserts them
+ * into its Prisma `update.data` block.
+ */
+declare function clearPendingPlanVersionFields(): {
+    pendingPlanVersionId: null;
+    pendingPlanVersionEffectiveAt: null;
+    pendingPlanVersionAccepted: false;
+    pendingPlanVersionAcceptedAt: null;
+    pendingPlanVersionAcceptedByUserId: null;
+    pendingPlanVersionNotifiedAt: null;
+    pendingPlanVersionReminderSentAt: null;
+};
+/** Input shape for `computeNextPeriod`. */
+interface PeriodRollInput {
+    /** Subscription.currentPeriodEnd. NULL → no period active → SKIP. */
+    currentPeriodEnd: Date | null;
+    billingCycle: BillingCycle;
+    canceledAt: Date | null;
+}
+/** Result: the next period window or `null` (skip). */
+interface NextPeriodWindow {
+    currentPeriodStart: Date;
+    currentPeriodEnd: 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 `currentPeriodEnd === null` → SKIP (trial / PENDING_SALES).
+ *   - If `currentPeriodEnd > now` → SKIP (period still active).
+ *   - Otherwise → start := old `currentPeriodEnd`, end := periodEndAfter(start).
+ */
+declare function computeNextPeriod(sub: PeriodRollInput, now: Date): NextPeriodWindow | null;
+
+declare const REQUIRE_FEATURE_KEY = "require-feature";
+/**
+ * Tag handler with required feature keys.
+ *
+ * No value = public. Multiple values = logical OR.
+ */
+declare const RequireFeature: (...features: FeatureKey[]) => _nestjs_common.CustomDecorator<string>;
+
+interface FeatureGuardConfig {
+    /**
+     * Wraps `EntitlementService.computeLimits` in a tenant context.
+     * Consumers with RLS pass `runWithTenant(tenantId, fn)` here
+     * — so that the repository queries see the tenant in the DB session
+     * variables. Without RLS: omit the field, the default is identity.
+     */
+    tenantContextRunner?: <T>(tenantId: string, fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Reads the platform role from the `request.user` object. Used for the
+     * SUPER_ADMIN bypass — platform support may help a tenant even
+     * when the feature is not in that tenant's plan.
+     *
+     * Default: `user.role ?? user.platformRole`.
+     */
+    userRoleResolver?: (user: unknown) => string | undefined;
+    /**
+     * Reads the `tenantId` from the request. Default:
+     * `request.tenantId ?? request.user?.tenantId`.
+     */
+    tenantIdResolver?: (request: unknown) => string | undefined;
+}
+declare const FEATURE_GUARD_CONFIG_TOKEN: unique symbol;
+
+declare class FeatureGuard implements CanActivate {
+    private readonly reflector;
+    private readonly entitlements;
+    private readonly config;
+    private readonly upsellResolver;
+    private readonly logger;
+    constructor(reflector: Reflector, entitlements: EntitlementService, config?: FeatureGuardConfig | null, upsellResolver?: UpsellOfferResolver | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Upsell response (#36): with a registered `UpsellOfferResolver` the 403
+     * becomes machine-readable (`FeatureNotLicensedBody`), so consumer UIs can
+     * render a purchase offer. Without a resolver the previous plain 403
+     * remains — no breaking change.
+     *
+     * Deliberately 403 + `code` field instead of 402 — rationale in
+     * `@saasicat/types` upsell.types.ts (402 is reserved / inconsistently
+     * supported; SPA interceptors must not treat the 403 as an auth error, the
+     * distinction runs through `code`).
+     */
+    private buildNotLicensedException;
+    /**
+     * A resolver error must not turn the semantically correct 403 into a 500 —
+     * degrade to empty offers and log.
+     */
+    private resolveOffersSafe;
+}
+
+declare const UPSELL_OFFER_RESOLVER_TOKEN: unique symbol;
+/**
+ * Optional currency for the offers of the `CatalogBundleUpsellResolver`
+ * (ISO-4217 string, e.g. `'EUR'`). Without a provider: `'EUR'`.
+ */
+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);
+    resolveOffers(featureKeys: string[], tenantId: string): Promise<UpsellOffer[]>;
+    /**
+     * Uncovered dependencies of the missing features (#35) — feed into the
+     * coverage ranking. Without a CatalogEntryRepository: empty (ranking
+     * degrades to price).
+     */
+    private lookupUnmetRequires;
+    /** Only published-and-live AND marketed — non-marketed bundles are not an offer. */
+    private listLiveMarketedBundles;
+    private toOffer;
+}
+
+declare class LimitExceededFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: LimitExceededError, host: ArgumentsHost): void;
+}
+
+/**
+ * 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.
+ */
+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 (SPEC_V2 §6.5) — including the
+     * `availableLocales` pool. Flows into `PLAN_CATALOG_TOKEN.marketing`
+     * and from there into the admin manifest (`project.availableLocales`).
+     */
+    marketing?: PlanCatalog['marketing'];
+    /** App-specific adapter for DB reads. */
+    sink: ProviderSpec<PlanCatalogReadSink>;
+    /** Modules that must be visible in the DI scope (analogous to CatalogModule). */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    extraProviders?: Provider[];
+    /** Defaults to `true`. */
+    global?: boolean;
+}
+declare class PlanCatalogModule {
+    static forRoot(options: PlanCatalogModuleOptions): DynamicModule;
+    /**
+     * Tests / in-memory setup: takes the catalog object directly, without a
+     * sink/DB lookup. For unit tests + test bootstraps.
+     */
+    static forRootWithCatalog(catalog: PlanCatalog, opts?: {
+        global?: boolean;
+    }): 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 (SPEC_V2 §6.5). Optional. */
+    marketing?: PlanCatalog['marketing'];
+}
+declare function buildPlanCatalogFromSnapshot(settings: PlanCatalogBuildSettings, snapshot: PlanCatalogReadSnapshot): PlanCatalog;
+
+declare const PLAN_CATALOG_IMPORT_SINK_TOKEN: unique symbol;
+declare class PlanCatalogImporterService {
+    private readonly sink;
+    constructor(sink: PlanCatalogImportSink);
+    /**
+     * Import directly from a YAML string. Apps pass the contents of the
+     * `saas.yaml` through via the HTTP body; CLI tools can read the file
+     * contents themselves beforehand.
+     *
+     * @throws on a schema failure of the YAML (validated first via the loader).
+     */
+    importFromYaml(yamlContent: string, opts?: {
+        crossFieldChecks?: boolean;
+        source?: string;
+    }): Promise<PlanCatalogImportReport>;
+    importCatalog(catalog: PlanCatalog): Promise<PlanCatalogImportReport>;
+}
+
+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).
+     */
+    guards: Array<Type<CanActivate>>;
+}
+interface PlanCatalogImporterModuleOptions {
+    sink: ProviderSpec<PlanCatalogImportSink>;
+    controller?: PlanCatalogImporterControllerConfig;
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    extraProviders?: Provider[];
+    global?: boolean;
+}
+declare class PlanCatalogImporterModule {
+    static forRoot(options: PlanCatalogImporterModuleOptions): DynamicModule;
+}
+
+declare class PlanCatalogImportDto {
+    yamlContent: string;
+    crossFieldChecks?: boolean;
+}
+declare function buildPlanCatalogImporterController(guards: Array<Type<CanActivate>>): Type;
+
+/**
+ * Finds a plan in the catalog. `undefined` if it does not exist.
+ */
+declare function findPlan(catalog: PlanCatalog, planId: PlanId): PlanDef | undefined;
+/**
+ * Like `findPlan`, but throws a typed error if the plan does not exist.
+ * For code paths where its absence is a bug (plan-change validation,
+ * subscription snapshot on creation).
+ */
+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
+ * not belong in self-service onboarding lists.
+ */
+declare function getMarketedPlans(catalog: PlanCatalog): PlanDef[];
+/**
+ * Net list price from the catalog. `null` when:
+ *   - the plan does not exist
+ *   - the plan is `marketed: false` (e.g. ENTERPRISE — special contract,
+ *     no list price)
+ *   - the plan has no price for the cycle (`monthlyNet`/`yearlyNet === null`)
+ */
+declare function getPlanPriceNet(catalog: PlanCatalog, planId: PlanId, cycle: BillingCycle): number | null;
+/**
+ * Gross list price from the catalog (net * (1 + vatRate/100)).
+ * `null` with the same rules as `getPlanPriceNet`. `vatRate` is optional;
+ * default: `catalog.vatRate`.
+ */
+declare function getPlanPriceGross(catalog: PlanCatalog, planId: PlanId, cycle: BillingCycle, vatRate?: number): number | null;
+/**
+ * Checks whether a plan directly contains a feature (without considering
+ * Bundles / subscription). For marketing lists, plan comparison tables.
+ *
+ * Note: this is NOT the entitlement check for a concrete tenant.
+ * The real entitlement check (`EntitlementService.computeLimits`) takes
+ * Bundle bookings and custom limits into account — this helper function is
+ * only the static plan definition.
+ */
+declare function isFeatureInPlan(catalog: PlanCatalog, planId: PlanId, featureKey: FeatureKey): boolean;
+/**
+ * Aggregated plan Quota for a key. Returns `undefined` when the plan or the
+ * key does not exist.
+ *
+ * `-1` is the catalog convention for "unlimited"; consumers must map that to
+ * `Number.POSITIVE_INFINITY` themselves if they compute with it.
+ */
+declare function getPlanQuota(catalog: PlanCatalog, planId: PlanId, quotaKey: QuotaKey): number | undefined;
+/**
+ * List of all feature keys declared in the catalog that are not
+ * `plannedOnly: true`. For UI lists that show bookable features.
+ */
+declare function getActiveFeatureKeys(catalog: PlanCatalog): FeatureKey[];
+/**
+ * Checks whether a feature is `plannedOnly: true`. If the feature is not
+ * declared in the catalog, the function returns `false` (conservative:
+ * unknown keys are not marked as "planned").
+ */
+declare function isFeaturePlannedOnly(catalog: PlanCatalog, featureKey: FeatureKey): boolean;
+
+declare const FEATURE_UI_REGISTRY_TOKEN: unique symbol;
+
+interface MarketingFields {
+    displayLabel?: string;
+    description?: string;
+    visible?: boolean;
+    badge?: string;
+    topFeatures?: MarketingTopFeature[];
+    trialEnabled?: boolean;
+    trialDays?: number;
+    priceTag?: string | null;
+    ctaLabel?: string | null;
+    highlight?: boolean;
+    priority?: number;
+}
+interface PlanResponseEntry {
+    id: string;
+    name: string;
+    tagline: string;
+    monthlyNet: number | null;
+    yearlyNet: number | null;
+    popular: boolean;
+    quotas: Record<string, number>;
+    features: string[];
+    /** SPEC_V2 §11.1 M6 — optional, present if a MarketingProjection exists. */
+    marketing?: MarketingFields;
+}
+interface PublicBundleEntry {
+    bundleVersionId: string;
+    bundleKey: string;
+    label: string;
+    description: string | null;
+    features: string[];
+    quotas: Record<string, number>;
+    monthlyNet: string | null;
+    yearlyNet: string | null;
+    /**
+     * Uncovered feature dependencies (#35): union of the `requires` of the
+     * contained features minus the ones contained in the bundle itself. The
+     * configurator greys out the bundle if these keys are neither in the plan
+     * nor in the current selection. Empty without a CatalogEntryRepository
+     * (no requires data available).
+     */
+    requiresFeatures: string[];
+    marketing?: MarketingFields;
+}
+interface PublicBusinessTypeEntry {
+    businessTypeVersionId: string;
+    businessTypeKey: string;
+    label: string;
+    description: string | null;
+    monthlyNet: string | null;
+    yearlyNet: string | null;
+    bundleKeys: string[];
+    quotaOverrides: Record<string, number>;
+    marketing?: MarketingFields;
+}
+declare class PublicCatalogController {
+    private readonly planCatalog;
+    private readonly featureRegistry;
+    private readonly projectKey;
+    private readonly marketingRepo;
+    private readonly bundleRepo;
+    private readonly businessTypeRepo;
+    private readonly catalogEntryRepo;
+    constructor(planCatalog: PlanCatalog, featureRegistry: FeatureUiRegistry, projectKey?: string | null, marketingRepo?: MarketingProjectionRepository | null, bundleRepo?: BundleRepository | null, businessTypeRepo?: BusinessTypeRepository | null, catalogEntryRepo?: CatalogEntryRepository | null);
+    listPlans(lang?: string, localeParam?: string): Promise<PlanResponseEntry[]>;
+    listFeatureRegistry(): Promise<FeatureUiRegistry>;
+    /**
+     * SPEC_V2 §11.1 M6 Pack 2c — public catalog endpoint for bundles
+     * (stem list with live versions). If a `MarketingProjection` with
+     * `targetType=BUNDLE` + matching locale exists, it is merged in.
+     */
+    listBundles(lang?: string, localeParam?: string): Promise<PublicBundleEntry[]>;
+    /**
+     * `requires` data for `requiresFeatures` (#35) — comes from the
+     * FeatureCatalogEntries. Without a CatalogEntryRepository or on DB errors,
+     * an empty index: the auth-free endpoint must not break on this,
+     * `requiresFeatures` then stays conservatively empty.
+     */
+    private loadFeatureRequiresIndex;
+    /**
+     * SPEC_V2 §11.1 M6 Pack 2c — public catalog endpoint for BusinessTypes
+     * (stem list with live versions + bundle composition + marketing).
+     */
+    listBusinessTypes(lang?: string, localeParam?: string): Promise<PublicBusinessTypeEntry[]>;
+    private lookupMarketing;
+    private toBundleEntry;
+}
+
+interface PublicCatalogModuleOptions {
+    /** Required: consumer-specific FeatureUiRegistry. */
+    featureUiRegistry: FeatureUiRegistry;
+    /**
+     * SPEC_V2 §11.1 M6 Pack 2c — app identity (e.g. "clubapp"). Used
+     * for marketing lookups + bundles/business-types filter.
+     * Optional; if omitted, the new endpoints return empty lists.
+     */
+    projectKey?: string;
+    /**
+     * Optional. When set, `/billing/bundles` is active.
+     */
+    bundleRepository?: ProviderSpec<BundleRepository>;
+    /**
+     * Optional. When set, `/billing/business-types` is active.
+     */
+    businessTypeRepository?: ProviderSpec<BusinessTypeRepository>;
+    /**
+     * Optional. When set, marketing texts are merged into /billing/bundles
+     * and /billing/business-types (locale filter).
+     */
+    marketingRepository?: ProviderSpec<MarketingProjectionRepository>;
+    /**
+     * Optional (#13). When set (+ projectKey), `/billing/feature-registry`
+     * overlays the editable `FeatureCatalogEntry.icon` from the DB over the
+     * static registry.
+     */
+    catalogEntryRepository?: ProviderSpec<CatalogEntryRepository>;
+    /**
+     * Modules whose providers must be visible in the DI scope — typically
+     * `PrismaModule`/`PlatformAdaptersModule` for the repositories.
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    extraProviders?: Provider[];
+}
+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_BUSINESS_TYPE_REPOSITORY_TOKEN: unique symbol;
+declare const PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN: unique symbol;
+
+/**
+ * List of all auth guards the platform controller should iterate in order
+ * (analogous to `@UseGuards(JwtAuthGuard, TenantGuard, RolesGuard)`).
+ * Provided via `forRoot.authGuards` — can be an array of existing instances
+ * or a factory provider.
+ */
+declare const TENANT_AUTH_GUARDS_TOKEN: unique symbol;
+/**
+ * Resolver function `(req) => string` that extracts the `tenantId` from the
+ * request. Default: `req.user.tenantId`.
+ */
+declare const TENANT_ID_RESOLVER_TOKEN: unique symbol;
+/**
+ * Resolver function `(req) => string` that extracts the `userId` from the
+ * request. Default: `req.user.sub ?? req.user.id`.
+ */
+declare const USER_ID_RESOLVER_TOKEN: unique symbol;
+/**
+ * Resolver function `(req) => string` that extracts the user email from the
+ * request. Optional — used by the audit-log path to build the AdminActor
+ * (`{userId, email, source: 'web', context}`). Default: `req.user.email`.
+ * If the consumer's JWT does not carry an email, the resolver can return
+ * `null` — the audit-log path then falls back to `'unknown'`.
+ */
+declare const USER_EMAIL_RESOLVER_TOKEN: unique symbol;
+/**
+ * Resolver function `(req) => string` that extracts an audit context from the
+ * request (e.g. session ID, trace ID). Default: `req.headers['x-session-id']`
+ * or `'tenant-self-service'`.
+ */
+declare const AUDIT_CONTEXT_RESOLVER_TOKEN: unique symbol;
+/** Adapter token: consumer's `SubscriptionUsagePort` implementation. */
+declare const SUBSCRIPTION_USAGE_PORT_TOKEN: unique symbol;
+/** Adapter token: consumer's `UsageSnapshotPort` implementation. */
+declare const USAGE_SNAPSHOT_PORT_TOKEN: unique symbol;
+/** Adapter token: consumer's `TenantSubscriptionWritePort` implementation. */
+declare const SUBSCRIPTION_WRITE_PORT_TOKEN: unique symbol;
+type TenantIdResolver = (req: unknown) => string | null | undefined;
+type UserIdResolver = (req: unknown) => string | null | undefined;
+type UserEmailResolver = (req: unknown) => string | null | undefined;
+type AuditContextResolver = (req: unknown) => string | null | undefined;
+type AuthGuardList = ReadonlyArray<CanActivate>;
+/**
+ * Optional adapter token: projects the new trial end of a change
+ * (app-specific trial logic, e.g. carry-over of the remaining time). Without a
+ * port, `PlanChangePreviewDto.projectedTrialEndsAt` stays `null` and the wizard
+ * falls back to the current trial end.
+ */
+declare const TRIAL_PROJECTION_PORT_TOKEN: unique symbol;
+interface TrialProjectionInput {
+    /** Current plan key of the subscription. */
+    currentPlan: string;
+    /** Target plan key of the change. */
+    targetPlan: string;
+    /** Current trial end (null = no trial). */
+    currentTrialEndsAt: Date | null;
+    /** Subscription status (e.g. 'TRIAL'/'ACTIVE'). */
+    status: string;
+    now: Date;
+}
+interface TrialProjectionPort {
+    /**
+     * Projected new trial end after the change. `null` if nothing changes or
+     * the target package does not support a trial.
+     */
+    projectTrialEndsAt(input: TrialProjectionInput): Promise<Date | null>;
+}
+/**
+ * Optional adapter token: provides due scheduled plan changes for the
+ * `PendingPlanMaterializationService`. Without a port, the service is not
+ * registered (materialization is opt-in).
+ */
+declare const PENDING_PLAN_QUERY_PORT_TOKEN: unique symbol;
+/** A due scheduled plan change — minimal for materialization. */
+interface DuePendingPlanChange {
+    tenantId: string;
+    /** Target plan key of the scheduled change (`pendingPlan`). */
+    pendingPlan: string;
+    /** Target cycle (`pendingBillingCycle`); `null` → default MONTHLY. */
+    pendingBillingCycle: string | null;
+}
+interface PendingPlanQueryPort {
+    /**
+     * Returns all subscriptions with a due scheduled plan change:
+     * `pendingPlan != null AND pendingEffectiveAt <= now AND status != 'TRIAL'`.
+     * TRIAL is excluded — there the trial lifecycle drives the transition.
+     */
+    findDuePendingPlanChanges(now: Date): Promise<DuePendingPlanChange[]>;
+}
+
+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 SelfServiceBlockedPlans {
+    asTarget?: string[];
+    asSource?: string[];
+}
+declare const SELF_SERVICE_BLOCKED_PLANS_TOKEN: unique symbol;
+/**
+ * Bundle counterpart (#37): `bundleKeys` lists bundles that are not
+ * bookable via self-service (only via sales/special contract).
+ * Applies in `SubscriptionBundlesService.addBundleToSubscription`
+ * (enforcement, 422) and in the bundle preview (blocker indication).
+ */
+interface SelfServiceBlockedBundles {
+    bundleKeys?: string[];
+}
+declare const SELF_SERVICE_BLOCKED_BUNDLES_TOKEN: unique symbol;
+
+interface ProrationDto {
+    daysRemainingInPeriod: number;
+    daysInPeriod: number;
+    periodStart: Date;
+    periodEnd: Date;
+    currentPriceNet: number;
+    targetPriceNet: number;
+    /** Prorated surcharge/credit until end of period. Negative = credit. */
+    prorataDeltaNet: number;
+}
+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';
+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;
+    message: string;
+}
+interface PlanChangePreviewDto {
+    changeType: PlanChangeType;
+    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 "regulär ab Ende der Testphase".
+     */
+    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;
+    /** TRIAL end, if status === 'TRIAL'. */
+    trialEndsAt: 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 catalog;
+    private readonly entitlements;
+    private readonly subscriptions;
+    private readonly usageSnapshot;
+    private readonly blockedPlans;
+    private readonly trialProjection;
+    constructor(catalog: PlanCatalog, entitlements: EntitlementService, subscriptions: SubscriptionUsagePort, usageSnapshot: UsageSnapshotPort, blockedPlans?: SelfServiceBlockedPlans | null, trialProjection?: TrialProjectionPort | 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[]>;
+    private classify;
+    /** Catalog order = rank. Non-marketed plans go to the end. */
+    private planRank;
+    private resolveEffectiveAt;
+    private computeProration;
+}
+
+/**
+ * Optional hook token: the platform `changePlan` path + the
+ * `PendingPlanMaterializationService` call the freeze after the plan mutation
+ * (analogous to `TrialProjectionPort`). Without a port nothing is frozen — the
+ * entitlements then stay catalog-/version-pinned as before.
+ */
+declare const CONTRACT_FREEZE_PORT_TOKEN: unique symbol;
+/** Adapter token: consumer-specific bundle/version data access. */
+declare const CONTRACT_FREEZE_SOURCE_PORT_TOKEN: unique symbol;
+/** Config token: the consumer's `projectKey` for the contract. */
+declare const CONTRACT_FREEZE_PROJECT_KEY_TOKEN: unique symbol;
+interface ContractFreezePort {
+    /**
+     * Freezes the agreed service at `effectiveFrom` as the new active
+     * `SubscriptionContract` (supersedes the previous one). Non-fatal for the
+     * caller — the plan change is already persisted.
+     */
+    freezeOnPlanChange(tenantId: string, newPlan: string, billingCycle: BillingCycle, effectiveFrom: Date): Promise<void>;
+}
+/** Frozen bundle line items + their version ids (trace). */
+interface ContractFreezeBundleSnapshot {
+    lineItems: NewContractLineItemData[];
+    bundleVersionIds: string[];
+}
+/**
+ * Consumer-specific data access for the freeze: live PlanVersion id
+ * (trace) + booked bundles as contract line items. The generic freeze
+ * logic (plan line item from the catalog, snapshot, contract assembly) lives in
+ * the platform `SubscriptionContractFreezeService`.
+ */
+interface ContractFreezeSourcePort {
+    /** Live (published, non-superseded) PlanVersion id of the target plan, or null. */
+    findLivePlanVersionId(planId: string): Promise<string | null>;
+    /**
+     * The tenant's active (non-terminated) bundle bookings as line items.
+     * `vatRate` is passed through so the gross price is computed consistently
+     * with the catalog VAT. Apps without a bundle schema return empty lists.
+     */
+    loadBookedBundles(tenantId: string, cycle: 'monthly' | 'yearly', vatRate: number): Promise<ContractFreezeBundleSnapshot>;
+}
+
+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 SubscriptionContractFreezeService implements ContractFreezePort {
+    private readonly catalog;
+    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>;
+}
+
+declare function computeCarriedTrialEndsAt(currentTrialDays: number, newTrialDays: number, currentTrialEndsAt: Date, now: Date): Date;
+
+declare class PreviewPlanChangeDto {
+    plan: string;
+    billingCycle: string;
+}
+declare class ChangePlanDto extends PreviewPlanChangeDto {
+    /** Immediate change (true) vs. change at period end (false/undefined). */
+    effectiveImmediately?: boolean;
+}
+declare class CancelSubscriptionDto {
+    /** true = cancel immediately (status CANCELED). false/undefined = at period end. */
+    immediately?: boolean;
+}
+
+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 (12 months) 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 = 12. */
+    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;
+}
+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;
+}
+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). */
+    listForSubscription(subscriptionId: string): Promise<SubscriptionBundleView[]>;
+    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;
+}): 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;
+
+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;
+    limits: ReturnType<typeof toEffectiveLimitsSnapshot>;
+    usage: Record<string, number>;
+    /**
+     * P11.4 (METAMODELL §17a): 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;
+    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);
+    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;
+        status: string;
+        immediate: boolean;
+    }>;
+    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;
+}
+
+interface TenantBillingModuleOptions {
+    /**
+     * App guards in the order in which they should be executed
+     * (e.g. `[JwtAuthGuard, TenantGuard]`). The platform combines them via
+     * `ComposedTenantAuthGuard`. At least one guard is mandatory —
+     * missing configuration leads to 403 (safe default).
+     *
+     * Variant 1: array of guard instances (e.g. via factory provider).
+     * Variant 2: Pick<FactoryProvider, 'useFactory' | 'inject'> — apps
+     * pass their guard classes through via `inject` and the factory builds
+     * the array.
+     */
+    authGuards: ProviderSpec<ReadonlyArray<CanActivate>>;
+    /** Adapter to the subscription display form (`GET /billing/usage`). */
+    subscriptionUsagePort: ProviderSpec<SubscriptionUsagePort>;
+    /** Adapter to usage counters of all `quotaKeys`. */
+    usageSnapshotPort: ProviderSpec<UsageSnapshotPort>;
+    /** Adapter for plan/add-on mutations (phase C). */
+    subscriptionWritePort: ProviderSpec<TenantSubscriptionWritePort>;
+    /**
+     * Optional adapter that provides the projected new trial end of a change
+     * (app trial logic, e.g. carry-over). Without a port,
+     * `PlanChangePreviewDto.projectedTrialEndsAt` stays `null`.
+     */
+    trialProjectionPort?: ProviderSpec<TrialProjectionPort>;
+    /**
+     * Optional adapter that provides due scheduled plan changes (#19). If it is
+     * passed, the module registers the `PendingPlanMaterializationService`
+     * (exported) — the consumer triggers it via its own cron. Without a
+     * port, the materialization stays disabled (lazy resolution as before).
+     */
+    pendingPlanQueryPort?: ProviderSpec<PendingPlanQueryPort>;
+    /**
+     * Optional contract freeze hook (#18). If it is configured, the
+     * platform `changePlan` path (non-TRIAL) AND the materialization freeze
+     * the agreed service after the plan mutation as a `SubscriptionContract`
+     * (analogous to `trialProjectionPort`). Consumer-specific are only `projectKey`
+     * + bundle/version data access (`sourcePort`); the contract logic is
+     * generic. `subscriptionContractRepository` is the same repo that also goes
+     * to `EntitlementModule.forRoot` — the freeze needs it in its own scope.
+     */
+    contractFreeze?: {
+        projectKey: string;
+        sourcePort: ProviderSpec<ContractFreezeSourcePort>;
+        subscriptionContractRepository: ProviderSpec<SubscriptionContractRepository>;
+    };
+    /**
+     * Plans that are not accepted as target/source via self-service
+     * (typically ENTERPRISE → special contract). `null`/undefined = no blocks.
+     */
+    selfServiceBlockedPlans?: SelfServiceBlockedPlans;
+    /** Optional tenant ID resolver. Default: `req.user.tenantId`. */
+    tenantIdResolver?: TenantIdResolver;
+    /** Optional user ID resolver. Default: `req.user.sub ?? req.user.id`. */
+    userIdResolver?: UserIdResolver;
+    /**
+     * Optional email resolver for the audit log path. Default: `req.user.email`.
+     * If the consumer JWT does not include the email, the resolver can
+     * return `null` — the audit log then uses `'unknown'`.
+     */
+    userEmailResolver?: UserEmailResolver;
+    /**
+     * Optional audit context resolver (session ID / trace ID). Default:
+     * `req.headers['x-session-id']` or `'tenant-self-service'`.
+     */
+    auditContextResolver?: AuditContextResolver;
+    /**
+     * Modules whose providers must be visible within this module.
+     * Typical use case: the app's own `AuthModule`, so that the `JwtAuthGuard`
+     * is injectable in the `authGuards` factory. Without this entry NestJS throws
+     * `UnknownDependenciesException` for JwtAuthGuard.
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * Additional providers that are registered in the DynamicModule itself —
+     * typically: the adapter classes referenced in `inject:[Adapter]` lists
+     * (e.g. `PrismaSubscriptionUsagePort`). NestJS 11.1.19
+     * resolves factory inject tokens only in the DynamicModule's own scope.
+     */
+    extraProviders?: Provider[];
+    /** Register the module globally — default `false`. */
+    global?: boolean;
+}
+declare class TenantBillingModule {
+    static forRoot(options: TenantBillingModuleOptions): DynamicModule;
+}
+
+/**
+ * Builds the `ConfiguratorCatalog` (for onboarding step 3) from the
+ * live `plan_versions` (SuperAdmin defines plans + prices) plus the
+ * app-specific plan-marketing source (`ConfiguratorMarketingProvider`).
+ *
+ * Deliberately no DI on the marketing provider via token — the builder is
+ * a pure-function-like class that consumers call directly (typically in an
+ * app adapter that implements `RegistrationConfiguratorLookup.getCatalog()`).
+ */
+declare class ConfiguratorCatalogBuilder {
+    build(input: {
+        sources: ConfiguratorSourcesLookup;
+        marketing: ConfiguratorMarketingProvider;
+    }): Promise<ConfiguratorCatalog>;
+}
+
+declare const SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN: unique symbol;
+/** Optional config token; default = 12 months minimum term. */
+declare const SUBSCRIPTION_BUNDLE_CONFIG_TOKEN: unique symbol;
+
+interface SubscriptionBundlePreviewIssue {
+    code: string;
+    message: string;
+}
+/** 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;
+}
+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;
+    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;
+    }, 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;
+    /** `projectKey` lives on the bundle stem, not on the version. */
+    private resolveProjectKey;
+}
+/**
+ * List price (net) for the billing cycle including plan-specific
+ * pricing override (BundlePricingOverride with `planId`, without
+ * `businessTypeKey`). null = no price maintained for the cycle.
+ */
+declare function resolveBundlePriceNet(bundleVersion: BundleVersionRow, planKey: string, billingCycle: string): number | null;
+
+interface SubscriptionBundleControllerOptions {
+    extraGuards?: Array<Type<CanActivate>>;
+    /**
+     * Auth guard list analogous to `TenantBillingModule.forRoot.authGuards`.
+     * Without this list, `ComposedTenantAuthGuard` blocks fail-closed.
+     */
+    authGuards?: ProviderSpec<ReadonlyArray<CanActivate>>;
+    /**
+     * Usage port for subscription lookup and current plan compatibility.
+     * If not set, an imported module must export the token.
+     */
+    subscriptionUsagePort?: ProviderSpec<SubscriptionUsagePort>;
+    /** Optional tenant-ID resolver. Default: `req.user.tenantId`. */
+    tenantIdResolver?: TenantIdResolver;
+}
+interface SubscriptionBundleModuleOptions {
+    subscriptionBundleRepository: ProviderSpec<SubscriptionBundleRepository>;
+    /**
+     * Optional — if omitted, `BUNDLE_REPOSITORY_TOKEN` is expected via
+     * default inject from the DI scope (typically via an imported
+     * `CatalogModule`).
+     */
+    bundleRepository?: ProviderSpec<BundleRepository>;
+    /** Default minimum term (months). Default = 12. */
+    defaultMinimumTermMonths?: number;
+    /**
+     * Self-service policy (#37): bundles that are only bookable via sales.
+     * Applies in `addBundleToSubscription` (422 BUNDLE_NOT_SELF_SERVICE)
+     * and in the preview (blocker).
+     */
+    selfServiceBlockedBundles?: SelfServiceBlockedBundles;
+    /**
+     * If set: the tenant self-service controller is mounted at
+     * `/billing/subscription-bundles` (GET/POST/DELETE). The
+     * `extraGuards` are applied in addition to the platform default
+     * `ComposedTenantAuthGuard` (role/MFA guards).
+     *
+     * Prerequisite: the consumer has already registered `TenantBillingModule`
+     * — the controller needs `SUBSCRIPTION_USAGE_PORT_TOKEN`
+     * + `TENANT_ID_RESOLVER_TOKEN` in the same DI scope.
+     */
+    controller?: SubscriptionBundleControllerOptions;
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    extraProviders?: Provider[];
+    global?: boolean;
+}
+declare class SubscriptionBundleModule {
+    static forRoot(options: SubscriptionBundleModuleOptions): DynamicModule;
+}
+
+/**
+ * Factory analogous to `buildBundlesController` etc. — the consumer can pass
+ * additional guards (e.g. RoleGuard) in addition to the platform default
+ * `ComposedTenantAuthGuard`.
+ */
+declare function buildTenantSubscriptionBundlesController(extraGuards?: Array<Type<CanActivate>>): Type;
+
+export { AUDIT_CONTEXT_RESOLVER_TOKEN, type AddBundleToSubscriptionInput, type AjvErrorLike, type AuditContextResolver, type AuthGuardList, type BundlePreviewSnapshot, CONTRACT_FREEZE_PORT_TOKEN, CONTRACT_FREEZE_PROJECT_KEY_TOKEN, CONTRACT_FREEZE_SOURCE_PORT_TOKEN, type CancelBundleFromSubscriptionInput, CancelSubscriptionDto, CatalogBundleUpsellResolver, ChangePlanDto, CompleteOnboardingSubscriptionDto, ComposedTenantAuthGuard, ConfiguratorCatalogBuilder, type ContractFreezeBundleSnapshot, type ContractFreezePort, type ContractFreezeSourcePort, type DuePendingPlanChange, FEATURE_GUARD_CONFIG_TOKEN, FEATURE_UI_REGISTRY_TOKEN, FeatureGuard, type FeatureGuardConfig, LimitExceededFilter, type LimitsCheckRow, type LoadPlanCatalogOptions, type MarketingFields, type NextPeriodWindow, PENDING_PLAN_QUERY_PORT_TOKEN, PLAN_CATALOG_IMPORT_SINK_TOKEN, PLAN_CATALOG_READ_SINK_TOKEN, PLAN_CATALOG_TOKEN, PUBLIC_CATALOG_BUNDLE_REPOSITORY_TOKEN, PUBLIC_CATALOG_BUSINESS_TYPE_REPOSITORY_TOKEN, PUBLIC_CATALOG_MARKETING_REPOSITORY_TOKEN, PUBLIC_CATALOG_PROJECT_KEY_TOKEN, PendingPlanMaterializationService, type PendingPlanQueryPort, type PeriodRollInput, type PlanCatalogBuildSettings, PlanCatalogImportDto, type PlanCatalogImporterControllerConfig, PlanCatalogImporterModule, type PlanCatalogImporterModuleOptions, PlanCatalogImporterService, PlanCatalogModule, type PlanCatalogModuleOptions, PlanCatalogValidationError, type PlanChangeContext, type PlanChangePreviewDto, type PlanChangePreviewIssue, PlanChangePreviewService, type PlanChangeType, type PlanResponseEntry, type PlanSnapshotDto, PreviewPlanChangeDto, type ProrationDto, type ProrationInput, type PublicBundleEntry, type PublicBusinessTypeEntry, PublicCatalogController, PublicCatalogModule, type PublicCatalogModuleOptions, PublishValidationError, type PublishablePlanVersion, REQUIRE_FEATURE_KEY, type RedundantFeatureHint, type RenewalDecision, type RenewalSubInput, RequireFeature, SELF_SERVICE_BLOCKED_BUNDLES_TOKEN, SELF_SERVICE_BLOCKED_PLANS_TOKEN, SUBSCRIPTION_BUNDLE_CONFIG_TOKEN, SUBSCRIPTION_BUNDLE_REPOSITORY_TOKEN, SUBSCRIPTION_USAGE_PORT_TOKEN, SUBSCRIPTION_WRITE_PORT_TOKEN, type SelfServiceBlockedBundles, type SelfServiceBlockedPlans, type SubscriptionBundleAddPreviewDto, type SubscriptionBundleCancelPreviewDto, type SubscriptionBundleConfig, type SubscriptionBundleControllerOptions, SubscriptionBundleModule, type SubscriptionBundleModuleOptions, type SubscriptionBundlePreviewContext, type SubscriptionBundlePreviewIssue, SubscriptionBundlePreviewService, SubscriptionBundlesService, SubscriptionContractFreezeService, TENANT_AUTH_GUARDS_TOKEN, TENANT_ID_RESOLVER_TOKEN, TRIAL_PROJECTION_PORT_TOKEN, TenantAdminGuard, TenantBillingController, TenantBillingModule, type TenantBillingModuleOptions, type TenantIdResolver, type TrialProjectionInput, type TrialProjectionPort, UPSELL_OFFER_CURRENCY_TOKEN, UPSELL_OFFER_RESOLVER_TOKEN, USAGE_SNAPSHOT_PORT_TOKEN, USER_EMAIL_RESOLVER_TOKEN, USER_ID_RESOLVER_TOKEN, type UsageResponse, type UserEmailResolver, type UserIdResolver, addMonths, assertBaseVersionFresh, assertChangeNote, assertDraftPublishable, assertOptimisticLockHeld, buildPlanCatalogFromSnapshot, buildPlanCatalogImporterController, buildTenantSubscriptionBundlesController, clearPendingPlanVersionFields, computeCarriedTrialEndsAt, computeNextPeriod, computeProration, decideRenewal, findPlan, getActiveFeatureKeys, getMarketedPlans, getPlanOrThrow, getPlanPriceGross, getPlanPriceNet, getPlanQuota, initialPeriodWindow, isFeatureInPlan, isFeaturePlannedOnly, loadPlanCatalogFromFile, loadPlanCatalogFromString, periodEndAfter, periodEndWithMinLead, resolveBundleCancelEffectiveAt, resolveBundlePriceNet };