@saasicat/core 1.0.0-rc.22 → 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 = {
   /**
@@ -724,6 +826,24 @@ 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,
@@ -734,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
@@ -1570,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.",
@@ -1605,7 +1727,16 @@ var ERROR_MESSAGES_EN = {
   // ── 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) => {
@@ -1781,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.",
@@ -1816,7 +1948,16 @@ var ERROR_MESSAGES_DE = {
   // ── 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,
@@ -1831,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,
@@ -1876,13 +2021,20 @@ export {
   identityCorrectionDelta,
   isBundleRedundant,
   isForeignPaymentMethodReferenceError,
+  isMaintenanceAnnouncementLapsed,
+  isMaintenanceOverrun,
   isPaymentCallbackRejectedError,
   isPlatformUserExistsError,
   isVersionEditable,
   issuerIdentityOf,
   keepOneRecommended,
+  maintenanceRetryAfterSeconds,
+  maintenanceStatusOf,
+  maintenanceWindowStatusOf,
+  maintenanceWindowViewOf,
   missingRequiresFor,
   movedIdentityFields,
+  parseZonedInstant,
   pickActivePromo,
   planCatalogSettingsOf,
   previousUtcDay,
@@ -1903,6 +2055,7 @@ export {
   subscriberPaymentMethodColumns,
   toBundleStemRow,
   toContractLineItemRecord,
+  toMaintenanceWindowRecord,
   toPlanRow,
   toPlanVersionRow,
   toRunningContractIssuer,

package/package.json

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