bcv-exchange-rate

v1.0.1

Published

10 days ago

Librería profesional de Node.js para el rastreo de indicadores económicos oficiales de Venezuela (BCV) y Colombia (TRM - COP). Especializada en monedas fronterizas.

Downloads

217

0High
0Medium
0Low

carrilloapps

bcv trm venezuela colombia cop ves frontera tasa de cambio exchange-rate indicadores economía scraping

bcv-exchange-rate

Librería profesional de Node.js para consultar indicadores económicos oficiales de Venezuela (BCV) y Colombia (TRM). Extrae los datos directamente del Banco Central de Venezuela y del portal de datos abiertos del Gobierno de Colombia, con tipado estricto, reintentos con backoff, caché en memoria activa por defecto, jerarquía de errores tipada y logger basado en interfaz, sin dependencias forzadas.

Características

Multi-indicador. Tasas oficiales del BCV (USD, EUR, CNY, TRY, RUB) y TRM de Colombia (COP).
Historial bancario paginado. Tasas de compra y venta por institución financiera venezolana.
Reintentos automáticos con backoff exponencial configurable.
Caché en memoria con TTL por llamada y stale-while-error opcional.
Jerarquía de errores tipada (NetworkError, TrmApiError, ValidationError).
Logger basado en interfaz. Compatible con winston, pino, bunyan o console, sin dependencias forzadas.
TLS seguro por defecto (strictSSL: true), con desactivación explícita cuando sea necesario.
Dual CJS/ESM con declaraciones .d.ts.
Estado por sección (status.current, status.history) para detectar fallos parciales.
Cobertura del 100 % forzada en CI.

Instalación

npm install bcv-exchange-rate

Requiere Node.js 20 LTS o superior. Si usas winston como logger (opcional):

npm install winston

Inicio rápido

import { getBcvRates, getTrmRates } from 'bcv-exchange-rate';

const bcv = await getBcvRates({ currencies: 'USD', includeHistory: false });
console.log(`USD/VES: ${bcv.current.USD} (vigencia ${bcv.effectiveDate})`);

const trm = await getTrmRates({ limit: 1 });
console.log(`TRM: ${trm?.current.value} COP`);

Versión CommonJS:

const { getBcvRates } = require('bcv-exchange-rate');

Ejemplo con caché y reintentos

const bcv = await getBcvRates({
  currencies: ['USD', 'EUR'],
  retries: 3,
  retryDelayMs: 500,
  cacheTtlMs: 60_000,
  cacheStaleTtlMs: 10 * 60_000,
});

if (bcv.status.current === 'failed') {
  console.warn('Tasa actual no disponible; se usa el historial como alternativa');
}

Documentación

La documentación extendida vive en docs/:

Primeros pasos

Referencia

Guías temáticas

Operaciones

Solución de problemas

Desarrollo

npm install
npm test             # Jest con cobertura del 100 % forzada.
npm run lint         # ESLint.
npm run format       # Prettier.
npm run build        # Dual CJS/ESM más declaraciones.

Más detalles en CONTRIBUTING.md.