ofx_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f82d22f9c1dce1691202e851448967eccd5ee7438871b10b5392038c128f084
+  data.tar.gz: 1bb156f591d24d2297457e7e0a27a7bcf13bb003fc69670c349285af757610de
+SHA512:
+  metadata.gz: 8586682ea5992fb07a2fa516bc02f113cad703034d97fa088590fd55c913e9996a850e43d5442898af6642b37d3af9563584038912454db5e96a9371089e6b8e
+  data.tar.gz: 7e8ab351c06a24a55d13299563bce802e32247c22d6046d36aef40f43c010dfa9597a1b7481108fca7f635886638a0a340c3ff6d8c658b37ec990bad6790811e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Geron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,315 @@
+# OFX
+
+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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ofx_kit"
+```
+
+## Usage
+
+### Basic parsing
+
+```ruby
+# Parse from a file path
+ofx = OFX.new("statement.ofx")
+
+# Parse from an IO object
+ofx = OFX.new(File.open("statement.ofx"))
+ofx = OFX.new(StringIO.new(raw_content))
+
+# Block form — yields the parser
+OFX.new("statement.ofx") do |p|
+  puts p.account.account_id
+end
+```
+
+### Accessing data
+
+```ruby
+ofx.filename      # => "statement.ofx" (nil for IO inputs without a path)
+ofx.headers       # => { "VERSION" => "102", "ENCODING" => "USASCII", ... }
+
+# Single-statement files
+ofx.account       # => OFX::BankAccount or OFX::CreditCardAccount
+ofx.transactions  # => Array of OFX::Transaction
+ofx.balance       # => OFX::Balance
+
+# Multiple-statement files — use the plural forms
+ofx.accounts      # => [OFX::BankAccount, ...]
+ofx.statements    # => [OFX::BankStatement, ...]
+ofx.balances      # => [OFX::Balance, ...]
+```
+
+### Transactions
+
+```ruby
+t = ofx.transactions.first
+
+t.fit_id        # => "20240115001"       String
+t.type          # => "DEBIT"             String
+t.memo          # => "Pagamento boleto"  String
+t.posted_at     # => Time object
+t.amount        # => Money object (positive = credit, negative = debit)
+t.amount_cents  # => Integer (same as t.amount.fractional)
+
+t.amount.currency.iso_code  # => "BRL"
+t.amount.to_d               # => BigDecimal("-150.50")
+```
+
+### Credits, debits, and scopes
+
+`stmt.transactions` and `account.transactions` both return an `OFX::TransactionCollection`
+with `.credits`, `.debits`, `length`, and the full `Enumerable` API:
+
+```ruby
+stmt = ofx.statements.first
+txns = stmt.transactions           # => OFX::TransactionCollection
+
+txns.length                        # => 2
+txns.credits                       # => TransactionCollection of positive amounts
+txns.debits                        # => TransactionCollection of negative amounts
+txns.total_credits                 # => Money (sum of positive transactions)
+txns.total_debits                  # => Money (sum of negative transactions)
+txns.net                           # => Money (total_credits + total_debits)
+txns.map(&:memo)                   # => ["Pagamento boleto", "Deposito salario"]
+txns.sort_by(&:posted_at)          # => Array, sorted by date
+```
+
+### Balance
+
+```ruby
+bal = ofx.balance
+bal.amount        # => Money object
+bal.amount_cents  # => Integer
+bal.posted_at     # => Time object
+```
+
+### Summary
+
+```ruby
+ofx.summary
+# => {
+#   headers: { "VERSION" => "102", ... },
+#   statements: {
+#     "12345-6" => {
+#       currency:      "BRL",
+#       transactions:  { count: 2, net_cents: 284_950 },
+#       credits:       { count: 1, total_cents: 300_000 },
+#       debits:        { count: 1, total_cents: -15_050 },
+#       balance_cents: 500_000
+#     }
+#   }
+# }
+```
+
+### Error handling
+
+```ruby
+OFX.new("missing.ofx")      # => Errno::ENOENT
+OFX.new("bad_header.ofx")   # => OFX::InvalidHeaderError
+OFX.new("bad_xml.ofx")      # => OFX::InvalidBodyError
+OFX.new(42)                 # => ArgumentError
+
+# Calling #account or #balance on a multi-statement file:
+ofx.account   # => OFX::MultipleStatementsError (use `accounts`)
+ofx.balance   # => OFX::MultipleStatementsError (use `balances`)
+
+```
+
+## Configuration
+
+Use `map` to bind OFX XML tags to Ruby attribute names of your choice.
+
+### Adding new fields
+
+Map proprietary XML tags that your bank emits but the gem doesn't know about by default:
+
+```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
+
+`map` renames the default attribute for any non-protected OFX tag:
+
+```ruby
+OFX.configure do |config|
+  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)
+```
+
+> **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`.
+
+### Loading mappings from a YAML file
+
+For larger configurations, use a YAML file instead of inline `map` calls:
+
+```ruby
+OFX.configure do |config|
+  config.load_mappings("config/ofx_mappings.yml")
+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:
+
+```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)
+
+  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)
+```
+
+### Silencing warnings
+
+`transactions` and `balances` aggregate across all statements in a multi-statement file and emit a warning. To silence them:
+
+```ruby
+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'
+```
+
+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`.
+
+### 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
+# config/initializers/ofx.rb
+OFX.configure do |config|
+  config.multi_statement_warnings = false  # silence aggregation warnings
+end
+```
+
+## Contributing
+
+1. Fork the repository and create a feature branch.
+2. Install dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+3. Make your changes. Add or update specs to cover them.
+4. Run the test suite and linter before opening a pull request:
+
+   ```bash
+   bundle exec rspec
+   bundle exec rubocop
+   ```
+
+All tests must pass and RuboCop must report no offenses.
+
+## Testing locally via console
+
+You can exercise the gem interactively using `irb` from the project root. The `spec/fixtures/` directory contains sample OFX files ready to use.
+
+```bash
+bundle exec irb -r ./lib/ofx_kit
+```
+
+```ruby
+# Parse a bank statement (OFX 1.x)
+ofx = OFX.new("spec/fixtures/bank_simple.ofx")
+ofx.account.account_id   # => "12345-6"
+ofx.transactions.length  # => 2
+ofx.balance.amount       # => Money object
+
+# Parse an OFX 2.x file
+ofx = OFX.new("spec/fixtures/bank_ofx2.ofx")
+ofx.headers              # => { "VERSION" => "220", ... }
+
+# Parse a credit card statement
+ofx = OFX.new("spec/fixtures/credit_card.ofx")
+ofx.account              # => OFX::CreditCardAccount
+ofx.transactions.first.amount.to_d  # => BigDecimal
+
+# Multiple statements
+ofx = OFX.new("spec/fixtures/bank_multiple.ofx")
+ofx.accounts.length      # => 2
+ofx.statements.map { |s| s.account.account_id }
+
+# Try custom field mappings
+OFX.configure do |config|
+  config.transaction.map "HISPAYEEMEMO", to: "extended_memo"
+end
+ofx = OFX.new("spec/fixtures/bank_simple.ofx")
+ofx.transactions.first.extended_memo
+OFX.reset_config!  # restore defaults between tests
+```
+
+## License
+
+MIT

data/lib/generators/ofx/eject_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Ofx
+  module Generators
+    # Ejects OFX field mappings into the Rails application so they can be customized.
+    #
+    # Creates +config/initializers/ofx_mappings.yml+ with the gem's default field
+    # 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
+    class EjectGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Ejects OFX field mappings into config/initializers/ofx_mappings.yml'
+
+      def eject_mappings
+        copy_file 'ofx_mappings.yml', 'config/initializers/ofx_mappings.yml'
+      end
+    end
+  end
+end

data/lib/generators/ofx/templates/ofx_mappings.yml

@@ -0,0 +1,33 @@
+# config/initializers/ofx_mappings.yml
+#
+# Each value is the Ruby attribute name exposed on the domain object.
+# Example: changing FITID from "fit_id" to "uid" means
+#   transaction.fit_id  →  transaction.uid
+#
+# Bank-specific XML tags not listed below can also be captured.
+# Simply add them to the relevant section:
+#
+#   STMTTRN:
+#     HISPAYEEMEMO: "extended_memo"    # → transaction.extended_memo
+#   BANKACCTFROM:
+#     AGENCIA: "branch_code"           # → account.branch_code
+#
+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/base/account.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module OFX
+  module Base
+    # Abstract base class for financial accounts.
+    class Account < Entity
+      attr_accessor :currency
+
+      wired_by_builder :statement, :balance, :transactions
+    end
+  end
+end

data/lib/ofx_kit/base/builder.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module OFX
+  module Base
+    # 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
+      include Configuration::DateParser
+      include Configuration::MappingApplicator
+
+      def initialize(document)
+        @document = document
+      end
+
+      # @return [Array<BankStatement, 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) }
+      end
+
+      private
+
+      def build_bank_statement(node)
+        currency = currency_for(node, :bank_statement)
+        account  = build_bank_account(node.at_css(OFX.config.xml_tag_for(:bank_account)), currency)
+        txns     = TransactionCollection.new(
+          node.css(OFX.config.xml_tag_for(:transaction)).map { |t| build_transaction(t, currency) }
+        )
+        bal  = build_balance(node.at_css(OFX.config.xml_tag_for(:balance)), currency)
+        stmt = BankStatement.new(account: account, transactions: txns, balance: bal)
+        wire(stmt)
+        stmt
+      end
+
+      def build_credit_card_statement(node)
+        currency = currency_for(node, :credit_card_statement)
+        account  = build_credit_card_account(node.at_css(OFX.config.xml_tag_for(:credit_card_account)), currency)
+        txns     = TransactionCollection.new(
+          node.css(OFX.config.xml_tag_for(:transaction)).map { |t| build_transaction(t, currency) }
+        )
+        bal  = build_balance(node.at_css(OFX.config.xml_tag_for(:balance)), currency)
+        stmt = CreditCardStatement.new(account: account, transactions: txns, balance: bal)
+        wire(stmt)
+        stmt
+      end
+
+      def build_bank_account(node, currency)
+        account = BankAccount.new
+        apply_mappings(account, node, :bank_account)
+        account.currency ||= currency
+        account
+      end
+
+      def build_credit_card_account(node, currency)
+        account = CreditCardAccount.new
+        apply_mappings(account, node, :credit_card_account)
+        account.currency ||= currency
+        account
+      end
+
+      def build_transaction(node, currency)
+        t = Transaction.new
+        apply_mappings(t, node, :transaction)
+
+        if t.amount
+          t.amount       = Money.from_amount(t.amount.to_d, currency)
+          t.amount_cents = t.amount.fractional
+        end
+
+        t.posted_at   = parse_date(t.posted_at)   if t.posted_at.is_a?(String)
+        t.occurred_at = parse_date(t.occurred_at) if t.occurred_at.is_a?(String)
+
+        t
+      end
+
+      def build_balance(node, currency)
+        return nil unless node
+
+        b = Balance.new
+        apply_mappings(b, node, :balance)
+
+        if b.amount
+          b.amount       = Money.from_amount(b.amount.to_d, currency)
+          b.amount_cents = b.amount.fractional
+        end
+
+        b.posted_at = parse_date(b.posted_at) if b.posted_at.is_a?(String)
+        b
+      end
+
+      def wire(stmt)
+        acct = stmt.account
+        wire_relations(acct,
+                       statement: -> { stmt }, balance: -> { stmt.balance },
+                       transactions: -> { stmt.transactions })
+        wire_relations(stmt.balance, statement: -> { stmt }, account: -> { acct }) if stmt.balance
+        wire_relations(stmt.transactions, statement: -> { stmt })
+        stmt.transactions.each { |t| wire_relations(t, statement: -> { stmt }, account: -> { acct }) }
+      end
+
+      def wire_relations(obj, **methods) = methods.each { |name, fn| obj.define_singleton_method(name, &fn) }
+    end
+  end
+end

data/lib/ofx_kit/base/document.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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}
+    # to extract statement data for domain object construction.
+    class Document
+      attr_reader :headers
+
+      def initialize(headers:, body:)
+        @headers = headers
+        @body    = body
+      end
+
+      # @return [String, nil] OFX version declared in the file header
+      def version
+        @headers['VERSION']
+      end
+
+      # @return [Nokogiri::XML::NodeSet] all STMTRS (bank statement) nodes in the document
+      def bank_statement_nodes
+        @body.css('STMTRS')
+      end
+
+      # @return [Nokogiri::XML::NodeSet] all CCSTMTRS (credit card statement) nodes in the document
+      def credit_card_statement_nodes
+        @body.css('CCSTMTRS')
+      end
+    end
+  end
+end

data/lib/ofx_kit/base/entity.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OFX
+  module Base
+    # Abstract base for domain objects that support dynamic field mappings
+    # 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
+    class Entity
+      def self.ensure_attribute(name)
+        attr_accessor name.to_sym unless method_defined?(name)
+      end
+
+      def self.wired_by_builder(*names)
+        names.each { |name| define_method(name) { nil } }
+      end
+    end
+  end
+end

data/lib/ofx_kit/base/statement.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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
+
+      def initialize(account:, transactions:, balance:)
+        @account      = account
+        @transactions = transactions
+        @balance      = balance
+      end
+
+      def bank_statement?        = false
+      def credit_card_statement? = false
+    end
+  end
+end