@devlas/dte-sii 2.19.0 → 2.20.0

package/DTE.js

@@ -12,6 +12,7 @@ const { DOMParser } = require('@xmldom/xmldom');
 const {
   sanitizeSiiText,
   sanitizeTedText,
+  assertLargoMaximo,
   formatBase64InXml,
   normalizeEmisor,
   normalizeReceptor,
@@ -22,6 +23,21 @@ const {
 } = require('./utils');
 const { serializeNode, escapeAttr, escapeText, buildSignedInfo, buildSignature } = require('./utils/c14n');
 
+/**
+ * Sanitiza y valida el nombre de un ítem antes de que entre al XML.
+ *
+ * Lanza si supera los 80 caracteres que admite `NmbItem` en el XSD del SII — el SII
+ * rechaza el SOBRE COMPLETO cuando uno solo de sus documentos falla el schema (medido el
+ * 2026-09-01: 3 boletas cayeron juntas por un ítem de 83 caracteres, 2 de ellas con datos
+ * válidos). Mejor lanzar acá, con el campo y el valor, que dejar que el SII lo rechace
+ * tres pasos después con "Error en Schema" sin decir cuál documento ni por qué.
+ */
+function sanitizeNmbItem(nombre) {
+  const valor = sanitizeSiiText(nombre);
+  assertLargoMaximo(valor, 80, 'NmbItem');
+  return valor;
+}
+
 // ============================================
 // CONSTANTES
 // ============================================
@@ -140,7 +156,7 @@ class DTE {
       const det = {
         NroLinDet: idx + 1,
         ...(esItemExento ? { IndExe: 1 } : {}),
-        NmbItem: sanitizeSiiText(item.NmbItem),
+        NmbItem: sanitizeNmbItem(item.NmbItem),
         QtyItem: qty,
         ...(item.UnmdItem ? { UnmdItem: item.UnmdItem } : {}),
         PrcItem: prc,
@@ -247,7 +263,7 @@ class DTE {
   _buildDetalle(det) {
     return (Array.isArray(det) ? det : [det]).map(item => ({
       ...item,
-      NmbItem: sanitizeSiiText(item.NmbItem),
+      NmbItem: sanitizeNmbItem(item.NmbItem),
       ...(item.DscItem ? { DscItem: sanitizeSiiText(item.DscItem) } : {}),
     }));
   }

package/dte-sii.d.ts

@@ -626,14 +626,73 @@ export interface FolioTope {
   bloqueado?: boolean;
 }
 
-export interface ReobtenerCafResult {
-  /** Rutas de los CAF recuperados. El SII entrega los folios de a uno, así que pueden ser varios. */
-  paths: string[];
-  /** Cantidad total de folios recuperados entre todos los rangos. */
-  folios: number;
-  /** Rangos que se descartaron por estar anulados en el SII. */
-  descartados: Array<{ desde: number; hasta: number; motivo: string }>;
-}
+/** Un rango ya autorizado que el portal ofrece para reobtener. */
+export interface RangoReobtenible {
+  /** Campos ocultos del formulario del portal. Hay que devolverlos tal cual para bajar el CAF. */
+  campos: Record<string, string>;
+  folioDesde: number;
+  folioHasta: number;
+  /** Folios que cubre el rango. */
+  cantidad: number;
+  /**
+   * true si el SII anuló el rango. Los documentos emitidos con esos folios se
+   * rechazan, así que hay que saltarlo.
+   *
+   * Ojo: el portal marca los ANULADOS y nada más. Un folio ya emitido aparece
+   * como reobtenible igual, y por eso `FolioService.reobtenerCaf` recibe
+   * `yaEmitido`: ese dato el SII no lo publica.
+   */
+  anulado: boolean;
+}
+
+/** Resultado de `CafSolicitor.reobtenerCaf`, para un solo rango. */
+export type ReobtenerRangoResult =
+  | {
+      success: true;
+      /** Ruta donde quedó el CAF descargado. */
+      cafPath: string;
+      /** El XML del CAF tal como lo entregó el portal. */
+      xml: string;
+      reobtenido: true;
+      folioDesde: number;
+      folioHasta: number;
+      otorgados: number;
+    }
+  | {
+      success: false;
+      errorCode:
+        | 'RANGO_ANULADO'
+        | 'REOBTENCION_SIN_FORMULARIO'
+        | 'REOBTENCION_SIN_DESCARGA'
+        | 'REOBTENCION_SIN_CAF';
+      [extra: string]: unknown;
+    };
+
+/**
+ * Resultado de `FolioService.reobtenerCaf`.
+ *
+ * Union discriminada por `ok` a propósito: obliga a comprobarlo antes de leer
+ * las rutas. El método **nunca devuelve null**, ni siquiera al fallar, así que
+ * `if (!resultado)` no detecta nada.
+ */
+export type ReobtenerCafResult =
+  | {
+      ok: true;
+      /** Rutas de los CAF recuperados. El SII entrega los rangos de a uno, así que pueden ser varios. */
+      cafPaths: string[];
+      /** Atajo al primero de `cafPaths`. */
+      cafPath: string;
+    }
+  | {
+      ok: false;
+      /** Qué impidió completar la reobtención, en texto legible. */
+      motivo: string;
+      /**
+       * Folios que sí se alcanzaron a cubrir, cuando el fallo es por cantidad.
+       * Ausente si el fallo fue antes de mirar los rangos.
+       */
+      disponibles?: number;
+    };
 
 export class FolioService {
   constructor(config?: FolioServiceConfig);
@@ -661,7 +720,7 @@ export class FolioService {
      * cada documento vuelve rechazado con `DTE-3-101`.
      */
     yaEmitido?: (rango: { folioDesde: number; folioHasta: number }) => boolean;
-  }): Promise<ReobtenerCafResult | null>;
+  }): Promise<ReobtenerCafResult>;
   /** El CAF más reciente de un tipo para este RUT y ambiente, o null. */
   findLatestCaf(tipoDte: number): string | null;
   /**
@@ -771,9 +830,17 @@ export class CafSolicitor {
    * ⚠️ El listado incluye rangos ANULADOS sin distinguirlos: solo al abrir cada uno el
    * portal lo avisa. Por eso `reobtenerCaf` hace un request por rango.
    */
-  listarReobtenibles(tipoDte: number): Promise<Array<{ desde: number; hasta: number; raw?: string }>>;
-  /** Descarga el CAF de un rango ya autorizado. Devuelve null si el rango está anulado. */
-  reobtenerCaf(tipoDte: number, rango: { desde: number; hasta: number }): Promise<string | null>;
+  listarReobtenibles(tipoDte: number): Promise<RangoReobtenible[]>;
+  /**
+   * Descarga el CAF de un rango ya autorizado.
+   *
+   * `rango` es un elemento tal cual sale de `listarReobtenibles`: lleva los
+   * campos ocultos del formulario del portal en `campos`, que el portal exige de
+   * vuelta. No se puede construir a mano con solo los folios.
+   *
+   * **No devuelve el XML ni null**, devuelve un objeto con `success`.
+   */
+  reobtenerCaf(tipoDte: number, rango: RangoReobtenible): Promise<ReobtenerRangoResult>;
 }
 
 // ============================================
@@ -821,6 +888,11 @@ export function sanitizeSiiText(text: string): string;
  */
 export function sanitizeTedText(text: string): string;
 export function truncateText(text: string, maxLen: number, preserveWords?: boolean): string;
+/**
+ * Lanza si `text` supera `maxLength` caracteres — para campos con `xs:maxLength` fijo en
+ * el XSD (ej. NmbItem: 80). Se valida el texto YA sanitizado, el que efectivamente va al XML.
+ */
+export function assertLargoMaximo(text: string, maxLength: number, campo: string): void;
 export function sanitizeGiroRecep(giro: string): string;
 export function sanitizeRazonSocial(razonSocial: string): string;
 export function sanitizeNombreItem(nombre: string): string;
@@ -965,6 +1037,7 @@ export const utils: {
   sanitizeSiiText: typeof sanitizeSiiText;
   sanitizeTedText: typeof sanitizeTedText;
   truncateText: typeof truncateText;
+  assertLargoMaximo: typeof assertLargoMaximo;
   sanitizeGiroRecep: typeof sanitizeGiroRecep;
   sanitizeRazonSocial: typeof sanitizeRazonSocial;
   sanitizeNombreItem: typeof sanitizeNombreItem;

package/index.js

@@ -46,6 +46,7 @@ const {
   sanitizeSiiText,
   sanitizeTedText,
   truncateText,
+  assertLargoMaximo,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
   sanitizeNombreItem,
@@ -260,6 +261,7 @@ module.exports = {
   sanitizeSiiText,
   sanitizeTedText,
   truncateText,
+  assertLargoMaximo,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
   sanitizeNombreItem,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devlas/dte-sii",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Facturación y boletas electrónicas para el SII de Chile. Genera, timbra, firma y envía DTEs, libros electrónicos y automatiza la certificación.",
   "main": "index.js",
   "types": "dte-sii.d.ts",

package/utils/index.js

@@ -54,6 +54,7 @@ const {
   sanitizeSiiText,
   sanitizeTedText,
   truncateText,
+  assertLargoMaximo,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
   sanitizeNombreItem,
@@ -179,6 +180,7 @@ module.exports = {
   sanitizeSiiText,
   sanitizeTedText,
   truncateText,
+  assertLargoMaximo,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
   sanitizeNombreItem,

package/utils/sanitize.js

@@ -118,6 +118,41 @@ function truncateText(text, maxLen, preserveWords = false) {
   return sanitized.substring(0, maxLen);
 }
 
+/**
+ * Lanza si `text` supera `maxLength` caracteres — para campos con `xs:maxLength` fijo en
+ * el XSD del SII (ej. NmbItem: 80).
+ *
+ * ── Por qué lanza y no trunca ─────────────────────────────────────────────────
+ * Esta librería ya tenía `sanitizeNombreItem`/`sanitizeRazonSocial`/etc. (más abajo),
+ * que truncan en silencio — pero nunca se conectaron a los campos que serializa `DTE.js`
+ * (`sanitizeSiiText` corre sola ahí, sin ningún control de largo). El resultado real:
+ * un `NmbItem` de 83 caracteres pasaba intacto y el SII rechazaba recién al validar el
+ * XML — y **rechaza el sobre completo**, no solo ese documento (medido el 2026-09-01,
+ * 3 boletas de un mismo envío cayeron juntas, 2 de ellas con datos válidos).
+ *
+ * Truncar en una librería de serialización es una decisión de negocio disfrazada de
+ * detalle técnico: recorta lo que el cliente ve impreso en su documento tributario, y
+ * hacerlo en silencio esconde el dato malo en vez de exponerlo. Esta librería conoce el
+ * contrato del XSD — le corresponde avisar temprano, con un mensaje que diga campo,
+ * límite y valor, para que el consumidor decida qué hacer (corregir el dato, truncar con
+ * su propia política, etc.) en vez de que el SII lo rechace tres pasos después con un
+ * error genérico de schema.
+ *
+ * @param {string} text - Texto YA sanitizado (post `sanitizeSiiText`) — se valida el que
+ *   efectivamente va al XML, no el original.
+ * @param {number} maxLength
+ * @param {string} campo - Nombre del elemento XSD, para el mensaje de error.
+ * @throws {Error} si `text.length > maxLength`
+ */
+function assertLargoMaximo(text, maxLength, campo) {
+  const valor = String(text ?? '');
+  if (valor.length > maxLength) {
+    throw new Error(
+      `${campo} excede el largo maximo del XSD (${maxLength} caracteres, tiene ${valor.length}): "${valor}"`
+    );
+  }
+}
+
 /**
  * Sanitizar giro para receptor (máximo 40 caracteres)
  * 
@@ -184,6 +219,7 @@ module.exports = {
   sanitizeSiiText,
   sanitizeTedText,
   truncateText,
+  assertLargoMaximo,
   sanitizeGiroRecep,
   sanitizeRazonSocial,
   sanitizeNombreItem,