@saasicat/core 1.0.0-rc.21 → 1.0.0-rc.23

package/dist/index.js

@@ -283,6 +283,100 @@ function appendNullableDecimalChange(out, field, oldValue, newValue, polarity) {
   appendDecimalChange(out, field, oldValue, newValue, polarity);
 }
 
+// src/maintenance-window.types.ts
+var MAINTENANCE_MESSAGE_MAX_LENGTH = 500;
+var MAINTENANCE_STATE_MAX_AGE_SECONDS = 5;
+var MAINTENANCE_CAPABILITY = "maintenance.manage";
+
+// src/maintenance-window-mapping.ts
+function toMaintenanceWindowRecord(row) {
+  return {
+    id: row.id,
+    startsAt: row.startsAt,
+    endsAt: row.endsAt,
+    message: row.message,
+    createdAt: row.createdAt,
+    createdBy: row.createdBy,
+    lockedAt: row.lockedAt,
+    lockedBy: row.lockedBy,
+    endedAt: row.endedAt,
+    endedBy: row.endedBy
+  };
+}
+
+// src/maintenance-window-views.ts
+var RETRY_AFTER_WITHOUT_END_SECONDS = 60;
+var iso = (date) => date ? date.toISOString() : null;
+function maintenanceWindowStatusOf(window) {
+  if (window.endedAt) return window.lockedAt ? "ended" : "cancelled";
+  return window.lockedAt ? "locked" : "announced";
+}
+function isMaintenanceOverrun(window, now) {
+  return maintenanceWindowStatusOf(window) === "locked" && window.endsAt !== null && window.endsAt.getTime() <= now.getTime();
+}
+function isMaintenanceAnnouncementLapsed(window, now) {
+  return maintenanceWindowStatusOf(window) === "announced" && window.endsAt !== null && window.endsAt.getTime() <= now.getTime();
+}
+function maintenanceStatusOf(open, now) {
+  if (!open) return { state: "none" };
+  const status = maintenanceWindowStatusOf(open);
+  if (status === "locked" && open.lockedAt) {
+    return {
+      state: "locked",
+      lockedAt: open.lockedAt.toISOString(),
+      endsAt: iso(open.endsAt),
+      message: open.message,
+      overrun: isMaintenanceOverrun(open, now)
+    };
+  }
+  if (status === "announced" && open.startsAt && open.endsAt && !isMaintenanceAnnouncementLapsed(open, now)) {
+    return {
+      state: "announced",
+      startsAt: open.startsAt.toISOString(),
+      endsAt: open.endsAt.toISOString(),
+      message: open.message
+    };
+  }
+  return { state: "none" };
+}
+function maintenanceWindowViewOf(window, now) {
+  return {
+    id: window.id,
+    status: maintenanceWindowStatusOf(window),
+    startsAt: iso(window.startsAt),
+    endsAt: iso(window.endsAt),
+    message: window.message,
+    createdAt: window.createdAt.toISOString(),
+    createdBy: window.createdBy,
+    lockedAt: iso(window.lockedAt),
+    lockedBy: window.lockedBy,
+    endedAt: iso(window.endedAt),
+    endedBy: window.endedBy,
+    overrun: isMaintenanceOverrun(window, now),
+    lapsed: isMaintenanceAnnouncementLapsed(window, now)
+  };
+}
+function maintenanceRetryAfterSeconds(window, now) {
+  if (!window.endsAt || window.endsAt.getTime() <= now.getTime()) {
+    return RETRY_AFTER_WITHOUT_END_SECONDS;
+  }
+  return Math.max(1, Math.ceil((window.endsAt.getTime() - now.getTime()) / 1e3));
+}
+
+// src/zoned-instant.ts
+function endsInOffset(text) {
+  const sign = text.charAt(text.length - 6);
+  return (sign === "+" || sign === "-") && text.charAt(text.length - 3) === ":";
+}
+function parseZonedInstant(text) {
+  const value = text.trim();
+  if (!value.includes("T")) return null;
+  const zoned = value.endsWith("Z") || value.endsWith("z") || endsInOffset(value);
+  if (!zoned) return null;
+  const moment = new Date(value);
+  return Number.isNaN(moment.getTime()) ? null : moment;
+}
+
 // src/settings-subtree.ts
 var CATALOGUE_KEYS = /* @__PURE__ */ new Set([
   "schemaVersion",
@@ -613,7 +707,15 @@ var CONTRACT_ERROR_CODES = {
   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"
+  SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED",
+  /**
+   * A successor would run beside another contract of the tenant: the
+   * contract in force moved while it was being written — another successor
+   * took its place, or a cancellation capped it — and kept moving on a
+   * second attempt, or a contract begins after the moment the successor
+   * would take effect. Nothing was written.
+   */
+  SUBSCRIPTION_CONTRACT_CHANGED: "SUBSCRIPTION_CONTRACT_CHANGED"
 };
 var SUBSCRIBER_ERROR_CODES = {
   /**
@@ -711,12 +813,37 @@ 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. */
   SETTINGS_CHANGE_NOT_FOUND: "SETTINGS_CHANGE_NOT_FOUND"
 };
+var MAINTENANCE_ERROR_CODES = {
+  /** The application is locked for maintenance; the body carries the window. */
+  MAINTENANCE: "MAINTENANCE",
+  /** A window is already open: move or cancel it before announcing another. */
+  MAINTENANCE_WINDOW_ALREADY_OPEN: "MAINTENANCE_WINDOW_ALREADY_OPEN",
+  /** No open window has this id — it ended, or it never existed. */
+  MAINTENANCE_WINDOW_NOT_OPEN: "MAINTENANCE_WINDOW_NOT_OPEN",
+  /** The window is locked: its start is history, and unlocking is what ends it. */
+  MAINTENANCE_WINDOW_LOCKED: "MAINTENANCE_WINDOW_LOCKED",
+  /** The announced end is not after the announced start. */
+  MAINTENANCE_WINDOW_END_NOT_AFTER_START: "MAINTENANCE_WINDOW_END_NOT_AFTER_START",
+  /** The announced end has already passed. */
+  MAINTENANCE_WINDOW_END_IN_PAST: "MAINTENANCE_WINDOW_END_IN_PAST",
+  /** A time without its zone, or not a date and time at all; `field` names which. */
+  MAINTENANCE_TIME_INVALID: "MAINTENANCE_TIME_INVALID",
+  /** The message is longer than `MAINTENANCE_MESSAGE_MAX_LENGTH`. */
+  MAINTENANCE_MESSAGE_TOO_LONG: "MAINTENANCE_MESSAGE_TOO_LONG"
+};
 var PLATFORM_ERROR_CODES = {
   ...SETUP_ERROR_CODES,
   ...AUTH_ERROR_CODES,
@@ -727,7 +854,8 @@ var PLATFORM_ERROR_CODES = {
   ...SUBSCRIBER_ERROR_CODES,
   ...REGISTRATION_ERROR_CODES,
   ...PAYMENT_ERROR_CODES,
-  ...SETTINGS_ERROR_CODES
+  ...SETTINGS_ERROR_CODES,
+  ...MAINTENANCE_ERROR_CODES
 };
 
 // src/errors.ts
@@ -977,6 +1105,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}`;
@@ -1092,6 +1297,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,
@@ -1100,7 +1306,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,
@@ -1108,7 +1314,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
@@ -1132,15 +1338,6 @@ 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(", ")}.`
-    );
-  }
-  return match;
-}
 var FOREIGN_PAYMENT_METHOD_REFERENCE = "FOREIGN_PAYMENT_METHOD_REFERENCE";
 var ForeignPaymentMethodReferenceError = class extends Error {
   constructor(gatewayAccount, paymentMethodRef) {
@@ -1166,6 +1363,30 @@ function refuseForeignPaymentMethodReference(recorded, subscriberId) {
   );
 }
 
+// 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
 function toSubscriptionContractRecord(row, lineItems) {
   return {
@@ -1470,6 +1691,7 @@ var ERROR_MESSAGES_EN = {
   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",
+  SUBSCRIPTION_CONTRACT_CHANGED: "The contracts of tenant '{tenantId}' changed while a successor was being written, or one begins after the moment it would take effect, so it would run beside another. Nothing was written.",
   // ── subscriber ──
   SUBSCRIBER_REQUIRED: "Tenant '{tenantId}' has no subscriber. Nothing is agreed or charged without the party to it: create the tenant's subscriber first.",
   SUBSCRIBER_ALREADY_EXISTS: "Tenant '{tenantId}' already has a subscriber.",
@@ -1501,10 +1723,20 @@ 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 ──
-  SETTINGS_CHANGE_NOT_FOUND: "No recorded settings change has this id."
+  SETTINGS_CHANGE_NOT_FOUND: "No recorded settings change has this id.",
+  // ── maintenance ──
+  MAINTENANCE: "The application is under maintenance.",
+  MAINTENANCE_WINDOW_ALREADY_OPEN: "A maintenance window is already open. Move or cancel it before announcing another.",
+  MAINTENANCE_WINDOW_NOT_OPEN: "No open maintenance window has this id.",
+  MAINTENANCE_WINDOW_LOCKED: "This maintenance window is locked. Its start cannot move, and unlocking is what ends it.",
+  MAINTENANCE_WINDOW_END_NOT_AFTER_START: "The end of a maintenance window has to be after its start.",
+  MAINTENANCE_WINDOW_END_IN_PAST: "The end of a maintenance window cannot be in the past.",
+  MAINTENANCE_TIME_INVALID: "The {field} has to be a date and time with its zone, such as 2026-10-02T22:00+02:00.",
+  MAINTENANCE_MESSAGE_TOO_LONG: "The message may be at most {max} characters long."
 };
 function formatErrorMessage(template, params = {}) {
   return template.replace(/\{(\w+)\}/g, (match, name) => {
@@ -1680,6 +1912,7 @@ var ERROR_MESSAGES_DE = {
   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",
+  SUBSCRIPTION_CONTRACT_CHANGED: "Die Vertr\xE4ge von Mandant '{tenantId}' haben sich ge\xE4ndert, w\xE4hrend ein Nachfolger geschrieben wurde, oder einer beginnt nach dem Zeitpunkt, ab dem er g\xE4lte, sodass er neben einem anderen liefe. Es wurde nichts geschrieben.",
   // ── subscriber ──
   SUBSCRIBER_REQUIRED: "Mandant '{tenantId}' hat keinen Vertragspartner. Ohne ihn wird nichts vereinbart oder berechnet: Zuerst muss der Vertragspartner des Mandanten angelegt werden.",
   SUBSCRIBER_ALREADY_EXISTS: "Mandant '{tenantId}' hat bereits einen Vertragspartner.",
@@ -1711,10 +1944,20 @@ 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 ──
-  SETTINGS_CHANGE_NOT_FOUND: "Keine aufgezeichnete Einstellungs\xE4nderung hat diese ID."
+  SETTINGS_CHANGE_NOT_FOUND: "Keine aufgezeichnete Einstellungs\xE4nderung hat diese ID.",
+  // ── maintenance ──
+  MAINTENANCE: "Die Anwendung wird gerade gewartet.",
+  MAINTENANCE_WINDOW_ALREADY_OPEN: "Es ist bereits ein Wartungsfenster offen. Verschiebe oder streiche es, bevor du ein weiteres ank\xFCndigst.",
+  MAINTENANCE_WINDOW_NOT_OPEN: "Kein offenes Wartungsfenster hat diese ID.",
+  MAINTENANCE_WINDOW_LOCKED: "Dieses Wartungsfenster ist gesperrt. Sein Beginn l\xE4sst sich nicht mehr verschieben, und beendet wird es durch Entsperren.",
+  MAINTENANCE_WINDOW_END_NOT_AFTER_START: "Das Ende eines Wartungsfensters muss nach seinem Beginn liegen.",
+  MAINTENANCE_WINDOW_END_IN_PAST: "Das Ende eines Wartungsfensters darf nicht in der Vergangenheit liegen.",
+  MAINTENANCE_TIME_INVALID: "{field} muss Datum und Uhrzeit mit Zeitzone sein, etwa 2026-10-02T22:00+02:00.",
+  MAINTENANCE_MESSAGE_TOO_LONG: "Die Nachricht darf h\xF6chstens {max} Zeichen lang sein."
 };
 export {
   ACTIVE_SUBSCRIPTION_CONTRACT_STATUSES,
@@ -1729,6 +1972,10 @@ export {
   FEATURE_NOT_LICENSED,
   ForeignPaymentMethodReferenceError,
   LEGAL_IDENTITY_FIELDS,
+  MAINTENANCE_CAPABILITY,
+  MAINTENANCE_ERROR_CODES,
+  MAINTENANCE_MESSAGE_MAX_LENGTH,
+  MAINTENANCE_STATE_MAX_AGE_SECONDS,
   MARKETING_PRIORITY_MAX,
   MARKETING_PRIORITY_MIN,
   OTP_RATE_LIMIT_MAX_SENDS,
@@ -1751,6 +1998,7 @@ export {
   REGISTRATION_STEP_BY_STATUS,
   SETTINGS_ERROR_CODES,
   SETUP_ERROR_CODES,
+  SUBSCRIBER_ACCOUNT_CAPABILITY,
   SUBSCRIBER_ERROR_CODES,
   applyPromo,
   assertPersistenceCapabilities,
@@ -1773,13 +2021,20 @@ export {
   identityCorrectionDelta,
   isBundleRedundant,
   isForeignPaymentMethodReferenceError,
+  isMaintenanceAnnouncementLapsed,
+  isMaintenanceOverrun,
   isPaymentCallbackRejectedError,
   isPlatformUserExistsError,
   isVersionEditable,
   issuerIdentityOf,
   keepOneRecommended,
+  maintenanceRetryAfterSeconds,
+  maintenanceStatusOf,
+  maintenanceWindowStatusOf,
+  maintenanceWindowViewOf,
   missingRequiresFor,
   movedIdentityFields,
+  parseZonedInstant,
   pickActivePromo,
   planCatalogSettingsOf,
   previousUtcDay,
@@ -1795,15 +2050,19 @@ export {
   selectChargeableBundles,
   settingsSubtreeOf,
   startOfUtcDay,
+  subscriberChargeColumns,
   subscriberFromRegistration,
   subscriberPaymentMethodColumns,
   toBundleStemRow,
   toContractLineItemRecord,
+  toMaintenanceWindowRecord,
   toPlanRow,
   toPlanVersionRow,
   toRunningContractIssuer,
+  toSubscriberChargeRecord,
   toSubscriberCorrectionRecord,
   toSubscriberPaymentMethodRecord,
   toSubscriberRecord,
+  toSubscriptionBundleRecord,
   toSubscriptionContractRecord
 };

package/package.json

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