@infosel-sdk/securities-prices

SDK de Securities para acceder a precios de valores y datos del mercado financiero. Proporciona servicios para recuperar gráficos intradiarios, datos históricos, instantáneas del mercado e información financiera en tiempo real.

🚀 Características

• 📊 Datos Intradiarios: Gráficos y reportes en tiempo real
• 📈 Datos Históricos: Información histórica con múltiples períodos
• 💹 Instantáneas del Mercado: Últimos precios, ofertas y demandas
• 📊 Profundidad del Libro: Información detallada de liquidez
• 📈 Rendimientos: Cálculos de rendimiento en diferentes períodos
• 🔐 Autenticación Flexible: Soporte para KeyCloak y tokens existentes
• ⚡ Configuración Moderna: Builder pattern para configuración validada

📦 Instalación

npm install @infosel-sdk/securities-prices @infosel-sdk/core

🚀 Inicio Rápido

✨ Configuración Moderna (Recomendado)

La nueva API del core proporciona una configuración más limpia y validada:

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';

// Configuración moderna con Builder Pattern
const authConfig = AuthConfigurationBuilder.keyCloak()
  .withRealm('hub')
  .withEnvironment('qa')
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: 'tu-client-id',
    client_secret: 'tu-client-secret',
  })
  .build();

// Inicializar SDK Manager con configuración moderna
const sdkManager = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

// Inicializar SDK de Securities
const securitiesSDK = new SecuritiesPricesSDK(sdkManager);

// Usar el SDK
const intradayData = await securitiesSDK.getIntradayChart({
  symbol: 'AMXL',
  exchange: 'BMV',
  period: '1D',
});

🔄 Configuración Legacy (Compatibilidad)

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager } from '@infosel-sdk/core';

// Configuración legacy (mantenida para compatibilidad)
const sdkManager = InfoselSdkManager.init({
  mode: 'qa',
  authProviderConfig: {
    type: 'key-cloak',
    realm: 'hub',
    credentials: {
      grant_type: 'client_credentials',
      client_id: 'tu-client-id',
      client_secret: 'tu-client-secret',
    },
  },
});

const securitiesSDK = new SecuritiesPricesSDK(sdkManager);

Configuración con Token Existente

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager, AuthConfigurationBuilder, Token } from '@infosel-sdk/core';

// Configuración con token existente
const token: Token = {
  accessToken: 'tu-access-token',
  refreshToken: 'tu-refresh-token',
};

const authConfig = AuthConfigurationBuilder.existingToken()
  .withRealm('hub')
  .withEnvironment('prod')
  .withClientId('hub-app')
  .withToken(token)
  .build();

const sdkManager = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

const securitiesSDK = new SecuritiesPricesSDK(sdkManager);

Configuración con Valores por Defecto

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';

// Configuración mínima con valores por defecto
const authConfig = AuthConfigurationBuilder.keyCloak()
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: 'tu-client-id',
    client_secret: 'tu-client-secret',
  })
  .build(); // Usa 'hub' como realm y 'prod' como environment por defecto

const sdkManager = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

const securitiesSDK = new SecuritiesPricesSDK(sdkManager);

Configuración por Ambiente

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager, AuthConfigurationBuilder, Environment } from '@infosel-sdk/core';

function createSecuritiesSDK(environment: Environment) {
  const authConfig = AuthConfigurationBuilder.keyCloak()
    .withEnvironment(environment)
    .withRealm(environment === 'qa' ? 'qa-realm' : 'prod-realm')
    .withCredentials({
      grant_type: 'client_credentials',
      client_id: environment === 'qa' ? 'qa-client' : 'prod-client',
      client_secret: environment === 'qa' ? 'qa-secret' : 'prod-secret',
    })
    .build();

  const sdkManager = InfoselSdkManager.initWithConfiguration({
    authConfiguration: authConfig,
  });

  return new SecuritiesPricesSDK(sdkManager);
}

// Usar según el ambiente
const qaSecurities = createSecuritiesSDK('qa');
const prodSecurities = createSecuritiesSDK('prod');

🔍 Validación de Configuración

La nueva API incluye validaciones robustas:

import { AuthConfigurationBuilder } from '@infosel-sdk/core';

const builder = AuthConfigurationBuilder.keyCloak()
  .withRealm('invalid@realm') // Caracteres inválidos
  .withCredentials({
    grant_type: 'client_credentials',
    client_id: '', // Client ID vacío
    client_secret: 'secret',
  });

// Validar antes de construir
const validation = builder.validate();
if (!validation.isValid) {
  console.log('Errores:', validation.errors);
  // ['Realm contains invalid characters...', 'Client ID is required...']
}

// O validar automáticamente al construir
try {
  const config = builder.build();
} catch (error) {
  console.error(error.message); // Lista todos los errores de validación
}

Configuración de Entorno

Para una configuración segura, usa variables de entorno:

Archivo .env

# Configuración de entorno
NODE_ENV=prod

# Configuración de KeyCloak
KEYCLOAK_GRANT_TYPE=client_credentials
KEYCLOAK_CLIENT_ID=tu-client-id
KEYCLOAK_CLIENT_SECRET=tu-client-secret
KEYCLOAK_REALM=hub

Configuración en código

import { SecuritiesPricesSDK } from '@infosel-sdk/securities-prices';
import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';

// Cargar configuración desde variables de entorno
const authConfig = AuthConfigurationBuilder.keyCloak()
  .withRealm(process.env.KEYCLOAK_REALM || 'hub')
  .withEnvironment(process.env.NODE_ENV === 'production' ? 'prod' : 'qa')
  .withCredentials({
    grant_type: process.env.KEYCLOAK_GRANT_TYPE || 'client_credentials',
    client_id: process.env.KEYCLOAK_CLIENT_ID!,
    client_secret: process.env.KEYCLOAK_CLIENT_SECRET!,
  })
  .build();

const sdkManager = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

const securitiesSDK = new SecuritiesPricesSDK(sdkManager);

📊 Métodos Disponibles

Datos Intradiarios

// Obtener gráfico intradiario
const intraday = await securitiesSDK.getIntradayChart({
  symbol: 'AMXL',
  exchange: 'BMV',
  period: '1D', // '1D', '1W', '1M'
});

// Obtener reporte intradiario
const report = await securitiesSDK.getIntradayReport({
  symbol: 'AMXL',
  exchange: 'BMV',
  period: '1D',
});

Datos Históricos

// Obtener gráfico histórico
const historical = await securitiesSDK.getHistoricalChart({
  symbol: 'AMXL',
  exchange: 'BMV',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  period: '1D',
});

// Obtener histórico con último precio negociado
const historicalWithLastPrice = await securitiesSDK.getHistoricalChartWithLastTradedPrice({
  symbol: 'AMXL',
  exchange: 'BMV',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  period: '1D',
});

// Obtener reporte histórico
const historicalReport = await securitiesSDK.getHistoricalReport({
  symbol: 'AMXL',
  exchange: 'BMV',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  period: '1D',
});

Instantáneas del Mercado

// Obtener último precio negociado
const lastPrice = await securitiesSDK.getLastTradedPrice({
  symbol: 'AMXL',
  exchange: 'BMV',
});

// Obtener mejor oferta y demanda
const bestBidOffer = await securitiesSDK.getBestBidOffer({
  symbol: 'AMXL',
  exchange: 'BMV',
});

// Obtener profundidad del libro
const depthOfBook = await securitiesSDK.getDepthOfBook({
  symbol: 'AMXL',
  exchange: 'BMV',
  levels: 5,
});

// Obtener rendimientos
const returns = await securitiesSDK.getReturns({
  symbol: 'AMXL',
  exchange: 'BMV',
  period: '1M', // '1D', '1W', '1M', '3M', '6M', '1Y'
});

📋 Parámetros Comunes

Símbolos y Exchanges

• Símbolos: 'AMXL', 'FEMSAUBD', 'WALMEX', etc.
• Exchanges: 'BMV' (Bolsa Mexicana de Valores)

Períodos Disponibles

• Intradiarios: '1D', '1W', '1M'
• Históricos: '1D', '1W', '1M'
• Rendimientos: '1D', '1W', '1M', '3M', '6M', '1Y'

Modos de Operación

• prod: Producción
• qa: Pruebas
• preprod: Pre-producción

🚨 Manejo de Errores

import { SdkError, SdkErrorType } from '@infosel-sdk/core';

try {
  const data = await securitiesSDK.getIntradayChart({
    symbol: 'AMXL',
    exchange: 'BMV',
    period: '1D',
  });
  return data;
} catch (error) {
  if (error instanceof SdkError) {
    switch (error.type) {
      case SdkErrorType.AXIOS_RESPONSE_ERROR:
        console.error('Error de respuesta HTTP:', error.message);
        break;
      case SdkErrorType.INVALID_AUTH_PROVIDER_CONFIG:
        console.error('Configuración de autenticación inválida:', error.message);
        break;
      default:
        console.error('Error del SDK:', error.message);
    }
  }
  throw error;
}

📚 Referencia de API

Clases Principales

SecuritiesPricesSDK

Punto de entrada principal para el SDK de Securities. Se inicializa con el InfoselSdkManager y proporciona métodos para acceder a datos de precios y mercado.

InfoselSdkManager

Gestor central del SDK que maneja la configuración, autenticación y modo de operación. Se inicializa usando el método estático initWithConfiguration() con configuración moderna o init() con configuración legacy.

AuthConfigurationBuilder

Builder para crear configuraciones de autenticación validadas y centralizadas. Proporciona una API fluida para configurar autenticación KeyCloak y basada en tokens.

Casos de Uso

Datos Intradiarios

• GetIntradayChartUseCase: Obtener gráfico intradiario
• GetIntradayReportUseCase: Obtener reporte intradiario

Datos Históricos

• GetHistoricalChartUseCase: Obtener gráfico histórico
• GetHistoricalChartWithLastTradedPriceUseCase: Obtener histórico con último precio
• GetHistoricalReportUseCase: Obtener reporte histórico

Instantáneas del Mercado

• GetLastTradedPriceUseCase: Obtener último precio negociado
• GetBestBidOfferUseCase: Obtener mejor oferta y demanda
• GetDepthOfBookUseCase: Obtener profundidad del libro
• GetReturnsUseCase: Obtener rendimientos

Entidades

Entidades Principales

• IntradayChart: Datos de gráfico intradiario
• HistoricalChart: Datos de gráfico histórico
• LastTradedPrice: Último precio negociado
• BestBidOffer: Mejor oferta y demanda
• DepthOfBook: Profundidad del libro
• Returns: Rendimientos del instrumento

Entidades de Solicitud

• IntradayChartRequest: Parámetros para datos intradiarios
• HistoricalChartRequest: Parámetros para datos históricos
• LastTradedPriceRequest: Parámetros para último precio
• BestBidOfferRequest: Parámetros para oferta y demanda
• DepthOfBookRequest: Parámetros para profundidad del libro
• ReturnsRequest: Parámetros para rendimientos

🔗 Dependencias

Peer Dependencies

• @nestjs/common: ^10.0.0
• class-transformer: ^0.5.1
• class-validator: ^0.14.1

Runtime Dependencies

• @infosel-sdk/core: Funcionalidad principal del SDK (versión ^0.0.4)
• axios: Cliente HTTP
• tslib: Biblioteca runtime de TypeScript

🆕 Novedades en Core v0.0.4

✨ Configuration Builder Pattern

• Nueva API fluida para configuración sin duplicaciones
• Validaciones centralizadas con mensajes de error descriptivos
• Single source of truth para configuración de realm
• Compatibilidad hacia atrás mantenida

🔧 Mejoras en Configuración

• Configuración dinámica de realm para múltiples ambientes
• Validación de formatos de realm, client_id y credenciales
• Valores por defecto inteligentes basados en el tipo de autenticación
• Type safety mejorado con TypeScript

📖 Documentación

• Ejemplos completos de uso del Configuration Builder
• Guías de migración desde configuración legacy
• Casos de uso avanzados para diferentes ambientes

🔄 Migración desde Configuración Legacy

Antes

// ❌ Configuración duplicada
const sdk = InfoselSdkManager.init({
  mode: 'qa',
  realm: 'my-realm', // Primera definición
  authProviderConfig: {
    type: 'key-cloak',
    realm: 'my-realm', // Segunda definición (duplicada)
    credentials: {
      /* ... */
    },
  },
});

Después

// ✅ Single source of truth
const authConfig = AuthConfigurationBuilder.keyCloak()
  .withRealm('my-realm') // Una sola definición
  .withEnvironment('qa')
  .withCredentials({
    /* ... */
  })
  .build();

const sdk = InfoselSdkManager.initWithConfiguration({
  authConfiguration: authConfig,
});

🧪 Testing

# Ejecutar tests
npm test

# Ejecutar tests con cobertura
npm run test:coverage

# Ejecutar tests específicos
npm test -- --testPathPattern="securities_prices"

🔨 Development

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build:lib

# Crear distribución
npm run publish:lib

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia ISC. Ver el archivo LICENSE para más detalles.

🔗 Paquetes Relacionados

• @infosel-sdk/core: Funcionalidad core del SDK (versión ^0.0.4)
• @infosel-sdk/markets: SDK de mercados financieros
• @infosel-sdk/news: SDK de noticias y contenido
• @infosel-sdk/funds: SDK de fondos de inversión
• @infosel-sdk/calendar: SDK de calendario económico
• @infosel-sdk/users: SDK de gestión de usuarios

Autor: Infosel
Mantenedor: [email protected]
Hecho con ❤️ por el equipo de Infosel