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

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.20
+    version: 1.0.0-rc.21
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -1979,6 +1979,9 @@ components:
                 validUntil: { type: string, format: date-time, nullable: true }
                 maxRedemptions: { type: integer, nullable: true }
                 redemptionsCount: { type: integer }
+                heldCount:
+                    type: integer
+                    description: Slots held for checkouts that started and have not concluded.
                 appliesToPlans:
                     type: array
                     items: { type: string }

package/package.json

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

package/prisma-fragments/02-promo-code.prisma

@@ -56,6 +56,10 @@ model PromoCode {
     // Availability-relevant — counts only redemptions with status=ACTIVE.
     // Incremented atomically in the redeem() path, decremented on trial cancellation.
     redemptionsCount Int @default(0)
+    // Slots kept for checkouts that have started and not concluded (see
+    // PromoCodeHold). A code has a free slot while redemptionsCount + heldCount
+    // stays below maxRedemptions; the status says nothing about holds.
+    heldCount        Int @default(0)
 
     // Plan whitelist as String[] — values are plan IDs from plans.yaml.
     // Consumers using a Postgres enum can cast the field locally.
@@ -86,6 +90,7 @@ model PromoCode {
 
     redemptions    PromoCodeRedemption[]
     validationLogs PromoCodeValidationLog[]
+    holds          PromoCodeHold[]
 
     @@index([status, validFrom, validUntil])
     @@index([campaignTag])
@@ -126,6 +131,39 @@ model PromoCodeRedemption {
     @@map("promo_code_redemptions")
 }
 
+// -----------------------------------------------------------------------------
+// PromoCodeHold — a slot of a code kept for a checkout from its start, so that
+// a customer who reaches the payment form keeps the code they started with.
+// For a sign-up, `expiresAt` is the last moment a confirmation of its payment
+// form can arrive, not the checkout's lifetime. It counts in
+// PromoCode.heldCount, and it ends in one of three ways, each deleting the row
+// and giving the count back: the conclusion turns it into the redemption, the
+// checkout offer's code changes, or `expiresAt` passes. It is a reservation
+// rather than a record — what a customer was granted is the
+// PromoCodeRedemption.
+// -----------------------------------------------------------------------------
+
+model PromoCodeHold {
+    id          String @id @default(uuid())
+    promoCodeId String
+    // Not a foreign key: an offer deleted while it holds a slot leaves the hold
+    // to expire, which gives the slot back. A cascade would delete the row and
+    // leave heldCount counting it.
+    checkoutOfferId String    @unique
+    expiresAt       DateTime
+    // The id of the transaction a conclusion runs on (`txid_current()`), set on
+    // that transaction and gone before it commits: the redemption running on
+    // the same transaction finds its slot by it, and no other one can.
+    handedOverTx    BigInt?
+    createdAt       DateTime  @default(now())
+
+    promoCode PromoCode @relation(fields: [promoCodeId], references: [id])
+
+    @@index([promoCodeId, expiresAt])
+    @@index([expiresAt])
+    @@map("promo_code_holds")
+}
+
 // -----------------------------------------------------------------------------
 // PromoCodeValidationLog — audit trail of all validation attempts
 // (including failed NOT_FOUND/EXPIRED), for anti-abuse analysis.

package/prisma-fragments/14-payments.prisma

@@ -15,6 +15,14 @@
 // payment method, a partial unique index in sql/constraints.postgres.sql;
 // the one a newer payment method replaced stays as `REPLACED`.
 //
+// Within an account a reference belongs to exactly one subscriber, which is
+// what `@@unique([gatewayAccount, paymentMethodRef])` below holds. The port
+// draws the same boundary for reading: a confirmation carrying a reference
+// another subscriber holds is refused rather than recorded, and a read by
+// reference names the subscriber it asks about. Both are reached on the
+// gateway's callback, which arrives without a session — an installation that
+// keeps its tenants apart with a policy on this table lifts it there.
+//
 // Contract: @saasicat/core (SubscriberPaymentMethodRepository, PaymentEventLog).
 // Both are needed wherever payment methods are taken — self-registration or
 // not — because every gateway callback is claimed in `PaymentEventLog`.

package/prisma-fragments/README.md

@@ -28,22 +28,22 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 
 ## Files
 
-| File                                                                 | Models                                                                       |
-| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                      |
-| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeValidationLog` + Enums         |
-| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                        |
-| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                   |
-| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                    |
-| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                      |
-| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                  |
-| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                   |
-| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                 |
-| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                            |
-| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                         |
-| [`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` |
+| File                                                                 | Models                                                                                |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                               |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeHold`, `PromoCodeValidationLog` + Enums |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                                 |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                            |
+| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                             |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                               |
+| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                           |
+| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                            |
+| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration` + `RegistrationStatus`                                          |
+| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                                     |
+| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                                  |
+| [`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`          |
 
 ## How the consumer uses the fragments
 
@@ -94,7 +94,7 @@ from ever being deleted.
 ### 3. Table names (`@@map`) are canonical
 
 `subscriptions`, `checkout_offers`, `plans`, `plan_versions`, `promo_codes`,
-`promo_code_redemptions`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
+`promo_code_redemptions`, `promo_code_holds`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
 `bundle_versions`, `capability_catalog_entries`, `feature_catalog_entries`,
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,

package/schemas/admin-manifest.schema.json

@@ -76,7 +76,7 @@
             "properties": {
                 "source": {
                     "type": "string",
-                    "description": "Path to the source, e.g. 'config/saas.yaml'"
+                    "description": "Where the plans and features were read from: 'database' for the ones an operator publishes, 'given' for a catalogue passed in at start"
                 },
                 "hash": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/=_-]{32,}$" },
                 "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },

package/schemas/promo-code.schema.json

@@ -129,7 +129,8 @@
                 "value",
                 "durationType",
                 "status",
-                "redemptionsCount"
+                "redemptionsCount",
+                "heldCount"
             ],
             "additionalProperties": false,
             "properties": {
@@ -143,6 +144,11 @@
                 "validUntil": { "type": ["string", "null"], "format": "date-time" },
                 "maxRedemptions": { "type": ["integer", "null"], "minimum": 1 },
                 "redemptionsCount": { "type": "integer", "minimum": 0 },
+                "heldCount": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Slots held for checkouts that started and have not concluded. A code has a free slot while redemptionsCount + heldCount is below maxRedemptions."
+                },
                 "appliesToPlans": {
                     "type": "array",
                     "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" }

package/sql/1.0-a-promo-slot-is-held-through-checkout.postgres.sql

@@ -0,0 +1,69 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a promo code's slot is held from the start of a checkout.
+-- =============================================================================
+--
+-- A sign-up that starts its checkout with a promo code keeps a slot of that
+-- code until the checkout concludes, or until a confirmation of its payment
+-- form can no longer arrive, so that a customer who reaches the payment form is
+-- not refused afterwards because somebody else took the code's last redemption
+-- in between. Run it the same way as the other files in
+-- this directory, before `db push` where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-promo-slot-is-held-through-checkout.postgres.sql
+--
+-- What it touches, in one transaction, and only where `promo_codes` is there:
+--
+--   1. `promo_codes` — gains `heldCount`, the slots held for checkouts, next to
+--      `redemptionsCount`. Every existing code starts at 0: no checkout held a
+--      slot before this file.
+--   2. `promo_code_holds` — created with its indexes and its foreign key to
+--      `promo_codes`. One row per checkout offer holding a slot; the row is
+--      deleted when the hold ends, so the table stays small.
+--
+-- Safe to run again: the column, the table and the indexes are created only
+-- where they are missing, and the 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('promo_codes') IS NULL THEN
+        RAISE NOTICE 'promo_codes is not present — nothing to do; this installation takes no promo codes.';
+        RETURN;
+    END IF;
+
+    ALTER TABLE "promo_codes" ADD COLUMN IF NOT EXISTS "heldCount" INTEGER NOT NULL DEFAULT 0;
+
+    CREATE TABLE IF NOT EXISTS "promo_code_holds" (
+        "id" TEXT NOT NULL,
+        "promoCodeId" TEXT NOT NULL,
+        "checkoutOfferId" TEXT NOT NULL,
+        "expiresAt" TIMESTAMP(3) NOT NULL,
+        "handedOverTx" BIGINT,
+        "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+        CONSTRAINT "promo_code_holds_pkey" PRIMARY KEY ("id")
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS "promo_code_holds_checkoutOfferId_key"
+        ON "promo_code_holds"("checkoutOfferId");
+    CREATE INDEX IF NOT EXISTS "promo_code_holds_promoCodeId_expiresAt_idx"
+        ON "promo_code_holds"("promoCodeId", "expiresAt");
+    CREATE INDEX IF NOT EXISTS "promo_code_holds_expiresAt_idx"
+        ON "promo_code_holds"("expiresAt");
+
+    -- `ADD CONSTRAINT` has no `IF NOT EXISTS`.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+         WHERE conrelid = to_regclass('promo_code_holds')
+           AND conname = 'promo_code_holds_promoCodeId_fkey'
+    ) THEN
+        ALTER TABLE "promo_code_holds"
+            ADD CONSTRAINT "promo_code_holds_promoCodeId_fkey"
+            FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id")
+            ON DELETE RESTRICT ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+COMMIT;

package/sql/reference-schema.postgres.sql

@@ -128,6 +128,7 @@ CREATE TABLE "promo_codes" (
     "validUntil" TIMESTAMP(3),
     "maxRedemptions" INTEGER,
     "redemptionsCount" INTEGER NOT NULL DEFAULT 0,
+    "heldCount" INTEGER NOT NULL DEFAULT 0,
     "appliesToPlans" TEXT[],
     "appliesToBilling" "BillingCycle",
     "firstTimeCustomersOnly" BOOLEAN NOT NULL DEFAULT true,
@@ -164,6 +165,18 @@ CREATE TABLE "promo_code_redemptions" (
     CONSTRAINT "promo_code_redemptions_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "promo_code_holds" (
+    "id" TEXT NOT NULL,
+    "promoCodeId" TEXT NOT NULL,
+    "checkoutOfferId" TEXT NOT NULL,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "handedOverTx" BIGINT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "promo_code_holds_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateTable
 CREATE TABLE "promo_code_validation_logs" (
     "id" TEXT NOT NULL,
@@ -710,6 +723,15 @@ CREATE INDEX "promo_code_redemptions_promoCodeId_status_idx" ON "promo_code_rede
 -- CreateIndex
 CREATE INDEX "promo_code_redemptions_startsAt_endsAt_idx" ON "promo_code_redemptions"("startsAt", "endsAt");
 
+-- CreateIndex
+CREATE UNIQUE INDEX "promo_code_holds_checkoutOfferId_key" ON "promo_code_holds"("checkoutOfferId");
+
+-- CreateIndex
+CREATE INDEX "promo_code_holds_promoCodeId_expiresAt_idx" ON "promo_code_holds"("promoCodeId", "expiresAt");
+
+-- CreateIndex
+CREATE INDEX "promo_code_holds_expiresAt_idx" ON "promo_code_holds"("expiresAt");
+
 -- CreateIndex
 CREATE INDEX "promo_code_validation_logs_codeAttempt_createdAt_idx" ON "promo_code_validation_logs"("codeAttempt", "createdAt");
 
@@ -899,6 +921,9 @@ ALTER TABLE "promo_code_redemptions" ADD CONSTRAINT "promo_code_redemptions_prom
 -- AddForeignKey
 ALTER TABLE "promo_code_redemptions" ADD CONSTRAINT "promo_code_redemptions_subscriptionId_fkey" FOREIGN KEY ("subscriptionId") REFERENCES "subscriptions"("id") ON DELETE CASCADE ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "promo_code_holds" ADD CONSTRAINT "promo_code_holds_promoCodeId_fkey" FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
 -- AddForeignKey
 ALTER TABLE "promo_code_validation_logs" ADD CONSTRAINT "promo_code_validation_logs_promoCodeId_fkey" FOREIGN KEY ("promoCodeId") REFERENCES "promo_codes"("id") ON DELETE SET NULL ON UPDATE CASCADE;