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

package/dist/index.d.cts

@@ -1,10 +1,11 @@
-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
  * must ship to call itself a SaaSiCat persistence adapter; optional members
- * activate additional scenario groups (absent → the group reports as
- * skipped, never silently).
+ * activate additional scenario groups. An absent member fails its scenarios
+ * unless the contract options declare it in `gaps`, in which case they report
+ * as skipped.
  */
 interface ContractAdapterInstances {
     capabilities: PersistenceCapabilities;
@@ -17,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`,
@@ -125,11 +133,25 @@ interface PersistenceContractHarness {
     /** Teardown after the last scenario (close pools etc.). */
     close?(): Promise<void>;
 }
+/**
+ * A part of the contract an adapter may deliberately not provide.
+ *
+ * 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' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
     /** Builds the harness once for the whole suite. */
     create(): Promise<PersistenceContractHarness>;
+    /**
+     * The parts this adapter deliberately does not provide. Their scenarios
+     * report as skipped; a part missing without being named here fails its
+     * scenarios, and a part named here that the harness does provide fails
+     * the suite.
+     */
+    gaps?: readonly ContractGap[];
 }
 
 /**
@@ -144,4 +166,4 @@ interface PersistenceAdapterContractOptions {
  */
 declare function persistenceAdapterContract(options: PersistenceAdapterContractOptions): void;
 
-export { type ContractAdapterInstances, type ContractSeed, type PersistenceAdapterContractOptions, type PersistenceContractHarness, persistenceAdapterContract };
+export { type ContractAdapterInstances, type ContractGap, type ContractSeed, type PersistenceAdapterContractOptions, type PersistenceContractHarness, persistenceAdapterContract };

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-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
  * must ship to call itself a SaaSiCat persistence adapter; optional members
- * activate additional scenario groups (absent → the group reports as
- * skipped, never silently).
+ * activate additional scenario groups. An absent member fails its scenarios
+ * unless the contract options declare it in `gaps`, in which case they report
+ * as skipped.
  */
 interface ContractAdapterInstances {
     capabilities: PersistenceCapabilities;
@@ -17,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`,
@@ -125,11 +133,25 @@ interface PersistenceContractHarness {
     /** Teardown after the last scenario (close pools etc.). */
     close?(): Promise<void>;
 }
+/**
+ * A part of the contract an adapter may deliberately not provide.
+ *
+ * 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' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
     /** Builds the harness once for the whole suite. */
     create(): Promise<PersistenceContractHarness>;
+    /**
+     * The parts this adapter deliberately does not provide. Their scenarios
+     * report as skipped; a part missing without being named here fails its
+     * scenarios, and a part named here that the harness does provide fails
+     * the suite.
+     */
+    gaps?: readonly ContractGap[];
 }
 
 /**
@@ -144,4 +166,4 @@ interface PersistenceAdapterContractOptions {
  */
 declare function persistenceAdapterContract(options: PersistenceAdapterContractOptions): void;
 
-export { type ContractAdapterInstances, type ContractSeed, type PersistenceAdapterContractOptions, type PersistenceContractHarness, persistenceAdapterContract };
+export { type ContractAdapterInstances, type ContractGap, type ContractSeed, type PersistenceAdapterContractOptions, type PersistenceContractHarness, persistenceAdapterContract };