@saasicat/spec 1.0.0-rc.2 → 1.0.0-rc.20

package/admin-api.openapi.yaml

@@ -17,10 +17,19 @@ openapi: 3.1.0
 #   - Tenant end-customer API (self-service plan change) — separate file
 #   - Onboarding API — separate file (uses PromoCode preview)
 #   - X-Rechnung — its own package, its own OpenAPI file
+#
+# Who serves what: an operation marked `x-served-by: app` is part of this
+# contract but NOT shipped by @saasicat/nest — the tenant model, platform user
+# administration and the promo-code detail view reach into data the application
+# owns, so the application serves those routes and the admin UI calls them.
+# Everything else is served by the reference implementation.
+# `tests/openapi-covers-the-implementation.test.js` holds both directions: no
+# undocumented route, and no documented operation without an implementation or
+# that marker.
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 0.1.0-draft
+    version: 1.0.0-rc.20
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -48,6 +57,7 @@ tags:
     - name: mfa
     - name: manifest
     - name: catalog
+    - name: settings
 
 security:
     - bearerAuth: []
@@ -141,7 +151,7 @@ paths:
     # ────────────────────────────────────────────────────────
     # Dashboard
     # ────────────────────────────────────────────────────────
-    /dashboard/stats:
+    /stats/dashboard:
         get:
             tags: [dashboard]
             summary: Global platform metrics
@@ -153,53 +163,6 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/DashboardStats'
 
-    # ────────────────────────────────────────────────────────
-    # Plan catalog (read-only — maintained via file + reload endpoint)
-    # ────────────────────────────────────────────────────────
-    /plans:
-        get:
-            tags: [plans]
-            summary: Currently loaded plan catalog
-            responses:
-                '200':
-                    description: Catalog
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/PlanCatalog'
-
-    /plans/reload:
-        post:
-            tags: [plans]
-            summary: Reload the plan catalog from file (for admin CLI / hot-reload dev)
-            x-mfa-required: true
-            responses:
-                '200':
-                    description: Loaded
-                    content:
-                        application/json:
-                            schema:
-                                type: object
-                                properties:
-                                    loadedAt: { type: string, format: date-time }
-                                    planCount: { type: integer }
-                                    source: { type: string, description: Path or URL }
-
-    /plans/last-update:
-        get:
-            tags: [plans]
-            summary: When the catalog was last loaded + hash
-            responses:
-                '200':
-                    description: Meta
-                    content:
-                        application/json:
-                            schema:
-                                type: object
-                                properties:
-                                    loadedAt: { type: string, format: date-time }
-                                    hash: { type: string, description: SHA-256 of the YAML content }
-
     # ────────────────────────────────────────────────────────
     # Tenants
     # ────────────────────────────────────────────────────────
@@ -234,6 +197,7 @@ paths:
 
         post:
             tags: [tenants]
+            x-served-by: app # the tenant model is the application's
             summary: Create a tenant manually (bypasses the onboarding flow)
             x-mfa-required: true
             requestBody:
@@ -262,6 +226,7 @@ paths:
                             schema: { $ref: '#/components/schemas/AdminTenantDetail' }
         delete:
             tags: [tenants]
+            x-served-by: app # the tenant model is the application's
             summary: Soft-delete a tenant (set deletedAt)
             x-mfa-required: true
             requestBody:
@@ -315,6 +280,7 @@ paths:
             - $ref: '#/components/parameters/TenantSlug'
         post:
             tags: [tenants]
+            x-served-by: app # the tenant model is the application's
             summary: Short-lived JWT as TENANT_ADMIN for support insight
             x-mfa-required: true
             requestBody:
@@ -344,6 +310,7 @@ paths:
             - $ref: '#/components/parameters/TenantSlug'
         get:
             tags: [tenants]
+            x-served-by: app # the tenant model is the application's
             summary: GDPR / audit export of all tenant data as a ZIP
             x-mfa-required: true
             responses:
@@ -361,6 +328,7 @@ paths:
             - $ref: '#/components/parameters/TenantSlug'
         get:
             tags: [subscriptions]
+            x-served-by: app # no admin-side subscription route ships
             summary: Current subscription + add-ons + effective limits
             responses:
                 '200':
@@ -371,6 +339,7 @@ paths:
 
         patch:
             tags: [subscriptions]
+            x-served-by: app # no admin-side subscription route ships
             summary: Change plan, custom limits, or pilot flag
             x-mfa-required: true
             requestBody:
@@ -435,6 +404,7 @@ paths:
               schema: { type: string }
         post:
             tags: [users]
+            x-served-by: app # platform users live in the application's identity store
             summary: Trigger a password-reset email (sends no plaintext passwords)
             x-mfa-required: true
             requestBody:
@@ -457,6 +427,7 @@ paths:
               schema: { type: string }
         post:
             tags: [users]
+            x-served-by: app # platform users live in the application's identity store
             summary: Deactivate a user (block login)
             x-mfa-required: true
             requestBody:
@@ -476,6 +447,7 @@ paths:
             - $ref: '#/components/parameters/TenantSlug'
         post:
             tags: [users]
+            x-served-by: app # the tenant model is the application's
             summary: Transfer the TENANT_ADMIN role to another user
             x-mfa-required: true
             requestBody:
@@ -546,6 +518,7 @@ paths:
               schema: { type: string, format: uuid }
         get:
             tags: [promo-codes]
+            x-served-by: app # the detail view joins application data
             responses:
                 '200':
                     description: Detail
@@ -622,41 +595,217 @@ paths:
                                               items: { $ref: '#/components/schemas/AuditEntryDto' }
 
     # ────────────────────────────────────────────────────────
-    # MFA
+    # First-run setup (SetupModule, packages/nest/src/setup/*)
+    #
+    # Public by design: before the first SUPER_ADMIN there is no session to
+    # authenticate. The window is open only while zero SUPER_ADMIN exist and
+    # is additionally gated by the operator-set SETUP_TOKEN.
     # ────────────────────────────────────────────────────────
-    /mfa/setup:
-        post:
-            tags: [mfa]
-            summary: Start TOTP setup (returns QR-code URI + secret)
+    /setup/status:
+        get:
+            tags: [setup]
+            security: [] # PUBLIC — answers whether the window is still open
+            summary: Whether first-run setup is still open
             responses:
                 '200':
-                    description: Setup data
+                    description: Status
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [needsSetup]
+                                properties:
+                                    needsSetup:
+                                        type: boolean
+                                        description: true as long as no SUPER_ADMIN exists
+
+    /setup:
+        post:
+            tags: [setup]
+            security: [] # PUBLIC — see the section note
+            summary: Create the first SUPER_ADMIN and start its MFA enrolment
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [token, email]
+                            properties:
+                                token: { type: string, description: Must match SETUP_TOKEN }
+                                email: { type: string, format: email }
+                                password:
+                                    type: string
+                                    minLength: 8
+                                    description: Generated by the server when omitted
+            responses:
+                '201':
+                    description: Created — the response carries the enrolment secret once
                     content:
                         application/json:
                             schema:
                                 type: object
+                                required: [userId, email, otpauthUri, qrDataUrl, secret]
                                 properties:
+                                    userId: { type: string }
+                                    email: { type: string, format: email }
                                     otpauthUri: { type: string }
-                                    secret: { type: string }
-                                    recoveryCodes:
-                                        type: array
-                                        items: { type: string }
+                                    qrDataUrl: { type: string, description: PNG data URL }
+                                    secret: { type: string, description: Base32 TOTP secret }
+                                    generatedPassword:
+                                        type: string
+                                        description: Present only when the server generated it
+                '400':
+                    description: The email is not an address the platform accepts
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                '401':
+                    description: The token does not match SETUP_TOKEN
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                '403':
+                    description: SETUP_TOKEN is not set — setup is disabled
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                '409':
+                    description: >-
+                        Either the window has closed itself because a SUPER_ADMIN already
+                        exists (`SETUP_ALREADY_DONE`), or the address is taken by a platform
+                        user (`EMAIL_EXISTS`). The `code` tells them apart.
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
 
-    /mfa/confirm:
+    /setup/confirm-mfa:
         post:
-            tags: [mfa]
-            summary: Confirm setup with the first code
+            tags: [setup]
+            security: [] # PUBLIC — see the section note
+            summary: Confirm the enrolment with the first TOTP code, closing the window
             requestBody:
                 required: true
                 content:
                     application/json:
                         schema:
                             type: object
-                            required: [code]
+                            required: [token, userId, code]
                             properties:
+                                token: { type: string }
+                                userId: { type: string }
                                 code: { type: string, pattern: '^[0-9]{6}$' }
             responses:
-                '200': { description: Activated }
+                '200':
+                    description: Activated
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [ok]
+                                properties:
+                                    ok: { type: boolean }
+                '401':
+                    description: The token does not match SETUP_TOKEN
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                '403':
+                    description: SETUP_TOKEN is not set — setup is disabled
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+
+    # ────────────────────────────────────────────────────────
+    # Plan catalog import (PlanCatalogImporterModule)
+    # ────────────────────────────────────────────────────────
+    /billing/plan-catalog/import:
+        post:
+            tags: [plans]
+            summary: Import a plan catalog YAML into the catalog tables
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [yamlContent]
+                            properties:
+                                yamlContent: { type: string, description: Contents of saas.yaml }
+                                crossFieldChecks:
+                                    type: boolean
+                                    default: true
+                                    description: Validate references between plans, features and quotas
+            responses:
+                '201':
+                    description: Import report — the counters say what was new and what already matched
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required:
+                                    - plansCreated
+                                    - plansSkipped
+                                    - planVersionsCreated
+                                    - planVersionsSkipped
+                                    - featureEntriesCreated
+                                    - featureEntriesSkipped
+                                    - warnings
+                                properties:
+                                    plansCreated: { type: integer }
+                                    plansSkipped: { type: integer }
+                                    planVersionsCreated: { type: integer }
+                                    planVersionsSkipped: { type: integer }
+                                    featureEntriesCreated: { type: integer }
+                                    featureEntriesSkipped: { type: integer }
+                                    warnings: { type: array, items: { type: string } }
+                '400':
+                    description: The YAML failed schema validation
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+
+    # ────────────────────────────────────────────────────────
+    # Subscriptions
+    # ────────────────────────────────────────────────────────
+    /subscriptions:
+        get:
+            tags: [subscriptions]
+            summary: Every tenant subscription, one row each
+            responses:
+                '200':
+                    description: Rows
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    type: object
+                                    required: [id, tenant, plan, status, billingCycle]
+                                    properties:
+                                        id: { type: string }
+                                        tenant:
+                                            type: object
+                                            required: [slug, name]
+                                            properties:
+                                                slug: { type: string }
+                                                name: { type: string }
+                                        plan: { type: string }
+                                        status: { type: string }
+                                        billingCycle: { type: string }
+                                        periodEndsAt:
+                                            type: string
+                                            format: date-time
+                                            nullable: true
+                                        monthlyNet: { type: string, nullable: true }
+                                    additionalProperties: true
 
     # ────────────────────────────────────────────────────────
     # Catalog V2 — Plan/Bundle/Marketing/Promotion + Discovery
@@ -1199,6 +1348,42 @@ paths:
                     }
             responses: { '200': { description: Synchronized } }
 
+    # ── The applied configuration (SettingsModule, packages/nest/src/settings/*) ──
+    #
+    # Read-only. What the installation is running on — read off the loaded
+    # catalogue — and the record of it: since when, from where, and what changed
+    # between two starts. The record is a mirror of config/saas.yaml, never a
+    # source, so there is no write operation here.
+
+    /settings:
+        get:
+            tags: [settings]
+            summary: The running configuration, since when it applies, and what changed at boot
+            responses:
+                '200':
+                    description: The applied settings and their record
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AppliedSettingsView' }
+
+    /settings/changes/{id}/acknowledge:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        post:
+            tags: [settings]
+            summary: Mark a recorded settings change as seen
+            description: >-
+                The record survives until this is called. The acknowledgement keeps its first
+                author — a second call changes nothing and answers the record as it stands — and
+                is written to the audit log as SETTINGS_CHANGE_ACKNOWLEDGE.
+            responses:
+                '200':
+                    description: The change, acknowledged
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/SettingsChangeView' }
+                '404':
+                    description: No recorded change has this id (`SETTINGS_CHANGE_NOT_FOUND`)
+
     # ── Discovery (scan/status, outside /catalog) ──
     /discovery:
         get:
@@ -1240,13 +1425,78 @@ components:
             schema: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$' }
 
     schemas:
+        # ────────── Applied settings (packages/nest/src/settings/settings.controller.ts) ──────────
+        AppliedSettingsView:
+            type: object
+            required: [source, fingerprint, settings, recorded, appliedAt, changes]
+            properties:
+                source:
+                    {
+                        type: string,
+                        description: 'Where the running settings came from: the absolute path of the file, or a phrase saying they were handed in as code',
+                    }
+                fingerprint:
+                    {
+                        type: string,
+                        description: 'sha256-<hex> over the canonical JSON of `settings`',
+                    }
+                settings:
+                    type: object
+                    additionalProperties: true
+                    description: 'The settings subtree of the catalogue as it was resolved — everything but plans and features'
+                recorded:
+                    {
+                        type: boolean,
+                        description: 'Whether this installation keeps a record at all (a persistence adapter provides the port)',
+                    }
+                appliedAt:
+                    type: [string, 'null']
+                    format: date-time
+                    description: 'When these values became the running configuration. Null where nothing is recorded, or the record describes an earlier configuration.'
+                changes:
+                    type: array
+                    description: 'Newest first; empty where nothing is recorded'
+                    items: { $ref: '#/components/schemas/SettingsChangeView' }
+
+        SettingsChangeView:
+            type: object
+            required: [id, noticedAt, source, differences, acknowledgedAt, acknowledgedBy]
+            properties:
+                id: { type: string }
+                noticedAt:
+                    {
+                        type: string,
+                        format: date-time,
+                        description: 'The start that found the fingerprint moved',
+                    }
+                source: { type: string }
+                differences:
+                    type: array
+                    items: { $ref: '#/components/schemas/SettingsDifference' }
+                acknowledgedAt: { type: [string, 'null'], format: date-time }
+                acknowledgedBy:
+                    {
+                        type: [string, 'null'],
+                        description: 'An actor tag, as the audit log writes it',
+                    }
+
+        SettingsDifference:
+            type: object
+            required: [path]
+            properties:
+                path:
+                    {
+                        type: string,
+                        description: 'Dotted, as the loader names a field: tenantBilling.cancellationNoticeDays.monthly',
+                    }
+                before: { description: 'Absent where the leaf did not exist before' }
+                after: { description: 'Absent where the leaf no longer exists' }
+
         # ────────── Catalog V2 (DTO = SSOT: packages/nest/src/catalog/dto/*) ──────────
         CatalogPlanCreate:
             type: object
-            required: [projectKey, planKey, label]
+            required: [planKey, label]
             properties:
-                projectKey:
-                    { type: string, pattern: '^[a-z][a-z0-9-]*$', description: 'kebab-case' }
                 planKey:
                     {
                         type: string,
@@ -1287,9 +1537,8 @@ components:
 
         CatalogBundleCreate:
             type: object
-            required: [projectKey, bundleKey, label]
+            required: [bundleKey, label]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 bundleKey: { type: string, pattern: '^[A-Z][A-Z0-9_]*$', description: 'no hyphen' }
                 label: { type: string, minLength: 1, maxLength: 120 }
                 description: { type: string, maxLength: 2000 }
@@ -1347,9 +1596,8 @@ components:
 
         CatalogMarketingProjectionCreate:
             type: object
-            required: [projectKey, targetType, targetVersionId, displayLabel, description]
+            required: [targetType, targetVersionId, displayLabel, description]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 targetType: { type: string, enum: [PLAN, BUNDLE] }
                 targetVersionId: { type: string }
                 locale: { type: string, pattern: '^[a-z]{2}(-[A-Z]{2})?$', default: de }
@@ -1465,9 +1713,8 @@ components:
 
         CatalogMarketingSettingsUpdate:
             type: object
-            required: [projectKey, activeLocales]
+            required: [activeLocales]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 activeLocales:
                     type: array
                     uniqueItems: true
@@ -1475,9 +1722,8 @@ components:
 
         CatalogPromotionCreate:
             type: object
-            required: [projectKey, internalLabel, type, value, validFrom, validTo]
+            required: [internalLabel, type, value, validFrom, validTo]
             properties:
-                projectKey: { type: string, pattern: '^[a-z][a-z0-9-]*$' }
                 internalLabel: { type: string, maxLength: 120 }
                 type: { type: string, enum: [percent, amount, intro, freeMonths] }
                 value:
@@ -1550,10 +1796,15 @@ components:
         # ────────── Plan-Catalog (mirror of plans.yaml) ──────────
         PlanCatalog:
             type: object
-            required: [schemaVersion, projectKey, currency, vatRate, plans]
+            required: [schemaVersion, app, currency, vatRate, plans]
             properties:
                 schemaVersion: { type: integer, const: 1 }
-                projectKey: { type: string, description: 'Project key of the app (kebab-case)' }
+                app:
+                    type: object
+                    required: [name]
+                    description: 'App identity — the only place the application is named'
+                    properties:
+                        name: { type: string, minLength: 1 }
                 currency: { type: string, pattern: '^[A-Z]{3}$' }
                 vatRate: { type: number, format: decimal, description: 'in percent' }
                 features:

package/cli-conventions.md

@@ -27,7 +27,7 @@ for the audit log:
 - Without an identity → writing commands are rejected with exit code `2`
   (see §6).
 
-Read commands (e.g. `… mandant list`) are allowed without an identity, but
+Read commands (e.g. `… tenant list`) are allowed without an identity, but
 write `actor=anonymous` to the local log.
 
 ## 2. Mandatory MFA for Critical Operations
@@ -35,9 +35,9 @@ write `actor=anonymous` to the local log.
 The following operations **MUST** prompt for a TOTP code
 (Google Authenticator) before execution:
 
-- `… paket apply` (PlanCatalog mutation)
+- `… plans apply` (PlanCatalog mutation)
 - `… pilot create|grant|revoke` (pilot override)
-- `… mandant suspend|impersonate` (tenant security operations)
+- `… tenant suspend|impersonate` (tenant security operations)
 - `… plan-version publish` (PlanVersion publication)
 - `… user reassign-admin` (last-admin escalation)
 - `… admin mfa-reset` (MFA reset of another SUPER_ADMIN)
@@ -57,12 +57,12 @@ is not `NODE_ENV=development` and not a localhost DB), every
 writing command must be confirmed interactively:
 
 ```text
-? Tippe production zur Bestätigung: production
+? Type production to confirm: production
 ```
 
 - Alternative: `--yes` / `-y` skips the confirmation (for CI/CD).
 - Plus `--dry-run` is the default for destructive commands like
-  `… paket apply` and `… rabatt delete`. Only `--apply` or
+  `… plans apply` and `… discounts delete`. Only `--apply` or
   `--yes` applies.
 
 `production` detection should run through the consumer's implementation of the
@@ -110,11 +110,11 @@ redefine them, because cron/CI scripts pattern-match on them:
 | 4    | Connectivity error (DB unreachable, sidecar service down)                                                                            |
 | 5    | Permission error (user is not allowed to perform this operation — e.g. a SUPER_ADMIN operation, but the user is only a TENANT_ADMIN) |
 | 6    | Conflict (optimistic-lock mismatch, idempotency violation)                                                                           |
-| 7    | Drift detected (e.g. `paket diff` finds differences; `manifest check` finds inconsistencies)                                         |
+| 7    | Drift detected (e.g. `plans diff` finds differences; `manifest check` finds inconsistencies)                                         |
 | 99   | Internal error (uncaught exception, bug reports welcome)                                                                             |
 
 Read commands return `0` even for an empty result set (no drift =
-no error). Drift-detection commands (`paket diff`, `manifest check`)
+no error). Drift-detection commands (`plans diff`, `manifest check`)
 return `7` when drift is found — CI gates can react to that.
 
 ## 7. Consumer Plugin API
@@ -136,23 +136,23 @@ Plugin commands automatically inherit:
 
 ```bash
 # Read operation, no identity required
-$ myapp mandant list --output=json | jq '.[] | select(.status=="ACTIVE")'
+$ myapp tenant list --output=json | jq '.[] | select(.status=="ACTIVE")'
 
 # Writing with identity, dry-run as default
-$ myapp paket apply config/plans.yaml
-ℹ Diff: 2 Pläne aktualisiert, 1 Bundle neu.
-ℹ Dry-run — nutze --apply zum Schreiben.
+$ myapp plans apply config/plans.yaml
+ℹ Diff: 2 plans updated, 1 bundle added.
+ℹ Dry run — pass --apply to write.
 
 # Writing with mandatory MFA
-$ myapp paket apply config/plans.yaml --apply
-ℹ Erfordert MFA-Bestätigung.
-? TOTP-Code: 482 159
-✓ PlanCatalog aktualisiert. AuditLog: PLAN_CATALOG_UPDATE.
+$ myapp plans apply config/plans.yaml --apply
+ℹ MFA confirmation required.
+? TOTP code: 482 159
+✓ PlanCatalog updated. AuditLog: PLAN_CATALOG_UPDATE.
 
 # Production confirm
 $ NODE_ENV=production myapp pilot grant pilot-schmidt --as=admin@example.com
-? Tippe production zur Bestätigung: production
-ℹ Erfordert MFA-Bestätigung.
-? TOTP-Code: 217 998
-✓ Pilot-Grant gespeichert.
+? Type production to confirm: production
+ℹ MFA confirmation required.
+? TOTP code: 217 998
+✓ Pilot grant stored.
 ```