@saasicat/persistence-testing 1.0.0-rc.2 → 1.0.0-rc.20

package/dist/index.d.cts

@@ -1,10 +1,11 @@
-import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, TenantSubscriptionWritePort, BundleRepository, PlanRepository, PromoSubscriptionLookup } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, PaymentEventLog, SubscriberPaymentMethodRepository, 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,34 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the subscriber scenarios: a customer number the database
+     * counts, one live subscriber per tenant however many callers create one
+     * at once, and a correction that records the values it replaced. A
+     * contract names its subscriber, so the contract scenarios write theirs
+     * through `seed.createSubscriber` rather than through this port.
+     */
+    subscriberRepository?: SubscriberRepository;
+    /**
+     * Enables the gateway event scenarios: an event is claimed once per
+     * account, a duplicate leaves the caller's transaction usable, and a claim
+     * rolled back with its transaction is free for the gateway's retry.
+     */
+    paymentEventLog?: PaymentEventLog;
+    /**
+     * Enables the payment method scenarios: one payment method in use per
+     * subscriber however many confirmations arrive at once, the one it
+     * replaced kept as history, and a confirmation recorded twice recognised.
+     * Its subscribers come from `seed.createSubscriber`.
+     */
+    subscriberPaymentMethodRepository?: SubscriberPaymentMethodRepository;
+    /**
+     * 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`,
@@ -25,6 +54,14 @@ interface ContractAdapterInstances {
     tenantSubscriptionWrite?: TenantSubscriptionWritePort;
     /** Enables BundleVersion validity-window and auto-succession scenarios. */
     bundleRepository?: BundleRepository;
+    /**
+     * Enables the booking scenarios — the junction a tenant's bundles hang off.
+     *
+     * Separate from `bundleRepository`, which is the catalog: one answers what
+     * may be sold, the other what a tenant actually bought and for which
+     * period. `adapter-drizzle` has neither yet.
+     */
+    subscriptionBundleRepository?: SubscriptionBundleRepository;
     /** Enables PlanVersion lifecycle, identity and validity-window scenarios. */
     planRepository?: PlanRepository;
     /**
@@ -37,6 +74,16 @@ interface ContractAdapterInstances {
      * tenant, which is what makes selecting the wrong row possible at all.
      */
     promoSubscriptionLookup?: PromoSubscriptionLookup;
+    /**
+     * Enables the applied-settings scenarios: the one row an installation keeps
+     * about the configuration it runs on, and the changes noticed between
+     * starts. The singleton and the guard are the parts worth a contract — two
+     * adapters that upsert differently would leave one of them with two rows
+     * and a reader picking one at random, and one whose write ignores the
+     * fingerprint it was given lets every replica of a deployment record the
+     * same change.
+     */
+    appliedSettings?: AppliedSettingsPort;
 }
 /** Fixture writers — implemented per adapter against its own schema. */
 interface ContractSeed {
@@ -63,6 +110,34 @@ interface ContractSeed {
     }): Promise<{
         subscriptionId: string;
     }>;
+    /**
+     * A published BundleVersion to book against.
+     *
+     * A fixture writer rather than a call into `bundleRepository`: the catalog
+     * repository is a subject of the suite, not a tool for setting up someone
+     * else's scenario, and a booking scenario that failed because the catalog
+     * did would say the wrong thing.
+     *
+     * Optional because an adapter may not carry the catalog tables at all —
+     * `adapter-drizzle` does not. A required writer nobody can implement is a
+     * contract that lies about what conformance means; the booking scenarios
+     * gate on this and report the gap as a skip instead.
+     */
+    createBundleVersion?(input: {
+        bundleKey: string;
+        features: string[];
+    }): Promise<{
+        bundleVersionId: string;
+    }>;
+    /**
+     * Clears a booking's `canceledAt` while leaving `canceledEffectiveAt`.
+     *
+     * A shape no repository method produces, and one the nullable columns
+     * nonetheless permit — so the adapters have to agree on how to read it.
+     * Optional: a harness that cannot reach its store directly says so and the
+     * scenario skips, rather than the scenario inventing a way in.
+     */
+    clearBookingRequestDate?(subscriptionBundleId: string): Promise<void>;
     createPromoCode(input: {
         code: string;
         maxRedemptions: number | null;
@@ -70,6 +145,19 @@ interface ContractSeed {
     }): Promise<{
         promoCodeId: string;
     }>;
+    /**
+     * A subscriber row for a contract scenario to name, linked to no tenant.
+     *
+     * A fixture writer for the reason `createBundleVersion` is one: the
+     * subscriber repository is a subject of its own scenarios, and a contract
+     * scenario that failed because of it would say the wrong thing. Optional
+     * like the port it stands beside; the contract scenarios report it missing.
+     */
+    createSubscriber?(input: {
+        legalName: string;
+    }): Promise<{
+        subscriberId: string;
+    }>;
 }
 interface PersistenceContractHarness {
     adapter: ContractAdapterInstances;
@@ -79,13 +167,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' | 'subscribers' | 'paymentEventLog' | 'subscriberPaymentMethods' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
-    /** Project identity used by catalog lifecycle scenarios. */
-    projectKey: 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[];
 }
 
 /**
@@ -94,11 +194,10 @@ interface PersistenceAdapterContractOptions {
  * ```ts
  * persistenceAdapterContract({
  *     name: 'adapter-prisma @ postgres',
- *     projectKey: 'my-app',
  *     create: () => createPrismaHarness(),
  * });
  * ```
  */
 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, PlanRepository, PromoSubscriptionLookup } from '@saasicat/core';
+import { PersistenceCapabilities, TransactionRunner, SubscriptionRepository, PlanVersionRepository, PromoCodeRepository, PromoCodeRedemptionRepository, MfaPort, AuditPort, AuditQueryPort, SubscriptionContractRepository, SubscriberRepository, PaymentEventLog, SubscriberPaymentMethodRepository, 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,34 @@ interface ContractAdapterInstances {
     audit?: AuditPort;
     auditQuery?: AuditQueryPort;
     subscriptionContractRepository?: SubscriptionContractRepository;
+    /**
+     * Enables the subscriber scenarios: a customer number the database
+     * counts, one live subscriber per tenant however many callers create one
+     * at once, and a correction that records the values it replaced. A
+     * contract names its subscriber, so the contract scenarios write theirs
+     * through `seed.createSubscriber` rather than through this port.
+     */
+    subscriberRepository?: SubscriberRepository;
+    /**
+     * Enables the gateway event scenarios: an event is claimed once per
+     * account, a duplicate leaves the caller's transaction usable, and a claim
+     * rolled back with its transaction is free for the gateway's retry.
+     */
+    paymentEventLog?: PaymentEventLog;
+    /**
+     * Enables the payment method scenarios: one payment method in use per
+     * subscriber however many confirmations arrive at once, the one it
+     * replaced kept as history, and a confirmation recorded twice recognised.
+     * Its subscribers come from `seed.createSubscriber`.
+     */
+    subscriberPaymentMethodRepository?: SubscriberPaymentMethodRepository;
+    /**
+     * 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`,
@@ -25,6 +54,14 @@ interface ContractAdapterInstances {
     tenantSubscriptionWrite?: TenantSubscriptionWritePort;
     /** Enables BundleVersion validity-window and auto-succession scenarios. */
     bundleRepository?: BundleRepository;
+    /**
+     * Enables the booking scenarios — the junction a tenant's bundles hang off.
+     *
+     * Separate from `bundleRepository`, which is the catalog: one answers what
+     * may be sold, the other what a tenant actually bought and for which
+     * period. `adapter-drizzle` has neither yet.
+     */
+    subscriptionBundleRepository?: SubscriptionBundleRepository;
     /** Enables PlanVersion lifecycle, identity and validity-window scenarios. */
     planRepository?: PlanRepository;
     /**
@@ -37,6 +74,16 @@ interface ContractAdapterInstances {
      * tenant, which is what makes selecting the wrong row possible at all.
      */
     promoSubscriptionLookup?: PromoSubscriptionLookup;
+    /**
+     * Enables the applied-settings scenarios: the one row an installation keeps
+     * about the configuration it runs on, and the changes noticed between
+     * starts. The singleton and the guard are the parts worth a contract — two
+     * adapters that upsert differently would leave one of them with two rows
+     * and a reader picking one at random, and one whose write ignores the
+     * fingerprint it was given lets every replica of a deployment record the
+     * same change.
+     */
+    appliedSettings?: AppliedSettingsPort;
 }
 /** Fixture writers — implemented per adapter against its own schema. */
 interface ContractSeed {
@@ -63,6 +110,34 @@ interface ContractSeed {
     }): Promise<{
         subscriptionId: string;
     }>;
+    /**
+     * A published BundleVersion to book against.
+     *
+     * A fixture writer rather than a call into `bundleRepository`: the catalog
+     * repository is a subject of the suite, not a tool for setting up someone
+     * else's scenario, and a booking scenario that failed because the catalog
+     * did would say the wrong thing.
+     *
+     * Optional because an adapter may not carry the catalog tables at all —
+     * `adapter-drizzle` does not. A required writer nobody can implement is a
+     * contract that lies about what conformance means; the booking scenarios
+     * gate on this and report the gap as a skip instead.
+     */
+    createBundleVersion?(input: {
+        bundleKey: string;
+        features: string[];
+    }): Promise<{
+        bundleVersionId: string;
+    }>;
+    /**
+     * Clears a booking's `canceledAt` while leaving `canceledEffectiveAt`.
+     *
+     * A shape no repository method produces, and one the nullable columns
+     * nonetheless permit — so the adapters have to agree on how to read it.
+     * Optional: a harness that cannot reach its store directly says so and the
+     * scenario skips, rather than the scenario inventing a way in.
+     */
+    clearBookingRequestDate?(subscriptionBundleId: string): Promise<void>;
     createPromoCode(input: {
         code: string;
         maxRedemptions: number | null;
@@ -70,6 +145,19 @@ interface ContractSeed {
     }): Promise<{
         promoCodeId: string;
     }>;
+    /**
+     * A subscriber row for a contract scenario to name, linked to no tenant.
+     *
+     * A fixture writer for the reason `createBundleVersion` is one: the
+     * subscriber repository is a subject of its own scenarios, and a contract
+     * scenario that failed because of it would say the wrong thing. Optional
+     * like the port it stands beside; the contract scenarios report it missing.
+     */
+    createSubscriber?(input: {
+        legalName: string;
+    }): Promise<{
+        subscriberId: string;
+    }>;
 }
 interface PersistenceContractHarness {
     adapter: ContractAdapterInstances;
@@ -79,13 +167,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' | 'subscribers' | 'paymentEventLog' | 'subscriberPaymentMethods' | 'checkoutOffers' | 'appliedSettings';
 interface PersistenceAdapterContractOptions {
     /** Display name in the test output, e.g. `'adapter-prisma @ postgres16'`. */
     name: string;
-    /** Project identity used by catalog lifecycle scenarios. */
-    projectKey: 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[];
 }
 
 /**
@@ -94,11 +194,10 @@ interface PersistenceAdapterContractOptions {
  * ```ts
  * persistenceAdapterContract({
  *     name: 'adapter-prisma @ postgres',
- *     projectKey: 'my-app',
  *     create: () => createPrismaHarness(),
  * });
  * ```
  */
 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 };