@arela/uploader 1.0.22 → 1.0.24

package/src/document-types/factura-inter-agencia.js

@@ -0,0 +1,186 @@
+// NOTE: We intentionally do NOT import `FieldResult` from
+// '../document-type-shared.js' to avoid a circular-import TDZ when this
+// module is imported directly (e.g. from unit tests). `FieldResult` is a
+// plain data-class with shape `{ name, found, value }`, so we construct
+// equivalent plain objects locally.
+const fieldResult = (name, found, value) => ({ name, found, value });
+
+/**
+ * Factura Inter-Agencia Document Type Definition
+ *
+ * Detects CFDIs (XML or PDF) issued between customs broker agencies (e.g.,
+ * NORCOM ↔ PALCO). These files are dropped into a pedimento folder by the
+ * broker but they are NOT part of the customs electronic file (expediente
+ * aduanal) — they are inter-agency billing for broker services.
+ *
+ * Detection rules (ALL required):
+ *   1) CFDI markers present (either xml structure or PDF text representation)
+ *   2) Both emisor and receptor RFCs belong to the configured agency pair
+ *      (NAA120215F20 = NORCOM, PCC1008161WA = PALCO) in any direction.
+ *   3) At least one concepto with ClaveProdServ 78141502 (Servicios de
+ *      agentes aduaneros) — confirms the billing is for broker services.
+ *
+ * IMPORTANT: This matcher MUST be registered BEFORE `facturasComerciales`
+ * in document-type-shared.js — both would match a CFDI in a pedimento
+ * folder, but inter-agency invoices must take precedence so they are
+ * filtered out of the Arela push pipeline (see arela-api
+ * NON_PUSHABLE_TYPES_SQL).
+ *
+ * Currently scope-limited to NORCOM↔PALCO. To widen, move INTER_AGENCIA_RFCS
+ * to env config and require ≥2 distinct RFCs from the configured list.
+ */
+
+/**
+ * RFCs of agencies whose mutual invoices should be excluded from the Arela
+ * push pipeline. Order is irrelevant — a match is any pair of distinct RFCs
+ * from this set appearing as emisor and receptor.
+ */
+export const INTER_AGENCIA_RFCS = ['NAA120215F20', 'PCC1008161WA'];
+
+const BROKER_SERVICE_CLAVE_PROD_SERV = '78141502';
+
+const CFDI_XML_MARKERS = [
+  /cfdi:Comprobante/i,
+  /xmlns:cfdi/i,
+  /TipoDeComprobante/i,
+];
+
+/**
+ * Detect that the source represents a CFDI — either as the original XML
+ * structure or as text extracted from a printed CFDI (PDF representation).
+ *
+ * PDF text loses XML tags, so we look for the human-readable equivalents
+ * commonly rendered by SAT-style invoice templates ("Folio Fiscal", "Sello
+ * Digital del CFDI", "Cadena Original ... Certificacion Digital del SAT").
+ */
+function isCfdiContent(source) {
+  const xmlHits = CFDI_XML_MARKERS.filter((re) => re.test(source)).length;
+  if (xmlHits >= 2) return true;
+
+  const pdfMarkers = [
+    /folio\s*fiscal/i,
+    /sello\s*digital\s*del\s*cfdi/i,
+    /cadena\s*original.*certificaci[oó]n\s*digital\s*del\s*sat/i,
+    /representaci[oó]n\s*impresa\s*de\s*un\s*cfdi/i,
+  ];
+  return pdfMarkers.filter((re) => re.test(source)).length >= 2;
+}
+
+/**
+ * Return the subset of INTER_AGENCIA_RFCS that appear in `source`. Matching is
+ * case-insensitive and uses word boundaries so substrings inside larger tokens
+ * (cert/sello base64) don't produce false positives.
+ */
+function findInterAgenciaRfcs(source) {
+  const found = new Set();
+  for (const rfc of INTER_AGENCIA_RFCS) {
+    const re = new RegExp(`\\b${rfc}\\b`, 'i');
+    if (re.test(source)) found.add(rfc.toUpperCase());
+  }
+  return [...found];
+}
+
+export const facturaInterAgenciaDefinition = {
+  type: 'factura_inter_agencia',
+  extensions: ['xml', 'pdf'],
+
+  match: (source) => {
+    if (!isCfdiContent(source)) return false;
+
+    // Need ≥2 distinct configured RFCs present (one as emisor, one as receptor)
+    const rfcsFound = findInterAgenciaRfcs(source);
+    if (rfcsFound.length < 2) return false;
+
+    // Confirm the invoice is for broker services (customs agent services)
+    if (!source.includes(BROKER_SERVICE_CLAVE_PROD_SERV)) return false;
+
+    return true;
+  },
+
+  // Pedimento extraction is optional / informational — these files are
+  // excluded from push, so arela_path is never composed. We still extract
+  // a pedimento number when present (from the "Referencias" / "Pedimento:"
+  // section of the printable CFDI) for auditability.
+  extractNumPedimento: (source, fields) => {
+    return fields?.find((f) => f.name === 'numPedimento')?.value ?? null;
+  },
+
+  extractPedimentoYear: (source, fields) => {
+    const numPedimento = fields?.find((f) => f.name === 'numPedimento')?.value;
+    if (numPedimento && numPedimento.length >= 2) {
+      const yy = parseInt(numPedimento.substring(0, 2), 10);
+      if (!isNaN(yy)) return yy < 50 ? yy + 2000 : yy + 1900;
+    }
+    return null;
+  },
+
+  extractors: [
+    {
+      field: 'rfcEmisor',
+      extract: (source) => {
+        // XML form: <cfdi:Emisor Rfc="..." />
+        const xmlMatch = source.match(
+          /<[^>]*Emisor[^>]*Rfc\s*=\s*["']([A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3})["']/i,
+        );
+        if (xmlMatch) return fieldResult('rfcEmisor', true, xmlMatch[1]);
+
+        // PDF form: "Emisor" section followed by RFC label/value on later lines.
+        // We pick the first INTER_AGENCIA RFC that appears in the document.
+        const rfcs = findInterAgenciaRfcs(source);
+        if (rfcs.length > 0) return fieldResult('rfcEmisor', true, rfcs[0]);
+
+        return fieldResult('rfcEmisor', false, null);
+      },
+    },
+    {
+      field: 'rfcReceptor',
+      extract: (source) => {
+        const xmlMatch = source.match(
+          /<[^>]*Receptor[^>]*Rfc\s*=\s*["']([A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3})["']/i,
+        );
+        if (xmlMatch) return fieldResult('rfcReceptor', true, xmlMatch[1]);
+
+        const rfcs = findInterAgenciaRfcs(source);
+        if (rfcs.length >= 2) {
+          return fieldResult('rfcReceptor', true, rfcs[1]);
+        }
+        return fieldResult('rfcReceptor', false, null);
+      },
+    },
+    {
+      field: 'folio',
+      extract: (source) => {
+        // CFDI Folio attribute
+        const xmlMatch = source.match(/\bFolio\s*=\s*["']([A-Z0-9-]+)["']/i);
+        if (xmlMatch) return fieldResult('folio', true, xmlMatch[1]);
+
+        // PDF: "Numero Folio    012749"
+        const pdfMatch = source.match(/Numero\s+Folio\s+([A-Z0-9-]+)/i);
+        if (pdfMatch) return fieldResult('folio', true, pdfMatch[1]);
+
+        return fieldResult('folio', false, null);
+      },
+    },
+    {
+      field: 'uuid',
+      extract: (source) => {
+        const uuidRe =
+          /[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}/i;
+        const m = source.match(uuidRe);
+        return fieldResult('uuid', !!m, m ? m[0].toUpperCase() : null);
+      },
+    },
+    {
+      field: 'numPedimento',
+      extract: (source) => {
+        // Printable CFDI "Pedimento: 3458 6000046 Fecha: ..." — recovers an
+        // 11-digit pedimento (no YY prefix). Useful for auditability only.
+        const m = source.match(/Pedimento:?\s*(\d{4})\s*(\d{7})/i);
+        if (m) {
+          return fieldResult('numPedimento', true, `${m[1]}${m[2]}`);
+        }
+        return fieldResult('numPedimento', false, null);
+      },
+    },
+  ],
+};

package/src/document-types/pedimento-completo-xml.js

@@ -1,10 +1,8 @@
 // VUCEM "consultarPedimentoCompleto" XML matcher.
 //
-// STATUS: implemented but NOT registered in `document-type-shared.js`. To
-// activate, uncomment the import + registration in that file. All downstream
-// code (composeArelaPath, arela-api propagation SQL, IdentifyCommand
-// counters) already includes `pedimento_completo_xml`, so re-enabling is a
-// single-line change.
+// Registered in `document-type-shared.js`. Downstream code
+// (composeArelaPath, arela-api propagation SQL, IdentifyCommand counters)
+// also includes `pedimento_completo_xml`.
 //
 // Filename patterns recognized (try in order — patente extraction):
 //   1) VU_PATENTE_ADUANA_PEDIMENTO.xml          → e.g. VU_3429_070_5016101.xml
@@ -47,6 +45,22 @@ function pad(value, length) {
   return String(value).padStart(length, '0');
 }
 
+/**
+ * Convert a VUCEM `aduanaEntradaSalida.clave` (e.g. "70", "750", "40") to the
+ * 2-digit "sección aduanera" prefix used inside the 15-digit pedimento number.
+ *
+ *   VUCEM strips leading zeros from the canonical 3-digit SAT aduana code,
+ *   so `070` (Ciudad Juárez) arrives as `70`. The pedimento prefix is the
+ *   first 2 digits of the 3-digit code:
+ *     `70`  → `070` → `07`   (Cd. Juárez)
+ *     `750` → `750` → `75`   (Puebla)
+ *     `40`  → `040` → `04`   (Lázaro Cárdenas)
+ */
+function aduanaToSeccion(claveValue) {
+  if (claveValue == null) return null;
+  return pad(claveValue, 3).substring(0, 2);
+}
+
 /**
  * Try the three known filename patterns and return {patente, aduana, pedimento}
  * with any subset of the fields populated. Returns null if no pattern matches.
@@ -102,12 +116,17 @@ function yyFromIsoDate(iso) {
   return m ? m[1].substring(2, 4) : null;
 }
 
-// Find <ns2:fechas> block with nested clave==2 and return its <ns2:fecha>.
-function findPaymentDate(source) {
+// Find <ns2:fechas> block whose nested <clave> matches `claveValue` and
+// return its <ns2:fecha>. Works for both shapes:
+//   <fechas><clave>N</clave><fecha>...</fecha></fechas>
+//   <fechas><fecha>...</fecha><tipo><clave>N</clave></tipo></fechas>
+// (firstTag finds the FIRST <clave> in the block — both layouts expose only
+//  one clave per fechas entry.)
+function findFechaByClave(source, claveValue) {
   const fechasBlocks = allTagBlocks(source, 'fechas');
   for (const block of fechasBlocks) {
     const clave = firstTag(block, 'clave');
-    if (clave === '2') {
+    if (clave === claveValue) {
       const fecha = firstTag(block, 'fecha');
       if (fecha) return fecha;
     }
@@ -115,6 +134,18 @@ function findPaymentDate(source) {
   return null;
 }
 
+// Fecha de pago de las contribuciones (tipo.clave == 2).
+function findPaymentDate(source) {
+  return findFechaByClave(source, '2');
+}
+
+// Fecha de presentacion (tipo.clave == 5). This is the authoritative source
+// for the pedimento's YY prefix — a pedimento opened in Dec-2025 but paid in
+// Jan-2026 keeps the `25` prefix, matching what VUCEM stamps in the filename.
+function findPresentationDate(source) {
+  return findFechaByClave(source, '5');
+}
+
 // --------------------------- extractors ------------------------------------
 
 const rfcExtractor = {
@@ -152,7 +183,7 @@ const aduanaEntradaSalidaExtractor = {
     return new FieldResult(
       'aduanaEntradaSalida',
       !!clave,
-      clave ? pad(clave, 2) : null,
+      aduanaToSeccion(clave),
     );
   },
 };
@@ -165,6 +196,14 @@ const paymentDateExtractor = {
   },
 };
 
+const presentationDateExtractor = {
+  field: 'presentationDate',
+  extract: (source) => {
+    const fecha = findPresentationDate(source);
+    return new FieldResult('presentationDate', !!fecha, fecha);
+  },
+};
+
 const fechaPagoRectificacionExtractor = {
   field: 'fechaPagoRectificacion',
   extract: (source) => {
@@ -257,8 +296,14 @@ export const pedimentoCompletoXmlDefinition = {
 
   /**
    * Compose the 15-digit pedimento number from XML body + filename.
-   *   YY: from rectification fechaPago if present, else from the clave==2
-   *       payment-date fecha; falls back to filename pattern 3.
+   *   YY: priority order (most authoritative first):
+   *     1) Filename pattern 3 (`{15-digit}.xml`) — VUCEM stamps the correct
+   *        prefix at export time.
+   *     2) Fecha de presentacion (<fechas><clave>5) — the year the pedimento
+   *        was opened. Authoritative for the YY prefix even when payment
+   *        crosses calendar year (e.g. opened Dec-2025, paid Jan-2026 → YY=25).
+   *     3) Rectification fechaPago (only when no presentation date exists).
+   *     4) Payment date (last-resort fallback).
    *   AA: from <aduanaEntradaSalida><clave> padded to 2.
    *   PPPP: from the filename (any of the three patterns).
    *   NNNNNNN: from <pedimento> padded to 7.
@@ -267,15 +312,19 @@ export const pedimentoCompletoXmlDefinition = {
   extractNumPedimento: (source, fields, filePath) => {
     const parts = parseFilenameParts(filePath);
 
+    const presentation = fields?.find(
+      (f) => f.name === 'presentationDate' && f.found,
+    )?.value;
     const rect = fields?.find(
       (f) => f.name === 'fechaPagoRectificacion' && f.found,
     )?.value;
     const pay = fields?.find((f) => f.name === 'paymentDate' && f.found)?.value;
 
     let yy =
+      (parts && parts.year) ||
+      yyFromIsoDate(presentation) ||
       yyFromIsoDate(rect) ||
       yyFromIsoDate(pay) ||
-      (parts && parts.year) ||
       null;
 
     const aduanaField = fields?.find(
@@ -315,6 +364,7 @@ export const pedimentoCompletoXmlDefinition = {
     tipoOperacionExtractor,
     aduanaEntradaSalidaExtractor,
     paymentDateExtractor,
+    presentationDateExtractor,
     fechaPagoRectificacionExtractor,
     coveExtractor,
     numEDocumentoExtractor,

package/src/document-types/pedimento-completo.js

@@ -17,17 +17,19 @@ export const pedimentoCompletoDefinition = {
   type: 'pedimento_completo',
   extensions: ['pdf'],
   match: (source) => {
-    // Hard exclude: "FORMA SIMPLIFICADA" is handled by pedimento_simplificado.
-    if (/FORMA SIMPLIFICADA DE PEDIMENTO/i.test(source)) return false;
+    // Hard exclude: "FORMA SIMPLIFICADA [DE|DEL] PEDIMENTO" is handled by
+    // pedimento_simplificado.
+    if (/FORMA\s+SIMPLIFICADA\s+DEL?\s+PEDIMENTO/i.test(source)) return false;
 
     // Hard exclude: "AVISO CONSOLIDADO" shares the header trio but is a
     // different document type handled by aviso_consolidado.
     if (/AVISO\s+CONSOLIDADO/i.test(source)) return false;
 
+    // The colon after "T. OPER" is optional — see note in pedimento-simplificado.js.
     const hasHeaderFields =
       /NUM\.?\s*PEDIMENTO:/i.test(source) &&
       /CVE\.?\s*PEDIMENTO:/i.test(source) &&
-      /T\.?\s*OPER:/i.test(source);
+      /T\.?\s*OPER:?/i.test(source);
     if (hasHeaderFields) {
       const hasCopyMarker =
         /ORIGINAL:\s*ADMINISTRACION GENERAL DE ADUANAS/i.test(source) ||

package/src/document-types/pedimento-simplificado.js

@@ -12,15 +12,18 @@ export const pedimentoSimplificadoDefinition = {
     if (/AVISO\s+CONSOLIDADO/i.test(source)) return false;
 
     // Fast path: the literal title appears on standard SIMP layouts.
-    if (/FORMA SIMPLIFICADA DE PEDIMENTO/i.test(source)) return true;
+    // Some prevalidators print "FORMA SIMPLIFICADA DEL PEDIMENTO" (with DEL).
+    if (/FORMA\s+SIMPLIFICADA\s+DEL?\s+PEDIMENTO/i.test(source)) return true;
 
     // Some PDFs (single-page anchors) lack that title but still carry the
     // three pedimento header fields. Treat them as simplificado UNLESS they
     // have the multi-page copy markers that uniquely identify a completo.
+    // NOTE: the colon after "T. OPER" is optional — many printable layouts
+    // render OPER as a table-header label with the value in the next cell.
     const hasHeaderFields =
       /NUM\.?\s*PEDIMENTO:/i.test(source) &&
       /CVE\.?\s*PEDIMENTO:/i.test(source) &&
-      /T\.?\s*OPER:/i.test(source);
+      /T\.?\s*OPER:?/i.test(source);
     if (!hasHeaderFields) return false;
 
     const hasCompletoCopyMarker =

package/src/document-types/proforma.js

@@ -16,9 +16,9 @@ export const proformaDefinition = {
   type: 'proforma',
   extensions: ['pdf'],
 
-  // Same content marker as pedimento simplificado
+  // Same content marker as pedimento simplificado (accepts "DE" or "DEL").
   match: (source) => {
-    return /FORMA SIMPLIFICADA DE PEDIMENTO/i.test(source);
+    return /FORMA\s+SIMPLIFICADA\s+DEL?\s+PEDIMENTO/i.test(source);
   },
 
   extractNumPedimento: pedimentoSimplificadoDefinition.extractNumPedimento,

package/src/file-detection.js

@@ -3,10 +3,9 @@ import path from 'path';
 import { PDFParse } from 'pdf-parse';
 
 import { extractDocumentFields } from './document-type-shared.js';
+import { classifyDocument } from './scoring/scoring-engine.js';
 
-// Document types that participate in arela_path composition. The XML type is
-// kept here even though its matcher is currently disabled — once re-enabled
-// in document-type-shared.js no further changes are needed here.
+// Document types that participate in arela_path composition.
 const ARELA_PATH_TYPES = new Set([
   'pedimento_simplificado',
   'pedimento_completo',
@@ -86,6 +85,17 @@ function composeArelaPath(
  * Detects document types and extracts metadata from files
  */
 export class FileDetectionService {
+  constructor() {
+    // Best-match matchers (adapted from the API). When set, classification uses
+    // the scoring engine; otherwise it falls back to legacy first-match-wins.
+    this.matchers = null;
+  }
+
+  /** Provide the resolved+adapted matcher set for scoring-based classification. */
+  setMatchers(matchers) {
+    this.matchers = matchers && matchers.length ? matchers : null;
+  }
+
   /**
    * Detect document type from a file
    * @param {string} filePath - Path to the file to analyze
@@ -142,9 +152,23 @@ export class FileDetectionService {
         };
       }
 
-      // Extract document fields and detect type
-      const [detectedType, fields, detectedPedimento, detectedPedimentoYear] =
-        extractDocumentFields(text, fileExtension, filePath);
+      // Extract document fields and detect type. Use the best-match scoring
+      // engine when matchers are configured; otherwise legacy first-match-wins.
+      let detectedType, fields, detectedPedimento, detectedPedimentoYear;
+      if (this.matchers) {
+        const r = classifyDocument(this.matchers, {
+          source: text,
+          extension: fileExtension,
+          filePath,
+        });
+        detectedType = r.detectedType;
+        fields = r.fields;
+        detectedPedimento = r.detectedPedimento;
+        detectedPedimentoYear = r.detectedPedimentoYear;
+      } else {
+        [detectedType, fields, detectedPedimento, detectedPedimentoYear] =
+          extractDocumentFields(text, fileExtension, filePath);
+      }
 
       // Extract RFC from fields
       const rfc = fields?.find((f) => f.name === 'rfc')?.value ?? null;

package/src/scoring/db-matcher-adapter.js

@@ -0,0 +1,98 @@
+/**
+ * Adapt DB matchers (from arela-api `GET /document-matcher/resolved`) into the
+ * shape the scoring engine consumes — the HYBRID model:
+ *
+ *   - SELECTION comes from the DB matcher's clues / qualify (per-RFC + globals).
+ *   - EXTRACTION uses the rich JS extractors keyed by `documentType` when one
+ *     exists (resolveType, multi-pattern field extractors, pedimento composition);
+ *     otherwise it falls back to building simple regex extractors from the DB
+ *     matcher's `fieldExtractors`.
+ *
+ * This keeps per-client matching configurable from the UI while preserving the
+ * robust field extraction that already ships in the uploader.
+ */
+// IMPORTANT: load document-type-shared FIRST so it becomes the root of the
+// shared<->definitions import cycle and fully evaluates before the individual
+// definitions are referenced (otherwise: "Cannot access X before initialization").
+import { FieldResult } from '../document-type-shared.js';
+import { dodaPdfDefinition } from '../document-types/doda-pdf.js';
+import { dodaXmlDefinition } from '../document-types/doda-xml.js';
+import { facturaInterAgenciaDefinition } from '../document-types/factura-inter-agencia.js';
+import { facturasComerciales } from '../document-types/facturas-comerciales.js';
+import { pedimentoCompletoXmlDefinition } from '../document-types/pedimento-completo-xml.js';
+import { pedimentoCompletoDefinition } from '../document-types/pedimento-completo.js';
+import { pedimentoSimplificadoDefinition } from '../document-types/pedimento-simplificado.js';
+import { supportDocumentDefinition } from '../document-types/support-document.js';
+
+// documentType -> rich extraction half of the JS definition.
+function extractionOf(def) {
+  return {
+    extractors: def.extractors,
+    resolveType: def.resolveType,
+    extractNumPedimento: def.extractNumPedimento,
+    extractPedimentoYear: def.extractPedimentoYear,
+  };
+}
+
+const EXTRACTION_REGISTRY = {
+  pedimento_simplificado: extractionOf(pedimentoSimplificadoDefinition),
+  pedimento_completo: extractionOf(pedimentoCompletoDefinition),
+  pedimento_completo_xml: extractionOf(pedimentoCompletoXmlDefinition),
+  doda_pdf: extractionOf(dodaPdfDefinition),
+  doda_xml: extractionOf(dodaXmlDefinition),
+  factura_inter_agencia: extractionOf(facturaInterAgenciaDefinition),
+  factura_comercial: extractionOf(facturasComerciales),
+  support_document: extractionOf(supportDocumentDefinition),
+};
+
+// Build a scoring-engine extractor from a DB fieldExtractor (regex + capture).
+function regexExtractor(fe) {
+  return {
+    field: fe.field,
+    extract: (source) => {
+      try {
+        const m = source.match(new RegExp(fe.extractor, fe.flags || ''));
+        return new FieldResult(fe.field, !!m, m ? (m[1] ?? m[0]) : null);
+      } catch {
+        return new FieldResult(fe.field, false, null);
+      }
+    },
+  };
+}
+
+/**
+ * Convert resolved DB matchers into scoring-engine matchers.
+ * @param {Array} dbMatchers - matchers from the API (with clues + fieldExtractors)
+ * @returns {Array} scoring matchers
+ */
+export function adaptDbMatchers(dbMatchers) {
+  return (dbMatchers || []).map((m) => {
+    const rich = EXTRACTION_REGISTRY[m.documentType];
+    const extraction = rich
+      ? rich
+      : { extractors: (m.fieldExtractors || []).map(regexExtractor) };
+
+    return {
+      documentType: m.documentType,
+      extensions: Array.isArray(m.extensions)
+        ? m.extensions
+        : String(m.extensions || '')
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+      minScore: m.minScore ?? undefined,
+      priority: m.priority ?? 0,
+      qualify: m.qualify ?? undefined,
+      clues: (m.clues || []).map((c) => ({
+        kind: c.kind,
+        pattern: c.pattern,
+        flags: c.flags || undefined,
+        weight: c.weight ?? 1,
+        group: c.group || undefined,
+        required: !!c.required,
+        negative: !!c.negative,
+      })),
+      ...extraction,
+    };
+  });
+}