@saasicat/persistence-testing 1.0.0-rc.14 → 1.0.0-rc.15

package/README.md

@@ -16,6 +16,9 @@ Verified scenarios:
 - PlanVersion and BundleVersion validity windows with auto-succession
 - `countByPlanVersionId` counts current AND pending bindings in one query
 - transaction rollback discards writes
+- a contract written on a transaction is undone with it, and found by the offer it came from
+- a checkout offer is consumed once, whoever asks first, and a consume on a rolled-back transaction
+  leaves it open
 - `findByTenantIdLocked` serializes concurrent transactions (row lock)
 - concurrent `claimSlot` grants exactly `maxRedemptions` slots
 - claim / exhaust / release lifecycle
@@ -91,7 +94,7 @@ persistenceAdapterContract({
     }),
     // The parts this adapter deliberately does not provide. A part named here
     // that the harness does provide fails the suite as well.
-    gaps: ['subscriptionContracts', 'appliedSettings'],
+    gaps: ['subscriptionContracts', 'checkoutOffers', 'appliedSettings'],
 });
 ```
 

package/dist/.build-stamp

@@ -1 +1 @@
-fe1ab043363d0764aaf580f2167335fcb0c2659c445bcc9540708782cb751a27
+8fdc45ae34c5869710281576820410215b122b89385485ab7973ebfc8359157b

package/dist/index.cjs

@@ -38,6 +38,58 @@ module.exports = __toCommonJS(index_exports);
 var import_strict = __toESM(require("node:assert/strict"), 1);
 var import_node_test = require("node:test");
 var LOCK_HOLD_MS = 150;
+var OFFER = {
+  planKey: "STANDARD",
+  planVersionId: null,
+  billingCycle: "monthly",
+  priceBreakdown: {
+    currency: "EUR",
+    billingCycle: "monthly",
+    planNet: 49,
+    bundlesNet: 0,
+    regularNet: 49,
+    effectiveNet: 49,
+    vatRate: 19,
+    effectiveGross: 58.31
+  }
+};
+function contractFromOffer(offerId) {
+  return {
+    tenantId: `tenant-${offerId}`,
+    effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+    originalOfferId: offerId,
+    priceSnapshot: {
+      currency: "EUR",
+      billingCycle: "monthly",
+      subtotalNet: 49,
+      discountNet: 0,
+      totalNet: 49,
+      vatRate: 19,
+      totalGross: 58.31
+    },
+    lineItems: [
+      {
+        kind: "plan",
+        sourceKey: "STANDARD",
+        sourceVersionId: null,
+        titleSnapshot: "Standard",
+        descriptionSnapshot: null,
+        quantity: 1,
+        unit: null,
+        priceNet: 49,
+        priceGross: 58.31,
+        billingCycle: "monthly",
+        currency: "EUR",
+        taxRate: 19,
+        taxAmount: 9.31,
+        minimumTermUntil: null,
+        featuresSnapshot: [],
+        quotaEffectsSnapshot: {},
+        metadata: null
+      }
+    ]
+  };
+}
 var CONTRACT_GAPS = {
   atomicPlanBinding: {
     reason: "adapter does not expose atomic plan-binding writes",
@@ -138,6 +190,10 @@ var CONTRACT_GAPS = {
     reason: "adapter provides no SubscriptionContractRepository",
     present: ({ adapter }) => Boolean(adapter.subscriptionContractRepository)
   },
+  checkoutOffers: {
+    reason: "adapter provides no CheckoutOfferRepository",
+    present: ({ adapter }) => Boolean(adapter.checkoutOfferRepository)
+  },
   appliedSettings: {
     reason: "adapter provides no AppliedSettingsPort",
     present: ({ adapter }) => Boolean(adapter.appliedSettings)
@@ -1665,6 +1721,86 @@ function persistenceAdapterContract(options) {
         );
       }
     });
+    (0, import_node_test.test)("a contract written on a transaction is undone with it, and found by its offer", async (t) => {
+      const { adapter } = harness;
+      const contracts = adapter.subscriptionContractRepository;
+      if (!contracts) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      await import_strict.default.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await contracts.create(contractFromOffer("offer-rolled-back"), tx);
+          throw new Error("the conclusion fails after the contract is written");
+        })
+      );
+      import_strict.default.equal(
+        await contracts.findByOriginalOfferId("offer-rolled-back"),
+        null,
+        "the contract outlived its transaction"
+      );
+      const kept = await adapter.transactionRunner.run(
+        (tx) => contracts.create(contractFromOffer("offer-kept"), tx)
+      );
+      const found = await contracts.findByOriginalOfferId("offer-kept");
+      import_strict.default.equal(found?.id, kept.id);
+      import_strict.default.equal(found?.lineItems.length, 1, "with its lines");
+      import_strict.default.equal(await contracts.findByOriginalOfferId("offer-nobody-concluded"), null);
+    });
+    (0, import_node_test.test)("an offer is consumed once, whoever asks first", async (t) => {
+      const offers = harness.adapter.checkoutOfferRepository;
+      if (!offers) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      import_strict.default.equal(offer.status, "open");
+      const attempts = await Promise.allSettled([
+        offers.consume(offer.id),
+        offers.consume(offer.id)
+      ]);
+      import_strict.default.equal(
+        attempts.filter((attempt) => attempt.status === "fulfilled").length,
+        1,
+        "exactly one consume wins"
+      );
+      const consumed = await offers.findById(offer.id);
+      import_strict.default.equal(consumed?.status, "consumed");
+      import_strict.default.ok(consumed?.consumedAt, "and it records when");
+      await import_strict.default.rejects(() => offers.consume(offer.id), "a later consume is refused");
+      import_strict.default.equal(
+        (await offers.findById(offer.id))?.consumedAt,
+        consumed.consumedAt,
+        "and changes nothing"
+      );
+    });
+    (0, import_node_test.test)("a consume on a transaction that rolls back leaves the offer open", async (t) => {
+      const { adapter } = harness;
+      const offers = adapter.checkoutOfferRepository;
+      if (!offers) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      await import_strict.default.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await offers.consume(offer.id, tx);
+          throw new Error("the contract after the consume fails");
+        })
+      );
+      const afterwards = await offers.findById(offer.id);
+      import_strict.default.equal(afterwards?.status, "open", "the consume outlived its transaction");
+      import_strict.default.equal(afterwards?.consumedAt, null);
+      import_strict.default.equal((await offers.consume(offer.id)).status, "consumed");
+    });
     const SETTINGS = {
       app: { name: "Demo" },
       currency: "EUR",

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -18,6 +18,13 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the checkout offer scenarios: an offer is consumed once, and a
+     * consume on a transaction that rolls back leaves it open. Neither shipped
+     * adapter provides one; an application that implements the port wires it
+     * here.
+     */
+    checkoutOfferRepository?: CheckoutOfferRepository;
     /**
      * Enables the atomic plan-binding scenarios. Adapters should expose this
      * member only for a mode that promises to keep `plan`,
@@ -132,7 +139,7 @@ interface PersistenceContractHarness {
  * Each names the members its scenarios need; `contract.ts` holds the list with
  * what each one checks.
  */
-type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'appliedSettings';
+type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, CheckoutOfferRepository, TenantSubscriptionWritePort, BundleRepository, SubscriptionBundleRepository, PlanRepository, PromoSubscriptionLookup, AppliedSettingsPort } from '@saasicat/core';
 
 /**
  * Port instances under test. Required members define the minimum an adapter
@@ -18,6 +18,13 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the checkout offer scenarios: an offer is consumed once, and a
+     * consume on a transaction that rolls back leaves it open. Neither shipped
+     * adapter provides one; an application that implements the port wires it
+     * here.
+     */
+    checkoutOfferRepository?: CheckoutOfferRepository;
     /**
      * Enables the atomic plan-binding scenarios. Adapters should expose this
      * member only for a mode that promises to keep `plan`,
@@ -132,7 +139,7 @@ interface PersistenceContractHarness {
  * Each names the members its scenarios need; `contract.ts` holds the list with
  * what each one checks.
  */
-type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'appliedSettings';
+type ContractGap = 'atomicPlanBinding' | 'atomicOnboarding' | 'promoCodes' | 'promoCodeRedemptions' | 'promoSubscriptionLookup' | 'planRepository' | 'planLifecycle' | 'planRetirement' | 'planVersionReads' | 'planVersionRetirement' | 'bundleRepository' | 'bundleValidity' | 'bundleDraftDiscard' | 'bundleDraftPublish' | 'bundleRetirement' | 'bundleBookings' | 'halfCancelledBookingSeed' | 'countByPlanVersionId' | 'audit' | 'mfa' | 'subscriptionContracts' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;

package/dist/index.js

@@ -2,6 +2,58 @@
 import assert from "node:assert/strict";
 import { after, before, beforeEach, describe, test } from "node:test";
 var LOCK_HOLD_MS = 150;
+var OFFER = {
+  planKey: "STANDARD",
+  planVersionId: null,
+  billingCycle: "monthly",
+  priceBreakdown: {
+    currency: "EUR",
+    billingCycle: "monthly",
+    planNet: 49,
+    bundlesNet: 0,
+    regularNet: 49,
+    effectiveNet: 49,
+    vatRate: 19,
+    effectiveGross: 58.31
+  }
+};
+function contractFromOffer(offerId) {
+  return {
+    tenantId: `tenant-${offerId}`,
+    effectiveFrom: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+    originalOfferId: offerId,
+    priceSnapshot: {
+      currency: "EUR",
+      billingCycle: "monthly",
+      subtotalNet: 49,
+      discountNet: 0,
+      totalNet: 49,
+      vatRate: 19,
+      totalGross: 58.31
+    },
+    lineItems: [
+      {
+        kind: "plan",
+        sourceKey: "STANDARD",
+        sourceVersionId: null,
+        titleSnapshot: "Standard",
+        descriptionSnapshot: null,
+        quantity: 1,
+        unit: null,
+        priceNet: 49,
+        priceGross: 58.31,
+        billingCycle: "monthly",
+        currency: "EUR",
+        taxRate: 19,
+        taxAmount: 9.31,
+        minimumTermUntil: null,
+        featuresSnapshot: [],
+        quotaEffectsSnapshot: {},
+        metadata: null
+      }
+    ]
+  };
+}
 var CONTRACT_GAPS = {
   atomicPlanBinding: {
     reason: "adapter does not expose atomic plan-binding writes",
@@ -102,6 +154,10 @@ var CONTRACT_GAPS = {
     reason: "adapter provides no SubscriptionContractRepository",
     present: ({ adapter }) => Boolean(adapter.subscriptionContractRepository)
   },
+  checkoutOffers: {
+    reason: "adapter provides no CheckoutOfferRepository",
+    present: ({ adapter }) => Boolean(adapter.checkoutOfferRepository)
+  },
   appliedSettings: {
     reason: "adapter provides no AppliedSettingsPort",
     present: ({ adapter }) => Boolean(adapter.appliedSettings)
@@ -1629,6 +1685,86 @@ function persistenceAdapterContract(options) {
         );
       }
     });
+    test("a contract written on a transaction is undone with it, and found by its offer", async (t) => {
+      const { adapter } = harness;
+      const contracts = adapter.subscriptionContractRepository;
+      if (!contracts) {
+        missing(t, "subscriptionContracts");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await contracts.create(contractFromOffer("offer-rolled-back"), tx);
+          throw new Error("the conclusion fails after the contract is written");
+        })
+      );
+      assert.equal(
+        await contracts.findByOriginalOfferId("offer-rolled-back"),
+        null,
+        "the contract outlived its transaction"
+      );
+      const kept = await adapter.transactionRunner.run(
+        (tx) => contracts.create(contractFromOffer("offer-kept"), tx)
+      );
+      const found = await contracts.findByOriginalOfferId("offer-kept");
+      assert.equal(found?.id, kept.id);
+      assert.equal(found?.lineItems.length, 1, "with its lines");
+      assert.equal(await contracts.findByOriginalOfferId("offer-nobody-concluded"), null);
+    });
+    test("an offer is consumed once, whoever asks first", async (t) => {
+      const offers = harness.adapter.checkoutOfferRepository;
+      if (!offers) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      assert.equal(offer.status, "open");
+      const attempts = await Promise.allSettled([
+        offers.consume(offer.id),
+        offers.consume(offer.id)
+      ]);
+      assert.equal(
+        attempts.filter((attempt) => attempt.status === "fulfilled").length,
+        1,
+        "exactly one consume wins"
+      );
+      const consumed = await offers.findById(offer.id);
+      assert.equal(consumed?.status, "consumed");
+      assert.ok(consumed?.consumedAt, "and it records when");
+      await assert.rejects(() => offers.consume(offer.id), "a later consume is refused");
+      assert.equal(
+        (await offers.findById(offer.id))?.consumedAt,
+        consumed.consumedAt,
+        "and changes nothing"
+      );
+    });
+    test("a consume on a transaction that rolls back leaves the offer open", async (t) => {
+      const { adapter } = harness;
+      const offers = adapter.checkoutOfferRepository;
+      if (!offers) {
+        missing(t, "checkoutOffers");
+        return;
+      }
+      if (!adapter.capabilities.transactions) {
+        t.skip("adapter declares no transaction capability");
+        return;
+      }
+      const offer = await offers.create(OFFER);
+      await assert.rejects(
+        adapter.transactionRunner.run(async (tx) => {
+          await offers.consume(offer.id, tx);
+          throw new Error("the contract after the consume fails");
+        })
+      );
+      const afterwards = await offers.findById(offer.id);
+      assert.equal(afterwards?.status, "open", "the consume outlived its transaction");
+      assert.equal(afterwards?.consumedAt, null);
+      assert.equal((await offers.consume(offer.id)).status, "consumed");
+    });
     const SETTINGS = {
       app: { name: "Demo" },
       currency: "EUR",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/persistence-testing",
-  "version": "1.0.0-rc.14",
+  "version": "1.0.0-rc.15",
   "description": "Contract test kit for SaaSiCat persistence adapters: one node:test suite that every adapter (Prisma, Drizzle, ...) must pass against a real database — locks, transaction rollback, atomic promo claims, tenant isolation, audit/MFA roundtrips.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,7 @@
     "dist"
   ],
   "dependencies": {
-    "@saasicat/core": "^1.0.0-rc.14"
+    "@saasicat/core": "^1.0.0-rc.15"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",