amortizy 2.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1bf3cd11455f5c2c301066d64f911a15e696dd1b033c2b865a5d7ddaff93e05
-  data.tar.gz: 34482d2f3553108c4ad04d3dd238ff486e3c72aa266fd4f19582607720df98ff
+  metadata.gz: 4ca0ea325340402016df8375d37a1df326360b5c83757133ab91d7d90586d98b
+  data.tar.gz: d8323ccba488c8e3fd4ed75095ede9b84615011bcdd881e038b9e539ffc2d694
 SHA512:
-  metadata.gz: e1d49aaa154f7dbce6a7f5e9fddf77c04a4f6ea90af9662b4cfa1c6ed787a70672277cd6a8425346277067fef6af76ac2d3ec32ddfd2f7b3d972f049cdd43846
-  data.tar.gz: 94aaf0a040ba624cedc10ea49db5a873712b8682a6f6191439088eb02df8f74d27bb86c14cb9288607a51217d9f091ab643b3d4108fb83b3e04dcf8e28a11dd3
+  metadata.gz: bfa7d476af355d10e128f26906c102f9fed268c8ac62ade499bb5cefb230d7288579d98e27970271250a7ad6e1d8c6f1fdb9d4230ab06d2ea1e0322af6706e19
+  data.tar.gz: b2c3bef7394514492942ff87f61f229f74a398337298a3bd9671a01c48ff914357fd50ba2146210b56c7907624b9667c6df491e76699239c2f180b78c0780e2c

data/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.1] - 2026-10-21
+
+### Fixed
+- README example outputs now match what the gem returns (Quick Start, `#schedule`, `#summary`, disclosure APR and term)
+- README no longer documents an `amortizy` command-line tool, which the gem has never shipped
+- The packaged gem no longer includes internal planning notes (`tasks/`)
+- README notes the known origination-fee double count in disclosures (#11) and the Saturday holiday issue (#8)
+
+## [3.1.0] - 2026-10-21
+
+### Added
+- `balloon_amount:` leaves a lump sum of principal due with the final payment (#3)
+- The final row of a balloon loan has `payment_type: "Balloon Payment"`
+- `#balloon_amount` reader and `balloon_amount` in `#summary`
+- Console summary shows the balloon when there is one
+- `Disclosure#balloon_payment`, and `balloon_payment` in `#to_h` / `#to_labeled_h` for balloon loans
+
+## [3.0.1] - 2026-10-21
+
+### Fixed
+- Simple-interest payments are sized on each period's actual days, so the final payment matches the regular payment and long or bank-day schedules no longer end early (#12). Simple-interest payment amounts change slightly as a result.
+
+### Changed
+- README now explains negative amortization: at high rates, a long period's interest can be more than the level payment, which shows as a negative `principal_payment`
+
+## [3.0.0] - 2026-10-21
+
+### Changed
+- Requires Ruby 3.3 or newer (3.0, 3.1 and 3.2 are end-of-life)
+- `holidays` dependency updated from 8.x to 11.7; holiday dates are unchanged
+- CI now tests Ruby 3.3, 3.4 and 4.0
+
+## [2.1.0] - 2026-04-20
+
+### Added
+
+#### Commercial Financing Disclosure Module
+- **`Amortizy::Disclosure`** - new class that computes disclosure data elements for
+  closed-end commercial loan transactions per California SB 1235 (Title 10, Chapter 3)
+- **APR calculation** using the actuarial method per Appendix J of Regulation Z
+  (12 CFR Part 1026, section 940) with Newton-Raphson solver and bisection fallback
+- **Finance charge** - total dollar cost of financing including interest and all fees (section 943)
+- **Amount financed** - principal adjusted for prepaid finance charges (section 900(a)(1)(B))
+- **Recipient funds** - net amount disbursed to borrower after third-party payoffs (section 900(a)(26))
+- **Term display** - formatted per regulation: days for terms <= 1 year,
+  years/months for longer terms (section 901(a)(4))
+- **Average monthly cost** - automatically computed for non-monthly payment frequencies (section 910(a)(12))
+- **Prepayment information** - structured data for prepayment penalty disclosures (section 910(a)(8-10))
+- **`#to_h`** - flat hash of all computed values
+- **`#to_labeled_h`** - hash with regulation-correct labels from section 910
+
+#### Design Notes
+- Disclosure class wraps an existing `AmortizationSchedule` — no changes to the engine API
+- Values are jurisdiction-agnostic: computed per the most stringent methodology (California),
+  usable for any state's commercial financing disclosure requirements
+- Origination fee is treated as a prepaid finance charge by default
+- APR rounded to nearest 10 basis points per section 901(a)(5)
+- APR accuracy within 1/8 of 1 percentage point tolerance per section 955
+
 ## [2.0.0] - 2026-04-19
 
 ### Added
@@ -127,7 +186,6 @@ bundle update amortizy
 
 Potential features for future releases:
 
-- Additional payment frequencies (monthly, bi-weekly)
 - More interest calculation methods
 - Support for additional holiday calendars (state, international)
 - Balloon payment support

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://img.shields.io/gem/v/amortizy.svg?style=flat)](https://rubygems.org/gems/amortizy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Ruby gem for generating loan amortization schedules. Supports monthly, bi-weekly, weekly, and daily payment frequencies with grace periods, interest-only payments, federal bank holidays, and multiple interest calculation methods.
+A Ruby gem for generating loan amortization schedules. Supports monthly, bi-weekly, weekly, and daily payment frequencies with grace periods, interest-only payments, balloon payments, federal bank holidays, and multiple interest calculation methods.
 
 Perfect for financial applications, lending platforms, and loan calculators.
 
@@ -15,11 +15,13 @@ Perfect for financial applications, lending platforms, and loan calculators.
 - **Interest calculation methods**: Simple (accrued daily) or precomputed (fixed per payment)
 - **Grace periods**: Grace periods before first payment (interest accrues and capitalizes)
 - **Interest-only periods**: Configure initial interest-only payment phases
+- **Balloon payments**: Leave a lump sum due with the final payment, common in commercial lending
 - **Fee handling**: Origination fees and additional fees with three treatment options
 - **Bank day calculations**: Automatically skip weekends and US Federal Reserve holidays
 - **Multiple output formats**: Console display or CSV export
 - **Public API**: Programmatic access to schedule data, summaries, and totals
-- **Testing**: 70 RSpec tests
+- **Commercial financing disclosures**: APR (Reg Z actuarial method), finance charge, amount financed, and more
+- **Tested**: RSpec suite covering every option above
 
 ## Installation
 
@@ -61,9 +63,9 @@ schedule.generate
 
 # Access data programmatically
 schedule.summary          # => { start_date:, end_date:, principal:, total_payments:, ... }
-schedule.payment_amount   # => 8791.59
-schedule.total_interest   # => 5499.06
-schedule.total_paid       # => 105499.06
+schedule.payment_amount   # => 8789.68
+schedule.total_interest   # => 5476.15
+schedule.total_paid       # => 105476.15
 schedule.end_date         # => #<Date: 2027-01-15>
 
 # Get the full schedule as an array of hashes
@@ -93,7 +95,7 @@ schedule.end_date           # => the date of the 26th payment
 schedule.term_months        # => nil (not applicable when using num_payments)
 ```
 
-### Advanced Example with All Features
+### Advanced Example
 
 ```ruby
 schedule = Amortizy::AmortizationSchedule.new(
@@ -135,6 +137,7 @@ schedule.generate
 | `interest_only_periods` | Integer | No | 0 | - | Number of interest-only payments |
 | `grace_period_days` | Integer | No | 0 | - | Days before first payment |
 | `interest_method` | Symbol | No | `:simple` | `:simple`, `:precomputed` | Interest calculation method |
+| `balloon_amount` | Numeric or decimal String | No | 0 | >= 0, less than the amortized balance; other text raises `ArgumentError` | Principal left unpaid until the final payment. See [Balloon Payments](#balloon-payments) |
 
 *Provide either `term_months` or `num_payments`, not both.
 
@@ -156,19 +159,23 @@ Returns a frozen array of payment hashes. Each hash contains:
 ```ruby
 {
   payment_number: 1,
-  date: #<Date>,
-  principal_payment: 8302.48,
-  interest_payment: 489.11,
+  date: #<Date: 2026-02-15>,
+  principal_payment: 7940.36,
+  interest_payment: 849.32,
   additional_fee_payment: 0.0,
-  total_payment: 8791.59,
-  principal_balance: 91697.52,
-  accrued_interest: 489.11,
-  total_balance: 92186.63,
+  total_payment: 8789.68,
+  principal_balance: 92059.64,
+  accrued_interest: 849.32,
+  total_balance: 92908.95,
   payment_type: "Regular Payment",
-  days_in_period: 29
+  days_in_period: 31
 }
 ```
 
+`payment_type` is one of `"Regular Payment"`, `"Interest Only"`, `"Balloon Payment"` (the final row of a
+balloon loan), `"Additional Fee Payment"` (row `0`, with `:separate_payment`) or `"Grace Period"` (row
+`"Grace"`, which also carries `grace_interest_capitalized`).
+
 #### `#summary`
 
 Returns a hash with loan totals:
@@ -181,9 +188,10 @@ Returns a hash with loan totals:
   total_payments: 12,
   frequency: :monthly,
   annual_rate: 10.0,
-  payment_amount: 8791.59,
-  total_interest: 5499.06,
-  total_paid: 105499.06
+  payment_amount: 8789.68,
+  balloon_amount: 0.0,
+  total_interest: 5476.15,
+  total_paid: 105476.15
 }
 ```
 
@@ -194,13 +202,14 @@ Returns a hash with loan totals:
 | `#end_date` | Date of the last payment |
 | `#total_interest` | Sum of all interest payments |
 | `#total_paid` | Sum of all payments |
-| `#payment_amount` | Regular payment amount |
+| `#payment_amount` | Regular payment amount (excludes any balloon) |
+| `#balloon_amount` | Balloon due with the final payment (0.0 when none) |
 
 ## Payment Frequencies
 
 ### Monthly (`:monthly`)
 
-Payments on the same day each month. If the start date is the 31st, payments on shorter months use the last day of the month (e.g., Jan 31 -> Feb 28 -> Mar 28).
+Payments on the same day each month, starting one month after the start date (or after the grace period). If the start date is the 31st, payments on shorter months use the last day of the month, and later payments keep that earlier day (e.g., Jan 31 -> Feb 28 -> Mar 28 -> Apr 28).
 
 ### Bi-weekly (`:biweekly`)
 
@@ -227,7 +236,7 @@ The fee is added to the loan principal upfront, increasing the base amount finan
 **Best for:** Rolling all costs into the loan amount
 
 ### 3. Separate Payment (`:separate_payment`)
-The fee is collected as a separate first payment before regular amortization begins.
+The fee is collected as a separate payment (`payment_number: 0`) one period after the start, before regular amortization begins.
 
 **Best for:** Collecting fees upfront separately from the loan repayment
 
@@ -239,21 +248,72 @@ Interest accrues daily on the remaining principal balance. As you pay down the p
 
 **Formula:** Daily interest = (Principal Balance x Annual Rate) / 365
 
+The level payment is sized on the actual number of days in each scheduled period (after bank-day
+adjustments), so the final payment equals the regular payment and the schedule runs its full term.
+
+**Negative amortization:** a level payment can be smaller than the interest on a long period, such as
+a 31-day month at a high rate. That row shows a negative `principal_payment` and the unpaid interest is
+added to the balance. For example, a 30-year loan at 18% does this in every 31-day month for its first
+seven years or so (through about payment 89). With `bank_days_only: true`, weekend and holiday shifts
+make some periods 32 to 34 days long, and it continues through about payment 193. The schedule still
+pays off exactly on the final payment.
+
 **Best for:** Traditional amortizing loans, consumer loans
 
 ### Precomputed Interest (`:precomputed`)
 
-Total interest is calculated upfront based on the original principal and divided equally across all payments. Interest per payment stays constant regardless of principal reduction.
+Total interest is calculated upfront on the principal plus origination fee for the estimated length of the loan, then divided equally across all payments. Interest per payment stays constant regardless of principal reduction.
 
 **Best for:** Fixed payment structures, certain consumer loan types
 
+## Balloon Payments
+
+A balloon loan's regular payments only pay the principal down to `balloon_amount`. That remaining
+principal is due as a lump sum with the final payment. Commercial real estate and equipment loans
+often work this way, with a short term and payments sized as if the loan ran much longer.
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 500_000.00,
+  term_months: 60,
+  annual_rate: 7.25,
+  frequency: :monthly,
+  balloon_amount: 350_000.00
+)
+
+schedule.payment_amount          # => 5103.18   (payments 1-59)
+schedule.schedule.last
+# => { payment_number: 60, date: #<Date 2031-01-15>, total_payment: 355103.18,
+#      payment_type: "Balloon Payment", principal_balance: 0, ... }
+```
+
+How it works:
+
+- **Simple interest:** the payment is sized on the actual days in each period so that exactly
+  `balloon_amount` is left after the regular payments. With equal-length periods this is the standard
+  annuity payment with a future value. Interest keeps accruing on the balloon for the whole term.
+- **Precomputed interest:** the principal portion of each payment is
+  `(amortized balance - balloon_amount) / principal payments`. Interest is unchanged.
+- **The final payment** is the regular payment plus the balloon, to the cent.
+- **A balloon close to the principal** leaves a payment barely above the interest, so longer periods
+  can show negative amortization (see [Simple Interest](#simple-interest-simple)). The final payment
+  still settles the loan exactly.
+- **Works with** every frequency, `num_payments`, interest-only periods, grace periods and fees. The
+  limit is measured against the amortized balance: principal + origination fee + capitalized grace
+  interest, plus the additional fee when it is `:add_to_principal`.
+- **Disclosures:** `Amortizy::Disclosure` reads the actual schedule, so the balloon is included in
+  the total payment amount, the finance charge and the APR. `#balloon_payment` returns the final
+  payment (regular payment plus balloon), and `#to_h` / `#to_labeled_h` include it as
+  `balloon_payment` / "Balloon Payment" when the loan has a balloon.
+
 ## Federal Bank Holidays
 
 When `bank_days_only: true`, the schedule automatically skips weekends and US Federal Reserve holidays:
 
 - New Year's Day, MLK Jr. Day, Presidents' Day, Memorial Day, Juneteenth, Independence Day, Labor Day, Columbus Day, Veterans Day, Thanksgiving, Christmas
 
-Weekend observation rules are handled automatically by the `holidays` gem.
+Weekend observation comes from the `holidays` gem: a Sunday holiday is observed the following Monday. **Known issue:** a Saturday holiday is currently also treated as closing the preceding Friday, which the Federal Reserve does not do ([#8](https://github.com/zapatify/amortizy/issues/8)).
 
 ## Usage Examples
 
@@ -325,23 +385,114 @@ schedule = Amortizy::AmortizationSchedule.new(
 schedule.generate(output: :csv, csv_path: "commercial_loan.csv")
 ```
 
-## Command Line Interface
+## Commercial Financing Disclosures
 
-Amortizy includes an interactive CLI tool:
+Amortizy includes a disclosure module for computing data elements required by California SB 1235 and similar state commercial financing disclosure laws (New York, Georgia, etc.). The calculations follow California's regulations (10 CCR §900 et seq.). Check the methodology against your state's rules before relying on it elsewhere.
 
-```bash
-amortizy
+The `Disclosure` class wraps an existing `AmortizationSchedule` and computes nine disclosure elements. The gem computes the numbers — your application handles document formatting.
+
+**Key assumption:** The origination fee is treated as a prepaid finance charge (deducted from amount financed, included in finance charge). This is the standard treatment for commercial lending.
+
+**Known issue:** `AmortizationSchedule` adds the origination fee to the balance the borrower repays, and `Disclosure` also deducts it from the amount financed, so the fee is counted twice. Until this is resolved, the amount financed is understated by the fee and the finance charge and APR are overstated ([#11](https://github.com/zapatify/amortizy/issues/11)). The example figures below reflect the current behavior.
+
+### Basic Usage
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 50_000,
+  annual_rate: 12.0,
+  frequency: :monthly,
+  term_months: 36,
+  origination_fee: 500,
+  additional_fee: 250,
+  additional_fee_treatment: :distributed
+)
+
+disclosure = Amortizy::Disclosure.new(schedule)
+
+disclosure.apr                   # => 13.6 (Reg Z actuarial method, 10 bps precision)
+disclosure.finance_charge        # => 11123.13
+disclosure.amount_financed       # => 49500.0
+disclosure.total_payment_amount  # => 60623.13
+disclosure.recipient_funds       # => 49500.0
+disclosure.term_display          # => "3 years, 0.03 months"
+disclosure.average_monthly_cost  # => nil (monthly frequency)
+disclosure.prepayment            # => { has_non_interest_charges: false, ... }
 ```
 
-The CLI provides:
-1. Run default examples (demonstrates simple vs precomputed interest)
-2. Enter parameters manually with interactive prompts
-3. Automatic CSV generation option
+### With Third-Party Payments and Prepayment Info
+
+```ruby
+disclosure = Amortizy::Disclosure.new(
+  schedule,
+  third_party_payments: 10_000,
+  prepayment_penalty_max: 1_200,
+  additional_prepayment_fees: [
+    { amount: 250.0, description: "Early termination fee" }
+  ]
+)
+
+disclosure.recipient_funds  # => 39500.0 (amount_financed - third_party_payments)
+disclosure.prepayment
+# => {
+#   has_non_interest_charges: true,
+#   max_non_interest_finance_charge: 1200.0,
+#   has_additional_fees: true,
+#   additional_fees: [{ amount: 250.0, description: "Early termination fee" }]
+# }
+```
+
+### Output Formats
+
+```ruby
+# Raw values
+disclosure.to_h
+# => { amount_financed: 49500.0, apr: 13.6, finance_charge: 11123.13, ... }
+
+# With regulation-correct labels (per CA SB 1235 section 910)
+disclosure.to_labeled_h
+# => {
+#   amount_financed: { label: "Funding Provided", value: 49500.0 },
+#   apr: { label: "Annual Percentage Rate (APR)", value: 13.6 },
+#   finance_charge: { label: "Finance Charge", value: 11123.13 },
+#   ...
+# }
+```
+
+### Disclosure Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `third_party_payments` | Float | 0 | Amounts paid to third parties from the financing |
+| `prepayment_penalty_max` | Float | 0 | Maximum non-interest charge on early payoff |
+| `additional_prepayment_fees` | Array | [] | Array of `{ amount:, description: }` hashes |
+
+### Disclosure Elements
+
+| Element | Method | Description | Regulatory Reference |
+|---------|--------|-------------|---------------------|
+| Funding Provided | `#amount_financed` | Principal adjusted for prepaid finance charges | §900(a)(1)(B) |
+| APR | `#apr` | Annual percentage rate (Reg Z actuarial method) | §940 |
+| Finance Charge | `#finance_charge` | Total dollar cost (derived from Reg Z identity) | §943 |
+| Total Payment Amount | `#total_payment_amount` | Sum of all borrower payments | §910(a)(5) |
+| Payment | `#payment_amount` | Regular periodic payment | §910(a)(6) |
+| Balloon Payment | `#balloon_payment` | Final payment of a balloon loan; `nil` (and omitted from the hashes) otherwise | - |
+| Term | `#term_display` | Days (<=1yr) or years/months (>1yr) | §901(a)(4) |
+| Average Monthly Cost | `#average_monthly_cost` | For non-monthly frequencies only | §910(a)(12) |
+| Recipient Funds | `#recipient_funds` | Net amount to borrower | §900(a)(26) |
+| Prepayment | `#prepayment` | Prepayment penalty details | §910(a)(8-10) |
+
+### Technical Notes
+
+- **APR calculation** uses the actuarial method per Appendix J of Regulation Z (12 CFR Part 1026). Newton-Raphson solver with bisection fallback. APR rounded to nearest 10 basis points per §901(a)(5). Accuracy within 1/8 of 1 percentage point per §955.
+- **Finance charge** is derived from the Reg Z identity: `total_payment_amount - amount_financed`. This guarantees the three core disclosure values are always internally consistent.
+- **Floating-point arithmetic** is used for all calculations. This is adequate for typical commercial loans. For extremely large principals or very long terms (1000+ payments), consider validating against a reference APR calculator.
 
 ## Requirements
 
-- Ruby 3.0 or higher
-- `holidays` gem (~> 8.0) - automatically installed as a dependency
+- Ruby 3.3 or higher
+- `holidays` gem (~> 11.7) - automatically installed as a dependency
 
 ## Development
 
@@ -363,7 +514,7 @@ bin/console
 
 ## Testing
 
-The test suite includes 70 RSpec examples covering:
+The RSpec suite covers:
 
 - Initialization and validation
 - Payment calculations for all four frequencies
@@ -372,6 +523,7 @@ The test suite includes 70 RSpec examples covering:
 - Schedule generation and full amortization
 - Interest methods (simple vs precomputed)
 - Grace periods and interest-only periods
+- Balloon payments across frequencies, interest methods and fees
 - Bank day functionality and federal holiday detection
 - Fee treatments (distributed, add to principal, separate payment)
 - Monthly date drift prevention with bank_days_only
@@ -379,6 +531,9 @@ The test suite includes 70 RSpec examples covering:
 - Public API (schedule, summary, convenience methods)
 - Deep freeze immutability
 - Edge cases (year boundaries, month-end clamping, input validation)
+- Commercial financing disclosures (APR, finance charge, amount financed, all nine elements)
+- Reg Z identity verification across all fee treatment modes
+- APR solver convergence (grace periods, interest-only, short-term, zero-rate loans)
 
 Run the test suite:
 

data/lib/amortizy/console_formatter.rb

@@ -62,6 +62,7 @@ module Amortizy
       puts "Annual Rate: #{format('%.2f', summary[:annual_rate])}%"
       puts "\nOriginal Principal: $#{format('%.2f', summary[:principal])}"
       puts "Regular Payment: $#{format('%.2f', summary[:payment_amount])}"
+      puts "Balloon Payment: $#{format('%.2f', summary[:balloon_amount])}" if summary[:balloon_amount].positive?
       puts "Total Interest Paid: $#{format('%.2f', summary[:total_interest])}"
       puts "Total Amount Paid: $#{format('%.2f', summary[:total_paid])}"
       puts '=' * 195

data/lib/amortizy/disclosure.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+# Commercial Financing Disclosure Calculator
+#
+# Computes disclosure data elements for closed-end commercial loan transactions
+# per California SB 1235 (Title 10, Chapter 3, Subchapter 3). Values are
+# jurisdiction-agnostic — the gem computes numbers, not documents.
+#
+# APR is calculated using the actuarial method per Appendix J of Regulation Z
+# (12 CFR Part 1026), as required by section 940 of the regulation.
+#
+# Key assumption: the origination fee is treated as a prepaid finance charge
+# (deducted from amount financed, included in finance charge).
+#
+# Regulatory references:
+#   - Section 910: Closed-end transaction disclosure contents
+#   - Section 940: APR calculation method
+#   - Section 943: Finance charge definition
+#   - Section 900(a)(1)(B): Amount financed for closed-end transactions
+#   - Section 900(a)(26): Recipient funds
+#   - Section 901(a)(4): Term display formatting
+#   - Section 901(a)(5): APR rounding (nearest 10 basis points)
+#   - Section 955: APR tolerance (1/8 of 1 percentage point)
+
+module Amortizy
+  class Disclosure
+    APR_MAX_ITERATIONS = 100
+    APR_CONVERGENCE_TOLERANCE = 1e-8
+    APR_REG_Z_TOLERANCE = 0.00125 # 1/8 of 1 percentage point
+
+    def initialize(schedule, third_party_payments: 0, prepayment_penalty_max: 0,
+                   additional_prepayment_fees: [])
+      raise ArgumentError, 'First argument must be an Amortizy::AmortizationSchedule' unless schedule.is_a?(Amortizy::AmortizationSchedule)
+
+      @schedule = schedule
+      @third_party_payments = third_party_payments.to_f
+      @prepayment_penalty_max = prepayment_penalty_max.to_f
+      @additional_prepayment_fees = additional_prepayment_fees
+    end
+
+    # --- Finance Charge (§943) ---
+    # Total dollar cost of the financing. Derived from the Reg Z identity:
+    #   Finance Charge = Total Payment Amount - Amount Financed
+    # This ensures the three core disclosure values are always consistent.
+
+    def finance_charge
+      @finance_charge ||= total_payment_amount - amount_financed
+    end
+
+    # --- Amount Financed (§900(a)(1)(B)) ---
+    # Principal + financed amounts - prepaid finance charges (origination fee).
+
+    def amount_financed
+      @amount_financed ||= begin
+        base = principal - origination_fee
+        base += additional_fee if fee_treatment == :add_to_principal
+        base
+      end
+    end
+
+    # --- Total Payment Amount (§910(a)(5)) ---
+
+    def total_payment_amount
+      @schedule.total_paid
+    end
+
+    # --- Payment Amount ---
+
+    def payment_amount
+      @schedule.payment_amount
+    end
+
+    # --- Balloon Payment ---
+    # The final scheduled payment of a balloon loan (regular payment plus the
+    # balloon), or nil when the loan fully amortizes.
+
+    def balloon_payment
+      return nil unless @schedule.balloon_amount.positive?
+
+      @schedule.schedule.last[:total_payment]
+    end
+
+    # --- Payment Frequency ---
+
+    def payment_frequency
+      @schedule.frequency
+    end
+
+    # --- Recipient Funds (§900(a)(26)) ---
+    # Net amount given directly to the borrower.
+
+    def recipient_funds
+      amount_financed - @third_party_payments
+    end
+
+    # --- Term (§901(a)(4)) ---
+
+    def term_days
+      @term_days ||= (@schedule.end_date - disbursement_date).to_i
+    end
+
+    def term_display
+      if term_days <= 365
+        "#{term_days} days"
+      else
+        years = term_days / 365
+        remaining_days = term_days % 365
+        months = (remaining_days / 30.4).round(2)
+        year_label = years == 1 ? 'year' : 'years'
+        month_label = (months - 1.0).abs < 0.005 ? 'month' : 'months'
+        format('%d %s, %.2f %s', years, year_label, months, month_label)
+      end
+    end
+
+    # --- Average Monthly Cost (§910(a)(12)) ---
+    # Only for non-monthly payment frequencies.
+
+    def average_monthly_cost
+      return nil if @schedule.frequency == :monthly
+      return nil if term_days <= 0
+
+      total_payment_amount / (term_days / 30.4)
+    end
+
+    # --- APR (§940) ---
+    # Actuarial method per Appendix J, Regulation Z (12 CFR Part 1026).
+    # Rounded to nearest 10 basis points per §901(a)(5).
+
+    def apr
+      @apr ||= begin
+        raw_apr = calculate_apr
+        round_to_ten_basis_points(raw_apr)
+      end
+    end
+
+    # --- Prepayment (§910(a)(8-10)) ---
+
+    def prepayment
+      @prepayment ||= {
+        has_non_interest_charges: @prepayment_penalty_max.positive?,
+        max_non_interest_finance_charge: @prepayment_penalty_max.positive? ? @prepayment_penalty_max : nil,
+        has_additional_fees: @additional_prepayment_fees.any?,
+        additional_fees: @additional_prepayment_fees
+      }
+    end
+
+    # --- Output Methods ---
+
+    def to_h
+      {
+        amount_financed: amount_financed.round(2),
+        apr: apr,
+        finance_charge: finance_charge.round(2),
+        total_payment_amount: total_payment_amount.round(2),
+        payment_amount: payment_amount.round(2),
+        payment_frequency: payment_frequency,
+        term_days: term_days,
+        term_display: term_display,
+        average_monthly_cost: average_monthly_cost&.round(2),
+        recipient_funds: recipient_funds.round(2),
+        prepayment: prepayment
+      }.merge(balloon_payment ? { balloon_payment: balloon_payment.round(2) } : {})
+    end
+
+    def to_labeled_h
+      {
+        amount_financed: { label: 'Funding Provided', value: amount_financed.round(2) },
+        apr: { label: 'Annual Percentage Rate (APR)', value: apr },
+        finance_charge: { label: 'Finance Charge', value: finance_charge.round(2) },
+        total_payment_amount: { label: 'Total Payment Amount', value: total_payment_amount.round(2) },
+        payment_amount: { label: 'Payment', value: payment_amount.round(2) },
+        payment_frequency: { label: 'Payment Frequency', value: payment_frequency },
+        term_days: { label: 'Term', value: term_display },
+        average_monthly_cost: { label: 'Average Monthly Cost', value: average_monthly_cost&.round(2) },
+        recipient_funds: { label: 'Recipient Funds', value: recipient_funds.round(2) },
+        prepayment: prepayment
+      }.merge(balloon_payment ? { balloon_payment: { label: 'Balloon Payment', value: balloon_payment.round(2) } } : {})
+    end
+
+    private
+
+    def disbursement_date
+      @schedule.start_date
+    end
+
+    def principal
+      @schedule.principal
+    end
+
+    def origination_fee
+      @schedule.origination_fee
+    end
+
+    def additional_fee
+      @schedule.additional_fee
+    end
+
+    def fee_treatment
+      @schedule.additional_fee_treatment
+    end
+
+    # --- APR Calculation ---
+    #
+    # Solves for the annual rate i such that:
+    #   Amount Financed = Σ (Payment_k / (1 + i/365)^(days_k))
+    #
+    # where days_k is the number of days from disbursement to payment k.
+    #
+    # Uses Newton-Raphson with bisection fallback.
+
+    def calculate_apr
+      cash_flows = extract_cash_flows
+      return 0.0 if cash_flows.empty?
+      return 0.0 if amount_financed <= 0
+      return 0.0 if cash_flows.length > 10_000
+
+      # Initial guess: use the nominal annual rate as starting point
+      guess = @schedule.annual_rate
+      guess = 0.10 if guess.zero?
+
+      apr_newton_raphson(cash_flows, guess) || apr_bisection(cash_flows)
+    end
+
+    def extract_cash_flows
+      flows = []
+      start = disbursement_date
+
+      @schedule.schedule.each do |row|
+        payment = row[:total_payment]
+        next if payment.nil? || payment <= 0
+
+        days_from_start = (row[:date] - start).to_i
+        next if days_from_start <= 0
+
+        flows << { days: days_from_start, amount: payment }
+      end
+
+      flows
+    end
+
+    # Present value of all payments at annual rate r, minus amount financed.
+    # When this equals zero, r is the APR.
+    def pv_function(cash_flows, annual_rate)
+      daily_rate = annual_rate / 365.0
+      pv = cash_flows.sum do |cf|
+        cf[:amount] / ((1.0 + daily_rate)**cf[:days])
+      end
+      pv - amount_financed
+    end
+
+    # Derivative of the PV function with respect to annual_rate.
+    def pv_derivative(cash_flows, annual_rate)
+      daily_rate = annual_rate / 365.0
+      cash_flows.sum do |cf|
+        -cf[:days] * cf[:amount] / (365.0 * ((1.0 + daily_rate)**(cf[:days] + 1)))
+      end
+    end
+
+    def apr_newton_raphson(cash_flows, initial_guess)
+      rate = initial_guess
+
+      APR_MAX_ITERATIONS.times do
+        f = pv_function(cash_flows, rate)
+        f_prime = pv_derivative(cash_flows, rate)
+
+        return rate * 100.0 if f.abs < APR_CONVERGENCE_TOLERANCE
+        return nil if f_prime.abs < 1e-15 # derivative too small, switch to bisection
+
+        step = f / f_prime
+        rate -= step
+
+        # Guard against negative rates or runaway
+        return nil if rate <= -1.0 / 365.0
+        return nil if rate > 10.0 # 1000% APR cap — something went wrong
+      end
+
+      nil # didn't converge
+    end
+
+    def apr_bisection(cash_flows)
+      low = -0.001
+      high = 10.0
+
+      # Ensure the interval brackets the root
+      f_low = pv_function(cash_flows, low)
+      f_high = pv_function(cash_flows, high)
+
+      # If both same sign, try expanding
+      if (f_low * f_high).positive?
+        high = 50.0
+        f_high = pv_function(cash_flows, high)
+        return 0.0 if (f_low * f_high).positive?
+      end
+
+      (APR_MAX_ITERATIONS * 5).times do
+        mid = (low + high) / 2.0
+        f_mid = pv_function(cash_flows, mid)
+
+        return mid * 100.0 if f_mid.abs < APR_CONVERGENCE_TOLERANCE
+
+        if (f_low * f_mid).negative?
+          high = mid
+        else
+          low = mid
+          f_low = f_mid
+        end
+      end
+
+      ((low + high) / 2.0) * 100.0
+    end
+
+    def round_to_ten_basis_points(apr_percent)
+      (apr_percent * 10).round / 10.0
+    end
+  end
+end

data/lib/amortizy/engine.rb

@@ -5,6 +5,7 @@
 # Generates comprehensive loan amortization schedules with support for:
 # - Grace periods with capitalized interest
 # - Interest-only payment periods
+# - Balloon payments due at maturity
 # - Origination and additional fees
 # - Simple or precomputed interest methods
 # - Bank business day calculations (Federal Reserve holidays)
@@ -16,12 +17,15 @@ require 'holidays'
 
 module Amortizy
   class AmortizationSchedule
-    attr_reader :start_date, :principal, :term_months, :annual_rate, :frequency, :additional_fee_label
+    DECIMAL_STRING = /\A\s*[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?\s*\z/
+    private_constant :DECIMAL_STRING
+    attr_reader :start_date, :principal, :term_months, :annual_rate, :frequency, :additional_fee_label,
+                :origination_fee, :additional_fee, :additional_fee_treatment, :balloon_amount
 
     def initialize(start_date:, principal:, annual_rate:, frequency:, term_months: nil, num_payments: nil,
                    origination_fee: 0, additional_fee: 0, additional_fee_label: 'Additional Fee',
                    additional_fee_treatment: :distributed, bank_days_only: false, interest_only_periods: 0,
-                   grace_period_days: 0, interest_method: :simple)
+                   grace_period_days: 0, interest_method: :simple, balloon_amount: 0)
       @start_date = Date.parse(start_date.to_s)
       @principal = principal.to_f
       @annual_rate = annual_rate.to_f / 100.0
@@ -34,6 +38,7 @@ module Amortizy
       @interest_only_periods = interest_only_periods.to_i
       @grace_period_days = grace_period_days.to_i
       @interest_method = interest_method.to_sym
+      @balloon_amount = parse_balloon_amount(balloon_amount)
 
       validate_principal!
       validate_frequency!
@@ -41,6 +46,7 @@ module Amortizy
       validate_fee_treatment!
       validate_interest_only_periods!
       validate_interest_method!
+      validate_balloon_amount!
     end
 
     def generate(output: :console, csv_path: nil)
@@ -70,6 +76,7 @@ module Amortizy
         frequency: @frequency,
         annual_rate: @annual_rate * 100.0,
         payment_amount: payment_amount,
+        balloon_amount: @balloon_amount,
         total_interest: total_interest,
         total_paid: total_paid
       }
@@ -141,6 +148,26 @@ module Amortizy
       raise ArgumentError, 'Interest method must be :simple or :precomputed'
     end
 
+    def parse_balloon_amount(value)
+      return 0.0 if value.nil?
+      raise ArgumentError if value.is_a?(String) && !value.match?(DECIMAL_STRING)
+
+      amount = Float(value)
+      return amount if amount.finite?
+
+      raise ArgumentError
+    rescue ArgumentError, TypeError, RangeError
+      raise ArgumentError, "balloon_amount must be a number, got #{value.inspect}"
+    end
+
+    def validate_balloon_amount!
+      raise ArgumentError, 'balloon_amount must not be negative' if @balloon_amount.negative?
+      return if @balloon_amount < effective_principal
+
+      raise ArgumentError,
+            "balloon_amount must be less than the amortized balance (#{format('%.2f', effective_principal)})"
+    end
+
     def total_payments
       @num_payments
     end
@@ -250,7 +277,7 @@ module Amortizy
       principal_payments = num - @interest_only_periods
 
       if @interest_method == :precomputed
-        principal_payment_portion = effective_principal / principal_payments
+        principal_payment_portion = (effective_principal - @balloon_amount) / principal_payments
         interest_portion = precomputed_interest_per_payment
 
         if @additional_fee_treatment == :distributed
@@ -259,15 +286,7 @@ module Amortizy
           principal_payment_portion + interest_portion
         end
       else
-        days_per_period = calculate_average_days_per_period
-        period_rate = (@annual_rate / 365.0) * days_per_period
-
-        base_payment = if period_rate.zero?
-                         effective_principal / principal_payments
-                       else
-                         effective_principal * (period_rate * ((1 + period_rate)**principal_payments)) /
-                           (((1 + period_rate)**principal_payments) - 1)
-                       end
+        base_payment = level_payment
 
         if @additional_fee_treatment == :distributed
           base_payment + (@additional_fee / num)
@@ -277,6 +296,62 @@ module Amortizy
       end
     end
 
+    # The level payment that leaves the balloon (zero for a fully amortizing loan)
+    # outstanding with the final payment, when interest is charged on each
+    # period's actual days. Interest-only periods leave the balance unchanged, so
+    # only the amortizing periods count. Each period grows the balance by
+    # (1 + r_k), which makes the final balance linear in the payment:
+    #
+    #   payment = (balance * prod(1 + r_k) - balloon) / sum_k prod_{i>k}(1 + r_i)
+    def level_payment
+      growth = 1.0
+      payments_value = 0.0
+      amortizing_period_rates.reverse_each do |rate|
+        payments_value += growth
+        growth *= 1 + rate
+      end
+      ((effective_principal * growth) - @balloon_amount) / payments_value
+    end
+
+    def amortizing_period_rates
+      previous_date = first_regular_period_start
+      rates = regular_payment_dates.map do |date|
+        rate = (@annual_rate / 365.0) * calculate_days_between(previous_date, date)
+        previous_date = date
+        rate
+      end
+      rates.drop(@interest_only_periods)
+    end
+
+    def separate_fee_payment?
+      @additional_fee_treatment == :separate_payment && @additional_fee.positive?
+    end
+
+    def separate_fee_date
+      next_payment_date(first_payment_date)
+    end
+
+    def first_regular_period_start
+      separate_fee_payment? ? separate_fee_date : first_payment_date
+    end
+
+    # For monthly frequency, track the target date separately from the actual
+    # payment date to prevent bank-day adjustments from compounding drift.
+    def regular_payment_dates
+      @regular_payment_dates ||= begin
+        monthly_target = first_payment_date
+        previous_date = first_regular_period_start
+        Array.new(total_payments) do
+          if @frequency == :monthly
+            monthly_target = advance_by_month(monthly_target)
+            previous_date = next_bank_day(monthly_target)
+          else
+            previous_date = next_payment_date(previous_date)
+          end
+        end.freeze
+      end
+    end
+
     def federal_holiday?(date)
       holidays = Holidays.on(date, :federalreserve, :observed)
       !holidays.empty?
@@ -329,7 +404,6 @@ module Amortizy
       payment_amount = calculate_payment
       balance = effective_principal
       accrued_interest = 0.0
-      payment_date = first_payment_date
       previous_payment_date = first_payment_date
       payment_number = 0
       num = total_payments
@@ -353,8 +427,8 @@ module Amortizy
         }
       end
 
-      if @additional_fee_treatment == :separate_payment && @additional_fee.positive?
-        payment_date = next_payment_date(payment_date)
+      if separate_fee_payment?
+        payment_date = separate_fee_date
         schedule_data << {
           payment_number: 0,
           date: payment_date,
@@ -374,20 +448,10 @@ module Amortizy
       additional_fee_per_payment = @additional_fee_treatment == :distributed ? (@additional_fee / num) : 0.0
       precomputed_interest = @interest_method == :precomputed ? precomputed_interest_per_payment : 0.0
 
-      # For monthly frequency, track the target date separately from the actual
-      # payment date to prevent bank-day adjustments from compounding drift.
-      monthly_target = @frequency == :monthly ? first_payment_date : nil
-
       while payment_number < num && balance > 0.01
+        payment_date = regular_payment_dates[payment_number]
         payment_number += 1
 
-        if @frequency == :monthly && monthly_target
-          monthly_target = advance_by_month(monthly_target)
-          payment_date = next_bank_day(monthly_target)
-        else
-          payment_date = next_payment_date(previous_payment_date)
-        end
-
         days_in_period = calculate_days_between(previous_payment_date, payment_date)
 
         if @interest_method == :precomputed
@@ -406,7 +470,7 @@ module Amortizy
         else
           principal_payment = [payment_amount - interest_payment - additional_fee_per_payment, balance].min
           principal_payment = balance if payment_number == num
-          payment_type = 'Regular Payment'
+          payment_type = payment_number == num && @balloon_amount.positive? ? 'Balloon Payment' : 'Regular Payment'
         end
 
         total_payment = principal_payment + interest_payment + additional_fee_per_payment

data/lib/amortizy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Amortizy
-  VERSION = '2.0.0'
+  VERSION = '3.1.1'
 end

data/lib/amortizy.rb

@@ -4,6 +4,7 @@ require_relative 'amortizy/version'
 require_relative 'amortizy/engine'
 require_relative 'amortizy/console_formatter'
 require_relative 'amortizy/csv_formatter'
+require_relative 'amortizy/disclosure'
 
 module Amortizy
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amortizy
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Rich Zapata
@@ -15,17 +15,17 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '11.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '11.7'
 description: Generate loan amortization schedules with monthly, bi-weekly, weekly,
-  or daily payments. Supports grace periods, interest-only payments, federal bank
-  holidays, and multiple interest calculation methods.
+  or daily payments. Supports grace periods, interest-only payments, balloon payments,
+  federal bank holidays, and multiple interest calculation methods.
 email:
 - rzapata@gmail.com
 executables: []
@@ -40,10 +40,10 @@ files:
 - lib/amortizy.rb
 - lib/amortizy/console_formatter.rb
 - lib/amortizy/csv_formatter.rb
+- lib/amortizy/disclosure.rb
 - lib/amortizy/engine.rb
 - lib/amortizy/version.rb
 - sig/amortizy.rbs
-- tasks/todo.md
 homepage: https://github.com/zapatify/amortizy
 licenses:
 - MIT
@@ -60,7 +60,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/tasks/todo.md

@@ -1,74 +0,0 @@
-# Amortizy v2.0 — Dynamic Payment Model
-
-## Goal
-
-Replace the hardcoded term/payment lookup table with a dynamic calculation engine.
-Support two entry points: `term_months` (calculate payment count) or `num_payments`
-(calculate end date). Add monthly and bi-weekly frequencies.
-
----
-
-## Phase 1: Dynamic Payment Engine
-
-### 1.1 Dual input model
-- [ ] Accept `term_months` OR `num_payments` — one required, not both
-- [ ] Validate: raise `ArgumentError` if both provided, or neither
-- [ ] When `term_months` given: calculate `num_payments` from frequency
-  - monthly: `term_months`
-  - bi-weekly: `term_months * 2` (approx 26/year)
-  - weekly: `term_months * 52 / 12` (rounded)
-  - daily: calculate actual business/calendar days in the term
-- [ ] When `num_payments` given: calculate end date by walking the payment schedule forward
-- [ ] Remove the hardcoded `calculate_total_payments` lookup table
-- [ ] Remove `validate_term_months!` (any positive integer is now valid)
-
-### 1.2 New frequencies
-- [ ] Add `:monthly` frequency — payment on same day each month (or last business day)
-- [ ] Add `:biweekly` frequency — every 14 days
-- [ ] Update `validate_frequency!` to accept all four
-- [ ] Handle month-end edge cases for monthly (e.g., start Jan 31 — Feb payment is Feb 28)
-
-### 1.3 Dynamic day calculation
-- [ ] Replace static payment counts with actual date walking
-- [ ] For daily + `bank_days_only`: count actual business days in the term
-- [ ] For weekly/biweekly: walk forward by 7/14 days, skip to next bank day if needed
-- [ ] For monthly: advance by calendar month, adjust for bank days
-
-## Phase 2: Public API Cleanup
-
-### 2.1 Expose schedule data
-- [ ] Make `generate_schedule_data` public, rename to `schedule` or `to_a`
-- [ ] Return frozen array of payment hashes
-- [ ] Add `summary` method — returns hash with totals, dates, payment count
-- [ ] Remove `send(:generate_schedule_data)` from README examples
-
-### 2.2 Convenience methods
-- [ ] `#end_date` — last payment date
-- [ ] `#total_interest` — sum of all interest payments
-- [ ] `#total_paid` — sum of all payments
-- [ ] `#payment_amount` — make public (currently private)
-
-## Phase 3: Extract Formatters
-
-- [ ] Extract `ConsoleFormatter` — takes schedule data, renders table
-- [ ] Extract `CsvFormatter` — takes schedule data, writes CSV
-- [ ] `generate(output:)` delegates to formatter
-- [ ] Engine class focuses on math only
-
-## Phase 4: Polish
-
-- [ ] Fix README broken markdown in Development section
-- [ ] Update README examples for new API
-- [ ] Update gemspec description
-- [ ] Add CHANGELOG entry for v2.0
-- [ ] Bump version
-- [ ] Update Ruby requirement to >= 3.0
-- [ ] Run full spec suite, update/add specs for new features
-
----
-
-## Breaking changes (v2.0)
-
-- `term_months` no longer restricted to [6, 9, 12, 15, 18]
-- `generate_schedule_data` renamed to public method
-- New frequencies may change default behavior for existing users (unlikely — additive)