mercury_banking 0.5.34

data/lib/mercury_banking/reports/reconciliation.rb

@@ -0,0 +1,307 @@
+module MercuryBanking
+  module Reports
+    # Module for reconciliation between ledger and Mercury balances
+    module Reconciliation
+      # Generate a reconciliation report to identify when balances diverged
+      def generate_reconciliation_report(client, account_name, start_date, end_date = nil, format = 'ledger')
+        puts "Generating reconciliation report for #{account_name} from #{start_date} to #{end_date || 'present'}..."
+        
+        # Find the account by name
+        account = find_account_by_name(client, account_name)
+        return unless account
+        
+        # Get current balance from Mercury
+        current_mercury_balance = account['currentBalance']
+        
+        # Get all transactions for the account
+        transactions = get_account_transactions(client, account['id'], start_date)
+        
+        # Filter by end date if specified
+        if end_date
+          end_date_obj = Date.parse(end_date)
+          transactions = transactions.select do |t|
+            transaction_date = t["postedAt"] ? Date.parse(t["postedAt"]) : Date.parse(t["createdAt"])
+            transaction_date <= end_date_obj
+          end
+        end
+        
+        if transactions.empty?
+          puts "No transactions found for reconciliation."
+          return
+        end
+        
+        # Sort transactions by date
+        transactions = sort_transactions_by_date(transactions)
+        
+        # Group transactions by month for easier analysis
+        monthly_transactions = group_transactions_by_month(transactions)
+        
+        # Create a temporary file for ledger export
+        require 'tempfile'
+        temp_file = Tempfile.new(['mercury_reconciliation', ".#{format}"])
+        output_file = temp_file.path
+        
+        # Export all transactions to the ledger file
+        case format
+        when 'ledger'
+          export_to_ledger(transactions, output_file, [], false)
+        when 'beancount'
+          export_to_beancount(transactions, output_file, [], false)
+        else
+          puts "Unsupported format: #{format}. Please use 'ledger' or 'beancount'."
+          temp_file.unlink
+          return
+        end
+        
+        # Analyze each month to find when divergence occurred
+        puts "\n=== Monthly Reconciliation Analysis ==="
+        puts "Period".ljust(15) + "Mercury Balance".ljust(20) + "Ledger Balance".ljust(20) + "Difference".ljust(15) + "Status"
+        puts "-" * 80
+        
+        cumulative_ledger_balance = 0
+        divergence_point = nil
+        monthly_data = []
+        
+        monthly_transactions.each do |month, month_transactions|
+          # Calculate the Mercury balance at the end of this month
+          last_transaction = month_transactions.last
+          last_date = last_transaction["postedAt"] ? Date.parse(last_transaction["postedAt"]) : Date.parse(last_transaction["createdAt"])
+          
+          # Get ledger balance for this month
+          month_end_date = last_date.strftime("%Y-%m-%d")
+          ledger_balance = get_ledger_balance_at_date(output_file, month_end_date, account_name, format)
+          
+          # Calculate Mercury balance at this point in time
+          # This is an approximation based on current balance and subsequent transactions
+          mercury_balance_at_month_end = calculate_mercury_balance_at_date(current_mercury_balance, transactions, last_date)
+          
+          # Calculate difference
+          difference = mercury_balance_at_month_end - ledger_balance
+          
+          # Determine status
+          status = difference.abs < 0.01 ? "✓ Balanced" : "⚠️ Diverged"
+          
+          # Record the first divergence point
+          if difference.abs >= 0.01 && divergence_point.nil?
+            divergence_point = month
+          end
+          
+          # Format for display
+          month_str = month
+          mercury_balance_str = format("$%.2f", mercury_balance_at_month_end)
+          ledger_balance_str = format("$%.2f", ledger_balance)
+          difference_str = format("$%.2f", difference)
+          
+          puts month_str.ljust(15) + mercury_balance_str.ljust(20) + ledger_balance_str.ljust(20) + difference_str.ljust(15) + status
+          
+          monthly_data << {
+            period: month,
+            mercury_balance: mercury_balance_at_month_end,
+            ledger_balance: ledger_balance,
+            difference: difference,
+            status: status
+          }
+        end
+        
+        puts "-" * 80
+        
+        # If divergence was found, analyze the specific month in more detail
+        if divergence_point
+          puts "\n=== Detailed Analysis of Divergence Point: #{divergence_point} ==="
+          
+          # Get transactions for the divergence month
+          divergence_month_transactions = monthly_transactions[divergence_point]
+          
+          # Check for pending or failed transactions
+          pending_transactions = divergence_month_transactions.select { |t| t["status"] != "posted" }
+          
+          if pending_transactions.any?
+            puts "\nPotential issues found: #{pending_transactions.count} transactions with non-posted status"
+            puts "\nTransactions with non-posted status:"
+            
+            pending_transactions.each do |t|
+              date = t["postedAt"] ? Time.parse(t["postedAt"]).strftime("%Y-%m-%d") : Time.parse(t["createdAt"]).strftime("%Y-%m-%d")
+              amount = format("$%.2f", t["amount"])
+              description = t["bankDescription"] || t["externalMemo"] || "Unknown transaction"
+              status = t["status"]
+              
+              puts "#{date} | #{amount} | #{status.upcase} | #{description}"
+            end
+          end
+          
+          # Check for transactions on the same day with opposite amounts (potential duplicates or corrections)
+          potential_corrections = find_potential_corrections(divergence_month_transactions)
+          
+          if potential_corrections.any?
+            puts "\nPotential corrections or duplicates found:"
+            
+            potential_corrections.each do |pair|
+              t1, t2 = pair
+              date1 = t1["postedAt"] ? Time.parse(t1["postedAt"]).strftime("%Y-%m-%d") : Time.parse(t1["createdAt"]).strftime("%Y-%m-%d")
+              date2 = t2["postedAt"] ? Time.parse(t2["postedAt"]).strftime("%Y-%m-%d") : Time.parse(t2["createdAt"]).strftime("%Y-%m-%d")
+              
+              puts "#{date1} | #{format("$%.2f", t1["amount"])} | #{t1["bankDescription"] || t1["externalMemo"] || "Unknown"}"
+              puts "#{date2} | #{format("$%.2f", t2["amount"])} | #{t2["bankDescription"] || t2["externalMemo"] || "Unknown"}"
+              puts "-" * 50
+            end
+          end
+        end
+        
+        # Clean up temporary file
+        temp_file.unlink
+        
+        return monthly_data
+      end
+      
+      private
+      
+      # Find account by name
+      def find_account_by_name(client, account_name)
+        accounts = client.accounts
+        account = accounts.find { |a| a["name"] == account_name }
+        
+        unless account
+          puts "Error: Account '#{account_name}' not found. Available accounts:"
+          accounts.each { |a| puts "- #{a['name']}" }
+          return nil
+        end
+        
+        account
+      end
+      
+      # Get transactions for a specific account
+      def get_account_transactions(client, account_id, start_date)
+        client.get_transactions(account_id, start_date)
+      end
+      
+      # Sort transactions by date
+      def sort_transactions_by_date(transactions)
+        transactions.sort_by do |t|
+          date = t["postedAt"] || t["createdAt"]
+          Time.parse(date)
+        end
+      end
+      
+      # Group transactions by month
+      def group_transactions_by_month(transactions)
+        transactions.group_by do |t|
+          date = t["postedAt"] ? Time.parse(t["postedAt"]) : Time.parse(t["createdAt"])
+          date.strftime("%Y-%m")
+        end
+      end
+      
+      # Get ledger balance at a specific date
+      def get_ledger_balance_at_date(file_path, date, account_name, format)
+        case format
+        when 'ledger'
+          # First, check what accounts actually exist in the ledger file
+          accounts_cmd = "ledger -f #{file_path} accounts"
+          accounts_output = `#{accounts_cmd}`
+          puts "\n=== Available Accounts in Ledger File ==="
+          puts accounts_output
+          
+          # Find the closest matching account
+          ledger_accounts = accounts_output.split("\n")
+          
+          # Try to find an exact match first
+          exact_match = ledger_accounts.find { |a| a == "Assets:#{account_name}" }
+          if exact_match
+            puts "Found exact account match: #{exact_match}"
+            account_to_use = exact_match
+          else
+            # Try to find a partial match
+            partial_matches = ledger_accounts.select { |a| a.include?(account_name.split(' ').first) }
+            if partial_matches.any?
+              puts "Found partial account matches: #{partial_matches.join(', ')}"
+              account_to_use = partial_matches.first
+            else
+              # If no match found, just use the first Assets account
+              assets_accounts = ledger_accounts.select { |a| a.start_with?('Assets:') }
+              if assets_accounts.any?
+                puts "No match found, using first Assets account: #{assets_accounts.first}"
+                account_to_use = assets_accounts.first
+              else
+                puts "No Assets accounts found in ledger file"
+                return 0.0
+              end
+            end
+          end
+          
+          # Now use the matched account for the balance command
+          cmd = "ledger -f #{file_path} --end #{date} balance --flat '#{account_to_use}'"
+          output = `#{cmd}`
+          
+          # Debug information
+          puts "\n=== Ledger Debug Information ==="
+          puts "Command: #{cmd}"
+          puts "Raw output: #{output}"
+          
+          # Extract balance from output using a more flexible regex
+          # The ledger output format is typically something like:
+          #    $2950.00  Assets:Mercury Checking
+          if output =~ /\s+\$\s*([\d,.-]+)\s+/
+            balance = $1.gsub(',', '').to_f
+            puts "Extracted balance: $#{balance}"
+            balance
+          else
+            puts "No balance found in output, returning 0.0"
+            0.0
+          end
+        when 'beancount'
+          cmd = "bean-report #{file_path} -e #{date} balances 'Assets:#{account_name.gsub(/[^a-zA-Z0-9]/, '-')}'"
+          output = `#{cmd}`
+          
+          # Extract balance from output
+          if output =~ /([\d,.-]+)\s+USD/
+            $1.gsub(',', '').to_f
+          else
+            0.0
+          end
+        else
+          0.0
+        end
+      end
+      
+      # Calculate Mercury balance at a specific date
+      def calculate_mercury_balance_at_date(current_balance, transactions, target_date)
+        # Start with current balance
+        balance_at_date = current_balance
+        
+        # Subtract all transactions that occurred after the target date
+        transactions.each do |t|
+          transaction_date = t["postedAt"] ? Date.parse(t["postedAt"]) : Date.parse(t["createdAt"])
+          
+          if transaction_date > target_date
+            # Reverse the effect of this transaction
+            balance_at_date -= t["amount"]
+          end
+        end
+        
+        balance_at_date
+      end
+      
+      # Find potential corrections or duplicates
+      def find_potential_corrections(transactions)
+        potential_pairs = []
+        
+        # Group transactions by date
+        by_date = transactions.group_by do |t|
+          date = t["postedAt"] ? Time.parse(t["postedAt"]) : Time.parse(t["createdAt"])
+          date.strftime("%Y-%m-%d")
+        end
+        
+        # Look for transactions on the same day with opposite amounts
+        by_date.each do |date, day_transactions|
+          day_transactions.combination(2).each do |t1, t2|
+            # Check if amounts are opposite (with small tolerance for rounding)
+            if (t1["amount"] + t2["amount"]).abs < 0.01
+              potential_pairs << [t1, t2]
+            end
+          end
+        end
+        
+        potential_pairs
+      end
+    end
+  end
+end 

data/lib/mercury_banking/utils/command_utils.rb

@@ -0,0 +1,18 @@
+module MercuryBanking
+  module Utils
+    # Utility methods for command operations
+    module CommandUtils
+      # Check if a command exists in the system PATH
+      def command_exists?(command)
+        exts = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+        ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
+          exts.each do |ext|
+            exe = File.join(path, "#{command}#{ext}")
+            return true if File.executable?(exe) && !File.directory?(exe)
+          end
+        end
+        false
+      end
+    end
+  end
+end 

data/lib/mercury_banking/version.rb

@@ -0,0 +1,3 @@
+module MercuryBanking
+  VERSION = "0.5.34"
+end

data/lib/mercury_banking.rb

@@ -0,0 +1,19 @@
+require "mercury_banking/version"
+require 'uri'
+require 'net/http'
+require 'json'
+require 'terminal-table'
+require 'csv'
+
+# Load all modules
+require 'mercury_banking/api'
+require 'mercury_banking/recipient'
+require 'mercury_banking/multi'
+require 'mercury_banking/reconciliation'
+require 'mercury_banking/utils/command_utils'
+require 'mercury_banking/reports/balance_sheet'
+require 'mercury_banking/reports/reconciliation'
+
+module MercuryBanking
+  class Error < StandardError; end
+end

data/mercury_banking.gemspec

@@ -0,0 +1,37 @@
+require_relative 'lib/mercury_banking/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mercury_banking"
+  spec.version       = MercuryBanking::VERSION
+  spec.authors       = ["Jonathan Siegel", "Yusuke Ishida"]
+  spec.email         = ["jonathan@siegel.io", "yusuke@xenon.io"]
+
+  spec.summary       = %q{Client library for talking to Mercury API.}
+  spec.description   = %q{Using this gem, you can access all of your accounts and their transaction histories or make payments to other accounts.
+  }
+  spec.homepage      = "https://github.com/XenonIO/mercury-banking"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/XenonIO/mercury-banking"
+  spec.metadata["changelog_uri"] = "https://github.com/XenonIO/mercury-banking"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency 'pry', '>= 0'
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_dependency 'thor', '~> 1.2.0'
+  spec.add_dependency 'terminal-table', '~> 1.8.0'
+  spec.add_dependency 'activesupport', '~> 7.0.0'
+  spec.add_dependency 'symmetric-encryption', '~> 4.6.0'
+end

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: mercury_banking
+version: !ruby/object:Gem::Version
+  version: 0.5.34
+platform: ruby
+authors:
+- Jonathan Siegel
+- Yusuke Ishida
+bindir: bin
+cert_chain: []
+date: 2025-03-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: symmetric-encryption
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.6.0
+description: "Using this gem, you can access all of your accounts and their transaction
+  histories or make payments to other accounts.\n  "
+email:
+- jonathan@siegel.io
+- yusuke@xenon.io
+executables:
+- console
+- mercury
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env_test"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LINTING_REPORT.md
+- README.md
+- Rakefile
+- bin/console
+- bin/mercury
+- bin/setup
+- lib/mercury_banking.rb
+- lib/mercury_banking/api.rb
+- lib/mercury_banking/cli.rb
+- lib/mercury_banking/cli/accounts.rb
+- lib/mercury_banking/cli/base.rb
+- lib/mercury_banking/cli/financials.rb
+- lib/mercury_banking/cli/reconciliation.rb
+- lib/mercury_banking/cli/reports.rb
+- lib/mercury_banking/cli/transactions.rb
+- lib/mercury_banking/formatters/export_formatter.rb
+- lib/mercury_banking/formatters/table_formatter.rb
+- lib/mercury_banking/multi.rb
+- lib/mercury_banking/recipient.rb
+- lib/mercury_banking/reconciliation.rb
+- lib/mercury_banking/reports/balance_sheet.rb
+- lib/mercury_banking/reports/reconciliation.rb
+- lib/mercury_banking/utils/command_utils.rb
+- lib/mercury_banking/version.rb
+- mercury_banking.gemspec
+homepage: https://github.com/XenonIO/mercury-banking
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/XenonIO/mercury-banking
+  source_code_uri: https://github.com/XenonIO/mercury-banking
+  changelog_uri: https://github.com/XenonIO/mercury-banking
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Client library for talking to Mercury API.
+test_files: []