@saasicat/spec 1.0.0-rc.22 → 1.0.0-rc.23

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.22
+    version: 1.0.0-rc.23
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -58,6 +58,7 @@ tags:
     - name: manifest
     - name: catalog
     - name: settings
+    - name: maintenance
 
 security:
     - bearerAuth: []
@@ -1406,6 +1407,146 @@ paths:
                 '404':
                     description: No recorded change has this id (`SETTINGS_CHANGE_NOT_FOUND`)
 
+    # ── Maintenance windows (MaintenanceModule, packages/nest/src/maintenance/*) ──
+    #
+    # An operator announces a window, locks the application for a deploy and
+    # unlocks it. The announced times are what tenants are told; they never
+    # start or end the lock. These routes stay reachable while the lock holds.
+    # The status a tenant's page reads is `GET /public/maintenance`, outside
+    # this document's prefix.
+
+    /maintenance:
+        get:
+            tags: [maintenance]
+            summary: The open window, if any, and the ones before it
+            responses:
+                '200':
+                    description: The overview, read fresh
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceOverview' }
+        post:
+            tags: [maintenance]
+            summary: Announce a window to the tenants
+            description: >-
+                Locks nobody out. Refused while another window is open. The application hears
+                of it through its `MaintenanceNotificationPort`, where it binds one. Audited as
+                MAINTENANCE_WINDOW_ANNOUNCE.
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceAnnouncement' }
+            responses:
+                '201':
+                    description: The window, announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '400':
+                    description: >-
+                        A time without its zone (`MAINTENANCE_TIME_INVALID`), an end not after the
+                        start (`MAINTENANCE_WINDOW_END_NOT_AFTER_START`) or in the past
+                        (`MAINTENANCE_WINDOW_END_IN_PAST`), a message too long
+                        (`MAINTENANCE_MESSAGE_TOO_LONG`)
+                '409':
+                    description: Another window is open (`MAINTENANCE_WINDOW_ALREADY_OPEN`)
+
+    /maintenance/{id}:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        patch:
+            tags: [maintenance]
+            summary: Move the open window, or change its message
+            description: >-
+                What is left out stays; `message: null` takes the message away. A locked window
+                keeps its start and may still move its expected end. Audited as
+                MAINTENANCE_WINDOW_RESCHEDULE.
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceRevision' }
+            responses:
+                '200':
+                    description: The window as it now stands
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '400':
+                    description: As for announcing
+                '404':
+                    description: No open window has this id (`MAINTENANCE_WINDOW_NOT_OPEN`)
+                '409':
+                    description: The window is locked and its start cannot move (`MAINTENANCE_WINDOW_LOCKED`)
+
+    /maintenance/{id}/cancel:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        post:
+            tags: [maintenance]
+            summary: Call off an announced window
+            description: Audited as MAINTENANCE_WINDOW_CANCEL. A locked window is ended by unlocking it.
+            responses:
+                '201':
+                    description: The window, cancelled
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                '404':
+                    description: No open window has this id (`MAINTENANCE_WINDOW_NOT_OPEN`)
+                '409':
+                    description: The window is locked (`MAINTENANCE_WINDOW_LOCKED`)
+
+    /maintenance/lock:
+        post:
+            tags: [maintenance]
+            summary: Lock every tenant out
+            description: >-
+                Locks the open window, or opens one locked at once where none is open. Locking what
+                is locked changes nothing and says so. Takes effect in every process within
+                `takesEffectWithinSeconds`. Audited as MAINTENANCE_LOCK.
+            x-mfa-required: true
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/MaintenanceLockRequest' }
+            responses:
+                '201':
+                    description: The lock
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceLockView' }
+                '400':
+                    description: An end without its zone or in the past
+                '404':
+                    description: The window named is not the open one (`MAINTENANCE_WINDOW_NOT_OPEN`)
+
+    /maintenance/unlock:
+        post:
+            tags: [maintenance]
+            summary: Let tenants back in
+            description: >-
+                Ends the locked window. Where nothing is locked it changes nothing and says so; an
+                announced window is left as it is. Audited as MAINTENANCE_UNLOCK.
+            x-mfa-required: true
+            requestBody:
+                required: false
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                windowId:
+                                    { type: string, description: The window the operator means }
+            responses:
+                '201':
+                    description: What the unlock did
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/MaintenanceUnlockView' }
+                '404':
+                    description: The window named is not the open one (`MAINTENANCE_WINDOW_NOT_OPEN`)
+
     # ── Discovery (scan/status, outside /catalog) ──
     /discovery:
         get:
@@ -1514,6 +1655,123 @@ components:
                 before: { description: 'Absent where the leaf did not exist before' }
                 after: { description: 'Absent where the leaf no longer exists' }
 
+        # ────────── Maintenance windows (packages/core/src/maintenance-window.types.ts) ──────────
+        MaintenanceWindowView:
+            type: object
+            required:
+                [
+                    id,
+                    status,
+                    startsAt,
+                    endsAt,
+                    message,
+                    createdAt,
+                    createdBy,
+                    lockedAt,
+                    lockedBy,
+                    endedAt,
+                    endedBy,
+                    overrun,
+                    lapsed,
+                ]
+            properties:
+                id: { type: string }
+                status: { type: string, enum: [announced, locked, ended, cancelled] }
+                startsAt:
+                    {
+                        type: [string, 'null'],
+                        format: date-time,
+                        description: 'The announced start; null for a window locked without being announced',
+                    }
+                endsAt:
+                    {
+                        type: [string, 'null'],
+                        format: date-time,
+                        description: 'The announced, expected end; null where nobody said',
+                    }
+                message: { type: [string, 'null'], description: 'Shown to the tenants as written' }
+                createdAt: { type: string, format: date-time }
+                createdBy: { type: string, description: 'An actor tag, as the audit log writes it' }
+                lockedAt: { type: [string, 'null'], format: date-time }
+                lockedBy: { type: [string, 'null'] }
+                endedAt: { type: [string, 'null'], format: date-time }
+                endedBy: { type: [string, 'null'] }
+                overrun: { type: boolean, description: 'Locked, and past its announced end' }
+                lapsed:
+                    {
+                        type: boolean,
+                        description: 'Announced, never locked, and past its announced end: tenants no longer see it',
+                    }
+
+        MaintenanceOverview:
+            type: object
+            required: [open, recent, takesEffectWithinSeconds]
+            properties:
+                open:
+                    oneOf:
+                        - $ref: '#/components/schemas/MaintenanceWindowView'
+                        - type: 'null'
+                recent:
+                    type: array
+                    description: 'Newest first, the open one included'
+                    items: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                takesEffectWithinSeconds:
+                    { type: integer, description: 'How long a lock takes to reach every process' }
+
+        MaintenanceAnnouncement:
+            type: object
+            required: [startsAt, endsAt]
+            properties:
+                startsAt:
+                    {
+                        type: string,
+                        description: 'Date and time with its zone, e.g. 2026-10-02T22:00+02:00',
+                    }
+                endsAt:
+                    {
+                        type: string,
+                        description: 'Date and time with its zone; after startsAt, and ahead',
+                    }
+                message: { type: [string, 'null'], maxLength: 500 }
+
+        MaintenanceRevision:
+            type: object
+            properties:
+                startsAt: { type: string, description: 'Date and time with its zone' }
+                endsAt: { type: string, description: 'Date and time with its zone' }
+                message:
+                    { type: [string, 'null'], maxLength: 500, description: 'null takes it away' }
+
+        MaintenanceLockRequest:
+            type: object
+            properties:
+                windowId:
+                    {
+                        type: string,
+                        description: 'The window the operator means; left out, the open one or a new one',
+                    }
+                endsAt: { type: string, description: 'The expected end, with its zone' }
+                message: { type: [string, 'null'], maxLength: 500 }
+
+        MaintenanceLockView:
+            type: object
+            required: [window, alreadyLocked, takesEffectWithinSeconds]
+            properties:
+                window: { $ref: '#/components/schemas/MaintenanceWindowView' }
+                alreadyLocked:
+                    { type: boolean, description: 'The lock already held; nothing changed' }
+                takesEffectWithinSeconds: { type: integer }
+
+        MaintenanceUnlockView:
+            type: object
+            required: [window, wasLocked]
+            properties:
+                window:
+                    oneOf:
+                        - $ref: '#/components/schemas/MaintenanceWindowView'
+                        - type: 'null'
+                wasLocked: { type: boolean }
+
         # ────────── Catalog V2 (DTO = SSOT: packages/nest/src/catalog/dto/*) ──────────
         CatalogPlanCreate:
             type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.22",
+  "version": "1.0.0-rc.23",
   "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
   "type": "module",
   "main": "./index.cjs",

package/prisma-fragments/16-maintenance-window.prisma

@@ -0,0 +1,47 @@
+// =============================================================================
+// SaaS platform Prisma fragment: MaintenanceWindow
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per maintenance window: announced to the tenants ahead of time,
+// locked while a deploy runs a migration that must not race with requests, and
+// ended when the operator says so. A window can also be locked at once without
+// having been announced, which leaves `startsAt` null.
+//
+// While a window is locked, every running version of the application reads this
+// table on its requests — the one being replaced as well as the one replacing
+// it. Its shape is therefore part of the contract between two releases: it
+// gains columns, and never in a deploy the lock protects.
+//
+// At most ONE window is open (not yet ended) at a time. Prisma cannot express a
+// partial unique index; the one that holds it is in
+// sql/constraints.postgres.sql, and it is what makes two operators locking at
+// the same moment land one window rather than two.
+//
+// Optional: adopt it where `maintenance` is turned on in
+// `SaaSiCatModule.forRoot`, which refuses to start without a place to keep
+// windows.
+
+model MaintenanceWindow {
+    id        String    @id @default(uuid())
+    // What the tenants were told: the announced start and the expected end.
+    // Neither starts or ends the lock — that is the operator's command.
+    startsAt  DateTime?
+    endsAt    DateTime?
+    // The operator's words to the tenants, shown as written.
+    message   String?
+    // When the window was recorded — announced, or locked at once — and by whom
+    // (an actor tag, as the audit log writes it).
+    createdAt DateTime  @default(now())
+    createdBy String
+    // Null while the window is only announced.
+    lockedAt  DateTime?
+    lockedBy  String?
+    // Set when the window is over: unlocked, or cancelled before it locked.
+    endedAt   DateTime?
+    endedBy   String?
+
+    @@index([createdAt])
+    @@map("maintenance_windows")
+}

package/prisma-fragments/README.md

@@ -45,6 +45,7 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 | [`13-subscriber.prisma`](13-subscriber.prisma)                       | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`                              |
 | [`14-payments.prisma`](14-payments.prisma)                           | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`          |
 | [`15-subscriber-ledger.prisma`](15-subscriber-ledger.prisma)         | `SubscriberLedgerEntry`                                                               |
+| [`16-maintenance-window.prisma`](16-maintenance-window.prisma)       | `MaintenanceWindow`                                                                   |
 
 ## How the consumer uses the fragments
 

package/schemas/admin-manifest.schema.json

@@ -141,7 +141,8 @@
                         "marketingCatalog": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmail": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" },
-                        "settings": { "$ref": "#/$defs/StandardPageDef" }
+                        "settings": { "$ref": "#/$defs/StandardPageDef" },
+                        "maintenance": { "$ref": "#/$defs/StandardPageDef" }
                     }
                 },
                 "projectPages": {

package/sql/1.0-maintenance-windows-are-kept.postgres.sql

@@ -0,0 +1,51 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — maintenance windows are kept.
+-- =============================================================================
+--
+-- One table, additive: `maintenance_windows` holds one row per maintenance
+-- window — announced to the tenants, locked while a deploy runs, ended when the
+-- operator unlocks. The platform reads it on every request while it is turned
+-- on (`maintenance` in `SaaSiCatModule.forRoot`), through a cache of a few
+-- seconds.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-maintenance-windows-are-kept.postgres.sql
+--
+-- Apply it in an ordinary deploy, BEFORE the first deploy you lock: the lock
+-- protects a deploy only when the version already running reads it, so the
+-- table has to be there, and that version with it, before it is needed.
+--
+-- The index on a constant is what holds an installation to one open window:
+-- every open row carries the same key, so a second one collides, and a window
+-- that ended leaves the index.
+--
+-- Safe to run again: the table and both indexes are created only where they are
+-- missing. On a database created from `reference-schema.postgres.sql` the whole
+-- file does nothing at all.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "maintenance_windows" (
+    "id" TEXT NOT NULL,
+    "startsAt" TIMESTAMP(3),
+    "endsAt" TIMESTAMP(3),
+    "message" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "createdBy" TEXT NOT NULL,
+    "lockedAt" TIMESTAMP(3),
+    "lockedBy" TEXT,
+    "endedAt" TIMESTAMP(3),
+    "endedBy" TEXT,
+
+    CONSTRAINT "maintenance_windows_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "maintenance_windows_createdAt_idx"
+    ON "maintenance_windows"("createdAt");
+
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -47,6 +47,15 @@ ALTER TABLE applied_settings
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
 
+-- At most ONE maintenance window is open — announced or locked, not yet ended.
+--
+-- The index is on a constant, so every open row carries the same key and a
+-- second one collides. A window that ended leaves the index and makes room for
+-- the next. Two operators locking at the same moment therefore land one window,
+-- because the second insert meets the first and is told a window is open.
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
 -- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
 -- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
 -- tenants a subscriber had before stay in its history. Two partial unique

package/sql/reference-schema.postgres.sql

@@ -18,6 +18,7 @@
 --   prisma-fragments/13-subscriber.prisma
 --   prisma-fragments/14-payments.prisma
 --   prisma-fragments/15-subscriber-ledger.prisma
+--   prisma-fragments/16-maintenance-window.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -706,6 +707,22 @@ CREATE TABLE "subscriber_ledger_entries" (
     CONSTRAINT "subscriber_ledger_entries_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "maintenance_windows" (
+    "id" TEXT NOT NULL,
+    "startsAt" TIMESTAMP(3),
+    "endsAt" TIMESTAMP(3),
+    "message" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "createdBy" TEXT NOT NULL,
+    "lockedAt" TIMESTAMP(3),
+    "lockedBy" TEXT,
+    "endedAt" TIMESTAMP(3),
+    "endedBy" TEXT,
+
+    CONSTRAINT "maintenance_windows_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -940,6 +957,9 @@ CREATE INDEX "subscriber_ledger_entries_contractLineItemId_idx" ON "subscriber_l
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriber_ledger_entries_subscriptionId_source_sourceRef_p_key" ON "subscriber_ledger_entries"("subscriptionId", "source", "sourceRef", "periodStart", "origin");
 
+-- CreateIndex
+CREATE INDEX "maintenance_windows_createdAt_idx" ON "maintenance_windows"("createdAt");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
@@ -1049,6 +1069,15 @@ ALTER TABLE applied_settings
 ALTER TABLE applied_settings
     ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
 
+-- At most ONE maintenance window is open — announced or locked, not yet ended.
+--
+-- The index is on a constant, so every open row carries the same key and a
+-- second one collides. A window that ended leaves the index and makes room for
+-- the next. Two operators locking at the same moment therefore land one window,
+-- because the second insert meets the first and is told a window is open.
+CREATE UNIQUE INDEX IF NOT EXISTS maintenance_windows_one_open
+    ON maintenance_windows ((true)) WHERE "endedAt" IS NULL;
+
 -- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
 -- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
 -- tenants a subscriber had before stay in its history. Two partial unique