@infosel-sdk/markets 1.2.0

package/README.md

@@ -0,0 +1,996 @@
+# @infosel-sdk/markets
+
+SDK de Mercados Financieros para la plataforma Infosel. Proporciona herramientas completas para acceder a datos de mercado, gestionar instrumentos, crear widgets y manejar espacios de trabajo para aplicaciones financieras.
+
+## 🚀 Características
+
+- **Acceso a Datos de Mercado**: Datos de mercado en tiempo real e históricos
+- **Gestión de Instrumentos**: Buscar, crear y gestionar instrumentos financieros
+- **Sistema de Widgets**: Crear y gestionar widgets financieros personalizables
+- **Gestión de Espacios de Trabajo**: Organizar y gestionar espacios de trabajo de usuarios
+- **Datos de Gráficos**: Acceder a datos de gráficos con múltiples marcos de tiempo
+- **Reportes Financieros**: Acceder a datos financieros e informes de instrumentos
+
+## 📦 Instalación
+
+```bash
+npm install @infosel-sdk/markets
+```
+
+## 🚀 Inicio Rápido
+
+### ✨ Configuración Moderna (Recomendado)
+
+La nueva API del core proporciona una configuración más limpia y validada:
+
+```typescript
+import InfoselMarkets from '@infosel-sdk/markets';
+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 Mercados
+const marketsSDK = InfoselMarkets.init({ sdkManager });
+
+// Usar el SDK
+const searchResults = await marketsSDK.searchInstruments({
+  query: 'AAPL',
+  limit: 10,
+  offset: 0,
+});
+```
+
+### Configuración con Token Existente
+
+```typescript
+import InfoselMarkets from '@infosel-sdk/markets';
+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 marketsSDK = InfoselMarkets.init({ sdkManager });
+```
+
+
+
+## 🔍 Validación de Configuración
+
+La nueva API incluye validaciones robustas:
+
+```typescript
+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
+}
+```
+
+## 📚 API Completa del SDK
+
+### 🔍 Búsqueda y Gestión de Instrumentos
+
+#### Buscar Instrumentos
+
+```typescript
+// Búsqueda básica
+const searchResults = await marketsSDK.searchInstruments({
+  query: 'AAPL',
+  limit: 10,
+});
+
+// Búsqueda con filtros avanzados
+const filteredResults = await marketsSDK.searchInstruments({
+  query: 'TECH',
+  limit: 20,
+  marketTypeIds: [1, 2], // Tipos de mercado específicos
+  valueTypeIds: [1], // Tipos de valor específicos
+  exchangeIds: [1, 2], // Exchanges específicos
+});
+
+console.log('Instrumentos encontrados:', searchResults);
+```
+
+#### Obtener Lista de Instrumentos
+
+```typescript
+const instruments = await marketsSDK.getInstruments({
+  // Parámetros de paginación y filtros
+  limit: 50,
+  offset: 0,
+});
+
+console.log('Total de instrumentos:', instruments.total);
+console.log('Instrumentos:', instruments.instruments);
+```
+
+#### Crear Instrumento Personalizado
+
+```typescript
+const newInstrument = await marketsSDK.createInstrument({
+  symbol: 'CUSTOM_STOCK',
+  uniqueKey: 'CUSTOM_001',
+  widgetId: 'widget-123',
+  // Otros campos del instrumento
+});
+
+console.log('Instrumento creado:', newInstrument);
+```
+
+#### Eliminar Instrumento
+
+```typescript
+const result = await marketsSDK.deleteInstrument('instrument-id-123');
+console.log('Resultado:', result); // Mensaje de confirmación
+```
+
+#### Obtener Campos del Instrumento
+
+```typescript
+const fields = await marketsSDK.getInstrumentFields('instrument-id-123');
+console.log('Campos disponibles:', fields);
+```
+
+### 📊 Detalles Financieros de Instrumentos
+
+#### Perfil del Instrumento
+
+```typescript
+const profile = await marketsSDK.getInstrumentDetailProfile({
+  instrumentId: 'AAPL_US',
+});
+
+console.log('Perfil del instrumento:', profile);
+```
+
+#### Datos Financieros Trimestrales
+
+```typescript
+const quarterlyData = await marketsSDK.getInstrumentDetailFinancialQuartely({
+  instrumentId: 'AAPL_US',
+  period: 'QUARTERLY',
+});
+
+console.log('Datos trimestrales:', quarterlyData);
+```
+
+#### Datos Financieros Anuales
+
+```typescript
+const annualData = await marketsSDK.getInstrumentDetailFinancialAnnual({
+  instrumentId: 'AAPL_US',
+  period: 'ANNUAL',
+});
+
+console.log('Datos anuales:', annualData);
+```
+
+#### Razones Financieras del Instrumento
+
+```typescript
+const financialReasons = await marketsSDK.getInstrumentDetailFinancialReasons({
+  instrumentId: 'AAPL_US',
+  period: 'QUARTERLY',
+});
+
+console.log('Razones financieras:', financialReasons);
+```
+
+#### Reportes Financieros con Razones
+
+```typescript
+const reportReasons = await marketsSDK.getInstrumentReportFinancialReasons({
+  instrumentId: 'AAPL_US',
+  period: 'QUARTERLY',
+});
+
+console.log('Reporte con razones:', reportReasons);
+```
+
+### 🎯 Gestión de Widgets
+
+#### Crear Widget
+
+```typescript
+// Widget de gráfico
+const chartWidget = await marketsSDK.createWidget({
+  workspaceId: 'workspace-123',
+  type: 'CHART',
+  name: 'Gráfico de AAPL',
+  instruments: [
+    {
+      uniqueKey: 'AAPL_US',
+      symbol: 'AAPL',
+    },
+  ],
+});
+
+// Widget de tabla
+const tableWidget = await marketsSDK.createWidget({
+  workspaceId: 'workspace-123',
+  type: 'DYNAMIC_TABLE',
+  name: 'Tabla de Precios',
+  instruments: [
+    {
+      uniqueKey: 'AAPL_US',
+      symbol: 'AAPL',
+    },
+    {
+      uniqueKey: 'MSFT_US',
+      symbol: 'MSFT',
+    },
+  ],
+});
+
+console.log('Widget creado:', chartWidget);
+```
+
+#### Tipos de Widgets Disponibles
+
+```typescript
+// Tipos soportados:
+// - 'DYNAMIC_TABLE': Tabla dinámica
+// - 'PREDEFINED_TABLE': Tabla predefinida
+// - 'CUSTOM_TABLE': Tabla personalizada
+// - 'NEWS_LIST': Lista de noticias
+// - 'TICKER_TAPE': Cinta de ticker
+// - 'CHART': Gráfico
+// - 'UNKNOWN': Tipo desconocido
+```
+
+#### Actualizar Instrumentos del Widget
+
+```typescript
+const updatedInstruments = await marketsSDK.updateWidgetInstruments({
+  widgetId: 'widget-123',
+  instruments: {
+    keys: ['AAPL_US', 'MSFT_US', 'GOOGL_US'],
+  },
+});
+
+console.log('Instrumentos actualizados:', updatedInstruments);
+```
+
+#### Eliminar Widget
+
+```typescript
+const result = await marketsSDK.deleteWidget('widget-123');
+console.log('Resultado:', result);
+```
+
+#### Obtener Widgets del Proyecto
+
+```typescript
+const projectWidgets = await marketsSDK.getProjectWidgets({
+  projectId: 'project-123',
+});
+
+console.log('Widgets del proyecto:', projectWidgets);
+```
+
+### 🏢 Gestión de Espacios de Trabajo
+
+#### Crear Espacio de Trabajo
+
+```typescript
+const workspace = await marketsSDK.createWorkspace({
+  name: 'Mi Dashboard de Trading',
+  description: 'Espacio de trabajo personal para análisis de mercado',
+  userId: 'user-123', // Opcional: asociar a usuario específico
+  projectId: 'project-123', // Opcional: asociar a proyecto específico
+});
+
+console.log('Espacio de trabajo creado:', workspace);
+```
+
+#### Obtener Espacios de Trabajo
+
+```typescript
+// Obtener todos los espacios de trabajo
+const allWorkspaces = await marketsSDK.getWorkspaces({
+  projectId: 'project-123', // ID del proyecto requerido
+  params: {
+    instruments: {
+      options: {
+        limit: 100,
+        offset: 0,
+        sort: { field: 'name', direction: 'asc' }, // Ordenar por nombre ascendente
+      },
+    },
+  },
+});
+
+// Obtener espacios de trabajo por usuario
+const userWorkspaces = await marketsSDK.getWorkspacesByUser({
+  userId: 'user-123',
+  params: {
+    instruments: {
+      options: {
+        limit: 50,
+        offset: 0,
+        sort: { field: 'createdAt', direction: 'desc' }, // Ordenar por fecha de creación descendente
+      },
+    },
+  },
+});
+
+// Obtener espacios de trabajo específicos del usuario
+const specificUserWorkspaces = await marketsSDK.getUserWorkspaces({
+  connectionId: 'connection-123',
+});
+
+console.log('Espacios de trabajo:', allWorkspaces);
+
+**Nota importante**: Los métodos `getWorkspaces()` y `getWorkspacesByUser()` requieren un `projectId` o `userId` respectivamente, y los parámetros de paginación (`limit`, `offset`) y ordenamiento (`sort`) deben estar anidados dentro de `params.instruments.options`.
+```
+
+#### Obtener Detalles del Espacio de Trabajo
+
+```typescript
+const workspaceDetails = await marketsSDK.getWorkspace({
+  workspaceId: 'workspace-123',
+});
+
+console.log('Detalles del workspace:', workspaceDetails);
+console.log('Widgets en el workspace:', workspaceDetails.widgets);
+```
+
+#### Eliminar Espacio de Trabajo
+
+```typescript
+const result = await marketsSDK.deleteWorkspace({
+  id: 'workspace-123',
+});
+
+console.log('Resultado:', result);
+```
+
+### 📈 Datos de Gráficos
+
+#### Obtener Datos de Gráfico
+
+```typescript
+// Gráfico diario
+const dailyChart = await marketsSDK.getChartData({
+  instrumentKey: 'AAPL_US',
+  period: {
+    type: 'day',
+    value: 1,
+    interval: 1,
+  },
+});
+
+// Gráfico semanal
+const weeklyChart = await marketsSDK.getChartData({
+  instrumentKey: 'AAPL_US',
+  period: {
+    type: 'week',
+    value: 4,
+    interval: 1,
+  },
+});
+
+// Gráfico mensual
+const monthlyChart = await marketsSDK.getChartData({
+  instrumentKey: 'AAPL_US',
+  period: {
+    type: 'month',
+    value: 12,
+    interval: 1,
+  },
+});
+
+console.log('Datos del gráfico diario:', dailyChart);
+```
+
+#### Tipos de Períodos Disponibles
+
+```typescript
+// Tipos de período soportados:
+// - 'day': Períodos diarios
+// - 'week': Períodos semanales
+// - 'month': Períodos mensuales
+// - 'year': Períodos anuales
+
+// Ejemplos de configuración:
+const periods = {
+  // 1 día con intervalos de 1 hora
+  daily: { type: 'day', value: 1, interval: 1 },
+  
+  // 5 días con intervalos de 1 día
+  week: { type: 'day', value: 5, interval: 1 },
+  
+  // 4 semanas con intervalos de 1 semana
+  monthly: { type: 'week', value: 4, interval: 1 },
+  
+  // 12 meses con intervalos de 1 mes
+  yearly: { type: 'month', value: 12, interval: 1 },
+};
+```
+
+## 🔧 Ejemplos Prácticos Completos
+
+### 📱 Dashboard de Trading Completo
+
+```typescript
+import InfoselMarkets from '@infosel-sdk/markets';
+import { InfoselSdkManager, AuthConfigurationBuilder } from '@infosel-sdk/core';
+
+class TradingDashboard {
+  private marketsSDK: InfoselMarkets;
+
+  constructor() {
+    this.initializeSDK();
+  }
+
+  private async initializeSDK() {
+    const authConfig = AuthConfigurationBuilder.keyCloak()
+      .withRealm('hub')
+      .withEnvironment('qa')
+      .withCredentials({
+        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,
+    });
+
+    this.marketsSDK = InfoselMarkets.init({ sdkManager });
+  }
+
+  // Crear dashboard completo
+  async createCompleteDashboard(userId: string) {
+    try {
+      // 1. Crear espacio de trabajo
+      const workspace = await this.marketsSDK.createWorkspace({
+        name: 'Dashboard de Trading',
+        description: 'Dashboard completo para análisis de mercado',
+        userId,
+        // Nota: userId y projectId son mutuamente excluyentes
+        // Si se proporciona userId, no se debe incluir projectId
+      });
+
+      // 2. Crear widget de gráfico para AAPL
+      const chartWidget = await this.marketsSDK.createWidget({
+        workspaceId: workspace.id,
+        type: 'CHART',
+        name: 'Gráfico AAPL',
+        instruments: [{ uniqueKey: 'AAPL_US', symbol: 'AAPL' }],
+      });
+
+      // 3. Crear widget de tabla para múltiples instrumentos
+      const tableWidget = await this.marketsSDK.createWidget({
+        workspaceId: workspace.id,
+        type: 'DYNAMIC_TABLE',
+        name: 'Portafolio',
+        instruments: [
+          { uniqueKey: 'AAPL_US', symbol: 'AAPL' },
+          { uniqueKey: 'MSFT_US', symbol: 'MSFT' },
+          { uniqueKey: 'GOOGL_US', symbol: 'GOOGL' },
+        ],
+      });
+
+      // 4. Obtener datos del gráfico
+      const chartData = await this.marketsSDK.getChartData({
+        instrumentKey: 'AAPL_US',
+        period: { type: 'day', value: 30, interval: 1 },
+      });
+
+      // 5. Obtener perfil del instrumento
+      const profile = await this.marketsSDK.getInstrumentDetailProfile({
+        instrumentId: 'AAPL_US',
+      });
+
+      return {
+        workspace,
+        widgets: [chartWidget, tableWidget],
+        chartData,
+        profile,
+      };
+    } catch (error) {
+      console.error('Error creando dashboard:', error);
+      throw error;
+    }
+  }
+
+  // Buscar instrumentos
+  async searchInstruments(query: string, limit: number = 10) {
+    try {
+      const results = await this.marketsSDK.searchInstruments({
+        query,
+        limit,
+      });
+      return results;
+    } catch (error) {
+      console.error('Error buscando instrumentos:', error);
+      throw error;
+    }
+  }
+
+  // Obtener datos financieros
+  async getFinancialData(instrumentId: string) {
+    try {
+      const [quarterly, annual, profile] = await Promise.all([
+        this.marketsSDK.getInstrumentDetailFinancialQuartely({
+          instrumentId,
+          period: 'QUARTERLY',
+        }),
+        this.marketsSDK.getInstrumentDetailFinancialAnnual({
+          instrumentId,
+          period: 'ANNUAL',
+        }),
+        this.marketsSDK.getInstrumentDetailProfile({
+          instrumentId,
+        }),
+      ]);
+
+      return { quarterly, annual, profile };
+    } catch (error) {
+      console.error('Error obteniendo datos financieros:', error);
+      throw error;
+    }
+  }
+}
+
+// Uso del dashboard
+async function main() {
+  const dashboard = new TradingDashboard();
+  
+  try {
+    // Crear dashboard completo
+    const result = await dashboard.createCompleteDashboard('user-123');
+    console.log('Dashboard creado:', result);
+
+    // Buscar instrumentos
+    const searchResults = await dashboard.searchInstruments('TECH', 5);
+    console.log('Resultados de búsqueda:', searchResults);
+
+    // Obtener datos financieros
+    const financialData = await dashboard.getFinancialData('AAPL_US');
+    console.log('Datos financieros:', financialData);
+  } catch (error) {
+    console.error('Error en main:', error);
+  }
+}
+
+main();
+```
+
+### 🔍 Sistema de Búsqueda Avanzada
+
+```typescript
+class AdvancedInstrumentSearch {
+  private marketsSDK: InfoselMarkets;
+
+  constructor(marketsSDK: InfoselMarkets) {
+    this.marketsSDK = marketsSDK;
+  }
+
+  // Búsqueda con múltiples filtros
+  async searchWithFilters(options: {
+    query: string;
+    marketTypes?: number[]; // Tipos de mercado (ej: [1, 2] para Acciones y Bonos)
+    valueTypes?: number[];  // Tipos de valor (ej: [1] para Equity)
+    exchanges?: number[];   // Exchanges (ej: [1, 2] para NYSE y NASDAQ)
+    limit?: number;
+  }) {
+    try {
+      const results = await this.marketsSDK.searchInstruments({
+        query: options.query,
+        limit: options.limit || 20,
+        marketTypeIds: options.marketTypes,
+        valueTypeIds: options.valueTypes,
+        exchangeIds: options.exchanges,
+      });
+
+      return results;
+    } catch (error) {
+      console.error('Error en búsqueda avanzada:', error);
+      throw error;
+    }
+  }
+
+  // Búsqueda por sector (filtra solo acciones)
+  async searchBySector(sector: string, limit: number = 15) {
+    return this.searchWithFilters({
+      query: sector,
+      limit,
+      marketTypes: [1], // 1 = Mercado de acciones
+    });
+  }
+
+  // Búsqueda por exchange específico
+  async searchByExchange(exchange: string, limit: number = 15) {
+    return this.searchWithFilters({
+      query: exchange,
+      limit,
+      exchanges: [1, 2], // 1 = NYSE, 2 = NASDAQ
+    });
+  }
+}
+
+// Uso del sistema de búsqueda
+const searchSystem = new AdvancedInstrumentSearch(marketsSDK);
+
+// Búsqueda por sector
+const techStocks = await searchSystem.searchBySector('TECHNOLOGY');
+console.log('Acciones de tecnología:', techStocks);
+
+// Búsqueda por exchange
+const nasdaqStocks = await searchSystem.searchByExchange('NASDAQ');
+console.log('Acciones del NASDAQ:', nasdaqStocks);
+```
+
+### 📊 Gestor de Widgets
+
+```typescript
+class WidgetManager {
+  private marketsSDK: InfoselMarkets;
+
+  constructor(marketsSDK: InfoselMarkets) {
+    this.marketsSDK = marketsSDK;
+  }
+
+  // Crear widget de gráfico
+  async createChartWidget(workspaceId: string, instrument: string, name: string) {
+    try {
+      const widget = await this.marketsSDK.createWidget({
+        workspaceId,
+        type: 'CHART',
+        name,
+        instruments: [{ uniqueKey: instrument, symbol: instrument }],
+      });
+
+      return widget;
+    } catch (error) {
+      console.error('Error creando widget de gráfico:', error);
+      throw error;
+    }
+  }
+
+  // Crear widget de tabla
+  async createTableWidget(
+    workspaceId: string,
+    instruments: string[],
+    name: string
+  ) {
+    try {
+      const widget = await this.marketsSDK.createWidget({
+        workspaceId,
+        type: 'DYNAMIC_TABLE',
+        name,
+        instruments: instruments.map(instrument => ({
+          uniqueKey: instrument,
+          symbol: instrument,
+        })),
+      });
+
+      return widget;
+    } catch (error) {
+      console.error('Error creando widget de tabla:', error);
+      throw error;
+    }
+  }
+
+  // Actualizar instrumentos de un widget
+  async updateWidgetInstruments(widgetId: string, instruments: string[]) {
+    try {
+      const updatedInstruments = await this.marketsSDK.updateWidgetInstruments({
+        widgetId,
+        instruments: { keys: instruments },
+      });
+
+      return updatedInstruments;
+    } catch (error) {
+      console.error('Error actualizando instrumentos:', error);
+      throw error;
+    }
+  }
+
+  // Eliminar widget
+  async deleteWidget(widgetId: string) {
+    try {
+      const result = await this.marketsSDK.deleteWidget(widgetId);
+      return result;
+    } catch (error) {
+      console.error('Error eliminando widget:', error);
+      throw error;
+    }
+  }
+}
+
+// Uso del gestor de widgets
+const widgetManager = new WidgetManager(marketsSDK);
+
+// Crear widgets en un workspace
+async function setupWorkspaceWidgets(workspaceId: string) {
+  try {
+    // Widget de gráfico para AAPL
+    const chartWidget = await widgetManager.createChartWidget(
+      workspaceId,
+      'AAPL_US',
+      'Gráfico de Apple'
+    );
+
+    // Widget de tabla para portafolio
+    const tableWidget = await widgetManager.createTableWidget(
+      workspaceId,
+      ['AAPL_US', 'MSFT_US', 'GOOGL_US'],
+      'Portafolio Principal'
+    );
+
+    console.log('Widgets creados:', { chartWidget, tableWidget });
+    return { chartWidget, tableWidget };
+  } catch (error) {
+    console.error('Error configurando widgets:', error);
+    throw error;
+  }
+}
+```
+
+## 📚 Referencia de API
+
+### Clases Principales
+
+#### `InfoselMarkets`
+
+Punto de entrada principal para el SDK de Mercados. Se inicializa usando el método estático `init()` que recibe el `InfoselSdkManager`.
+
+#### `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.
+
+#### `MarketsMapper`
+
+Mapeador de datos para convertir entre modelos de API y dominio.
+
+### Métodos Disponibles
+
+#### 🔍 Gestión de Instrumentos
+
+| Método | Descripción | Parámetros |
+|--------|-------------|------------|
+| `searchInstruments()` | Buscar instrumentos financieros | `SearchInstrumentRequest` |
+| `getInstruments()` | Obtener lista de instrumentos | `GetInstrumentsRequest` |
+| `createInstrument()` | Crear nuevo instrumento | `CreateInstrumentRequest` |
+| `deleteInstrument()` | Eliminar instrumento | `string` (ID) |
+| `getInstrumentFields()` | Obtener campos del instrumento | `string` (ID) |
+
+#### 📊 Detalles de Instrumentos
+
+| Método | Descripción | Parámetros |
+|--------|-------------|------------|
+| `getInstrumentDetailProfile()` | Obtener perfil del instrumento | `InstrumentDetailProfileRequest` |
+| `getInstrumentDetailFinancialQuartely()` | Datos financieros trimestrales | `InstrumentDetailFinancialQuarterlyRequest` |
+| `getInstrumentDetailFinancialAnnual()` | Datos financieros anuales | `InstrumentDetailFinancialAnnualRequest` |
+| `getInstrumentDetailFinancialReasons()` | Razones financieras | `InstrumentDetailFinancialReasonsRequest` |
+| `getInstrumentReportFinancialReasons()` | Reportes financieros con razones | `InstrumentReportFinancialReasonsRequest` |
+
+#### 🎯 Gestión de Widgets
+
+| Método | Descripción | Parámetros |
+|--------|-------------|------------|
+| `createWidget()` | Crear nuevo widget | `CreateWidgetRequest` |
+| `deleteWidget()` | Eliminar widget | `string` (ID) |
+| `updateWidgetInstruments()` | Actualizar instrumentos del widget | `UpdateWidgetInstrumentsRequest` |
+| `getProjectWidgets()` | Obtener widgets del proyecto | `GetProjectWidgetsRequest` |
+
+#### 🏢 Gestión de Espacios de Trabajo
+
+| Método | Descripción | Parámetros |
+|--------|-------------|------------|
+| `createWorkspace()` | Crear nuevo espacio de trabajo | `CreateWorkspaceRequest` |
+| `getWorkspaces()` | Obtener espacios de trabajo | `GetWorkspacesRequest` |
+| `getWorkspacesByUser()` | Obtener espacios de trabajo del usuario | `GetWorkspacesByUserRequest` |
+| `getUserWorkspaces()` | Obtener espacios de trabajo específicos del usuario | `GetUserWorkspaceRequest` |
+| `getWorkspace()` | Obtener detalles del workspace | `GetWorkspaceRequest` |
+| `deleteWorkspace()` | Eliminar espacio de trabajo | `DeleteWorkspaceRequest` |
+
+#### 📈 Datos de Gráficos
+
+| Método | Descripción | Parámetros |
+|--------|-------------|------------|
+| `getChartData()` | Obtener datos de gráficos | `ChartRequest` |
+
+### Entidades
+
+#### Entidades Principales
+
+- `Instrument`: Representación de instrumento financiero
+- `Widget`: Configuración y datos del widget
+- `Workspace`: Espacio de trabajo del usuario
+- `ChartItem`: Punto de datos del gráfico
+- `SearchResultItem`: Elemento de resultado de búsqueda
+
+#### Entidades de Solicitud/Respuesta
+
+- `SearchInstrumentsRequest`: Parámetros de búsqueda
+- `CreateWidgetRequest`: Parámetros de creación de widget
+- `CreateWorkspaceRequest`: Parámetros de creación de espacio de trabajo
+- `ChartRequest`: Parámetros de solicitud de datos de gráfico
+
+#### Tipos de Widgets
+
+- `DYNAMIC_TABLE`: Tabla dinámica con datos en tiempo real
+- `PREDEFINED_TABLE`: Tabla predefinida con estructura fija
+- `CUSTOM_TABLE`: Tabla personalizable
+- `NEWS_LIST`: Lista de noticias financieras
+- `TICKER_TAPE`: Cinta de ticker con precios
+- `CHART`: Gráfico de precios y volúmenes
+
+#### Tipos de Períodos de Gráficos
+
+- `day`: Períodos diarios
+- `week`: Períodos semanales
+- `month`: Períodos mensuales
+- `year`: Períodos anuales
+
+## 🔗 Dependencias
+
+- `@infosel-sdk/core`: Funcionalidad core 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
+
+## 🧪 Testing
+
+### Pruebas Unitarias
+
+```bash
+# Ejecutar tests unitarios
+npm test
+
+# Ejecutar tests con cobertura
+npm run test:coverage
+```
+
+### Pruebas E2E (End-to-End)
+
+Las pruebas e2e utilizan información real y autenticación con Keycloak para verificar el funcionamiento completo del SDK.
+
+#### Configuración
+
+```bash
+# Variables de entorno requeridas
+KEYCLOAK_CLIENT_ID=
+KEYCLOAK_CLIENT_SECRET=
+TEST_ENV=qa                    # qa, prod, preprod
+TEST_TIMEOUT=30000            # Timeout en milisegundos
+DEBUG_E2E=true                # Habilitar logs de debug
+```
+
+#### Ejecución
+
+```bash
+# Ejecutar todas las pruebas e2e
+npm run test:e2e
+
+# Ejecutar con debug habilitado
+npm run test:e2e:debug
+
+# Usando el script de utilidad
+./src/__tests__/e2e/run-e2e.sh
+
+# Con opciones personalizadas
+./src/__tests__/e2e/run-e2e.sh -d -e prod -t 60000
+```
+
+#### Script de Utilidad
+
+El script `run-e2e.sh` proporciona una interfaz fácil para ejecutar pruebas e2e:
+
+```bash
+# Mostrar ayuda
+./src/__tests__/e2e/run-e2e.sh --help
+
+# Ejecutar con configuración por defecto
+./src/__tests__/e2e/run-e2e.sh
+
+# Ejecutar en entorno de producción con debug
+./src/__tests__/e2e/run-e2e.sh -d -e prod
+
+# Ejecutar con credenciales personalizadas
+./src/__tests__/e2e/run-e2e.sh -c my-client -s my-secret
+```
+
+#### Pruebas Incluidas
+
+- **SDK Core Configuration**: Verificación de inicialización y autenticación
+- **Markets API Integration**: Conexión real a la API de markets
+- **Workspace Operations**: Operaciones de workspace con datos reales
+- **Performance and Reliability**: Verificación de tiempos de respuesta y concurrencia
+
+#### Notas Importantes
+
+- Las pruebas e2e requieren conectividad a internet
+- Utilizan servicios reales, no mocks
+- Los timeouts son más largos que en pruebas unitarias
+- Se ejecutan secuencialmente para evitar conflictos
+- No se incluyen en el coverage report
+
+Para más detalles, consulta el [README de pruebas e2e](src/__tests__/e2e/README.md).
+
+
+## 📞 Soporte
+
+Para soporte y preguntas, por favor contacta al equipo de desarrollo de Infosel.
+
+## 🔗 Paquetes Relacionados
+
+- `@infosel-sdk/core`: Funcionalidad core del SDK (versión ^0.0.4)
+- `@infosel-sdk/news`: SDK de noticias y contenido
+- `@infosel-sdk/securities`: SDK de valores y trading
+
+---