# Tu backend

## El proxy

Tu página llama a tu backend, y tu backend reenvía esas llamadas a Engine con el token de tu key. Móntalo **antes** de cualquier parser de cuerpo: lee el cuerpo él mismo. Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés.

```js
// Your backend for the SDK path: the Engine proxy, so the browser carries no token. Node 20.3+.
// Mount it BEFORE any body parser:
//   const engine = engineProxyHandler({ session })
//   if (req.url.startsWith('/engine/')) return engine(req, res)
import { createTokenSource, createEngineProxy, ownsAll } from '@neurologyca/capture-server'
import { toNodeListener } from '@neurologyca/capture-server/node'

/**
 * YOUR app's session: signing in and both ownership checks are yours (ownsAll checks every id a route carries).
 * `req` is a Fetch `Request`, not an Express `req`: there is no `req.session`. Read your session cookie from
 * `req.headers.get('cookie')` and look it up in your session store.
 * @typedef {object} YourSession
 * @property {(req: Request) => Promise<boolean>} signedIn
 * @property {(req: Request, userProtocolId: string, protocolMechanicId: string | null) => Promise<boolean>} ownsEnrolment
 * @property {(req: Request, userId: string) => Promise<boolean>} isUser
 */

/** @param {{ engineBase?: string, apiKey?: string, session: YourSession, fetch?: typeof fetch }} opts */
export function engineProxyHandler({ engineBase = process.env.ENGINE_BASE, apiKey = process.env.ENGINE_API_KEY, session: yourSession, fetch: fetchImpl }) {
  if (!engineBase || !apiKey) throw new Error('Set ENGINE_BASE and ENGINE_API_KEY in your backend environment')
  const tokens = createTokenSource({ baseUrl: engineBase, apiKey, fetch: fetchImpl }) // the key lives here and only here
  return toNodeListener(createEngineProxy({
    baseUrl: engineBase,
    tokens,
    mountPath: '/engine',
    fetch: fetchImpl,
    authorize: async (req, route) => (await yourSession.signedIn(req)) && ownsAll(route, {
      userProtocol: async (up, pm) => yourSession.ownsEnrolment(req, up, pm),
      user: async (userId) => yourSession.isUser(req, userId),
    }),
  }))
}
```

`createTokenSource` pide y cachea el token; `createEngineProxy` solo reenvía las rutas que llama el SDK (abajo) y pregunta a `authorize` por cada petición; `ownsAll` comprueba **todos** los ids que lleva la ruta, la inscripción y la persona.

`createEngineProxy` limita el cuerpo de la petición con `maxBodyBytes`: 16 MiB por defecto desde `capture-server` 0.12.0 (antes, 8 MiB), y un cuerpo por encima del tope se rechaza con `413` `E_BODY_TOO_LARGE` antes de llegar a Engine. Desde 0.34.0 el SDK envía como mucho 3 MB de frames por lote, así que lo que tengas delante de tu proxy necesita un tope de cuerpo de al menos 4,5 MB, o 10 MB delante de un SDK anterior a 0.34.0. Los límites por plataforma, también los de las funciones serverless, están en [Proxy a mano](/docs/es/api/proxy/).

## Las 13 rutas

El proxy reenvía exactamente estas y responde `404` ante rutas desconocidas y `405` ante un método no permitido:

| # | Nombre | Método | Ruta |
| --- | --- | --- | --- |
| 1 | `protocol` | GET | `/user-protocols/{up}` |
| 2 | `plan` | GET | `/user-protocols/{up}/mechanics/{pm}` |
| 3 | `sessions` | GET | `/user-protocols/{up}/{pm}/sessions` |
| 4 | `baseline-get` | GET | `/users/{userId}/baseline` |
| 5 | `baseline-post` | POST | `/users/{userId}/baseline` |
| 6 | `stream` | GET | `/stream/{up}` |
| 7 | `context` | POST | `/user-protocols/{up}/{pm}/context` |
| 8 | `query` | PATCH | `/user-protocols/{up}/{pm}/query` |
| 9 | `frames` | POST | `/process-kpn-emo` |
| 10 | `results` | GET | `/results/{up}/{pm}` |
| 11 | `analyze-stream` | POST | `/analyze/stream` |
| 12 | `analyze` | POST | `/analyze` |
| 13 | `cancel` | POST | `/user-protocols/{up}/{pm}/cancel` |

Desde 0.10.0 el proxy reenvía `?captureId=` en `cancel`, y solo ahí: con él, el SDK 0.29.0 cancela solo su propia captura al soltar una grabación o un replay; si otra captura tiene la posición, Engine responde `200` con `cancelled: false` y `reason: other_capture_open` (`other_capture_open`) y la deja en paz. Reenvía exactamente un UUID en minúsculas; un `captureId` mal formado o repetido es un `400 E_BAD_REQUEST` que nunca llega a Engine, y cualquier otra query se descarta, en todas las rutas. Una sesión en vivo sigue cancelando sin él.

Sin `capture-server`, las mismas rutas a mano: [Proxy a mano](/docs/es/api/proxy/).

## Tu sesión delante del proxy

`authorize` recibe un `Request` de Fetch: lee tu cookie de sesión de `req.headers.get('cookie')`. Sin sesión: devuelve `false` y el proxy responde `403`. Usa una cookie con `SameSite=Lax` o `Strict`; el proxy rechaza un `Content-Type` o un `Sec-Fetch-Site` que no encaje. Sirve el proxy en el origen de la página si puedes. En otro origen hacen falta las dos mitades: `cors: { origins: ['https://app.ejemplo.com'], credentials: true }` en `createEngineProxy` y `credentials: 'include'` en el cliente (desde `@neurologyca/capture` 0.45.0; `capture-server` 0.20.1 expone además `Retry-After` a esa página): [Un proxy en otro origen](/docs/es/api/proxy/#un-proxy-en-otro-origen).

## Personas e inscripciones: createEngineAdmin

Tu backend crea a la persona y la inscribe, y guarda el par (`userProtocolId`, `protocolMechanicId`) que necesita la página:

```js
import { createEngineAdmin } from '@neurologyca/capture-server'

const admin = createEngineAdmin({ baseUrl: process.env.ENGINE_BASE, apiKey: process.env.ENGINE_API_KEY })
const { externalId } = await admin.createUser({ name: 'your-user', narrative: { language: 'es' } }) // UUID opaco; narrative.language fija el idioma de la interpretación (default 'en')
const { userProtocolId } = await admin.enrol(externalId, protocolPid)
const next = await admin.getNextPosition(userProtocolId) // { userProtocolId, protocolMechanicId, … } o null
```

El proxy solo acepta un `userId` que cumpla `^[A-Za-z0-9_-]{1,128}$`, así que un email usado como `externalId` recibe un 404 en las rutas del baseline: conserva el UUID generado. `createUser` rechaza un `externalId` que le pases y no sea un UUID; para conservar un esquema de identificadores que ya tienes, actívalo con `allowNonUuidExternalId: true`, y que sea opaco (nunca un email ni un nombre) y cumpla ese patrón.

`createEngineAdmin` es la misma API HTTP desde Node: cada método es una llamada documentada de Engine. `deleteUser` es físico e irreversible.

El **idioma de la interpretación** se fija en la persona, con `narrative.language` (default `en`) — no en `transcribe` (eso solo cambia el transcrito) ni en `/analyze`. Pasa el idioma de la UI al crear o actualizar la persona (`createUser`/`updateUser`), o una captura en español vuelve interpretada en inglés. `audience` también vive en la persona; ver `narrative` y `CreateUserInput` en la [referencia del SDK](/docs/es/sdk/reference/).

**El kit de un protocolo en tu backend.** `admin.buildTenantKit(protocolPid)` lo genera (`kind`, `config`, `env`, `pending`, `notices`). Desde `capture-server` 0.20.0 cubre también Measurement: un protocolo cuyo catálogo dice `interpreted: false` recibe `kind: 'measurement'`, con `config` `{ engineBaseUrl, taxonomy: { contextId: MEASUREMENT_CONTEXT_ID } }` (`MEASUREMENT_CONTEXT_ID` vale `'measurement'`, un relleno que el SDK no envía en cuanto Engine dice que el protocolo no se interpreta), `pending` solo con `env.ROLE`, opcional, y un aviso de que no habrá interpretación: captúralo con `triggerAnalysis: false`. Los demás kits llevan `kind: 'context'`. Ramifica por `kit.kind` y resuelve el kit antes de `admin.enrol`, así un kit que falle no deja una inscripción huérfana. `listProtocolLibrary()` también lo dice: `ProtocolSummary.interpreted` (el del protocolo o, si no, el de su grupo, `group.interpreted`; `null` si el catálogo no lo dice). Contra un Engine cuyo catálogo no publica `interpreted`, Measurement sigue lanzando `E_KIT_NO_CONTEXT`: ahí, usa la configuración fija que lleva el kit de Measurement de la consola ([Measurement](/docs/es/guides/measurement/#lo-que-aún-no-está)). Con `capture-server` 0.19.0 y anteriores, `buildTenantKit` lanza siempre `E_KIT_NO_CONTEXT` con Measurement.

## El receptor de subidas

En diferido, tu backend también recibe las grabaciones: `createUploadReceiver` con un almacenamiento (`localDiskStorage` en disco, o el tuyo), `authorize`, `checkManifest` y `onComplete`. Tiene dos manejadores, los dos montados antes de cualquier body parser: `receiver.handler` para las subidas y `receiver.mediaHandler` para `/media/<captureId>/video`, el vídeo firmado que descarga el servicio de procesado (sin él, el servicio recibe un 404 y el trabajo falla con `E_DOWNLOAD_FAILED`, que no se reintenta). El ejemplo está en [Diferido (en servidor)](/docs/es/sdk/deferred/#tu-receptor). La retención de las subidas confirmadas es tuya: `sweep` solo borra las abandonadas. El receptor no arranca temporizadores, así que llama tú a `receiver.sweep()` (por ejemplo cada hora desde tu planificador): borra las subidas sin confirmar que llevan `abandonedAfterMs` sin tocarse (72 h por defecto). `receiver.remove(captureId)` borra un vídeo confirmado cuando termina su trabajo; un vídeo confirmado nunca caduca por sí solo ([Privacidad](/docs/es/resources/privacy/)).

## Los informes de arranque (opcional)

Con `startup.report.url` en el cliente ([En el dispositivo](/docs/es/sdk/on-device/#la-pantalla-de-arranque)), la página envía un informe de cada arranque: sus etapas y tiempos, las comprobaciones del dispositivo y cómo acabó. Sin esa opción no sale nada de la página, y **DevLab no monta ningún receptor**: esta sección es solo para tu backend. Desde `capture-server` 0.18.0, `createStartupReportReceiver` los recibe, los valida y los guarda, y `localDiskStartupReports` (de `@neurologyca/capture-server/node`) los guarda en un disco local, un proceso por directorio; para varios procesos, implementa `StartupReportStorage` sobre tu propio almacén. Con capture 0.43.0 usa `capture-server` 0.19.0 o posterior: la página envía informes de esquema 2 cuando llevan algo que el esquema 1 no admite (sobre todo con `keepPrepared`: `prepared` en un baseline, `prepared.origin`, `kept`), y desde la 0.19.0 el receptor los valida igual de estricto que el esquema 1 y responde `400` a uno que rompe las reglas; antes los guardaba marcados `unvalidated`.

```js
// Your backend, optional (Node 20.3+): the receiver of the startup reports the page sends with startup.report.url.
// It stores data of the person's browser (stages, times, device checks and, by default, the user agent): your consent and
// privacy notice cover it. Mount it BEFORE any body parser:
//   if (req.url === '/startup-reports') return startupReports(req, res)
import { createStartupReportReceiver } from '@neurologyca/capture-server'
import { localDiskStartupReports, toNodeListener } from '@neurologyca/capture-server/node'

/**
 * @param {object} o
 * @param {string} o.dir a private directory for the reports (one process per directory)
 * @param {string[]} o.origins the exact origins of your pages, such as 'https://app.example.com'
 */
export function startupReportsHandler(o) {
  const reports = createStartupReportReceiver({
    storage: localDiskStartupReports({ dir: o.dir }),
    allowedOrigins: o.origins, // anonymous by design (sendBeacon carries no credential): another or no Origin answers 403
    onError: (_error) => console.error('startup reports: receiver error'), // never the body
  })
  // reports.read({ since }) returns the stored reports, one per startup; call reports.sweep() from your scheduler
  return { reports, listener: toNodeListener(reports.handler) }
}
```

- Guarda **datos del navegador de la persona**: las etapas, las comprobaciones del dispositivo y, salvo que el cliente pase `startup.includeUserAgent: false`, el user agent, más los pares de `context` que añadas. Tu consentimiento y tu aviso de privacidad tienen que cubrirlo; el SDK no lo pide.
- Es anónimo por diseño, porque `sendBeacon` no lleva credencial: exige `allowedOrigins` (un `scheme://host[:port]` exacto; otro `Origin`, o ninguno, responde `403`), y `authorize(req)` es una barrera más, opcional. Solo acepta `POST` (si no, `405`), valida cada informe con rigor (`400`) y limita el tamaño (64 KiB, `413`) y el ritmo (600 por minuto en total, 60 por `clientKey`, `429`).
- Guarda el informe validado y su `receivedAt`, nunca una cabecera, una dirección ni la clave del cliente; 14 días y 100 MiB por defecto (`retentionMs`, `maxBytes`; con el almacén lleno responde `507`). `reports.read({ since, until })` devuelve un informe por arranque; llama a `reports.sweep()` desde tu planificador.
- Pon la URL en el `connect-src` de tu CSP (`'self'` la cubre en tu propio origen).

## Rotar la key

`createTokenSource` lee la key al crearse: tras una rotación, hay que reiniciar (o redesplegar) tu backend con la key nueva. Vuelve a pedir token una vez tras un `401`. Por defecto `createEngineAdmin` y `createTokenSource` llevan cachés de token separadas; para compartir una, pasa tus `tokens` a `createEngineAdmin`. Dentro de los paquetes no hay rotación de credenciales: rota en DevLab ([Keys](/docs/es/access/keys/)).

## El token y su alcance

El token que añade el proxy es el token de desarrollador de tu organización: alcanza toda la organización. En resumen, la frontera es tu `authorize` con `ownsAll`: nunca dejes pasar una petición sin las dos comprobaciones.
