appydave-tools 0.84.0 → 0.86.0

data/lib/appydave/tools/bank_reconciliation/clean/read_transactions.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module Appydave
+  module Tools
+    module BankReconciliation
+      module Clean
+        # Read transactions from a CSV file
+        class ReadTransactions
+          WISE_HEADER_PREFIX = 'ID,Status,Direction,"Created on","Finished on","Source fee amount",' \
+                               '"Source fee currency","Target fee amount","Target fee currency","Source name",' \
+                               '"Source amount (after fees)","Source currency","Target name",' \
+                               '"Target amount (after fees)","Target currency","Exchange rate",Reference,Batch'
+          PAYPAL_HEADER_PREFIX = '"Date","Time","Time zone","Name","Type","Status","Currency",' \
+                                 '"Amount","Fees","Total","Exchange Rate","Receipt ID","Balance",' \
+                                 '"Transaction ID","Item Title"'
+          # Exact match — short header risks start_with? collision with future formats
+          COMMONWEALTH_SIMPLE_HEADER = 'Date,Amount,Description,Balance'
+          attr_reader :platform
+          attr_reader :transactions
+
+          def initialize(file)
+            @file = file
+          end
+
+          def read
+            csv_lines = File.read(@file).lines
+            csv_lines[0] = csv_lines[0].sub("\xEF\xBB\xBF", '') if csv_lines[0]&.start_with?("\xEF\xBB\xBF")
+
+            @platform = detect_platform(csv_lines)
+
+            case platform
+            when :bankwest
+              read_bankwest(csv_lines)
+            when :bankwest2
+              read_bankwest2(csv_lines)
+            when :commonwealth1
+              read_commonwealth1(csv_lines)
+            when :wise
+              read_wise(csv_lines)
+            when :paypal
+              read_paypal(csv_lines)
+            when :commonwealth_simple
+              read_commonwealth_simple(csv_lines)
+            else
+              raise Appydave::Tools::Error, 'Unknown platform X'
+            end
+          end
+
+          private
+
+          def read_bankwest(csv_lines)
+            @transactions = []
+
+            # Skip the header line and parse each subsequent line
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              transaction = Models::Transaction.new(
+                bsb_number: row['BSB Number'] || '',
+                account_number: row['Account Number'] || '',
+                transaction_date: row['Transaction Date'],
+                narration: row['Narration'],
+                cheque_number: row['Cheque Number'],
+                debit: row['Debit'],
+                credit: row['Credit'],
+                balance: row['Balance'],
+                transaction_type: row['Transaction Type']
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          def read_bankwest2(csv_lines)
+            @transactions = []
+
+            # Skip the header line and parse each subsequent line
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              values = row['BSB / Account Number'].split(' - ')
+
+              transaction = Models::Transaction.new(
+                bsb_number: values.length > 1 ? values.first : '',
+                account_number: values.length > 1 ? values.last : row['BSB / Account Number'],
+                transaction_date: row['Transaction Date'],
+                narration: row['Narration'],
+                cheque_number: row['Cheque Number'],
+                debit: row['Debit'],
+                credit: row['Credit'],
+                balance: row['Balance'],
+                transaction_type: row['Transaction Type']
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          def read_commonwealth1(csv_lines)
+            @transactions = []
+
+            # Skip the header line and parse each subsequent line
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              transaction = Models::Transaction.new(
+                bsb_number: row['bsb_number'],
+                account_number: row['account_number'],
+                transaction_date: row['transaction_date'],
+                narration: row['description'],
+                cheque_number: '',
+                debit: row['amount'].to_f.negative? ? row['amount'] : '',
+                credit: row['amount'].to_f.positive? ? row['amount'] : '',
+                balance: row['balance'],
+                transaction_type: ''
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          # Wise CSV header:
+          # ID,Status,Direction,"Created on","Finished on","Source fee amount","Source fee currency",
+          # "Target fee amount","Target fee currency","Source name","Source amount (after fees)",
+          # "Source currency","Target name","Target amount (after fees)","Target currency",
+          # "Exchange rate",Reference,Batch
+          def read_wise(csv_lines)
+            @transactions = []
+
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              amount   = row['Source amount (after fees)']
+              incoming = row['Direction'].to_s.strip.upcase == 'IN'
+
+              puts "Wise: unexpected Direction '#{row['Direction']}' on row #{row['ID']} — defaulting to debit" \
+                unless %w[IN OUT].include?(row['Direction'].to_s.strip.upcase)
+
+              transaction = Models::Transaction.new(
+                bsb_number: '',
+                account_number: 'WISE',
+                transaction_date: row['Created on'],
+                narration: row['Reference'] || '',
+                cheque_number: "#{row['Source currency']}|#{row['Target currency']}|#{row['Exchange rate']}|#{row['Target name']}",
+                debit: incoming ? '' : amount,
+                credit: incoming ? amount : '',
+                balance: '',
+                transaction_type: ''
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          # PayPal CSV header:
+          # "Date","Time","Time zone","Name","Type","Status","Currency","Amount","Fees","Total",
+          # "Exchange Rate","Receipt ID","Balance","Transaction ID","Item Title"
+          def read_paypal(csv_lines)
+            @transactions = []
+
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              next if row['Date'].to_s.strip.empty?
+
+              name      = row['Name'].to_s.strip
+              item      = row['Item Title'].to_s.strip
+              narration = name.empty? ? item : name
+              currency  = row['Currency'].to_s.strip
+              narration = "#{narration} (#{currency})" if !currency.empty? && currency != 'AUD'
+
+              amount = row['Amount'].to_s.strip
+              debit  = amount.to_f.negative? ? amount : ''
+              credit = amount.to_f.positive? ? amount : ''
+
+              transaction = Models::Transaction.new(
+                bsb_number: '',
+                account_number: 'PAYPAL',
+                transaction_date: row['Date'],
+                narration: narration,
+                cheque_number: '',
+                debit: debit,
+                credit: credit,
+                balance: row['Balance'],
+                transaction_type: row['Type'].to_s
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          # CBA 4-column export (Date,Amount,Description,Balance). The CSV carries
+          # no account identity, so we tag rows with the generic identifier 'CBA-SIMPLE'
+          # and let the downstream mapper resolve it via the local
+          # ~/.config/appydave/bank-reconciliation.json config (same pattern as WISE
+          # and PAYPAL). Real BSB / account number stay out of source.
+          def read_commonwealth_simple(csv_lines)
+            @transactions = []
+
+            CSV.parse(csv_lines.join, headers: true).each do |row|
+              next if row['Date'].to_s.strip.empty?
+
+              amount = parse_signed_amount(row['Amount'])
+              debit  = amount.negative? ? amount.to_s('F') : ''
+              credit = amount.positive? ? amount.to_s('F') : ''
+
+              transaction = Models::Transaction.new(
+                bsb_number: '',
+                account_number: 'CBA-SIMPLE',
+                transaction_date: row['Date'],
+                narration: row['Description'].to_s,
+                cheque_number: nil,
+                debit: debit,
+                credit: credit,
+                balance: parse_signed_amount(row['Balance']).to_s('F'),
+                transaction_type: nil
+              )
+              transaction.add_source_file(@file)
+              @transactions << transaction
+            end
+
+            @transactions
+          end
+
+          # For bankwest the first row is the CSV will look like:
+          # BSB Number,Account Number,Transaction Date,Narration,Cheque Number,Debit,Credit,Balance,Transaction Type
+          def detect_platform(csv_lines)
+            return :bankwest if csv_lines.first.start_with?('BSB Number,Account Number,Transaction Date,Narration,Cheque Number,Debit,Credit,Balance,Transaction Type')
+            return :bankwest2 if csv_lines.first.start_with?('Account Name,BSB / Account Number,Transaction Date,Narration,Cheque Number,Debit,Credit,Balance,Transaction Type')
+            return :commonwealth1 if csv_lines.first.start_with?('bsb_number,account_number,transaction_date,amount,description,balance') # Standard Account
+            return :commonwealth2 if csv_lines.first.start_with?('transaction_date,narration,debit_credit_amount,debit_credit_currency,balance_amount,balance_currency') # Travel Money
+            return :wise if csv_lines.first.start_with?(WISE_HEADER_PREFIX)
+            return :paypal if csv_lines.first.start_with?(PAYPAL_HEADER_PREFIX)
+            return :commonwealth_simple if csv_lines.first.strip == COMMONWEALTH_SIMPLE_HEADER
+
+            puts "Unknown platform detected. CSV columns are: #{csv_lines.first.strip}"
+            raise Appydave::Tools::Error, 'Unknown platform'
+          end
+
+          def parse_signed_amount(str)
+            return BigDecimal('0') if str.nil? || str.to_s.strip.empty?
+
+            clean = str.to_s.gsub(/[$,\s"]/, '')
+            return BigDecimal('0') if clean.empty?
+
+            case clean[0]
+            when '+' then BigDecimal(clean[1..])
+            when '-' then -BigDecimal(clean[1..])
+            else BigDecimal(clean)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/bank_reconciliation/models/transaction.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module BankReconciliation
+      module Models
+        # Unified transaction model for raw and reconciled data
+        class Transaction
+          attr_accessor :bsb_number,
+                        :account_number,
+                        :transaction_date,
+                        :narration,
+                        :cheque_number,
+                        :debit,
+                        :credit,
+                        :balance,
+                        :transaction_type,
+                        :platform,
+                        :coa_code,
+                        :coa_match_type,
+                        :account_name,
+                        :source_files,
+                        :fin_year
+
+          def initialize(bsb_number: nil,
+                         account_number: nil,
+                         transaction_date: nil,
+                         narration: nil,
+                         cheque_number: nil,
+                         debit: nil,
+                         credit: nil,
+                         balance: nil,
+                         transaction_type: nil,
+                         platform: nil,
+                         coa_code: nil,
+                         coa_match_type: nil,
+                         account_name: nil)
+            account_number = account_number&.strip
+            @bsb_number = bsb_number&.strip
+            @account_number = account_number
+            @transaction_date = parse_date(transaction_date)
+            @narration = narration&.gsub(/\s{2,}/, ' ')&.strip
+            @cheque_number = cheque_number&.strip
+            @debit = debit # clean_amount(debit, account_number, coa_code)
+            @credit = credit # clean_amount(credit, account_number, coa_code)
+            @balance = balance&.strip
+            @transaction_type = transaction_type&.strip
+            @platform = platform
+            @coa_code = coa_code
+            @coa_match_type = coa_match_type
+            @account_name = account_name
+            @source_files = []
+            @fin_year = determine_fin_year(@transaction_date)
+          end
+
+          def add_source_file(source_file)
+            @source_files << source_file.strip unless @source_files.include?(source_file.strip)
+          end
+
+          def self.csv_headers
+            %i[
+              platform
+              account_name
+              bsb_number
+              account_number
+              transaction_date
+              narration
+              debit
+              credit
+              balance
+              transaction_type
+              coa_code
+              coa_match_type
+              source_files
+              fin_year
+            ]
+          end
+
+          def to_csv_row
+            [
+              @platform,
+              @account_name,
+              @bsb_number,
+              @account_number,
+              @transaction_date,
+              @narration,
+              @debit ? format('%.2f', @debit) : '',
+              @credit ? format('%.2f', @credit) : '',
+              @balance,
+              @transaction_type,
+              @coa_code,
+              @coa_match_type,
+              @source_files.join('; '),
+              @fin_year
+            ]
+          end
+
+          def clean_amount(amount)
+            return nil if amount.nil? || amount.strip.empty?
+
+            cleaned_amount = amount.to_f.round(2)
+
+            if swap_plus_minus_for_transactions
+              if cleaned_amount.negative?
+                cleaned_amount = cleaned_amount.abs
+                # else
+                #   cleaned_amount *= -1
+              end
+              puts "Fixed negative amount for account: #{account_number} and COA: #{coa_code}, original amount: #{amount}, fixed amount: #{cleaned_amount}" if coa_code == 'DANCE'
+            end
+            cleaned_amount
+          end
+
+          # Returns true if this transaction's amount should have its sign flipped
+          # based on the per-account, per-FY, per-COA rules stored in config.
+          #
+          # Rules live in ~/.config/appydave/bank-reconciliation.json under
+          # `sign_flip_rules` — see BankReconciliationConfig::SignFlipRule.
+          # Personal account numbers MUST NOT be hardcoded here; the config file
+          # is local-only and never committed to the repo.
+          def swap_plus_minus_for_transactions
+            sign_flip_rules.any? do |rule|
+              (rule.fin_year.nil? || rule.fin_year == fin_year) &&
+                rule.account_number == account_number &&
+                rule.coa_codes.include?(coa_code)
+            end
+          end
+
+          private
+
+          def sign_flip_rules
+            Appydave::Tools::Configuration::Config.bank_reconciliation.sign_flip_rules
+          rescue StandardError
+            []
+          end
+
+          def parse_date(date_string)
+            formats = ['%d/%m/%Y', '%Y-%m-%d %H:%M:%S']
+            formats.each do |format|
+              return Date.strptime(date_string, format)
+            rescue Date::Error
+              next
+            end
+            raise Date::Error, "Invalid date format: #{date_string}"
+          end
+
+          def determine_fin_year(date)
+            if date.month >= 7
+              "#{date.year}-#{date.year + 1}"
+            else
+              "#{date.year - 1}-#{date.year}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/brain_context/options.rb

@@ -34,11 +34,15 @@ module Appydave
         @tokens = false
         @base_dir = Dir.pwd
 
-        @omi_dir = File.expand_path('~/dev/raw-intake/omi')
+        configured_omi = read_setting('omi-directory-path')
+        @omi_dir = configured_omi || File.expand_path('~/dev/raw-intake/omi')
       end
 
       def brains_root
-        @brains_root ||= File.expand_path('~/dev/ad/brains')
+        @brains_root ||= begin
+          configured = read_setting('brains-root-path')
+          configured || File.expand_path('~/dev/ad/brains')
+        end
       end
 
       def brains_index_path
@@ -52,6 +56,19 @@ module Appydave
       def omi_query?
         omi
       end
+
+      private
+
+      # Read a path value from settings config, expanding ~ if set.
+      # Returns nil if config is unavailable or key is absent/blank.
+      def read_setting(key)
+        value = Appydave::Tools::Configuration::Config.settings.get(key)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        File.expand_path(value)
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/appydave/tools/configuration/example_installer.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Configuration
+      # Installs bundled example configuration files into the user's config directory.
+      #
+      # Example files live at config/examples/*.example.json inside the gem.
+      # Each file is installed without the `.example` segment in its name so that
+      # `settings.example.json` becomes `settings.json` in the target directory.
+      #
+      # Files are never overwritten — existing files are skipped and reported.
+      #
+      # @example Install all examples
+      #   result = ExampleInstaller.new.install
+      #   result[:installed] #=> ["settings.json", "locations.json"]
+      #   result[:skipped]   #=> []
+      class ExampleInstaller
+        EXAMPLES_PATH = File.expand_path('../../../../config/examples', __dir__)
+
+        # @param target_path [String, nil] Directory to install into.
+        #   Defaults to the active Config.config_path (~/.config/appydave).
+        def initialize(target_path: nil)
+          @target_path = target_path || Config.config_path
+        end
+
+        # Install all bundled example files that do not yet exist.
+        #
+        # @return [Hash] with keys :installed (Array<String>) and :skipped (Array<String>)
+        def install
+          FileUtils.mkdir_p(@target_path)
+          results = { installed: [], skipped: [] }
+
+          example_files.each do |src|
+            dest = destination_for(src)
+            basename = File.basename(dest)
+
+            if File.exist?(dest)
+              results[:skipped] << basename
+            else
+              FileUtils.cp(src, dest)
+              results[:installed] << basename
+            end
+          end
+
+          results
+        end
+
+        # List the filenames that would be installed (target names, not source names).
+        #
+        # @return [Array<String>]
+        def available
+          example_files.map { |f| target_name(f) }
+        end
+
+        private
+
+        def example_files
+          Dir.glob(File.join(EXAMPLES_PATH, '*.example.*')).sort
+        end
+
+        def destination_for(src)
+          File.join(@target_path, target_name(src))
+        end
+
+        def target_name(src)
+          File.basename(src).sub('.example', '')
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/configuration/models/bank_reconciliation_config.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Configuration
+      module Models
+        # Bank reconciliation configuration
+        class BankReconciliationConfig < ConfigBase
+          # def
+          # Retrieve all bank accounts
+          def bank_accounts
+            data['bank_accounts'].map do |account|
+              BankAccount.new(account)
+            end
+          end
+
+          def chart_of_accounts
+            data['chart_of_accounts'].map do |entry|
+              ChartOfAccount.new(entry)
+            end
+          end
+
+          # Sign-flip rules — per-account, per-fin-year, per-COA exceptions where the
+          # raw bank-export sign is wrong and needs flipping during clean_amount.
+          # Personal account numbers belong here (in config), not in source.
+          def sign_flip_rules
+            (data['sign_flip_rules'] || []).map do |rule|
+              SignFlipRule.new(rule)
+            end
+          end
+
+          def get_bank_account(account_number, bsb = nil)
+            normalized_bsb = bsb.to_s.empty? ? nil : bsb
+            account_data = data['bank_accounts'].find do |account|
+              acct_bsb = account['bsb'].to_s.empty? ? nil : account['bsb']
+              account['account_number'] == account_number && (normalized_bsb.nil? || acct_bsb == normalized_bsb)
+            end
+
+            BankAccount.new(account_data) if account_data
+          end
+
+          # Retrieve a chart of account entry by code
+          def get_chart_of_account(code)
+            entry_data = data['chart_of_accounts'].find { |entry| entry['code'] == code }
+            ChartOfAccount.new(entry_data) if entry_data
+          end
+
+          def print
+            log.subheading 'Bank Reconciliation - Accounts'
+
+            tp bank_accounts, :account_number, :bsb, :name, :bank
+
+            log.subheading 'Bank Reconciliation - Chart of Accounts'
+
+            tp chart_of_accounts, :code, :narration
+          end
+
+          def coa_to_csv
+            csv_file_path = File.join(Config.config_path, 'bank_reconciliation.chart_of_accounts.csv')
+
+            CSV.open(csv_file_path, 'w') do |csv|
+              csv << %w[code narration]
+
+              chart_of_accounts.sort_by(&:code).each do |entry|
+                csv << [entry.code, entry.narration]
+              end
+            end
+          end
+
+          def coa_csv_to_json
+            csv_file_path = File.join(Config.config_path, 'bank_reconciliation.chart_of_accounts.csv')
+
+            coa_data = CSV.read(csv_file_path, headers: true).map(&:to_h)
+
+            data['chart_of_accounts'] = coa_data
+
+            save
+          end
+
+          private
+
+          def default_data
+            {
+              'bank_accounts' => [],
+              'chart_of_accounts' => [],
+              'sign_flip_rules' => []
+            }
+          end
+
+          # Inner class to represent a bank account
+          class BankAccount
+            attr_accessor :account_number, :bsb, :name, :platform
+
+            def initialize(data)
+              @account_number = data['account_number']
+              @bsb = data['bsb']
+              @name = data['name']
+              @platform = data['platform']
+            end
+
+            def to_h
+              {
+                'account_number' => @account_number,
+                'bsb' => @bsb,
+                'name' => @name,
+                'platform' => @platform
+              }
+            end
+          end
+
+          # Inner class to represent a chart of account entry
+          class ChartOfAccount
+            attr_accessor :code, :narration
+
+            def initialize(data)
+              @code = data['code']
+              @narration = data['narration']
+            end
+
+            def to_h
+              {
+                'code' => @code,
+                'narration' => @narration
+              }
+            end
+          end
+
+          # Inner class to represent a sign-flip rule.
+          # Matches a transaction by (optional fin_year, account_number, coa_code).
+          # When nil, fin_year matches any year.
+          class SignFlipRule
+            attr_accessor :fin_year, :account_number, :coa_codes
+
+            def initialize(data)
+              @fin_year = data['fin_year']
+              @account_number = data['account_number']
+              @coa_codes = data['coa_codes'] || []
+            end
+
+            def to_h
+              {
+                'fin_year' => @fin_year,
+                'account_number' => @account_number,
+                'coa_codes' => @coa_codes
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/configuration/models/settings_config.rb

@@ -42,6 +42,18 @@ module Appydave
             get('current_user')
           end
 
+          # Path to the root brains directory (second-brain knowledge base)
+          # Configure via settings.json key: brains-root-path
+          def brains_root_path
+            get('brains-root-path')
+          end
+
+          # Path to the OMI wearable transcripts directory
+          # Configure via settings.json key: omi-directory-path
+          def omi_directory_path
+            get('omi-directory-path')
+          end
+
           def print
             log.subheading 'Settings Configuration'