dgii-ts 0.2.0 → 0.3.0

package/README.en.md

@@ -40,8 +40,9 @@ that pass validation despite failing the check-digit algorithm.
 ### Resilient client (DgiiClient)
 
 `DgiiClient` is the recommended entry point for real-time queries. It uses
-web scraping as its primary strategy with SOAP fallback, a circuit breaker
-to prevent cascading failures, and retry with exponential backoff.
+web scraping with a circuit breaker to prevent cascading failures and retry
+with exponential backoff. The SOAP fallback is opt-in (`soapFallback: true`)
+and off by default since version 0.3.0.
 
 ### Web scraping
 
@@ -52,8 +53,8 @@ endpoint in January 2025.
 ### SOAP client (WSMovilDGII) — deprecated
 
 Typed wrapper around DGII's SOAP service. **Permanently blocked by DGII
-since January 2025.** Kept as an internal fallback but not recommended
-for direct use.
+since January 2025.** Kept as an opt-in `DgiiClient` fallback (off by
+default) and not recommended for direct use.
 
 ### Bulk data importer
 
@@ -74,6 +75,29 @@ pnpm add dgii-ts
 yarn add dgii-ts
 ```
 
+## Agent skill
+
+dgii-ts ships a skill ([`skills/dgii-ts/SKILL.md`](./skills/dgii-ts/SKILL.md))
+that teaches coding agents (Claude Code, Cursor, Codex, Copilot, and others
+that support [Agent Skills](https://agentskills.io)) to use the library
+correctly: what each validator checks, how to handle `DgiiClient` errors,
+and how to avoid hammering DGII.
+
+```bash
+# Any supported agent
+npx skills add franklinmdev/dgii-ts --skill dgii-ts
+```
+
+In Claude Code you can also install it as a plugin:
+
+```text
+/plugin marketplace add franklinmdev/dgii-ts
+/plugin install dgii-ts@dgii-ts
+```
+
+The skill is also included in the npm package, under
+`node_modules/dgii-ts/skills/`.
+
 ## Quick start
 
 ### Validate an RNC
@@ -141,8 +165,11 @@ const ncfResult = await client.getNCF('131098193', 'B0100000001');
 ### Validate an e-NCF online
 
 For an e-NCF (E-series) DGII requires the buyer's RNC. Without it DGII
-answers with a required-field message and `getNCF` throws
-`DgiiServiceError`. The security code is optional.
+answers with a required-field message: `ScrapingClient.getNCF` throws
+`DgiiServiceError` and `DgiiClient.getNCF` wraps it in
+`AllStrategiesFailedError` after exhausting retries and the fallback
+(the message keeps DGII's text). The same happens without the
+security code: DGII requires it too (verified with an E31 e-NCF).
 
 ```typescript
 const ecfResult = await client.getNCF('101010632', 'E310125217173', {
@@ -185,7 +212,7 @@ ignored for a B-series NCF.
 
 | Class/Method | Description |
 | --- | --- |
-| `DgiiClient` | Scraping + SOAP fallback, circuit breaker, retry |
+| `DgiiClient` | Scraping, circuit breaker, retry (optional SOAP fallback) |
 | `client.getContribuyente(rnc)` | Looks up taxpayer data by RNC |
 | `client.getNCF(rnc, ncf, options?)` | Validates a fiscal receipt against DGII (`options` for e-NCF) |
 
@@ -227,7 +254,7 @@ accepts an `encoding` option (defaults to `latin1`).
 ├─────────────────────────────────────────────────┤
 │  Layer 2: DgiiClient (resilient)                │
 │  ✓ Web scraping (primary)                       │
-│  ✓ SOAP fallback  ✓ Circuit breaker  ✓ Retry   │
+│  ✓ Circuit breaker  ✓ Retry                    │
 ├─────────────────────────────────────────────────┤
 │  Layer 3: Bulk data (DGII_RNC.zip)              │
 │  ✓ Daily download  ✓ TXT parsing                │
@@ -235,8 +262,7 @@ accepts an `encoding` option (defaults to `latin1`).
 ```
 
 **Layer 1** is instant and works offline. **Layer 2** provides real-time data
-using web scraping as the primary strategy, with SOAP fallback, circuit
-breaker, and retry with exponential backoff. **Layer 3** is ideal for batch
+using web scraping, a circuit breaker, and retry with exponential backoff. **Layer 3** is ideal for batch
 operations where you need to look up thousands of RNCs quickly.
 
 ## Project status

package/README.md

@@ -43,8 +43,9 @@ pasan validación aunque no cumplan el algoritmo de dígito verificador.
 ### Cliente resiliente (DgiiClient)
 
 `DgiiClient` es el punto de entrada recomendado para consultas en tiempo real.
-Usa web scraping como estrategia primaria con fallback a SOAP, circuit breaker
-para evitar cascadas de errores, y retry con backoff exponencial.
+Usa web scraping con circuit breaker para evitar cascadas de errores y retry
+con backoff exponencial. El fallback a SOAP es opcional (`soapFallback: true`)
+y está apagado por defecto desde la versión 0.3.0.
 
 ### Web scraping
 
@@ -56,7 +57,8 @@ bloqueó el endpoint SOAP en enero 2025.
 
 Wrapper tipado alrededor del servicio SOAP de la DGII. **Bloqueado
 permanentemente por la DGII en enero 2025.** Se mantiene como fallback
-interno pero no se recomienda su uso directo.
+opcional de `DgiiClient` (apagado por defecto) y no se recomienda su uso
+directo.
 
 ### Importador de datos masivos
 
@@ -77,6 +79,29 @@ pnpm add dgii-ts
 yarn add dgii-ts
 ```
 
+## Skill para agentes de IA
+
+dgii-ts incluye un skill ([`skills/dgii-ts/SKILL.md`](./skills/dgii-ts/SKILL.md))
+que enseña a los agentes de código (Claude Code, Cursor, Codex, Copilot y
+otros compatibles con [Agent Skills](https://agentskills.io)) a usar la
+librería correctamente: qué valida cada validador, cómo manejar los
+errores de `DgiiClient` y cómo no saturar a la DGII.
+
+```bash
+# Cualquier agente compatible
+npx skills add franklinmdev/dgii-ts --skill dgii-ts
+```
+
+En Claude Code también se puede instalar como plugin:
+
+```text
+/plugin marketplace add franklinmdev/dgii-ts
+/plugin install dgii-ts@dgii-ts
+```
+
+El skill viene además dentro del paquete de npm, en
+`node_modules/dgii-ts/skills/`.
+
 ## Uso rápido
 
 ### Validar un RNC
@@ -144,8 +169,11 @@ const ncfResult = await client.getNCF('131098193', 'B0100000001');
 ### Validar e-NCF en línea
 
 Para un e-NCF (serie E) la DGII exige el RNC del comprador. Sin él
-responde con un mensaje de campo requerido y `getNCF` lanza
-`DgiiServiceError`. El código de seguridad es opcional.
+responde con un mensaje de campo requerido: `ScrapingClient.getNCF`
+lanza `DgiiServiceError` y `DgiiClient.getNCF` lo envuelve en
+`AllStrategiesFailedError` tras agotar reintentos y fallback (el
+mensaje conserva el texto de la DGII). Lo mismo pasa sin el código
+de seguridad: la DGII también lo exige (verificado con un e-NCF E31).
 
 ```typescript
 const ecfResult = await client.getNCF('101010632', 'E310125217173', {
@@ -189,7 +217,7 @@ serie B.
 
 | Clase/Método | Descripción |
 | --- | --- |
-| `DgiiClient` | Cliente con scraping + SOAP fallback, circuit breaker y retry |
+| `DgiiClient` | Cliente con scraping, circuit breaker y retry (SOAP fallback opcional) |
 | `client.getContribuyente(rnc)` | Consulta datos de un contribuyente por RNC |
 | `client.getNCF(rnc, ncf, options?)` | Valida un comprobante fiscal contra la DGII (`options` para e-NCF) |
 
@@ -231,7 +259,7 @@ Acepta `encoding` en las opciones (`latin1` por defecto).
 ├─────────────────────────────────────────────────┤
 │  Capa 2: DgiiClient (resiliente)                │
 │  ✓ Web scraping (primario)                      │
-│  ✓ SOAP fallback  ✓ Circuit breaker  ✓ Retry   │
+│  ✓ Circuit breaker  ✓ Retry                    │
 ├─────────────────────────────────────────────────┤
 │  Capa 3: Datos masivos (DGII_RNC.zip)           │
 │  ✓ Descarga diaria  ✓ Parseo TXT               │
@@ -239,8 +267,8 @@ Acepta `encoding` en las opciones (`latin1` por defecto).
 ```
 
 La **capa 1** es instantánea y funciona sin conexión. La **capa 2** ofrece
-datos en tiempo real con web scraping como estrategia primaria, fallback a
-SOAP, circuit breaker y retry con backoff exponencial. La **capa 3** es
+datos en tiempo real con web scraping, circuit breaker y retry con backoff
+exponencial. La **capa 3** es
 ideal para operaciones en lote donde necesitas buscar miles de RNC rápidamente.
 
 ## Estado del proyecto

package/dist/{chunk-FRM5XREF.cjs → chunk-6REHWG3R.cjs}

@@ -94,7 +94,7 @@ function parseContribuyenteHtml(html) {
     rnc: _chunkQH4BK5X3cjs.stripNonDigits.call(void 0, rnc),
     nombre: _chunkQH4BK5X3cjs.collapseSpaces.call(void 0, nombre),
     nombreComercial: _chunkQH4BK5X3cjs.collapseSpaces.call(void 0, nombreComercial),
-    estado: rawEstado.toUpperCase().includes("ACTIVO") ? "ACTIVO" : "INACTIVO",
+    estado: _chunkQH4BK5X3cjs.collapseSpaces.call(void 0, rawEstado).toUpperCase() === "ACTIVO" ? "ACTIVO" : "INACTIVO",
     categoria: _chunkQH4BK5X3cjs.collapseSpaces.call(void 0, categoria),
     esFacturadorElectronico: rawFacturadorElectronico.trim().toUpperCase().replace(/[ÍI]/g, "I").startsWith("SI"),
     actividadEconomica: actividadEconomica ? _chunkQH4BK5X3cjs.collapseSpaces.call(void 0, actividadEconomica) : void 0,
@@ -210,13 +210,13 @@ function extractTableFields(tableHtml) {
   const fields = /* @__PURE__ */ new Map();
   for (const match of tableHtml.matchAll(BOLD_STYLE_PATTERN)) {
     const label = normalizeLabel(_nullishCoalesce(match[1], () => ( "")));
-    const value = stripHtmlTags(_nullishCoalesce(match[2], () => ( "")));
+    const value = decodeHtmlEntities(stripHtmlTags(_nullishCoalesce(match[2], () => ( ""))));
     if (label) fields.set(label, value);
   }
   if (fields.size === 0) {
     for (const match of tableHtml.matchAll(BOLD_TAG_PATTERN)) {
       const label = normalizeLabel(_nullishCoalesce(match[1], () => ( "")));
-      const value = stripHtmlTags(_nullishCoalesce(match[2], () => ( "")));
+      const value = decodeHtmlEntities(stripHtmlTags(_nullishCoalesce(match[2], () => ( ""))));
       if (label) fields.set(label, value);
     }
   }

package/dist/{chunk-6ZRPVQPP.cjs → chunk-DUKBAJTM.cjs}

@@ -3,7 +3,7 @@
 var _chunkDLB5RJ7Ecjs = require('./chunk-DLB5RJ7E.cjs');
 
 
-var _chunkFRM5XREFcjs = require('./chunk-FRM5XREF.cjs');
+var _chunk6REHWG3Rcjs = require('./chunk-6REHWG3R.cjs');
 
 
 
@@ -52,7 +52,11 @@ var ConsecutiveBreaker = class {
       this._onSuccess();
       return result;
     } catch (error) {
-      this._onFailure();
+      if (error instanceof _chunkNASWEFHNcjs.DgiiNotFoundError) {
+        this._onSuccess();
+      } else {
+        this._onFailure();
+      }
       throw error;
     }
   }
@@ -123,7 +127,7 @@ async function withRetry(fn, options = DEFAULT_RETRY_OPTIONS) {
 var DgiiClient = class {
   constructor(options) {
     const timeout = _optionalChain([options, 'optionalAccess', _ => _.timeout]);
-    this._scraping = new (0, _chunkFRM5XREFcjs.ScrapingClient)(
+    this._scraping = new (0, _chunk6REHWG3Rcjs.ScrapingClient)(
       timeout ? { timeout } : void 0
     );
     this._soap = new (0, _chunkDLB5RJ7Ecjs.DgiiSoapClient)(
@@ -139,7 +143,7 @@ var DgiiClient = class {
       ...DEFAULT_RETRY_OPTIONS,
       ..._optionalChain([options, 'optionalAccess', _4 => _4.retry])
     };
-    this._soapFallback = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _5 => _5.soapFallback]), () => ( true));
+    this._soapFallback = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _5 => _5.soapFallback]), () => ( false));
   }
   /**
    * Consulta datos de un contribuyente por RNC o cédula.
@@ -156,6 +160,11 @@ var DgiiClient = class {
    * @param ncf - NCF o e-NCF a validar
    * @param options - Datos adicionales del e-NCF (`rncComprador`,
    *   `codigoSeguridad`). Se ignoran cuando `ncf` no es un e-NCF válido.
+   *
+   * Para un e-NCF sin `rncComprador` la DGII responde con un mensaje de
+   * campo requerido: `ScrapingClient.getNCF` lanza `DgiiServiceError` y
+   * este método lo envuelve en `AllStrategiesFailedError` tras agotar
+   * reintentos y fallback (el mensaje conserva el texto de la DGII).
    */
   async getNCF(rnc, ncf, options) {
     return this._executeWithFallback(

package/dist/{chunk-7ILLRYE4.js → chunk-LRPZFX62.js}

@@ -94,7 +94,7 @@ function parseContribuyenteHtml(html) {
     rnc: stripNonDigits(rnc),
     nombre: collapseSpaces(nombre),
     nombreComercial: collapseSpaces(nombreComercial),
-    estado: rawEstado.toUpperCase().includes("ACTIVO") ? "ACTIVO" : "INACTIVO",
+    estado: collapseSpaces(rawEstado).toUpperCase() === "ACTIVO" ? "ACTIVO" : "INACTIVO",
     categoria: collapseSpaces(categoria),
     esFacturadorElectronico: rawFacturadorElectronico.trim().toUpperCase().replace(/[ÍI]/g, "I").startsWith("SI"),
     actividadEconomica: actividadEconomica ? collapseSpaces(actividadEconomica) : void 0,
@@ -210,13 +210,13 @@ function extractTableFields(tableHtml) {
   const fields = /* @__PURE__ */ new Map();
   for (const match of tableHtml.matchAll(BOLD_STYLE_PATTERN)) {
     const label = normalizeLabel(match[1] ?? "");
-    const value = stripHtmlTags(match[2] ?? "");
+    const value = decodeHtmlEntities(stripHtmlTags(match[2] ?? ""));
     if (label) fields.set(label, value);
   }
   if (fields.size === 0) {
     for (const match of tableHtml.matchAll(BOLD_TAG_PATTERN)) {
       const label = normalizeLabel(match[1] ?? "");
-      const value = stripHtmlTags(match[2] ?? "");
+      const value = decodeHtmlEntities(stripHtmlTags(match[2] ?? ""));
       if (label) fields.set(label, value);
     }
   }

package/dist/{chunk-JV4HWHYP.js → chunk-YV4IPACJ.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-QTN5ZT4P.js";
 import {
   ScrapingClient
-} from "./chunk-7ILLRYE4.js";
+} from "./chunk-LRPZFX62.js";
 import {
   AllStrategiesFailedError,
   DgiiConnectionError,
@@ -52,7 +52,11 @@ var ConsecutiveBreaker = class {
       this._onSuccess();
       return result;
     } catch (error) {
-      this._onFailure();
+      if (error instanceof DgiiNotFoundError) {
+        this._onSuccess();
+      } else {
+        this._onFailure();
+      }
       throw error;
     }
   }
@@ -139,7 +143,7 @@ var DgiiClient = class {
       ...DEFAULT_RETRY_OPTIONS,
       ...options?.retry
     };
-    this._soapFallback = options?.soapFallback ?? true;
+    this._soapFallback = options?.soapFallback ?? false;
   }
   /**
    * Consulta datos de un contribuyente por RNC o cédula.
@@ -156,6 +160,11 @@ var DgiiClient = class {
    * @param ncf - NCF o e-NCF a validar
    * @param options - Datos adicionales del e-NCF (`rncComprador`,
    *   `codigoSeguridad`). Se ignoran cuando `ncf` no es un e-NCF válido.
+   *
+   * Para un e-NCF sin `rncComprador` la DGII responde con un mensaje de
+   * campo requerido: `ScrapingClient.getNCF` lanza `DgiiServiceError` y
+   * este método lo envuelve en `AllStrategiesFailedError` tras agotar
+   * reintentos y fallback (el mensaje conserva el texto de la DGII).
    */
   async getNCF(rnc, ncf, options) {
     return this._executeWithFallback(

package/dist/client.cjs

@@ -3,9 +3,9 @@
 
 
 
-var _chunk6ZRPVQPPcjs = require('./chunk-6ZRPVQPP.cjs');
+var _chunkDUKBAJTMcjs = require('./chunk-DUKBAJTM.cjs');
 require('./chunk-DLB5RJ7E.cjs');
-require('./chunk-FRM5XREF.cjs');
+require('./chunk-6REHWG3R.cjs');
 require('./chunk-OSGHCQFA.cjs');
 require('./chunk-WMFHPNFP.cjs');
 require('./chunk-QH4BK5X3.cjs');
@@ -15,4 +15,4 @@ require('./chunk-NASWEFHN.cjs');
 
 
 
-exports.ConsecutiveBreaker = _chunk6ZRPVQPPcjs.ConsecutiveBreaker; exports.DgiiClient = _chunk6ZRPVQPPcjs.DgiiClient; exports.isRetryableError = _chunk6ZRPVQPPcjs.isRetryableError; exports.withRetry = _chunk6ZRPVQPPcjs.withRetry;
+exports.ConsecutiveBreaker = _chunkDUKBAJTMcjs.ConsecutiveBreaker; exports.DgiiClient = _chunkDUKBAJTMcjs.DgiiClient; exports.isRetryableError = _chunkDUKBAJTMcjs.isRetryableError; exports.withRetry = _chunkDUKBAJTMcjs.withRetry;

package/dist/client.d.cts

@@ -59,7 +59,11 @@ declare class ConsecutiveBreaker {
 interface ClientOptions {
     /** Tiempo de espera en milisegundos (por defecto: 15000) */
     timeout?: number;
-    /** Habilitar fallback a SOAP (por defecto: true) */
+    /**
+     * Habilitar fallback a SOAP (por defecto: false). La DGII bloqueó el
+     * endpoint SOAP en enero 2025; activarlo solo agrega una petición
+     * inútil tras cada falla del scraping.
+     */
     soapFallback?: boolean;
     /** Opciones de reintentos */
     retry?: Partial<RetryOptions>;
@@ -70,8 +74,9 @@ interface ClientOptions {
 /**
  * Cliente resiliente para consultas a la DGII.
  *
- * Usa web scraping como estrategia principal y SOAP como
- * fallback (con circuit breaker y reintentos automáticos).
+ * Usa web scraping con circuit breaker y reintentos automáticos. El
+ * fallback a SOAP es opcional (`soapFallback: true`) y está apagado por
+ * defecto: la DGII bloqueó ese endpoint en enero 2025.
  */
 declare class DgiiClient {
     private readonly _scraping;
@@ -92,6 +97,11 @@ declare class DgiiClient {
      * @param ncf - NCF o e-NCF a validar
      * @param options - Datos adicionales del e-NCF (`rncComprador`,
      *   `codigoSeguridad`). Se ignoran cuando `ncf` no es un e-NCF válido.
+     *
+     * Para un e-NCF sin `rncComprador` la DGII responde con un mensaje de
+     * campo requerido: `ScrapingClient.getNCF` lanza `DgiiServiceError` y
+     * este método lo envuelve en `AllStrategiesFailedError` tras agotar
+     * reintentos y fallback (el mensaje conserva el texto de la DGII).
      */
     getNCF(rnc: string, ncf: string, options?: NcfQueryOptions): Promise<NcfQueryResult>;
     private _executeWithFallback;

package/dist/client.d.ts

@@ -59,7 +59,11 @@ declare class ConsecutiveBreaker {
 interface ClientOptions {
     /** Tiempo de espera en milisegundos (por defecto: 15000) */
     timeout?: number;
-    /** Habilitar fallback a SOAP (por defecto: true) */
+    /**
+     * Habilitar fallback a SOAP (por defecto: false). La DGII bloqueó el
+     * endpoint SOAP en enero 2025; activarlo solo agrega una petición
+     * inútil tras cada falla del scraping.
+     */
     soapFallback?: boolean;
     /** Opciones de reintentos */
     retry?: Partial<RetryOptions>;
@@ -70,8 +74,9 @@ interface ClientOptions {
 /**
  * Cliente resiliente para consultas a la DGII.
  *
- * Usa web scraping como estrategia principal y SOAP como
- * fallback (con circuit breaker y reintentos automáticos).
+ * Usa web scraping con circuit breaker y reintentos automáticos. El
+ * fallback a SOAP es opcional (`soapFallback: true`) y está apagado por
+ * defecto: la DGII bloqueó ese endpoint en enero 2025.
  */
 declare class DgiiClient {
     private readonly _scraping;
@@ -92,6 +97,11 @@ declare class DgiiClient {
      * @param ncf - NCF o e-NCF a validar
      * @param options - Datos adicionales del e-NCF (`rncComprador`,
      *   `codigoSeguridad`). Se ignoran cuando `ncf` no es un e-NCF válido.
+     *
+     * Para un e-NCF sin `rncComprador` la DGII responde con un mensaje de
+     * campo requerido: `ScrapingClient.getNCF` lanza `DgiiServiceError` y
+     * este método lo envuelve en `AllStrategiesFailedError` tras agotar
+     * reintentos y fallback (el mensaje conserva el texto de la DGII).
      */
     getNCF(rnc: string, ncf: string, options?: NcfQueryOptions): Promise<NcfQueryResult>;
     private _executeWithFallback;

package/dist/client.js

@@ -3,9 +3,9 @@ import {
   DgiiClient,
   isRetryableError,
   withRetry
-} from "./chunk-JV4HWHYP.js";
+} from "./chunk-YV4IPACJ.js";
 import "./chunk-QTN5ZT4P.js";
-import "./chunk-7ILLRYE4.js";
+import "./chunk-LRPZFX62.js";
 import "./chunk-H42U4GI5.js";
 import "./chunk-KW4ZV6FJ.js";
 import "./chunk-D26S6EXD.js";

package/dist/index.cjs

@@ -17,7 +17,7 @@ require('./chunk-2ST6QKHA.cjs');
 
 
 
-var _chunk6ZRPVQPPcjs = require('./chunk-6ZRPVQPP.cjs');
+var _chunkDUKBAJTMcjs = require('./chunk-DUKBAJTM.cjs');
 
 
 
@@ -27,7 +27,7 @@ var _chunkDLB5RJ7Ecjs = require('./chunk-DLB5RJ7E.cjs');
 
 
 
-var _chunkFRM5XREFcjs = require('./chunk-FRM5XREF.cjs');
+var _chunk6REHWG3Rcjs = require('./chunk-6REHWG3R.cjs');
 
 
 
@@ -69,4 +69,4 @@ var _chunkNASWEFHNcjs = require('./chunk-NASWEFHN.cjs');
 
 
 
-exports.AllStrategiesFailedError = _chunkNASWEFHNcjs.AllStrategiesFailedError; exports.BulkFormatError = _chunkNASWEFHNcjs.BulkFormatError; exports.ConsecutiveBreaker = _chunk6ZRPVQPPcjs.ConsecutiveBreaker; exports.DGII_BULK_URL = _chunkVIZWYFHPcjs.DGII_BULK_URL; exports.DGII_ESTADOS = _chunkVIZWYFHPcjs.DGII_ESTADOS; exports.DGII_NCF_URL = _chunkFRM5XREFcjs.DGII_NCF_URL; exports.DGII_RNC_URL = _chunkFRM5XREFcjs.DGII_RNC_URL; exports.DGII_SOAP_BASE_URL = _chunkDLB5RJ7Ecjs.DGII_SOAP_BASE_URL; exports.DgiiClient = _chunk6ZRPVQPPcjs.DgiiClient; exports.DgiiConnectionError = _chunkNASWEFHNcjs.DgiiConnectionError; exports.DgiiError = _chunkNASWEFHNcjs.DgiiError; exports.DgiiNotFoundError = _chunkNASWEFHNcjs.DgiiNotFoundError; exports.DgiiServiceError = _chunkNASWEFHNcjs.DgiiServiceError; exports.DgiiSoapClient = _chunkDLB5RJ7Ecjs.DgiiSoapClient; exports.ECF_TYPE_NAMES = _chunkOSGHCQFAcjs.ECF_TYPE_NAMES; exports.NCF_TYPE_NAMES = _chunkUW6W2JHWcjs.NCF_TYPE_NAMES; exports.SOAP_ACTIONS = _chunkDLB5RJ7Ecjs.SOAP_ACTIONS; exports.ScrapingClient = _chunkFRM5XREFcjs.ScrapingClient; exports.downloadBulkFile = _chunkVIZWYFHPcjs.downloadBulkFile; exports.isRetryableError = _chunk6ZRPVQPPcjs.isRetryableError; exports.parseBulkFile = _chunkVIZWYFHPcjs.parseBulkFile; exports.validateCedula = _chunkUW6W2JHWcjs.validateCedula; exports.validateEcf = _chunkOSGHCQFAcjs.validateEcf; exports.validateNcf = _chunkUW6W2JHWcjs.validateNcf; exports.validateRnc = _chunkUW6W2JHWcjs.validateRnc; exports.withRetry = _chunk6ZRPVQPPcjs.withRetry;
+exports.AllStrategiesFailedError = _chunkNASWEFHNcjs.AllStrategiesFailedError; exports.BulkFormatError = _chunkNASWEFHNcjs.BulkFormatError; exports.ConsecutiveBreaker = _chunkDUKBAJTMcjs.ConsecutiveBreaker; exports.DGII_BULK_URL = _chunkVIZWYFHPcjs.DGII_BULK_URL; exports.DGII_ESTADOS = _chunkVIZWYFHPcjs.DGII_ESTADOS; exports.DGII_NCF_URL = _chunk6REHWG3Rcjs.DGII_NCF_URL; exports.DGII_RNC_URL = _chunk6REHWG3Rcjs.DGII_RNC_URL; exports.DGII_SOAP_BASE_URL = _chunkDLB5RJ7Ecjs.DGII_SOAP_BASE_URL; exports.DgiiClient = _chunkDUKBAJTMcjs.DgiiClient; exports.DgiiConnectionError = _chunkNASWEFHNcjs.DgiiConnectionError; exports.DgiiError = _chunkNASWEFHNcjs.DgiiError; exports.DgiiNotFoundError = _chunkNASWEFHNcjs.DgiiNotFoundError; exports.DgiiServiceError = _chunkNASWEFHNcjs.DgiiServiceError; exports.DgiiSoapClient = _chunkDLB5RJ7Ecjs.DgiiSoapClient; exports.ECF_TYPE_NAMES = _chunkOSGHCQFAcjs.ECF_TYPE_NAMES; exports.NCF_TYPE_NAMES = _chunkUW6W2JHWcjs.NCF_TYPE_NAMES; exports.SOAP_ACTIONS = _chunkDLB5RJ7Ecjs.SOAP_ACTIONS; exports.ScrapingClient = _chunk6REHWG3Rcjs.ScrapingClient; exports.downloadBulkFile = _chunkVIZWYFHPcjs.downloadBulkFile; exports.isRetryableError = _chunkDUKBAJTMcjs.isRetryableError; exports.parseBulkFile = _chunkVIZWYFHPcjs.parseBulkFile; exports.validateCedula = _chunkUW6W2JHWcjs.validateCedula; exports.validateEcf = _chunkOSGHCQFAcjs.validateEcf; exports.validateNcf = _chunkUW6W2JHWcjs.validateNcf; exports.validateRnc = _chunkUW6W2JHWcjs.validateRnc; exports.withRetry = _chunkDUKBAJTMcjs.withRetry;

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   DgiiClient,
   isRetryableError,
   withRetry
-} from "./chunk-JV4HWHYP.js";
+} from "./chunk-YV4IPACJ.js";
 import {
   DGII_SOAP_BASE_URL,
   DgiiSoapClient,
@@ -27,7 +27,7 @@ import {
   DGII_NCF_URL,
   DGII_RNC_URL,
   ScrapingClient
-} from "./chunk-7ILLRYE4.js";
+} from "./chunk-LRPZFX62.js";
 import {
   ECF_TYPE_NAMES,
   validateEcf

package/dist/scraping.cjs

@@ -4,7 +4,7 @@
 
 
 
-var _chunkFRM5XREFcjs = require('./chunk-FRM5XREF.cjs');
+var _chunk6REHWG3Rcjs = require('./chunk-6REHWG3R.cjs');
 require('./chunk-OSGHCQFA.cjs');
 require('./chunk-WMFHPNFP.cjs');
 require('./chunk-QH4BK5X3.cjs');
@@ -14,4 +14,4 @@ require('./chunk-NASWEFHN.cjs');
 
 
 
-exports.DGII_NCF_URL = _chunkFRM5XREFcjs.DGII_NCF_URL; exports.DGII_RNC_URL = _chunkFRM5XREFcjs.DGII_RNC_URL; exports.FORM_FIELDS = _chunkFRM5XREFcjs.FORM_FIELDS; exports.ScrapingClient = _chunkFRM5XREFcjs.ScrapingClient;
+exports.DGII_NCF_URL = _chunk6REHWG3Rcjs.DGII_NCF_URL; exports.DGII_RNC_URL = _chunk6REHWG3Rcjs.DGII_RNC_URL; exports.FORM_FIELDS = _chunk6REHWG3Rcjs.FORM_FIELDS; exports.ScrapingClient = _chunk6REHWG3Rcjs.ScrapingClient;

package/dist/scraping.js

@@ -4,7 +4,7 @@ import {
   DGII_RNC_URL,
   FORM_FIELDS,
   ScrapingClient
-} from "./chunk-7ILLRYE4.js";
+} from "./chunk-LRPZFX62.js";
 import "./chunk-H42U4GI5.js";
 import "./chunk-KW4ZV6FJ.js";
 import "./chunk-D26S6EXD.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dgii-ts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Librería TypeScript para validación e integración con la DGII de República Dominicana — RNC, Cédula, NCF, e-NCF",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -80,7 +80,8 @@
   },
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsup",

package/skills/dgii-ts/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: dgii-ts
+description: Write correct TypeScript or JavaScript with the dgii-ts library for Dominican Republic tax data from the DGII (Dirección General de Impuestos Internos). Covers validating RNC and cédula numbers, checking NCF and e-NCF (e-CF) invoice numbers, looking up taxpayers (contribuyentes) live, verifying an e-NCF's status, and importing the DGII_RNC.zip taxpayer registry. Use this whenever code touches RNC, cédula, NCF, e-NCF, comprobantes fiscales, facturación electrónica, or Dominican tax IDs, even if the user never names dgii-ts, and before writing any mod-11 or Luhn check or any DGII scraper by hand.
+---
+
+# dgii-ts
+
+dgii-ts validates Dominican tax identifiers offline and queries the DGII
+online. Most mistakes with it come from three misunderstandings: treating
+an offline `valid: true` as "DGII confirmed this", using the wrong entry
+point for live queries, and handling errors in a way that either hides
+real outages or hammers DGII's servers. This skill exists to prevent
+those.
+
+If the project does not depend on it yet: `npm install dgii-ts`
+(Node 18 or later).
+
+## Pick the entry point
+
+| Need | Use | Network |
+| --- | --- | --- |
+| Is this RNC, cédula, NCF or e-NCF well formed? (forms, imports, and always before a live lookup) | `validateRnc`, `validateCedula`, `validateNcf`, `validateEcf` from `dgii-ts/validators` | none |
+| Does DGII know this taxpayer, what is its name and status? Is this invoice number real? | one shared `DgiiClient` from `dgii-ts/client` | DGII web pages |
+| Many RNCs at once, an offline copy of the registry, search by name | `downloadBulkFile` and `parseBulkFile` from `dgii-ts/bulk` | one ~23 MB download |
+
+Three things the library also exports that you should not reach for:
+
+- `DgiiSoapClient` (`dgii-ts/soap`) is deprecated. DGII shut the SOAP
+  service off in January 2025 and it currently answers without data.
+- `ScrapingClient` (`dgii-ts/scraping`) is the low-level layer that
+  `DgiiClient` wraps. Used directly it has no retries and no circuit
+  breaker.
+- Hand-written check digits or regexes. DGII has real identifiers that
+  fail the checksum; the validators carry a whitelist of them, so a
+  hand-rolled mod-11 or Luhn rejects real taxpayers.
+
+## Offline validators
+
+```ts
+import { validateRnc, validateCedula, validateNcf, validateEcf } from 'dgii-ts/validators';
+
+validateRnc('131-09819-3');   // { valid: true, formatted: '1-31-09819-3' }
+validateCedula('00114272360'); // { valid: true, formatted: '001-1427236-0' }
+validateNcf('b0100000001');   // { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }
+validateEcf('E310000000001'); // { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }
+validateRnc('131098194');     // { valid: false }
+```
+
+- **`valid: true` only means well formed.** It does not mean the RNC is
+  registered or active, or that the NCF was ever issued or belongs to that
+  issuer. Only `DgiiClient` can say that. Word UI messages accordingly
+  ("invalid format" vs "not registered with DGII").
+- RNC and cédula: every non-digit is stripped first, so dashes and spaces
+  are fine. RNC is 9 digits (mod-11), cédula is 11 digits (Luhn).
+  `formatted` is `X-XX-XXXXX-X` or `XXX-XXXXXXX-X`.
+- NCF and e-NCF: only uppercased and trimmed; separators are **not**
+  stripped, so `B01-00000001` is invalid. NCF is `B` + 2-digit type + 8
+  digits (11 chars). e-NCF is `E` + 2-digit type + 10 digits (13 chars).
+  Unknown type codes are invalid. Valid NCF types: 01, 02, 03, 04, 11,
+  12, 13, 14, 15, 16, 17. Valid e-NCF types: 31, 32, 33, 34, 41, 43, 44,
+  45, 46, 47. `NCF_TYPE_NAMES` and `ECF_TYPE_NAMES` (exported from the
+  same subpath, keyed by the 2-digit code) give Spanish display names.
+- Non-string input returns `{ valid: false }` and never throws, so the
+  validators are safe on raw form data.
+- The result is a discriminated union: check `valid` before reading
+  `formatted`, `type` or `serie`.
+- A Dominican taxpayer ID is either an RNC (companies, 9 digits) or a
+  cédula (people, 11 digits). A field that accepts "RNC o cédula" should
+  accept either validator's `valid: true`. `getContribuyente` accepts
+  both.
+- Store the digits (`value.replace(/\D/g, '')`) and use `formatted` for
+  display.
+
+## Live lookups with DgiiClient
+
+Run it on the server. DGII's pages send no CORS headers, so a browser
+cannot call them; use an API route, server action or backend job.
+
+Create **one** client and reuse it:
+
+```ts
+// dgii.ts
+import { DgiiClient } from 'dgii-ts/client';
+
+export const dgii = new DgiiClient({ soapFallback: false });
+```
+
+Retry and circuit-breaker state live inside the instance. A new client per
+request never trips its breaker, so during a DGII outage every request
+keeps hitting DGII. `soapFallback` is `false` by default from dgii-ts
+0.3.0; older versions default to `true`, so pass `false` explicitly. The
+SOAP service is shut off: the fallback only adds a wasted request after
+every failed lookup, and an empty SOAP reply would be reported as
+`DgiiNotFoundError`, making an outage look like "not registered". Do not
+turn it on.
+
+Options and defaults: `timeout` 15000 ms (clamped to 1 to 120 s);
+`retry: { maxRetries: 2, baseDelayMs: 500, maxDelayMs: 10000 }`
+(exponential backoff with jitter); `circuitBreaker: { failureThreshold: 5,
+recoveryTimeoutMs: 60000, successThreshold: 2 }`. Pass partial objects;
+the rest keeps its default.
+
+### Taxpayer: `getContribuyente(rncOrCedula)`
+
+```ts
+import type { Contribuyente } from 'dgii-ts';
+import { DgiiNotFoundError } from 'dgii-ts/errors';
+
+async function findTaxpayer(digits: string): Promise<Contribuyente | null> {
+  try {
+    return await dgii.getContribuyente(digits);
+  } catch (err) {
+    // Not registered with DGII: a normal answer, not an outage
+    if (err instanceof DgiiNotFoundError) return null;
+    throw err;
+  }
+}
+```
+
+A `Contribuyente` has `rnc` (digits only), `nombre`, `nombreComercial`,
+`estado`, `categoria`, `esFacturadorElectronico`, and the optional
+`actividadEconomica`, `regimenDePagos` and `administracionLocal`.
+
+- `estado` is `'ACTIVO'` or `'INACTIVO'`. Every other DGII status
+  (suspended, cancelled, and so on) is reported as `'INACTIVO'`.
+- An unregistered RNC or cédula **throws** `DgiiNotFoundError`. It is not
+  retried and does not count against the circuit breaker.
+- Pass the digits you validated, not user input as typed.
+
+### Invoice number: `getNCF(rncEmisor, ncf, options?)`
+
+For a B-series NCF:
+
+```ts
+const r = await dgii.getNCF('131098193', 'B0100000001');
+// found:     { valid: true, rnc, ncf, nombreComercial? }
+// not found: { valid: false, rnc: '', ncf: '' } (other fields undefined)
+```
+
+Unlike `getContribuyente`, a missing or invalid NCF does **not** throw; it
+returns `valid: false`.
+
+For an e-NCF (E-series), DGII needs the buyer's RNC **and** the 6-character
+security code printed on the invoice. The types mark both optional because
+B-series lookups ignore them, but without either one DGII refuses to answer
+and `DgiiClient` throws `AllStrategiesFailedError` whose message contains
+DGII's "es necesario completar el campo..." text.
+
+```ts
+const e = await dgii.getNCF('101010632', 'E310125217173', {
+  rncComprador: '131262414',
+  codigoSeguridad: 'KrOLI0',
+});
+// { valid: true, rnc: '101010632', ncf: 'E310125217173',
+//   rncComprador: '131262414', codigoSeguridad: 'KrOLI0',
+//   estado: 'Aceptado', montoTotal: 230677.74, totalItbis: 35188.13,
+//   fechaEmision: '2026-02-11', fechaFirma: '2026-02-11' }
+```
+
+- For an e-NCF, `valid: true` means DGII **found** it, not that it is
+  accepted. Check `estado`.
+- A wrong security code gives `valid: false`.
+- `montoTotal` and `totalItbis` are numbers; `fechaEmision` and
+  `fechaFirma` are strings exactly as DGII shows them.
+- The library decides "e-NCF or not" with `validateEcf`, so run the
+  offline validator first and only pass the options for an e-NCF.
+- DGII also accepts a foreign ID in place of the buyer's RNC, but the
+  library has no option for it.
+
+## Errors
+
+`DgiiClient` only ever throws two things:
+
+| Error (`code`) | Meaning | What to do |
+| --- | --- | --- |
+| `DgiiNotFoundError` (`DGII_NOT_FOUND`) | `getContribuyente`: DGII has no such RNC or cédula | Tell the user it is not registered. Do not retry. |
+| `AllStrategiesFailedError` (`DGII_ALL_STRATEGIES_FAILED`) | Everything else, after the built-in retries: network down, timeout, DGII HTTP error, circuit open, DGII page changed, missing e-NCF fields, empty input | Report "DGII is unavailable, try later" and log `err.errors` (one error per strategy tried; `err.cause` is the first). |
+
+The underlying `DgiiConnectionError` (`DGII_CONNECTION_ERROR`) and
+`DgiiServiceError` (`DGII_SERVICE_ERROR`, with optional `statusCode`) are
+inside `err.errors`; they are only thrown directly by the low-level
+clients. `BulkFormatError` (`DGII_BULK_FORMAT_ERROR`) comes from
+`parseBulkFile`. All of them extend `DgiiError` and are exported from
+`dgii-ts/errors` (and the root). Matching on `err.code` also works when
+`instanceof` cannot, for example when an app loads the package both as
+ESM and as CommonJS.
+
+Do not wrap calls in your own retry loop. The client already retries
+connection errors and HTTP 5xx with backoff, and deliberately does not
+retry 4xx or unexpected pages, because repeating those will not help.
+
+Because empty input and missing e-NCF fields also surface as
+`AllStrategiesFailedError`, validate before calling. Otherwise a
+programming error looks like a DGII outage.
+
+## Be gentle with DGII
+
+DGII publishes no rate limit and these are its public web pages. Each
+lookup is two HTTP requests (load the form, submit it).
+
+- Validate offline first. Never send DGII an identifier that fails the
+  validator.
+- Share one client (above).
+- Cache results. Taxpayer names and statuses rarely change within a day.
+- For batches, go one at a time or with very low concurrency. For more
+  than a few dozen RNCs, use the bulk file instead of live lookups.
+- Keep the default retry and circuit-breaker settings unless you have a
+  measured reason; raising retries multiplies load during an outage.
+
+## Bulk registry: DGII_RNC.zip
+
+Node only (it uses `node:https` and `node:fs`).
+
+The library downloads the ZIP but does not unzip it, and it has no zip
+dependency. Extract the single entry `TMP/DGII_RNC.TXT` with the zip tool
+the project already uses, or `adm-zip` (`npm install adm-zip`, plus
+`@types/adm-zip` for TypeScript):
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import AdmZip from 'adm-zip';
+import { downloadBulkFile, parseBulkFile } from 'dgii-ts/bulk';
+
+const zipPath = await downloadBulkFile({ outputDir: '/var/data/dgii' });
+
+const entry = new AdmZip(zipPath).getEntry('TMP/DGII_RNC.TXT');
+if (!entry) throw new Error('DGII_RNC.zip no longer contains TMP/DGII_RNC.TXT');
+const txtPath = '/var/data/dgii/DGII_RNC.TXT';
+await writeFile(txtPath, entry.getData());
+
+const rows = await parseBulkFile({ filePath: txtPath });
+const byRnc = new Map(rows.map((row) => [row.rnc, row]));
+```
+
+- `downloadBulkFile` writes `<outputDir>/DGII_RNC.zip` (overwriting it) and
+  returns that path, relative if `outputDir` was relative. `timeout`
+  defaults to 60 s (clamped 5 s to 10 min). It rejects with a plain
+  `Error`, not a `DgiiError`.
+- The ZIP holds one file, `TMP/DGII_RNC.TXT`: about 90 MB, pipe-delimited,
+  latin-1. The parser defaults to `latin1`; do not pass `utf8` or names
+  like MUÑOZ get corrupted.
+- `parseBulkFile` returns the whole registry as one array (about 790,000
+  rows in September 2026, roughly 0.5 GB of memory at peak). Load it in a
+  scheduled job and write it to a database or index; do not parse it per
+  request.
+- To check a list (suppliers, customers), validate each ID with
+  `validateRnc` **or** `validateCedula` (people appear by cédula), report
+  the ones that fail as bad format rather than "not registered", and look
+  the rest up by their digits.
+- Each row: `rnc` (bare digits: 9 for an RNC, 11 for a cédula), `nombre`,
+  `nombreComercial`, `actividad` (DGII truncates it), `estado`, `regimen`,
+  `fechaConstitucion` (`dd/mm/yyyy` or empty).
+- Bulk `estado` is DGII's full vocabulary, `DGII_ESTADOS`: `ACTIVO`,
+  `SUSPENDIDO`, `DADO DE BAJA`, `CESE TEMPORAL`, `ANULADO`, `RECHAZADO`.
+  That is not comparable with `getContribuyente`'s `ACTIVO`/`INACTIVO`.
+- Rows without exactly 11 columns are skipped. If most sampled rows have
+  an unknown `estado`, it throws `BulkFormatError`: DGII changed the
+  layout, so fail loudly rather than import garbage.
+
+## Imports
+
+| Subpath | Contents | Runs in |
+| --- | --- | --- |
+| `dgii-ts/validators` | the four validators, `NCF_TYPE_NAMES`, `ECF_TYPE_NAMES` | anywhere, including the browser |
+| `dgii-ts/client` | `DgiiClient` | server (Node 18+) |
+| `dgii-ts/errors` | the error classes | anywhere |
+| `dgii-ts/bulk` | `downloadBulkFile`, `parseBulkFile`, `DGII_ESTADOS`, `DGII_BULK_URL` | Node |
+| `dgii-ts` | everything above plus the low-level clients | server |
+
+Types (`ValidationResult`, `NcfValidationResult`, `Contribuyente`,
+`NcfQueryOptions`, `NcfQueryResult`, `BulkContribuyente`, `ClientOptions`)
+are exported from the root. Both ESM `import` and CommonJS `require` work.
+In client-side bundles import from `dgii-ts/validators` only.