@saasicat/adapter-prisma 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PersistenceInjectionToken, PasswordHasher, SaasicatPersistenceAdapter, TransactionRunner, TransactionContext, MfaPort, AuditPort, AdminActor, AuditQueryPort, AuditQuery, AuditEntry, AuditStatsPort, RlsBypassPort, SubscriptionRepository, SubscriptionRecord, PlanVersionRepository, PlanVersionRecord, PromoCodeRepository, PromoCodeRecord, PromoCodeFilter, CreatePromoCodeData, UpdatePromoCodeData, PromoCodeRedemptionRepository, PromoCodeRedemptionRecord, PromoCodeRedemptionStatus, PromoCodeRedemptionListItem, PromoCodeValidationLogRepository, PromoSubscriptionLookup, BillingCycle, PromoRevenueDeductionAggregator, SuperAdminProvisioningPort, CreateSuperAdminCliInput, PlatformUserDto, PlanCatalogReadSink, PlanCatalogReadSnapshot, PlanCatalogImportSink, UpsertPlanInput, UpsertResult, UpsertPlanVersionInput, UpsertFeatureCatalogEntryInput } from '@saasicat/types';
+import { PersistenceInjectionToken, PasswordHasher, SaasicatPersistenceAdapter, TransactionRunner, TransactionContext, MfaPort, AuditPort, AdminActor, AuditQueryPort, AuditQuery, AuditEntry, AuditStatsPort, RlsBypassPort, SubscriptionRepository, SubscriptionRecord, SubscriptionBundleRepository, SubscriptionBundleRecord, CreateSubscriptionBundleData, CancelSubscriptionBundleData, TenantSubscriptionWritePort, ImmediatePlanChangeInput, ScheduledPlanChangeInput, PlanVersionRepository, PlanVersionRecord, PromoCodeRepository, PromoCodeRecord, PromoCodeFilter, CreatePromoCodeData, UpdatePromoCodeData, PromoCodeRedemptionRepository, PromoCodeRedemptionRecord, PromoCodeRedemptionStatus, PromoCodeRedemptionListItem, PromoCodeValidationLogRepository, PromoSubscriptionLookup, BillingCycle, PromoRevenueDeductionAggregator, SuperAdminProvisioningPort, CreateSuperAdminCliInput, PlatformUserDto, PlanCatalogReadSink, PlanCatalogReadSnapshot, PlanCatalogImportSink, UpsertPlanInput, UpsertResult, UpsertPlanVersionInput, UpsertFeatureCatalogEntryInput, PlanRepository, PlanListFilter, PlanRow, CreatePlanData, UpdatePlanData, PlanVersionRow, CreatePlanVersionDraftData, UpdatePlanVersionDraftData, VersionChange, BundleRepository, BundleListFilter, BundleRow, CreateBundleData, UpdateBundleData, BundleVersionRow, CreateBundleVersionDraftData, UpdateBundleVersionDraftData, CatalogEntryRepository, CatalogEntryFilter, CapabilityCatalogEntryRow, FeatureCatalogEntryRow, QuotaCatalogEntryRow, UpsertCapabilityEntryData, UpsertFeatureEntryData, UpsertQuotaEntryData, SetCatalogEntryReviewData, CatalogEntryI18n, UpdateCatalogEntryBaseData, MarketingProjectionRepository, MarketingProjectionFilter, MarketingProjectionRow, CreateMarketingProjectionData, UpdateMarketingProjectionData, MarketingSettingsRepository, MarketingSettingsRow, UpdateMarketingSettingsData, PromotionRepository, PromotionFilter, PromotionRow, CreatePromotionData, UpdatePromotionData, SubscriptionContractRepository, SubscriptionContractFilter, SubscriptionContractRecord, CreateSubscriptionContractData, TerminateSubscriptionContractData } from '@saasicat/types';
 
 declare const PRISMA_CLIENT_TOKEN: unique symbol;
 /** Prisma `Decimal` values arrive as objects with `toString()`; tests may use plain values. */
@@ -16,7 +16,7 @@ interface SubscriptionRowLike {
     pendingPlan: string | null;
     pendingEffectiveAt: Date | null;
     customLimits: unknown;
-    planVersionId: string | null;
+    planVersionId: string;
     pendingPlanVersionId: string | null;
     startedAt: Date | null;
 }
@@ -547,6 +547,36 @@ interface PrismaTxLike {
 interface PrismaLike extends PrismaTxLike {
     $transaction<T>(fn: (tx: PrismaTxLike) => Promise<T>): Promise<T>;
 }
+/**
+ * Generic structural minimum of a Prisma model delegate. The catalog-plane
+ * repositories (bundle, plan, catalog-entry, marketing,
+ * promotion, contract) declare their own DB-row interfaces and view the
+ * injected client through `{ model: PrismaModelDelegateLike<Row> }` casts —
+ * this keeps each repo self-contained and avoids hard-coding every delegate on
+ * `PrismaTxLike`. Args mirror Prisma's `where`/`data`/`select`/`orderBy` shapes
+ * and are typed `unknown`: the repos build them inline and Prisma validates
+ * them at runtime; only the results are typed, matching the package's
+ * structural-minimum philosophy.
+ */
+interface PrismaModelDelegateLike<Row> {
+    findMany(args?: unknown): Promise<Row[]>;
+    findUnique(args: unknown): Promise<Row | null>;
+    findFirst(args?: unknown): Promise<Row | null>;
+    create(args: unknown): Promise<Row>;
+    update(args: unknown): Promise<Row>;
+    delete(args: unknown): Promise<Row>;
+    upsert(args: unknown): Promise<Row>;
+    updateMany(args: unknown): Promise<{
+        count: number;
+    }>;
+    createMany(args: unknown): Promise<{
+        count: number;
+    }>;
+    deleteMany(args: unknown): Promise<{
+        count: number;
+    }>;
+    count(args?: unknown): Promise<number>;
+}
 
 interface PrismaPersistenceOptions {
     /**
@@ -581,9 +611,14 @@ interface PrismaPersistenceOptions {
  * });
  * ```
  *
- * Slices not shipped by this adapter (contracts, bundles, registration,
- * tenant-billing write ports) stay absent — consumers keep providing custom
- * adapters for those features.
+ * This bundle covers the core/entitlement/promo/plan-catalog slices consumed
+ * by `SaasPlatformModule`. The catalog plane (CatalogModule) and the V3
+ * contract loop take their repositories directly as `forRoot` options — wire
+ * the standalone `PrismaPlanRepository` / `PrismaBundleRepository` /
+ * `PrismaCatalogEntryRepository` /
+ * `PrismaMarketingProjectionRepository` / `PrismaMarketingSettingsRepository` /
+ * `PrismaPromotionRepository` / `PrismaSubscriptionContractRepository` exports
+ * there. The registration and tenant-billing write ports remain app-specific.
  */
 declare function prismaPersistence(options: PrismaPersistenceOptions): SaasicatPersistenceAdapter;
 
@@ -696,11 +731,6 @@ declare class AsyncLocalRlsBypassAdapter implements RlsBypassPort {
  * `SubscriptionRepository` against the canonical `subscriptions` +
  * `plan_versions` tables.
  *
- * Limitation: subscriptions that bind ONLY a `businessTypeVersionId` (no
- * `planVersionId`) are not supported by this shipped adapter — the
- * BusinessType composition needs app-specific aggregation. Such rows raise a
- * descriptive error instead of returning wrong entitlements.
- *
  * `countByBundleVersionId` is deliberately not implemented (the
  * `subscription_bundles` junction is not part of this adapter's slice);
  * the platform then treats affected bundle versions as frozen (fail-closed).
@@ -716,6 +746,58 @@ declare class PrismaSubscriptionRepository implements SubscriptionRepository {
     private toRecord;
 }
 
+/**
+ * `SubscriptionBundleRepository` against the canonical `subscription_bundles`
+ * junction (SPEC_V2 §11.1 M6 Pack 2e). Dumb persistence: domain constraints
+ * (plan compatibility, minimum-term default, cancellation-window computation)
+ * live in the platform's `SubscriptionBundlesService`; `add`/`cancel` here only
+ * write what they are handed. "Active" is `canceledAt IS NULL OR
+ * canceledEffectiveAt > asOf`, mirroring the port contract.
+ */
+declare class PrismaSubscriptionBundleRepository implements SubscriptionBundleRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private db;
+    listBySubscription(subscriptionId: string): Promise<SubscriptionBundleRecord[]>;
+    findById(subscriptionBundleId: string): Promise<SubscriptionBundleRecord | null>;
+    listActiveBySubscription(subscriptionId: string, asOf?: Date): Promise<SubscriptionBundleRecord[]>;
+    add(data: CreateSubscriptionBundleData): Promise<SubscriptionBundleRecord>;
+    cancel(subscriptionBundleId: string, data: CancelSubscriptionBundleData): Promise<SubscriptionBundleRecord>;
+    reactivate(subscriptionBundleId: string): Promise<SubscriptionBundleRecord>;
+    countActiveByBundleVersionId(bundleVersionId: string, asOf?: Date): Promise<number>;
+}
+
+/**
+ * `TenantSubscriptionWritePort` against the canonical `subscriptions` table.
+ * Pure persistence: trial carry-over (#17) and contract freeze (#18) are
+ * resolved in the platform `changePlan` path and handed down as plain values —
+ * this adapter only writes what it receives.
+ *
+ * The optional `applyOnboardingSelection` is not implemented; the platform
+ * service then falls back to sequential `changePlanImmediate` + promo redeem
+ * (best-effort, port contract P10.1.1).
+ */
+declare class PrismaTenantSubscriptionWriteAdapter implements TenantSubscriptionWritePort {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private db;
+    changePlanImmediate(tenantId: string, input: ImmediatePlanChangeInput): Promise<{
+        plan: string;
+        billingCycle: string;
+    }>;
+    schedulePlanChange(tenantId: string, input: ScheduledPlanChangeInput): Promise<void>;
+    acceptPendingPlanVersion(tenantId: string, userId: string, now: Date): Promise<{
+        accepted: boolean;
+        acceptedAt: Date | null;
+        effectiveAt: Date | null;
+        alreadyAccepted: boolean;
+    }>;
+    cancelSubscription(tenantId: string, immediate: boolean, now: Date): Promise<{
+        canceledAt: Date | null;
+        status: string;
+    }>;
+}
+
 /**
  * `PlanVersionRepository` against the canonical `plan_versions` table.
  *
@@ -856,4 +938,198 @@ declare class PrismaPlanCatalogImportSink implements PlanCatalogImportSink {
     upsertFeatureCatalogEntry(input: UpsertFeatureCatalogEntryInput): Promise<UpsertResult>;
 }
 
-export { AsyncLocalRlsBypassAdapter, type DecimalLike, PASSWORD_HASHER_TOKEN, PRISMA_CLIENT_TOKEN, PrismaAuditAdapter, PrismaAuditQueryAdapter, PrismaAuditStatsAdapter, type PrismaLike, PrismaMfaAdapter, type PrismaPersistenceOptions, PrismaPlanCatalogImportSink, PrismaPlanCatalogReadSink, PrismaPlanVersionRepository, PrismaPromoCodeRedemptionRepository, PrismaPromoCodeRepository, PrismaPromoCodeValidationLogRepository, PrismaPromoSubscriptionLookup, PrismaSubscriptionRepository, PrismaSuperAdminBootstrapAdapter, PrismaTransactionRunner, type PrismaTxLike, ZeroPromoRevenueDeductionAggregator, buildActorTag, prismaPersistence };
+/**
+ * `PlanRepository` against the canonical `plans` + `plan_versions` tables
+ * (SPEC_V2 §11.1 M6). Plan stem CRUD (Pack 1) and PlanVersion lifecycle
+ * (Pack 2a) live in one adapter; the soft binding is
+ * `PlanVersion.planId === Plan.planKey`, so the lifecycle methods take the
+ * **planKey**, not the plan UUID.
+ *
+ * Schema limitation: the canonical `plan_versions` fragment
+ * (03-plan-versions.prisma) intentionally has no validity-window columns
+ * (`validFrom`/`validUntil`) and no `endsAt` column — it carries a generic
+ * `quotas Json` instead of fixed quota columns. Consequences:
+ * - Every `PlanVersionRow.validFrom`/`validUntil` maps to `null`.
+ * - `publishPlanVersionDraft` persists only the publish/supersede state; the
+ *   `validFrom`/`validUntil` in `publishMeta` cannot be stored, so
+ *   auto-succession reduces to setting `supersededAt` on the previous live version.
+ * - `findActivePlanVersion` (validity-window read) and `terminate` (endsAt)
+ *   throw, because their contract depends on columns this schema does not have.
+ *   Consumers that need them provide a custom adapter on an extended schema.
+ */
+declare class PrismaPlanRepository implements PlanRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private db;
+    list(filter: PlanListFilter): Promise<PlanRow[]>;
+    findById(planId: string): Promise<PlanRow | null>;
+    findByKey(projectKey: string, planKey: string): Promise<PlanRow | null>;
+    create(data: CreatePlanData): Promise<PlanRow>;
+    update(planId: string, data: UpdatePlanData): Promise<PlanRow>;
+    softDelete(planId: string): Promise<void>;
+    hardDelete(planId: string): Promise<void>;
+    listVersions(planKey: string): Promise<PlanVersionRow[]>;
+    findVersionById(versionId: string): Promise<PlanVersionRow | null>;
+    findCurrentDraft(planKey: string): Promise<PlanVersionRow | null>;
+    findLatestLivePlanVersion(planKey: string, tx?: TransactionContext): Promise<PlanVersionRow | null>;
+    findActivePlanVersion(): Promise<PlanVersionRow | null>;
+    createPlanVersionDraft(data: CreatePlanVersionDraftData): Promise<PlanVersionRow>;
+    updatePlanVersionDraft(versionId: string, data: UpdatePlanVersionDraftData): Promise<PlanVersionRow>;
+    publishPlanVersionDraft(versionId: string, publishMeta: {
+        publishedByUserId: string | null;
+        publishedChanges: VersionChange[];
+        nonRegressive: boolean;
+        validFrom: Date;
+        validUntil: Date | null;
+    }, tx?: TransactionContext): Promise<PlanVersionRow>;
+    deletePlanVersionDraft(versionId: string): Promise<void>;
+    terminate(): Promise<PlanVersionRow>;
+}
+
+/**
+ * `BundleRepository` against the canonical `bundles` + `bundle_versions`
+ * tables (SPEC_V2 §5 + §11.1 M3). Versioning mirrors `PlanVersion`: at most one
+ * draft (`publishedAt IS NULL`) per bundle, monotonically incrementing
+ * `version`, `supersededAt` marking the previous live version on publish.
+ *
+ * Divergence from time-aware consumer schemas: the canonical `bundle_versions`
+ * table carries **no** `validFrom`/`validUntil` columns. The `BundleVersionRow`
+ * therefore always reports both as `null`, and the `validFrom`/`validUntil`
+ * inputs on the Create/Update DTOs and on `publishDraft`'s `publishMeta` are
+ * accepted (to satisfy the port signature) but not persisted — consistent with
+ * `PrismaPlanVersionRepository`, which documents the same schema gap.
+ *
+ * Atomicity of `publishDraft` (supersede-previous + publish-draft) is delegated
+ * to the caller's `TransactionContext`, following the package convention that
+ * repositories never open their own `$transaction`.
+ */
+declare class PrismaBundleRepository implements BundleRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private db;
+    list(filter: BundleListFilter): Promise<BundleRow[]>;
+    findById(bundleId: string): Promise<BundleRow | null>;
+    findByKey(projectKey: string, bundleKey: string): Promise<BundleRow | null>;
+    create(data: CreateBundleData): Promise<BundleRow>;
+    update(bundleId: string, data: UpdateBundleData): Promise<BundleRow>;
+    softDelete(bundleId: string): Promise<void>;
+    listVersions(bundleId: string): Promise<BundleVersionRow[]>;
+    findVersionById(versionId: string): Promise<BundleVersionRow | null>;
+    findCurrentDraft(bundleId: string): Promise<BundleVersionRow | null>;
+    findLatestLive(bundleId: string, tx?: TransactionContext): Promise<BundleVersionRow | null>;
+    createDraft(data: CreateBundleVersionDraftData): Promise<BundleVersionRow>;
+    updateDraft(versionId: string, data: UpdateBundleVersionDraftData): Promise<BundleVersionRow>;
+    publishDraft(versionId: string, publishMeta: {
+        publishedByUserId: string | null;
+        publishedChanges: VersionChange[];
+        nonRegressive: boolean;
+        validFrom: Date;
+        validUntil: Date | null;
+    }, tx?: TransactionContext): Promise<BundleVersionRow>;
+    deleteDraft(versionId: string): Promise<void>;
+}
+
+/**
+ * `CatalogEntryRepository` against the canonical `capability_catalog_entries`,
+ * `feature_catalog_entries` and `quota_catalog_entries` tables (SPEC_V2 §6.3 —
+ * discovery review workflow).
+ *
+ * `upsert*` writes only the code-derived fields + the service-resolved status
+ * and leaves `i18n`, `sortOrder`, `createdAt` and the approval fields untouched
+ * on update (Prisma's `update` payload simply omits them). `retireMissing`
+ * marks entries whose key vanished from the code snapshot.
+ */
+declare class PrismaCatalogEntryRepository implements CatalogEntryRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private get db();
+    listCapabilities(filter: CatalogEntryFilter): Promise<CapabilityCatalogEntryRow[]>;
+    listFeatures(filter: CatalogEntryFilter): Promise<FeatureCatalogEntryRow[]>;
+    listQuotas(filter: CatalogEntryFilter): Promise<QuotaCatalogEntryRow[]>;
+    upsertCapability(data: UpsertCapabilityEntryData): Promise<CapabilityCatalogEntryRow>;
+    upsertFeature(data: UpsertFeatureEntryData): Promise<FeatureCatalogEntryRow>;
+    upsertQuota(data: UpsertQuotaEntryData): Promise<QuotaCatalogEntryRow>;
+    retireMissing(projectKey: string, type: 'capability' | 'feature' | 'quota', presentKeys: string[]): Promise<number>;
+    setFeatureSuccessor(projectKey: string, featureKey: string, successorKey: string | null): Promise<FeatureCatalogEntryRow>;
+    setQuotaSuccessor(projectKey: string, quotaKey: string, successorKey: string | null): Promise<QuotaCatalogEntryRow>;
+    findFeature(projectKey: string, featureKey: string): Promise<FeatureCatalogEntryRow | null>;
+    findQuota(projectKey: string, quotaKey: string): Promise<QuotaCatalogEntryRow | null>;
+    setFeatureReview(projectKey: string, featureKey: string, data: SetCatalogEntryReviewData): Promise<FeatureCatalogEntryRow>;
+    setQuotaReview(projectKey: string, quotaKey: string, data: SetCatalogEntryReviewData): Promise<QuotaCatalogEntryRow>;
+    setFeatureI18n(projectKey: string, featureKey: string, i18n: CatalogEntryI18n): Promise<FeatureCatalogEntryRow>;
+    setQuotaI18n(projectKey: string, quotaKey: string, i18n: CatalogEntryI18n): Promise<QuotaCatalogEntryRow>;
+    setFeatureBase(projectKey: string, featureKey: string, data: UpdateCatalogEntryBaseData): Promise<FeatureCatalogEntryRow>;
+    setQuotaBase(projectKey: string, quotaKey: string, data: UpdateCatalogEntryBaseData): Promise<QuotaCatalogEntryRow>;
+}
+
+/**
+ * `MarketingProjectionRepository` against the canonical `marketing_projections`
+ * table. Not versioned: per (`targetType`, `targetVersionId`, `locale`) there is
+ * exactly one row (enforced by a unique index), edited directly. `create` on a
+ * duplicate triple therefore raises the DB unique-constraint error.
+ */
+declare class PrismaMarketingProjectionRepository implements MarketingProjectionRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private get db();
+    list(filter: MarketingProjectionFilter): Promise<MarketingProjectionRow[]>;
+    findById(id: string): Promise<MarketingProjectionRow | null>;
+    findByTarget(targetType: string, targetVersionId: string, locale: string): Promise<MarketingProjectionRow | null>;
+    create(data: CreateMarketingProjectionData): Promise<MarketingProjectionRow>;
+    update(id: string, data: UpdateMarketingProjectionData): Promise<MarketingProjectionRow>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * `MarketingSettingsRepository` against the canonical `marketing_settings`
+ * table (one row per project). A missing row means "full locale pool active",
+ * so `get` returns null and the platform falls back to the pool.
+ */
+declare class PrismaMarketingSettingsRepository implements MarketingSettingsRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private get db();
+    get(projectKey: string): Promise<MarketingSettingsRow | null>;
+    upsert(projectKey: string, data: UpdateMarketingSettingsData): Promise<MarketingSettingsRow>;
+}
+
+/**
+ * `PromotionRepository` against the canonical `promotions` table. Not
+ * versioned: promotions are edited directly.
+ *
+ * The nullable `onlyLocales` JSON column cannot be set to null through Prisma's
+ * query API without the `Prisma.DbNull` sentinel — which this Prisma-agnostic
+ * package deliberately does not import. On `create` a null restriction is
+ * therefore written by omission (the column defaults to SQL NULL); on `update`
+ * an explicit null clear runs as a raw statement.
+ */
+declare class PrismaPromotionRepository implements PromotionRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private get db();
+    list(filter: PromotionFilter): Promise<PromotionRow[]>;
+    findById(id: string): Promise<PromotionRow | null>;
+    create(data: CreatePromotionData): Promise<PromotionRow>;
+    update(id: string, data: UpdatePromotionData): Promise<PromotionRow>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Append-only `SubscriptionContractRepository` against the canonical
+ * `subscription_contracts` + `contract_line_items` tables. Contracts store full
+ * snapshots and are never rewritten: `create` writes the contract and its line
+ * items atomically via a single nested-create, and `terminate` only closes a
+ * contract (sets `effectiveUntil` + `status`). There is no line-item mutation.
+ */
+declare class PrismaSubscriptionContractRepository implements SubscriptionContractRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    private get db();
+    list(filter: SubscriptionContractFilter): Promise<SubscriptionContractRecord[]>;
+    findById(contractId: string): Promise<SubscriptionContractRecord | null>;
+    findActiveByTenantId(tenantId: string, asOf?: Date): Promise<SubscriptionContractRecord | null>;
+    create(data: CreateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+    terminate(contractId: string, data: TerminateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+}
+
+export { AsyncLocalRlsBypassAdapter, type DecimalLike, PASSWORD_HASHER_TOKEN, PRISMA_CLIENT_TOKEN, PrismaAuditAdapter, PrismaAuditQueryAdapter, PrismaAuditStatsAdapter, PrismaBundleRepository, PrismaCatalogEntryRepository, type PrismaLike, PrismaMarketingProjectionRepository, PrismaMarketingSettingsRepository, PrismaMfaAdapter, type PrismaModelDelegateLike, type PrismaPersistenceOptions, PrismaPlanCatalogImportSink, PrismaPlanCatalogReadSink, PrismaPlanRepository, PrismaPlanVersionRepository, PrismaPromoCodeRedemptionRepository, PrismaPromoCodeRepository, PrismaPromoCodeValidationLogRepository, PrismaPromoSubscriptionLookup, PrismaPromotionRepository, PrismaSubscriptionBundleRepository, PrismaSubscriptionContractRepository, PrismaSubscriptionRepository, PrismaSuperAdminBootstrapAdapter, PrismaTenantSubscriptionWriteAdapter, PrismaTransactionRunner, type PrismaTxLike, ZeroPromoRevenueDeductionAggregator, buildActorTag, prismaPersistence };