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

package/dist/{module-options-COSEb0VW.d.ts → module-options-DmQ3G4sZ.d.ts}

@@ -1,14 +1,15 @@
 import { Type, DynamicModule, ForwardReference, Provider, CanActivate, FactoryProvider } from '@nestjs/common';
-import { SuperAdminProvisioningPort, MfaPort, AuditPort, RlsBypassPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, AdminResourcesPort, FeatureUiRegistry, PlanCatalog, SaaSiCatPersistenceAdapter, QuotaProvider, SubscriptionUsagePort, UsageSnapshotPort, TenantSubscriptionWritePort, FirstTimeCustomerCheck } from '@saasicat/core';
+import { SuperAdminProvisioningPort, MfaPort, AuditPort, RlsBypassPort, AppliedSettingsPort, EmailPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, AdminResourcesPort, FeatureUiRegistry, PlanCatalog, SaaSiCatPersistenceAdapter, QuotaProvider, SubscriptionUsagePort, UsageSnapshotPort, TenantSubscriptionWritePort, FirstTimeCustomerCheck } from '@saasicat/core';
 import { P as ProviderSpec } from './di-CcNeq9v-.js';
-import { d as AdminResourcesModuleOptions, g as AdminStatsModuleOptions, b as AdminManifestConfig } from './admin-resources.module-DF5_Q7RD.js';
-import { t as TenantBillingModuleOptions, p as SubscriptionBundleModuleOptions, n as SubscriptionBundleControllerOptions } from './tenant-billing.module-wUbsQSFG.js';
-import { b as CatalogModuleOptions } from './catalog.module-BTnMsE6u.js';
-import { b as DiscoveryAppInfo } from './discovery.scanner-9cMqF95o.js';
-import { E as EntitlementResolutionConfig } from './plan-resolution-Cgo_TR1H.js';
-import { a as PromoCodesModuleOptions } from './promo.module-Z8h1PNX-.js';
-import { b as CheckoutOfferModuleOptions } from './checkout-offer.module-CMtiQJTT.js';
-import { a as SubscriptionContractModuleOptions } from './subscription-contract.module-fDFdQ0jm.js';
+import { A as AdminResourcesModuleOptions, a as AdminStatsModuleOptions, b as AdminManifestConfig } from './admin-resources.module-CWqdI9BV.js';
+import { L as LoadPlanCatalogOptions, T as TenantBillingModuleOptions, S as SubscriptionBundleModuleOptions, a as SubscriptionBundleControllerOptions } from './tenant-billing.module-DohgJJ2m.js';
+import { C as CatalogModuleOptions, P as PublicMarketingCatalogOptions, N as NewPaymentMethodsSource } from './catalog.module-C9O7BxRq.js';
+import { D as DiscoveryAppInfo } from './discovery.scanner-DXKc6JkV.js';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CwUy_OqC.js';
+import { P as PromoCodesModuleOptions } from './promo.module-DuIJdK3U.js';
+import { C as CheckoutOfferModuleOptions } from './checkout-offer.module-x7SP_dX4.js';
+import { P as PaymentsModuleOptions, a as PaymentsTenantRoutesOptions } from './payments.module-CQGv_VG7.js';
+import { S as SubscriptionContractModuleOptions } from './subscription-contract.module-BfIRpc1o.js';
 
 interface SetupModuleOptions {
     /**
@@ -82,6 +83,21 @@ interface SaaSiCatAdapters {
     mfa?: ProviderSpec<MfaPort>;
     audit?: ProviderSpec<AuditPort>;
     rlsBypass?: ProviderSpec<RlsBypassPort>;
+    /**
+     * Optional. Where the record of the applied configuration is kept; the
+     * `persistence` bundle supplies it by default. Without either, the platform
+     * runs the configuration all the same and says once, at boot, that it is
+     * not recording it.
+     */
+    appliedSettings?: ProviderSpec<AppliedSettingsPort>;
+    /**
+     * Optional. How the platform mails an operator — today, the people
+     * `config/saas.yaml#notifications.settingsChanged` names when a start
+     * finds the settings changed. Not part of a persistence bundle: mail is not
+     * persistence. Without it the record is still written, and the boot log
+     * says once that the addresses in the file reach nobody.
+     */
+    email?: ProviderSpec<EmailPort>;
     /**
      * Optional. If provided, `PlanCatalogModule` is hydrated from this sink
      * (DB read at boot). If omitted, `planCatalog` MUST be passed as a ready
@@ -105,7 +121,17 @@ interface SaaSiCatAdapters {
     transactionRunner?: ProviderSpec<TransactionRunner>;
 }
 type PlatformImports = Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
-interface SaaSiCatCatalogOptions extends Pick<CatalogModuleOptions, 'strictModeCheckMode' | 'autoSyncDiscoveryAtBoot' | 'marketedOnlyFeatures' | 'publicMarketingCatalog' | 'extraProviders'> {
+interface SaaSiCatCatalogOptions extends Pick<CatalogModuleOptions, 'strictModeCheckMode' | 'autoSyncDiscoveryAtBoot' | 'marketedOnlyFeatures' | 'extraProviders'> {
+    /**
+     * The auth-free pricing-page endpoint. Unlike `CatalogModule`'s own option,
+     * `newPaymentMethodsFrom` is left out here: it is filled from `payments`,
+     * so the endpoint and the gateways cannot disagree. Naming a source
+     * overrides that; there is no way to say "none" here, because `payments`
+     * says it already.
+     */
+    publicMarketingCatalog?: Omit<PublicMarketingCatalogOptions, 'newPaymentMethodsFrom'> & {
+        newPaymentMethodsFrom?: Type<NewPaymentMethodsSource>;
+    };
     /** Labels/icons used by discovery review and the public catalog. */
     featureUiRegistry: FeatureUiRegistry;
     /** Mount the SuperAdmin catalog controllers. Default `true`. */
@@ -127,6 +153,19 @@ interface SaaSiCatTenantBillingOptions extends Omit<TenantBillingModuleOptions,
     usageSnapshotPort?: ProviderSpec<UsageSnapshotPort>;
     subscriptionWritePort?: ProviderSpec<TenantSubscriptionWritePort>;
 }
+/**
+ * Payment methods through a payment gateway. The event log and the payment
+ * methods come from `persistence.payments`, the subscribers from
+ * `persistence.entitlement`, and the tenant's routes share `tenantBilling`'s
+ * authentication and resolvers.
+ */
+interface SaaSiCatPaymentsOptions extends Pick<PaymentsModuleOptions, 'gateways' | 'imports' | 'extraProviders'> {
+    /**
+     * Who of a tenant's users holds the billing permission, which the tenant's
+     * payment method routes require. Default: the tenant's administrator.
+     */
+    billingPermissionGuards?: PaymentsTenantRoutesOptions['billingPermissionGuards'];
+}
 interface SaaSiCatSubscriptionBundlesOptions extends Omit<SubscriptionBundleModuleOptions, 'subscriptionBundleRepository' | 'bundleRepository' | 'controller' | 'imports' | 'extraProviders' | 'global'> {
     /** Default mounts the tenant controller and reuses tenant-billing auth. */
     controller?: false | Omit<SubscriptionBundleControllerOptions, 'authGuards' | 'subscriptionUsagePort'>;
@@ -134,12 +173,16 @@ interface SaaSiCatSubscriptionBundlesOptions extends Omit<SubscriptionBundleModu
     extraProviders?: Provider[];
 }
 interface SaaSiCatAdminResourcesOptions extends Omit<AdminResourcesModuleOptions, 'resources' | 'guards' | 'global'> {
-    /** Override the default controller guards + `SuperAdminGuard` chain. */
+    /**
+     * Override the default controller guards + `SuperAdminGuard` chain.
+     * Suspending and reactivating a tenant require the second factor either
+     * way; that check sits on the two handlers, not in this list.
+     */
     guards?: Array<Type<CanActivate>>;
     /** Custom schema override; the persistence bundle supplies the default. */
     resources?: ProviderSpec<AdminResourcesPort>;
 }
-interface SaaSiCatPromoCodesOptions extends Omit<PromoCodesModuleOptions, 'promoCodeRepository' | 'redemptionRepository' | 'validationLogRepository' | 'subscriptionLookup' | 'revenueAggregator' | 'transactionRunner' | 'firstTimeCustomerCheck' | 'adminController' | 'global'> {
+interface SaaSiCatPromoCodesOptions extends Omit<PromoCodesModuleOptions, 'promoCodeRepository' | 'redemptionRepository' | 'validationLogRepository' | 'subscriptionLookup' | 'revenueAggregator' | 'holdRepository' | 'transactionRunner' | 'firstTimeCustomerCheck' | 'adminController' | 'global'> {
     /**
      * Required when the public preview/redeem flow is enabled. Admin-only
      * setups do not need an app-specific customer-history check.
@@ -169,53 +212,81 @@ interface SaaSiCatAdminStatsOptions extends Omit<AdminStatsModuleOptions, 'audit
  * Public checkout-offer flow. Catalog repositories default to the persistence
  * bundle, while the app still supplies its checkout-offer repository.
  */
-interface SaaSiCatCheckoutOfferOptions extends Omit<CheckoutOfferModuleOptions, 'bundleRepository' | 'planRepository' | 'catalogEntryRepository' | 'global'> {
+interface SaaSiCatCheckoutOfferOptions extends Omit<CheckoutOfferModuleOptions, 'bundleRepository' | 'planRepository' | 'promotionRepository' | 'catalogEntryRepository' | 'conclusion' | 'global'> {
     bundleRepository?: CheckoutOfferModuleOptions['bundleRepository'];
+    /**
+     * Defaults to the persistence bundle's subscription contract repository and
+     * transaction runner, so `conclude` works wherever the bundle has both.
+     */
+    conclusion?: Partial<NonNullable<CheckoutOfferModuleOptions['conclusion']>>;
+    /** Defaults to the persistence bundle's plan repository; an offer cannot be priced without one. */
     planRepository?: CheckoutOfferModuleOptions['planRepository'];
+    promotionRepository?: CheckoutOfferModuleOptions['promotionRepository'];
     catalogEntryRepository?: CheckoutOfferModuleOptions['catalogEntryRepository'];
 }
-/** Subscription-contract service, deriving its repository from persistence by default. */
-interface SaaSiCatSubscriptionContractOptions extends Omit<SubscriptionContractModuleOptions, 'subscriptionContractRepository' | 'global'> {
+/**
+ * Subscription-contract service and the subscriber service beside it, deriving
+ * both repositories from persistence by default.
+ */
+interface SaaSiCatSubscriptionContractOptions extends Omit<SubscriptionContractModuleOptions, 'subscriptionContractRepository' | 'subscriberRepository' | 'global'> {
     subscriptionContractRepository?: SubscriptionContractModuleOptions['subscriptionContractRepository'];
+    subscriberRepository?: SubscriptionContractModuleOptions['subscriberRepository'];
 }
 /**
  * What `SaaSiCatModule.forRoot()` composes.
  *
  * One subsystem is deliberately absent: **self-registration**. A prospect
- * signing themselves up — mail address, OTP, plan choice, payment, activation —
- * is `RegistrationModule` from `@saasicat/nest/registration`, and it is
- * hand-wired: ten required ports, none of which a persistence bundle supplies.
+ * signing themselves up — mail address, OTP, plan choice, payment method,
+ * activation — is `RegistrationModule` from `@saasicat/nest/registration`, and
+ * it is hand-wired: its required ports are ones no persistence bundle
+ * supplies. Its payment method is taken through `payments`, which is composed
+ * here.
  *
- * That is a decision with a reason and a plan, not an omission: the ten ports
+ * That is a decision with a reason and a plan, not an omission: those ports
  * have no executable contract yet (`@saasicat/persistence-testing` covers the
- * catalogue, subscription, promo and audit ports and none of these), and
+ * ports a persistence bundle supplies and none of these), and
  * folding unverified ports into a bundle would move the problem rather than
- * check it. See `docs/self-registration.md`.
+ * check it. See `docs/guides/self-registration.md`.
  *
  * Everything else — an operator creating tenants through the SuperAdmin UI, a
  * CLI, or your own onboarding form — is composed here.
  */
+/**
+ * The members `dbCatalog` takes. The type below is derived from this list, so
+ * the shape the platform refuses at boot and the shape the compiler accepts
+ * cannot drift apart — and `saasicat codemod v1` reads the same list.
+ */
+declare const DB_CATALOG_MEMBERS: readonly ["path", "env"];
+/**
+ * Which `config/saas.yaml` a database-held catalogue reads its settings from.
+ *
+ * The same file the quickstart path loads, read by the platform. A `plans:` or
+ * `features:` block in it is not read on this path — the sink is their source —
+ * so a file kept as the seed for `saasicat catalog import` still loads.
+ */
+type DbCatalogOptions = Pick<LoadPlanCatalogOptions, (typeof DB_CATALOG_MEMBERS)[number]>;
 interface SaaSiCatModuleOptions {
     /**
      * Plan catalog. Either as an already-loaded object (quickstart, comes
      * directly from `loadPlanCatalogFromFile('config/saas.yaml')`) or via DB
      * hydration: a sink reference in `adapters.planCatalogReadSink` /
-     * `persistence.planCatalogReadSink` **plus** the `dbCatalog` identity.
+     * `persistence.planCatalogReadSink` **plus** `dbCatalog` naming the file.
      */
     planCatalog?: PlanCatalog;
     /**
-     * App identity for the DB-hydration path — required when `planCatalog`
-     * is omitted. The read sink only loads plans/features (filtered by
-     * `projectKey`); branding, currency and VAT cannot come from the
-     * database and must be supplied here.
-     */
-    dbCatalog?: {
-        projectKey: string;
-        currency: string;
-        vatRate: number;
-        app?: PlanCatalog['app'];
-        marketing?: PlanCatalog['marketing'];
-    };
+     * The DB-hydration path — required when `planCatalog` is omitted: the
+     * `config/saas.yaml` the platform reads the settings from. The read sink
+     * loads plans and features; `app`, `currency`, `vatRate`, `tenantBilling`,
+     * `marketing` and `notifications` are not in the database and never will
+     * be, so they come from the file this names.
+     *
+     * A path rather than the values. The option used to take them as values,
+     * and every consumer forwarded them from the file it had loaded anyway —
+     * by agreement, which is a second place a setting can live. The file
+     * defines them by construction now: there is nothing here to type a
+     * setting into.
+     */
+    dbCatalog?: DbCatalogOptions;
     /**
      * Aggregate persistence bundle from an adapter package (e.g.
      * `prismaPersistence({ client: PrismaService })` from
@@ -231,13 +302,16 @@ interface SaaSiCatModuleOptions {
      */
     adapters?: SaaSiCatAdapters;
     /**
-     * Class-level guards for the platform controllers (`GET /admin/discovery`
-     * and `GET /admin/manifest`). REQUIRED — otherwise the platform throws at
-     * boot, because a manifest controller must never be silently registered
-     * without auth (platform security).
+     * The guards that establish who is calling the platform's controllers —
+     * typically `[JwtAuthGuard]`. REQUIRED: the platform does not mount an
+     * administration route whose protection nobody decided.
      *
-     * Pass `[]` explicitly if the endpoint is intentionally auth-free
-     * (CI/smoke test).
+     * Authentication only. Every operator route the platform mounts — the
+     * administration, catalogue, discovery, manifest, settings, promo codes and
+     * statistics — runs `SuperAdminGuard` after these, and the tenant manifest
+     * falls back to these guards alone, so a role check added here would lock
+     * tenants out of their own manifest. With `[]` nothing establishes a
+     * caller, and `SuperAdminGuard` refuses every operator request.
      */
     controller: {
         guards: Array<Type<CanActivate>>;
@@ -257,6 +331,19 @@ interface SaaSiCatModuleOptions {
      * app can simply override.
      */
     includeManifestController?: boolean;
+    /**
+     * Mount the platform's `GET /admin/settings` controller — the running
+     * configuration, since when it applies, and what changed between two
+     * starts. Default `true`.
+     *
+     * Set `false` when the app serves that route itself; the record is kept
+     * and compared at boot either way, only the endpoint is left out — the
+     * sidebar entry stays, since the page is shipped and the route answers. Note
+     * what the endpoint answers: the resolved settings and the absolute path of
+     * `config/saas.yaml`, behind `controller.guards` and `SuperAdminGuard` —
+     * the same chain as the manifest and discovery.
+     */
+    includeSettingsController?: boolean;
     /**
      * Modules whose providers must be visible in the DI scope (typically:
      * `AuthModule` with the `JwtAuthGuard`).
@@ -323,6 +410,13 @@ interface SaaSiCatModuleOptions {
      * `quotaProviders` unless explicitly overridden.
      */
     tenantBilling?: false | SaaSiCatTenantBillingOptions;
+    /**
+     * Payment methods through a payment gateway: the webhook route for every
+     * account in `config/saas.yaml#payments`, and — with `tenantBilling` — the
+     * tenant's payment method behind the billing permission. Self-registration
+     * takes a sign-up's payment method through it.
+     */
+    payments?: false | SaaSiCatPaymentsOptions;
     /**
      * Add-on bundle service and tenant controller. `true` uses defaults and
      * reuses tenant-billing auth/usage; an object customizes policy.
@@ -403,4 +497,4 @@ interface SaaSiCatModuleOptions {
     enforcementChainCheck?: boolean;
 }
 
-export { PLAN_RESOLVER_PORT_TOKEN as P, type SaaSiCatAdapters as S, type TenantManifestControllerOptions as T, type SaaSiCatAdminResourcesOptions as a, type SaaSiCatAdminStatsOptions as b, type SaaSiCatCatalogOptions as c, type SaaSiCatCheckoutOfferOptions as d, type SaaSiCatModuleOptions as e, type SaaSiCatPromoCodesOptions as f, type SaaSiCatSetupOptions as g, type SaaSiCatSubscriptionBundlesOptions as h, type SaaSiCatSubscriptionContractOptions as i, type SaaSiCatTenantAuthGuards as j, type SaaSiCatTenantBillingOptions as k, SetupModule as l, type SetupModuleOptions as m, StaticPlanResolver as n, type PlanResolverPort as o, buildTenantManifestController as p };
+export { DB_CATALOG_MEMBERS as D, PLAN_RESOLVER_PORT_TOKEN as P, type SaaSiCatAdapters as S, type TenantManifestControllerOptions as T, StaticPlanResolver as a, type PlanResolverPort as b, type SaaSiCatModuleOptions as c, type SaaSiCatAdminResourcesOptions as d, type SaaSiCatAdminStatsOptions as e, type SaaSiCatCatalogOptions as f, type SaaSiCatCheckoutOfferOptions as g, type SaaSiCatPromoCodesOptions as h, type SaaSiCatSetupOptions as i, type SaaSiCatSubscriptionBundlesOptions as j, type SaaSiCatSubscriptionContractOptions as k, type SaaSiCatTenantAuthGuards as l, type SaaSiCatTenantBillingOptions as m, SetupModule as n, type SetupModuleOptions as o, type DbCatalogOptions as p, buildTenantManifestController as q };

package/dist/{module-options-BG3MzQva.d.cts → module-options-qAOwinHR.d.cts}

@@ -1,14 +1,15 @@
 import { Type, DynamicModule, ForwardReference, Provider, CanActivate, FactoryProvider } from '@nestjs/common';
-import { SuperAdminProvisioningPort, MfaPort, AuditPort, RlsBypassPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, AdminResourcesPort, FeatureUiRegistry, PlanCatalog, SaaSiCatPersistenceAdapter, QuotaProvider, SubscriptionUsagePort, UsageSnapshotPort, TenantSubscriptionWritePort, FirstTimeCustomerCheck } from '@saasicat/core';
+import { SuperAdminProvisioningPort, MfaPort, AuditPort, RlsBypassPort, AppliedSettingsPort, EmailPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, AdminResourcesPort, FeatureUiRegistry, PlanCatalog, SaaSiCatPersistenceAdapter, QuotaProvider, SubscriptionUsagePort, UsageSnapshotPort, TenantSubscriptionWritePort, FirstTimeCustomerCheck } from '@saasicat/core';
 import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
-import { d as AdminResourcesModuleOptions, g as AdminStatsModuleOptions, b as AdminManifestConfig } from './admin-resources.module-CpvzcfCc.cjs';
-import { t as TenantBillingModuleOptions, p as SubscriptionBundleModuleOptions, n as SubscriptionBundleControllerOptions } from './tenant-billing.module-BznC3XtW.cjs';
-import { b as CatalogModuleOptions } from './catalog.module-BDDO6iwq.cjs';
-import { b as DiscoveryAppInfo } from './discovery.scanner-9cMqF95o.cjs';
-import { E as EntitlementResolutionConfig } from './plan-resolution-Cgo_TR1H.cjs';
-import { a as PromoCodesModuleOptions } from './promo.module-DtvIycpt.cjs';
-import { b as CheckoutOfferModuleOptions } from './checkout-offer.module-CVpWrzbe.cjs';
-import { a as SubscriptionContractModuleOptions } from './subscription-contract.module-CEK8HS5-.cjs';
+import { A as AdminResourcesModuleOptions, a as AdminStatsModuleOptions, b as AdminManifestConfig } from './admin-resources.module-B4XNvdH-.cjs';
+import { L as LoadPlanCatalogOptions, T as TenantBillingModuleOptions, S as SubscriptionBundleModuleOptions, a as SubscriptionBundleControllerOptions } from './tenant-billing.module-ClbjzocC.cjs';
+import { C as CatalogModuleOptions, P as PublicMarketingCatalogOptions, N as NewPaymentMethodsSource } from './catalog.module-T-I5Ricz.cjs';
+import { D as DiscoveryAppInfo } from './discovery.scanner-DXKc6JkV.cjs';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CwUy_OqC.cjs';
+import { P as PromoCodesModuleOptions } from './promo.module-CKkECmU8.cjs';
+import { C as CheckoutOfferModuleOptions } from './checkout-offer.module-DFhGy6JO.cjs';
+import { P as PaymentsModuleOptions, a as PaymentsTenantRoutesOptions } from './payments.module-BdUq9ot_.cjs';
+import { S as SubscriptionContractModuleOptions } from './subscription-contract.module-DTMuUJYd.cjs';
 
 interface SetupModuleOptions {
     /**
@@ -82,6 +83,21 @@ interface SaaSiCatAdapters {
     mfa?: ProviderSpec<MfaPort>;
     audit?: ProviderSpec<AuditPort>;
     rlsBypass?: ProviderSpec<RlsBypassPort>;
+    /**
+     * Optional. Where the record of the applied configuration is kept; the
+     * `persistence` bundle supplies it by default. Without either, the platform
+     * runs the configuration all the same and says once, at boot, that it is
+     * not recording it.
+     */
+    appliedSettings?: ProviderSpec<AppliedSettingsPort>;
+    /**
+     * Optional. How the platform mails an operator — today, the people
+     * `config/saas.yaml#notifications.settingsChanged` names when a start
+     * finds the settings changed. Not part of a persistence bundle: mail is not
+     * persistence. Without it the record is still written, and the boot log
+     * says once that the addresses in the file reach nobody.
+     */
+    email?: ProviderSpec<EmailPort>;
     /**
      * Optional. If provided, `PlanCatalogModule` is hydrated from this sink
      * (DB read at boot). If omitted, `planCatalog` MUST be passed as a ready
@@ -105,7 +121,17 @@ interface SaaSiCatAdapters {
     transactionRunner?: ProviderSpec<TransactionRunner>;
 }
 type PlatformImports = Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
-interface SaaSiCatCatalogOptions extends Pick<CatalogModuleOptions, 'strictModeCheckMode' | 'autoSyncDiscoveryAtBoot' | 'marketedOnlyFeatures' | 'publicMarketingCatalog' | 'extraProviders'> {
+interface SaaSiCatCatalogOptions extends Pick<CatalogModuleOptions, 'strictModeCheckMode' | 'autoSyncDiscoveryAtBoot' | 'marketedOnlyFeatures' | 'extraProviders'> {
+    /**
+     * The auth-free pricing-page endpoint. Unlike `CatalogModule`'s own option,
+     * `newPaymentMethodsFrom` is left out here: it is filled from `payments`,
+     * so the endpoint and the gateways cannot disagree. Naming a source
+     * overrides that; there is no way to say "none" here, because `payments`
+     * says it already.
+     */
+    publicMarketingCatalog?: Omit<PublicMarketingCatalogOptions, 'newPaymentMethodsFrom'> & {
+        newPaymentMethodsFrom?: Type<NewPaymentMethodsSource>;
+    };
     /** Labels/icons used by discovery review and the public catalog. */
     featureUiRegistry: FeatureUiRegistry;
     /** Mount the SuperAdmin catalog controllers. Default `true`. */
@@ -127,6 +153,19 @@ interface SaaSiCatTenantBillingOptions extends Omit<TenantBillingModuleOptions,
     usageSnapshotPort?: ProviderSpec<UsageSnapshotPort>;
     subscriptionWritePort?: ProviderSpec<TenantSubscriptionWritePort>;
 }
+/**
+ * Payment methods through a payment gateway. The event log and the payment
+ * methods come from `persistence.payments`, the subscribers from
+ * `persistence.entitlement`, and the tenant's routes share `tenantBilling`'s
+ * authentication and resolvers.
+ */
+interface SaaSiCatPaymentsOptions extends Pick<PaymentsModuleOptions, 'gateways' | 'imports' | 'extraProviders'> {
+    /**
+     * Who of a tenant's users holds the billing permission, which the tenant's
+     * payment method routes require. Default: the tenant's administrator.
+     */
+    billingPermissionGuards?: PaymentsTenantRoutesOptions['billingPermissionGuards'];
+}
 interface SaaSiCatSubscriptionBundlesOptions extends Omit<SubscriptionBundleModuleOptions, 'subscriptionBundleRepository' | 'bundleRepository' | 'controller' | 'imports' | 'extraProviders' | 'global'> {
     /** Default mounts the tenant controller and reuses tenant-billing auth. */
     controller?: false | Omit<SubscriptionBundleControllerOptions, 'authGuards' | 'subscriptionUsagePort'>;
@@ -134,12 +173,16 @@ interface SaaSiCatSubscriptionBundlesOptions extends Omit<SubscriptionBundleModu
     extraProviders?: Provider[];
 }
 interface SaaSiCatAdminResourcesOptions extends Omit<AdminResourcesModuleOptions, 'resources' | 'guards' | 'global'> {
-    /** Override the default controller guards + `SuperAdminGuard` chain. */
+    /**
+     * Override the default controller guards + `SuperAdminGuard` chain.
+     * Suspending and reactivating a tenant require the second factor either
+     * way; that check sits on the two handlers, not in this list.
+     */
     guards?: Array<Type<CanActivate>>;
     /** Custom schema override; the persistence bundle supplies the default. */
     resources?: ProviderSpec<AdminResourcesPort>;
 }
-interface SaaSiCatPromoCodesOptions extends Omit<PromoCodesModuleOptions, 'promoCodeRepository' | 'redemptionRepository' | 'validationLogRepository' | 'subscriptionLookup' | 'revenueAggregator' | 'transactionRunner' | 'firstTimeCustomerCheck' | 'adminController' | 'global'> {
+interface SaaSiCatPromoCodesOptions extends Omit<PromoCodesModuleOptions, 'promoCodeRepository' | 'redemptionRepository' | 'validationLogRepository' | 'subscriptionLookup' | 'revenueAggregator' | 'holdRepository' | 'transactionRunner' | 'firstTimeCustomerCheck' | 'adminController' | 'global'> {
     /**
      * Required when the public preview/redeem flow is enabled. Admin-only
      * setups do not need an app-specific customer-history check.
@@ -169,53 +212,81 @@ interface SaaSiCatAdminStatsOptions extends Omit<AdminStatsModuleOptions, 'audit
  * Public checkout-offer flow. Catalog repositories default to the persistence
  * bundle, while the app still supplies its checkout-offer repository.
  */
-interface SaaSiCatCheckoutOfferOptions extends Omit<CheckoutOfferModuleOptions, 'bundleRepository' | 'planRepository' | 'catalogEntryRepository' | 'global'> {
+interface SaaSiCatCheckoutOfferOptions extends Omit<CheckoutOfferModuleOptions, 'bundleRepository' | 'planRepository' | 'promotionRepository' | 'catalogEntryRepository' | 'conclusion' | 'global'> {
     bundleRepository?: CheckoutOfferModuleOptions['bundleRepository'];
+    /**
+     * Defaults to the persistence bundle's subscription contract repository and
+     * transaction runner, so `conclude` works wherever the bundle has both.
+     */
+    conclusion?: Partial<NonNullable<CheckoutOfferModuleOptions['conclusion']>>;
+    /** Defaults to the persistence bundle's plan repository; an offer cannot be priced without one. */
     planRepository?: CheckoutOfferModuleOptions['planRepository'];
+    promotionRepository?: CheckoutOfferModuleOptions['promotionRepository'];
     catalogEntryRepository?: CheckoutOfferModuleOptions['catalogEntryRepository'];
 }
-/** Subscription-contract service, deriving its repository from persistence by default. */
-interface SaaSiCatSubscriptionContractOptions extends Omit<SubscriptionContractModuleOptions, 'subscriptionContractRepository' | 'global'> {
+/**
+ * Subscription-contract service and the subscriber service beside it, deriving
+ * both repositories from persistence by default.
+ */
+interface SaaSiCatSubscriptionContractOptions extends Omit<SubscriptionContractModuleOptions, 'subscriptionContractRepository' | 'subscriberRepository' | 'global'> {
     subscriptionContractRepository?: SubscriptionContractModuleOptions['subscriptionContractRepository'];
+    subscriberRepository?: SubscriptionContractModuleOptions['subscriberRepository'];
 }
 /**
  * What `SaaSiCatModule.forRoot()` composes.
  *
  * One subsystem is deliberately absent: **self-registration**. A prospect
- * signing themselves up — mail address, OTP, plan choice, payment, activation —
- * is `RegistrationModule` from `@saasicat/nest/registration`, and it is
- * hand-wired: ten required ports, none of which a persistence bundle supplies.
+ * signing themselves up — mail address, OTP, plan choice, payment method,
+ * activation — is `RegistrationModule` from `@saasicat/nest/registration`, and
+ * it is hand-wired: its required ports are ones no persistence bundle
+ * supplies. Its payment method is taken through `payments`, which is composed
+ * here.
  *
- * That is a decision with a reason and a plan, not an omission: the ten ports
+ * That is a decision with a reason and a plan, not an omission: those ports
  * have no executable contract yet (`@saasicat/persistence-testing` covers the
- * catalogue, subscription, promo and audit ports and none of these), and
+ * ports a persistence bundle supplies and none of these), and
  * folding unverified ports into a bundle would move the problem rather than
- * check it. See `docs/self-registration.md`.
+ * check it. See `docs/guides/self-registration.md`.
  *
  * Everything else — an operator creating tenants through the SuperAdmin UI, a
  * CLI, or your own onboarding form — is composed here.
  */
+/**
+ * The members `dbCatalog` takes. The type below is derived from this list, so
+ * the shape the platform refuses at boot and the shape the compiler accepts
+ * cannot drift apart — and `saasicat codemod v1` reads the same list.
+ */
+declare const DB_CATALOG_MEMBERS: readonly ["path", "env"];
+/**
+ * Which `config/saas.yaml` a database-held catalogue reads its settings from.
+ *
+ * The same file the quickstart path loads, read by the platform. A `plans:` or
+ * `features:` block in it is not read on this path — the sink is their source —
+ * so a file kept as the seed for `saasicat catalog import` still loads.
+ */
+type DbCatalogOptions = Pick<LoadPlanCatalogOptions, (typeof DB_CATALOG_MEMBERS)[number]>;
 interface SaaSiCatModuleOptions {
     /**
      * Plan catalog. Either as an already-loaded object (quickstart, comes
      * directly from `loadPlanCatalogFromFile('config/saas.yaml')`) or via DB
      * hydration: a sink reference in `adapters.planCatalogReadSink` /
-     * `persistence.planCatalogReadSink` **plus** the `dbCatalog` identity.
+     * `persistence.planCatalogReadSink` **plus** `dbCatalog` naming the file.
      */
     planCatalog?: PlanCatalog;
     /**
-     * App identity for the DB-hydration path — required when `planCatalog`
-     * is omitted. The read sink only loads plans/features (filtered by
-     * `projectKey`); branding, currency and VAT cannot come from the
-     * database and must be supplied here.
-     */
-    dbCatalog?: {
-        projectKey: string;
-        currency: string;
-        vatRate: number;
-        app?: PlanCatalog['app'];
-        marketing?: PlanCatalog['marketing'];
-    };
+     * The DB-hydration path — required when `planCatalog` is omitted: the
+     * `config/saas.yaml` the platform reads the settings from. The read sink
+     * loads plans and features; `app`, `currency`, `vatRate`, `tenantBilling`,
+     * `marketing` and `notifications` are not in the database and never will
+     * be, so they come from the file this names.
+     *
+     * A path rather than the values. The option used to take them as values,
+     * and every consumer forwarded them from the file it had loaded anyway —
+     * by agreement, which is a second place a setting can live. The file
+     * defines them by construction now: there is nothing here to type a
+     * setting into.
+     */
+    dbCatalog?: DbCatalogOptions;
     /**
      * Aggregate persistence bundle from an adapter package (e.g.
      * `prismaPersistence({ client: PrismaService })` from
@@ -231,13 +302,16 @@ interface SaaSiCatModuleOptions {
      */
     adapters?: SaaSiCatAdapters;
     /**
-     * Class-level guards for the platform controllers (`GET /admin/discovery`
-     * and `GET /admin/manifest`). REQUIRED — otherwise the platform throws at
-     * boot, because a manifest controller must never be silently registered
-     * without auth (platform security).
+     * The guards that establish who is calling the platform's controllers —
+     * typically `[JwtAuthGuard]`. REQUIRED: the platform does not mount an
+     * administration route whose protection nobody decided.
      *
-     * Pass `[]` explicitly if the endpoint is intentionally auth-free
-     * (CI/smoke test).
+     * Authentication only. Every operator route the platform mounts — the
+     * administration, catalogue, discovery, manifest, settings, promo codes and
+     * statistics — runs `SuperAdminGuard` after these, and the tenant manifest
+     * falls back to these guards alone, so a role check added here would lock
+     * tenants out of their own manifest. With `[]` nothing establishes a
+     * caller, and `SuperAdminGuard` refuses every operator request.
      */
     controller: {
         guards: Array<Type<CanActivate>>;
@@ -257,6 +331,19 @@ interface SaaSiCatModuleOptions {
      * app can simply override.
      */
     includeManifestController?: boolean;
+    /**
+     * Mount the platform's `GET /admin/settings` controller — the running
+     * configuration, since when it applies, and what changed between two
+     * starts. Default `true`.
+     *
+     * Set `false` when the app serves that route itself; the record is kept
+     * and compared at boot either way, only the endpoint is left out — the
+     * sidebar entry stays, since the page is shipped and the route answers. Note
+     * what the endpoint answers: the resolved settings and the absolute path of
+     * `config/saas.yaml`, behind `controller.guards` and `SuperAdminGuard` —
+     * the same chain as the manifest and discovery.
+     */
+    includeSettingsController?: boolean;
     /**
      * Modules whose providers must be visible in the DI scope (typically:
      * `AuthModule` with the `JwtAuthGuard`).
@@ -323,6 +410,13 @@ interface SaaSiCatModuleOptions {
      * `quotaProviders` unless explicitly overridden.
      */
     tenantBilling?: false | SaaSiCatTenantBillingOptions;
+    /**
+     * Payment methods through a payment gateway: the webhook route for every
+     * account in `config/saas.yaml#payments`, and — with `tenantBilling` — the
+     * tenant's payment method behind the billing permission. Self-registration
+     * takes a sign-up's payment method through it.
+     */
+    payments?: false | SaaSiCatPaymentsOptions;
     /**
      * Add-on bundle service and tenant controller. `true` uses defaults and
      * reuses tenant-billing auth/usage; an object customizes policy.
@@ -403,4 +497,4 @@ interface SaaSiCatModuleOptions {
     enforcementChainCheck?: boolean;
 }
 
-export { PLAN_RESOLVER_PORT_TOKEN as P, type SaaSiCatAdapters as S, type TenantManifestControllerOptions as T, type SaaSiCatAdminResourcesOptions as a, type SaaSiCatAdminStatsOptions as b, type SaaSiCatCatalogOptions as c, type SaaSiCatCheckoutOfferOptions as d, type SaaSiCatModuleOptions as e, type SaaSiCatPromoCodesOptions as f, type SaaSiCatSetupOptions as g, type SaaSiCatSubscriptionBundlesOptions as h, type SaaSiCatSubscriptionContractOptions as i, type SaaSiCatTenantAuthGuards as j, type SaaSiCatTenantBillingOptions as k, SetupModule as l, type SetupModuleOptions as m, StaticPlanResolver as n, type PlanResolverPort as o, buildTenantManifestController as p };
+export { DB_CATALOG_MEMBERS as D, PLAN_RESOLVER_PORT_TOKEN as P, type SaaSiCatAdapters as S, type TenantManifestControllerOptions as T, StaticPlanResolver as a, type PlanResolverPort as b, type SaaSiCatModuleOptions as c, type SaaSiCatAdminResourcesOptions as d, type SaaSiCatAdminStatsOptions as e, type SaaSiCatCatalogOptions as f, type SaaSiCatCheckoutOfferOptions as g, type SaaSiCatPromoCodesOptions as h, type SaaSiCatSetupOptions as i, type SaaSiCatSubscriptionBundlesOptions as j, type SaaSiCatSubscriptionContractOptions as k, type SaaSiCatTenantAuthGuards as l, type SaaSiCatTenantBillingOptions as m, SetupModule as n, type SetupModuleOptions as o, type DbCatalogOptions as p, buildTenantManifestController as q };