ofx_kit 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f82d22f9c1dce1691202e851448967eccd5ee7438871b10b5392038c128f084
-  data.tar.gz: 1bb156f591d24d2297457e7e0a27a7bcf13bb003fc69670c349285af757610de
+  metadata.gz: 56019a467dfb822daae452b467ec5e51cc6044513048e5fa6ed2db82522e39d0
+  data.tar.gz: aba4a9a24703b9b7b58af9a3c04ec271a8d6d5c2975163487ee61e551a8fcf6f
 SHA512:
-  metadata.gz: 8586682ea5992fb07a2fa516bc02f113cad703034d97fa088590fd55c913e9996a850e43d5442898af6642b37d3af9563584038912454db5e96a9371089e6b8e
-  data.tar.gz: 7e8ab351c06a24a55d13299563bce802e32247c22d6046d36aef40f43c010dfa9597a1b7481108fca7f635886638a0a340c3ff6d8c658b37ec990bad6790811e
+  metadata.gz: e07dc48f4349908f645485553f10ed1aa76ede8927e89b6da95137f1a5a7bf3258d8e03835e58c060bbf0a12921a725b36105712ef9b8490f401f8ae125de25a
+  data.tar.gz: d09b9ff3bd3d04ad198d12a0bca8ee4e12ee2b2d9daa09e08c6d832bff2243c13e22e6fee0497a6b0fcc2e315c6d4ae6472b4078d7e63e6b544738e52e70fc2b

data/README.md

@@ -1,4 +1,7 @@
-# OFX
+# OFX Kit
+
+[![Gem Version](https://badge.fury.io/rb/ofx_kit.svg)](https://badge.fury.io/rb/ofx_kit) [![Downloads](https://img.shields.io/gem/dt/ofx_kit?label=Downloads)](https://rubygems.org/gems/ofx_kit)
+
 
 A Ruby gem for parsing OFX (Open Financial Exchange) files. Supports OFX 1.x (SGML) and OFX 2.x (XML), bank statements and credit card statements, with a fluent API and configurable field mappings.
 
@@ -123,47 +126,46 @@ ofx.balance   # => OFX::MultipleStatementsError (use `balances`)
 
 ## Configuration
 
-Use `map` to bind OFX XML tags to Ruby attribute names of your choice.
+### Field mappings
 
-### Adding new fields
-
-Map proprietary XML tags that your bank emits but the gem doesn't know about by default:
+Use `map` to add new attributes or rename built-in ones:
 
 ```ruby
 OFX.configure do |config|
-  config.bank_account.map "AGENCIA", to: "branch_code"
-  config.transaction.map "HISPAYEEMEMO", to: "extended_memo"
-end
-
-ofx = OFX.new("statement.ofx")
-ofx.account.branch_code              # => "0272"
-ofx.transactions.first.extended_memo # => "Tarifa bancaria"
-```
-
-### Renaming built-in fields
+  # New field: your bank emits a tag the gem doesn't know about by default
+  config.bank_account.map "AGENCIA",      to: "branch_code"
+  config.transaction.map  "HISPAYEEMEMO", to: "extended_memo"
 
-`map` renames the default attribute for any non-protected OFX tag:
-
-```ruby
-OFX.configure do |config|
+  # Rename a built-in field to a name that fits your domain
   config.transaction.map "FITID", to: "uid"   # default is fit_id
   config.transaction.map "NAME",  to: "payee_name"
 end
 
 ofx = OFX.new("statement.ofx")
-ofx.transactions.first.uid        # => "20240115001"
-ofx.transactions.first.payee_name # => "ACME Corp"
-# ofx.transactions.first.fit_id  # => nil (FITID is now mapped to uid)
+ofx.account.branch_code               # => "0272"
+ofx.transactions.first.extended_memo  # => "Tarifa bancaria"
+ofx.transactions.first.uid            # => "20240115001"
+# ofx.transactions.first.fit_id       # => nil (FITID is now mapped to uid)
 ```
 
-> **Protected core fields** — The following OFX fields are used internally by the
-> gem to build Money objects and parse dates. They cannot be renamed:
-> `CURDEF`, `TRNAMT`, `DTPOSTED`, `DTUSER`, `BALAMT`, `DTASOF`.
-> Attempting to remap them raises `OFX::ConfigurationError`.
+> **Protected core fields** — `CURDEF`, `TRNAMT`, `DTPOSTED`, `DTUSER`, `BALAMT`, `DTASOF`
+> are used internally to build Money objects and parse dates. They cannot be renamed;
+> attempting to do so raises `OFX::ConfigurationError`.
 
 ### Loading mappings from a YAML file
 
-For larger configurations, use a YAML file instead of inline `map` calls:
+For larger configurations or Rails apps, a YAML file is cleaner than inline `map` calls.
+
+**Rails** — eject the template with:
+
+```bash
+rails generate ofx:eject
+```
+
+This creates `config/initializers/ofx_mappings.yml`, which the gem detects and loads
+automatically on boot — no `OFX.configure` call needed.
+
+**Standalone** — point `load_mappings` at any YAML file:
 
 ```ruby
 OFX.configure do |config|
@@ -171,35 +173,15 @@ OFX.configure do |config|
 end
 ```
 
-The file must have a `FIELDS:` top-level key, with OFX section tags underneath.
-Each entry maps an XML tag to the Ruby attribute name you want to use:
+The file must have a `FIELDS:` top-level key:
 
 ```yaml
 FIELDS:
   STMTTRN:
-    # New field: your bank emits HISPAYEEMEMO but the gem doesn't know it by default
-    HISPAYEEMEMO: extended_memo      # → transaction.extended_memo
-
-    # Override: rename a standard field to a name that fits your domain
-    FITID: uid                       # → transaction.uid  (default was fit_id)
-
+    HISPAYEEMEMO: extended_memo   # → transaction.extended_memo (new field)
+    FITID: uid                    # → transaction.uid  (default was fit_id)
   BANKACCTFROM:
-    # New field: Brazilian banks emit AGENCIA for the branch number
-    AGENCIA: branch_code             # → account.branch_code
-```
-
-After loading:
-
-```ruby
-ofx = OFX.new("statement.ofx")
-
-# Custom fields — read proprietary XML tags as Ruby attributes
-ofx.transactions.first.extended_memo  # => "Tarifa bancaria"
-ofx.account.branch_code               # => "0272"
-
-# Overridden field — standard tag mapped to a different name
-ofx.transactions.first.uid            # => "20240115001"
-# ofx.transactions.first.fit_id       # => nil (FITID is now mapped to uid)
+    AGENCIA: branch_code          # → account.branch_code (new field)
 ```
 
 ### Silencing warnings
@@ -210,40 +192,12 @@ ofx.transactions.first.uid            # => "20240115001"
 OFX.config.multi_statement_warnings = false
 ```
 
-### Default currency
-
-When a `TransactionCollection` is empty and has no statement context (e.g. an in-memory collection built in tests), aggregation methods like `total_credits` and `net` need a currency to produce a `Money.new(0, ...)` value. The fallback is `OFX.config.default_currency`, which defaults to `'USD'`:
-
-```ruby
-OFX.config.default_currency = 'BRL'
-```
+### Currency
 
-In normal usage this fallback is never reached — the gem wires every collection to its statement at parse time and reads the currency directly from `statement.account.currency`.
+The OFX specification requires `CURDEF` in every statement (`STMTRS` / `CCSTMTRS`). If the tag is absent, the gem raises `OFX::Errors::InvalidBodyError` rather than silently assuming a currency.
 
 ### Rails
 
-**Field mappings** — run the eject generator to copy the default mappings into your app:
-
-```bash
-rails generate ofx:eject
-```
-
-This creates `config/initializers/ofx_mappings.yml` with all default mappings.
-The OFX gem detects and loads this file automatically on boot — no initializer or
-`OFX.configure` call needed.
-
-Edit the file to rename built-in fields or capture bank-specific XML tags:
-
-```yaml
-# config/initializers/ofx_mappings.yml
-FIELDS:
-  STMTTRN:
-    FITID: "uid"                      # transaction.fit_id → transaction.uid
-    HISPAYEEMEMO: "extended_memo"     # → transaction.extended_memo (new field)
-  BANKACCTFROM:
-    AGENCIA: "branch_code"            # → account.branch_code (new field)
-```
-
 **Behavioral options** — create a standard initializer:
 
 ```ruby

data/lib/generators/{ofx → ofx_kit}/eject_generator.rb

@@ -2,7 +2,8 @@
 
 require 'rails/generators'
 
-module Ofx
+module OFX
+  # Namespace for Rails generator classes provided by the ofx_kit gem.
   module Generators
     # Ejects OFX field mappings into the Rails application so they can be customized.
     #
@@ -10,8 +11,9 @@ module Ofx
     # mappings. The file is auto-detected and loaded by the OFX gem on boot —
     # no initializer or +OFX.configure+ call is needed.
     #
-    # @example
-    #   rails generate ofx:eject
+    # === Example
+    #
+    #   rails generate ofx_kit:eject
     class EjectGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
 

data/lib/ofx_kit/balance.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents the ledger balance of an account at a specific point in time.
+  #
+  # === Example
+  #
+  #   bal = OFX.new("statement.ofx").balance
+  #   bal.amount.format  #=> "$2,500.00"
+  #   bal.amount_cents   #=> 250000
+  #   bal.posted_at      #=> 2024-01-31 00:00:00 +0000
+  #   bal.account        #=> #<OFX::BankAccount ...>
+  class Balance < Base::Entity
+    # Closing balance as a Money object (or +nil+).
+    attr_accessor :amount
+    # Closing balance in the smallest currency unit, e.g. cents (Integer or +nil+).
+    attr_accessor :amount_cents
+    # Date the balance was posted (Time or +nil+).
+    attr_accessor :posted_at
+
+    # The statement (BankStatement or CreditCardStatement) and account
+    # (BankAccount or CreditCardAccount) this balance belongs to.
+    wired_by_builder :statement, :account
+  end
+end

data/lib/ofx_kit/bank_account.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OFX
+  # Represents a bank (checking or savings) account parsed from an OFX statement.
+  #
+  # === Example
+  #
+  #   account = OFX.new("bank.ofx").account
+  #   account.account_id    #=> "123456789"
+  #   account.bank_id       #=> "021000021"
+  #   account.account_type  #=> "CHECKING"
+  #   account.currency      #=> "USD"
+  #   account.balance       #=> #<OFX::Balance ...>
+  #   account.transactions  #=> #<OFX::TransactionCollection ...>
+  class BankAccount < Base::Account
+    # Routing number of the financial institution (String or +nil+).
+    attr_accessor :bank_id
+    # Account number (String).
+    attr_accessor :account_id
+    # Account type, e.g. "CHECKING", "SAVINGS" (String or +nil+).
+    attr_accessor :account_type
+    # Branch identifier, when present (String or +nil+).
+    attr_accessor :branch_id
+  end
+end

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

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

data/lib/ofx_kit/base/account.rb

@@ -4,8 +4,11 @@ module OFX
   module Base
     # Abstract base class for financial accounts.
     class Account < Entity
+      # ISO 4217 currency code, e.g. "USD", "BRL" (String).
       attr_accessor :currency
 
+      # The statement (BankStatement or CreditCardStatement), closing balance (Balance or
+      # +nil+), and transactions (TransactionCollection) for this account.
       wired_by_builder :statement, :balance, :transactions
     end
   end

data/lib/ofx_kit/base/builder.rb

@@ -2,18 +2,22 @@
 
 module OFX
   module Base
-    # Constructs domain objects ({BankStatement}, {CreditCardStatement}, etc.)
-    # from a parsed {Base::Document}. Applies field mappings defined in {Configuration}
+    ##
+    # Constructs domain objects (BankStatement, CreditCardStatement, etc.)
+    # from a parsed Base::Document. Applies field mappings defined in Configuration
     # and converts raw OFX values (amounts, dates) into typed Ruby objects.
-    class Builder
+    class Builder # :nodoc:
       include Configuration::DateParser
       include Configuration::MappingApplicator
 
+      ##
+      # Creates a new builder for the given +document+ (Base::Document).
       def initialize(document)
         @document = document
       end
 
-      # @return [Array<BankStatement, CreditCardStatement>]
+      ##
+      # Returns all parsed statements (Array of BankStatement or CreditCardStatement).
       def statements
         @document.bank_statement_nodes.map { |n| build_bank_statement(n) } +
           @document.credit_card_statement_nodes.map { |n| build_credit_card_statement(n) }

data/lib/ofx_kit/base/document.rb

@@ -2,28 +2,40 @@
 
 module OFX
   module Base
+    ##
     # Wraps the parsed OFX file, providing access to headers and XML body nodes.
-    # Consumers use {#bank_statement_nodes} and {#credit_card_statement_nodes}
+    # Consumers use #bank_statement_nodes and #credit_card_statement_nodes
     # to extract statement data for domain object construction.
     class Document
+      ##
+      # Parsed OFX header key/value pairs (Hash).
       attr_reader :headers
 
+      ##
+      # Creates a new document.
+      # +headers+ is a Hash of parsed OFX header key/value pairs.
+      # +body+ is a Nokogiri::XML::Document of the parsed OFX body.
       def initialize(headers:, body:)
         @headers = headers
         @body    = body
       end
 
-      # @return [String, nil] OFX version declared in the file header
+      ##
+      # Returns the OFX version declared in the file header (String or +nil+).
       def version
         @headers['VERSION']
       end
 
-      # @return [Nokogiri::XML::NodeSet] all STMTRS (bank statement) nodes in the document
+      ##
+      # Returns all STMTRS (bank statement) nodes in the document
+      # (Nokogiri::XML::NodeSet).
       def bank_statement_nodes
         @body.css('STMTRS')
       end
 
-      # @return [Nokogiri::XML::NodeSet] all CCSTMTRS (credit card statement) nodes in the document
+      ##
+      # Returns all CCSTMTRS (credit card statement) nodes in the document
+      # (Nokogiri::XML::NodeSet).
       def credit_card_statement_nodes
         @body.css('CCSTMTRS')
       end

data/lib/ofx_kit/base/entity.rb

@@ -1,19 +1,29 @@
 # frozen_string_literal: true
 
 module OFX
-  module Base
+  module Base # :nodoc:
+    ##
     # Abstract base for domain objects that support dynamic field mappings
-    # and relationship wiring via {Base::Builder}.
+    # and relationship wiring via Base::Builder.
     #
     # Subclasses gain two class-level macros:
-    # - {.ensure_attribute} — dynamically adds +attr_accessor+ for custom mapped fields
-    # - {.wired_by_builder} — declares nil-returning placeholder methods that
-    #   {Base::Builder#wire_relations} overrides per-instance at build time
+    # - .ensure_attribute — dynamically adds +attr_accessor+ for custom mapped fields
+    # - .wired_by_builder — declares nil-returning placeholder methods that
+    #   Base::Builder#wire_relations overrides per-instance at build time
     class Entity
+      ##
+      # Ensures the given attribute exists on the class, adding +attr_accessor+ if needed.
+      # Called by Base::Builder when applying custom field mappings.
+      # +name+ is an attribute name (String or Symbol).
       def self.ensure_attribute(name)
         attr_accessor name.to_sym unless method_defined?(name)
       end
 
+      ##
+      # Declares one or more placeholder instance methods that return +nil+.
+      # Base::Builder replaces each with a singleton method on the built instance
+      # that returns the wired relation.
+      # +names+ is an Array of Symbol relation names to declare.
       def self.wired_by_builder(*names)
         names.each { |name| define_method(name) { nil } }
       end

data/lib/ofx_kit/base/statement.rb

@@ -2,18 +2,36 @@
 
 module OFX
   module Base
+    ##
     # Base class for OFX statement types, aggregating an account,
     # its transactions, and the closing balance.
     class Statement
-      attr_accessor :account, :transactions, :balance
+      ##
+      # The account associated with this statement (BankAccount or CreditCardAccount).
+      attr_accessor :account
+      ##
+      # The transactions in this statement (TransactionCollection).
+      attr_accessor :transactions
+      ##
+      # The closing balance for this statement (Balance or +nil+).
+      attr_accessor :balance
 
+      ##
+      # Creates a new statement.
+      # +account+ is a BankAccount or CreditCardAccount.
+      # +transactions+ is a TransactionCollection.
+      # +balance+ is a Balance or +nil+.
       def initialize(account:, transactions:, balance:)
         @account      = account
         @transactions = transactions
         @balance      = balance
       end
 
+      ##
+      # Always +false+.
       def bank_statement?        = false
+      ##
+      # Always +false+.
       def credit_card_statement? = false
     end
   end

data/lib/ofx_kit/configuration/core.rb

@@ -3,31 +3,45 @@
 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.
+  # - *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
+    ##
+    # Absolute path to the built-in core OFX field mappings (read-only).
     CORE_MAPPINGS_PATH = File.join(__dir__, '..', 'mappings', 'core_mappings.yml')
+    ##
+    # Absolute path to the built-in user-layer field mappings.
     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+.
+    # Auto-loaded on boot when present. Ejected via +rails generate ofx_kit:eject+.
     RAILS_MAPPINGS_PATH = 'config/initializers/ofx_mappings.yml'
 
+    ##
+    # Controls whether a warning is emitted when OFX::Parser#transactions or
+    # OFX::Parser#balances aggregate across multiple statements.
+    # Defaults to +true+.
     attr_writer :multi_statement_warnings
-    attr_accessor :default_currency
 
+    ##
+    # Returns +true+ if multi-statement aggregation warnings are enabled.
     def multi_statement_warnings?
       @multi_statement_warnings
     end
 
+    ##
+    # Creates a new Configuration instance.
+    # +auto_load_path+ is the path to a YAML mappings file loaded automatically on
+    # initialization. Defaults to RAILS_MAPPINGS_PATH expanded from the working directory.
     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', {})
@@ -40,23 +54,41 @@ module OFX
       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 a SectionProxy for bank statement field mappings.
+    def bank_statement        = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:bank_statement))
+
+    ##
+    # Returns a SectionProxy for credit card statement field mappings.
+    def credit_card_statement = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:credit_card_statement))
+
+    ##
+    # Returns a SectionProxy for transaction field mappings.
+    def transaction           = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:transaction))
+
+    ##
+    # Returns a SectionProxy for bank account field mappings.
+    def bank_account          = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:bank_account))
+
+    ##
+    # Returns a SectionProxy for credit card account field mappings.
+    def credit_card_account   = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:credit_card_account))
+
+    ##
+    # Returns a SectionProxy for balance field mappings.
+    def balance               = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:balance))
 
-    # 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
+    ##
+    # Returns the OFX XML tag name corresponding to the given +section_name+
+    # (String or Symbol), e.g. +:transaction+. Returns +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.
+    ##
+    # Returns the merged Hash of XML tag to Ruby attribute mappings for the given
+    # +section_name+ (String or Symbol).
     # 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
@@ -64,19 +96,34 @@ module OFX
       (@core_fields[tag] || {}).merge(@user_fields[tag] || {})
     end
 
-    # Merges additional field mappings from a YAML file into the user-layer configuration.
+    ##
+    # Merges additional field mappings from a YAML file at +path+ (String)
+    # 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
+    #
+    # Raises Errors::ConfigurationError if the file is missing, malformed, references
+    # unknown sections, or attempts to override a core field mapping.
+    #
+    # === Example: Load a custom mappings file
+    #
+    #   OFX.configure do |config|
+    #     config.load_mappings 'config/my_ofx_mappings.yml'
+    #   end
+    #
+    # === Example: Expected YAML format
+    #
+    #   # config/my_ofx_mappings.yml
+    #   FIELDS:
+    #     STMTTRN:
+    #       MYFIELD: my_attribute
     def load_mappings(path)
-      raise ConfigurationError, "Mappings file not found: #{path}" unless File.exist?(path)
+      raise Errors::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)
+      raise Errors::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"
+        raise Errors::ConfigurationError, "Invalid mappings file: missing top-level 'FIELDS' key"
       end
 
       fields.each { |tag, mappings| merge_user_section(tag, mappings) }
@@ -86,11 +133,11 @@ module OFX
 
     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(', ')}"
+        raise Errors::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}"
+        raise Errors::ConfigurationError, "Mapping value for '#{xml_tag}' must be a Hash, got #{mappings.class}"
       end
 
       mappings.each_key { |k| assert_not_core!(xml_tag, k) }
@@ -103,7 +150,7 @@ module OFX
       core_attr = @core_fields.dig(xml_tag.to_s, xml_key.to_s)
       return unless core_attr
 
-      raise ConfigurationError,
+      raise Errors::ConfigurationError,
             "Cannot override core mapping '#{xml_tag}.#{xml_key}' (reserved as '#{core_attr}')"
     end
   end

data/lib/ofx_kit/configuration/date_parser.rb

@@ -4,7 +4,7 @@ require 'time'
 
 module OFX
   class Configuration
-    # Mixin included by {Base::Builder} to parse OFX date strings into +Time+ objects.
+    # 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

data/lib/ofx_kit/configuration/mapping_applicator.rb

@@ -2,9 +2,9 @@
 
 module OFX
   class Configuration
-    # Mixin included by {Base::Builder} to apply {Configuration} field mappings
+    # 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.
+    # custom attributes exist via Base::Entity.ensure_attribute, and assigns them.
     module MappingApplicator
       private
 
@@ -23,7 +23,9 @@ module OFX
       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
+        raise Errors::InvalidBodyError, 'Missing required CURDEF tag' if value.nil? || value.empty?
+
+        value
       end
 
       def text_at(node, css_tag)

data/lib/ofx_kit/configuration/section_proxy.rb

@@ -2,6 +2,7 @@
 
 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
@@ -11,14 +12,22 @@ module OFX
         @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
+      ##
+      # Maps +xml_key+ (the OFX XML element name, String) to a Ruby attribute name
+      # via the +to+ keyword (String or Symbol) for this section.
+      #
+      # Raises Errors::ConfigurationError if +xml_key+ is a core-protected field.
+      #
+      # === Example: Map a custom bank-specific field
+      #
+      #   OFX.configure do |config|
+      #     config.transaction.map 'MYFIELD', to: :my_attribute
+      #   end
+      #   OFX.new("statement.ofx").transactions.first.my_attribute  #=> "custom value"
       def map(xml_key, to:)
         core_attr = @core_fields.dig(@xml_tag.to_s, xml_key.to_s)
         if core_attr
-          raise OFX::ConfigurationError,
+          raise OFX::Errors::ConfigurationError,
                 "Cannot override core mapping '#{@xml_tag}.#{xml_key}' (reserved as '#{core_attr}')"
         end