@saasicat/nest 0.2.0

package/dist/saas-platform.module-CgZ2omgg.d.cts

@@ -0,0 +1,180 @@
+import { Type, CanActivate, DynamicModule, ForwardReference, FactoryProvider } from '@nestjs/common';
+import { MfaPort, AuditPort, RlsBypassPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, PlanCatalog, QuotaProvider } from '@saasicat/types';
+import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
+import { A as AdminManifestConfig } from './admin-manifest.config-DyrQNT7M.cjs';
+import { D as DiscoveryAppInfo } from './discovery.scanner-CUYLKlYT.cjs';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CFCoUkrE.cjs';
+
+declare const PLAN_RESOLVER_PORT_TOKEN: unique symbol;
+interface PlanResolverPort {
+    /**
+     * Returns the tenant's active `planId`. `null` = no plan assigned →
+     * the guard / interceptor throws 403 or lets it through, depending on
+     * the configuration.
+     */
+    getPlanIdForTenant(tenantId: string): Promise<string | null>;
+}
+/**
+ * Static fallback: always returns the same plan for all tenants. Useful
+ * for local development and for apps that do not yet have a contract concept.
+ *
+ * The quickstart path uses this implicitly when `adapters.planResolver` is
+ * not set and `defaultPlanId` was provided in SaasPlatformModule.forRoot().
+ */
+declare class StaticPlanResolver implements PlanResolverPort {
+    private readonly planId;
+    constructor(planId: string);
+    getPlanIdForTenant(): Promise<string | null>;
+}
+
+interface TenantManifestControllerOptions {
+    path?: string;
+    guards: Array<Type<CanActivate>>;
+}
+/**
+ * Creates a controller class that maps `GET <path>` to
+ * `TenantManifestService.getManifest(tenantId)`. `tenantId` comes from
+ * `request.user.tenantId` (default — matches the JwtAuthGuard pattern of
+ * most apps) or from `request.tenantId`.
+ *
+ * Route path: default `tenant/manifest`. Apps with a globalPrefix `/api/v1`
+ * thus get `/api/v1/tenant/manifest`.
+ */
+declare function buildTenantManifestController(options: TenantManifestControllerOptions): Type<unknown>;
+
+/**
+ * Adapter bindings for the platform ports. Accepted as class tokens, values
+ * or factory specs.
+ */
+interface SaasPlatformAdapters {
+    mfa: ProviderSpec<MfaPort>;
+    audit: ProviderSpec<AuditPort>;
+    rlsBypass: ProviderSpec<RlsBypassPort>;
+    /**
+     * Optional. If provided, `PlanCatalogModule` is hydrated from this sink
+     * (DB read at boot). If omitted, `planCatalog` MUST be passed as a ready
+     * object (quickstart path — YAML-direct).
+     */
+    planCatalogReadSink?: ProviderSpec<PlanCatalogReadSink>;
+    /**
+     * Optional — resolver `tenantId → planId`. The quickstart path uses this
+     * together with the `StaticEntitlementService` to automatically check
+     * `@RequireFeature` and `@EnforceQuota` against the plan catalog limit.
+     * If not set, `defaultPlanId` **must** be provided — a `StaticPlanResolver`
+     * then returns the same plan for all tenants.
+     */
+    planResolver?: ProviderSpec<PlanResolverPort>;
+    /**
+     * Optional — required only when `entitlement: true`. Repositories for the
+     * V3 contract/entitlement loop.
+     */
+    subscriptionRepository?: ProviderSpec<SubscriptionRepository>;
+    planVersionRepository?: ProviderSpec<PlanVersionRepository>;
+    transactionRunner?: ProviderSpec<TransactionRunner>;
+}
+interface SaasPlatformModuleOptions {
+    /**
+     * Plan catalog. Either as an already-loaded object (quickstart, comes
+     * directly from `loadPlanCatalogFromFile('config/saas.yaml')`) or as a
+     * sink reference in `adapters.planCatalogReadSink` for DB hydration.
+     */
+    planCatalog?: PlanCatalog;
+    /**
+     * Adapter bindings.
+     */
+    adapters: SaasPlatformAdapters;
+    /**
+     * 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).
+     *
+     * Pass `[]` explicitly if the endpoint is intentionally auth-free
+     * (CI/smoke test).
+     */
+    controller: {
+        guards: Array<Type<CanActivate>>;
+    };
+    /**
+     * Additional guards only for `POST /admin/manifest/reload` (typically:
+     * `MfaGuard`). Optional.
+     */
+    reloadGuards?: Array<Type<CanActivate>>;
+    /**
+     * Modules whose providers must be visible in the DI scope (typically:
+     * `AuthModule` with the `JwtAuthGuard`).
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * App identity for the DiscoveryScanner. If omitted, `planCatalog.app` is
+     * used (recommendation: simply declare it in the YAML).
+     */
+    app?: DiscoveryAppInfo;
+    /**
+     * Optional — snapshot path for the DiscoveryScanner. Default:
+     * `var/discovery-snapshot.json`. `null` to disable.
+     */
+    discoverySnapshotPath?: string | null;
+    /**
+     * `AdminManifestConfig`. If omitted, the module assembles a minimal variant
+     * from `planCatalog` — good for quickstart, but for full manifest features
+     * (build hash, locales, KPI cards) the consumer should provide its own
+     * factory.
+     */
+    adminManifestConfig?: AdminManifestConfig | Pick<FactoryProvider<AdminManifestConfig>, 'useFactory' | 'inject'>;
+    /**
+     * Default `false`. If `true`, `EntitlementModule.forRoot({...})` is called
+     * with the repositories from `adapters` — only meaningful if the app
+     * implements the V3 contract path (`subscriptionRepository` & co. must then
+     * be set).
+     */
+    entitlement?: false | {
+        resolutionConfig?: EntitlementResolutionConfig;
+    };
+    /**
+     * Fallback plan ID for the `StaticPlanResolver`. If neither
+     * `adapters.planResolver` nor `defaultPlanId` is set, the
+     * `StaticEntitlementService` is not activated — `@RequireFeature`/
+     * `@EnforceQuota` are then **ineffective** (discovery markup with no
+     * runtime effect). Platform warning at boot.
+     */
+    defaultPlanId?: string;
+    /**
+     * QuotaProvider classes declared with `@DefinesQuota({...})` that the
+     * `EnforceQuotaInterceptor` must use for count calculation. The platform
+     * registers them as app providers and collects them in
+     * `QUOTA_PROVIDERS_TOKEN`.
+     */
+    quotaProviders?: Array<Type<QuotaProvider>>;
+    /**
+     * Enable the tenant manifest — the app UI gets a filtered manifest per
+     * tenant with features, quotas and visible navigation. Requires that
+     * `defaultPlanId` or `adapters.planResolver` is set.
+     */
+    tenantManifest?: TenantManifestControllerOptions;
+}
+/**
+ * Bundles PlanCatalog + Discovery + Admin + AdminManifest (+ optionally
+ * Entitlement) into a single `forRoot({...})` call. Reduces AppModule
+ * boilerplate and eliminates the ordering trap.
+ *
+ * Quickstart path:
+ *
+ * ```ts
+ * SaasPlatformModule.forRoot({
+ *     planCatalog: loadPlanCatalogFromFile({ path: 'config/saas.yaml' }),
+ *     controller: { guards: [JwtAuthGuard] },
+ *     imports: [AuthModule],
+ *     adapters: {
+ *         mfa: PrismaMfaAdapter,           // from @saasicat/prisma
+ *         audit: PrismaAuditAdapter,
+ *         rlsBypass: AsyncLocalRlsBypassAdapter,
+ *     },
+ * })
+ * ```
+ */
+declare class SaasPlatformModule {
+    static forRoot(options: SaasPlatformModuleOptions): DynamicModule;
+}
+
+export { type PlanResolverPort as P, type SaasPlatformModuleOptions as S, type TenantManifestControllerOptions as T, PLAN_RESOLVER_PORT_TOKEN as a, type SaasPlatformAdapters as b, SaasPlatformModule as c, StaticPlanResolver as d, buildTenantManifestController as e };

package/dist/saas-platform.module-DT9TnCzk.d.ts

@@ -0,0 +1,180 @@
+import { Type, CanActivate, DynamicModule, ForwardReference, FactoryProvider } from '@nestjs/common';
+import { MfaPort, AuditPort, RlsBypassPort, PlanCatalogReadSink, SubscriptionRepository, PlanVersionRepository, TransactionRunner, PlanCatalog, QuotaProvider } from '@saasicat/types';
+import { P as ProviderSpec } from './di-CcNeq9v-.js';
+import { A as AdminManifestConfig } from './admin-manifest.config-DyrQNT7M.js';
+import { D as DiscoveryAppInfo } from './discovery.scanner-CUYLKlYT.js';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CFCoUkrE.js';
+
+declare const PLAN_RESOLVER_PORT_TOKEN: unique symbol;
+interface PlanResolverPort {
+    /**
+     * Returns the tenant's active `planId`. `null` = no plan assigned →
+     * the guard / interceptor throws 403 or lets it through, depending on
+     * the configuration.
+     */
+    getPlanIdForTenant(tenantId: string): Promise<string | null>;
+}
+/**
+ * Static fallback: always returns the same plan for all tenants. Useful
+ * for local development and for apps that do not yet have a contract concept.
+ *
+ * The quickstart path uses this implicitly when `adapters.planResolver` is
+ * not set and `defaultPlanId` was provided in SaasPlatformModule.forRoot().
+ */
+declare class StaticPlanResolver implements PlanResolverPort {
+    private readonly planId;
+    constructor(planId: string);
+    getPlanIdForTenant(): Promise<string | null>;
+}
+
+interface TenantManifestControllerOptions {
+    path?: string;
+    guards: Array<Type<CanActivate>>;
+}
+/**
+ * Creates a controller class that maps `GET <path>` to
+ * `TenantManifestService.getManifest(tenantId)`. `tenantId` comes from
+ * `request.user.tenantId` (default — matches the JwtAuthGuard pattern of
+ * most apps) or from `request.tenantId`.
+ *
+ * Route path: default `tenant/manifest`. Apps with a globalPrefix `/api/v1`
+ * thus get `/api/v1/tenant/manifest`.
+ */
+declare function buildTenantManifestController(options: TenantManifestControllerOptions): Type<unknown>;
+
+/**
+ * Adapter bindings for the platform ports. Accepted as class tokens, values
+ * or factory specs.
+ */
+interface SaasPlatformAdapters {
+    mfa: ProviderSpec<MfaPort>;
+    audit: ProviderSpec<AuditPort>;
+    rlsBypass: ProviderSpec<RlsBypassPort>;
+    /**
+     * Optional. If provided, `PlanCatalogModule` is hydrated from this sink
+     * (DB read at boot). If omitted, `planCatalog` MUST be passed as a ready
+     * object (quickstart path — YAML-direct).
+     */
+    planCatalogReadSink?: ProviderSpec<PlanCatalogReadSink>;
+    /**
+     * Optional — resolver `tenantId → planId`. The quickstart path uses this
+     * together with the `StaticEntitlementService` to automatically check
+     * `@RequireFeature` and `@EnforceQuota` against the plan catalog limit.
+     * If not set, `defaultPlanId` **must** be provided — a `StaticPlanResolver`
+     * then returns the same plan for all tenants.
+     */
+    planResolver?: ProviderSpec<PlanResolverPort>;
+    /**
+     * Optional — required only when `entitlement: true`. Repositories for the
+     * V3 contract/entitlement loop.
+     */
+    subscriptionRepository?: ProviderSpec<SubscriptionRepository>;
+    planVersionRepository?: ProviderSpec<PlanVersionRepository>;
+    transactionRunner?: ProviderSpec<TransactionRunner>;
+}
+interface SaasPlatformModuleOptions {
+    /**
+     * Plan catalog. Either as an already-loaded object (quickstart, comes
+     * directly from `loadPlanCatalogFromFile('config/saas.yaml')`) or as a
+     * sink reference in `adapters.planCatalogReadSink` for DB hydration.
+     */
+    planCatalog?: PlanCatalog;
+    /**
+     * Adapter bindings.
+     */
+    adapters: SaasPlatformAdapters;
+    /**
+     * 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).
+     *
+     * Pass `[]` explicitly if the endpoint is intentionally auth-free
+     * (CI/smoke test).
+     */
+    controller: {
+        guards: Array<Type<CanActivate>>;
+    };
+    /**
+     * Additional guards only for `POST /admin/manifest/reload` (typically:
+     * `MfaGuard`). Optional.
+     */
+    reloadGuards?: Array<Type<CanActivate>>;
+    /**
+     * Modules whose providers must be visible in the DI scope (typically:
+     * `AuthModule` with the `JwtAuthGuard`).
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * App identity for the DiscoveryScanner. If omitted, `planCatalog.app` is
+     * used (recommendation: simply declare it in the YAML).
+     */
+    app?: DiscoveryAppInfo;
+    /**
+     * Optional — snapshot path for the DiscoveryScanner. Default:
+     * `var/discovery-snapshot.json`. `null` to disable.
+     */
+    discoverySnapshotPath?: string | null;
+    /**
+     * `AdminManifestConfig`. If omitted, the module assembles a minimal variant
+     * from `planCatalog` — good for quickstart, but for full manifest features
+     * (build hash, locales, KPI cards) the consumer should provide its own
+     * factory.
+     */
+    adminManifestConfig?: AdminManifestConfig | Pick<FactoryProvider<AdminManifestConfig>, 'useFactory' | 'inject'>;
+    /**
+     * Default `false`. If `true`, `EntitlementModule.forRoot({...})` is called
+     * with the repositories from `adapters` — only meaningful if the app
+     * implements the V3 contract path (`subscriptionRepository` & co. must then
+     * be set).
+     */
+    entitlement?: false | {
+        resolutionConfig?: EntitlementResolutionConfig;
+    };
+    /**
+     * Fallback plan ID for the `StaticPlanResolver`. If neither
+     * `adapters.planResolver` nor `defaultPlanId` is set, the
+     * `StaticEntitlementService` is not activated — `@RequireFeature`/
+     * `@EnforceQuota` are then **ineffective** (discovery markup with no
+     * runtime effect). Platform warning at boot.
+     */
+    defaultPlanId?: string;
+    /**
+     * QuotaProvider classes declared with `@DefinesQuota({...})` that the
+     * `EnforceQuotaInterceptor` must use for count calculation. The platform
+     * registers them as app providers and collects them in
+     * `QUOTA_PROVIDERS_TOKEN`.
+     */
+    quotaProviders?: Array<Type<QuotaProvider>>;
+    /**
+     * Enable the tenant manifest — the app UI gets a filtered manifest per
+     * tenant with features, quotas and visible navigation. Requires that
+     * `defaultPlanId` or `adapters.planResolver` is set.
+     */
+    tenantManifest?: TenantManifestControllerOptions;
+}
+/**
+ * Bundles PlanCatalog + Discovery + Admin + AdminManifest (+ optionally
+ * Entitlement) into a single `forRoot({...})` call. Reduces AppModule
+ * boilerplate and eliminates the ordering trap.
+ *
+ * Quickstart path:
+ *
+ * ```ts
+ * SaasPlatformModule.forRoot({
+ *     planCatalog: loadPlanCatalogFromFile({ path: 'config/saas.yaml' }),
+ *     controller: { guards: [JwtAuthGuard] },
+ *     imports: [AuthModule],
+ *     adapters: {
+ *         mfa: PrismaMfaAdapter,           // from @saasicat/prisma
+ *         audit: PrismaAuditAdapter,
+ *         rlsBypass: AsyncLocalRlsBypassAdapter,
+ *     },
+ * })
+ * ```
+ */
+declare class SaasPlatformModule {
+    static forRoot(options: SaasPlatformModuleOptions): DynamicModule;
+}
+
+export { type PlanResolverPort as P, type SaasPlatformModuleOptions as S, type TenantManifestControllerOptions as T, PLAN_RESOLVER_PORT_TOKEN as a, type SaasPlatformAdapters as b, SaasPlatformModule as c, StaticPlanResolver as d, buildTenantManifestController as e };

package/dist/service-DX8KbGXl.d.cts

@@ -0,0 +1,109 @@
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PlanCatalog, CreatePromoCodeData, PromoCodeRecord, UpdatePromoCodeData, PromoCodeFilter, PromoCodeRedemptionListItem, BillingCycle, PromoCodeRedemptionRecord, TransactionContext } from '@saasicat/types';
+
+type PreviewReason = 'NOT_FOUND' | 'EXPIRED' | 'EXHAUSTED' | 'PAUSED' | 'PLAN_MISMATCH' | 'BILLING_MISMATCH' | 'BELOW_MINIMUM_AMOUNT' | 'WOULD_PRODUCE_ZERO_INVOICE' | 'NOT_FIRST_TIME_CUSTOMER' | 'RATE_LIMITED';
+type PreviewInvalid = {
+    valid: false;
+    reason: PreviewReason;
+};
+interface PreviewValid {
+    valid: true;
+    code: string;
+    label: string;
+    discount: {
+        valueType: PromoCodeRecord['valueType'];
+        value: string;
+        durationType: PromoCodeRecord['durationType'];
+        durationValue: number | null;
+    };
+    price: {
+        originalGross: string;
+        discountGross: string;
+        discountedGross: string;
+        includedVat: string;
+        nextRegularAmountGross: string;
+        regularStartsAt: string | null;
+    };
+}
+type PreviewResult = PreviewValid | PreviewInvalid;
+interface PreviewInput {
+    code: string;
+    planId: string;
+    billingCycle: BillingCycle;
+    /** For the firstTimeCustomersOnly check. */
+    email?: string;
+    ipHash?: string;
+    sessionId?: string;
+}
+interface RedeemInput {
+    code: string;
+    subscriptionId: string;
+    tenantId: string;
+    /** For the firstTimeCustomersOnly check in the final redeem path. */
+    email?: string;
+}
+interface PromoServiceConfig {
+    /** Plans that are not discountable (e.g. 'ENTERPRISE'). */
+    nonRedeemablePlans?: readonly string[];
+}
+interface PromoCodeStats {
+    code: PromoCodeRecord;
+    validations: number;
+    redemptions: {
+        active: number;
+        total: number;
+        reversed: number;
+        expired: number;
+    };
+    /** Decimal-as-string ('0.00' if no aggregator is available). */
+    revenueDeductionGross: string;
+}
+declare class PromoCodesService {
+    private readonly promoRepo;
+    private readonly redemptionRepo;
+    private readonly validationLogRepo;
+    private readonly firstTimeCheck;
+    private readonly subscriptionLookup;
+    private readonly revenueAggregator;
+    private readonly transactionRunner;
+    private readonly planCatalog;
+    private readonly config;
+    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository, validationLogRepo: PromoCodeValidationLogRepository, firstTimeCheck: FirstTimeCustomerCheck, subscriptionLookup: PromoSubscriptionLookup, revenueAggregator: PromoRevenueDeductionAggregator, transactionRunner: TransactionRunner, planCatalog: PlanCatalog, config: PromoServiceConfig);
+    create(input: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    update(id: string, input: UpdatePromoCodeData): Promise<PromoCodeRecord>;
+    softDelete(id: string): Promise<void>;
+    findAll(filter?: PromoCodeFilter): Promise<PromoCodeRecord[]>;
+    findOne(id: string): Promise<PromoCodeRecord>;
+    stats(id: string): Promise<PromoCodeStats>;
+    listRedemptions(promoCodeId: string): Promise<PromoCodeRedemptionListItem[]>;
+    preview(input: PreviewInput): Promise<PreviewResult>;
+    /**
+     * Wraps `redeemInTransaction` in its own transaction-runner call —
+     * the default path when the caller has no external tx context
+     * (e.g. POST /billing/promo/redeem as a stand-alone endpoint).
+     */
+    redeem(input: RedeemInput): Promise<PromoCodeRedemptionRecord>;
+    /**
+     * Redeems a promo code within an EXTERNAL transaction — the caller
+     * (typically `TenantSubscriptionWritePort.applyOnboardingSelection`)
+     * already has `prisma.$transaction(...)` open and passes the `tx`
+     * context through. This lands plan change, add-on insert, and redemption
+     * insert in a single DB transaction (P10.1.1).
+     */
+    redeemInTransaction(input: RedeemInput, tx: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    reverse(subscriptionId: string): Promise<PromoCodeRedemptionRecord | null>;
+    private checkEligibility;
+    private checkFirstTimeCustomer;
+    /**
+     * Lazy expiry: sets codes whose validUntil has passed to EXPIRED.
+     * Called before every find/preview — defense-in-depth alongside the cron.
+     */
+    private lazyExpire;
+    /**
+     * Lowest applicable plan price. With a whitelist it takes the minimum
+     * from the whitelist, otherwise across all marketed plans of the catalog
+     * (except non-redeemable).
+     */
+    private lowestApplicablePlanGross;
+}
+
+export { type PreviewInput as P, type RedeemInput as R, type PreviewInvalid as a, type PreviewReason as b, type PreviewResult as c, type PreviewValid as d, type PromoCodeStats as e, PromoCodesService as f, type PromoServiceConfig as g };

package/dist/service-DX8KbGXl.d.ts

@@ -0,0 +1,109 @@
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PlanCatalog, CreatePromoCodeData, PromoCodeRecord, UpdatePromoCodeData, PromoCodeFilter, PromoCodeRedemptionListItem, BillingCycle, PromoCodeRedemptionRecord, TransactionContext } from '@saasicat/types';
+
+type PreviewReason = 'NOT_FOUND' | 'EXPIRED' | 'EXHAUSTED' | 'PAUSED' | 'PLAN_MISMATCH' | 'BILLING_MISMATCH' | 'BELOW_MINIMUM_AMOUNT' | 'WOULD_PRODUCE_ZERO_INVOICE' | 'NOT_FIRST_TIME_CUSTOMER' | 'RATE_LIMITED';
+type PreviewInvalid = {
+    valid: false;
+    reason: PreviewReason;
+};
+interface PreviewValid {
+    valid: true;
+    code: string;
+    label: string;
+    discount: {
+        valueType: PromoCodeRecord['valueType'];
+        value: string;
+        durationType: PromoCodeRecord['durationType'];
+        durationValue: number | null;
+    };
+    price: {
+        originalGross: string;
+        discountGross: string;
+        discountedGross: string;
+        includedVat: string;
+        nextRegularAmountGross: string;
+        regularStartsAt: string | null;
+    };
+}
+type PreviewResult = PreviewValid | PreviewInvalid;
+interface PreviewInput {
+    code: string;
+    planId: string;
+    billingCycle: BillingCycle;
+    /** For the firstTimeCustomersOnly check. */
+    email?: string;
+    ipHash?: string;
+    sessionId?: string;
+}
+interface RedeemInput {
+    code: string;
+    subscriptionId: string;
+    tenantId: string;
+    /** For the firstTimeCustomersOnly check in the final redeem path. */
+    email?: string;
+}
+interface PromoServiceConfig {
+    /** Plans that are not discountable (e.g. 'ENTERPRISE'). */
+    nonRedeemablePlans?: readonly string[];
+}
+interface PromoCodeStats {
+    code: PromoCodeRecord;
+    validations: number;
+    redemptions: {
+        active: number;
+        total: number;
+        reversed: number;
+        expired: number;
+    };
+    /** Decimal-as-string ('0.00' if no aggregator is available). */
+    revenueDeductionGross: string;
+}
+declare class PromoCodesService {
+    private readonly promoRepo;
+    private readonly redemptionRepo;
+    private readonly validationLogRepo;
+    private readonly firstTimeCheck;
+    private readonly subscriptionLookup;
+    private readonly revenueAggregator;
+    private readonly transactionRunner;
+    private readonly planCatalog;
+    private readonly config;
+    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository, validationLogRepo: PromoCodeValidationLogRepository, firstTimeCheck: FirstTimeCustomerCheck, subscriptionLookup: PromoSubscriptionLookup, revenueAggregator: PromoRevenueDeductionAggregator, transactionRunner: TransactionRunner, planCatalog: PlanCatalog, config: PromoServiceConfig);
+    create(input: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    update(id: string, input: UpdatePromoCodeData): Promise<PromoCodeRecord>;
+    softDelete(id: string): Promise<void>;
+    findAll(filter?: PromoCodeFilter): Promise<PromoCodeRecord[]>;
+    findOne(id: string): Promise<PromoCodeRecord>;
+    stats(id: string): Promise<PromoCodeStats>;
+    listRedemptions(promoCodeId: string): Promise<PromoCodeRedemptionListItem[]>;
+    preview(input: PreviewInput): Promise<PreviewResult>;
+    /**
+     * Wraps `redeemInTransaction` in its own transaction-runner call —
+     * the default path when the caller has no external tx context
+     * (e.g. POST /billing/promo/redeem as a stand-alone endpoint).
+     */
+    redeem(input: RedeemInput): Promise<PromoCodeRedemptionRecord>;
+    /**
+     * Redeems a promo code within an EXTERNAL transaction — the caller
+     * (typically `TenantSubscriptionWritePort.applyOnboardingSelection`)
+     * already has `prisma.$transaction(...)` open and passes the `tx`
+     * context through. This lands plan change, add-on insert, and redemption
+     * insert in a single DB transaction (P10.1.1).
+     */
+    redeemInTransaction(input: RedeemInput, tx: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    reverse(subscriptionId: string): Promise<PromoCodeRedemptionRecord | null>;
+    private checkEligibility;
+    private checkFirstTimeCustomer;
+    /**
+     * Lazy expiry: sets codes whose validUntil has passed to EXPIRED.
+     * Called before every find/preview — defense-in-depth alongside the cron.
+     */
+    private lazyExpire;
+    /**
+     * Lowest applicable plan price. With a whitelist it takes the minimum
+     * from the whitelist, otherwise across all marketed plans of the catalog
+     * (except non-redeemable).
+     */
+    private lowestApplicablePlanGross;
+}
+
+export { type PreviewInput as P, type RedeemInput as R, type PreviewInvalid as a, type PreviewReason as b, type PreviewResult as c, type PreviewValid as d, type PromoCodeStats as e, PromoCodesService as f, type PromoServiceConfig as g };