module.exports = {
  slug: "compound-interest",
  title: "Compound interest",
  deck_category: "finance",
  description: "Computes the final amount of a principal that compounds periodically at a fixed nominal annual rate.",
  inputs: [
    { name: "principal", type: "number", unit: "currency units", required: true, description: "Starting amount", min: 0 },
    { name: "annual_rate_percent", type: "number", unit: "%", required: true, description: "Nominal annual rate", min: 0 },
    { name: "compounds_per_year", type: "integer", required: true, description: "Compounding periods per year", enum: [1, 2, 4, 12, 52, 365] },
    { name: "years", type: "number", unit: "years", required: true, description: "Term", min: 0 }
  ],
  outputs: [
    { name: "final_amount", unit: "currency units", description: "Amount after the term" },
    { name: "interest_earned", unit: "currency units", description: "Total interest earned over the term" }
  ],
  steps: [
    "Convert the annual rate to a decimal: r = annual_rate_percent / 100.",
    "Periodic rate i = r / compounds_per_year; periods n = compounds_per_year * years.",
    "final_amount = principal * (1 + i) ^ n, rounded to 2 decimals.",
    "interest_earned = final_amount - principal, rounded to 2 decimals."
  ],
  constants: [],
  sources: [
    { kind: "edition_page", value: "Brealey, Myers, Allen, Principles of Corporate Finance, 13th ed., Chapter 3, section 3-1 (Compound Interest)", title: "Principles of Corporate Finance", publisher: "McGraw-Hill", retrieved_utc: "2026-09-30T19:31:29Z", note: "Standard compound interest formula FV = PV*(1+i)^n" }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `What is the final amount of a $${inputs.principal} principal invested at ${inputs.annual_rate_percent}% annual interest, compounded ${inputs.compounds_per_year} times per year for ${inputs.years} years?`;
  },
  run(inputs) {
    const { principal, annual_rate_percent, compounds_per_year, years } = 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(compounds_per_year) || compounds_per_year <= 0) throw new Error("compounds_per_year must be a positive integer");
    if (typeof years !== "number" || years < 0) throw new Error("years must be a non-negative number");
    const r = annual_rate_percent / 100;
    const i = r / compounds_per_year;
    const n = compounds_per_year * years;
    const final_amount = Math.round(principal * Math.pow(1 + i, n) * 100) / 100;
    const interest_earned = Math.round((final_amount - principal) * 100) / 100;
    return {
      answer: `$${final_amount.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ",")}`,
      values: { final_amount, interest_earned }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { principal: 1000, annual_rate_percent: 5, compounds_per_year: 12, years: 10 },
      expected: { answer: "$1,647.01" },
      check: "hand computation: i = 0.05/12 = 0.0041666..., n = 120, final = 1000*(1.0041666...)^120 = 1647.0094..., rounds to 1647.01"
    },
    {
      name: "test vector: annual compounding",
      inputs: { principal: 5000, annual_rate_percent: 4, compounds_per_year: 1, years: 5 },
      expected: { answer: "$6,083.26" },
      check: "hand computation: final = 5000*(1.04)^5 = 6083.2603..., rounds to 6083.26"
    }
  ]
};