Merge branch 'main' into feature/centralized-error-handling-complete

Author: Cedarich

ai-connector/mcp-browser-openai-4o-v1/hetzner/hetzner.json

@@ -2,19 +2,19 @@
   "meta": {
     "schemaVersion": "1.0.0",
     "mcpVersion": "mcp-browser-openai-4o-v1",
-    "created_at": "2025-07-10T14:38:10.890Z",
-    "updated_at": "2025-07-10T14:38:10.890Z",
+    "created_at": "2025-07-28T14:16:50.069Z",
+    "updated_at": "2025-07-28T14:16:50.069Z",
     "country": [
-      "US"
+      "FR"
     ]
   },
   "data": {
     "type": "blueprint",
-    "id": "b130ac18-04b5-4185-ad5f-e907b1f457b4",
+    "id": "09ba0c9a-30b7-4237-b91c-b206a10797cb",
     "attributes": {
       "encrypted": {
         "iv": "69f316062bacbd3d45415bb1eaff8c5e",
-        "content": "57c535501c3be97b250bde2d3947af4295bd1b4467528bd62e72a640aa41cdba7f34a033e83fc89e2b1a3365b41a29c1b2e193bd8f3f2ba303a63bfcba5fd10a99538f2ac0934499f76886cb9ef879d57dc547a2613c0a9fb972e289a7c29f0d4f05338ed400f1466e332526f31dcba2493f943a49e7b9f4c202dced51d906d77813a3f7c25d2eb7aa0abc018a349e2f9a6360b7ea82e3314021e822e66c0a4c51e11825dc548b80da2b270b48fa33c712ce0d1d5d312590df67380fa9d1e50d03f358fd3144ee98181d12e2e7472f9d9d13bbd319d6f85c54daaf69cf67c72271b3635e026ed546e750b4d725606a4f087ec0277115e38c0060d9f8317385622f7fa3535b57771938331f3e2263cb01298c2a904ad6b90df81e4d967b3d8fd33585dbfab961e9763be48b45968f6cacc37983f86d7cc30c5722381ed12dfb53db3ffc28ef7bb266ef7904b13936183074d4304b5244d7f8bc3f21ea56e1595515a547a7f38dc85420629a836dbc417b9cf3563ffe1e10f42075d8b76a5aec2d08f97f9c8035d8d1d533f26597f162c8d972a3df5c71440b487a5912392bc8678892c4f43124c9dac7c1e65c8840470594b8ca1942707e3299624e2bcbaa3fddd2e44e39a8dd278f7815b49bac059efdff07e9798925fd2a46be4583d403c352839ea3865a9428eda5b6134550e718df"
+        "content": "57c535501c3be97b250bde2d3947af4295bd1b4467528bd62e72a640aa41cdba7f34a033e83fc89e2b1a3365b41a29c13e9de923173360a4e69cf7c9924544b88f629ea5de8d6ffb8bfbed56b923d35a245600d92140186016fc62b132265e565fe50c0efc69af92e29bb7cefb7c4b7fd95f44e4cf0a240963d6296483f2eaeb6126a8d55b2e37c460c95bfcadfcf1a078c9c968dcc8d774cce373ea75b77a5e939a6b73d7435b1a302c6f708a9c537077f28bf45b037a8df0fb0a96ef5036bfc22d8193206291768d8f38b1d0ddae23d4c74cb300b00576a1ed78d159f6ce9dd906937a4b6adc6016cc99ca3bd31ec6766d2b9dae7bf5b8a51976ba07fa0de4c5a0070e71f63f8de1e4ee4b975eaa77237d076621d2c18af4cfab08c2c981ca"
       }
     }
   }

ai-invoice-extractor/README.md

@@ -26,9 +26,12 @@
 
 - 🔍 Extract invoice/receipt data
 - 🧠 Choose your AI models (OpenAI, Mistral, Anthropic, Google Gemini, and Ollama)
+- 🇮🇹 **Full FatturaPA support** for Italian e-invoicing (TD01, TD17-TD19)
 - 🔧 Set AI keys with CLI and environment variables
 - ⭐ Pretty print the output
 - 🔄 Pipe output with other CLI
+- 📄 Export to XML/JSON formats
+- 🏛️ Public Administration support (CIG/CUP codes)
 
 ## Usage
 
@@ -117,6 +120,23 @@ export EXTRACTOR_API_KEY=sk-your-openai-key
 npx ai-invoice-extractor invoice.pdf
 ```
 
+#### FatturaPA (Italian E-Invoicing)
+```sh
+# Extract FatturaPA data with full Italian e-invoicing support
+npx ai-invoice-extractor -k sk-key -p fattura.pdf
+
+# Export to FatturaPA XML format
+npx ai-invoice-extractor -k sk-key fattura.pdf | node -e "
+  const { FatturapaXmlExporter } = require('./dist/exporters');
+  const exporter = new FatturapaXmlExporter();
+  const data = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+  console.log(exporter.export(data));
+"
+
+# Extract cross-border invoice (TD18)
+npx ai-invoice-extractor -k sk-key crossborder-invoice.pdf
+```
+
 #### Different AI Vendors
 ```sh
 # Mistral AI
@@ -171,6 +191,236 @@ The CLI provides helpful error messages for common issues:
 - **Documents:** PDF
 - **File size:** Up to 20MB (varies by AI provider)
 
+## FatturaPA (Italian E-Invoicing) Support
+
+The AI Invoice Extractor provides comprehensive support for FatturaPA, the Italian electronic invoicing standard mandated by the Agenzia delle Entrate (Italian Revenue Agency).
+
+### Supported Document Types
+
+| Code | Description | Support |
+|------|-------------|---------|
+| **TD01** | Domestic invoice | ✅ Full support |
+| **TD17** | Domestic reverse charge integration | ✅ Full support |
+| **TD18** | Intra-EU purchase integration | ✅ Full support |
+| **TD19** | Extra-EU purchase integration | ✅ Full support |
+| **TD20-27** | Specialized invoice types | ✅ Basic support |
+
+### Key Features
+
+- **🏢 Complete Party Data:** Italian VAT IDs, Codice Fiscale, REA registration, PEC addresses
+- **🌍 Cross-Border Support:** Foreign VAT IDs, tax representatives, currency conversion
+- **💰 Tax Compliance:** All Italian VAT rates, nature codes (N1-N7), withholding taxes
+- **🏛️ Public Administration:** CIG/CUP codes, office codes, administrative references  
+- **📋 Line Items:** Product codes, service periods, discounts, custom information
+- **💳 Payment Terms:** All Italian payment methods (MP01-MP22), IBAN/BIC, installments
+- **📎 References:** Order numbers, contracts, transport documents
+- **🔧 Export Formats:** SDI-compliant XML, structured JSON, validation format
+
+### Extracted Fields
+
+The extractor captures **300+ fields** including:
+
+#### Document Header
+- Document type code (TD01, TD17-TD19, etc.)
+- Invoice number, issue date, due date
+- Currency code and exchange rates (for cross-border)
+- Transmission format and country codes
+
+#### Party Information (Supplier & Customer)
+- Legal name and form
+- Italian VAT ID (`IT` + 11 digits) and Tax ID (Codice Fiscale)
+- Foreign VAT IDs for cross-border transactions  
+- Complete addresses with Italian province codes
+- Contact information (phone, email, PEC)
+- REA registration details (office, number, share capital)
+- Tax representative information (for foreign suppliers)
+
+#### Tax Details
+- Multiple VAT rates and amounts
+- Nature codes for exemptions (N1-N7 with descriptions)
+- Withholding taxes (RT01, RT02 types)
+- Administrative references for PA invoices
+
+#### Line Items
+- Descriptions, quantities, unit prices, totals
+- Discounts and markups (percentage and amount)
+- VAT rates per line item
+- Product codes (EAN, internal, etc.)
+- Service periods (start/end dates)
+- Cross-border customs information
+
+#### Payment Information
+- Payment conditions (TP01-TP03)
+- Payment methods (MP01-MP22)
+- Bank details (IBAN, BIC, bank name)
+- Installment schedules
+- Early payment discounts and late penalties
+
+#### References & Additional Data
+- CIG (tender codes) and CUP (project codes) for PA
+- Order numbers and contract references
+- Transport and delivery information
+- Digital signature details
+- Attachments and notes
+
+### Usage Examples
+
+#### Basic FatturaPA Extraction
+```sh
+# Extract Italian domestic invoice
+npx ai-invoice-extractor -k sk-key fattura-domestica.pdf
+
+# Extract cross-border invoice (German supplier to Italian customer)
+npx ai-invoice-extractor -k sk-key fattura-crossborder.pdf
+
+# Extract with pretty formatting
+npx ai-invoice-extractor -k sk-key -p fattura.pdf
+```
+
+#### Programmatic Usage
+```javascript
+import { Extractor } from 'ai-invoice-extractor';
+import { FatturapaXmlExporter, FatturapaJsonExporter } from 'ai-invoice-extractor/exporters';
+
+// Extract invoice data
+const extractor = Extractor.create({
+  vendor: 'openai',
+  model: 'gpt-4o',
+  apiKey: 'sk-your-key'
+});
+
+const invoiceData = await extractor.analyseFile({
+  path: 'fattura.pdf',
+  prompt: 'EXTRACT_INVOICE_FATTURAPA',
+  output: fatturapaInvoiceSchema
+});
+
+// Export to XML (SDI-compliant)
+const xmlExporter = new FatturapaXmlExporter({
+  formatOutput: true,
+  validateRequired: true
+});
+const xml = xmlExporter.export(invoiceData);
+
+// Export to JSON (structured)
+const jsonExporter = new FatturapaJsonExporter({
+  includeMetadata: true,
+  cleanNullValues: true
+});
+const json = jsonExporter.export(invoiceData);
+
+// Export for validation
+const validationJson = jsonExporter.exportForValidation(invoiceData);
+```
+
+#### XML Output Sample
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ns2:FatturaElettronica versione="FPR12" xmlns:ns2="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2">
+  <FatturaElettronicaHeader>
+    <DatiTrasmissione>
+      <IdTrasmittente>
+        <IdPaese>IT</IdPaese>
+        <IdCodice>12345678901</IdCodice>
+      </IdTrasmittente>
+      <FormatoTrasmissione>FPR12</FormatoTrasmissione>
+    </DatiTrasmissione>
+    <CedentePrestatore>
+      <DatiAnagrafici>
+        <IdFiscaleIVA>
+          <IdPaese>IT</IdPaese>
+          <IdCodice>IT12345678901</IdCodice>
+        </IdFiscaleIVA>
+        <Anagrafica>
+          <Denominazione>Tech Solutions S.r.l.</Denominazione>
+        </Anagrafica>
+      </DatiAnagrafici>
+    </CedentePrestatore>
+  </FatturaElettronicaHeader>
+  <FatturaElettronicaBody>
+    <DatiGenerali>
+      <DatiGeneraliDocumento>
+        <TipoDocumento>TD01</TipoDocumento>
+        <Divisa>EUR</Divisa>
+        <Data>2024-03-15</Data>
+        <Numero>INV-2024-001</Numero>
+      </DatiGeneraliDocumento>
+    </DatiGenerali>
+    <!-- ... more XML content ... -->
+  </FatturaElettronicaBody>
+</ns2:FatturaElettronica>
+```
+
+#### JSON Output Sample
+```json
+{
+  "header": {
+    "transmission": {
+      "sender_country": "IT",
+      "sender_code": "IT12345678901",
+      "format": "FPR12"
+    },
+    "supplier": {
+      "identification": {
+        "vat_id": "IT12345678901",
+        "tax_id": "12345678901"
+      },
+      "legal_info": {
+        "name": "Tech Solutions S.r.l."
+      },
+      "address": {
+        "street": "Via Roma",
+        "city": "Milano",
+        "postal_code": "20121",
+        "province": "MI",
+        "country": "IT"
+      }
+    }
+  },
+  "body": {
+    "general_data": {
+      "document_type": "TD01",
+      "currency": { "code": "EUR" },
+      "date": "2024-03-15",
+      "number": "INV-2024-001",
+      "totals": {
+        "taxable_amount": 1000.00,
+        "vat_amount": 220.00,
+        "total_amount": 1220.00
+      }
+    },
+    "line_items": [
+      {
+        "line_number": 1,
+        "description": "Servizi di consulenza IT",
+        "quantity": 1,
+        "unit_price": 1000.00,
+        "total_price": 1000.00,
+        "vat": {
+          "rate": 22.00,
+          "amount": 220.00
+        }
+      }
+    ]
+  }
+}
+```
+
+### Validation & Compliance
+
+The XML exporter generates output that is:
+- ✅ **SDI Compliant:** Validates against Italian Sistema di Interscambio
+- ✅ **Schema Valid:** Follows FatturaPA XSD 1.2.1 specification  
+- ✅ **Tax Authority Ready:** Can be submitted directly to Agenzia delle Entrate
+- ✅ **Cross-Border Ready:** Handles TD17-TD19 scenarios correctly
+
+### Examples & Testing
+
+The repository includes comprehensive examples:
+- `examples/fatturapa/domestic-invoice-sample.json` - Italian domestic invoice (TD01)
+- `examples/fatturapa/crossborder-invoice-sample.json` - Cross-border invoice (TD18)
+- Complete test suite with 15+ scenarios covering all document types
+
 ## Contributing 
 
 We use [Bun](https://bun.sh/) instead of npm:

ai-invoice-extractor/examples/fatturapa/README.md

@@ -0,0 +1,26 @@
+# FatturaPA Examples
+
+This directory contains sample invoices in various formats demonstrating FatturaPA support:
+
+## Domestic Invoices (TD01)
+- `domestic-invoice-sample.json` - Sample Italian domestic invoice
+- `domestic-invoice-golden.xml` - Expected XML output
+- `domestic-invoice-golden.json` - Expected JSON output
+
+## Cross-Border Invoices (TD17-TD19)
+- `crossborder-invoice-sample.json` - Sample cross-border invoice
+- `crossborder-invoice-golden.xml` - Expected XML output  
+- `crossborder-invoice-golden.json` - Expected JSON output
+
+## Public Administration
+- `pa-invoice-sample.json` - Sample PA invoice with CIG/CUP codes
+- `pa-invoice-golden.xml` - Expected XML output
+- `pa-invoice-golden.json` - Expected JSON output
+
+## Usage
+
+These examples can be used for:
+- Testing the FatturaPA extraction and export functionality
+- Validating output against Italian SDI requirements
+- Understanding the complete FatturaPA data structure
+- Development and integration testing