# Instalación

> Instalar los paquetes @devlas-cl de SII SDK desde GitHub Packages con un token clásico, un .npmrc y la etiqueta de versión del licenciatario.

Fuente: https://sii.devlas.cl/docs/instalacion

# Instalación

Los paquetes `@devlas-cl/*` son privados y se distribuyen por el registro npm de GitHub Packages (`https://npm.pkg.github.com`), no por npmjs.com. Cada licenciatario recibe su propia copia con un sufijo de versión y una etiqueta propia, y el acceso queda ligado a su nivel (también el nivel Libre, gratis con registro). Requiere Node.js 24 o superior; los paquetes son solo ESM.

## Requisitos previos

- Devlas aprueba tu registro y da acceso de lectura a los paquetes de tu nivel. Sin ese acceso la instalación responde 403 o 404.
- Al aprobarlo, Devlas entrega la **etiqueta** de versión (por ejemplo `c7f3a1b2c`) que usarás en cada instalación.
- Node.js 24 o superior (`engines.node >=24`).

## Pasos

### 1. Token personal clásico

GitHub Packages no acepta tokens fine-grained. Crea un token clásico (GitHub: Settings, Developer settings, Personal access tokens, Tokens (classic)) con el permiso `read:packages` y nada más, con vencimiento (recomendado: 90 días). Si la cuenta pertenece a una organización con SSO, autoriza el token para esa organización.

### 2. Token fuera del repositorio

```sh
export NODE_AUTH_TOKEN='ghp_...'   # nunca en un archivo versionado
```

### 3. `.npmrc` en la raíz del proyecto

Se versiona, porque no contiene el token (lo lee de la variable):

```ini
@devlas-cl:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```

### 4. Instalar con tu etiqueta

Usa la misma etiqueta en todos los paquetes `@devlas-cl`. Núcleo para emitir boletas, facturas y notas:

```sh
pnpm add @devlas-cl/comun@<etiqueta> @devlas-cl/dominio@<etiqueta> @devlas-cl/xml@<etiqueta> @devlas-cl/protocolo@<etiqueta> @devlas-cl/sii@<etiqueta>
```

## Paquetes según el nivel

Los niveles son acumulativos. Paquetes publicados y a qué nivel pertenecen:

| Paquete | Nivel que lo entrega | Contenido |
|---|---|---|
| `@devlas-cl/comun` | Todos | `Resultado`, `ErrorSii`, catálogo de códigos, puertos, `mensajeParaUsuario` |
| `@devlas-cl/dominio` | Todos | `Documento`, RUT, `fechaTributaria`, cálculo de montos, vigencia del CAF |
| `@devlas-cl/xml` | Todos | `prepararDte`, `prepararSobre`, `prevalidarEmision`, `leerCaf`, `abrirCertificado`, XSD |
| `@devlas-cl/protocolo` | Todos | Lectores de respuestas del SII, catálogo, veredictos, políticas de consulta y envío |
| `@devlas-cl/sii` | Todos | Llamadas al SII: `emitir`, `enviarBoletas`, `enviarDte`, `consultarEstadoEnvio`, RCV, reclamos |
| `@devlas-cl/soluciones` | Todos | `habilitar`, `diagnosticarEmisor`, `resumirFoliosCaf` |
| `@devlas-cl/impresion` | Todos | Ticket térmico, PDF y timbre PDF417 |
| `@devlas-cl/folios` | AutoCAF y Certificador | `autoCaf`, `pedirCaf`, `reobtenerCaf`, `anularFolios`, `consultarTopeFolios`, `llamadasFoliosDeSii` |
| `@devlas-cl/certificacion` | Certificador | `avanzarCorrida`, `crearPasosSii`, sets, libros, muestras |

`@devlas-cl/contabilidad` (IVA, PPM, reajuste, interés penal, multas) también se publica, sin nivel declarado. `@devlas-cl/pruebas` (falsos y pruebas de contrato) no se publica.

Opcionales en cualquier nivel (recetas e impresión):

```sh
pnpm add @devlas-cl/soluciones@<etiqueta> @devlas-cl/impresion@<etiqueta>
```

AutoCAF suma `folios` (depende de `soluciones`):

```sh
pnpm add @devlas-cl/soluciones@<etiqueta> @devlas-cl/folios@<etiqueta>
```

Certificador suma `certificacion` (depende de `folios`, `soluciones` e `impresion`):

```sh
pnpm add @devlas-cl/soluciones@<etiqueta> @devlas-cl/impresion@<etiqueta> @devlas-cl/folios@<etiqueta> @devlas-cl/certificacion@<etiqueta>
```

## Versiones y actualizaciones

- Tu versión es la del lanzamiento con un sufijo tuyo (por ejemplo `0.6.0-c7f3a1b2c`) y la etiqueta es ese sufijo.
- Para actualizar, vuelve a instalar con la misma etiqueta: Devlas la mueve a cada versión nueva.
- Un rango como `^0.6.0` no sirve: las versiones con sufijo no entran en rangos de otra versión.
- Todos los paquetes llevan el mismo número de versión. No hay matriz de compatibilidad: instala todos con la misma etiqueta.
- Las dependencias internas entre paquetes quedan fijadas a la versión exacta de tu copia.

## Integración continua

Guarda el token clásico como secreto del pipeline (por ejemplo `DEVLAS_PACKAGES_TOKEN`) y pásalo como `NODE_AUTH_TOKEN` al paso de instalación. El `GITHUB_TOKEN` de otro repositorio no sirve para leer estos paquetes. Usa un token propio del pipeline.

```yaml
- uses: actions/setup-node@v4
  with:
    registry-url: https://npm.pkg.github.com
    scope: '@devlas-cl'
- run: pnpm install --frozen-lockfile
  env:
    NODE_AUTH_TOKEN: ${{ secrets.DEVLAS_PACKAGES_TOKEN }}
```

## Rotación y vencimiento del token

- Antes de que venza, crea uno nuevo, actualiza la variable o el secreto y borra el anterior.
- Token vencido o revocado: las instalaciones nuevas fallan con 401 o 403. Lo ya instalado en `node_modules` sigue funcionando; solo dejas de poder instalar o actualizar.
- Token filtrado: revócalo de inmediato en GitHub y crea otro.

## Solo ESM

Los paquetes no se cargan con `require()`. Desde CommonJS usa `import()` dinámico dentro de una función `async`. En TypeScript con CommonJS necesitas `moduleResolution` `node16` o `nodenext`.

```ts
// Desde CommonJS, dentro de una función async:
const { abrirCertificado } = await import('@devlas-cl/xml')
```

## Contenido de cada paquete publicado

Cada tarball trae solo `dist` (JavaScript compilado con tipos), `package.json`, `README.md`, `COMMERCIAL.md` y `THIRD-PARTY-NOTICES.md`. Sin código fuente, pruebas ni mapas.