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

package/dist/promo/index.d.ts

@@ -1,9 +1,10 @@
-import { PromoCodeValueType, PromoCodeDurationType, BillingCycle, PromoCodeRepository, PromoCodeRedemptionRepository } from '@saasicat/core';
-import { i as PromoCodesService, f as PreviewResult } from '../promo.service-BJbKAmw3.js';
-export { C as CODE_MAX_LENGTH, a as CODE_MIN_LENGTH, b as CODE_PATTERN, c as PreviewInput, d as PreviewInvalid, e as PreviewReason, g as PreviewValid, h as PromoCodeStats, P as PromoServiceConfig, R as RedeemInput } from '../promo.service-BJbKAmw3.js';
+import { PromoCodeValueType, PromoCodeDurationType, BillingCycle, PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeHoldRepository } from '@saasicat/core';
+import { a as PromoCodesService, i as PreviewResult } from '../promo.service-CFjfF0Xm.js';
+export { C as CODE_MAX_LENGTH, b as CODE_MIN_LENGTH, c as CODE_PATTERN, d as CheckoutHoldInput, e as PreviewInput, f as PreviewInvalid, g as PreviewOptions, h as PreviewReason, j as PreviewValid, k as PromoCodeStats, P as PromoServiceConfig, R as RedeemInput } from '../promo.service-CFjfF0Xm.js';
 export { P as PromoCodeRateLimitGuard, h as hashIp, i as ipFingerprint } from '../rate-limit.guard-dntqAlfZ.js';
-export { P as PromoCodesModule, a as PromoCodesModuleOptions } from '../promo.module-Z8h1PNX-.js';
+export { a as PromoCodesModule, P as PromoCodesModuleOptions } from '../promo.module-DuIJdK3U.js';
 import { Type, CanActivate } from '@nestjs/common';
+import '../plan-catalog-source-DWe-BGY1.js';
 import '../di-CcNeq9v-.js';
 
 /** Structural view of a PromoCode for the calculator functions.
@@ -80,20 +81,34 @@ interface PromoLabelOptions {
 declare function buildLabel(code: Pick<PromoCodeForCalc, 'valueType' | 'value' | 'durationType' | 'durationValue'>, cycle: BillingCycle, options?: PromoLabelOptions): string;
 
 declare function round2(n: number): number;
-/** Gross = net * (1 + vatRate/100). */
+/**
+ * Whether a tax rate is one SaaSiCat accepts. Every tax rate in SaaSiCat is a
+ * percentage — 19 means 19 % — wherever it is stated: the settings, the
+ * catalogue, an offer, a contract, a contract line.
+ *
+ * A percentage lies from 0 to 100, and none lies strictly between 0 and 1:
+ * that is the shape of a fraction such as 0.19, and a fraction is refused
+ * rather than taken for a fraction of a per cent.
+ */
+declare function isTaxRatePercent(rate: number): boolean;
+/** Gross = net * (1 + vatRate/100), with `vatRate` a percentage. */
 declare function grossFromNet(net: number, vatRate: number): number;
-/** VAT included in the gross amount: gross * (vatRate / (100 + vatRate)). */
+/** Net = gross * 100 / (100 + vatRate), with `vatRate` a percentage. */
+declare function netFromGross(gross: number, vatRate: number): number;
+/** VAT included in the gross amount: gross * vatRate / (100 + vatRate). */
 declare function computeIncludedVat(grossAmount: number, vatRate: number): number;
 
 declare class PromoCodeExpirer {
     private readonly promoRepo;
     private readonly redemptionRepo;
+    private readonly holds;
     private readonly logger;
-    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository);
+    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository, holds?: PromoCodeHoldRepository | null);
     expirePromoCodes(): Promise<void>;
 }
 
 declare const PROMO_CODE_REPOSITORY_TOKEN: unique symbol;
+declare const PROMO_CODE_HOLD_REPOSITORY_TOKEN: unique symbol;
 declare const PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN: unique symbol;
 declare const PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN: unique symbol;
 declare const PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN: unique symbol;
@@ -166,4 +181,4 @@ declare class UpdatePromoCodeDto {
     revenueDeductionAccount?: string | null;
 }
 
-export { CreatePromoCodeDto, PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN, PROMO_CODE_REPOSITORY_TOKEN, PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN, PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN, PROMO_REVENUE_DEDUCTION_AGGREGATOR_TOKEN, PROMO_SERVICE_CONFIG_TOKEN, PROMO_SUBSCRIPTION_LOOKUP_TOKEN, PROMO_TRANSACTION_RUNNER_TOKEN, PreviewPromoCodeDto, PreviewResult, PromoCodeExpirer, type PromoCodeForCalc, PromoCodePublicController, PromoCodesService, type PromoLabelOptions, UpdatePromoCodeDto, addCycles, buildLabel, buildPromoCodeAdminController, computeDiscountGross, computeDiscountedGross, computeIncludedVat, computeRegularStartsAt, grossFromNet, round2 };
+export { CreatePromoCodeDto, PROMO_CODE_HOLD_REPOSITORY_TOKEN, PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN, PROMO_CODE_REPOSITORY_TOKEN, PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN, PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN, PROMO_REVENUE_DEDUCTION_AGGREGATOR_TOKEN, PROMO_SERVICE_CONFIG_TOKEN, PROMO_SUBSCRIPTION_LOOKUP_TOKEN, PROMO_TRANSACTION_RUNNER_TOKEN, PreviewPromoCodeDto, PreviewResult, PromoCodeExpirer, type PromoCodeForCalc, PromoCodePublicController, PromoCodesService, type PromoLabelOptions, UpdatePromoCodeDto, addCycles, buildLabel, buildPromoCodeAdminController, computeDiscountGross, computeDiscountedGross, computeIncludedVat, computeRegularStartsAt, grossFromNet, isTaxRatePercent, netFromGross, round2 };

package/dist/promo/index.js

@@ -10,11 +10,13 @@ import {
   buildPromoCodeAdminController,
   hashIp,
   ipFingerprint
-} from "../chunk-TXC3LHHB.js";
+} from "../chunk-4SDSYV4A.js";
+import "../chunk-OOTEXP47.js";
 import {
   CODE_MAX_LENGTH,
   CODE_MIN_LENGTH,
   CODE_PATTERN,
+  PROMO_CODE_HOLD_REPOSITORY_TOKEN,
   PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN,
   PROMO_CODE_REPOSITORY_TOKEN,
   PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN,
@@ -29,22 +31,26 @@ import {
   computeDiscountGross,
   computeDiscountedGross,
   computeRegularStartsAt
-} from "../chunk-VXEYLNIB.js";
-import "../chunk-O2J2HDXA.js";
-import "../chunk-YSC46BGM.js";
+} from "../chunk-3RLWML2S.js";
+import "../chunk-TBBZWZQT.js";
 import {
   computeIncludedVat,
   grossFromNet,
+  isTaxRatePercent,
+  netFromGross,
   round2
-} from "../chunk-DQKCK7DX.js";
-import "../chunk-57V6ZTI6.js";
-import "../chunk-SABTXESR.js";
+} from "../chunk-6PJE7EWO.js";
+import "../chunk-SZ7RFPXA.js";
+import "../chunk-YSC46BGM.js";
+import "../chunk-FEQZCWUL.js";
+import "../chunk-J7NJRK3K.js";
 import "../chunk-SHUYVCID.js";
 export {
   CODE_MAX_LENGTH,
   CODE_MIN_LENGTH,
   CODE_PATTERN,
   CreatePromoCodeDto,
+  PROMO_CODE_HOLD_REPOSITORY_TOKEN,
   PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN,
   PROMO_CODE_REPOSITORY_TOKEN,
   PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN,
@@ -70,5 +76,7 @@ export {
   grossFromNet,
   hashIp,
   ipFingerprint,
+  isTaxRatePercent,
+  netFromGross,
   round2
 };

package/dist/{promo.module-DtvIycpt.d.cts → promo.module-CKkECmU8.d.cts}

@@ -1,7 +1,7 @@
 import { Type, CanActivate, DynamicModule, ForwardReference } from '@nestjs/common';
-import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner } from '@saasicat/core';
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PromoCodeHoldRepository } from '@saasicat/core';
 import { P as ProviderSpec } from './di-CcNeq9v-.cjs';
-import { P as PromoServiceConfig } from './promo.service-BJbKAmw3.cjs';
+import { P as PromoServiceConfig } from './promo.service-BYBu6dy3.cjs';
 
 interface PromoCodesModuleOptions {
     promoCodeRepository: ProviderSpec<PromoCodeRepository>;
@@ -11,6 +11,12 @@ interface PromoCodesModuleOptions {
     subscriptionLookup: ProviderSpec<PromoSubscriptionLookup>;
     revenueAggregator: ProviderSpec<PromoRevenueDeductionAggregator>;
     transactionRunner: ProviderSpec<TransactionRunner>;
+    /**
+     * The slots a code keeps for checkouts that have started. Left out, no
+     * checkout holds a slot, and a sign-up that asks for one is refused at
+     * start-up of the hold rather than holding nothing.
+     */
+    holdRepository?: ProviderSpec<PromoCodeHoldRepository>;
     config?: PromoServiceConfig;
     /**
      * Default `true`. Set to `false` if the consumer wants to disable the cron
@@ -36,4 +42,4 @@ declare class PromoCodesModule {
     static forRoot(options: PromoCodesModuleOptions): DynamicModule;
 }
 
-export { PromoCodesModule as P, type PromoCodesModuleOptions as a };
+export { type PromoCodesModuleOptions as P, PromoCodesModule as a };

package/dist/{promo.module-Z8h1PNX-.d.ts → promo.module-DuIJdK3U.d.ts}

@@ -1,7 +1,7 @@
 import { Type, CanActivate, DynamicModule, ForwardReference } from '@nestjs/common';
-import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner } from '@saasicat/core';
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PromoCodeHoldRepository } from '@saasicat/core';
 import { P as ProviderSpec } from './di-CcNeq9v-.js';
-import { P as PromoServiceConfig } from './promo.service-BJbKAmw3.js';
+import { P as PromoServiceConfig } from './promo.service-CFjfF0Xm.js';
 
 interface PromoCodesModuleOptions {
     promoCodeRepository: ProviderSpec<PromoCodeRepository>;
@@ -11,6 +11,12 @@ interface PromoCodesModuleOptions {
     subscriptionLookup: ProviderSpec<PromoSubscriptionLookup>;
     revenueAggregator: ProviderSpec<PromoRevenueDeductionAggregator>;
     transactionRunner: ProviderSpec<TransactionRunner>;
+    /**
+     * The slots a code keeps for checkouts that have started. Left out, no
+     * checkout holds a slot, and a sign-up that asks for one is refused at
+     * start-up of the hold rather than holding nothing.
+     */
+    holdRepository?: ProviderSpec<PromoCodeHoldRepository>;
     config?: PromoServiceConfig;
     /**
      * Default `true`. Set to `false` if the consumer wants to disable the cron
@@ -36,4 +42,4 @@ declare class PromoCodesModule {
     static forRoot(options: PromoCodesModuleOptions): DynamicModule;
 }
 
-export { PromoCodesModule as P, type PromoCodesModuleOptions as a };
+export { type PromoCodesModuleOptions as P, PromoCodesModule as a };

package/dist/promo.service-BYBu6dy3.d.cts

@@ -0,0 +1,215 @@
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PromoCodeHoldRepository, CreatePromoCodeData, PromoCodeRecord, UpdatePromoCodeData, PromoCodeFilter, PromoCodeRedemptionListItem, BillingCycle, PromoPreviewInvalidReason, TransactionContext, PromoCodeRedemptionRecord } from '@saasicat/core';
+import { P as PlanCatalogSource } from './plan-catalog-source-DWe-BGY1.cjs';
+
+declare const CODE_MIN_LENGTH = 4;
+declare const CODE_MAX_LENGTH = 32;
+declare const CODE_PATTERN: RegExp;
+type PreviewReason = PromoPreviewInvalidReason;
+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;
+        discountNet: 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 PreviewOptions {
+    /**
+     * The checkout offer the code is priced for. A live slot that offer holds
+     * is its own and is not counted against it.
+     */
+    checkoutOfferId?: string;
+    /**
+     * The offer is priced as it is concluded: its live slot also keeps the
+     * code's state as it was when the slot was taken, so a code paused or past
+     * its validity since is still accepted for the checkout that holds it.
+     */
+    concluding?: boolean;
+}
+interface RedeemInput {
+    code: string;
+    subscriptionId: string;
+    tenantId: string;
+    /** For the firstTimeCustomersOnly check in the final redeem path. */
+    email?: string;
+}
+/** A slot of a code to hold for a checkout. */
+interface CheckoutHoldInput {
+    /** The checkout offer the slot is held for; it holds one at most. */
+    checkoutOfferId: string;
+    code: string;
+    planId: string;
+    billingCycle: BillingCycle;
+    /** For the firstTimeCustomersOnly check. */
+    email?: string;
+    /** When the checkout expires, and with it the hold. */
+    until: Date;
+}
+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;
+    };
+    /** Slots held for checkouts that have not concluded, which no one else can take. */
+    held: 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 planCatalogs;
+    private readonly config;
+    private readonly holds;
+    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository, validationLogRepo: PromoCodeValidationLogRepository, firstTimeCheck: FirstTimeCustomerCheck, subscriptionLookup: PromoSubscriptionLookup, revenueAggregator: PromoRevenueDeductionAggregator, transactionRunner: TransactionRunner, planCatalogs: PlanCatalogSource, config: PromoServiceConfig, holds?: PromoCodeHoldRepository | null);
+    create(input: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    /**
+     * Changes a code under the rules a new one is held to, asking the rules the
+     * named fields bear on: the terms as they stand after the change have to be
+     * ones `create` would accept. Pausing alone is always possible.
+     */
+    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, options?: PreviewOptions): Promise<PreviewResult>;
+    /**
+     * Holds a slot of the code for a checkout offer until `until`, after every
+     * check a preview makes — so a customer who reaches the payment form keeps
+     * the code however many others redeem it meanwhile. Starting the same
+     * checkout again moves the expiry of the slot it holds rather than taking a
+     * second — later, never earlier (`PromoCodeHoldRepository.extend`); a
+     * checkout that held another code gives that one back.
+     *
+     * Refused with `PROMO_CODE_NOT_REDEEMABLE` and the reason a preview would
+     * give, `EXHAUSTED` when every slot is redeemed or held — also when the
+     * code changed between that check and taking the slot. Nothing is held
+     * then, and a slot the offer held before stays with it until it expires.
+     */
+    holdForCheckout(input: CheckoutHoldInput): Promise<void>;
+    /** Gives back the slot a checkout offer holds, if it holds one. */
+    releaseCheckoutHold(checkoutOfferId: string, tx?: TransactionContext): Promise<void>;
+    /**
+     * Gives back the slot a checkout offer holds only while it still expires at
+     * `expiresAt` — the hold as the caller wrote it. A slot another start of the
+     * checkout moved since stays with the form that start opened.
+     */
+    releaseCheckoutHoldIfUnmoved(checkoutOfferId: string, expiresAt: Date): Promise<void>;
+    /**
+     * Hands the offer's live hold to the redemption that runs on `tx`: redeeming
+     * the code there takes the held slot instead of a free one, whatever
+     * happened to the code since the hold was taken. The caller releases it
+     * with `releaseCheckoutHold` on the same transaction once the redemption
+     * had its chance — a hold the redemption did not take is not held any more.
+     * False when the offer holds no live slot.
+     */
+    handOverCheckoutHold(checkoutOfferId: string, tx: TransactionContext): Promise<boolean>;
+    /**
+     * 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).
+     *
+     * A checkout that held a slot of the code, and whose conclusion handed it
+     * over on this transaction, is redeemed on that slot: its state is not
+     * asked again, and no free slot is taken. Otherwise a free one is claimed.
+     * Either way the redemption is refused where a preview would refuse on the
+     * price — an invoice of zero the code does not allow — and it records at
+     * most the price it is redeemed against.
+     */
+    redeemInTransaction(input: RedeemInput, tx: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    reverse(subscriptionId: string): Promise<PromoCodeRedemptionRecord | null>;
+    /**
+     * Why a code does not apply to a plan, or what it takes off it. The plans
+     * are read only once the code itself has passed, so somebody trying codes
+     * that do not exist costs no read of the plan tables.
+     */
+    private judge;
+    /** Everything about a code that needs no plan price: its state, its slots, and the plans it fits. */
+    private checkCode;
+    /** Whether the code can be used now at all: its status and its validity window. */
+    private checkState;
+    /** Whether the plan is sold at a price in this rhythm, and one the code's minimum allows. */
+    private checkPlanPrice;
+    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;
+    /**
+     * The code with the slots of its expired holds given back, so that what
+     * it counts as held is what is held now. One code at a time: this runs on
+     * every preview, and a sweep of one code locks one row.
+     */
+    private findWithLiveHolds;
+    /**
+     * Why a code the checks passed a moment ago had no slot to take: it may
+     * have been paused, deleted or run past its validity in between, and a
+     * refusal that says "exhausted" for any of them misleads the customer and
+     * the log a support answer is built on.
+     */
+    private whyNoSlot;
+    /** Whether the checkout offer holds a slot of this code that has not expired. */
+    private holdsLiveSlot;
+    /** The slots of a code held right now, its expired holds given back first. */
+    private liveHeldCount;
+    private requireHolds;
+    private ruleContext;
+    /**
+     * 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 { CODE_MAX_LENGTH as C, type PromoServiceConfig as P, type RedeemInput as R, PromoCodesService as a, CODE_MIN_LENGTH as b, CODE_PATTERN as c, type CheckoutHoldInput as d, type PreviewInput as e, type PreviewInvalid as f, type PreviewOptions as g, type PreviewReason as h, type PreviewResult as i, type PreviewValid as j, type PromoCodeStats as k };

package/dist/promo.service-CFjfF0Xm.d.ts

@@ -0,0 +1,215 @@
+import { PromoCodeRepository, PromoCodeRedemptionRepository, PromoCodeValidationLogRepository, FirstTimeCustomerCheck, PromoSubscriptionLookup, PromoRevenueDeductionAggregator, TransactionRunner, PromoCodeHoldRepository, CreatePromoCodeData, PromoCodeRecord, UpdatePromoCodeData, PromoCodeFilter, PromoCodeRedemptionListItem, BillingCycle, PromoPreviewInvalidReason, TransactionContext, PromoCodeRedemptionRecord } from '@saasicat/core';
+import { P as PlanCatalogSource } from './plan-catalog-source-DWe-BGY1.js';
+
+declare const CODE_MIN_LENGTH = 4;
+declare const CODE_MAX_LENGTH = 32;
+declare const CODE_PATTERN: RegExp;
+type PreviewReason = PromoPreviewInvalidReason;
+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;
+        discountNet: 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 PreviewOptions {
+    /**
+     * The checkout offer the code is priced for. A live slot that offer holds
+     * is its own and is not counted against it.
+     */
+    checkoutOfferId?: string;
+    /**
+     * The offer is priced as it is concluded: its live slot also keeps the
+     * code's state as it was when the slot was taken, so a code paused or past
+     * its validity since is still accepted for the checkout that holds it.
+     */
+    concluding?: boolean;
+}
+interface RedeemInput {
+    code: string;
+    subscriptionId: string;
+    tenantId: string;
+    /** For the firstTimeCustomersOnly check in the final redeem path. */
+    email?: string;
+}
+/** A slot of a code to hold for a checkout. */
+interface CheckoutHoldInput {
+    /** The checkout offer the slot is held for; it holds one at most. */
+    checkoutOfferId: string;
+    code: string;
+    planId: string;
+    billingCycle: BillingCycle;
+    /** For the firstTimeCustomersOnly check. */
+    email?: string;
+    /** When the checkout expires, and with it the hold. */
+    until: Date;
+}
+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;
+    };
+    /** Slots held for checkouts that have not concluded, which no one else can take. */
+    held: 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 planCatalogs;
+    private readonly config;
+    private readonly holds;
+    constructor(promoRepo: PromoCodeRepository, redemptionRepo: PromoCodeRedemptionRepository, validationLogRepo: PromoCodeValidationLogRepository, firstTimeCheck: FirstTimeCustomerCheck, subscriptionLookup: PromoSubscriptionLookup, revenueAggregator: PromoRevenueDeductionAggregator, transactionRunner: TransactionRunner, planCatalogs: PlanCatalogSource, config: PromoServiceConfig, holds?: PromoCodeHoldRepository | null);
+    create(input: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    /**
+     * Changes a code under the rules a new one is held to, asking the rules the
+     * named fields bear on: the terms as they stand after the change have to be
+     * ones `create` would accept. Pausing alone is always possible.
+     */
+    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, options?: PreviewOptions): Promise<PreviewResult>;
+    /**
+     * Holds a slot of the code for a checkout offer until `until`, after every
+     * check a preview makes — so a customer who reaches the payment form keeps
+     * the code however many others redeem it meanwhile. Starting the same
+     * checkout again moves the expiry of the slot it holds rather than taking a
+     * second — later, never earlier (`PromoCodeHoldRepository.extend`); a
+     * checkout that held another code gives that one back.
+     *
+     * Refused with `PROMO_CODE_NOT_REDEEMABLE` and the reason a preview would
+     * give, `EXHAUSTED` when every slot is redeemed or held — also when the
+     * code changed between that check and taking the slot. Nothing is held
+     * then, and a slot the offer held before stays with it until it expires.
+     */
+    holdForCheckout(input: CheckoutHoldInput): Promise<void>;
+    /** Gives back the slot a checkout offer holds, if it holds one. */
+    releaseCheckoutHold(checkoutOfferId: string, tx?: TransactionContext): Promise<void>;
+    /**
+     * Gives back the slot a checkout offer holds only while it still expires at
+     * `expiresAt` — the hold as the caller wrote it. A slot another start of the
+     * checkout moved since stays with the form that start opened.
+     */
+    releaseCheckoutHoldIfUnmoved(checkoutOfferId: string, expiresAt: Date): Promise<void>;
+    /**
+     * Hands the offer's live hold to the redemption that runs on `tx`: redeeming
+     * the code there takes the held slot instead of a free one, whatever
+     * happened to the code since the hold was taken. The caller releases it
+     * with `releaseCheckoutHold` on the same transaction once the redemption
+     * had its chance — a hold the redemption did not take is not held any more.
+     * False when the offer holds no live slot.
+     */
+    handOverCheckoutHold(checkoutOfferId: string, tx: TransactionContext): Promise<boolean>;
+    /**
+     * 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).
+     *
+     * A checkout that held a slot of the code, and whose conclusion handed it
+     * over on this transaction, is redeemed on that slot: its state is not
+     * asked again, and no free slot is taken. Otherwise a free one is claimed.
+     * Either way the redemption is refused where a preview would refuse on the
+     * price — an invoice of zero the code does not allow — and it records at
+     * most the price it is redeemed against.
+     */
+    redeemInTransaction(input: RedeemInput, tx: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    reverse(subscriptionId: string): Promise<PromoCodeRedemptionRecord | null>;
+    /**
+     * Why a code does not apply to a plan, or what it takes off it. The plans
+     * are read only once the code itself has passed, so somebody trying codes
+     * that do not exist costs no read of the plan tables.
+     */
+    private judge;
+    /** Everything about a code that needs no plan price: its state, its slots, and the plans it fits. */
+    private checkCode;
+    /** Whether the code can be used now at all: its status and its validity window. */
+    private checkState;
+    /** Whether the plan is sold at a price in this rhythm, and one the code's minimum allows. */
+    private checkPlanPrice;
+    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;
+    /**
+     * The code with the slots of its expired holds given back, so that what
+     * it counts as held is what is held now. One code at a time: this runs on
+     * every preview, and a sweep of one code locks one row.
+     */
+    private findWithLiveHolds;
+    /**
+     * Why a code the checks passed a moment ago had no slot to take: it may
+     * have been paused, deleted or run past its validity in between, and a
+     * refusal that says "exhausted" for any of them misleads the customer and
+     * the log a support answer is built on.
+     */
+    private whyNoSlot;
+    /** Whether the checkout offer holds a slot of this code that has not expired. */
+    private holdsLiveSlot;
+    /** The slots of a code held right now, its expired holds given back first. */
+    private liveHeldCount;
+    private requireHolds;
+    private ruleContext;
+    /**
+     * 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 { CODE_MAX_LENGTH as C, type PromoServiceConfig as P, type RedeemInput as R, PromoCodesService as a, CODE_MIN_LENGTH as b, CODE_PATTERN as c, type CheckoutHoldInput as d, type PreviewInput as e, type PreviewInvalid as f, type PreviewOptions as g, type PreviewReason as h, type PreviewResult as i, type PreviewValid as j, type PromoCodeStats as k };