consultame-sdk 1.0.0

package/README.md

@@ -0,0 +1,585 @@
+# consultame-sdk
+
+Librería en **TypeScript** para generar los mensajes XML (SOAP) e insumos criptográficos
+que se necesitan para interactuar con **SIFEN** (Sistema Integrado de Facturación Electrónica
+Nacional de Paraguay – SET).
+
+La librería **no** hace las peticiones HTTP al web service de SIFEN: su responsabilidad es
+**construir los sobres XML** (consulta de RUC, consulta de lote, consulta de documento),
+**extraer el certificado y la llave privada** desde un archivo de firma digital `.p12`/`.pfx`
+y **generar el código QR** que se incrusta en el documento electrónico firmado.
+Con esa salida, la aplicación consumidora firma y envía los mensajes por su cuenta.
+
+---
+
+## Tabla de contenido
+
+- [Instalación](#instalación)
+- [Uso rápido](#uso-rápido)
+- [API pública](#api-pública)
+  - [`consultRuc`](#consultrucconsultrucdto)
+  - [`consultDocument`](#consultdocumentconsultdocumentdto)
+  - [`consultBatch`](#consultbatchconsultbatchdto)
+  - [`obtainDigitalSign`](#obtaindigitalsigndigitalsigndto)
+  - [`generateQr`](#generateqrgenerationqrdto)
+- [DTOs (contratos de entrada)](#dtos-contratos-de-entrada)
+- [Funciones utilitarias internas](#funciones-utilitarias-internas)
+- [Arquitectura del proyecto](#arquitectura-del-proyecto)
+- [Estructura de carpetas](#estructura-de-carpetas)
+- [Scripts de desarrollo](#scripts-de-desarrollo)
+- [Estado / roadmap](#estado--roadmap)
+
+---
+
+## Instalación
+
+```bash
+pnpm add consultame-sdk
+# o
+npm install consultame-sdk
+```
+
+Dependencias en tiempo de ejecución:
+
+| Paquete                                                  | Para qué se usa                                              |
+| -------------------------------------------------------- | ------------------------------------------------------------ |
+| [`node-forge`](https://www.npmjs.com/package/node-forge) | Leer los certificados `.p12`/`.pfx` y exportarlos a PEM.     |
+| [`xml2js`](https://www.npmjs.com/package/xml2js)         | Parsear y reconstruir el XML del documento al generar el QR. |
+| [`crypto-js`](https://www.npmjs.com/package/crypto-js)   | Calcular el hash SHA-256 (`cHashQR`) del código QR.          |
+
+La librería se publica en formato dual **CommonJS + ESM** con tipos incluidos:
+
+```ts
+// ESM
+import { SifenService } from "consultame-sdk";
+
+// CommonJS
+const { SifenService } = require("consultame-sdk");
+```
+
+---
+
+## Uso rápido
+
+Todo el punto de entrada público es la clase **`SifenService`**. Se instancia sin
+argumentos y ya arma internamente sus casos de uso y dependencias.
+
+```ts
+import { SifenService } from "consultame-skd";
+
+const sifen = new SifenService();
+
+// 1) Consultar un RUC → devuelve el XML SOAP listo, normalizado en una sola línea
+const xmlRuc = sifen.consultRuc({
+  id: 1,
+  ruc: "80012345-6",
+});
+
+// 2) Consultar un documento electrónico por su CDC
+const xmlDocumento = sifen.consultDocument({
+  id: 2,
+  cdc: "01800123456001001000000012023052212345678901",
+});
+
+// 3) Consultar el estado de un lote enviado
+const xmlLote = sifen.consultBatch({
+  id: 3,
+  codigoLote: "1234567890",
+});
+
+// 4) Extraer certificado + llave privada desde la firma digital (.p12)
+const firma = sifen.obtainDigitalSign({
+  camino: "./certificados/firma.p12",
+  contraseña: "mi-clave-secreta",
+});
+
+console.log(firma.certificado); // PEM del certificado
+console.log(firma.llavePrivada); // PEM de la llave privada
+
+// 5) Generar el QR e incrustarlo en un documento electrónico ya firmado (asíncrono)
+const xmlConQr = await sifen.generateQr({
+  xml: xmlFirmado, // XML del rDE ya firmado digitalmente
+  csc: "ABCD0000000000000000000000000000",
+  idCsc: "0001",
+  ambiente: "test", // "test" | "produccion"
+});
+```
+
+---
+
+## API pública
+
+Todos los métodos viven en la clase `SifenService`. Son **síncronos**, salvo
+[`generateQr`](#generateqrgenerationqrdto), que es **asíncrono** y devuelve una `Promise`.
+
+### `consultRuc(consultRucDto)`
+
+Genera el sobre SOAP `rEnviConsRUC` para consultar los datos de un contribuyente por RUC.
+
+| Parámetro | Tipo     | Descripción                           |
+| --------- | -------- | ------------------------------------- |
+| `id`      | `number` | Identificador de la petición (`dId`). |
+| `ruc`     | `string` | RUC del contribuyente a consultar.    |
+
+**Retorna:** `string` — XML SOAP normalizado (sin saltos de línea ni tabulaciones).
+
+```ts
+const xml = sifen.consultRuc({ id: 1, ruc: "80012345-6" });
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</summary>
+
+```xml
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnviConsRUC xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>1</dId>
+      <dRUCCons>80012345-6</dRUCCons>
+    </rEnviConsRUC>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `consultDocument(consultDocumentDto)`
+
+Genera el sobre SOAP `rEnviConsDeRequest` para consultar un documento electrónico
+(factura, nota, etc.) mediante su **CDC** (Código de Control).
+
+| Parámetro | Tipo     | Descripción                           |
+| --------- | -------- | ------------------------------------- |
+| `id`      | `number` | Identificador de la petición (`dId`). |
+| `cdc`     | `string` | CDC de 44 dígitos del documento.      |
+
+**Retorna:** `string` — XML SOAP normalizado.
+
+```ts
+const xml = sifen.consultDocument({
+  id: 2,
+  cdc: "01800123456001001000000012023052212345678901",
+});
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</summary>
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnviConsDeRequest xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>2</dId>
+      <dCDC>01800123456001001000000012023052212345678901</dCDC>
+    </rEnviConsDeRequest>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `consultBatch(consultBatchDto)`
+
+Genera el sobre SOAP `rEnviConsLoteDe` para consultar el estado de un **lote**
+previamente enviado a SIFEN.
+
+| Parámetro    | Tipo     | Descripción                                     |
+| ------------ | -------- | ----------------------------------------------- |
+| `id`         | `number` | Identificador de la petición (`dId`).           |
+| `codigoLote` | `string` | Número de protocolo del lote (`dProtConsLote`). |
+
+**Retorna:** `string` — XML SOAP normalizado.
+
+```ts
+const xml = sifen.consultBatch({ id: 3, codigoLote: "1234567890" });
+```
+
+<details>
+<summary>Ejemplo de salida (formateada para lectura)</summary>
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
+  <env:Header/>
+  <env:Body>
+    <rEnviConsLoteDe xmlns="http://ekuatia.set.gov.py/sifen/xsd">
+      <dId>3</dId>
+      <dProtConsLote>1234567890</dProtConsLote>
+    </rEnviConsLoteDe>
+  </env:Body>
+</env:Envelope>
+```
+
+</details>
+
+---
+
+### `obtainDigitalSign(digitalSignDto)`
+
+Lee un archivo de firma digital `.p12`/`.pfx`, valida que contenga llave privada y
+certificado, y los devuelve en formato **PEM**.
+
+| Parámetro    | Tipo     | Descripción                              |
+| ------------ | -------- | ---------------------------------------- |
+| `camino`     | `string` | Ruta al archivo `.p12`/`.pfx`.           |
+| `contraseña` | `string` | Contraseña que protege la firma digital. |
+
+**Retorna:** `ResponseDigitalSign`
+
+```ts
+interface ResponseDigitalSign {
+  certificado: string; // certificado en formato PEM
+  llavePrivada: string; // llave privada en formato PEM
+}
+```
+
+**Errores que puede lanzar:**
+
+- `"La firma digital no contiene una llave privada"` — el `.p12` no tiene llave.
+- `"La firma digital no contiene un certificado"` — el `.p12` no tiene certificado.
+- Errores de `node-forge` si la contraseña es incorrecta o el archivo está corrupto.
+
+```ts
+try {
+  const { certificado, llavePrivada } = sifen.obtainDigitalSign({
+    camino: "./certificados/firma.p12",
+    contraseña: "clave",
+  });
+} catch (error) {
+  // contraseña incorrecta, archivo inválido o sin llave/certificado
+}
+```
+
+---
+
+### `generateQr(generationQrDto)`
+
+Toma un documento electrónico (`rDE`) **ya firmado digitalmente**, calcula el enlace del
+código QR exigido por SIFEN y devuelve el **mismo XML con el nodo `<gCamFuFD><dCarQR>`
+incrustado**.
+
+> ⚠️ Este es el único método **asíncrono** de la librería: devuelve `Promise<string>`.
+
+| Parámetro  | Tipo     | Descripción                                                            |
+| ---------- | -------- | ---------------------------------------------------------------------- |
+| `xml`      | `string` | XML del `rDE` **firmado** (debe contener el nodo `Signature`).         |
+| `csc`      | `string` | Código de Seguridad del Contribuyente (secreto, entregado por la SET). |
+| `idCsc`    | `string` | Identificador del CSC (ej. `"0001"`).                                  |
+| `ambiente` | `string` | `"test"` o `"produccion"`. Define el dominio base del enlace del QR.   |
+
+**Retorna:** `Promise<string>` — el XML reconstruido con el nodo `dCarQR`.
+
+```ts
+const xmlConQr = await sifen.generateQr({
+  xml: xmlFirmado,
+  csc: "ABCD0000000000000000000000000000",
+  idCsc: "0001",
+  ambiente: "test",
+});
+```
+
+#### Cómo se construye el QR
+
+1. Se parsea el XML y se **valida que exista el nodo `Signature`**; si no está, lanza error.
+2. Se elige el dominio base según el ambiente:
+   - `test` → `https://ekuatia.set.gov.py/consultas-test`
+   - `produccion` → `https://ekuatia.set.gov.py/consultas`
+3. Se le concatena `/qr?` y los parámetros extraídos del documento, **en este orden**:
+
+   | Parámetro                 | Origen en el XML                                         | Notas                                           |
+   | ------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
+   | `nVersion`                | `rDE > dVerFor`                                          | Versión del formato.                            |
+   | `Id`                      | `rDE > DE[@Id]`                                          | El CDC del documento.                           |
+   | `dFeEmiDE`                | `rDE > DE > gDatGralOpe > dFeEmiDE`                      | Convertido a **hexadecimal**.                   |
+   | `dRucRec` _o_ `dNumIDRec` | `... > gDatRec`                                          | `dRucRec` si `iNatRec == 1`, si no `dNumIDRec`. |
+   | `dTotGralOpe`             | `rDE > DE > gTotSub > dTotGralOpe`                       | `0` si no existe.                               |
+   | `dTotIVA`                 | `rDE > DE > gTotSub > dTotIVA`                           | `0` si no existe.                               |
+   | `cItems`                  | Cantidad de `gDtipDE > gCamItem`                         | `0` si no hay ítems.                            |
+   | `DigestValue`             | `rDE > Signature > SignedInfo > Reference > DigestValue` | Convertido a **hexadecimal**.                   |
+   | `IdCSC`                   | Parámetro `idCsc`                                        | Último antes del hash.                          |
+   | `cHashQR`                 | `SHA256(cadena_de_parámetros + csc)`                     | Se agrega al final.                             |
+
+4. El enlace resultante se escribe en `rDE > gCamFuFD > dCarQR` y se reconstruye el XML.
+
+<details>
+<summary>Ejemplo del enlace generado dentro de <code>dCarQR</code></summary>
+
+```
+https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&Id=01800123456001001000000012023052212345678901&dFeEmiDE=323032332d30352d32325431303a30303a3030&dRucRec=80012345&dTotGralOpe=550000&dTotIVA=50000&cItems=3&DigestValue=6a4b2c...&IdCSC=0001&cHashQR=9f2a7c1e4b8d...
+```
+
+Y así queda incrustado en el XML de salida:
+
+```xml
+<rDE>
+  <dVerFor>150</dVerFor>
+  <DE Id="01800123456001001000000012023052212345678901">
+    ...
+  </DE>
+  <Signature>...</Signature>
+  <gCamFuFD>
+    <dCarQR>https://ekuatia.set.gov.py/consultas-test/qr?nVersion=150&amp;Id=...&amp;cHashQR=...</dCarQR>
+  </gCamFuFD>
+</rDE>
+```
+
+</details>
+
+**Errores que puede lanzar:**
+
+- `"XML debe estar firmado digitalmente para generar el QR"` — el XML no tiene nodo `Signature`.
+- Errores de parseo de `xml2js` si el XML está malformado.
+- `TypeError` si el documento no respeta la estructura esperada del `rDE` (por ejemplo,
+  falta `gDatRec` o `gDtipDE`).
+
+```ts
+try {
+  const xmlConQr = await sifen.generateQr({
+    xml: xmlFirmado,
+    csc: process.env.SIFEN_CSC!,
+    idCsc: "0001",
+    ambiente: "produccion",
+  });
+} catch (error) {
+  // XML sin firmar, malformado o con estructura inesperada
+}
+```
+
+> **Nota sobre el `ambiente`:** internamente se compara contra el enum `SIFEN_ENVIRONMENT`
+> (`"test"` / `"produccion"`). Cualquier valor distinto de `"test"` cae en el enlace de
+> **producción**, así que conviene pasar el valor exacto.
+
+---
+
+## DTOs (contratos de entrada)
+
+Todos los DTOs de consulta extienden `GenerateIdDto`, que aporta el campo `id`.
+
+```ts
+interface GenerateIdDto {
+  id: number;
+}
+
+interface ConsultRucDto extends GenerateIdDto {
+  ruc: string;
+}
+
+interface ConsultDocumentDto extends GenerateIdDto {
+  cdc: string;
+}
+
+interface ConsultBatchDto extends GenerateIdDto {
+  codigoLote: string;
+}
+
+interface DigitalSignDto {
+  camino: string; // ruta al .p12
+  contraseña: string; // clave del .p12
+}
+
+interface GenerationQrDto {
+  xml: string; // XML del rDE ya firmado
+  csc: string; // Código de Seguridad del Contribuyente
+  idCsc: string; // Identificador del CSC
+  ambiente: string; // "test" | "produccion"
+}
+```
+
+Enums disponibles en [`src/shared/utils/dictionary.utils.ts`](src/shared/utils/dictionary.utils.ts):
+
+```ts
+enum SIFEN_ENVIRONMENT {
+  TEST = "test",
+  PRODUCCION = "produccion",
+}
+
+enum LINK_SIFEN {
+  TEST = "https://ekuatia.set.gov.py/consultas-test",
+  PRODUCCION = "https://ekuatia.set.gov.py/consultas",
+}
+```
+
+DTOs ya definidos pero **aún sin implementación** en la persistencia (ver
+[roadmap](#estado--roadmap)):
+
+```ts
+interface CancelInvoiceDto extends GenerateIdDto {
+  cdc: string;
+  motivo: string;
+}
+
+interface InvalidationInvoiceDto extends GenerateIdDto {
+  timbrado: string;
+  establecimiento: number;
+  puntoExpedicion: number;
+  desde: number;
+  hasta: number;
+  tipoDocumento: number;
+  motivo: string;
+}
+```
+
+---
+
+## Funciones utilitarias internas
+
+Viven en [`src/shared/functions/functions.utils.ts`](src/shared/functions/functions.utils.ts).
+No forman parte de la API pública, pero es útil conocerlas:
+
+| Función                      | Qué hace                                                                                      |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `generateConsultRucXml`      | Arma el string XML de consulta de RUC.                                                        |
+| `generateConsultDocumentXml` | Arma el string XML de consulta de documento por CDC.                                          |
+| `generateConsultBatchXml`    | Arma el string XML de consulta de lote.                                                       |
+| `normalizeXML`               | Colapsa el XML a una sola línea: elimina saltos, tabulaciones y espacios entre etiquetas.     |
+| `readDigitalSign`            | Lee el `.p12` con `node-forge` y extrae certificado + llave privada en PEM.                   |
+| `generateQr`                 | Arma el enlace del QR (params + hash SHA-256) y lo incrusta en `gCamFuFD > dCarQR`. _(async)_ |
+| `calculateDigitVerification` | Calcula el dígito verificador (DV) de una cédula/RUC según el algoritmo módulo 11.            |
+
+---
+
+## Arquitectura del proyecto
+
+El proyecto sigue una **arquitectura hexagonal (puertos y adaptadores)** combinada con
+principios de **Clean Architecture**, organizada por el módulo de negocio `sifen`.
+
+```
+             ┌──────────────────────────────────────────────┐
+             │                 applications                 │
+             │   SifenService  (punto de entrada / fachada)  │
+             │   DTOs (contratos de entrada)                 │
+             └───────────────────────┬──────────────────────┘
+                                     │ orquesta
+                                     ▼
+             ┌──────────────────────────────────────────────┐
+             │                    domain                     │
+             │   useCases  (ConsultRuc, ConsultBatch, ...)   │
+             │   repository (SifenRepository = PUERTO)        │
+             └───────────────────────┬──────────────────────┘
+                                     │ implementado por
+                                     ▼
+             ┌──────────────────────────────────────────────┐
+             │                infrastructure                 │
+             │   SifenPersistence (ADAPTADOR del puerto)      │
+             │   → usa funciones utilitarias (XML, forge)     │
+             └──────────────────────────────────────────────┘
+```
+
+**Flujo de una llamada** (ej. `consultRuc`):
+
+1. La app llama a `SifenService.consultRuc(dto)` — capa **applications**.
+2. El servicio delega en `ConsultRucUseCase.execute(dto)` — capa **domain**.
+3. El caso de uso invoca la interfaz `SifenRepository` (**puerto**), sin conocer la implementación.
+4. En runtime el puerto lo resuelve `SifenPersistence` (**adaptador**) — capa **infrastructure**.
+5. La persistencia usa las funciones utilitarias para generar y normalizar el XML.
+
+**Por qué esta separación:**
+
+- **`domain`** no depende de nada externo: define _qué_ se hace (casos de uso) y el
+  contrato `SifenRepository`. Es el núcleo estable.
+- **`infrastructure`** contiene los detalles concretos (armado de XML, `node-forge`, `fs`).
+  Se puede reemplazar sin tocar el dominio.
+- **`applications`** expone la fachada y los DTOs que consume el mundo exterior.
+- **`shared`** agrupa utilidades y DTOs de respuesta transversales a los módulos.
+
+La inversión de dependencias es clave: `SifenPersistence implements SifenRepository`, de
+modo que el dominio depende de la **abstracción**, no de la implementación.
+
+---
+
+## Estructura de carpetas
+
+```
+consultame-sdk/
+├── src/
+│   ├── index.ts                          # Punto de entrada público → exporta SifenService
+│   │
+│   ├── shared/                           # Código transversal
+│   │   ├── dto/
+│   │   │   └── responseDigitalSign.dto.ts # ResponseDigitalSign { certificado, llavePrivada }
+│   │   ├── functions/
+│   │   │   └── functions.utils.ts        # XML, normalizeXML, readDigitalSign, generateQr, DV
+│   │   └── utils/
+│   │       └── dictionary.utils.ts       # Enums SIFEN_ENVIRONMENT y LINK_SIFEN
+│   │
+│   └── sifen/                            # Módulo de negocio SIFEN
+│       ├── applications/                 # Capa de aplicación (fachada + contratos)
+│       │   ├── dtos/
+│       │   │   ├── index.ts              # Barrel de DTOs
+│       │   │   ├── generateId.dto.ts     # GenerateIdDto (base)
+│       │   │   ├── consultRuc.dto.ts
+│       │   │   ├── consultDocument.dto.ts
+│       │   │   ├── consultBatch.dto.ts
+│       │   │   ├── digitalSign.dto.ts
+│       │   │   ├── generationQr.dto.ts
+│       │   │   ├── cancelDocument.dto.ts
+│       │   │   └── invalidationInvoice.dto.ts
+│       │   └── services/
+│       │       └── sifen.service.ts      # SifenService (fachada pública)
+│       │
+│       ├── domain/                       # Núcleo de negocio
+│       │   ├── repository/
+│       │   │   └── sifen.repository.ts   # SifenRepository (PUERTO / interfaz)
+│       │   └── useCases/
+│       │       ├── index.ts              # Barrel de casos de uso
+│       │       ├── consultRuc.useCase.ts
+│       │       ├── consultDocument.useCase.ts
+│       │       ├── consultBatch.useCase.ts
+│       │       ├── obtainDigitalSign.useCase.ts
+│       │       └── generateQr.useCase.ts
+│       │
+│       └── infrastructure/               # Detalles concretos (ADAPTADORES)
+│           └── persistence/
+│               └── sifen.persistence.ts  # SifenPersistence implements SifenRepository
+│
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts                        # Build dual CJS + ESM (target node22)
+├── pnpm-workspace.yaml
+└── README.md
+```
+
+---
+
+## Scripts de desarrollo
+
+| Script             | Comando                     | Descripción                                         |
+| ------------------ | --------------------------- | --------------------------------------------------- |
+| `pnpm build`       | `tsup && build:types`       | Compila a `dist/` (CJS + ESM) y genera los `.d.ts`. |
+| `pnpm build:types` | `tsc --emitDeclarationOnly` | Solo emite las declaraciones de tipos.              |
+| `pnpm dev`         | `tsup --watch`              | Build en modo watch.                                |
+| `pnpm typecheck`   | `tsc --noEmit`              | Verifica tipos sin emitir archivos.                 |
+| `pnpm play`        | `tsx src/index.ts`          | Ejecuta `src/index.ts` para pruebas manuales.       |
+| `pnpm play:watch`  | `tsx watch src/index.ts`    | Igual que `play` pero en modo watch.                |
+
+---
+
+## Estado / roadmap
+
+Funcionalidades **implementadas**:
+
+- ✅ Consulta de RUC (`consultRuc`)
+- ✅ Consulta de documento por CDC (`consultDocument`)
+- ✅ Consulta de lote (`consultBatch`)
+- ✅ Lectura de firma digital `.p12` → PEM (`obtainDigitalSign`)
+- ✅ Generación e incrustación del código QR (`generateQr`)
+
+Definidas pero **pendientes de implementación** (hoy lanzan `Method not implemented`
+o aún no están expuestas en `SifenService`):
+
+- ⏳ Cancelación de documento (`cancelationInvoice` / `CancelInvoiceDto`)
+- ⏳ Inutilización de documentos (`invalidationInvoice` / `InvalidationInvoiceDto`)
+
+---
+
+> **Nota:** esta librería genera insumos (XML, credenciales y el QR) para SIFEN, pero no
+> realiza el envío HTTP ni la firma XMLDSig de los documentos. Esa parte queda a cargo de
+> la aplicación consumidora — de hecho, `generateQr` **requiere** que el XML ya venga
+> firmado, porque toma el `DigestValue` de la firma para calcular el hash del QR.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SifenService } from "./sifen/applications/services/sifen.service";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAC"}