@saasicat/spec 1.0.0-rc.25 → 1.0.0-rc.26

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.25
+    version: 1.0.0-rc.26
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -387,6 +387,45 @@ paths:
                 '404':
                     description: No tenant with this slug (`TENANT_NOT_FOUND`)
 
+    /invoices/{id}/document:
+        parameters:
+            - name: id
+              in: path
+              required: true
+              description: The invoice's id
+              schema: { type: string }
+        get:
+            tags: [subscriptions]
+            summary: The document an invoice was issued as
+            description: >-
+                Served where the platform keeps invoices
+                (`tenantBilling.chargeJournal.invoices`) and shows tenants
+                (`adminResources`); the manifest announces it as
+                `invoices.read`. Answers the file archived for the invoice,
+                checked against the checksum recorded when it was rendered —
+                never a new rendering. Its media type is the one the renderer
+                gave, a PDF for a ZUGFeRD invoice.
+            responses:
+                '200':
+                    description: The archived file, as an attachment
+                    headers:
+                        Content-Disposition:
+                            description: >-
+                                `attachment; filename="…"`, the renderer's file
+                                name kept to letters, digits, `.`, `_` and `-`
+                            schema: { type: string }
+                    content:
+                        application/pdf:
+                            schema: { type: string, format: binary }
+                '404':
+                    description: No invoice with this id (`SUBSCRIPTION_INVOICE_NOT_FOUND`)
+                '409':
+                    description: >-
+                        The invoice still waits for its document
+                        (`SUBSCRIPTION_INVOICE_DOCUMENT_NOT_ARCHIVED`), or its
+                        archived file does not match the recorded checksum and
+                        is not handed out (`SUBSCRIPTION_INVOICE_DOCUMENT_MISMATCH`)
+
     /tenants/{slug}/subscriber:
         parameters:
             - $ref: '#/components/parameters/TenantSlug'
@@ -1354,6 +1393,129 @@ paths:
                                 type: array
                                 items: { $ref: '#/components/schemas/BundleVersionRetirement' }
 
+    # ── Feature withdrawals ──
+    #
+    # Served where the manifest carries the capability `features.withdraw`: where the
+    # installation can list everybody a withdrawal reaches. A feature withdrawn for a reason
+    # outside the platform — an external service stopped, a law changed — is granted to
+    # nobody from the date named until the withdrawal is lifted. The subscriptions holding
+    # it when it is announced are told at once; each line is reduced by the amount named
+    # for its plan or add-on and rhythm, and each may end at once while it is withdrawn.
+
+    /feature-withdrawals:
+        get:
+            tags: [catalog]
+            summary: Every withdrawal, the most recently announced first
+            responses:
+                '200':
+                    description: List, each with how many it reached, told and ended at once
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/FeatureWithdrawal' }
+        post:
+            tags: [catalog]
+            summary: Withdraw a feature from every subscription that holds it
+            description: >-
+                The withdrawal and one notice per subscription are recorded in one transaction,
+                then handed to the application's `SubscriptionNoticePort` as `feature-withdrawn`;
+                a notice that cannot be sent now is sent by the next run. The reductions are
+                written into each subscription's contract. Audited as FEATURE_WITHDRAW.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/FeatureWithdrawalAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalAnnounced' }
+                '404':
+                    description: >-
+                        Not offered here: the stores cannot list everybody a withdrawal reaches
+                        (`FEATURE_WITHDRAWAL_UNAVAILABLE`)
+                '409':
+                    description: >-
+                        The subscriptions it reaches are no longer the ones named
+                        (`FEATURE_WITHDRAWAL_PREVIEW_CHANGED`, with the preview as it stands), or
+                        another withdrawal of the feature landed first (`FEATURE_WITHDRAWAL_OPEN`)
+                '422':
+                    description: >-
+                        An unknown feature (`FEATURE_WITHDRAWAL_FEATURE_UNKNOWN`), a date already
+                        past (`FEATURE_WITHDRAWAL_DATE_IN_PAST`), a reduction that names nothing it
+                        reaches, is named twice or exceeds the lowest price it reduces
+                        (`FEATURE_WITHDRAWAL_REDUCTION_*`), or the first blocker the preview reports
+
+    /feature-withdrawals/preview:
+        get:
+            tags: [catalog]
+            summary: What withdrawing the feature from the date would do now
+            parameters:
+                - name: featureKey
+                  in: query
+                  required: true
+                  schema: { type: string }
+                - name: effectiveFrom
+                  in: query
+                  required: false
+                  description: ISO-8601; now where left out
+                  schema: { type: string, format: date-time }
+            responses:
+                '200':
+                    description: >-
+                        Whom it reaches with which lines, whom it does not and why, the plans and
+                        add-ons a reduction may be named for, and every blocker
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalPreview' }
+                '404':
+                    description: Not offered here (`FEATURE_WITHDRAWAL_UNAVAILABLE`)
+                '422':
+                    description: >-
+                        An unknown feature (`FEATURE_WITHDRAWAL_FEATURE_UNKNOWN`), or a date already
+                        past (`FEATURE_WITHDRAWAL_DATE_IN_PAST`)
+
+    /feature-withdrawals/{id}/lift:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        post:
+            tags: [catalog]
+            summary: Lift a withdrawal from a date
+            description: >-
+                From the date the feature is granted again, and the reduction and the right to end
+                at once end; every subscription it reached that still runs is told as
+                `feature-withdrawal-lifted`. Audited as FEATURE_WITHDRAWAL_LIFT.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                liftedFrom:
+                                    type: string
+                                    format: date-time
+                                    description: ISO-8601; now where left out
+            responses:
+                '201':
+                    description: Lifted
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalLifted' }
+                '404':
+                    description: No withdrawal has that id (`FEATURE_WITHDRAWAL_NOT_FOUND`)
+                '409':
+                    description: >-
+                        Lifted already (`FEATURE_WITHDRAWAL_ALREADY_LIFTED`, with its date), or nobody
+                        it reaches told of it yet, telling them having failed just now
+                        (`FEATURE_WITHDRAWAL_NOT_TOLD_YET`)
+                '422':
+                    description: A date already past (`FEATURE_WITHDRAWAL_LIFT_IN_PAST`)
+
     # ── Bundles ──
     /catalog/bundles:
         get:
@@ -2384,6 +2546,182 @@ components:
                 told: { type: integer, description: 'Notices sent at once' }
                 failed: { type: integer, description: 'Notices the next run sends' }
 
+        FeatureWithdrawalReduction:
+            type: object
+            required: [kind, key, billingCycle, amountNet]
+            properties:
+                kind: { type: string, enum: [plan, bundle] }
+                key: { type: string, description: 'The plan key, or the add-on key' }
+                billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                amountNet:
+                    type: number
+                    description: 'Net, per whole period of the rhythm, to the cent'
+
+        FeatureWithdrawalAnnouncement:
+            type: object
+            required: [featureKey, reason, reductions, subscriptionIds]
+            properties:
+                featureKey: { type: string }
+                reason: { type: string, description: 'Shown to the subscribers as written' }
+                effectiveFrom:
+                    { type: string, format: date-time, description: 'Now where left out' }
+                reductions:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureWithdrawalReduction' }
+                subscriptionIds:
+                    type: array
+                    description: 'The subscriptions the operator was shown in the preview'
+                    items: { type: string }
+
+        FeatureWithdrawalRow:
+            type: object
+            required:
+                [
+                    id,
+                    featureKey,
+                    reason,
+                    effectiveFrom,
+                    liftedFrom,
+                    reductions,
+                    announcedAt,
+                    announcedBy,
+                    liftedAt,
+                    liftedBy,
+                    toldAt,
+                ]
+            properties:
+                id: { type: string }
+                featureKey: { type: string }
+                reason: { type: string }
+                effectiveFrom: { type: string, format: date-time }
+                liftedFrom: { type: [string, 'null'], format: date-time }
+                reductions:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureWithdrawalReduction' }
+                announcedAt: { type: string, format: date-time }
+                announcedBy:
+                    { type: string, description: 'An actor tag, as the audit log writes it' }
+                liftedAt: { type: [string, 'null'], format: date-time }
+                liftedBy: { type: [string, 'null'] }
+                toldAt:
+                    type: [string, 'null']
+                    format: date-time
+                    description: >-
+                        When the subscriptions it reaches were told; null until then — the
+                        quarter-hourly run tells a withdrawal still null.
+
+        FeatureWithdrawal:
+            allOf:
+                - $ref: '#/components/schemas/FeatureWithdrawalRow'
+                - type: object
+                  required: [featureLabel, progress]
+                  properties:
+                      featureLabel: { type: string }
+                      progress:
+                          type: object
+                          required: [reached, told, endedAtOnce]
+                          properties:
+                              reached: { type: integer, description: 'Subscriptions it reached' }
+                              told:
+                                  type: integer
+                                  description: 'Of those, the ones whose notice reached somebody'
+                              endedAtOnce:
+                                  type: integer
+                                  description: 'Subscriptions and bookings ended at once under it'
+
+        FeatureWithdrawalAnnounced:
+            type: object
+            required: [withdrawal, told, failed]
+            properties:
+                withdrawal: { $ref: '#/components/schemas/FeatureWithdrawalRow' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
+        FeatureWithdrawalLifted:
+            type: object
+            required: [withdrawal, told, failed]
+            properties:
+                withdrawal: { $ref: '#/components/schemas/FeatureWithdrawalRow' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
+        FeatureWithdrawalPreview:
+            type: object
+            required: [feature, effectiveFrom, asOf, reached, skipped, targets, blockers]
+            properties:
+                feature:
+                    type: object
+                    required: [key, label]
+                    properties:
+                        key: { type: string }
+                        label: { type: string }
+                effectiveFrom: { type: string, description: 'ISO-8601' }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, status, lines, specialTerms]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            status: { type: string }
+                            lines:
+                                type: array
+                                items:
+                                    type: object
+                                    required:
+                                        [
+                                            line,
+                                            key,
+                                            label,
+                                            subscriptionBundleId,
+                                            billingCycle,
+                                            priceNet,
+                                        ]
+                                    properties:
+                                        line: { type: string, enum: [plan, bundle] }
+                                        key: { type: string }
+                                        label: { type: string }
+                                        subscriptionBundleId: { type: [string, 'null'] }
+                                        billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                                        priceNet: { type: [number, 'null'] }
+                            specialTerms:
+                                type: boolean
+                                description: 'Holds the feature through special terms, and no line'
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            reason: { type: string, enum: [ends-before] }
+                targets:
+                    type: array
+                    description: 'Each plan and add-on in a rhythm a reduction may be named for'
+                    items:
+                        type: object
+                        required: [kind, key, label, billingCycle, lines, lowestPriceNet]
+                        properties:
+                            kind: { type: string, enum: [plan, bundle] }
+                            key: { type: string }
+                            label: { type: string }
+                            billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                            lines: { type: integer }
+                            lowestPriceNet: { type: [number, 'null'] }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'FEATURE_WITHDRAWAL_*' }
+                            message: { type: string }
+                            params: { type: object }
+
         RetiredBundleVersionRef:
             type: object
             required: [bundleVersionId, bundleKey, version]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/spec",
-  "version": "1.0.0-rc.25",
+  "version": "1.0.0-rc.26",
   "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

@@ -73,6 +73,7 @@ model SubscriptionContract {
 
     lineItems     ContractLineItem[]
     ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoices      SubscriptionInvoice[]     // see 20-subscription-invoice.prisma
 
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
@@ -131,6 +132,7 @@ model ContractLineItem {
 
     contract      SubscriptionContract    @relation(fields: [contractId], references: [id], onDelete: Cascade)
     ledgerEntries SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoiceLines  SubscriptionInvoiceLine[] // see 20-subscription-invoice.prisma
 
     @@index([contractId, kind])
     @@index([sourceVersionId])

package/prisma-fragments/13-subscriber.prisma

@@ -75,6 +75,7 @@ model Subscriber {
     paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
     paymentMethodSetups SubscriberPaymentMethodSetup[]
     ledgerEntries       SubscriberLedgerEntry[] // see 15-subscriber-ledger.prisma
+    invoices            SubscriptionInvoice[]   // see 20-subscription-invoice.prisma
 
     @@map("subscribers")
 }

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

@@ -57,6 +57,7 @@ model SubscriberLedgerEntry {
     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)
+    invoiceLine      SubscriptionInvoiceLine? // see 20-subscription-invoice.prisma
 
     @@unique([subscriptionId, source, sourceRef, periodStart, origin])
     @@index([subscriberId, bookedAt])

package/prisma-fragments/20-subscription-invoice.prisma

@@ -0,0 +1,145 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriptionInvoice
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The invoices issued from the charge journal (15-subscriber-ledger.prisma):
+// the charges a billing period opens with on one invoice, a charge that arises
+// later on an invoice of its own. An invoice copies everything it states when
+// it is issued — the issuer, the subscriber, the tax treatment the adapter
+// decided, the tax per rate — so a later change leaves it as it was. Nothing
+// updates or deletes an invoice; a correction is a cancellation invoice and its
+// replacement.
+//
+// A line invoices one charge, and a charge stands on one line: the unique
+// `chargeId` is what makes a second run issuing the same charges write
+// nothing, however many run at the same time.
+//
+// The number range is the table `subscription_invoice_numbers`, one row per
+// year holding the last number drawn. An invoice draws its number by raising
+// that row in the transaction that writes the invoice, so an invoice that
+// fails to be written leaves no gap, and two at the same time wait for each
+// other rather than drawing the same number. One installation is the range of
+// one issuer; the number is `<prefix>-<year>-<sequence>`.
+//
+// The days an invoice states — its issue date, its due date, the period its
+// charges cover — are calendar days in the installation's time zone, kept as
+// `date` columns; `issuedAt` is the instant it was issued.
+//
+// `origin` and `source` on a line are text holding the charge's closed sets,
+// checked when a row is read (`toSubscriptionInvoiceRecord` in @saasicat/core).
+//
+// Optional: adopt it, all four models together, where
+// `tenantBilling.chargeJournal.invoices` is configured, which needs the charge
+// journal.
+//
+// Contract: @saasicat/core (SubscriptionInvoiceRepository).
+
+model SubscriptionInvoice {
+    id             String @id @default(uuid())
+    number         String @unique
+    numberPrefix   String
+    numberYear     Int
+    numberSequence Int
+
+    tenantId       String
+    subscriberId   String
+    subscriptionId String
+    contractId     String
+
+    issuedAt           DateTime
+    issueDate          DateTime @db.Date
+    dueDate            DateTime @db.Date
+    servicePeriodFrom  DateTime @db.Date
+    servicePeriodUntil DateTime @db.Date
+
+    currency        String
+    // The parties as the invoice names them, copied when it was issued.
+    issuerParty     Json
+    subscriberParty Json
+    // The footer lines config/saas.yaml named on the issue date (SC-PRIC-077).
+    footer          Json    @default("[]")
+    // The adapter's treatment, with its name and version, and the tax per rate.
+    taxTreatment    Json
+    taxes           Json
+    totalNet        Decimal @db.Decimal(12, 2)
+    totalTax        Decimal @db.Decimal(12, 2)
+    totalGross      Decimal @db.Decimal(12, 2)
+
+    createdAt DateTime @default(now())
+
+    subscriber Subscriber                   @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+    contract   SubscriptionContract         @relation(fields: [contractId], references: [id], onDelete: Restrict)
+    lines      SubscriptionInvoiceLine[]
+    document   SubscriptionInvoiceDocument?
+    archive    SubscriptionInvoiceArchive?
+
+    @@unique([numberYear, numberSequence])
+    @@index([subscriberId, issuedAt])
+    @@index([subscriptionId])
+    @@map("subscription_invoices")
+}
+
+model SubscriptionInvoiceLine {
+    id                 String @id @default(uuid())
+    invoiceId          String
+    position           Int
+    chargeId           String @unique
+    contractLineItemId String
+
+    title  String
+    origin String
+    source String
+
+    periodFrom  DateTime @db.Date
+    periodUntil DateTime @db.Date
+
+    amountNet Decimal @db.Decimal(10, 2)
+    taxRate   Decimal @db.Decimal(5, 2)
+
+    invoice          SubscriptionInvoice   @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+    charge           SubscriberLedgerEntry @relation(fields: [chargeId], references: [id], onDelete: Restrict)
+    contractLineItem ContractLineItem      @relation(fields: [contractLineItemId], references: [id], onDelete: Restrict)
+
+    @@unique([invoiceId, position])
+    @@index([contractLineItemId])
+    @@map("subscription_invoice_lines")
+}
+
+// Where an invoice's document stands. The checksum is recorded once, before
+// the file is archived, and every later download is checked against it; the
+// archive's confirmation and the delivery are set once each. A rendering with
+// another checksum is refused rather than recorded over the first. A run claims
+// the mail before it sends it, so of several instances one does.
+model SubscriptionInvoiceDocument {
+    invoiceId         String    @id
+    // SHA-256 of the rendered file, 64 lower-case hex digits.
+    checksum          String
+    mediaType         String
+    fileName          String
+    // In bytes.
+    size              Int
+    renderedAt        DateTime
+    // Null while the invoice waits for its document.
+    archivedAt        DateTime?
+    // When the run mailing it took it on; null while no run holds it.
+    deliveryClaimedAt DateTime?
+    // Null until the invoice is handed to the mail.
+    deliveredAt       DateTime?
+    deliveredTo       String?
+
+    invoice SubscriptionInvoice @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+
+    @@index([archivedAt])
+    @@map("subscription_invoice_documents")
+}
+
+model SubscriptionInvoiceNumber {
+    // The year the numbers count in; the range restarts at 1 each year.
+    year Int @id
+    // The last number drawn in that year.
+    last Int
+
+    @@map("subscription_invoice_numbers")
+}

package/prisma-fragments/21-feature-withdrawal.prisma

@@ -0,0 +1,56 @@
+// =============================================================================
+// SaaS platform Prisma fragment: FeatureWithdrawal
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// One row per feature withdrawn for a reason outside the platform: an external
+// service the feature depends on stopped, or a law took it away or changed it.
+// From `effectiveFrom` the platform grants the feature to nobody, until the
+// operator lifts the withdrawal from `liftedFrom`. Kept as evidence of what was
+// announced, why, when and by whom, and of the reductions the operator named.
+//
+// What it means for each subscription it reaches — which lines, what each is
+// reduced by — is a `subscription_notices` row of kind feature-withdrawn whose
+// subject is this row's id. Those are written once this row is: who it reaches
+// is read after it is recorded, so a change concluded while it was being
+// announced is reached, and `toldAt` is set in the transaction that writes
+// them. A row whose `toldAt` is still null is told by the next run.
+//
+// `reductions` is a JSON list of `{ kind, key, billingCycle, amountNet }`: the
+// net amount a plan or an add-on, by its key, is reduced by for one whole
+// period of that rhythm without the feature.
+//
+// At most ONE withdrawal of a feature is not lifted at a time. Prisma cannot
+// express a partial unique index; the one that holds it is in
+// sql/constraints.postgres.sql, and it is what makes two operators announcing
+// at the same moment land one withdrawal rather than two.
+//
+// Optional: adopt it where an operator may withdraw features. Without it,
+// withdrawing a feature is off.
+//
+// Contract: @saasicat/core (FeatureWithdrawalRepository).
+
+model FeatureWithdrawal {
+    id         String    @id @default(uuid())
+    featureKey String
+    // Why, in the operator's words, shown to the subscribers as written.
+    reason     String
+
+    effectiveFrom DateTime
+    // Null until the operator lifts it.
+    liftedFrom    DateTime?
+
+    reductions Json @default("[]")
+
+    announcedAt DateTime @default(now())
+    // Who announced it, and who lifted it — actor tags, as the audit log writes them.
+    announcedBy String
+    liftedAt    DateTime?
+    liftedBy    String?
+    // When the subscriptions it reaches were told; null until then.
+    toldAt      DateTime?
+
+    @@index([featureKey])
+    @@map("feature_withdrawals")
+}

package/prisma-fragments/22-subscription-invoice-archive.prisma

@@ -0,0 +1,34 @@
+// =============================================================================
+// SaaSiCat platform Prisma fragment: SubscriptionInvoiceArchive
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// The database archive of the invoices' documents (20-subscription-invoice.prisma):
+// one file per invoice, under its invoice, with the checksum recorded when it
+// was rendered. A row is written once and never changed: the migration
+// `1.0-an-invoice-document-is-archived.postgres.sql` installs a trigger that
+// refuses every UPDATE and DELETE, whoever asks. Keep it, with its database
+// backups, as long as the law asks — in Germany 8 years from the end of the
+// calendar year an invoice was issued in — and in the European Union.
+//
+// Optional: adopt it where the invoices' documents are kept in the database,
+// as `persistence.entitlement.subscriptionInvoiceArchive` keeps them. An
+// installation that archives elsewhere, such as object storage with a
+// retention lock, binds its own `InvoiceArchivePort` instead.
+//
+// Contract: @saasicat/core (InvoiceArchivePort).
+
+model SubscriptionInvoiceArchive {
+    invoiceId  String   @id
+    // SHA-256 of `content`, 64 lower-case hex digits.
+    checksum   String
+    mediaType  String
+    fileName   String
+    content    Bytes
+    archivedAt DateTime
+
+    invoice SubscriptionInvoice @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+
+    @@map("subscription_invoice_archive")
+}