AvanzaCast/packages/backend-api/README.md

AvanzaCast — backend-api

Este servicio expone las APIs de backend para AvanzaCast: generación de tokens para LiveKit, gestión de sesiones para el Studio, registro de tokens provenientes de un token-server, gestión de usuarios y broadcasts.

Endpoints principales

• GET /health — healthcheck.

• POST /api/session — generar sesión (token) para un room y username.

  • Body: { room: string, username: string, ttl?: number }
  • Respuesta: { id, studioUrl, redirectUrl, ttlSeconds }

• GET /api/session/:id — obtener sesión por id (token, url, room, username, ttlSeconds).

• POST /api/session/:id/consume — marcar sesión consumida (single-use).

• POST /api/tokens — registro de tokens generados por un token-server externo.

  • Body: { sessionId: string, token: string, room?: string, username?: string, ttl?: number, createdBy?: number }
  • (El token-server puede llamar este endpoint para persistir tokens con el usuario asociado.)

• GET /api/token?room=<>&username=<> — (legacy) generar token sin crear sesión almacenada (usa LIVEKIT_API_KEY/LIVEKIT_API_SECRET si están configuradas).

• POST /api/session/validate — proxy para validar un token contra LiveKit.

• User & Broadcasts management (pueden usar Prisma o fallback en memoria):

  • POST /api/users — crear usuario { email, username, displayName?, isAdmin? }
  • GET /api/users/:id — obtener usuario
  • POST /api/broadcasts — crear broadcast { title, description?, ownerId? }
  • GET /api/broadcasts — listar broadcasts
  • POST /api/broadcasts/:id/session — crear sesión vinculada a un broadcast (genera token y guarda session)

Variables de entorno (más relevantes)

• PORT — puerto de escucha (default 4000)
• DATABASE_URL — cadena de conexión PostgreSQL (opcional, para Prisma)
• LIVEKIT_API_KEY, LIVEKIT_API_SECRET — credenciales LiveKit para generar AccessTokens reales
• LIVEKIT_WS_URL o LIVEKIT_URL — URL del servidor LiveKit (ws/wss o http(s))
• VITE_BROADCASTPANEL_URL, VITE_STUDIO_URL — URLs del frontend para construir redirect/studioUrl
• VITE_TOKEN_SERVER_URL — token-server host (para CORS/allowed origins)
• REDIS_URL — Redis si lo quieres usar
• ALLOW_ALL_CORS — si se quiere permitir cualquier origen (debug only)
• SESSION_TTL_SECONDS — TTL por defecto para sesiones (300s por defecto)

Integración con token-server

• Un token-server puede generar tokens y llamar POST /api/tokens para registrar la sesión/token en el backend.
• El POST /api/tokens persiste la sesión en la base de datos (Prisma) o en Redis/memoria si Prisma no está disponible.
• Para mayor seguridad puedes proteger POST /api/tokens con un secreto compartido. Recomendación: añadir BACKEND_REGISTER_SECRET y que el token-server envíe X-BACKEND-SECRET.

Cómo ejecutar localmente (quick start)

En el monorepo, desde la raíz:

1. Backend API (dev)

cd packages/backend-api
npm install
# Arrancar en dev (usa tsx)
npm run dev

2. Generar tokens / registrar sesiones

• Puedes usar la propia ruta POST /api/session del backend-api para crear una sesión y obtener un token si LIVEKIT_API_KEY/LIVEKIT_API_SECRET están configuradas. De lo contrario el backend devolverá un token "dev" (mock) para pruebas.

3. Probar generación y registro

# crea session/token
curl -sS -X POST http://localhost:4000/api/session -H 'Content-Type: application/json' -d '{"room":"test-room","username":"e2e","ttl":300}' | jq .
# verifica que la sesión se puede obtener por id (usar id devuelto)
curl -sS http://localhost:4000/api/session/<id> | jq .

Generar sesión internamente (server-to-server)

Puedes pedir al backend-api que genere la sesión de forma segura usando el endpoint interno protegido POST /api/internal/session. Esto requiere que en tu .env configures BACKEND_REGISTER_SECRET y que la petición incluya el header X-BACKEND-SECRET.

Para pruebas locales hay un script incluido:

# establece el secreto en la misma sesión o en el .env
export BACKEND_REGISTER_SECRET=devregistersecret
npm run internal:request --workspace packages/backend-api
# o desde el package folder
cd packages/backend-api && npm run internal:request

# el script usa por defecto room=test-room y username=e2e

El resultado incluirá id, studioUrl, redirectUrl, ttlSeconds y token.

4. Probar desde el frontend broadcast-panel

• Asegúrate packages/broadcast-panel/.env apunta a la URL correcta del backend (p. ej. VITE_BACKEND_API_URL=http://localhost:4000).
• Arranca broadcast-panel e intenta crear una transmisión y click en "Entrar al estudio". El flujo intentará obtener una session desde /api/session y el StudioPortal recoge la sesión desde sessionStorage o por evento.

Notas de seguridad y producción

• No uses credenciales dev en producción. Protege el endpoint /api/tokens con autenticación (token mutual, HMAC o IP allowlist).
• Si usas Prisma, ejecuta npm run prisma:migrate y npm run prisma:generate antes de arrancar el servicio.

API examples (curl)

Generate session (backend-api):

curl -sS -X POST http://localhost:4000/api/session -H 'Content-Type: application/json' -d '{"room":"room1","username":"cesar","ttl":300}' | jq .

Register token (token-server -> backend-api):

curl -sS -X POST http://localhost:4000/api/tokens -H 'Content-Type: application/json' -d '{"sessionId":"abcd123","token":"jwt..","room":"room1","username":"cesar","ttl":300}' | jq .

Get session by id:

curl -sS http://localhost:4000/api/session/abcd123 | jq .

Next steps / mejoras

• Añadir protección a /api/tokens (header secreto o auth) y actualizar el token-server para enviarlo.
• Añadir pruebas e2e que cubran el flujo completo (token-server -> backend-api -> broadcast-panel -> studio).
• Si quieres, implemento la protección con BACKEND_REGISTER_SECRET y actualizaré la documentación.

---

Si quieres que implemente la protección BACKEND_REGISTER_SECRET ahora, lo hago y detallo cómo configurar ambas partes.