@valentine-efagene/qshelter-common 2.0.40 → 2.0.42

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

@@ -0,0 +1 @@
+export {};

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

@@ -42,6 +42,7 @@ export * from './Settings';
 export * from './Social';
 export * from './Tenant';
 export * from './Transaction';
+export * from './UnderwritingDecision';
 export * from './User';
 export * from './UserRole';
 export * from './UserSuspension';

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

@@ -42,6 +42,7 @@ export * from './Settings';
 export * from './Social';
 export * from './Tenant';
 export * from './Transaction';
+export * from './UnderwritingDecision';
 export * from './User';
 export * from './UserRole';
 export * from './UserSuspension';

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

@@ -43,6 +43,7 @@ export type * from './models/DocumentTemplate.js';
 export type * from './models/OfferLetter.js';
 export type * from './models/ContractTermination.js';
 export type * from './models/Prequalification.js';
+export type * from './models/UnderwritingDecision.js';
 export type * from './models/PaymentMethodChangeRequest.js';
 export type * from './models/DocumentRequirementRule.js';
 export type * from './models/DomainEvent.js';

package/dist/src/events/notification-enums.d.ts

@@ -26,6 +26,9 @@ export declare enum NotificationType {
     OFFER_LETTER_SENT = "offerLetterSent",
     OFFER_LETTER_SIGNED = "offerLetterSigned",
     OFFER_LETTER_EXPIRED = "offerLetterExpired",
+    UNDERWRITING_APPROVED = "underwritingApproved",
+    UNDERWRITING_REJECTED = "underwritingRejected",
+    UNDERWRITING_CONDITIONAL = "underwritingConditional",
     ADMIN_CONTRIBUTION_RECEIVED = "adminContributionReceived",
     ADMIN_PROPERTY_ALLOCATION = "adminPropertyAllocation",
     ADMIN_INVITE = "adminInviteAdmin",

package/dist/src/events/notification-enums.js

@@ -34,6 +34,10 @@ export var NotificationType;
     NotificationType["OFFER_LETTER_SENT"] = "offerLetterSent";
     NotificationType["OFFER_LETTER_SIGNED"] = "offerLetterSigned";
     NotificationType["OFFER_LETTER_EXPIRED"] = "offerLetterExpired";
+    // Underwriting
+    NotificationType["UNDERWRITING_APPROVED"] = "underwritingApproved";
+    NotificationType["UNDERWRITING_REJECTED"] = "underwritingRejected";
+    NotificationType["UNDERWRITING_CONDITIONAL"] = "underwritingConditional";
     // Admin
     NotificationType["ADMIN_CONTRIBUTION_RECEIVED"] = "adminContributionReceived";
     NotificationType["ADMIN_PROPERTY_ALLOCATION"] = "adminPropertyAllocation";

package/package.json

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

package/prisma/migrations/20260104084843_add_document_templates_and_offer_letters/migration.sql

@@ -0,0 +1,77 @@
+-- AlterTable
+ALTER TABLE `contract_documents` MODIFY `status` ENUM('DRAFT', 'PENDING', 'PENDING_SIGNATURE', 'SENT', 'VIEWED', 'SIGNED', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED') NOT NULL DEFAULT 'PENDING';
+
+-- CreateTable
+CREATE TABLE `document_templates` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `code` VARCHAR(191) NOT NULL,
+    `description` VARCHAR(191) NULL,
+    `version` INTEGER NOT NULL DEFAULT 1,
+    `htmlTemplate` TEXT NOT NULL,
+    `cssStyles` TEXT NULL,
+    `mergeFields` JSON NULL,
+    `isActive` BOOLEAN NOT NULL DEFAULT true,
+    `isDefault` BOOLEAN NOT NULL DEFAULT false,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `document_templates_tenantId_idx`(`tenantId`),
+    INDEX `document_templates_code_idx`(`code`),
+    UNIQUE INDEX `document_templates_tenantId_code_version_key`(`tenantId`, `code`, `version`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `offer_letters` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `contractId` VARCHAR(191) NOT NULL,
+    `templateId` VARCHAR(191) NOT NULL,
+    `letterNumber` VARCHAR(191) NOT NULL,
+    `type` ENUM('PROVISIONAL', 'FINAL') NOT NULL,
+    `status` ENUM('DRAFT', 'GENERATED', 'SENT', 'VIEWED', 'SIGNED', 'EXPIRED', 'CANCELLED') NOT NULL DEFAULT 'DRAFT',
+    `htmlContent` TEXT NULL,
+    `pdfUrl` VARCHAR(191) NULL,
+    `pdfKey` VARCHAR(191) NULL,
+    `mergeData` JSON NULL,
+    `sentAt` DATETIME(3) NULL,
+    `viewedAt` DATETIME(3) NULL,
+    `signedAt` DATETIME(3) NULL,
+    `signatureIp` VARCHAR(191) NULL,
+    `signatureData` JSON NULL,
+    `expiresAt` DATETIME(3) NULL,
+    `expiredAt` DATETIME(3) NULL,
+    `cancelledAt` DATETIME(3) NULL,
+    `cancelReason` VARCHAR(191) NULL,
+    `generatedById` VARCHAR(191) NULL,
+    `sentById` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `offer_letters_letterNumber_key`(`letterNumber`),
+    INDEX `offer_letters_tenantId_idx`(`tenantId`),
+    INDEX `offer_letters_contractId_idx`(`contractId`),
+    INDEX `offer_letters_type_idx`(`type`),
+    INDEX `offer_letters_status_idx`(`status`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `document_templates` ADD CONSTRAINT `document_templates_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `offer_letters` ADD CONSTRAINT `offer_letters_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `offer_letters` ADD CONSTRAINT `offer_letters_contractId_fkey` FOREIGN KEY (`contractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `offer_letters` ADD CONSTRAINT `offer_letters_templateId_fkey` FOREIGN KEY (`templateId`) REFERENCES `document_templates`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `offer_letters` ADD CONSTRAINT `offer_letters_generatedById_fkey` FOREIGN KEY (`generatedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `offer_letters` ADD CONSTRAINT `offer_letters_sentById_fkey` FOREIGN KEY (`sentById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/migrations/20260104095131_add_underwriting_decision/migration.sql

@@ -0,0 +1,31 @@
+-- CreateTable
+CREATE TABLE `underwriting_decisions` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `prequalificationId` VARCHAR(191) NOT NULL,
+    `decision` ENUM('APPROVE', 'REJECT', 'CONDITIONAL') NOT NULL,
+    `score` DOUBLE NULL,
+    `reasons` JSON NULL,
+    `conditions` JSON NULL,
+    `rulesVersion` VARCHAR(191) NULL,
+    `ruleResults` JSON NULL,
+    `externalChecks` JSON NULL,
+    `isManualReview` BOOLEAN NOT NULL DEFAULT false,
+    `reviewedBy` VARCHAR(191) NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `reviewNotes` TEXT NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `underwriting_decisions_tenantId_idx`(`tenantId`),
+    INDEX `underwriting_decisions_prequalificationId_idx`(`prequalificationId`),
+    INDEX `underwriting_decisions_decision_idx`(`decision`),
+    INDEX `underwriting_decisions_createdAt_idx`(`createdAt`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `underwriting_decisions` ADD CONSTRAINT `underwriting_decisions_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `underwriting_decisions` ADD CONSTRAINT `underwriting_decisions_prequalificationId_fkey` FOREIGN KEY (`prequalificationId`) REFERENCES `prequalifications`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -178,6 +178,12 @@ enum OfferLetterStatus {
   CANCELLED
 }
 
+enum UnderwritingDecisionKind {
+  APPROVE
+  REJECT
+  CONDITIONAL
+}
+
 // =============================================================================
 // USER & AUTH DOMAIN
 // =============================================================================
@@ -316,6 +322,9 @@ model Tenant {
   documentTemplates DocumentTemplate[]
   offerLetters      OfferLetter[]
 
+  // Underwriting
+  underwritingDecisions UnderwritingDecision[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -1218,10 +1227,10 @@ model DocumentTemplate {
   name        String // "Provisional Offer Letter", "Final Offer Letter"
   code        String // PROVISIONAL_OFFER, FINAL_OFFER
   description String?
-  version     Int    @default(1)
+  version     Int     @default(1)
 
   // Template content (Handlebars)
-  htmlTemplate String @db.Text
+  htmlTemplate String  @db.Text
   cssStyles    String? @db.Text
 
   // Merge field definitions for UI
@@ -1242,9 +1251,9 @@ model DocumentTemplate {
 }
 
 model OfferLetter {
-  id         String @id @default(cuid())
+  id         String   @id @default(cuid())
   tenantId   String
-  tenant     Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
   contractId String
   contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
 
@@ -1253,29 +1262,29 @@ model OfferLetter {
   template   DocumentTemplate @relation(fields: [templateId], references: [id])
 
   // Letter details
-  letterNumber String           @unique // OL-XXXXXX
+  letterNumber String            @unique // OL-XXXXXX
   type         OfferLetterType
   status       OfferLetterStatus @default(DRAFT)
 
   // Generated document
-  htmlContent  String?  @db.Text // Rendered HTML
-  pdfUrl       String? // S3 URL of generated PDF
-  pdfKey       String? // S3 key for deletion/access
+  htmlContent String? @db.Text // Rendered HTML
+  pdfUrl      String? // S3 URL of generated PDF
+  pdfKey      String? // S3 key for deletion/access
 
   // Merge data used (snapshot for audit)
   mergeData Json? // All data merged into template
 
   // Signing workflow
-  sentAt      DateTime?
-  viewedAt    DateTime?
-  signedAt    DateTime?
-  signatureIp String?
+  sentAt        DateTime?
+  viewedAt      DateTime?
+  signedAt      DateTime?
+  signatureIp   String?
   signatureData Json? // {method, timestamp, metadata}
 
   // Validity
-  expiresAt   DateTime?
-  expiredAt   DateTime?
-  cancelledAt DateTime?
+  expiresAt    DateTime?
+  expiredAt    DateTime?
+  cancelledAt  DateTime?
   cancelReason String?
 
   // Audit
@@ -1439,6 +1448,9 @@ model Prequalification {
   contractId String?   @unique
   contract   Contract? @relation(fields: [contractId], references: [id])
 
+  // Underwriting decisions for this prequalification
+  underwritingDecisions UnderwritingDecision[]
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
@@ -1449,6 +1461,54 @@ model Prequalification {
   @@map("prequalifications")
 }
 
+// =============================================================================
+// UNDERWRITING DECISION - Automated/manual credit decisions
+// =============================================================================
+// Records each underwriting decision for a prequalification. Multiple decisions
+// may exist if re-evaluation occurs (e.g., after document submission).
+// =============================================================================
+
+model UnderwritingDecision {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Link to prequalification being evaluated
+  prequalificationId String
+  prequalification   Prequalification @relation(fields: [prequalificationId], references: [id], onDelete: Cascade)
+
+  // Decision outcome
+  decision UnderwritingDecisionKind
+
+  // Scoring and rationale
+  score      Float? // Computed risk score (0-100)
+  reasons    Json? // Array of reason codes/messages for decision
+  conditions Json? // Array of conditions for CONDITIONAL decisions
+
+  // Rule engine metadata
+  rulesVersion String? // Version of rules/model used
+  ruleResults  Json? // Detailed rule evaluation results
+
+  // External data references (credit bureau, verifications)
+  externalChecks Json? // { creditBureau: {...}, incomeVerification: {...} }
+
+  // Manual review (if escalated)
+  isManualReview Boolean   @default(false)
+  reviewedBy     String? // Admin who reviewed
+  reviewedAt     DateTime?
+  reviewNotes    String?   @db.Text
+
+  // Audit
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([prequalificationId])
+  @@index([decision])
+  @@index([createdAt])
+  @@map("underwriting_decisions")
+}
+
 // =============================================================================
 // PAYMENT METHOD CHANGE REQUEST - Mid-contract payment method changes
 // =============================================================================