extras_de_cont 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3adf9f273d4799d379dd3b863486098e0f74713c679abeea1c4d3bc9c19c84f3
-  data.tar.gz: a4f71318dfc8c9ee3a604b776bc0975b3af69d8487cdddef78c25a754193fcda
+  metadata.gz: 6dde609d769123f6ba26d34fc0efa79b82ad91b18f6f84d725362480f6c9ef3a
+  data.tar.gz: 236b56eb1c323f3dafc2278135424f5cd51edb336fdd45462c0c73a1e1db83af
 SHA512:
-  metadata.gz: e6b6afc9476cdf5dfb67f1dbb6e7cf8404da6757329cc3435a9bb42d0f064a4fa0a7df98a30003ed4fd821724551933076a88a75dd156e4c2818989a73aa0487
-  data.tar.gz: adb65db1676e5181ae680a45ab1c0c0b56ed6a3d8622b591fe5fa5cba4d670ed00e990318d72919664194e6c5d83630882561294cf1bfa65b42b2c77a92875a7
+  metadata.gz: 48a679a6514c868d895d68ba56ed821e4528b7b48d9acb90638f16a5d723b2736e7e67afd6fdd85481ec1c9980318e16bc823091f564e6bc1963c554bc505e6c
+  data.tar.gz: a31df94d256b541092714e9d54351cd785e46dd0e58120c593699733cb9f90530548bcce9040d5cdfa36c421d775c80335f95a19f24711918549e454c1fee147

data/README.md

@@ -35,3 +35,78 @@ Run the Revolut parser test with:
 ```bash
 ruby -Ilib:test test/revolut_rule_test.rb
 ```
+
+## Supported Banks
+
+| Bank | Symbol | Currencies | Features |
+|---|---|---|---|
+| Revolut | `:revolut` | RON, EUR, USD, GBP, PLN, CZK, HUF, BGN, TRY, UAH | Personal & Business, multi-section, symbol currencies |
+| UniCredit | `:unicredit` | RON, EUR | Romanian month names, page breaks, transaction markers |
+| BRD | `:brd` | RON, EUR | Below-line amounts, Romanian number format |
+
+## Development
+
+```bash
+bundle install          # Install dependencies
+bundle exec rake test   # Run all tests
+bundle exec rake standard  # Run linter
+bundle exec rake build  # Build gem
+```
+
+## Contributing
+
+Contributions are welcome. Here is how to add a new bank:
+
+### 1. Gather information
+
+Obtain a sample PDF statement from the bank and extract its text:
+
+```bash
+ruby -Ilib -e 'require "extras_de_cont"; puts ExtrasDeCont::Parser.new(ARGV[0]).text' /path/to/statement.pdf
+```
+
+### 2. Create a rule class
+
+Add `lib/extras_de_cont/rules/<bank>.rb` inheriting from `Rules::Base`. See existing rules in `lib/extras_de_cont/rules/` for patterns.
+
+### 3. Register the bank
+
+Add the require and `BANK_RULES` entry in `lib/extras_de_cont.rb`:
+
+```ruby
+require "extras_de_cont/rules/<bank>"
+# ...
+BANK_RULES = {
+  brd: Rules::Brd,
+  <bank>: Rules::<BankName>,
+  revolut: Rules::Revolut,
+  unicredit: Rules::UniCredit
+}.freeze
+```
+
+### 4. Write tests
+
+Add `test/extras_de_cont/rules/<bank>_rule_test.rb`. Use sanitized fixtures — never commit real financial data. Run with:
+
+```bash
+bundle exec ruby -Ilib:test test/extras_de_cont/rules/<bank>_rule_test.rb
+bundle exec rake standard
+```
+
+### Code style
+
+This project uses [Standard Ruby](https://github.com/standardrb/standard). Run `bundle exec rake standard` before submitting changes.
+
+## AI-Assisted Development
+
+This project supports AI-assisted development via [OpenCode](https://github.com/anomalyco/opencode).
+
+A skill is provided for adding new bank statement parsers. When using an AI coding assistant, it can load the skill 
+at `.agents/skills/add-bank-statement/SKILL.md` to guide the process. 
+The skill covers rule class creation, registration, RBS signatures, test patterns, and fixture anonymization.
+
+The project maintains a [MemPalace](https://github.com/anomalyco/mempalace) knowledge graph (`mempalace.yaml`) 
+that organizes the codebase into wings and rooms. AI agents can query this to learn about the project structure, 
+existing parsers, test patterns, and conventions without reading every file.
+
+For more context, see `AGENTS.md`.

data/extras_de_cont.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = "extras_de_cont"
-  s.version = "1.0.2"
+  s.version = "1.2.0"
   s.licenses = ["GPLv3"]
   s.summary = "A simple library which helps you extract transactions from a PDF bank statement."
   s.description = <<~TEXT
@@ -14,8 +14,8 @@ Gem::Specification.new do |s|
   s.authors = ["Denis Nutiu"]
   s.email = "dnutiu@nuculabs.dev"
   s.homepage = "https://nuculabs.dev"
-  s.metadata = { "source_code_uri" => "https://gitlab.nuculabs.dev/dnutiu/extras-de-cont",
-                 "rubygems_mfa_required" => "true" }
+  s.metadata = {"source_code_uri" => "https://gitlab.nuculabs.dev/dnutiu/extras-de-cont",
+                 "rubygems_mfa_required" => "true"}
   s.required_ruby_version = ">= 3.0.0"
 
   # Files to include in the gem

data/lib/extras_de_cont/rules/brd.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "date"
+require "extras_de_cont/transaction"
+
+module ExtrasDeCont
+  module Rules
+    class Brd < Rules::Base
+      DATE_PREFIX = /\A(?<date>\d{2}\/\d{2}\/\d{4})\b/
+      AMOUNT_PATTERN = /\d{1,3}(?:\.\d{3})*,\d{2}/
+      TABLE_HEADER_PATTERN = /Data oper\.\s+Descriere operatiune\s+Debit\s+Credit\s+Data val\./
+
+      NOISE_PATTERNS = [
+        /\APag\./,
+        /\ABRD-Groupe/,
+        /\ACAPITAL SOCIAL/,
+        /\AMihalache/,
+        /\ATel:/,
+        /\ARO361579/,
+        /\A255\/06/,
+        /\APJR01INCR/,
+        /\ACIFRE CHEIE/,
+        /\ACONTURI DETINUTE/,
+        /\AFonduri proprii/,
+        /\ALimita de credit/,
+        /\ACredit neutilizat/,
+        /\ADescoperit/,
+        /\ANr\. Zile/,
+        /\ATotal disponibil/,
+        /\ATotal sume/,
+        /\ADomicilierea contului/,
+        /\AReferinte bancare/,
+        /\ATitular \/ Account/,
+        /\AIBAN /,
+        /\ANumar cont/,
+        /\AExtras de cont/,
+        /\ADe la \/ From/,
+        /\ADocumentul este/,
+        /\ACNP\/CUI:/,
+        /\ASWIFT/,
+        /\AAg\. /,
+        /\AStr\. /,
+        /\A•/,
+        /\Ahttp/,
+        /\ASold/,
+        /\ATotal debit/,
+        /\ACard:MBS/,
+        /\ATrans\.Date/
+      ].freeze
+
+      def parse(text)
+        transactions = []
+        current_table = nil
+        current_currency = nil
+        above_lines = []
+        below_lines = []
+        date_line = nil
+
+        each_normalized_line(text) do |line|
+          if line.start_with?("Valuta / Currency")
+            current_currency = line.split.last
+            next
+          end
+
+          if table_header?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            current_table = extract_columns(line)
+            above_lines = []
+            below_lines = []
+            date_line = nil
+            next
+          end
+
+          if noise?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            above_lines = []
+            below_lines = []
+            date_line = nil
+            next
+          end
+
+          next if current_table.nil?
+
+          if date_line?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            date_line = line
+            below_lines = []
+            next
+          end
+
+          if date_line
+            below_lines << line
+          else
+            above_lines << line
+          end
+        end
+
+        try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+        transactions
+      end
+
+      private
+
+      def each_normalized_line(text)
+        text.each_line do |line|
+          normalized = line.tr("\u00A0", " ").strip
+          next if normalized.empty?
+          yield normalized
+        end
+      end
+
+      def table_header?(line)
+        line.match?(TABLE_HEADER_PATTERN)
+      end
+
+      def date_line?(line)
+        line.match?(DATE_PREFIX)
+      end
+
+      def noise?(line)
+        NOISE_PATTERNS.any? { |pattern| line.match?(pattern) }
+      end
+
+      def extract_columns(line)
+        {
+          debit: line.index("Debit"),
+          credit: line.index("Credit")
+        }
+      end
+
+      def try_flush(date_line, above_lines, below_lines, table, currency, transactions)
+        return if date_line.nil? || table.nil?
+
+        transaction = build_transaction(date_line, above_lines, below_lines, table, currency)
+        transactions << transaction if transaction
+      end
+
+      def build_transaction(date_line, above_lines, below_lines, table, currency)
+        date_match = date_line.match(DATE_PREFIX)
+        return if date_match.nil?
+
+        date = parse_date(date_match[:date])
+
+        amounts_on_date = date_line.to_enum(:scan, AMOUNT_PATTERN).map { Regexp.last_match }
+
+        if amounts_on_date.any?
+          transaction_amount_match = amounts_on_date.first
+          main_description = date_line[date_match.end(0)...transaction_amount_match.begin(0)].to_s.strip
+        else
+          amount_line = below_lines.find { |l| l.match?(AMOUNT_PATTERN) }
+          return unless amount_line
+
+          amount_match = amount_line.match(AMOUNT_PATTERN)
+          transaction_amount_match = amount_match
+          main_description = date_line[date_match.end(0)..].to_s.strip
+          main_description = main_description.sub(/\s*\d{2}\/\d{2}\/\d{4}\s*\z/, "")
+        end
+
+        midpoint = (table[:debit] + 2 * table[:credit]) / 3
+        debit = transaction_amount_match.begin(0) < midpoint
+        amount = parse_amount(transaction_amount_match[0])
+        amount = -amount if debit
+
+        description_lines = below_lines.map(&:strip).reject(&:empty?)
+        if !amounts_on_date.any? && description_lines.first
+          stripped = description_lines.first.sub(AMOUNT_PATTERN, "").strip
+          description_lines[0] = stripped unless stripped.empty?
+        end
+        description_parts = [*above_lines.map(&:strip), main_description, *description_lines]
+        description = description_parts.reject(&:empty?).join(" | ")
+
+        Transaction.new(date, description, amount, currency)
+      end
+
+      def parse_date(value)
+        day, month, year = value.split("/").map(&:to_i)
+        Date.new(year, month, day)
+      end
+
+      def parse_amount(value)
+        value.delete(".").sub(",", ".").to_f
+      end
+    end
+  end
+end

data/lib/extras_de_cont/rules/revolut.rb

@@ -11,24 +11,45 @@ module ExtrasDeCont
         "Pending from ",
         "Account transactions from ",
         "Reverted from ",
-        "Deposit transactions from "
+        "Deposit transactions from ",
+        "Transactions from "
       ].freeze
 
       DOCUMENT_NOISE_HEADERS = [
+        "Account statement",
         "Balance summary",
         "The balance on your statement might differ",
+        "There were no transactions during this period",
+        "Transaction types",
+        "Your funds are held and protected by a licensed bank",
         "Report lost or stolen card",
         "+",
         "Get help directly in app",
+        "Get help directly In app",
         "Scan the QR code",
         "RON Statement",
+        " Statement",
         "Generated on the ",
         "Revolut Bank UAB",
         "© "
       ].freeze
 
-      DATE_PREFIX = /\A(?<date>[A-Z][a-z]{2} \d{1,2}, \d{4})\b/
-      AMOUNT = /-?\d[\d,]*\.\d{2} [A-Z]{3}/
+      CURRENCY_SYMBOLS = {
+        "$" => "USD",
+        "€" => "EUR",
+        "£" => "GBP",
+        "zł" => "PLN",
+        "Kč" => "CZK",
+        "Ft" => "HUF",
+        "лв" => "BGN",
+        "₺" => "TRY",
+        "₴" => "UAH"
+      }.freeze
+      DATE_FORMATS = ["%b %e, %Y", "%e %b %Y"].freeze
+      DATE_PREFIX = /\A(?<date>(?:[A-Z][a-z]{2} \d{1,2}, \d{4}|\d{1,2} [A-Z][a-z]{2} \d{4}))\b/
+      NUMBER = /-?(?:\d{1,3}(?:[ ,]\d{3})+|\d+)\.\d{2}/
+      CURRENCY_SYMBOL = Regexp.union(CURRENCY_SYMBOLS.keys.sort_by { |symbol| -symbol.length })
+      AMOUNT = /(?:#{NUMBER} [A-Z]{3}|#{CURRENCY_SYMBOL}#{NUMBER}|#{NUMBER} ?#{CURRENCY_SYMBOL})/
 
       def parse(text)
         transactions = []
@@ -105,16 +126,41 @@ module ExtrasDeCont
           parse_date(match[:date]),
           description,
           amount,
-          amount_string.split.last
+          parse_currency(amount_string)
         )
       end
 
       def parse_date(value)
-        Date.strptime(value, "%b %e, %Y")
+        DATE_FORMATS.each do |format|
+          return Date.strptime(value, format)
+        rescue Date::Error
+          next
+        end
       end
 
       def parse_amount(value)
-        value.split.first.delete(",").to_f
+        numeric_value(value).delete(", ").to_f
+      end
+
+      def parse_currency(value)
+        symbol = currency_symbol(value)
+        return CURRENCY_SYMBOLS.fetch(symbol) if symbol
+
+        value.split.last
+      end
+
+      def numeric_value(value)
+        symbol = currency_symbol(value)
+        return value.delete_prefix(symbol) if symbol && value.start_with?(symbol)
+        return value.delete_suffix(symbol).strip if symbol
+
+        value.sub(/\s+[A-Z]{3}\z/, "")
+      end
+
+      def currency_symbol(value)
+        CURRENCY_SYMBOLS.keys.find do |symbol|
+          value.start_with?(symbol) || value.end_with?(symbol)
+        end
       end
 
       def section_header?(line)
@@ -147,11 +193,12 @@ module ExtrasDeCont
         amount_matches = row.to_enum(:scan, AMOUNT).map { Regexp.last_match }
         return if amount_matches.empty?
 
-        transaction_match = if table.fetch(:has_balance)
-                              amount_matches[-2] if amount_matches.length > 1
-                            else
-                              amount_matches[-1]
-                            end
+        transaction_match =
+          if table.fetch(:has_balance)
+            amount_matches[-2] if amount_matches.length > 1
+          else
+            amount_matches[-1]
+          end
         return if transaction_match.nil?
 
         description = row[date_match.end(0)...transaction_match.begin(0)].to_s.strip

data/lib/extras_de_cont/rules/unicredit.rb

@@ -1,8 +1,205 @@
 # frozen_string_literal: true
 
+require "date"
+require "extras_de_cont/transaction"
+
 module ExtrasDeCont
   module Rules
     class UniCredit < Rules::Base
+      ROMANIAN_MONTHS = {
+        "ianuarie" => 1, "februarie" => 2, "martie" => 3, "aprilie" => 4,
+        "mai" => 5, "iunie" => 6, "iulie" => 7, "august" => 8,
+        "septembrie" => 9, "octombrie" => 10, "noiembrie" => 11, "decembrie" => 12
+      }.freeze
+
+      RO_MONTH_NAMES = ROMANIAN_MONTHS.keys.freeze
+      DATE_PATTERN = /\b(\d{1,2})\s+(#{RO_MONTH_NAMES.join("|")})\s+(\d{4})\b/i
+      DATE_PREFIX = /\A\s*#{DATE_PATTERN}/
+
+      TABLE_HEADER_PATTERN = /Data\s+Descriere\s+Debit\s+Credit\s+Sold/
+
+      SECTION_HEADERS = [
+        "TRANZACȚII",
+        "SUMAR CONT",
+        "EXTRAS DE CONT"
+      ].freeze
+
+      NOISE_PATTERNS = [
+        /\AUniCredit Bank S\.A\./,
+        /\ABulevardul/,
+        /\ASector \d/,
+        /\ATel:/,
+        /\AEmail:/,
+        /\Aunicredit\.ro/,
+        /\ACapital social:/,
+        /\APrezentul extras/,
+        /\AFondurile disponibile/,
+        /\APentru mai multe/,
+        /\ANUME CLIENT:/,
+        /\AADRESA:/,
+        /\ASUCURSALA:/,
+        /\ADATA EXTRAS CONT/,
+        /\APERIOADA/,
+        /\ATIP CONT:/,
+        /\AIBAN:/,
+        /\AMONEDA:/,
+        /\AOperator de date/,
+        /\ASold inițial/,
+        /\ASold final/,
+        /\AOperator de date cu/
+      ].freeze
+
+      NEW_TRANSACTION_MARKERS = [
+        /\A\+CMS CLT-/,
+        /\A\+GPP/,
+        /\APlata electronica/,
+        /\APlata Instant/,
+        /\AIncasare Instant/,
+        /\ATransfer electronic/
+      ].freeze
+
+      AMOUNT_PATTERN = /\d{1,3}(?:[.,]\d{3})*\.\d{2}/
+      CURRENCY_FROM_HEADER = /Sold\(([A-Z]{3})\)/
+
+      def parse(text)
+        transactions = []
+        current_currency = nil
+        current_table = nil
+        above_lines = []
+        below_lines = []
+        date_line = nil
+
+        each_normalized_line(text) do |line|
+          if (m = line.match(CURRENCY_FROM_HEADER))
+            current_currency = m[1]
+          end
+
+          if table_header?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            current_table = extract_column_positions(line)
+            above_lines, below_lines, date_line = [], [], nil
+            next
+          end
+
+          if noise?(line) || section_header?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            above_lines, below_lines, date_line = [], [], nil
+            next
+          end
+
+          next if current_table.nil?
+
+          if date_line?(line)
+            try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+            date_line = line
+            below_lines = []
+            next
+          end
+
+          if date_line
+            if new_transaction_marker?(line)
+              try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+              date_line, below_lines = nil, []
+              above_lines = [line]
+            else
+              below_lines << line
+            end
+          else
+            above_lines << line
+          end
+        end
+
+        try_flush(date_line, above_lines, below_lines, current_table, current_currency, transactions)
+        transactions
+      end
+
+      private
+
+      def each_normalized_line(text)
+        text.each_line do |line|
+          normalized = line.tr("\u00A0", " ").strip
+          next if normalized.empty?
+
+          yield normalized
+        end
+      end
+
+      def table_header?(line)
+        line.match?(TABLE_HEADER_PATTERN)
+      end
+
+      def date_line?(line)
+        line.match?(DATE_PREFIX)
+      end
+
+      def noise?(line)
+        NOISE_PATTERNS.any? { |pattern| line.match?(pattern) }
+      end
+
+      def section_header?(line)
+        SECTION_HEADERS.any? { |header| line == header }
+      end
+
+      def new_transaction_marker?(line)
+        NEW_TRANSACTION_MARKERS.any? { |pattern| line.match?(pattern) }
+      end
+
+      def extract_column_positions(line)
+        {
+          debit: line.index("Debit"),
+          credit: line.index("Credit"),
+          sold: line.index("Sold")
+        }
+      end
+
+      def try_flush(date_line, above_lines, below_lines, table, currency, transactions)
+        return if date_line.nil? || table.nil?
+
+        transaction = build_transaction(date_line, above_lines, below_lines, table, currency)
+        transactions << transaction if transaction
+      end
+
+      def build_transaction(date_line, above_lines, below_lines, table, currency)
+        date_match = date_line.match(DATE_PREFIX)
+        return if date_match.nil?
+
+        amounts = date_line.to_enum(:scan, AMOUNT_PATTERN).map { Regexp.last_match }
+        return if amounts.size < 2
+
+        transaction_amount_match = amounts[-2]
+        description_start = date_match.end(0)
+        description_end = transaction_amount_match.begin(0)
+        main_description = date_line[description_start...description_end].to_s.strip
+
+        amount_string = transaction_amount_match[0]
+        amount = amount_string.delete(", ").to_f
+        midpoint = (table[:debit] + table[:credit]) / 2
+        amount = -amount if transaction_amount_match.begin(0) < midpoint
+
+        description = build_description(main_description, above_lines, below_lines)
+
+        Transaction.new(
+          parse_date(date_match[1].to_i, date_match[2], date_match[3].to_i),
+          description,
+          amount,
+          currency || extract_currency_from_header(date_line)
+        )
+      end
+
+      def parse_date(day, month_name, year)
+        month = ROMANIAN_MONTHS[month_name.downcase]
+        Date.new(year, month, day)
+      end
+
+      def build_description(main_desc, above_lines, below_lines)
+        parts = [*above_lines.map(&:strip), main_desc, *below_lines.map(&:strip)]
+        parts.reject(&:empty?).join(" | ")
+      end
+
+      def extract_currency_from_header(date_line)
+        m = date_line.match(CURRENCY_FROM_HEADER)
+        m ? m[1] : nil
+      end
     end
   end
 end

data/lib/extras_de_cont.rb

@@ -2,6 +2,7 @@
 
 require "extras_de_cont/parser"
 require "extras_de_cont/rules/base"
+require "extras_de_cont/rules/brd"
 require "extras_de_cont/rules/revolut"
 require "extras_de_cont/rules/unicredit"
 
@@ -9,8 +10,9 @@ require "extras_de_cont/rules/unicredit"
 module ExtrasDeCont
   # Map of supported banks (symbol → rule class)
   BANK_RULES = {
-    unicredit: Rules::UniCredit,
-    revolut: Rules::Revolut
+    brd: Rules::Brd,
+    revolut: Rules::Revolut,
+    unicredit: Rules::UniCredit
   }.freeze
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: extras_de_cont
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Denis Nutiu
@@ -39,6 +39,7 @@ files:
 - lib/extras_de_cont.rb
 - lib/extras_de_cont/parser.rb
 - lib/extras_de_cont/rules/base.rb
+- lib/extras_de_cont/rules/brd.rb
 - lib/extras_de_cont/rules/revolut.rb
 - lib/extras_de_cont/rules/unicredit.rb
 - lib/extras_de_cont/transaction.rb