Refactor code structure for improved readability and maintainability

2026-02-22 18:18:46 +01:00
parent c27e9bec7a
commit 0c9c408564
98 changed files with 8207 additions and 5250 deletions
--- a/docs/02-tecnico/apis.md
+++ b/docs/02-tecnico/apis.md
@@ -0,0 +1,523 @@
+# APIs del Sistema — Guía completa
+
+Este documento integra toda la información sobre APIs del sistema: obtención de claves, prioridades, estrategias, comparación y configuración.
+
+---
+
+## Tabla de Contenidos
+
+1. [APIs priorizadas (MVP)](#apis-priorizadas-mvp)
+2. [Obtención de claves](#obtención-de-claves)
+3. [Guía de integración](#guía-de-integración)
+4. [Comparación detallada](#comparación-detallada)
+5. [Estrategias técnicas](#estrategias-técnicas)
+6. [Configuración y despliegue](#configuración-y-despliegue)
+
+---
+
+## APIs priorizadas (MVP)
+
+### Prioridad Alta
+
+1. **IGDB (Internet Game Database)** - Calidad superior, amplia cobertura
+2. **RAWG (Rawg.io)** - Buena cobertura, datos de tiendas
+
+### Prioridad Media
+
+3. **TheGamesDB** - Artwork comunitario
+4. **ScreenScraper** - Media específica para ROMs
+
+### Prioridad Baja (para futuras versiones)
+
+5. **PriceCharting** - Precios físicos
+6. **IsThereAnyDeal** - Ofertas digitales
+7. **MobyGames** - Datos históricos detallados
+8. **eBay** - Datos de mercado
+
+---
+
+## Obtención de claves
+
+### IGDB (Internet Game Database)
+
+IGDB usa **OAuth 2.0 via Twitch**. Steps:
+
+1. Go to [Twitch Developer Console](https://dev.twitch.tv/console/apps)
+2. Sign in with your Twitch account (create one if needed)
+3. Click "Create Application"
+   - Name: "Quasar" (or your app name)
+   - Category: Select relevant category
+   - Accept terms, click Create
+4. You'll see:
+   - **Client ID** — Copy this
+   - Click "New Secret" to generate **Client Secret** — Copy this
+5. Go to Settings → OAuth Redirect URLs
+   - Add: `http://localhost:3000/oauth/callback` (development)
+   - For production: `https://yourdomain.com/oauth/callback`
+6. In your `.env` file:
+   ```
+   IGDB_CLIENT_ID=your_client_id
+   IGDB_CLIENT_SECRET=your_client_secret
+   ```
+7. Start Quasar, it will use IGDB automatically
+
+**Rate Limit:** 4 requests/second
+
+### RAWG (Rawg.io)
+
+RAWG has a simpler **API Key** approach:
+
+1. Go to [RAWG Settings](https://rawg.io/settings/account)
+2. Sign up if needed, then login
+3. Find "API Key" section
+4. Click "Create new key" (if needed) or copy existing key
+5. In your `.env` file:
+   ```
+   RAWG_API_KEY=your_api_key_here
+   ```
+6. Start Quasar
+
+**Rate Limit:** 20 requests/second (free tier)
+
+**Note:** RAWG requires attribution in UI (include "Powered by RAWG" somewhere visible)
+
+### TheGamesDB (thegamesdb.net)
+
+TheGamesDB uses a simple **API Key**:
+
+1. Go to [TheGamesDB API](https://thegamesdb.net/api)
+2. Find "API Key" section (free registration required)
+3. Register or login
+4. Copy your API key
+5. In your `.env` file:
+   ```
+   THEGAMESDB_API_KEY=your_api_key_here
+   ```
+6. Start Quasar
+
+**Rate Limit:** 1 request/second (free tier)
+
+### ScreenScraper
+
+ScreenScraper requiere cuenta y modelo de donación:
+
+1. Go to [ScreenScraper](https://www.screenscraper.fr/)
+2. Create account
+3. Niveles de donación ofrecen límites distintos (ej.: 50.000 scrapes/día en nivel Bronze)
+4. En tu `.env` file:
+   ```
+   SCREENSCRAPER_USERNAME=your_username
+   SCREENSCRAPER_PASSWORD=your_password
+   ```
+
+---
+
+## Guía de integración
+
+### IGDB
+
+- **Obtener credenciales**: registrar una app en Twitch Developer Console para obtener `CLIENT_ID` y `CLIENT_SECRET`. Obtener token con grant type `client_credentials` (POST a `https://id.twitch.tv/oauth2/token`).
+
+- **Endpoints principales**: `POST https://api.igdb.com/v4/games` (consulta flexible via body con sintaxis IGDB), `POST https://api.igdb.com/v4/covers`, `POST https://api.igdb.com/v4/platforms`.
+
+- **Ejemplo (buscar)**:
+
+```bash
+# Obtener token
+curl -X POST 'https://id.twitch.tv/oauth2/token?client_id=$IGDB_CLIENT_ID&client_secret=$IGDB_CLIENT_SECRET&grant_type=client_credentials'
+
+# Buscar juegos
+curl -X POST 'https://api.igdb.com/v4/games' \
+  -H "Client-ID: $IGDB_CLIENT_ID" \
+  -H "Authorization: Bearer $IGDB_TOKEN" \
+  -H 'Accept: application/json' \
+  --data 'fields id,name,first_release_date,platforms.name,genres.name,cover.url; search "zelda"; limit 5;'
+```
+
+- **Respuesta (esquemática)**:
+
+```json
+[
+  {
+    "id": 12345,
+    "name": "Ejemplo",
+    "first_release_date": 1459468800,
+    "platforms": [{ "name": "Nintendo Switch" }],
+    "cover": { "url": "//images.igdb.com/...jpg" }
+  }
+]
+```
+
+- **Límites y manejo**: la API puede devolver `429` o cabeceras de límite; implementar retries exponenciales (ej. 3 intentos) y respetar `Retry-After`. Implementar circuit breaker si la API falla repetidamente.
+- **Atribución**: mostrar origen de datos (ej. "Datos: IGDB") según términos del servicio.
+
+### RAWG
+
+- **Obtener credenciales**: registrarse en RAWG para obtener `RAWG_API_KEY` (https://rawg.io/apidocs).
+- **Endpoints principales**: `GET https://api.rawg.io/api/games?key=API_KEY&search=...`, `GET https://api.rawg.io/api/games/{id}`.
+- **Ejemplo**:
+
+```bash
+curl 'https://api.rawg.io/api/games?key=$RAWG_API_KEY&search=zelda&page_size=5'
+```
+
+- **Respuesta (esquemática)**:
+
+```json
+{
+  "count": 100,
+  "results": [
+    { "id": 3498, "name": "GTA V", "released": "2013-09-17", "background_image": "https://..." }
+  ]
+}
+```
+
+- **Límites y manejo**: RAWG suele tener límites por clave/plan; cachear y fallback a otros proveedores si falla.
+- **Atribución**: revisar condiciones y mostrar HTTP o texto de fuente si es requerido por el proveedor.
+
+### TheGamesDB
+
+- **Obtener credenciales**: crear cuenta y generar API Key en https://thegamesdb.net.
+- **Endpoints**: búsqueda por nombre y detalles (`/v1/Games/ByGameName?name=...`, `/v1/Games/ByGameID?id=...`).
+- **Ejemplo**:
+
+```bash
+curl -H 'Authorization: Bearer $THEGAMESDB_KEY' 'https://api.thegamesdb.net/v1/Games/ByGameName?name=zelda'
+```
+
+### Estrategia de fallback y normalización
+
+- **Orden de prioridad**: IGDB → RAWG → TheGamesDB (configurable).
+- **Normalización (mapping)**:
+  - `title` ← `name`
+  - `platform` ← `platforms[].name`
+  - `release_date` ← `first_release_date` / `released` → convertir a ISO 8601
+  - `genres` ← `genres[].name`
+  - `cover_url` ← `cover.url` / `background_image`
+  - `external_ids` ← `{ igdb: id, rawg: id, thegamesdb: id }`
+
+- **Fallback**: si IGDB no tiene portada, intentar RAWG; si falla, usar TheGamesDB. Registrar la fuente usada.
+
+### Caché y almacenamiento de artwork
+
+- **Caché metadata**: LRU en memoria o Redis con TTL (por ejemplo 24h) para evitar sobrecargar APIs.
+- **Almacenamiento de imágenes**: descargar y optimizar con `sharp` (crear versiones: thumb, medium), almacenar en `storage/artwork/{gameId}/cover.jpg` o S3.
+- **Servicio proxy**: servir imágenes desde backend para no exponer keys ni URLs externas.
+
+### Manejo de errores y resiliencia
+
+- Implementar **retries** exponenciales con jitter (3 intentos).
+- Implementar **circuit breaker** para desconectar llamadas a un proveedor fuera de servicio por N minutos.
+- Limitar concurrencia por proveedor (p. ej. 5 llamadas simultáneas) y usar colas para trabajos masivos (enriquecimiento masivo).
+
+---
+
+## Comparación detallada
+
+### Resumen por API
+
+#### IGDB (Internet Games Database)
+
+- **Resumen:** Base de datos muy completa (propiedad de Twitch/Amazon) con endpoints para juegos, covers, screenshots, plataformas, ratings, compañías y más.
+- **Autenticación / Requisitos:** OAuth vía Twitch (Client ID + Client Secret → token) — requiere cuenta Twitch y 2FA para registrar apps.
+- **Datos principales:** covers, screenshots, genres, developers, ESRB/PEGI, platforms, videos, websites, age ratings, tags.
+- **Rate limits / cuotas:** 4 peticiones/segundo; hasta 8 peticiones abiertas (si se excede → 429 Too Many Requests).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** Twitch Developer Service Agreement — https://www.twitch.tv/p/legal/developer-agreement/
+- **Cláusula clave:** "There is a rate limit of 4 requests per second. If you go over this limit you will receive a response with status code `429 Too Many Requests`." — https://api-docs.igdb.com/
+- **Costes / modelo:** Gratuito para uso no comercial; acuerdos comerciales para partners (atribución en caso de partnership).
+- **Enlace:** https://api-docs.igdb.com/
+
+#### RAWG
+
+- **Resumen:** Gran base de datos (medio millón de juegos), buena para metadata general y enlaces a tiendas.
+- **Autenticación / Requisitos:** API key en query string (`key=YOUR_API_KEY`).
+- **Datos principales:** descripciones, screenshots, plataformas, géneros, ratings, enlaces a tiendas, playtime estimado.
+- **Rate limits / cuotas:** Planes gratuitos con límites (ej. free tier limitada) y planes comerciales con mayor cuota (p.ej. hasta 50k requests/mes en planes de negocio).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://rawg.io/tos_api
+- **Cláusula clave:** "Free for personal use as long as you attribute RAWG as the source of the data and/or images and add an active hyperlink from every page where the data of RAWG is used. No data redistribution." — https://rawg.io/tos_api
+- **Costes / modelo:** Free tier para proyectos personales; planes comerciales (pago mensual) para uso en productos con gran tráfico.
+- **Enlace:** https://rawg.io/apidocs
+
+#### TheGamesDB
+
+- **Resumen:** Base de datos comunitaria para juegos y artwork, con API pública v2.
+- **Autenticación / Requisitos:** Registro y uso de API key (ver docs); repositorio público del proyecto (GPLv3 para el código del servidor).
+- **Datos principales:** imágenes, covers, plataformas, metadatos básicos.
+- **Rate limits / cuotas:** No siempre documentados públicamente (consultar docs/registro).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** No documentado públicamente — consultado https://api.thegamesdb.net/ y https://github.com/TheGamesDB/TheGamesDBv2 (código bajo GPL‑3.0)
+- **Cláusula clave:** No documentado públicamente — verificar con el equipo de TheGamesDB antes de uso comercial/redistribución.
+- **Enlace:** https://api.thegamesdb.net/
+
+#### ScreenScraper
+
+- **Resumen:** Servicio francés orientado a frontends, con enorme cantidad de media y opciones de scraping.
+- **Autenticación / Requisitos:** Cuenta en ScreenScraper; modelo de soporte/donación que habilita límites mayores.
+- **Datos principales:** screenshots, boxart, videos, manuals, metadata comunitaria.
+- **Rate limits / cuotas:** Planes por donación (ej.: 50.000 scrapes/día en niveles básicos; aumentos en niveles superiores).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.screenscraper.fr/
+- **Cláusula clave:** "Niveles de donación ofrecen límites distintos (p.ej. 50.000 scrapes/día en nivel Bronze); consultar la cuenta para límites exactos." — https://www.screenscraper.fr/
+- **Costes / modelo:** Donación / suscripción para aumentar cuotas y velocidad.
+- **Enlace:** https://www.screenscraper.fr/
+
+#### MobyGames
+
+- **Resumen:** Base histórica con screenshots, covers, reviews y credits; muy usada por investigación y metadata profunda.
+- **Autenticación / Requisitos:** API y/o MobyPlus; la API requiere registro y suscripción.
+- **Datos principales:** screenshots, covers, credits, precios históricos limitados.
+- **Rate limits / cuotas:** Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.mobygames.com/api/subscribe/
+- **Cláusula clave:** "Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second." — https://www.mobygames.com/api/subscribe/
+- **Costes / modelo:** Acceso vía suscripción / MobyPro; contactar para condiciones comerciales.
+- **Enlace:** https://www.mobygames.com/api/subscribe/
+
+#### PriceCharting
+
+- **Resumen:** Fuente especializada en historial de precios para juegos físicos y coleccionables.
+- **Autenticación / Requisitos:** API documentada en el sitio; el acceso completo requiere suscripción / token pagado.
+- **Datos principales:** precios históricos, condiciones (complete, loose), plataforma y comparables de mercado.
+- **Rate limits / cuotas:** No siempre publicadas públicamente; contactar a PriceCharting para detalles.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.pricecharting.com/api-documentation (ver también https://www.pricecharting.com/page/terms-of-service)
+- **Cláusula clave:** "API's are a premium tool. You must have a paid subscription to access the API." — https://www.pricecharting.com/api-documentation
+- **Costes / modelo:** Servicio comercial (licencias / API keys pagadas).
+- **Enlace:** https://www.pricecharting.com/api-documentation
+
+#### IsThereAnyDeal (Itad)
+
+- **Resumen:** Agregador de ofertas con histórico y mapeo de keys/tiendas; útil para tracking de ofertas digitales.
+- **Autenticación / Requisitos:** API Key (docs en https://docs.isthereanydeal.com/).
+- **Datos principales:** price history, deals, store IDs, game mappings.
+- **Rate limits / cuotas:** Access to API is rate limited and subject to change (limits provided in headers); contactar si necesita mayor cuota.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://docs.isthereanydeal.com/
+- **Cláusula clave:** "You MUST NOT change provided data in any way. You SHOULD provide a link to IsThereAnyDeal.com or mention IsThereAnyDeal API." — https://docs.isthereanydeal.com/
+- **Costes / modelo:** Free tier; acuerdos comerciales para uso intensivo.
+- **Enlace:** https://docs.isthereanydeal.com/
+
+#### eBay
+
+- **Resumen:** Fuente de datos de mercado (listings, precios vendidos) para estimar valor real de mercado.
+- **Autenticación / Requisitos:** Registro en eBay Developers Program; claves y OAuth para endpoints de venta/completed items.
+- **Datos principales:** listados, historiales vendidos (completed), especificaciones de artículos.
+- **Rate limits / cuotas:** Límite de llamadas por aplicación; eBay puede limitar y suspender acceso si se exceden los límites.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://developer.ebay.com/join/api-license-agreement
+- **Cláusula clave:** "You may not sell, rent, trade, distribute, lease (or otherwise commercialize), copy, store or modify eBay Content, other than for the purposes allowed by this API License Agreement." y "eBay reserves the right to limit the number of periodic API calls you are allowed to make." — https://developer.ebay.com/join/api-license-agreement
+- **Costes / modelo:** Free para desarrolladores con límites; uso intensivo o comerciales pueden requerir acuerdos o certificaciones.
+- **Enlace:** https://developer.ebay.com/
+
+### Tabla resumida
+
+| API            | Data types                                              | Auth                             | Free / Paid                                | Fecha verificación | Licencia / Nota legal                                                                                   | Notes                                                          |
+| -------------- | ------------------------------------------------------- | -------------------------------- | ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| IGDB           | covers, screenshots, genres, ESRB, companies, platforms | OAuth via Twitch                 | Free (non-commercial); commercial partners | 2026-02-07         | TOS: https://www.twitch.tv/p/legal/developer-agreement/                                                 | 4 rps rate limit; muy completa                                 |
+| RAWG           | games, screenshots, stores, ratings, playtime           | API key (query param)            | Free tier; paid commercial plans           | 2026-02-07         | TOS: https://rawg.io/tos_api (atribución requerida)                                                     | Free for personal use; atribución requerida; no redistribución |
+| TheGamesDB     | images, basic metadata                                  | API key (registro)               | Free / community                           | 2026-02-07         | Repo/TOS: https://github.com/TheGamesDB/TheGamesDBv2 (codigo GPL-3.0) / TOS no documentada públicamente | No TOS público claro; código backend GPL‑3.0                   |
+| ScreenScraper  | images, videos, manuals                                 | Account + token (donation tiers) | Donation / paid tiers                      | 2026-02-07         | TOS: https://www.screenscraper.fr/ (donation/tiers)                                                     | Donación/premium para mayores cuotas (p.ej. 50k/día)           |
+| PriceCharting  | price history                                           | API key / commercial             | Paid                                       | 2026-02-07         | Paid: https://www.pricecharting.com/api-documentation                                                   | API premium; requiere suscripción                              |
+| IsThereAnyDeal | deals, price history                                    | API key                          | Free tier / paid                           | 2026-02-07         | TOS: https://docs.isthereanydeal.com/                                                                   | Requiere atribución; prohíbe modificar datos                   |
+| MobyGames      | screenshots, credits, covers                            | Subscribe / API key              | Paid / subscription                        | 2026-02-07         | Paid/Subscribe: https://www.mobygames.com/api/subscribe/                                                | Access via subscription; non-commercial rate limits documented |
+| eBay           | listings, sold data                                     | eBay Dev keys / OAuth            | Free (with limits)                         | 2026-02-07         | TOS: https://developer.ebay.com/                                                                        | Terms restrict distribution; API License Agreement             |
+
+### Conclusión y recomendación para MVP
+
+Recomiendo un **set inicial de APIs (priorizado)**: **IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal.**
+
+- **Por qué:** IGDB + RAWG cubren **amplia metadata** y campos útiles (genres, plataformas, covers); TheGamesDB aporta **artwork comunitario**; ScreenScraper cubre assets específicos para ROM/frontends (videos/logos); PriceCharting e IsThereAnyDeal cubren **precios físicos y ofertas digitales** respectivamente.
+- **Prioridad:** 1) IGDB (calidad + licencia accesible) 2) RAWG (cobertura y datos de tiendas) 3) TheGamesDB (artwork) 4) ScreenScraper (media específica) 5) PriceCharting (precios físicos) 6) IsThereAnyDeal (ofertas digitales).
+
+---
+
+## Estrategias técnicas
+
+### Variables de entorno (ejemplos)
+
+```
+IGDB_CLIENT_ID=...
+IGDB_CLIENT_SECRET=...
+RAWG_API_KEY=...
+THEGAMESDB_API_KEY=...
+SCREENSCRAPER_USERNAME=...
+SCREENSCRAPER_PASSWORD=...
+EXTERNAL_API_CONCURRENCY=5
+```
+
+> Nota: **Nunca** exponer estas claves en el cliente; siempre pasar por el backend.
+
+### Normalización de datos
+
+```typescript
+interface NormalizedGame {
+  title: string;
+  platform: string;
+  release_date: string; // ISO 8601
+  genres: string[];
+  cover_url: string;
+  external_ids: {
+    igdb?: string;
+    rawg?: string;
+    thegamesdb?: string;
+  };
+  source: 'igdb' | 'rawg' | 'thegamesdb' | 'screenscraper';
+}
+```
+
+### Ejemplo de implementación
+
+```typescript
+class MetadataService {
+  private apis = [
+    new IGDBService(),
+    new RAWGService(),
+    new TheGamesDBService(),
+    new ScreenScraperService(),
+  ];
+
+  async searchGame(title: string): Promise<NormalizedGame> {
+    for (const api of this.apis) {
+      try {
+        const result = await api.search(title);
+        if (result) {
+          return this.normalize(result, api.getSource());
+        }
+      } catch (error) {
+        console.warn(`${api.getSource()} failed:`, error);
+        continue;
+      }
+    }
+    throw new Error('All APIs failed');
+  }
+
+  private normalize(data: any, source: string): NormalizedGame {
+    return {
+      title: data.name || data.title,
+      platform: data.platforms?.[0]?.name || '',
+      release_date: this.normalizeDate(data.first_release_date || data.released),
+      genres: data.genres?.map((g: any) => g.name) || [],
+      cover_url: data.cover?.url || data.background_image || '',
+      external_ids: {
+        igdb: data.id,
+        rawg: data.id,
+        thegamesdb: data.id,
+      },
+      source: source as any,
+    };
+  }
+}
+```
+
+---
+
+## Configuración y despliegue
+
+### Testing Without Real Keys
+
+Para desarrollo/testing:
+
+- Dejar API keys como `your_*_here` en `.env.local`
+- Quasar will gracefully degrade and show limited metadata
+- Frontend will still work with manual game entry
+
+### Production Deployment
+
+Para producción:
+
+1. Generar nuevas claves en cada servicio (no reutilizar claves de desarrollo)
+2. Almacenar claves en **Gitea Secrets** (para pipelines CI/CD automatizados)
+3. O usar variables de entorno en tu proveedor de hosting
+4. Rotar claves cada 3 meses
+5. Monitorear límites de rate en los dashboards de los servicios
+
+### Gitea Actions CI/CD Setup
+
+Para habilitar pruebas automatizadas con API keys en Gitea Actions:
+
+#### 1. Store Secrets in Gitea
+
+Navigate to your repository settings:
+
+```
+https://your-gitea-instance/your-org/quasar/settings/secrets/actions
+```
+
+Add these secrets:
+
+- `IGDB_CLIENT_ID` (from Twitch Developer Console)
+- `IGDB_CLIENT_SECRET` (from Twitch Developer Console)
+- `RAWG_API_KEY` (from RAWG settings)
+- `THEGAMESDB_API_KEY` (from TheGamesDB API)
+- `SCREENSCRAPER_USERNAME` (from ScreenScraper)
+- `SCREENSCRAPER_PASSWORD` (from ScreenScraper)
+
+#### 2. Workflow Configuration
+
+The `.gitea/workflows/ci.yml` workflow automatically:
+
+- ✅ Installs dependencies
+- ✅ Runs linting checks
+- ✅ Executes backend tests (Vitest)
+- ✅ Executes frontend tests (Vitest)
+- ✅ Starts backend + frontend servers
+- ✅ Runs E2E tests (Playwright) with real metadata APIs
+- ✅ Uploads test reports on failure
+
+#### 3. Testing Flow
+
+1. **Push** code to `main` or `develop`
+2. **Gitea Actions** picks up the `.gitea/workflows/ci.yml`
+3. **Secrets are injected** as environment variables
+4. **E2E tests** fetch real metadata from APIs (using injected secrets)
+5. **Build fails** if any test fails (prevents broken code)
+
+#### 4. Local Development
+
+For local testing, use `.env.local`:
+
+```bash
+IGDB_CLIENT_ID=your_local_id
+IGDB_CLIENT_SECRET=your_local_secret
+RAWG_API_KEY=your_local_key
+THEGAMESDB_API_KEY=your_local_key
+SCREENSCRAPER_USERNAME=your_username
+SCREENSCRAPER_PASSWORD=your_password
+```
+
+**Note:** CI/CD uses Gitea Secrets (not `.env` files), so never commit real credentials.
+
+### Troubleshooting
+
+**"IGDB_CLIENT_ID not found"** → Check `.env` file exists and has correct format
+
+**"429 Too Many Requests"** → Rate limit exceeded, wait and retry
+
+**"Invalid API Key"** → Copy key exactly (no spaces), verify it's active on service website
+
+**"ScreenScraper authentication failed"** → Check donation level and account status
+
+---
+
+## Fuentes
+
+- IGDB API docs: https://api-docs.igdb.com/ — TOS: https://www.twitch.tv/p/legal/developer-agreement/
+- RAWG API & TOS: https://rawg.io/apidocs / https://rawg.io/tos_api
+- TheGamesDB API / repo: https://api.thegamesdb.net/ / https://github.com/TheGamesDB/TheGamesDBv2/blob/master/LICENSE
+- ScreenScraper: https://www.screenscraper.fr/
+- MobyGames API: https://www.mobygames.com/api/subscribe/
+- PriceCharting API & Terms: https://www.pricecharting.com/api-documentation / https://www.pricecharting.com/page/terms-of-service
+- IsThereAnyDeal docs/TOS: https://docs.isthereanydeal.com/
+- eBay API License Agreement: https://developer.ebay.com/join/api-license-agreement
+
+## Metadatos
+
+- **Autor:** Quasar (investigación automatizada)
+- **Fecha verificación:** 2026-02-07
+- **Última actualización:** 2026-02-07
+
+---
+
+**Nota:** Si quieres, puedo preparar una matriz técnica (endpoints concretos, ejemplos de requests y una PoC de integración para 2 APIs prioritarias).