@saasicat/core 1.0.0-rc.13 → 1.0.0-rc.15

package/dist/.build-stamp

@@ -1 +1 @@
-80e103efbcf415693ffe96c49f6aae0ba7201fb0aa4cac7b47004cd3d69fb3cc
+785f84b789c4fbc325a4d35f81dec979a2575832412363bbcf2fbbe87995e875

package/dist/index.cjs

@@ -543,6 +543,11 @@ var BILLING_ERROR_CODES = {
   PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG",
   /** Plan exists but cannot be booked via self-service. */
   PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE",
+  /**
+   * Plan carries no price for the requested billing cycle, so it is not sold
+   * in it: a plan without a yearly price is a monthly plan.
+   */
+  PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE",
   /** Plan change refused. Carries `blockers[]` with their own codes. */
   PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED",
   /**
@@ -651,6 +656,7 @@ var CONTRACT_ERROR_CODES = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START",
   // ── stage 3 ──
@@ -658,6 +664,12 @@ var CONTRACT_ERROR_CODES = {
   CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED",
   CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED",
+  /**
+   * The offer changed between the checks of `conclude` and the transaction
+   * that consumed it, so the contract checked is not the one the offer now
+   * describes. Nothing was written; load the offer and conclude it again.
+   */
+  CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED"
@@ -1081,6 +1093,7 @@ var ERROR_MESSAGES_EN = {
   NO_ACTIVE_PLAN_VERSION: "No plan version for {planId} active as of {asOf} \u2014 neither the validFrom window is satisfied nor is a latest-live version available.",
   PLAN_NOT_IN_CATALOG: 'Plan "{planKey}" is not in the catalog',
   PLAN_NOT_SELF_SERVICE: "{planName} is only activated via a special contract. Please contact the contract manager.",
+  PLAN_NOT_SOLD_IN_CYCLE: "{planName} has no price for this billing rhythm and cannot be booked in it.",
   PLAN_CHANGE_BLOCKED: "Plan change during onboarding is blocked.",
   SUBSCRIPTION_CHANGED: "This subscription changed while the request was being decided. Reload it.",
   NO_SUBSCRIPTION: "This tenant has no subscription to cancel.",
@@ -1133,12 +1146,14 @@ var ERROR_MESSAGES_EN = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "{field} must be a valid date.",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "effectiveUntil must be after effectiveFrom.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "A line item's taxAmount must be exactly priceGross minus priceNet.",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "A subscription contract states a tax rate of {taxRate} at {field}, which is not a percentage: a rate lies from 0 to 100, and a value between 0 and 1 is refused as a fraction.",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "effectiveUntil must be after the effectiveFrom of the contract.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "A line item must be booked in the currency its contract was priced in.",
   CHECKOUT_OFFER_NOT_FOUND: "CheckoutOffer '{offerId}' not found",
   CHECKOUT_OFFER_EXPIRED: "Checkout offer '{offerId}' has expired and cannot be {action}",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "Checkout offer '{offerId}' has already been consumed and cannot be {action}",
   CHECKOUT_OFFER_NOT_CONSUMED: "CheckoutOffer '{offerId}' must be consumed before the contract is created",
+  CHECKOUT_OFFER_CHANGED: "Checkout offer '{offerId}' changed while it was being concluded. Load it again.",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SubscriptionContract '{contractId}' not found",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "No active subscription contract for tenant {tenantId}",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SubscriptionContract '{contractId}' is already closed",
@@ -1268,6 +1283,7 @@ var ERROR_MESSAGES_DE = {
   NO_ACTIVE_PLAN_VERSION: "Zum {asOf} ist keine Planversion f\xFCr {planId} aktiv \u2014 weder ist das validFrom-Fenster erf\xFCllt, noch steht eine j\xFCngste Live-Version bereit.",
   PLAN_NOT_IN_CATALOG: 'Plan "{planKey}" steht nicht im Katalog',
   PLAN_NOT_SELF_SERVICE: "{planName} wird nur \xFCber einen Sondervertrag freigeschaltet. Bitte wenden Sie sich an die Vertragsverwaltung.",
+  PLAN_NOT_SOLD_IN_CYCLE: "{planName} hat f\xFCr diesen Abrechnungsrhythmus keinen Preis und kann darin nicht gebucht werden.",
   PLAN_CHANGE_BLOCKED: "W\xE4hrend des Onboardings ist ein Planwechsel gesperrt.",
   SUBSCRIPTION_CHANGED: "Dieses Abonnement hat sich ge\xE4ndert, w\xE4hrend die Anfrage entschieden wurde. Bitte lade es neu.",
   NO_SUBSCRIPTION: "Dieser Mandant hat kein Abonnement, das gek\xFCndigt werden kann.",
@@ -1320,12 +1336,14 @@ var ERROR_MESSAGES_DE = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "{field} muss ein g\xFCltiges Datum sein.",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "effectiveUntil muss nach effectiveFrom liegen.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "taxAmount einer Position muss exakt priceGross minus priceNet sein.",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "Ein Abo-Vertrag nennt bei {field} einen Steuersatz von {taxRate}, der kein Prozentsatz ist: Ein Satz liegt zwischen 0 und 100, und ein Wert zwischen 0 und 1 wird als Bruch abgelehnt.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "Eine Position muss in der W\xE4hrung gebucht sein, in der ihr Vertrag bepreist ist.",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "effectiveUntil muss nach dem effectiveFrom des Vertrags liegen.",
   CHECKOUT_OFFER_NOT_FOUND: "CheckoutOffer '{offerId}' nicht gefunden",
   CHECKOUT_OFFER_EXPIRED: "Checkout-Angebot '{offerId}' ist abgelaufen \u2014 '{action}' ist nicht mehr m\xF6glich",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "Checkout-Angebot '{offerId}' wurde bereits eingel\xF6st \u2014 '{action}' ist nicht mehr m\xF6glich",
   CHECKOUT_OFFER_NOT_CONSUMED: "CheckoutOffer '{offerId}' muss eingel\xF6st sein, bevor der Vertrag entsteht",
+  CHECKOUT_OFFER_CHANGED: "Checkout-Angebot '{offerId}' hat sich w\xE4hrend des Abschlusses ge\xE4ndert. Bitte neu laden.",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SubscriptionContract '{contractId}' nicht gefunden",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "Kein aktiver Abo-Vertrag f\xFCr Mandant {tenantId}",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SubscriptionContract '{contractId}' ist bereits geschlossen",

package/dist/index.d.cts

@@ -2003,6 +2003,11 @@ interface PromoPreviewValidResponse {
         /** Decimal-as-string, e.g. "199.00". */
         originalGross: string;
         discountGross: string;
+        /**
+         * `discountGross` in net, converted at the installation's VAT rate —
+         * the figure a page showing net prices takes off the plan price.
+         */
+        discountNet: string;
         discountedGross: string;
         includedVat: string;
         nextRegularAmountGross: string;
@@ -2821,16 +2826,8 @@ interface SubscriptionContractPriceSnapshot {
     discountNet: number;
     totalNet: number;
     /**
-     * The rate this contract's total was computed at — in per cent where the
-     * contract was frozen from the catalogue, and as the offer stated it where
-     * it was concluded from one.
-     *
-     * A checkout offer prices its lines as `net * (1 + vatRate)`, so it states
-     * a fraction, and the value is copied here as it stands. The field
-     * therefore carries both units across a history and cannot be compared
-     * across contracts. `ContractLineItemRecord.taxRate` is always per cent and
-     * is the one to read; this is kept as written because it is the record of
-     * what the contract was concluded with.
+     * The tax rate this contract's total was computed at, as a percentage:
+     * 19 means 19 %, as every tax rate in SaaSiCat is.
      */
     vatRate: number;
     totalGross: number;
@@ -3088,7 +3085,15 @@ interface SubscriptionContractRepository {
      * instead of drawing an extra pool connection (starvation guard, #70).
      */
     findActiveByTenantId(tenantId: string, asOf?: Date, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
-    create(data: CreateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+    /** With `tx`, the contract is written on that transaction and undone with it. */
+    create(data: CreateSubscriptionContractData, tx?: TransactionContext): Promise<SubscriptionContractRecord>;
+    /**
+     * The contract concluded from a checkout offer (`originalOfferId`), or
+     * `null` when none was. An offer is consumed once and so yields one
+     * contract (`SC-MKT-017`); where an application's own path wrote two, the
+     * earliest is returned, so the answer does not depend on read order.
+     */
+    findByOriginalOfferId(offerId: string, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
     terminate(contractId: string, data: TerminateSubscriptionContractData): Promise<SubscriptionContractRecord>;
 }
 /**
@@ -3404,6 +3409,8 @@ interface PlanVersionRepository {
      *
      * Note: ignores `validFrom`/`validUntil`. For time-aware
      * resolution (onboarding, plan fallback for TRIAL) use `findActive`.
+     *
+     * A plan key no plan has finds `null`, not an error.
      */
     findLatestLive(planId: string, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
     /**
@@ -3416,6 +3423,8 @@ interface PlanVersionRepository {
      * return the highest `validFrom`, explicitly ordering null start dates
      * last as a legacy fallback. Adapters without validity columns may omit
      * the method (consumers fall back to `findLatestLive`).
+     *
+     * A plan key no plan has finds `null`, not an error.
      */
     findActive?(planId: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
 }
@@ -4029,8 +4038,19 @@ interface CheckoutOfferRepository {
     findById(id: string): Promise<CheckoutOfferRow | null>;
     create(data: CreateCheckoutOfferData): Promise<CheckoutOfferRow>;
     update(id: string, data: UpdateCheckoutOfferData): Promise<CheckoutOfferRow>;
-    /** Sets `status = 'consumed'` + `consumedAt = NOW()`. */
-    consume(id: string): Promise<CheckoutOfferRow>;
+    /**
+     * Sets `status = 'consumed'` + `consumedAt = NOW()`, and only while the
+     * offer is still `open`: the write carries that condition, so of two
+     * callers consuming at once one succeeds and the other is refused with
+     * `CHECKOUT_OFFER_ALREADY_CONSUMED` (or `CHECKOUT_OFFER_EXPIRED`). A check
+     * before the write cannot decide it, because the status can change in
+     * between.
+     *
+     * With `tx`, the write runs on that transaction, so it is undone with
+     * everything else the transaction wrote. `CheckoutOfferService.conclude`
+     * depends on that; the persistence contract holds both.
+     */
+    consume(id: string, tx?: TransactionContext): Promise<CheckoutOfferRow>;
 }
 
 /** Which changes to list. */
@@ -4351,6 +4371,11 @@ declare const BILLING_ERROR_CODES: {
     readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
     /** Plan exists but cannot be booked via self-service. */
     readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /**
+     * Plan carries no price for the requested billing cycle, so it is not sold
+     * in it: a plan without a yearly price is a monthly plan.
+     */
+    readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -4448,12 +4473,19 @@ declare const CONTRACT_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
     readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH";
+    readonly SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH";
     readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
     readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
     readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
     readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
     readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    /**
+     * The offer changed between the checks of `conclude` and the transaction
+     * that consumed it, so the contract checked is not the one the offer now
+     * describes. Nothing was written; load the offer and conclude it again.
+     */
+    readonly CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED";
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
@@ -4562,12 +4594,19 @@ declare const PLATFORM_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
     readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH";
+    readonly SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH";
     readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
     readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
     readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
     readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
     readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    /**
+     * The offer changed between the checks of `conclude` and the transaction
+     * that consumed it, so the contract checked is not the one the offer now
+     * describes. Nothing was written; load the offer and conclude it again.
+     */
+    readonly CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED";
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
@@ -4595,6 +4634,11 @@ declare const PLATFORM_ERROR_CODES: {
     readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
     /** Plan exists but cannot be booked via self-service. */
     readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /**
+     * Plan carries no price for the requested billing cycle, so it is not sold
+     * in it: a plan without a yearly price is a monthly plan.
+     */
+    readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -5186,8 +5230,6 @@ interface ConfiguratorModel {
     popular?: boolean;
 }
 interface ConfiguratorCatalog {
-    /** Factor `yearlyNet = monthlyNet * cycleDiscount` (typically 10 = 2 months free). */
-    cycleDiscount: number;
     currency: string;
     vatRate: number;
     models: ConfiguratorModel[];
@@ -5212,6 +5254,10 @@ interface ConfiguratorPriceBreakdown {
     modelMonthlyNet: number;
     subtotalMonthlyNet: number;
     subtotalNet: number;
+    /**
+     * Net amount taken off `subtotalNet`: the promo preview's gross discount
+     * converted at `vatRate`.
+     */
     discountAmount: number;
     totalNet: number;
     vatRate: number;
@@ -5288,8 +5334,6 @@ interface ConfiguratorPlanMarketing {
  */
 interface ConfiguratorMarketingProvider {
     listPlanMarketing(): ConfiguratorPlanMarketing[];
-    /** Factor `yearlyNet = monthlyNet * cycleDiscount`. Default `10`. */
-    getCycleDiscount(): number;
     getVatRate(): number;
     getCurrency(): string;
 }
@@ -5310,6 +5354,7 @@ interface RegistrationPromoPreview {
         reason?: string;
         percent?: number;
         label?: string;
+        /** The discount in gross, reckoned against `subtotalGross`. */
         discountAmount?: number;
     }>;
 }

package/dist/index.d.ts

@@ -2003,6 +2003,11 @@ interface PromoPreviewValidResponse {
         /** Decimal-as-string, e.g. "199.00". */
         originalGross: string;
         discountGross: string;
+        /**
+         * `discountGross` in net, converted at the installation's VAT rate —
+         * the figure a page showing net prices takes off the plan price.
+         */
+        discountNet: string;
         discountedGross: string;
         includedVat: string;
         nextRegularAmountGross: string;
@@ -2821,16 +2826,8 @@ interface SubscriptionContractPriceSnapshot {
     discountNet: number;
     totalNet: number;
     /**
-     * The rate this contract's total was computed at — in per cent where the
-     * contract was frozen from the catalogue, and as the offer stated it where
-     * it was concluded from one.
-     *
-     * A checkout offer prices its lines as `net * (1 + vatRate)`, so it states
-     * a fraction, and the value is copied here as it stands. The field
-     * therefore carries both units across a history and cannot be compared
-     * across contracts. `ContractLineItemRecord.taxRate` is always per cent and
-     * is the one to read; this is kept as written because it is the record of
-     * what the contract was concluded with.
+     * The tax rate this contract's total was computed at, as a percentage:
+     * 19 means 19 %, as every tax rate in SaaSiCat is.
      */
     vatRate: number;
     totalGross: number;
@@ -3088,7 +3085,15 @@ interface SubscriptionContractRepository {
      * instead of drawing an extra pool connection (starvation guard, #70).
      */
     findActiveByTenantId(tenantId: string, asOf?: Date, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
-    create(data: CreateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+    /** With `tx`, the contract is written on that transaction and undone with it. */
+    create(data: CreateSubscriptionContractData, tx?: TransactionContext): Promise<SubscriptionContractRecord>;
+    /**
+     * The contract concluded from a checkout offer (`originalOfferId`), or
+     * `null` when none was. An offer is consumed once and so yields one
+     * contract (`SC-MKT-017`); where an application's own path wrote two, the
+     * earliest is returned, so the answer does not depend on read order.
+     */
+    findByOriginalOfferId(offerId: string, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
     terminate(contractId: string, data: TerminateSubscriptionContractData): Promise<SubscriptionContractRecord>;
 }
 /**
@@ -3404,6 +3409,8 @@ interface PlanVersionRepository {
      *
      * Note: ignores `validFrom`/`validUntil`. For time-aware
      * resolution (onboarding, plan fallback for TRIAL) use `findActive`.
+     *
+     * A plan key no plan has finds `null`, not an error.
      */
     findLatestLive(planId: string, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
     /**
@@ -3416,6 +3423,8 @@ interface PlanVersionRepository {
      * return the highest `validFrom`, explicitly ordering null start dates
      * last as a legacy fallback. Adapters without validity columns may omit
      * the method (consumers fall back to `findLatestLive`).
+     *
+     * A plan key no plan has finds `null`, not an error.
      */
     findActive?(planId: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
 }
@@ -4029,8 +4038,19 @@ interface CheckoutOfferRepository {
     findById(id: string): Promise<CheckoutOfferRow | null>;
     create(data: CreateCheckoutOfferData): Promise<CheckoutOfferRow>;
     update(id: string, data: UpdateCheckoutOfferData): Promise<CheckoutOfferRow>;
-    /** Sets `status = 'consumed'` + `consumedAt = NOW()`. */
-    consume(id: string): Promise<CheckoutOfferRow>;
+    /**
+     * Sets `status = 'consumed'` + `consumedAt = NOW()`, and only while the
+     * offer is still `open`: the write carries that condition, so of two
+     * callers consuming at once one succeeds and the other is refused with
+     * `CHECKOUT_OFFER_ALREADY_CONSUMED` (or `CHECKOUT_OFFER_EXPIRED`). A check
+     * before the write cannot decide it, because the status can change in
+     * between.
+     *
+     * With `tx`, the write runs on that transaction, so it is undone with
+     * everything else the transaction wrote. `CheckoutOfferService.conclude`
+     * depends on that; the persistence contract holds both.
+     */
+    consume(id: string, tx?: TransactionContext): Promise<CheckoutOfferRow>;
 }
 
 /** Which changes to list. */
@@ -4351,6 +4371,11 @@ declare const BILLING_ERROR_CODES: {
     readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
     /** Plan exists but cannot be booked via self-service. */
     readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /**
+     * Plan carries no price for the requested billing cycle, so it is not sold
+     * in it: a plan without a yearly price is a monthly plan.
+     */
+    readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -4448,12 +4473,19 @@ declare const CONTRACT_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
     readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH";
+    readonly SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH";
     readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
     readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
     readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
     readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
     readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    /**
+     * The offer changed between the checks of `conclude` and the transaction
+     * that consumed it, so the contract checked is not the one the offer now
+     * describes. Nothing was written; load the offer and conclude it again.
+     */
+    readonly CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED";
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
@@ -4562,12 +4594,19 @@ declare const PLATFORM_ERROR_CODES: {
     readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
     readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH";
+    readonly SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT";
     readonly SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH";
     readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
     readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
     readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
     readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
     readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    /**
+     * The offer changed between the checks of `conclude` and the transaction
+     * that consumed it, so the contract checked is not the one the offer now
+     * describes. Nothing was written; load the offer and conclude it again.
+     */
+    readonly CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED";
     readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
     readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
     readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
@@ -4595,6 +4634,11 @@ declare const PLATFORM_ERROR_CODES: {
     readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
     /** Plan exists but cannot be booked via self-service. */
     readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /**
+     * Plan carries no price for the requested billing cycle, so it is not sold
+     * in it: a plan without a yearly price is a monthly plan.
+     */
+    readonly PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE";
     /** Plan change refused. Carries `blockers[]` with their own codes. */
     readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
     /**
@@ -5186,8 +5230,6 @@ interface ConfiguratorModel {
     popular?: boolean;
 }
 interface ConfiguratorCatalog {
-    /** Factor `yearlyNet = monthlyNet * cycleDiscount` (typically 10 = 2 months free). */
-    cycleDiscount: number;
     currency: string;
     vatRate: number;
     models: ConfiguratorModel[];
@@ -5212,6 +5254,10 @@ interface ConfiguratorPriceBreakdown {
     modelMonthlyNet: number;
     subtotalMonthlyNet: number;
     subtotalNet: number;
+    /**
+     * Net amount taken off `subtotalNet`: the promo preview's gross discount
+     * converted at `vatRate`.
+     */
     discountAmount: number;
     totalNet: number;
     vatRate: number;
@@ -5288,8 +5334,6 @@ interface ConfiguratorPlanMarketing {
  */
 interface ConfiguratorMarketingProvider {
     listPlanMarketing(): ConfiguratorPlanMarketing[];
-    /** Factor `yearlyNet = monthlyNet * cycleDiscount`. Default `10`. */
-    getCycleDiscount(): number;
     getVatRate(): number;
     getCurrency(): string;
 }
@@ -5310,6 +5354,7 @@ interface RegistrationPromoPreview {
         reason?: string;
         percent?: number;
         label?: string;
+        /** The discount in gross, reckoned against `subtotalGross`. */
         discountAmount?: number;
     }>;
 }

package/dist/index.js

@@ -454,6 +454,11 @@ var BILLING_ERROR_CODES = {
   PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG",
   /** Plan exists but cannot be booked via self-service. */
   PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE",
+  /**
+   * Plan carries no price for the requested billing cycle, so it is not sold
+   * in it: a plan without a yearly price is a monthly plan.
+   */
+  PLAN_NOT_SOLD_IN_CYCLE: "PLAN_NOT_SOLD_IN_CYCLE",
   /** Plan change refused. Carries `blockers[]` with their own codes. */
   PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED",
   /**
@@ -562,6 +567,7 @@ var CONTRACT_ERROR_CODES = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START",
   // ── stage 3 ──
@@ -569,6 +575,12 @@ var CONTRACT_ERROR_CODES = {
   CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED",
   CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED",
+  /**
+   * The offer changed between the checks of `conclude` and the transaction
+   * that consumed it, so the contract checked is not the one the offer now
+   * describes. Nothing was written; load the offer and conclude it again.
+   */
+  CHECKOUT_OFFER_CHANGED: "CHECKOUT_OFFER_CHANGED",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED"
@@ -992,6 +1004,7 @@ var ERROR_MESSAGES_EN = {
   NO_ACTIVE_PLAN_VERSION: "No plan version for {planId} active as of {asOf} \u2014 neither the validFrom window is satisfied nor is a latest-live version available.",
   PLAN_NOT_IN_CATALOG: 'Plan "{planKey}" is not in the catalog',
   PLAN_NOT_SELF_SERVICE: "{planName} is only activated via a special contract. Please contact the contract manager.",
+  PLAN_NOT_SOLD_IN_CYCLE: "{planName} has no price for this billing rhythm and cannot be booked in it.",
   PLAN_CHANGE_BLOCKED: "Plan change during onboarding is blocked.",
   SUBSCRIPTION_CHANGED: "This subscription changed while the request was being decided. Reload it.",
   NO_SUBSCRIPTION: "This tenant has no subscription to cancel.",
@@ -1044,12 +1057,14 @@ var ERROR_MESSAGES_EN = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "{field} must be a valid date.",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "effectiveUntil must be after effectiveFrom.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "A line item's taxAmount must be exactly priceGross minus priceNet.",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "A subscription contract states a tax rate of {taxRate} at {field}, which is not a percentage: a rate lies from 0 to 100, and a value between 0 and 1 is refused as a fraction.",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "effectiveUntil must be after the effectiveFrom of the contract.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "A line item must be booked in the currency its contract was priced in.",
   CHECKOUT_OFFER_NOT_FOUND: "CheckoutOffer '{offerId}' not found",
   CHECKOUT_OFFER_EXPIRED: "Checkout offer '{offerId}' has expired and cannot be {action}",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "Checkout offer '{offerId}' has already been consumed and cannot be {action}",
   CHECKOUT_OFFER_NOT_CONSUMED: "CheckoutOffer '{offerId}' must be consumed before the contract is created",
+  CHECKOUT_OFFER_CHANGED: "Checkout offer '{offerId}' changed while it was being concluded. Load it again.",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SubscriptionContract '{contractId}' not found",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "No active subscription contract for tenant {tenantId}",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SubscriptionContract '{contractId}' is already closed",
@@ -1179,6 +1194,7 @@ var ERROR_MESSAGES_DE = {
   NO_ACTIVE_PLAN_VERSION: "Zum {asOf} ist keine Planversion f\xFCr {planId} aktiv \u2014 weder ist das validFrom-Fenster erf\xFCllt, noch steht eine j\xFCngste Live-Version bereit.",
   PLAN_NOT_IN_CATALOG: 'Plan "{planKey}" steht nicht im Katalog',
   PLAN_NOT_SELF_SERVICE: "{planName} wird nur \xFCber einen Sondervertrag freigeschaltet. Bitte wenden Sie sich an die Vertragsverwaltung.",
+  PLAN_NOT_SOLD_IN_CYCLE: "{planName} hat f\xFCr diesen Abrechnungsrhythmus keinen Preis und kann darin nicht gebucht werden.",
   PLAN_CHANGE_BLOCKED: "W\xE4hrend des Onboardings ist ein Planwechsel gesperrt.",
   SUBSCRIPTION_CHANGED: "Dieses Abonnement hat sich ge\xE4ndert, w\xE4hrend die Anfrage entschieden wurde. Bitte lade es neu.",
   NO_SUBSCRIPTION: "Dieser Mandant hat kein Abonnement, das gek\xFCndigt werden kann.",
@@ -1231,12 +1247,14 @@ var ERROR_MESSAGES_DE = {
   SUBSCRIPTION_CONTRACT_INVALID_DATE: "{field} muss ein g\xFCltiges Datum sein.",
   SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "effectiveUntil muss nach effectiveFrom liegen.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_TAX_MISMATCH: "taxAmount einer Position muss exakt priceGross minus priceNet sein.",
+  SUBSCRIPTION_CONTRACT_TAX_RATE_NOT_PERCENT: "Ein Abo-Vertrag nennt bei {field} einen Steuersatz von {taxRate}, der kein Prozentsatz ist: Ein Satz liegt zwischen 0 und 100, und ein Wert zwischen 0 und 1 wird als Bruch abgelehnt.",
   SUBSCRIPTION_CONTRACT_LINE_ITEM_CURRENCY_MISMATCH: "Eine Position muss in der W\xE4hrung gebucht sein, in der ihr Vertrag bepreist ist.",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "effectiveUntil muss nach dem effectiveFrom des Vertrags liegen.",
   CHECKOUT_OFFER_NOT_FOUND: "CheckoutOffer '{offerId}' nicht gefunden",
   CHECKOUT_OFFER_EXPIRED: "Checkout-Angebot '{offerId}' ist abgelaufen \u2014 '{action}' ist nicht mehr m\xF6glich",
   CHECKOUT_OFFER_ALREADY_CONSUMED: "Checkout-Angebot '{offerId}' wurde bereits eingel\xF6st \u2014 '{action}' ist nicht mehr m\xF6glich",
   CHECKOUT_OFFER_NOT_CONSUMED: "CheckoutOffer '{offerId}' muss eingel\xF6st sein, bevor der Vertrag entsteht",
+  CHECKOUT_OFFER_CHANGED: "Checkout-Angebot '{offerId}' hat sich w\xE4hrend des Abschlusses ge\xE4ndert. Bitte neu laden.",
   SUBSCRIPTION_CONTRACT_NOT_FOUND: "SubscriptionContract '{contractId}' nicht gefunden",
   NO_ACTIVE_SUBSCRIPTION_CONTRACT: "Kein aktiver Abo-Vertrag f\xFCr Mandant {tenantId}",
   SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SubscriptionContract '{contractId}' ist bereits geschlossen",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/core",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.15",
   "description": "TypeScript contracts for SaaSiCat — capabilities, catalogs, subscriptions, entitlements, admin manifests, persistence ports — and the pure domain logic both server and browser run: error catalogues, plan-diff classification, promo arithmetic, feature requirements.",
   "type": "module",
   "main": "./dist/index.cjs",