dte-sdk

Contribuir

Las contribuciones son bienvenidas. dte-sdk produce documentos tributarios válidos y maneja llaves de firma, así que la exactitud y la cobertura de tests importan más que la velocidad. Esta guía te deja listo.

Reportar issues#

¿Encontraste un bug o tienes una solicitud de funcionalidad?

  1. Busca primero entre los issues existentes.
  2. Abre un issue nuevo con una descripción clara, pasos para reproducirlo, comportamiento esperado vs. real, y un ejemplo de código mínimo.

Si adjuntas XML u objetos de entrada, enmascáralos: reemplaza RUT, nombres y montos reales por los valores de ejemplo de esta documentación, y nunca adjuntes un CAF, certificado o contraseña reales.

Para vulnerabilidades de seguridad, no abras un issue público. Sigue la política de seguridad privada del repositorio. Revisa Seguridad.

Configuración de desarrollo#

Requisitos previos#

  • Node.js 20 o superior
  • npm
  • git

Empezar#

Shell
git clone https://github.com/arrowsw/dte-sdk.git
cd dte-sdk
npm install
 
npm test          # run the test suite
npm run build     # build the ESM and CJS bundles
npm run lint      # lint the source and tests
npm run size      # check the bundle against its size budget

Enviar un pull request#

1

Crea una rama

Shell
git checkout -b feature/my-feature
2

Implementa con tests

Agrega tests para el nuevo comportamiento: el camino feliz, cada código de DteError que pueda lanzar y casos límite como redondeo, descuentos y líneas exentas. La cobertura no debe bajar.

3

Verifica localmente

Shell
npm test
npm run lint
npm run build
npm run size
4

Haz commit y abre el PR

Usa un mensaje de commit claro y convencional. Describe el cambio, enlaza el issue que resuelve y señala cualquier impacto disruptivo en la API pública.

Guías de código#

  • Escrito en TypeScript; sigue el estilo existente y corre el linter.
  • Agrega JSDoc a cada función pública.
  • Sin dependencias en runtime. Tener cero dependencias es parte de la promesa del paquete; abre un issue antes de proponer una.
  • Solo APIs de la plataforma web. Usa Web Crypto, no node:crypto, para que el mismo código corra en Node, Deno, Bun y el navegador.
  • El dinero es CLP entero. Redondea half-up en los puntos documentados y nunca dejes que un monto con decimales de punto flotante llegue al XML.
  • Preserva las invariantes de seguridad: los mensajes de error siguen siendo genéricos y nunca repiten RUT, montos, llaves ni contraseñas.

Guías de tests#

La suite es el contrato: 412 tests en 14 suites, todos pasando. Replica la estructura existente:

TypeScript
describe('stampDte', () => {
  describe('happy path', () => {
    test('stamps a folio inside the CAF range', () => { /* … */ })
  })
  describe('errors', () => {
    test('throws FOLIO_OUT_OF_RANGE for a folio outside the range', () => { /* … */ })
    test('throws CAF_EXPIRED after the CAF expiry date', () => { /* … */ })
  })
  describe('edge cases', () => {
    test('accepts the first and last folio of the range', () => { /* … */ })
  })
})
  • Solo fixtures. Los tests usan CAF y certificados generados para pruebas. Nunca hagas commit de un CAF real, un .pfx real ni una contraseña.
  • RUT válidos. Todo RUT en un test debe tener un dígito verificador Módulo 11 correcto, salvo que el test trate justamente de uno inválido. Reutiliza 76.123.456-0 y 77.654.321-7.
  • Montos exactos. Compara los totales como enteros exactos; los bugs de redondeo del IVA se esconden en el "casi igual".

Estructura del proyecto#

Código
dte-sdk/
├── src/          # Library source (single entry: index.ts)
├── tests/        # Test suites and fixtures
├── scripts/      # Build helpers
├── dist/         # Build output (ESM + CJS)
└── package.json

Actualizar la documentación#

¿Viste un error en este sitio? Abre un issue con la página y la corrección. Cuando agregues o cambies una funcionalidad del paquete, por favor también:

  1. Actualiza el README.md raíz y el CHANGELOG.md.
  2. Incluye ejemplos de código ejecutables que usen los valores de ejemplo documentados.
  3. Menciona en la descripción del PR cualquier cambio en una firma o en un código de error.

Áreas que siempre ayudan#

  • Tests: más casos límite de redondeo, descuentos, líneas exentas y envíos con varios documentos.
  • Documentación: explicaciones más claras, más ejemplos, traducciones.
  • Tooling: CI, experiencia de desarrollo, automatización de releases.

Licencia#

MIT © Arrow Software.

Gracias por contribuir. Tu ayuda hace que la facturación electrónica sea más fácil para cada desarrollador en Chile.

← AnteriorSeguridad