@infosel-sdk/news/README.md

Financial news SDK for Infosel platform. Provides comprehensive tools for accessing, filtering, and managing financial news data, including news services, sectors, and detailed news items with advanced filtering capabilities.

# @infosel-sdk/news

SDK de noticias financieras para la plataforma Infosel. Proporciona herramientas integrales para acceder, filtrar y gestionar datos de noticias financieras, incluyendo servicios de noticias, sectores y elementos de noticias detallados con capacidades de filtrado avanzado.

## 🚀 Características

- **Recuperación de Noticias**: Obtener elementos de noticias con filtrado avanzado y paginación
- **Gestión de Servicios**: Acceder a servicios de noticias disponibles y sus descripciones
- **Clasificación por Sectores**: Navegar por sectores de noticias para contenido dirigido
- **Noticias Detalladas**: Recuperar detalles completos de elementos de noticias incluyendo archivos adjuntos
- **Filtrado Avanzado**: Filtrar por rango de fechas, servicios, sectores y consultas personalizadas
- **Múltiples Tipos de Lista**: Soporte para noticias trending, más relevantes, últimas y relacionadas
- **Noticias por Sector**: Filtrar noticias específicamente por sector económico
- **Noticias del Día**: Obtener noticias publicadas en el día actual
- **Noticias Más Leídas**: Acceder a las noticias con mayor engagement
- **Metadatos de Respuesta**: Información detallada sobre paginación y estado de las consultas

## 📦 Instalación

```bash
npm install @infosel-sdk/news
```

## 🔧 Prerrequisitos

Este SDK requiere que el paquete `@infosel-sdk/core` esté instalado y configurado:

```bash
npm install @infosel-sdk/core
```

## 🏗️ Configuración

```typescript
import { InfoselSdkManager } from '@infosel-sdk/core';
import InfoselNews from '@infosel-sdk/news';

// Inicializar el gestor del SDK
const sdkManager = InfoselSdkManager.init({
  mode: 'prod', // o 'qa' para pruebas
  // ... otras opciones de configuración
});

// Inicializar el SDK de Noticias
const newsSDK = InfoselNews.init({ sdkManager });
```

## 📚 Referencia de la API

### Métodos Principales

#### 1. `getServices()` - Obtener Servicios de Noticias Disponibles

Recupera todos los servicios de noticias disponibles con sus IDs y descripciones.

```typescript
const services = await newsSDK.getServices();
console.log(services);
// Salida: [
//   { id: 1, description: "Noticias Financieras" },
//   { id: 2, description: "Actualizaciones de Mercado" },
//   { id: 3, description: "Reportes Económicos" }
// ]
```

#### 2. `getSectors()` - Obtener Sectores de Noticias

Recupera todos los sectores de noticias disponibles para categorización.

```typescript
const sectors = await newsSDK.getSectors();
console.log(sectors);
// Salida: [
//   { id: 1, description: "Tecnología" },
//   { id: 2, description: "Finanzas" },
//   { id: 3, description: "Salud" }
// ]
```

#### 3. `getNews(request: NewsRequest)` - Obtener Elementos de Noticias

Recupera elementos de noticias basados en criterios y filtros especificados.

```typescript
const newsRequest = {
  listType: NewsListType.LATEST_NEWS,
  services: [1, 2], // Filtrar por IDs de servicios específicos
  sectors: [1, 3], // Filtrar por IDs de sectores específicos
  dateRange: {
    start: new Date('2024-01-01'),
    end: new Date('2024-01-31'),
  },
  pagination: {
    page: 1,
    rows: 20,
  },
  filter: {
    type: NewsFilterType.KEYWORDS,
    query: 'bitcoin criptomonedas',
  },
};

const newsItems = await newsSDK.getNews(newsRequest);
console.log(newsItems);
```

#### 4. `getDetail(id: number)` - Obtener Detalle de Elemento de Noticia

Recupera información detallada sobre un elemento de noticia específico por ID.

```typescript
const newsDetail = await newsSDK.getDetail(12345);
console.log(newsDetail);
```

#### 5. `getNewsBySector(sectorId: number, request?: NewsSectorRequest)` - Obtener Noticias por Sector

Recupera noticias específicas de un sector económico particular con opciones de filtrado avanzado.

```typescript
const sectorNews = await newsSDK.getNewsBySector(1, {
  services: [1, 2], // Filtrar por servicios específicos
  rows: 20,
  page: 1,
  symbol: 'AAPL', // Filtrar por símbolo financiero
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  newsTypeId: 1, // Tipo específico de noticia
});

console.log(`Noticias del sector: ${sectorNews.data.length}`);
console.log('Metadatos:', sectorNews.metadata);
```

#### 6. `getNewsToday(request?: NewsTodayRequest)` - Obtener Noticias del Día

Recupera noticias publicadas en el día actual con múltiples opciones de filtrado.

```typescript
const todayNews = await newsSDK.getNewsToday({
  services: [1], // Solo noticias financieras
  limit: 50, // Límite de resultados
  offset: 0, // Desplazamiento para paginación
  onlyTop: true, // Solo noticias destacadas
  rows: 25,
  page: 1,
  sourcesId: [1, 2], // Fuentes específicas
  sectors: [1, 3], // Sectores específicos
  symbol: 'TSLA', // Símbolo financiero
  newsTypeId: [1, 2], // Tipos de noticia
});

console.log(`Noticias del día: ${todayNews.data.length}`);
todayNews.data.forEach(news => {
  console.log(`📰 ${news.header} - ${news.date} ${news.time}`);
});
```

#### 7. `getNewsDetails(request?: NewsDetailsRequest)` - Obtener Detalles de Noticias

Recupera noticias con información detallada y opciones de búsqueda avanzada.

```typescript
const detailedNews = await newsSDK.getNewsDetails({
  services: [1, 2],
  rows: 30,
  page: 1,
  limit: 100,
  offset: 0,
  symbol: 'MSFT',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  newsTypeId: 1,
  keyword: 'inteligencia artificial',
});

console.log(`Noticias detalladas encontradas: ${detailedNews.data.length}`);
detailedNews.data.forEach(news => {
  console.log(`📰 ${news.header}`);
  console.log(`🏷️ ${news.tags}`);
  console.log(`🌍 ${news.countries}`);
  console.log(`📄 ${news.body.substring(0, 100)}...`);
});
```

#### 8. `getNewsMostRead(request?: NewsMostReadRequest)` - Obtener Noticias Más Leídas

Recupera las noticias con mayor engagement y lectura, perfectas para análisis de tendencias.

```typescript
const mostReadNews = await newsSDK.getNewsMostRead({
  services: [1], // Servicios específicos
  sourcesId: [1, 2, 3], // Fuentes de noticias
  rows: 50,
  page: 1,
});

console.log(`Noticias más leídas: ${mostReadNews.data.length}`);
mostReadNews.data.forEach((news, index) => {
  console.log(`${index + 1}. 📰 ${news.header}`);
  console.log(`   📅 ${news.date} ${news.time}`);
  console.log(`   🏷️ ${news.tags}`);
  console.log(`   📊 Prioridad: ${news.priority}`);
  console.log(`   📎 Archivos: ${news.numberAttachedFiles}`);
});
```

## 🏷️ Tipos de Datos

### NewsRequest

Interfaz para configurar búsqueda y filtrado de noticias:

```typescript
interface NewsRequest {
  listType?: NewsListType; // Tipo de lista de noticias a recuperar
  services?: number[]; // Array de IDs de servicios para filtrar
  sectors?: number[]; // Array de IDs de sectores para filtrar
  dateRange?: {
    // Filtro de rango de fechas
    start: Date;
    end: Date;
  };
  pagination?: {
    // Configuración de paginación
    page: number;
    rows: number;
  };
  filter?: {
    // Filtrado basado en texto
    type: NewsFilterType;
    query: string;
  };
}
```

### NewsSectorRequest

Interfaz para filtrar noticias por sector:

```typescript
interface NewsSectorRequest {
  services?: number[]; // Servicios específicos
  rows?: number; // Número de filas por página
  page?: number; // Número de página
  symbol?: string; // Símbolo financiero
  startDate?: Date; // Fecha de inicio
  endDate?: Date; // Fecha de fin
  newsTypeId?: number; // ID del tipo de noticia
}
```

### NewsTodayRequest

Interfaz para obtener noticias del día:

```typescript
interface NewsTodayRequest {
  services?: number[]; // Servicios específicos
  limit?: number; // Límite de resultados
  offset?: number; // Desplazamiento
  onlyTop?: boolean; // Solo noticias destacadas
  rows?: number; // Filas por página
  page?: number; // Número de página
  sourcesId?: number[]; // IDs de fuentes
  sectors?: number[]; // IDs de sectores
  symbol?: string; // Símbolo financiero
  newsTypeId?: number[]; // IDs de tipos de noticia
}
```

### NewsDetailsRequest

Interfaz para obtener noticias con detalles completos:

```typescript
interface NewsDetailsRequest {
  services?: number[]; // Servicios específicos
  rows?: number; // Filas por página
  page?: number; // Número de página
  limit?: number; // Límite de resultados
  offset?: number; // Desplazamiento
  symbol?: string; // Símbolo financiero
  startDate?: Date; // Fecha de inicio
  endDate?: Date; // Fecha de fin
  newsTypeId?: number; // ID del tipo de noticia
  keyword?: string; // Palabra clave para búsqueda
}
```

### NewsMostReadRequest

Interfaz para obtener noticias más leídas:

```typescript
interface NewsMostReadRequest {
  services?: number[]; // Servicios específicos
  sourcesId?: number[]; // IDs de fuentes
  rows?: number; // Filas por página
  page?: number; // Número de página
}
```

### NewsItem

Información completa del elemento de noticia:

```typescript
interface NewsItem {
  id: number; // Identificador único
  serviceId: number; // ID del servicio asociado
  priority: number; // Nivel de prioridad de la noticia
  sectors: NewsSector[]; // Sectores asociados
  date: Date; // Fecha de publicación
  source: string; // Fuente de la noticia
  countries: string[]; // Países relacionados
  tags: string[]; // Etiquetas asociadas
  header: string; // Título de la noticia
  abstract: string; // Resumen de la noticia
  body: string; // Contenido completo de la noticia
  symbols: string[]; // Símbolos financieros relacionados
  image: string; // URL de la imagen destacada
  numberOfAttachedFiles: number; // Cantidad de archivos adjuntos
  files: NewsFile[]; // Archivos adjuntos
}
```

### NewsMetadata

Metadatos de respuesta para paginación y estado:

```typescript
interface NewsMetadata {
  statuscode: number; // Código de estado de la respuesta
  pagination?: {
    // Información de paginación
    total: number; // Total de registros
    limit: number; // Límite por página
    offset: number; // Desplazamiento actual
  };
  totalRegistros?: number; // Total de registros (alternativo)
}
```

### NewsListType

Enumeración de tipos de lista de noticias disponibles:

```typescript
enum NewsListType {
  MOST_RELEVANT = 1, // Noticias más relevantes
  MOST_READ = 2, // Artículos más leídos
  RELATED = 3, // Noticias relacionadas
  TRENDING = 4, // Temas trending
  NEWS_BY_INSTRUMENT = 8, // Noticias por instrumento financiero
  LATEST_NEWS = 9, // Últimas noticias
  FAVORITE = 10, // Noticias favoritas/guardadas
}
```

### NewsFilterType

Enumeración de tipos de filtro:

```typescript
enum NewsFilterType {
  NO_FILTER = 0, // Sin filtro aplicado
  KEYWORDS = 1, // Filtrar por palabras clave
  TAGS = 2, // Filtrar por etiquetas
}
```

### NewsService & NewsSector

Interfaces básicas de entidades:

```typescript
interface NewsService {
  id: number; // Identificador del servicio
  description: string; // Descripción del servicio
}

interface NewsSector {
  id: number; // Identificador del sector
  description: string; // Descripción del sector
}
```

### NewsFile

Información de archivo adjunto:

```typescript
interface NewsFile {
  type: NewsFileType; // Tipo de archivo (Archivo, Imagen, o -)
  url: string; // URL de descarga del archivo
  size: number; // Tamaño del archivo en bytes
  format: string; // Formato del archivo
  alt: string; // Texto alternativo
}

type NewsFileType = 'File' | 'Image' | '-';
```

## 💡 Ejemplos de Uso

### Ejemplo 1: Dashboard de Noticias Financieras

```typescript
import { NewsListType, NewsFilterType } from '@infosel-sdk/news';

// Obtener últimas noticias financieras
const financialNews = await newsSDK.getNews({
  listType: NewsListType.LATEST_NEWS,
  services: [1], // Servicio de noticias financieras
  pagination: {
    page: 1,
    rows: 10,
  },
});

// Mostrar elementos de noticias
financialNews.forEach(news => {
  console.log(`📰 ${news.header}`);
  console.log(`📅 ${news.date.toLocaleDateString()}`);
  console.log(`🏷️ ${news.tags.join(', ')}`);
  console.log(`📄 ${news.abstract}`);
  console.log('---');
});
```

### Ejemplo 2: Monitoreo de Noticias por Sector

```typescript
// Obtener noticias del sector tecnológico de la última semana
const techNews = await newsSDK.getNewsBySector(1, {
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
  endDate: new Date(),
  rows: 25,
  page: 1,
});

console.log(
  `Se encontraron ${techNews.data.length} elementos de noticias tecnológicas`,
);
console.log('Metadatos de paginación:', techNews.metadata);
```

### Ejemplo 3: Búsqueda Avanzada con Palabras Clave

```typescript
// Buscar noticias sobre empresas específicas
const companyNews = await newsSDK.getNewsDetails({
  keyword: 'Apple Microsoft Google',
  limit: 50,
  rows: 15,
  page: 1,
});

// Filtrar por símbolos específicos
const relevantNews = companyNews.data.filter(
  news =>
    news.header.toLowerCase().includes('apple') ||
    news.header.toLowerCase().includes('microsoft') ||
    news.header.toLowerCase().includes('google'),
);

console.log(`Noticias relevantes encontradas: ${relevantNews.length}`);
```

### Ejemplo 4: Análisis de Noticias Trending

```typescript
// Obtener noticias más leídas para análisis de tendencias
const mostReadNews = await newsSDK.getNewsMostRead({
  services: [1, 2], // Servicios financieros y de mercado
  rows: 100,
  page: 1,
});

// Analizar temas trending
const trendingTopics = mostReadNews.data.reduce((acc, news) => {
  const tags = news.tags.split(',').map(tag => tag.trim());
  tags.forEach(tag => {
    acc[tag] = (acc[tag] || 0) + 1;
  });
  return acc;
}, {} as Record<string, number>);

// Ordenar por frecuencia
const sortedTopics = Object.entries(trendingTopics)
  .sort(([, a], [, b]) => b - a)
  .slice(0, 10);

console.log('🔥 Temas Trending Principales:');
sortedTopics.forEach(([topic, count]) => {
  console.log(`${topic}: ${count} menciones`);
});
```

### Ejemplo 5: Noticias del Día con Filtros Avanzados

```typescript
// Obtener noticias destacadas del día en sectores específicos
const todayHighlights = await newsSDK.getNewsToday({
  onlyTop: true, // Solo noticias destacadas
  sectors: [1, 2, 3], // Tecnología, Finanzas, Salud
  services: [1], // Servicio principal
  limit: 30,
  rows: 15,
  page: 1,
});

console.log(`📰 Noticias destacadas del día: ${todayHighlights.data.length}`);

// Agrupar por sector
const newsBySector = todayHighlights.data.reduce((acc, news) => {
  const sector = news.sectors || 'General';
  if (!acc[sector]) acc[sector] = [];
  acc[sector].push(news);
  return acc;
}, {} as Record<string, typeof todayHighlights.data>);

Object.entries(newsBySector).forEach(([sector, news]) => {
  console.log(`\n🏢 ${sector}: ${news.length} noticias`);
  news.forEach(item => {
    console.log(`  • ${item.header} (${item.date} ${item.time})`);
  });
});
```

### Ejemplo 6: Sistema de Monitoreo de Noticias en Tiempo Real

```typescript
// Función para monitorear noticias en tiempo real
async function monitorNews() {
  try {
    // Obtener noticias del día cada hora
    const todayNews = await newsSDK.getNewsToday({
      limit: 100,
      rows: 50,
      page: 1,
    });

    // Obtener noticias más leídas
    const mostRead = await newsSDK.getNewsMostRead({
      rows: 25,
      page: 1,
    });

    // Combinar y analizar
    const allNews = [...todayNews.data, ...mostRead.data];

    console.log(`📊 Resumen de Monitoreo:`);
    console.log(`   • Noticias del día: ${todayNews.data.length}`);
    console.log(`   • Noticias más leídas: ${mostRead.data.length}`);
    console.log(`   • Total analizado: ${allNews.length}`);

    // Detectar noticias urgentes (alta prioridad)
    const urgentNews = allNews.filter(news => news.priority >= 8);
    if (urgentNews.length > 0) {
      console.log(`🚨 Noticias urgentes: ${urgentNews.length}`);
      urgentNews.forEach(news => {
        console.log(`   ⚠️ ${news.header} - Prioridad: ${news.priority}`);
      });
    }
  } catch (error) {
    console.error('Error en monitoreo de noticias:', error);
  }
}

// Ejecutar monitoreo
monitorNews();
```

## 🔍 Manejo de Errores

Los métodos del SDK devuelven Promesas que pueden rechazarse con varios tipos de errores. Siempre envuelve tus llamadas en bloques try-catch:

```typescript
try {
  const news = await newsSDK.getNewsToday({
    limit: 50,
    rows: 10,
    page: 1,
  });
  console.log('Noticias recuperadas exitosamente:', news.data.length);
  console.log('Metadatos:', news.metadata);
} catch (error) {
  console.error('Error al recuperar noticias:', error);
  // Manejar tipos de error específicos apropiadamente
}
```

## 🔗 Paquetes Relacionados

- `@infosel-sdk/core` - Funcionalidad principal del SDK
- `@infosel-sdk/markets` - Datos de mercados financieros
- `@infosel-sdk/securities` - Información de valores
- `@infosel-sdk/users` - Gestión de usuarios

---

Para más información, visita el [Portal de Desarrolladores de Infosel](https://developer.infosel.com) o contacta a nuestro equipo de soporte.