@plenti.org/ccl

Currency Conversion Library (CCL) es la librería TypeScript que replica la lógica USD/COP usada en PlentiAll.

Características clave

• Integración directa con SET-ICAP (mercados 71 y 76) con Yahoo Finance como respaldo automático.
• Horarios, reglas de selección de tasa y validaciones idénticas al backend de producción.
• Caché rotativo con persistencia de la última tasa válida y manejador de errores con códigos tipados.

Instalación

npm install @plenti.org/ccl
# o
yarn add @plenti.org/ccl
# o
pnpm add @plenti.org/ccl

Configuración rápida

1. Expone la contraseña de SET-ICAP en tu entorno:

SETICAP_PWD=tu_password_de_seticap

2. Importa la librería desde cualquier parte de tu proyecto. Fuera de entornos de test, el token manager y el job de actualización se inician solos:

import { APIService } from '@plenti.org/ccl';

3. Usa utilidades opcionales cuando necesites control manual:

import { startTokenManager, isTokenAvailable, getCurrentToken } from '@plenti.org/ccl';

startTokenManager();

if (!isTokenAvailable()) {
  throw new Error('Token de Set-ICAP no disponible');
}

const token = getCurrentToken();

Uso rápido

import { getExchangeRate, checkMarketStatus, getYahooFx, APIService } from '@plenti.org/ccl';

// Orquestación completa con proveedores internos
const rate = await getExchangeRate({
  fetchSeticapSpotRate: async () => (await APIService.getExchangeRates()).usdToCop,
  fetchSeticapNextDayRate: async () => (await APIService.getNextDayExchangeRate()).usdToCop,
  fetchYahooRate: async () => (await getYahooFx()).usdToCop
});

console.log(rate); // { rate, source, marketCondition, timestamp }

// Estado del mercado colombiano en cualquier momento
const status = checkMarketStatus();
console.log(status); // { isOpen, status, condition, description, timeInfo }

Diagrama de flujo

flowchart TD
    A[Aplicación cliente] -->|1. getExchangeRate| B{Token SET-ICAP disponible}
    B -->|Sí| C[Orquestador de mercado]
    B -->|No| D[startTokenManager]
    D --> E[Renueva token y reintenta]
    E --> B
    C --> F[/SET-ICAP mercado 71/]
    F -->|Éxito| J[Selecciona tasa final]
    F -->|Error| G[/SET-ICAP mercado 76/]
    G -->|Éxito| J
    G -->|Error| H[/Yahoo Finance/]
    H -->|Éxito| J
    H -->|Error| I[Última tasa válida o tasa de emergencia]
    J --> K[Actualiza caché rotativo]
    K --> L[Retorna rate, source, marketCondition, timestamp]
    L --> M[Logs y métricas opcionales]

Cómo funciona

• SET-ICAP: utiliza entity: "SOMOSPLENTI" y usr_name: "nicolas", reintenta hasta 5 veces y renueva token cada 6 horas con SETICAP_PWD.
• Reglas de mercado: 08:00–13:00 usa tasa spot (71); 13:00–16:30 usa tasa next day (76); fuera de horario se compara SET-ICAP vs Yahoo Finance.
• Caché: dos niveles (principal y fallback) que rotan con cada tasa válida; puedes depurarlo con clearCache() o inspeccionarlo con getCacheStatistics().
• Fallbacks y errores: orden de recuperación 71 → 76 → Yahoo → última tasa → tasa de emergencia, normalizando errores con ErrorCodes.

API esencial

• getExchangeRate(providers, date?): orquesta los proveedores y entrega { rate, source, marketCondition, timestamp }.
• initializeMarketSystem(config?): ajusta caché, fallbacks y timeouts.
• checkMarketStatus(date?): expone metadatos del mercado.
• globalMarketOrchestrator: instancia para ejecutar orchestrateRateProcessing.
• APIService: llamadas directas a SET-ICAP, limpieza de caché y forzado de refresh.
• getYahooFx(): proveedor Yahoo Finance sin procesar.
• globalExchangeRateCache: gestión manual del caché rotativo.

Desarrollo

npm test           # tests unitarios e integración
npm run build      # genera artefactos en dist/

Contribución y licencia

Aceptamos contribuciones vía pull requests. Ejecuta npm run build y npm test antes de enviarlas. Distribuimos la librería bajo licencia MIT.