# Results in your backend

## How results arrive, by mode

**On-device (real time)**: in the page, `onResult` and `stop()` → `CaptureOutcome`; at any time, `GET /results/{userProtocolId}/{protocolMechanicId}` or `client.retrieveResults(userProtocolId, protocolMechanicId)`; while capturing, the event stream `GET /stream/{userProtocolId}`. **Deferred (server-side)**: the processing service replays the recording against Engine and tells your backend with its signed webhook; then you read `GET /results` as above.

## SDK and API, in both directions

**Backend first**: `createEngineAdmin` creates the person and the enrolment, and the page captures with that pair. **Browser first**: the page captures with the SDK, and your backend reads later. Both rest on the same thing: your backend stores the pair at enrolment and, with it, reads `GET /results` whenever it needs to (`createEngineAdmin().getResults` is that route, from Node). This module stores the pair, reads the results and the stored interpretation, and deletes the person at the end; `store` is your database:

```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)
    },
  }
}
```

Since `capture-server` 0.15.0, `getResults` also returns `speech`: per step, what was asked (`questionText`) and what was said (`transcript`) ([HCIs and results](/docs/concepts/results/#speech); only in the test environment's Engine). `speech` is `null` when the Engine does not send the block. To read every mechanic of an enrolment at once, `getProtocolResults({ userProtocolId })` returns `{ mechanics: [...] }`, each with its `protocolMechanicId`, `order`, `rawResults`, `aggResults` and `speech`; it needs your key (a capture token cannot read it).

The raw call returns the same body (shortened to the aggregates):

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

## SSE or polling

`results.ready` as the signal, `/results` as the truth. The event arrives once per position, and not in every case: keep polling `GET /results` until it has data.

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

The list shows each event name once: `hci.warning` arrives once per batch you send, only for an indicator your context includes, and it is not an alert: DevLab does not show the level that triggers it (`threshold`), so do not build on it. Whether it is sent depends on the environment.

## Engine sends no webhooks

Engine has no webhooks: you use the event stream or you poll. The only webhook in the system is the processing service's, to your backend, in deferred.

## Keep the pair

Save `userProtocolId` and `protocolMechanicId` in your backend when you enrol, not in the tab: `E_RESULTS_TIMEOUT` is not a loss, and with the pair you read the results later. Store your opaque `externalId` with them too, never the email: it is what deletes the person. Engine does not expire results today: they stay until `admin.deleteUser(externalId)` (`DELETE /users/{externalId}`) deletes the person and everything of theirs, which cannot be undone ([Deletion and retention](/docs/resources/privacy/#deletion-and-retention)). What else to keep, and how to read the interpretation again for free: [What to keep](/docs/guides/show-results/#what-to-keep-and-how-to-read-again-without-paying).

## One-off queries

The catalogue (`GET /catalog/protocols`, `GET /catalog/contexts`), a person's state (`GET /users/{externalId}/status`) and their enrolments (`GET /users/{externalId}/user-protocols`, or `admin.listEnrolments`) are plain reads from your backend. See the [HTTP API guide](/docs/api/) and the [API reference](/docs/reference/).

The interpretation is read the same way: `admin.analyze(pair)` returns the stored one (`fromCache: true`) when the analysis came out complete; with `metadata.status` `degraded` or `failed`, or none stored yet, every call regenerates it, which costs language-model tokens and time: generating an interpretation usually takes tens of seconds and can take about two minutes end to end ([The interpretation](/docs/sdk/processing/#the-interpretation)): ask once, never in a loop. Which audience to send so it comes from the cache: [What to keep](/docs/guides/show-results/#what-to-keep-and-how-to-read-again-without-paying). To force a new one, and when not to: [Ask for a fresh interpretation](/docs/concepts/results/#ask-for-a-fresh-interpretation). Since `capture-server` 0.16.0, `AnalyzeResult.structured` carries the interpretation's structured data whole; a 0 to 100 index, when the domain has one, is read from it with `readScoreIndex(result.structured)` ([A 0 to 100 index](/docs/concepts/results/#a-0-to-100-index)).

With the SDK in real time there is one interpretation per session since 0.38.0: the stored one. The text the person saw on the page is the one `admin.analyze(pair)` returns afterwards (`fromCache: true`), because `stop()` waits for Engine's notice and, if it does not arrive, reads it once with `POST /analyze` instead of generating another. `SessionReport.interpretationSource` (in the page) says where it came from; `'analyze-generated'` means `/analyze` had to generate one, and the session may have been interpreted twice. Up to 0.37 there were **two interpretations** of one session, both billed: see [two interpretations](/docs/resources/pitfalls/#pf-two-interpretations). Over the HTTP API, every call to `/analyze/stream` still generates a new one that Engine does not store; with the SDK, only if you ask for `interpretation: 'stream'`.

How the analysis came out is `metadata.status`; the rest of `metadata` (model, token counts, ids, timings) is internal to Engine. This documentation does not promise those fields: do not build on them or show them to your users, because they can change or disappear without notice.

## The deferred webhook as a contract

`createWebhookHandler({ secret, nonces, onEvent })` verifies each delivery. What you can rely on:

- The signed fields are in the body: `ProcessorWebhookEvent.jobId`, `ProcessorWebhookEvent.captureId`, `ProcessorWebhookEvent.status` (`succeeded`, `failed` or, since `capture-server` 0.11.0, the non-terminal `interpreting`), `ProcessorWebhookEvent.interpretation` (on a `succeeded`), `ProcessorWebhookEvent.outcome`, `ProcessorWebhookEvent.errorCode`, `ProcessorWebhookEvent.retryable`.
- `X-Neuro-Delivery` and `X-Neuro-Job` travel outside the signature: a hint, never an authority.
- The signature is valid ±300 s around your server's clock and each nonce is kept 600 s, so keep the clock in sync.
- Deliveries are at least once and in no guaranteed order: act only if the `jobId` in the body is the one you saved and the job you stored is still in flight: the status in your table, or the one `processor.getJob` returns, is one of `queued`, `downloading`, `preparing`, `transcribing`, `replaying`, `waiting` or `interpreting` (`ProcessorJobStatus`). The `status` of the event itself is `succeeded` or `failed` (terminal) or `interpreting` (an interim notice that closes nothing). Do nothing on a second event, and nothing on an `interpreting` that arrives after the terminal one.
- Answer `2xx` quickly and do the work afterwards.
- HTTPS only.
- Exempt this route from your framework's CSRF protection (it is signed, not a browser form).

If a delivery never arrives, poll with `processor.getJob(jobId)`. The handler takes a single `secret`, so it cannot accept two at once: rotating it means a brief cut, and if you cannot afford one, poll with `processor.getJob` while you change it.

```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) // the same state the webhook carries, when you need it
```

Since `capture-server` 0.11.0 the job waits for the interpretation: `succeeded` arrives once it is ready or once it is known it will not come, and its `interpretation` says which. The job is a success whatever that value is: the indicators are in `/results`. What to do with each value: [The interpretation](/docs/sdk/processing/#the-interpretation).

## Test the webhook locally

To test your handler without the service, sign a synthetic event yourself and post it to your route. `capture-server` verifies signatures but does not make them, so this is the format it checks: the header `X-Neuro-Signature: t=<epoch ms>,n=<uuid>,v1=<hex>`, where `v1` is the HMAC-SHA256, with your secret, of `webhook.<t>.<n>.<raw body>` (the exact bytes you post). Use a current `t` (±300 s) and a new `n` each time.
