Integro docs faltantes de la rama de franco

backend/docs/FINNHUB.md

@@ -0,0 +1,199 @@
+# FINNHUB.md — Modulo de noticias financieras
+
+Fuente de titulares financieros para el pipeline de IA. Consulta la API REST de Finnhub (free tier) y proporciona noticias filtradas por relevancia al mercado analizado.
+
+**No expone endpoints REST publicos.** Es un modulo interno consumido unicamente por `signals/aiPipeline.js` durante la generacion de senales (cada 5 min).
+
+---
+
+## Variables de entorno
+
+| Variable | Obligatoria | Descripcion |
+|---|---|---|
+| `FINNHUB_API_KEY` | No | API key de Finnhub (finnhub.io). Sin ella el modulo devuelve array vacio y el pipeline usa rule-based. |
+
+---
+
+## API interna
+
+### `getMarketNews(category, limit)`
+
+**Archivo:** `src/finnhub/finnhub.client.js`
+
+Obtiene noticias generales del mercado por categoria.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `category` | string | `"general"` | Categoria: `general`, `forex`, `crypto`, `merger` |
+| `limit` | int | `50` | Maximo de noticias a devolver |
+
+**Retorno:** `Promise<Object[]>` — array de noticias normalizadas.
+
+**Noticia normalizada:**
+
+```json
+{
+  "id": 12345,
+  "headline": "Fed signals potential rate cut...",
+  "summary": "The Federal Reserve hinted at...",
+  "url": "https://example.com/news/12345",
+  "source": "Reuters",
+  "related": "AAPL",
+  "datetime": "2026-05-15T14:30:00.000Z"
+}
+```
+
+---
+
+### `getCompanyNews(symbol, daysBack)`
+
+**Archivo:** `src/finnhub/finnhub.client.js`
+
+Obtiene noticias de una empresa especifica en un rango de fechas.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `symbol` | string | — | Simbolo bursatil (ej. `AAPL`, `TSLA`, `BTC`) |
+| `daysBack` | int | `7` | Dias hacia atras desde hoy |
+
+**Retorno:** `Promise<Object[]>` — noticias normalizadas de la empresa.
+
+---
+
+### `fetchFinancialNews(daysBack)`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Agrega noticias de multiples categorias (`general`, `forex`, `crypto`) para el pipeline de IA.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `daysBack` | int | `7` | No aplica directamente; se usa el rango por defecto de Finnhub |
+
+**Retorno:** `Promise<Object[]>` — hasta 90 noticias agregadas (50 general + 20 forex + 20 crypto).
+
+---
+
+### `filterNewsByRelevance(news, question)`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Filtra noticias por keywords extraidas de la pregunta del mercado. Elimina stop words en ingles y espanol; matching case-insensitive.
+
+**Parametros**
+
+| Param | Tipo | Descripcion |
+|---|---|---|
+| `news` | Object[] | Array de noticias normalizadas |
+| `question` | string | Pregta del mercado (ej. "Will Bitcoin reach $100k?") |
+
+**Retorno:** `Object[]` — noticias que contienen al menos una keyword en `headline` o `summary`.
+
+---
+
+### `fetchHeadlinesForPipeline({ symbols, daysBack, limitPerSymbol })`
+
+**Archivo:** `src/finnhub/finnhub.service.js`
+
+Obtiene noticias de multiples simbolos en paralelo, truncando a maximo 5 simbolos para respetar el rate limit.
+
+**Parametros**
+
+| Param | Tipo | Default | Descripcion |
+|---|---|---|---|
+| `symbols` | string[] | `[]` | Lista de simbolos bursatiles |
+| `daysBack` | int | `7` | Dias hacia atras |
+| `limitPerSymbol` | int | `20` | Maximo de noticias por simbolo |
+
+**Retorno:** `Promise<Object[]>` — noticias agregadas con campo `symbol` anadido.
+
+**Limitacion:** si `symbols.length > 5`, se trunca a 5 y se emite warning en logs.
+
+---
+
+## Pipeline de noticias dentro de la generacion de senales
+
+```
+scheduler.js (cada 5 min)
+    ↓
+aiPipeline.run(market)
+    ↓ Paso 1: Obtener noticias
+    fetchFinancialNews()           → general + forex + crypto
+    ↓ Paso 2: Filtrar por relevancia
+    filterNewsByRelevance(news, market.question)
+    ↓ Paso 3: Filtrar por sentimiento (FinBERT)
+    filterWithFinBERT(headlines)
+    ↓ Paso 4: Generar senal (Qwen3-8B / OpenRouter / rule-based)
+```
+
+**Nota:** si Finnhub no esta configurado o falla, los pasos 1-2 devuelven array vacio y el pipeline continua con rule-based usando el precio del mercado.
+
+---
+
+## Rate limiter y restricciones
+
+| Restriccion | Implementacion |
+|---|---|
+| **Free tier: 60 llamadas/min** | Rate limiter en memoria en `finnhub.client.js`. Si se excede, devuelve `[]`. |
+| **Sin API key** | `ensureApiKey()` devuelve `false`; todas las funciones retornan `[]` sin lanzar error. |
+| **Sin endpoints REST** | El modulo es puramente interno; no se expone via HTTP. |
+| **Limite de 5 simbolos** | `fetchHeadlinesForPipeline` trunca `symbols` a 5 para no saturar el rate limit. |
+| **Errores de red** | Capturados internamente; se loguean como `warn` y se retorna `[]`. |
+
+**Calculo de uso tipico:**
+- `fetchFinancialNews()` = 3 llamadas (general + forex + crypto)
+- Top 20 mercados cada 5 min = 20 x 3 = 60 llamadas/5min (en el limite exacto del free tier)
+
+---
+
+## Ejemplo de uso interno
+
+```js
+// Desde aiPipeline.js
+import { fetchFinancialNews, filterNewsByRelevance } from '../finnhub/finnhub.service.js';
+
+async function run(market) {
+  // 1. Obtener noticias
+  const allNews = await fetchFinancialNews(30);
+
+  // 2. Filtrar por relevancia respecto al mercado
+  const relevant = filterNewsByRelevance(allNews, market.question);
+
+  // 3. Continuar con FinBERT + Qwen3-8B...
+}
+```
+
+---
+
+## Logs esperados
+
+```
+# Sin API key configurada
+[DEBUG] Finnhub API key not configured, returning empty array
+
+# Rate limit excedido
+[WARN] Finnhub rate limit exceeded (60 calls/min), returning empty array
+
+# Pipeline continua sin noticias
+[WARN] news fetch failed, continuing without news
+```
+
+---
+
+## Archivos del modulo
+
+```
+backend/src/finnhub/
+├── finnhub.client.js   # Cliente HTTP + rate limiter
+└── finnhub.service.js  # Logica de negocio y filtrado
+```
+
+---
+
+*Ultima actualizacion: mayo 2026*

backend/src/alerts/alerts.service.js

@@ -22,7 +22,7 @@
 import { z } from 'zod';
 import { alertsRepository } from './alerts.repository.js';
 import { watchlistRepository } from '../watchlist/watchlist.repository.js';
-import { sendMessage } from './telegram.client.js';
+import { sendMessage, formatPriceAlert } from './telegram.client.js';
 import { emitPriceAlert } from '../socket/broadcaster.js';
 import { logger } from '../utils/logger.js';
 
@@ -49,10 +49,7 @@ export const alertsService = {
       const recent = await alertsRepository.findRecent(user.id, market.id, 'price_threshold', DEDUP_WINDOW_MS);
       if (recent) continue;
 
-      const pct = (market.yesPrice * 100).toFixed(1);
-      const threshold = (alertThreshold * 100).toFixed(1);
-      const message =
-        `<b>Price Alert</b>\n${market.question}\nYES: ${pct}% ≥ threshold ${threshold}%`;
+      const message = formatPriceAlert(market.question, market.yesPrice, alertThreshold);
 
       await alertsRepository.create({ userId: user.id, marketId: market.id, type: 'price_threshold', message });
       await sendMessage(user.telegramChatId, message);

backend/src/alerts/telegram.client.js

@@ -1,32 +1,59 @@
 /**
- * Servicio de envio de alertas por Telegram Bot API.
+ * Cliente de integracion con Telegram Bot API.
  *
  * Responsabilidades:
  *   - sendMessage(chatId, text) → POST a api.telegram.org/bot<TOKEN>/sendMessage.
+ *   - formatPriceAlert(question, yesPrice, threshold) → construye mensaje HTML
+ *     escapando entidades del input de usuario.
+ *   - escapeHtml(text) → escapa caracteres HTML sensibles (&, <, >, ").
  *   - Parse_mode: HTML (permite formato basico: <b>, <i>).
- *   - Si falta TELEGRAM_BOT_TOKEN o chatId, la funcion retorna silenciosamente.
+ *   - Si falta TELEGRAM_BOT_TOKEN o chatId, sendMessage retorna silenciosamente.
  *   - Errores de red se capturan y loguean como warn (no bloquean el flujo).
+ *   - Respuestas de Telegram con ok: false se loguean como warn y no lanzan excepcion.
  *
  * Consumido por:
  *   - alerts.service.js → processAll() cuando se dispara una alerta.
  *
  * Seguridad:
  *   - El token se lee de variables de entorno (nunca hardcodeado).
- *   - Se recomienda escapar entidades HTML si el texto incluye input de usuario.
+ *   - Todo texto dinamico se escapa via escapeHtml antes de inyectarse en HTML.
  */
 
 import { httpPost } from '../utils/httpClient.js';
 import { config } from '../config.js';
 import { logger } from '../utils/logger.js';
 
+export function escapeHtml(text) {
+  if (typeof text !== 'string') return String(text ?? '');
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export function formatPriceAlert(question, yesPrice, threshold) {
+  const safeQuestion = escapeHtml(question);
+  const pct = (yesPrice * 100).toFixed(1);
+  const thr = (threshold * 100).toFixed(1);
+  return `<b>Price Alert</b>\n${safeQuestion}\nYES: ${pct}% ≥ threshold ${thr}%`;
+}
+
 export async function sendMessage(chatId, text) {
   if (!config.TELEGRAM_BOT_TOKEN || !chatId) return;
   try {
-    await httpPost(
+    const result = await httpPost(
       `https://api.telegram.org/bot${config.TELEGRAM_BOT_TOKEN}/sendMessage`,
       { chat_id: chatId, text, parse_mode: 'HTML' },
       { retries: 1, timeout: 8_000 },
     );
+    if (result && result.ok === false) {
+      logger.warn(
+        { chatId, description: result.description, errorCode: result.error_code },
+        'telegram API returned ok=false',
+      );
+      return;
+    }
   } catch (err) {
     logger.warn({ err: err.message, chatId }, 'telegram send failed');
   }