extras_de_cont 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9393dd1d6d9cec4a77e34393af8a0ccb3459c0486835f7df0eed74410cff435
-  data.tar.gz: f5008d24c8f24b1f2b7a0d0bda8a675a2c886fba09e86b9d91bb888c7a1d7b92
+  metadata.gz: a4d3354f9da96a1d04fc3a8bd388be67338417b12dedeea21073390725606bd9
+  data.tar.gz: 26201c9fad4bbad47fa7cf241c9bc9418621e65c01ff14031fb938fb783dcf85
 SHA512:
-  metadata.gz: 07e61564409929f0c316b834ac18ad00d54a4a0a9f6b1f221c012e3064f5ad046de1324781545455f6417fb4198450b49773613e1d59b936a8410e25286238e3
-  data.tar.gz: 64cce605262cdcb5a31aa164b76e6f108f8b24149f136c92d237b888dcd894813cda0fce0bf8e801862e162ecfbd88e095cc479c61661f2bab9054bb822b08a0
+  metadata.gz: 738d0e661f0d5ad9bf74efad90e1101626602245db40790b2216c0cf6ea41bf54a0569581f723538261cbc19a084eddccd74830475770f184a884be406a4fe7c
+  data.tar.gz: 96abcb5cc28ae8ac7ca676ff95f0d9903735cb5ed04876a3d5f055c804aca435e38868f89280592976c15527d3872c8256e1513df035b3885f64d8614c4e9108

data/README.md

@@ -24,6 +24,19 @@ transactions.each do |t|
 end
 ```
 
+Revolut CSV exports are supported with `:revolut_csv`:
+
+```ruby
+transactions = ExtrasDeCont.parse(csv_file, bank: :revolut_csv)
+```
+
+Completed and reverted rows are returned; pending rows are ignored. Reverted amounts are inverted so they offset the original transaction. To parse overlapping statements safely, pass the keys of transactions already imported:
+
+```ruby
+already_imported = imported_transactions.map(&:deduplication_key)
+transactions = ExtrasDeCont.parse(csv_file, bank: :revolut_csv, exclude: already_imported)
+```
+
 Or use the included entrypoint:
 
 ```bash
@@ -41,6 +54,7 @@ ruby -Ilib:test test/revolut_rule_test.rb
 | Bank      | Symbol       | Currencies | Features                                               |
 |-----------|--------------|---|--------------------------------------------------------|
 | Revolut   | `:revolut`   | RON, EUR, USD, GBP, PLN, CZK, HUF, BGN, TRY, UAH | Personal & Business, multi-section, symbol currencies  |
+| Revolut CSV | `:revolut_csv` | RON, EUR, USD, GBP, PLN, CZK, HUF, BGN, TRY, UAH | Completed/reverted rows, fees, duplicate exclusion |
 | UniCredit | `:unicredit` | RON, EUR | Romanian month names, page breaks, transaction markers |
 | BRD       | `:brd`       | RON, EUR | Below-line amounts, Romanian number format             |
 | ING       | `:ing`       | RON | Normal bank statements in RON                          |

data/extras_de_cont.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = "extras_de_cont"
-  s.version = "1.4.0"
+  s.version = "1.5.0"
   s.licenses = ["GPLv3"]
-  s.summary = "A simple library which helps you extract transactions from a PDF bank statement."
+  s.summary = "A library for extracting transactions from bank statements."
   s.description = <<~TEXT
-    A simple library which helps you extract transactions from a PDF bank statement.
+    A library for extracting transactions from PDF bank statements and Revolut CSV exports.
     Fine tuned for Romanian bank statements.
 
     Repository: https://github.com/dnutiu/extras-de-cont
@@ -25,5 +25,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency "pdf-reader", "~> 2.15"
+  s.add_dependency "csv", "~> 3.3"
+  s.add_dependency "bigdecimal", "~> 3.1"
   s.add_dependency "zeitwerk", "~> 2.8"
 end

data/lib/extras_de_cont/rules/revolut_csv.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "csv"
+require "date"
+require "digest"
+
+module ExtrasDeCont
+  module Rules
+    # Parses Revolut's account-statement CSV export.
+    class RevolutCsv < Rules::Base
+      REQUIRED_HEADERS = ["Started Date", "Description", "Amount", "Fee", "Currency", "State"].freeze
+      INCLUDED_STATES = %w[COMPLETED REVERTED].freeze
+
+      def parse(source)
+        csv_data = source.respond_to?(:read) ? source.read : source.to_s
+        csv_data = csv_data.dup.force_encoding(Encoding::UTF_8).delete_prefix("\uFEFF")
+        rows = CSV.parse(csv_data, headers: true, skip_blanks: true)
+        validate_headers!(rows.headers)
+
+        rows.filter_map do |row|
+          state = row["State"].to_s.strip.upcase
+          next unless INCLUDED_STATES.include?(state)
+
+          parse_row(row, state)
+        end
+      end
+
+      private
+
+      def validate_headers!(headers)
+        missing_headers = REQUIRED_HEADERS - Array(headers)
+        return if missing_headers.empty?
+
+        raise ArgumentError, "Invalid Revolut CSV: missing #{missing_headers.join(", ")} column(s)"
+      end
+
+      def parse_row(row, state)
+        date = DateTime.strptime(row.fetch("Started Date").to_s.strip, "%Y-%m-%d %H:%M:%S").to_date
+        description = row.fetch("Description").to_s.strip
+        currency = row.fetch("Currency").to_s.strip.upcase
+        amount = decimal(row.fetch("Amount")) - decimal(row["Fee"], default: "0")
+        amount = -amount if state == "REVERTED"
+
+        raise ArgumentError, "Invalid Revolut CSV: included row has no description" if description.empty?
+        return if amount.zero?
+
+        Transaction.new(
+          date,
+          description,
+          amount,
+          currency,
+          state: state,
+          deduplication_key: deduplication_key(row, state)
+        )
+      rescue ArgumentError => e
+        raise e if e.message.start_with?("Invalid Revolut CSV")
+
+        raise ArgumentError, "Invalid Revolut CSV row: #{e.message}"
+      end
+
+      def decimal(value, default: nil)
+        value = default if value.to_s.strip.empty? && !default.nil?
+        BigDecimal(value.to_s.strip)
+      end
+
+      def deduplication_key(row, state)
+        Digest::SHA256.hexdigest(
+          [
+            row["Type"],
+            row["Product"],
+            row["Started Date"],
+            row["Completed Date"],
+            row["Description"],
+            row["Amount"],
+            row["Fee"],
+            row["Currency"],
+            state
+          ].map { |value| value.to_s.strip }.join("\u001f")
+        )
+      end
+    end
+  end
+end

data/lib/extras_de_cont/transaction.rb

@@ -1,20 +1,35 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module ExtrasDeCont
   # Models a simple bank transaction
   class Transaction
-    attr_reader :date, :description, :amount, :currency
+    attr_reader :date, :description, :amount, :currency, :state, :deduplication_key
 
     def initialize(
       date,
       description,
       amount,
-      currency
+      currency,
+      **options
     )
       @date = date
       @description = description
       @amount = amount
       @currency = currency
+      @state = options[:state]
+      @deduplication_key = options[:deduplication_key] || build_deduplication_key
+    end
+
+    def reverted?
+      state.to_s.casecmp?("REVERTED")
+    end
+
+    private
+
+    def build_deduplication_key
+      Digest::SHA256.hexdigest([date, description, amount, currency, state].join("\u001f"))
     end
   end
 end

data/lib/extras_de_cont.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
+require "zeitwerk"
 
-require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "unicredit" => "UniCredit"
 )
-loader.setup # ready!
-
-
+loader.setup
 
 # The ExtrasDeCont module contains utilities for parsing bank statements.
 module ExtrasDeCont
@@ -17,24 +15,64 @@ module ExtrasDeCont
     brd: ExtrasDeCont::Rules::Brd,
     ing: ExtrasDeCont::Rules::Ing,
     revolut: ExtrasDeCont::Rules::Revolut,
+    revolut_csv: ExtrasDeCont::Rules::RevolutCsv,
     unicredit: ExtrasDeCont::Rules::UniCredit
   }.freeze
 
+  RAW_TEXT_BANKS = %i[revolut_csv].freeze
+
   class << self
-    # Parses a PDF bank statement and returns structured transactions.
+    # Parses a bank statement and returns structured transactions.
     #
     # @param file [String, Pathname, IO] path to the PDF file or an IO-like object
-    # @param bank [Symbol] the bank identifier (:unicredit, :revolut, etc.)
+    # @param bank [Symbol] the bank identifier (:unicredit, :revolut, :revolut_csv, etc.)
+    # @param exclude [Array<String, Transaction>] deduplication keys or transactions already imported
     # @return [Array<ExtrasDeCont::Transaction>]
     # @raise [ArgumentError] if the bank is not supported
-    def parse(file, bank:)
+    def parse(file, bank:, exclude: [])
+      bank = bank.to_sym
       rule_class = BANK_RULES[bank]
       raise ArgumentError, "Unsupported bank: #{bank}. Supported banks: #{BANK_RULES.keys.join(", ")}" unless rule_class
 
-      p = ExtrasDeCont::Parser.new(file)
-      p.parse_with(rule_class.new)
+      transactions =
+        if RAW_TEXT_BANKS.include?(bank)
+          rule_class.new.parse(read_raw_file(file))
+        else
+          ExtrasDeCont::Parser.new(file).parse_with(rule_class.new)
+        end
+
+      deduplicate(transactions, exclude, within_file: RAW_TEXT_BANKS.include?(bank))
+    end
+
+    private
+
+    def read_raw_file(file)
+      return file.read if file.respond_to?(:read)
+      return file if file.is_a?(String) && !file_path?(file)
+
+      File.binread(file.respond_to?(:to_path) ? file.to_path : file)
+    end
+
+    def file_path?(file)
+      File.file?(file)
+    rescue Errno::ENAMETOOLONG
+      false
+    end
+
+    def deduplicate(transactions, exclude, within_file:)
+      seen = Array(exclude).to_h do |item|
+        [item.respond_to?(:deduplication_key) ? item.deduplication_key : item.to_s, true]
+      end
+
+      transactions.each_with_object([]) do |transaction, unique_transactions|
+        key = transaction.deduplication_key
+        next if seen.key?(key)
+
+        unique_transactions << transaction
+        seen[key] = true if within_file
+      end
     end
   end
 end
 
-loader.eager_load # optionally
+loader.eager_load

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: extras_de_cont
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Denis Nutiu
@@ -23,6 +23,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.15'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +66,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.8'
 description: |
-  A simple library which helps you extract transactions from a PDF bank statement.
+  A library for extracting transactions from PDF bank statements and Revolut CSV exports.
   Fine tuned for Romanian bank statements.
 
   Repository: https://github.com/dnutiu/extras-de-cont
@@ -56,6 +84,7 @@ files:
 - lib/extras_de_cont/rules/brd.rb
 - lib/extras_de_cont/rules/ing.rb
 - lib/extras_de_cont/rules/revolut.rb
+- lib/extras_de_cont/rules/revolut_csv.rb
 - lib/extras_de_cont/rules/unicredit.rb
 - lib/extras_de_cont/transaction.rb
 homepage: https://nuculabs.dev
@@ -80,5 +109,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: A simple library which helps you extract transactions from a PDF bank statement.
+summary: A library for extracting transactions from bank statements.
 test_files: []