# Los resultados en tu backend

## Cómo llegan los resultados, por modo

**En el dispositivo (tiempo real)**: en la página, `onResult` y `stop()` → `CaptureOutcome`; en cualquier momento, `GET /results/{userProtocolId}/{protocolMechanicId}` o `client.retrieveResults(userProtocolId, protocolMechanicId)`; mientras capturas, el flujo de eventos `GET /stream/{userProtocolId}`. **Diferido (en servidor)**: el servicio de procesado reproduce la grabación contra Engine y avisa a tu backend con su webhook firmado; después lees `GET /results` como arriba.

## SDK y API, en las dos direcciones

**Primero el backend**: `createEngineAdmin` crea a la persona y la inscripción, y la página captura con ese par. **Primero el navegador**: la página captura con el SDK y tu backend lee después. Las dos se apoyan en lo mismo: tu backend guarda el par al inscribir y, con él, lee `GET /results` cuando lo necesita (`createEngineAdmin().getResults` es esa ruta, desde Node). Este módulo guarda el par, lee los resultados y la interpretación guardada, y borra a la persona al acabar; `store` es tu base de datos. Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés:

```js
// Store and read later, from your backend. At enrolment, keep the pair next to your user: it is all you need to read
// the results later (a report, a dashboard, another session). Engine does not expire results today: they stay until
// you delete the person. `store` is your database; any table with these four columns will do.
import { randomUUID } from 'node:crypto'
import { createEngineAdmin } from '@neurologyca/capture-server'

/**
 * @typedef {{ userId: string, externalId: string, userProtocolId: string, protocolMechanicId: string }} Capture
 * @typedef {{ insert(c: Capture): Promise<string>, get(captureId: string): Promise<Capture | null>, ofUser(userId: string): Promise<Capture[]>, deleteOfUser(userId: string): Promise<void> }} CaptureStore
 * @param {{ store: CaptureStore, engineBase?: string, apiKey?: string, fetch?: typeof fetch }} opts
 */
export function storeAndReadLater({ store, engineBase = process.env.ENGINE_BASE, apiKey = process.env.ENGINE_API_KEY, fetch: fetchImpl }) {
  if (!engineBase || !apiKey) throw new Error('Set ENGINE_BASE and ENGINE_API_KEY in your backend environment')
  const admin = createEngineAdmin({ baseUrl: engineBase, apiKey, fetch: fetchImpl })
  /** @param {Capture} c */
  const pairOf = (c) => ({ userProtocolId: c.userProtocolId, protocolMechanicId: c.protocolMechanicId })
  return {
    // 1 · At enrolment: create the person, enrol them and store the pair. The browser captures with that pair.
    /** @param {string} userId your user @param {string} protocolId the protocol in your kit @param {string} [language] of the interpretation */
    async enrolPerson(userId, protocolId, language = process.env.NARRATIVE_LANGUAGE ?? 'en') {
      const externalId = randomUUID() // opaque: never the email
      await admin.createUser({ externalId, name: 'person', narrative: { language } }) // without it, Engine writes in English
      const { userProtocolId } = await admin.enrol(externalId, protocolId)
      const next = await admin.getNextPosition(userProtocolId)
      if (!next) throw new Error('The protocol has no position to capture')
      const captureId = await store.insert({ userId, externalId, userProtocolId, protocolMechanicId: next.protocolMechanicId })
      return { captureId, userProtocolId, protocolMechanicId: next.protocolMechanicId }
    },
    // 2 · Whenever you need it: now or weeks later. There is no webhook in real time: if you read right at the end and
    // there is no data yet, read again a little later.
    /** @param {string} captureId */
    async readLater(captureId) {
      const c = await store.get(captureId)
      if (!c) return null
      const { rawResults, aggResults, speech } = await admin.getResults(pairOf(c))
      return { rawResults, aggResults, speech }
    },
    // The stored interpretation, with a protocol that interprets (Measurement does not). Without reAnalyze it is not
    // generated or billed again: never ask for it in a loop. With inProgress: true (a 202: Engine is still writing it), it
    // is not «no interpretation»: ask again after retryAfterMs (about 30 s when null), a few times at most.
    /** @param {string} captureId */
    async readInterpretation(captureId) {
      const c = await store.get(captureId)
      return c ? admin.analyze(pairOf(c)) : null
    },
    // 3 · When you are done: delete the person and everything of theirs in Engine. It cannot be undone.
    /** @param {string} userId */
    async forget(userId) {
      for (const externalId of new Set((await store.ofUser(userId)).map((c) => c.externalId))) await admin.deleteUser(externalId)
      await store.deleteOfUser(userId)
    },
  }
}
```

Desde `capture-server` 0.15.0, `getResults` devuelve también `speech`: por step, lo que se preguntó (`questionText`) y lo que se dijo (`transcript`) ([HCIs y resultados](/docs/es/concepts/results/#speech); solo en el Engine del entorno de pruebas). `speech` es `null` cuando Engine no manda el bloque. Para leer de una vez todas las mecánicas de una inscripción, `getProtocolResults({ userProtocolId })` devuelve `{ mechanics: [...] }`, cada una con su `protocolMechanicId`, `order`, `rawResults`, `aggResults` y `speech`; necesita tu key (un token de captura no puede leerla).

La llamada cruda devuelve el mismo cuerpo (recortado a los agregados):

```json
{
  "aggResults": {
    "1": {
      "mean": {
        "valence": 6.751,
        "arousal": 69.775,
        "Confusion": 14.618,
        "Stress_intens": 54.195
      }
    }
  }
}
```

## SSE o sondeo

`results.ready` como señal, `/results` como verdad. El evento llega una vez por posición, y no en todos los casos: sigue sondeando `GET /results` hasta que traiga datos.

```json
{
  "events": ["connected", "hci.warning", "results.ready"]
}
```

La lista muestra cada nombre de evento una sola vez: `hci.warning` llega una vez por lote que envías, solo de un indicador que tu contexto incluye, y no es una alerta: DevLab no enseña el nivel que lo dispara (`threshold`), así que no construyas sobre él. Que se envíe depende del entorno.

## Engine no manda webhooks

Engine no tiene webhooks: usas el flujo de eventos o sondeas. El único webhook del sistema es el del servicio de procesado, hacia tu backend, en el diferido.

## Guarda el par

Guarda `userProtocolId` y `protocolMechanicId` en tu backend al inscribir, no en la pestaña: `E_RESULTS_TIMEOUT` no es una pérdida, y con el par lees los resultados más tarde. Guarda también tu `externalId` opaco, nunca el email: es lo que borra a la persona. Hoy Engine no caduca los resultados: siguen ahí hasta que `admin.deleteUser(externalId)` (`DELETE /users/{externalId}`) borra a la persona y todo lo suyo, y no se puede deshacer ([Supresión y retención](/docs/es/resources/privacy/#supresión-y-retención)). Qué más guardar, y cómo releer gratis la interpretación: [Qué guardar](/docs/es/guides/show-results/#qué-guardar-y-cómo-releer-sin-pagar).

## Consultas puntuales

El catálogo (`GET /catalog/protocols`, `GET /catalog/contexts`), el estado de una persona (`GET /users/{externalId}/status`) y sus inscripciones (`GET /users/{externalId}/user-protocols`, o `admin.listEnrolments`) son lecturas simples desde tu backend. Mira la [guía de la API HTTP](/docs/es/api/) y la [referencia de la API](/docs/es/reference/).

La interpretación se lee igual: `admin.analyze(pair)` devuelve la guardada (`fromCache: true`) si el análisis salió completo; con `metadata.status` `degraded` o `failed`, o sin una guardada, cada llamada la regenera, y eso cuesta tokens del modelo de lenguaje y tiempo: generar una interpretación suele tardar decenas de segundos y puede tardar unos dos minutos de punta a punta ([La interpretación](/docs/es/sdk/processing/#la-interpretación)): pídela una vez, nunca en bucle. Qué audiencia enviar para que salga de la caché: [Qué guardar](/docs/es/guides/show-results/#qué-guardar-y-cómo-releer-sin-pagar). Para forzar una nueva, y cuándo no: [Pedir una interpretación nueva](/docs/es/concepts/results/#pedir-una-interpretación-nueva). Desde `capture-server` 0.16.0, `AnalyzeResult.structured` trae entero los datos estructurados de la interpretación; un índice de 0 a 100, si el dominio lo tiene, se lee de ahí con `readScoreIndex(result.structured)` ([Un índice de 0 a 100](/docs/es/concepts/results/#un-índice-de-0-a-100)).

Con el SDK en tiempo real hay una interpretación por sesión desde 0.38.0: la guardada. El texto que vio la persona en la página es el que devuelve después `admin.analyze(pair)` (`fromCache: true`), porque `stop()` espera el aviso de Engine y, si no llega, la lee una vez con `POST /analyze` en vez de generar otra. `SessionReport.interpretationSource` (en la página) dice de dónde salió; `'analyze-generated'` significa que `/analyze` tuvo que generarla, y la sesión pudo interpretarse dos veces. Hasta 0.37 había **dos interpretaciones** de una misma sesión, y las dos se cobraban: ve [dos interpretaciones](/docs/es/resources/pitfalls/#pf-two-interpretations). Por la API HTTP, cada llamada a `/analyze/stream` sigue generando una nueva que Engine no guarda; con el SDK, solo si pides `interpretation: 'stream'`.

Cómo salió el análisis lo dice `metadata.status`; el resto de `metadata` (modelo, recuento de tokens, ids, tiempos) es interno de Engine. Esta documentación no promete esos campos: no te apoyes en ellos ni los enseñes a tus usuarios, porque pueden cambiar o desaparecer sin aviso.

## El webhook del diferido como contrato

`createWebhookHandler({ secret, nonces, onEvent })` verifica cada entrega. Lo que puedes dar por seguro:

- Los campos firmados vienen en el cuerpo: `ProcessorWebhookEvent.jobId`, `ProcessorWebhookEvent.captureId`, `ProcessorWebhookEvent.status` (`succeeded`, `failed` o, desde `capture-server` 0.11.0, el no terminal `interpreting`), `ProcessorWebhookEvent.interpretation` (en un `succeeded`), `ProcessorWebhookEvent.outcome`, `ProcessorWebhookEvent.errorCode`, `ProcessorWebhookEvent.retryable`.
- `X-Neuro-Delivery` y `X-Neuro-Job` viajan fuera de la firma: una pista, nunca una autoridad.
- La firma vale ±300 s alrededor del reloj de tu servidor y cada nonce se guarda 600 s, así que mantén el reloj sincronizado.
- Las entregas son al menos una vez y sin orden garantizado: actúa solo si el `jobId` del cuerpo es el que guardaste y el trabajo que guardaste sigue en curso: el estado de tu tabla, o el que devuelve `processor.getJob`, es uno de `queued`, `downloading`, `preparing`, `transcribing`, `replaying`, `waiting` o `interpreting` (`ProcessorJobStatus`). El `status` del propio evento es `succeeded` o `failed` (terminales) o `interpreting` (un aviso intermedio que no cierra nada). No hagas nada ante un segundo evento, ni ante un `interpreting` que llega después del terminal.
- Responde `2xx` rápido y haz el trabajo después.
- Solo HTTPS.
- Excluye esta ruta de la protección CSRF de tu framework (va firmada, no es un formulario del navegador).

Si una entrega no llega nunca, sondea con `processor.getJob(jobId)`. El manejador recibe un único `secret`, así que no puede aceptar dos a la vez: rotarlo implica un corte breve, y si no puedes permitirte uno, sondea con `processor.getJob` mientras lo cambias.

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

const processor = createProcessorClient({ url: process.env.PROCESSOR_URL, apiKey: process.env.PROCESSOR_API_KEY })
const job = await processor.getJob(jobId) // el mismo estado que lleva el webhook, cuando lo necesites
```

Desde `capture-server` 0.11.0 el trabajo espera la interpretación: `succeeded` llega cuando está lista o cuando consta que no llegará, y su `interpretation` dice cuál de las dos. El trabajo es un éxito valga lo que valga: los indicadores están en `/results`. Qué hacer con cada valor: [La interpretación](/docs/es/sdk/processing/#la-interpretación).

## Probar el webhook en local

Para probar tu manejador sin el servicio, firma tú un evento sintético y enviándolo a tu ruta. `capture-server` verifica firmas pero no las hace, así que este es el formato que comprueba: la cabecera `X-Neuro-Signature: t=<epoch ms>,n=<uuid>,v1=<hex>`, donde `v1` es el HMAC-SHA256, con tu secreto, de `webhook.<t>.<n>.<raw body>` (los bytes exactos que envías). Usa un `t` actual (±300 s) y un `n` nuevo cada vez.
