@saasicat/core 1.0.0-rc.20 → 1.0.0-rc.22

package/dist/index.js

@@ -87,27 +87,33 @@ function pickActivePromo(promotions, targetKey, locale, cycle, today = /* @__PUR
   return matches[0] ?? null;
 }
 function applyPromo(promo, basePrice) {
+  const result = boundedPromo(promo, basePrice);
+  return result && result.discounted < result.original ? result : null;
+}
+function boundedPromo(promo, basePrice) {
   if (!promo || basePrice === null || basePrice === void 0) return null;
   if (promo.type === "percent" && typeof promo.value === "number") {
+    const pct = withinBounds(promo.value, 100);
     return {
       kind: "percent",
-      discounted: Math.round(basePrice * (100 - promo.value)) / 100,
+      discounted: Math.round(basePrice * (100 - pct)) / 100,
       original: basePrice,
-      pct: promo.value
+      pct
     };
   }
   if (promo.type === "amount" && typeof promo.value === "number") {
+    const saved = withinBounds(promo.value, basePrice);
     return {
       kind: "amount",
-      discounted: Math.max(0, basePrice - promo.value),
+      discounted: Math.round((basePrice - saved) * 100) / 100,
       original: basePrice,
-      saved: promo.value
+      saved
     };
   }
-  if (promo.type === "intro" && typeof promo.value === "object") {
+  if (promo.type === "intro" && typeof promo.value === "object" && promo.value !== null) {
     return {
       kind: "intro",
-      discounted: promo.value.price,
+      discounted: withinBounds(promo.value.price, basePrice),
       original: basePrice,
       months: promo.value.months
     };
@@ -117,6 +123,14 @@ function applyPromo(promo, basePrice) {
   }
   return null;
 }
+function withinBounds(value, upper) {
+  return Math.min(Math.max(value, 0), Math.max(upper, 0));
+}
+function promotionOnPrice(promotions, targetKey, locale, cycle, basePrice, today = /* @__PURE__ */ new Date(), targetType = "PLAN") {
+  const promotion = pickActivePromo(promotions, targetKey, locale, cycle, today, targetType);
+  const result = applyPromo(promotion, basePrice);
+  return promotion && result ? { promotion, result } : null;
+}
 
 // src/quota-value.ts
 function readQuotaValue(value) {
@@ -413,6 +427,12 @@ var CATALOG_ERROR_CODES = {
   FEATURE_NOT_FOUND: "FEATURE_NOT_FOUND",
   QUOTA_NOT_FOUND: "QUOTA_NOT_FOUND",
   PROMOTION_NOT_FOUND: "PROMOTION_NOT_FOUND",
+  /**
+   * A promotion's value is not one its type takes: a percentage above 0 and
+   * at most 100, an amount above 0, an intro price of at least 0 for a whole
+   * number of months, or a whole number of free months.
+   */
+  PROMOTION_VALUE_INVALID: "PROMOTION_VALUE_INVALID",
   MARKETING_PROJECTION_NOT_FOUND: "MARKETING_PROJECTION_NOT_FOUND",
   // ── already exists ──
   PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS",
@@ -572,6 +592,13 @@ var CONTRACT_ERROR_CODES = {
   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",
+  /**
+   * The lines do not add up to a total the contract states, counted as often
+   * as each falls due in one period. `field` names the total.
+   */
+  SUBSCRIPTION_CONTRACT_LINES_DO_NOT_ADD_UP: "SUBSCRIPTION_CONTRACT_LINES_DO_NOT_ADD_UP",
+  /** Something that takes money off states a negative amount. */
+  SUBSCRIPTION_CONTRACT_DISCOUNT_NEGATIVE: "SUBSCRIPTION_CONTRACT_DISCOUNT_NEGATIVE",
   SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START",
   // ── stage 3 ──
   CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND",
@@ -684,7 +711,14 @@ var PAYMENT_ERROR_CODES = {
    * A success or cancel URL at an origin `config/saas.yaml#payments.returnUrlOrigins`
    * does not name. Carries `field`.
    */
-  PAYMENT_RETURN_URL_NOT_ALLOWED: "PAYMENT_RETURN_URL_NOT_ALLOWED"
+  PAYMENT_RETURN_URL_NOT_ALLOWED: "PAYMENT_RETURN_URL_NOT_ALLOWED",
+  /**
+   * The gateway failed — unreachable, refusing the account's keys, or
+   * answering with an error — while opening its form or reading a callback
+   * back. Answered with 502; what the gateway answered stays in the server
+   * log.
+   */
+  PAYMENT_GATEWAY_FAILED: "PAYMENT_GATEWAY_FAILED"
 };
 var SETTINGS_ERROR_CODES = {
   /** No recorded change has this id, or the installation keeps no record at all. */
@@ -950,6 +984,83 @@ function textOrNull(value) {
   return trimmed === "" ? null : trimmed;
 }
 
+// src/closed-value.ts
+function oneOf(allowed, value, source) {
+  const match = allowed.find((entry) => entry === value);
+  if (match === void 0) {
+    throw new Error(
+      `${source.table} row '${source.id}' holds ${source.column} '${value}', which is none of ${allowed.join(", ")}.`
+    );
+  }
+  return match;
+}
+
+// src/subscriber-ledger-mapping.ts
+var ORIGINS = {
+  activation: true,
+  renewal: true,
+  planChange: true,
+  bundleBooking: true,
+  credit: true,
+  correction: true
+};
+var SOURCES = {
+  plan: true,
+  bundle: true,
+  discount: true
+};
+var TABLE = "subscriber_ledger_entries";
+var CENT_TOLERANCE = 1e-6;
+function toSubscriberChargeRecord(row) {
+  const where = (column) => ({ table: TABLE, column, id: row.id });
+  return {
+    id: row.id,
+    subscriberId: row.subscriberId,
+    tenantId: row.tenantId,
+    subscriptionId: row.subscriptionId,
+    contractId: row.contractId,
+    contractLineItemId: row.contractLineItemId,
+    origin: oneOf(keysOf(ORIGINS), row.origin, where("origin")),
+    source: oneOf(keysOf(SOURCES), row.source, where("source")),
+    sourceRef: row.sourceRef,
+    periodStart: row.periodStart,
+    periodEnd: row.periodEnd,
+    currency: row.currency,
+    amountNet: Number(row.amountNet),
+    bookedAt: row.bookedAt,
+    createdAt: row.createdAt
+  };
+}
+function subscriberChargeColumns(charge) {
+  const cents = charge.amountNet * 100;
+  if (!Number.isFinite(cents) || Math.abs(cents - Math.round(cents)) > CENT_TOLERANCE) {
+    throw new Error(
+      `A charge of ${charge.amountNet} is not a whole number of cents; round it once where it is derived, before it is written.`
+    );
+  }
+  return {
+    subscriberId: charge.subscriberId,
+    tenantId: charge.tenantId,
+    subscriptionId: charge.subscriptionId,
+    contractId: charge.contractId,
+    contractLineItemId: charge.contractLineItemId,
+    origin: charge.origin,
+    source: charge.source,
+    sourceRef: charge.sourceRef,
+    periodStart: charge.periodStart,
+    periodEnd: charge.periodEnd,
+    currency: charge.currency,
+    amountNet: charge.amountNet.toFixed(2),
+    bookedAt: charge.bookedAt
+  };
+}
+function keysOf(record) {
+  return Object.keys(record);
+}
+
+// src/subscriber-ledger.types.ts
+var SUBSCRIBER_ACCOUNT_CAPABILITY = "charges.read";
+
 // src/subscriber-mapping.ts
 function formatCustomerNumber(prefix, sequence) {
   return `${prefix}${sequence}`;
@@ -1065,6 +1176,7 @@ function toIdentityValues(value) {
 // src/subscriber-payment-method-mapping.ts
 var PAYMENT_METHOD_TYPES = ["card", "sepa_debit"];
 var STATUSES = ["ACTIVE", "REPLACED"];
+var TABLE2 = "subscriber_payment_methods";
 function toSubscriberPaymentMethodRecord(row) {
   return {
     id: row.id,
@@ -1073,7 +1185,7 @@ function toSubscriberPaymentMethodRecord(row) {
     provider: row.provider,
     customerRef: row.customerRef,
     paymentMethodRef: row.paymentMethodRef,
-    type: oneOf(PAYMENT_METHOD_TYPES, row.type, "type", row.id),
+    type: oneOf(PAYMENT_METHOD_TYPES, row.type, { table: TABLE2, column: "type", id: row.id }),
     brand: row.brand,
     last4: row.last4,
     expiryMonth: row.expiryMonth,
@@ -1081,7 +1193,7 @@ function toSubscriberPaymentMethodRecord(row) {
     country: row.country,
     bankCode: row.bankCode,
     mandateReference: row.mandateReference,
-    status: oneOf(STATUSES, row.status, "status", row.id),
+    status: oneOf(STATUSES, row.status, { table: TABLE2, column: "status", id: row.id }),
     confirmedAt: row.confirmedAt,
     replacedAt: row.replacedAt,
     createdAt: row.createdAt
@@ -1105,14 +1217,53 @@ function subscriberPaymentMethodColumns(data) {
     confirmedAt: data.confirmedAt
   };
 }
-function oneOf(allowed, value, column, id) {
-  const match = allowed.find((entry) => entry === value);
-  if (match === void 0) {
-    throw new Error(
-      `subscriber_payment_methods row '${id}' holds ${column} '${value}', which is none of ${allowed.join(", ")}.`
+var FOREIGN_PAYMENT_METHOD_REFERENCE = "FOREIGN_PAYMENT_METHOD_REFERENCE";
+var ForeignPaymentMethodReferenceError = class extends Error {
+  constructor(gatewayAccount, paymentMethodRef) {
+    super(
+      `Payment method '${paymentMethodRef}' of account '${gatewayAccount}' belongs to another subscriber. A reference belongs to exactly one, so it is not handed out.`
     );
+    this.gatewayAccount = gatewayAccount;
+    this.paymentMethodRef = paymentMethodRef;
+    this.name = "ForeignPaymentMethodReferenceError";
   }
-  return match;
+  gatewayAccount;
+  paymentMethodRef;
+  code = FOREIGN_PAYMENT_METHOD_REFERENCE;
+};
+function isForeignPaymentMethodReferenceError(error) {
+  return error instanceof Error && error.code === FOREIGN_PAYMENT_METHOD_REFERENCE;
+}
+function refuseForeignPaymentMethodReference(recorded, subscriberId) {
+  if (recorded.subscriberId === subscriberId) return;
+  throw new ForeignPaymentMethodReferenceError(
+    recorded.gatewayAccount,
+    recorded.paymentMethodRef
+  );
+}
+
+// src/subscription-bundle-mapping.ts
+var BILLING_CYCLES = ["MONTHLY", "YEARLY"];
+function toSubscriptionBundleRecord(row) {
+  const billingCycle = row.billingCycle ?? null;
+  return {
+    id: row.id,
+    subscriptionId: row.subscriptionId,
+    bundleVersionId: row.bundleVersionId,
+    startedAt: row.startedAt,
+    minimumTermEndsAt: row.minimumTermEndsAt,
+    billingCycle: billingCycle === null ? null : oneOf(BILLING_CYCLES, billingCycle, {
+      table: "subscription_bundles",
+      column: "billingCycle",
+      id: row.id
+    }),
+    currentPeriodStart: row.currentPeriodStart ?? null,
+    currentPeriodEnd: row.currentPeriodEnd ?? null,
+    canceledAt: row.canceledAt,
+    canceledEffectiveAt: row.canceledEffectiveAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt
+  };
 }
 
 // src/subscription-contract-mapping.ts
@@ -1324,6 +1475,7 @@ var ERROR_MESSAGES_EN = {
   FEATURE_NOT_FOUND: "Feature '{featureKey}' not found",
   QUOTA_NOT_FOUND: "Quota '{quotaKey}' not found",
   PROMOTION_NOT_FOUND: "Promotion '{promotionId}' not found",
+  PROMOTION_VALUE_INVALID: "The value of a '{type}' promotion is not one its type takes: a percentage above 0 and at most 100, an amount above 0, an intro price of at least 0 for a whole number of months, or a whole number of free months.",
   MARKETING_PROJECTION_NOT_FOUND: "MarketingProjection '{projectionId}' not found",
   PLAN_ALREADY_EXISTS: "Plan '{planKey}' already exists",
   BUNDLE_ALREADY_EXISTS: "Bundle '{bundleKey}' already exists",
@@ -1378,7 +1530,7 @@ var ERROR_MESSAGES_EN = {
   // ── promo ──
   PROMO_CODE_NOT_FOUND: "Code not found",
   PROMO_CODE_ALREADY_EXISTS: "The code already exists.",
-  PROMO_CODE_HAS_REDEMPTIONS: "The code already has redemptions \u2014 it cannot be soft-deleted. Pause it instead.",
+  PROMO_CODE_HAS_REDEMPTIONS: "The code already has redemptions, or checkouts holding one \u2014 it cannot be soft-deleted. Pause it instead.",
   PROMO_CODE_NOT_REDEEMABLE: "Code cannot be redeemed: {reason}",
   PROMO_CODE_FORMAT_INVALID: 'The code may only contain upper-case letters, digits, "-" and "_" (4\u201332 characters).',
   PROMO_PERCENT_OUT_OF_RANGE: "The percentage must be between 0 and 100.",
@@ -1408,6 +1560,8 @@ var ERROR_MESSAGES_EN = {
   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.",
+  SUBSCRIPTION_CONTRACT_LINES_DO_NOT_ADD_UP: "The line items of a subscription contract add up to {lines} for {field}, but the contract states {stated}.",
+  SUBSCRIPTION_CONTRACT_DISCOUNT_NEGATIVE: "A subscription contract states a discount of {amount} at {field}; a discount takes money off and is never negative.",
   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}",
@@ -1447,6 +1601,7 @@ var ERROR_MESSAGES_EN = {
   PAYMENT_GATEWAY_ACCOUNT_UNKNOWN: "No payment gateway account is configured under '{account}'.",
   PAYMENT_CALLBACK_REJECTED: "The payment callback could not be verified.",
   PAYMENT_RETURN_URL_NOT_ALLOWED: "The {field} leads to a site this installation does not return to.",
+  PAYMENT_GATEWAY_FAILED: "The payment provider did not answer as expected. Please try again in a few minutes.",
   // ── entitlement (code lives in upsell.types.ts) ──
   [FEATURE_NOT_LICENSED]: "Feature {featureKeys} is not included in the current plan.",
   // ── settings ──
@@ -1531,6 +1686,7 @@ var ERROR_MESSAGES_DE = {
   FEATURE_NOT_FOUND: "Feature '{featureKey}' nicht gefunden",
   QUOTA_NOT_FOUND: "Quota '{quotaKey}' nicht gefunden",
   PROMOTION_NOT_FOUND: "Promotion '{promotionId}' nicht gefunden",
+  PROMOTION_VALUE_INVALID: "Der Wert einer Aktion vom Typ '{type}' passt nicht zu ihrem Typ: ein Prozentsatz \xFCber 0 und h\xF6chstens 100, ein Betrag \xFCber 0, ein Einf\xFChrungspreis ab 0 f\xFCr eine ganze Zahl von Monaten oder eine ganze Zahl von Gratismonaten.",
   MARKETING_PROJECTION_NOT_FOUND: "MarketingProjection '{projectionId}' nicht gefunden",
   PLAN_ALREADY_EXISTS: "Plan '{planKey}' gibt es bereits",
   BUNDLE_ALREADY_EXISTS: "Bundle '{bundleKey}' gibt es bereits",
@@ -1585,7 +1741,7 @@ var ERROR_MESSAGES_DE = {
   // ── promo ──
   PROMO_CODE_NOT_FOUND: "Code nicht gefunden",
   PROMO_CODE_ALREADY_EXISTS: "Diesen Code gibt es bereits.",
-  PROMO_CODE_HAS_REDEMPTIONS: "Der Code wurde bereits eingel\xF6st \u2014 er l\xE4sst sich nicht per Soft-Delete entfernen. Pausiere ihn stattdessen.",
+  PROMO_CODE_HAS_REDEMPTIONS: "Der Code wurde bereits eingel\xF6st oder ist f\xFCr einen laufenden Checkout reserviert \u2014 er l\xE4sst sich nicht per Soft-Delete entfernen. Pausiere ihn stattdessen.",
   PROMO_CODE_NOT_REDEEMABLE: "Der Code l\xE4sst sich nicht einl\xF6sen: {reason}",
   PROMO_CODE_FORMAT_INVALID: 'Der Code darf nur Gro\xDFbuchstaben, Ziffern, "-" und "_" enthalten (4\u201332 Zeichen).',
   PROMO_PERCENT_OUT_OF_RANGE: "Der Prozentwert muss zwischen 0 und 100 liegen.",
@@ -1614,6 +1770,8 @@ var ERROR_MESSAGES_DE = {
   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_LINES_DO_NOT_ADD_UP: "Die Positionen eines Abo-Vertrags ergeben {lines} f\xFCr {field}, der Vertrag nennt aber {stated}.",
+  SUBSCRIPTION_CONTRACT_DISCOUNT_NEGATIVE: "Ein Abo-Vertrag nennt bei {field} einen Rabatt von {amount}; ein Rabatt zieht Geld ab und ist nie negativ.",
   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",
@@ -1654,6 +1812,7 @@ var ERROR_MESSAGES_DE = {
   PAYMENT_GATEWAY_ACCOUNT_UNKNOWN: "Unter '{account}' ist kein Konto eines Zahlungsanbieters eingerichtet.",
   PAYMENT_CALLBACK_REJECTED: "Die R\xFCckmeldung des Zahlungsanbieters lie\xDF sich nicht pr\xFCfen.",
   PAYMENT_RETURN_URL_NOT_ALLOWED: "Die {field} f\xFChrt auf eine Seite, zu der diese Installation nicht zur\xFCckleitet.",
+  PAYMENT_GATEWAY_FAILED: "Der Zahlungsanbieter hat nicht wie erwartet geantwortet. Bitte versuche es in ein paar Minuten noch einmal.",
   // ── entitlement (code lives in upsell.types.ts) ──
   [FEATURE_NOT_LICENSED]: "Das Feature {featureKeys} ist im aktuellen Plan nicht enthalten.",
   // ── settings ──
@@ -1670,6 +1829,7 @@ export {
   ERROR_MESSAGES_DE,
   ERROR_MESSAGES_EN,
   FEATURE_NOT_LICENSED,
+  ForeignPaymentMethodReferenceError,
   LEGAL_IDENTITY_FIELDS,
   MARKETING_PRIORITY_MAX,
   MARKETING_PRIORITY_MIN,
@@ -1693,6 +1853,7 @@ export {
   REGISTRATION_STEP_BY_STATUS,
   SETTINGS_ERROR_CODES,
   SETUP_ERROR_CODES,
+  SUBSCRIBER_ACCOUNT_CAPABILITY,
   SUBSCRIBER_ERROR_CODES,
   applyPromo,
   assertPersistenceCapabilities,
@@ -1714,6 +1875,7 @@ export {
   formatErrorMessage,
   identityCorrectionDelta,
   isBundleRedundant,
+  isForeignPaymentMethodReferenceError,
   isPaymentCallbackRejectedError,
   isPlatformUserExistsError,
   isVersionEditable,
@@ -1725,15 +1887,18 @@ export {
   planCatalogSettingsOf,
   previousUtcDay,
   promoStatus,
+  promotionOnPrice,
   readQuotaRecord,
   readQuotaValue,
   recordedIssuerIdentity,
+  refuseForeignPaymentMethodReference,
   resolveBundleAvailability,
   resolveErrorMessage,
   sameLegalIdentity,
   selectChargeableBundles,
   settingsSubtreeOf,
   startOfUtcDay,
+  subscriberChargeColumns,
   subscriberFromRegistration,
   subscriberPaymentMethodColumns,
   toBundleStemRow,
@@ -1741,8 +1906,10 @@ export {
   toPlanRow,
   toPlanVersionRow,
   toRunningContractIssuer,
+  toSubscriberChargeRecord,
   toSubscriberCorrectionRecord,
   toSubscriberPaymentMethodRecord,
   toSubscriberRecord,
+  toSubscriptionBundleRecord,
   toSubscriptionContractRecord
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/core",
-  "version": "1.0.0-rc.20",
+  "version": "1.0.0-rc.22",
   "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",