@saasicat/adapter-prisma 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,859 @@
+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';
+
+declare const PRISMA_CLIENT_TOKEN: unique symbol;
+/** Prisma `Decimal` values arrive as objects with `toString()`; tests may use plain values. */
+type DecimalLike = {
+    toString(): string;
+} | string | number;
+interface SubscriptionRowLike {
+    id: string;
+    tenantId: string;
+    plan: string;
+    billingCycle: string;
+    status: string;
+    isPilot: boolean;
+    trialEntitlementPlan: string | null;
+    pendingPlan: string | null;
+    pendingEffectiveAt: Date | null;
+    customLimits: unknown;
+    planVersionId: string | null;
+    pendingPlanVersionId: string | null;
+    startedAt: Date | null;
+}
+interface PlanVersionRowLike {
+    id: string;
+    planId: string;
+    version: number;
+    baseVersionId: string | null;
+    features: unknown;
+    quotas: unknown;
+    monthlyNet: DecimalLike;
+    yearlyNet: DecimalLike;
+    marketed: boolean;
+    publishedAt: Date | null;
+    supersededAt: Date | null;
+    publishedChanges: unknown;
+    changeNote: string;
+    nonRegressive: boolean;
+    createdByUserId: string | null;
+    publishedByUserId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface PlanRowLike {
+    id: string;
+    projectKey: string;
+    planKey: string;
+    label: string;
+    description: string | null;
+    icon: string | null;
+    sortOrder: number;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+interface FeatureCatalogEntryRowLike {
+    id: string;
+    projectKey: string;
+    featureKey: string;
+    label: string;
+    description: string | null;
+    marketingLabel: string | null;
+    marketingDescription: string | null;
+    icon: string | null;
+    tier: string | null;
+    discoveryStatus: string;
+    requires: string[];
+    replaces: string[];
+    successorKey: string | null;
+    approvedAt: Date | null;
+    approvedBy: string | null;
+    approvedSignature: string | null;
+    plannedOnly: boolean;
+    core: boolean;
+    i18n: unknown;
+    sortOrder: number;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+interface PromoCodeRowLike {
+    id: string;
+    code: string;
+    valueType: string;
+    value: DecimalLike;
+    durationType: string;
+    durationValue: number | null;
+    validFrom: Date | null;
+    validUntil: Date | null;
+    maxRedemptions: number | null;
+    redemptionsCount: number;
+    appliesToPlans: string[];
+    appliesToBilling: string | null;
+    firstTimeCustomersOnly: boolean;
+    minimumPlanAmountGross: DecimalLike | null;
+    allowZeroInvoice: boolean;
+    status: string;
+    description: string | null;
+    campaignTag: string | null;
+    revenueDeductionAccount: string | null;
+    createdById: string;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+interface PromoCodeRedemptionRowLike {
+    id: string;
+    promoCodeId: string;
+    subscriptionId: string;
+    tenantId: string;
+    appliedValueType: string;
+    appliedValue: DecimalLike;
+    appliedDurationType: string;
+    appliedDurationValue: number | null;
+    startsAt: Date;
+    endsAt: Date | null;
+    status: string;
+    redeemedAt: Date;
+    reversedAt: Date | null;
+}
+interface AuditLogRowLike {
+    id: string;
+    tenantId: string | null;
+    userId: string | null;
+    entity: string;
+    entityId: string;
+    action: string;
+    changes: unknown;
+    actorTag: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    createdAt: Date;
+}
+interface SuperAdminUserRowLike {
+    id: string;
+    email: string;
+    passwordHash: string;
+    firstName: string | null;
+    lastName: string | null;
+    platformRole: string;
+    isActive: boolean;
+    lastLoginAt: Date | null;
+    deletedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type SortDirection = 'asc' | 'desc';
+interface SubscriptionDelegateLike {
+    findUnique(args: {
+        where: {
+            id?: string;
+            tenantId?: string;
+        };
+    }): Promise<SubscriptionRowLike | null>;
+    findMany(args?: {
+        where?: {
+            status?: {
+                in: string[];
+            };
+        };
+    }): Promise<SubscriptionRowLike[]>;
+    count(args?: {
+        where?: {
+            OR?: Array<{
+                planVersionId?: string;
+                pendingPlanVersionId?: string;
+            }>;
+        };
+    }): Promise<number>;
+}
+interface PlanVersionDelegateLike {
+    findUnique(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<PlanVersionRowLike | null>;
+    findFirst(args: {
+        where: {
+            planId?: string;
+            version?: number;
+            publishedAt?: {
+                not: null;
+            } | null;
+            supersededAt?: null;
+        };
+        orderBy?: {
+            version?: SortDirection;
+        };
+    }): Promise<PlanVersionRowLike | null>;
+    findMany(args?: {
+        where?: {
+            planId?: {
+                in: string[];
+            };
+            publishedAt?: {
+                not: null;
+            } | null;
+            supersededAt?: null;
+        };
+    }): Promise<PlanVersionRowLike[]>;
+    create(args: {
+        data: {
+            planId: string;
+            version: number;
+            features: unknown;
+            quotas: unknown;
+            monthlyNet: string;
+            yearlyNet: string;
+            marketed: boolean;
+            publishedAt: Date | null;
+            changeNote: string;
+        };
+    }): Promise<PlanVersionRowLike>;
+    updateMany(args: {
+        where: {
+            planId?: string;
+            publishedAt?: {
+                not: null;
+            } | null;
+            supersededAt?: null;
+            version?: {
+                lt: number;
+            };
+        };
+        data: {
+            supersededAt?: Date;
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+interface PlanDelegateLike {
+    findFirst(args: {
+        where: {
+            projectKey?: string;
+            planKey?: string;
+            deletedAt?: null;
+        };
+    }): Promise<PlanRowLike | null>;
+    findMany(args?: {
+        where?: {
+            projectKey?: string;
+            deletedAt?: null;
+        };
+        orderBy?: {
+            sortOrder?: SortDirection;
+        };
+    }): Promise<PlanRowLike[]>;
+    create(args: {
+        data: {
+            projectKey: string;
+            planKey: string;
+            label: string;
+            description?: string | null;
+            sortOrder?: number;
+        };
+    }): Promise<PlanRowLike>;
+}
+interface FeatureCatalogEntryDelegateLike {
+    findFirst(args: {
+        where: {
+            projectKey?: string;
+            featureKey?: string;
+            deletedAt?: null;
+        };
+    }): Promise<FeatureCatalogEntryRowLike | null>;
+    findMany(args?: {
+        where?: {
+            projectKey?: string;
+            deletedAt?: null;
+        };
+        orderBy?: {
+            sortOrder?: SortDirection;
+        };
+    }): Promise<FeatureCatalogEntryRowLike[]>;
+    create(args: {
+        data: {
+            projectKey: string;
+            featureKey: string;
+            label: string;
+            icon?: string | null;
+            tier?: string | null;
+            plannedOnly?: boolean;
+            core?: boolean;
+        };
+    }): Promise<FeatureCatalogEntryRowLike>;
+}
+interface PromoCodeDelegateLike {
+    findUnique(args: {
+        where: {
+            id?: string;
+            code?: string;
+        };
+    }): Promise<PromoCodeRowLike | null>;
+    findMany(args?: {
+        where?: {
+            deletedAt?: null;
+            status?: string;
+            campaignTag?: string;
+            code?: {
+                contains: string;
+            };
+        };
+        orderBy?: {
+            createdAt?: SortDirection;
+        };
+    }): Promise<PromoCodeRowLike[]>;
+    create(args: {
+        data: {
+            code: string;
+            valueType: string;
+            value: string;
+            durationType: string;
+            durationValue: number | null;
+            validFrom: Date | null;
+            validUntil: Date | null;
+            maxRedemptions: number | null;
+            appliesToPlans: string[];
+            appliesToBilling: string | null;
+            firstTimeCustomersOnly: boolean;
+            minimumPlanAmountGross: string | null;
+            allowZeroInvoice: boolean;
+            description: string | null;
+            campaignTag: string | null;
+            revenueDeductionAccount: string | null;
+            createdById: string;
+        };
+    }): Promise<PromoCodeRowLike>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: {
+            status?: string;
+            description?: string | null;
+            validUntil?: Date | null;
+            maxRedemptions?: number | null;
+            deletedAt?: Date;
+        };
+    }): Promise<PromoCodeRowLike>;
+    updateMany(args: {
+        where: {
+            status?: {
+                in: string[];
+            };
+            validUntil?: {
+                lt: Date;
+            };
+        };
+        data: {
+            status?: string;
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+interface PromoCodeRedemptionDelegateLike {
+    findUnique(args: {
+        where: {
+            id?: string;
+            subscriptionId?: string;
+        };
+    }): Promise<PromoCodeRedemptionRowLike | null>;
+    findMany(args?: {
+        where?: {
+            promoCodeId?: string;
+        };
+        orderBy?: {
+            redeemedAt?: SortDirection;
+        };
+    }): Promise<PromoCodeRedemptionRowLike[]>;
+    create(args: {
+        data: {
+            promoCodeId: string;
+            subscriptionId: string;
+            tenantId: string;
+            appliedValueType: string;
+            appliedValue: string;
+            appliedDurationType: string;
+            appliedDurationValue: number | null;
+            startsAt: Date;
+            endsAt: Date | null;
+        };
+    }): Promise<PromoCodeRedemptionRowLike>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: {
+            status?: string;
+            reversedAt?: Date | null;
+        };
+    }): Promise<PromoCodeRedemptionRowLike>;
+    count(args?: {
+        where?: {
+            promoCodeId?: string;
+            status?: string;
+        };
+    }): Promise<number>;
+    updateMany(args: {
+        where: {
+            status?: string;
+            endsAt?: {
+                lt: Date;
+            };
+        };
+        data: {
+            status?: string;
+        };
+    }): Promise<{
+        count: number;
+    }>;
+}
+interface PromoCodeValidationLogDelegateLike {
+    create(args: {
+        data: {
+            promoCodeId: string | null;
+            codeAttempt: string;
+            result: string;
+            ipHash?: string | null;
+            sessionId?: string | null;
+        };
+    }): Promise<unknown>;
+    count(args?: {
+        where?: {
+            promoCodeId?: string;
+            result?: string;
+        };
+    }): Promise<number>;
+}
+interface AuditLogDelegateLike {
+    create(args: {
+        data: {
+            tenantId: string | null;
+            userId: string | null;
+            entity: string;
+            entityId: string;
+            action: string;
+            changes: unknown;
+            actorTag: string | null;
+        };
+    }): Promise<unknown>;
+    findMany(args?: {
+        where?: {
+            tenantId?: string;
+            userId?: string;
+            entity?: string;
+            entityId?: string;
+            action?: string;
+            actorTag?: string | {
+                startsWith: string;
+            };
+            createdAt?: {
+                gte?: Date;
+                lte?: Date;
+            };
+        };
+        orderBy?: {
+            createdAt?: SortDirection;
+        };
+        skip?: number;
+        take?: number;
+    }): Promise<AuditLogRowLike[]>;
+    count(args?: {
+        where?: {
+            createdAt?: {
+                gte?: Date;
+            };
+        };
+    }): Promise<number>;
+}
+interface SuperAdminUserDelegateLike {
+    findUnique(args: {
+        where: {
+            email: string;
+        };
+    }): Promise<SuperAdminUserRowLike | null>;
+    count(args?: {
+        where?: {
+            isActive?: boolean;
+            deletedAt?: null;
+        };
+    }): Promise<number>;
+    create(args: {
+        data: {
+            email: string;
+            passwordHash: string;
+            firstName?: string | null;
+            lastName?: string | null;
+        };
+    }): Promise<SuperAdminUserRowLike>;
+}
+interface SuperAdminMfaDelegateLike {
+    findUnique(args: {
+        where: {
+            userId: string;
+        };
+    }): Promise<{
+        userId: string;
+        secret: string | null;
+        enabledAt: Date | null;
+        updatedAt: Date;
+    } | null>;
+    upsert(args: {
+        where: {
+            userId: string;
+        };
+        create: {
+            userId: string;
+            secret: string | null;
+            enabledAt: Date | null;
+        };
+        update: {
+            secret: string | null;
+            enabledAt: Date | null;
+        };
+    }): Promise<unknown>;
+}
+/**
+ * Structural sub-interface of a Prisma transaction client
+ * (`Prisma.TransactionClient`): the table delegates plus raw access, without
+ * `$transaction`. Repository methods that accept an opaque
+ * `TransactionContext` cast it to this shape.
+ */
+interface PrismaTxLike {
+    subscription: SubscriptionDelegateLike;
+    planVersion: PlanVersionDelegateLike;
+    plan: PlanDelegateLike;
+    featureCatalogEntry: FeatureCatalogEntryDelegateLike;
+    promoCode: PromoCodeDelegateLike;
+    promoCodeRedemption: PromoCodeRedemptionDelegateLike;
+    promoCodeValidationLog: PromoCodeValidationLogDelegateLike;
+    auditLog: AuditLogDelegateLike;
+    superAdminUser: SuperAdminUserDelegateLike;
+    superAdminMfa: SuperAdminMfaDelegateLike;
+    $queryRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<unknown>;
+    $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+}
+/**
+ * Structural sub-interface of `@prisma/client.PrismaClient`. The adapters
+ * expect only the delegates they actually use — no hard import on
+ * `@prisma/client`, so the package builds without a Prisma generate and can be
+ * mocked in tests.
+ *
+ * A consumer's `PrismaService extends PrismaClient` (generated from the
+ * canonical prisma-fragments schema) satisfies the interface automatically.
+ */
+interface PrismaLike extends PrismaTxLike {
+    $transaction<T>(fn: (tx: PrismaTxLike) => Promise<T>): Promise<T>;
+}
+
+interface PrismaPersistenceOptions {
+    /**
+     * The app's Prisma client: either its injection token (typically the
+     * `PrismaService` class) — resolved through Nest DI at boot — or a ready
+     * `PrismaLike` instance (tests, non-DI scripts).
+     */
+    client: PrismaLike | PersistenceInjectionToken;
+    /**
+     * App `PasswordHasher` (token or instance). Enables
+     * `core.superAdminProvisioning` (setup wizard / create-super-admin);
+     * without it the slice member stays absent.
+     */
+    passwordHasher?: PasswordHasher | PersistenceInjectionToken;
+    /**
+     * Set to true when the app's Prisma middleware really lifts RLS
+     * (`SET LOCAL row_security = off`) while
+     * `AsyncLocalRlsBypassAdapter.isBypassActive()`. Only toggles the
+     * declared `rowLevelSecurity` capability — the adapter cannot verify the
+     * middleware. Default false.
+     */
+    rlsIntegration?: boolean;
+}
+/**
+ * Builds the `SaasicatPersistenceAdapter` bundle for Prisma + PostgreSQL on
+ * the canonical schema (`@saasicat/spec` prisma-fragments):
+ *
+ * ```ts
+ * SaasPlatformModule.forRoot({
+ *     persistence: prismaPersistence({ client: PrismaService }),
+ *     // ...
+ * });
+ * ```
+ *
+ * Slices not shipped by this adapter (contracts, bundles, registration,
+ * tenant-billing write ports) stay absent — consumers keep providing custom
+ * adapters for those features.
+ */
+declare function prismaPersistence(options: PrismaPersistenceOptions): SaasicatPersistenceAdapter;
+
+/**
+ * `TransactionRunner` over `prisma.$transaction`. The interactive transaction
+ * client is passed through as the opaque `TransactionContext`; every
+ * repository in this package resolves it back via `resolveClient`.
+ */
+declare class PrismaTransactionRunner implements TransactionRunner {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    run<T>(fn: (tx: TransactionContext) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Default implementation of `MfaPort` against the `SuperAdminMfa` table
+ * from the platform Prisma fragment.
+ *
+ * Schema assumption:
+ *
+ * ```prisma
+ * model SuperAdminMfa {
+ *     userId    String   @id
+ *     secret    String?
+ *     enabledAt DateTime?
+ *     updatedAt DateTime @updatedAt
+ * }
+ * ```
+ */
+declare class PrismaMfaAdapter implements MfaPort {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    getSecret(userId: string): Promise<string | null>;
+    setSecret(userId: string, secret: string | null): Promise<void>;
+    isEnabled(userId: string): Promise<boolean>;
+}
+
+/** `'web:<email>:<sessionId>'` / `'cli:<email>:<host>'` — audit-event.schema.json ActorTagPattern. */
+declare function buildActorTag(actor: AdminActor): string;
+/**
+ * Default implementation of `AuditPort` against the canonical `audit_logs`
+ * table (`@saasicat/spec` prisma-fragments/04-audit-log.prisma).
+ *
+ * SuperAdmin actions are platform-global, so `tenantId` stays null; the
+ * actor lands as `userId` + `actorTag`.
+ */
+declare class PrismaAuditAdapter implements AuditPort {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    write(input: {
+        actor: AdminActor;
+        entity: string;
+        entityId: string;
+        action: string;
+        changes?: Record<string, unknown>;
+    }): Promise<void>;
+}
+
+/**
+ * `AuditQueryPort` against the canonical `audit_logs` table. Powers
+ * `<app> audit tail` and the admin audit pages.
+ */
+declare class PrismaAuditQueryAdapter implements AuditQueryPort {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    list(filter: AuditQuery): Promise<AuditEntry[]>;
+}
+
+/** `AuditStatsPort` against the canonical `audit_logs` table. */
+declare class PrismaAuditStatsAdapter implements AuditStatsPort {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    countSince(since: Date): Promise<number>;
+}
+
+/**
+ * Default implementation of `RlsBypassPort` via `node:async_hooks`.
+ *
+ * Sets `bypass: true` for the duration of the given callback in the current
+ * async context. Your PrismaService reads `isBypassActive()` (e.g. in a
+ * Prisma middleware or an interceptor) and issues `SET LOCAL row_security
+ * = off` in the current transaction when active.
+ *
+ * Example middleware:
+ *
+ * ```ts
+ * constructor(private readonly rls: AsyncLocalRlsBypassAdapter) {
+ *     super();
+ *     this.$use(async (params, next) => {
+ *         if (this.rls.isBypassActive() && params.action.startsWith('find')) {
+ *             // Bypass mode active — disable RLS for this query.
+ *             await this.$executeRawUnsafe('SET LOCAL row_security = off');
+ *         }
+ *         return next(params);
+ *     });
+ * }
+ * ```
+ */
+declare class AsyncLocalRlsBypassAdapter implements RlsBypassPort {
+    private readonly storage;
+    runWithBypass<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * `true` during the execution of a `runWithBypass(...)` callback.
+     * Query this in the PrismaService or an interceptor.
+     */
+    isBypassActive(): boolean;
+}
+
+/**
+ * `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).
+ */
+declare class PrismaSubscriptionRepository implements SubscriptionRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    findByTenantId(tenantId: string): Promise<SubscriptionRecord | null>;
+    findByTenantIdLocked(tenantId: string, tx: TransactionContext): Promise<SubscriptionRecord | null>;
+    countByPlanVersionId(planVersionId: string): Promise<number>;
+    countActiveByPlanKey(_projectKey: string): Promise<Record<string, number>>;
+    private loadByTenantId;
+    private toRecord;
+}
+
+/**
+ * `PlanVersionRepository` against the canonical `plan_versions` table.
+ *
+ * `findActive` is deliberately not implemented: the canonical schema carries
+ * no `validFrom`/`validUntil` columns yet, so time-aware resolution is not
+ * expressible — consumers fall back to `findLatestLive` (documented port
+ * behavior).
+ */
+declare class PrismaPlanVersionRepository implements PlanVersionRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    findLatestLive(planId: string, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
+}
+
+/**
+ * `PromoCodeRepository` against the canonical `promo_codes` table.
+ *
+ * The availability-critical mutations (`claimSlot`, `releaseSlot`,
+ * `markExhaustedIfFull`) run as single atomic UPDATE statements — the
+ * column-to-column guard (`redemptionsCount < maxRedemptions`) is not
+ * expressible in the Prisma query API, so they use `$executeRaw`. The raw
+ * statements maintain `updatedAt` manually because they bypass Prisma's
+ * `@updatedAt`.
+ */
+declare class PrismaPromoCodeRepository implements PromoCodeRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    findById(id: string): Promise<PromoCodeRecord | null>;
+    findByCode(code: string, tx?: TransactionContext): Promise<PromoCodeRecord | null>;
+    findMany(filter: PromoCodeFilter): Promise<PromoCodeRecord[]>;
+    create(data: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    update(id: string, data: UpdatePromoCodeData): Promise<PromoCodeRecord>;
+    softDelete(id: string): Promise<void>;
+    claimSlot(id: string, tx?: TransactionContext): Promise<boolean>;
+    markExhaustedIfFull(id: string, tx?: TransactionContext): Promise<void>;
+    releaseSlot(id: string, tx?: TransactionContext): Promise<void>;
+    expireDueCodes(now: Date): Promise<number>;
+}
+
+/**
+ * `PromoCodeRedemptionRepository` against the canonical
+ * `promo_code_redemptions` table. Double redemption per subscription is
+ * excluded by the `subscriptionId` unique constraint — a concurrent second
+ * `create` fails at the database.
+ */
+declare class PrismaPromoCodeRedemptionRepository implements PromoCodeRedemptionRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    findBySubscription(subscriptionId: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord | null>;
+    create(data: Omit<PromoCodeRedemptionRecord, 'id' | 'redeemedAt' | 'status' | 'reversedAt'>, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    setReversed(id: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    countByPromoCode(promoCodeId: string, status?: PromoCodeRedemptionStatus): Promise<number>;
+    listByPromoCode(promoCodeId: string): Promise<PromoCodeRedemptionListItem[]>;
+    expireDueRedemptions(now: Date): Promise<number>;
+}
+
+/** `PromoCodeValidationLogRepository` against `promo_code_validation_logs`. */
+declare class PrismaPromoCodeValidationLogRepository implements PromoCodeValidationLogRepository {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    log(args: {
+        promoCodeId: string | null;
+        codeAttempt: string;
+        result: string;
+        ipHash?: string;
+        sessionId?: string;
+    }): Promise<void>;
+    countValid(promoCodeId: string): Promise<number>;
+}
+
+/** `PromoSubscriptionLookup` against the canonical `subscriptions` table. */
+declare class PrismaPromoSubscriptionLookup implements PromoSubscriptionLookup {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    findById(subscriptionId: string, tx?: TransactionContext): Promise<{
+        id: string;
+        tenantId: string;
+        plan: string;
+        billingCycle: BillingCycle;
+        startedAt: Date | null;
+    } | null>;
+}
+
+/**
+ * Default `PromoRevenueDeductionAggregator` for apps without an
+ * `InvoiceDiscount` table: always reports `'0.00'` (the documented port
+ * fallback). Apps with invoice discounts replace it with their own adapter.
+ */
+declare class ZeroPromoRevenueDeductionAggregator implements PromoRevenueDeductionAggregator {
+    sumGrossForPromoCode(_promoCodeId: string): Promise<string>;
+}
+
+/**
+ * DI token for the app's `PasswordHasher` implementation (argon2/bcrypt —
+ * the algorithm stays app-specific). `prismaPersistence({ passwordHasher })`
+ * wires it automatically; manual setups bind it themselves.
+ */
+declare const PASSWORD_HASHER_TOKEN: unique symbol;
+/**
+ * `SuperAdminProvisioningPort` against the canonical `super_admin_users`
+ * table (prisma-fragments/10-super-admin.prisma). Backs the first-run setup
+ * wizard and `<app> user create-super-admin`.
+ */
+declare class PrismaSuperAdminBootstrapAdapter implements SuperAdminProvisioningPort {
+    private readonly prisma;
+    private readonly passwordHasher;
+    constructor(prisma: PrismaLike, passwordHasher: PasswordHasher);
+    countSuperAdmins(): Promise<number>;
+    createSuperAdmin(input: CreateSuperAdminCliInput): Promise<PlatformUserDto>;
+}
+
+/**
+ * `PlanCatalogReadSink` against the canonical `plans`, `plan_versions` and
+ * `feature_catalog_entries` tables — DB hydration of the plan catalog at
+ * boot (`PlanCatalogModule.forRoot({ sink })`).
+ *
+ * `validFrom`/`validUntil` are reported as null: the canonical schema does
+ * not persist booking windows yet (see docs/data-model.md, "Known gaps").
+ */
+declare class PrismaPlanCatalogReadSink implements PlanCatalogReadSink {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    loadSnapshot(projectKey: string): Promise<PlanCatalogReadSnapshot>;
+}
+
+/**
+ * `PlanCatalogImportSink` against the canonical catalog tables — the
+ * one-shot `saas.yaml → DB` import at boot.
+ *
+ * Idempotency per the port contract: existing rows (identity match) are
+ * skipped without error; only the created/skipped flags are reported.
+ */
+declare class PrismaPlanCatalogImportSink implements PlanCatalogImportSink {
+    private readonly prisma;
+    constructor(prisma: PrismaLike);
+    upsertPlan(input: UpsertPlanInput): Promise<UpsertResult>;
+    upsertPlanVersion(input: UpsertPlanVersionInput): Promise<UpsertResult>;
+    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 };