@arela/uploader 1.0.21 → 1.0.23

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

@@ -7,7 +7,39 @@ export const pedimentoSimplificadoDefinition = {
   type: 'pedimento_simplificado',
   extensions: ['pdf'],
   match: (source) => {
-    return /FORMA SIMPLIFICADA DE PEDIMENTO/i.test(source);
+    // 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;
+
+    // Fast path: the literal title appears on standard SIMP layouts.
+    // 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);
+    if (!hasHeaderFields) return false;
+
+    const hasCompletoCopyMarker =
+      /ORIGINAL:\s*ADMINISTRACION GENERAL DE ADUANAS/i.test(source) ||
+      /SEGUNDA\s+COPIA/i.test(source) ||
+      /TERCERA\s+COPIA/i.test(source) ||
+      /COPIA\s+(SIMPLIFICAD[AO])?\s*TRANSPORTISTA/i.test(source) ||
+      /ANEXO\s+DEL\s+PEDIMENTO/i.test(source) ||
+      /\*+FIN\s+DE\s+PEDIMENTO\s*\*+/i.test(source);
+    if (hasCompletoCopyMarker) return false;
+
+    // Exclude COVE/eDocument forms that may reference a pedimento in their body.
+    if (/COMPROBANTE\s+DE\s+VALOR\s+ELECTR[ÓO]NICO/i.test(source)) return false;
+    if (/\bCOVE\b\s*:/i.test(source) && !/PAGO/i.test(source)) return false;
+
+    return true;
   },
 
   /**

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

@@ -4,9 +4,7 @@ import { PDFParse } from 'pdf-parse';
 
 import { extractDocumentFields } from './document-type-shared.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',

package/src/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 
+import datastageCommand from './commands/DatastageCommand.js';
 import gdriveSyncCommand from './commands/GDriveSyncCommand.js';
 import identifyCommand from './commands/IdentifyCommand.js';
 import pollWorkerCommand from './commands/PollWorkerCommand.js';
@@ -26,6 +27,7 @@ class ArelaUploaderCLI {
     this.scanCommand = scanCommand;
     this.uploadCommand = new UploadCommand();
     this.watchCommand = watchCommand;
+    this.datastageCommand = datastageCommand;
 
     this.#setupProgram();
     this.#setupCommands();
@@ -204,6 +206,34 @@ class ArelaUploaderCLI {
         }
       });
 
+    // Datastage command — upload monthly datastage *.zip files from a directory
+    this.program
+      .command('datastage')
+      .description(
+        '📦 Upload monthly datastage *.zip files from a directory to Arela',
+      )
+      .requiredOption(
+        '--dir <path>',
+        'Directory containing *.zip files (non-recursive)',
+      )
+      .option(
+        '--api <target>',
+        'API target: default|agencia|cliente',
+        'default',
+      )
+      .option('--retry-failed', 'Re-attempt files in failed status')
+      .option('--show-stats', 'Print final stats summary')
+      .action(async (options) => {
+        try {
+          if (options.api && options.api !== 'default') {
+            appConfig.setApiTarget(options.api);
+          }
+          await this.datastageCommand.execute(options);
+        } catch (error) {
+          this.errorHandler.handleFatalError(error, { command: 'datastage' });
+        }
+      });
+
     // Detection command
     this.program
       .command('detect')
@@ -335,6 +365,18 @@ class ArelaUploaderCLI {
         'Number of files to process in each batch',
         '100',
       )
+      .option(
+        '--table <tableName>',
+        'Process only this scan table (instead of all instance tables)',
+      )
+      .option(
+        '--reset-attempts',
+        'Reset detection_attempts to 0 before processing so previously-failed files are retried',
+      )
+      .option(
+        '--path-prefix <mapping>',
+        'Remap file path prefix for cross-platform access. Format: FROM:TO  e.g. "O:/=/Volumes/nas/"',
+      )
       .option('--show-stats', 'Show performance statistics')
       .action(async (options) => {
         try {

package/src/services/DatastageApiService.js

@@ -0,0 +1,240 @@
+import FormData from 'form-data';
+import fs from 'fs';
+import { Agent } from 'http';
+import { Agent as HttpsAgent } from 'https';
+import fetch from 'node-fetch';
+import path from 'path';
+
+import appConfig from '../config/config.js';
+import logger from './LoggingService.js';
+
+/**
+ * Datastage API Service
+ * Handles API communication for the arela datastage command:
+ *  - tracking endpoints under /api/uploader/datastage/*
+ *  - zip upload endpoint POST /api/datastage (multipart, field: zipFile)
+ */
+export class DatastageApiService {
+  /**
+   * @param {string|null} apiTarget - 'default'|'agencia'|'cliente'
+   */
+  constructor(apiTarget = null) {
+    this.apiTarget = apiTarget;
+    const apiConfig = appConfig.getApiConfig(apiTarget);
+    this.baseUrl = apiConfig.baseUrl;
+    this.token = apiConfig.token;
+
+    const maxApiConnections = parseInt(process.env.MAX_API_CONNECTIONS) || 10;
+    const connectionTimeout =
+      parseInt(process.env.API_CONNECTION_TIMEOUT) || 300000;
+
+    this.maxRetries = parseInt(process.env.API_MAX_RETRIES) || 3;
+    this.useExponentialBackoff =
+      process.env.API_RETRY_EXPONENTIAL_BACKOFF !== 'false';
+    this.fixedRetryDelay = parseInt(process.env.API_RETRY_DELAY) || 1000;
+
+    const agentOpts = {
+      keepAlive: true,
+      keepAliveMsecs: 30000,
+      maxSockets: maxApiConnections,
+      maxFreeSockets: Math.ceil(maxApiConnections / 2),
+      maxTotalSockets: maxApiConnections + 5,
+      timeout: connectionTimeout,
+      scheduling: 'fifo',
+    };
+    this.httpAgent = new Agent(agentOpts);
+    this.httpsAgent = new HttpsAgent(agentOpts);
+
+    logger.debug(
+      `🔗 Datastage API Service configured (target=${apiTarget || 'default'})`,
+    );
+  }
+
+  #getAgent(url) {
+    return url.startsWith('https://') ? this.httpsAgent : this.httpAgent;
+  }
+
+  #isRetryableError(error, response = null) {
+    if (
+      error?.code === 'ECONNRESET' ||
+      error?.code === 'ETIMEDOUT' ||
+      error?.code === 'ECONNREFUSED' ||
+      error?.code === 'ENOTFOUND' ||
+      error?.code === 'EAI_AGAIN'
+    ) {
+      return true;
+    }
+    if (response) {
+      const s = response.status;
+      if (s === 429 || (s >= 500 && s < 600)) return true;
+    }
+    if (error?.message && error.message.includes('timeout')) return true;
+    return false;
+  }
+
+  #calculateBackoff(attempt) {
+    if (!this.useExponentialBackoff) {
+      const jitter = this.fixedRetryDelay * 0.2 * (Math.random() * 2 - 1);
+      return Math.floor(this.fixedRetryDelay + jitter);
+    }
+    const baseDelay = 1000;
+    const maxDelay = 16000;
+    const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+    const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+    return Math.floor(delay + jitter);
+  }
+
+  #sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+  }
+
+  async #requestJson(endpoint, method = 'GET', body = null, headers = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const options = {
+      method,
+      headers: {
+        'x-api-key': this.token,
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+      agent: this.#getAgent(url),
+    };
+    if (body) options.body = JSON.stringify(body);
+
+    let lastError;
+    let lastResponse = null;
+    const retries = this.maxRetries;
+
+    for (let attempt = 1; attempt <= retries + 1; attempt++) {
+      try {
+        const response = await fetch(url, options);
+        lastResponse = response;
+        if (!response.ok) {
+          const errorText = await response.text();
+          let errorMessage = `API ${method} ${endpoint} failed: ${response.status} ${response.statusText}`;
+          try {
+            const j = JSON.parse(errorText);
+            errorMessage = j.message || errorMessage;
+          } catch {
+            errorMessage = errorText || errorMessage;
+          }
+          const err = new Error(errorMessage);
+          err.status = response.status;
+          if (this.#isRetryableError(err, response) && attempt <= retries) {
+            const d = this.#calculateBackoff(attempt);
+            logger.warn(
+              `Retrying ${method} ${endpoint} (attempt ${attempt}/${retries + 1}) in ${d}ms: ${errorMessage}`,
+            );
+            await this.#sleep(d);
+            continue;
+          }
+          throw err;
+        }
+        return await response.json();
+      } catch (error) {
+        lastError = error;
+        if (this.#isRetryableError(error, lastResponse) && attempt <= retries) {
+          const d = this.#calculateBackoff(attempt);
+          logger.warn(
+            `Retrying ${method} ${endpoint} (attempt ${attempt}/${retries + 1}) in ${d}ms: ${error.message}`,
+          );
+          await this.#sleep(d);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError;
+  }
+
+  // --- Tracking endpoints ---
+
+  async registerUpload({
+    absolutePath,
+    fileName,
+    sizeBytes,
+    fileModifiedAt,
+    sourceDirectory,
+  }) {
+    return this.#requestJson('/api/uploader/datastage/register', 'POST', {
+      absolutePath,
+      fileName,
+      sizeBytes,
+      fileModifiedAt,
+      sourceDirectory,
+    });
+  }
+
+  async getPending(sourceDirectory = null) {
+    const qs = sourceDirectory
+      ? `?sourceDirectory=${encodeURIComponent(sourceDirectory)}`
+      : '';
+    return this.#requestJson(`/api/uploader/datastage/pending${qs}`, 'GET');
+  }
+
+  async getStats(sourceDirectory = null) {
+    const qs = sourceDirectory
+      ? `?sourceDirectory=${encodeURIComponent(sourceDirectory)}`
+      : '';
+    return this.#requestJson(`/api/uploader/datastage/stats${qs}`, 'GET');
+  }
+
+  async markUploaded(id, { datastageId, folio }) {
+    return this.#requestJson(
+      `/api/uploader/datastage/${id}/mark-uploaded`,
+      'PATCH',
+      { datastageId, folio },
+    );
+  }
+
+  async markFailed(id, error) {
+    return this.#requestJson(
+      `/api/uploader/datastage/${id}/mark-failed`,
+      'PATCH',
+      { error: String(error || 'unknown') },
+    );
+  }
+
+  // --- Zip upload ---
+
+  /**
+   * Upload a single zip file to POST /api/datastage (multipart, field name 'zipFile').
+   * Returns the created Datastage row { id, folio, ... }.
+   */
+  async uploadZip(localPath) {
+    const url = `${this.baseUrl}/api/datastage`;
+    const form = new FormData();
+    const fileName = path.basename(localPath);
+    form.append('zipFile', fs.createReadStream(localPath), {
+      filename: fileName,
+      contentType: 'application/zip',
+    });
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.token,
+        ...form.getHeaders(),
+      },
+      body: form,
+      agent: this.#getAgent(url),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      let msg = `Datastage upload failed: ${response.status} ${response.statusText}`;
+      try {
+        const j = JSON.parse(text);
+        msg = j.message || msg;
+      } catch {
+        msg = text || msg;
+      }
+      const err = new Error(msg);
+      err.status = response.status;
+      throw err;
+    }
+    return await response.json();
+  }
+}
+
+export default DatastageApiService;

package/src/services/ScanApiService.js

@@ -375,6 +375,20 @@ export class ScanApiService {
    * @param {boolean} allTypes - When true, fetch all supported file types instead of just likely-simplificado PDFs
    * @returns {Promise<Object>} { data: Array, hasMore: boolean }
    */
+  /**
+   * Get a single file record by ID (for single-file identify mode).
+   * @param {string} tableName - Scan table name (with or without cli. prefix)
+   * @param {string} fileId - UUID of the file record
+   * @returns {Promise<{ id: string, file_name: string, file_extension: string, absolute_path: string }>}
+   */
+  async getFileRecord(tableName, fileId) {
+    const cleanTable = tableName.replace(/^cli\./, '');
+    const url = `/api/uploader/scan/file-record?tableName=${encodeURIComponent(cleanTable)}&fileId=${encodeURIComponent(fileId)}`;
+    const result = await this.#request(url, 'GET');
+    logger.debug(`Fetched file record ${fileId} from ${cleanTable}`);
+    return result;
+  }
+
   async fetchPdfsForDetection(
     tableName,
     offset = 0,
@@ -398,6 +412,22 @@ export class ScanApiService {
     return result;
   }
 
+  /**
+   * Reset detection_attempts to 0 for undetected files so they can be re-processed.
+   * @param {string} tableName - Target scan table name
+   * @param {string|null} absolutePath - If provided, reset only this specific file
+   * @returns {Promise<{ reset: number }>}
+   */
+  async resetDetectionAttempts(tableName, absolutePath = null) {
+    let url = `/api/uploader/scan/reset-detection-attempts?tableName=${encodeURIComponent(tableName)}`;
+    if (absolutePath) {
+      url += `&absolutePath=${encodeURIComponent(absolutePath)}`;
+    }
+    const result = await this.#request(url, 'PATCH');
+    logger.debug(`Reset ${result.reset} detection attempt(s) in ${tableName}`);
+    return result;
+  }
+
   /**
    * Batch update detection results
    * @param {string} tableName - Target table name

package/tests/unit/factura-inter-agencia.test.js

@@ -0,0 +1,218 @@
+/**
+ * Unit tests for the factura_inter_agencia matcher.
+ *
+ * Verifies that NORCOM↔PALCO CFDIs (XML and printable PDF text) are
+ * detected as `factura_inter_agencia`, and that ordinary CFDIs are NOT
+ * mis-classified.
+ */
+import { describe, it, expect } from '@jest/globals';
+
+import {
+  facturaInterAgenciaDefinition,
+  INTER_AGENCIA_RFCS,
+} from '../../src/document-types/factura-inter-agencia.js';
+import { extractDocumentFields } from '../../src/document-type-shared.js';
+
+const NORCOM_RFC = 'NAA120215F20';
+const PALCO_RFC = 'PCC1008161WA';
+
+// Realistic CFDI 4.0 XML between NORCOM (emisor) and PALCO (receptor).
+// Conceptos use ClaveProdServ 78141502 (servicios de agentes aduaneros).
+const CFDI_XML_INTER_AGENCIA = `<?xml version="1.0" encoding="utf-8"?>
+<cfdi:Comprobante xmlns:cfdi="http://www.sat.gob.mx/cfd/4" Version="4.0" Folio="012749"
+  TipoDeComprobante="I" SubTotal="3000.00" Total="3480.00" Moneda="MXN">
+  <cfdi:Emisor Rfc="${NORCOM_RFC}" Nombre="NORCOM AGENTES ADUANALES" RegimenFiscal="601"/>
+  <cfdi:Receptor Rfc="${PALCO_RFC}" Nombre="PALCO, CONSORCIO DE COMERCIO INTERNACIONAL"
+    DomicilioFiscalReceptor="32380" RegimenFiscalReceptor="601" UsoCFDI="G03"/>
+  <cfdi:Conceptos>
+    <cfdi:Concepto ClaveProdServ="78141502" NoIdentificacion="HONO" Cantidad="1.00"
+      ClaveUnidad="E48" Unidad="Unidad de servicio" Descripcion="HONORARIOS"
+      ValorUnitario="1300.00" Importe="1300.00" ObjetoImp="02"/>
+    <cfdi:Concepto ClaveProdServ="78141502" NoIdentificacion="VALID" Cantidad="1.00"
+      ClaveUnidad="E48" Unidad="Unidad de servicio" Descripcion="VALIDACION"
+      ValorUnitario="200.00" Importe="200.00" ObjetoImp="02"/>
+  </cfdi:Conceptos>
+</cfdi:Comprobante>`;
+
+// Same agencies but conceptos do NOT use 78141502 — should NOT match.
+const CFDI_XML_INTER_AGENCIA_WRONG_CONCEPT = CFDI_XML_INTER_AGENCIA.replace(
+  /78141502/g,
+  '90121502',
+);
+
+// CFDI between unrelated taxpayers — should NOT match.
+const CFDI_XML_REGULAR = `<?xml version="1.0" encoding="utf-8"?>
+<cfdi:Comprobante xmlns:cfdi="http://www.sat.gob.mx/cfd/4" Version="4.0" Folio="000123"
+  TipoDeComprobante="I" SubTotal="100.00" Total="116.00">
+  <cfdi:Emisor Rfc="ACME010101AB1" Nombre="ACME COMERCIAL" RegimenFiscal="601"/>
+  <cfdi:Receptor Rfc="XYZ020202CD2" Nombre="CLIENTE FINAL"
+    DomicilioFiscalReceptor="00000" RegimenFiscalReceptor="601" UsoCFDI="G03"/>
+  <cfdi:Conceptos>
+    <cfdi:Concepto ClaveProdServ="78141502" NoIdentificacion="ITEM" Cantidad="1.00"
+      ClaveUnidad="E48" Unidad="Unidad de servicio" Descripcion="SERVICIO"
+      ValorUnitario="100.00" Importe="100.00" ObjetoImp="02"/>
+  </cfdi:Conceptos>
+</cfdi:Comprobante>`;
+
+// Text extracted from the printable PDF representation of a CFDI inter-agencia.
+// Mirrors what pdf-parse returns for the sample SICINGR70-012749(...).pdf.
+const CFDI_PDF_TEXT_INTER_AGENCIA = `NORCOM AGENTES ADUANALES S.C
+Tipo de Comprobante: (I) Ingreso
+Folio Fiscal 84FC9CE2-00D5-4843-B377-B463321F9FC6
+Numero Folio 012749
+Emisor
+RFC ${NORCOM_RFC}
+Razon Social NORCOM AGENTES ADUANALES
+Receptor
+RFC ${PALCO_RFC}
+Razon Social PALCO, CONSORCIO DE COMERCIO INTERNACIONAL
+Pedimento: 3458 6000046 Fecha: 17/02/2026 Tipo: EXP Clave: A1
+Erogaciones
+78141502 HONO HONORARIOS 1,300.00
+78141502 SERCOM SERVICIOS COMPLEMENTARIOS 1,500.00
+78141502 VALID VALIDACION 200.00
+Sello Digital del CFDI
+c4oBJ8/zAol0zg1jVe4MK8...
+Cadena Original del Complemento de Certificacion Digital del SAT
+||4.0|012749|...
+Este documento es una representación impresa de un CFDI`;
+
+describe('factura_inter_agencia matcher', () => {
+  describe('configured RFC set', () => {
+    it('includes NORCOM and PALCO RFCs', () => {
+      expect(INTER_AGENCIA_RFCS).toContain(NORCOM_RFC);
+      expect(INTER_AGENCIA_RFCS).toContain(PALCO_RFC);
+    });
+  });
+
+  describe('match()', () => {
+    it('matches a NORCOM→PALCO XML CFDI with broker-service conceptos', () => {
+      expect(facturaInterAgenciaDefinition.match(CFDI_XML_INTER_AGENCIA)).toBe(
+        true,
+      );
+    });
+
+    it('matches the PDF-text representation of the same CFDI', () => {
+      expect(
+        facturaInterAgenciaDefinition.match(CFDI_PDF_TEXT_INTER_AGENCIA),
+      ).toBe(true);
+    });
+
+    it('does NOT match when ClaveProdServ is not 78141502', () => {
+      expect(
+        facturaInterAgenciaDefinition.match(
+          CFDI_XML_INTER_AGENCIA_WRONG_CONCEPT,
+        ),
+      ).toBe(false);
+    });
+
+    it('does NOT match a CFDI between unrelated taxpayers', () => {
+      expect(facturaInterAgenciaDefinition.match(CFDI_XML_REGULAR)).toBe(false);
+    });
+
+    it('does NOT match arbitrary non-CFDI text containing the RFCs', () => {
+      const text = `Reporte interno
+RFC emisor: ${NORCOM_RFC}
+RFC cliente: ${PALCO_RFC}
+Clave 78141502`;
+      // No CFDI markers → should not match.
+      expect(facturaInterAgenciaDefinition.match(text)).toBe(false);
+    });
+
+    it('does NOT match if only one of the configured RFCs is present', () => {
+      const text = CFDI_XML_INTER_AGENCIA.replace(PALCO_RFC, 'XYZ020202CD2');
+      expect(facturaInterAgenciaDefinition.match(text)).toBe(false);
+    });
+  });
+
+  describe('extractors', () => {
+    it('extracts emisor + receptor RFCs from XML', () => {
+      const rfcEmisor = facturaInterAgenciaDefinition.extractors
+        .find((e) => e.field === 'rfcEmisor')
+        .extract(CFDI_XML_INTER_AGENCIA);
+      const rfcReceptor = facturaInterAgenciaDefinition.extractors
+        .find((e) => e.field === 'rfcReceptor')
+        .extract(CFDI_XML_INTER_AGENCIA);
+
+      expect(rfcEmisor.found).toBe(true);
+      expect(rfcEmisor.value).toBe(NORCOM_RFC);
+      expect(rfcReceptor.found).toBe(true);
+      expect(rfcReceptor.value).toBe(PALCO_RFC);
+    });
+
+    it('extracts both RFCs from PDF text via fallback', () => {
+      const rfcEmisor = facturaInterAgenciaDefinition.extractors
+        .find((e) => e.field === 'rfcEmisor')
+        .extract(CFDI_PDF_TEXT_INTER_AGENCIA);
+      const rfcReceptor = facturaInterAgenciaDefinition.extractors
+        .find((e) => e.field === 'rfcReceptor')
+        .extract(CFDI_PDF_TEXT_INTER_AGENCIA);
+
+      expect(rfcEmisor.found).toBe(true);
+      expect(rfcReceptor.found).toBe(true);
+      // Order is the order of first appearance in the document.
+      const found = [rfcEmisor.value, rfcReceptor.value].sort();
+      expect(found).toEqual([NORCOM_RFC, PALCO_RFC].sort());
+    });
+
+    it('extracts the UUID (folio fiscal) from both formats', () => {
+      const uuidExtractor = facturaInterAgenciaDefinition.extractors.find(
+        (e) => e.field === 'uuid',
+      );
+
+      const fromXml = uuidExtractor.extract(CFDI_XML_INTER_AGENCIA);
+      // XML sample has no UUID inside the comprobante body — that's fine.
+      expect(fromXml.found).toBe(false);
+
+      const fromPdf = uuidExtractor.extract(CFDI_PDF_TEXT_INTER_AGENCIA);
+      expect(fromPdf.found).toBe(true);
+      expect(fromPdf.value).toBe('84FC9CE2-00D5-4843-B377-B463321F9FC6');
+    });
+
+    it('extracts numPedimento from the printable PDF "Pedimento:" line', () => {
+      const numExtractor = facturaInterAgenciaDefinition.extractors.find(
+        (e) => e.field === 'numPedimento',
+      );
+      const result = numExtractor.extract(CFDI_PDF_TEXT_INTER_AGENCIA);
+      expect(result.found).toBe(true);
+      expect(result.value).toBe('34586000046');
+    });
+
+    it('extracts the CFDI folio from XML attribute', () => {
+      const folio = facturaInterAgenciaDefinition.extractors
+        .find((e) => e.field === 'folio')
+        .extract(CFDI_XML_INTER_AGENCIA);
+      expect(folio.found).toBe(true);
+      expect(folio.value).toBe('012749');
+    });
+  });
+
+  describe('registry order (factura_inter_agencia precedes facturas_comerciales)', () => {
+    it('resolves the inter-agency CFDI XML to factura_inter_agencia, not factura_comercial', () => {
+      const [detectedType] = extractDocumentFields(
+        CFDI_XML_INTER_AGENCIA,
+        'xml',
+        '/tmp/SICINGR70-012749(PALCO).XML',
+      );
+      expect(detectedType).toBe('factura_inter_agencia');
+    });
+
+    it('resolves the inter-agency CFDI PDF text to factura_inter_agencia', () => {
+      const [detectedType] = extractDocumentFields(
+        CFDI_PDF_TEXT_INTER_AGENCIA,
+        'pdf',
+        '/tmp/SICINGR70-012749(PALCO).pdf',
+      );
+      expect(detectedType).toBe('factura_inter_agencia');
+    });
+
+    it('falls through to factura_comercial for a regular CFDI', () => {
+      const [detectedType] = extractDocumentFields(
+        CFDI_XML_REGULAR,
+        'xml',
+        '/tmp/regular-invoice.xml',
+      );
+      expect(detectedType).toBe('factura_comercial');
+    });
+  });
+});