@valentine-efagene/qshelter-common 2.0.78 → 2.0.82

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.78",
+  "version": "2.0.82",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/migrations/20260107214834_add_contract_refund_model/migration.sql

@@ -0,0 +1,64 @@
+/*
+  Warnings:
+
+  - You are about to alter the column `actorType` on the `contract_events` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(15))`.
+  - You are about to alter the column `eventGroup` on the `contract_events` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(14))`.
+  - You are about to alter the column `eventType` on the `contract_events` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(13))`.
+  - You are about to alter the column `refundStatus` on the `contract_terminations` table. The data in that column could be lost. The data in that column will be cast from `Enum(EnumId(34))` to `Enum(EnumId(27))`.
+
+*/
+-- AlterTable
+ALTER TABLE `contract_events` MODIFY `actorType` ENUM('USER', 'SYSTEM', 'WEBHOOK', 'ADMIN') NULL,
+    MODIFY `eventGroup` ENUM('STATE_CHANGE', 'PAYMENT', 'DOCUMENT', 'NOTIFICATION', 'WORKFLOW') NULL,
+    MODIFY `eventType` ENUM('CONTRACT_CREATED', 'CONTRACT_STATE_CHANGED', 'PHASE_ACTIVATED', 'PHASE_COMPLETED', 'STEP_COMPLETED', 'STEP_REJECTED', 'DOCUMENT_SUBMITTED', 'DOCUMENT_APPROVED', 'DOCUMENT_REJECTED', 'PAYMENT_INITIATED', 'PAYMENT_COMPLETED', 'PAYMENT_FAILED', 'INSTALLMENTS_GENERATED', 'CONTRACT_SIGNED', 'CONTRACT_TERMINATED', 'CONTRACT_TRANSFERRED', 'UNDERWRITING_COMPLETED', 'OFFER_LETTER_GENERATED') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `contract_terminations` MODIFY `refundStatus` ENUM('PENDING', 'APPROVED', 'REJECTED', 'PROCESSING', 'COMPLETED', 'FAILED', 'CANCELLED') NOT NULL DEFAULT 'PENDING';
+
+-- CreateTable
+CREATE TABLE `contract_refunds` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `contractId` VARCHAR(191) NOT NULL,
+    `amount` DOUBLE NOT NULL,
+    `reason` TEXT NOT NULL,
+    `status` ENUM('PENDING', 'APPROVED', 'REJECTED', 'PROCESSING', 'COMPLETED', 'FAILED', 'CANCELLED') NOT NULL DEFAULT 'PENDING',
+    `requestedById` VARCHAR(191) NOT NULL,
+    `approvedById` VARCHAR(191) NULL,
+    `processedById` VARCHAR(191) NULL,
+    `paymentMethod` VARCHAR(191) NULL,
+    `referenceNumber` VARCHAR(191) NULL,
+    `recipientName` VARCHAR(191) NULL,
+    `recipientAccount` VARCHAR(191) NULL,
+    `recipientBank` VARCHAR(191) NULL,
+    `requestedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `approvedAt` DATETIME(3) NULL,
+    `rejectedAt` DATETIME(3) NULL,
+    `processedAt` DATETIME(3) NULL,
+    `approvalNotes` TEXT NULL,
+    `rejectionNotes` TEXT NULL,
+    `processingNotes` TEXT NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `contract_refunds_contractId_idx`(`contractId`),
+    INDEX `contract_refunds_status_idx`(`status`),
+    INDEX `contract_refunds_tenantId_idx`(`tenantId`),
+    INDEX `contract_refunds_requestedById_idx`(`requestedById`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `contract_refunds` ADD CONSTRAINT `contract_refunds_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_refunds` ADD CONSTRAINT `contract_refunds_contractId_fkey` FOREIGN KEY (`contractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_refunds` ADD CONSTRAINT `contract_refunds_requestedById_fkey` FOREIGN KEY (`requestedById`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_refunds` ADD CONSTRAINT `contract_refunds_approvedById_fkey` FOREIGN KEY (`approvedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_refunds` ADD CONSTRAINT `contract_refunds_processedById_fkey` FOREIGN KEY (`processedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

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