invoice_extractor_arca 0.2.0

data/lib/invoice_extractor_arca/qr/payload_parser.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "uri"
+
+module InvoiceExtractorArca
+  module Qr
+    class PayloadParser
+      def parse(raw_value, image_file:, page_number: nil)
+        uri = URI.parse(raw_value)
+        p_value = query_param(uri.query, "p")
+
+        if p_value.nil? || p_value.empty?
+          return invalid_candidate(
+            raw_value,
+            "missing_p_parameter",
+            "QR URL does not include a p query parameter",
+            image_file: image_file,
+            page_number: page_number
+          )
+        end
+
+        decoded_json, warning = decode_base64(p_value)
+        payload = JSON.parse(decoded_json)
+
+        unless payload.is_a?(Hash)
+          return invalid_candidate(
+            raw_value,
+            "invalid_payload_json",
+            "Decoded QR payload is JSON, but not an object",
+            image_file: image_file,
+            page_number: page_number
+          )
+        end
+
+        {
+          valid: true,
+          url: raw_value,
+          p: p_value,
+          decoded_json: decoded_json,
+          payload: payload,
+          image_file: image_file,
+          page_number: page_number,
+          errors: [],
+          warnings: [warning].compact
+        }
+      rescue URI::InvalidURIError => e
+        invalid_candidate(
+          raw_value,
+          "invalid_qr_url",
+          e.message,
+          image_file: image_file,
+          page_number: page_number
+        )
+      rescue ArgumentError => e
+        invalid_candidate(
+          raw_value,
+          "invalid_base64_payload",
+          e.message,
+          image_file: image_file,
+          page_number: page_number
+        )
+      rescue JSON::ParserError => e
+        invalid_candidate(
+          raw_value,
+          "invalid_json_payload",
+          e.message,
+          image_file: image_file,
+          page_number: page_number
+        )
+      end
+
+      private
+
+      def query_param(query, name)
+        URI.decode_www_form(query.to_s).each do |key, value|
+          return value if key == name
+        end
+
+        nil
+      end
+
+      def decode_base64(value)
+        [Base64.strict_decode64(value), nil]
+      rescue ArgumentError
+        [
+          Base64.urlsafe_decode64(value),
+          {
+            code: "urlsafe_base64_payload",
+            message: "QR payload used URL-safe Base64 decoding",
+            component: "qr"
+          }
+        ]
+      end
+
+      def invalid_candidate(
+        raw_value,
+        code,
+        message,
+        image_file:,
+        page_number:
+      )
+        {
+          valid: false,
+          url: raw_value,
+          p: nil,
+          decoded_json: nil,
+          payload: nil,
+          image_file: image_file,
+          page_number: page_number,
+          errors: [
+            {
+              code: code,
+              message: message,
+              component: "qr"
+            }
+          ],
+          warnings: []
+        }
+      end
+    end
+  end
+end

data/lib/invoice_extractor_arca/qr/reader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module InvoiceExtractorArca
+  module Qr
+    class Reader
+      def initialize(scanner:, parser:, result_builder:)
+        @scanner = scanner
+        @parser = parser
+        @result_builder = result_builder
+      end
+
+      def read(
+        source_file:,
+        targets:,
+        image_files: targets.map { |target| target[:path] }
+      )
+        outputs = targets.map { |target| scan_target(target) }
+
+        candidates = outputs.flat_map do |output|
+          output[:values].map do |raw_value|
+            @parser.parse(
+              raw_value,
+              image_file: output[:image_file],
+              page_number: output[:page_number]
+            )
+          end
+        end
+
+        warnings = outputs.flat_map { |output| output[:warnings] }
+
+        @result_builder.build(
+          source_file: source_file,
+          image_files: image_files,
+          candidates: candidates,
+          warnings: warnings
+        )
+      end
+
+      private
+
+      def scan_target(target)
+        result = @scanner.scan(target.fetch(:path))
+
+        {
+          image_file: target.fetch(:path),
+          page_number: target[:page_number],
+          values: Array(result[:values]),
+          warnings: Array(result[:warnings])
+        }
+      end
+    end
+  end
+end

data/lib/invoice_extractor_arca/qr/result_builder.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+
+module InvoiceExtractorArca
+  module Qr
+    class ResultBuilder
+      MODES = %i[first_valid all error].freeze
+
+      def initialize(multiple_qr: :first_valid)
+        @multiple_qr = normalize_mode(multiple_qr)
+      end
+
+      def build(
+        source_file:,
+        image_files:,
+        candidates:,
+        warnings:
+      )
+        valid_candidates = candidates.select { |candidate| candidate[:valid] }
+        distinct_candidates = distinct(valid_candidates)
+
+        if valid_candidates.empty?
+          return not_found_result(
+            source_file: source_file,
+            image_files: image_files,
+            candidates: candidates,
+            warnings: warnings
+          )
+        end
+
+        if @multiple_qr == :error && distinct_candidates.length > 1
+          return multiple_qr_result(
+            source_file: source_file,
+            image_files: image_files,
+            candidates: candidates,
+            valid_candidates: valid_candidates,
+            distinct_candidates: distinct_candidates,
+            warnings: warnings
+          )
+        end
+
+        success_result(
+          source_file: source_file,
+          image_files: image_files,
+          candidates: candidates,
+          selected: valid_candidates.first,
+          valid_candidates: valid_candidates,
+          distinct_candidates: distinct_candidates,
+          warnings: warnings
+        )
+      end
+
+      def failure(source_file:, code:, message:)
+        {
+          found: false,
+          count: 0,
+          valid_count: 0,
+          distinct_valid_count: 0,
+          duplicate_valid_count: 0,
+          raw_values: [],
+          selected_index: nil,
+          selected_url: nil,
+          p: nil,
+          decoded_json: nil,
+          payload: nil,
+          candidates: [],
+          source_file: source_file,
+          image_file: nil,
+          image_files: [],
+          errors: [
+            {
+              code: code,
+              message: message,
+              component: "qr"
+            }
+          ],
+          warnings: []
+        }
+      end
+
+      private
+
+      def normalize_mode(value)
+        mode = value.to_sym
+        return mode if MODES.include?(mode)
+
+        raise Errors::UnsupportedFileType,
+          "Invalid multiple_qr mode: #{value.inspect}"
+      end
+
+      def not_found_result(
+        source_file:,
+        image_files:,
+        candidates:,
+        warnings:
+      )
+        errors = candidates.flat_map { |candidate| candidate[:errors] }
+
+        base_result(
+          source_file: source_file,
+          image_files: image_files,
+          candidates: candidates,
+          warnings: collected_warnings(candidates, warnings)
+        ).merge(
+          found: false,
+          valid_count: 0,
+          distinct_valid_count: 0,
+          duplicate_valid_count: 0,
+          errors: errors
+        )
+      end
+
+      def multiple_qr_result(
+        source_file:,
+        image_files:,
+        candidates:,
+        valid_candidates:,
+        distinct_candidates:,
+        warnings:
+      )
+        base_result(
+          source_file: source_file,
+          image_files: image_files,
+          candidates: candidates,
+          warnings: collected_warnings(candidates, warnings)
+        ).merge(
+          found: false,
+          valid_count: valid_candidates.length,
+          distinct_valid_count: distinct_candidates.length,
+          duplicate_valid_count:
+            valid_candidates.length - distinct_candidates.length,
+          errors: [
+            {
+              code: "multiple_qr_found",
+              message:
+                "More than one distinct ARCA QR payload was found",
+              component: "qr",
+              details: {
+                valid_count: valid_candidates.length,
+                distinct_valid_count: distinct_candidates.length
+              }
+            }
+          ]
+        )
+      end
+
+      def success_result(
+        source_file:,
+        image_files:,
+        candidates:,
+        selected:,
+        valid_candidates:,
+        distinct_candidates:,
+        warnings:
+      )
+        base_result(
+          source_file: source_file,
+          image_files: image_files,
+          candidates: candidates,
+          warnings: collected_warnings(candidates, warnings)
+        ).merge(
+          found: true,
+          valid_count: valid_candidates.length,
+          distinct_valid_count: distinct_candidates.length,
+          duplicate_valid_count:
+            valid_candidates.length - distinct_candidates.length,
+          selected_index: candidates.index(selected),
+          selected_url: selected[:url],
+          p: selected[:p],
+          decoded_json: selected[:decoded_json],
+          payload: selected[:payload],
+          errors: []
+        )
+      end
+
+      def base_result(source_file:, image_files:, candidates:, warnings:)
+        {
+          found: false,
+          count: candidates.length,
+          valid_count: 0,
+          distinct_valid_count: 0,
+          duplicate_valid_count: 0,
+          raw_values: candidates.map { |candidate| candidate[:url] },
+          selected_index: nil,
+          selected_url: nil,
+          p: nil,
+          decoded_json: nil,
+          payload: nil,
+          candidates: candidates,
+          source_file: source_file,
+          image_file: image_files.first,
+          image_files: image_files,
+          errors: [],
+          warnings: warnings
+        }
+      end
+
+      def collected_warnings(candidates, scanner_warnings)
+        scanner_warnings +
+          candidates.flat_map { |candidate| candidate[:warnings] }
+      end
+
+      def distinct(candidates)
+        candidates.uniq do |candidate|
+          canonical_payload(candidate[:payload])
+        end
+      end
+
+      def canonical_payload(payload)
+        JSON.generate(deep_sort(payload))
+      end
+
+      def deep_sort(value)
+        case value
+        when Hash
+          value
+            .sort_by { |key, _value| key.to_s }
+            .to_h
+            .transform_values { |child| deep_sort(child) }
+        when Array
+          value.map { |child| deep_sort(child) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/invoice_extractor_arca/qr_extractor.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "pdf/renderer"
+require_relative "scanners/factory"
+require_relative "qr/payload_parser"
+require_relative "qr/result_builder"
+require_relative "qr/reader"
+
+module InvoiceExtractorArca
+  class QrExtractor
+    IMAGE_EXTENSIONS = %w[
+      .png
+      .jpg
+      .jpeg
+      .webp
+      .bmp
+      .tif
+      .tiff
+    ].freeze
+
+    def initialize(
+      resolver:,
+      runner:,
+      renderer: nil,
+      converter: nil,
+      page_range: nil,
+      resolution: 300,
+      multiple_qr: :first_valid,
+      scanner: nil,
+      qr_scanner: :zbar,
+      python_command: :python3,
+      parser: Qr::PayloadParser.new,
+      result_builder: nil,
+      reader: nil
+    )
+      @page_range = page_range
+      @resolution = resolution
+
+      # `converter` remains temporarily supported for compatibility.
+      @renderer =
+        renderer ||
+        converter ||
+        Pdf::Renderer.new(
+          resolver: resolver,
+          runner: runner
+        )
+
+      scanner ||=
+        Scanners::Factory.new(
+          resolver: resolver,
+          runner: runner,
+          python_command: python_command
+        ).build(qr_scanner)
+
+      result_builder ||=
+        Qr::ResultBuilder.new(multiple_qr: multiple_qr)
+
+      @result_builder = result_builder
+
+      @reader =
+        reader ||
+        Qr::Reader.new(
+          scanner: scanner,
+          parser: parser,
+          result_builder: result_builder
+        )
+    end
+
+    def extract(file_path)
+      if pdf?(file_path)
+        extract_pdf(file_path)
+      elsif image?(file_path)
+        extract_image(file_path)
+      else
+        unsupported_file(file_path)
+      end
+    rescue Errors::UnsupportedFileType => e
+      @result_builder.failure(
+        source_file: file_path,
+        code: "unsupported_file_type",
+        message: e.message
+      )
+    end
+
+    private
+
+    def extract_pdf(file_path)
+      @renderer.render(
+        file_path,
+        page_range: @page_range,
+        resolution: @resolution
+      ) do |image_paths|
+        paths = Array(image_paths)
+        pages = requested_pages(paths.length)
+
+        targets = paths.zip(pages).map do |path, page_number|
+          {
+            path: path,
+            page_number: page_number
+          }
+        end
+
+        @reader.read(
+          source_file: file_path,
+          targets: targets,
+          image_files: paths
+        )
+      end
+    end
+
+    def extract_image(file_path)
+      @reader.read(
+        source_file: file_path,
+        targets: [
+          {
+            path: file_path,
+            page_number: nil
+          }
+        ],
+        image_files: []
+      )
+    end
+
+    def requested_pages(rendered_count)
+      pages =
+        case @page_range
+        when nil
+          [1]
+        when Integer
+          [@page_range]
+        when Range
+          @page_range.to_a
+        when Array
+          @page_range
+        else
+          []
+        end
+
+      pages.first(rendered_count)
+    end
+
+    def unsupported_file(file_path)
+      raise Errors::UnsupportedFileType,
+        "Unsupported file type: #{File.extname(file_path)}"
+    end
+
+    def pdf?(file_path)
+      File.extname(file_path).downcase == ".pdf"
+    end
+
+    def image?(file_path)
+      IMAGE_EXTENSIONS.include?(File.extname(file_path).downcase)
+    end
+  end
+end

data/lib/invoice_extractor_arca/result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module InvoiceExtractorArca
+  class Result
+    attr_reader :source,
+      :qr,
+      :voucher,
+      :text,
+      :enrichment,
+      :validation,
+      :errors,
+      :metadata,
+      :final
+
+    def initialize(
+      source: {},
+      qr: {},
+      voucher: nil,
+      text: {},
+      enrichment: {},
+      validation: {},
+      errors: [],
+      metadata: {},
+      final: {}
+    )
+      @source = source || {}
+      @qr = qr || {}
+      @voucher = voucher
+      @text = text || {}
+      @enrichment = enrichment || {}
+      @validation = validation || {}
+      @errors = errors || []
+      @metadata = metadata || {}
+      @final = final || {}
+    end
+
+    def success?
+      errors.none?(&:error?) && !voucher.nil? && qr[:found] == true
+    end
+
+    def failure?
+      !success?
+    end
+
+    def final_payload
+      {
+        qr_payload: voucher&.dig(:original),
+        voucher: voucher&.dig(:normalized),
+        enrichment: normalized_enrichment
+      }
+    end
+
+    def normalized_enrichment
+      enrichment.each_with_object({}) do |(name, value), output|
+        output[name] =
+          if name == :service_rows
+            Array(value).map { |row| normalized_service_row(row) }
+          elsif value.is_a?(Hash)
+            value[:normalized]
+          else
+            value
+          end
+      end
+    end
+
+    def normalized_service_row(row)
+      row.each_with_object({}) do |(name, value), output|
+        output[name] =
+          value.is_a?(Hash) ? value[:normalized] : value
+      end
+    end
+
+    def to_h
+      {
+        source: source,
+        data: final_payload,
+        qr: qr,
+        voucher: voucher,
+        text: text,
+        enrichment: enrichment,
+        validation: validation,
+        errors: errors.map(&:to_h),
+        metadata: metadata,
+        final: final
+      }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end