@valentine-efagene/qshelter-common 2.0.72 → 2.0.74

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

@@ -51,4 +51,6 @@ export type * from './models/EventHandler.js';
 export type * from './models/WorkflowEvent.js';
 export type * from './models/EventHandlerExecution.js';
 export type * from './models/DomainEvent.js';
+export type * from './models/PropertyTransferRequest.js';
+export type * from './models/ApprovalRequest.js';
 export type * from './commonInputTypes.js';

package/package.json

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

package/prisma/migrations/20260106062140_add_step_event_attachments/migration.sql

@@ -0,0 +1,22 @@
+-- CreateTable
+CREATE TABLE `step_event_attachments` (
+    `id` VARCHAR(191) NOT NULL,
+    `stepId` VARCHAR(191) NOT NULL,
+    `trigger` ENUM('ON_COMPLETE', 'ON_REJECT', 'ON_SUBMIT', 'ON_RESUBMIT', 'ON_START') NOT NULL,
+    `handlerId` VARCHAR(191) NOT NULL,
+    `priority` INTEGER NOT NULL DEFAULT 100,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `step_event_attachments_stepId_idx`(`stepId`),
+    INDEX `step_event_attachments_handlerId_idx`(`handlerId`),
+    UNIQUE INDEX `step_event_attachments_stepId_handlerId_trigger_key`(`stepId`, `handlerId`, `trigger`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `step_event_attachments` ADD CONSTRAINT `step_event_attachments_stepId_fkey` FOREIGN KEY (`stepId`) REFERENCES `payment_method_phase_steps`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `step_event_attachments` ADD CONSTRAINT `step_event_attachments_handlerId_fkey` FOREIGN KEY (`handlerId`) REFERENCES `event_handlers`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20260107121844_add_property_transfer_requests/migration.sql

@@ -0,0 +1,64 @@
+/*
+  Warnings:
+
+  - A unique constraint covering the columns `[transferredFromId]` on the table `contracts` will be added. If there are existing duplicate values, this will fail.
+
+*/
+-- AlterTable
+ALTER TABLE `contracts` ADD COLUMN `transferredFromId` VARCHAR(191) NULL,
+    MODIFY `status` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED', 'TRANSFERRED') NOT NULL DEFAULT 'DRAFT',
+    MODIFY `state` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED', 'TRANSFERRED') NOT NULL DEFAULT 'DRAFT';
+
+-- CreateTable
+CREATE TABLE `property_transfer_requests` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `sourceContractId` VARCHAR(191) NOT NULL,
+    `targetPropertyUnitId` VARCHAR(191) NOT NULL,
+    `requestedById` VARCHAR(191) NOT NULL,
+    `reviewedById` VARCHAR(191) NULL,
+    `status` ENUM('PENDING', 'APPROVED', 'REJECTED', 'IN_PROGRESS', 'COMPLETED', 'FAILED') NOT NULL DEFAULT 'PENDING',
+    `reason` TEXT NULL,
+    `reviewNotes` TEXT NULL,
+    `priceAdjustmentHandling` VARCHAR(191) NULL,
+    `sourceTotalAmount` DOUBLE NULL,
+    `targetTotalAmount` DOUBLE NULL,
+    `priceAdjustment` DOUBLE NULL,
+    `paymentsMigrated` INTEGER NULL,
+    `targetContractId` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `reviewedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `property_transfer_requests_tenantId_idx`(`tenantId`),
+    INDEX `property_transfer_requests_sourceContractId_idx`(`sourceContractId`),
+    INDEX `property_transfer_requests_targetPropertyUnitId_idx`(`targetPropertyUnitId`),
+    INDEX `property_transfer_requests_requestedById_idx`(`requestedById`),
+    INDEX `property_transfer_requests_status_idx`(`status`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE UNIQUE INDEX `contracts_transferredFromId_key` ON `contracts`(`transferredFromId`);
+
+-- AddForeignKey
+ALTER TABLE `contracts` ADD CONSTRAINT `contracts_transferredFromId_fkey` FOREIGN KEY (`transferredFromId`) REFERENCES `contracts`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_sourceContractId_fkey` FOREIGN KEY (`sourceContractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_targetPropertyUnitId_fkey` FOREIGN KEY (`targetPropertyUnitId`) REFERENCES `property_units`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_requestedById_fkey` FOREIGN KEY (`requestedById`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_reviewedById_fkey` FOREIGN KEY (`reviewedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_targetContractId_fkey` FOREIGN KEY (`targetContractId`) REFERENCES `contracts`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/migrations/20260107172301_add_approval_request_model/migration.sql

@@ -0,0 +1,46 @@
+-- CreateTable
+CREATE TABLE `approval_requests` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `type` ENUM('PROPERTY_TRANSFER', 'PROPERTY_UPDATE', 'USER_WORKFLOW', 'CREDIT_CHECK', 'CONTRACT_TERMINATION', 'REFUND_APPROVAL') NOT NULL,
+    `status` ENUM('PENDING', 'IN_REVIEW', 'APPROVED', 'REJECTED', 'CANCELLED', 'EXPIRED') NOT NULL DEFAULT 'PENDING',
+    `priority` ENUM('LOW', 'NORMAL', 'HIGH', 'URGENT') NOT NULL DEFAULT 'NORMAL',
+    `entityType` VARCHAR(191) NOT NULL,
+    `entityId` VARCHAR(191) NOT NULL,
+    `title` VARCHAR(255) NOT NULL,
+    `description` TEXT NULL,
+    `payload` JSON NULL,
+    `requestedById` VARCHAR(191) NOT NULL,
+    `assigneeId` VARCHAR(191) NULL,
+    `reviewedById` VARCHAR(191) NULL,
+    `reviewNotes` TEXT NULL,
+    `decision` ENUM('APPROVED', 'REJECTED', 'REQUEST_CHANGES') NULL,
+    `expiresAt` DATETIME(3) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `assignedAt` DATETIME(3) NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `approval_requests_tenantId_idx`(`tenantId`),
+    INDEX `approval_requests_type_idx`(`type`),
+    INDEX `approval_requests_status_idx`(`status`),
+    INDEX `approval_requests_priority_idx`(`priority`),
+    INDEX `approval_requests_entityType_entityId_idx`(`entityType`, `entityId`),
+    INDEX `approval_requests_requestedById_idx`(`requestedById`),
+    INDEX `approval_requests_assigneeId_idx`(`assigneeId`),
+    INDEX `approval_requests_createdAt_idx`(`createdAt`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `approval_requests` ADD CONSTRAINT `approval_requests_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_requests` ADD CONSTRAINT `approval_requests_requestedById_fkey` FOREIGN KEY (`requestedById`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_requests` ADD CONSTRAINT `approval_requests_assigneeId_fkey` FOREIGN KEY (`assigneeId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_requests` ADD CONSTRAINT `approval_requests_reviewedById_fkey` FOREIGN KEY (`reviewedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -48,6 +48,16 @@ enum ContractStatus {
   COMPLETED
   CANCELLED
   TERMINATED
+  TRANSFERRED // Contract was transferred to a different property
+}
+
+enum TransferRequestStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  IN_PROGRESS
+  COMPLETED
+  FAILED
 }
 
 enum PhaseStatus {
@@ -292,6 +302,15 @@ model User {
   offerLettersGenerated OfferLetter[] @relation("OfferLetterGenerator")
   offerLettersSent      OfferLetter[] @relation("OfferLetterSender")
 
+  // Property transfer requests
+  transferRequestsSubmitted PropertyTransferRequest[] @relation("TransferRequestor")
+  transferRequestsReviewed  PropertyTransferRequest[] @relation("TransferReviewer")
+
+  // Unified approval requests
+  approvalRequestsSubmitted ApprovalRequest[] @relation("ApprovalRequestor")
+  approvalRequestsAssigned  ApprovalRequest[] @relation("ApprovalAssignee")
+  approvalRequestsReviewed  ApprovalRequest[] @relation("ApprovalReviewer")
+
   @@index([email])
   @@index([tenantId])
   @@map("users")
@@ -381,6 +400,12 @@ model Tenant {
   eventHandlers  EventHandler[]
   workflowEvents WorkflowEvent[]
 
+  // Property transfer requests
+  propertyTransferRequests PropertyTransferRequest[]
+
+  // Unified approval requests
+  approvalRequests ApprovalRequest[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -779,6 +804,9 @@ model PropertyUnit {
   // Relations
   contracts Contract[]
 
+  // Transfer requests targeting this unit
+  transferRequests PropertyTransferRequest[]
+
   @@unique([variantId, unitNumber])
   @@index([variantId])
   @@index([status])
@@ -1083,6 +1111,16 @@ model Contract {
   // Payment method change requests for this contract
   paymentMethodChangeRequests PaymentMethodChangeRequest[]
 
+  // Transfer tracking - when a contract is transferred to a different property
+  transferredFromId String?   @unique // Source contract if this was created via transfer
+  transferredFrom   Contract? @relation("ContractTransfer", fields: [transferredFromId], references: [id])
+  transferredTo     Contract? @relation("ContractTransfer")
+
+  // Transfer requests where this contract is the source
+  outgoingTransferRequests PropertyTransferRequest[] @relation("SourceContract")
+  // Transfer requests where this contract is the target (created after approval)
+  incomingTransferRequests PropertyTransferRequest[] @relation("TargetContract")
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -1974,3 +2012,151 @@ model DomainEvent {
   @@index([occurredAt])
   @@map("domain_events")
 }
+
+// =============================================================================
+// Property Transfer Request
+// =============================================================================
+// Allows a buyer to request transferring their contract to a different property
+// while preserving payments, completed workflow steps, and progress.
+// =============================================================================
+
+model PropertyTransferRequest {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Source contract being transferred
+  sourceContractId String
+  sourceContract   Contract @relation("SourceContract", fields: [sourceContractId], references: [id], onDelete: Cascade)
+
+  // Target property unit
+  targetPropertyUnitId String
+  targetPropertyUnit   PropertyUnit @relation(fields: [targetPropertyUnitId], references: [id])
+
+  // Requestor (buyer) and reviewer (admin)
+  requestedById String
+  requestedBy   User    @relation("TransferRequestor", fields: [requestedById], references: [id])
+  reviewedById  String?
+  reviewedBy    User?   @relation("TransferReviewer", fields: [reviewedById], references: [id])
+
+  // Status and workflow
+  status TransferRequestStatus @default(PENDING)
+
+  // Request details
+  reason String? @db.Text // Buyer's reason for transfer
+
+  // Review details
+  reviewNotes             String? @db.Text // Admin notes on decision
+  priceAdjustmentHandling String? // How to handle price difference: ADD_TO_MORTGAGE, REQUIRE_PAYMENT, CREDIT_BUYER
+
+  // Computed values
+  sourceTotalAmount Float? // Original contract total
+  targetTotalAmount Float? // New contract total (based on target property)
+  priceAdjustment   Float? // Difference (positive = buyer owes more)
+  paymentsMigrated  Int?   // Number of payments migrated
+
+  // Result - new contract created after approval
+  targetContractId String?
+  targetContract   Contract? @relation("TargetContract", fields: [targetContractId], references: [id])
+
+  // Timestamps
+  createdAt   DateTime  @default(now())
+  reviewedAt  DateTime?
+  completedAt DateTime?
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([sourceContractId])
+  @@index([targetPropertyUnitId])
+  @@index([requestedById])
+  @@index([status])
+  @@map("property_transfer_requests")
+}
+
+// =============================================================================
+// UNIFIED APPROVAL REQUESTS
+// =============================================================================
+
+enum ApprovalRequestType {
+  PROPERTY_TRANSFER    // Property unit transfer between contracts
+  PROPERTY_UPDATE      // Property/unit listing update requiring approval
+  USER_WORKFLOW        // User workflow step approval
+  CREDIT_CHECK         // Credit check result review
+  CONTRACT_TERMINATION // Contract termination approval
+  REFUND_APPROVAL      // Refund request approval
+}
+
+enum ApprovalRequestStatus {
+  PENDING      // Awaiting review
+  IN_REVIEW    // Assigned to reviewer
+  APPROVED     // Approved by reviewer
+  REJECTED     // Rejected by reviewer
+  CANCELLED    // Cancelled by requestor
+  EXPIRED      // Auto-expired (if TTL configured)
+}
+
+enum ApprovalRequestPriority {
+  LOW
+  NORMAL
+  HIGH
+  URGENT
+}
+
+// Polymorphic approval request model for unified admin dashboard
+model ApprovalRequest {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Request type and status
+  type     ApprovalRequestType
+  status   ApprovalRequestStatus   @default(PENDING)
+  priority ApprovalRequestPriority @default(NORMAL)
+
+  // Polymorphic reference to the entity requiring approval
+  entityType String // e.g., "PropertyTransferRequest", "PropertyUnit", "User"
+  entityId   String // ID of the referenced entity
+
+  // Request metadata
+  title       String  @db.VarChar(255) // Human-readable title for the request
+  description String? @db.Text        // Detailed description
+
+  // Payload for any additional context (JSON)
+  payload Json? // Flexible data storage for type-specific details
+
+  // Requestor - who created the request
+  requestedById String
+  requestedBy   User   @relation("ApprovalRequestor", fields: [requestedById], references: [id])
+
+  // Assignee - admin/reviewer assigned to handle this request
+  assigneeId String?
+  assignee   User?   @relation("ApprovalAssignee", fields: [assigneeId], references: [id])
+
+  // Reviewer - who made the final decision (may differ from assignee)
+  reviewedById String?
+  reviewedBy   User?   @relation("ApprovalReviewer", fields: [reviewedById], references: [id])
+
+  // Review details
+  reviewNotes String? @db.Text // Reviewer's notes/comments
+  decision    ApprovalDecision? // APPROVED, REJECTED, REQUEST_CHANGES
+
+  // Expiration
+  expiresAt DateTime? // Optional TTL for auto-expiration
+
+  // Timestamps
+  createdAt   DateTime  @default(now())
+  assignedAt  DateTime? // When assigned to reviewer
+  reviewedAt  DateTime? // When decision was made
+  completedAt DateTime? // When fully processed
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([type])
+  @@index([status])
+  @@index([priority])
+  @@index([entityType, entityId])
+  @@index([requestedById])
+  @@index([assigneeId])
+  @@index([createdAt])
+  @@map("approval_requests")
+}