@valentine-efagene/qshelter-common 2.0.77 → 2.0.81

package/dist/generated/client/models/index.d.ts

@@ -7,6 +7,7 @@ export * from './ContractEvent';
 export * from './ContractInstallment';
 export * from './ContractPayment';
 export * from './ContractPhase';
+export * from './ContractRefund';
 export * from './ContractTermination';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';

package/dist/generated/client/models/index.js

@@ -7,6 +7,7 @@ export * from './ContractEvent';
 export * from './ContractInstallment';
 export * from './ContractPayment';
 export * from './ContractPhase';
+export * from './ContractRefund';
 export * from './ContractTermination';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';

package/dist/generated/client/models.d.ts

@@ -32,6 +32,7 @@ export type * from './models/PaymentMethodPhaseStep.js';
 export type * from './models/StepEventAttachment.js';
 export type * from './models/PaymentMethodPhaseDocument.js';
 export type * from './models/Contract.js';
+export type * from './models/ContractRefund.js';
 export type * from './models/ContractPhase.js';
 export type * from './models/ContractEvent.js';
 export type * from './models/DocumentationStep.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.77",
+  "version": "2.0.81",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/schema.prisma

@@ -153,16 +153,6 @@ enum TerminationStatus {
   CANCELLED // Termination request was cancelled
 }
 
-enum RefundStatus {
-  NOT_APPLICABLE // No refund needed (no payments made)
-  PENDING // Refund not yet initiated
-  INITIATED // Refund request sent to payment gateway
-  PROCESSING // Gateway processing refund
-  PARTIAL_COMPLETED // Some refund completed (penalties deducted)
-  COMPLETED // Full refund completed
-  FAILED // Refund failed (needs manual intervention)
-}
-
 enum TerminationInitiator {
   BUYER
   SELLER
@@ -240,6 +230,16 @@ enum EventActorType {
   ADMIN
 }
 
+enum RefundStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  PROCESSING
+  COMPLETED
+  FAILED
+  CANCELLED
+}
+
 // =============================================================================
 // EVENT-DRIVEN WORKFLOW ENUMS
 // =============================================================================
@@ -347,6 +347,11 @@ model User {
   approvalRequestsAssigned  ApprovalRequest[] @relation("ApprovalAssignee")
   approvalRequestsReviewed  ApprovalRequest[] @relation("ApprovalReviewer")
 
+  // Contract refunds
+  requestedRefunds ContractRefund[] @relation("RefundRequester")
+  approvedRefunds  ContractRefund[] @relation("RefundApprover")
+  processedRefunds ContractRefund[] @relation("RefundProcessor")
+
   @@index([email])
   @@index([tenantId])
   @@map("users")
@@ -442,6 +447,9 @@ model Tenant {
   // Unified approval requests
   approvalRequests ApprovalRequest[]
 
+  // Contract refunds
+  contractRefunds ContractRefund[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -1159,6 +1167,9 @@ model Contract {
   // Audit trail
   events ContractEvent[]
 
+  // Refund requests
+  refunds ContractRefund[]
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -1169,6 +1180,61 @@ model Contract {
   @@map("contracts")
 }
 
+// =============================================================================
+// CONTRACT REFUNDS - Track refund requests for overpayments or cancellations
+// =============================================================================
+model ContractRefund {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  amount Float
+  reason String       @db.Text
+  status RefundStatus @default(PENDING)
+
+  // Who requested the refund
+  requestedById String
+  requestedBy   User   @relation("RefundRequester", fields: [requestedById], references: [id])
+
+  // Who approved/rejected the refund
+  approvedById String?
+  approvedBy   User?   @relation("RefundApprover", fields: [approvedById], references: [id])
+
+  // Who processed the refund (finance team)
+  processedById String?
+  processedBy   User?   @relation("RefundProcessor", fields: [processedById], references: [id])
+
+  // Refund payment details
+  paymentMethod    String? // BANK_TRANSFER, CHEQUE, MOBILE_MONEY, etc.
+  referenceNumber  String? // Bank/payment reference
+  recipientName    String?
+  recipientAccount String?
+  recipientBank    String?
+
+  // Timestamps
+  requestedAt DateTime  @default(now())
+  approvedAt  DateTime?
+  rejectedAt  DateTime?
+  processedAt DateTime?
+
+  // Additional notes
+  approvalNotes   String? @db.Text
+  rejectionNotes  String? @db.Text
+  processingNotes String? @db.Text
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([contractId])
+  @@index([status])
+  @@index([tenantId])
+  @@index([requestedById])
+  @@map("contract_refunds")
+}
+
 // Phase within a contract - can be DOCUMENTATION or PAYMENT type
 // Admin names phases freely (e.g., "KYC Documents", "Downpayment", "Monthly Mortgage")
 model ContractPhase {
@@ -1624,7 +1690,7 @@ model ContractTermination {
   settlementNotes  String? @db.Text
 
   // Refund processing
-  refundStatus         RefundStatus @default(NOT_APPLICABLE)
+  refundStatus         RefundStatus @default(PENDING)
   refundReference      String? // Payment gateway reference
   refundMethod         String? // ORIGINAL_METHOD, BANK_TRANSFER, CHECK, WALLET
   refundAccountDetails Json? // Encrypted bank details if needed