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

package/dist/chunk-3RLWML2S.js

@@ -0,0 +1,896 @@
+import {
+  getPlanPriceGross
+} from "./chunk-TBBZWZQT.js";
+import {
+  computeIncludedVat,
+  netFromGross,
+  round2
+} from "./chunk-6PJE7EWO.js";
+import {
+  PLAN_CATALOG_SOURCE_TOKEN
+} from "./chunk-FEQZCWUL.js";
+import {
+  __name
+} from "./chunk-SHUYVCID.js";
+
+// src/promo/calculator.ts
+function computeDiscountGross(plan, code) {
+  const v = Number(code.value);
+  if (code.valueType === "PERCENT") {
+    return round2(plan.gross * v / 100);
+  }
+  return round2(v);
+}
+__name(computeDiscountGross, "computeDiscountGross");
+function computeDiscountedGross(planGross, discountGross) {
+  return round2(planGross - discountGross);
+}
+__name(computeDiscountedGross, "computeDiscountedGross");
+function computeRegularStartsAt(startsAt, cycle, durationType, durationValue) {
+  const result = new Date(startsAt);
+  if (durationType === "ONCE") {
+    return addCycles(result, cycle, 1);
+  }
+  if (durationType === "MONTHS") {
+    result.setMonth(result.getMonth() + (durationValue ?? 0));
+    return result;
+  }
+  return addCycles(result, cycle, durationValue ?? 0);
+}
+__name(computeRegularStartsAt, "computeRegularStartsAt");
+function addCycles(date, cycle, n) {
+  const r = new Date(date);
+  if (cycle === "YEARLY") {
+    r.setFullYear(r.getFullYear() + n);
+  } else {
+    r.setMonth(r.getMonth() + n);
+  }
+  return r;
+}
+__name(addCycles, "addCycles");
+var LEGACY_LABEL_LOCALE = "de-DE";
+var LEGACY_LABEL_CURRENCY = "EUR";
+var ICU_NON_BREAKING_SPACES = /[\u00A0\u202F]/g;
+function requireSupportedLocale(locale) {
+  if (Intl.NumberFormat.supportedLocalesOf([
+    locale
+  ]).length === 0) {
+    throw new RangeError(`buildLabel: locale "${locale}" names a language this runtime cannot serve. It would be formatted as "${new Intl.NumberFormat(locale).resolvedOptions().locale}" instead \u2014 a language nobody chose. Pass a tag the runtime serves.`);
+  }
+}
+__name(requireSupportedLocale, "requireSupportedLocale");
+function formatPromoValue(value, valueType, { locale = LEGACY_LABEL_LOCALE, currency = LEGACY_LABEL_CURRENCY }) {
+  requireSupportedLocale(locale);
+  const numberFormat = valueType === "PERCENT" ? {
+    style: "unit",
+    unit: "percent"
+  } : {
+    style: "currency",
+    currency
+  };
+  return new Intl.NumberFormat(locale, numberFormat).format(value).replace(ICU_NON_BREAKING_SPACES, " ");
+}
+__name(formatPromoValue, "formatPromoValue");
+function buildLabel(code, cycle, options = {}) {
+  const value = Number(code.value);
+  const valueStr = formatPromoValue(value, code.valueType, options);
+  if (code.durationType === "ONCE") {
+    return `${valueStr} once`;
+  }
+  if (code.durationType === "MONTHS") {
+    const m = code.durationValue ?? 0;
+    return m === 1 ? `${valueStr} for the first month` : `${valueStr} for ${m} months`;
+  }
+  const n = code.durationValue ?? 0;
+  if (n === 1) return cycle === "YEARLY" ? `${valueStr} for the first year` : `${valueStr} for the first month`;
+  return cycle === "YEARLY" ? `${valueStr} for the first ${n} years` : `${valueStr} for the first ${n} months`;
+}
+__name(buildLabel, "buildLabel");
+
+// src/promo/promo.tokens.ts
+var PROMO_CODE_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoCodeRepository");
+var PROMO_CODE_HOLD_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoCodeHoldRepository");
+var PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoCodeRedemptionRepository");
+var PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoCodeValidationLogRepository");
+var PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoFirstTimeCustomerCheck");
+var PROMO_SUBSCRIPTION_LOOKUP_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoSubscriptionLookup");
+var PROMO_REVENUE_DEDUCTION_AGGREGATOR_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoRevenueDeductionAggregator");
+var PROMO_TRANSACTION_RUNNER_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoTransactionRunner");
+var PROMO_SERVICE_CONFIG_TOKEN = /* @__PURE__ */ Symbol.for("saasicat/nest/PromoServiceConfig");
+
+// src/promo/promo.service.ts
+import { BadRequestException as BadRequestException2, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import { BILLING_ERROR_CODES, CONTRACT_ERROR_CODES, PROMO_ERROR_CODES as PROMO_ERROR_CODES2 } from "@saasicat/core";
+
+// src/promo/code-rules.ts
+import { BadRequestException } from "@nestjs/common";
+import { PROMO_ERROR_CODES } from "@saasicat/core";
+var PERCENT_MIN_EXCLUSIVE = 0;
+var PERCENT_MAX = 100;
+var DURATION_MIN = 1;
+var DURATION_MAX = 24;
+var ALL_TERMS = /* @__PURE__ */ new Set([
+  "valueType",
+  "value",
+  "durationType",
+  "durationValue",
+  "validFrom",
+  "validUntil",
+  "appliesToPlans",
+  "minimumPlanAmountGross",
+  "allowZeroInvoice"
+]);
+async function assertCodeTerms(terms, changed, context) {
+  const touches = /* @__PURE__ */ __name((...fields) => fields.some((field) => changed.has(field)), "touches");
+  if (touches("valueType", "value")) assertValue(terms);
+  if (touches("durationType", "durationValue")) assertDuration(terms);
+  if (touches("validFrom", "validUntil")) assertValidityWindow(terms);
+  if (touches("appliesToPlans")) assertPlansDiscountable(terms, context.nonRedeemablePlans);
+  if (touches("minimumPlanAmountGross")) assertMinimumAmount(terms);
+  if (touches("valueType", "value", "allowZeroInvoice", "appliesToPlans")) {
+    await assertNoZeroInvoice(terms, context);
+  }
+}
+__name(assertCodeTerms, "assertCodeTerms");
+function discountOnPlan(code, planGross) {
+  const discountGross = Math.min(computeDiscountGross({
+    gross: planGross
+  }, code), planGross);
+  const discountedGross = computeDiscountedGross(planGross, discountGross);
+  return {
+    discountGross,
+    discountedGross,
+    zeroInvoice: !code.allowZeroInvoice && discountedGross <= 0
+  };
+}
+__name(discountOnPlan, "discountOnPlan");
+function appliedValue(code, planGross) {
+  const cap = code.valueType === "PERCENT" ? PERCENT_MAX : planGross;
+  return Number(code.value) > cap ? cap.toFixed(2) : code.value;
+}
+__name(appliedValue, "appliedValue");
+function assertValue(terms) {
+  if (terms.valueType === "PERCENT") {
+    if (!(terms.value > PERCENT_MIN_EXCLUSIVE && terms.value <= PERCENT_MAX)) {
+      throw new BadRequestException({
+        code: PROMO_ERROR_CODES.PROMO_PERCENT_OUT_OF_RANGE,
+        message: "The percentage must be between 0 and 100.",
+        params: {
+          value: terms.value,
+          min: PERCENT_MIN_EXCLUSIVE,
+          max: PERCENT_MAX
+        }
+      });
+    }
+  } else if (!(terms.value > 0)) {
+    throw new BadRequestException({
+      code: PROMO_ERROR_CODES.PROMO_AMOUNT_NOT_POSITIVE,
+      message: "The amount must be positive.",
+      params: {
+        value: terms.value,
+        min: 0
+      }
+    });
+  }
+}
+__name(assertValue, "assertValue");
+function assertDuration(terms) {
+  if (terms.durationType === "ONCE") {
+    if (terms.durationValue != null) {
+      throw new BadRequestException({
+        code: PROMO_ERROR_CODES.PROMO_ONE_OFF_WITH_DURATION,
+        message: "A one-off discount must not set a duration.",
+        params: {
+          durationValue: terms.durationValue
+        }
+      });
+    }
+    return;
+  }
+  const v = terms.durationValue;
+  if (v == null || v < DURATION_MIN || v > DURATION_MAX) {
+    throw new BadRequestException({
+      code: PROMO_ERROR_CODES.PROMO_DURATION_INVALID,
+      message: "Invalid duration (at most 24 months or billing periods).",
+      params: {
+        durationValue: v ?? null,
+        min: DURATION_MIN,
+        max: DURATION_MAX
+      }
+    });
+  }
+}
+__name(assertDuration, "assertDuration");
+function assertValidityWindow(terms) {
+  if (terms.validFrom && terms.validUntil && terms.validFrom >= terms.validUntil) {
+    throw new BadRequestException({
+      code: PROMO_ERROR_CODES.PROMO_VALIDITY_WINDOW_INVALID,
+      message: "Invalid validity window.",
+      params: {
+        validFrom: terms.validFrom.toISOString(),
+        validUntil: terms.validUntil.toISOString()
+      }
+    });
+  }
+}
+__name(assertValidityWindow, "assertValidityWindow");
+function assertPlansDiscountable(terms, blocked) {
+  for (const plan of terms.appliesToPlans) {
+    if (blocked.includes(plan)) {
+      throw new BadRequestException({
+        code: PROMO_ERROR_CODES.PROMO_PLAN_NOT_DISCOUNTABLE,
+        message: `${plan}-Plan cannot be discounted.`,
+        params: {
+          plan
+        }
+      });
+    }
+  }
+}
+__name(assertPlansDiscountable, "assertPlansDiscountable");
+function assertMinimumAmount(terms) {
+  if (terms.minimumPlanAmountGross != null && terms.minimumPlanAmountGross <= 0) {
+    throw new BadRequestException({
+      code: PROMO_ERROR_CODES.PROMO_MIN_AMOUNT_NOT_POSITIVE,
+      message: "The minimum plan gross amount must be positive.",
+      params: {
+        value: terms.minimumPlanAmountGross,
+        min: 0
+      }
+    });
+  }
+}
+__name(assertMinimumAmount, "assertMinimumAmount");
+async function assertNoZeroInvoice(terms, context) {
+  if (terms.valueType !== "ABSOLUTE" || terms.allowZeroInvoice) return;
+  const lowest = await context.lowestApplicablePlanGross(terms.appliesToPlans);
+  if (lowest != null && terms.value >= lowest) {
+    throw new BadRequestException({
+      code: PROMO_ERROR_CODES.PROMO_WOULD_PRODUCE_ZERO_INVOICE,
+      message: "For absolute amounts the discount must stay below the lowest applicable plan price, or allowZeroInvoice must be enabled.",
+      params: {
+        value: terms.value,
+        lowestApplicablePlanGross: lowest
+      }
+    });
+  }
+}
+__name(assertNoZeroInvoice, "assertNoZeroInvoice");
+
+// src/promo/promo.service.ts
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var CODE_MIN_LENGTH = 4;
+var CODE_MAX_LENGTH = 32;
+var CODE_PATTERN = /^[A-Z0-9_-]{4,32}$/;
+var HOLD_ATTEMPTS = 2;
+function notRedeemable(reason) {
+  return new BadRequestException2({
+    code: PROMO_ERROR_CODES2.PROMO_CODE_NOT_REDEEMABLE,
+    message: `Code cannot be redeemed: ${reason}`,
+    params: {
+      reason
+    }
+  });
+}
+__name(notRedeemable, "notRedeemable");
+var PromoCodesService = class {
+  static {
+    __name(this, "PromoCodesService");
+  }
+  promoRepo;
+  redemptionRepo;
+  validationLogRepo;
+  firstTimeCheck;
+  subscriptionLookup;
+  revenueAggregator;
+  transactionRunner;
+  planCatalogs;
+  config;
+  holds;
+  constructor(promoRepo, redemptionRepo, validationLogRepo, firstTimeCheck, subscriptionLookup, revenueAggregator, transactionRunner, planCatalogs, config, holds = null) {
+    this.promoRepo = promoRepo;
+    this.redemptionRepo = redemptionRepo;
+    this.validationLogRepo = validationLogRepo;
+    this.firstTimeCheck = firstTimeCheck;
+    this.subscriptionLookup = subscriptionLookup;
+    this.revenueAggregator = revenueAggregator;
+    this.transactionRunner = transactionRunner;
+    this.planCatalogs = planCatalogs;
+    this.config = config;
+    this.holds = holds;
+  }
+  // ─── ADMIN: Creation / Editing ─────────────────────────────────────────
+  async create(input) {
+    const code = input.code.trim().toUpperCase();
+    if (!CODE_PATTERN.test(code)) {
+      throw new BadRequestException2({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_FORMAT_INVALID,
+        message: 'The code may only contain upper-case letters, digits, "-" and "_" (4\u201332 characters).',
+        params: {
+          promoCode: code,
+          minLength: CODE_MIN_LENGTH,
+          maxLength: CODE_MAX_LENGTH
+        }
+      });
+    }
+    await assertCodeTerms({
+      valueType: input.valueType,
+      value: input.value,
+      durationType: input.durationType,
+      durationValue: input.durationValue ?? null,
+      validFrom: input.validFrom ?? null,
+      validUntil: input.validUntil ?? null,
+      appliesToPlans: input.appliesToPlans ?? [],
+      minimumPlanAmountGross: input.minimumPlanAmountGross ?? null,
+      allowZeroInvoice: input.allowZeroInvoice ?? false
+    }, ALL_TERMS, this.ruleContext());
+    const exists = await this.promoRepo.findByCode(code);
+    if (exists) {
+      throw new BadRequestException2({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_ALREADY_EXISTS,
+        message: "The code already exists.",
+        params: {
+          promoCode: code
+        }
+      });
+    }
+    return this.promoRepo.create({
+      ...input,
+      code
+    });
+  }
+  /**
+   * 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.
+   */
+  async update(id, input) {
+    const existing = await this.promoRepo.findById(id);
+    if (!existing) {
+      throw new NotFoundException({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_NOT_FOUND,
+        message: "Code not found",
+        params: {
+          promoCodeId: id,
+          promoCode: null
+        }
+      });
+    }
+    if (input.maxRedemptions != null && existing.maxRedemptions != null) {
+      if (input.maxRedemptions < existing.maxRedemptions) {
+        throw new BadRequestException2({
+          code: PROMO_ERROR_CODES2.PROMO_MAX_REDEMPTIONS_LOWERED,
+          message: "maxRedemptions cannot be lowered.",
+          params: {
+            current: existing.maxRedemptions,
+            requested: input.maxRedemptions
+          }
+        });
+      }
+    }
+    const changed = new Set(Object.keys(input).filter((field) => input[field] !== void 0));
+    await assertCodeTerms(termsAfter(existing, input), changed, this.ruleContext());
+    return this.promoRepo.update(id, input);
+  }
+  async softDelete(id) {
+    const redemptions = await this.redemptionRepo.countByPromoCode(id);
+    const held = await this.liveHeldCount(id);
+    if (redemptions > 0 || held > 0) {
+      throw new BadRequestException2({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_HAS_REDEMPTIONS,
+        message: "The code already has redemptions, or checkouts holding one \u2014 it cannot be soft-deleted. Pause it instead.",
+        params: {
+          promoCodeId: id,
+          redemptions,
+          held
+        }
+      });
+    }
+    await this.promoRepo.softDelete(id);
+  }
+  async findAll(filter = {}) {
+    await this.lazyExpire();
+    await this.holds?.expireDue(/* @__PURE__ */ new Date());
+    return this.promoRepo.findMany(filter);
+  }
+  async findOne(id) {
+    await this.lazyExpire();
+    await this.holds?.expireDue(/* @__PURE__ */ new Date(), id);
+    const code = await this.promoRepo.findById(id);
+    if (!code || code.deletedAt) {
+      throw new NotFoundException({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_NOT_FOUND,
+        message: "Code not found",
+        params: {
+          promoCodeId: id,
+          promoCode: null
+        }
+      });
+    }
+    return code;
+  }
+  async stats(id) {
+    const code = await this.findOne(id);
+    const [active, total, reversed, expired, validations, revenueDeductionGross] = await Promise.all([
+      this.redemptionRepo.countByPromoCode(id, "ACTIVE"),
+      this.redemptionRepo.countByPromoCode(id),
+      this.redemptionRepo.countByPromoCode(id, "REVERSED"),
+      this.redemptionRepo.countByPromoCode(id, "EXPIRED"),
+      this.validationLogRepo.countValid(id),
+      this.revenueAggregator.sumGrossForPromoCode(id)
+    ]);
+    return {
+      code,
+      validations,
+      redemptions: {
+        active,
+        total,
+        reversed,
+        expired
+      },
+      held: code.heldCount,
+      revenueDeductionGross
+    };
+  }
+  async listRedemptions(promoCodeId) {
+    return this.redemptionRepo.listByPromoCode(promoCodeId);
+  }
+  // ─── PUBLIC: Preview / Validation ──────────────────────────────────────
+  async preview(input, options = {}) {
+    const code = input.code.trim().toUpperCase();
+    if (!CODE_PATTERN.test(code)) {
+      await this.validationLogRepo.log({
+        promoCodeId: null,
+        codeAttempt: code,
+        result: "NOT_FOUND",
+        ipHash: input.ipHash,
+        sessionId: input.sessionId
+      });
+      return {
+        valid: false,
+        reason: "NOT_FOUND"
+      };
+    }
+    await this.lazyExpire();
+    const now = /* @__PURE__ */ new Date();
+    const promo = await this.findWithLiveHolds(code, now);
+    const ownSlot = promo !== null && options.checkoutOfferId !== void 0 && await this.holdsLiveSlot(options.checkoutOfferId, promo, now);
+    const verdict = await this.judge(promo, input, {
+      ownSlot,
+      held: ownSlot && options.concluding === true,
+      countSlots: true
+    });
+    await this.validationLogRepo.log({
+      promoCodeId: promo?.id ?? null,
+      codeAttempt: code,
+      result: verdict.reason ?? "VALID",
+      ipHash: input.ipHash,
+      sessionId: input.sessionId
+    });
+    if (verdict.reason !== null) return {
+      valid: false,
+      reason: verdict.reason
+    };
+    const { catalog, planGross, discount } = verdict;
+    const regularStartsAt = computeRegularStartsAt(now, input.billingCycle, verdict.promo.durationType, verdict.promo.durationValue);
+    return {
+      valid: true,
+      code: verdict.promo.code,
+      label: buildLabel(verdict.promo, input.billingCycle),
+      discount: {
+        valueType: verdict.promo.valueType,
+        value: Number(verdict.promo.value).toFixed(2),
+        durationType: verdict.promo.durationType,
+        durationValue: verdict.promo.durationValue
+      },
+      price: {
+        originalGross: planGross.toFixed(2),
+        discountGross: discount.discountGross.toFixed(2),
+        discountNet: netFromGross(discount.discountGross, catalog.vatRate).toFixed(2),
+        discountedGross: discount.discountedGross.toFixed(2),
+        includedVat: computeIncludedVat(discount.discountedGross, catalog.vatRate).toFixed(2),
+        nextRegularAmountGross: planGross.toFixed(2),
+        regularStartsAt: regularStartsAt ? regularStartsAt.toISOString() : null
+      }
+    };
+  }
+  // ─── Checkout: a slot held until the conclusion ────────────────────────
+  /**
+   * 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.
+   */
+  async holdForCheckout(input) {
+    const holds = this.requireHolds();
+    const offerId = input.checkoutOfferId;
+    await this.lazyExpire();
+    const promo = await this.findWithLiveHolds(input.code.trim().toUpperCase(), /* @__PURE__ */ new Date());
+    for (let attempt = 0; attempt < HOLD_ATTEMPTS; attempt += 1) {
+      const own = await holds.findByCheckoutOffer(offerId);
+      const ownSlot = own !== null && own.promoCodeId === promo?.id;
+      const held = ownSlot && own.expiresAt > /* @__PURE__ */ new Date();
+      const verdict = await this.judge(promo, input, {
+        ownSlot,
+        held,
+        countSlots: true
+      });
+      if (verdict.reason !== null) throw notRedeemable(verdict.reason);
+      const promoCodeId = verdict.promo.id;
+      if (ownSlot && await holds.extend(offerId, promoCodeId, input.until)) return;
+      if (own && !ownSlot) await holds.release(offerId);
+      const taken = await holds.take({
+        promoCodeId,
+        checkoutOfferId: offerId,
+        expiresAt: input.until
+      });
+      if (taken.outcome === "taken") return;
+      if (taken.outcome === "no-slot") throw notRedeemable(await this.whyNoSlot(promoCodeId));
+    }
+    throw new ConflictException({
+      code: CONTRACT_ERROR_CODES.CHECKOUT_OFFER_CHANGED,
+      message: `Checkout offer '${offerId}' changed while its promo code was being held. Load it again.`,
+      params: {
+        offerId
+      }
+    });
+  }
+  /** Gives back the slot a checkout offer holds, if it holds one. */
+  async releaseCheckoutHold(checkoutOfferId, tx) {
+    await this.holds?.release(checkoutOfferId, tx);
+  }
+  /**
+   * 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.
+   */
+  async releaseCheckoutHoldIfUnmoved(checkoutOfferId, expiresAt) {
+    await this.holds?.releaseIfUnmoved(checkoutOfferId, expiresAt);
+  }
+  /**
+   * 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.
+   */
+  async handOverCheckoutHold(checkoutOfferId, tx) {
+    return await this.holds?.handOver(checkoutOfferId, /* @__PURE__ */ new Date(), tx) ?? false;
+  }
+  // ─── Onboarding path: atomic redemption ────────────────────────────────
+  /**
+   * 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).
+   */
+  async redeem(input) {
+    return this.transactionRunner.run((tx) => this.redeemInTransaction(input, tx));
+  }
+  /**
+   * 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.
+   */
+  async redeemInTransaction(input, tx) {
+    const code = input.code.trim().toUpperCase();
+    const promo = await this.promoRepo.findByCode(code, tx);
+    if (!promo || promo.deletedAt) {
+      throw new BadRequestException2({
+        code: PROMO_ERROR_CODES2.PROMO_CODE_NOT_FOUND,
+        // The lookup runs on the code string, so there is no id to report.
+        message: "Code not found",
+        params: {
+          promoCodeId: null,
+          promoCode: code
+        }
+      });
+    }
+    const sub = await this.subscriptionLookup.findById(input.subscriptionId, tx);
+    if (!sub) {
+      throw new NotFoundException({
+        code: BILLING_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,
+        message: "Subscription not found",
+        params: {
+          tenantId: input.tenantId
+        }
+      });
+    }
+    if (sub.tenantId !== input.tenantId) {
+      throw new BadRequestException2({
+        code: BILLING_ERROR_CODES.SUBSCRIPTION_TENANT_MISMATCH,
+        message: "Subscription does not belong to the tenant",
+        params: {
+          subscriptionId: sub.id,
+          tenantId: input.tenantId
+        }
+      });
+    }
+    const held = await this.holds?.convertHandedOver(promo.id, tx) ?? false;
+    const verdict = await this.judge(promo, {
+      code,
+      planId: sub.plan,
+      billingCycle: sub.billingCycle,
+      email: input.email
+    }, {
+      held,
+      countSlots: false,
+      requireEmail: true
+    });
+    if (verdict.reason !== null) throw notRedeemable(verdict.reason);
+    if (!held) {
+      await this.holds?.expireDue(/* @__PURE__ */ new Date(), promo.id, tx);
+      if (!await this.promoRepo.claimSlot(promo.id, tx)) {
+        throw notRedeemable("EXHAUSTED");
+      }
+    }
+    await this.promoRepo.markExhaustedIfFull(promo.id, tx);
+    const startsAt = sub.startedAt ?? /* @__PURE__ */ new Date();
+    const endsAt = promo.durationType === "ONCE" ? null : computeRegularStartsAt(startsAt, sub.billingCycle, promo.durationType, promo.durationValue);
+    return this.redemptionRepo.create({
+      promoCodeId: promo.id,
+      subscriptionId: sub.id,
+      tenantId: sub.tenantId,
+      appliedValueType: promo.valueType,
+      appliedValue: appliedValue(promo, verdict.planGross),
+      appliedDurationType: promo.durationType,
+      appliedDurationValue: promo.durationValue,
+      startsAt,
+      endsAt
+    }, tx);
+  }
+  async reverse(subscriptionId) {
+    return this.transactionRunner.run(async (tx) => {
+      const redemption = await this.redemptionRepo.findBySubscription(subscriptionId, tx);
+      if (!redemption || redemption.status !== "ACTIVE") return redemption;
+      const updated = await this.redemptionRepo.setReversed(redemption.id, tx);
+      await this.promoRepo.releaseSlot(redemption.promoCodeId, tx);
+      return updated;
+    });
+  }
+  // ─── Helpers ───────────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async judge(promo, input, options) {
+    const refused = this.checkCode(promo, input, options);
+    if (refused) return {
+      reason: refused
+    };
+    const found = promo;
+    const catalog = await this.planCatalogs.current();
+    const reason = this.checkPlanPrice(found, input, catalog) ?? await this.checkFirstTimeCustomer(found, input.email, options);
+    if (reason) return {
+      reason
+    };
+    const planGross = getPlanPriceGross(catalog, input.planId, input.billingCycle);
+    const discount = discountOnPlan(found, planGross);
+    if (discount.zeroInvoice) return {
+      reason: "WOULD_PRODUCE_ZERO_INVOICE"
+    };
+    return {
+      reason: null,
+      promo: found,
+      catalog,
+      planGross,
+      discount
+    };
+  }
+  /** Everything about a code that needs no plan price: its state, its slots, and the plans it fits. */
+  checkCode(promo, input, options) {
+    if (!promo || promo.deletedAt) return "NOT_FOUND";
+    if (!options.held) {
+      const state = this.checkState(promo) ?? (options.countSlots ? checkFreeSlot(promo, options.ownSlot === true) : null);
+      if (state) return state;
+    }
+    const blocked = this.config.nonRedeemablePlans ?? [];
+    if (blocked.includes(input.planId)) {
+      return "PLAN_MISMATCH";
+    }
+    if (promo.appliesToPlans.length > 0 && !promo.appliesToPlans.includes(input.planId)) {
+      return "PLAN_MISMATCH";
+    }
+    if (promo.appliesToBilling && promo.appliesToBilling !== input.billingCycle) {
+      return "BILLING_MISMATCH";
+    }
+    return null;
+  }
+  /** Whether the code can be used now at all: its status and its validity window. */
+  checkState(promo) {
+    if (promo.status === "EXPIRED") return "EXPIRED";
+    if (promo.status === "EXHAUSTED") return "EXHAUSTED";
+    if (promo.status === "PAUSED") return "PAUSED";
+    const now = /* @__PURE__ */ new Date();
+    if (promo.validFrom && promo.validFrom > now) return "EXPIRED";
+    if (promo.validUntil && promo.validUntil < now) return "EXPIRED";
+    return null;
+  }
+  /** Whether the plan is sold at a price in this rhythm, and one the code's minimum allows. */
+  checkPlanPrice(promo, input, catalog) {
+    const planGross = getPlanPriceGross(catalog, input.planId, input.billingCycle);
+    if (planGross == null) return "PLAN_MISMATCH";
+    if (promo.minimumPlanAmountGross && planGross < Number(promo.minimumPlanAmountGross)) {
+      return "BELOW_MINIMUM_AMOUNT";
+    }
+    return null;
+  }
+  async checkFirstTimeCustomer(promo, email, options = {}) {
+    if (!promo || !promo.firstTimeCustomersOnly) return null;
+    if (!email) return options.requireEmail ? "NOT_FIRST_TIME_CUSTOMER" : null;
+    const existing = await this.firstTimeCheck.hasExistingCustomerForEmail(email);
+    return existing ? "NOT_FIRST_TIME_CUSTOMER" : null;
+  }
+  /**
+   * Lazy expiry: sets codes whose validUntil has passed to EXPIRED.
+   * Called before every find/preview — defense-in-depth alongside the cron.
+   */
+  async lazyExpire() {
+    const now = /* @__PURE__ */ new Date();
+    await this.promoRepo.expireDueCodes(now);
+    await this.redemptionRepo.expireDueRedemptions(now);
+  }
+  /**
+   * 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.
+   */
+  async findWithLiveHolds(code, now) {
+    const promo = await this.promoRepo.findByCode(code);
+    if (!promo || !this.holds) return promo;
+    const ended = await this.holds.expireDue(now, promo.id);
+    return ended > 0 ? this.promoRepo.findByCode(code) : promo;
+  }
+  /**
+   * 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.
+   */
+  async whyNoSlot(promoCodeId) {
+    const now = await this.promoRepo.findById(promoCodeId);
+    if (!now || now.deletedAt) return "NOT_FOUND";
+    return this.checkState(now) ?? "EXHAUSTED";
+  }
+  /** Whether the checkout offer holds a slot of this code that has not expired. */
+  async holdsLiveSlot(checkoutOfferId, promo, now) {
+    const hold = await this.holds?.findByCheckoutOffer(checkoutOfferId);
+    return hold != null && hold.promoCodeId === promo.id && hold.expiresAt > now;
+  }
+  /** The slots of a code held right now, its expired holds given back first. */
+  async liveHeldCount(promoCodeId) {
+    if (!this.holds) return 0;
+    await this.holds.expireDue(/* @__PURE__ */ new Date(), promoCodeId);
+    return (await this.promoRepo.findById(promoCodeId))?.heldCount ?? 0;
+  }
+  requireHolds() {
+    if (!this.holds) {
+      throw new Error("Holding a promo code for a checkout needs a PromoCodeHoldRepository: the shipped persistence bundles provide one as `promo.holdRepository`; pass it to PromoCodesModule.forRoot as `holdRepository` when wiring the module by hand.");
+    }
+    return this.holds;
+  }
+  ruleContext() {
+    return {
+      nonRedeemablePlans: this.config.nonRedeemablePlans ?? [],
+      lowestApplicablePlanGross: /* @__PURE__ */ __name(async (plans) => this.lowestApplicablePlanGross(await this.planCatalogs.current(), plans), "lowestApplicablePlanGross")
+    };
+  }
+  /**
+   * 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).
+   */
+  lowestApplicablePlanGross(catalog, plans) {
+    const blocked = new Set(this.config.nonRedeemablePlans ?? []);
+    const candidates = plans.length > 0 ? plans : (catalog.plans ?? []).filter((p) => p.marketed !== false && !blocked.has(p.id)).map((p) => p.id);
+    let min = null;
+    for (const p of candidates) {
+      const g = getPlanPriceGross(catalog, p, "MONTHLY");
+      if (g == null) continue;
+      if (min == null || g < min) min = g;
+    }
+    return min;
+  }
+};
+PromoCodesService = _ts_decorate([
+  Injectable(),
+  _ts_param(0, Inject(PROMO_CODE_REPOSITORY_TOKEN)),
+  _ts_param(1, Inject(PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN)),
+  _ts_param(2, Inject(PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN)),
+  _ts_param(3, Inject(PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN)),
+  _ts_param(4, Inject(PROMO_SUBSCRIPTION_LOOKUP_TOKEN)),
+  _ts_param(5, Inject(PROMO_REVENUE_DEDUCTION_AGGREGATOR_TOKEN)),
+  _ts_param(6, Inject(PROMO_TRANSACTION_RUNNER_TOKEN)),
+  _ts_param(7, Inject(PLAN_CATALOG_SOURCE_TOKEN)),
+  _ts_param(8, Inject(PROMO_SERVICE_CONFIG_TOKEN)),
+  _ts_param(9, Optional()),
+  _ts_param(9, Inject(PROMO_CODE_HOLD_REPOSITORY_TOKEN)),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof PromoCodeRepository === "undefined" ? Object : PromoCodeRepository,
+    typeof PromoCodeRedemptionRepository === "undefined" ? Object : PromoCodeRedemptionRepository,
+    typeof PromoCodeValidationLogRepository === "undefined" ? Object : PromoCodeValidationLogRepository,
+    typeof FirstTimeCustomerCheck === "undefined" ? Object : FirstTimeCustomerCheck,
+    typeof PromoSubscriptionLookup === "undefined" ? Object : PromoSubscriptionLookup,
+    typeof PromoRevenueDeductionAggregator === "undefined" ? Object : PromoRevenueDeductionAggregator,
+    typeof TransactionRunner === "undefined" ? Object : TransactionRunner,
+    typeof PlanCatalogSource === "undefined" ? Object : PlanCatalogSource,
+    typeof PromoServiceConfig === "undefined" ? Object : PromoServiceConfig,
+    Object
+  ])
+], PromoCodesService);
+function checkFreeSlot(promo, ownSlot) {
+  if (promo.maxRedemptions == null) return null;
+  const taken = promo.redemptionsCount + promo.heldCount - (ownSlot ? 1 : 0);
+  return taken >= promo.maxRedemptions ? "EXHAUSTED" : null;
+}
+__name(checkFreeSlot, "checkFreeSlot");
+function termsAfter(existing, change) {
+  const kept = /* @__PURE__ */ __name((changed, current) => changed !== void 0 ? changed : current, "kept");
+  return {
+    valueType: kept(change.valueType, existing.valueType),
+    value: kept(change.value, Number(existing.value)),
+    durationType: kept(change.durationType, existing.durationType),
+    durationValue: kept(change.durationValue, existing.durationValue),
+    validFrom: kept(change.validFrom, existing.validFrom),
+    validUntil: kept(change.validUntil, existing.validUntil),
+    appliesToPlans: kept(change.appliesToPlans, existing.appliesToPlans),
+    minimumPlanAmountGross: kept(change.minimumPlanAmountGross, existing.minimumPlanAmountGross == null ? null : Number(existing.minimumPlanAmountGross)),
+    allowZeroInvoice: kept(change.allowZeroInvoice, existing.allowZeroInvoice)
+  };
+}
+__name(termsAfter, "termsAfter");
+
+export {
+  computeDiscountGross,
+  computeDiscountedGross,
+  computeRegularStartsAt,
+  addCycles,
+  buildLabel,
+  PROMO_CODE_REPOSITORY_TOKEN,
+  PROMO_CODE_HOLD_REPOSITORY_TOKEN,
+  PROMO_CODE_REDEMPTION_REPOSITORY_TOKEN,
+  PROMO_CODE_VALIDATION_LOG_REPOSITORY_TOKEN,
+  PROMO_FIRST_TIME_CUSTOMER_CHECK_TOKEN,
+  PROMO_SUBSCRIPTION_LOOKUP_TOKEN,
+  PROMO_REVENUE_DEDUCTION_AGGREGATOR_TOKEN,
+  PROMO_TRANSACTION_RUNNER_TOKEN,
+  PROMO_SERVICE_CONFIG_TOKEN,
+  CODE_MIN_LENGTH,
+  CODE_MAX_LENGTH,
+  CODE_PATTERN,
+  PromoCodesService
+};