ofx_kit 0.1.0

data/lib/ofx_kit/configuration/core.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module OFX
+  # Manages XML-to-Ruby field mappings used during OFX document parsing.
+  #
+  # Mappings are split into two layers:
+  # - *Core* ({core_mappings.yml}): OFX-standard fields whose Ruby attribute names are
+  #   referenced by name inside {Base::Builder}. These cannot be overridden.
+  # - *User* ({field_mappings.yml}): convenience mappings that can be added to or replaced
+  #   at runtime via {#load_mappings} or the {OFX.configure} block.
+  class Configuration
+    CORE_MAPPINGS_PATH = File.join(__dir__, '..', 'mappings', 'core_mappings.yml')
+    MAPPINGS_PATH      = File.join(__dir__, '..', 'mappings', 'field_mappings.yml')
+
+    # Conventional path for user mappings in a Rails application.
+    # Auto-loaded on boot when present. Ejected via +rails generate ofx:eject+.
+    RAILS_MAPPINGS_PATH = 'config/initializers/ofx_mappings.yml'
+
+    attr_writer :multi_statement_warnings
+    attr_accessor :default_currency
+
+    def multi_statement_warnings?
+      @multi_statement_warnings
+    end
+
+    def initialize(auto_load_path: File.expand_path(RAILS_MAPPINGS_PATH))
+      @multi_statement_warnings = true
+      @default_currency = 'USD'
+
+      core = YAML.safe_load_file(CORE_MAPPINGS_PATH)
+      @sections = core.fetch('SECTIONS', {})
+      @core_fields = core.fetch('FIELDS', {})
+      @section_to_tag = @sections.invert
+
+      user = YAML.safe_load_file(MAPPINGS_PATH)
+      @user_fields = user.fetch('FIELDS', {})
+
+      load_mappings(auto_load_path) if File.exist?(auto_load_path)
+    end
+
+    # Returns a {SectionProxy} for the given section, allowing inline mapping
+    # configuration via {SectionProxy#map}.
+    %w[bank_statement credit_card_statement transaction bank_account credit_card_account balance].each do |section|
+      define_method(section) { SectionProxy.new(@user_fields, @core_fields, xml_tag_for(section)) }
+    end
+
+    # Returns the OFX XML tag name corresponding to the given section identifier.
+    # @param section_name [String, Symbol] section identifier (e.g. +:transaction+)
+    # @return [String, nil] the XML tag name, or +nil+ if not found
+    def xml_tag_for(section_name)
+      @section_to_tag[section_name.to_s]
+    end
+
+    # Returns the merged hash of XML tag → Ruby attribute mappings for the given section.
+    # Core mappings take precedence; user mappings extend them.
+    # @param section_name [String, Symbol] section identifier
+    # @return [Hash{String => String}] mapping of XML tags to Ruby attribute names
+    def xml_mappings_for(section_name)
+      tag = xml_tag_for(section_name)
+      return {} unless tag
+
+      (@core_fields[tag] || {}).merge(@user_fields[tag] || {})
+    end
+
+    # Merges additional field mappings from a YAML file into the user-layer configuration.
+    # The file must have a top-level +FIELDS+ key. Core OFX fields cannot be overridden.
+    # @param path [String] path to the YAML mappings file
+    # @raise [ConfigurationError] if the file is missing, malformed, references unknown
+    #   sections, or attempts to override a core field mapping
+    def load_mappings(path)
+      raise ConfigurationError, "Mappings file not found: #{path}" unless File.exist?(path)
+
+      raw = YAML.safe_load_file(path)
+      raise ConfigurationError, 'Invalid mappings file: expected a Hash' unless raw.is_a?(Hash)
+
+      fields = raw.fetch('FIELDS') do
+        raise ConfigurationError, "Invalid mappings file: missing top-level 'FIELDS' key"
+      end
+
+      fields.each { |tag, mappings| merge_user_section(tag, mappings) }
+    end
+
+    private
+
+    def merge_user_section(xml_tag, mappings)
+      unless @sections.key?(xml_tag.to_s)
+        raise ConfigurationError, "Unknown section '#{xml_tag}'. Valid sections: #{@sections.keys.join(', ')}"
+      end
+
+      unless mappings.is_a?(Hash)
+        raise ConfigurationError, "Mapping value for '#{xml_tag}' must be a Hash, got #{mappings.class}"
+      end
+
+      mappings.each_key { |k| assert_not_core!(xml_tag, k) }
+
+      @user_fields[xml_tag.to_s] ||= {}
+      @user_fields[xml_tag.to_s].merge!(mappings)
+    end
+
+    def assert_not_core!(xml_tag, xml_key)
+      core_attr = @core_fields.dig(xml_tag.to_s, xml_key.to_s)
+      return unless core_attr
+
+      raise ConfigurationError,
+            "Cannot override core mapping '#{xml_tag}.#{xml_key}' (reserved as '#{core_attr}')"
+    end
+  end
+end

data/lib/ofx_kit/configuration/date_parser.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module OFX
+  class Configuration
+    # Mixin included by {Base::Builder} to parse OFX date strings into +Time+ objects.
+    # Handles the two formats found in OFX files (YYYYMMDD and YYYYMMDDHHMMSS),
+    # stripping any timezone suffixes (e.g. +[+05:30]+) before parsing.
+    module DateParser
+      private
+
+      def parse_date(str)
+        return nil if str.nil? || str.empty?
+
+        clean = str.gsub(/\[.*?\]/, '').strip
+
+        case clean.length
+        when 8  then Time.strptime(clean, '%Y%m%d')
+        when 14 then Time.strptime(clean, '%Y%m%d%H%M%S')
+        else         Time.parse(clean)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/ofx_kit/configuration/mapping_applicator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OFX
+  class Configuration
+    # Mixin included by {Base::Builder} to apply {Configuration} field mappings
+    # from an XML node onto a domain object. Reads XML text values, ensures
+    # custom attributes exist via {Base::Entity.ensure_attribute}, and assigns them.
+    module MappingApplicator
+      private
+
+      def apply_mappings(object, node, section)
+        return unless node
+
+        OFX.config.xml_mappings_for(section).each do |xml_tag, ruby_attr|
+          value = text_at(node, xml_tag)
+          next if value.nil? || value.empty?
+
+          object.class.ensure_attribute(ruby_attr) if object.class.respond_to?(:ensure_attribute)
+          object.public_send(:"#{ruby_attr}=", value)
+        end
+      end
+
+      def currency_for(node, section)
+        xml_tag = OFX.config.xml_mappings_for(section).key('currency')
+        value = xml_tag && text_at(node, xml_tag)
+        (value.nil? || value.empty?) ? OFX.config.default_currency : value
+      end
+
+      def text_at(node, css_tag)
+        node.at_css(css_tag)&.text&.strip
+      end
+    end
+  end
+end

data/lib/ofx_kit/configuration/section_proxy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OFX
+  class Configuration
+    # Proxy object returned by section accessors (e.g. +OFX.config.transaction+).
+    # Provides a fluent interface for adding individual user-layer field mappings.
+    class SectionProxy
+      def initialize(user_fields, core_fields, xml_tag)
+        @user_fields = user_fields
+        @core_fields = core_fields
+        @xml_tag     = xml_tag
+      end
+
+      # Maps an OFX XML key to a Ruby attribute name for this section.
+      # @param xml_key [String] the OFX XML element name
+      # @param to [String, Symbol] the Ruby attribute name to map to
+      # @raise [ConfigurationError] if xml_key is a core-protected field
+      def map(xml_key, to:)
+        core_attr = @core_fields.dig(@xml_tag.to_s, xml_key.to_s)
+        if core_attr
+          raise OFX::ConfigurationError,
+                "Cannot override core mapping '#{@xml_tag}.#{xml_key}' (reserved as '#{core_attr}')"
+        end
+
+        @user_fields[@xml_tag] ||= {}
+        @user_fields[@xml_tag][xml_key] = to
+      end
+    end
+  end
+end

data/lib/ofx_kit/configuration.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'configuration/core'
+require_relative 'configuration/section_proxy'
+require_relative 'configuration/date_parser'
+require_relative 'configuration/mapping_applicator'

data/lib/ofx_kit/domain/balance.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents the ledger balance of an account at a specific point in time.
+  class Balance < Base::Entity
+    attr_accessor :amount, :amount_cents, :posted_at
+
+    wired_by_builder :statement, :account
+  end
+end

data/lib/ofx_kit/domain/bank_account.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a bank (checking or savings) account parsed from an OFX statement.
+  class BankAccount < Base::Account
+    attr_accessor :bank_id, :account_id, :account_type, :branch_id
+  end
+end

data/lib/ofx_kit/domain/bank_statement.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a complete bank statement parsed from an OFX file,
+  # aggregating the account, its transactions, and the closing balance.
+  class BankStatement < Base::Statement
+    def bank_statement? = true
+  end
+end

data/lib/ofx_kit/domain/credit_card_account.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a credit card account parsed from an OFX statement.
+  class CreditCardAccount < Base::Account
+    attr_accessor :account_id
+  end
+end

data/lib/ofx_kit/domain/credit_card_statement.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a complete credit card statement parsed from an OFX file,
+  # aggregating the account, its transactions, and the closing balance.
+  class CreditCardStatement < Base::Statement
+    def credit_card_statement? = true
+  end
+end

data/lib/ofx_kit/domain/transaction.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a single financial transaction parsed from an OFX statement.
+  class Transaction < Base::Entity
+    attr_accessor :fit_id, :type, :posted_at, :occurred_at,
+                  :amount, :amount_cents,
+                  :name, :memo, :payee,
+                  :check_number, :ref_number, :sic
+
+    wired_by_builder :statement, :account
+  end
+end

data/lib/ofx_kit/domain/transaction_collection.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OFX
+  # An +Enumerable+ collection of {Transaction} objects parsed from an OFX statement.
+  # Provides convenience filters for credits and debits.
+  class TransactionCollection
+    include Enumerable
+
+    # Placeholder overridden per-instance by {Base::Builder#wire} at build time.
+    def statement = nil
+
+    # @param transactions [Array<Transaction>] the list of transactions
+    def initialize(transactions)
+      @transactions = transactions
+    end
+
+    # Iterates over each transaction.
+    # @yieldparam transaction [Transaction]
+    def each(&)
+      @transactions.each(&)
+    end
+
+    # @return [Integer] number of transactions in the collection
+    def length
+      @transactions.length
+    end
+
+    # @return [TransactionCollection] a new collection containing only positive-amount transactions
+    def credits
+      sub = self.class.new(select { |t| t.amount.positive? })
+      # Propagate statement wiring so inferred_currency resolves to the correct
+      # account currency even when this sub-collection has no transactions.
+      if (stmt = statement)
+        sub.define_singleton_method(:statement) { stmt }
+      end
+      sub
+    end
+
+    # @return [TransactionCollection] a new collection containing only negative-amount transactions
+    def debits
+      sub = self.class.new(select { |t| t.amount.negative? })
+      # Same as credits — statement is the authoritative source of currency.
+      if (stmt = statement)
+        sub.define_singleton_method(:statement) { stmt }
+      end
+      sub
+    end
+
+    # @return [Money] sum of all positive transaction amounts
+    def total_credits
+      sum_amounts(credits)
+    end
+
+    # @return [Money] sum of all negative transaction amounts
+    def total_debits
+      sum_amounts(debits)
+    end
+
+    # @return [Money] net amount (credits + debits)
+    # @note This is NOT the account balance. It reflects only the transactions present in
+    #   the OFX file and ignores any accumulated prior balance (e.g. opening cash balance
+    #   or unpaid invoice from a previous period). Use {Balance} for the actual account balance.
+    def net
+      total_credits + total_debits
+    end
+
+    # @return [Array<Transaction>] a duplicate of the internal transactions array
+    def to_a
+      @transactions.dup
+    end
+
+    # @param other [TransactionCollection] collection to compare against
+    # @return [Boolean]
+    def ==(other)
+      @transactions == other.to_a
+    end
+
+    private
+
+    def currency
+      statement&.account&.currency
+    end
+
+    def inferred_currency
+      currency || OFX.config.default_currency
+    end
+
+    def sum_amounts(collection)
+      return Money.new(0, inferred_currency) if collection.none?
+
+      collection.map(&:amount).inject(:+)
+    end
+  end
+end

data/lib/ofx_kit/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OFX
+  # Base error class for all OFX-related exceptions.
+  class Error < StandardError; end
+
+  # Raised when the OFX file cannot be parsed.
+  class ParseError < Error; end
+
+  # Raised when the OFX file header is malformed or missing.
+  class InvalidHeaderError < ParseError; end
+
+  # Raised when the OFX file body cannot be parsed into a valid document.
+  class InvalidBodyError < ParseError; end
+
+  # Raised when the OFX version declared in the file is not supported.
+  class UnsupportedVersionError < Error
+    # @return [String] the unsupported version string found in the file
+    attr_reader :version
+
+    # @param version [String] the unsupported OFX version string
+    def initialize(version)
+      @version = version
+      super("Unsupported OFX version: #{version}")
+    end
+  end
+
+  # Raised when a character encoding error occurs while reading the OFX file.
+  class EncodingError < Error; end
+
+  # Raised when the library configuration is invalid or inconsistent.
+  class ConfigurationError < Error; end
+
+  # Raised when an operation requires a single statement but multiple were found.
+  class MultipleStatementsError < Error; end
+end

data/lib/ofx_kit/mappings/core_mappings.yml

@@ -0,0 +1,23 @@
+SECTIONS:
+  STMTRS:       "bank_statement"
+  CCSTMTRS:     "credit_card_statement"
+  STMTTRN:      "transaction"
+  BANKACCTFROM: "bank_account"
+  CCACCTFROM:   "credit_card_account"
+  LEDGERBAL:    "balance"
+
+FIELDS:
+  STMTRS:
+    CURDEF: "currency"
+
+  CCSTMTRS:
+    CURDEF: "currency"
+
+  STMTTRN:
+    TRNAMT:   "amount"
+    DTPOSTED: "posted_at"
+    DTUSER:   "occurred_at"
+
+  LEDGERBAL:
+    BALAMT: "amount"
+    DTASOF: "posted_at"

data/lib/ofx_kit/mappings/field_mappings.yml

@@ -0,0 +1,19 @@
+FIELDS:
+  STMTTRN:
+    FITID:    "fit_id"
+    TRNTYPE:  "type"
+    NAME:     "name"
+    MEMO:     "memo"
+    PAYEE:    "payee"
+    CHECKNUM: "check_number"
+    REFNUM:   "ref_number"
+    SIC:      "sic"
+
+  BANKACCTFROM:
+    BANKID:   "bank_id"
+    ACCTID:   "account_id"
+    ACCTTYPE: "account_type"
+    BRANCHID: "branch_id"
+
+  CCACCTFROM:
+    ACCTID: "account_id"

data/lib/ofx_kit/parser.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module OFX
+  # Implementation class for OFX parsing.
+  # Prefer the top-level {OFX.new} entry point over instantiating this class directly.
+  #
+  # @api private
+  class Parser
+    # @param resource [String, IO] file path or IO object containing OFX data
+    # @param block [Proc] optional block; receives the parser instance (arity 1)
+    #   or is evaluated in the parser's context (arity != 1)
+    def initialize(resource, &block)
+      @filename  = extract_filename(resource)
+      content    = read_resource(resource)
+      tokenizer  = build_tokenizer(content).new(content)
+      @document  = Base::Document.new(headers: tokenizer.headers, body: tokenizer.body)
+      @statements = Base::Builder.new(@document).statements
+
+      return unless block_given?
+
+      block.arity == 1 ? block.call(self) : instance_eval(&block)
+    end
+
+    # @return [Array<BankStatement, CreditCardStatement>] all statements in the file
+    # @return [String, nil] original file path, if a path string was provided
+    attr_reader :statements, :filename
+
+    # @return [Hash] parsed OFX header fields
+    def headers
+      @document.headers
+    end
+
+    # Returns the account for files containing a single statement.
+    # @return [Account, nil]
+    # @raise [MultipleStatementsError] if the file contains more than one statement
+    def account
+      if statements.length > 1
+        raise MultipleStatementsError, 'File contains multiple statements. Use `accounts` to get all accounts.'
+      end
+
+      statements.first&.account
+    end
+
+    # @return [Array<Account>] all accounts across all statements
+    def accounts
+      statements.map(&:account)
+    end
+
+    # Returns all transactions aggregated across all statements.
+    # Emits a warning when the file contains multiple statements.
+    # @return [TransactionCollection]
+    def transactions
+      if statements.length > 1 && OFX.config.multi_statement_warnings?
+        warn "[OFX] `transactions` is aggregating across #{statements.length} statements. " \
+             'For per-account transactions use `statements[i].transactions`. ' \
+             'To disable this warning: OFX.config.multi_statement_warnings = false'
+      end
+
+      TransactionCollection.new(statements.flat_map { |s| s.transactions.to_a })
+    end
+
+    # Returns the balance for files containing a single statement.
+    # @return [Balance, nil]
+    # @raise [MultipleStatementsError] if the file contains more than one statement
+    def balance
+      if statements.length > 1
+        raise MultipleStatementsError, 'File contains multiple statements. Use `balances` to get all balances.'
+      end
+
+      statements.first&.balance
+    end
+
+    # @return [Array<Balance, nil>] balances for each statement
+    def balances
+      if statements.length > 1 && OFX.config.multi_statement_warnings?
+        warn "[OFX] `balances` is aggregating across #{statements.length} statements. " \
+             'For per-account balance use `statements[i].balance`. ' \
+             'To disable this warning: OFX.config.multi_statement_warnings = false'
+      end
+
+      statements.map(&:balance)
+    end
+
+    # Returns a structured summary of all statements, including transaction counts,
+    # credit/debit totals (in cents), and closing balance.
+    # @return [Hash]
+    def summary
+      {
+        headers: headers.compact,
+        statements: statements.each_with_object({}) do |stmt, h|
+          acct = stmt.account
+          txns = stmt.transactions
+          h[acct.account_id] = {
+            currency: acct.currency,
+            transactions: { count: txns.length, net_cents: txns.net.fractional },
+            credits: { count: txns.credits.length, total_cents: txns.total_credits.fractional },
+            debits: { count: txns.debits.length, total_cents: txns.total_debits.fractional },
+            balance_cents: stmt.balance&.amount&.fractional
+          }
+        end
+      }
+    end
+
+    private
+
+    def extract_filename(resource)
+      case resource
+      when String then resource
+      else resource.respond_to?(:path) ? resource.path : nil
+      end
+    end
+
+    def read_resource(resource)
+      raw = case resource
+            when String        then File.read(resource)
+            when IO, StringIO  then resource.read
+            else raise ArgumentError, "Expected a file path (String) or IO object, got #{resource.class}"
+            end
+
+      raw.encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
+    end
+
+    def build_tokenizer(content)
+      if content.lstrip.start_with?('<?')
+        Tokenizer::OFX2
+      else
+        Tokenizer::OFX1
+      end
+    end
+  end
+end

data/lib/ofx_kit/tokenizer/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OFX
+  module Tokenizer
+    # Abstract base class for OFX tokenizers.
+    # Subclasses must implement {#parse!} to populate +@headers+ and +@body+
+    # from the raw file content.
+    class Base
+      # @return [Hash] parsed header key/value pairs
+      # @return [Nokogiri::XML::Document] parsed XML body
+      attr_reader :headers, :body
+
+      # @param content [String] raw OFX file content
+      def initialize(content)
+        @content = content.dup.force_encoding('UTF-8')
+        parse!
+      end
+
+      private
+
+      def parse!
+        raise NotImplementedError, "#{self.class} must implement #parse!"
+      end
+
+      def convert_to_utf8(str)
+        return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+
+        str.encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
+      rescue Encoding::UndefinedConversionError
+        str.dup.force_encoding('ISO-8859-1').encode('UTF-8')
+      end
+    end
+  end
+end

data/lib/ofx_kit/tokenizer/ofx1.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module OFX
+  module Tokenizer
+    # Tokenizer for OFX version 1 files, which use an SGML-like format.
+    # Splits the file into a colon-separated header section and an SGML body,
+    # then normalizes the body into valid XML before parsing with Nokogiri.
+    class OFX1 < Base
+      private
+
+      def parse!
+        content = convert_to_utf8(@content)
+        parts   = content.split(/<OFX>/i, 2)
+
+        raise InvalidHeaderError, 'Missing <OFX> tag in OFX file' if parts.size < 2
+
+        @headers = parse_headers(parts[0])
+        @body    = parse_body("<OFX>#{parts[1]}")
+      end
+
+      def parse_headers(raw)
+        raw.lines.each_with_object({}) do |line, result|
+          line = line.strip
+          next if line.empty?
+
+          key, value = line.split(':', 2)
+          next unless key && value
+
+          result[key.strip] = value.strip == 'NONE' ? nil : value.strip
+        end
+      end
+
+      def parse_body(raw)
+        normalized = normalize_sgml(raw)
+        doc = Nokogiri::XML(normalized, &:nonet)
+        raise InvalidBodyError, "OFX body could not be parsed: #{doc.errors.first}" if doc.errors.any?
+
+        doc
+      end
+
+      def normalize_sgml(body)
+        body.gsub(%r{(<([A-Z0-9_]+)>)\s*([^<\r\n][^<\r\n]*)(</\2>)?}) do
+          tag_open = ::Regexp.last_match(1)
+          tag_name = ::Regexp.last_match(2)
+          content  = ::Regexp.last_match(3).strip
+          "#{tag_open}#{content}</#{tag_name}>"
+        end
+      end
+    end
+  end
+end