ing_kontoauszug_parser 0.1.0

data/lib/ing_kontoauszug_parser/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module IngKontoauszugParser
+  # The current version of the ing_kontoauszug_parser gem.
+  #
+  # Follows semantic versioning (major.minor.patch):
+  # - Major: Breaking API changes
+  # - Minor: New features, backward compatible
+  # - Patch: Bug fixes, backward compatible
+  #
+  # @return [String] the version string
+  # @api public
+  VERSION = '0.1.0'
+end

data/lib/ing_kontoauszug_parser.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'ing_kontoauszug_parser/version'
+require_relative 'ing_kontoauszug_parser/statement_parser'
+
+# A Ruby library for parsing ING Bank (Germany) account statement PDFs.
+#
+# This gem extracts structured transaction data from ING statement PDFs,
+# including IBAN validation, SEPA reference extraction, and transaction
+# categorization.
+#
+# == Quick Start
+#
+#   require 'ing_kontoauszug_parser'
+#
+#   parser = IngKontoauszugParser::StatementParser.new
+#   result = parser.parse(file_path: 'statement.pdf')
+#
+#   puts "Account: #{result[:header][:iban]}"
+#   result[:statements].each do |transaction|
+#     puts "#{transaction[:booking_date]}: #{transaction[:recipient]} #{transaction[:amount_eur]}"
+#   end
+#
+# == Key Features
+#
+# - PDF text extraction with automatic backend selection (poppler or pdf-reader)
+# - IBAN extraction and ISO 13616 checksum validation
+# - SEPA mandate and reference extraction
+# - Google Pay transaction detection
+# - Configurable language labels for international statements
+#
+# == Exception Handling
+#
+# All library exceptions inherit from {IngKontoauszugParser::Error}, allowing
+# you to rescue all parsing failures in one place:
+#
+#   begin
+#     result = parser.parse(file_path: path)
+#   rescue IngKontoauszugParser::Error => e
+#     logger.error "Failed to parse statement: #{e.message}"
+#   end
+#
+# For more specific handling, rescue individual exception classes:
+# - {HeaderNotFound} - IBAN not found in statement
+# - {InvalidIBAN} - IBAN checksum validation failed
+# - {BookingParseError} - Transaction parsing failed
+#
+# @see StatementParser The main parsing interface
+# @see https://github.com/bigcurl/ing-kontoauszug-parser GitHub repository
+module IngKontoauszugParser
+  # Base exception class for all parsing-related errors.
+  #
+  # Rescue this class to catch any error raised by the library.
+  # All specific exceptions inherit from this class.
+  #
+  # @example Catch all library errors
+  #   begin
+  #     result = parser.parse(file_path: 'statement.pdf')
+  #   rescue IngKontoauszugParser::Error => e
+  #     puts "Parsing failed: #{e.message}"
+  #   end
+  class Error < StandardError; end
+
+  # Raised when the IBAN cannot be located in the statement text.
+  #
+  # This typically indicates that the PDF is not a valid ING statement,
+  # the text extraction failed to capture the header, or the statement
+  # format has changed.
+  #
+  # @example Handle missing IBAN
+  #   begin
+  #     result = parser.parse(file_path: path)
+  #   rescue IngKontoauszugParser::HeaderNotFound
+  #     puts "Could not find account IBAN - is this an ING statement?"
+  #   end
+  class HeaderNotFound < Error; end
+
+  # Raised when the extracted IBAN fails ISO 13616 checksum validation.
+  #
+  # This may indicate a corrupted PDF, OCR errors during text extraction,
+  # or an intentionally invalid IBAN. You can disable validation by passing
+  # +validate_iban: false+ to the parser constructor.
+  #
+  # @example Handle invalid IBAN
+  #   begin
+  #     result = parser.parse(file_path: path)
+  #   rescue IngKontoauszugParser::InvalidIBAN => e
+  #     puts "IBAN validation failed: #{e.message}"
+  #   end
+  class InvalidIBAN < Error; end
+
+  # Raised when transaction parsing fails or no transactions are found.
+  #
+  # This may occur if the statement format is unexpected, the PDF contains
+  # no transactions (empty statement), or the text extraction produced
+  # malformed output.
+  #
+  # @example Handle parsing failure
+  #   begin
+  #     result = parser.parse(file_path: path)
+  #   rescue IngKontoauszugParser::BookingParseError => e
+  #     puts "Could not parse transactions: #{e.message}"
+  #   end
+  class BookingParseError < Error; end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: ing_kontoauszug_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- bigcurl
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pdf-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+description: A toolkit for ingesting and parsing statements from ING Bank.
+email:
+- bigcurl@users.noreply.github.com
+executables:
+- console
+- pdf_to_json
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/console
+- bin/pdf_to_json
+- bin/setup
+- lib/ing_kontoauszug_parser.rb
+- lib/ing_kontoauszug_parser/header.rb
+- lib/ing_kontoauszug_parser/pdf_extractor.rb
+- lib/ing_kontoauszug_parser/statement_parser.rb
+- lib/ing_kontoauszug_parser/text_parser.rb
+- lib/ing_kontoauszug_parser/version.rb
+homepage: https://github.com/bigcurl/ing-kontoauszug-parser
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/bigcurl/ing-kontoauszug-parser
+  source_code_uri: https://github.com/bigcurl/ing-kontoauszug-parser
+  changelog_uri: https://github.com/bigcurl/ing-kontoauszug-parser/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Parse statements from ING Bank
+test_files: []