@openfactura/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xaviigna
+
+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.md

@@ -1,3 +1,396 @@
-# Temporary Holding Version
+# @openfactura/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente de línea de comandos de [Open Factura](../../README.md), la plataforma abierta de facturación
+electrónica de El Salvador (DTE, Ministerio de Hacienda). Emite, consulta e invalida documentos desde la
+terminal o desde un script, e incluye un servidor MCP por stdio para Claude y otros asistentes.
+
+La CLI habla con un servidor de Open Factura únicamente por su API REST: no firma ni transmite por su
+cuenta, y no necesita el certificado de Hacienda en su equipo.
+
+## Instalación
+
+Requiere Node.js 20 o superior (también funciona con Bun).
+
+```bash
+npm i -g @openfactura/cli
+openfactura --version
+
+# o sin instalar
+npx @openfactura/cli --help
+```
+
+## Inicio de sesión
+
+Cree una clave de API en el panel web (Desarrolladores → Nueva clave). Las claves `of_test_…` trabajan contra
+el ambiente de pruebas del MH y las `of_live_…` contra producción.
+
+```bash
+openfactura login --url https://factura.su-empresa.sv
+# Clave de API (of_test_… u of_live_…): ← se teclea sin mostrarse
+```
+
+`login` verifica la clave contra el servidor y la guarda en `~/.config/openfactura/config.json`
+(o en `$XDG_CONFIG_HOME/openfactura/config.json`) con permisos `0600`. La clave completa nunca se
+imprime: la CLI muestra sólo sus primeros 14 caracteres.
+
+```bash
+openfactura login --url https://factura.su-empresa.sv --key of_test_…   # sin preguntar
+echo "$CLAVE" | openfactura login                                        # desde una tubería
+openfactura login --profile produccion                                   # otro perfil
+openfactura logout                                                       # borra la clave guardada
+```
+
+Evite `--key` en equipos compartidos: el valor queda en el historial de la terminal.
+
+En un servidor de integración continua no hace falta `login`; basta con las variables de entorno:
+
+```bash
+export OPENFACTURA_URL=https://factura.su-empresa.sv
+export OPENFACTURA_API_KEY=of_test_…
+openfactura whoami
+```
+
+### De dónde sale cada valor
+
+| Valor            | Orden de prioridad                                                      |
+| ---------------- | ----------------------------------------------------------------------- |
+| URL del servidor | `--url` → `OPENFACTURA_URL` → perfil guardado → `http://localhost:8788` |
+| Clave de API     | `OPENFACTURA_API_KEY` → perfil guardado                                 |
+| Perfil           | `--profile` → `OPENFACTURA_PROFILE` → `default`                         |
+
+## Comandos
+
+Todos aceptan `--json` (imprime el JSON de la API en stdout, para scripts), `--url`, `--profile` y
+`--help`.
+
+### Sesión y emisor
+
+```bash
+openfactura whoami      # actor, permisos, ambiente, servidor y prefijo de la clave
+openfactura emisor      # datos fiscales, establecimientos, puntos de venta y credenciales cargadas
+```
+
+```text
+$ openfactura whoami
+Actor:        clave
+Organización: aaFgOwpa4md9Tl6Ct9e42AJ2jNnAltjh
+Ambiente:     00 Pruebas (simulador del MH)
+Servidor:     http://localhost:8788 (defecto)
+Clave:        of_test_0d2aEw… (entorno)
+Perfil:       default
+Permisos:     dte:read, dte:emit, dte:invalidate, clientes:read, …
+```
+
+### Clientes
+
+```bash
+openfactura clientes list
+openfactura clientes list --q "contribuyente"
+
+openfactura clientes add --file cliente.json
+openfactura clientes add \
+  --tipo-documento 36 --num-documento 0614-290786-103-1 --nrc 234567-8 \
+  --nombre "CLIENTE CONTRIBUYENTE, S.A. DE C.V." \
+  --cod-actividad 46900 --desc-actividad "Venta al por mayor de otros productos" \
+  --departamento 06 --municipio 23 --distrito 14 --complemento "Av. Olímpica #100" \
+  --telefono 22445566 --correo compras@cliente.com.sv
+```
+
+`--tipo-documento`: `36` NIT, `13` DUI, `03` pasaporte, `02` carné de residente, `37` otro. También
+existe `--nombre-comercial`. El archivo de `--file` lleva los mismos campos que la API
+(`tipoDocumento`, `numDocumento`, `nombre`, …); `--file -` lee la entrada estándar.
+
+### Productos
+
+```bash
+openfactura productos list --q licencia
+
+openfactura productos add --file producto.json
+openfactura productos add --codigo LIC-001 --descripcion "Licencia anual" --precio 100 --tipo-item 2
+```
+
+`--precio` va **sin IVA**. `--tipo-item`: `1` bien (por defecto), `2` servicio, `3` ambos, `4` otros
+tributos. `--uni-medida`: código de CAT-014 (por defecto `59`, unidad). `--tipo-venta`: `gravada`
+(por defecto), `exenta` o `noSujeta`.
+
+### Catálogos del MH
+
+```bash
+openfactura catalogos                               # lista de catálogos
+openfactura catalogos CAT-012                       # departamentos
+openfactura catalogos CAT-013 --departamento 06     # municipios de San Salvador
+openfactura catalogos CAT-019 --q "programación"    # actividades económicas
+```
+
+### DTE
+
+El archivo de emisión es el mismo cuerpo de `POST /api/v1/dte`:
+
+```json
+{
+  "tipoDte": "01",
+  "datos": {
+    "items": [
+      { "descripcion": "Servicio de consultoría", "cantidad": 2, "precioUni": 11.3, "tipoItem": 2 }
+    ]
+  }
+}
+```
+
+- `tipoDte`: `01` Factura, `03` Crédito Fiscal, `04` Nota de Remisión, `05` Nota de Crédito, `06` Nota de
+  Débito, `07` Comprobante de Retención, `11` Factura de Exportación, `14` Sujeto Excluido.
+- `datos`: `items`, `receptor`, `condicionOperacion`, `pagos`, `documentosRelacionados`… En Factura,
+  `precioUni` **incluye** IVA; en Crédito Fiscal, notas y remisión va **sin** IVA.
+- `clienteId` (opcional): usa un cliente guardado como receptor. `puntoVentaId` (opcional): punto de
+  venta que emite; por defecto el primero.
+
+Un Crédito Fiscal para un cliente guardado:
+
+```json
+{
+  "tipoDte": "03",
+  "clienteId": "c6de4c6c-d772-4f19-811a-5419655dcd06",
+  "datos": { "items": [{ "descripcion": "Licencia anual", "cantidad": 1, "precioUni": 100 }] }
+}
+```
+
+#### Validar
+
+```bash
+openfactura dte validar factura.json
+cat factura.json | openfactura dte validar -
+```
+
+Construye el documento y lo valida contra el esquema del MH sin consumir número de control, sin firmar y
+sin transmitir. Imprime los totales y los problemas; termina con salida `1` si hay problemas.
+
+#### Emitir
+
+```bash
+openfactura dte emitir factura.json
+generar-factura | openfactura dte emitir - --json > emitido.json
+```
+
+```text
+$ openfactura dte emitir factura.json
+Idempotency-Key: 853c48f2-f488-45d5-af00-0369495f0c05
+Estado:               procesado
+Tipo:                 01 Factura
+Número de control:    DTE-01-M001P001-000000000000002
+Código de generación: 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4
+Total:                $22.60
+Sello recibido:       20265EE94C1B2C4CBB56F56121E37F5AC8CA7D27
+```
+
+Cada emisión lleva una `Idempotency-Key`. Si no la indica, la CLI genera un UUID y lo muestra (por
+stderr) **antes** de enviar. Si la red falla y no sabe si el documento se emitió, repita el comando con
+esa misma clave: el servidor devuelve el resultado original y no emite dos veces.
+
+```bash
+openfactura dte emitir factura.json --idempotency-key 853c48f2-f488-45d5-af00-0369495f0c05
+openfactura dte emitir factura.json --idempotency-key pedido-1042     # su propio identificador
+```
+
+Si el MH no responde, el documento queda firmado en estado `contingencia` y se transmite después con
+`openfactura contingencia transmitir`.
+
+#### Consultar
+
+```bash
+openfactura dte list
+openfactura dte list --tipo 01 --estado procesado --desde 2026-11-01 --hasta 2026-11-30
+openfactura dte list --q "cliente contribuyente" --pagina 2
+
+openfactura dte get 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4     # estado, sello, respuesta del MH, eventos
+
+openfactura dte json 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4               # JSON oficial a stdout
+openfactura dte json 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -o dte.json
+
+openfactura dte pdf 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4                # guarda <codigo>.pdf aquí
+openfactura dte pdf 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -o factura.pdf
+```
+
+`--estado`: `pendiente`, `procesado`, `rechazado`, `contingencia` o `invalidado`.
+
+#### Invalidar
+
+```bash
+openfactura dte invalidar 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 --tipo 2 --motivo "Operación rescindida"
+openfactura dte invalidar <codigo> --tipo 1 --reemplazo <codigo-del-dte-que-lo-corrige>
+```
+
+`--tipo`: `1` error en la información (requiere `--reemplazo`), `2` rescindir la operación, `3` otro
+(requiere `--motivo` y `--reemplazo`). La invalidación es irreversible. El mismo comando invalida un
+evento de retorno u operaciones especiales si recibe su código. Un DTE con un retorno vigente no se
+invalida hasta invalidar antes el retorno.
+
+#### Retorno (evento 18)
+
+Devolución de bienes, reembolso o envases sobre una Factura (01), Factura de Exportación (11) o Sujeto
+Excluido (14) procesados, sin invalidar el documento. Plazo: 3 meses desde la fecha del documento.
+
+```bash
+echo '{ "items": [{ "descripcion": "Silla", "cantidad": 1, "precioUni": 22.6 }] }' \
+  | openfactura dte retorno 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -
+```
+
+`precioUni` va como en el documento original: en Factura con IVA, en 11 y 14 sin IVA. Como `dte emitir`,
+lleva `Idempotency-Key` y pide confirmación con una clave `of_live_…`.
+
+### Eventos
+
+```bash
+openfactura eventos operaciones-especiales simplificadas.json   # evento 17
+openfactura eventos list --tipo retorno
+openfactura eventos get <codigo>
+openfactura eventos json <codigo> -o retorno.json
+openfactura eventos pdf <codigo> -o retorno.pdf
+```
+
+El archivo de operaciones especiales informa facturas simplificadas (`"tipoDocumento": "02"`, por rangos)
+o comprobantes de control interno (`"97"`):
+
+```json
+{
+  "tipoDocumento": "02",
+  "fecha": "2026-10-31",
+  "items": [
+    { "descripcion": "Facturas simplificadas", "docDel": "1", "docAl": "25", "precioUni": 10 }
+  ]
+}
+```
+
+### Contingencia
+
+```bash
+openfactura contingencia transmitir
+```
+
+### Webhooks
+
+Su sistema recibe un `POST` firmado cuando un documento cambia de estado. La clave necesita el permiso
+`webhooks:manage`.
+
+```bash
+openfactura webhooks add https://erp.su-empresa.sv/hooks/openfactura \
+  --eventos dte.procesado,dte.rechazado --descripcion "ERP"   # sin --eventos: todos
+openfactura webhooks list
+openfactura webhooks test <id>          # envía webhook.prueba; salida 1 si no se entrega
+openfactura webhooks deliveries <id>    # últimas 50 entregas, con intentos y errores
+openfactura webhooks rotate <id>        # secreto nuevo; el anterior deja de firmar
+openfactura webhooks remove <id>
+```
+
+`add` y `rotate` muestran el secreto de firma (`whsec_…`) una sola vez. Eventos: `dte.procesado`,
+`dte.rechazado`, `dte.contingencia`, `dte.invalidado`, `retorno.procesado`,
+`operaciones_especiales.procesado`. Cómo verificar la cabecera `OpenFactura-Signature`: sección
+«Webhooks» de `docs/api.md` en el repositorio del servidor.
+
+### Confirmación en producción
+
+Con una clave `of_live_…`, `dte emitir`, `dte retorno`, `eventos operaciones-especiales`,
+`dte invalidar` y `contingencia transmitir` piden confirmación
+porque tienen efecto fiscal. Use `--yes` para omitirla. Si no hay una terminal interactiva (un script,
+una tubería, `dte emitir -`), la CLI no pregunta: exige `--yes` y termina con salida `2` si falta.
+
+## Uso en scripts
+
+`--json` imprime en stdout exactamente el JSON de la API; los avisos y errores van a stderr.
+
+```bash
+codigo=$(openfactura dte emitir factura.json --json | jq -r .codigoGeneracion)
+openfactura dte pdf "$codigo" -o "facturas/$codigo.pdf"
+```
+
+Los errores se imprimen en stderr como `Error [codigo]: mensaje`, seguidos del detalle: cada problema de
+`dte_invalido` como `ruta: mensaje`, o las observaciones del MH en `dte_rechazado`. Con `--json`, stderr
+recibe el JSON de error de la API (`{ "error": { "code", "message", "details" } }`); en un `429` se le
+agrega el campo `retryAfter` con los segundos de espera.
+
+### Códigos de salida
+
+| Código | Significado                                                                            |
+| ------ | -------------------------------------------------------------------------------------- |
+| `0`    | Todo bien                                                                              |
+| `1`    | Error de la API o de validación (incluye `dte validar` con problemas y errores de red) |
+| `2`    | Uso incorrecto: opción o argumento inválido, archivo ilegible, falta `--yes`           |
+| `3`    | Sin autenticar: falta la clave, o es inválida, fue revocada o expiró                   |
+| `4`    | Límite de peticiones excedido; se imprime `Retry-After`                                |
+
+### Variables de entorno
+
+| Variable              | Uso                                                        |
+| --------------------- | ---------------------------------------------------------- |
+| `OPENFACTURA_API_KEY` | Clave de API. Tiene prioridad sobre la clave guardada      |
+| `OPENFACTURA_URL`     | URL del servidor                                           |
+| `OPENFACTURA_PROFILE` | Perfil de configuración (por defecto `default`)            |
+| `XDG_CONFIG_HOME`     | Carpeta base de la configuración (por defecto `~/.config`) |
+
+## Servidor MCP (stdio)
+
+`openfactura mcp` es un servidor [MCP](https://modelcontextprotocol.io) por stdio. Sirve para los
+clientes que no pueden enviar un encabezado HTTP fijo al servidor MCP remoto (`/mcp`). Expone las mismas
+herramientas que el remoto y las ejecuta llamando a la API REST con su clave:
+
+`emisor_obtener`, `catalogo_buscar`, `clientes_buscar`, `cliente_crear`, `productos_buscar`,
+`producto_crear`, `dte_validar`, `dte_emitir`, `dte_listar`, `dte_obtener`, `dte_invalidar`,
+`dte_retorno`, `operaciones_especiales_informar`, `eventos_listar`, `evento_obtener`,
+`webhooks_listar`, `webhook_crear`, `webhook_eliminar`, `webhook_probar`.
+
+Cada herramienta exige el mismo permiso que su ruta REST, así que la clave decide qué puede hacer el
+asistente. Empiece con una clave `of_test_…`; `dte_emitir`, `dte_retorno`, `operaciones_especiales_informar` y
+`dte_invalidar` tienen efecto fiscal con una
+clave `of_live_…`, y aquí no hay confirmación de la CLI: la da usted en su cliente MCP al aprobar la
+llamada.
+
+### Claude Code
+
+```bash
+claude mcp add openfactura \
+  --env OPENFACTURA_API_KEY=of_test_… \
+  --env OPENFACTURA_URL=https://factura.su-empresa.sv \
+  -- npx -y @openfactura/cli mcp
+```
+
+### Claude Desktop
+
+En `claude_desktop_config.json` (o en un `.mcp.json` de proyecto para Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "openfactura": {
+      "command": "npx",
+      "args": ["-y", "@openfactura/cli", "mcp"],
+      "env": {
+        "OPENFACTURA_API_KEY": "of_test_…",
+        "OPENFACTURA_URL": "https://factura.su-empresa.sv"
+      }
+    }
+  }
+}
+```
+
+Si ya ejecutó `openfactura login` en ese equipo puede omitir `env`: el servidor usa el perfil guardado.
+
+Si su cliente sí admite encabezados HTTP, puede conectarse al servidor remoto sin instalar nada:
+
+```bash
+claude mcp add --transport http openfactura https://factura.su-empresa.sv/mcp \
+  --header "Authorization: Bearer of_test_…"
+```
+
+## Desarrollo
+
+```bash
+bun install
+bun run dev -- whoami     # ejecuta desde el código fuente
+bun run build             # dist/index.js
+bun run test
+bun run type-check
+```
+
+## Licencia
+
+MIT. La CLI es un cliente independiente del servidor de Open Factura (AGPL-3.0): se comunica con él
+únicamente por HTTP y no incluye su código.