module.exports = {
  slug: "apr-to-apy",
  title: "APR to APY (effective annual rate)",
  deck_category: "finance",
  description: "Converts a nominal annual percentage rate compounded periodically into the effective annual percentage yield.",
  inputs: [
    { name: "nominal_annual_rate_percent", type: "number", unit: "%", required: true, description: "Nominal annual rate (APR)", min: 0 },
    { name: "compounds_per_year", type: "integer", required: true, description: "Number of compounding periods per year", enum: [1, 2, 4, 12, 52, 365] }
  ],
  outputs: [
    { name: "effective_annual_rate_percent", unit: "%", description: "Effective annual rate (APY)" }
  ],
  steps: [
    "Convert the nominal rate to a decimal: r = nominal_annual_rate_percent / 100.",
    "Periodic rate i = r / compounds_per_year.",
    "APY as a decimal = (1 + i) ^ compounds_per_year - 1.",
    "effective_annual_rate_percent = APY * 100, rounded to 4 decimals for display as a percent with 2 shown."
  ],
  constants: [],
  sources: [
    { kind: "edition_page", value: "Brealey, Myers, Allen, Principles of Corporate Finance, 13th ed., Chapter 3, section on compounding intervals and the effective annual rate", title: "Principles of Corporate Finance", publisher: "McGraw-Hill", retrieved_utc: "2026-09-30T19:31:29Z", note: "APY = (1 + APR/n)^n - 1" }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `What is the effective annual rate (APY) of a nominal annual rate of ${inputs.nominal_annual_rate_percent}% compounded ${inputs.compounds_per_year} times per year?`;
  },
  run(inputs) {
    const { nominal_annual_rate_percent, compounds_per_year } = inputs;
    if (typeof nominal_annual_rate_percent !== "number" || nominal_annual_rate_percent < 0) throw new Error("nominal_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");
    const r = nominal_annual_rate_percent / 100;
    const i = r / compounds_per_year;
    const apyDecimal = Math.pow(1 + i, compounds_per_year) - 1;
    const effective_annual_rate_percent = Math.round(apyDecimal * 100 * 100) / 100;
    return {
      answer: `${effective_annual_rate_percent.toFixed(2)}%`,
      values: { effective_annual_rate_percent }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { nominal_annual_rate_percent: 12, compounds_per_year: 12 },
      expected: { answer: "12.68%" },
      check: "hand computation: i = 0.01, APY = (1.01)^12 - 1 = 0.126825..., 12.6825% rounds to 12.68%"
    },
    {
      name: "test vector: quarterly compounding",
      inputs: { nominal_annual_rate_percent: 6, compounds_per_year: 4 },
      expected: { answer: "6.14%" },
      check: "hand computation: i = 0.015, APY = (1.015)^4 - 1 = 0.061364..., 6.1364% rounds to 6.14%"
    }
  ]
};