dgii-ts 0.1.0 → 0.1.1

package/README.en.md

@@ -19,11 +19,13 @@ basic RNC or NCF lookups. Dominican developers rely on fragile scrapers that
 parse ASP.NET WebForms pages with ViewState — and those pages have changed URLs
 at least three times, breaking every existing integration.
 
-**dgii-ts** solves this with a three-layer approach designed for resilience:
+**dgii-ts** solves this with a four-layer approach designed for resilience:
 
 1. **Offline validation** — never fails, zero network calls
-2. **SOAP client** — real-time queries against the WSMovilDGII service
-3. **Bulk data** — import DGII's daily bulk RNC file (DGII\_RNC.zip)
+2. **Web scraping** — real-time queries against DGII's ASP.NET pages
+3. **SOAP client** *(deprecated)* — WSMovilDGII wrapper, blocked by
+   DGII since January 2025
+4. **Bulk data** — import DGII's daily bulk RNC file (DGII\_RNC.zip)
 
 ## Features
 
@@ -35,11 +37,23 @@ points of failure. Includes whitelists of 578 Cedulas and 23 RNCs
 (source: [python-stdnum](https://github.com/arthurdejong/python-stdnum))
 that pass validation despite failing the check-digit algorithm.
 
-### SOAP client (WSMovilDGII)
+### Resilient client (DgiiClient)
 
-Typed wrapper around DGII's SOAP service for taxpayer lookups
-(`GetContribuyentes`) and fiscal receipt validation (`GetNCF`). Includes
-full TypeScript types for all responses.
+`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
+
+Queries DGII's ASP.NET pages by extracting ViewState tokens and parsing
+response HTML. This is the primary strategy since DGII blocked the SOAP
+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.
 
 ### Bulk data importer
 
@@ -104,22 +118,26 @@ const result = validateEcf('E310000000001');
 import { validateRnc } from 'dgii-ts/validators';
 ```
 
-Available submodules: `dgii-ts/validators`, `dgii-ts/soap`, and
-`dgii-ts/bulk`.
-
-### Look up a taxpayer (SOAP) — *coming soon*
+Available submodules: `dgii-ts/validators`, `dgii-ts/client`,
+`dgii-ts/scraping`, `dgii-ts/soap`, `dgii-ts/bulk`, and `dgii-ts/errors`.
 
-> **Note:** The SOAP client is not yet implemented. The interface is defined
-> and will be available in a future release.
+### Look up a taxpayer
 
 ```typescript
-import { DgiiSoapClient } from 'dgii-ts';
+import { DgiiClient } from 'dgii-ts/client';
 
-const client = new DgiiSoapClient();
+const client = new DgiiClient();
 const result = await client.getContribuyente('131098193');
 // { rnc: '131098193', nombre: '...', estado: '...', ... }
 ```
 
+### Validate an NCF online
+
+```typescript
+const ncfResult = await client.getNCF('131098193', 'B0100000001');
+// { rnc: '131098193', ncf: 'B0100000001', estado: '...', ... }
+```
+
 ## API reference
 
 ### Validators
@@ -131,20 +149,36 @@ const result = await client.getContribuyente('131098193');
 | `validateNcf(value)` | Validates NCF format and type (B-series) |
 | `validateEcf(value)` | Validates e-NCF format and type (E-series) |
 
-### SOAP client
+### Resilient client
 
 | Class/Method | Description |
 | --- | --- |
-| `DgiiSoapClient` | Typed client for WSMovilDGII |
+| `DgiiClient` | Scraping + SOAP fallback, circuit breaker, retry |
 | `client.getContribuyente(rnc)` | Looks up taxpayer data by RNC |
 | `client.getNCF(rnc, ncf)` | Validates a fiscal receipt against DGII |
 
+### Scraping
+
+| Class/Method | Description |
+| --- | --- |
+| `ScrapingClient` | Queries DGII's ASP.NET pages |
+| `client.getContribuyente(rnc)` | Looks up taxpayer data by RNC |
+| `client.getNCF(rnc, ncf)` | Validates a fiscal receipt |
+
+### SOAP client (deprecated)
+
+| Class/Method | Description |
+| --- | --- |
+| `DgiiSoapClient` | WSMovilDGII client (blocked) |
+| `client.getContribuyente(rnc)` | Looks up taxpayer data by RNC |
+| `client.getNCF(rnc, ncf)` | Validates a fiscal receipt |
+
 ### Bulk data
 
 | Class/Method | Description |
 | --- | --- |
-| `downloadBulkFile(path)` | Downloads DGII\_RNC.zip to the given directory |
-| `parseBulkFile(path)` | Parses the taxpayer TXT file |
+| `downloadBulkFile(options)` | Downloads DGII\_RNC.zip to the given directory |
+| `parseBulkFile(options)` | Parses the taxpayer TXT file |
 
 ## Architecture
 
@@ -155,8 +189,9 @@ const result = await client.getContribuyente('131098193');
 │  Layer 1: Offline validation                    │
 │  ✓ RNC/Cedula check-digit  ✓ NCF/e-NCF format  │
 ├─────────────────────────────────────────────────┤
-│  Layer 2: SOAP client (WSMovilDGII)             │
-│  ✓ Taxpayer lookup  ✓ NCF validation            │
+│  Layer 2: DgiiClient (resilient)                │
+│  ✓ Web scraping (primary)                       │
+│  ✓ SOAP fallback  ✓ Circuit breaker  ✓ Retry   │
 ├─────────────────────────────────────────────────┤
 │  Layer 3: Bulk data (DGII_RNC.zip)              │
 │  ✓ Daily download  ✓ TXT parsing                │
@@ -164,15 +199,18 @@ const result = await client.getContribuyente('131098193');
 ```
 
 **Layer 1** is instant and works offline. **Layer 2** provides real-time data
-for recently registered taxpayers. **Layer 3** is ideal for batch operations
-where you need to look up thousands of RNCs quickly.
+using web scraping as the primary strategy, with SOAP fallback, 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
 
 - [x] Offline validation (RNC, Cedula, NCF, e-NCF)
-- [ ] SOAP client (WSMovilDGII)
-- [ ] Bulk data importer (DGII\_RNC.zip)
-- [ ] CLI tool
+- [x] Web scraping of DGII's ASP.NET pages
+- [x] SOAP client WSMovilDGII (deprecated — blocked by DGII)
+- [x] Resilient client with circuit breaker and retry
+- [x] Bulk data importer (download + parsing)
+- [x] Published on npm
 
 ## Security
 

package/README.md

@@ -20,12 +20,15 @@ dependen de scrapers frágiles que parsean páginas ASP.NET con ViewState — y
 esas páginas han cambiado de URL al menos tres veces, rompiendo cada integración
 existente.
 
-**dgii-ts** resuelve esto con un enfoque de tres capas diseñado para
+**dgii-ts** resuelve esto con un enfoque de cuatro capas diseñado para
 resiliencia:
 
 1. **Validación offline** — nunca falla, cero llamadas de red
-2. **Cliente SOAP** — consultas en tiempo real contra el servicio WSMovilDGII
-3. **Datos masivos** — importación del archivo diario DGII\_RNC.zip
+2. **Web scraping** — consultas en tiempo real contra las páginas
+   ASP.NET de la DGII
+3. **Cliente SOAP** *(deprecated)* — wrapper del servicio WSMovilDGII,
+   bloqueado por la DGII en enero 2025
+4. **Datos masivos** — importación del archivo diario DGII\_RNC.zip
 
 ## Características
 
@@ -37,11 +40,23 @@ puntos de fallo externos. Incluye whitelists de 578 cédulas y 23 RNCs
 (fuente: [python-stdnum](https://github.com/arthurdejong/python-stdnum)) que
 pasan validación aunque no cumplan el algoritmo de dígito verificador.
 
-### Cliente SOAP (WSMovilDGII)
+### Cliente resiliente (DgiiClient)
 
-Wrapper tipado alrededor del servicio SOAP de la DGII para consultas de
-contribuyentes (`GetContribuyentes`) y validación de comprobantes fiscales
-(`GetNCF`). Incluye tipos TypeScript completos para todas las respuestas.
+`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.
+
+### Web scraping
+
+Consulta las páginas ASP.NET de la DGII extrayendo tokens ViewState y
+parseando el HTML de respuesta. Es la estrategia principal desde que la DGII
+bloqueó el endpoint SOAP en enero 2025.
+
+### Cliente SOAP (WSMovilDGII) — deprecated
+
+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.
 
 ### Importador de datos masivos
 
@@ -106,22 +121,26 @@ const result = validateEcf('E310000000001');
 import { validateRnc } from 'dgii-ts/validators';
 ```
 
-Los submódulos disponibles son `dgii-ts/validators`, `dgii-ts/soap` y
-`dgii-ts/bulk`.
-
-### Consultar contribuyente (SOAP) — *pendiente*
+Los submódulos disponibles son `dgii-ts/validators`, `dgii-ts/client`,
+`dgii-ts/scraping`, `dgii-ts/soap`, `dgii-ts/bulk` y `dgii-ts/errors`.
 
-> **Nota:** El cliente SOAP aún no está implementado. La interfaz está definida
-> y estará disponible en una futura versión.
+### Consultar contribuyente
 
 ```typescript
-import { DgiiSoapClient } from 'dgii-ts';
+import { DgiiClient } from 'dgii-ts/client';
 
-const client = new DgiiSoapClient();
+const client = new DgiiClient();
 const result = await client.getContribuyente('131098193');
 // { rnc: '131098193', nombre: '...', estado: '...', ... }
 ```
 
+### Validar NCF en línea
+
+```typescript
+const ncfResult = await client.getNCF('131098193', 'B0100000001');
+// { rnc: '131098193', ncf: 'B0100000001', estado: '...', ... }
+```
+
 ## Referencia del API
 
 ### Validadores
@@ -133,20 +152,36 @@ const result = await client.getContribuyente('131098193');
 | `validateNcf(value)` | Valida formato y tipo de NCF (serie B) |
 | `validateEcf(value)` | Valida formato y tipo de e-NCF (serie E) |
 
-### Cliente SOAP
+### Cliente resiliente
 
 | Clase/Método | Descripción |
 | --- | --- |
-| `DgiiSoapClient` | Cliente tipado para WSMovilDGII |
+| `DgiiClient` | Cliente con scraping + SOAP fallback, circuit breaker y retry |
 | `client.getContribuyente(rnc)` | Consulta datos de un contribuyente por RNC |
 | `client.getNCF(rnc, ncf)` | Valida un comprobante fiscal contra la DGII |
 
+### Scraping
+
+| Clase/Método | Descripción |
+| --- | --- |
+| `ScrapingClient` | Consulta páginas ASP.NET de la DGII |
+| `client.getContribuyente(rnc)` | Consulta contribuyente por RNC |
+| `client.getNCF(rnc, ncf)` | Valida comprobante fiscal |
+
+### Cliente SOAP (deprecated)
+
+| Clase/Método | Descripción |
+| --- | --- |
+| `DgiiSoapClient` | Cliente para WSMovilDGII (bloqueado) |
+| `client.getContribuyente(rnc)` | Consulta contribuyente por RNC |
+| `client.getNCF(rnc, ncf)` | Valida comprobante fiscal |
+
 ### Datos masivos
 
 | Clase/Método | Descripción |
 | --- | --- |
-| `downloadBulkFile(path)` | Descarga DGII\_RNC.zip al directorio especificado |
-| `parseBulkFile(path)` | Parsea el archivo TXT de contribuyentes |
+| `downloadBulkFile(options)` | Descarga DGII\_RNC.zip |
+| `parseBulkFile(options)` | Parsea el archivo TXT |
 
 ## Arquitectura
 
@@ -157,8 +192,9 @@ const result = await client.getContribuyente('131098193');
 │  Capa 1: Validación offline                     │
 │  ✓ Check-digit RNC/Cédula  ✓ Formato NCF/e-NCF │
 ├─────────────────────────────────────────────────┤
-│  Capa 2: Cliente SOAP (WSMovilDGII)             │
-│  ✓ Consulta contribuyentes  ✓ Validación NCF   │
+│  Capa 2: DgiiClient (resiliente)                │
+│  ✓ Web scraping (primario)                      │
+│  ✓ SOAP fallback  ✓ Circuit breaker  ✓ Retry   │
 ├─────────────────────────────────────────────────┤
 │  Capa 3: Datos masivos (DGII_RNC.zip)           │
 │  ✓ Descarga diaria  ✓ Parseo TXT               │
@@ -166,15 +202,18 @@ const result = await client.getContribuyente('131098193');
 ```
 
 La **capa 1** es instantánea y funciona sin conexión. La **capa 2** ofrece
-datos en tiempo real para contribuyentes recién registrados. La **capa 3** es
+datos en tiempo real con web scraping como estrategia primaria, fallback a
+SOAP, 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
 
 - [x] Validación offline (RNC, cédula, NCF, e-NCF)
-- [ ] Cliente SOAP WSMovilDGII
-- [ ] Importador DGII\_RNC.zip
-- [ ] Herramienta CLI
+- [x] Web scraping de las páginas ASP.NET de la DGII
+- [x] Cliente SOAP WSMovilDGII (deprecated — bloqueado por la DGII)
+- [x] Cliente resiliente con circuit breaker y retry
+- [x] Importador DGII\_RNC.zip (descarga + parseo)
+- [x] Publicado en npm
 
 ## Seguridad
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dgii-ts",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -48,16 +48,34 @@
       }
     },
     "./scraping": {
-      "import": { "types": "./dist/scraping.d.ts", "default": "./dist/scraping.js" },
-      "require": { "types": "./dist/scraping.d.cts", "default": "./dist/scraping.cjs" }
+      "import": {
+        "types": "./dist/scraping.d.ts",
+        "default": "./dist/scraping.js"
+      },
+      "require": {
+        "types": "./dist/scraping.d.cts",
+        "default": "./dist/scraping.cjs"
+      }
     },
     "./client": {
-      "import": { "types": "./dist/client.d.ts", "default": "./dist/client.js" },
-      "require": { "types": "./dist/client.d.cts", "default": "./dist/client.cjs" }
+      "import": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      },
+      "require": {
+        "types": "./dist/client.d.cts",
+        "default": "./dist/client.cjs"
+      }
     },
     "./errors": {
-      "import": { "types": "./dist/errors.d.ts", "default": "./dist/errors.js" },
-      "require": { "types": "./dist/errors.d.cts", "default": "./dist/errors.cjs" }
+      "import": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.js"
+      },
+      "require": {
+        "types": "./dist/errors.d.cts",
+        "default": "./dist/errors.cjs"
+      }
     }
   },
   "sideEffects": false,