amortizy 1.0.0 → 2.0.0

data/README.md

@@ -1,43 +1,414 @@
 # Amortizy
 
-TODO: Delete this and the text below, and describe your gem
+[![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)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/amortizy`. To experiment with that code, run `bin/console` for an interactive prompt.
+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.
+
+Perfect for financial applications, lending platforms, and loan calculators.
+
+## Features
+
+- **Multiple payment frequencies**: Monthly, bi-weekly, weekly, or daily payments
+- **Flexible loan terms**: Any term length in months, or specify an exact payment count
+- **Dual input model**: Provide `term_months` (gem calculates payment count) or `num_payments` (you specify exactly how many)
+- **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
+- **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
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'amortizy'
+```
+
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install amortizy
+```
+
+## Quick Start
+
+### Monthly Loan (most common)
+
+```ruby
+require 'amortizy'
+
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 100_000.00,
+  term_months: 12,
+  annual_rate: 10.0,
+  frequency: :monthly
+)
+
+# Display in console
+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.end_date         # => #<Date: 2027-01-15>
+
+# Get the full schedule as an array of hashes
+schedule.schedule.each do |payment|
+  puts "#{payment[:date]} - $#{'%.2f' % payment[:total_payment]}"
+end
+
+# Generate CSV file
+schedule.generate(output: :csv, csv_path: "schedule.csv")
 ```
 
-## Usage
+### Specify Exact Payment Count
+
+Instead of a term length, tell the gem exactly how many payments you want:
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 50_000.00,
+  num_payments: 26,
+  annual_rate: 12.0,
+  frequency: :biweekly
+)
+
+schedule.schedule.length    # => 26
+schedule.end_date           # => the date of the 26th payment
+schedule.term_months        # => nil (not applicable when using num_payments)
+```
+
+### Advanced Example with All Features
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 100_000.00,
+  term_months: 12,
+  annual_rate: 17.75,
+  frequency: :monthly,
+  origination_fee: 10_000.00,
+  additional_fee: 2_500.00,
+  additional_fee_label: "Processing Fee",
+  additional_fee_treatment: :distributed,
+  bank_days_only: true,
+  interest_only_periods: 3,
+  grace_period_days: 3,
+  interest_method: :simple
+)
+
+schedule.generate
+```
+
+## API Reference
+
+### Initialization Parameters
+
+| Parameter | Type | Required | Default | Options | Description |
+|-----------|------|----------|---------|---------|-------------|
+| `start_date` | String/Date | Yes | - | YYYY-MM-DD | Loan start date |
+| `principal` | Float | Yes | - | > 0 | Loan principal amount |
+| `term_months` | Integer | One of* | - | Any positive integer | Loan term in months |
+| `num_payments` | Integer | One of* | - | Any positive integer | Exact number of payments |
+| `annual_rate` | Float | Yes | - | - | Annual interest rate (%) |
+| `frequency` | Symbol | Yes | - | `:monthly`, `:biweekly`, `:weekly`, `:daily` | Payment frequency |
+| `origination_fee` | Float | No | 0 | - | Fee added to principal |
+| `additional_fee` | Float | No | 0 | - | Additional processing fee |
+| `additional_fee_label` | String | No | "Additional Fee" | - | Label for additional fee |
+| `additional_fee_treatment` | Symbol | No | `:distributed` | `:distributed`, `:add_to_principal`, `:separate_payment` | How to handle additional fee |
+| `bank_days_only` | Boolean | No | false | - | Skip weekends and holidays |
+| `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 |
+
+*Provide either `term_months` or `num_payments`, not both.
+
+### Public Methods
+
+#### `#generate(output: :console, csv_path: nil)`
+
+Render the schedule to console or CSV file.
+
+```ruby
+schedule.generate                                          # console output
+schedule.generate(output: :csv, csv_path: "schedule.csv")  # CSV file
+```
+
+#### `#schedule`
+
+Returns a frozen array of payment hashes. Each hash contains:
+
+```ruby
+{
+  payment_number: 1,
+  date: #<Date>,
+  principal_payment: 8302.48,
+  interest_payment: 489.11,
+  additional_fee_payment: 0.0,
+  total_payment: 8791.59,
+  principal_balance: 91697.52,
+  accrued_interest: 489.11,
+  total_balance: 92186.63,
+  payment_type: "Regular Payment",
+  days_in_period: 29
+}
+```
+
+#### `#summary`
+
+Returns a hash with loan totals:
+
+```ruby
+{
+  start_date: #<Date>,
+  end_date: #<Date>,
+  principal: 100000.0,
+  total_payments: 12,
+  frequency: :monthly,
+  annual_rate: 10.0,
+  payment_amount: 8791.59,
+  total_interest: 5499.06,
+  total_paid: 105499.06
+}
+```
+
+#### Convenience Methods
+
+| Method | Returns |
+|--------|---------|
+| `#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 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).
+
+### Bi-weekly (`:biweekly`)
+
+Payments every 14 days. Common for payroll-aligned loan repayment.
+
+### Weekly (`:weekly`)
+
+Payments every 7 days.
+
+### Daily (`:daily`)
+
+Payments every day. When combined with `bank_days_only: true`, payments skip weekends and federal holidays.
+
+## Fee Treatment Options
+
+### 1. Distributed (`:distributed`)
+The fee is spread evenly across all payments.
+
+**Best for:** Keeping individual payments manageable while recovering fees over time
+
+### 2. Add to Principal (`:add_to_principal`)
+The fee is added to the loan principal upfront, increasing the base amount financed.
+
+**Best for:** Rolling all costs into the loan amount
 
-TODO: Write usage instructions here
+### 3. Separate Payment (`:separate_payment`)
+The fee is collected as a separate first payment before regular amortization begins.
+
+**Best for:** Collecting fees upfront separately from the loan repayment
+
+## Interest Calculation Methods
+
+### Simple Interest (`:simple`)
+
+Interest accrues daily on the remaining principal balance. As you pay down the principal, interest payments decrease over time.
+
+**Formula:** Daily interest = (Principal Balance x Annual Rate) / 365
+
+**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.
+
+**Best for:** Fixed payment structures, certain consumer loan types
+
+## 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.
+
+## Usage Examples
+
+### 30-Year Mortgage
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 350_000.00,
+  term_months: 360,
+  annual_rate: 6.5,
+  frequency: :monthly
+)
+
+puts "Monthly payment: $#{'%.2f' % schedule.payment_amount}"
+puts "Total interest: $#{'%.2f' % schedule.total_interest}"
+```
+
+### Weekly Loan with Grace Period
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 75_000.00,
+  term_months: 12,
+  annual_rate: 15.0,
+  frequency: :weekly,
+  grace_period_days: 7
+)
+
+schedule.generate
+```
+
+### Interest-Only with Bank Days
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 100_000.00,
+  term_months: 18,
+  annual_rate: 10.0,
+  frequency: :weekly,
+  interest_only_periods: 8,
+  bank_days_only: true
+)
+
+schedule.generate
+```
+
+### Complex Commercial Loan
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 250_000.00,
+  term_months: 18,
+  annual_rate: 14.5,
+  frequency: :daily,
+  origination_fee: 25_000.00,
+  additional_fee: 5_000.00,
+  additional_fee_label: "Processing Fee",
+  additional_fee_treatment: :distributed,
+  bank_days_only: true,
+  interest_only_periods: 20,
+  grace_period_days: 5,
+  interest_method: :simple
+)
+
+schedule.generate(output: :csv, csv_path: "commercial_loan.csv")
+```
+
+## 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
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Run linter
+bundle exec rubocop
+
+# Run interactive console
+bin/console
+```
+
+## Testing
+
+The test suite includes 70 RSpec examples covering:
+
+- Initialization and validation
+- Payment calculations for all four frequencies
+- Dual input model (term_months vs num_payments)
+- Effective principal calculations
+- Schedule generation and full amortization
+- Interest methods (simple vs precomputed)
+- Grace periods and interest-only periods
+- Bank day functionality and federal holiday detection
+- Fee treatments (distributed, add to principal, separate payment)
+- Monthly date drift prevention with bank_days_only
+- CSV generation
+- Public API (schedule, summary, convenience methods)
+- Deep freeze immutability
+- Edge cases (year boundaries, month-end clamping, input validation)
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/amortizy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/amortizy/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/zapatify/amortizy.
+
+### How to Contribute
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`bundle exec rspec`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to your branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
+
+## Author
 
-Everyone interacting in the Amortizy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/amortizy/blob/main/CODE_OF_CONDUCT.md).
+**Rich Zapata** - [@zapatify](https://github.com/zapatify)

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/lib/amortizy/console_formatter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Amortizy
+  class ConsoleFormatter
+    def initialize(schedule_obj)
+      @schedule_obj = schedule_obj
+      @data = schedule_obj.schedule
+    end
+
+    def render
+      puts header
+      puts '-' * 195
+
+      @data.each do |row|
+        puts row[:payment_type] == 'Grace Period' ? grace_row(row) : payment_row(row)
+      end
+
+      print_summary
+    end
+
+    private
+
+    def header
+      format(
+        '%-8s %-12s %-8s %15s %15s %18s %18s %20s %18s %18s %20s',
+        'Payment', 'Date', 'Days', 'Principal Pmt', 'Interest Pmt',
+        @schedule_obj.additional_fee_label, 'Total Payment', 'Principal Balance',
+        'Accrued Interest', 'Total Balance', 'Payment Type'
+      )
+    end
+
+    def grace_row(row)
+      format(
+        '%-8s %-12s %-8d %15s %15s %18s %18s %20.2f %18s %18.2f %20s',
+        'Grace', row[:date].strftime('%Y-%m-%d'), row[:days_in_period],
+        '---', "+#{format('%.2f', row[:grace_interest_capitalized])}",
+        '---', '0.00', row[:principal_balance], '---',
+        row[:principal_balance], 'Grace Period'
+      )
+    end
+
+    def payment_row(row)
+      label = row[:payment_number].is_a?(Integer) && row[:payment_number].zero? ? 'Fee' : row[:payment_number].to_s
+      format(
+        '%-8s %-12s %-8d %15.2f %15.2f %18.2f %18.2f %20.2f %18.2f %18.2f %20s',
+        label, row[:date].strftime('%Y-%m-%d'), row[:days_in_period],
+        row[:principal_payment], row[:interest_payment], row[:additional_fee_payment],
+        row[:total_payment], row[:principal_balance], row[:accrued_interest],
+        row[:total_balance], row[:payment_type]
+      )
+    end
+
+    def print_summary
+      summary = @schedule_obj.summary
+      puts "\n#{'=' * 195}"
+      puts 'LOAN SUMMARY'
+      puts '=' * 195
+      puts "Loan Start Date: #{summary[:start_date].strftime('%Y-%m-%d')}"
+      puts "End Date: #{summary[:end_date].strftime('%Y-%m-%d')}"
+      puts "Total Payments: #{summary[:total_payments]}"
+      puts "Payment Frequency: #{summary[:frequency].to_s.capitalize}"
+      puts "Annual Rate: #{format('%.2f', summary[:annual_rate])}%"
+      puts "\nOriginal Principal: $#{format('%.2f', summary[:principal])}"
+      puts "Regular Payment: $#{format('%.2f', summary[:payment_amount])}"
+      puts "Total Interest Paid: $#{format('%.2f', summary[:total_interest])}"
+      puts "Total Amount Paid: $#{format('%.2f', summary[:total_paid])}"
+      puts '=' * 195
+    end
+  end
+end

data/lib/amortizy/csv_formatter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'csv'
+
+module Amortizy
+  class CsvFormatter
+    HEADERS = [
+      'Payment Number', 'Date', 'Days in Period', 'Principal Payment',
+      'Interest Payment', 'Additional Fee Payment', 'Total Payment',
+      'Principal Balance Remaining', 'Accrued Interest', 'Total Balance',
+      'Payment Type', 'Grace Interest Capitalized'
+    ].freeze
+
+    def initialize(schedule_obj)
+      @data = schedule_obj.schedule
+    end
+
+    def render(csv_path)
+      CSV.open(csv_path, 'w') do |csv|
+        csv << HEADERS
+
+        @data.each do |row|
+          csv << [
+            row[:payment_number],
+            row[:date].strftime('%Y-%m-%d'),
+            row[:days_in_period],
+            format('%.2f', row[:principal_payment] || 0),
+            format('%.2f', row[:interest_payment] || 0),
+            format('%.2f', row[:additional_fee_payment] || 0),
+            format('%.2f', row[:total_payment] || 0),
+            format('%.2f', row[:principal_balance]),
+            format('%.2f', row[:accrued_interest] || 0),
+            format('%.2f', row[:total_balance]),
+            row[:payment_type],
+            row[:grace_interest_capitalized] ? format('%.2f', row[:grace_interest_capitalized]) : ''
+          ]
+        end
+      end
+
+      puts "CSV file generated: #{csv_path}"
+    end
+  end
+end