ofx_kit 0.1.0 → 1.0.0

data/lib/ofx_kit/{domain/credit_card_account.rb → credit_card_account.rb}

@@ -3,6 +3,7 @@
 module OFX
   # Represents a credit card account parsed from an OFX statement.
   class CreditCardAccount < Base::Account
+    # Credit card account number (String).
     attr_accessor :account_id
   end
 end

data/lib/ofx_kit/{domain/credit_card_statement.rb → credit_card_statement.rb}

@@ -4,6 +4,7 @@ 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
+    # Always +true+.
     def credit_card_statement? = true
   end
 end

data/lib/ofx_kit/errors/configuration_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when the library configuration is invalid or inconsistent.
+    class ConfigurationError < Error; end
+  end
+end

data/lib/ofx_kit/errors/encoding_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when a character encoding error occurs while reading the OFX file.
+    class EncodingError < Error; end
+  end
+end

data/lib/ofx_kit/errors/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OFX
+  # Namespace for all gem-specific exception classes.
+  # All errors inherit from Errors::Error, so callers can rescue the entire hierarchy
+  # with <tt>rescue OFX::Errors::Error</tt>.
+  module Errors
+    # Base error class for all OFX-related exceptions.
+    class Error < StandardError; end
+  end
+end

data/lib/ofx_kit/errors/invalid_body_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when the OFX file body cannot be parsed into a valid document.
+    class InvalidBodyError < ParseError; end
+  end
+end

data/lib/ofx_kit/errors/invalid_header_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when the OFX file header is malformed or missing.
+    class InvalidHeaderError < ParseError; end
+  end
+end

data/lib/ofx_kit/errors/multiple_statements_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when an operation requires a single statement but multiple were found.
+    class MultipleStatementsError < Error; end
+  end
+end

data/lib/ofx_kit/errors/parse_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    # Raised when the OFX file cannot be parsed.
+    class ParseError < Error; end
+  end
+end

data/lib/ofx_kit/errors/unsupported_version_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OFX
+  module Errors
+    ##
+    # Raised when the OFX version declared in the file is not supported.
+    class UnsupportedVersionError < Error
+      ##
+      # The unsupported version string found in the file (String).
+      attr_reader :version
+
+      ##
+      # Creates a new error for the given unsupported +version+ string.
+      def initialize(version)
+        @version = version
+        super("Unsupported OFX version: #{version}")
+      end
+    end
+  end
+end

data/lib/ofx_kit/parser.rb

@@ -1,19 +1,21 @@
 # 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
+  ##
+  # The object returned by OFX.new. Provides access to the parsed statements,
+  # accounts, transactions, and balances from an OFX file or IO object.
+  # Prefer the top-level OFX.new entry point over instantiating this class directly.
   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)
+    ##
+    # Parses the given OFX +resource+ and builds the statement graph.
+    # +resource+ is a file path (String) or IO object containing OFX data.
+    # If a +block+ is given with arity 1, it receives the parser instance;
+    # otherwise it is evaluated in the parser's context.
     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)
+      @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?
@@ -21,34 +23,69 @@ module OFX
       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
+    ##
+    # All statements in the file (Array of BankStatement or CreditCardStatement).
+    #
+    # === Example: Iterate statements in a multi-account file
+    #
+    #   ofx = OFX.new("multi.ofx")
+    #   ofx.statements.each do |stmt|
+    #     puts "#{stmt.account.account_id}: #{stmt.transactions.length} transactions"
+    #   end
+    attr_reader :statements
+
+    ##
+    # Original file path, if a path string was provided (String or +nil+).
+    attr_reader :filename
+
+    ##
+    # Returns the parsed OFX header fields (Hash).
     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
+    ##
+    # Returns the account for files containing a single statement
+    # (BankAccount, CreditCardAccount, or +nil+).
+    # Raises Errors::MultipleStatementsError if the file contains more than one statement.
+    #
+    # === Example
+    #
+    #   ofx = OFX.new("statement.ofx")
+    #   ofx.account.account_id    #=> "123456789"
+    #   ofx.account.currency      #=> "USD"
+    #   ofx.account.bank_id       #=> "021000021"   # BankAccount only
     def account
       if statements.length > 1
-        raise MultipleStatementsError, 'File contains multiple statements. Use `accounts` to get all accounts.'
+        raise Errors::MultipleStatementsError, 'File contains multiple statements. Use `accounts` to get all accounts.'
       end
 
       statements.first&.account
     end
 
-    # @return [Array<Account>] all accounts across all statements
+    ##
+    # Returns all accounts across all statements
+    # (Array of BankAccount or CreditCardAccount).
+    #
+    # === Example: Multi-statement file
+    #
+    #   ofx = OFX.new("multi.ofx")
+    #   ofx.accounts.map(&:account_id)  #=> ["123456", "789012"]
     def accounts
       statements.map(&:account)
     end
 
-    # Returns all transactions aggregated across all statements.
+    ##
+    # Returns all transactions aggregated across all statements as a TransactionCollection.
     # Emits a warning when the file contains multiple statements.
-    # @return [TransactionCollection]
+    #
+    # === Example
+    #
+    #   ofx = OFX.new("statement.ofx")
+    #   ofx.transactions.length               #=> 42
+    #   ofx.transactions.credits.length       #=> 10
+    #   ofx.transactions.total_debits.format  #=> "-$1,234.56"
+    #   ofx.transactions.net.format           #=> "$500.00"
     def transactions
       if statements.length > 1 && OFX.config.multi_statement_warnings?
         warn "[OFX] `transactions` is aggregating across #{statements.length} statements. " \
@@ -59,18 +96,26 @@ module OFX
       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
+    ##
+    # Returns the balance for files containing a single statement (Balance or +nil+).
+    # Raises Errors::MultipleStatementsError if the file contains more than one statement.
+    #
+    # === Example
+    #
+    #   ofx = OFX.new("statement.ofx")
+    #   ofx.balance.amount.format  #=> "$2,500.00"
+    #   ofx.balance.amount_cents   #=> 250000
+    #   ofx.balance.posted_at      #=> 2024-01-31 00:00:00 +0000
     def balance
       if statements.length > 1
-        raise MultipleStatementsError, 'File contains multiple statements. Use `balances` to get all balances.'
+        raise Errors::MultipleStatementsError, 'File contains multiple statements. Use `balances` to get all balances.'
       end
 
       statements.first&.balance
     end
 
-    # @return [Array<Balance, nil>] balances for each statement
+    ##
+    # Returns balances for each statement (Array of Balance or +nil+).
     def balances
       if statements.length > 1 && OFX.config.multi_statement_warnings?
         warn "[OFX] `balances` is aggregating across #{statements.length} statements. " \
@@ -81,9 +126,16 @@ module OFX
       statements.map(&:balance)
     end
 
+    ##
     # Returns a structured summary of all statements, including transaction counts,
     # credit/debit totals (in cents), and closing balance.
-    # @return [Hash]
+    #
+    # Returns a Hash with keys:
+    # - +:headers+ — compact OFX header fields
+    # - +:statements+ — hash keyed by account_id, each with:
+    #   +:currency+, +:transactions+ ({count:, net_cents:}),
+    #   +:credits+ ({count:, total_cents:}), +:debits+ ({count:, total_cents:}),
+    #   +:balance_cents+
     def summary
       {
         headers: headers.compact,

data/lib/ofx_kit/tokenizer/base.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 module OFX
-  module Tokenizer
+  module Tokenizer # :nodoc:
+    ##
     # Abstract base class for OFX tokenizers.
-    # Subclasses must implement {#parse!} to populate +@headers+ and +@body+
+    # 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
+      ##
+      # Parsed header key/value pairs (Hash).
+      attr_reader :headers
+      ##
+      # Parsed XML body (Nokogiri::XML::Document).
+      attr_reader :body
 
-      # @param content [String] raw OFX file content
+      ##
+      # Creates a new tokenizer and immediately parses +content+ (raw OFX String).
       def initialize(content)
         @content = content.dup.force_encoding('UTF-8')
         parse!

data/lib/ofx_kit/tokenizer/ofx1.rb

@@ -14,7 +14,7 @@ module OFX
         content = convert_to_utf8(@content)
         parts   = content.split(/<OFX>/i, 2)
 
-        raise InvalidHeaderError, 'Missing <OFX> tag in OFX file' if parts.size < 2
+        raise Errors::InvalidHeaderError, 'Missing <OFX> tag in OFX file' if parts.size < 2
 
         @headers = parse_headers(parts[0])
         @body    = parse_body("<OFX>#{parts[1]}")
@@ -35,7 +35,7 @@ module OFX
       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?
+        raise Errors::InvalidBodyError, "OFX body could not be parsed: #{doc.errors.first}" if doc.errors.any?
 
         doc
       end

data/lib/ofx_kit/tokenizer/ofx2.rb

@@ -11,7 +11,7 @@ module OFX
         content = convert_to_utf8(@content)
         doc     = Nokogiri::XML(content, &:nonet)
 
-        raise InvalidBodyError, "OFX2 body could not be parsed: #{doc.errors.first}" if doc.errors.any?
+        raise Errors::InvalidBodyError, "OFX2 body could not be parsed: #{doc.errors.first}" if doc.errors.any?
 
         @headers = parse_headers(doc)
         @body    = doc

data/lib/ofx_kit/transaction.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a single financial transaction parsed from an OFX statement.
+  #
+  # === Example
+  #
+  #   txn = OFX.new("statement.ofx").transactions.first
+  #   txn.type         #=> "DEBIT"
+  #   txn.name         #=> "AMAZON.COM"
+  #   txn.amount       #=> #<Money fractional:-5099 currency:USD>
+  #   txn.posted_at    #=> 2024-01-15 00:00:00 +0000
+  #   txn.account      #=> #<OFX::BankAccount ...>
+  #   txn.statement    #=> #<OFX::BankStatement ...>
+  class Transaction < Base::Entity
+    # Unique transaction identifier / FITID (String).
+    attr_accessor :fit_id
+    # Transaction type, e.g. "DEBIT", "CREDIT", "CHECK" (String).
+    attr_accessor :type
+    # Date the transaction was posted (Time or +nil+).
+    attr_accessor :posted_at
+    # Date the transaction actually occurred (Time or +nil+).
+    attr_accessor :occurred_at
+    # Transaction amount as a Money object (or +nil+).
+    attr_accessor :amount
+    # Transaction amount in the smallest currency unit, e.g. cents (Integer or +nil+).
+    attr_accessor :amount_cents
+    # Payee or description name (String or +nil+).
+    attr_accessor :name
+    # Memo or additional description (String or +nil+).
+    attr_accessor :memo
+    # Payee name from the PAYEE field, when present (String or +nil+).
+    attr_accessor :payee
+    # Check number, if applicable (String or +nil+).
+    attr_accessor :check_number
+    # Reference number (String or +nil+).
+    attr_accessor :ref_number
+    # Standard industry code / SIC (String or +nil+).
+    attr_accessor :sic
+
+    # The statement (BankStatement or CreditCardStatement) and account
+    # (BankAccount or CreditCardAccount) this transaction belongs to.
+    wired_by_builder :statement, :account
+  end
+end

data/lib/ofx_kit/transaction_collection.rb

@@ -0,0 +1,126 @@
+# 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
+
+    ##
+    # The statement (BankStatement, CreditCardStatement, or +nil+) this collection belongs to.
+    # Overridden per-instance by Base::Builder at build time.
+    def statement = nil
+
+    ##
+    # Creates a new collection from +transactions+ (Array of Transaction).
+    def initialize(transactions)
+      @transactions = transactions
+    end
+
+    ##
+    # Iterates over each transaction.
+    #
+    # :yields: transaction
+    def each(&)
+      @transactions.each(&)
+    end
+
+    ##
+    # Returns the number of transactions in the collection (Integer).
+    def length
+      @transactions.length
+    end
+
+    ##
+    # Returns a new TransactionCollection containing only positive-amount transactions.
+    #
+    # === Example
+    #
+    #   ofx.transactions.credits.length        #=> 5
+    #   ofx.transactions.credits.first.amount  #=> #<Money fractional:10000 currency:USD>
+    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
+
+    ##
+    # Returns a new TransactionCollection containing only negative-amount transactions.
+    #
+    # === Example
+    #
+    #   ofx.transactions.debits.length             #=> 37
+    #   ofx.transactions.debits.first.name         #=> "AMAZON.COM"
+    #   ofx.transactions.debits.first.amount_cents #=> -5099
+    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
+
+    ##
+    # Returns the sum of all positive transaction amounts as a Money object.
+    #
+    # === Example
+    #
+    #   ofx.transactions.total_credits.format  #=> "$350.00"
+    def total_credits
+      sum_amounts(credits)
+    end
+
+    ##
+    # Returns the sum of all negative transaction amounts as a Money object.
+    #
+    # === Example
+    #
+    #   ofx.transactions.total_debits.format  #=> "-$1,234.56"
+    def total_debits
+      sum_amounts(debits)
+    end
+
+    ##
+    # Returns the net amount (credits + debits) as a Money object.
+    # 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.
+    #
+    # === Example
+    #
+    #   ofx.transactions.net.format  #=> "$500.00"
+    def net
+      total_credits + total_debits
+    end
+
+    ##
+    # Returns a duplicate of the internal transactions array.
+    def to_a
+      @transactions.dup
+    end
+
+    ##
+    # Returns +true+ if both collections contain the same transactions as +other+.
+    def ==(other)
+      @transactions == other.to_a
+    end
+
+    private
+
+    def currency
+      statement&.account&.currency
+    end
+
+    def sum_amounts(collection)
+      return Money.new(0, currency) if collection.none?
+
+      collection.map(&:amount).inject(:+)
+    end
+  end
+end

data/lib/ofx_kit/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module OFX
-  VERSION = '0.1.0'
+  # Current gem version (String).
+  VERSION = '1.0.0'
 end

data/lib/ofx_kit.rb

@@ -8,50 +8,64 @@ require 'stringio'
 require 'time'
 
 require_relative 'ofx_kit/version'
-require_relative 'ofx_kit/errors'
-require_relative 'ofx_kit/configuration'
+require_relative 'ofx_kit/errors/error'
+require_relative 'ofx_kit/errors/parse_error'
+require_relative 'ofx_kit/errors/invalid_header_error'
+require_relative 'ofx_kit/errors/invalid_body_error'
+require_relative 'ofx_kit/errors/unsupported_version_error'
+require_relative 'ofx_kit/errors/encoding_error'
+require_relative 'ofx_kit/errors/configuration_error'
+require_relative 'ofx_kit/errors/multiple_statements_error'
+require_relative 'ofx_kit/configuration/core'
+require_relative 'ofx_kit/configuration/section_proxy'
+require_relative 'ofx_kit/configuration/date_parser'
+require_relative 'ofx_kit/configuration/mapping_applicator'
 require_relative 'ofx_kit/base/entity'
 require_relative 'ofx_kit/base/account'
 require_relative 'ofx_kit/base/statement'
 require_relative 'ofx_kit/base/document'
-require_relative 'ofx_kit/domain/bank_account'
-require_relative 'ofx_kit/domain/credit_card_account'
-require_relative 'ofx_kit/domain/transaction'
-require_relative 'ofx_kit/domain/transaction_collection'
-require_relative 'ofx_kit/domain/balance'
-require_relative 'ofx_kit/domain/bank_statement'
-require_relative 'ofx_kit/domain/credit_card_statement'
+require_relative 'ofx_kit/bank_account'
+require_relative 'ofx_kit/credit_card_account'
+require_relative 'ofx_kit/transaction'
+require_relative 'ofx_kit/transaction_collection'
+require_relative 'ofx_kit/balance'
+require_relative 'ofx_kit/bank_statement'
+require_relative 'ofx_kit/credit_card_statement'
 require_relative 'ofx_kit/base/builder'
 require_relative 'ofx_kit/tokenizer/base'
 require_relative 'ofx_kit/tokenizer/ofx1'
 require_relative 'ofx_kit/tokenizer/ofx2'
 require_relative 'ofx_kit/parser'
 
+##
 # Top-level namespace for the ofx_kit gem.
-# Provides module-level access to the shared {Configuration} instance and
-# a {.configure} block for customizing field mappings and XML tags.
+# Provides module-level access to the shared Configuration instance and
+# a configure block for customizing field mappings and XML tags.
+#
+# === Example: Configure custom field mappings
 #
-# @example Configure custom field mappings
 #   OFX.configure do |config|
 #     config.transaction.map 'MYFIELD', to: :my_attribute
 #   end
 module OFX
   class << self
-    # Parses an OFX file or IO object and returns a {Parser} instance.
+    ##
+    # Parses an OFX file or IO object and returns a Parser instance.
     # This is the primary entry point for the gem.
+    # +resource+ is a file path (String) or IO object containing OFX data.
     #
-    # @param resource [String, IO] file path or IO object containing OFX data
-    # @return [Parser]
+    # === Example: Parse a file path
     #
-    # @example Parse a file path
     #   ofx = OFX.new("statement.ofx")
     #   ofx.account       #=> OFX::BankAccount
     #   ofx.transactions  #=> OFX::TransactionCollection
     #
-    # @example Parse an IO object
+    # === Example: Parse an IO object
+    #
     #   ofx = OFX.new(File.open("statement.ofx"))
     #
-    # @example Block form
+    # === Example: Block form
+    #
     #   OFX.new("statement.ofx") do |ofx|
     #     puts ofx.balance
     #   end
@@ -59,22 +73,27 @@ module OFX
       Parser.new(resource, &)
     end
 
-    # Yields the current {Configuration} instance for customization.
-    # @yieldparam config [Configuration]
-    # @raise [ConfigurationError] if the block raises any error
+    ##
+    # Yields the current Configuration instance for customization.
+    #
+    # :yields: config
+    #
+    # Raises Errors::ConfigurationError if the block raises any error.
     def configure
       yield config
-    rescue ConfigurationError
+    rescue Errors::ConfigurationError
       raise
     rescue StandardError => e
-      raise ConfigurationError, e.message
+      raise Errors::ConfigurationError, e.message
     end
 
-    # @return [Configuration] the shared configuration instance (lazy-initialized)
+    ##
+    # Returns the shared configuration instance (lazy-initialized).
     def config
       @config ||= Configuration.new
     end
 
+    ##
     # Resets the configuration to its default state.
     # Useful in tests to restore default field mappings between examples.
     def reset_config!