@wirms/calculator-engine 1.0.1 → 2.0.0

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+type TxType = 'purchase' | 'rateTermRefi' | 'cashOutRefi';
+type Lang = 'en' | 'es';
 interface DSCRInput {
     /** Purchase price or current value */
     purchasePrice: number;
@@ -26,6 +28,28 @@ interface DSCRInput {
     /** Whether this is an interest-only loan */
     interestOnly?: boolean;
 }
+interface DSCRInputFull {
+    /** Monthly gross rental income */
+    monthlyRent: number;
+    /** Target loan amount (not derived from price × LTV) */
+    loanAmount: number;
+    /** Annual interest rate as percentage (e.g. 7.5 for 7.5%) */
+    interestRate: number;
+    /** Loan term in years (15–40) */
+    loanTerm: number;
+    /** Annual property taxes */
+    annualTaxes: number;
+    /** Annual hazard insurance */
+    annualInsurance: number;
+    /** Monthly HOA dues */
+    monthlyHOA: number;
+    /** As-is appraised value */
+    appraisedValue: number;
+    /** FICO credit score (580–800) */
+    creditScore: number;
+    /** Transaction type */
+    transactionType: TxType;
+}
 interface DSCRResult {
     dscr: number;
     loanAmount: number;
@@ -39,18 +63,121 @@ interface DSCRResult {
     /** DSCR tier label */
     tier: 'excellent' | 'good' | 'acceptable' | 'weak' | 'negative';
 }
+interface DSCRResultFull {
+    /** DSCR ratio (rent / PITIA) */
+    dscr: number;
+    /** Monthly principal & interest */
+    pi: number;
+    /** Monthly taxes (annualTaxes / 12) */
+    taxes: number;
+    /** Monthly insurance (annualInsurance / 12) */
+    insurance: number;
+    /** Total PITIA (pi + taxes + insurance + hoa) */
+    pitia: number;
+    /** Net cash flow (rent - pitia) */
+    cashFlow: number;
+    /** Max LTV % for user's current scenario (DSCR-based) */
+    userLtvPct: number | null;
+    /** Max LTV % at DSCR ≥ 1.0 (algebraic solver) */
+    dscrLtvPct: number | null;
+    /** Max loan at DSCR = 1.0, capped by LTV × appraisal */
+    dscrMaxLoan: number | null;
+    /** Difference: dscrMaxLoan - loanAmount */
+    dscrLoanDelta: number | null;
+    /** Monthly rent needed to achieve DSCR = 1.0 at current loan */
+    rentForDscr1: number;
+    /** Rent gap: rentForDscr1 - monthlyRent */
+    rentGap: number;
+    /** Alt qualifying max LTV % (85/85/80) */
+    altLtvPct: number;
+    /** Alt qualifying max loan (appraisedValue × altLtvPct) */
+    altMaxLoan: number;
+    /** Difference: altMaxLoan - loanAmount */
+    altLoanDelta: number;
+    /** Leverage gap: altMaxLoan - dscrMaxLoan (or altMaxLoan if no DSCR program) */
+    leverageGap: number;
+}
 interface SolverResult {
     value: number;
     resultingDSCR: number;
     feasible: boolean;
 }
+interface MaxDscrLoanResult {
+    maxLoan: number;
+    ltvPct: number;
+    binding: 'dscr' | 'ltv';
+}
+interface CreditInsight {
+    message: string;
+    type: 'boost' | 'info' | 'warning';
+}
+interface AltStrategyMessages {
+    subtitle: string;
+    planBNote: string;
+    planCNote: string;
+}
 
 declare function clamp(value: number, min: number, max: number): number;
 declare function formatCurrency(value: number, decimals?: number): string;
+declare function formatCompact(n: number): string;
 declare function calculateDSCR(input: DSCRInput): DSCRResult;
-/** Find max loan amount that achieves targetDSCR */
+/**
+ * Full DSCR calculator matching lukeroasst.com.
+ * DSCR = rent / PITIA. Includes LTV matrix lookups,
+ * algebraic max-loan solver, alt qualifying comparison,
+ * and rent gap analysis.
+ */
+declare function calculateDSCRFull(input: DSCRInputFull): DSCRResultFull;
+/** Find max loan amount that achieves targetDSCR (v1 NOI-based) */
 declare function solveMaxLoan(input: Omit<DSCRInput, 'ltv'>, targetDSCR: number): SolverResult;
-/** Find minimum monthly rent to achieve targetDSCR */
+/** Find minimum monthly rent to achieve targetDSCR (v1 NOI-based) */
 declare function solveMinRent(input: DSCRInput, targetDSCR: number): SolverResult;
 
-export { type DSCRInput, type DSCRResult, type SolverResult, calculateDSCR, clamp, formatCurrency, solveMaxLoan, solveMinRent };
+/**
+ * Real lender LTV matrix: DSCR x FICO x Loan Amount x TxType -> Max LTV
+ *
+ * Sources: HomeXpress (verified S49), theLender (#theNONI), Acra Lending,
+ * ARC Homes (Edge), American Heritage, HomeBridge.
+ *
+ * HARD CAPS: 85% purchase, 85% R/T, 80% cash-out. No exceptions.
+ */
+declare function getMaxLtv(dscr: number, fico: number, loanAmt: number, txType: TxType): number | null;
+/**
+ * Alternative qualifying max LTV (Asset Depletion, Bank Statement, P&L).
+ * Hard caps: 85% purchase, 85% rate/term, 80% cash-out.
+ */
+declare function getAltLtv(txType: TxType): number;
+
+/**
+ * Algebraic solver: find max loan where DSCR = 1.0, capped by LTV x appraised.
+ *
+ * DSCR = rent / PITIA. PITIA = PI + taxes + insurance + HOA.
+ * PI = loan x paymentFactor.
+ * So: loan = (rent/targetDscr - fixedExpenses) / paymentFactor.
+ * Result is capped by LTV x appraisedValue (secondary constraint, rarely binding).
+ *
+ * @param monthlyRent - Gross monthly rental income
+ * @param interestRate - Annual rate as percentage (e.g. 7.5)
+ * @param loanTerm - Loan term in years
+ * @param annualTaxes - Annual property taxes
+ * @param annualInsurance - Annual hazard insurance
+ * @param monthlyHOA - Monthly HOA dues
+ * @param appraisedValue - As-is appraised value
+ * @param fico - Borrower FICO score
+ * @param txType - Transaction type
+ */
+declare function getMaxDscrLoan(monthlyRent: number, interestRate: number, loanTerm: number, annualTaxes: number, annualInsurance: number, monthlyHOA: number, appraisedValue: number, fico: number, txType: TxType): MaxDscrLoanResult | null;
+
+/**
+ * FICO-aware credit insight messaging.
+ * Returns a contextual message based on the borrower's score relative
+ * to the next LTV tier breakpoint.
+ */
+declare function getCreditInsight(fico: number, dscr: number, loanAmt: number, txType: TxType, currentLtv: number | null, lang: Lang): CreditInsight | null;
+/**
+ * FICO-aware alternative strategy messaging for Plan B (Asset Depletion)
+ * and Plan C (Bank Statement / P&L).
+ */
+declare function getAltStrategyMessage(fico: number, _dscr: number, txType: TxType, lang: Lang): AltStrategyMessages;
+
+export { type AltStrategyMessages, type CreditInsight, type DSCRInput, type DSCRInputFull, type DSCRResult, type DSCRResultFull, type Lang, type MaxDscrLoanResult, type SolverResult, type TxType, calculateDSCR, calculateDSCRFull, clamp, formatCompact, formatCurrency, getAltLtv, getAltStrategyMessage, getCreditInsight, getMaxDscrLoan, getMaxLtv, solveMaxLoan, solveMinRent };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+type TxType = 'purchase' | 'rateTermRefi' | 'cashOutRefi';
+type Lang = 'en' | 'es';
 interface DSCRInput {
     /** Purchase price or current value */
     purchasePrice: number;
@@ -26,6 +28,28 @@ interface DSCRInput {
     /** Whether this is an interest-only loan */
     interestOnly?: boolean;
 }
+interface DSCRInputFull {
+    /** Monthly gross rental income */
+    monthlyRent: number;
+    /** Target loan amount (not derived from price × LTV) */
+    loanAmount: number;
+    /** Annual interest rate as percentage (e.g. 7.5 for 7.5%) */
+    interestRate: number;
+    /** Loan term in years (15–40) */
+    loanTerm: number;
+    /** Annual property taxes */
+    annualTaxes: number;
+    /** Annual hazard insurance */
+    annualInsurance: number;
+    /** Monthly HOA dues */
+    monthlyHOA: number;
+    /** As-is appraised value */
+    appraisedValue: number;
+    /** FICO credit score (580–800) */
+    creditScore: number;
+    /** Transaction type */
+    transactionType: TxType;
+}
 interface DSCRResult {
     dscr: number;
     loanAmount: number;
@@ -39,18 +63,121 @@ interface DSCRResult {
     /** DSCR tier label */
     tier: 'excellent' | 'good' | 'acceptable' | 'weak' | 'negative';
 }
+interface DSCRResultFull {
+    /** DSCR ratio (rent / PITIA) */
+    dscr: number;
+    /** Monthly principal & interest */
+    pi: number;
+    /** Monthly taxes (annualTaxes / 12) */
+    taxes: number;
+    /** Monthly insurance (annualInsurance / 12) */
+    insurance: number;
+    /** Total PITIA (pi + taxes + insurance + hoa) */
+    pitia: number;
+    /** Net cash flow (rent - pitia) */
+    cashFlow: number;
+    /** Max LTV % for user's current scenario (DSCR-based) */
+    userLtvPct: number | null;
+    /** Max LTV % at DSCR ≥ 1.0 (algebraic solver) */
+    dscrLtvPct: number | null;
+    /** Max loan at DSCR = 1.0, capped by LTV × appraisal */
+    dscrMaxLoan: number | null;
+    /** Difference: dscrMaxLoan - loanAmount */
+    dscrLoanDelta: number | null;
+    /** Monthly rent needed to achieve DSCR = 1.0 at current loan */
+    rentForDscr1: number;
+    /** Rent gap: rentForDscr1 - monthlyRent */
+    rentGap: number;
+    /** Alt qualifying max LTV % (85/85/80) */
+    altLtvPct: number;
+    /** Alt qualifying max loan (appraisedValue × altLtvPct) */
+    altMaxLoan: number;
+    /** Difference: altMaxLoan - loanAmount */
+    altLoanDelta: number;
+    /** Leverage gap: altMaxLoan - dscrMaxLoan (or altMaxLoan if no DSCR program) */
+    leverageGap: number;
+}
 interface SolverResult {
     value: number;
     resultingDSCR: number;
     feasible: boolean;
 }
+interface MaxDscrLoanResult {
+    maxLoan: number;
+    ltvPct: number;
+    binding: 'dscr' | 'ltv';
+}
+interface CreditInsight {
+    message: string;
+    type: 'boost' | 'info' | 'warning';
+}
+interface AltStrategyMessages {
+    subtitle: string;
+    planBNote: string;
+    planCNote: string;
+}
 
 declare function clamp(value: number, min: number, max: number): number;
 declare function formatCurrency(value: number, decimals?: number): string;
+declare function formatCompact(n: number): string;
 declare function calculateDSCR(input: DSCRInput): DSCRResult;
-/** Find max loan amount that achieves targetDSCR */
+/**
+ * Full DSCR calculator matching lukeroasst.com.
+ * DSCR = rent / PITIA. Includes LTV matrix lookups,
+ * algebraic max-loan solver, alt qualifying comparison,
+ * and rent gap analysis.
+ */
+declare function calculateDSCRFull(input: DSCRInputFull): DSCRResultFull;
+/** Find max loan amount that achieves targetDSCR (v1 NOI-based) */
 declare function solveMaxLoan(input: Omit<DSCRInput, 'ltv'>, targetDSCR: number): SolverResult;
-/** Find minimum monthly rent to achieve targetDSCR */
+/** Find minimum monthly rent to achieve targetDSCR (v1 NOI-based) */
 declare function solveMinRent(input: DSCRInput, targetDSCR: number): SolverResult;
 
-export { type DSCRInput, type DSCRResult, type SolverResult, calculateDSCR, clamp, formatCurrency, solveMaxLoan, solveMinRent };
+/**
+ * Real lender LTV matrix: DSCR x FICO x Loan Amount x TxType -> Max LTV
+ *
+ * Sources: HomeXpress (verified S49), theLender (#theNONI), Acra Lending,
+ * ARC Homes (Edge), American Heritage, HomeBridge.
+ *
+ * HARD CAPS: 85% purchase, 85% R/T, 80% cash-out. No exceptions.
+ */
+declare function getMaxLtv(dscr: number, fico: number, loanAmt: number, txType: TxType): number | null;
+/**
+ * Alternative qualifying max LTV (Asset Depletion, Bank Statement, P&L).
+ * Hard caps: 85% purchase, 85% rate/term, 80% cash-out.
+ */
+declare function getAltLtv(txType: TxType): number;
+
+/**
+ * Algebraic solver: find max loan where DSCR = 1.0, capped by LTV x appraised.
+ *
+ * DSCR = rent / PITIA. PITIA = PI + taxes + insurance + HOA.
+ * PI = loan x paymentFactor.
+ * So: loan = (rent/targetDscr - fixedExpenses) / paymentFactor.
+ * Result is capped by LTV x appraisedValue (secondary constraint, rarely binding).
+ *
+ * @param monthlyRent - Gross monthly rental income
+ * @param interestRate - Annual rate as percentage (e.g. 7.5)
+ * @param loanTerm - Loan term in years
+ * @param annualTaxes - Annual property taxes
+ * @param annualInsurance - Annual hazard insurance
+ * @param monthlyHOA - Monthly HOA dues
+ * @param appraisedValue - As-is appraised value
+ * @param fico - Borrower FICO score
+ * @param txType - Transaction type
+ */
+declare function getMaxDscrLoan(monthlyRent: number, interestRate: number, loanTerm: number, annualTaxes: number, annualInsurance: number, monthlyHOA: number, appraisedValue: number, fico: number, txType: TxType): MaxDscrLoanResult | null;
+
+/**
+ * FICO-aware credit insight messaging.
+ * Returns a contextual message based on the borrower's score relative
+ * to the next LTV tier breakpoint.
+ */
+declare function getCreditInsight(fico: number, dscr: number, loanAmt: number, txType: TxType, currentLtv: number | null, lang: Lang): CreditInsight | null;
+/**
+ * FICO-aware alternative strategy messaging for Plan B (Asset Depletion)
+ * and Plan C (Bank Statement / P&L).
+ */
+declare function getAltStrategyMessage(fico: number, _dscr: number, txType: TxType, lang: Lang): AltStrategyMessages;
+
+export { type AltStrategyMessages, type CreditInsight, type DSCRInput, type DSCRInputFull, type DSCRResult, type DSCRResultFull, type Lang, type MaxDscrLoanResult, type SolverResult, type TxType, calculateDSCR, calculateDSCRFull, clamp, formatCompact, formatCurrency, getAltLtv, getAltStrategyMessage, getCreditInsight, getMaxDscrLoan, getMaxLtv, solveMaxLoan, solveMinRent };

package/dist/index.js

@@ -21,13 +21,119 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   calculateDSCR: () => calculateDSCR,
+  calculateDSCRFull: () => calculateDSCRFull,
   clamp: () => clamp,
+  formatCompact: () => formatCompact,
   formatCurrency: () => formatCurrency,
+  getAltLtv: () => getAltLtv,
+  getAltStrategyMessage: () => getAltStrategyMessage,
+  getCreditInsight: () => getCreditInsight,
+  getMaxDscrLoan: () => getMaxDscrLoan,
+  getMaxLtv: () => getMaxLtv,
   solveMaxLoan: () => solveMaxLoan,
   solveMinRent: () => solveMinRent
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/dscr/ltv.ts
+function getMaxLtv(dscr, fico, loanAmt, txType) {
+  const pick = (p, rt, co) => {
+    if (txType === "purchase") return p;
+    if (txType === "rateTermRefi") return rt;
+    return co;
+  };
+  if (dscr >= 1) {
+    if (fico >= 720) {
+      if (loanAmt <= 15e5) return pick(85, 85, 80);
+      if (loanAmt <= 2e6) return pick(75, 75, 70);
+      if (loanAmt <= 3e6) return pick(70, 70, 65);
+      if (loanAmt <= 35e5) return pick(65, 65, 60);
+      return pick(60, 60, 55);
+    }
+    if (fico >= 700) {
+      if (loanAmt <= 15e5) return pick(80, 80, 75);
+      if (loanAmt <= 2e6) return pick(75, 75, 70);
+      if (loanAmt <= 3e6) return pick(70, 70, 65);
+      return pick(65, 65, 60);
+    }
+    if (fico >= 680) {
+      if (loanAmt <= 15e5) return pick(75, 75, 75);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      if (loanAmt <= 3e6) return pick(65, 65, 60);
+      return null;
+    }
+    if (fico >= 660) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      if (loanAmt <= 3e6) return pick(65, 65, 60);
+      return null;
+    }
+    if (fico >= 640) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      return null;
+    }
+    if (fico >= 620) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      return null;
+    }
+    if (fico >= 600 && loanAmt <= 15e5) return pick(60, 60, null);
+    return null;
+  }
+  if (dscr >= 0.75) {
+    if (fico >= 720) {
+      if (loanAmt <= 15e5) return pick(75, 75, 70);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      return null;
+    }
+    if (fico >= 700) {
+      if (loanAmt <= 15e5) return pick(75, 70, 70);
+      return null;
+    }
+    if (fico >= 660) {
+      if (loanAmt <= 15e5) return pick(70, 70, 65);
+      return null;
+    }
+    if (fico >= 640) {
+      if (loanAmt <= 1e6) return pick(65, 65, 60);
+      return null;
+    }
+    return null;
+  }
+  if (fico >= 700) {
+    if (loanAmt <= 1e6) return pick(65, 65, 60);
+    if (loanAmt <= 15e5) return pick(60, 60, null);
+    return null;
+  }
+  if (fico >= 660) {
+    if (loanAmt <= 1e6) return pick(60, 60, null);
+    return null;
+  }
+  return null;
+}
+function getAltLtv(txType) {
+  if (txType === "purchase") return 85;
+  if (txType === "rateTermRefi") return 85;
+  return 80;
+}
+
+// src/dscr/solvers.ts
+function getMaxDscrLoan(monthlyRent, interestRate, loanTerm, annualTaxes, annualInsurance, monthlyHOA, appraisedValue, fico, txType) {
+  const monthlyRate = interestRate / 100 / 12;
+  const n = loanTerm * 12;
+  const fixedExpenses = annualTaxes / 12 + annualInsurance / 12 + monthlyHOA;
+  const paymentFactor = monthlyRate > 0 ? monthlyRate * Math.pow(1 + monthlyRate, n) / (Math.pow(1 + monthlyRate, n) - 1) : 1 / n;
+  const targetPi = monthlyRent / 1 - fixedExpenses;
+  if (targetPi <= 0) return null;
+  const maxLoanAtDscr1 = Math.floor(targetPi / paymentFactor);
+  const ltvPct = getMaxLtv(1, fico, maxLoanAtDscr1, txType);
+  if (ltvPct === null) return null;
+  const ltvCap = appraisedValue > 0 ? Math.floor(appraisedValue * (ltvPct / 100)) : Infinity;
+  if (maxLoanAtDscr1 <= ltvCap) {
+    return { maxLoan: maxLoanAtDscr1, ltvPct, binding: "dscr" };
+  }
+  return { maxLoan: ltvCap, ltvPct, binding: "ltv" };
+}
+
 // src/dscr/engine.ts
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -40,6 +146,11 @@ function formatCurrency(value, decimals = 0) {
     maximumFractionDigits: decimals
   }).format(value);
 }
+function formatCompact(n) {
+  if (n >= 1e6) return `$${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `$${Math.round(n / 1e3)}K`;
+  return formatCurrency(n);
+}
 function calcMonthlyPayment(principal, annualRate, amortYears, interestOnly) {
   if (principal <= 0 || annualRate <= 0) return 0;
   const monthlyRate = annualRate / 12;
@@ -82,6 +193,68 @@ function calculateDSCR(input) {
     tier: getDSCRTier(dscr)
   };
 }
+function calculateDSCRFull(input) {
+  const {
+    monthlyRent,
+    loanAmount,
+    interestRate,
+    loanTerm,
+    annualTaxes,
+    annualInsurance,
+    monthlyHOA,
+    appraisedValue,
+    creditScore,
+    transactionType
+  } = input;
+  const monthlyRate = interestRate / 100 / 12;
+  const n = loanTerm * 12;
+  const pi = monthlyRate > 0 ? loanAmount * (monthlyRate * Math.pow(1 + monthlyRate, n)) / (Math.pow(1 + monthlyRate, n) - 1) : loanAmount / n;
+  const taxes = annualTaxes / 12;
+  const insurance = annualInsurance / 12;
+  const pitia = pi + taxes + insurance + monthlyHOA;
+  const dscrRaw = pitia > 0 ? monthlyRent / pitia : 0;
+  const dscr = Math.round(dscrRaw * 100) / 100;
+  const cashFlow = monthlyRent - pitia;
+  const userLtvPct = getMaxLtv(dscr, creditScore, loanAmount, transactionType);
+  const solved = getMaxDscrLoan(
+    monthlyRent,
+    interestRate,
+    loanTerm,
+    annualTaxes,
+    annualInsurance,
+    monthlyHOA,
+    appraisedValue,
+    creditScore,
+    transactionType
+  );
+  const dscrLtvPct = solved ? solved.ltvPct : null;
+  const dscrMaxLoan = solved ? solved.maxLoan : null;
+  const dscrLoanDelta = dscrMaxLoan !== null ? dscrMaxLoan - loanAmount : null;
+  const rentForDscr1 = Math.ceil(pitia);
+  const rentGap = rentForDscr1 - monthlyRent;
+  const altLtvPct = getAltLtv(transactionType);
+  const altMaxLoan = Math.round(appraisedValue * (altLtvPct / 100));
+  const altLoanDelta = altMaxLoan - loanAmount;
+  const leverageGap = dscrMaxLoan !== null ? altMaxLoan - dscrMaxLoan : altMaxLoan;
+  return {
+    dscr,
+    pi,
+    taxes,
+    insurance,
+    pitia,
+    cashFlow,
+    userLtvPct,
+    dscrLtvPct,
+    dscrMaxLoan,
+    dscrLoanDelta,
+    rentForDscr1,
+    rentGap,
+    altLtvPct,
+    altMaxLoan,
+    altLoanDelta,
+    leverageGap
+  };
+}
 function solveMaxLoan(input, targetDSCR) {
   const grossMonthly = input.monthlyRent;
   const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
@@ -131,11 +304,96 @@ function solveMinRent(input, targetDSCR) {
     feasible: minRent > 0
   };
 }
+
+// src/dscr/credit.ts
+function getCreditInsight(fico, dscr, loanAmt, txType, currentLtv, lang) {
+  const es = lang === "es";
+  if (fico === 700) {
+    return {
+      message: es ? "700 es el valor predeterminado. Ingrese su puntaje real \u2014 720+ desbloquea hasta 85% LTV en compras." : "700 is the default. Enter your actual score \u2014 720+ unlocks up to 85% LTV on purchases.",
+      type: "info"
+    };
+  }
+  if (fico >= 710 && fico < 720 && dscr >= 1) {
+    const nextLtv = getMaxLtv(dscr, 720, loanAmt, txType);
+    if (nextLtv !== null && currentLtv !== null && nextLtv > currentLtv) {
+      return {
+        message: es ? `A solo ${720 - fico} puntos de 720 FICO \u2014 eso desbloquea ${nextLtv}% LTV (${nextLtv - currentLtv}% m\xE1s apalancamiento).` : `Just ${720 - fico} points from 720 FICO \u2014 that unlocks ${nextLtv}% LTV (${nextLtv - currentLtv}% more leverage).`,
+        type: "boost"
+      };
+    }
+  }
+  if (fico >= 690 && fico < 700 && dscr >= 1) {
+    const nextLtv = getMaxLtv(dscr, 700, loanAmt, txType);
+    if (nextLtv !== null && currentLtv !== null && nextLtv > currentLtv) {
+      return {
+        message: es ? `A solo ${700 - fico} puntos de 700 FICO \u2014 eso desbloquea ${nextLtv}% LTV.` : `Just ${700 - fico} points from 700 FICO \u2014 that unlocks ${nextLtv}% LTV.`,
+        type: "boost"
+      };
+    }
+  }
+  if (fico >= 760) {
+    return {
+      message: es ? "Puntaje \xE9lite \u2014 califica para el mejor pricing y m\xE1ximo apalancamiento en todos los programas." : "Elite score \u2014 qualifies for best pricing and maximum leverage across all programs.",
+      type: "boost"
+    };
+  }
+  if (fico < 640 && fico >= 620) {
+    return {
+      message: es ? "Opciones limitadas a 70% LTV max y montos menores. Considere estrategias alternativas de calificaci\xF3n." : "Limited to 70% LTV max and smaller loan amounts. Consider alternative qualifying strategies below.",
+      type: "warning"
+    };
+  }
+  if (fico < 620) {
+    return {
+      message: es ? "La mayor\xEDa de programas DSCR requieren 620+ FICO. Las estrategias alternativas pueden funcionar con puntajes m\xE1s bajos." : "Most DSCR programs require 620+ FICO. Alternative strategies below may work with lower scores.",
+      type: "warning"
+    };
+  }
+  return null;
+}
+function getAltStrategyMessage(fico, _dscr, txType, lang) {
+  const es = lang === "es";
+  const altLtv = getAltLtv(txType);
+  if (fico >= 720) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, las estrategias alternativas desbloquean hasta ${altLtv}% LTV \u2014 su puntaje le da acceso a las mejores opciones:` : `With ${fico} FICO, alternative strategies unlock up to ${altLtv}% LTV \u2014 your score gives you access to the best options:`,
+      planBNote: es ? "Su cr\xE9dito de 720+ califica para el m\xE1ximo apalancamiento con agotamiento de activos." : "Your 720+ credit qualifies for maximum leverage with asset depletion.",
+      planCNote: es ? "Puntaje fuerte \u2014 bank statement y P&L programas disponibles con pricing competitivo." : "Strong score \u2014 bank statement and P&L programs available at competitive pricing."
+    };
+  }
+  if (fico >= 700) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, todav\xEDa tiene acceso fuerte a estrategias alternativas hasta ${altLtv}% LTV:` : `With ${fico} FICO, you still have strong access to alternative strategies up to ${altLtv}% LTV:`,
+      planBNote: es ? "Buen cr\xE9dito \u2014 califica para agotamiento de activos con la mayor\xEDa de prestamistas." : "Good credit \u2014 qualifies for asset depletion with most lenders.",
+      planCNote: es ? "Bank statement y P&L programas ampliamente disponibles en este rango de puntaje." : "Bank statement and P&L programs widely available at this score range."
+    };
+  }
+  if (fico >= 660) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, las estrategias alternativas a\xFAn funcionan pero con LTV reducido. Mejorar a 700+ ampl\xEDa significativamente sus opciones:` : `With ${fico} FICO, alternative strategies still work but at reduced LTV. Improving to 700+ significantly expands your options:`,
+      planBNote: es ? "Disponible \u2014 algunos prestamistas pueden requerir reservas adicionales." : "Available \u2014 some lenders may require additional reserves.",
+      planCNote: es ? "Bank statement disponible. P&L puede requerir 680+ con algunos prestamistas." : "Bank statement available. P&L may require 680+ with some lenders."
+    };
+  }
+  return {
+    subtitle: es ? `Con ${fico} FICO, las opciones son m\xE1s limitadas. Las estrategias alternativas pueden restaurar apalancamiento, pero considere mejorar su cr\xE9dito para mejores t\xE9rminos:` : `With ${fico} FICO, options are more limited. Alternative strategies can restore leverage, but consider improving credit for better terms:`,
+    planBNote: es ? "Disponibilidad limitada \u2014 consulte para opciones espec\xEDficas." : "Limited availability \u2014 consult for specific options.",
+    planCNote: es ? "Bank statement puede funcionar con reservas adicionales. P&L generalmente requiere 660+." : "Bank statement may work with additional reserves. P&L typically requires 660+."
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   calculateDSCR,
+  calculateDSCRFull,
   clamp,
+  formatCompact,
   formatCurrency,
+  getAltLtv,
+  getAltStrategyMessage,
+  getCreditInsight,
+  getMaxDscrLoan,
+  getMaxLtv,
   solveMaxLoan,
   solveMinRent
 });

package/dist/index.mjs

@@ -1,3 +1,102 @@
+// src/dscr/ltv.ts
+function getMaxLtv(dscr, fico, loanAmt, txType) {
+  const pick = (p, rt, co) => {
+    if (txType === "purchase") return p;
+    if (txType === "rateTermRefi") return rt;
+    return co;
+  };
+  if (dscr >= 1) {
+    if (fico >= 720) {
+      if (loanAmt <= 15e5) return pick(85, 85, 80);
+      if (loanAmt <= 2e6) return pick(75, 75, 70);
+      if (loanAmt <= 3e6) return pick(70, 70, 65);
+      if (loanAmt <= 35e5) return pick(65, 65, 60);
+      return pick(60, 60, 55);
+    }
+    if (fico >= 700) {
+      if (loanAmt <= 15e5) return pick(80, 80, 75);
+      if (loanAmt <= 2e6) return pick(75, 75, 70);
+      if (loanAmt <= 3e6) return pick(70, 70, 65);
+      return pick(65, 65, 60);
+    }
+    if (fico >= 680) {
+      if (loanAmt <= 15e5) return pick(75, 75, 75);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      if (loanAmt <= 3e6) return pick(65, 65, 60);
+      return null;
+    }
+    if (fico >= 660) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      if (loanAmt <= 3e6) return pick(65, 65, 60);
+      return null;
+    }
+    if (fico >= 640) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      return null;
+    }
+    if (fico >= 620) {
+      if (loanAmt <= 15e5) return pick(70, 70, 70);
+      return null;
+    }
+    if (fico >= 600 && loanAmt <= 15e5) return pick(60, 60, null);
+    return null;
+  }
+  if (dscr >= 0.75) {
+    if (fico >= 720) {
+      if (loanAmt <= 15e5) return pick(75, 75, 70);
+      if (loanAmt <= 2e6) return pick(70, 70, 65);
+      return null;
+    }
+    if (fico >= 700) {
+      if (loanAmt <= 15e5) return pick(75, 70, 70);
+      return null;
+    }
+    if (fico >= 660) {
+      if (loanAmt <= 15e5) return pick(70, 70, 65);
+      return null;
+    }
+    if (fico >= 640) {
+      if (loanAmt <= 1e6) return pick(65, 65, 60);
+      return null;
+    }
+    return null;
+  }
+  if (fico >= 700) {
+    if (loanAmt <= 1e6) return pick(65, 65, 60);
+    if (loanAmt <= 15e5) return pick(60, 60, null);
+    return null;
+  }
+  if (fico >= 660) {
+    if (loanAmt <= 1e6) return pick(60, 60, null);
+    return null;
+  }
+  return null;
+}
+function getAltLtv(txType) {
+  if (txType === "purchase") return 85;
+  if (txType === "rateTermRefi") return 85;
+  return 80;
+}
+
+// src/dscr/solvers.ts
+function getMaxDscrLoan(monthlyRent, interestRate, loanTerm, annualTaxes, annualInsurance, monthlyHOA, appraisedValue, fico, txType) {
+  const monthlyRate = interestRate / 100 / 12;
+  const n = loanTerm * 12;
+  const fixedExpenses = annualTaxes / 12 + annualInsurance / 12 + monthlyHOA;
+  const paymentFactor = monthlyRate > 0 ? monthlyRate * Math.pow(1 + monthlyRate, n) / (Math.pow(1 + monthlyRate, n) - 1) : 1 / n;
+  const targetPi = monthlyRent / 1 - fixedExpenses;
+  if (targetPi <= 0) return null;
+  const maxLoanAtDscr1 = Math.floor(targetPi / paymentFactor);
+  const ltvPct = getMaxLtv(1, fico, maxLoanAtDscr1, txType);
+  if (ltvPct === null) return null;
+  const ltvCap = appraisedValue > 0 ? Math.floor(appraisedValue * (ltvPct / 100)) : Infinity;
+  if (maxLoanAtDscr1 <= ltvCap) {
+    return { maxLoan: maxLoanAtDscr1, ltvPct, binding: "dscr" };
+  }
+  return { maxLoan: ltvCap, ltvPct, binding: "ltv" };
+}
+
 // src/dscr/engine.ts
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -10,6 +109,11 @@ function formatCurrency(value, decimals = 0) {
     maximumFractionDigits: decimals
   }).format(value);
 }
+function formatCompact(n) {
+  if (n >= 1e6) return `$${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `$${Math.round(n / 1e3)}K`;
+  return formatCurrency(n);
+}
 function calcMonthlyPayment(principal, annualRate, amortYears, interestOnly) {
   if (principal <= 0 || annualRate <= 0) return 0;
   const monthlyRate = annualRate / 12;
@@ -52,6 +156,68 @@ function calculateDSCR(input) {
     tier: getDSCRTier(dscr)
   };
 }
+function calculateDSCRFull(input) {
+  const {
+    monthlyRent,
+    loanAmount,
+    interestRate,
+    loanTerm,
+    annualTaxes,
+    annualInsurance,
+    monthlyHOA,
+    appraisedValue,
+    creditScore,
+    transactionType
+  } = input;
+  const monthlyRate = interestRate / 100 / 12;
+  const n = loanTerm * 12;
+  const pi = monthlyRate > 0 ? loanAmount * (monthlyRate * Math.pow(1 + monthlyRate, n)) / (Math.pow(1 + monthlyRate, n) - 1) : loanAmount / n;
+  const taxes = annualTaxes / 12;
+  const insurance = annualInsurance / 12;
+  const pitia = pi + taxes + insurance + monthlyHOA;
+  const dscrRaw = pitia > 0 ? monthlyRent / pitia : 0;
+  const dscr = Math.round(dscrRaw * 100) / 100;
+  const cashFlow = monthlyRent - pitia;
+  const userLtvPct = getMaxLtv(dscr, creditScore, loanAmount, transactionType);
+  const solved = getMaxDscrLoan(
+    monthlyRent,
+    interestRate,
+    loanTerm,
+    annualTaxes,
+    annualInsurance,
+    monthlyHOA,
+    appraisedValue,
+    creditScore,
+    transactionType
+  );
+  const dscrLtvPct = solved ? solved.ltvPct : null;
+  const dscrMaxLoan = solved ? solved.maxLoan : null;
+  const dscrLoanDelta = dscrMaxLoan !== null ? dscrMaxLoan - loanAmount : null;
+  const rentForDscr1 = Math.ceil(pitia);
+  const rentGap = rentForDscr1 - monthlyRent;
+  const altLtvPct = getAltLtv(transactionType);
+  const altMaxLoan = Math.round(appraisedValue * (altLtvPct / 100));
+  const altLoanDelta = altMaxLoan - loanAmount;
+  const leverageGap = dscrMaxLoan !== null ? altMaxLoan - dscrMaxLoan : altMaxLoan;
+  return {
+    dscr,
+    pi,
+    taxes,
+    insurance,
+    pitia,
+    cashFlow,
+    userLtvPct,
+    dscrLtvPct,
+    dscrMaxLoan,
+    dscrLoanDelta,
+    rentForDscr1,
+    rentGap,
+    altLtvPct,
+    altMaxLoan,
+    altLoanDelta,
+    leverageGap
+  };
+}
 function solveMaxLoan(input, targetDSCR) {
   const grossMonthly = input.monthlyRent;
   const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
@@ -101,10 +267,95 @@ function solveMinRent(input, targetDSCR) {
     feasible: minRent > 0
   };
 }
+
+// src/dscr/credit.ts
+function getCreditInsight(fico, dscr, loanAmt, txType, currentLtv, lang) {
+  const es = lang === "es";
+  if (fico === 700) {
+    return {
+      message: es ? "700 es el valor predeterminado. Ingrese su puntaje real \u2014 720+ desbloquea hasta 85% LTV en compras." : "700 is the default. Enter your actual score \u2014 720+ unlocks up to 85% LTV on purchases.",
+      type: "info"
+    };
+  }
+  if (fico >= 710 && fico < 720 && dscr >= 1) {
+    const nextLtv = getMaxLtv(dscr, 720, loanAmt, txType);
+    if (nextLtv !== null && currentLtv !== null && nextLtv > currentLtv) {
+      return {
+        message: es ? `A solo ${720 - fico} puntos de 720 FICO \u2014 eso desbloquea ${nextLtv}% LTV (${nextLtv - currentLtv}% m\xE1s apalancamiento).` : `Just ${720 - fico} points from 720 FICO \u2014 that unlocks ${nextLtv}% LTV (${nextLtv - currentLtv}% more leverage).`,
+        type: "boost"
+      };
+    }
+  }
+  if (fico >= 690 && fico < 700 && dscr >= 1) {
+    const nextLtv = getMaxLtv(dscr, 700, loanAmt, txType);
+    if (nextLtv !== null && currentLtv !== null && nextLtv > currentLtv) {
+      return {
+        message: es ? `A solo ${700 - fico} puntos de 700 FICO \u2014 eso desbloquea ${nextLtv}% LTV.` : `Just ${700 - fico} points from 700 FICO \u2014 that unlocks ${nextLtv}% LTV.`,
+        type: "boost"
+      };
+    }
+  }
+  if (fico >= 760) {
+    return {
+      message: es ? "Puntaje \xE9lite \u2014 califica para el mejor pricing y m\xE1ximo apalancamiento en todos los programas." : "Elite score \u2014 qualifies for best pricing and maximum leverage across all programs.",
+      type: "boost"
+    };
+  }
+  if (fico < 640 && fico >= 620) {
+    return {
+      message: es ? "Opciones limitadas a 70% LTV max y montos menores. Considere estrategias alternativas de calificaci\xF3n." : "Limited to 70% LTV max and smaller loan amounts. Consider alternative qualifying strategies below.",
+      type: "warning"
+    };
+  }
+  if (fico < 620) {
+    return {
+      message: es ? "La mayor\xEDa de programas DSCR requieren 620+ FICO. Las estrategias alternativas pueden funcionar con puntajes m\xE1s bajos." : "Most DSCR programs require 620+ FICO. Alternative strategies below may work with lower scores.",
+      type: "warning"
+    };
+  }
+  return null;
+}
+function getAltStrategyMessage(fico, _dscr, txType, lang) {
+  const es = lang === "es";
+  const altLtv = getAltLtv(txType);
+  if (fico >= 720) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, las estrategias alternativas desbloquean hasta ${altLtv}% LTV \u2014 su puntaje le da acceso a las mejores opciones:` : `With ${fico} FICO, alternative strategies unlock up to ${altLtv}% LTV \u2014 your score gives you access to the best options:`,
+      planBNote: es ? "Su cr\xE9dito de 720+ califica para el m\xE1ximo apalancamiento con agotamiento de activos." : "Your 720+ credit qualifies for maximum leverage with asset depletion.",
+      planCNote: es ? "Puntaje fuerte \u2014 bank statement y P&L programas disponibles con pricing competitivo." : "Strong score \u2014 bank statement and P&L programs available at competitive pricing."
+    };
+  }
+  if (fico >= 700) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, todav\xEDa tiene acceso fuerte a estrategias alternativas hasta ${altLtv}% LTV:` : `With ${fico} FICO, you still have strong access to alternative strategies up to ${altLtv}% LTV:`,
+      planBNote: es ? "Buen cr\xE9dito \u2014 califica para agotamiento de activos con la mayor\xEDa de prestamistas." : "Good credit \u2014 qualifies for asset depletion with most lenders.",
+      planCNote: es ? "Bank statement y P&L programas ampliamente disponibles en este rango de puntaje." : "Bank statement and P&L programs widely available at this score range."
+    };
+  }
+  if (fico >= 660) {
+    return {
+      subtitle: es ? `Con ${fico} FICO, las estrategias alternativas a\xFAn funcionan pero con LTV reducido. Mejorar a 700+ ampl\xEDa significativamente sus opciones:` : `With ${fico} FICO, alternative strategies still work but at reduced LTV. Improving to 700+ significantly expands your options:`,
+      planBNote: es ? "Disponible \u2014 algunos prestamistas pueden requerir reservas adicionales." : "Available \u2014 some lenders may require additional reserves.",
+      planCNote: es ? "Bank statement disponible. P&L puede requerir 680+ con algunos prestamistas." : "Bank statement available. P&L may require 680+ with some lenders."
+    };
+  }
+  return {
+    subtitle: es ? `Con ${fico} FICO, las opciones son m\xE1s limitadas. Las estrategias alternativas pueden restaurar apalancamiento, pero considere mejorar su cr\xE9dito para mejores t\xE9rminos:` : `With ${fico} FICO, options are more limited. Alternative strategies can restore leverage, but consider improving credit for better terms:`,
+    planBNote: es ? "Disponibilidad limitada \u2014 consulte para opciones espec\xEDficas." : "Limited availability \u2014 consult for specific options.",
+    planCNote: es ? "Bank statement puede funcionar con reservas adicionales. P&L generalmente requiere 660+." : "Bank statement may work with additional reserves. P&L typically requires 660+."
+  };
+}
 export {
   calculateDSCR,
+  calculateDSCRFull,
   clamp,
+  formatCompact,
   formatCurrency,
+  getAltLtv,
+  getAltStrategyMessage,
+  getCreditInsight,
+  getMaxDscrLoan,
+  getMaxLtv,
   solveMaxLoan,
   solveMinRent
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wirms/calculator-engine",
-  "version": "1.0.1",
-  "description": "Pure TypeScript DSCR and investor calculator engine — zero dependencies",
+  "version": "2.0.0",
+  "description": "Pure TypeScript DSCR and investor calculator engine — full lender LTV matrix, algebraic solvers, credit insight engine, bilingual. Zero dependencies.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -26,6 +26,7 @@
     "url": "https://github.com/roasst/investor-tools.git",
     "directory": "packages/calculator-engine"
   },
+  "keywords": ["dscr", "calculator", "mortgage", "real-estate", "investor", "ltv", "loan"],
   "author": "WIRMS <luke@roasst.com>",
   "license": "UNLICENSED"
 }