invoice_extractor_arca 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16278ffa86026380d3f66d0fdd3d028217583262f84747f6c0abb9fe9ff9a0ee
+  data.tar.gz: fb9ee435a5d1d0783955c9650494dcc683c7a50a4f73eb8e9cd46b115cc6f906
+SHA512:
+  metadata.gz: '09bada94fdc09cb05f364b1e195002f217f9fb9791a6d35b2457dd7d9b920f0a37821f01f3dc1aa5bd941382b778803ed43a4d716f9b404771f2470c8ba822c4'
+  data.tar.gz: d46cc254d2a855408511427eae31da7802b45005e8689cb98e28603406983e5ad0911d09536861fe67e576faeb2352f85d999d0c918cc69ef2236762b885e339

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- Command-line interface through `arca-invoice-extract`.
+- Compact and pretty JSON output.
+- Documented CLI exit codes.
+- CLI options for strict mode, enrichment, page selection, rendering resolution, QR scanner selection, multiple QR handling, and dependency paths.
+- QR scanner fallback chains using ZBar and QReader.
+- RapidOCR-based text extraction for invoice images.
+- PDF text extraction with page selection.
+- Regex-based invoice field enrichment.
+- Layout-aware extraction of product and service rows.
+- Reconciliation between QR-derived and text-derived invoice values.
+- ARCA catalogs for voucher types, currencies, document types, IVA conditions, payment methods, copy types, and units of measure.
+- Unit and integration tests for the CLI, OCR, enrichment, reconciliation, scanners, and PDF processing.
+
+### Changed
+
+- Expanded extraction results with `text`, `enrichment`, and `validation` sections.
+- Improved multiple-QR handling by distinguishing duplicate payloads from distinct payloads.
+- QR scanner selection is now configurable.
+- Image extraction can optionally enrich invoice data using OCR.
+- Structured diagnostics now distinguish errors from warnings.
+
+### Fixed
+
+- Preserved actual PDF page numbers in QR candidates.
+- Improved handling of URL-safe Base64 QR payloads.
+- Normalized Argentine decimal values, dates, document numbers, and invoice codes.
+- Ensured temporary rendered PDF pages are removed after processing.
+
+### Security
+
+- External commands are executed using argument arrays rather than shell command strings.
+
+## [0.1.0] - 2026-07-28
+
+### Added
+
+- Initial release.
+- QR-first extraction from PDF and image invoices.
+- ARCA QR payload decoding and voucher validation.
+- Structured result and error objects.
+- PDF rendering and QR scanning with ZBar.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Juan Manuel Llaury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,631 @@
+# InvoiceExtractorArca
+
+A Ruby gem for extracting structured data from Argentine ARCA electronic invoices.
+
+The gem follows a **QR-first** approach:
+
+1. Detect and decode the ARCA QR code from an image or PDF.
+2. Validate and normalize the QR payload.
+3. Return a structured result object.
+4. Optionally extract text from PDFs or images.
+5. Enrich the result with invoice fields and service rows.
+6. Reconcile extracted text values against the authoritative QR payload.
+
+## Features
+
+- Extract ARCA invoice data from:
+  - PDF files
+  - PNG
+  - JPG / JPEG
+  - WEBP
+  - BMP
+  - TIFF
+- QR-first extraction strategy
+- ARCA payload validation
+- Voucher normalization
+- Currency validation
+- Document type validation
+- Multiple QR detection
+- PDF text extraction
+- Structured error reporting
+- Strict and permissive modes
+- Multiple QR scanner backends:
+  - zbarimg
+  - QReader (Python)
+  - Fallback chains
+- PDF text extraction with `pdftotext`
+- Image OCR enrichment with RapidOCR
+- Regex-based invoice field enrichment
+- Service-row extraction from invoice tables
+- QR-to-text reconciliation
+- Command-line interface with JSON output
+- Configurable page selection and rendering resolution
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "invoice_extractor_arca"
+```
+
+and run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install invoice_extractor_arca
+```
+
+---
+
+## External Dependencies
+
+The gem relies on external tools:
+
+### Required
+
+```bash
+pdftoppm
+pdftotext
+zbarimg
+```
+
+### Optional
+
+For the QReader backend:
+
+```bash
+python3
+opencv-python
+qreader
+```
+
+---
+
+### OCR enrichment for images
+
+Image enrichment uses RapidOCR through Python.
+
+Install the optional OCR dependencies:
+
+```bash
+python3 -m venv .venv-ocr
+.venv-ocr/bin/pip install -r requirements-ocr.txt
+```
+
+Pass the virtual-environment interpreter when using the Ruby API:
+
+```ruby
+result = InvoiceExtractorArca.extract_image(
+  "invoice.png",
+  dependency_paths: {
+    python3: ".venv-ocr/bin/python"
+  }
+)
+```
+
+Or with the command-line interface:
+
+```bash
+arca-invoice-extract \
+  --dependency python3=.venv-ocr/bin/python \
+  invoice.png
+```
+
+## Verify Dependencies
+
+```ruby
+InvoiceExtractorArca.check_dependencies
+```
+
+Example:
+
+```ruby
+{
+  pdftoppm: {
+    available: true,
+    path: "/usr/bin/pdftoppm"
+  },
+  pdftotext: {
+    available: true,
+    path: "/usr/bin/pdftotext"
+  },
+  zbarimg: {
+    available: true,
+    path: "/usr/bin/zbarimg"
+  }
+}
+```
+
+To raise if dependencies are missing:
+
+```ruby
+InvoiceExtractorArca.check_dependencies!
+```
+
+---
+
+## Basic Usage
+
+### Extract from PDF
+
+```ruby
+result = InvoiceExtractorArca.extract("invoice.pdf")
+```
+
+### Extract from Image
+
+```ruby
+result = InvoiceExtractorArca.extract("invoice.jpg")
+```
+
+### PDF-only API
+
+```ruby
+result = InvoiceExtractorArca.extract_pdf("invoice.pdf")
+```
+
+### Image-only API
+
+```ruby
+result = InvoiceExtractorArca.extract_image("invoice.png")
+```
+
+---
+
+## Successful Result
+
+```ruby
+result.success?
+# => true
+```
+
+Example:
+
+```ruby
+result.voucher[:normalized]
+
+{
+  version: 1,
+  issued_on: "2024-06-30",
+  issuer_cuit: "30712345678",
+  point_of_sale: "00001",
+  voucher_type_code: "006",
+  voucher_type_description: "FACTURA B",
+  voucher_number: "00000123",
+  invoice_number: "00001-00000123",
+  amount: "1500.00",
+  currency_code: "PES",
+  currency_description: "PESOS"
+}
+```
+
+---
+
+## Strict Mode
+
+By default, the gem returns structured errors without raising exceptions.
+
+```ruby
+result = InvoiceExtractorArca.extract("invoice.pdf")
+```
+
+Enable strict mode:
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  strict: true
+)
+```
+
+Possible exceptions:
+
+```ruby
+InvoiceExtractorArca::Errors::UnreadableFile
+InvoiceExtractorArca::Errors::QrNotFound
+InvoiceExtractorArca::Errors::MultipleQrFound
+InvoiceExtractorArca::Errors::InvalidVoucherSchema
+InvoiceExtractorArca::Errors::MissingDependency
+InvoiceExtractorArca::Errors::UnsupportedFileType
+```
+
+---
+
+## Configuring QR Scanners
+
+### Default
+
+```ruby
+qr_scanner: :zbar_then_qreader
+```
+
+### Available Options
+
+```ruby
+:zbar
+:qreader
+:zbar_then_qreader
+:qreader_then_zbar
+:all
+```
+
+Example:
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  qr_scanner: :all
+)
+```
+
+---
+
+## Multiple QR Handling
+
+Default:
+
+```ruby
+multiple_qr: :first_valid
+```
+
+Available options:
+
+```ruby
+:first_valid
+:error
+```
+
+Example:
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  multiple_qr: :error
+)
+```
+
+When multiple distinct ARCA payloads are found:
+
+```ruby
+result.success?
+# => false
+
+result.errors
+```
+
+---
+
+## PDF Processing Options
+
+### Specific Page
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  page_range: 3
+)
+```
+
+### Page Range
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  page_range: 1..5
+)
+```
+
+### Non-consecutive Pages
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  page_range: [1, 3, 5]
+)
+```
+
+### Custom Resolution
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  resolution: 400
+)
+```
+
+---
+
+## PDF Text Extraction
+
+Text extraction is enabled by default.
+
+```ruby
+result.text
+```
+
+Example:
+
+```ruby
+{
+  extracted: true,
+  source: "pdftotext",
+  raw: "...",
+  normalized: "..."
+}
+```
+
+Disable text extraction:
+
+```ruby
+InvoiceExtractorArca.extract(
+  "invoice.pdf",
+  enrichment: false
+)
+```
+
+---
+
+## Result Structure
+
+```ruby
+result.to_h
+```
+
+```ruby
+{
+  source: {},
+  qr: {},
+  voucher: {},
+  text: {},
+  enrichment: {},
+  validation: {},
+  errors: [],
+  metadata: {}
+}
+```
+
+---
+
+## Invoice enrichment
+
+When enrichment is enabled, the extractor attempts to identify additional invoice fields from PDF text or image OCR.
+
+Examples include:
+
+- Issuer and recipient information
+- Invoice dates
+- Payment method
+- Subtotal, taxes, and total
+- Authorization code and expiration date
+- Product or service rows
+
+Each extracted field includes metadata such as:
+
+```ruby
+{
+  raw: "611388,00",
+  normalized: "611388.00",
+  source: "pdf_text",
+  method: "label_regex",
+  confidence: "high"
+}
+```
+
+Fields that cannot be identified are returned with a `nil` normalized value and a diagnostic warning.
+
+## QR reconciliation
+
+QR values are treated as the authoritative invoice values. Text and OCR values are compared against selected QR fields.
+
+```ruby
+result.validation
+```
+
+A comparison can have one of these statuses:
+
+- `match`
+- `mismatch`
+- `not_extracted`
+
+A mismatch produces a warning but does not overwrite the QR-derived voucher data.
+
+## Error Handling
+
+Example:
+
+```ruby
+unless result.success?
+  result.errors.each do |error|
+    puts "#{error.code}: #{error.message}"
+  end
+end
+```
+
+---
+
+## Supported ARCA Fields
+
+The gem validates and normalizes:
+
+- ver
+- fecha
+- cuit
+- ptoVta
+- tipoCmp
+- nroCmp
+- importe
+- moneda
+- ctz
+- tipoDocRec
+- nroDocRec
+- tipoCodAut
+- codAut
+
+It also validates against built-in ARCA catalogs for:
+
+- Voucher types
+- Currencies
+- Recipient document types
+
+---
+
+## Command-line interface
+
+The gem installs the `arca-invoice-extract` executable.
+
+### Basic extraction
+
+```bash
+arca-invoice-extract invoice.pdf
+```
+
+The command writes the complete extraction result as JSON to standard output.
+
+### Pretty JSON output
+
+```bash
+arca-invoice-extract --pretty invoice.pdf
+```
+
+### Disable text and OCR enrichment
+
+```bash
+arca-invoice-extract --no-enrichment invoice.pdf
+```
+
+### Strict mode
+
+```bash
+arca-invoice-extract --strict invoice.pdf
+```
+
+Strict mode raises known extraction errors instead of returning them in the result.
+
+### Select one PDF page
+
+```bash
+arca-invoice-extract --page 2 invoice.pdf
+```
+
+### Select a PDF page range
+
+```bash
+arca-invoice-extract --pages 2-5 invoice.pdf
+```
+
+Page numbers must be positive, and the first page must not be greater than the last page.
+
+### Set PDF rendering resolution
+
+```bash
+arca-invoice-extract --resolution 400 invoice.pdf
+```
+
+The default resolution is 300 DPI.
+
+### Select a QR scanner
+
+```bash
+arca-invoice-extract --qr-scanner zbar invoice.pdf
+```
+
+Available values:
+
+- `zbar`
+- `qreader`
+- `zbar_then_qreader`
+- `qreader_then_zbar`
+- `all`
+
+### Handle multiple QR payloads
+
+Use the first valid payload:
+
+```bash
+arca-invoice-extract --multiple-qr first_valid invoice.pdf
+```
+
+Return an extraction failure when multiple distinct payloads are found:
+
+```bash
+arca-invoice-extract --multiple-qr error invoice.pdf
+```
+
+### Configure dependency paths
+
+The option may be repeated:
+
+```bash
+arca-invoice-extract \
+  --dependency pdftoppm=/usr/local/bin/pdftoppm \
+  --dependency pdftotext=/usr/local/bin/pdftotext \
+  --dependency zbarimg=/usr/local/bin/zbarimg \
+  invoice.pdf
+```
+
+### Display help
+
+```bash
+arca-invoice-extract --help
+```
+
+### Exit codes
+
+| Exit code | Meaning |
+|---:|---|
+| `0` | Extraction succeeded |
+| `1` | Extraction failed or a known extraction error was raised |
+| `2` | Invalid command-line arguments |
+| `3` | Runtime or operating-system error |
+
+Extraction results are written to standard output. CLI usage errors and raised exceptions are written to standard error.
+
+## Development
+
+Install dependencies:
+
+```bash
+bin/setup
+```
+
+Run tests:
+
+```bash
+rake test
+```
+
+Run linting:
+
+```bash
+bundle exec standardrb
+```
+
+Run all checks:
+
+```bash
+rake
+```
+
+---
+
+## Roadmap
+
+Planned improvements:
+
+- Broader integration coverage across different ARCA invoice layouts
+- Synthetic and privacy-safe invoice fixtures
+- Improved OCR and table-parsing resilience
+- Expanded RBS type definitions
+
+---
+
+## License
+
+Released under the MIT License.

data/exe/arca-invoice-extract

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "invoice_extractor_arca"
+
+exit InvoiceExtractorArca::CLI.new(ARGV).run

data/lib/invoice_extractor_arca/catalogs/copy_types.json

@@ -0,0 +1,5 @@
+{
+  "01": "ORIGINAL",
+  "02": "DUPLICADO",
+  "03": "TRIPLICADO"
+}