amortizy 2.1.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00f0ccad91127633326557a81254c429737b526a834bb18de2235b842390f7ef
-  data.tar.gz: fcf4c2b4d999c1c276446fb36ea85984c7d380b4819b9592f55afcdb405985d2
+  metadata.gz: 580f55e8a6cadb029944b8fec559b2f280cbcee6c5452f2c132dd3fa314c0cec
+  data.tar.gz: b3c68e7a5f0f9c35536754c1a4e665cef3ae814b358128e59747be1d735ca2de
 SHA512:
-  metadata.gz: 73e33d2c4a0ee6f0ab15d9618d4aa53df5bbbe16608630f125dac377e674e82bf8c576362e492257692c928b6ec0328781cd91c752a57b8d55c36946154fb804
-  data.tar.gz: 0c9e25aabdceee720c8fb6fcf2367b101fbce214642e4be84022f0ea2ca166478ea2bbeb190018bca41c03fe63b5e87963e5c79f1fc23b4b333cea71d72d8314
+  metadata.gz: 05a7f4cb9713cefefa2036f9cc6a0b906601b3bf4d143cb1b76338c040f3b804c313f25a46dd4bf88992bb97883b42842b5729815d77d1c12c24ce64f2372cc4
+  data.tar.gz: aa4e32281172160851e5c84d364229ef18e8e4a7e07f1849022cff3734e64db6fc7068f1ea301c1bd0eaae0c2ee95fd0ca40c1a0f3d58be019ae7203de4f3fa0

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.2] - 2026-10-21
+
+### Fixed
+- `additional_fee_treatment: :separate_payment` no longer gives the borrower an interest-free period (#13). Interest accrues from funding, so the first regular payment includes the fee period's interest, on every frequency. Precomputed interest also counts the fee period
+- Monthly loans with a separate fee now put payment 1 one month after the fee instead of on the fee date, matching the other frequencies. These loans now mature one month later (e.g. `term_months: 12` ends in month 13)
+
+## [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

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,12 +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
 - **Commercial financing disclosures**: APR (Reg Z actuarial method), finance charge, amount financed, and more
-- **Testing**: 120 RSpec tests
+- **Tested**: RSpec suite covering every option above
 
 ## Installation
 
@@ -62,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
@@ -94,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(
@@ -136,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.
 
@@ -157,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:
@@ -182,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
 }
 ```
 
@@ -195,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`)
 
@@ -228,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. Regular payments begin one period after the fee. Interest accrues from funding, so the first regular payment carries the interest for the fee's period as well as its own, and the loan matures one period after `term_months`.
 
 **Best for:** Collecting fees upfront separately from the loan repayment
 
@@ -240,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
 
@@ -328,12 +387,14 @@ schedule.generate(output: :csv, csv_path: "commercial_loan.csv")
 
 ## Commercial Financing Disclosures
 
-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.). Values are jurisdiction-agnostic — computed per the most stringent methodology, usable for any state.
+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.
 
 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
@@ -350,12 +411,12 @@ schedule = Amortizy::AmortizationSchedule.new(
 
 disclosure = Amortizy::Disclosure.new(schedule)
 
-disclosure.apr                   # => 12.3 (Reg Z actuarial method, 10 bps precision)
-disclosure.finance_charge        # => 11119.65
+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  # => 60619.65
+disclosure.total_payment_amount  # => 60623.13
 disclosure.recipient_funds       # => 49500.0
-disclosure.term_display          # => "3 years, 0.20 months"
+disclosure.term_display          # => "3 years, 0.03 months"
 disclosure.average_monthly_cost  # => nil (monthly frequency)
 disclosure.prepayment            # => { has_non_interest_charges: false, ... }
 ```
@@ -387,14 +448,14 @@ disclosure.prepayment
 ```ruby
 # Raw values
 disclosure.to_h
-# => { amount_financed: 49500.0, apr: 12.3, finance_charge: 11119.65, ... }
+# => { 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: 12.3 },
-#   finance_charge: { label: "Finance Charge", value: 11119.65 },
+#   apr: { label: "Annual Percentage Rate (APR)", value: 13.6 },
+#   finance_charge: { label: "Finance Charge", value: 11123.13 },
 #   ...
 # }
 ```
@@ -416,6 +477,7 @@ disclosure.to_labeled_h
 | 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) |
@@ -427,23 +489,10 @@ disclosure.to_labeled_h
 - **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.
 
-## Command Line Interface
-
-Amortizy includes an interactive CLI tool:
-
-```bash
-amortizy
-```
-
-The CLI provides:
-1. Run default examples (demonstrates simple vs precomputed interest)
-2. Enter parameters manually with interactive prompts
-3. Automatic CSV generation option
-
 ## 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
 
@@ -465,7 +514,7 @@ bin/console
 
 ## Testing
 
-The test suite includes 120 RSpec examples covering:
+The RSpec suite covers:
 
 - Initialization and validation
 - Payment calculations for all four frequencies
@@ -474,6 +523,7 @@ The test suite includes 120 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

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

@@ -70,6 +70,16 @@ module Amortizy
       @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
@@ -149,7 +159,7 @@ module Amortizy
         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
@@ -164,7 +174,7 @@ module Amortizy
         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

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,13 +17,15 @@ require 'holidays'
 
 module Amortizy
   class AmortizationSchedule
+    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
+                :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
@@ -35,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!
@@ -42,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)
@@ -71,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
       }
@@ -142,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
@@ -199,10 +225,10 @@ module Amortizy
       total_days.to_f / sample_size
     end
 
+    # A separate fee row takes a period of its own, and interest accrues through it.
     def estimate_total_loan_days
-      num = total_payments
-      avg_days_per_period = calculate_average_days_per_period
-      num * avg_days_per_period
+      periods = total_payments + (separate_fee_payment? ? 1 : 0)
+      periods * calculate_average_days_per_period
     end
 
     def calculate_precomputed_total_interest
@@ -251,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
@@ -260,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)
@@ -278,6 +296,67 @@ 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
+
+    # Interest accrues from funding (or the end of the grace period). A separate
+    # fee row collects no interest, so the first regular payment carries the
+    # interest for the fee's period too.
+    def amortizing_period_rates
+      previous_date = first_payment_date
+      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
+        # A separate fee takes the first period, so regular payments start a
+        # month after the fee's (unadjusted) target date.
+        monthly_target = separate_fee_payment? ? advance_by_month(first_payment_date) : 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?
@@ -330,7 +409,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
@@ -354,8 +432,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,
@@ -369,26 +447,15 @@ module Amortizy
           payment_type: 'Additional Fee Payment',
           days_in_period: 0
         }
-        previous_payment_date = payment_date
       end
 
       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
@@ -407,7 +474,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.1.0'
+  VERSION = '3.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amortizy
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.1.2
 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: []
@@ -44,7 +44,6 @@ files:
 - lib/amortizy/engine.rb
 - lib/amortizy/version.rb
 - sig/amortizy.rbs
-- tasks/todo.md
 homepage: https://github.com/zapatify/amortizy
 licenses:
 - MIT
@@ -61,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,203 +0,0 @@
-# Amortizy v2.1 — Commercial Financing Disclosure Module
-
-## Goal
-
-Add a `Disclosure` class that computes California SB 1235 disclosure data elements
-for closed-end commercial loan transactions. The gem exposes jurisdiction-agnostic
-numbers — APR (Reg Z actuarial method), finance charge, amount financed, recipient
-funds, term, average monthly cost, and prepayment info — queryable via a clean API.
-
-**Design decisions:**
-- `Amortizy::Disclosure` is a separate class that wraps an `AmortizationSchedule`
-- Origination fee is treated as a prepaid finance charge by default (deducted from
-  amount financed, included in finance charge) — must be documented
-- No state/jurisdiction parameters — data elements are universal
-- No document formatting — the gem computes numbers, not PDFs
-- Scoped to closed-end transactions only (no MCA, factoring, leases, open-end)
-
-**Regulatory references:**
-- Section 910: Closed-end transaction disclosure contents
-- Section 940: APR calculation (Appendix J, 12 CFR Part 1026 — actuarial method)
-- Section 943: Finance charge definition
-- Section 900(a)(1)(B): Amount financed for closed-end transactions
-- Section 900(a)(26): Recipient funds
-- Section 955: APR tolerance (1/8 of 1 percentage point)
-
----
-
-## Phase 1: Disclosure Class Skeleton
-
-### 1.1 Create `lib/amortizy/disclosure.rb`
-- [ ] Define `Amortizy::Disclosure` class
-- [ ] Accept `AmortizationSchedule` as first argument
-- [ ] Accept keyword args: `third_party_payments: 0`, `prepayment_penalty_max: 0`,
-      `additional_prepayment_fees: []`
-- [ ] Validate that schedule argument is an `AmortizationSchedule`
-- [ ] Store schedule reference and disclosure-specific params
-
-### 1.2 Wire into gem
-- [ ] Add `require_relative 'amortizy/disclosure'` to `lib/amortizy.rb`
-- [ ] Create `spec/disclosure_spec.rb` with basic instantiation tests
-
----
-
-## Phase 2: Simple Computed Properties
-
-These derive directly from existing schedule data with minimal new logic.
-
-### 2.1 Finance Charge (§943)
-- [ ] `#finance_charge` — total dollar cost of financing
-- [ ] Calculation: `total_interest + origination_fee + additional_fee`
-- [ ] All charges that would be included under 12 CFR 1026.4 if this were consumer credit
-- [ ] Spec: verify against known loan (e.g., $50K, 12%, 36mo, $500 orig fee, $250 addl fee)
-
-### 2.2 Amount Financed (§900(a)(1)(B))
-- [ ] `#amount_financed` — principal + financed amounts - prepaid finance charges
-- [ ] For closed-end: `principal + additional_fee (if add_to_principal) - origination_fee`
-- [ ] Origination fee treated as prepaid finance charge (deducted)
-- [ ] Additional fee treatment depends on `additional_fee_treatment` setting:
-  - `:distributed` or `:separate_payment` → not added to amount financed
-  - `:add_to_principal` → added to amount financed
-- [ ] Spec: test all three fee treatment scenarios
-
-### 2.3 Total Payment Amount (§910(a)(5))
-- [ ] `#total_payment_amount` — delegates to `schedule.total_paid`
-- [ ] Spec: verify matches schedule total
-
-### 2.4 Recipient Funds (§900(a)(26))
-- [ ] `#recipient_funds` — net amount given directly to the borrower
-- [ ] Calculation: `amount_financed - third_party_payments`
-- [ ] Spec: with and without third-party payments
-
-### 2.5 Term Display (§901(a)(4))
-- [ ] `#term_days` — total days from start to last payment
-- [ ] `#term_display` — formatted per regulation:
-  - Term <= 1 year: display in days (e.g., "270 days")
-  - Term > 1 year: display in years and months, remainder as decimal
-    (e.g., "2 years, 3.15 months")
-- [ ] Spec: test boundary at exactly 365 days, and multi-year terms
-
-### 2.6 Average Monthly Cost (§910(a)(12))
-- [ ] `#average_monthly_cost` — total payments / (term_days / 30.4)
-- [ ] Returns `nil` for monthly frequency (only required for non-monthly)
-- [ ] Spec: weekly and biweekly loans, verify nil for monthly
-
----
-
-## Phase 3: APR Calculation (§940)
-
-The core engineering work. APR per Appendix J of Regulation Z (12 CFR Part 1026).
-
-### 3.1 Actuarial method solver
-- [ ] Implement APR calculation using the actuarial method
-- [ ] The APR is the rate `i` that satisfies:
-      `Amount Financed = Σ (Payment_k / (1 + i)^(t_k / 365))`
-      where `t_k` is the number of days from disbursement to payment k
-- [ ] Use Newton-Raphson iteration to solve for `i`
-- [ ] Convergence tolerance: 1/8 of 1 percentage point (0.00125) per §955
-- [ ] Maximum iterations: 100 (with fallback to bisection if Newton diverges)
-- [ ] Cash flows: amount financed is the initial advance (positive);
-      each scheduled payment is an outflow (negative)
-- [ ] Include all finance charge components in the payment stream
-
-### 3.2 Cash flow extraction
-- [ ] Extract payment dates and amounts from the schedule
-- [ ] Include separate_payment additional fees in the stream
-- [ ] Include grace period payments if any
-- [ ] Disbursement date = schedule start_date
-- [ ] Each payment: { date:, amount: } from schedule rows
-
-### 3.3 APR formatting
-- [ ] `#apr` — returns APR as a percentage rounded to nearest 10 basis points (§901(a)(5))
-      e.g., 14.8, 14.85, not 14.8532
-- [ ] Spec: verify against known Reg Z examples
-- [ ] Spec: tolerance check — result within 1/8 percentage point of exact
-
-### 3.4 Edge cases
-- [ ] Zero-interest loans (APR should reflect fees only)
-- [ ] Loans with grace periods (disbursement date vs first payment date gap)
-- [ ] Interest-only periods followed by amortizing payments
-- [ ] Precomputed interest method
-- [ ] Very short terms (< 30 days)
-- [ ] Very long terms (> 10 years)
-
----
-
-## Phase 4: Prepayment Information (§910(a)(8-10))
-
-### 4.1 Prepayment hash
-- [ ] `#prepayment` — returns hash:
-      ```ruby
-      {
-        has_non_interest_charges: true/false,
-        max_non_interest_finance_charge: Float or nil,
-        has_additional_fees: true/false,
-        additional_fees: [] # array of { amount:, description: } hashes
-      }
-      ```
-- [ ] Derived from `prepayment_penalty_max` and `additional_prepayment_fees` inputs
-- [ ] Spec: all four combinations (charges/no charges x fees/no fees)
-
----
-
-## Phase 5: Output Methods
-
-### 5.1 `#to_h`
-- [ ] Returns flat hash of all computed values:
-      ```ruby
-      {
-        amount_financed:, apr:, finance_charge:, total_payment_amount:,
-        payment_amount:, payment_frequency:, term_days:, term_display:,
-        average_monthly_cost:, recipient_funds:, prepayment:
-      }
-      ```
-- [ ] All monetary values as Float, rounded to 2 decimal places
-- [ ] Spec: verify all keys present, types correct
-
-### 5.2 `#to_labeled_h`
-- [ ] Returns hash with regulation-correct labels:
-      ```ruby
-      {
-        amount_financed: { label: "Funding Provided", value: 50_250.00 },
-        apr: { label: "Annual Percentage Rate (APR)", value: 14.85 },
-        finance_charge: { label: "Finance Charge", value: 10_432.50 },
-        ...
-      }
-      ```
-- [ ] Labels follow §910 column 1 text for fixed-rate closed-end transactions
-- [ ] Spec: verify exact label strings match regulation text
-
----
-
-## Phase 6: Documentation & Polish
-
-### 6.1 README updates
-- [ ] Add Disclosure section to README with usage examples
-- [ ] Document the origination fee = prepaid finance charge assumption
-- [ ] Document regulatory references (CA SB 1235, sections 910/940/943)
-- [ ] Note that labels follow California regulation but values are jurisdiction-agnostic
-
-### 6.2 CHANGELOG
-- [ ] Add v2.1.0 entry documenting the disclosure module
-
-### 6.3 Version bump
-- [ ] Bump version to 2.1.0 in `version.rb`
-
-### 6.4 Final spec run
-- [ ] Full suite green — existing specs unaffected
-- [ ] Disclosure specs comprehensive — all nine data elements tested
-- [ ] APR accuracy verified against at least 3 known Reg Z examples
-
----
-
-## Out of Scope
-
-- MCA / sales-based financing disclosures (§914)
-- Factoring disclosures (§912, §913)
-- Open-end credit plan disclosures (§911)
-- Lease financing disclosures (§915)
-- Asset-based lending disclosures (§916)
-- Disclosure document generation (PDF/HTML formatting)
-- Jurisdiction detection or state-specific logic
-- Adjustable rate APR estimation (amortizy only does fixed-rate)
-- Retrospective APR auditing (§931)