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

package/prisma-fragments/10-super-admin.prisma

@@ -42,7 +42,7 @@ model SuperAdminMfa {
     // admins live exclusively in `super_admin_users` may add the relation:
     // user SuperAdminUser @relation(fields: [userId], references: [id], onDelete: Cascade)
     userId    String    @id
-    secret    String? // TOTP secret; null after reset
+    secret    String? // TOTP secret, sealed by the installation's SecretSealer; null after reset
     enabledAt DateTime? // set when a secret is stored, null after reset
 
     updatedAt DateTime @updatedAt

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/17-subscription-notice.prisma

@@ -0,0 +1,55 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriptionNotice
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per notice a subscriber is due: that a newer version of their plan is
+// offered to them, or that the version they are on is being retired — each told
+// once. The platform records a notice before it has the
+// application send it and confirms it after, so the unique key below is what
+// makes a notice once — however many instances run the job — and the row is
+// what shows later when it went out, to whom and how.
+//
+// A run takes a notice on by setting `claimedAt`, and lets it go again where the
+// sending failed; a claim older than a quarter of an hour counts as abandoned.
+// `deliveredAt`, `recipients` and `channel` are set together, when the
+// application confirms it sent the notice.
+//
+// The record is evidence of what a subscriber was told, and outlives the
+// subscription like the subscriber's account does (ADR 0012): `tenantId` and
+// `subscriptionId` are kept as values, not as keys.
+//
+// `kind` is text holding a closed set: version-offered, version-retired,
+// version-retirement-reminder.
+//
+// Optional: adopt it where `tenantBilling.versionNotices` is configured, which
+// refuses to start without a place to keep notices; a retirement needs it too.
+//
+// Contract: @saasicat/core (SubscriptionNoticeRepository).
+
+model SubscriptionNotice {
+    id             String @id @default(uuid())
+    tenantId       String
+    subscriptionId String
+
+    kind    String
+    // What the notice is about — for version-offered, the id of the version
+    // offered; for version-retired and version-retirement-reminder, the id of
+    // the version retired, so a subscription is told of a version's retirement
+    // once and reminded of it once.
+    subject String
+    // The notice as it was last handed to the application.
+    content Json
+
+    createdAt   DateTime  @default(now())
+    claimedAt   DateTime?
+    deliveredAt DateTime?
+    // Who it went to and how, in the application's own terms.
+    recipients  Json?
+    channel     String?
+
+    @@unique([subscriptionId, kind, subject])
+    @@index([kind, subject])
+    @@map("subscription_notices")
+}

package/prisma-fragments/18-version-retirement.prisma

@@ -0,0 +1,44 @@
+// =============================================================================
+// SaaS platform Prisma fragment: VersionRetirement
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per retirement an operator announces: a plan version ended for the
+// subscriptions already on it, with the version they continue on. It is the one
+// exception to a subscription keeping its version, so it is kept as evidence of
+// what was announced, when and by whom.
+//
+// What it means for each subscription it reaches — the date it takes effect,
+// the last day to cancel without notice, and to whom and how that was told — is
+// a `subscription_notices` row of kind version-retired, written in the same
+// transaction: its subject is the retired version, its content names this
+// row's id as `retirementId`.
+//
+// The versions are kept as values, not as keys: the record outlives the
+// catalogue entries it names, as the notices do (ADR 0012).
+//
+// Optional: adopt it where an operator may retire versions
+// (`tenantBilling.orderlyRetirement` in config/saas.yaml), which refuses to
+// start without a place to keep announcements.
+//
+// Contract: @saasicat/core (VersionRetirementRepository).
+
+model VersionRetirement {
+    id String @id @default(uuid())
+
+    retiredPlanVersionId String
+    retiredPlanKey       String
+    retiredVersion       Int
+
+    replacementPlanVersionId String
+    replacementPlanKey       String
+    replacementVersion       Int
+
+    announcedAt DateTime @default(now())
+    // Who announced it — an actor tag, as the audit log writes it.
+    announcedBy String
+
+    @@index([retiredPlanVersionId])
+    @@map("version_retirements")
+}

package/prisma-fragments/README.md

@@ -45,6 +45,8 @@ 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`                                                                   |
+| [`17-subscription-notice.prisma`](17-subscription-notice.prisma)     | `SubscriptionNotice`                                                                  |
 
 ## 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/schemas/audit-event.schema.json

@@ -38,7 +38,7 @@
         },
         "actorTag": {
             "type": ["string", "null"],
-            "description": "Origin marker. Format: 'web:<email>:<sessionId>' or 'cli:<email>:<host>'."
+            "description": "Origin marker. Format: 'web:<email>:<sessionId>', 'cli:<email>:<host>', or 'job:platform:<job>' for a platform job acting on its own schedule."
         },
         "ipAddress": { "type": ["string", "null"] },
         "userAgent": { "type": ["string", "null"] },
@@ -48,7 +48,7 @@
     "$defs": {
         "ActorTagPattern": {
             "type": "string",
-            "pattern": "^(web|cli):[^:]+:[^:]+$",
+            "pattern": "^(web|cli|job):[^:]+:[^:]+$",
             "description": "Mandatory format for actorTag."
         },
 

package/schemas/plan-catalog.schema.json

@@ -59,7 +59,7 @@
             "type": "object",
             "additionalProperties": false,
             "description": "Commercial settings for the tenant-facing self-service routes. Required, and required member by member: every one of these has a money or a legal consequence, and a value left out is still a decision — just an invisible one. The file is read at boot, so a change lands on the next restart.",
-            "required": ["cancellationNoticeDays", "selfServiceBlockedPlans"],
+            "required": ["cancellationNoticeDays", "selfServiceBlockedPlans", "orderlyRetirement"],
             "properties": {
                 "cancellationNoticeDays": {
                     "type": "object",
@@ -100,6 +100,18 @@
                             "description": "Plan IDs that may not be left via self-service — typically an active special contract, whose change goes through sales."
                         }
                     }
+                },
+                "orderlyRetirement": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "description": "Whether the operator may retire a plan version for the subscriptions already on it — end it, or raise its price, with three calendar months of notice and a named replacement. It reaches contracts customers have already made, so it rests on a clause in the operator's terms, legally reviewed; without one only the rule that a subscription keeps its version applies.",
+                    "required": ["termsConfirmed"],
+                    "properties": {
+                        "termsConfirmed": {
+                            "type": "boolean",
+                            "description": "true states that the operator's terms carry that clause. Only then does the admin offer a retirement and the server accept one; false refuses it."
+                        }
+                    }
                 }
             }
         },

package/sql/1.0-a-newer-version-is-only-offered.postgres.sql

@@ -0,0 +1,33 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a newer version is only offered.
+-- =============================================================================
+--
+-- A subscription keeps the plan version it is bound to, and a newer one reaches
+-- it as an offer beside the plan (`SC-SUB-020`); taking it is a change like any
+-- other. The pending version — announced, reminded about, accepted and rolled
+-- forward at the end of the term — is gone, and so are the seven columns that
+-- carried it. Dropping them discards every pending version still recorded,
+-- accepted ones included: a newer version then reaches the subscription as an
+-- offer.
+--
+-- 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-a-newer-version-is-only-offered.postgres.sql
+--
+-- Run it once nothing reads the columns any more: no running version of the
+-- application, and no job of your own — a notice or renewal job that set or
+-- rolled forward a pending version — still uses them. A column's index and its
+-- foreign key go with it.
+--
+-- Safe to run again, and on a database without a subscriptions table: every
+-- column is dropped only where it exists.
+
+ALTER TABLE IF EXISTS "subscriptions"
+    DROP COLUMN IF EXISTS "pendingPlanVersionId",
+    DROP COLUMN IF EXISTS "pendingPlanVersionEffectiveAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAccepted",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAcceptedAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionAcceptedByUserId",
+    DROP COLUMN IF EXISTS "pendingPlanVersionNotifiedAt",
+    DROP COLUMN IF EXISTS "pendingPlanVersionReminderSentAt";

package/sql/1.0-a-retirement-is-announced.postgres.sql

@@ -0,0 +1,43 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a retirement is announced.
+-- =============================================================================
+--
+-- One table, additive: `version_retirements` keeps every retirement an operator
+-- announces — a plan version ended for the subscriptions already on it, the
+-- version they continue on, when and by whom. What it means for each
+-- subscription is a `subscription_notices` row of kind `version-retired`, which
+-- `1.0-a-subscriber-is-told-once.postgres.sql` creates.
+--
+-- 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-a-retirement-is-announced.postgres.sql
+--
+-- The record outlives the catalogue entries it names, so the versions are kept
+-- as values and the table has no foreign key: nothing else has to exist for it
+-- to be created.
+--
+-- Safe to run again: the table and its index 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 "version_retirements" (
+    "id" TEXT NOT NULL,
+    "retiredPlanVersionId" TEXT NOT NULL,
+    "retiredPlanKey" TEXT NOT NULL,
+    "retiredVersion" INTEGER NOT NULL,
+    "replacementPlanVersionId" TEXT NOT NULL,
+    "replacementPlanKey" TEXT NOT NULL,
+    "replacementVersion" INTEGER NOT NULL,
+    "announcedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "announcedBy" TEXT NOT NULL,
+
+    CONSTRAINT "version_retirements_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "version_retirements_retiredPlanVersionId_idx"
+    ON "version_retirements"("retiredPlanVersionId");
+
+COMMIT;

package/sql/1.0-a-scheduled-change-keeps-its-quoted-version.postgres.sql

@@ -0,0 +1,129 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a scheduled change to another plan binds the version it was
+-- quoted at.
+-- =============================================================================
+--
+-- `subscriptions` gains "pendingChangeVersionId": the version of "pendingPlan"
+-- the plan-change preview showed when the change was scheduled. When the change
+-- comes due, the platform binds that version rather than whichever is in effect
+-- that day, so a version published in between does not reach the customer by a
+-- change they already agreed to. Run it BEFORE `db push`, the same way as the
+-- other files in this directory:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-scheduled-change-keeps-its-quoted-version.postgres.sql
+--
+-- What happens to a change scheduled before this file. The version it was
+-- shown was never recorded, so the one live and in effect now stands for it:
+-- the newest published, not superseded, not ended, and — on a schema with
+-- validity windows — already begun. A version published ahead of its date is
+-- left out; the change then binds the version in effect when it comes due, as
+-- it did before this file. A change that stays on its plan is left empty: it keeps the
+-- version bound, whatever that is by the day it comes due. A plan with no live
+-- version is left empty too, and binds the version in effect when it comes due.
+--
+-- The plan is found the way the Prisma adapter's `planBinding` stores it: by
+-- its key in "plan_versions"."planId" (`legacy-plan-key`), or — where the
+-- column holds the plan's row id (`normalized-plan-id`) — through the row of
+-- "plans" that carries the key. The fragment generates that row id as a UUID,
+-- so it does not coincide with a key and at most one of the two matches. The
+-- second is left out where "plans" has no "planKey", which includes a schema
+-- with no "plans" at all.
+--
+-- Safe to run again: the column, its index and its foreign key are added only
+-- where they are missing, and the backfill runs only in the run that adds the
+-- column. A second run therefore finds the column and changes nothing — it
+-- does not pin a version published since the first run to a change scheduled
+-- before it. On a database created from `reference-schema.postgres.sql` the
+-- whole file does nothing: the column is already there.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('subscriptions') IS NULL OR to_regclass('plan_versions') IS NULL THEN
+        RAISE NOTICE 'subscriptions or plan_versions is not present — nothing to migrate.';
+        RETURN;  -- an installation that never adopted these fragments
+    END IF;
+
+    IF NOT EXISTS (
+        SELECT 1
+        FROM information_schema.columns
+        WHERE table_schema = current_schema()
+          AND table_name = 'subscriptions'
+          AND column_name = 'pendingChangeVersionId'
+    ) THEN
+        ALTER TABLE "subscriptions" ADD COLUMN "pendingChangeVersionId" TEXT;
+
+        -- Live and in effect: published, not superseded, and — where the
+        -- schema has the columns — not ended and already begun. An ended
+        -- version takes no new bookings, and one published ahead of its date
+        -- is not the one in effect. Each clause is added only where its column
+        -- exists; a schema from before it ends and delays nothing.
+        EXECUTE format(
+            $backfill$
+            UPDATE "subscriptions" AS s
+            SET "pendingChangeVersionId" = (
+                SELECT v."id"
+                FROM "plan_versions" AS v
+                WHERE (v."planId" = s."pendingPlan" %s)
+                  AND v."publishedAt" IS NOT NULL
+                  AND v."supersededAt" IS NULL
+                  %s
+                  %s
+                ORDER BY v."version" DESC
+                LIMIT 1
+            )
+            WHERE s."pendingPlan" IS NOT NULL
+              AND s."pendingPlan" <> s."plan"
+            $backfill$,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plans'
+                      AND column_name = 'planKey'
+                )
+                THEN 'OR v."planId" IN (SELECT p."id" FROM "plans" AS p WHERE p."planKey" = s."pendingPlan")'
+                ELSE ''
+            END,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plan_versions'
+                      AND column_name = 'endsAt'
+                )
+                THEN 'AND (v."endsAt" IS NULL OR v."endsAt" > NOW())'
+                ELSE ''
+            END,
+            CASE
+                WHEN EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = current_schema()
+                      AND table_name = 'plan_versions'
+                      AND column_name = 'validFrom'
+                )
+                THEN 'AND (v."validFrom" IS NULL OR v."validFrom" <= NOW())'
+                ELSE ''
+            END
+        );
+    END IF;
+
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'subscriptions_pendingChangeVersionId_fkey'
+    ) THEN
+        ALTER TABLE "subscriptions"
+            ADD CONSTRAINT "subscriptions_pendingChangeVersionId_fkey"
+            FOREIGN KEY ("pendingChangeVersionId") REFERENCES "plan_versions"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+
+    CREATE INDEX IF NOT EXISTS "subscriptions_pendingChangeVersionId_idx"
+        ON "subscriptions"("pendingChangeVersionId");
+END
+$$;
+
+COMMIT;

package/sql/1.0-a-subscriber-is-told-once.postgres.sql

@@ -0,0 +1,48 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a subscriber is told once.
+-- =============================================================================
+--
+-- One table, additive: `subscription_notices` keeps the record of every notice
+-- a subscriber is due — that a newer version of their plan is offered to them —
+-- with when it went out, to whom and how. The platform writes it where
+-- `tenantBilling.versionNotices` is turned on, and the unique key is what makes
+-- each notice once rather than once per run.
+--
+-- 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-a-subscriber-is-told-once.postgres.sql
+--
+-- The record outlives the subscription, as the subscriber's account does, so
+-- the table keeps the tenant and the subscription as values and has no foreign
+-- key: nothing else has to exist for it to be created.
+--
+-- 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 "subscription_notices" (
+    "id" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "kind" TEXT NOT NULL,
+    "subject" TEXT NOT NULL,
+    "content" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "claimedAt" TIMESTAMP(3),
+    "deliveredAt" TIMESTAMP(3),
+    "recipients" JSONB,
+    "channel" TEXT,
+
+    CONSTRAINT "subscription_notices_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "subscription_notices_kind_subject_idx"
+    ON "subscription_notices"("kind", "subject");
+
+CREATE UNIQUE INDEX IF NOT EXISTS "subscription_notices_subscriptionId_kind_subject_key"
+    ON "subscription_notices"("subscriptionId", "kind", "subject");
+
+COMMIT;

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