module.exports = {
  slug: "total-interest-over-loan",
  title: "Total interest over a loan",
  deck_category: "finance",
  description: "Computes the total interest paid over the full life of a fixed-payment amortizing loan.",
  inputs: [
    { name: "principal", type: "number", unit: "currency units", required: true, description: "Original loan amount", min: 0 },
    { name: "annual_rate_percent", type: "number", unit: "%", required: true, description: "Nominal annual interest rate, compounded monthly", min: 0 },
    { name: "months", type: "integer", required: true, description: "Number of monthly payments (loan term in months)", min: 1 }
  ],
  outputs: [
    { name: "monthly_payment", unit: "currency units", description: "Fixed monthly payment" },
    { name: "total_paid", unit: "currency units", description: "Sum of all payments over the loan" },
    { name: "total_interest", unit: "currency units", description: "Total interest paid over the loan" }
  ],
  steps: [
    "Convert the annual rate to a decimal: r = annual_rate_percent / 100; monthly rate i = r / 12.",
    "Compute the fixed monthly payment using the standard annuity formula: payment = principal * i * (1+i)^months / ((1+i)^months - 1) (or principal/months if i = 0).",
    "total_paid = payment * months.",
    "total_interest = total_paid - principal.",
    "Round monthly_payment, total_paid, and total_interest to 2 decimals (money to cents)."
  ],
  constants: [],
  sources: [
    { kind: "edition_page", value: "Brealey, Myers, Allen, Principles of Corporate Finance, 13th ed., Chapter 3, section 3-3 (Loan Amortization)", title: "Principles of Corporate Finance", publisher: "McGraw-Hill", retrieved_utc: "2026-09-30T19:31:29Z", note: "Total interest equals the sum of all fixed payments minus the original principal" }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `How much total interest is paid over the life of a $${inputs.principal} loan at ${inputs.annual_rate_percent}% annual interest amortized over ${inputs.months} months?`;
  },
  run(inputs) {
    const { principal, annual_rate_percent, months } = inputs;
    if (typeof principal !== "number" || principal < 0) throw new Error("principal must be a non-negative number");
    if (typeof annual_rate_percent !== "number" || annual_rate_percent < 0) throw new Error("annual_rate_percent must be a non-negative number");
    if (!Number.isInteger(months) || months <= 0) throw new Error("months must be a positive integer");
    const r = annual_rate_percent / 100;
    const i = r / 12;
    let payment;
    if (i === 0) {
      payment = principal / months;
    } else {
      const factor = Math.pow(1 + i, months);
      payment = (principal * i * factor) / (factor - 1);
    }
    const monthly_payment = Math.round(payment * 100) / 100;
    const total_paid = Math.round(monthly_payment * months * 100) / 100;
    const total_interest = Math.round((total_paid - principal) * 100) / 100;
    const fmt = (n) => n.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
    return {
      answer: `$${fmt(total_interest)}`,
      values: { monthly_payment, total_paid, total_interest }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { principal: 200000, annual_rate_percent: 6, months: 360 },
      expected: { answer: "$231,676.00" },
      check: "hand computation: payment = 1199.10 (see loan-payment-amortized), total_paid = 1199.10*360 = 431676.00, total_interest = 431676.00-200000 = 231676.00"
    },
    {
      name: "test vector: zero interest",
      inputs: { principal: 12000, annual_rate_percent: 0, months: 12 },
      expected: { answer: "$0.00" },
      check: "hand computation: payment = 1000.00, total_paid = 12000.00, total_interest = 0.00"
    }
  ]
};