@saasicat/nest 0.7.0 → 0.9.0

package/dist/subscription-bundles.module-DCpV-Pb5.d.cts

@@ -0,0 +1,291 @@
+import { CanActivate, Type, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
+import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
+import { NewContractLineItemData, BillingCycle, SubscriptionUsagePort, UsageSnapshotPort, TenantSubscriptionWritePort, SubscriptionContractRepository, SubscriptionBundleRepository, BundleRepository } from '@saasicat/types';
+
+/**
+ * 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[]>;
+}
+
+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;
+
+/**
+ * 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>;
+}
+
+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[];
+    /** 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;
+}
+
+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;
+}
+
+export { AUDIT_CONTEXT_RESOLVER_TOKEN as A, type UserIdResolver as B, CONTRACT_FREEZE_PORT_TOKEN as C, type DuePendingPlanChange as D, PENDING_PLAN_QUERY_PORT_TOKEN as P, SELF_SERVICE_BLOCKED_BUNDLES_TOKEN as S, TENANT_AUTH_GUARDS_TOKEN as T, USAGE_SNAPSHOT_PORT_TOKEN as U, type AuditContextResolver as a, type AuthGuardList as b, CONTRACT_FREEZE_PROJECT_KEY_TOKEN as c, CONTRACT_FREEZE_SOURCE_PORT_TOKEN as d, type ContractFreezeBundleSnapshot as e, type ContractFreezePort as f, type ContractFreezeSourcePort as g, type PendingPlanQueryPort as h, SELF_SERVICE_BLOCKED_PLANS_TOKEN as i, SUBSCRIPTION_USAGE_PORT_TOKEN as j, SUBSCRIPTION_WRITE_PORT_TOKEN as k, type SelfServiceBlockedBundles as l, type SelfServiceBlockedPlans as m, type SubscriptionBundleControllerOptions as n, SubscriptionBundleModule as o, type SubscriptionBundleModuleOptions as p, TENANT_ID_RESOLVER_TOKEN as q, TRIAL_PROJECTION_PORT_TOKEN as r, TenantBillingModule as s, type TenantBillingModuleOptions as t, type TenantIdResolver as u, type TrialProjectionInput as v, type TrialProjectionPort as w, USER_EMAIL_RESOLVER_TOKEN as x, USER_ID_RESOLVER_TOKEN as y, type UserEmailResolver as z };