# API /api/session

Este README documenta la API de sesión incluida en `app/api/session` del proyecto.

Objetivo
- Proveer endpoints simples para crear y recuperar sesiones E2E que devuelven un token LiveKit y una `studioUrl` construida con la convención `/rooms/<roomName>`.

Endpoints

1) POST /api/session
- Uso: crea una sesión (genera token JWT con `livekit-server-sdk`) y guarda una entrada en el store en memoria.
- Request body (JSON):
  - room (string) — nombre de la sala (opcional, por defecto `e2e-room`).
  - username (string) — identidad del participante (opcional).
  - ttl (number) — tiempo de vida en segundos del token (opcional, por defecto 300).
- Response (200):
  ```json
  { "id": "sess_<ts>_<rand>", "token": "<JWT>", "studioUrl": "https://mi-dominio/rooms/<room>" }
  ```

2) GET /api/session/:id
- Uso: recuperar la sesión previamente creada por `POST /api/session`.
- Response (200): retorna el objeto de sesión guardado en memoria, por ejemplo:
  ```json
  {
    "id": "sess_...",
    "token": "...",
    "room": "mi-room",
    "username": "visual-runner",
    "studioUrl": "https://mi-dominio/rooms/mi-room",
    "createdAt": 169...
  }
  ```

Variables de entorno relevantes
- LIVEKIT_API_KEY (required): clave pública para LiveKit.
- LIVEKIT_API_SECRET (required): secreto para firmar tokens.
- STUDIO_BASE (optional): base URL del frontend; si está definida, `studioUrl` se construye como `${STUDIO_BASE}/rooms/${room}`.
  - Alternativas atendidas: `STUDIO_URL` o `BROADCAST_URL` si `STUDIO_BASE` no existe.

Notas técnicas
- El store es un Map en memoria (`app/api/session/store.ts`). Es volátil: si el servidor se reinicia, las sesiones se perderán. Para entornos reales usa Redis o una DB.
- El token se genera con `AccessToken` del paquete `livekit-server-sdk` y contiene los grants para `roomJoin`, `canPublish` y `canSubscribe`.

Comandos de ejemplo

1) Crear sesión (POST):

```bash
curl -sS -X POST http://localhost:3000/api/session \
  -H 'Content-Type: application/json' \
  -d '{"room":"mi-room-e2e","username":"tester","ttl":300}' | jq .
```

2) Recuperar sesión (GET):

```bash
curl -sS http://localhost:3000/api/session/sess_169... | jq .
```

3) Decodificar el token (inspección del payload JWT):

```bash
TOKEN="eyJhbGciOiJ..."
echo $TOKEN | cut -d '.' -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .
```

4) Probar manualmente en el frontend (DevTools)
- Abre: `https://mi-dominio/rooms/mi-room-e2e`.
- En la consola ejecuta:

```js
window.postMessage({ type: 'LIVEKIT_TOKEN', token: 'TOKEN_AQUI', room: '' }, window.location.origin);
```

El frontend debe escuchar `message` y conectar usando el token.

Probar con el E2E script
- Arrancar Chrome con remote-debugging (usa `packages/broadcast-panel/e2e/start-chrome-remote.sh`).
- Ejecutar el script:

```bash
REMOTE_DEBUG_ADDRESS=127.0.0.1 REMOTE_DEBUG_PORT=9222 \
TOKEN_SERVER="http://localhost:3000" \
ROOM="mi-room-e2e" \
BROADCAST_BASE="https://mi-dominio" \
node packages/broadcast-panel/e2e/generate_visual_baseline.js
```

Artefactos generados por el E2E script
- Logs: `packages/broadcast-panel/e2e/e2e/out/generate_visual_baseline.log` (o `e2e/out/...` en la raíz del repo)
- Captura: `packages/broadcast-panel/e2e/e2e/out/visual_<timestamp>/studio.png`
- Baseline: `packages/broadcast-panel/e2e/e2e/baseline/studio.png`

Depuración rápida
- Si `POST /api/session` devuelve 500: revisa `LIVEKIT_API_KEY`/`LIVEKIT_API_SECRET` en el entorno del backend.
- Si `studioUrl` es vacío: exporta `STUDIO_BASE` antes de hacer POST.
- Si la página no reacciona al `postMessage`: revisa el listener `window.addEventListener('message', ...)` en el frontend.

Siguientes pasos recomendados
- Reemplazar el store en memoria por Redis para persistencia en entornos multi-instanacia.
- Añadir autenticación y control de acceso para la creación/consulta de sesiones.

Si quieres, puedo:
- Añadir un mock token server con `tools/mock-token-server.js` para pruebas locales sin credenciales reales.
- Añadir un endpoint para listar sesiones (solo para debugging).

---
**Fin del README de `app/api/session`**