feat(sire): RVIE Ventas + RCE Compras automation

[Railly]

Summary

End-to-end automation for SUNAT SIRE (Sistema Integrado de Registros Electrónicos) — the mandatory monthly electronic books filing system that all CPE emisores must complete since 2024.

Why this matters: SIRE is the biggest monthly tax dolor for any empresa peruana. Late filing = multa hasta 1 UIT (S/5,350 in 2026). Today contadores do this manually in the SOL portal every month. This PR automates 95% of the workflow.

What's in this PR

SIRE-specific OAuth (password grant)

• Extended oauth.ts: when username/password provided, switches from client_credentials → password grant + clientessol endpoint variant
• New host: api-sire.sunat.gob.pe (separate from api.sunat.gob.pe used in PR feat(rest): consulta CPE OAuth + padrón RUC local #3)
• Same in-process token cache + 401 retry as PR feat(rest): consulta CPE OAuth + padrón RUC local #3
• CPE consulta from PR feat(rest): consulta CPE OAuth + padrón RUC local #3 keeps working unchanged (auto-detects which grant to use)

SIRE client (src/sunat-rest/sire.ts)

• listarPeriodos(codLibro) — GET ejercicios + periodos disponibles
• descargarPropuesta({codLibro, perTributario}) — async, returns ticket
• descargarRvie(perTributario) — async, returns ticket
• aceptarPropuestaRvie(perTributario) — POST, returns ticket
• consultarTicket(numTicket) — GET status (01/03/06/07/10)
• descargarArchivo({...}) — streams the ZIP/TXT bytes
• pollTicket({...}) — backoff 2s/4s/8s/16s/30s, max 5min
• codLibro: 140000 RVIE | 080000 RCE
• sireCredentials() builds the password-grant creds shape

Commands

# Setup once
export SUNAT_API_CLIENT_ID=...   # SOL → Credenciales API SUNAT, URI = "MIGE RCE y RVIE - SIRE"
export SUNAT_API_CLIENT_SECRET=...
export SUNAT_RUC=20XXXXXXXXX
export SUNAT_USER=MODDATOS
export SUNAT_PASSWORD='clave-sol'

# Monthly RVIE workflow
sunat sire ventas periodos
sunat sire ventas propuesta --periodo 202404 --wait --out propuesta.zip
sunat sire ventas aceptar --periodo 202404 --yes
sunat sire ventas descargar --periodo 202404 --wait --out rvie.zip

# RCE — same pattern
sunat sire compras periodos
sunat sire compras propuesta --periodo 202404 --wait --out compras.zip
sunat sire compras ticket --num 20240100000123 --wait

--wait polls getStatus until terminal (06=Terminado, 07/10=error). Without --wait, returns ticket for manual polling.

Tests

223 pass / 2 skip / 0 fail in 2.8s (was 209)

New unit tests (14):
- sireCredentials concat RUC+SOL_USER, scope sire
- OAuth password grant: posts to clientessol with grant_type=password
- listarPeriodos hits api-sire host with codLibro in path
- descargarPropuesta: RVIE vs RCE use different endpoints
- descargarRvie hits exportarregistropropuesta
- aceptarPropuestaRvie POSTs to /aceptapropuesta
- consultarTicket: maps registros[0], handles empty
- pollTicket: completed/error/still-processing transitions

What's NOT in this PR (deferred)

Capability	Why	Path forward
Reemplazar propuesta + Importar comprobantes	Uses TUS.IO resumable upload protocol; SUNAT's own note says "deben ser desarrollados en JAVA"	Next PR with TUS.IO TS client
Reportes complementarios (resumen, inconsistencias, CAR, casillas)	Same async ticket pattern as propuesta, easy adds	Add as needed
Tipo de cambio masivo	JSON POST, easy add	Add when relevant
End-to-end smoke against real SIRE	RUC test 20000000001 (PR #1) doesn't have RVIE periods	Verify with real RUC + cert post-merge

SUNAT specs honored

All endpoints follow Manual de Servicios Web Api SIRE Ventas v22 (March 2024) verified shapes. See src/sunat-rest/SIRE-RESEARCH.md for full mapping.

SUNAT's note: "los servicios del API SIRE no deben ser consumidos desde un cliente Web, en caso de utilizar un cliente Web se producirá error de CORS". CLI is server-side, no CORS concern.

Test plan

• bun test green (223 pass / 2 skip / 0 fail)
• sunat sire --help lists ventas + compras
• sunat sire ventas --help lists 5 verbs
• OAuth password grant unit-tested with mocks
• All endpoints unit-tested with mocks (request URL + method + body shape)
• CI green on push
• Verify with real RUC + cert post-merge