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

package/README.md

@@ -33,7 +33,7 @@ from there.
 | `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    |
+| `schemas/subscriber-ledger.schema.json` | One charge in a subscriber's account              |
 | `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                    |

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.21
+    version: 1.0.0-rc.22
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -125,7 +125,7 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: 'admin-manifest.schema.json'
+                                $ref: 'schemas/admin-manifest.schema.json'
                 '304':
                     description: Unchanged since ETag
                 '403':
@@ -368,6 +368,28 @@ paths:
                         application/json:
                             schema: { $ref: '#/components/schemas/SubscriptionDetail' }
 
+    /tenants/{slug}/charges:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: The charges of the tenant's subscriber, newest first
+            description: >-
+                Served where the platform keeps a charge journal
+                (`tenantBilling.chargeJournal`) and shows tenants
+                (`adminResources`); the manifest announces it as `charges.read`.
+                Read only, and net: a charge's tax is decided when it is
+                invoiced. No total — without invoices and payments, a sum would
+                be read as what is owed.
+            responses:
+                '200':
+                    description: The account
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberAccount' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
     # ────────────────────────────────────────────────────────
     # Users
     # ────────────────────────────────────────────────────────
@@ -1915,6 +1937,38 @@ components:
                 promoRedemption:
                     $ref: '#/components/schemas/PromoRedemptionDto'
 
+        AdminSubscriberAccount:
+            type: object
+            required: [holder, entries]
+            properties:
+                holder:
+                    type: object
+                    nullable: true
+                    description: Whose account it is; null for a tenant that has no subscriber.
+                    required: [id, customerNumber, legalName]
+                    properties:
+                        id: { type: string }
+                        customerNumber: { type: string }
+                        legalName: { type: string }
+                entries:
+                    type: array
+                    description: >-
+                        Newest first — by when each charge became due, then by
+                        its period, then the plan before its add-ons before its
+                        discounts.
+                    items:
+                        type: object
+                        required: [charge, title]
+                        properties:
+                            charge: { $ref: 'schemas/subscriber-ledger.schema.json' }
+                            title:
+                                type: string
+                                nullable: true
+                                description: >-
+                                    The contract line's title as it was when the
+                                    contract was concluded; null where that line
+                                    cannot be read.
+
         # ────────── User ──────────
         AdminUserRow:
             type: object

package/index.cjs

@@ -3,19 +3,19 @@ const adminManifestSchema = require('./schemas/admin-manifest.schema.json');
 const planCatalogSchema = require('./schemas/plan-catalog.schema.json');
 const promoCodeSchema = require('./schemas/promo-code.schema.json');
 const auditEventSchema = require('./schemas/audit-event.schema.json');
-const tenantLedgerSchema = require('./schemas/tenant-ledger.schema.json');
+const subscriberLedgerSchema = require('./schemas/subscriber-ledger.schema.json');
 
 module.exports = {
     adminManifestSchema,
     planCatalogSchema,
     promoCodeSchema,
     auditEventSchema,
-    tenantLedgerSchema,
+    subscriberLedgerSchema,
     SCHEMAS: {
         adminManifest: adminManifestSchema,
         planCatalog: planCatalogSchema,
         promoCode: promoCodeSchema,
         auditEvent: auditEventSchema,
-        tenantLedger: tenantLedgerSchema,
+        subscriberLedger: subscriberLedgerSchema,
     },
 };

package/index.d.cts

@@ -4,12 +4,12 @@ export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
-export declare const tenantLedgerSchema: Record<string, unknown>;
+export declare const subscriberLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
-    readonly tenantLedger: Record<string, unknown>;
+    readonly subscriberLedger: Record<string, unknown>;
 };

package/index.d.ts

@@ -5,12 +5,12 @@ export declare const adminManifestSchema: Record<string, unknown>;
 export declare const planCatalogSchema: Record<string, unknown>;
 export declare const promoCodeSchema: Record<string, unknown>;
 export declare const auditEventSchema: Record<string, unknown>;
-export declare const tenantLedgerSchema: Record<string, unknown>;
+export declare const subscriberLedgerSchema: Record<string, unknown>;
 
 export declare const SCHEMAS: {
     readonly adminManifest: Record<string, unknown>;
     readonly planCatalog: Record<string, unknown>;
     readonly promoCode: Record<string, unknown>;
     readonly auditEvent: Record<string, unknown>;
-    readonly tenantLedger: Record<string, unknown>;
+    readonly subscriberLedger: Record<string, unknown>;
 };

package/index.js

@@ -6,14 +6,14 @@ import adminManifestSchema from './schemas/admin-manifest.schema.json' with { ty
 import planCatalogSchema from './schemas/plan-catalog.schema.json' with { type: 'json' };
 import promoCodeSchema from './schemas/promo-code.schema.json' with { type: 'json' };
 import auditEventSchema from './schemas/audit-event.schema.json' with { type: 'json' };
-import tenantLedgerSchema from './schemas/tenant-ledger.schema.json' with { type: 'json' };
+import subscriberLedgerSchema from './schemas/subscriber-ledger.schema.json' with { type: 'json' };
 
 export {
     adminManifestSchema,
     planCatalogSchema,
     promoCodeSchema,
     auditEventSchema,
-    tenantLedgerSchema,
+    subscriberLedgerSchema,
 };
 
 export const SCHEMAS = {
@@ -21,5 +21,5 @@ export const SCHEMAS = {
     planCatalog: planCatalogSchema,
     promoCode: promoCodeSchema,
     auditEvent: auditEventSchema,
-    tenantLedger: tenantLedgerSchema,
+    subscriberLedger: subscriberLedgerSchema,
 };

package/package.json

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

package/prisma-fragments/08-subscription-contract.prisma

@@ -64,7 +64,8 @@ model SubscriptionContract {
     promoCodeSnapshots  Json @default("[]")
     termsSnapshot       Json?
 
-    lineItems ContractLineItem[]
+    lineItems     ContractLineItem[]
+    ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
@@ -121,7 +122,8 @@ model ContractLineItem {
 
     createdAt DateTime @default(now())
 
-    contract SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+    contract      SubscriptionContract    @relation(fields: [contractId], references: [id], onDelete: Cascade)
+    ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     @@index([contractId, kind])
     @@index([sourceVersionId])

package/prisma-fragments/13-subscriber.prisma

@@ -52,6 +52,7 @@ model Subscriber {
     contracts      SubscriptionContract[]
     paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
     paymentMethodSetups SubscriberPaymentMethodSetup[]
+    ledgerEntries       SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
 
     @@map("subscribers")
 }

package/prisma-fragments/15-subscriber-ledger.prisma

@@ -0,0 +1,65 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriberLedgerEntry
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The subscriber's account: one row per charge that became due, one per
+// contract line and period. The platform derives each charge from the contract
+// in force, the billing windows and the bookings, and writes it once — the
+// unique index below is what makes a second derivation of the same charge a
+// no-op, however many run at the same time. A row is never updated or deleted:
+// a mistake is answered with a counter-entry.
+//
+// A charge is net. The tax is the invoice's, decided by the tax adapter when
+// the charge is invoiced (ADR 0013), so this table records the amount, its
+// currency and the period, and nothing that a later invoice would have to
+// agree with to the cent.
+//
+// The account belongs to the subscriber, not to the tenant, and outlives it
+// (ADR 0012): `tenantId` and `subscriptionId` are kept as values, and the keys
+// that point anywhere point at the subscriber and the contract line, which are
+// kept as long as the documents that need them.
+//
+// `origin` and `source` are text holding a closed set, checked when a row is
+// read (`toSubscriberChargeRecord` in @saasicat/core):
+//   origin: activation | renewal | planChange | bundleBooking | credit | correction
+//   source: plan | bundle | discount
+//
+// Optional: adopt it where `tenantBilling.chargeJournal` is configured, which
+// needs frozen contracts (`contractFreeze`).
+//
+// Contract: @saasicat/core (SubscriberLedgerRepository).
+
+model SubscriberLedgerEntry {
+    id                 String @id @default(uuid())
+    subscriberId       String
+    tenantId           String
+    subscriptionId     String
+    contractId         String
+    contractLineItemId String
+
+    origin String
+    source String
+    // The subscription id for the plan, the booking id for an add-on, the
+    // discount's key — stable across the contracts that replace one another.
+    sourceRef String
+
+    periodStart DateTime
+    periodEnd   DateTime
+
+    currency  String
+    amountNet Decimal @db.Decimal(10, 2)
+
+    bookedAt  DateTime
+    createdAt DateTime @default(now())
+
+    subscriber       Subscriber           @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+    contract         SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Restrict)
+    contractLineItem ContractLineItem     @relation(fields: [contractLineItemId], references: [id], onDelete: Restrict)
+
+    @@unique([subscriptionId, source, sourceRef, periodStart, origin])
+    @@index([subscriberId, bookedAt])
+    @@index([contractLineItemId])
+    @@map("subscriber_ledger_entries")
+}

package/prisma-fragments/README.md

@@ -44,6 +44,7 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 | [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                                   |
 | [`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`                                                               |
 
 ## How the consumer uses the fragments
 

package/schemas/subscriber-ledger.schema.json

@@ -0,0 +1,100 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/subscriber-ledger.schema.json",
+    "title": "SubscriberCharge",
+    "description": "One charge in a subscriber's account: an amount that became due for a period, derived from a line of the contract in force. The journal is append-only — a charge 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. A charge is net: the tax is decided by the tax adapter when the charge is invoiced, from the subscriber's origin on that day, and computed once per rate on the invoice.",
+    "type": "object",
+    "required": [
+        "id",
+        "subscriberId",
+        "tenantId",
+        "subscriptionId",
+        "contractId",
+        "contractLineItemId",
+        "origin",
+        "source",
+        "sourceRef",
+        "periodStart",
+        "periodEnd",
+        "currency",
+        "amountNet",
+        "bookedAt",
+        "createdAt"
+    ],
+    "additionalProperties": false,
+    "properties": {
+        "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The charge'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."
+        },
+        "subscriberId": {
+            "type": "string",
+            "description": "The party the contract is concluded with, whose account this is. It outlives the tenant."
+        },
+        "tenantId": {
+            "type": "string",
+            "description": "The tenant the subscription belonged to when the charge arose."
+        },
+        "subscriptionId": {
+            "type": "string",
+            "description": "The subscription the charge arose on. Part of the natural key."
+        },
+        "contractId": {
+            "type": "string",
+            "description": "The contract whose line the charge realises."
+        },
+        "contractLineItemId": {
+            "type": "string",
+            "description": "The contract line the charge came from, so that every invoice line can be traced back to what was agreed."
+        },
+        "origin": { "$ref": "#/$defs/SubscriberChargeOrigin" },
+        "source": { "$ref": "#/$defs/SubscriberChargeSource" },
+        "sourceRef": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Which thing of its source the charge is for, stable across contracts: the subscription id for the plan, the booking id for an add-on, the discount's key for a discount. Part of the natural key (subscriptionId, source, sourceRef, periodStart, origin), which is unique — a charge derived twice is written once."
+        },
+        "periodStart": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The start of the period the charge belongs to — the grouping key for an invoice."
+        },
+        "periodEnd": { "type": "string", "format": "date-time" },
+        "currency": {
+            "type": "string",
+            "pattern": "^[A-Z]{3}$",
+            "description": "ISO 4217, as the contract line records it — recorded per charge so that a charge written in 2026 still means what it meant after the configured currency changes."
+        },
+        "amountNet": {
+            "type": "number",
+            "description": "Net, rounded to the currency's decimal places once, when the charge is written; the written figure is the truth from then on. Negative for a discount."
+        },
+        "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" }
+    },
+
+    "$defs": {
+        "SubscriberChargeOrigin": {
+            "type": "string",
+            "enum": [
+                "activation",
+                "renewal",
+                "planChange",
+                "bundleBooking",
+                "credit",
+                "correction"
+            ],
+            "description": "What made the charge arise. activation: the first period of a subscription. renewal: a later period. planChange: what an immediate plan change adds. bundleBooking: the first, short period of an add-on. credit: a decision that reduces what is owed. correction: a counter-entry reversing an earlier charge, which is how the append-only journal answers a mistake."
+        },
+        "SubscriberChargeSource": {
+            "type": "string",
+            "enum": ["plan", "bundle", "discount"],
+            "description": "Which kind of contract line the charge realises."
+        }
+    }
+}

package/sql/1.0-a-subscriber-account-records-its-charges.postgres.sql

@@ -0,0 +1,101 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a subscriber's account records the charges its contracts give.
+-- =============================================================================
+--
+-- The journal of charges: one row per contract line and period, derived from
+-- the contract in force, the billing windows and the bookings, and written
+-- once (ADR 0012, #276 step 4). Needed where `tenantBilling.chargeJournal` is
+-- configured. Run it BEFORE `db push`, and after
+-- `1.0-a-contract-names-its-subscriber.postgres.sql`, whose `subscribers`
+-- table it points at:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-subscriber-account-records-its-charges.postgres.sql
+--
+-- What it touches, in one transaction:
+--
+--   `subscriber_ledger_entries` — created with its indexes, among them the
+--   unique index on (subscriptionId, source, sourceRef, periodStart, origin)
+--   that makes a charge derived twice a charge written once, and its foreign
+--   keys to `subscribers`, `subscription_contracts` and `contract_line_items`.
+--   Skipped, with a notice, where one of those three tables is missing.
+--
+-- Nothing is backfilled: the first time the platform brings an account up to
+-- date it charges the period each subscription is in, and nothing before it.
+--
+-- Safe to run again: the table and every index are created only where they are
+-- missing, and each foreign key only where its name is not taken. On a
+-- database created from `reference-schema.postgres.sql` the whole file does
+-- nothing at all.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('subscribers') IS NULL
+        OR to_regclass('subscription_contracts') IS NULL
+        OR to_regclass('contract_line_items') IS NULL THEN
+        RAISE NOTICE 'subscribers, subscription_contracts or contract_line_items is not present — subscriber_ledger_entries is not created; the journal needs contracts and the subscribers they are concluded with.';
+        RETURN;
+    END IF;
+
+    CREATE TABLE IF NOT EXISTS "subscriber_ledger_entries" (
+        "id" TEXT NOT NULL,
+        "subscriberId" TEXT NOT NULL,
+        "tenantId" TEXT NOT NULL,
+        "subscriptionId" TEXT NOT NULL,
+        "contractId" TEXT NOT NULL,
+        "contractLineItemId" TEXT NOT NULL,
+        "origin" TEXT NOT NULL,
+        "source" TEXT NOT NULL,
+        "sourceRef" TEXT NOT NULL,
+        "periodStart" TIMESTAMP(3) NOT NULL,
+        "periodEnd" TIMESTAMP(3) NOT NULL,
+        "currency" TEXT NOT NULL,
+        "amountNet" DECIMAL(10,2) NOT NULL,
+        "bookedAt" TIMESTAMP(3) NOT NULL,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        CONSTRAINT "subscriber_ledger_entries_pkey" PRIMARY KEY ("id")
+    );
+    CREATE INDEX IF NOT EXISTS "subscriber_ledger_entries_subscriberId_bookedAt_idx"
+        ON "subscriber_ledger_entries"("subscriberId", "bookedAt");
+    CREATE INDEX IF NOT EXISTS "subscriber_ledger_entries_contractLineItemId_idx"
+        ON "subscriber_ledger_entries"("contractLineItemId");
+    -- The name is the one Prisma derives and cuts at 63 characters, so that a
+    -- later `db push` finds it rather than creating a second index.
+    CREATE UNIQUE INDEX IF NOT EXISTS "subscriber_ledger_entries_subscriptionId_source_sourceRef_p_key"
+        ON "subscriber_ledger_entries"("subscriptionId", "source", "sourceRef", "periodStart", "origin");
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_subscriberId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_subscriberId_fkey"
+            FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_contractId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_contractId_fkey"
+            FOREIGN KEY ("contractId") REFERENCES "subscription_contracts"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('subscriber_ledger_entries')
+           AND conname = 'subscriber_ledger_entries_contractLineItemId_fkey'
+    ) THEN
+        ALTER TABLE "subscriber_ledger_entries"
+            ADD CONSTRAINT "subscriber_ledger_entries_contractLineItemId_fkey"
+            FOREIGN KEY ("contractLineItemId") REFERENCES "contract_line_items"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+COMMIT;

package/sql/reference-schema.postgres.sql

@@ -17,6 +17,7 @@
 --   prisma-fragments/12-applied-settings.prisma
 --   prisma-fragments/13-subscriber.prisma
 --   prisma-fragments/14-payments.prisma
+--   prisma-fragments/15-subscriber-ledger.prisma
 -- plus the normative constraints from sql/constraints.postgres.sql.
 -- Do not edit by hand — change the fragments/constraints and regenerate.
 
@@ -684,6 +685,27 @@ CREATE TABLE "PaymentEventLog" (
     CONSTRAINT "PaymentEventLog_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "subscriber_ledger_entries" (
+    "id" TEXT NOT NULL,
+    "subscriberId" TEXT NOT NULL,
+    "tenantId" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "contractId" TEXT NOT NULL,
+    "contractLineItemId" TEXT NOT NULL,
+    "origin" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "sourceRef" TEXT NOT NULL,
+    "periodStart" TIMESTAMP(3) NOT NULL,
+    "periodEnd" TIMESTAMP(3) NOT NULL,
+    "currency" TEXT NOT NULL,
+    "amountNet" DECIMAL(10,2) NOT NULL,
+    "bookedAt" TIMESTAMP(3) NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "subscriber_ledger_entries_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateIndex
 CREATE UNIQUE INDEX "subscriptions_tenantId_key" ON "subscriptions"("tenantId");
 
@@ -909,6 +931,15 @@ CREATE INDEX "PaymentEventLog_status_processedAt_idx" ON "PaymentEventLog"("stat
 -- CreateIndex
 CREATE UNIQUE INDEX "PaymentEventLog_gatewayAccount_eventId_key" ON "PaymentEventLog"("gatewayAccount", "eventId");
 
+-- CreateIndex
+CREATE INDEX "subscriber_ledger_entries_subscriberId_bookedAt_idx" ON "subscriber_ledger_entries"("subscriberId", "bookedAt");
+
+-- CreateIndex
+CREATE INDEX "subscriber_ledger_entries_contractLineItemId_idx" ON "subscriber_ledger_entries"("contractLineItemId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscriber_ledger_entries_subscriptionId_source_sourceRef_p_key" ON "subscriber_ledger_entries"("subscriptionId", "source", "sourceRef", "periodStart", "origin");
+
 -- AddForeignKey
 ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_planVersionId_fkey" FOREIGN KEY ("planVersionId") REFERENCES "plan_versions"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
@@ -960,6 +991,15 @@ ALTER TABLE "subscriber_payment_methods" ADD CONSTRAINT "subscriber_payment_meth
 -- AddForeignKey
 ALTER TABLE "subscriber_payment_method_setups" ADD CONSTRAINT "subscriber_payment_method_setups_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_subscriberId_fkey" FOREIGN KEY ("subscriberId") REFERENCES "subscribers"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_contractId_fkey" FOREIGN KEY ("contractId") REFERENCES "subscription_contracts"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "subscriber_ledger_entries" ADD CONSTRAINT "subscriber_ledger_entries_contractLineItemId_fkey" FOREIGN KEY ("contractLineItemId") REFERENCES "contract_line_items"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- =============================================================================
 -- SaaSiCat — normative PostgreSQL constraints the Prisma DSL cannot express.
 -- =============================================================================

package/schemas/tenant-ledger.schema.json

@@ -1,236 +0,0 @@
-{
-    "$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" }
-                        ]
-                    }
-                }
-            }
-        }
-    }
-}