Ir al contenido
DevLab

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.

En esta página
  1. El proxy
  2. Las 13 rutas
  3. Tu sesión delante del proxy
  4. Personas e inscripciones: createEngineAdmin
  5. El receptor de subidas
  6. Los informes de arranque (opcional)
  7. Rotar la key
  8. El token y su alcance

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.

JavaScript
// 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.

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.

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.

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

JavaScript
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.

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.

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).

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.

JavaScript
// 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).

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 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.