dgii-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franklin Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,192 @@
+# dgii-ts
+
+[![npm version](https://img.shields.io/npm/v/dgii-ts.svg)](https://www.npmjs.com/package/dgii-ts)
+[![CI](https://github.com/franklinmdev/dgii-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/franklinmdev/dgii-ts/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+
+TypeScript library for validation and integration with the Dominican Republic's
+tax authority (DGII) — RNC, Cedula, NCF, e-NCF.
+
+[🇩🇴 Español](./README.md)
+
+---
+
+## Why?
+
+The Dominican Republic's tax authority (DGII) offers no public REST API for
+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:
+
+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)
+
+## Features
+
+### Offline validation
+
+Algorithmic check-digit validation for RNC (9 digits), Cedula (11 digits),
+NCF (B-series), and e-NCF (E-series). No network dependencies, no external
+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)
+
+Typed wrapper around DGII's SOAP service for taxpayer lookups
+(`GetContribuyentes`) and fiscal receipt validation (`GetNCF`). Includes
+full TypeScript types for all responses.
+
+### Bulk data importer
+
+Downloads and parses the daily taxpayer ZIP file published by DGII
+(`DGII_RNC.zip`). Ideal for batch operations and fast local lookups.
+
+## Installation
+
+```bash
+npm install dgii-ts
+```
+
+```bash
+pnpm add dgii-ts
+```
+
+```bash
+yarn add dgii-ts
+```
+
+## Quick start
+
+### Validate an RNC
+
+```typescript
+import { validateRnc } from 'dgii-ts';
+
+const result = validateRnc('131098193');
+// { valid: true, formatted: '1-31-09819-3' }
+```
+
+### Validate a Cedula
+
+```typescript
+import { validateCedula } from 'dgii-ts';
+
+const result = validateCedula('00114272360');
+// { valid: true, formatted: '001-1427236-0' }
+```
+
+### Validate an NCF
+
+```typescript
+import { validateNcf } from 'dgii-ts';
+
+const result = validateNcf('B0100000001');
+// { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }
+```
+
+### Validate an e-NCF
+
+```typescript
+import { validateEcf } from 'dgii-ts';
+
+const result = validateEcf('E310000000001');
+// { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }
+```
+
+### Import only validators (tree-shaking)
+
+```typescript
+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*
+
+> **Note:** The SOAP client is not yet implemented. The interface is defined
+> and will be available in a future release.
+
+```typescript
+import { DgiiSoapClient } from 'dgii-ts';
+
+const client = new DgiiSoapClient();
+const result = await client.getContribuyente('131098193');
+// { rnc: '131098193', nombre: '...', estado: '...', ... }
+```
+
+## API reference
+
+### Validators
+
+| Function | Description |
+| --- | --- |
+| `validateRnc(value)` | Validates a 9-digit RNC with check digit |
+| `validateCedula(value)` | Validates an 11-digit Cedula with check digit |
+| `validateNcf(value)` | Validates NCF format and type (B-series) |
+| `validateEcf(value)` | Validates e-NCF format and type (E-series) |
+
+### SOAP client
+
+| Class/Method | Description |
+| --- | --- |
+| `DgiiSoapClient` | Typed client for WSMovilDGII |
+| `client.getContribuyente(rnc)` | Looks up taxpayer data by RNC |
+| `client.getNCF(rnc, ncf)` | Validates a fiscal receipt against DGII |
+
+### Bulk data
+
+| Class/Method | Description |
+| --- | --- |
+| `downloadBulkFile(path)` | Downloads DGII\_RNC.zip to the given directory |
+| `parseBulkFile(path)` | Parses the taxpayer TXT file |
+
+## Architecture
+
+```text
+┌─────────────────────────────────────────────────┐
+│               Your application                  │
+├─────────────────────────────────────────────────┤
+│  Layer 1: Offline validation                    │
+│  ✓ RNC/Cedula check-digit  ✓ NCF/e-NCF format  │
+├─────────────────────────────────────────────────┤
+│  Layer 2: SOAP client (WSMovilDGII)             │
+│  ✓ Taxpayer lookup  ✓ NCF validation            │
+├─────────────────────────────────────────────────┤
+│  Layer 3: Bulk data (DGII_RNC.zip)              │
+│  ✓ Daily download  ✓ TXT parsing                │
+└─────────────────────────────────────────────────┘
+```
+
+**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.
+
+## Project status
+
+- [x] Offline validation (RNC, Cedula, NCF, e-NCF)
+- [ ] SOAP client (WSMovilDGII)
+- [ ] Bulk data importer (DGII\_RNC.zip)
+- [ ] CLI tool
+
+## Security
+
+To report vulnerabilities, see [SECURITY.md](./SECURITY.md).
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+## License
+
+[MIT](./LICENSE)
+
+## Disclaimer
+
+This is an independent community library, not affiliated with or endorsed by
+DGII. For critical tax data, always verify with a licensed tax professional.

package/README.md

@@ -0,0 +1,196 @@
+# dgii-ts
+
+[![npm version](https://img.shields.io/npm/v/dgii-ts.svg)](https://www.npmjs.com/package/dgii-ts)
+[![CI](https://github.com/franklinmdev/dgii-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/franklinmdev/dgii-ts/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+
+Librería TypeScript para validación e integración con la DGII de
+República Dominicana — RNC, cédula, NCF, e-NCF.
+
+[🇺🇸 English](./README.en.md)
+
+---
+
+## ¿Por qué?
+
+La Dirección General de Impuestos Internos (DGII) no ofrece un API REST
+público para consultas básicas de RNC o NCF. Los desarrolladores dominicanos
+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
+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
+
+## Características
+
+### Validación offline
+
+Validación algorítmica de dígitos verificadores para RNC (9 dígitos), cédula
+(11 dígitos), NCF (serie B) y e-NCF (serie E). Sin dependencias de red, sin
+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)
+
+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.
+
+### Importador de datos masivos
+
+Descarga y parseo del archivo ZIP diario de contribuyentes que publica la DGII
+(`DGII_RNC.zip`). Ideal para operaciones en lote y búsquedas locales rápidas.
+
+## Instalación
+
+```bash
+npm install dgii-ts
+```
+
+```bash
+pnpm add dgii-ts
+```
+
+```bash
+yarn add dgii-ts
+```
+
+## Uso rápido
+
+### Validar un RNC
+
+```typescript
+import { validateRnc } from 'dgii-ts';
+
+const result = validateRnc('131098193');
+// { valid: true, formatted: '1-31-09819-3' }
+```
+
+### Validar una cédula
+
+```typescript
+import { validateCedula } from 'dgii-ts';
+
+const result = validateCedula('00114272360');
+// { valid: true, formatted: '001-1427236-0' }
+```
+
+### Validar un NCF
+
+```typescript
+import { validateNcf } from 'dgii-ts';
+
+const result = validateNcf('B0100000001');
+// { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }
+```
+
+### Validar un e-NCF
+
+```typescript
+import { validateEcf } from 'dgii-ts';
+
+const result = validateEcf('E310000000001');
+// { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }
+```
+
+### Importar solo validadores (tree-shaking)
+
+```typescript
+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*
+
+> **Nota:** El cliente SOAP aún no está implementado. La interfaz está definida
+> y estará disponible en una futura versión.
+
+```typescript
+import { DgiiSoapClient } from 'dgii-ts';
+
+const client = new DgiiSoapClient();
+const result = await client.getContribuyente('131098193');
+// { rnc: '131098193', nombre: '...', estado: '...', ... }
+```
+
+## Referencia del API
+
+### Validadores
+
+| Función | Descripción |
+| --- | --- |
+| `validateRnc(value)` | Valida RNC de 9 dígitos con dígito verificador |
+| `validateCedula(value)` | Valida cédula de 11 dígitos con dígito verificador |
+| `validateNcf(value)` | Valida formato y tipo de NCF (serie B) |
+| `validateEcf(value)` | Valida formato y tipo de e-NCF (serie E) |
+
+### Cliente SOAP
+
+| Clase/Método | Descripción |
+| --- | --- |
+| `DgiiSoapClient` | Cliente tipado para WSMovilDGII |
+| `client.getContribuyente(rnc)` | Consulta datos de un contribuyente por RNC |
+| `client.getNCF(rnc, ncf)` | Valida un comprobante fiscal contra la DGII |
+
+### Datos masivos
+
+| Clase/Método | Descripción |
+| --- | --- |
+| `downloadBulkFile(path)` | Descarga DGII\_RNC.zip al directorio especificado |
+| `parseBulkFile(path)` | Parsea el archivo TXT de contribuyentes |
+
+## Arquitectura
+
+```text
+┌─────────────────────────────────────────────────┐
+│                  Tu aplicación                  │
+├─────────────────────────────────────────────────┤
+│  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 3: Datos masivos (DGII_RNC.zip)           │
+│  ✓ Descarga diaria  ✓ Parseo TXT               │
+└─────────────────────────────────────────────────┘
+```
+
+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
+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
+
+## Seguridad
+
+Para reportar vulnerabilidades, consulta [SECURITY.md](./SECURITY.md).
+
+## Contribuciones
+
+Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](./CONTRIBUTING.md)
+para más detalles.
+
+## Licencia
+
+[MIT](./LICENSE)
+
+## Nota
+
+Esta es una librería comunitaria independiente, no está afiliada ni respaldada
+por la DGII. Para datos fiscales críticos, verifica siempre con un profesional
+contable autorizado.

package/dist/bulk.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkFZ6QDTC4cjs = require('./chunk-FZ6QDTC4.cjs');
+require('./chunk-QH4BK5X3.cjs');
+
+
+
+
+exports.DGII_BULK_URL = _chunkFZ6QDTC4cjs.DGII_BULK_URL; exports.downloadBulkFile = _chunkFZ6QDTC4cjs.downloadBulkFile; exports.parseBulkFile = _chunkFZ6QDTC4cjs.parseBulkFile;

package/dist/bulk.d.cts

@@ -0,0 +1,30 @@
+import { B as BulkContribuyente } from './index-CS-7YY2y.cjs';
+
+interface DownloadOptions {
+    /** Directorio de destino para el archivo ZIP */
+    outputDir: string;
+    /** Tiempo de espera en milisegundos (por defecto: 60000) */
+    timeout?: number;
+}
+interface ParseOptions {
+    /** Ruta al archivo TXT extraído del ZIP */
+    filePath: string;
+}
+declare const DGII_BULK_URL: string;
+
+/**
+ * Descarga el archivo masivo DGII_RNC.zip desde el portal de la DGII.
+ *
+ * @returns Ruta absoluta al archivo ZIP descargado
+ */
+declare function downloadBulkFile(options: DownloadOptions): Promise<string>;
+
+/**
+ * Parsea el archivo TXT de contribuyentes extraido de DGII_RNC.zip.
+ *
+ * El archivo usa delimitador pipe (|) con 9 columnas.
+ * Los registros pueden tener espacios dobles que se limpian.
+ */
+declare function parseBulkFile(options: ParseOptions): Promise<BulkContribuyente[]>;
+
+export { BulkContribuyente, DGII_BULK_URL, type DownloadOptions, type ParseOptions, downloadBulkFile, parseBulkFile };

package/dist/bulk.d.ts

@@ -0,0 +1,30 @@
+import { B as BulkContribuyente } from './index-CS-7YY2y.js';
+
+interface DownloadOptions {
+    /** Directorio de destino para el archivo ZIP */
+    outputDir: string;
+    /** Tiempo de espera en milisegundos (por defecto: 60000) */
+    timeout?: number;
+}
+interface ParseOptions {
+    /** Ruta al archivo TXT extraído del ZIP */
+    filePath: string;
+}
+declare const DGII_BULK_URL: string;
+
+/**
+ * Descarga el archivo masivo DGII_RNC.zip desde el portal de la DGII.
+ *
+ * @returns Ruta absoluta al archivo ZIP descargado
+ */
+declare function downloadBulkFile(options: DownloadOptions): Promise<string>;
+
+/**
+ * Parsea el archivo TXT de contribuyentes extraido de DGII_RNC.zip.
+ *
+ * El archivo usa delimitador pipe (|) con 9 columnas.
+ * Los registros pueden tener espacios dobles que se limpian.
+ */
+declare function parseBulkFile(options: ParseOptions): Promise<BulkContribuyente[]>;
+
+export { BulkContribuyente, DGII_BULK_URL, type DownloadOptions, type ParseOptions, downloadBulkFile, parseBulkFile };

package/dist/bulk.js

@@ -0,0 +1,11 @@
+import {
+  DGII_BULK_URL,
+  downloadBulkFile,
+  parseBulkFile
+} from "./chunk-KIS7MVIW.js";
+import "./chunk-D26S6EXD.js";
+export {
+  DGII_BULK_URL,
+  downloadBulkFile,
+  parseBulkFile
+};

package/dist/chunk-2ST6QKHA.cjs

@@ -0,0 +1 @@
+"use strict";