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

package/schemas/plan-catalog.schema.json

@@ -4,22 +4,17 @@
     "title": "PlanCatalog",
     "description": "Language-neutral definition of a plan catalog + app identity for a SaaS app. Maintained by the consumer as a YAML/JSON file (`config/saas.yaml`) and mirrored into platform tables at backend boot.",
     "type": "object",
-    "required": ["schemaVersion", "projectKey", "currency", "vatRate"],
+    "required": ["schemaVersion", "app", "currency", "vatRate", "tenantBilling"],
     "additionalProperties": false,
     "properties": {
         "schemaVersion": {
             "type": "integer",
             "const": 1
         },
-        "projectKey": {
-            "type": "string",
-            "pattern": "^[a-z][a-z0-9-]{1,30}$",
-            "description": "Unique key of the consuming project. Cross-audit marker."
-        },
         "app": {
             "type": "object",
             "additionalProperties": false,
-            "description": "App identity block (branding + version). Consumed by AdminPublicBootController + AdminManifestConfigFactory.",
+            "description": "App identity block (branding + version). One installation serves one application, so this is the only place it is named. Consumed by AdminPublicBootController + AdminManifestConfigFactory.",
             "required": ["name"],
             "properties": {
                 "name": {
@@ -57,7 +52,56 @@
             "type": "number",
             "minimum": 0,
             "maximum": 100,
-            "description": "VAT rate in percent. Required (even when 0)."
+            "not": { "exclusiveMinimum": 0, "exclusiveMaximum": 1 },
+            "description": "VAT rate as a percentage: 19 means 19 %. Required (even when 0). Every tax rate in SaaSiCat is a percentage, so a value between 0 and 1, the shape of a fraction such as 0.19, is refused."
+        },
+        "tenantBilling": {
+            "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"],
+            "properties": {
+                "cancellationNoticeDays": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "description": "Days of notice before a term ends, one number per rhythm. A cancellation declared after the window has closed takes effect at the first period end that actually serves the notice. Two numbers rather than one because a monthly and a yearly contract cannot share a notice period: a fortnight is unusual on a year, and three months is void against a consumer on a month. No ceiling is enforced — §309 Nr. 9 BGB caps it at one month in German consumer contracts, and an installation serving businesses is not bound by that.",
+                    "required": ["monthly", "yearly"],
+                    "properties": {
+                        "monthly": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "description": "Notice days on a monthly rhythm. 0 means there is no door to be shut out of: a cancellation on the last day still lands at the term end."
+                        },
+                        "yearly": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "description": "Notice days on a yearly rhythm. Raise it and the cut is hard — a declaration made after the window lands one full year later."
+                        }
+                    }
+                },
+                "selfServiceBlockedPlans": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "description": "Plans a tenant may not move to or away from without talking to sales. Both lists are required and may be empty; an empty list is the explicit statement that self-service reaches every plan.",
+                    "required": ["asTarget", "asSource"],
+                    "properties": {
+                        "asTarget": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "description": "Plan IDs that may not be selected via self-service — typically ENTERPRISE, which only a special contract activates."
+                        },
+                        "asSource": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "description": "Plan IDs that may not be left via self-service — typically an active special contract, whose change goes through sales."
+                        }
+                    }
+                }
+            }
         },
         "marketing": {
             "type": "object",
@@ -67,26 +111,191 @@
             "properties": {
                 "availableLocales": {
                     "type": "array",
-                    "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+                    },
                     "minItems": 1,
                     "uniqueItems": true,
                     "description": "Allowed language pool the app may market. First = default locale. From it the SuperAdmin activates a subset in the marketing catalog (LocaleManager)."
                 }
             }
         },
+        "notifications": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Who is told when something in this file changes between two starts. The record inside the application is written either way; mail is the addition, never the substitute. Optional: an installation of one operator who signs in daily needs nothing here.",
+            "properties": {
+                "settingsChanged": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "format": "email"
+                    },
+                    "uniqueItems": true,
+                    "description": "Addresses mailed when the settings applied at a start differ from the ones applied at the previous start. Mailed only where an email port is bound (`adapters.email`); without one the boot log says so once and the change is recorded in the application only. An empty list names nobody."
+                }
+            }
+        },
+        "issuer": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["legalName"],
+            "description": "The legal entity on the operator's side of every contract this installation concludes, and later of every invoice it issues. A contract copies it on the day it is concluded, so the contract keeps naming its counterparty after this block changes. Optional for now: a contract concluded while it is absent records that no issuer was named.",
+            "properties": {
+                "legalName": {
+                    "type": "string",
+                    "pattern": "\\S",
+                    "description": "The registered name, legal form included, as a contract names the party (e.g. \"Example Software GmbH\"). Compared with the recorded one after the surrounding whitespace is taken off, so a value that is only whitespace is not a name at all."
+                },
+                "addressLine1": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Street and number."
+                },
+                "addressLine2": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "A second address line, such as a building or a c/o."
+                },
+                "postalCode": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "city": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "country": {
+                    "type": "string",
+                    "pattern": "^[A-Z]{2}$",
+                    "description": "ISO 3166-1 alpha-2 country code, e.g. DE."
+                },
+                "vatId": {
+                    "type": "string",
+                    "pattern": "\\S",
+                    "description": "VAT identification number, e.g. DE123456789."
+                },
+                "taxNumber": {
+                    "type": "string",
+                    "pattern": "\\S",
+                    "description": "The tax number the issuer's tax office assigned, where it is stated beside or instead of the VAT identification number."
+                },
+                "correctionOf": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["reason"],
+                    "description": "Declares that a changed `legalName`, `vatId` or `taxNumber` corrects the same legal entity rather than naming another one -- a misspelt name, a tax identifier that was wrong or missing, a change of name the entity went through. Without it a start that finds a different identity recorded is refused while contracts concluded under the previous one still run, because moving a contract to another legal entity is a transfer and not an edit of a setting. Name here, for every identity field the change moves, the value the installation recorded before it -- `null` where it recorded none. The declaration is needed only for the start that carries the change; a later deploy may drop it. It carries no date of its own: the settings record dates the start that applied it, and where the legal change has a date of its own it belongs in `reason`.",
+                    "properties": {
+                        "legalName": {
+                            "type": ["string", "null"],
+                            "pattern": "\\S",
+                            "description": "The registered name being replaced, or `null` where none was recorded."
+                        },
+                        "vatId": {
+                            "type": ["string", "null"],
+                            "pattern": "\\S",
+                            "description": "The VAT identification number being replaced, or `null` where none was recorded."
+                        },
+                        "taxNumber": {
+                            "type": ["string", "null"],
+                            "pattern": "\\S",
+                            "description": "The tax number being replaced, or `null` where none was recorded."
+                        },
+                        "reason": {
+                            "type": "string",
+                            "pattern": "\\S",
+                            "description": "Why the same entity now reads differently, e.g. \"Change of legal form, registered 2026-07-01\". Kept in the settings record with both value trees."
+                        }
+                    }
+                }
+            }
+        },
+        "subscribers": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "How the parties this installation concludes contracts with are numbered.",
+            "properties": {
+                "customerNumberPrefix": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9._/-]{1,16}$",
+                    "description": "Put in front of every customer number assigned from the next start on: `K-` gives K-10001. A customer number keeps the prefix it was assigned with, so changing this renumbers nobody. Omitted, a customer number is the number alone."
+                }
+            }
+        },
+        "payments": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["accounts", "returnUrlOrigins"],
+            "description": "The payment gateway accounts this installation takes payment methods through. SaaSiCat keeps the gateway's reference to a payment method and its masked details, never a card number or an IBAN. The keys and the webhook secret of each account are bound in the application's code from the environment and never written here.",
+            "properties": {
+                "newPaymentMethods": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+                    "description": "The account a new payment method is taken at, at sign-up and when a tenant changes its payment method. It names one of `accounts`, which then has to list its `methods`. Omitted, no new payment method is taken, and the accounts listed stay for the references they hold."
+                },
+                "returnUrlOrigins": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "string",
+                        "pattern": "^https?://[^/?#\\s]+$"
+                    },
+                    "description": "The origins a gateway's form may send a person back to, e.g. `https://app.example.com`: the scheme, the host and a port, no path. A sign-up or a tenant naming a success or cancel URL at any other origin is refused, so the operator's own payment form cannot be made to forward somebody to a page of a stranger's choosing."
+                },
+                "accounts": {
+                    "type": "object",
+                    "minProperties": 1,
+                    "propertyNames": {
+                        "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
+                    },
+                    "additionalProperties": {
+                        "$ref": "#/$defs/PaymentGatewayAccount"
+                    },
+                    "description": "Every gateway account by the name its webhook route carries: `/webhooks/payment/<name>`. An account that still holds a payment method in use stays listed after another takes the new ones, so its callbacks keep being handled; a start that finds a stored reference to an account missing here refuses, naming the account."
+                }
+            }
+        },
         "features": {
             "type": "array",
-            "items": { "$ref": "#/$defs/FeatureDef" },
+            "items": {
+                "$ref": "#/$defs/FeatureDef"
+            },
             "description": "Master list of all feature flags of the project. Plans may only reference keys declared here."
         },
         "plans": {
             "type": "array",
-            "items": { "$ref": "#/$defs/PlanDef" },
+            "items": {
+                "$ref": "#/$defs/PlanDef"
+            },
             "description": "Optional. When omitted, plans come exclusively from the AdminUI / DB."
         }
     },
-
     "$defs": {
+        "PaymentGatewayAccount": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["provider"],
+            "description": "One account at a payment gateway: a merchant account whose keys the application binds.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+                    "description": "The gateway the account is at, as its adapter names itself: `stripe` for @saasicat/payment-stripe. A start refuses an account whose bound adapter names another."
+                },
+                "methods": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                        "type": "string",
+                        "enum": ["card", "sepa_debit"]
+                    },
+                    "description": "The payment methods a new payment method may be at this account: `card`, `sepa_debit`. Required for the account `newPaymentMethods` names and read for no other."
+                }
+            }
+        },
         "FeatureDef": {
             "type": "object",
             "required": ["key"],
@@ -97,8 +306,13 @@
                     "pattern": "^[A-Z][A-Z0-9_]+$",
                     "description": "SCREAMING_SNAKE_CASE; unique per catalog."
                 },
-                "label": { "type": "string", "minLength": 1 },
-                "icon": { "type": "string" },
+                "label": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "icon": {
+                    "type": "string"
+                },
                 "tier": {
                     "type": "string",
                     "description": "Optional logical group. Convention: CORE / ADVANCED / PRO / BUSINESS / ENTERPRISE_ONLY."
@@ -110,7 +324,6 @@
                 }
             }
         },
-
         "PlanDef": {
             "type": "object",
             "required": ["id", "quotas", "features"],
@@ -121,8 +334,13 @@
                     "pattern": "^[A-Z][A-Z0-9_]+$",
                     "description": "Plan ID. Freely chosen by the consumer (BASIC, STANDARD, ...). Ends up as a string in Subscription.plan."
                 },
-                "name": { "type": "string", "minLength": 1 },
-                "tagline": { "type": "string" },
+                "name": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "tagline": {
+                    "type": "string"
+                },
                 "marketed": {
                     "type": "boolean",
                     "default": true,
@@ -156,7 +374,10 @@
                 },
                 "features": {
                     "type": "array",
-                    "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[A-Z][A-Z0-9_]+$"
+                    },
                     "uniqueItems": true,
                     "description": "List of included feature keys; all must exist in features[].key."
                 }

package/schemas/tenant-ledger.schema.json

@@ -0,0 +1,236 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/tenant-ledger.schema.json",
+    "title": "TenantLedgerEntry",
+    "description": "One entry in a tenant's account. Two kinds share one journal: a charge is what became due, a payment is what settled part of it. The journal is append-only — an entry is never updated, and a mistake is answered with a counter-entry rather than an edit, so the account says what happened rather than what somebody thinks today.",
+    "oneOf": [{ "$ref": "#/$defs/LedgerCharge" }, { "$ref": "#/$defs/LedgerPayment" }],
+
+    "$defs": {
+        "LedgerEntryKind": {
+            "type": "string",
+            "enum": ["charge", "payment"],
+            "description": "charge: an amount became due. payment: an amount settled."
+        },
+
+        "ChargeOrigin": {
+            "type": "string",
+            "enum": [
+                "activation",
+                "renewal",
+                "planChange",
+                "bundleBooking",
+                "credit",
+                "correction"
+            ],
+            "description": "What made the charge arise. activation: the first period of a subscription. renewal: a period renewing. planChange: the prorated difference of an immediate plan change. bundleBooking: an add-on booked. credit: a decision that reduces what is owed. correction: a counter-entry reversing an earlier one, which is how the append-only journal answers a mistake."
+        },
+
+        "Currency": {
+            "type": "string",
+            "pattern": "^[A-Z]{3}$",
+            "description": "ISO 4217. Recorded per entry even though an installation configures one at a time, so that a row written in 2026 still means what it meant after the configured currency changes."
+        },
+
+        "LedgerCharge": {
+            "type": "object",
+            "title": "LedgerCharge",
+            "description": "An amount that became due. It names the period it belongs to, so the charges that make up one invoice can be found later, and it names the agreement it came from, so it can be walked back to what the tenant agreed to.",
+            "required": [
+                "id",
+                "tenantId",
+                "kind",
+                "subscriptionId",
+                "origin",
+                "originRef",
+                "periodStart",
+                "periodEnd",
+                "currency",
+                "amountNet",
+                "taxRate",
+                "taxAmount",
+                "amountGross",
+                "bookedAt",
+                "createdAt"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "The entry's own identifier. Never shown to a customer as an invoice number: invoice numbering is sequential, gapless and legally constrained per country, and an identifier somebody has already seen on a screen cannot become one later without confusion."
+                },
+                "tenantId": { "type": "string" },
+                "kind": { "const": "charge" },
+                "subscriptionId": {
+                    "type": "string",
+                    "description": "The subscription the charge arose on. Part of the natural key below."
+                },
+                "origin": { "$ref": "#/$defs/ChargeOrigin" },
+                "originRef": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Which thing within the origin the charge is for, so that two charges of the same origin in the same period stay apart. activation and renewal: the subscription id. planChange: the id of the contract the change concluded, which differs for every change. bundleBooking: the booking id. credit and correction: the entry they answer. Never empty — the natural key (subscriptionId, origin, originRef, periodStart) is unique, and a NULL would not collide with itself, which is the one thing the key exists to prevent."
+                },
+                "periodStart": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The billing period the charge belongs to. It is the grouping key for a later invoice: a set of individually booked amounts with nothing tying them to a period leaves 'which charges go on one invoice' to guesswork."
+                },
+                "periodEnd": { "type": "string", "format": "date-time" },
+                "contractId": {
+                    "type": ["string", "null"],
+                    "description": "The frozen agreement the charge realises. Null where none was frozen — a subscription older than the contract model, or a credit that answers no line."
+                },
+                "contractLineItemId": {
+                    "type": ["string", "null"],
+                    "description": "The contract line the charge came from. Null under the same conditions as contractId."
+                },
+                "currency": { "$ref": "#/$defs/Currency" },
+                "amountNet": {
+                    "type": "number",
+                    "description": "Held to the currency's decimal places. Negative on a credit or a correction."
+                },
+                "taxRate": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100,
+                    "description": "The rate in percent, recorded rather than left to live in the ratio between net and gross. A ratio cannot be reproduced for a rounded gross, cannot express an exempt or reverse-charge line, and does not survive a rate change."
+                },
+                "taxAmount": {
+                    "type": "number",
+                    "description": "The tax contained in the charge. It closes the gap between amountNet and amountGross exactly, so the entry cannot disagree with itself."
+                },
+                "amountGross": { "type": "number" },
+                "bookedAt": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "When the amount became due. The account is ordered by this, not by when the row was written."
+                },
+                "createdAt": { "type": "string", "format": "date-time" }
+            }
+        },
+
+        "LedgerPayment": {
+            "type": "object",
+            "title": "LedgerPayment",
+            "description": "An amount that settled. What talks to a bank, a card processor or an invoice run is a consumer's adapter behind a port; this records only that the money arrived and which external reference it arrived under. It carries no tax split: a payment is a movement of money, and the net, the rate and the tax belong to the charges it settles — asking a payment for them would make an integrator write a number nobody knows, which the account would then read as a fact.",
+            "required": [
+                "id",
+                "tenantId",
+                "kind",
+                "externalReference",
+                "currency",
+                "amountGross",
+                "bookedAt",
+                "createdAt"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "format": "uuid" },
+                "tenantId": { "type": "string" },
+                "kind": { "const": "payment" },
+                "externalReference": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The payment provider's own identifier for the settlement. It is what makes a payment reconcilable against the provider, and what a second delivery of the same provider event is recognised by."
+                },
+                "settlesEntryId": {
+                    "type": ["string", "null"],
+                    "description": "The charge this payment settles, where the provider says which. Null for a payment on account, which reduces the balance without naming a charge."
+                },
+                "currency": { "$ref": "#/$defs/Currency" },
+                "amountGross": {
+                    "type": "number",
+                    "description": "What arrived. Negative on a reversal, which is a movement the other way rather than an edit of the payment it answers."
+                },
+                "bookedAt": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The value date — when the money settled, which is not when the row was written."
+                },
+                "createdAt": { "type": "string", "format": "date-time" }
+            }
+        },
+
+        "TenantAccountOpenItem": {
+            "type": "object",
+            "title": "TenantAccountOpenItem",
+            "description": "A charge that is not yet settled in full.",
+            "required": [
+                "entryId",
+                "origin",
+                "periodStart",
+                "periodEnd",
+                "currency",
+                "amountGross",
+                "settledGross",
+                "openGross",
+                "dueAt"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "entryId": { "type": "string", "format": "uuid" },
+                "origin": { "$ref": "#/$defs/ChargeOrigin" },
+                "periodStart": { "type": "string", "format": "date-time" },
+                "periodEnd": { "type": "string", "format": "date-time" },
+                "currency": { "$ref": "#/$defs/Currency" },
+                "amountGross": { "type": "number" },
+                "settledGross": {
+                    "type": "number",
+                    "description": "What payments naming this charge have settled so far."
+                },
+                "openGross": {
+                    "type": "number",
+                    "description": "amountGross minus settledGross."
+                },
+                "dueAt": { "type": "string", "format": "date-time" }
+            }
+        },
+
+        "TenantAccount": {
+            "type": "object",
+            "title": "TenantAccount",
+            "description": "What a tenant and an administrator both read: the balance, what is open, and the history. One shape for both, because a balance a tenant is shown and a balance an administrator is shown must not be two answers.",
+            "required": [
+                "tenantId",
+                "currency",
+                "asOf",
+                "chargedGross",
+                "paidGross",
+                "balanceGross",
+                "openItems",
+                "entries"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "tenantId": { "type": "string" },
+                "currency": { "$ref": "#/$defs/Currency" },
+                "asOf": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "A balance is only ever true at a moment, and this is the moment."
+                },
+                "chargedGross": { "type": "number" },
+                "paidGross": { "type": "number" },
+                "balanceGross": {
+                    "type": "number",
+                    "description": "chargedGross minus paidGross. Positive means the tenant owes; negative means they have paid ahead."
+                },
+                "openItems": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/TenantAccountOpenItem" }
+                },
+                "entries": {
+                    "type": "array",
+                    "description": "The history the read was asked for, newest first. The window is the caller's decision, not a property of the account.",
+                    "items": {
+                        "oneOf": [
+                            { "$ref": "#/$defs/LedgerCharge" },
+                            { "$ref": "#/$defs/LedgerPayment" }
+                        ]
+                    }
+                }
+            }
+        }
+    }
+}