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

package/README.md

@@ -1,8 +1,30 @@
 # @saasicat/spec
 
+## What this is
+
 Language-neutral spec of the SaaS platform — JSON Schemas, OpenAPI and
 acceptance test scenarios.
 
+## What this is not
+
+Not runnable code. JSON Schemas, an OpenAPI document, Prisma fragments and SQL
+constraints — a contract any language can implement, which is why the reference
+implementation is a separate package.
+
+Not a migration tool. The fragments are merged into your own `schema.prisma`
+by `saasicat schema apply`, and your Prisma or Drizzle migration flow takes it
+from there.
+
+## Entry points
+
+| Entry                         | What is in it                                                                                               |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `.`                           | The hand-written index: constants and helpers over the schemas.                                             |
+| `./schemas/*.json`            | The JSON Schemas — the source of truth for every wire format.                                               |
+| `./prisma-fragments/*.prisma` | One fragment per table group, merged by `saasicat schema apply`.                                            |
+| `./prisma-fragments/`         | The directory itself, for tooling that enumerates the fragments.                                            |
+| `./sql/*.sql`                 | The reference schema, the constraints Prisma cannot express, and the migrations a consumer applies by hand. |
+
 ## Contents
 
 | File                                    | Purpose                                           |
@@ -11,6 +33,7 @@ acceptance test scenarios.
 | `schemas/plan-catalog.schema.json`      | App identity config format (`config/saas.yaml`)   |
 | `schemas/promo-code.schema.json`        | Promo code format incl. redemption lifecycle      |
 | `schemas/audit-event.schema.json`       | Audit log entry format                            |
+| `schemas/tenant-ledger.schema.json`     | A tenant's account: charges, payments, balance    |
 | `admin-api.openapi.yaml`                | NORMATIVE REST contract of the SuperAdmin backend |
 | `acceptance/`                           | HTTP test scenarios (stubs; runner planned)       |
 | `index.js` / `index.cjs` / `index.d.ts` | Re-exports for JS/TS consumers                    |
@@ -57,3 +80,10 @@ pnpm add @saasicat/spec
   live in the DB, curated via the SuperAdmin UI.
 - **`schemaVersion` is required** in every top-level schema. Major bumps
   break — that is allowed, but must be documented in a migration note.
+
+## Next
+
+- [Data model](../../docs/explanation/data-model.md) — the tables the fragments declare
+- [From capability to contract](../../docs/explanation/capability-to-contract.md) — what the schemas
+  describe
+- [Codegen](../../docs/explanation/adr/0006-spec-to-types-codegen.md) — how types are derived from them

package/acceptance/README.md

@@ -10,10 +10,10 @@ document, but an executable set of guarantees.
 Each scenario is a YAML file with the structure:
 
 ```yaml
-scenario: 'Kurzbeschreibung des Verhaltens (1 Satz)'
+scenario: 'What the behaviour is, in one sentence'
 description: |
-    Längere Beschreibung — was wird hier abgesichert, warum ist es wichtig.
-    Verweise auf SPEC-Sektion oder offene Frage.
+    The longer version — what this holds, and why it matters.
+    Point at the SPEC section, or at the question still open.
 
 setup: # state setup via Admin API calls
     - createTenant: { slug: '...', email: '...' }

package/acceptance/mfa/totp-verify-good-and-bad-code.yaml

@@ -18,26 +18,26 @@ cases:
     - name: 'valid TOTP code'
       request:
           method: POST
-          path: /api/v1/admin/tenants/test-mandant/suspend
+          path: /api/v1/admin/tenants/test-tenant/suspend
           auth: { as: 'super@platform.example' }
           headers:
               X-Mfa-Code: '{{generateTotpFor: super@platform.example}}'
           body: { reason: 'test reason' }
       pre:
-          - createTenant: { slug: 'test-mandant', email: 'x@test-mandant.example' }
+          - createTenant: { slug: 'test-tenant', email: 'x@test-tenant.example' }
       then:
           status: 200
 
     - name: 'invalid TOTP code'
       request:
           method: POST
-          path: /api/v1/admin/tenants/test-mandant/suspend
+          path: /api/v1/admin/tenants/test-tenant/suspend
           auth: { as: 'super@platform.example' }
           headers:
               X-Mfa-Code: '000000'
           body: { reason: 'test reason' }
       pre:
-          - createTenant: { slug: 'test-mandant-2', email: 'y@test-mandant-2.example' }
+          - createTenant: { slug: 'test-tenant-2', email: 'y@test-tenant-2.example' }
       then:
           status: 401
           body:
@@ -46,11 +46,11 @@ cases:
     - name: 'missing TOTP header'
       request:
           method: POST
-          path: /api/v1/admin/tenants/test-mandant-3/suspend
+          path: /api/v1/admin/tenants/test-tenant-3/suspend
           auth: { as: 'super@platform.example' }
           body: { reason: 'test reason' }
       pre:
-          - createTenant: { slug: 'test-mandant-3', email: 'z@test-mandant-3.example' }
+          - createTenant: { slug: 'test-tenant-3', email: 'z@test-tenant-3.example' }
       then:
           status: 401
           body: