# Migrar desde Engine 1.5

> Plantéalo como una integración nueva que reutiliza tu backend de tokens, tu proxy y tu interfaz, no como un cambio de nombres.

## Qué cambia en el modelo

En Engine 1.5, una página abría una **sesión**, capturaba un rato y pedía la interpretación. En Engine 2, una persona se **inscribe en un protocolo**, y cada captura es **una posición** de él, con un plan de steps (ver [Protocolos](/docs/es/concepts/protocols/)). Crear usuarios e inscribirlos es trabajo de tu backend.

## Qué se mantiene

- La API key nunca llega al navegador: tu backend obtiene los tokens con la key y hace de proxy de Engine.
- Capture sigue enviando geometría facial, nunca imágenes.

## Ruta por ruta

| Tema | Engine 1.5 | Engine 2 |
| --- | --- | --- |
| Token | `POST /token` con `user`, `tenant` y `securityKey`: un token por usuario final | `POST /token` con `apiKey`: un token por key. El usuario final pasa del token a cada petición (`externalId`, ids de inscripción) |
| Usuarios | Se creaban al vuelo con el primer token | Los crea tu backend con `POST /users`; `externalId` es único por organización |
| Qué capturas | Una **sesión** libre (`POST /session`, con su `order`) | Una **posición** de un protocolo en el que el usuario está **inscrito** (`POST /user-protocols`), identificada por `userProtocolId` y `protocolMechanicId`, con su plan de steps |
| Taxonomía de la interpretación | Campos del cuerpo de `POST /session` | `POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context` |
| Narrativa (voz, profundidad, idioma) | En el cuerpo de la sesión | En el perfil del usuario (`POST /users` y `PATCH /users/{external_id}`), más `audience` en `/analyze` |
| Envío de frames | `POST /process-kpn-emo` con `sessionId`, `step` = `order` y `baseline` | La misma ruta con `userProtocolId`, `protocolMechanicId` y el `step` del plan; sin el flag `baseline`; `featuresMeta` en cada frame |
| Baseline | Una sesión con `baseline: true`; la validez la calculaba el cliente | Su propia ruta, `POST` y `GET /users/{app_user}/baseline`; el servidor dice si es válido |
| Resultados | `GET /results/{sessionId}` | `GET /results/{userProtocolId}/{protocolMechanicId}` (también por step y por inscripción) |
| Interpretación | `POST /analyze` con `sessionId`, `timeStart`, `timeEnd` | `POST /analyze` con `userProtocolId`, `protocolMechanicId`, `step` y `audience` opcionales, con caché por audiencia; también `POST /analyze/stream` |
| Eventos | `GET /stream/{sessionId}` | `GET /stream/{userProtocolId}`, por inscripción, que se cierra con `stream.end` y un `reason` |
| Listar sesiones | `GET /sessions/` | `GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions` y `GET /users/{external_id}/status` |
| Constellation Lite | `lite_analysis` en la sesión | No forma parte del API público de Engine 2; pregunta a Neurologyca |

Esta guía cubre la integración, no tus datos: para usuarios y baselines existentes, pregunta a Neurologyca.

## Si usas el SDK

| SDK de Engine 1.5 | SDK de Engine 2 |
| --- | --- |
| `createNeuroClient` | `createProtocolClient` |
| `defineNeuroCapture` | Sin componente: `createProtocolClient` y tus propias pantallas ([Steps y marcado](/docs/es/sdk/steps/)) |
| `siteKeyTokenProvider` y la pasarela alojada | Retirados: el proxy de tu backend añade el token ([Tu backend](/docs/es/sdk/backend/)) |
| `narrative` | Rechazada con un mensaje: la narrativa va en el perfil del usuario (`POST` y `PATCH /users/{external_id}`), desde tu backend |
| `lite_analysis` | Rechazada: no forma parte de Engine 2; pregunta a Neurologyca |
| `contextText` | Sin equivalente: el único texto libre que recibe la interpretación es la transcripción (la frase `query` sigue existiendo) |
| `interpretationTimeoutMs` | Renombrada `analyzeTimeoutMs` |
| `triggerAnalysis` en el cliente | Por captura (`captureProtocol`) |
| — | Un paquete de servidor nuevo, `@neurologyca/capture-server`, para crear usuarios, inscribirlos y generar el kit de un contexto |

Tu proxy pasa de las rutas de Engine 1.5 a las [13 rutas](/docs/es/api/proxy/) que llama el SDK de Engine 2.

## Qué añade Engine 2

El catálogo, el estado y el bloqueo de usuarios, el borrado con confirmación, Measurement, las microintervenciones y los scopes de las keys. Empieza por el [quickstart](/docs/es/start/quickstart/).

## De 0.25 a 0.27

Si ya tienes la versión previa anterior del SDK de Engine 2 (0.25), estos son los cambios que debes hacer, según el changelog de `@neurologyca/capture` (0.26.0 **Breaking** y 0.27.0) y el de `@neurologyca/capture-server` 0.9.0. La lista completa está en el [Changelog del SDK](/docs/es/resources/changelog/).

### Rompe

1. `<neuro-capture>` desaparece: usa `createProtocolClient` o `createRecordingClient`, `describeStep` y tus propias pantallas. Lo que el elemento hacía por ti (mantener la pantalla encendida, el aviso `beforeunload`) ahora es tuyo: usa `keepScreenOn` y `guardUnload`.
2. `stop()` resuelve con el resultado: un `CaptureOutcome` en vivo, un `RecordingResult` al grabar.
3. `RecordingSessionHandle` ya no extiende `ProtocolSessionHandle`: usa `createRecordingClient`, que no necesita cast.
4. Una sola forma para `E_CONFLICT`: `e.reason` y `e.conflict.<campo>`.
5. El cliente de grabación (`@neurologyca/capture/record`) graba solo MP4/H.264.
6. Una grabación rechaza un `captureId` que ya está guardado en el navegador (`E_CAPTURE_ID_IN_USE`).
7. `RecordingResult` tiene un `storage` obligatorio y `ProtocolSessionHandle` tiene `captureId` y `stepTiming()`: un doble de test escrito a mano debe añadirlos.
8. `CaptureSource` gana `{ type: 'frames' }`, así que un `switch` exhaustivo sobre `source.type` deja de compilar.
9. La base de datos de grabaciones pasa a la versión 2: cierra las pestañas con un SDK anterior antes de grabar.
10. `capture.global.js` no registra ninguna etiqueta: la API está en `window.NeuroCapture`.
11. `@neurologyca/capture-server` 0.9.0 exige Node 20.3 o posterior (`engines.node` es `>=20.3`).

### Nuevo o recomendado

12. El navegador no necesita token: crea el cliente sin `getToken` (ahora es opcional), detrás del proxy de tu backend (`createEngineProxy`).
13. Sube las grabaciones con `uploadRecording`, la mitad del navegador del contrato cuya mitad de servidor es `createUploadReceiver`.
14. `stepDurations` avisa por defecto y tiene un `'off'`.
15. Desde la 0.27.0, un `<video>` es una fuente completa: su audio llega a la transcripción (con su `src` puesto antes), su final es el final de la fuente (`source.ended`) y puedes grabarlo.

## De 0.27 a 0.43

Si tienes 0.27, estos son los cambios que debes hacer hasta `@neurologyca/capture` 0.43.0 y `@neurologyca/capture-server` 0.19.0, según sus changelogs (los **Breaking** de 0.36.0, 0.36.3, 0.38.0, 0.42.0, 0.42.1 y 0.43.0, y el tipo más ancho de 0.28.0). La lista completa está en el [Changelog del SDK](/docs/es/resources/changelog/).

### Rompe

1. 0.28.0: `ManifestStep.endedBy` gana `'source'`, el step que cerró el fin de la fuente grabada (un `<video>` o un stream que terminó); antes decía `'timer'`. Un `switch` exhaustivo sobre él necesita el caso nuevo.
2. 0.36.0 (kodec 5): `FORWARDED_CODEC_EVENTS` ya no lista `hubert-enabled`, `hubert-revoked`, `voice-enabled` ni `voice-revoked`; un listener sobre ellos no salta nunca.
3. 0.36.0 renombró `PlanStep.targetConstellationHciId` a `targetHciId` y 0.36.3 lo deshizo (con `ProtocolSummary.group` en `@neurologyca/capture-server` 0.14.3): desde 0.27 el nombre no cambia, pero el código escrito contra 0.36.0 a 0.36.2 vuelve a `targetConstellationHciId`.
4. 0.38.0: `stop()` ya no genera una segunda interpretación: espera la que guarda Engine (hasta `analyzeTimeoutMs`) y solo entonces llama una vez a `POST /analyze`, así que puede tardar más; `analyze.progress` solo llega con `interpretation: 'stream'` ([El resultado](/docs/es/sdk/on-device/#el-resultado)).
5. 0.38.0: `PlanStep` gana los obligatorios `expectsSpeech` y `presentationSeconds`, y `SessionReport` gana `interpretationSource`, `interpretationMode` y `streamDropsDuringWait`: el código que los construye a mano debe añadirlos.
6. 0.42.0: un `transcribe.selfHost.wasmPaths` de texto es ahora un prefijo que debe acabar en `/`, bajo el que tu servidor sirve el par de onnxruntime que pide el dispositivo ([CSP y transcripción](/docs/es/guides/csp-transcription/)).
7. 0.42.0: `createProtocolClient` lanza `E_UNKNOWN_OPTION` con una opción que no conoce, como ya hacía `createRecordingClient`: quita de la configuración cualquier clave de más.
8. 0.42.0: `ProtocolClientHandle` gana `prepare`, `release` y `cacheStatus` (y `RecordingClientHandle`, `prepare` y `release`), `SessionReport` gana `startup` y `transcriptionLoad`, y `CaptureStartError` gana `stage` y `reason`: un doble de test tipado debe añadirlos.
9. 0.42.1 y 0.43.0: `StartupMessageKey` gana `'first-frame.timeout-media'` y `'first-frame.face-reload-failed'`: un `Record<StartupMessageKey, string>` con tus propios textos debe añadir las dos.
10. 0.43.0: `StartupReport.schema` es `1 | 2` y `PreparedBlock.prepareId` puede ser `null`. Un receptor de informes de arranque valida el esquema 2 con `@neurologyca/capture-server` 0.19.0 o posterior ([Los informes de arranque](/docs/es/sdk/backend/#los-informes-de-arranque-opcional)).
11. 0.43.0 (kodec `5.0.0-rc.14`): una fuente que ya terminó cuando empieza la captura falla en el acto, con `CaptureStartError` y `stage: 'source'`; pasa un stream vivo o un vídeo que aún se reproduce.

### Nuevo o recomendado

12. `client.prepare()` y `client.release()` (0.42.0) cargan los modelos antes de Empezar ([Preparar antes de Empezar](/docs/es/sdk/on-device/#preparar-antes-de-empezar)), y `keepPrepared` (0.43.0) los guarda de una captura a la siguiente ([Guardar los modelos entre capturas](/docs/es/sdk/on-device/#guardar-los-modelos-entre-capturas)).
13. `startup`, `onStartupStage` y `STARTUP_MESSAGES` (0.42.0) enseñan el arranque etapa a etapa, con topes para que no se cuelgue ([La pantalla de arranque](/docs/es/sdk/on-device/#la-pantalla-de-arranque)).
14. `signal` en `captureProtocol` (0.42.0) cancela una captura mientras arranca, y `captureProtocol({ transcribe: false })` hace una captura sin micrófono en un cliente configurado con transcripción.

## De 0.43 a 0.45

Si tienes 0.43, estos son los cambios que debes hacer hasta `@neurologyca/capture` 0.45.0 y `@neurologyca/capture-server` 0.20.1, según sus changelogs (0.44.0, 0.45.0, 0.20.0 y 0.20.1). Ninguno rompe en ejecución: cambia la lectura de un `202` y algunos tipos ganan campos obligatorios. `PlanStep.expectsSpeech` (0.38.0) y `targetConstellationHciId` (0.36.3) no cambian en este tramo. Si vienes de una versión anterior, sigue antes [De 0.27 a 0.43](#de-027-a-043), cuya 0.43.0 es la última versión incompatible. La lista completa está en el [Changelog del SDK](/docs/es/resources/changelog/).

### Cambios que hacer

1. 0.44.0: `client.analyze()` (en `createProtocolClient` y `createRecordingClient`) resuelve a `AnalyzeAnswer`, que añade los obligatorios `inProgress` y `retryAfterMs` a `interpretation`, `fromCache` y `raw`: un doble de test tipado que construya su resultado debe añadir los dos (`inProgress: false, retryAfterMs: null` para una respuesta normal).
2. 0.44.0: al cerrar una captura, un `202 ANALYSIS_IN_PROGRESS` ya no acaba en `E_INTERPRETATION_TIMEOUT`: el SDK espera y vuelve a pedirla (`analysis.in-progress`) y, si se agota la espera, acaba con el nuevo `E_ANALYSIS_IN_PROGRESS` (recuperable, estado `timeout`). El código que ramifica por `E_INTERPRETATION_TIMEOUT` para decir «interpretación pendiente» debe tratar también `E_ANALYSIS_IN_PROGRESS` ([Errores](/docs/es/sdk/errors/)), y un `switch` exhaustivo sobre `ProtocolErrorCode` necesita el caso nuevo.
3. 0.44.0 y 0.20.0: una interpretación `null` con `inProgress: true` es «interpretando», no «sin interpretación»: mira `inProgress` antes de dar por definitivo un `interpretation: null` y vuelve a pedirla pasados `retryAfterMs` ([El 202 de la interpretación](/docs/es/sdk/errors/#el-202-de-la-interpretación)).
4. 0.20.0: `AnalyzeResult` (`analyze()` y `EngineAdmin.analyze`) y `AudienceReading` (`analyzeForAudiences`) ganan los obligatorios `inProgress` y `retryAfterMs`, `ProtocolSummary` y su `group` ganan `interpreted` (`boolean | null`), y `TenantKit` gana `kind` (`'context' | 'measurement'`): un doble de test tipado de cualquiera de ellos debe añadirlos.
5. 0.20.0: `buildTenantKit` ya no lanza `E_KIT_NO_CONTEXT` con Measurement: da `kind: 'measurement'`, con `taxonomy.contextId: MEASUREMENT_CONTEXT_ID` y un aviso de capturar con `triggerAnalysis: false`. Ramifica por `kit.kind` donde capturabas `E_KIT_NO_CONTEXT` para caer en una configuración fija de Measurement ([Tu backend](/docs/es/sdk/backend/#personas-e-inscripciones-createengineadmin)).

### Nuevo o recomendado

6. `credentials` (0.45.0) en `createProtocolClient`, `createRecordingClient` y `urlTokenProvider`: `'include'` para un proxy en otro origen que decide por tu cookie de sesión, con `cors: { origins, credentials: true }` en `createEngineProxy` y `capture-server` 0.20.1, que expone `Retry-After` a esa página ([Un proxy en otro origen](/docs/es/api/proxy/#un-proxy-en-otro-origen)).
7. 0.45.0: un `/analyze` repetido tras un `202` recibe solo lo que queda de la espera, así que el cierre acaba como mucho unos 10 s después de `analyzeTimeoutMs`.
