@ambushsoftworks/nestjs-payments-graphql 0.1.0 → 0.1.3

package/prisma/payment-models.prisma

@@ -0,0 +1,504 @@
+// =============================================================================
+// @ambushsoftworks/nestjs-payments-graphql — Reference Prisma schema
+// =============================================================================
+//
+// This file is a DOCUMENTATION FRAGMENT. It is not loaded by Prisma at runtime
+// and it is not imported automatically anywhere. Copy the models and enums
+// below into your own `schema.prisma` and wire up the consumer-owned relations
+// (marked with `// CONSUMER:`) to the models in your application.
+//
+// Field shapes are fixed by the package's repository interfaces
+// (IInvoiceRepository, IPaymentRepository, etc.). You may:
+//   - Rename models freely (your repo adapter is the mapping layer).
+//   - Add columns (e.g. a soft-delete flag, additional audit fields).
+//   - Swap column types for compatible ones (e.g. `@db.VarChar(255)` on strings).
+//
+// You may NOT:
+//   - Change the cardinality of a field (e.g. make a required field optional
+//     without reflecting that in your repository adapter).
+//   - Drop tracked enum values (listed below).
+//
+// The package is database-agnostic — PostgreSQL examples are shown (e.g.
+// `@db.Decimal(5, 4)`); swap for your provider's equivalents as needed.
+//
+// -----------------------------------------------------------------------------
+// Model checklist
+// -----------------------------------------------------------------------------
+//
+// Always required:
+//   - Invoice
+//   - InvoiceLineItem
+//   - Payment
+//   - Refund
+//   - PaymentConfig
+//   - PaymentProvider
+//   - ProcessedWebhookEvent
+//
+// Required when `features.paymentPlans = true`:
+//   - PaymentPlan
+//   - PaymentPlanInstallment
+//
+// Required when `features.recurringInvoices = true`:
+//   - RecurringInvoice
+//   - RecurringInvoiceLineItem
+//   - PaymentCustomer
+//
+// All enums are required if you use the corresponding model.
+// =============================================================================
+
+
+// -----------------------------------------------------------------------------
+// Enums
+// -----------------------------------------------------------------------------
+// These enum value sets must match exactly — core services compare against
+// these strings. Add new values at your own risk; the package will not
+// recognize them.
+
+enum InvoiceStatus {
+  DRAFT
+  SENT
+  PARTIALLY_PAID
+  PAID
+  OVERDUE
+  VOID
+  REFUNDED
+}
+
+enum PaymentMethod {
+  CREDIT_CARD
+  DEBIT
+  E_TRANSFER
+  BANK_TRANSFER
+  CHEQUE
+  CASH
+  OTHER
+}
+
+enum PaymentStatus {
+  PENDING
+  PENDING_CONFIRMATION
+  PROCESSING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+  REJECTED
+  REFUNDED
+  PARTIALLY_REFUNDED
+}
+
+enum RefundStatus {
+  PENDING
+  PROCESSING
+  SUCCEEDED
+  FAILED
+}
+
+enum PaymentPlanStatus {
+  ACTIVE
+  COMPLETED
+  CANCELLED
+  DEFAULTED
+}
+
+enum InstallmentStatus {
+  PENDING
+  INVOICED
+  PAID
+  OVERDUE
+  WAIVED
+  CANCELLED
+}
+
+enum RecurringIntervalUnit {
+  DAYS
+  MONTHS
+}
+
+enum RecurringInvoiceStatus {
+  ACTIVE
+  PAUSED
+  CANCELLED
+}
+
+
+// -----------------------------------------------------------------------------
+// Core models (always required)
+// -----------------------------------------------------------------------------
+
+model PaymentConfig {
+  id         String @id @default(uuid())
+  divisionId String @unique // CONSUMER: tenant/org/division scope — unique per tenant
+
+  // E-transfer settings
+  eTransferEnabled     Boolean @default(false)
+  eTransferEmail       String?
+  eTransferRecipient   String? // Display name for e-transfer recipient
+  eTransferAutoDeposit Boolean @default(true)
+
+  // Defaults applied when an invoice omits currency or tax rate
+  defaultCurrency String   @default("USD")
+  defaultTaxRate  Decimal? @db.Decimal(5, 4) // e.g. 0.1300 for 13%
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  providers PaymentProvider[]
+
+  // CONSUMER: add @relation to your Tenant/Division/Organization model
+  // division Division @relation(fields: [divisionId], references: [id], onDelete: Cascade)
+}
+
+model PaymentProvider {
+  id              String  @id @default(uuid())
+  paymentConfigId String
+  providerType    String // e.g. "stripe"
+  isActive        Boolean @default(true)
+  config          Json? // Non-secret config (account IDs, webhook endpoint IDs)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  paymentConfig PaymentConfig @relation(fields: [paymentConfigId], references: [id], onDelete: Cascade)
+
+  @@unique([paymentConfigId, providerType])
+}
+
+model Invoice {
+  id            String        @id @default(uuid())
+  divisionId    String // CONSUMER: tenant/org scope
+  invoiceNumber String        @unique
+  status        InvoiceStatus @default(DRAFT)
+
+  // CONSUMER: opaque foreign key to your client/customer/contact record.
+  // The package treats this as an opaque string.
+  clientDetailsId String
+
+  // Polymorphic entity reference — what this invoice is FOR (booking, order,
+  // enrollment, etc.). Both fields nullable so invoices may stand alone.
+  referenceType String?
+  referenceId   String?
+
+  // Payment plan link (populated when an invoice is generated from an installment)
+  paymentPlanId     String?
+  installmentNumber Int?
+
+  // Recurring invoice link (populated when an invoice is generated from a recurring config)
+  recurringInvoiceId String?
+
+  // Financial amounts — ALL IN CENTS (integer minor units).
+  // taxRate is a decimal fraction: 0.1300 = 13%.
+  subtotal   Int     @default(0)
+  taxRate    Decimal @default(0) @db.Decimal(5, 4)
+  taxAmount  Int     @default(0)
+  discount   Int     @default(0)
+  total      Int     @default(0)
+  amountPaid Int     @default(0)
+  amountDue  Int     @default(0)
+
+  currency String @default("USD")
+
+  // E-transfer — code is the client-visible confirmation string, answer is
+  // the security answer the client must provide to the bank.
+  eTransferCode   String? @unique
+  eTransferAnswer String?
+
+  issuedAt DateTime?
+  dueAt    DateTime?
+
+  notes       String? // Internal staff notes (never exposed to clients)
+  clientNotes String? // Visible on invoice to client
+
+  // Consumer-defined key-value pairs (opaque to the package)
+  metadata Json?
+
+  // Audit fields
+  createdBy  String // CONSUMER: accountId/userId who created this invoice
+  voidedBy   String?
+  voidedAt   DateTime?
+  voidReason String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Relations
+  lineItems        InvoiceLineItem[]
+  payments         Payment[]
+  // Reverse relation for PaymentPlanInstallment.invoiceId one-to-one
+  installment      PaymentPlanInstallment?
+  paymentPlan      PaymentPlan?             @relation("InvoicePlan", fields: [paymentPlanId], references: [id], onDelete: SetNull)
+  recurringInvoice RecurringInvoice?        @relation(fields: [recurringInvoiceId], references: [id])
+
+  // CONSUMER: add relations to your tenant and client models.
+  // Use `onDelete: Restrict` on financial relations — data-retention rules
+  // typically forbid cascade-deleting invoices when a client is removed.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([divisionId, status])
+  @@index([clientDetailsId])
+  @@index([referenceType, referenceId])
+  @@index([paymentPlanId])
+  @@index([recurringInvoiceId])
+  @@index([status, dueAt]) // For overdue scheduler
+}
+
+model InvoiceLineItem {
+  id        String @id @default(uuid())
+  invoiceId String
+
+  description String
+  quantity    Int     @default(1)
+  unitPrice   Int // cents
+  sortOrder   Int     @default(0)
+  isTaxable   Boolean @default(true)
+
+  // Optional polymorphic reference — what this line item represents
+  referenceType String?
+  referenceId   String?
+
+  // Consumer-defined key-value pairs (opaque to the package)
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  invoice Invoice @relation(fields: [invoiceId], references: [id], onDelete: Cascade)
+
+  @@index([invoiceId, sortOrder])
+}
+
+model Payment {
+  id        String        @id @default(uuid())
+  invoiceId String
+  amount    Int // cents
+  currency  String        @default("USD")
+  method    PaymentMethod
+  status    PaymentStatus @default(PENDING)
+
+  // Provider fields (both null for manual payments, both set for online)
+  provider          String? // e.g. "stripe"
+  providerPaymentId String?
+  providerData      Json? // Provider-specific metadata — NEVER log raw card data
+  receiptUrl        String?
+
+  // Manual payment fields
+  referenceNumber String? // cheque number, e-transfer confirmation, etc.
+  notes           String?
+  processedAt     DateTime? // When payment was actually processed (may differ from createdAt)
+  receivedBy      String? // CONSUMER: accountId who recorded the manual payment
+
+  // Reconciliation — set true when gateway cancellation fails during voidInvoice
+  needsReconciliation Boolean @default(false)
+
+  // Audit
+  createdBy String // CONSUMER: accountId/userId who created the payment
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  invoice Invoice  @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+  refunds Refund[]
+
+  // Note: null-null is valid (manual payments) — PostgreSQL unique allows multiple nulls.
+  @@unique([provider, providerPaymentId])
+  @@index([invoiceId, status])
+}
+
+model Refund {
+  id        String       @id @default(uuid())
+  paymentId String
+  amount    Int // cents
+  currency  String       @default("USD")
+  status    RefundStatus @default(PENDING)
+  reason    String?
+
+  // Provider fields (null for manual refunds)
+  providerRefundId String?
+  providerData     Json?
+
+  // Audit
+  createdBy   String // CONSUMER: accountId/userId who created the refund
+  processedBy String? // CONSUMER: accountId who processed a manual refund
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  payment Payment @relation(fields: [paymentId], references: [id], onDelete: Restrict)
+
+  @@index([paymentId])
+}
+
+model ProcessedWebhookEvent {
+  // Stripe event IDs are their own primary key.
+  // The package's IWebhookIdempotencyRepository uses this to no-op on replays.
+  eventId     String   @id
+  processedAt DateTime @default(now())
+
+  @@index([processedAt]) // For TTL cleanup via cleanupBefore()
+}
+
+
+// -----------------------------------------------------------------------------
+// Payment plan models (required when features.paymentPlans = true)
+// -----------------------------------------------------------------------------
+
+model PaymentPlan {
+  id         String            @id @default(uuid())
+  divisionId String // CONSUMER: tenant/org scope
+  status     PaymentPlanStatus @default(ACTIVE)
+
+  clientDetailsId String // CONSUMER: opaque client ID
+
+  // Polymorphic entity reference
+  referenceType String?
+  referenceId   String?
+
+  totalAmount Int // cents
+  currency    String @default("USD")
+
+  name        String?
+  description String?
+
+  createdBy    String // CONSUMER: accountId
+  cancelledBy  String?
+  cancelledAt  DateTime?
+  cancelReason String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  installments PaymentPlanInstallment[]
+  invoices     Invoice[]                @relation("InvoicePlan")
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([divisionId, status])
+  @@index([clientDetailsId])
+  @@index([referenceType, referenceId])
+}
+
+model PaymentPlanInstallment {
+  id            String            @id @default(uuid())
+  paymentPlanId String
+  sequenceOrder Int
+  amount        Int // cents
+  status        InstallmentStatus @default(PENDING)
+  dueAt         DateTime?
+
+  // One-to-one link to the generated invoice (null until invoiced).
+  // INVARIANT: when set, Invoice.paymentPlanId and Invoice.installmentNumber
+  // must also be set atomically by the consumer repository adapter.
+  invoiceId String? @unique
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  paymentPlan PaymentPlan @relation(fields: [paymentPlanId], references: [id], onDelete: Cascade)
+  invoice     Invoice?    @relation(fields: [invoiceId], references: [id], onDelete: SetNull)
+
+  @@index([paymentPlanId, sequenceOrder])
+}
+
+
+// -----------------------------------------------------------------------------
+// Recurring invoice models (required when features.recurringInvoices = true)
+// -----------------------------------------------------------------------------
+
+model RecurringInvoice {
+  id         String @id @default(uuid())
+  divisionId String // CONSUMER: tenant/org scope
+
+  // Schedule configuration
+  intervalUnit    RecurringIntervalUnit
+  intervalValue   Int
+  anchorDate      DateTime // Immutable after creation — all next dates are computed from this
+  nextInvoiceAt   DateTime
+  lastGeneratedAt DateTime? // Null = never generated; set after each successful generation
+
+  status   RecurringInvoiceStatus @default(ACTIVE)
+  autoSend Boolean                @default(true)
+
+  // Invoice template fields
+  clientDetailsId String // CONSUMER: opaque client ID
+  currency        String  @default("USD")
+  taxRate         Decimal @default(0) @db.Decimal(5, 4)
+  notes           String?
+  clientNotes     String?
+
+  // Polymorphic entity reference
+  referenceType String?
+  referenceId   String?
+
+  // Auto-charge (Phase 2) — uses the stored PaymentCustomer for the client
+  autoCharge          Boolean @default(false)
+  metadata            Json?
+  consecutiveFailures Int     @default(0)
+  lastFailureReason   String?
+
+  // Lifecycle tracking
+  pausedAt     DateTime?
+  pausedBy     String?
+  cancelledAt  DateTime?
+  cancelledBy  String?
+  cancelReason String?
+
+  createdBy String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  templateLineItems RecurringInvoiceLineItem[]
+  generatedInvoices Invoice[]
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([status, nextInvoiceAt]) // Used by the generator claim query
+  @@index([divisionId, status])
+}
+
+model RecurringInvoiceLineItem {
+  id                 String @id @default(uuid())
+  recurringInvoiceId String
+
+  description String
+  quantity    Int     @default(1)
+  unitPrice   Int // cents
+  sortOrder   Int     @default(0)
+  isTaxable   Boolean @default(true)
+
+  referenceType String?
+  referenceId   String?
+
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  recurringInvoice RecurringInvoice @relation(fields: [recurringInvoiceId], references: [id], onDelete: Cascade)
+
+  @@index([recurringInvoiceId, sortOrder])
+}
+
+model PaymentCustomer {
+  // Maps a (division, client, provider) triple to a provider-side customer ID
+  // (e.g. Stripe Customer). Powers auto-charge on recurring invoices and
+  // future saved-payment-method flows.
+  id                 String   @id @default(uuid())
+  divisionId         String
+  clientDetailsId    String
+  provider           String // "stripe"
+  providerCustomerId String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@unique([divisionId, clientDetailsId, provider])
+  @@index([providerCustomerId])
+}