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

package/dist/tenant-billing.module-ClbjzocC.d.cts

@@ -0,0 +1,364 @@
+import { PlanCatalog, BillingCycle, PlanVersionRow, SubscriptionUsagePort, SubscriptionBundleRepository, BundleRepository, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriberRepository } from '@saasicat/core';
+import { Type, CanActivate, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
+import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
+import { T as TenantIdResolver, a as TrialProjectionPort, P as PendingPlanQueryPort, b as UserIdResolver, U as UserEmailResolver, A as AuditContextResolver } from './tenant-billing.tokens-G-1xOlMr.cjs';
+import { P as PricedContractLineItem } from './contract-line-item-money-B0Z3Ogur.cjs';
+
+declare const FEATURE_GUARD_MARKER: unique symbol;
+/** A guard class or instance carrying the platform's marker. */
+interface MarkedFeatureGuard {
+    [FEATURE_GUARD_MARKER]: true;
+}
+/** True when `target` is one of the platform's entitlement guards. */
+declare function isPlatformFeatureGuard(target: unknown): boolean;
+
+/**
+ * The variables a document may refer to; `process.env` in production.
+ *
+ * `null` means there is no environment to resolve against, and every reference
+ * is then refused. That is the case for a document that did not come from the
+ * installation's own file — an upload through the catalogue import — because
+ * resolving `${DATABASE_URL}` for whoever posts a YAML body would hand them the
+ * server's environment one variable at a time.
+ */
+type EnvironmentVariables = Readonly<Record<string, string | undefined>> | null;
+
+/**
+ * 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;
+    /** `envVar` names the variable behind a reference that could not be resolved. */
+    params?: {
+        missingProperty?: string;
+        additionalProperty?: string;
+        envVar?: string;
+    };
+}
+/**
+ * `Error.name` for a document that could not be read as a catalog at all.
+ *
+ * A name rather than a class because the other failure of this kind comes from
+ * the YAML parser and is not ours to subclass — one predicate has to cover
+ * both, and a name is what both can carry.
+ */
+declare const PLAN_CATALOG_UNREADABLE_ERROR = "PlanCatalogUnreadableError";
+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;
+    /**
+     * The variables a `${NAME}` in the file may resolve against. Left out,
+     * `process.env`; a record of their own for tests; `null` to refuse every
+     * reference, the way the string variant does without one.
+     */
+    env?: EnvironmentVariables;
+}
+interface LoadPlanCatalogFromStringOptions {
+    /** Names the document in error messages — a path, or where the text came from. */
+    source: string;
+    crossFieldChecks?: boolean;
+    /**
+     * The variables a `${NAME}` in the document may resolve against.
+     *
+     * Left out, every reference is refused: a document handed in as text did
+     * not come from the installation's own file, and the catalogue import is
+     * one such caller. Resolving references for an uploaded body would read
+     * the server's environment for whoever can post one.
+     */
+    env?: EnvironmentVariables;
+}
+/**
+ * Loads + validates a saas.yaml file.
+ *
+ * Throws `PlanCatalogValidationError` on schema violations, cross-field
+ * violations, and references the environment cannot satisfy. Throws `Error`
+ * on IO/YAML parse errors.
+ */
+declare function loadPlanCatalogFromFile(opts: LoadPlanCatalogOptions): PlanCatalog;
+/**
+ * The absolute path `loadPlanCatalogFromFile` read `catalog` from, or null for
+ * a catalogue assembled in code — or copied: a spread of the loaded object is
+ * a new object, and this cannot follow it.
+ */
+declare function catalogSource(catalog: PlanCatalog): string | null;
+/**
+ * Variant for tests / in-memory loading: takes YAML content as a string,
+ * `source` is only for error logging.
+ */
+declare function loadPlanCatalogFromString(yamlContent: string, opts: LoadPlanCatalogFromStringOptions): PlanCatalog;
+
+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;
+
+/**
+ * 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;
+interface ContractFreezePort {
+    /**
+     * Refuses, with `SUBSCRIBER_REQUIRED`, a tenant that has no subscriber.
+     *
+     * A frozen contract names the party it is concluded with, and a freeze
+     * runs after the change that asks for it — a plan change already written,
+     * an add-on already booked. Asked first, the change is refused while
+     * nothing has moved; asked only by the freeze, the tenant would be on the
+     * new plan with the old contract still in force.
+     */
+    assertPartyFor(tenantId: string): Promise<void>;
+    /**
+     * 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, 
+    /**
+     * When the subscription ends, or null while it runs on.
+     *
+     * A contract cannot outlive the subscription it froze, and a freeze
+     * happens AFTER a cancellation as well: a plan change on a cancelled
+     * subscription is allowed, and each one supersedes the capped contract
+     * with a fresh one. Without this the replacement is uncapped and the
+     * ending is lost — repaired once at the cancellation, undone by the
+     * next change.
+     */
+    endsAt: Date | null): Promise<void>;
+    /**
+     * Ends the active contract at `effectiveAt`, with no successor.
+     *
+     * A frozen contract is the agreed service, and it cannot outlive the
+     * subscription that agreed to it. Without this the tenant's entitlements
+     * end on the date while the invoice side goes on reading an active
+     * agreement — two answers to "is this customer under contract", and the
+     * one that bills says yes.
+     *
+     * Same mechanic as the supersession above and deliberately not the same
+     * call: there is nothing to succeed it with.
+     */
+    endOnCancellation(tenantId: string, effectiveAt: Date): Promise<void>;
+}
+/** Frozen bundle line items + their version ids (trace). */
+interface ContractFreezeBundleSnapshot {
+    /**
+     * Priced in net, and nothing more — the platform records the gross, the
+     * currency and the tax rate, so a source never restates a setting it does
+     * not own, and every line of the contract carries its share of one tax
+     * computation rather than a rounding of its own.
+     */
+    lineItems: PricedContractLineItem[];
+    bundleVersionIds: string[];
+}
+/**
+ * Consumer-specific data access for the freeze: the plan version the tenant's
+ * subscription is bound to + booked bundles as contract line items. The generic
+ * freeze logic (plan line item, snapshot, contract assembly) lives in the
+ * platform `SubscriptionContractFreezeService`.
+ */
+interface ContractFreezeSourcePort {
+    /**
+     * The plan version the tenant's subscription is bound to — the row its
+     * `planVersionId` points at, whether or not a newer one is on sale — or
+     * `null` when the tenant has no subscription.
+     *
+     * The contract records this version's price, features and quotas. Not the
+     * version on sale now: a tenant who books an add-on after the operator
+     * published a successor keeps the version they bought (`SC-SUB-012`), and
+     * after a plan change the write has already bound the version it sold.
+     */
+    findBoundPlanVersion(tenantId: string): Promise<PlanVersionRow | null>;
+    /**
+     * The tenant's active (non-terminated) bundle bookings as line items,
+     * priced in net. Apps without a bundle schema return empty lists.
+     *
+     * `cycle` is the **plan's** rhythm, not the bookings'. A tenant on a yearly
+     * plan may hold monthly add-ons, so a source prices each booking in the
+     * rhythm that booking was made in and says which one that is on the line's
+     * own `billingCycle`. Pricing every line in the plan's rhythm puts a figure
+     * on the contract that nobody is charged, and the contract is the evidence
+     * of what was agreed.
+     */
+    loadBookedBundles(tenantId: string, cycle: 'monthly' | 'yearly'): Promise<ContractFreezeBundleSnapshot>;
+}
+
+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 = **0** — no commitment, so an
+     * add-on can be cancelled to its own period end. Set one to bind.
+     */
+    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;
+}
+
+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 for the tenant's bundle bookings.
+     *
+     * The plan-change preview reads it for one rule: a bundle may run in a
+     * shorter rhythm than its plan, never a longer one, so a move to a shorter
+     * cycle is refused while an add-on with a longer one is still active.
+     * `SubscriptionBundleModule` exports the same token, but it is a sibling
+     * import rather than an ancestor — its exports do not reach this module's
+     * providers, so without this option the rule resolves to "no bookings" and
+     * silently allows the move it exists to prevent.
+     */
+    subscriptionBundleRepository?: ProviderSpec<SubscriptionBundleRepository>;
+    /**
+     * 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 is only the
+     * 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?: {
+        sourcePort: ProviderSpec<ContractFreezeSourcePort>;
+        subscriptionContractRepository: ProviderSpec<SubscriptionContractRepository>;
+        /**
+         * The parties a frozen contract is between. A plan change or a booking
+         * for a tenant without a subscriber is refused before anything changes.
+         */
+        subscriberRepository: ProviderSpec<SubscriberRepository>;
+    };
+    /** 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[];
+    /** Additional providers this module makes visible to importing modules. */
+    extraExports?: NonNullable<DynamicModule['exports']>;
+    /** Register the module globally — default `false`. */
+    global?: boolean;
+}
+declare class TenantBillingModule {
+    static forRoot(options: TenantBillingModuleOptions): DynamicModule;
+}
+
+export { type AjvErrorLike as A, CONTRACT_FREEZE_PORT_TOKEN as C, type EnvironmentVariables as E, FEATURE_GUARD_MARKER as F, type LoadPlanCatalogOptions as L, type MarkedFeatureGuard as M, PLAN_CATALOG_UNREADABLE_ERROR as P, type SubscriptionBundleModuleOptions as S, type TenantBillingModuleOptions as T, type SubscriptionBundleControllerOptions as a, CONTRACT_FREEZE_SOURCE_PORT_TOKEN as b, type ContractFreezeBundleSnapshot as c, type ContractFreezePort as d, type ContractFreezeSourcePort as e, type LoadPlanCatalogFromStringOptions as f, PlanCatalogValidationError as g, SELF_SERVICE_BLOCKED_BUNDLES_TOKEN as h, SELF_SERVICE_BLOCKED_PLANS_TOKEN as i, type SelfServiceBlockedBundles as j, SubscriptionBundleModule as k, TenantBillingModule as l, catalogSource as m, isPlatformFeatureGuard as n, loadPlanCatalogFromFile as o, loadPlanCatalogFromString as p };