ing_kontoauszug_parser 0.1.0

data/lib/ing_kontoauszug_parser/text_parser.rb

@@ -0,0 +1,905 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'strscan'
+require_relative 'header'
+
+module IngKontoauszugParser
+  # Parses ING bank statement text into structured transaction data.
+  #
+  # This class implements a single-pass streaming parser optimized for processing
+  # ING Germany statement exports. It handles both PDF-extracted text and direct
+  # text exports, extracting IBAN, transaction details, SEPA references, and
+  # narrative information.
+  #
+  # == Architecture
+  #
+  # The parser uses a state machine approach with lazy evaluation:
+  # - IBAN extraction happens opportunistically while scanning for the first booking
+  # - Booking lines are detected via fast character checks before regex matching
+  # - Line caching avoids redundant string operations within a single line
+  # - Memory-efficient string building minimizes allocations
+  #
+  # == Performance Optimizations
+  #
+  # Several techniques reduce parsing time for large statements:
+  # - First-character rejection filters out non-matching lines before regex
+  # - Pre-compiled regex patterns avoid repeated compilation
+  # - Memoized strip operations via @line_cache
+  # - StringScanner for structured booking line parsing
+  #
+  # == Supported Formats
+  #
+  # The parser recognizes German ING statement format with configurable labels
+  # for international variants:
+  # - Booking lines: "DD.MM.YYYY TransferType Recipient Amount"
+  # - Value date lines: "DD.MM.YYYY" or "DD.MM.YYYY Narrative text"
+  # - SEPA fields: "Mandat: XXX" and "Referenz: XXX" (configurable)
+  # - End markers: "Neuer Betrag" or "Neuer Saldo" (configurable)
+  #
+  # @api private
+  # @see StatementParser The public API that delegates to this class
+  class TextParser
+    # Phrases that signal the end of the transaction list in German statements.
+    # When any of these appear on a line, parsing stops.
+    # @return [Array<String>] frozen array of German end markers
+    DEFAULT_END_MARKERS = ['Neuer Betrag', 'Neuer Saldo'].freeze
+
+    # SEPA mandate identifier label in German statements.
+    # @return [String] the German label for mandate IDs
+    DEFAULT_MANDATE_LABEL = 'Mandat:'
+
+    # SEPA reference label in German statements.
+    # @return [String] the German label for payment references
+    DEFAULT_REFERENCE_LABEL = 'Referenz:'
+
+    # Creates a new parser with language-specific configuration.
+    #
+    # Override the defaults to parse statements in other languages or with
+    # custom field labels.
+    #
+    # @param end_markers [Array<String>] phrases that signal the end of the
+    #   transaction list. Parsing stops when any marker is found.
+    # @param mandate_label [String] the label preceding SEPA mandate IDs
+    #   (e.g., "Mandate:" for English statements)
+    # @param reference_label [String] the label preceding SEPA references
+    #   (e.g., "Reference:" for English statements)
+    # @param validate_iban [Boolean] whether to verify the IBAN checksum
+    #   using ISO 13616 mod-97. Set to false for faster parsing when
+    #   IBAN validation is handled elsewhere.
+    #
+    # @example German defaults (no arguments needed)
+    #   parser = TextParser.new
+    #
+    # @example English statement configuration
+    #   parser = TextParser.new(
+    #     end_markers: ['New Balance'],
+    #     mandate_label: 'Mandate:',
+    #     reference_label: 'Reference:'
+    #   )
+    def initialize(end_markers: DEFAULT_END_MARKERS,
+                   mandate_label: DEFAULT_MANDATE_LABEL,
+                   reference_label: DEFAULT_REFERENCE_LABEL,
+                   validate_iban: true)
+      @end_markers = end_markers
+      @mandate_label = mandate_label
+      @reference_label = reference_label
+      @validate_iban = validate_iban
+      compile_dynamic_patterns
+    end
+
+    # Parses a complete statement text and extracts all transactions.
+    #
+    # This is the primary entry point for parsing raw statement text. It performs
+    # a single-pass scan that simultaneously extracts the IBAN and parses all
+    # booking lines, minimizing memory allocations.
+    #
+    # @param text [String] the complete statement text (from PDF extraction or
+    #   text export)
+    # @return [Hash] parsed result with the following structure:
+    #   - +:header+ [Hash] containing +:iban+ (String)
+    #   - +:statements+ [Array<Hash>] list of parsed transactions
+    #   - +:warnings+ [Array<String>] optional, present only if issues occurred
+    # @raise [HeaderNotFound] if no valid IBAN line is found in the text
+    # @raise [BookingParseError] if no booking lines can be identified
+    #
+    # @example Parse statement text
+    #   result = parser.parse_text(pdf_text)
+    #   result[:header][:iban]  #=> "DE89 3704 0044 0532 0130 00"
+    #   result[:statements].first[:amount_eur]  #=> "-31,49"
+    def parse_text(text)
+      text_str = text.to_s
+      @warnings = []
+
+      # Single-pass streaming parse with lazy IBAN extraction
+      iban, statements = parse_streaming_with_iban(text_str)
+
+      build_result(iban, statements)
+    end
+
+    # Parses pre-split lines when the text is already line-separated.
+    #
+    # Use this when you have an array of lines (e.g., from splitting on newlines
+    # or reading line-by-line from a file). This avoids re-splitting the text
+    # internally.
+    #
+    # @param lines [Array<String>] individual lines from the statement
+    # @return [Hash] parsed result with +:header+ and +:statements+ keys
+    # @raise [HeaderNotFound] if no valid IBAN line is found
+    # @raise [BookingParseError] if no booking lines can be identified
+    #
+    # @see #parse_text For parsing unsplit text
+    def parse_lines(lines)
+      lines_array = Array(lines)
+      @warnings = []
+
+      # Parse with lazy IBAN extraction from lines
+      iban, statements = parse_lines_with_iban(lines_array)
+
+      build_result(iban, statements)
+    end
+
+    # Parses transaction lines without requiring an IBAN header.
+    #
+    # Use this when parsing statement fragments or when the IBAN is already
+    # known from another source. Skips header extraction entirely and returns
+    # only the statements array.
+    #
+    # @param lines [Array<String>] lines containing only the transaction portion
+    # @return [Array<Hash>] parsed transactions (not wrapped in a result hash)
+    #
+    # @example Parse transactions without header
+    #   statements = parser.parse_statement_lines(transaction_lines)
+    #   statements.first[:recipient]  #=> "Amazon EU"
+    def parse_statement_lines(lines)
+      @warnings = []
+      @line_cache = {}
+      parse_lines_internal(Array(lines))
+    end
+
+    private
+
+    # String constants to avoid repeated allocations during parsing.
+    # @api private
+    NEWLINE = "\n"
+    EMPTY_STRING = ''
+    SPACE = ' '
+    IBAN_MARKER = 'IBAN'
+    private_constant :NEWLINE, :EMPTY_STRING, :SPACE, :IBAN_MARKER
+
+    # Assembles the final result hash from parsed components.
+    #
+    # @param iban [String] the extracted IBAN
+    # @param statements [Array<Hash>] the parsed transaction list
+    # @return [Hash] the complete result with header, statements, and optional warnings
+    # @api private
+    def build_result(iban, statements)
+      result = { header: { iban: iban }, statements: statements }
+      result[:warnings] = @warnings unless @warnings.empty?
+      result
+    end
+
+    # Performs streaming parse with simultaneous IBAN and transaction extraction.
+    #
+    # This is the core parsing loop that processes text line-by-line. It lazily
+    # extracts the IBAN (stopping search once found) while building up the
+    # transaction list. Uses early termination when end markers are found.
+    #
+    # @param text [String] the complete statement text
+    # @return [Array(String, Array<Hash>)] tuple of [iban, statements]
+    # @raise [HeaderNotFound] if IBAN cannot be found
+    # @api private
+    def parse_streaming_with_iban(text) # rubocop:disable Metrics/MethodLength
+      statements = []
+      current = nil
+      found_first_booking = false
+      finished = false
+      iban = nil
+      @line_cache = {}
+
+      text.each_line do |raw_line|
+        next if finished
+
+        line = raw_line.chomp.rstrip
+        @line_cache = {} # Reset cache for new line
+
+        # Lazy IBAN extraction - only scan lines until we find it
+        iban = extract_iban_from_line(line) if iban.nil? && line.include?(IBAN_MARKER)
+
+        # Skip until we find first booking line
+        unless found_first_booking
+          next unless booking_line_candidate?(line)
+
+          found_first_booking = true
+        end
+
+        # Skip page break lines
+        next if page_break_line_fast?(line)
+
+        # Process artifact removal
+        cleaned = remove_known_prefix_artifact_fast(line)
+
+        # Reset cache if line was modified by artifact removal
+        @line_cache = {} if cleaned != line
+
+        current, finished = process_line(current, cleaned, statements)
+      end
+
+      # Validate IBAN was found
+      unless iban
+        raise IngKontoauszugParser::HeaderNotFound,
+              'IBAN line not found in statement text'
+      end
+
+      statements << current if current
+      [iban, finalize_statements(statements)]
+    end
+
+    # Parses a line array with lazy IBAN extraction.
+    #
+    # Similar to {#parse_streaming_with_iban} but optimized for pre-split lines.
+    # Performs a single pass to find both the IBAN and the first booking line
+    # index, then delegates to {#parse_lines_internal} for transaction parsing.
+    #
+    # @param lines [Array<String>] the statement lines
+    # @return [Array(String, Array<Hash>)] tuple of [iban, statements]
+    # @raise [HeaderNotFound] if IBAN cannot be found
+    # @raise [BookingParseError] if no booking lines exist
+    # @api private
+    def parse_lines_with_iban(lines)
+      iban = nil
+      first_idx = nil
+      @line_cache = {}
+
+      # Single pass to find IBAN and first booking
+      lines.each_with_index do |line, idx|
+        line_str = line.to_s
+
+        # Lazy IBAN extraction
+        iban = extract_iban_from_line(line_str) if iban.nil? && line_str.include?(IBAN_MARKER)
+
+        # Find first booking line
+        if first_idx.nil? && booking_line_candidate?(line_str)
+          first_idx = idx
+          break if iban # Found both, stop scanning
+        end
+      end
+
+      validate_iban_and_booking_found!(iban, first_idx)
+      [iban, parse_lines_internal(lines, first_idx)]
+    end
+
+    # Validates that both IBAN and first booking line were found.
+    # @param iban [String, nil] the extracted IBAN
+    # @param first_idx [Integer, nil] index of first booking line
+    # @raise [HeaderNotFound] if IBAN is nil
+    # @raise [BookingParseError] if first_idx is nil
+    # @api private
+    def validate_iban_and_booking_found!(iban, first_idx)
+      unless iban
+        raise IngKontoauszugParser::HeaderNotFound,
+              'IBAN line not found in statement text'
+      end
+
+      return if first_idx
+
+      raise IngKontoauszugParser::BookingParseError,
+            'Could not locate the first booking line in the statement text'
+    end
+
+    # Attempts to extract an IBAN from a single line.
+    #
+    # Matches the ING statement format "IBAN DE89 3704 0044 ..." and optionally
+    # validates the checksum. Returns nil if the line doesn't contain an IBAN
+    # or if validation fails.
+    #
+    # @param line [String] a single line that may contain an IBAN
+    # @return [String, nil] the extracted IBAN or nil if not found/invalid
+    # @api private
+    def extract_iban_from_line(line)
+      match = line.match(IBAN_LINE_REGEX)
+      return nil unless match
+
+      iban = match[1].strip
+      Header.validate_iban!(iban) if @validate_iban
+      iban
+    rescue IngKontoauszugParser::InvalidIBAN
+      nil # Try next line if validation fails
+    end
+
+    # Quickly determines if a line might be a booking (transaction) line.
+    #
+    # Uses a two-stage check: first a fast character test (must start with a digit),
+    # then a regex match. This avoids expensive regex operations on lines that
+    # clearly aren't bookings.
+    #
+    # @param line [String] the line to check
+    # @return [Boolean] true if the line looks like a booking line
+    # @api private
+    def booking_line_candidate?(line)
+      return false if line.empty?
+
+      # Fast reject: first non-space char must be a digit
+      first_char = line.lstrip[0]
+      return false unless first_char && first_char >= '0' && first_char <= '9'
+
+      # Only run regex if fast check passes
+      line.match?(FIRST_BOOKING_LINE_REGEX)
+    end
+
+    # Finds the first booking line and parses from that point.
+    #
+    # Legacy entry point that scans for the first booking and delegates
+    # to {#parse_lines_internal}. Used when IBAN extraction is handled separately.
+    #
+    # @param lines [Array<String>] statement lines
+    # @return [Array<Hash>] parsed transactions
+    # @raise [BookingParseError] if no booking lines can be found
+    # @api private
+    def parse_from_lines(lines)
+      first_idx = nil
+      lines.each_with_index do |line, idx|
+        if booking_line_candidate?(line.to_s)
+          first_idx = idx
+          break
+        end
+      end
+
+      unless first_idx
+        raise IngKontoauszugParser::BookingParseError,
+              'Could not locate the first booking line in the statement text'
+      end
+
+      parse_lines_internal(lines, first_idx)
+    end
+
+    # Core line-by-line transaction parsing loop.
+    #
+    # Iterates through lines starting at start_idx, building transaction objects
+    # as it encounters booking lines and accumulating narrative text for each.
+    # Stops when an end marker is found.
+    #
+    # @param lines [Array<String>] the statement lines
+    # @param start_idx [Integer] index to start parsing from (default: 0)
+    # @return [Array<Hash>] finalized list of parsed transactions
+    # @api private
+    def parse_lines_internal(lines, start_idx = 0)
+      statements = []
+      current = nil
+      @line_cache = {}
+
+      idx = start_idx
+      len = lines.length
+
+      while idx < len
+        raw_line = lines[idx]
+        idx += 1
+
+        line = raw_line.to_s.rstrip
+        @line_cache = {} # Reset cache for new line
+
+        # Skip page breaks
+        next if page_break_line_fast?(line)
+
+        # Artifact removal
+        cleaned = remove_known_prefix_artifact_fast(line)
+
+        # Reset cache if line was modified by artifact removal
+        @line_cache = {} if cleaned != line
+
+        current, finished = process_line(current, cleaned, statements)
+        break if finished
+      end
+
+      statements << current if current
+      finalize_statements(statements)
+    end
+
+    # Processes a single line within the parsing state machine.
+    #
+    # Determines the line type and updates state accordingly:
+    # - End marker: finishes current statement, signals completion
+    # - Booking line: starts a new transaction
+    # - Other: adds to current transaction's narrative or value date
+    #
+    # @param current [Hash, nil] the in-progress transaction, or nil if none
+    # @param line [String] the line to process
+    # @param statements [Array<Hash>] accumulator for completed transactions
+    # @return [Array(Hash, Boolean)] tuple of [updated_current, finished_flag]
+    # @api private
+    def process_line(current, line, statements)
+      # Use memoized stripped value
+      stripped = get_stripped(line)
+
+      if end_of_statements_fast?(stripped)
+        statements << current if current
+        return [nil, true]
+      end
+
+      if (booking = parse_booking_line_fast(line))
+        statements << current if current
+        return [build_statement_from_booking(booking), false]
+      end
+
+      return [current, false] unless current
+
+      [apply_value_or_narrative(current, line), false]
+    end
+
+    # Returns the stripped version of a line, caching the result.
+    #
+    # Avoids calling String#strip multiple times for the same line during
+    # a single processing cycle. Cache is cleared for each new line.
+    #
+    # @param line [String] the line to strip
+    # @return [String] the stripped line (cached)
+    # @api private
+    def get_stripped(line)
+      @line_cache ||= {}
+      @line_cache[:stripped] ||= line.strip
+    end
+
+    # Determines if a line is a page break or header that should be skipped.
+    #
+    # ING statements repeat page headers/footers on each page. This method
+    # identifies common patterns like "Seite X von Y", column headers, and
+    # date lines that aren't part of the transaction data.
+    #
+    # @param line [String] the line to check
+    # @return [Boolean] true if the line should be skipped
+    # @api private
+    def page_break_line_fast?(line)
+      stripped = get_stripped(line)
+      return true if stripped.empty?
+
+      # Check first character for fast rejection of most lines
+      first_char = stripped[0]
+      return false unless PAGE_BREAK_FIRST_CHARS.include?(first_char)
+
+      PAGE_BREAK_PATTERNS.any? { |re| stripped.match?(re) }
+    end
+
+    # Checks if a line contains an end-of-statements marker.
+    #
+    # Uses first-character rejection to quickly filter out non-matching lines
+    # before running the full regex check against configured end markers.
+    #
+    # @param stripped [String] a pre-stripped line
+    # @return [Boolean] true if line contains an end marker
+    # @api private
+    def end_of_statements_fast?(stripped)
+      return false if stripped.empty?
+
+      # Fast reject using first character
+      first_char = stripped[0]
+      return false unless @end_markers_first_chars.include?(first_char)
+
+      stripped.match?(@end_of_statements_regex)
+    end
+
+    # Legacy wrapper for backward compatibility.
+    # @param line [String] line to check (will be stripped)
+    # @return [Boolean] true if end marker found
+    # @api private
+    # @deprecated Use {#end_of_statements_fast?} with pre-stripped input
+    def end_of_statements?(line)
+      end_of_statements_fast?(line.strip)
+    end
+
+    # Removes OCR artifacts that appear at line beginnings.
+    #
+    # PDF extraction sometimes produces spurious "T" prefixes before dates
+    # or SEPA labels due to OCR errors or text positioning issues. This method
+    # detects and removes these artifacts while preserving legitimate content.
+    #
+    # @param str [String] the line that may contain artifacts
+    # @return [String] the cleaned line (same object if no artifacts found)
+    # @api private
+    def remove_known_prefix_artifact_fast(str)
+      return str if str.empty?
+
+      stripped = str.strip
+      return str if stripped.empty?
+
+      # Check for T prefix artifact
+      if (m = str.match(ARTIFACT_PREFIX_REGEX))
+        leading_ws = m[1]
+        rest = m[2]
+        return "#{leading_ws}#{rest}" if rest.match?(ARTIFACT_DATE_REGEX)
+        return "#{leading_ws}#{rest}" if rest.match?(@artifact_label_regex)
+      end
+
+      str
+    end
+
+    # Legacy wrapper for artifact removal.
+    # @param str [String] line to clean
+    # @return [String] cleaned line
+    # @api private
+    # @deprecated Use {#remove_known_prefix_artifact_fast}
+    def remove_known_prefix_artifact(str)
+      remove_known_prefix_artifact_fast(str)
+    end
+
+    # Filters and cleans an array of lines for parsing.
+    #
+    # Removes page breaks and OCR artifacts from each line. Used as a
+    # preprocessing step when lines need cleaning before parsing.
+    #
+    # @param lines [Array<String>] raw lines from PDF extraction
+    # @return [Array<String>] cleaned lines with page breaks removed
+    # @api private
+    # @deprecated Prefer streaming parsing which handles cleanup inline
+    def sanitize_lines(lines)
+      lines.each_with_object([]) do |line, acc|
+        @line_cache = {} # Reset cache for each line
+        next if page_break_line_fast?(line)
+
+        cleaned = line.to_s.dup.rstrip
+        cleaned = remove_known_prefix_artifact_fast(cleaned)
+        acc << cleaned
+      end
+    end
+
+    # Compiles regex patterns from configurable labels at initialization.
+    #
+    # Creates optimized patterns for end markers, mandate/reference extraction,
+    # and artifact detection based on the configured labels. Also pre-computes
+    # first-character sets for fast rejection filtering.
+    #
+    # @return [void]
+    # @api private
+    def compile_dynamic_patterns
+      # Build end-of-statements regex from configured markers
+      markers_pattern = @end_markers.map { |m| Regexp.escape(m) }.join('|')
+      @end_of_statements_regex = /\b(?:#{markers_pattern})\b/
+
+      # Pre-compute first characters of end markers for fast rejection
+      @end_markers_first_chars = @end_markers.map { |m| m[0] }.uniq.freeze
+
+      # Build mandate/reference regexes from configured labels
+      mandate_escaped = Regexp.escape(@mandate_label)
+      reference_escaped = Regexp.escape(@reference_label)
+      @mandate_regex = /\b#{mandate_escaped}\s*([^\s]+(?:\s(?!#{reference_escaped})[^\s]+)*)/
+      @reference_regex = /\b#{reference_escaped}\s*([^\s]+(?:\s(?!#{mandate_escaped})[^\s]+)*)/
+
+      # Build artifact label regex
+      @artifact_label_regex = /\A\s*(#{reference_escaped}|#{mandate_escaped})/
+    end
+
+    # Matches IBAN line format: "IBAN DE89 3704 0044 0532 0130 00"
+    # Captures the IBAN portion (country code + check digits + BBAN).
+    IBAN_LINE_REGEX = /IBAN\s+([A-Z0-9 ]{10,})/
+    private_constant :IBAN_LINE_REGEX
+
+    # First characters of page break patterns for fast rejection.
+    # Lines not starting with these characters can skip the full regex check.
+    # Covers: Seite, Valuta, Girokonto, Kontoauszug, Datum, Buchung, Betrag
+    PAGE_BREAK_FIRST_CHARS = %w[S V G K D B].freeze
+    private_constant :PAGE_BREAK_FIRST_CHARS
+
+    # German date format: DD.MM.YYYY (e.g., "01.08.2025")
+    DATE_PATTERN = /\d{2}\.\d{2}\.\d{4}/
+
+    # German currency format with thousand separators and comma decimal.
+    # Matches: "1.234,56", "-31,49", "+100,00"
+    AMOUNT_PATTERN_FULL = /[-+]?\d{1,3}(?:\.\d{3})*,\d{2}/
+
+    # Value date followed by narrative text on the same line.
+    # Captures: (1) date, (2) remaining text
+    VALUE_DATE_WITH_TEXT_REGEX = /\A\s*(\d{2}\.\d{2}\.\d{4})\s+(.*)\z/
+
+    # Value date alone on a line (no narrative text).
+    VALUE_DATE_ONLY_REGEX = /\A\d{2}\.\d{2}\.\d{4}\z/
+
+    # Amount pattern for detecting stray amount lines.
+    AMOUNT_PATTERN = /[-+]?\d{1,3}(?:\.\d{3})*,\d{2}/
+
+    # Booking line format: "DD.MM.YYYY TransferType ..."
+    # Must start with date followed by whitespace and non-whitespace.
+    FIRST_BOOKING_LINE_REGEX = /^\s*\d{2}\.\d{2}\.\d{4}\s+\S/
+
+    # Acquirer Reference Number (ARN) for card transactions.
+    # Used as fallback reference when SEPA reference is not present.
+    ARN_REGEX = /\bARN\d{8,}\b/
+
+    # Google Pay indicator in narrative text.
+    GOOGLE_PAY_REGEX = /\bgoogle\s+pay\b/i
+
+    # OCR artifact pattern: spurious "T" prefix before content.
+    # Captures: (1) leading whitespace, (2) content after "T"
+    ARTIFACT_PREFIX_REGEX = /\A(\s*)T(.*)\z/
+
+    # Date pattern for artifact validation (ensures "T" was before a date).
+    ARTIFACT_DATE_REGEX = /\A\s*\d{2}\.\d{2}\.\d{4}\b/
+
+    private_constant :DATE_PATTERN, :AMOUNT_PATTERN_FULL,
+                     :VALUE_DATE_WITH_TEXT_REGEX, :VALUE_DATE_ONLY_REGEX, :AMOUNT_PATTERN,
+                     :FIRST_BOOKING_LINE_REGEX, :ARN_REGEX,
+                     :GOOGLE_PAY_REGEX,
+                     :ARTIFACT_PREFIX_REGEX, :ARTIFACT_DATE_REGEX
+
+    # Parses a booking (transaction) line into its components.
+    #
+    # Uses StringScanner for efficient left-to-right parsing of the format:
+    # "DD.MM.YYYY TransferType Recipient Amount"
+    #
+    # The amount is located by scanning from the right since recipient names
+    # can contain spaces.
+    #
+    # @param line [String] a potential booking line
+    # @return [Hash, nil] parsed components or nil if not a valid booking line
+    #   - +:booking_date+ [String] the transaction date
+    #   - +:transfer_type+ [String] transaction type (e.g., "Lastschrift")
+    #   - +:recipient+ [String] counterparty name
+    #   - +:amount_raw+ [String] amount in German format
+    # @api private
+    def parse_booking_line_fast(line)
+      # Fast reject: must start with optional whitespace then digit
+      stripped = get_stripped(line)
+      return nil if stripped.empty?
+
+      first_char = stripped[0]
+      return nil unless first_char.between?('0', '9')
+
+      # Use StringScanner for structured parsing
+      scanner = StringScanner.new(line)
+
+      # Skip leading whitespace
+      scanner.skip(/\s*/)
+
+      # Match date (DD.MM.YYYY)
+      date = scanner.scan(/\d{2}\.\d{2}\.\d{4}/)
+      return nil unless date
+
+      # Must have whitespace after date
+      return nil unless scanner.skip(/\s+/)
+
+      # Match transfer type (non-whitespace)
+      transfer_type = scanner.scan(/\S+/)
+      return nil unless transfer_type
+
+      # Must have whitespace
+      return nil unless scanner.skip(/\s+/)
+
+      # Scan to find amount at end - work backwards
+      rest = scanner.rest.rstrip
+
+      # Find the last amount pattern in the line
+      amount_match = rest.match(/(.*?)\s+([-+]?\d{1,3}(?:\.\d{3})*,\d{2})\s*\z/)
+      return nil unless amount_match
+
+      recipient = amount_match[1].strip
+      amount = amount_match[2]
+
+      { booking_date: date, transfer_type: transfer_type, recipient: recipient, amount_raw: amount }
+    end
+
+    # Legacy wrapper for booking line parsing.
+    # @param line [String] line to parse
+    # @return [Hash, nil] parsed booking or nil
+    # @api private
+    # @deprecated Use {#parse_booking_line_fast}
+    def parse_booking_line(line)
+      parse_booking_line_fast(line)
+    end
+
+    # Creates an initial statement hash from parsed booking data.
+    #
+    # Converts the raw booking components into the statement structure,
+    # including amount normalization and direction detection.
+    #
+    # @param booking [Hash] output from {#parse_booking_line_fast}
+    # @return [Hash] statement hash ready for narrative accumulation
+    # @api private
+    def build_statement_from_booking(booking)
+      amount_numeric = parse_amount(booking[:amount_raw])
+      {
+        booking_date: booking[:booking_date],
+        transfer_type: booking[:transfer_type],
+        recipient: booking[:recipient],
+        amount_eur: booking[:amount_raw],
+        amount_eur_numeric: amount_numeric.to_s('F'),
+        amount_direction: amount_direction(amount_numeric),
+        value_date: nil,
+        narrative_lines: []
+      }
+    end
+
+    # Converts German amount format to BigDecimal.
+    #
+    # German format uses dots as thousand separators and commas for decimals.
+    # "-1.234,56" becomes BigDecimal("-1234.56")
+    #
+    # @param raw [String] amount in German format (e.g., "-1.234,56")
+    # @return [BigDecimal] the numeric amount
+    # @api private
+    def parse_amount(raw)
+      BigDecimal(raw.delete('.').tr(',', '.'))
+    end
+
+    # Determines the transaction direction from the amount sign.
+    #
+    # @param amount_numeric [BigDecimal] the parsed amount
+    # @return [String] "debit" for negative, "credit" for positive, "neutral" for zero
+    # @api private
+    def amount_direction(amount_numeric)
+      return 'debit' if amount_numeric.negative?
+      return 'credit' if amount_numeric.positive?
+
+      'neutral'
+    end
+
+    # Adds value date or narrative text to an in-progress statement.
+    #
+    # After a booking line, subsequent lines are either:
+    # - A value date (alone or with narrative)
+    # - Pure narrative text
+    # - Stray amount lines (logged as warnings)
+    #
+    # @param current [Hash] the in-progress statement
+    # @param line [String] the line to process
+    # @return [Hash] the updated statement
+    # @api private
+    def apply_value_or_narrative(current, line)
+      stripped = get_stripped(line)
+
+      if current[:value_date].nil?
+        if (m = line.match(VALUE_DATE_WITH_TEXT_REGEX))
+          current[:value_date] = m[1]
+          initial = m[2].strip
+          current[:narrative_lines] << initial unless initial.empty?
+        elsif stripped.match?(VALUE_DATE_ONLY_REGEX)
+          current[:value_date] = stripped
+        elsif stripped.match?(AMOUNT_PATTERN)
+          @warnings << 'Encountered amount line without active statement'
+        else
+          current[:narrative_lines] << stripped
+        end
+      else
+        current[:narrative_lines] << stripped
+      end
+
+      current
+    end
+
+    # Post-processes all parsed statements for final output.
+    #
+    # Converts accumulated narrative lines to a single string, extracts
+    # mandate/reference identifiers, detects Google Pay transactions, and
+    # filters out incomplete statements (missing value date).
+    #
+    # @param statements [Array<Hash>] raw statement hashes with narrative_lines
+    # @return [Array<Hash>] finalized statements ready for output
+    # @api private
+    def finalize_statements(statements)
+      return [] if statements.empty?
+
+      statements.filter_map do |statement|
+        unless statement[:value_date]
+          @warnings << "Could not locate value date for statement: #{statement[:recipient]}"
+          next
+        end
+
+        narrative_lines = statement.delete(:narrative_lines)
+        narrative = build_narrative(narrative_lines)
+        s = statement.merge(narrative: narrative)
+
+        mandate_id, reference = extract_mandate_and_reference(narrative)
+        s[:mandate_id] = mandate_id if mandate_id
+        s[:reference] = reference if reference
+
+        s[:google_pay] = true if narrative.match?(GOOGLE_PAY_REGEX)
+        s
+      end
+    end
+
+    # Joins narrative lines into a single space-separated string.
+    #
+    # Uses pre-allocated string capacity and avoids intermediate array
+    # creation for better memory efficiency with long narratives.
+    #
+    # @param lines [Array<String>] individual narrative lines
+    # @return [String] joined narrative text
+    # @api private
+    def build_narrative(lines)
+      return EMPTY_STRING if lines.empty?
+
+      result = String.new(capacity: lines.sum(&:length) + lines.length)
+      first = true
+
+      lines.each do |line|
+        next if line.empty?
+
+        if first
+          first = false
+        else
+          result << SPACE
+        end
+        result << line
+      end
+
+      result
+    end
+
+    # Extracts SEPA mandate ID and reference from narrative text.
+    #
+    # Searches for configured labels (e.g., "Mandat:", "Referenz:") in the
+    # narrative. Falls back to ARN pattern for card transactions.
+    #
+    # @param narrative [String] the joined narrative text
+    # @return [Array(String, String)] tuple of [mandate_id, reference], either may be nil
+    # @api private
+    def extract_mandate_and_reference(narrative)
+      mandate_match = narrative.match(@mandate_regex)
+      reference_match = narrative.match(@reference_regex)
+
+      mandate = sanitize_identifier(mandate_match[1]) if mandate_match
+      reference = sanitize_identifier(reference_match[1]) if reference_match
+      reference ||= extract_arn_reference(narrative)
+      [mandate, reference]
+    end
+
+    # Matches whitespace for identifier normalization.
+    WHITESPACE_REGEX = /\s+/
+    private_constant :WHITESPACE_REGEX
+
+    # Removes internal whitespace from identifiers.
+    #
+    # SEPA mandate IDs and references may contain spaces from line wrapping
+    # that should be removed for consistent output.
+    #
+    # @param value [String] identifier that may contain whitespace
+    # @return [String] identifier with whitespace removed
+    # @api private
+    def sanitize_identifier(value)
+      value.gsub(WHITESPACE_REGEX, EMPTY_STRING)
+    end
+
+    # Extracts ARN (Acquirer Reference Number) from narrative.
+    #
+    # ARN is used for card transactions and serves as a fallback reference
+    # when no SEPA reference is present.
+    #
+    # @param narrative [String] the narrative text to search
+    # @return [String, nil] the ARN if found, nil otherwise
+    # @api private
+    def extract_arn_reference(narrative)
+      narrative[ARN_REGEX]
+    end
+
+    # Patterns matching ING statement page headers and footers.
+    #
+    # These lines appear on each page of multi-page statements and should be
+    # skipped during parsing. Ordered by likelihood for faster early exit.
+    #
+    # Patterns match:
+    # - "Seite X von Y" (page numbers)
+    # - "Valuta" (column header)
+    # - "Girokonto Nummer ..." (account header)
+    # - "Kontoauszug ..." (statement header)
+    # - "Datum DD.MM.YYYY" (date header)
+    # - "Buchung / Verwendungszweck" (column headers)
+    # - "Betrag (EUR)" (amount column header)
+    PAGE_BREAK_PATTERNS = [
+      /\ASeite\b/,
+      /\AValuta\z/,
+      /\AGirokonto Nummer\b/,
+      /\AKontoauszug\b/,
+      /\ADatum\b.*\d{2}\.\d{2}\.\d{4}\z/,
+      %r{\ABuchung\s+Buchung\s*/\s*Verwendungszweck\b},
+      /\ABetrag \(EUR\)\z/
+    ].freeze
+    private_constant :PAGE_BREAK_PATTERNS
+
+    # Legacy wrapper for page break detection.
+    # @param line [String] line to check
+    # @return [Boolean] true if line is a page break
+    # @api private
+    # @deprecated Use {#page_break_line_fast?}
+    def page_break_line?(line)
+      @line_cache = {}
+      page_break_line_fast?(line)
+    end
+  end
+end