mortctl 0.1.0

package/src/lib/calculations.ts

@@ -0,0 +1,314 @@
+/**
+ * Core mortgage calculations
+ */
+
+import {
+  LtvResult,
+  PmiInputs,
+  PmiResult,
+  LoanScenario,
+  PaymentBreakdown,
+  LoanLimits,
+} from '../types';
+
+/**
+ * 2026 Conforming Loan Limits (estimated)
+ */
+export const LOAN_LIMITS_2026: LoanLimits = {
+  baseline: 766550,      // Standard conforming limit
+  highCost: 1149825,     // High-cost area ceiling (150% of baseline)
+  fhaFloor: 498257,      // FHA floor
+  fhaCeiling: 1149825,   // FHA ceiling (same as high-cost)
+};
+
+/**
+ * High-cost counties (sample - would be comprehensive in production)
+ */
+export const HIGH_COST_COUNTIES: Record<string, number> = {
+  'Los Angeles, CA': 1149825,
+  'San Francisco, CA': 1149825,
+  'New York, NY': 1149825,
+  'Kings, NY': 1149825,
+  'Queens, NY': 1149825,
+  'Bronx, NY': 1149825,
+  'San Diego, CA': 1006250,
+  'Orange, CA': 1149825,
+  'Santa Clara, CA': 1149825,
+  'Alameda, CA': 1149825,
+  'Seattle, WA': 977500,
+  'King, WA': 977500,
+  'Honolulu, HI': 1149825,
+  'Washington, DC': 1149825,
+  'Montgomery, MD': 1149825,
+  'Fairfax, VA': 1149825,
+};
+
+/**
+ * Get conforming loan limit for a county
+ */
+export function getConformingLimit(county?: string, units: number = 1): number {
+  let baseLimit = LOAN_LIMITS_2026.baseline;
+  
+  if (county && HIGH_COST_COUNTIES[county]) {
+    baseLimit = HIGH_COST_COUNTIES[county];
+  }
+
+  // Multi-unit adjustments
+  const unitMultipliers: Record<number, number> = {
+    1: 1,
+    2: 1.28,
+    3: 1.55,
+    4: 1.92,
+  };
+
+  return Math.round(baseLimit * (unitMultipliers[units] || 1));
+}
+
+/**
+ * Calculate monthly P&I payment
+ */
+export function calculateMonthlyPayment(
+  principal: number,
+  annualRate: number,
+  termYears: number
+): number {
+  const monthlyRate = annualRate / 100 / 12;
+  const numPayments = termYears * 12;
+
+  if (monthlyRate === 0) {
+    return principal / numPayments;
+  }
+
+  const payment = principal * 
+    (monthlyRate * Math.pow(1 + monthlyRate, numPayments)) /
+    (Math.pow(1 + monthlyRate, numPayments) - 1);
+
+  return Math.round(payment * 100) / 100;
+}
+
+/**
+ * Calculate LTV/CLTV/HCLTV
+ */
+export function calculateLtv(
+  propertyValue: number,
+  loanAmount: number,
+  secondLien: number = 0,
+  heloc: number = 0
+): LtvResult {
+  const ltv = (loanAmount / propertyValue) * 100;
+  const cltv = ((loanAmount + secondLien) / propertyValue) * 100;
+  const hcltv = ((loanAmount + secondLien + heloc) / propertyValue) * 100;
+
+  const pmiRequired = ltv > 80;
+
+  return {
+    ltv: Math.round(ltv * 100) / 100,
+    cltv: Math.round(cltv * 100) / 100,
+    hcltv: Math.round(hcltv * 100) / 100,
+    pmiRequired,
+    pmiRemovalLtv: pmiRequired ? 78 : undefined,
+  };
+}
+
+/**
+ * PMI rate lookup table (approximate)
+ * Format: [LTV range][Credit score range] = annual rate %
+ */
+const PMI_RATES: Record<string, Record<string, number>> = {
+  '95-97': { '760+': 0.55, '740-759': 0.65, '720-739': 0.78, '700-719': 0.95, '680-699': 1.15, '<680': 1.40 },
+  '90-95': { '760+': 0.38, '740-759': 0.45, '720-739': 0.55, '700-719': 0.70, '680-699': 0.90, '<680': 1.15 },
+  '85-90': { '760+': 0.25, '740-759': 0.30, '720-739': 0.38, '700-719': 0.50, '680-699': 0.65, '<680': 0.85 },
+  '80-85': { '760+': 0.15, '740-759': 0.18, '720-739': 0.23, '700-719': 0.30, '680-699': 0.40, '<680': 0.55 },
+};
+
+/**
+ * Get credit score bracket for PMI lookup
+ */
+function getCreditBracket(score: number): string {
+  if (score >= 760) return '760+';
+  if (score >= 740) return '740-759';
+  if (score >= 720) return '720-739';
+  if (score >= 700) return '700-719';
+  if (score >= 680) return '680-699';
+  return '<680';
+}
+
+/**
+ * Get LTV bracket for PMI lookup
+ */
+function getLtvBracket(ltv: number): string {
+  if (ltv > 95) return '95-97';
+  if (ltv > 90) return '90-95';
+  if (ltv > 85) return '85-90';
+  if (ltv > 80) return '80-85';
+  return '80-85'; // Below 80 - no PMI normally
+}
+
+/**
+ * Calculate PMI
+ */
+export function calculatePmi(inputs: PmiInputs): PmiResult {
+  const { ltv, creditScore, loanAmount, termYears = 30 } = inputs;
+
+  // No PMI below 80% LTV
+  if (ltv <= 80) {
+    return {
+      required: false,
+      monthlyAmount: 0,
+      annualAmount: 0,
+      ratePercent: 0,
+      cancellationLtv: 80,
+    };
+  }
+
+  const ltvBracket = getLtvBracket(ltv);
+  const creditBracket = getCreditBracket(creditScore);
+  
+  const ratePercent = PMI_RATES[ltvBracket]?.[creditBracket] || 0.85;
+  const annualAmount = (loanAmount * ratePercent) / 100;
+  const monthlyAmount = annualAmount / 12;
+
+  // Estimate months to reach 78% LTV (automatic cancellation)
+  // Simplified - assumes 30-year at average rate
+  const avgRate = 6.5; // Approximate
+  const monthlyPayment = calculateMonthlyPayment(loanAmount, avgRate, termYears);
+  
+  // Very rough estimate of months to 78% LTV
+  const targetLoanAmount = loanAmount * (78 / ltv);
+  const reductionNeeded = loanAmount - targetLoanAmount;
+  
+  // Approximate based on early amortization (mostly interest)
+  const avgMonthlyPrincipal = monthlyPayment * 0.25; // Rough estimate
+  const monthsToCancel = Math.ceil(reductionNeeded / avgMonthlyPrincipal);
+
+  return {
+    required: true,
+    monthlyAmount: Math.round(monthlyAmount * 100) / 100,
+    annualAmount: Math.round(annualAmount * 100) / 100,
+    ratePercent,
+    cancellationLtv: 78,
+    monthsToCancel,
+  };
+}
+
+/**
+ * Calculate full payment breakdown
+ */
+export function calculatePaymentBreakdown(scenario: LoanScenario): PaymentBreakdown {
+  const principalAndInterest = calculateMonthlyPayment(
+    scenario.loanAmount,
+    scenario.interestRate,
+    scenario.termYears
+  );
+
+  const propertyTaxes = (scenario.propertyTaxes || scenario.propertyValue * 0.0125) / 12;
+  const homeownersInsurance = (scenario.homeownersInsurance || scenario.propertyValue * 0.0035) / 12;
+  const hoaDues = scenario.hoaDues || 0;
+
+  // Calculate PMI if needed
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+  const pmiResult = calculatePmi({
+    ltv,
+    creditScore: scenario.creditScore,
+    loanAmount: scenario.loanAmount,
+    termYears: scenario.termYears,
+  });
+
+  const totalPayment = principalAndInterest + propertyTaxes + homeownersInsurance + 
+    pmiResult.monthlyAmount + hoaDues;
+
+  return {
+    principalAndInterest: Math.round(principalAndInterest * 100) / 100,
+    propertyTaxes: Math.round(propertyTaxes * 100) / 100,
+    homeownersInsurance: Math.round(homeownersInsurance * 100) / 100,
+    mortgageInsurance: pmiResult.monthlyAmount,
+    hoaDues,
+    totalPayment: Math.round(totalPayment * 100) / 100,
+  };
+}
+
+/**
+ * Calculate FHA MIP (Mortgage Insurance Premium)
+ */
+export function calculateFhaMip(
+  loanAmount: number,
+  ltv: number,
+  termYears: number
+): { upfront: number; monthly: number; annualRate: number } {
+  // Upfront MIP: 1.75% of loan amount
+  const upfront = loanAmount * 0.0175;
+
+  // Annual MIP rates (as of 2024, may change)
+  // For loans > 15 years and LTV > 90%: 0.85%
+  // For loans > 15 years and LTV <= 90%: 0.80%
+  // For loans <= 15 years: 0.45% to 0.70% depending on LTV
+  let annualRate: number;
+  
+  if (termYears > 15) {
+    annualRate = ltv > 90 ? 0.85 : 0.80;
+  } else {
+    annualRate = ltv > 90 ? 0.70 : 0.45;
+  }
+
+  const monthly = (loanAmount * annualRate / 100) / 12;
+
+  return {
+    upfront: Math.round(upfront * 100) / 100,
+    monthly: Math.round(monthly * 100) / 100,
+    annualRate,
+  };
+}
+
+/**
+ * Calculate VA Funding Fee
+ */
+export function calculateVaFundingFee(
+  loanAmount: number,
+  downPaymentPercent: number,
+  firstTimeUse: boolean,
+  reservist: boolean = false
+): number {
+  // VA Funding Fee rates (2024)
+  // First use, no down: 2.15% (2.40% for reserves/NG)
+  // First use, 5-10% down: 1.50% (1.75% for reserves/NG)
+  // First use, 10%+ down: 1.25% (1.50% for reserves/NG)
+  // Subsequent use, no down: 3.30%
+  // Subsequent use, 5-10% down: 1.50%
+  // Subsequent use, 10%+ down: 1.25%
+
+  let rate: number;
+  
+  if (firstTimeUse) {
+    if (downPaymentPercent >= 10) {
+      rate = reservist ? 1.50 : 1.25;
+    } else if (downPaymentPercent >= 5) {
+      rate = reservist ? 1.75 : 1.50;
+    } else {
+      rate = reservist ? 2.40 : 2.15;
+    }
+  } else {
+    if (downPaymentPercent >= 10) {
+      rate = 1.25;
+    } else if (downPaymentPercent >= 5) {
+      rate = 1.50;
+    } else {
+      rate = 3.30;
+    }
+  }
+
+  return Math.round((loanAmount * rate / 100) * 100) / 100;
+}
+
+/**
+ * Calculate USDA Guarantee Fee
+ */
+export function calculateUsdaFee(loanAmount: number): { upfront: number; annual: number } {
+  // USDA fees (2024)
+  // Upfront: 1.0%
+  // Annual: 0.35%
+  
+  return {
+    upfront: Math.round((loanAmount * 0.01) * 100) / 100,
+    annual: Math.round((loanAmount * 0.0035) * 100) / 100,
+  };
+}

package/src/lib/eligibility.ts

@@ -0,0 +1,343 @@
+/**
+ * Loan program eligibility checking
+ */
+
+import {
+  LoanScenario,
+  EligibilityResult,
+  LoanProgram,
+  OccupancyType,
+} from '../types';
+import { getConformingLimit, LOAN_LIMITS_2026 } from './calculations';
+
+/**
+ * Check conventional loan eligibility
+ */
+export function checkConventionalEligibility(scenario: LoanScenario): EligibilityResult {
+  const reasons: string[] = [];
+  const warnings: string[] = [];
+  let eligible = true;
+
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+  const conformingLimit = getConformingLimit(
+    scenario.county ? `${scenario.county}, ${scenario.state}` : undefined,
+    scenario.units || 1
+  );
+
+  // Credit score check
+  if (scenario.creditScore < 620) {
+    eligible = false;
+    reasons.push('Credit score below 620 minimum');
+  } else if (scenario.creditScore < 680) {
+    warnings.push('Credit score below 680 may result in pricing adjustments');
+  }
+
+  // LTV check
+  if (ltv > 97) {
+    eligible = false;
+    reasons.push('LTV exceeds 97% maximum');
+  } else if (ltv > 95) {
+    warnings.push('LTV >95% requires additional eligibility criteria');
+  }
+
+  // Loan amount check (conforming vs jumbo)
+  if (scenario.loanAmount > conformingLimit) {
+    warnings.push(`Loan exceeds conforming limit ($${conformingLimit.toLocaleString()}), jumbo pricing applies`);
+  }
+
+  // Occupancy check for high LTV
+  if (ltv > 90 && scenario.occupancy !== 'primary') {
+    eligible = false;
+    reasons.push('LTV >90% only available for primary residence');
+  }
+
+  // Investment property restrictions
+  if (scenario.occupancy === 'investment') {
+    if (ltv > 85) {
+      eligible = false;
+      reasons.push('Investment property maximum LTV is 85%');
+    }
+    if (scenario.creditScore < 680) {
+      eligible = false;
+      reasons.push('Investment property requires 680+ credit score');
+    }
+  }
+
+  // Property type restrictions
+  if (scenario.propertyType === 'manufactured' && ltv > 95) {
+    eligible = false;
+    reasons.push('Manufactured homes limited to 95% LTV');
+  }
+
+  // Calculate min down payment
+  let minDownPct = scenario.occupancy === 'investment' ? 15 : 3;
+  if (scenario.occupancy === 'second-home') minDownPct = 10;
+  const minDownPayment = scenario.propertyValue * (minDownPct / 100);
+
+  return {
+    program: 'conventional',
+    eligible,
+    reasons: reasons.length > 0 ? reasons : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    maxLoanAmount: conformingLimit,
+    minDownPayment,
+    rateAdjustment: scenario.creditScore < 740 ? 0.25 : 0,
+  };
+}
+
+/**
+ * Check FHA loan eligibility
+ */
+export function checkFhaEligibility(scenario: LoanScenario): EligibilityResult {
+  const reasons: string[] = [];
+  const warnings: string[] = [];
+  let eligible = true;
+
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+  const fhaLimit = LOAN_LIMITS_2026.fhaCeiling; // Would be county-specific in production
+
+  // Credit score check
+  if (scenario.creditScore < 500) {
+    eligible = false;
+    reasons.push('Credit score below 500 minimum');
+  } else if (scenario.creditScore < 580) {
+    if (ltv > 90) {
+      eligible = false;
+      reasons.push('Credit score 500-579 requires 10% down payment (90% LTV max)');
+    }
+    warnings.push('Credit score 500-579 requires manual underwriting');
+  }
+
+  // LTV check
+  if (scenario.creditScore >= 580 && ltv > 96.5) {
+    eligible = false;
+    reasons.push('FHA maximum LTV is 96.5%');
+  }
+
+  // Occupancy - FHA is owner-occupied only
+  if (scenario.occupancy !== 'primary') {
+    eligible = false;
+    reasons.push('FHA loans require owner occupancy');
+  }
+
+  // Loan amount check
+  if (scenario.loanAmount > fhaLimit) {
+    eligible = false;
+    reasons.push(`Loan exceeds FHA limit ($${fhaLimit.toLocaleString()})`);
+  }
+
+  // Property type restrictions
+  if (scenario.propertyType === 'coop') {
+    warnings.push('Co-ops require FHA approval');
+  }
+
+  // Calculate min down payment
+  const minDownPct = scenario.creditScore >= 580 ? 3.5 : 10;
+  const minDownPayment = scenario.propertyValue * (minDownPct / 100);
+
+  return {
+    program: 'fha',
+    eligible,
+    reasons: reasons.length > 0 ? reasons : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    maxLoanAmount: fhaLimit,
+    minDownPayment,
+    rateAdjustment: 0, // FHA rates are generally competitive
+  };
+}
+
+/**
+ * Check VA loan eligibility
+ */
+export function checkVaEligibility(scenario: LoanScenario): EligibilityResult {
+  const reasons: string[] = [];
+  const warnings: string[] = [];
+  let eligible = true;
+
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+
+  // Veteran status required
+  if (!scenario.veteran) {
+    eligible = false;
+    reasons.push('VA loans require veteran/military eligibility');
+  }
+
+  // Credit score - VA has no official minimum but lenders typically require 580-620
+  if (scenario.creditScore < 580) {
+    warnings.push('Most VA lenders require 580+ credit score');
+  }
+
+  // LTV - VA allows 100% financing
+  if (ltv > 100) {
+    eligible = false;
+    reasons.push('VA maximum LTV is 100%');
+  }
+
+  // Occupancy - VA is owner-occupied only
+  if (scenario.occupancy !== 'primary') {
+    eligible = false;
+    reasons.push('VA loans require owner occupancy');
+  }
+
+  // No loan limit for full entitlement (post-2020)
+  // But there are limits for partial entitlement
+
+  // Property type restrictions
+  if (scenario.propertyType === 'coop') {
+    eligible = false;
+    reasons.push('VA does not allow co-op properties');
+  }
+
+  return {
+    program: 'va',
+    eligible,
+    reasons: reasons.length > 0 ? reasons : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    minDownPayment: 0, // VA allows 0% down
+    rateAdjustment: -0.25, // VA rates typically lower
+  };
+}
+
+/**
+ * Check USDA loan eligibility
+ */
+export function checkUsdaEligibility(scenario: LoanScenario): EligibilityResult {
+  const reasons: string[] = [];
+  const warnings: string[] = [];
+  let eligible = true;
+
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+
+  // Rural location required
+  if (!scenario.rural) {
+    eligible = false;
+    reasons.push('USDA loans require rural/eligible suburban location');
+  }
+
+  // Credit score
+  if (scenario.creditScore < 640) {
+    warnings.push('Credit score below 640 requires manual underwriting');
+  }
+
+  // LTV - USDA allows 100% financing
+  if (ltv > 100) {
+    eligible = false;
+    reasons.push('USDA maximum LTV is 100%');
+  }
+
+  // Occupancy - owner-occupied only
+  if (scenario.occupancy !== 'primary') {
+    eligible = false;
+    reasons.push('USDA loans require owner occupancy');
+  }
+
+  // Property type - single family only
+  if (scenario.units && scenario.units > 1) {
+    eligible = false;
+    reasons.push('USDA loans are for single-family homes only');
+  }
+
+  // Income limits would apply (not modeled here)
+  warnings.push('USDA has household income limits - verify eligibility');
+
+  return {
+    program: 'usda',
+    eligible,
+    reasons: reasons.length > 0 ? reasons : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    minDownPayment: 0,
+    rateAdjustment: 0,
+  };
+}
+
+/**
+ * Check jumbo loan eligibility
+ */
+export function checkJumboEligibility(scenario: LoanScenario): EligibilityResult {
+  const reasons: string[] = [];
+  const warnings: string[] = [];
+  let eligible = true;
+
+  const ltv = (scenario.loanAmount / scenario.propertyValue) * 100;
+  const conformingLimit = getConformingLimit(
+    scenario.county ? `${scenario.county}, ${scenario.state}` : undefined,
+    scenario.units || 1
+  );
+
+  // Check if actually jumbo
+  if (scenario.loanAmount <= conformingLimit) {
+    eligible = false;
+    reasons.push('Loan amount is within conforming limits - use conventional');
+  }
+
+  // Credit score - jumbo typically requires higher scores
+  if (scenario.creditScore < 700) {
+    eligible = false;
+    reasons.push('Jumbo loans typically require 700+ credit score');
+  } else if (scenario.creditScore < 720) {
+    warnings.push('Credit score below 720 may limit options');
+  }
+
+  // LTV - jumbo typically more restrictive
+  const maxLtv = scenario.occupancy === 'primary' ? 90 : 80;
+  if (ltv > maxLtv) {
+    eligible = false;
+    reasons.push(`Jumbo maximum LTV is ${maxLtv}% for ${scenario.occupancy}`);
+  }
+
+  // Reserves typically required
+  warnings.push('Jumbo loans typically require 6-12 months reserves');
+
+  // Min down payment
+  const minDownPct = scenario.occupancy === 'primary' ? 10 : 20;
+  const minDownPayment = scenario.propertyValue * (minDownPct / 100);
+
+  return {
+    program: 'jumbo',
+    eligible,
+    reasons: reasons.length > 0 ? reasons : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    minDownPayment,
+    rateAdjustment: 0.25, // Jumbo typically slightly higher
+  };
+}
+
+/**
+ * Check all program eligibility
+ */
+export function checkAllEligibility(scenario: LoanScenario): EligibilityResult[] {
+  return [
+    checkConventionalEligibility(scenario),
+    checkFhaEligibility(scenario),
+    checkVaEligibility(scenario),
+    checkUsdaEligibility(scenario),
+    checkJumboEligibility(scenario),
+  ];
+}
+
+/**
+ * Find best recommended program
+ */
+export function findBestProgram(
+  eligibility: EligibilityResult[]
+): LoanProgram | undefined {
+  const eligible = eligibility.filter(e => e.eligible);
+  if (eligible.length === 0) return undefined;
+
+  // Priority order: VA (if eligible), then lowest down payment, then best rate
+  const va = eligible.find(e => e.program === 'va');
+  if (va) return 'va';
+
+  const usda = eligible.find(e => e.program === 'usda');
+  if (usda) return 'usda';
+
+  // Sort by min down payment, then rate adjustment
+  eligible.sort((a, b) => {
+    const downA = a.minDownPayment || 0;
+    const downB = b.minDownPayment || 0;
+    if (downA !== downB) return downA - downB;
+    return (a.rateAdjustment || 0) - (b.rateAdjustment || 0);
+  });
+
+  return eligible[0].program;
+}