Tu backend
La mitad de servidor del SDK: el proxy que pone el token, tu sesión delante, createEngineAdmin, el receptor de subidas y la rotación de la key.
El proxy
Sección titulada «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.
// 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.
Las 13 rutas
Sección titulada «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.
Tu sesión delante del proxy
Sección titulada «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.
Personas e inscripciones: createEngineAdmin
Sección titulada «Personas e inscripciones: createEngineAdmin»Tu backend crea a la persona y la inscribe, y guarda el par (userProtocolId, protocolMechanicId) que necesita la página:
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 nullEl 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.
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). Con capture-server 0.19.0 y anteriores, buildTenantKit lanza siempre E_KIT_NO_CONTEXT con Measurement.
El receptor de subidas
Sección titulada «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). 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).
Los informes de arranque (opcional)
Sección titulada «Los informes de arranque (opcional)»Con startup.report.url en el cliente (En el dispositivo), 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.
// 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 decontextque añadas. Tu consentimiento y tu aviso de privacidad tienen que cubrirlo; el SDK no lo pide. - Es anónimo por diseño, porque
sendBeaconno lleva credencial: exigeallowedOrigins(unscheme://host[:port]exacto; otroOrigin, o ninguno, responde403), yauthorize(req)es una barrera más, opcional. Solo aceptaPOST(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 porclientKey,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 responde507).reports.read({ since, until })devuelve un informe por arranque; llama areports.sweep()desde tu planificador. - Pon la URL en el
connect-srcde tu CSP ('self'la cubre en tu propio origen).
Rotar la key
Sección titulada «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).
El token y su alcance
Sección titulada «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.