# IACL Comms

> Vídeo, audio y chat con IA en tiempo real y al cerrar la reunión, para integrarlo en tus propias apps y sistemas con una librería y una API key. Servidores en la UE.

Generado con `pnpm docs:llms` desde docs/developers y los tipos de los paquetes. No se edita a mano.

---

<!-- fuente: docs/developers/ia/contexto.md -->

# IACL Comms: contexto para una IA que programa con él

Este documento es la cabecera de `llms-full.txt` y `llms-small.txt`. Está escrito para un modelo
que va a escribir código de integración: primero el modelo mental, después las reglas que no
se pueden romper y, al final, dónde está cada cosa. Lo demás del fichero son las guías y la
referencia, generadas del propio código.

## Qué es

IACL Comms es vídeo, audio y chat con IA en tiempo real y al cerrar la reunión, para meterlo
dentro de la aplicación de quien integra. Hay una API HTTP (`https://api.comms.iaconsultinglabs.com/v1`),
eventos firmados por webhook y cuatro paquetes npm con licencia MIT:

| Paquete | Dónde corre | Para qué |
|---|---|---|
| `@iaconsultinglabs/comms-server` | Backend (Node ≥ 22) | Crear reuniones, dar accesos, configurar, leer el consumo, verificar webhooks. Usa la API key |
| `@iaconsultinglabs/comms-core` | Navegador, sin framework | Entrar a la reunión con un acceso, medios, chat, la IA en directo (`meeting.ai`) |
| `@iaconsultinglabs/comms-vue` | Navegador, Vue 3 | Los componentes ya hechos (`MeetingRoom`, `AiLivePanel`, `LiveCaptions`…) y composables (`useMeeting`, `useAi`…). También custom elements (`<iacl-meeting>`) para usarlo sin Vue |
| `@iaconsultinglabs/comms-contracts` | Los dos | Tipos y constantes del contrato (OpenAPI, eventos, errores) |

## El modelo mental

- **Tenant**: la cuenta del cliente en Comms. Todo lo que hace una clave es de su tenant.
- **API key**: `iacl_test_…` (prueba) o `iacl_live_…` (producción). Vive **solo en el backend**.
  - El modo lo da la clave, no un parámetro. Una clave de prueba ve y cambia solo lo de prueba
    (reuniones, eventos, configuración, consumo) y nunca lo de producción, y al revés.
  - Las claves de prueba: reuniones de hasta 4 personas y 15 minutos, IA **simulada** y
    determinista (`iacl-sandbox-live`, `iacl-sandbox-closing`), gratis.
  - Cada clave tiene permisos (`scopes`): `meetings:read`, `meetings:write`, `tokens:create`,
    `recordings:read`, `recordings:write`, `ai:read`, `ai:configure`, `ai:run`, `events:read`,
    `webhooks:manage`, `storage:manage`, `usage:read`, `keys:manage`. Sin el permiso, el error es
    `key_scope_missing`.
- **Reunión** (`mtg_…`): la crea el backend. Lleva sus ajustes, también los de la IA
  (`settings.ai`), y opcionalmente el contexto inicial para la IA (`aiContext`).
- **Acceso (token)**: el backend lo pide para cada persona (`issueMemberToken`, `issueGuestToken`)
  y se lo da al navegador. El navegador entra con ese acceso, nunca con la clave.
- **Persona y aparato**: la misma persona puede estar desde varios aparatos; la identidad es
  reunión + persona + aparato (`currentDevice()` en el navegador).
- **Eventos**: lo que pasa en Comms llega al backend por webhook firmado y se puede listar con
  la API. Hay que verificarlos (`verifyWebhook`) y tratarlos de forma idempotente por su id.
- **IA en directo**: transcripción, detectores en lenguaje natural, ayuda privada por turno
  (sugerencias, respuestas con fuente del contexto, datos, avisos) y salidas del modo. En el
  navegador se lee con `meeting.ai` (`comms-core`) o con `AiLivePanel`/`LiveCaptions` (`comms-vue`).
  Solo ve la ayuda privada quien tiene `aiAssist` en su acceso; nunca un invitado.
- **IA al cerrar**: resumen, acciones propuestas, comprobaciones y el resultado del modo, por
  evento (`summary.ready`, `action.proposed`, `ai.closing.completed`).
- **Modelos**: se eligen de un catálogo de IACL con precio (`listAiModels`), por cuenta
  (`setAiModelDefaults`) o por reunión. No se puede traer otro proveedor ni otra clave de IA.

## Reglas que no se rompen

1. **La API key nunca llega al navegador**, ni a un repositorio, ni a un log. Va en una variable
   de entorno del backend (`IACL_API_KEY`).
2. **El navegador solo recibe accesos**, pedidos por el backend después de decidir quién es la
   persona y si puede entrar.
3. **Comms propone y nunca ejecuta**: las acciones de la IA (`action.proposed`) las aprueba y
   ejecuta el sistema del integrador.
4. **Los webhooks se verifican** con su secreto antes de leerlos, y se procesan por id de evento
   una sola vez.
5. **Los errores se tratan por su `code` estable**, no por el texto (`isCommsApiError(error)` en
   el backend; `CommsError` en el navegador). Reintentar solo lo que la guía de errores dice que
   es reintentable, con la espera que pide la respuesta.
6. **Privacidad**: quien tiene `aiExcluded` no es oído ni transcrito; los mensajes privados del
   chat no pasan nunca por la IA; la grabación se entrega al almacenamiento del integrador y
   Comms borra su copia al confirmarse. Qué guarda Comms, cuánto y por qué: `privacy.md`.
7. **Si la IA falla, la llamada sigue**: el código del integrador no puede depender de que llegue
   una ayuda o un evento de IA para que la reunión funcione.
8. **Desarrollar con claves de prueba** y pasar a `iacl_live_…` solo en producción; la
   configuración de cada modo se prepara aparte.

## Anti-patrones

- Crear la reunión o pedir el acceso desde el navegador con la clave.
- Guardar el acceso de una persona y reutilizarlo para otra.
- Leer el cuerpo de un webhook sin verificar la firma, o con el cuerpo ya parseado (la firma va
  sobre el cuerpo crudo).
- Tratar `action.proposed` como una orden que se ejecuta sola.
- Pintar la ayuda privada de la IA a todos los participantes.
- Copiar los ids de modelo de la documentación en vez de leerlos de `listAiModels()`.

## Dónde está cada cosa

En este mismo fichero, por este orden: el inicio rápido, la integración entera paso a paso, las
claves, Node, el navegador, los widgets de Vue, la IA en directo, la IA al cerrar, la grabación,
los webhooks y su orden, errores y reintentos, límites, privacidad, el catálogo de eventos, el
de errores y, al final, la referencia de cada paquete sacada de sus tipos.

---

<!-- fuente: docs/developers/quickstart.md -->

# De cero a una videollamada con IA en 5 minutos

Al acabar tendrás una reunión con vídeo, chat y la IA en directo funcionando en tu ordenador,
creada desde tu backend y abierta en el navegador. Con una **clave de prueba**: la IA es
simulada, no cuesta nada y no sale nada a ningún proveedor.

```
 Navegador ── (1) pide la reunión y el acceso ──▶ TU backend ── clave de API ──▶ API de IACL Comms
     │                                                                              │
     └── (2) entra con el acceso (token de corta duración) ──▶ vídeo, chat e IA ◀────┘
```

La regla que no se rompe: **la clave de API vive solo en tu backend**. Al navegador le llega
un acceso de corta duración que vale para una conexión de una reunión.

El proyecto entero está en [`examples/quickstart`](../../examples/quickstart): lo de abajo son sus
ficheros, tal cual.

## 0. Lo que necesitas

- **Node 22 o superior.**
- **Una clave de prueba** (`iacl_test_…`). Pídela en el portal de clientes de IACL Comms o al
  equipo de IACL. Se enseña **una sola vez**: guárdala en tu gestor de secretos. Cómo son las
  claves, sus permisos y sus límites: [api-keys.md](api-keys.md).

Con una clave de prueba, cada reunión admite 4 personas y dura como mucho 15 minutos, y la IA
usa los modelos simulados (`iacl-sandbox-live` e `iacl-sandbox-closing`).

## 1. Instala (1 minuto)

```bash
npm create vite@latest mi-reunion -- --template vue-ts
cd mi-reunion
npm install @iaconsultinglabs/comms-server @iaconsultinglabs/comms-core @iaconsultinglabs/comms-vue
npm install -D tsx concurrently
```

Pon tu clave en un `.env` (nunca en el repositorio ni en el navegador):

```ini
IACL_API_KEY=iacl_test_…
IACL_API_URL=https://api.comms.iaconsultinglabs.com/v1
```

## 2. El backend (2 minutos)

`server.ts` crea la reunión con la IA en directo y da el acceso a quien entra. En tu aplicación,
esto va dentro de tus rutas (Express, Fastify…), detrás de tu sesión: ahí decides quién entra y
con qué papel.

```ts
// El backend del inicio rápido (docs/developers/quickstart.md): crea una reunión con la IA en
// directo y da el acceso a quien entra. La clave de API vive aquí y nunca sale al navegador.
//
//   IACL_API_KEY=iacl_test_…  IACL_API_URL=https://api.comms.iaconsultinglabs.com/v1
//   npm run server
import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
import { pathToFileURL } from 'node:url'
import { createCommsClient, isCommsApiError } from '@iaconsultinglabs/comms-server'
import type { Device } from '@iaconsultinglabs/comms-contracts'

export interface QuickstartOptions {
  /** Tu clave: `iacl_test_…` para probar (IA simulada, gratis), `iacl_live_…` en producción. */
  apiKey: string
  /** La API de IACL Comms, con su `/v1`. */
  apiUrl: string
}

async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
  const chunks: Buffer[] = []
  for await (const chunk of req) chunks.push(chunk as Buffer)
  return chunks.length > 0 ? (JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<string, unknown>) : {}
}

function send(res: ServerResponse, status: number, body: unknown): void {
  res.writeHead(status, { 'content-type': 'application/json' })
  res.end(JSON.stringify(body))
}

/** El servidor del ejemplo, sin arrancar: `listen(3000)` para usarlo. */
export function createQuickstartServer(options: QuickstartOptions): Server {
  const comms = createCommsClient({ baseUrl: options.apiUrl, apiKey: options.apiKey })

  async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
    const url = new URL(req.url ?? '/', 'http://localhost')

    // 1. Una reunión con la IA en directo. Con una clave de prueba, el modelo es el simulado.
    //    Si la página ya trae una (otra pestaña), se reutiliza.
    if (req.method === 'POST' && url.pathname === '/api/meeting') {
      const { meetingId } = (await readJson(req)) as { meetingId?: string | null }
      if (meetingId && /^mtg_[0-9a-z]+$/.test(meetingId)) {
        const existing = await comms.getMeeting(meetingId)
        return send(res, 200, { meetingId: existing.id, apiUrl: options.apiUrl })
      }
      const meeting = await comms.createMeeting({
        type: 'meeting',
        title: 'Mi primera reunión con IA',
        settings: { ai: { enabled: true, realtime: true, postMeeting: true, profileId: 'aip_tpl_sales' } },
        // Lo que la IA sabe al empezar. Tú decides de dónde sale: tu CRM, tu ERP, un documento…
        aiContext: {
          brief: 'Llamada comercial con un cliente que pide presupuesto para un proyecto nuevo.',
          documents: [
            {
              title: 'Propuesta enviada',
              text: 'Plazo de entrega: 15 de diciembre. Precio: 12.000 € más IVA, instalación aparte. Validez: 30 días.',
            },
          ],
        },
      })
      return send(res, 201, { meetingId: meeting.id, apiUrl: options.apiUrl })
    }

    // 2. El acceso de quien entra. En tu app, aquí decides quién es y si puede entrar.
    const match = /^\/api\/meetings\/(mtg_[0-9a-z]+)\/token$/.exec(url.pathname)
    if (req.method === 'POST' && match?.[1]) {
      const { device, name } = (await readJson(req)) as { device: Device; name?: string }
      const grant = await comms.issueMemberToken(match[1], {
        person: { id: `demo-${device.key}`, name: name ?? 'Demo' },
        device,
        role: 'host',
        aiAssist: true, // ve la ayuda privada de la IA
      })
      return send(res, 201, grant)
    }

    send(res, 404, { error: 'not found' })
  }

  return createServer((req, res) => {
    route(req, res).catch((error: unknown) => {
      if (isCommsApiError(error)) {
        console.error('comms:', error.code, error.status, error.requestId)
        return send(res, error.status, { error: error.code })
      }
      console.error(error)
      send(res, 500, { error: 'internal' })
    })
  })
}

// `npm run server`: arranca con lo que diga el entorno (.env).
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const apiKey = process.env['IACL_API_KEY'] ?? ''
  const apiUrl = process.env['IACL_API_URL'] ?? 'https://api.comms.iaconsultinglabs.com/v1'
  if (!/^iacl_(test|live)_/.test(apiKey)) {
    console.error('Falta IACL_API_KEY (iacl_test_… para probar). Copia .env.example a .env.')
    process.exit(1)
  }
  createQuickstartServer({ apiKey, apiUrl }).listen(3000, () => {
    console.log(`Backend en http://localhost:3000 (${apiKey.startsWith('iacl_test_') ? 'prueba: IA simulada' : 'producción'})`)
  })
}
```

## 3. La página (1 minuto)

`src/App.vue`: un botón que pide la reunión a tu backend y, dentro, `MeetingRoom`, la sala
entera: escenario, botones, chat, personas, subtítulos (`captions`) y el panel privado de la IA
(`ai-panel`).

```vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import { createMeeting, currentDevice, type CommsMeeting } from '@iaconsultinglabs/comms-core'
import { MeetingRoom } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css'

const meeting = shallowRef<CommsMeeting | null>(null)
const error = shallowRef<string | null>(null)

// La reunión va en la dirección (`?m=mtg_…`): ábrela en otra pestaña y entras en la misma.
const shared = new URLSearchParams(location.search).get('m')

async function start(): Promise<void> {
  error.value = null
  // Tu backend crea la reunión (con tu clave, que nunca llega aquí), o da la de la dirección.
  const response = await fetch('/api/meeting', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ meetingId: shared }),
  })
  if (!response.ok) {
    error.value = `No se pudo crear la reunión (${response.status})`
    return
  }
  const { meetingId, apiUrl } = (await response.json()) as { meetingId: string; apiUrl: string }
  history.replaceState(null, '', `?m=${meetingId}`)

  meeting.value = createMeeting({
    apiUrl,
    // Se llama al entrar, al volver tras un corte y al renovar el acceso.
    tokenSource: async () => {
      const grant = await fetch(`/api/meetings/${meetingId}/token`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ device: currentDevice(), name: 'Yo' }),
      })
      if (!grant.ok) throw new Error(`token: ${grant.status}`)
      return grant.json()
    },
  })
}
</script>

<template>
  <main class="quickstart">
    <MeetingRoom v-if="meeting" :meeting="meeting" meeting-title="Mi primera reunión con IA" locale="es" captions ai-panel />
    <section v-else>
      <h1>IACL Comms: inicio rápido</h1>
      <p>Una reunión con vídeo, chat e IA en directo. Con una clave de prueba, la IA es simulada.</p>
      <button type="button" @click="start">Empezar la reunión</button>
      <p v-if="error" role="alert">{{ error }}</p>
    </section>
  </main>
</template>

<style>
.quickstart { min-height: 100dvh; font-family: system-ui, sans-serif; }
.quickstart section { max-width: 40rem; margin: 4rem auto; padding: 0 1rem; }
.quickstart button { min-height: 44px; padding: 0 1.25rem; font: inherit; }
</style>
```

Y que la página mande `/api` a tu backend (`vite.config.ts`):

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: { proxy: { '/api': 'http://localhost:3000' } },
})
```

## 4. Arranca (1 minuto)

```bash
npx concurrently "npx tsx --env-file=.env server.ts" "npx vite"
```

Abre <http://localhost:5173> y pulsa «Empezar la reunión». Ábrela en otra pestaña con el mismo
enlace de reunión y verás dos conexiones.

- **Subtítulos:** el botón «Subtítulos» de la barra. Con la clave de prueba, el texto sale de un
  guion de prueba, no de tu voz: así ves cómo se pinta sin gastar nada.
- **El panel de la IA:** sugerencias, respuestas con su fuente, datos del contexto y avisos, solo
  para quien tiene la ayuda (`aiAssist`), nunca para un invitado.
- **Al terminar**, si la reunión pidió el cierre (`postMeeting`), te llega el resumen por webhook.

## 5. Y después

| Quieres | Lee |
|---|---|
| Recibir lo que pasa en tu servidor (webhooks firmados, ponerse al día) | [integracion-de-cero.md](integracion-de-cero.md) |
| Darle contexto a la IA, detectores propios y las salidas de tu modo | [ia-en-directo.md](ia-en-directo.md) |
| Tu propia pantalla en vez de `MeetingRoom` | [widgets-vue.md](widgets-vue.md) |
| Grabar | [recording.md](recording.md) |
| Pasar a producción | [api-keys.md](api-keys.md): cambia a `iacl_live_…`, y configura otra vez el webhook, el destino de grabaciones y la IA con esa clave (cada modo tiene la suya) |

Si no usas Node, todo esto se hace con HTTP a pelo: [curl.md](curl.md).

---

<!-- fuente: docs/developers/integracion-de-cero.md -->

# Integrar IACL Comms desde cero

Esta guía lleva de una aplicación sin nada a una con reuniones, invitados, grabación e IA en
directo, paso a paso y con todo el código. Cada bloque `ts` y `vue` de esta página **se compila
en la CI** contra los paquetes publicados (`tools/docs/snippets.mjs`): si uno deja de
funcionar, la CI falla. El mismo recorrido, ejecutable, está en
[examples/node/backend.mjs](examples/node/backend.mjs) (el backend) y en `apps/example-vue` (la
pantalla).

```
 Navegador ── (1) pide acceso ──▶ TU backend ── clave de API ──▶ api.comms.iaconsultinglabs.com/v1
     │                                ▲                                   │
     └── (2) entra con el token ──────┼───────────▶ medios (opaco)         │
                                      └──────── (3) webhooks firmados ◀────┘
```

**La regla que no se rompe: la clave de API vive solo en tu backend.** Al navegador le llega
un token de corta duración que vale para una conexión de una reunión.

| Paquete | Dónde | Para qué |
|---|---|---|
| [`@iaconsultinglabs/comms-server`](../../packages/server/README.md) | Tu backend (Node 22+) | Reuniones, accesos, webhooks, grabaciones, IA |
| [`@iaconsultinglabs/comms-vue`](../../packages/vue/README.md) | Tu web (Vue 3.5+) | La sala entera, o sus piezas |
| [`@iaconsultinglabs/comms-core`](../../packages/core/README.md) | Tu web, sin Vue | La reunión como objeto con eventos |
| [`@iaconsultinglabs/comms-contracts`](../../packages/contracts/README.md) | Los dos | Los tipos y las constantes del contrato |

## 0. Lo que necesitas

1. **Una cuenta y sus claves de API.** Date de alta en el portal de clientes de IACL Comms (te
   crea la cuenta con una clave de prueba) o pídeselas al equipo de IACL.
   - Empiezas con una clave de prueba (`iacl_test_<id>.<secreto>`). Las de producción
     (`iacl_live_…`) llegan con un plan de pago, o te las da el equipo de IACL, y la primera
     trae `keys:manage` para crear las demás.
   - Cada clave se enseña **una sola vez**: guárdala en tu gestor de secretos y pásala a tu
     backend por variable de entorno.
   - Con la de `keys:manage` creas las demás: una por backend y por entorno, cada una con
     solo lo que necesita. Lo ves en el apartado 2.5 y en [api-keys.md](api-keys.md).
   - Empieza con la de **prueba**: sus reuniones duran como mucho 15 minutos y tienen como
     mucho 4 personas, su IA es simulada (sin coste y sin mandar nada a ningún proveedor) y
     su consumo no se factura.
   - **Cada modo tiene su configuración**, como en Stripe: el webhook, el destino de
     grabaciones, los modos y los detectores que pongas con la clave de prueba son solo de
     prueba. Al pasar a producción, configúralos otra vez con la clave de producción
     ([api-keys.md](api-keys.md#la-configuración-por-modo)).
2. **Los paquetes.** Están en npm, con el scope `@iaconsultinglabs`, y se instalan sin token.

3. **Tu dominio dado de alta.** Dile a IACL desde qué orígenes se sirve tu web: la API solo
   acepta las llamadas del navegador que vengan de ellos.

## 1. Instala los paquetes

```bash
# En el backend
pnpm add @iaconsultinglabs/comms-server

# En la web
pnpm add @iaconsultinglabs/comms-core @iaconsultinglabs/comms-vue
```

`comms-contracts` llega como dependencia de los demás; instálalo aparte solo si usas sus
constantes en tu código.

## 2. El backend

### 2.1 El cliente

Uno por proceso. Reintenta lo que es seguro reintentar, corta a los 30 s y nunca escribe la
clave en un log ni en un error.

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

export const comms = createCommsClient({
  baseUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  apiKey: process.env.COMMS_API_KEY ?? '',
})

// La clave vale si la API contesta: una página vacía es un tenant sin reuniones.
const page = await comms.listMeetings({ limit: 1 })
console.log(page.items.length)
```

### 2.2 Crear reuniones y dar acceso

Tu backend crea la reunión cuando tu aplicación lo necesita (una cita, un hilo, una llamada) y,
cuando alguien quiere entrar, decide si puede y le da su acceso (`TokenGrant`). Este servidor
`node:http` hace las dos cosas. Con Express o Fastify es lo mismo dentro de tus rutas.

```ts
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
import { createCommsClient, isCommsApiError } from '@iaconsultinglabs/comms-server'
import type { Device } from '@iaconsultinglabs/comms-contracts'

const comms = createCommsClient({
  baseUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  apiKey: process.env.COMMS_API_KEY ?? '',
})

/** TU APP: quién pide, según tu sesión. Aquí, una cabecera para probar en local. */
function currentUser(req: IncomingMessage): { id: string; name: string } | null {
  const id = req.headers['x-demo-user']
  return typeof id === 'string' ? { id, name: 'Demo' } : null
}

async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
  const chunks: Buffer[] = []
  for await (const chunk of req) chunks.push(chunk as Buffer)
  return chunks.length > 0 ? (JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<string, unknown>) : {}
}

function send(res: ServerResponse, status: number, body: unknown): void {
  res.writeHead(status, { 'content-type': 'application/json' })
  res.end(JSON.stringify(body))
}

async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
  const user = currentUser(req)
  if (!user) return send(res, 401, { error: 'login required' })
  const url = new URL(req.url ?? '/', 'http://localhost')

  // Crear una reunión. `externalRef` es tu id; con él como Idempotency-Key, repetir no crea otra.
  if (req.method === 'POST' && url.pathname === '/api/meetings') {
    const { title, ref } = (await readJson(req)) as { title?: string; ref?: string }
    const meeting = await comms.createMeeting(
      { type: 'meeting', title: title ?? 'Reunión', ...(ref ? { externalRef: ref } : {}), settings: { guestsAllowed: true } },
      ref ? { idempotencyKey: `meeting:${ref}` } : {},
    )
    return send(res, 201, { meetingId: meeting.id })
  }

  // Dar el acceso. Lo pide el navegador (el `tokenSource` del paso 3) con su aparato.
  const match = /^\/api\/meetings\/(mtg_[0-9a-z]+)\/token$/.exec(url.pathname)
  if (req.method === 'POST' && match?.[1]) {
    const { device } = (await readJson(req)) as { device: Device }
    // TU APP: decide aquí si este usuario puede entrar en esta reunión y con qué rol.
    const grant = await comms.issueMemberToken(match[1], {
      person: { id: user.id, name: user.name },
      device,
      role: 'host',
    })
    return send(res, 201, grant) // el grant entero; nunca la clave de API
  }

  send(res, 404, { error: 'not found' })
}

createServer((req, res) => {
  route(req, res).catch((error: unknown) => {
    // Decide por `code`, que es estable; el mensaje es para personas.
    if (isCommsApiError(error, 'meeting_ended')) return send(res, 409, { error: 'meeting_ended' })
    if (isCommsApiError(error, 'plan_limit_reached')) return send(res, 422, { error: 'plan_limit_reached' })
    if (isCommsApiError(error)) console.error('comms:', error.code, error.status, error.requestId)
    send(res, 500, { error: 'internal' })
  })
}).listen(3000)
```

Para alguien de fuera, `issueGuestToken(meetingId, { person, device })`, solo si la reunión
admite invitados (`settings.guestsAllowed`) y cuando ya ha pasado **tu** puerta: el enlace, la
sala de espera y el consentimiento son tuyos, Comms no los guarda. `GuestLobby` y `KnockCards`
(paso 3) son la parte visible de esa puerta.

### 2.3 Recibir los webhooks

Comms te avisa de lo que pasa (empieza, entra alguien, termina, hay grabación, la IA detectó algo)
con un `POST` firmado. Primero dile dónde, una sola vez; la respuesta trae el secreto de firma,
**solo esa vez**:

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const endpoint = await comms.setWebhookEndpoint({ url: 'https://app.example.org/hooks/comms' })
console.log('Guarda esto como COMMS_WEBHOOK_SECRET:', endpoint.secret)
```

Y monta el receptor. Comprueba la firma y el reloj, deduplica por `id` y solo contesta 2xx si
tu código terminó bien, así que lo que falla se vuelve a entregar (durante 72 h):

```ts
import { createServer } from 'node:http'
import { createWebhookHandler } from '@iaconsultinglabs/comms-server'

const webhooks = createWebhookHandler({
  // El secreto actual y, durante una rotación, el anterior.
  secrets: () => [process.env.COMMS_WEBHOOK_SECRET, process.env.COMMS_WEBHOOK_SECRET_PREVIOUS].filter((s): s is string => Boolean(s)),
  handlers: {
    'meeting.ended': async (event) => {
      console.log('terminó', event.data.meetingId, event.data.durationSeconds, 's')
    },
    'participant.joined': async (event) => {
      console.log('entró', event.data.personId, 'desde', event.data.device?.label ?? 'un aparato')
    },
  },
  // Jamás la clave ni el cuerpo en el log.
  onError: (error) => console.error('webhook:', error instanceof Error ? error.message : error),
})

// Lee el cuerpo crudo él mismo: la firma cubre los bytes exactos. Con Express, `express.raw()`,
// nunca `express.json()`, delante de esta ruta.
createServer(webhooks.nodeListener()).listen(3001)
```

Tienes 10 s para contestar: el trabajo largo, fuera (guárdalo y responde).

### 2.4 Ponerse al día

Si tu servidor estuvo caído, `reconcile` pide a la API lo que te perdiste desde el último cursor
y lo procesa en orden, con la misma deduplicación que el webhook. Ejecútalo al arrancar y cada
pocos minutos:

```ts
import { MemoryCursorStore, MemoryIdempotencyStore, createCommsClient, reconcile } from '@iaconsultinglabs/comms-server'
import type { AnyEvent } from '@iaconsultinglabs/comms-contracts'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

// En producción, los dos sobre tu base de datos, y el de idempotencia compartido con el webhook.
const cursorStore = new MemoryCursorStore()
const idempotency = new MemoryIdempotencyStore()

async function onEvent(event: AnyEvent): Promise<void> {
  console.log(event.type, event.id) // la MISMA función que usa tu webhook
}

const result = await reconcile({
  client: comms,
  cursorStore,
  idempotency,
  onEvent,
  onCursorExpired: async () => {
    // Más de 72 h sin reconciliar: reconstruye tu estado con listMeetings/getMeeting.
  },
})
console.log(result.processed, 'nuevos,', result.duplicates, 'repetidos')
```

### 2.5 Tus claves y tu consumo

Con una clave con `keys:manage` gestionas las de tu cuenta: creas, cambias permisos y
límites, rotas sin cortar y revocas. Con `usage:read`, lees el consumo del mes por clave.

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const admin = createCommsClient({ apiKey: process.env.COMMS_ADMIN_KEY ?? '', baseUrl: 'https://api.comms.iaconsultinglabs.com/v1' })

// La clave del backend que crea reuniones: solo lo justo.
const created = await admin.createApiKey({
  label: 'Backend de reuniones',
  scopes: ['meetings:read', 'meetings:write', 'tokens:create', 'events:read', 'ai:read', 'ai:run'],
})
console.log('Guárdala en el gestor de secretos ahora:', created.apiKey.prefix)

// Rotar sin cortar: el secreto anterior sigue valiendo 24 h.
await admin.rotateApiKey(created.apiKey.id)

// Lo de este mes, por clave; lo de las claves de prueba va aparte, en `test`.
const usage = await admin.getUsage({ breakdown: 'apiKey' })
console.log(usage.meetingMinutes, usage.test?.meetingMinutes ?? 0, usage.byApiKey?.length ?? 0)
```

- Sin el permiso de una ruta, la respuesta es `key_scope_missing`.
- Al tope del mes de una clave, `key_limit_reached`.
- Al pasar el límite de peticiones, `rate_limited` con `Retry-After`.

Los permisos y los límites, uno por uno, están en [api-keys.md](api-keys.md).

## 3. La pantalla

### 3.1 La sala entera con `comms-vue`

`MeetingRoom` es la reunión completa: escenario, botones, chat, personas, ajustes, grabación e
IA. Lo único que necesita de ti es cómo pedir el token a tu backend:

```vue
<script setup lang="ts">
import { createMeeting, currentDevice } from '@iaconsultinglabs/comms-core'
import { MeetingRoom } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css'

const props = defineProps<{ meetingId: string }>()

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  // Se llama al entrar, al volver tras un corte de red y al renovar el token.
  tokenSource: async () => {
    const response = await fetch(`/api/meetings/${props.meetingId}/token`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ device: currentDevice() }),
    })
    if (!response.ok) throw new Error(`token: ${response.status}`)
    return response.json() // el TokenGrant que devolvió tu backend
  },
})
</script>

<template>
  <MeetingRoom :meeting="meeting" meeting-title="Revisión semanal" locale="es" captions ai-panel recording-control />
</template>
```

Abre la página en dos pestañas: verás dos conexiones en la misma reunión. Los textos vienen en
castellano, catalán, inglés y francés (`locale`), y cualquiera se cambia con `messages`.

### 3.2 Tus piezas con los composables

Si quieres tu propia pantalla, los composables dan cada parte, reactiva, y los componentes
sueltos (`CallStage`, `ControlsBar`, `ChatPanel`, `LiveCaptions`…) se combinan como quieras:

```vue
<script setup lang="ts">
import { createMeeting } from '@iaconsultinglabs/comms-core'
import { CallStage, useConnectionState, useLocalMedia, useMeeting, useParticipants } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css'

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  tokenSource: async () => (await fetch('/api/meetings/mtg_0000000000000000/token', { method: 'POST' })).json(),
})

const { join, leave } = useMeeting(meeting)
const { status } = useConnectionState(meeting)
const { participants, activeSpeaker, count } = useParticipants(meeting)
const { media, toggleMicrophone, toggleCamera, lastError } = useLocalMedia(meeting)

void join({ camera: false })
</script>

<template>
  <p>{{ status }} · {{ count }} personas</p>
  <CallStage :participants="participants" :active-speaker="activeSpeaker" />
  <button @click="toggleMicrophone">{{ media.microphone ? 'Silenciar' : 'Hablar' }}</button>
  <button @click="toggleCamera">{{ media.camera ? 'Apagar cámara' : 'Encender cámara' }}</button>
  <button @click="leave">Salir</button>
  <p v-if="lastError">{{ lastError.code }}</p>
</template>
```

### 3.3 Sin Vue: `comms-core`

`comms-core` es la reunión como objeto: métodos para hacer y eventos para enterarte. Funciona con
cualquier framework (o ninguno):

```ts
import { createMeeting, currentDevice, isCommsError } from '@iaconsultinglabs/comms-core'

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  tokenSource: async () => {
    const response = await fetch('/api/meetings/mtg_0000000000000000/token', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ device: currentDevice() }),
    })
    return response.json() // el TokenGrant que devolvió tu backend
  },
})

meeting.on('state', (state) => console.log('conexión:', state.status, state.reason ?? ''))
meeting.on('participants', (list) => {
  for (const one of list) {
    const video = document.querySelector<HTMLVideoElement>(`video[data-identity="${one.identity}"]`)
    if (video && video.srcObject !== one.media.camera) video.srcObject = one.media.camera
  }
})
meeting.on('error', (error) => console.warn(error.code))

try {
  await meeting.join({ microphone: true, camera: false })
} catch (error) {
  if (isCommsError(error, 'media_permission_denied')) console.log('Sin permiso de micro: entra sin él')
  else throw error
}

document.querySelector('#mute')?.addEventListener('click', () => void meeting.toggleMicrophone())
document.querySelector('#leave')?.addEventListener('click', () => void meeting.destroy())
```

El audio de los demás lo reproduce el motor: no lo pongas en otro `<audio>`. Los `<video>`,
siempre `muted`.

## 4. Grabar

Comms graba el audio de cada persona por separado (y el vídeo, si lo pides) y **te lo entrega a
ti**: tu backend recibe cada parte con un `PUT` firmado y Comms borra su copia en cuanto
contestas que la tienes. Primero, tu destino:

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const destination = await comms.setStorageDestination({
  type: 'tenant_endpoint',
  url: 'https://app.example.org/comms/recordings',
})
// El secreto de entrega llega solo esta vez: guárdalo como COMMS_DELIVERY_SECRET.
if (destination.type === 'tenant_endpoint') console.log(destination.deliverySecret)
```

Después, el receptor. Comprueba la firma, la longitud y el sha256, guarda cada fichero una vez y
contesta el recibo:

```ts
import { createServer } from 'node:http'
import { createFileRecordingStore, createRecordingIngestHandler } from '@iaconsultinglabs/comms-server'

const ingest = createRecordingIngestHandler({
  secrets: () => [process.env.COMMS_DELIVERY_SECRET, process.env.COMMS_DELIVERY_SECRET_PREVIOUS].filter((s): s is string => Boolean(s)),
  // Una carpeta fuera de cualquier directorio web, o tu almacén ({ head, put, get }).
  store: createFileRecordingStore('/var/lib/mi-app/grabaciones'),
  onStored: (ref, info) => console.log('recibido', ref.recordingId, ref.partId, info.kind, info.sizeBytes),
})

// Sin lector de cuerpo delante. La ruta que llama Comms tiene que llegar entera:
// con Express, `app.all('/comms/recordings/*', ingest.nodeListener())`.
createServer(ingest.nodeListener()).listen(3002)
```

Y graba: desde tu backend, o deja que el anfitrión lo haga desde la sala (con
`settings.recording.hostControl` y `recording-control` en `MeetingRoom`):

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })
const meetingId = 'mtg_0000000000000000'

const recording = await comms.startRecording(meetingId, { kinds: ['audio_per_participant'] })
// …
await comms.stopRecording(meetingId, recording.id)
// Cuando todo está entregado llega `recording.ready`; con él, si quieres, la transcripción:
await comms.requestTranscription(meetingId, recording.id, { language: 'es' })
```

Todos en la sala ven «Grabando» mientras se graba, invitados incluidos, y no se puede ocultar.
Quien no quiera ser grabado entra con `recordingExcluded: true` en su acceso. El detalle, con
el protocolo para un receptor en otro lenguaje: [recording.md](recording.md).

## 5. La IA

La IA de Comms es **de IACL**: no conectas tu proveedor ni tu clave. Eliges un modelo de nuestro
catálogo, con su precio, y recibes lo que hace: subtítulos, detecciones y sugerencias en
directo, y un resumen con acciones propuestas al terminar. **Comms propone y nunca ejecuta**:
qué hacer con cada propuesta lo decides tú.

### 5.1 Elegir el modelo

El catálogo dice qué modelos hay, qué hace cada uno, en qué idiomas, cómo de rápido es y
cuánto cuesta:

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const { data: models } = await comms.listAiModels()
for (const model of models) {
  const unit = model.price.unit === 'person_minute' ? 'minuto-persona' : 'reunión'
  console.log(`${model.name.es} (${model.id}): ${model.kind}, ${model.latency}, ${model.price.eur} € por ${unit}`)
}

// Los de tu cuenta, para no repetirlo en cada reunión. El que no mandes vuelve al de IACL.
const defaults = await comms.setAiModelDefaults({ liveModel: 'iacl-live-fast', closingModel: 'iacl-closing-standard' })
console.log(defaults.liveModel, defaults.closingModel, defaults.source)
```

- `kind`: `live` para el directo, `closing` para el cierre.
- `price.unit`: `person_minute` (cada minuto con la IA en directo, por cada persona que oye) o
  `meeting` (cada reunión cerrada).
- `status`: `available`, o `preview` si todavía puede cambiar. Uno `deprecated` dice por cuál
  cambiarlo (`replacedBy`) y hasta cuándo funciona (`until`).
- **El modelo y su precio se congelan al empezar la reunión**: un cambio del catálogo no cambia
  lo que cuesta una reunión en marcha.

### 5.2 Encender la IA en una reunión

En la reunión dices qué hace la IA (`profileId`, un modo: tuyo o una plantilla de IACL) y, si
quieres otro que el de tu cuenta, qué modelo:

```ts
import { createCommsClient, isCommsApiError } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

try {
  const meeting = await comms.createMeeting({
    type: 'meeting',
    title: 'Visita comercial',
    settings: {
      ai: {
        enabled: true,
        realtime: true, // subtítulos, detecciones y sugerencias durante la reunión
        postMeeting: true, // resumen y acciones al terminar
        profileId: 'aip_tpl_sales', // la plantilla «comercial» de IACL
        liveModel: 'iacl-live-precise', // otro que el de la cuenta, solo en esta reunión
      },
    },
  })
  console.log(meeting.id)
} catch (error) {
  // Un modelo que no está en el catálogo, o no es de ese tipo: details.available trae los que valen.
  if (isCommsApiError(error, 'ai_model_unavailable')) console.log(error.details)
  else throw error
}
```

Todos los de la sala ven que hay IA (`AiIndicator`, siempre visible, invitados incluidos). A
quien no quiera que la IA le oiga, dale su acceso con `aiExcluded: true`: ni su audio ni sus
mensajes se procesan. Los mensajes privados no se procesan nunca.

### 5.3 Lo que dice la IA, con nuestros componentes

Con la sala entera basta con dos propiedades: `captions` (el botón «Subtítulos»; cada persona los
pone para sí) y `ai-panel` (las detecciones y sugerencias de quien organiza):

```vue
<script setup lang="ts">
import type { CommsMeeting } from '@iaconsultinglabs/comms-core'
import { MeetingRoom } from '@iaconsultinglabs/comms-vue'

defineProps<{ meeting: CommsMeeting }>()
</script>

<template>
  <MeetingRoom :meeting="meeting" captions ai-panel />
</template>
```

O las piezas sueltas en tu pantalla, debajo de `useMeeting`:

```vue
<script setup lang="ts">
import { AiIndicator, AiLivePanel, LiveCaptions, useAi } from '@iaconsultinglabs/comms-vue'

const ai = useAi()
</script>

<template>
  <AiIndicator v-if="ai.active.value" :ai="ai.ai.value" :excluded="ai.excluded.value" />
  <LiveCaptions :max-lines="2" />
  <AiLivePanel v-if="ai.isHost.value" />
</template>
```

### 5.4 Lo que dice la IA, pintado por ti

Todo lo de la IA cuelga de `meeting.ai` (`comms-core`): su estado, lo que va llegando y los
eventos para que lo enseñes con tu diseño. En Vue, `useAi()` da lo mismo, reactivo.

```ts
import { createMeeting } from '@iaconsultinglabs/comms-core'

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  tokenSource: async () => (await fetch('/api/comms/token', { method: 'POST' })).json(),
})

// Subtítulos: el provisional se corrige con la misma `segmentId` y `revision` mayor.
meeting.ai.on('caption', (caption) => {
  const who = caption.speaker.name ?? 'Alguien'
  console.log(`${who}: ${caption.text}${caption.isFinal ? '' : '…'}`)
})

// La ayuda privada: sugerencias, respuestas con su fuente, datos del contexto y avisos.
// Solo le llega a quien la ve (`meeting.ai.assist`); nunca a un invitado.
meeting.ai.on('help', (help) => {
  console.log(help.kind, help.text, help.sources.map((s) => s.title))
  void meeting.ai.sendFeedback(help.suggestionId, 'useful')
})

// Detecciones en directo y las salidas de tu modo, con la forma de sus datos.
meeting.ai.on('detection', (detection) => console.log(detection.detectorName, detection.data))
meeting.ai.onResult<{ texto: string }>('fecha_entrega', (result) => console.log('Entrega:', result.data.texto))

// En qué está la IA, qué modelo la hace y si esta conexión ve la ayuda.
meeting.ai.on('status', (ai) => console.log(ai.status, ai.liveModel ?? 'sin directo', ai.assist))

await meeting.join()
```

Los eventos sueltos de antes (`aiCaption`, `aiDetection`, `aiSuggestion`, `aiPacket`) siguen
llegando durante 0.x, marcados como obsoletos.

La ayuda en directo entera (el contexto, cómo se procesa cada turno, los cuatro tipos de ayuda,
los detectores, las salidas del modo, el chat, el panel y el consumo de cada reunión) está en
[ia-en-directo.md](ia-en-directo.md).

### 5.5 En tu backend

Lo mismo llega a tu backend por webhook, junto con lo del cierre. Ahí decides qué hacer: crear la
tarea, mandar el presupuesto, guardar el resumen. Después, dile a Comms qué hiciste con cada
propuesta (`sendAiFeedback`): así se mide la calidad.

```ts
import { createServer } from 'node:http'
import { createCommsClient, createWebhookHandler } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const webhooks = createWebhookHandler({
  secrets: process.env.COMMS_WEBHOOK_SECRET ?? '',
  handlers: {
    'detection.matched': async (event) => {
      console.log('detección', event.data.detectorName, event.data.stage, event.data.data)
    },
    'assistant.suggestion': async (event) => {
      console.log('sugerencia a', event.data.audienceParticipantIds.length, 'conexiones:', event.data.text)
    },
    'summary.ready': async (event) => {
      // El resumen está en TU almacenamiento (lo entregó Comms, como las grabaciones).
      console.log('resumen', event.data.closingId, event.data.status, event.data.location ?? '')
    },
    'action.proposed': async (event) => {
      // TU APP: ejecútala si quieres (o pide aprobación a una persona) y cuenta qué hiciste.
      await comms.sendAiFeedback(event.data.meetingId, {
        items: [{ kind: 'action', id: event.data.actionId, decision: 'accepted' }],
      })
    },
  },
})

createServer(webhooks.nodeListener()).listen(3001)
```

Contexto, modos, detectores propios y el cierre a mano: [ai.md](ai.md).

### 5.6 Lo que cuesta

Comms mide la IA por modelo: minutos-persona en directo y reuniones cerradas, cada una al precio
que tenía su modelo al empezar. Es lo que IACL te factura, con el desglose por modelo y por
clave (`getUsage({ breakdown: 'apiKey' })`).

Con una clave de prueba, la IA usa los modelos simulados (`iacl-sandbox-live` e
`iacl-sandbox-closing`): mismos eventos, precio 0 y nada sale a ningún proveedor. Sirve para
montar y probar tu pantalla antes de pagar un minuto.

## 6. Errores y reintentos

Todo lo que falla lleva un **código estable**: decide por él, nunca por el mensaje.

```ts
import { CommsNetworkError, createCommsClient, isCommsApiError } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

try {
  await comms.endMeeting('mtg_0000000000000000')
} catch (error) {
  if (isCommsApiError(error, 'not_found')) console.log('No existe')
  else if (isCommsApiError(error)) console.error(error.code, error.status, 'requestId para soporte:', error.requestId)
  else if (error instanceof CommsNetworkError) console.error('Sin respuesta', error.timedOut ? '(tiempo agotado)' : '')
  else throw error
}
```

```ts
import { isCommsError, type CommsMeeting } from '@iaconsultinglabs/comms-core'

export async function enter(meeting: CommsMeeting): Promise<void> {
  try {
    await meeting.join()
  } catch (error) {
    if (isCommsError(error, 'media_permission_denied')) return meeting.join({ microphone: false, camera: false })
    if (isCommsError(error) && error.retryable) return meeting.retry()
    throw error
  }
}
```

- El SDK de servidor reintenta solo lo que es seguro (lecturas, y lo que lleva
  `Idempotency-Key`), con espera creciente y respetando `Retry-After`.
- El navegador vuelve a entrar solo si se corta la red (`reconnecting`); si se rinde
  (`failed`), `meeting.retry()` lo intenta otra vez.
- La lista de códigos: [errors.md](../errors.md). Qué se reintenta:
  [errors-and-retries.md](errors-and-retries.md).

## 7. Antes de ir a producción

- [ ] La clave de API está en el gestor de secretos y solo en el backend; no sale en logs.
- [ ] Usas una clave de producción (`iacl_live_…`) con solo los permisos que necesita ese
      backend, y sabes rotarla sin cortar (`rotateApiKey`).
- [ ] Tu dominio está dado de alta en IACL.
- [ ] El webhook lee el cuerpo crudo, admite dos secretos (rotación) y contesta en menos de 10 s.
- [ ] Deduplicas por `event.id` con un almacén compartido si tienes varios procesos, y
      reconcilias al arrancar y cada pocos minutos.
- [ ] Decides por `code`, nunca por `message`, y registras `requestId`.
- [ ] Ignoras (con 2xx) los tipos de evento y los campos que no conoces.
- [ ] La interfaz enseña siempre el indicador de IA y el de grabación cuando están activos.
- [ ] Si grabas, tu receptor guarda fuera de cualquier directorio web y sirve los ficheros con
      tu autorización.
- [ ] Has elegido los modelos de IA de tu cuenta y sabes su precio.

## Referencia

- Cada función, componente y tipo, generado del código: la carpeta `docs/reference/` de cada
  paquete (también dentro del paquete instalado, en `node_modules/@iaconsultinglabs/<paquete>/docs/reference/`).
- La API HTTP: [api-reference.html](api-reference.html), [curl.md](curl.md).
- Los eventos: [events.md](../events.md). Los errores: [errors.md](../errors.md).
- Los cambios de cada versión: el `CHANGELOG.md` de cada paquete.

---

<!-- fuente: docs/developers/api-keys.md -->

# Claves de API

Tu backend habla con IACL Comms con una **clave de API**. En esta guía verás cómo se
consigue, cómo se usa, cómo se rota sin cortar el servicio y qué permisos, límites y modos
tiene. Las reglas completas están en el [ADR 0056](../adr/0056-api-keys-de-clientes.md).

## En dos minutos

1. **Pídela.** Date de alta en el portal de clientes de IACL Comms: crea tu cuenta con una clave
   de prueba (`iacl_test_…`). Las de producción (`iacl_live_…`) se crean allí con un plan de
   pago, o te las da el equipo de IACL.
2. **Guárdala.** Se enseña una sola vez. Al gestor de secretos, y a tu backend por variable de
   entorno:

   ```ini
   # .env de tu backend (nunca en el repositorio)
   IACL_API_KEY=iacl_test_…
   ```

3. **Úsala solo en tu backend**, con `@iaconsultinglabs/comms-server` o en la cabecera
   `Authorization: Bearer …`. **Nunca en el navegador ni en una app:** allí va el acceso de
   corta duración que tu backend pide para cada persona (`issueToken`). El
   [inicio rápido](quickstart.md) lo monta entero.
4. **Prueba con la de prueba y pasa a la de producción** cuando esté listo:

   | | `iacl_test_…` | `iacl_live_…` |
   |---|---|---|
   | Reuniones | Hasta 4 personas y 15 minutos | Las de tu plan |
   | IA | Simulada: mismos eventos, gratis, nada sale a ningún proveedor | Los modelos del catálogo, a su precio |
   | Consumo | Aparte, no se factura | Se factura |
   | Configuración (webhook, grabaciones, modos, detectores) | La suya | La suya: cada modo tiene la propia |

## Cómo es una clave

```text
iacl_live_7m2n4p6q8r1s3tEXAMPLE.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└─modo──┘└──── id ──────┘ └──────────── secreto ──────────────────────┘
```

- El **prefijo** dice el modo: `iacl_live_` es de producción e `iacl_test_` es de prueba. Una
  clave no cambia nunca de modo.
- La clave completa se enseña **una sola vez**, al crearla o al rotarla. Comms solo guarda su
  hash: si la pierdes, rótala.
- Va siempre en la cabecera `Authorization: Bearer …` y **solo en tu servidor**. Nunca en el
  navegador ni en una app: allí va el token de cada conexión (`issueToken`).

## Conseguir la primera clave

Desde el portal de clientes creas, rotas y revocas tus claves sin escribir código. Para
hacerlo desde tu código necesitas una clave con el permiso `keys:manage` (créala en el portal
o pídesela al equipo de IACL). Con ella creas el resto: una para cada backend o entorno, cada
una con solo lo que necesita.

```bash
export COMMS_API="https://api.comms.iaconsultinglabs.com/v1"
export COMMS_API_KEY="iacl_live_EXAMPLE0000.not-a-real-secret"   # la de keys:manage, del gestor de secretos
```

### Crear una clave (`createOwnApiKey`)

Sin `scopes`, la clave tiene todos los permisos menos `keys:manage`. Sin `mode`, es de
producción.

```bash
curl -sS -X POST "$COMMS_API/api-keys" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Backend producción","scopes":["meetings:read","meetings:write","tokens:create","events:read"],"limits":{"requestsPerMinute":600}}'
```

La respuesta trae `secret`. Guárdalo en tu gestor de secretos **ahora**: no se vuelve a ver.

### Listar y consultar (`listOwnApiKeys`, `getOwnApiKey`)

Sin secretos: solo el prefijo para reconocerlas, el modo, los permisos, los límites y cuándo
se usaron por última vez.

```bash
curl -sS "$COMMS_API/api-keys" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS "$COMMS_API/api-keys/key_4kq9x2m7a1b3c5d7" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

### Cambiar el nombre, los permisos o los límites (`updateOwnApiKey`)

Vale desde la siguiente petición de esa clave. `limits` sustituye los límites enteros y
`null` los quita.

```bash
curl -sS -X PATCH "$COMMS_API/api-keys/key_4kq9x2m7a1b3c5d7" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["meetings:read","usage:read"],"limits":{"requestsPerMinute":60}}'
```

### Rotar sin cortar (`rotateOwnApiKey`)

Devuelve un secreto nuevo. El anterior sigue valiendo durante `graceSeconds`: por defecto
24 h y como mucho 7 días. Con `0` deja de valer en el acto. Mientras dura la gracia,
`previousSecretExpiresAt` dice hasta cuándo.

```bash
curl -sS -X POST "$COMMS_API/api-keys/key_4kq9x2m7a1b3c5d7/rotate" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"graceSeconds":3600}'
```

El orden seguro es este:

1. Rota.
2. Despliega el secreto nuevo en todos tus servidores.
3. Deja que pase la gracia.

Si rotas otra vez antes de que acabe la gracia, el secreto más antiguo deja de valer: solo
convive uno anterior.

### Revocar (`revokeOwnApiKey`)

La clave deja de valer en el acto, y también su secreto anterior si estaba en gracia. Las
reuniones que creó siguen. Una clave no puede revocarse a sí misma: hazlo con otra.

```bash
curl -sS -X DELETE "$COMMS_API/api-keys/key_4kq9x2m7a1b3c5d7" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## Permisos

Cada ruta pide exactamente un permiso. Si la clave no lo tiene, la respuesta es 403 con
`key_scope_missing`, y `details.scope` dice cuál falta.

| Permiso | Qué deja hacer |
|---|---|
| `meetings:read` | Listar y consultar reuniones |
| `meetings:write` | Crear, terminar y rechazar reuniones, pasar el mando, sacar a alguien |
| `tokens:create` | Emitir el acceso de una conexión (`issueToken`) |
| `events:read` | Reconciliar eventos por cursor (`listEvents`) |
| `recordings:read` | Consultar grabaciones y transcripciones |
| `recordings:write` | Empezar y parar grabaciones, pedir transcripciones |
| `storage:manage` | El destino de las grabaciones y su secreto |
| `webhooks:manage` | El webhook y su secreto |
| `ai:read` | El catálogo de modelos, los modos, los detectores, los cierres y el estado del contexto |
| `ai:configure` | Modelos por defecto, modos, detectores y la fuente de contexto |
| `ai:run` | La IA de una reunión: su contexto, cambiarla, pedir un cierre y valorar |
| `usage:read` | El consumo de la cuenta y de cada clave (`getUsage`) |
| `keys:manage` | Las claves de la cuenta (`/api-keys`) |

Lo recomendable es una clave por backend con lo justo. Por ejemplo, el servicio que solo crea
reuniones y emite accesos tendría `meetings:write`, `meetings:read` y `tokens:create`; el
panel de consumo, solo `usage:read`.

## Límites

Los de cada clave van aparte de los del plan de tu cuenta, y se ponen en `limits`:

| Límite | Al llegar |
|---|---|
| `requestsPerMinute` | `rate_limited` (429) con `Retry-After`. Las demás claves siguen |
| `meetingMinutesPerMonth` | `key_limit_reached` (422) al crear reuniones o emitir accesos |
| `aiRealtimeMinutesPerMonth` | `key_limit_reached` al crear o cambiar reuniones con IA en directo |
| `aiClosingsPerMonth` | `key_limit_reached` al pedir un cierre |

Los topes del mes nunca cortan lo que ya está en marcha: una reunión en curso sigue hasta que
acaba. `details` trae `limit`, `max` y `used`.

## Prueba y producción

Una clave `test` (`iacl_test_…`) sirve para desarrollar e integrar sin coste y sin tocar
nada de verdad:

- Sus reuniones salen con `mode: "test"`. Como mucho tienen 4 personas y duran 15 minutos.
- Sus topes del mes ya vienen puestos: 600 minutos de reunión, 300 de IA en directo, 50
  cierres y 120 peticiones por minuto. Los que pongas en `limits` mandan sobre estos.
- **La IA es simulada.** Solo ve y usa `iacl-sandbox-live` e `iacl-sandbox-closing`:
  subtítulos, detecciones, sugerencias y cierres deterministas, a precio 0 y sin mandar nada
  a ningún proveedor. La forma de los eventos es la misma que en producción, así que tu
  pantalla funciona igual.
- Su consumo va aparte (`Usage.test`): no suma a tus totales, no cuenta para tu plan y no se
  factura.
- Una clave `test` solo ve y crea claves `test`.

### La configuración, por modo

Como en Stripe, cada modo tiene **su propia configuración** (ADR 0059). No hace falta una cuenta
de pruebas aparte: con la clave de prueba configuras lo de prueba, y con la de producción, lo de
producción.

| Qué | Por separado en test y en live |
|---|---|
| Webhook (`setWebhookEndpoint`), con su propio secreto | Sí |
| Destino de grabaciones (`setStorageDestination`), con su propio secreto de entrega | Sí |
| Fuente de contexto de la IA (`setAiContextSource`) | Sí, firmada con el webhook de su modo |
| Modelos por defecto (`setAiModelDefaults`) | Sí; en test solo los simulados |
| Modos (`createAiProfile`) y detectores (`createDetector`) | Sí |
| Reuniones y eventos (`listMeetings`, `listEvents`) | Sí |

- **Las rutas son las mismas.** El modo lo da la clave que llama, y lo del otro modo responde
  `not_found`, como lo de otro cliente.
- **Una clave de prueba nunca lee ni cambia lo de producción**, ni al revés. Tampoco ve sus
  reuniones ni sus eventos.
- **Lo de una reunión va por la configuración de su modo:** los eventos de una reunión de
  prueba salen por el webhook de prueba, y sus grabaciones van al destino de prueba.
- **Sin configuración en un modo no se usa la del otro.** Sin webhook de prueba, lo de prueba
  solo está en `listEvents`. Sin destino de prueba, grabar una reunión de prueba es
  `storage_destination_missing`.
- **El consumo (`getUsage`) también va por modo.** Con una clave de prueba solo ves lo de
  prueba (sus claves y sus reuniones, con `mode: "test"`). Con una de producción ves lo de
  producción, con lo de prueba aparte en `test`.

Si antes usabas una clave de prueba con la configuración de la cuenta, esa configuración es
ahora la de producción: vuelve a configurar con tu clave de prueba lo que uses en pruebas.

## Consumo (`getUsage`)

Pide `usage:read`. Sin `period` devuelve el mes en curso; con `breakdown=apiKey` añade el
consumo de cada clave, con su IA por modelo.

```bash
curl -sS "$COMMS_API/usage?period=2026-10&breakdown=apiKey" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

- Los totales son de producción. Lo de prueba sale aparte, en `test`.
- Un mes ya terminado lleva `closed: true` y no cambia nunca más: es lo que se factura.
- En `byApiKey`, `apiKeyId: null` agrupa las reuniones creadas antes de que el consumo se
  atribuyera a cada clave.

## Con el SDK de Node

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

// Una clave de prueba para el entorno de desarrollo.
const { apiKey, secret } = await comms.createApiKey({ label: 'Desarrollo', mode: 'test' })

// Rotar con una hora de margen.
const rotated = await comms.rotateApiKey(apiKey.id, { graceSeconds: 3600 })

// El consumo del mes por clave.
const usage = await comms.getUsage({ breakdown: 'apiKey' })
```

`createApiKey` y `rotateApiKey` **no se reintentan nunca**: el secreto sale una vez, y
repetir la petición crearía otra clave o volvería a rotar.

## Tu plan y las claves de producción

Si tu cuenta la diste de alta en el portal de clientes, las claves de producción dependen de tu
plan (ADR 0061).

**Sin un plan de pago activo** solo hay claves de prueba. Crear una de producción, desde el portal
o con `keys:manage`, da `live_keys_not_allowed` (403).

**Con un pago pendiente** tienes unos días de gracia. Después, y hasta que se resuelva:
- crear una reunión de producción da `billing_hold` (402), con `details.since`;
- también dar acceso a una reunión de producción que aún no ha empezado.

Lo que sigue igual:
- las reuniones que están en curso, también para quien entra o se reconecta;
- las claves de prueba;
- leer, configurar y el consumo.

```ts
// `comms` y `isCommsApiError` como en el resto de la guía.
// try { await comms.createMeeting({ type: 'meeting' }) }
// catch (e) { if (isCommsApiError(e, 'billing_hold')) avisarDelPago(e.details?.since) }
```

## Si te suspenden la cuenta

Con la cuenta suspendida, ninguna clave vale (`tenant_suspended`, 403). Las reuniones que
estaban en curso siguen hasta que acaban, salvo que IACL las corte. Al reactivar la cuenta,
las claves que no estaban revocadas vuelven a valer sin hacer nada.

---

<!-- fuente: docs/developers/node.md -->

# El backend en Node: `@iaconsultinglabs/comms-server`

El SDK de servidor (0.1.0, estable) cubre toda la API del tenant: reuniones, acceso, mando,
eventos y webhook. Además verifica los webhooks, deduplica y reconcilia. No tiene
dependencias de ejecución y necesita Node 22 o superior. La referencia completa está en el
[README del paquete](../../packages/server/README.md); aquí, lo que se copia.

Un backend entero y probado (un test lo ejecuta contra la API simulada):
[examples/node/backend.mjs](examples/node/backend.mjs).

## Instalar y crear el cliente

```bash
pnpm add @iaconsultinglabs/comms-server   # desde npm, sin token
```

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

export const comms = createCommsClient({
  apiKey: process.env.COMMS_API_KEY!,                   // iacl_live_<id>.<secreto>
  baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', // con /v1
  timeoutMs: 15_000,                                    // por intento (30 s por defecto)
  retries: 2,                                           // solo en lo que se puede repetir sin riesgo
})
```

El paquete es solo ESM. Desde un backend CommonJS, cárgalo con `import()` la primera vez que
haga falta:

```js
// CommonJS
let commsPromise
function getComms() {
  commsPromise ??= import('@iaconsultinglabs/comms-server').then(({ createCommsClient }) =>
    createCommsClient({ apiKey: process.env.COMMS_API_KEY, baseUrl: process.env.COMMS_API }),
  )
  return commsPromise
}
```

## Cada operación

```ts
// Reuniones
const meeting = await comms.createMeeting(
  { type: 'meeting', title: 'Revisión de obra', externalRef: 'thread_66f1c0a2', settings: { guestsAllowed: true } },
  { idempotencyKey: 'thread_66f1c0a2' },
)
const call = await comms.createMeeting({ type: 'call', caller: { id: 'usr_ana' }, invitees: ['usr_marc'], settings: { video: false } })
const page = await comms.listMeetings({ status: 'active', limit: 20 })
for await (const m of comms.iterateMeetings({ externalRef: 'thread_66f1c0a2' })) console.log(m.id, m.status)
const detail = await comms.getMeeting(meeting.id) // con participants
await comms.endMeeting(meeting.id)                // { reason: 'call_cancelled' } para colgar una llamada que suena
await comms.declineCall(call.id, { personId: 'usr_marc' })

// Acceso
const host = await comms.issueMemberToken(meeting.id, { person: { id: 'usr_ana', name: 'Ana' }, device: { key: 'dk_7f3a9c2e' }, role: 'host' })
const guest = await comms.issueGuestToken(meeting.id, {
  person: { id: 'gst_51b2', name: 'Joan (Proveedor)' },
  device: { key: 'dk_c01d4e88', label: 'phone' },
  permissions: { screenShare: false },
})
// aiExcluded solo se puede pedir con issueToken (el genérico):
const excluded = await comms.issueToken(meeting.id, {
  person: { id: 'gst_77c1', kind: 'guest', name: 'Visita' },
  role: 'guest',
  device: { key: 'dk_0a1b2c3d' },
  aiExcluded: true,
})

// Quien manda
await comms.transferHost(meeting.id, { identity: host.identity })
await comms.removeParticipant(meeting.id, guest.identity, { scope: 'person', blockPerson: true })

// Eventos y webhook
const { secret } = await comms.setWebhookEndpoint({ url: 'https://app.example.org/hooks/comms' }) // "" si ya existía
const endpoint = await comms.getWebhookEndpoint()
const rotated = await comms.rotateWebhookSecret() // rotated.secret, una vez
for await (const event of comms.iterateEvents({ types: ['meeting.ended'] })) console.log(event.id)
```

Lo que el SDK de servidor **no** tiene en 0.1.0:

- las rutas `/participant/*` (chat y turno de pantalla): son del navegador, con el token del
  participante, y las hace `comms-core`;
- `/ops/*`: es de la operación de IACL;
- nada de IA que ejecute: las acciones propuestas las ejecuta tu sistema; el SDK solo tiene
  `sendAiFeedback` para devolver la decisión ([ai.md](ai.md)).

## Errores

```ts
import { isCommsApiError, CommsNetworkError, CursorExpiredError } from '@iaconsultinglabs/comms-server'

try {
  await comms.issueGuestToken(meetingId, input)
} catch (error) {
  if (isCommsApiError(error, 'guests_not_allowed')) return reply(403, 'Esta reunión no admite invitados')
  if (isCommsApiError(error, 'plan_limit_reached')) return reply(422, 'La reunión está llena')
  if (isCommsApiError(error, 'meeting_ended')) return reply(409, 'La reunión ya terminó')
  if (isCommsApiError(error)) logger.error({ code: error.code, status: error.status, requestId: error.requestId })
  if (error instanceof CommsNetworkError) logger.warn('Comms no contesta')
  throw error
}
```

Qué se reintenta solo y qué no: [errors-and-retries.md](errors-and-retries.md).

## Webhooks y reconciliación

```ts
import { createWebhookHandler, reconcile, type AnyEvent, type IdempotencyStore } from '@iaconsultinglabs/comms-server'

// Un almacén compartido por el webhook y la reconciliación (aquí, Redis).
const idempotency: IdempotencyStore = {
  seen: async (id) => (await redis.exists(`comms:evt:${id}`)) === 1,
  remember: async (id, ttl) => void (await redis.set(`comms:evt:${id}`, '1', 'EX', ttl)),
}

async function onEvent(event: AnyEvent) {
  switch (event.type) {
    case 'participant.joined':
      return attendance.markIn(event.data.meetingId, event.data.personId, event.data.joinedAt)
    case 'meeting.ended':
      return meetings.close(event.data.meetingId, event.data.durationSeconds, event.data.endReason)
    case 'message.sent':
      return chat.save(event.data) // el texto solo llega una vez: guárdalo aquí
  }
}

const webhook = createWebhookHandler({
  secrets: () => [process.env.COMMS_WEBHOOK_SECRET!, process.env.COMMS_WEBHOOK_SECRET_PREVIOUS].filter(Boolean) as string[],
  idempotency,
  onEvent,
  onError: (error) => logger.warn({ error: String(error) }, 'comms webhook'),
})
app.post('/hooks/comms', express.raw({ type: 'application/json', limit: '1mb' }), webhook.nodeListener())

// Al arrancar y cada 5 minutos.
setInterval(() => reconcile({ client: comms, cursorStore, idempotency, onEvent, onCursorExpired: rebuild }), 5 * 60_000)
```

Con Fastify, sin Express o con otro framework: `webhook.handle({ rawBody, headers })` y
contestas con `result.status` y `result.body`. Detalle en el
[README del paquete](../../packages/server/README.md#recibir-webhooks).

## Probar tu integración sin red

```ts
import { createMockCommsServer, signWebhookPayload, exampleEvent } from '@iaconsultinglabs/comms-server/testing'

const mock = await createMockCommsServer()          // una API simulada que valida contra el contrato
const comms = createCommsClient({ apiKey: mock.apiKey, baseUrl: mock.baseUrl })
mock.fail('issueToken', 'plan_limit_reached')        // el siguiente issueToken falla así
// … tu código …
expect(mock.contractViolations).toEqual([])          // no mandaste nada fuera del contrato

const { rawBody, headers } = signWebhookPayload({ secret: 'whsec_test', body: exampleEvent('meeting.ended') })
await webhook.handle({ rawBody, headers })           // un webhook firmado como lo firma IACL
```

`createMockCommsServer` necesita `ajv` y `ajv-formats` como `devDependencies`.

---

<!-- fuente: docs/developers/browser.md -->

# El navegador: `comms-core` y `comms-vue`

En el navegador hay dos paquetes, los dos en **beta** (`0.1.0-beta`, etiqueta `beta` del
registro). La API pública puede cambiar antes de la 0.1.0 estable; fija la versión exacta.

| Paquete | Qué es | Cuándo |
|---|---|---|
| `@iaconsultinglabs/comms-core` | El motor de la reunión, sin interfaz y sin framework | Si pintas tu propia interfaz, o usas React, Angular, Svelte… |
| `@iaconsultinglabs/comms-vue` | Composables y componentes Vue 3 sobre `comms-core`, también como custom elements | Si quieres la reunión hecha (escenario, botones, chat, vestíbulo) |

```bash
pnpm add @iaconsultinglabs/comms-core@beta
pnpm add @iaconsultinglabs/comms-vue@beta   # además, si usas Vue o los custom elements
```

Los dos piden el acceso a **tu backend** con una función, `tokenSource`, que devuelve el
`TokenGrant` que emitió tu backend ([node.md](node.md), [curl.md](curl.md)). El navegador
nunca ve la clave de API.

## El `tokenSource`

```ts
import { currentDevice, type TokenSource } from '@iaconsultinglabs/comms-core'

export function tokenSourceFor(meetingId: string): TokenSource {
  return async ({ reason }) => {
    // reason: 'join' al entrar, 'rejoin' al volver tras un corte, 'refresh' al renovar.
    const response = await fetch(`/api/meetings/${meetingId}/token`, {
      method: 'POST',
      credentials: 'include', // tu sesión
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ device: currentDevice(), reason }),
    })
    if (!response.ok) throw new Error(`token ${response.status}`)
    return response.json()
  }
}
```

`currentDevice()` da `{ key, label }`: una clave del aparato que vive en `sessionStorage`
mientras dura la pestaña. Con ella, recargar la página es volver con la misma conexión y no
aparecer dos veces. Pásala tal cual a `issueToken` como `device`.

Si tu backend contesta que no (la persona está bloqueada, la reunión terminó), el motor deja
de intentarlo y se queda en `failed`.

## Vue: la reunión entera

```vue
<script setup lang="ts">
import { createMeeting } from '@iaconsultinglabs/comms-core'
import { MeetingRoom } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css'
import { tokenSourceFor } from './tokenSource'

const props = defineProps<{ meetingId: string; title: string }>()
const emit = defineEmits<{ left: [] }>()

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1', // para el chat y el turno de pantalla
  tokenSource: tokenSourceFor(props.meetingId),
})
</script>

<template>
  <MeetingRoom :meeting="meeting" :meeting-title="title" locale="es" theme="auto" @left="emit('left')" />
</template>
```

- `MeetingRoom` entra al montar (`auto-join`, por defecto sí) y emite `left` al salir y
  `state` en cada cambio de estado de la conexión.
- `locale="es|en"`, `messages` para cambiar cualquier texto, y las variables CSS
  `--iacl-color-*`, `--iacl-radius` y `--iacl-font` para el tema.
- Piezas sueltas si montas tu pantalla: `CallStage`, `ControlsBar`, `ChatPanel`,
  `ParticipantsPanel`, `DeviceSettings`, `AiIndicator`… y los composables `useMeeting`,
  `useParticipants`, `useLocalMedia`, `useScreenShare`, `useMeetingChat`,
  `useAiDisclosure`. Lista completa en el [README de comms-vue](../../packages/vue/README.md).

### El vestíbulo de un invitado

La sala de espera es tuya (Comms no guarda nada de invitados). `GuestLobby` es solo la
interfaz: vista previa, cámara, micro, nombre y las condiciones que tenga que aceptar. Cuando
pulsa «Pedir entrar», recibes `request`; llamas a tu backend, que decide y, si entra, emite un
acceso de invitado.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { GuestLobby, MeetingRoom, type LobbyRequest, type LobbyStatus } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css'
import { guestTokenSourceFor } from './tokenSource'

const props = defineProps<{ invitationId: string }>()
const status = ref<LobbyStatus>('form')

async function onRequest(request: LobbyRequest) {
  status.value = 'waiting'
  // Tu backend: guarda el nombre y el consentimiento, avisa a quien organiza y espera su respuesta.
  const response = await fetch(`/api/invitations/${props.invitationId}/knock`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ name: request.name, consentAccepted: request.consentAccepted === true }),
  })
  status.value = response.ok ? 'admitted' : 'rejected'
}
</script>

<template>
  <GuestLobby
    v-if="status !== 'admitted'"
    meeting-title="Revisión de obra"
    :status="status"
    :consent="{ text: 'Acepto las condiciones de la reunión' }"
    @request="onRequest"
  />
  <MeetingRoom
    v-else
    :token-source="guestTokenSourceFor(invitationId)"
    api-url="https://api.comms.iaconsultinglabs.com/v1"
    meeting-title="Revisión de obra"
  />
</template>
```

(`guestTokenSourceFor` es como el `tokenSourceFor` de arriba, contra la ruta de tu backend
que emite el acceso de invitado con `issueGuestToken`.) Sin aceptar las condiciones, el
vestíbulo no emite `request`.

## Sin Vue: custom elements

```html
<script type="module">
  import { defineCommsElements } from '@iaconsultinglabs/comms-vue/elements'
  defineCommsElements() // <iacl-meeting>, <iacl-guest-lobby>, <iacl-knock-cards>

  const room = document.querySelector('iacl-meeting')
  // Lo que no es texto va como PROPIEDAD del elemento, no como atributo.
  room.apiUrl = 'https://api.comms.iaconsultinglabs.com/v1'
  room.tokenSource = () =>
    fetch('/api/meetings/mtg_4kq9x2m7a1b3c5d7/token', { method: 'POST' }).then((r) => r.json())
  room.addEventListener('left', () => location.assign('/'))
</script>

<iacl-meeting meeting-title="Obra 12" locale="es"></iacl-meeting>
```

La entrada `elements` lleva Vue dentro y sus estilos en cada shadow root: no hace falta
montar Vue.

## Sin Vue: `comms-core` a pelo

```ts
import { createMeeting, isCommsError, ScreenShareBusyError } from '@iaconsultinglabs/comms-core'

const meeting = createMeeting({ apiUrl: 'https://api.comms.iaconsultinglabs.com/v1', tokenSource: tokenSourceFor(meetingId) })

meeting.on('state', (state) => render.status(state.status)) // idle · connecting · connected · reconnecting · disconnected · failed
meeting.on('participants', (list) => render.tiles(list))

try {
  await meeting.join({ camera: true, microphone: true })
} catch (error) {
  if (isCommsError(error)) render.error(error.code) // decide por code: plan_limit_reached, person_blocked…
}

await meeting.toggleMicrophone()
try {
  await meeting.startScreenShare()
} catch (error) {
  if (error instanceof ScreenShareBusyError) render.askTakeOver() // otra conexión presenta
}
await meeting.sendChat('Hola')
await meeting.leave()
```

- `meeting.people` agrupa las conexiones por persona: alguien con el portátil y el móvil es
  una persona con dos conexiones.
- Si el navegador bloquea el audio hasta que el usuario toque algo, el motor lo avisa
  (`audioBlocked`) y `meeting.startAudio()` desde un clic lo desbloquea.
- El desenfoque de fondo necesita servir el wasm y el modelo de MediaPipe y pasar
  `blur: { wasmBaseUrl, modelUrl, strength? }` ([README de comms-core](../../packages/core/README.md#desenfoque)).

## La IA se enseña siempre

`TokenGrant.ai` dice si la reunión tiene IA activa. Si `ai.enabled` es `true`, tu interfaz
**tiene** que enseñarlo a todos, invitados incluidos, mientras dure (`AiIndicator` en
`comms-vue`, `meeting.ai` en `comms-core`). En el contrato 0.1.0 la IA está reservada y no
procesa nada: hoy llega siempre apagada.

## «Grabando» también se enseña siempre

Desde el contrato 0.2.0, `TokenGrant.recording` dice si se está grabando, y la sala avisa
cuando empieza o para (tema `iacl.recording`). Mientras `recording.active` sea `true`, tu
interfaz **tiene** que enseñarlo a todos: `MeetingRoom` lo hace solo (`RecordingIndicator`);
con `comms-core`, escucha `meeting.on('recording', …)` o lee `meeting.recording`.
`meeting.recordingExcluded` dice si a esta persona no se la graba.

El anfitrión puede grabar y parar desde la sala si la reunión tiene
`settings.recording.hostControl: true`: en `MeetingRoom`, con la propiedad
`recording-control` (`recordingControl` en Vue) aparece el botón «Grabar» para quien tiene
`role: host`; con `comms-core`, `meeting.startRecording()` y `meeting.stopRecording()`.
Los textos vienen en castellano, catalán, inglés y francés (`locale`: `es`, `ca`, `en`,
`fr`). Más en [recording.md](recording.md).

## El dominio de tu web

El navegador llama a `/participant/*` (chat y turno de pantalla) directamente a la API de
Comms, desde el dominio de tu web. Dile a IACL desde qué orígenes sirves la reunión
(`https://app.example.org`, y el de tus entornos de pruebas) para que los dé de alta. Un
origen que no esté en la lista del nodo no puede llamar a la API: el navegador bloquea el chat
y la pantalla compartida por CORS, aunque la reunión en sí funcione.

La conexión de medios usa la dirección que viene en el acceso (`connection.url`) y su TURN:
no tienes que configurar ningún otro dominio. Detrás de un cortafuegos corporativo, tiene que
poder salir como mínimo a `api.`, `rtc.` y `turn.comms.iaconsultinglabs.com` por TCP 443 (el
TURN por TLS en el 443 es el último recurso); la calidad es mejor si además sale por UDP
3478 y 50000-60000.

## Lo que no hay en el navegador

- Pantalla compartida en móviles: el navegador no lo permite, y `comms-vue` oculta el botón.
- Publicar pistas de audio o vídeo que ya tengas tú (tu propia captura): el motor abre la
  cámara y el micro él mismo. Está pedido (CR-8) y todavía no existe.
- Cifrado de extremo a extremo: `keyProvider` se acepta y se ignora con un aviso. En v1 no hay
  E2EE.

---

<!-- fuente: docs/developers/widgets-vue.md -->

# Los widgets de Vue

`@iaconsultinglabs/comms-vue` trae la reunión hecha (`MeetingRoom`) y cada una de sus piezas
suelta, para que montes tu pantalla con tu diseño. Todos son accesibles (teclado, lector de
pantalla, contraste), vienen en castellano, catalán, inglés y francés, y tienen tema claro,
oscuro y automático.

```ts
import { MeetingRoom } from '@iaconsultinglabs/comms-vue'
import '@iaconsultinglabs/comms-vue/style.css' // una vez, en tu app
```

Las props, eventos y slots de cada uno, con sus tipos, están en la
[referencia de componentes](../../packages/vue/docs/reference/components.md). Aquí va para qué
sirve cada uno y lo que más se usa.

## La reunión entera

| Widget | Para qué | Lo que más se usa |
|---|---|---|
| `MeetingRoom` | La reunión completa: escenario, botones, chat, personas, ajustes, avisos, grabación e IA. Igual para un miembro y para un invitado | `meeting` (o `apiUrl` + `tokenSource`), `meeting-title`, `locale`, `captions`, `ai-panel`, `recording-control`, `theme`. Eventos `left`, `state`, `admit`/`reject`. Slots `person-actions` y `connect-device` |
| `GuestLobby` | El vestíbulo antes de entrar: verse, elegir cámara, micro y altavoz, nombre, condiciones y «Pedir entrar» | `meeting-title`, `status` (lo cambia tu página), `consent`, `requires-approval`. Evento `request`: llama a tu backend con eso |
| `KnockCards` | «Fulano quiere entrar» con Admitir y Rechazar, para quien organiza | `knocks` (de tu backend). Eventos `admit`, `reject`, `admitAll` |

Sin Vue, los tres existen como custom elements: `<iacl-meeting>`, `<iacl-guest-lobby>` y
`<iacl-knock-cards>` (`@iaconsultinglabs/comms-vue/elements`), para cualquier web o framework.

## Las piezas, para tu propia pantalla

| Widget | Para qué | Lo que más se usa |
|---|---|---|
| `CallStage` | Quién se ve y cómo, como en Meet: cuadrícula, foco en quien habla, pantalla compartida grande | `participants` y `active-speaker` (de `useParticipants`), `screen-zoom` |
| `ParticipantTile` | Un recuadro: vídeo o cara, aro de «hablando», micro tachado, conexión perdida | `tile` (de `planStage`), `main`, `pinned`. Evento `select` |
| `MediaView` | El vídeo de una conexión, pidiendo solo la calidad que hace falta | `stream`, `identity`, `fit`, `mirror` |
| `SelfView` | Mi vídeo pequeño y flotante, arrastrable | `stream`, `label` |
| `ControlsBar` | Los botones: micro, cámara, pantalla, chat, personas, subtítulos, IA, grabar, salir | `captions`, `ai-panel`, `recording-control`, `unread`, `waiting`. Eventos `leave` y `panel` |
| `ChatPanel` | El chat de la reunión (no se guarda), con reintento si un mensaje falla | Va debajo de `useMeeting` |
| `ParticipantsPanel` | Las personas, con sus aparatos | Slots `actions` (tus acciones, que ejecuta tu backend) y `before` |
| `DeviceSettings` | Cámara, micro y altavoz de este aparato, y el desenfoque | Va debajo de `useMeeting` |
| `LevelMeter` | El nivel del micro en barras | `stream`, `active`, `label` |

## IA y grabación

| Widget | Para qué | Lo que más se usa |
|---|---|---|
| `AiIndicator` | «IA activa». Siempre a la vista para todos mientras la IA está encendida; no se puede ocultar | `ai` (de `useAi().ai`), `excluded` |
| `LiveCaptions` | Subtítulos en directo: cada persona los pone para sí | `max-lines`, `position` (`overlay` o `inline`), `force` |
| `AiLivePanel` | La ayuda privada en directo: sugerencias, respuestas con su fuente, datos del contexto, avisos, detecciones y las salidas de tu modo. **Nunca se pinta para un invitado** | `result-labels`. Slot `result` para pintar una salida a tu manera (con tu botón «Crear tarea») |
| `RecordingIndicator` | «Grabando». Siempre a la vista para todos mientras se graba | `recording` (de `useRecording`), `excluded` |

## Los composables

Si prefieres tus propios componentes, los composables dan cada parte de la reunión, reactiva:

| Composable | Da |
|---|---|
| `useMeeting(meeting)` | La reunión para todo lo de debajo, `join`, `leave` |
| `useConnectionState()` | `state`, `status`, `connected`, `reconnecting`, `quality` y `retry()` |
| `useParticipants()` | `participants`, `people`, `activeSpeaker`, `count` |
| `useLocalMedia()` | Mi micro, cámara y aparatos, y cómo cambiarlos |
| `useScreenShare()` | Compartir pantalla, y quién presenta |
| `useMeetingChat()` | Los mensajes y `send` |
| `useRecording()` | Si se graba y qué |
| `useAi()` | La IA de la reunión: estado, subtítulos, ayuda, detecciones y salidas del modo (sobre `meeting.ai`) |
| `useAiDisclosure()` | El aviso de IA para quien todavía no ha entrado |
| `useVideoView()` | Pedir solo la calidad de vídeo que pintas, en tus propios `<video>` |

Un ejemplo con piezas sueltas está en la [guía de integración](integracion-de-cero.md#32-tus-piezas-con-los-composables);
la reunión entera, en el [inicio rápido](quickstart.md).

## Textos, idioma y tema

- `locale`: `es`, `ca`, `en` o `fr`.
- `messages`: cambia cualquier texto por su clave (las claves están en `DEFAULT_MESSAGES`).
- `theme`: `auto`, `light` o `dark`. Los colores son variables CSS (`--iacl-*`): cámbialas
  para llevar tu marca.

---

<!-- fuente: docs/developers/ia-en-directo.md -->

# La IA en directo: ayuda durante la reunión

[ADR 0057](../adr/0057-ia-de-ayuda-en-directo-y-meeting-ai.md), sobre el
[ADR 0053](../adr/0053-ia-en-reuniones-contexto-modos-tiempo-real-y-cierre.md) y el catálogo de
modelos del [ADR 0055](../adr/0055-catalogo-de-modelos-iacl.md).

Mientras se habla, la IA de Comms escucha a quien puede oír, lee el chat público si se lo
pides, y manda **ayuda privada** a quien organiza:

| Tipo (`kind`) | Qué es | Ejemplo |
|---|---|---|
| `suggestion` | Qué decir o preguntar ahora | «Objeción de precio: pregunta con qué cifra contaban.» |
| `answer` | La respuesta a una pregunta que ha salido, **apoyada en tu contexto** (con `sources`) | «Según "Propuesta de septiembre": seis semanas desde la firma.» |
| `fact` | Un dato de tu contexto que viene al caso (con `sources`) | «Dato acordado: el importe cerrado es de 48.000 euros.» |
| `alert` | Un aviso | «Cuidado: esa promesa no está en lo acordado.» |

Además, **tus detectores** (en lenguaje natural) y **las salidas de tu modo** (el `result`
genérico) llegan como eventos con sus datos ya validados, para que montes tus flujos encima.

Tres reglas que no cambian:

1. **Si la IA falla o va lenta, la llamada sigue igual.** Lo sabrás por `ai.status`.
2. **Comms propone y nunca ejecuta.** Lo que hagas con cada ayuda es cosa tuya.
3. **La ayuda solo la ve quien tiene la IA activa**: nunca un invitado ni quien tiene
   `aiExcluded`. Los mensajes privados no se procesan nunca.

```bash
export COMMS_API="https://api.comms.iaconsultinglabs.com/v1"
export COMMS_API_KEY="iacl_test_EXAMPLE0000.not-a-real-secret"
export MEETING_ID="mtg_4kq9x2m7a1b3c5d7"
```

## 1. El contexto inicial

La IA entiende la reunión con lo que le das antes: de qué va, los objetivos, quién es quién y
documentos libres (un presupuesto, el acta anterior, la ficha del cliente). **Comms no supone
de dónde sale**: lo rellenas tú, con los datos de tu sistema.

Lo más cómodo es darlo al crear la reunión:

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const meeting = await comms.createMeeting({
  type: 'meeting',
  title: 'Visita comercial',
  settings: { ai: { enabled: true, realtime: true, profileId: 'aip_tpl_sales', inputs: ['audio', 'chat'] } },
  aiContext: {
    brief: 'Reforma de la tercera planta. Ya enviamos una propuesta en septiembre.',
    goals: ['Cerrar el alcance', 'Saber quién decide el presupuesto'],
    participants: [{ personId: 'gst_51b2', name: 'Joan Puig', role: 'cliente', organization: 'Construccions Puig' }],
    documents: [{ title: 'Propuesta de septiembre', text: 'El plazo de ejecución es de seis semanas desde la firma. El importe cerrado es de 48.000 euros.' }],
  },
})
console.log(meeting.id)
```

O después, antes de que entre nadie (`setMeetingAiContext`), o sirviéndolo desde tu sistema
para cada reunión (`setAiContextSource`, lo recomendado: Comms no lo guarda nunca).

- Solo en memoria y cifrado: nunca a disco, a la base de datos ni a los registros.
- Caduca, como mucho, a las 24 h; se borra al terminar el cierre.
- Como mucho 200 kB. **Nunca se devuelve**: `GET …/ai/context` solo dice de dónde sale.
- El contexto lo pone tu backend; el navegador de un invitado no puede tocarlo.

## 2. Qué procesa y cuándo

- **Con o sin IA, y qué entra**, por reunión: `settings.ai.enabled`, `realtime` y `inputs`
  (`audio`, `chat`). Sin `chat`, el chat no entra.
- **Por turno.** Cada vez que alguien termina de hablar (fin de frase del transcriptor o
  silencio), ese fragmento se procesa junto con tu contexto y lo dicho hasta ahora (una
  memoria condensada de la reunión). Un mensaje del chat público cuenta como un turno.
- **Sin gastar en balde.** No se manda audio en silencio ni fragmentos vacíos, y un turno muy
  corto («vale», «sí, claro») espera al siguiente y van juntos.
- **Gana lo último.** Nunca hay más de una evaluación a la vez por reunión, ni cola: lo que
  llega mientras tanto va entero a la siguiente. Una ayuda que llegaría tarde ya no se manda.
- **Topes:** por persona y por reunión (`cooldownSeconds`, `maxPerTenMinutes`,
  `maxPerMeeting`) y por minuto en toda la reunión (`maxPerMinute`, 2 por defecto).

## 3. El modo: ayuda, detectores y salidas

Lo que hace la IA lo dice el **modo** (`AiProfile`). La ayuda va en `live.suggestions`, y las
**salidas propias** del modo en `live.results`:

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const mode = await comms.createAiProfile({
  name: 'Visitas comerciales',
  instructions: 'Visitas a clientes de reformas: alcance, plazo y precio.',
  live: {
    detectionAudience: ['host'],
    suggestions: {
      enabled: true,
      audienceRoles: ['host'],
      triggers: ['question', 'context_fact', 'risk', 'objection'],
      maxPerMinute: 2,
    },
    results: [
      {
        id: 'fecha_entrega',
        description: 'El cliente da una fecha de entrega o un plazo.',
        outputSchema: { type: 'object', required: ['texto'], properties: { texto: { type: 'string', maxLength: 300 } } },
      },
    ],
  },
})
console.log(mode.id)
```

- **Disparadores** (`triggers`): `question` da una respuesta (`answer`), `context_fact` un dato
  (`fact`), `risk` un aviso (`alert`); `detection`, `objection`, `unanswered_question`,
  `missing_info` y `uncovered_topic`, una sugerencia. Sin documentos en el contexto, ni se
  pide responder ni dar datos.
- **Una respuesta o un dato siempre cita un documento de tu contexto que existe**, y si copia
  sus palabras se comprueba que están: el `excerpt` sale de tu documento, nunca del modelo.
- **Detectores en lenguaje natural** («avísame si el cliente menciona un plazo», «detecta
  compromisos de precio»): se crean con `createDetector` y su `outputSchema`, y salen como
  `detection.matched`.
- **Salidas del modo** (`results`): igual que un detector, pero propias del modo. Salen como
  `ai.result` con `{ profileId, outputId, data }`. Pasan las mismas barreras: umbral,
  evidencia que está en la transcripción, datos que validan contra su esquema, enfriamiento y
  tope.

## 4. Quién ve la ayuda

La ven las conexiones de la audiencia del modo (`audienceRoles`, `audiencePersonIds`,
`detectionAudience`) y las que tu backend marca con `aiAssist` al pedir el acceso. **Nunca un
invitado** (pedirlo para uno es `validation_failed`) **ni alguien con `aiExcluded`**.

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const grant = await comms.issueMemberToken('mtg_4kq9x2m7a1b3c5d7', {
  person: { id: 'usr_marta', name: 'Marta' },
  device: { key: 'dk_marta_portatil' },
  aiAssist: true, // la jefa de ventas también ve la ayuda
})
console.log(grant.aiAssist) // true: esta conexión ve el panel de ayuda
```

`TokenGrant.aiAssist` dice si esa conexión la ve; en el navegador, `meeting.ai.assist`.

## 5. Recibirla en el navegador

`meeting.ai` (`comms-core`) es la IA de la reunión en un solo sitio: el estado (de solo
lectura) y los eventos.

```ts
import { createMeeting } from '@iaconsultinglabs/comms-core'

const meeting = createMeeting({
  apiUrl: 'https://api.comms.iaconsultinglabs.com/v1',
  tokenSource: async () => (await fetch('/api/comms/token', { method: 'POST' })).json(),
})

meeting.ai.on('help', (help) => {
  // help.kind: 'suggestion' | 'answer' | 'fact' | 'alert'
  const where = help.sources.map((source) => source.title).join(', ')
  console.log(`[${help.kind}] ${help.text}${where ? ` (según ${where})` : ''}`)
})
meeting.ai.on('detection', (detection) => console.log(detection.detectorName, detection.data))
meeting.ai.onResult<{ texto: string }>('fecha_entrega', (result) => {
  console.log('Fecha de entrega:', result.data.texto, '·', result.evidence.excerpt)
})
meeting.ai.on('status', (ai) => console.log(ai.status, ai.assist))

await meeting.join()
```

| Evento de `meeting.ai.on` | Llega |
|---|---|
| `caption` | Un subtítulo, provisional o final |
| `detection` | Una detección en directo (nunca a un invitado) |
| `help` | Una ayuda privada (`kind`, `text`, `topic`, `sources`) |
| `result` | Una salida del modo (`profileId`, `outputId`, `data`, `evidence`) |
| `status` | Cambió el estado: aviso, procesador dentro, modelos, `assist` |
| `feedback` | Esta persona valoró una ayuda |
| `packet` | Cada paquete `iacl.ai*`, también los que esta versión aún no conoce |

`meeting.ai.help`, `detections` y `results` son las últimas que llegaron;
`meeting.ai.resultsOf<T>(outputId)`, las de una salida; `meeting.ai.sendFeedback(id, decision)`
mide la calidad. Los métodos y lo que escuchas son los mismos aunque el estado cambie.

## 6. El panel de ayuda en Vue

`MeetingRoom` con `ai-panel` ya lo trae. Suelto, `AiLivePanel` pinta los cuatro tipos (con el
tipo escrito, no solo en color), sus fuentes, las salidas del modo y las detecciones. **No se
pinta nunca para un invitado.**

```vue
<script setup lang="ts">
import { AiLivePanel, useAi } from '@iaconsultinglabs/comms-vue'

const ai = useAi()
const labels = { fecha_entrega: 'Fecha de entrega' }
</script>

<template>
  <AiLivePanel v-if="ai.assist.value" :result-labels="labels">
    <template #result="{ result }">
      <strong>{{ labels[result.outputId as keyof typeof labels] ?? result.outputId }}</strong>
      <span>{{ result.data['texto'] }}</span>
    </template>
  </AiLivePanel>
</template>
```

Para tu propio diseño, `useAi()` da `assist`, `help`, `results`, `detections`, `rateHelp` y
`dismissHelp`, reactivos.

## 7. En tu backend

Lo mismo llega por webhook, por el carril de IA en directo:

```ts
import { createServer } from 'node:http'
import { createWebhookHandler } from '@iaconsultinglabs/comms-server'

const webhooks = createWebhookHandler({
  secrets: process.env.COMMS_WEBHOOK_SECRET ?? '',
  handlers: {
    'assistant.suggestion': async (event) => {
      console.log(event.data.helpKind ?? 'suggestion', event.data.text, event.data.sources ?? [])
    },
    'ai.result': async (event) => {
      // TU APP: por ejemplo, apunta la fecha de entrega en la ficha del cliente.
      console.log(event.data.outputId, event.data.data, event.data.evidence.excerpt)
    },
    'detection.matched': async (event) => {
      console.log(event.data.detectorName, event.data.data)
    },
  },
})

createServer(webhooks.nodeListener()).listen(3001)
```

## 8. El consumo de una reunión

```bash
curl -sS "$COMMS_API/meetings/$MEETING_ID/ai/usage" -H "Authorization: Bearer $COMMS_API_KEY"
```

```ts
import { createCommsClient } from '@iaconsultinglabs/comms-server'

const comms = createCommsClient({ baseUrl: 'https://api.comms.iaconsultinglabs.com/v1', apiKey: process.env.COMMS_API_KEY ?? '' })

const usage = await comms.getMeetingAiUsage('mtg_4kq9x2m7a1b3c5d7')
console.log(usage.realtimeMinutes, usage.turns, usage.help, usage.results, usage.amountEur)
```

Minutos-persona en directo, turnos evaluados, ayudas, detecciones y salidas emitidas, cierres e
importe al precio congelado al empezar. Sin contenido. Lo mismo se suma al consumo del mes
(`getUsage`), a nombre de la clave que creó la reunión. Pide el permiso `usage:read`.

## 9. Probarlo sin gastar: la clave de prueba

Con una clave `iacl_test_…` la IA es **simulada**: `iacl-sandbox-live` e `iacl-sandbox-closing`,
deterministas, a precio 0 y sin mandar nada a ningún proveedor. Funciona también en un nodo de
producción sin ninguna clave de proveedor. El guion simulado dice, entre otras cosas, una
pregunta sobre el plazo de entrega y un «te lo garantizo»: con un documento en el contexto que
hable del plazo, salen una respuesta (`answer`) y un aviso (`alert`), y las salidas de tu modo
cuyo nombre coincide con lo dicho (`fecha_entrega` → «entrega»). El chat también entra.

---

<!-- fuente: docs/developers/ai.md -->

# La IA de la reunión

Contrato 0.2.0, [ADR 0053](../adr/0053-ia-en-reuniones-contexto-modos-tiempo-real-y-cierre.md).
**Mientras el nodo no tenga la IA encendida, todas estas rutas responden
`501 not_implemented`.** La forma ya es la definitiva: puedes programar contra ella.

**Qué hace un nodo con la IA encendida:** modos y plantillas, contexto (tu fuente o subido a
la reunión), cierres con resumen, comprobaciones y acciones propuestas, y `feedback` (fase A).
Si además tiene el directo (`realtime`): la transcripción en directo (fase B), los detectores
en directo (fase C) y las sugerencias privadas (fase D). Sin el directo en el nodo,
`updateMeetingAi` con `realtime: true` contesta `ai_not_enabled`.

## Las cuatro piezas

| Pieza | Qué es | Rutas |
|---|---|---|
| **Contexto** | Lo que aportas antes de la reunión: de qué va, objetivos, quién es quién y documentos | `/ai/context-source` (recomendado) o `/meetings/{id}/ai/context` |
| **Modos** | «¿Qué quieres que haga la IA?»: instrucciones, qué sale en directo y qué al terminar | `/ai-profiles`, y `settings.ai.profileId` en la reunión |
| **Directo** | Transcripción, detecciones y sugerencias privadas mientras se habla | `settings.ai.realtime`, `/detectors`, `PATCH /meetings/{id}/ai` |
| **Cierre** | Resumen, comprobaciones y acciones propuestas al terminar | `/meetings/{id}/ai/closings` |

Y cinco reglas que no cambian:

1. **Comms propone y nunca ejecuta.** Una acción llega como `action.proposed`; la aprueba y la
   ejecuta tu sistema, con los permisos de quien pulsa. Lo único que nos devuelves es la
   decisión (`/meetings/{id}/ai/feedback`), para medir la calidad.
2. **Si la IA falla, la llamada sigue.** Lo sabrás por `ai.status`.
3. **Los mensajes privados no se procesan nunca**, y nada de quien tiene `aiExcluded`.
4. **Todos ven que la IA está activa y qué hace** (`AiDisclosure.features`), invitados
   incluidos.
5. **El contexto no se guarda en el central.** Lo sirves tú, o vive solo en memoria con
   caducidad.
6. **La IA es de IACL.** Eliges un modelo de nuestro catálogo, con su precio. No puedes
   conectar otro proveedor ni traer tu propia clave.

```bash
export COMMS_API="https://api.comms.iaconsultinglabs.com/v1"
export COMMS_API_KEY="iacl_live_EXAMPLE0000.not-a-real-secret"
export MEETING_ID="mtg_4kq9x2m7a1b3c5d7"
```

## El modelo

[ADR 0055](../adr/0055-catalogo-de-modelos-iacl.md). La IA la procesa IACL, siempre en la UE.
Tú eliges **qué modelo** de nuestro catálogo y pagas **su precio**. Quién lo procesa por
debajo no forma parte del contrato.

```bash
curl -sS "$COMMS_API/ai/models"   -H "Authorization: Bearer $COMMS_API_KEY"
```

Cada modelo dice:

- qué parte cubre (`kind`): `live` para el directo y `closing` para el cierre;
- qué sabe hacer (`capabilities`) y en qué idiomas (`languages`; `ca-es` es catalán y
  castellano mezclados en la misma frase);
- cómo de rápido es (`latency`);
- cuánto cuesta (`price`): por minuto-persona en directo y por reunión al cierre;
- su estado (`status`): `available`, o `preview` si todavía puede cambiar.

Para no repetirlo en cada reunión, guarda los de tu cuenta. El campo que no mandes vuelve al
de IACL:

```bash
curl -sS -X PUT "$COMMS_API/ai/model-defaults"   -H "Authorization: Bearer $COMMS_API_KEY"   -H "Content-Type: application/json"   -d '{"liveModel":"iacl-live-precise"}'
```

```bash
curl -sS "$COMMS_API/ai/model-defaults"   -H "Authorization: Bearer $COMMS_API_KEY"
```

O elige el modelo en una reunión concreta, con `settings.ai.liveModel` y
`settings.ai.closingModel` al crearla, o con `updateMeetingAi` mientras no haya empezado:

```bash
curl -sS -X PATCH "$COMMS_API/meetings/$MEETING_ID/ai"   -H "Authorization: Bearer $COMMS_API_KEY"   -H "Content-Type: application/json"   -d '{"liveModel":"iacl-live-fast"}'
```

- **Al empezar la reunión, el modelo y su precio se congelan.** Si después cambia el
  catálogo, lo que cuesta una reunión en marcha no cambia, y cambiar el modelo con la reunión
  ya empezada es `conflict`.
- Un modelo que no está en el catálogo, o que no es de ese tipo, es `ai_model_unavailable`.
  `details.available` trae los que valen.
- El aviso de IA (`AiDisclosure`) dice qué modelo hace cada parte (`liveModel`,
  `closingModel`). Los subtítulos, las detecciones, las sugerencias y el cierre llevan
  también su `model`.
- Lo que gastas por modelo, con el importe al precio de cada reunión, está en
  `Usage.aiByModel`.

Con el SDK de servidor:

```ts
const { data: models } = await comms.listAiModels()
await comms.setAiModelDefaults({ liveModel: 'iacl-live-precise' })
```

## Contexto

### Lo recomendado: que lo sirva tu sistema (`setAiContextSource`)

Registras una URL tuya. Cuando la IA lo necesita, la API le hace un `POST` firmado como un
webhook (cabecera `IACL-Signature`, con el secreto de tu webhook) con
`{ meetingId, externalRef, contextRef, stage }`, y tú contestas `200` con el `AiContext` o
`204` si no hay. Antes de guardarla, la API prueba la URL (`stage: check`).

```bash
curl -sS -X PUT "$COMMS_API/ai/context-source" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/comms/ai-context","timeoutMs":5000}'
```

```bash
curl -sS "$COMMS_API/ai/context-source" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS -X DELETE "$COMMS_API/ai/context-source" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

`settings.ai.contextRef` es tu referencia opaca (el id de tu oportunidad, obra o candidato):
te llega de vuelta en esa petición.

Con el SDK de servidor no reimplementas la verificación: `createAiContextSourceHandler`
comprueba la firma (con tu secreto de webhook), contesta la petición de prueba y te pide
solo el contexto.

```ts
import { createAiContextSourceHandler } from '@iaconsultinglabs/comms-server'

const contextSource = createAiContextSourceHandler({
  secrets: () => process.env.COMMS_WEBHOOK_SECRET ?? '',
  // `null` = no hay contexto para esta reunión (204).
  resolve: async ({ contextRef }) => (contextRef ? buildContextFor(contextRef) : null),
})
app.post('/comms/ai-context', contextSource.nodeListener()) // sin body parser delante
```

### Sin backend: subirlo a la reunión (`setMeetingAiContext`)

Para n8n o pruebas. Solo en memoria, cifrado, nunca a disco ni a los registros, y caduca a
las 24 h como mucho. La respuesta nunca devuelve el contenido.

```bash
curl -sS -X PUT "$COMMS_API/meetings/$MEETING_ID/ai/context" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brief":"Visita para la reforma de la tercera planta.","goals":["Cerrar el alcance"],"participants":[{"name":"Joan Puig","role":"cliente"}]}'
```

```bash
curl -sS "$COMMS_API/meetings/$MEETING_ID/ai/context" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS -X DELETE "$COMMS_API/meetings/$MEETING_ID/ai/context" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## Modos

Tres plantillas de IACL de serie, de solo lectura: `aip_tpl_sales` (comercial),
`aip_tpl_project_followup` (seguimiento de proyecto u obra) y `aip_tpl_interview`
(entrevista). Úsalas tal cual o clónalas.

```bash
curl -sS "$COMMS_API/ai-profiles/templates" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS -X POST "$COMMS_API/ai-profiles" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: profile-visitas-1" \
  -d '{"name":"Visitas de reformas","fromTemplate":"aip_tpl_sales"}'
```

```bash
curl -sS "$COMMS_API/ai-profiles?limit=20" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS "$COMMS_API/ai-profiles/aip_6m8p0r2t4v6x8z1b" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

Cada cambio sube `version`; `live` y `closing` se sustituyen enteros. En las instrucciones
no pongas datos de personas: lo de una reunión concreta va en su contexto.

```bash
curl -sS -X PATCH "$COMMS_API/ai-profiles/aip_6m8p0r2t4v6x8z1b" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"closing":{"summary":{"enabled":true,"length":"short"},"actions":{"enabled":true,"types":[{"type":"task.create","name":"Crear tarea","description":"Alguien se compromete a hacer algo.","argumentsSchema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"}}}}]}}}'
```

```bash
curl -sS -X DELETE "$COMMS_API/ai-profiles/aip_6m8p0r2t4v6x8z1b" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## Detectores

En lenguaje natural, del tenant, de un modo o de una reunión, y en directo (`live`), al
cierre (`closing`, una «comprobación») o en los dos (`both`).

```bash
curl -sS -X POST "$COMMS_API/detectors" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Petición de presupuesto","description":"El cliente pide un presupuesto.","scope":{"type":"profile","profileId":"aip_6m8p0r2t4v6x8z1b"},"when":"live","minConfidence":0.8}'
```

```bash
curl -sS "$COMMS_API/detectors?profileId=aip_6m8p0r2t4v6x8z1b" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS "$COMMS_API/detectors/det_5n7p9r1t3v5x7z9b" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS -X PATCH "$COMMS_API/detectors/det_5n7p9r1t3v5x7z9b" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation":"persistence","cooldownSeconds":300}'
```

```bash
curl -sS -X DELETE "$COMMS_API/detectors/det_5n7p9r1t3v5x7z9b" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## La IA de una reunión en marcha

Encender el directo o cambiar de modo a mitad de reunión. Se avisa a todos en la sala.

```bash
curl -sS -X PATCH "$COMMS_API/meetings/$MEETING_ID/ai" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"realtime":true,"profileId":"aip_tpl_sales"}'
```

### La transcripción en directo

Con `realtime`, el procesador de IA entra en la reunión (oculto: no sale en la lista) y oye a
cada persona por separado, **menos a las de `aiExcluded`**, que nunca oye. Lo que sale:

- **`ai.status`**: `joined` al entrar; `failed` si no puede (`reason: capacity` si el nodo no
  tiene sitio, `plan_limit` si no cabe en tu plan) o si se cae, y `recovered` al volver;
  `left` al salir (`ended`, `disabled` o `plan_limit`). **La llamada sigue siempre.**
- **El aviso a la sala** (`iacl.ai`): `processorPresent` y `features` (`transcript` y, con
  subtítulos, `captions`). Enséñalo siempre que la IA esté dentro. Cada conexión lo recibe
  también al entrar, solo ella, si la IA está encendida o cambió desde su token: quien pide
  el acceso justo cuando entra el procesador ve el punto igual. Puede llegar repetido;
  `comms-core` aplica el último y no emite `ai` si no cambia nada.
- **`transcript.segment`** por webhook, solo los finales, con quién habla
  (`speakerParticipantId` y `personId`) y cuándo (`startMs`/`endMs` desde el inicio de la
  reunión). Con el modo `live.transcript: off`, ninguno.
- **Subtítulos** (modo `live.transcript: captions`): provisionales y finales a la sala por el
  tema `iacl.ai.transcript` (`AiCaptionPacket`). El mismo `segmentId` con `revision` mayor
  sustituye al anterior.
- **`transcript.ready`** con `origin: live` al terminar, con la transcripción entera en tu
  almacenamiento: con endpoint, `PUT {url}/{meetingId}/transcripts/{transcriptionId}.json|.md`
  (no hay grabación); con bucket, `<prefijo>/transcripts/<meetingId>/…`. Si el procesador se
  cayó a mitad, cada tramo es una transcripción distinta.
- **Uso**: `aiRealtimeMinutes` en minutos-persona (diez personas una hora, 600).

### En el navegador: comms-core y comms-vue

No hace falta leer el canal de datos a mano. `@iaconsultinglabs/comms-core` entrega lo
de la sala como eventos de la reunión, y `@iaconsultinglabs/comms-vue` lo pinta:

| Tema | comms-core | comms-vue |
|---|---|---|
| `iacl.ai` | `meeting.ai` (con `features`, `purpose` y `status`) y el evento `ai` | `AiIndicator` |
| `iacl.ai.transcript` | evento `aiCaption`, con la persona y sin revisiones viejas | `LiveCaptions` |
| `iacl.ai.detection` | evento `aiDetection` y `meeting.aiDetections` | `AiLivePanel` |
| `iacl.ai.suggestion` | evento `aiSuggestion` y `meeting.aiSuggestions` | `AiLivePanel` |
| cualquier `iacl.ai.*` | evento `aiPacket`: tipado si se conoce, en bruto si no | — |

Con la sala entera, basta con dos propiedades:

```vue
<MeetingRoom :meeting="meeting" captions ai-panel />
```

El motor solo acepta estos paquetes si vienen del servidor: uno publicado por un
participante se descarta. Tampoco entrega una detección a un invitado. Los ejemplos
están en los README de los dos paquetes.

Tu plan tiene que permitirlo (`ai.realtime`), con un tope de reuniones a la vez
(`ai.concurrentMeetings`) y, si lo tiene, de minutos al mes: al llegar, el procesador sale y
la llamada sigue.

### Las sugerencias privadas

Si el modo las pide (`live.suggestions.enabled`), la IA propone a quien dirige la reunión qué
decir o preguntar. **Solo lo propone: no hace nada.** Se disparan siempre por algo dicho, nunca
por tiempo (`live.suggestions.triggers`):

| Disparador | Cuándo |
|---|---|
| `detection` | Un detector en directo se cumple; la sugerencia cita su `matchId` |
| `objection` | Alguien pone una pega: «es muy caro», «no lo vemos claro» |
| `unanswered_question` | Una pregunta se queda sin contestar |
| `missing_info` | Falta un dato para avanzar: «no sé cuántos metros son» |
| `uncovered_topic` | Se acerca el cierre y un objetivo de tu contexto (`goals`) no se ha tratado |

```bash
curl -sS -X PATCH "$COMMS_API/ai-profiles/aip_6m8p0r2t4v6x8z1b" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"live":{"transcript":"final","suggestions":{"enabled":true,"audienceRoles":["host"],"audiencePersonIds":["usr_jefa_ventas"],"triggers":["detection","objection","unanswered_question"],"cooldownSeconds":60}}}'
```

- **A quién.** A las conexiones de `audienceRoles` (por defecto, solo el anfitrión) y de las
  personas de `audiencePersonIds`. **Nunca a un invitado** (papel o persona `guest`) salvo que la
  reunión tenga `settings.ai.suggestionsToGuests`.
- **Por dónde.** A la sala, por el tema `iacl.ai.suggestion` (`AiSuggestionPacket`) **solo a esas
  conexiones**: nadie más la recibe. A ti, `assistant.suggestion` por webhook, con las conexiones
  que la recibieron (`audienceParticipantIds`), el texto (≤ 280 caracteres), el `topic`, la
  `confidence`, la evidencia (siempre texto de la transcripción) y `latencyMs`.
- **Sin ruido.** Una sugerencia no sale si no supera `minConfidence`, si su evidencia no está en
  lo que se acaba de decir, si lo que propone ya se dijo después, si se parece a otra que ya
  salió, si quien la recibiría la recibió hace menos de `cooldownSeconds` (45 s), o al llegar a
  `maxPerTenMinutes` por persona o a `maxPerMeeting` en la reunión.
- **Privacidad.** Nada de quien tiene `aiExcluded` (ni cuenta como «ya dicho») y nunca el chat.
  El aviso de IA activa lo dice a todos: `features` lleva `suggestions`.
- **¿Sirvió?** Quien la recibió puede decirlo desde la sala
  (`POST /participant/ai/feedback`, [curl.md](curl.md)), y tú con `sendAiFeedback`
  (`kind: suggestion`, `useful` o `not_useful`, abajo).

## Cierre

Con `settings.ai.postMeeting` se pide solo en cuanto hay transcripción. A mano, para cerrar
ya o rehacerlo con otro modo:

```bash
curl -sS -X POST "$COMMS_API/meetings/$MEETING_ID/ai/closings" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: closing-redo-1" \
  -d '{"profileId":"aip_tpl_project_followup","outputs":["summary","checks"]}'
```

```bash
curl -sS "$COMMS_API/meetings/$MEETING_ID/ai/closings" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

```bash
curl -sS "$COMMS_API/meetings/$MEETING_ID/ai/closings/acl_8r0t2v4x6z8b1d3f" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

Llegan, por este orden: `summary.ready`, un `detection.matched` con `stage: closing` por
cada comprobación que se cumple, un `action.proposed` por acción y, al final,
`ai.closing.completed` (no llegan más de ese cierre).

**De dónde sale.** De la transcripción de la grabación. Si la reunión tiene grabación pero
aún no transcripción, el cierre la pide y espera (`queued`); sin grabación,
`ai_transcript_unavailable`. Con `settings.ai.postMeeting`, todo va solo al terminar:
grabación → transcripción → cierre.

**Dónde queda el resumen.** Como la grabación, en tu destino de almacenamiento:

- con `tenant_endpoint`, Comms te lo entrega firmado en
  `PUT {url}/{recordingId}/summaries/{closingId}.json` y `.md` (tipo `summary`). El
  receptor de referencia (`createRecordingIngestHandler`) ya los acepta; el `.json` es un
  `AiClosingDocument` (resumen, acciones propuestas y comprobaciones);
- con `s3`, en `<prefijo>/summaries/<meetingId>/<closingId>.json` y `.md`.

Los eventos salen cuando el documento ha llegado. Si la IA falla, la reunión y la
grabación no se enteran: recibes `ai.status` (`failed`, `component: closing`) y
`ai.closing.completed` con `status: failed`.

## Qué hiciste con cada propuesta

```bash
curl -sS -X POST "$COMMS_API/meetings/$MEETING_ID/ai/feedback" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"kind":"action","id":"act_2c4e6g8i0k2m4o6q","decision":"accepted"},{"kind":"detection","id":"dtm_9b1d3f5h7j9l1n3p","decision":"rejected","reason":"wrong"}]}'
```

Una sugerencia lleva `useful` o `not_useful`:

```bash
curl -sS -X POST "$COMMS_API/meetings/$MEETING_ID/ai/feedback" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"kind":"suggestion","id":"sug_3c5e7g9i1k3m5o7q","decision":"useful"}]}'
```

## Los eventos en directo

`transcript.segment` (solo los finales), `detection.matched` con `stage: live` y
`assistant.suggestion` van por un **carril propio por reunión**: en orden entre ellos y sin
esperar al resto de tus eventos, para llegar en unos 3 s. Llevan contenido y se borran de
nuestro registro en cuanto los acusas con un 2xx, como el chat: guárdalos en el mismo
manejador que contesta ([event-ordering.md](event-ordering.md)).

---

<!-- fuente: docs/developers/recording.md -->

# Grabar y transcribir

Desde el contrato 0.2.0, IACL Comms graba **el audio de cada persona por separado** (y, si
lo pides, su vídeo). Lo grabado es **tuyo**, y llega a ti de una de dos formas:

- **Sin bucket (lo recomendado, `tenant_endpoint`):** Comms graba en el disco de su nodo,
  **cifra** cada parte al cerrarla y te la **entrega** con un `PUT` firmado a un endpoint
  tuyo. En cuanto contestas que la tienes, Comms **borra su copia**. Si no contestas en
  72 h, la borra igual y te avisa (`delivery_expired`).
- **Con tu bucket S3 (`s3`):** Comms escribe directamente en tu bucket.

La transcripción se pide **después**, cuando quieras, y va al mismo sitio. IACL no se
queda ni con el audio ni con el texto: solo sabe que existe una grabación, su estado y
dónde dejó cada fichero.

Diseño: ADR 0051 (grabación), ADR 0052 (transcripción) y ADR 0054 (entrega sin bucket).

## 1. Recibir las grabaciones en tu backend (sin bucket)

### 1.1 Monta el receptor

Con el SDK de Node, `createRecordingIngestHandler` hace todo lo que hay que comprobar
(firma, reloj, longitud, sha256, idempotencia) y contesta lo que Comms necesita para borrar
su copia. Tú pones el almacén:

```js
import express from 'express'
import { createRecordingIngestHandler, createFileRecordingStore } from '@iaconsultinglabs/comms-server'

const ingest = createRecordingIngestHandler({
  // El deliverySecret (y, durante una rotación, también el anterior).
  secrets: () => [process.env.COMMS_DELIVERY_SECRET, process.env.COMMS_DELIVERY_SECRET_PREVIOUS].filter(Boolean),
  // Una carpeta propia, FUERA de cualquier directorio web. O tu almacén: { head, put, get }.
  store: createFileRecordingStore('/var/lib/mi-app/grabaciones'),
  onStored: (ref, info) => console.log('grabación recibida', ref, info.kind, info.sizeBytes),
})

// SIN express.json() ni ningún lector de cuerpo delante: el cuerpo es el fichero.
app.all('/api/v1/comms/recordings/ingest/*', ingest.nodeListener())
```

- **Sin sesión de usuario**: la autenticación es la firma.
- Si un proxy quita parte del camino antes de llegar a tu app (por ejemplo `/api`), pásala
  en `pathPrefix`: la firma cubre el camino que mandó Comms.
- Tu propio almacén implementa `head(ref)`, `put(ref, body, info)` y `get(ref)`. En `put`,
  `body` es un iterable que **lanza al final** si los bytes no casan con la longitud o el
  sha256 anunciados: escribe en un sitio temporal y haz visible el objeto solo si se ha
  consumido entero sin errores (`createFileRecordingStore` lo hace así).
- Para servir las grabaciones a tus usuarios, hazlo desde tu backend con tu autorización
  (y `Range` si quieres poder avanzar en el audio). El endpoint de entrega solo es para
  Comms.

### 1.2 Dale la URL a Comms

```bash
curl -sS -X PUT "$COMMS_API/storage-destination" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"tenant_endpoint","url":"https://admin.acme.example/api/v1/comms/recordings/ingest"}'
```

- La respuesta trae **`deliverySecret` una sola vez** (`dlsec_…`). Guárdalo en tu
  configuración. Es distinto del secreto del webhook.
- Comms comprueba la URL con un `HEAD {url}/iacl-check/check` firmado. La primera vez tu
  receptor aún no tiene el secreto y contesta 401: es lo esperado, y el destino queda con
  `verifiedAt: null`. Vuelve a hacer el `PUT` (no cambia el secreto) cuando lo hayas
  configurado y verás `verifiedAt` con fecha; si no, se pone solo con la primera entrega.
- Si la URL no responde (red, TLS, 5xx): `400 storage_destination_invalid`
  (`details.reason: unreachable`). Solo `https`, y nunca a una dirección privada.
- **Rotar el secreto:** `POST /storage-destination/rotate-secret`
  (`comms.rotateStorageDestinationSecret()`). Devuelve el nuevo una vez; durante 24 h
  Comms firma con los dos, para que cambies el tuyo sin perder entregas.

Con el SDK: `comms.setStorageDestination({ type: 'tenant_endpoint', url })`.

### 1.3 El protocolo (si no usas el SDK)

```http
PUT {url}/{recordingId}/{partId}
Content-Type: audio/ogg | video/webm | video/mp4 | application/json
Content-Length: <bytes>
IACL-Content-SHA256: <sha256 en hex del cuerpo>
IACL-Recording-Id: rec_…
IACL-Part-Id: audio-1
IACL-Person-Id: usr_ana              (solo en las partes de una persona)
IACL-Part-Kind: audio | video | mixed | manifest | transcript
IACL-Signature: t=<unix>,v1=<hex>[,v1=<hex>]
```

- **Firma:** `v1 = HMAC-SHA256(deliverySecret, "<t>.<MÉTODO>.<path>.<sha256>")`, en hex.
  `<path>` es el camino de la URL **sin query**, tal cual llega (tu base incluida:
  `/api/v1/comms/recordings/ingest/rec_…/audio-1`). En `GET` y `HEAD`, el sha256 va vacío:
  `"<t>.GET.<path>."`. Rechaza si el reloj difiere más de 300 s. Durante una rotación
  llegan dos `v1=`: vale si casa una.
- **`{partId}`:** `audio-<n>`, `video-<n>`, `mixed` (la mezcla de la reunión, solo si
  pediste `mixed_audio`; hace falta la versión del SDK que la acepta) y `manifest`. Las
  transcripciones van a
  `{url}/{recordingId}/transcripts/{transcriptionId}.json` y `.md`.
- **Qué contestar a un `PUT`:**
  - `201 {"stored":true,"sha256":"…"}` cuando lo has guardado;
  - `200` con lo mismo si ya tenías esa parte con el mismo sha256 (sin guardarla dos veces);
  - `409` si ya tienes esa parte con **otro** sha256;
  - `401` si la firma no vale. Compruébala ANTES de mirar si la parte existe.

  Comms **solo borra su copia** con un 2xx, `stored: true` y el mismo sha256. Cualquier
  otra cosa la reintenta con espera creciente (de 10 s a 1 h) durante 72 h.
- **`GET` y `HEAD`:** para transcribir, Comms lee cada parte con un `GET` firmado (`200`
  con el fichero, `Content-Type` y `Content-Length`; `404` si no está).
- **Orden:** con `mixed_audio`, la mezcla (`mixed`) llega cuando todas las partes están
  grabadas, minutos después de parar. El manifiesto (`manifest`, JSON) llega el **último**,
  cuando todo se ha entregado o se ha perdido; dice qué hay, de quién, sus desfases y
  duraciones, quién no se grabó y, en `mixed`, la mezcla.
- Vectores firmados para probar tu verificación: `packages/server/test/recordings.test.ts`
  (`VECTORS`).

### 1.4 Qué guarda Comms mientras tanto

- La parte que se está grabando, en el disco del nodo. En cuanto se cierra, la **cifra**
  (AES-256-GCM, con una clave por tenant) y borra el claro.
- La copia cifrada, solo hasta que la confirmas, y **como mucho 72 h**. Después la borra
  igual: la grabación sale `partial` o `failed` con `reason: delivery_expired`.
- Si el disco temporal del nodo se llena, no se admiten grabaciones **nuevas**
  (`403 recording_not_allowed`, `details.reason: staging_full`). Las llamadas siguen, y
  las grabaciones en curso también.

## 2. O dale tu bucket S3

Vale cualquier S3 compatible: AWS, Hetzner Object Storage (fsn1/nbg1, en la UE), Scaleway,
OVH, o un MinIO/RustFS propio. Crea un bucket y una credencial que **solo** pueda escribir
(y leer, si vas a transcribir) bajo un prefijo. Sin `List` ni `Delete`.

Política de ejemplo (AWS IAM; en Hetzner, MinIO y RustFS se escribe igual):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload"],
      "Resource": "arn:aws:s3:::acme-comms/iacl-comms/*"
    }
  ]
}
```

- `PutObject`: para grabar y para dejar la transcripción y el manifiesto.
- `GetObject`: solo si vas a transcribir. El proveedor lee cada parte con una URL firmada de
  15 minutos que genera la API con esta credencial.
- La retención es tuya: pon una regla de ciclo de vida en el bucket (por ejemplo, borrar a
  los 90 días).

```bash
curl -sS -X PUT "$COMMS_API/storage-destination" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"s3","endpoint":"https://fsn1.your-objectstorage.com","region":"fsn1","bucket":"acme-comms","prefix":"iacl-comms","forcePathStyle":true,"accessKeyId":"AKEXAMPLE0123456789","secretAccessKey":"example-secret-not-real-0123456789"}'
```

La API sube `iacl-comms/.iacl-comms-check` antes de guardar nada. Si no puede:
`400 storage_destination_invalid` con `details.reason`:

| `reason` | Qué pasa |
|---|---|
| `access_denied` | La credencial no puede escribir bajo el prefijo |
| `no_such_bucket` | El bucket no existe |
| `invalid_endpoint` | No es `https`, apunta a una red privada, o la región no casa con el bucket |
| `unreachable` | No se llega al servicio |

El secreto se guarda cifrado y **no se devuelve nunca**: `getStorageDestination` da
`accessKeyIdHint` (los 4 últimos caracteres). Para rotar la credencial, vuelve a hacer el
`PUT`.

Cambiar de un tipo de destino a otro, o quitarlo, con partes aún por entregar:
`409 conflict`.

## 3. Graba

Tu plan tiene que incluir la grabación (`Plan.recording`, lo fija IACL). Tres formas de
empezar:

- **Tu backend:** `POST /meetings/{id}/recordings` (`comms.startRecording(meetingId)`).
- **El anfitrión desde la sala:** si la reunión tiene `settings.recording.hostControl: true`,
  `@iaconsultinglabs/comms-vue` le enseña el botón «Grabar» (por debajo,
  `POST /participant/recording`).
- **Sola:** con `settings.recording.mode: auto`, empieza al entrar la primera conexión.

Y para parar: `POST …/recordings/{recordingId}/stop`, el botón del anfitrión, o al terminar
la reunión.

### Audio y vídeo

- **Por defecto, solo audio** (`audio_per_participant`): un `.ogg` (Opus) por persona y
  micrófono.
- **Vídeo, solo si lo pides** (`kinds: ["audio_per_participant", "video_per_participant"]`,
  al empezar o en `settings.recording.kinds`, y si el plan lo incluye): un fichero por
  persona y pista de vídeo (cámara o pantalla), **tal cual llega**, sin recodificar ni
  componer: `.webm` (VP8/VP9) o `.mp4` si el navegador publica H.264. Ocupa mucho más que
  el audio (≈ 0,5–1 GB por pista y hora).
- **La reunión en un solo audio** (`mixed_audio`, si el plan lo incluye): pídelo **junto** a
  `audio_per_participant` (`kinds: ["audio_per_participant", "mixed_audio"]`; sola,
  `400 validation_failed`). Al parar, Comms mezcla las partes de audio de todos, cada una
  en su momento (quien entra tarde suena cuando habló; los silencios del micrófono quedan
  como silencio), en **un `.ogg` Opus mono a ≈ 48 kbps** (≈ 21 MB por hora). Es lo que se
  escucha o se descarga; las partes por persona te siguen llegando y son las que usa la
  transcripción. Se hace al terminar, sin coste para la llamada. Si la mezcla falla, las
  partes llegan igual y su `recording.ready` sale `failed`.
- El vídeo compuesto (`video`) llega más adelante (`not_implemented`).

### Quién se graba

- Todo el que esté dentro y publique, también quien entre mientras se graba.
- **No** quien tenga `recordingExcluded`. Si al emitir su acceso no lo das, hereda
  `aiExcluded`: quien no consiente la IA tampoco se graba. Con `recordingExcluded: false` y
  `aiExcluded: true`, se graba pero su audio nunca va al transcriptor (ni Comms lo pide).
- La exclusión se aplica al grabar: no se empieza su parte, no se recorta después. Consta en
  `excludedParticipants`.
- Todos ven «Grabando» mientras dura: `Meeting.recording`, `TokenGrant.recording` y un aviso a
  la sala (`iacl.recording`) que `comms-core` expone como `meeting.recording`.

### Qué te llega

Con `tenant_endpoint`, las partes (`audio-1`, `video-2`…), la mezcla (`mixed`, si la
pediste) y, el último, `manifest`. Con `s3`:

```
<prefijo>/recordings/<meetingId>/<recordingId>/
  audio/<personId>/<identity>-<n>.ogg     una parte por persona y micrófono (Opus)
  video/<personId>/<identity>-<n>.webm    una por persona y pista de vídeo (si lo pediste)
  mixed.ogg                               la reunión en un solo audio (si pediste mixed_audio)
  manifest.json                           partes, desfases, duraciones y excluidos
<prefijo>/transcripts/<meetingId>/<transcriptionId>.json   segmentos por persona
<prefijo>/transcripts/<meetingId>/<transcriptionId>.md     legible
```

Si alguien sale y vuelve, su audio nuevo es otra parte con su `offsetMs`.

### Los eventos

| Evento | Cuándo |
|---|---|
| `recording.started` | Empieza a grabar (`startedBy.by`: `api`, `host` o `auto`) |
| `recording.stopped` | Deja de grabar (`reason`: `requested`, `meeting_ended`, `max_duration`, `plan_limit`…). Las partes aún se están subiendo o entregando |
| `recording.ready` | Todas las partes están en tu almacenamiento (o se han perdido). Uno por tipo (`kind`); el de `mixed_audio` lleva una sola parte, con `personId` e `identity` a `null` y `offsetMs: 0`. `parts[]` con `delivered`, `location` (`tenant:{recordingId}/{partId}` o `s3://bucket/clave`), `offsetMs`, `durationMs`, `contentType`, `sizeBytes` y, con `tenant_endpoint`, `partId` y `sha256`. Con `status: partial`/`failed`, `reason` (`delivery_expired`, `recording_failed`) |
| `transcript.ready` | La transcripción está en tu almacenamiento (`location`, `textLocation`), o falló (`status: failed`) |

## 4. Pide la transcripción

Cuando la grabación está `ready`:

```bash
curl -sS -X POST "$COMMS_API/meetings/$MEETING_ID/recordings/rec_7k2m9q4x1b3c5d7f8g9h/transcriptions" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"ca"}'
```

- Responde `202` con la transcripción en `queued`. Consulta su estado con
  `getTranscription`, o espera a `transcript.ready`.
- Cada persona se transcribe por separado (Azure Speech en `francecentral`, en la UE) y se
  intercalan por tiempo. Quién habla lo dice la parte, sin adivinar voces.
- **Con `tenant_endpoint`**, Comms te **pide** cada parte de audio con un `GET` firmado y la
  pasa en flujo al proveedor, sin guardarla; las de quien tiene `aiExcluded` no se piden
  nunca. Después te entrega el `.json` y el `.md` por `PUT` y, cuando los tienes, sale
  `transcript.ready`. El proveedor admite partes de **menos de 5 h y de 500 MB** subidas
  así; una más larga no se pide y consta en `failedParticipants` (si son todas, `failed`
  con el motivo en `error`).
- `language` fuerza un idioma (es, ca, en o fr). Sin él, los de `settings.ai.languages` de la
  reunión: con varios, se detecta por persona.
- Si una persona falla, sale igual (`status: partial`, `failedParticipants`). Si falla todo,
  se reintenta y, al final, `status: failed`.
- Cuenta para `Usage.aiPostMeetingMinutes` (el audio procesado).
- Con `settings.ai.enabled` y `settings.ai.postMeeting`, se pide sola al quedar lista la
  grabación.

## Errores propios

| Código | Cuándo |
|---|---|
| `storage_destination_missing` (409) | Grabar o transcribir sin destino configurado |
| `storage_destination_invalid` (400) | El bucket no acepta el objeto de prueba, o el endpoint no responde |
| `recording_active` (409) | Ya se graba en esa reunión (`details.recordingId`) |
| `recording_not_active` (409) | Parar algo que ya no graba |
| `recording_not_allowed` (403) | El anfitrión sin `hostControl`, quien no es anfitrión, o `details.reason: staging_full` (el disco temporal del nodo está lleno; prueba más tarde) |
| `recording_not_ready` (409) | Transcribir una grabación que aún no está en tu almacenamiento |
| `plan_limit_reached` (422) | El plan no graba ese tipo (`details.limit: recording`) o se acabaron sus minutos del mes |
| `conflict` (409) | Quitar o cambiar de tipo el destino con partes aún por entregar; rotar el secreto de un destino `s3` |
| `validation_failed` (400) | `mixed_audio` sin `audio_per_participant` (`details.fields[0].code: requires_audio_per_participant`) |
| `not_implemented` (501) | El nodo no tiene la grabación o la transcripción activadas, no mezcla audio (`mixed_audio`), o `video` (llega más adelante) |

---

<!-- fuente: docs/developers/webhooks.md -->

# Recibir y verificar los webhooks

Cada evento llega a tu webhook como un `POST` con el evento en JSON, firmado. Antes de creerte
nada, comprueba la firma. Con Node, `@iaconsultinglabs/comms-server` lo hace por ti
([node.md](node.md#webhooks-y-reconciliación)); en otro lenguaje, copia el ejemplo que toque.

## Lo que llega

```http
POST /hooks/comms HTTP/1.1
Content-Type: application/json
IACL-Signature: t=1790000000,v1=90434e36b1effa2b6ee1250c54b6121cbf8f6af0f2253e6480615154ab24a92a
IACL-Event-Id: evt_01j9z3k4m5n6p7r0
IACL-Event-Type: meeting.ended
IACL-Delivery-Attempt: 1

{"id":"evt_01j9z3k4m5n6p7r0","type":"meeting.ended","version":1,"tenantId":"ten_9x2kq4m7a1b3c5d7","occurredAt":"2026-10-02T09:47:30Z","data":{…}}
```

- **`IACL-Signature`**: `t=<segundos unix>,v1=<hex>`. Durante la rotación de un secreto (24 h)
  llegan dos `v1=`: vale si coincide uno.
- **`IACL-Event-Id`** e **`IACL-Event-Type`**: lo mismo que `id` y `type` del cuerpo, para
  enrutar sin parsear. Lo que manda es el cuerpo firmado: las cabeceras no van firmadas.
- **`IACL-Delivery-Attempt`**: 1 la primera vez; sube con cada reintento.
- El sobre es siempre `{ id, type, version, tenantId, occurredAt, data }`. Cada tipo y sus
  campos: [events.md](../events.md).

## El algoritmo

1. Lee el **cuerpo crudo**, los bytes tal como llegaron. Si tu framework ya lo ha convertido
   en un objeto, la firma no se puede comprobar: volver a serializarlo no da los mismos bytes.
2. De `IACL-Signature`, saca `t` (10 cifras) y cada `v1` (64 caracteres hexadecimales en
   minúscula). Ignora otros esquemas (`v2=`…) que pueda traer una versión futura.
3. Con cada secreto vigente (el actual y, durante una rotación, el anterior), calcula
   `HMAC-SHA256(secreto, "<t>.<cuerpo crudo>")` en hexadecimal minúscula. El secreto se usa
   tal cual, como texto UTF-8 (incluido el prefijo `whsec_`).
4. Compara con cada `v1` **en tiempo constante**. Vale si coincide alguno.
5. Rechaza si `|ahora − t| > 300` segundos, en los dos sentidos (anti-replay).
6. Solo entonces parsea el JSON. Deduplica por `id`. Si no conoces el `type` o la `version`,
   contesta 2xx y descártalo.

Con una firma mala contesta `401`. Con una buena, contesta `2xx` **en menos de 10 s**: guarda
el evento y procésalo después. Cualquier otra respuesta (o ninguna) cuenta como fallo y se
reintenta.

## Los ejemplos

Cada uno es una función sin dependencias, con el uso típico comentado al final. Todos dan el
resultado esperado en cada caso del [vector de prueba](examples/webhooks/test-vector.json),
que está firmado con el SDK. Los de **Node y Python** los comprueba un test en cada CI
(`packages/server/test/developer-docs.test.ts`); los de PHP, Go y C# se comprobaron con el
mismo vector a mano (PHP 8.3, Go 1.22 y .NET 8).

| Lenguaje | Fichero | Función |
|---|---|---|
| Node (sin SDK) | [verify.mjs](examples/webhooks/verify.mjs) | `verifyIaclSignature(rawBody, header, secrets, { now })` |
| Python 3.8+ | [verify.py](examples/webhooks/verify.py) | `verify_iacl_signature(raw_body, header, secrets, tolerance=300, now=None)` |
| PHP 7.4+ | [verify.php](examples/webhooks/verify.php) | `iacl_verify_signature($rawBody, $header, $secrets, $tolerance = 300, $now = null)` |
| Go | [verify.go](examples/webhooks/verify.go) | `iaclwebhook.Verify(rawBody, header, secrets, iaclwebhook.Tolerance, time.Now())` |
| C# (.NET 6+) | [IaclWebhook.cs](examples/webhooks/IaclWebhook.cs) | `IaclWebhook.Verify(rawBody, header, secrets)` |

Python, por ejemplo:

```python
import hashlib, hmac, re, time

def verify_iacl_signature(raw_body: bytes, header, secrets, tolerance=300, now=None) -> bool:
    if not header:
        return False
    timestamp, candidates = None, []
    for part in header.split(","):
        key, sep, value = part.partition("=")
        if not sep:
            return False
        if key == "t":
            if timestamp is not None or not re.match(r"^\d{10}$", value):
                return False
            timestamp = value
        elif key == "v1":
            if not re.match(r"^[0-9a-f]{64}$", value):
                return False
            candidates.append(value)
    if timestamp is None or not candidates:
        return False
    signed = timestamp.encode("ascii") + b"." + raw_body
    matched = False
    for secret in secrets:
        if not secret:
            continue
        expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
        for candidate in candidates:
            if hmac.compare_digest(expected, candidate):
                matched = True
    return matched and abs((time.time() if now is None else now) - int(timestamp)) <= tolerance
```

### Para probar el tuyo

El vector trae un cuerpo, dos secretos de ejemplo y diez casos (válido, durante una rotación,
secreto equivocado, cuerpo cambiado, demasiado viejo, del futuro, sin `v1`, hexadecimal en
mayúsculas, esquema desconocido…). Para cada caso, verifica `body` (o el `body` del caso, si
lo trae) con su `header` y sus `secrets`, usando `now` como reloj, y compara con `valid`.

## Dónde se suele romper

- **El cuerpo ya parseado.** Express con `express.json()` delante, Django REST Framework,
  Spring con `@RequestBody`… Pide los bytes: `express.raw()`, `request.get_data()`,
  `request.body` en Django, `file_get_contents('php://input')`, `io.ReadAll(r.Body)`.
- **Un proxy que reescribe el cuerpo** (compresión, normalización de JSON, otro juego de
  caracteres). Que la ruta del webhook pase sin tocar.
- **El reloj del servidor.** Con NTP apagado, la ventana de 300 s rechaza firmas buenas.
- **Solo un secreto.** Durante la rotación, acepta el actual y el anterior; si no, pierdes
  las entregas firmadas con el que todavía no has desplegado.
- **Trabajo largo dentro de la petición.** Pasados 10 s cuenta como fallo y se reintenta.
  Guarda y contesta; procesa después.

## Rotar el secreto sin perder eventos

1. `POST /webhook-endpoint/rotate-secret` devuelve el secreto nuevo (una vez).
2. Durante 24 h, cada entrega lleva dos `v1=`: el del nuevo y el del viejo.
3. Despliega el nuevo como `COMMS_WEBHOOK_SECRET` y deja el viejo como
   `COMMS_WEBHOOK_SECRET_PREVIOUS`.
4. Pasadas las 24 h, quita el viejo.

## Lo que no hace el webhook

- No garantiza el orden ni la entrega exacta una vez: [event-ordering.md](event-ordering.md).
- No es la única vía: lo que se pierda se recupera por cursor durante 72 h
  (`GET /events`, [curl.md](curl.md#reconciliar-por-cursor-listevents)).

---

<!-- fuente: docs/developers/event-ordering.md -->

# El orden de los eventos y lo que se garantiza

## Las dos vías

| | Webhook | Cursor (`GET /events`) |
|---|---|---|
| Cómo | IACL te hace un `POST` firmado por evento | Tú pides lo que falta desde tu último cursor |
| Cuándo | En cuanto pasa (segundos) | Cuando tú quieras (al arrancar y cada pocos minutos) |
| Orden | **No garantizado** (abajo) | **Sí**: el orden en que se emitieron |
| Cuánto tiempo | Reintentos durante 72 h | Ventana de 72 h |
| Entrega | Al menos una vez | Al menos una vez |

Usa las dos: el webhook para enterarte rápido y el cursor como red de seguridad. Comparte la
deduplicación entre ambas, para que un evento que llegue por los dos caminos se procese una
vez.

## El orden del webhook

Las entregas de un tenant se intentan en el orden en que se emitieron, en cada pasada. Pero si
una falla (tu servidor contestó 500, tardó más de 10 s o no estaba), **la siguiente no espera**:
se entrega, y la que falló se reintenta más tarde (10 s, 30 s, 1 min, 5 min, 15 min, 30 min y
después cada hora, hasta 72 h). Así que puede llegarte `participant.left` antes que su
`participant.joined`, o `meeting.ended` antes que el último `participant.left`.

El contrato 0.1.0 no garantiza el orden del webhook. Está propuesto garantizarlo por tenant
(OPS-3 en [la propuesta de la 0.2.0](../contract-0.2.0-proposal.md)); hasta que el contrato lo
diga, no dependas de él.

Cómo vivir con ello:

- **No dependas del orden de llegada.** Cada evento trae `occurredAt` y lo necesario para
  aplicarse solo (`meetingId`, `identity`, `personId`…).
- **Aplica con condiciones, no con secuencias.** Un `participant.left` de una conexión que no
  conoces aún se guarda igual; un `participant.joined` con `occurredAt` anterior a un `left` que
  ya tienes no la vuelve a meter.
- **Para el estado actual, pregunta.** `GET /meetings/{id}` dice quién está dentro ahora, y
  `meeting.ended` es definitivo: una reunión terminada no se reabre.
- **Si necesitas el orden estricto**, procesa desde el cursor (`reconcile` en el SDK), que sí
  va en orden, y usa el webhook solo como aviso de que hay algo nuevo.

## El carril de IA en directo

`transcript.segment`, `detection.matched` con `stage: live` y `assistant.suggestion` (contrato
0.2.0) van en **su propia cola por reunión**: en orden entre ellos, sin esperar a la cola del
resto de eventos de tu tenant y sin hacerla esperar. Así llegan en unos 3 s aunque tu
endpoint vaya lento con otros eventos. Por cursor siguen saliendo en el orden global.

- Por webhook, `transcript.segment` solo sale con `isFinal: true`.
- No mezcles su orden con el del resto: un `detection.matched` puede llegar antes que un
  `participant.joined` emitido antes.
- Llevan contenido (lo dicho, lo propuesto) y, como el chat, **se borran en cuanto los acusas**
  (abajo).

## Al menos una vez

El mismo evento puede llegar más de una vez: un reintento tras una respuesta tuya que se
perdió, o el mismo evento por el webhook y por el cursor. El `id` (`evt_…`) es el mismo en
todas. Deduplica por `id` **después** de procesar con éxito (si fallas, la repetición tiene
que procesarse) y, con varios procesos, haz el efecto idempotente por sí mismo: una clave única
derivada del `id` en la misma transacción.

## Lo que no conoces

- **Un tipo o una versión que no conoces:** contesta 2xx y descártalo. Si contestas con error,
  se reintenta 72 h para nada.
- **Un campo que no conoces:** ignóralo. Añadir un campo opcional a un evento es un cambio
  MINOR y puede llegar sin cambiar `version`. No valides en estricto lo que recibes.

## El chat (`message.sent`) y los eventos de IA con contenido son especiales

Llevan contenido: el texto del mensaje, o lo dicho y lo propuesto en `transcript.segment`,
`detection.matched`, `assistant.suggestion`, `action.proposed` y el `abstract` de
`summary.ready` (en `docs/events.md`, la columna «Lleva contenido»). Por eso:

- en la cola de IACL espera **cifrado**, y **se borra en cuanto tu webhook lo acusa** con un
  2xx;
- si no lo acusas, se puede leer por cursor hasta las 72 h, y después se borra;
- leerlo por cursor **no** cuenta como acuse: si tienes webhook y cursor, puede llegarte por
  los dos, o solo por uno.

Consecuencia: si quieres un historial del chat, **guárdalo dentro del mismo manejador que
contesta 2xx al webhook**. Si contestas 2xx y luego fallas al guardar, el texto se ha perdido
para siempre: IACL ya lo borró. Si fallas, contesta 500 y se reintentará.

## Tras más de 72 h sin reconciliar

El cursor responde `410 cursor_expired`: hay eventos que ya no existen. Reconstruye tu estado
desde las reuniones (`listMeetings` filtrando por `status` o `externalRef`, y `getMeeting`) y
vuelve a empezar el cursor. Los textos de chat de ese periodo que no acusaste se han perdido.
`reconcile` del SDK lo hace sin perder lo que pase durante la reconstrucción
(`onCursorExpired`).

---

<!-- fuente: docs/developers/errors-and-retries.md -->

# Errores, reintentos e idempotencia

## La forma de un error

Toda respuesta de error de la API tiene la misma forma:

```json
{
  "error": {
    "code": "plan_limit_reached",
    "message": "concurrentParticipants: 25 of 25 in use",
    "requestId": "req_01J9Z3",
    "details": { "limit": "concurrentParticipants" }
  }
}
```

- **Decide por `code`, nunca por `message`.** `code` es una lista cerrada de 27 valores que no
  cambian de significado dentro de la v1 ([errors.md](../errors.md)). `message` es para
  personas y puede cambiar.
- **`requestId`** (también en la cabecera `X-Request-Id` de cada respuesta) es lo que hay que
  dar a soporte. Regístralo en tus logs.
- **`details`** depende del código: `fields` en `validation_failed`, `limit` en
  `plan_limit_reached`, `presenter` y `canTakeOver` en `screen_share_busy`.
- Puede aparecer un código nuevo en una versión MINOR. Trata uno desconocido por su estado
  HTTP (4xx: no repitas igual; 5xx: reintenta).
- «No existe» y «es de otro tenant» son lo mismo: `404 not_found`, a propósito.

## Qué hacer con cada uno

| Código | HTTP | ¿Reintentar? | Qué hacer |
|---|---|---|---|
| `rate_limited` | 429 | Sí, tras `Retry-After` | Espera los segundos que diga la cabecera. Si el 429 llega del proxy sin cuerpo JSON ni `Retry-After`, espera con retroceso exponencial |
| `unavailable` | 503 | Sí, con retroceso | Algo nuestro está caído o en mantenimiento |
| `internal_error` | 500 | Sí, con retroceso, pocas veces | Fallo nuestro; si se repite, a soporte con el `requestId` |
| (sin respuesta: red o tiempo agotado) | — | Solo si la operación es repetible (abajo) | No sabes si se hizo: repite solo lo idempotente |
| `unauthorized` | 401 | No | Clave revocada o mal configurada; en `/participant/*`, token caducado o de otra reunión: pide otro a tu backend |
| `forbidden` | 403 | No | La credencial no permite esa acción |
| `tenant_suspended` | 403 | No | El tenant está suspendido: habla con IACL |
| `validation_failed` | 400 | No | Corrige la petición; `details.fields` dice qué |
| `idempotency_conflict` | 409 | No | Has reutilizado una `Idempotency-Key` con otro cuerpo |
| `plan_limit_reached` | 422 | Más tarde | No cabe en el plan ahora (`details.limit`). Dilo en la interfaz |
| `meeting_ended` | 409 | No | Las reuniones no se reabren: crea otra |
| `conflict`, `meeting_not_call`, `host_target_invalid` | 409 | No | El estado no lo permite; vuelve a leer la reunión |
| `guests_not_allowed`, `person_blocked`, `role_not_allowed`, `device_limit_reached` | 4xx | No | Decisión de la reunión o del contrato; dilo en la interfaz |
| `screen_share_busy` | 409 | Con `takeover: true` si `canTakeOver` | Otra conexión presenta |
| `cursor_expired` | 410 | No | El cursor tiene más de 72 h: reconstruye con `listMeetings`/`getMeeting` |
| `not_implemented` | 501 | No | Ruta reservada (detectores) |

## Qué se puede repetir sin riesgo

| Operación | ¿Repetible? | Por qué |
|---|---|---|
| Todos los `GET` | Sí | No cambian nada |
| `PUT /webhook-endpoint` | Sí | Deja el mismo estado |
| `POST /meetings` **con** `Idempotency-Key` | Sí | La misma clave y el mismo cuerpo devuelven la misma reunión durante 24 h |
| `POST /meetings` sin clave | **No** | Repetirla crea otra reunión |
| `POST /meetings/{id}/end` | En la práctica sí | Terminar una reunión ya terminada la devuelve tal cual |
| `DELETE /participant/screen-share` | Sí | Idempotente |
| `POST /participant/chat-messages` con `clientId` | Sí, con el mismo token | El mismo `clientId` no duplica el mensaje |
| `POST /meetings/{id}/tokens` | Sí, con el mismo `device.key` | Emite otro token para la misma identidad y no duplica a la persona. Con otra `device.key` sería otra conexión |
| `transferHost`, `removeParticipant`, `declineCall`, `rotate-secret`, `claimScreenShare` | **No** a ciegas | Cambian estado; vuelve a leer antes de repetir. Rotar dos veces deja sin valor el secreto de la primera |

`@iaconsultinglabs/comms-server` ya sigue estas reglas: reintenta los `GET`, el `PUT` y
`createMeeting` (al que pone una `Idempotency-Key` si no le das una) ante 429, 5xx y errores de
red, con espera exponencial con *jitter*, respetando `Retry-After` hasta 30 s. Nunca reintenta
`endMeeting`, `transferHost`, `issueToken`, `removeParticipant`, `declineCall` ni
`rotateWebhookSecret`.

## La `Idempotency-Key`

- De 8 a 64 caracteres de `[A-Za-z0-9_.:-]`.
- Elige una que salga de tu dominio y no del azar: el id de tu hilo, de tu cita, de tu
  llamada. Así, si tu propio proceso se reinicia a medias, la repetición tampoco duplica.
- Vale 24 h. La misma clave con **otro** cuerpo responde `409 idempotency_conflict`.
- Solo existe en `POST /meetings`.

## La idempotencia de los eventos

La entrega de eventos es «al menos una vez»: el mismo evento puede llegar dos veces por el
webhook, o una por el webhook y otra por el cursor. **Deduplica por `event.id`** antes del
efecto, y si tienes varios procesos, con un almacén compartido o, mejor, con una clave única
en la misma transacción que el efecto. Más en [event-ordering.md](event-ordering.md).

---

<!-- fuente: docs/developers/limits.md -->

# Límites

Tres clases de límites: los del **plan** de tu tenant (los fija IACL contigo), los del
**contrato** (iguales para todos; cambiarlos es un cambio de contrato) y los de **operación**
(protegen el servicio, no son contractuales y pueden ajustarse).

## El plan

| Límite | Qué cuenta | Si se pasa |
|---|---|---|
| `concurrentParticipants` | Conexiones principales a la vez en todo el tenant (los aparatos complementarios no cuentan) | `422 plan_limit_reached` al emitir el token, con `details.limit` |
| `participantsPerMeeting` | Conexiones principales a la vez en una reunión (2-100) | Ídem |
| `meetingMinutes` | Duración máxima de una reunión (1-1440) | La reunión termina con `endReason: max_duration` |
| `video` | Si se puede publicar cámara | `plan_limit_reached` si pides vídeo y el plan no lo tiene |

Cómo se aplica:

1. **Al emitir el token**, se aparta una plaza durante 60 s (`PLAN_RESERVATION_SECONDS`) o hasta
   que la conexión entra.
2. **Al entrar**, se comprueba otra vez. Si la reserva caducó y ya no hay sitio, la conexión se
   rechaza: el navegador ve `plan_limit_reached` y tu backend recibe `participant.left` con
   `reason: plan_limit` (sin `participant.joined` antes).
3. Volver con la misma identidad (recarga, corte de red) no consume plaza nueva.

`settings.maxParticipants` y `settings.maxDurationMinutes` de una reunión pueden bajar el
límite del plan, nunca subirlo.

## El contrato

| Qué | Límite |
|---|---|
| Conexiones de una misma persona en una reunión | 3 a la vez (`MAX_CONNECTIONS_PER_PERSON`): la principal y dos complementarias. La cuarta, `409 device_limit_reached` |
| Invitados a una llamada (`invitees`) | 1 a 8 |
| Timbre de una llamada (`ring.timeoutSeconds`) | 10 a 120 s; 25 por defecto |
| Cierre de una reunión vacía (`emptyTimeoutSeconds`) | 0 a 3600 s; 300 por defecto |
| Validez de un token para entrar (`ttlSeconds`) | 60 a 21 600 s; 3600 por defecto. Una conexión ya dentro no se corta al caducar |
| Chat en sala | 20 mensajes cada 10 s por conexión; 4000 caracteres por mensaje |
| Turno de pantalla (pedir o soltar) | 10 cada 60 s por conexión |
| `Idempotency-Key` | 8 a 64 caracteres; vale 24 h |
| `title` | 200 caracteres |
| `externalRef` | 128 caracteres de `[A-Za-z0-9_.:@/-]` |
| `metadata` | 16 claves de hasta 40 caracteres; valores de hasta 256 |
| Nombre visible de una persona | 80 caracteres |
| Páginas (`limit`) | 1 a 200; 50 por defecto |
| Ventana de eventos (cursor y reintentos del webhook) | 72 h |
| Respuesta del webhook | 2xx en 10 s |
| Reloj de la firma del webhook | ±300 s |
| Solape de secretos al rotar | 24 h |

Los números que un cliente necesita conocer están también como constantes en
`@iaconsultinglabs/comms-contracts` (`MAX_CONNECTIONS_PER_PERSON`, `PLAN_RESERVATION_SECONDS`,
`RATE_LIMITS`, `WEBHOOK_TOLERANCE_SECONDS`…).

## La operación

No son parte del contrato: protegen el servicio y pueden cambiar sin aviso de versión. Un
cliente que respete `429` y `Retry-After` no tiene que conocerlos.

| Qué | Hoy |
|---|---|
| Peticiones de la API del tenant | 3000 por minuto y tenant |
| Peticiones por IP en el proxy | 50 por segundo, con ráfagas de 100; por encima, `429` del proxy (puede llegar sin cuerpo JSON) |
| Tamaño del cuerpo de una petición | 64 KiB |
| Reuniones terminadas | Se consultan durante 90 días; después se borran |

## Si necesitas más

Los límites del plan se cambian hablando con IACL. Los del contrato, con una petición de
cambio de contrato: se estudian para la siguiente versión.

---

<!-- fuente: docs/developers/privacy.md -->

# Privacidad: qué guarda IACL y qué no

El principio: **la infraestructura central de Comms no guarda contenido de comunicaciones.**
El audio, el vídeo y la pantalla pasan por el servidor de medios y no se graban. El chat se
retransmite y solo espera, cifrado, hasta que lo recibes. Lo que se guarda son los datos
necesarios para dar el servicio, operarlo y medir el uso.

## Lo que se guarda, y cuánto

| Qué | Lleva | Cuánto tiempo |
|---|---|---|
| Tu tenant y su plan | Nombre, plan, estado, la referencia con la que IACL te conoce | Mientras seas cliente |
| Tus claves de API | **Solo el hash** y los primeros caracteres para reconocerla; la clave entera no se guarda | Hasta que se revoca |
| Tu webhook | La URL, los tipos de evento y el secreto **cifrado** | Mientras lo tengas configurado |
| Cada reunión | Tipo, estado, fechas, ajustes, `title`, `externalRef`, `metadata`, quién llama y a quién (`caller`, `invitees`: tus ids) y el resultado | 90 días después de terminar |
| Las conexiones de una reunión activa | Tu id de la persona, su nombre visible, tipo, rol, aparato (`device.key` y etiqueta) y si está excluida de la IA | Mientras la reunión está activa |
| Los eventos | El sobre y sus datos (ids, fechas, motivos). Sin contenido, salvo `message.sent` | 72 h |
| `message.sent` | El texto del mensaje, **cifrado** con una clave de tu tenant | Hasta que tu webhook lo acusa, y como mucho 72 h |
| Las entregas del webhook | Si se entregó, cuántos intentos y cuándo | 72 h |
| El uso | Por mes: reuniones, minutos de reunión, minutos de participante y el pico de conexiones a la vez. Sin personas | Para la facturación |
| Los registros técnicos | Peticiones (ruta, estado, duración, `requestId`), sin cuerpos; las cabeceras de credenciales se quitan antes de escribir | Lo que fije la operación |

## Lo que no se guarda

- **Audio, vídeo ni pantalla, salvo de paso.** Si grabas (contrato 0.2.0), lo grabado es
  tuyo: va a tu bucket, o se te entrega a tu endpoint. En ese último caso Comms guarda la
  parte **cifrada** en el disco del nodo solo hasta que confirmas que la tienes, y como
  mucho 72 h; la parte que se está grabando está en claro en ese disco hasta que se cierra
  (`recording.md`).
- **El chat**, más allá de la cola de entrega de arriba. Si quieres historial, lo guardas tú.
- **Nada de tus invitados fuera de la reunión.** La sala de espera, el enlace y el
  consentimiento viven en tu sistema; Comms solo ve el acceso que emites.
- **Transcripciones, resúmenes o el contexto de la IA.** Las transcripciones y los resúmenes
  van a tu almacenamiento (tu bucket o tu endpoint). El contexto de una reunión lo sirves tú (`setAiContextSource`) o vive solo
  en memoria, con caducidad de 24 h como mucho (`setMeetingAiContext`). Los modos y los
  detectores son configuración, no contenido, y de tu `sendAiFeedback` solo se guarda la
  decisión. `aiExcluded` se respeta siempre, y los mensajes privados no se procesan nunca.
  (Contrato 0.2.0; la IA aún no está encendida en ningún nodo.)
- **Tus claves en claro**, ni en la base de datos ni en los registros.

## Lo que tú controlas

- **Lo que pones en `title`, `externalRef` y `metadata`.** Se guarda tal cual 90 días. No
  pongas ahí contenido de nadie (textos, notas) ni datos personales que no hagan falta: usa
  ids tuyos.
- **El nombre visible** que pasas al emitir el acceso lo ven los demás participantes y se
  guarda solo mientras la reunión está activa. Los eventos llevan tu id de la persona, no su
  nombre.
- **Los ids de persona** (`person.id`) son tuyos y opacos para Comms. Usa uno que no sea un
  dato personal (no un correo ni un teléfono).
- **El historial**: si guardas el chat o la asistencia, lo guardas en tu sistema y bajo tu
  responsabilidad.

## Dónde

Los nodos están en Hetzner, en Alemania (UE). Los medios viajan cifrados (DTLS-SRTP) entre el
navegador y el servidor de medios, que los reenvía sin guardarlos. No hay cifrado de extremo a
extremo en v1: el servidor de medios podría técnicamente ver el flujo, aunque no lo graba.

## Si te vas

Hoy no hay una operación en el contrato para borrar un tenant y todo lo suyo de una vez: se
pide a IACL. Lo que caduca solo (reuniones a los 90 días, eventos a las 72 h) se borra
igualmente.

---

<!-- fuente: docs/events.md -->

# Catálogo de eventos (contrato v1)

> GENERADO desde `packages/contracts/openapi/comms.yaml` (`pnpm --filter @iaconsultinglabs/comms-contracts docs`). No editar a mano.

Todos los eventos viajan en el mismo sobre:

```json
{ "id": "evt_…", "type": "recurso.acción", "version": 1, "tenantId": "ten_…", "occurredAt": "…", "data": { } }
```

- **Entrega**: POST firmado al webhook del tenant, «al menos una vez». Deduplicar por `id`.
- **Firma**: `IACL-Signature: t=<unix>,v1=<hex>` con `v1 = HMAC-SHA256(secreto, "<t>.<cuerpo crudo>")`. Rechazar si el reloj difiere más de 300 s. Durante una rotación pueden llegar dos `v1=`; vale si coincide uno.
- **Reintentos**: con espera creciente durante 72 h. Después, el evento solo existe en el backend del tenant (si lo recibió).
- **Reconciliación**: `GET /v1/events?after=<cursor>` devuelve lo de las últimas 72 h en orden.
- **Contenido**: ninguno, salvo los eventos marcados abajo: `message.sent` (el texto del chat) y los de la IA que llevan lo dicho o lo propuesto (`transcript.segment`, `detection.matched`, `assistant.suggestion`, `action.proposed` y el `abstract` de `summary.ready`). Se entregan y no se guardan: **se borran del registro en cuanto el webhook los acusa** con un 2xx; si no, a las 72 h.
- **Carril de IA en directo**: `transcript.segment`, `detection.matched` con `stage: live` y `assistant.suggestion` van en su propia cola por reunión, en orden entre ellos, sin esperar a la cola del resto de eventos del tenant ni hacerla esperar (para llegar en ≈ 3 s). Por cursor siguen saliendo en el orden global mientras no se hayan borrado. Por webhook, `transcript.segment` solo sale con `isFinal: true`.
- **Campos que no conoces: ignóralos, no rechaces el evento.** Vale para el sobre y para `data`. Añadir un campo opcional a un evento es un cambio MINOR: IACL lo puede mandar sin subir `version`, y un receptor que rechace lo que no conoce se rompe con él. Los esquemas de abajo describen lo que se manda hoy; no los uses para validar en estricto lo que recibes.
- **Tipos y versiones que no conoces**: contesta 2xx y descártalos. Si contestas con error, se reintentan durante 72 h sin que sirva de nada.
- **`@iaconsultinglabs/comms-server` ya lo hace por defecto**: `verifyWebhook` comprueba la firma, el reloj y los campos obligatorios del sobre, y deja pasar los demás campos sin tocarlos (no revalida `data`). Un `type` o una `version` desconocidos llegan como error ignorable (`unknown_event_type`, `unsupported_event_version`), y el manejador de webhooks contesta 200 sin llamar a tu `onEvent`.

| Evento | Versión | Cuándo | Lleva contenido |
|---|---|---|---|
| `meeting.created` | 1 | Se ha creado una reunión | no |
| `meeting.started` | 1 | Ha entrado la primera conexión | no |
| `meeting.ended` | 1 | La reunión ha terminado | no |
| `participant.joined` | 1 | Ha entrado una conexión | no |
| `participant.left` | 1 | Ha salido una conexión | no |
| `guest.admitted` | 1 | Se ha emitido el primer acceso de un invitado | no |
| `screenshare.started` | 1 | Alguien ha empezado a compartir pantalla | no |
| `screenshare.stopped` | 1 | Se ha dejado de compartir pantalla | no |
| `host.changed` | 1 | Ha cambiado quién manda | no |
| `call.ringing` | 1 | Una llamada 1:1 empieza a sonar (el tenant avisa con su push) | no |
| `call.missed` | 1 | Nadie ha contestado (o quien llamaba ha colgado antes) | no |
| `message.sent` | 1 | Un mensaje en el chat de la sala (lleva el texto) | **sí** (texto) |
| `recording.started` | 1 | Empieza una grabación | no |
| `recording.stopped` | 1 | Una grabación deja de grabar (sus partes aún se están subiendo) | no |
| `recording.ready` | 1 | Una grabación está en el almacenamiento del tenant (una vez por tipo) | no |
| `transcript.segment` | 1 | Un trozo de transcripción en directo (solo los finales, por el carril de IA en directo) | **sí** |
| `transcript.ready` | 1 | La transcripción de una grabación está en el almacenamiento del tenant | no |
| `summary.ready` | 1 | El resumen de un cierre está en el almacenamiento del tenant | **sí** |
| `detection.matched` | 1 | Se ha cumplido un detector (en directo o, como comprobación, al cierre) | **sí** |
| `assistant.suggestion` | 1 | Sugerencia privada del asistente para unas conexiones concretas | **sí** |
| `ai.result` | 1 | Una salida en directo del modo de la reunión (el `result` genérico, con los datos según su esquema) | **sí** |
| `action.proposed` | 1 | Acción propuesta al cierre, con su evidencia (la aprueba y la ejecuta el tenant) | **sí** |
| `ai.status` | 1 | El procesador de IA entra, sale, falla, se recupera o trabaja degradado | no |
| `ai.closing.completed` | 1 | Ha terminado un cierre (no llegan más eventos de él) | no |

## `meeting.created`

Se ha creado una reunión.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meeting` | `MeetingSummary` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7q8",
  "type": "meeting.created",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:00:00Z",
  "data": {
    "meeting": {
      "id": "mtg_4kq9x2m7a1b3c5d7",
      "type": "meeting",
      "status": "scheduled",
      "title": "Revisión de obra",
      "externalRef": "thread_66f1c0a2"
    }
  }
}
```

## `meeting.started`

Ha entrado la primera conexión.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `type` | `MeetingType` | sí |  |
| `externalRef` | `ExternalRef` | no |  |
| `startedAt` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7q9",
  "type": "meeting.started",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:02:11Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "type": "meeting",
    "externalRef": "thread_66f1c0a2",
    "startedAt": "2026-10-02T09:02:11Z"
  }
}
```

## `meeting.ended`

La reunión ha terminado.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `type` | `MeetingType` | sí |  |
| `externalRef` | `ExternalRef` | no |  |
| `startedAt` | `string | null` | no |  |
| `endedAt` | `string` | sí |  |
| `endReason` | `EndReason` | sí |  |
| `durationSeconds` | `integer` | sí | Desde `startedAt` (0 si nunca empezó). |
| `peakParticipants` | `integer` | sí |  |
| `callOutcome` | `CallOutcome` \| `null` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r0",
  "type": "meeting.ended",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:47:30Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "type": "meeting",
    "externalRef": "thread_66f1c0a2",
    "startedAt": "2026-10-02T09:02:11Z",
    "endedAt": "2026-10-02T09:47:30Z",
    "endReason": "everyone_left",
    "durationSeconds": 2719,
    "peakParticipants": 6,
    "callOutcome": null
  }
}
```

## `participant.joined`

Ha entrado una conexión.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `identity` | `Identity` | sí |  |
| `personId` | `PersonId` | sí |  |
| `personKind` | `PersonKind` | sí |  |
| `role` | `Role` | sí |  |
| `device` | `Device` | sí |  |
| `companion` | `boolean` | sí |  |
| `joinedAt` | `string` | sí |  |
| `rejoined` | `boolean` | sí | La misma identidad ya había estado dentro de esta reunión (recarga, corte de red). |
| `aiExcluded` | `boolean` | sí | La IA no procesará nada suyo en esta reunión. |
| `recordingExcluded` | `boolean` | sí | No se grabará su audio en esta reunión. |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r1",
  "type": "participant.joined",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:02:11Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "identity": "prt_4kq9x2m7a1b3c5d7",
    "personId": "usr_ana",
    "personKind": "user",
    "role": "host",
    "device": {
      "key": "dk_7f3a9c2e",
      "label": "desktop"
    },
    "companion": false,
    "joinedAt": "2026-10-02T09:02:11Z",
    "rejoined": false,
    "aiExcluded": false,
    "recordingExcluded": false
  }
}
```

## `participant.left`

Ha salido una conexión.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `identity` | `Identity` | sí |  |
| `personId` | `PersonId` | sí |  |
| `leftAt` | `string` | sí |  |
| `reason` | `string` (left, removed, disconnected, replaced, meeting_ended, plan_limit, device_limit, transferred) | sí | `disconnected`: se perdió la conexión y no volvió a tiempo. `replaced`: la misma identidad entró desde otra conexión. `plan_limit` / `device_limit`: se rechazó AL ENTRAR porque su reserva había caducado y ya no cabía (ver `issueToken`). `transferred` (añadido en la siguiente MINOR): la persona pasó la llamada a otro aparato (`TokenRequest.transfer`); la persona sigue dentro desde ese otro aparato. Quien consuma este evento debe tratar un valor desconocido como `left`. |
| `durationSeconds` | `integer` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r2",
  "type": "participant.left",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:40:05Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "identity": "prt_8m1n3p5q7r9s2t4v",
    "personId": "gst_51b2",
    "leftAt": "2026-10-02T09:40:05Z",
    "reason": "left",
    "durationSeconds": 1810
  }
}
```

## `guest.admitted`

Se ha emitido el primer acceso de un invitado.

Sin nombre ni correo del invitado (los tiene el tenant).

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `personId` | `PersonId` | sí |  |
| `identity` | `Identity` | sí |  |
| `admittedAt` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r3",
  "type": "guest.admitted",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:09:47Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "personId": "gst_51b2",
    "identity": "prt_8m1n3p5q7r9s2t4v",
    "admittedAt": "2026-10-02T09:09:47Z"
  }
}
```

## `screenshare.started`

Alguien ha empezado a compartir pantalla.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `identity` | `Identity` | sí |  |
| `personId` | `PersonId` | sí |  |
| `startedAt` | `string` | sí |  |
| `tookOverFrom` | `ConnectionRef` \| `null` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r4",
  "type": "screenshare.started",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:15:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "identity": "prt_4kq9x2m7a1b3c5d7",
    "personId": "usr_ana",
    "startedAt": "2026-10-02T09:15:00Z",
    "tookOverFrom": {
      "identity": "prt_8m1n3p5q7r9s2t4v",
      "personId": "gst_51b2"
    }
  }
}
```

## `screenshare.stopped`

Se ha dejado de compartir pantalla.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `identity` | `Identity` | sí |  |
| `personId` | `PersonId` | sí |  |
| `stoppedAt` | `string` | sí |  |
| `reason` | `string` (stopped, taken_over, left, removed, meeting_ended) | sí |  |
| `durationSeconds` | `integer` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r5",
  "type": "screenshare.stopped",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:15:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "identity": "prt_8m1n3p5q7r9s2t4v",
    "personId": "gst_51b2",
    "stoppedAt": "2026-10-02T09:15:00Z",
    "reason": "taken_over",
    "durationSeconds": 240
  }
}
```

## `host.changed`

Ha cambiado quién manda.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `previous` | `ConnectionRef` \| `null` | sí |  |
| `current` | `ConnectionRef` \| `null` | sí |  |
| `reason` | `string` (transferred, host_left, host_returned, only_guests_left) | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r6",
  "type": "host.changed",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:30:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "previous": {
      "identity": "prt_4kq9x2m7a1b3c5d7",
      "personId": "usr_ana"
    },
    "current": {
      "identity": "prt_2b4d6f8h1j3k5m7n",
      "personId": "usr_bruno"
    },
    "reason": "transferred"
  }
}
```

## `call.ringing`

Una llamada 1:1 empieza a sonar (el tenant avisa con su push).

El tenant avisa a los invitados con SU push. IACL Comms no manda notificaciones.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `externalRef` | `ExternalRef` | no |  |
| `caller` | `PersonRef` | sí |  |
| `invitees` | `array` | sí |  |
| `video` | `boolean` | sí |  |
| `ringUntil` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r7",
  "type": "call.ringing",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T11:00:00Z",
  "data": {
    "meetingId": "mtg_7c9e1g3i5k7m9o1q",
    "externalRef": "thread_direct_ana_bruno",
    "caller": {
      "id": "usr_ana"
    },
    "invitees": [
      "usr_bruno"
    ],
    "video": false,
    "ringUntil": "2026-10-02T11:00:25Z"
  }
}
```

## `call.missed`

Nadie ha contestado (o quien llamaba ha colgado antes).

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `externalRef` | `ExternalRef` | no |  |
| `caller` | `PersonRef` | sí |  |
| `invitees` | `array` | sí |  |
| `reason` | `string` (timeout, cancelled) | sí | `timeout`: sonó y nadie contestó. `cancelled`: quien llamaba colgó antes. |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r8",
  "type": "call.missed",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T11:00:25Z",
  "data": {
    "meetingId": "mtg_7c9e1g3i5k7m9o1q",
    "externalRef": "thread_direct_ana_bruno",
    "caller": {
      "id": "usr_ana"
    },
    "invitees": [
      "usr_bruno"
    ],
    "reason": "timeout"
  }
}
```

## `message.sent`

Un mensaje en el chat de la sala (lleva el texto).

**Lleva contenido** (el sobre del mensaje): es la entrega al
tenant de un mensaje que la API no guarda. En la cola de
reintentos espera cifrado y se borra al entregarse o a las 72 h.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `messageId` | `MessageId` | sí |  |
| `from` | `ConnectionRef` | sí |  |
| `body` | `ChatMessageBody` | sí |  |
| `clientId` | `string` | no |  |
| `sentAt` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7r9",
  "type": "message.sent",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:20:13Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "messageId": "msg_3h5j7k9m1n3p5q7r",
    "from": {
      "identity": "prt_8m1n3p5q7r9s2t4v",
      "personId": "gst_51b2"
    },
    "body": {
      "format": "text",
      "text": "Os paso el plano por correo."
    },
    "clientId": "c_8f2k1m9q",
    "sentAt": "2026-10-02T09:20:13Z"
  }
}
```

## `recording.started`

Empieza una grabación.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `recordingId` | `RecordingId` | sí |  |
| `kinds` | `array` | sí |  |
| `startedBy` | `RecordingStartedBy` | sí |  |
| `startedAt` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7t0",
  "type": "recording.started",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:05:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "recordingId": "rec_7k2m9q4x1b3c5d7f8g9h",
    "kinds": [
      "audio_per_participant"
    ],
    "startedBy": {
      "by": "host",
      "identity": "prt_4kq9x2m7a1b3c5d7"
    },
    "startedAt": "2026-10-02T09:05:00Z"
  }
}
```

## `recording.stopped`

Una grabación deja de grabar (sus partes aún se están subiendo).

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `recordingId` | `RecordingId` | sí |  |
| `reason` | `RecordingStopReason` | sí |  |
| `stoppedAt` | `string` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7t1",
  "type": "recording.stopped",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:45:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "recordingId": "rec_7k2m9q4x1b3c5d7f8g9h",
    "reason": "requested",
    "stoppedAt": "2026-10-02T09:45:00Z"
  }
}
```

## `recording.ready`

Una grabación está en el almacenamiento del tenant (una vez por tipo).

Una grabación está en el almacenamiento del TENANT. Se emite una
vez por tipo (`kind`) con el mismo `recordingId`, y solo cuando
TODAS sus partes están entregadas o perdidas. Junto a las partes
queda `manifest.json` (partes, desfases, duraciones y
excluidos; sin contenido), que con `tenant_endpoint` se entrega
el último (`partId: manifest`).

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `recordingId` | `RecordingId` | sí |  |
| `kind` | `RecordingKind` | sí |  |
| `status` | `string` (complete, partial, failed) | sí | `partial`: alguna parte falló o no se pudo entregar (las demás están). `failed`: no hay ninguna. |
| `reason` | `string` (delivery_expired, recording_failed) | no | Solo con `partial` o `failed`. `delivery_expired`: alguna parte (o el manifiesto) no se pudo entregar en 72 h y Comms la borró. `recording_failed`: alguna no se llegó a grabar. |
| `durationSeconds` | `integer` | sí | Lo que duró la grabación. |
| `parts` | `array` | sí |  |
| `manifestLocation` | `string` | no | `tenant:{recordingId}/manifest` o `s3://<bucket>/<prefijo>/recordings/<meetingId>/<recordingId>/manifest.json`. Sin el campo si no se pudo entregar. |
| `excludedParticipants` | `ExcludedParticipants` | sí | Conexiones con `recordingExcluded`. Constan; no se grabaron. |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s0",
  "type": "recording.ready",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:48:30Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "recordingId": "rec_7k2m9q4x1b3c5d7f8g9h",
    "kind": "audio_per_participant",
    "status": "complete",
    "durationSeconds": 2400,
    "parts": [
      {
        "partId": "audio-1",
        "personId": "usr_ana",
        "identity": "prt_4kq9x2m7a1b3c5d7",
        "delivered": true,
        "location": "tenant:rec_7k2m9q4x1b3c5d7f8g9h/audio-1",
        "offsetMs": 0,
        "durationMs": 2399000,
        "contentType": "audio/ogg",
        "sizeBytes": 9600000,
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ],
    "manifestLocation": "tenant:rec_7k2m9q4x1b3c5d7f8g9h/manifest",
    "excludedParticipants": [
      {
        "identity": "prt_8m1n3p5q7r9s2t4v",
        "personId": "gst_51b2"
      }
    ],
    "source": "iacl"
  }
}
```

## `transcript.segment`

Un trozo de transcripción en directo (solo los finales, por el carril de IA en directo).

**Lleva contenido** (lo dicho). Un trozo de transcripción en
directo. El procesador oye a cada participante por separado:
quién habla lo dice de quién es el audio, sin diarización.

Por webhook **solo salen los finales** (`isFinal: true`), y solo
si el modo tiene `live.transcript` distinto de `off`; los
provisionales van solo a la sala, como subtítulos. Va por el
**carril de IA en directo** (en orden con los demás eventos en
directo de la misma reunión, sin esperar a la cola del tenant)
y se borra del registro en cuanto el webhook lo acusa. Si el
mismo `segmentId` llega otra vez, `revision` es mayor y
sustituye al anterior.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `segmentId` | `TranscriptSegmentId` | sí |  |
| `revision` | `integer` | sí | Crece con cada corrección del mismo `segmentId` (0 la primera vez). |
| `transcriptionId` | `TranscriptionId` | no | La transcripción en directo a la que pertenece; es el `transcriptionId` del `transcript.ready` con `origin: live` que llegará al terminar. |
| `speakerParticipantId` | `Identity` | sí | La `identity` de la CONEXIÓN que habla (`prt_…`, la de `TokenGrant.identity`), no de la persona: una persona con dos aparatos tiene dos. La persona está en `personId`. Se llama así desde 0.1.0 y no cambia. |
| `personId` | `PersonId` | sí |  |
| `startMs` | `integer` | sí | Desde el inicio de la reunión. |
| `endMs` | `integer` | sí |  |
| `text` | `string` | sí |  |
| `language` | `string` | sí |  |
| `isFinal` | `boolean` | sí |  |
| `confidence` | `number` | no |  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s1",
  "type": "transcript.segment",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:20:13Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "segmentId": "seg_01j9z3k4m5n6p7q8",
    "revision": 1,
    "transcriptionId": "trn_5k7m9p1r3t5v7x9z1b3d",
    "speakerParticipantId": "prt_4kq9x2m7a1b3c5d7",
    "personId": "usr_ana",
    "startMs": 1080000,
    "endMs": 1084500,
    "text": "Mañana revisamos la tercera planta.",
    "language": "es",
    "isFinal": true,
    "confidence": 0.94,
    "source": "iacl"
  }
}
```

## `transcript.ready`

La transcripción de una grabación está en el almacenamiento del tenant.

La transcripción de una grabación (`requestTranscription`, o sola
con `settings.ai.postMeeting`) o la del procesador en directo
(`origin: live`, al terminar la reunión). El texto está en el
almacenamiento del tenant: `location` (`.json`, segmentos por
persona con sus tiempos) y `textLocation` (`.md` legible). Con
`tenant_endpoint`, se emite después de entregar los dos
(`PUT {url}/{recordingId}/transcripts/{transcriptionId}.json|.md`)
y sus ubicaciones son `tenant:{recordingId}/transcripts/{transcriptionId}.json|.md`.
Con `origin: live` no hay grabación: va bajo la reunión
(`PUT {url}/{meetingId}/transcripts/{transcriptionId}.json|.md`,
`tenant:{meetingId}/transcripts/…`; con `s3`,
`<prefijo>/transcripts/<meetingId>/<transcriptionId>.json|.md`). Si
el procesador se cayó a mitad de reunión, cada tramo es una
transcripción en directo distinta (`status: partial` la que se
cortó). Sin destino de almacenamiento no se emite: el directo queda
en los `transcript.segment`.
Con `origin: recording`, `transcriptionId` es el `id` de la
`Transcription` (el de la ruta `…/transcriptions/{transcriptionId}`).
Con `origin: live` es el id de la transcripción en directo, que
**no** es un recurso `Transcription`: no se puede pedir por
`getTranscription`; solo identifica esa transcripción (en
`transcript.segment.transcriptionId` y en `requestAiClosing`).

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `transcriptionId` | `TranscriptionId` | sí |  |
| `origin` | `string` (recording, live) | no | `recording`: la transcripción de una grabación (lleva `recordingId`). `live`: la del procesador en directo (sin `recordingId`). Sin el campo, `recording`. |
| `recordingId` | `RecordingId` | no |  |
| `status` | `string` (complete, partial, failed) | no | `partial`: falta alguna persona (`failedParticipants`). `failed`: no salió nada; sin `location`. |
| `language` | `string` | sí |  |
| `segments` | `integer` | sí |  |
| `location` | `string` | no | En el almacenamiento del tenant (`s3://<bucket>/<clave>.json`). Siempre, salvo con `failed`. |
| `textLocation` | `string` | no | El documento legible (`.md`). |
| `excludedParticipants` | `ExcludedParticipants` | sí |  |
| `failedParticipants` | `ExcludedParticipants` | no |  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s2",
  "type": "transcript.ready",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:50:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "transcriptionId": "trn_3h5j7k9m1n3p5q7r9s2t",
    "origin": "recording",
    "recordingId": "rec_7k2m9q4x1b3c5d7f8g9h",
    "status": "complete",
    "language": "es",
    "segments": 412,
    "location": "s3://acme-comms/iacl-comms/transcripts/mtg_4kq9x2m7a1b3c5d7/trn_3h5j7k9m1n3p5q7r9s2t.json",
    "textLocation": "s3://acme-comms/iacl-comms/transcripts/mtg_4kq9x2m7a1b3c5d7/trn_3h5j7k9m1n3p5q7r9s2t.md",
    "excludedParticipants": [
      {
        "identity": "prt_8m1n3p5q7r9s2t4v",
        "personId": "gst_51b2"
      }
    ],
    "failedParticipants": [],
    "source": "iacl"
  }
}
```

## `summary.ready`

El resumen de un cierre está en el almacenamiento del tenant.

El resumen de un cierre. El documento está en el almacenamiento
del tenant: `textLocation` (`.md` legible) y `location` (`.json`
con las secciones y las referencias a segmentos). `abstract` es
un extracto corto para pintarlo sin ir al bucket: **es
contenido**, y se borra del registro en cuanto el webhook lo
acusa, como `message.sent`.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `closingId` | `AiClosingId` | sí |  |
| `summaryId` | `AiSummaryId` | sí |  |
| `status` | `string` (complete, failed) | sí | `failed`: el resumen no salió (el cierre puede seguir con las acciones); sin `location`. |
| `language` | `string` | sí |  |
| `location` | `string` | no | El `.json` en el almacenamiento del tenant (`s3://<bucket>/<prefijo>/summaries/<meetingId>/<closingId>.json`). |
| `textLocation` | `string` | no | El `.md` legible, al lado. |
| `abstract` | `string` | no | Extracto del resumen. Contenido: se borra del registro al acusarse. |
| `excludedParticipants` | `ExcludedParticipants` | sí |  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s3",
  "type": "summary.ready",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:51:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "closingId": "acl_8r0t2v4x6z8b1d3f",
    "summaryId": "sum_6n8p0r2t4v6x8z1b",
    "status": "complete",
    "language": "es",
    "location": "s3://acme-comms/iacl-comms/summaries/mtg_4kq9x2m7a1b3c5d7/acl_8r0t2v4x6z8b1d3f.json",
    "textLocation": "s3://acme-comms/iacl-comms/summaries/mtg_4kq9x2m7a1b3c5d7/acl_8r0t2v4x6z8b1d3f.md",
    "abstract": "El cliente pide presupuesto para la tercera planta; decide el gerente. Siguiente paso: visita técnica el jueves.",
    "excludedParticipants": [],
    "source": "iacl"
  }
}
```

## `detection.matched`

Se ha cumplido un detector (en directo o, como comprobación, al cierre).

**Lleva contenido** (el fragmento y lo extraído). Se ha cumplido
un detector: en directo (`stage: live`, por el carril de IA en
directo) o, como comprobación, al cierre (`stage: closing`, con
`closingId`). Lleva el fragmento de la transcripción que lo
justifica y los datos extraídos según su `outputSchema` (se
garantiza que validan). Se borra del registro al acusarse.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `matchId` | `AiDetectionMatchId` | sí |  |
| `detectorId` | `DetectorId` | sí |  |
| `detectorName` | `string` | sí |  |
| `stage` | `AiStage` | sí |  |
| `closingId` | `AiClosingId` | no | Solo con `stage: closing`. |
| `evidence` | `AiEvidence` | sí |  |
| `evidenceSegmentIds` | `array` | no | Todos los segmentos que lo justifican (`evidence` es el principal). |
| `data` | `object` | sí | Lo extraído, con la forma del `outputSchema` del detector (vacío si no tiene). |
| `confidence` | `number` | sí |  |
| `latencyMs` | `integer` | no | Solo con `stage: live`: desde el final del segmento que lo dispara hasta la emisión. |
| `model` | `AiModelId` | no | El modelo del catálogo que lo produjo (ADR 0055). |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s4",
  "type": "detection.matched",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:21:02Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "matchId": "dtm_9b1d3f5h7j9l1n3p",
    "detectorId": "det_5n7p9r1t3v5x7z9b",
    "detectorName": "Petición de presupuesto",
    "stage": "live",
    "evidence": {
      "excerpt": "¿Nos podéis pasar presupuesto para la tercera planta?",
      "participant": {
        "identity": "prt_8m1n3p5q7r9s2t4v",
        "personId": "gst_51b2"
      },
      "offsetMs": 1142000,
      "endOffsetMs": 1145200,
      "segmentId": "seg_01j9z3k4m5n6p7r2"
    },
    "evidenceSegmentIds": [
      "seg_01j9z3k4m5n6p7r2"
    ],
    "data": {
      "scope": "tercera planta"
    },
    "confidence": 0.91,
    "latencyMs": 2310,
    "source": "iacl"
  }
}
```

## `assistant.suggestion`

Sugerencia privada del asistente para unas conexiones concretas.

**Lleva contenido.** Una sugerencia PRIVADA para unas conexiones
concretas (`audienceParticipantIds`, por defecto solo quien
manda). Nunca a invitados, salvo que la reunión lo permita
(`settings.ai.suggestionsToGuests`). Llega a esas conexiones por
la sala (`AiSuggestionPacket`, solo a ellas) y al tenant por
webhook, por el carril de IA en directo. Se borra del registro
al acusarse.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `suggestionId` | `AiSuggestionId` | sí |  |
| `audienceParticipantIds` | `array` | sí | Las `identity` de las CONEXIONES que deben verla (`prt_…`, la de `TokenGrant.identity`), no ids de persona. Se llama así desde 0.1.0 y no cambia. |
| `text` | `string` | sí | La sugerencia, escrita por el modelo (≤ 280 caracteres). La evidencia, en cambio, sale siempre de la transcripción. |
| `topic` | `string` | no | De qué trata, en pocas palabras (lo que la sugerencia propone sacar o responder). |
| `confidence` | `number` | no |  |
| `trigger` | `AiSuggestionTrigger` | sí |  |
| `helpKind` | `AiHelpKind` | no | Qué tipo de ayuda es (ADR 0057). Sin el campo (emisores anteriores), `suggestion`. |
| `sources` | `array` | no | Con `answer` y `fact`: los documentos del contexto en que se apoya (al menos uno). El `excerpt` sale del documento, nunca del modelo. |
| `evidence` | `array` | sí |  |
| `latencyMs` | `integer` | no | Desde el final del segmento que la dispara hasta la emisión. |
| `model` | `AiModelId` | no | El modelo del catálogo que lo produjo (ADR 0055). |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s5",
  "type": "assistant.suggestion",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:21:05Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "suggestionId": "sug_3c5e7g9i1k3m5o7q",
    "audienceParticipantIds": [
      "prt_4kq9x2m7a1b3c5d7"
    ],
    "text": "Han pedido presupuesto: confirma plazo y alcance antes de cerrar.",
    "trigger": {
      "type": "detection",
      "matchId": "dtm_9b1d3f5h7j9l1n3p"
    },
    "evidence": [
      {
        "excerpt": "¿Nos podéis pasar presupuesto para la tercera planta?",
        "participant": {
          "identity": "prt_8m1n3p5q7r9s2t4v",
          "personId": "gst_51b2"
        },
        "offsetMs": 1142000
      }
    ],
    "latencyMs": 2840,
    "source": "iacl"
  }
}
```

## `ai.result`

Una salida en directo del modo de la reunión (el `result` genérico, con los datos según su esquema).

**Lleva contenido.** Una salida en directo que declara el modo de la
reunión (`AiProfile.live.results`, ADR 0057): el `result` genérico.
Los datos validan siempre contra el `outputSchema` de esa salida, y
la evidencia sale de la transcripción (o del chat). Sale por el
carril de IA en directo y, por la sala (`AiResultPacket`), solo a
quien ve la ayuda privada. Se borra del registro al acusarse.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `resultId` | `AiResultId` | sí |  |
| `profileId` | `AiProfileId` | sí |  |
| `outputId` | `AiLiveResultOutputId` | sí |  |
| `data` | `object` | sí | Lo extraído, con la forma del `outputSchema` de la salida (vacío si no tiene). |
| `evidence` | `AiEvidence` | sí |  |
| `evidenceSegmentIds` | `array` | no |  |
| `confidence` | `number` | sí |  |
| `latencyMs` | `integer` | no | Desde el final de lo dicho que la dispara hasta la emisión. |
| `model` | `AiModelId` | no | El modelo del catálogo que lo produjo (ADR 0055). |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s9",
  "type": "ai.result",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:24:10Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "resultId": "res_7d9f1h3j5l7n9p1r",
    "profileId": "aip_8r0t2v4x6z8b1d3f",
    "outputId": "plazo_entrega",
    "data": {
      "fecha": "2026-11-15"
    },
    "evidence": {
      "excerpt": "Lo necesitaríamos antes del quince de noviembre.",
      "participant": {
        "identity": "prt_8m1n3p5q7r9s2t4v",
        "personId": "gst_51b2"
      },
      "offsetMs": 1290000
    },
    "confidence": 0.88,
    "latencyMs": 2100,
    "source": "iacl"
  }
}
```

## `action.proposed`

Acción propuesta al cierre, con su evidencia (la aprueba y la ejecuta el tenant).

**Lleva contenido.** Una acción PROPUESTA en un cierre, con su
evidencia. **La aprobación y la ejecución son siempre del
tenant**, con los permisos de quien la aprueba: IACL Comms nunca
ejecuta acciones en sistemas del cliente. `actionType` es uno de
los tipos que declara el modo (`AiActionType`) y se garantiza
que `arguments` valida contra su `argumentsSchema`. Lo único
que vuelve a Comms es la decisión (`sendAiFeedback`), para
medir. Se borra del registro al acusarse.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `closingId` | `AiClosingId` | sí |  |
| `profileId` | `AiProfileId` | sí |  |
| `profileVersion` | `integer` | sí |  |
| `actionId` | `AiActionId` | sí |  |
| `actionType` | `AiActionTypeName` | sí |  |
| `name` | `string` | sí | El nombre del tipo de acción en el modo. |
| `description` | `string` | sí |  |
| `arguments` | `object` | sí | Los datos propuestos; validan contra el `argumentsSchema` del tipo. |
| `confidence` | `number` | sí |  |
| `evidence` | `array` | sí |  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s6",
  "type": "action.proposed",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:52:00Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "closingId": "acl_8r0t2v4x6z8b1d3f",
    "profileId": "aip_tpl_sales",
    "profileVersion": 1,
    "actionId": "act_2c4e6g8i0k2m4o6q",
    "actionType": "quote.request",
    "name": "Pedir presupuesto",
    "description": "Preparar presupuesto de la tercera planta para el cliente.",
    "arguments": {
      "scope": "tercera planta"
    },
    "confidence": 0.88,
    "evidence": [
      {
        "excerpt": "¿Nos podéis pasar presupuesto para la tercera planta?",
        "participant": {
          "identity": "prt_8m1n3p5q7r9s2t4v",
          "personId": "gst_51b2"
        },
        "offsetMs": 1142000
      }
    ],
    "source": "iacl"
  }
}
```

## `ai.status`

El procesador de IA entra, sale, falla, se recupera o trabaja degradado.

El procesador de IA entra (`joined`), sale (`left`), falla
(`failed`), se recupera (`recovered`) o sigue con una parte
caída (`degraded`, con `component`). **Que falle nunca afecta a
la llamada.**

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `status` | `string` (joined, left, failed, recovered, degraded) | sí |  |
| `component` | `string` (transcription, detectors, suggestions, closing, context) | no | La parte afectada (con `degraded` o `failed`). |
| `reason` | `string` (provider_unavailable, context_unavailable, plan_limit, capacity, e2ee_no_key, processor_restarted, disabled, ended) | no | `provider_unavailable`: el proveedor de IA no responde. `context_unavailable`: no hay contexto (la fuente del tenant falló o se perdió el de memoria). `plan_limit`: se llegó a un tope del plan. `capacity`: no hay sitio en el nodo. `e2ee_no_key`: reservado (E2EE). `processor_restarted`: el procesador se reinició y volvió. `disabled`: se apagó con `updateMeetingAi`. `ended`: terminó la reunión.  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s7",
  "type": "ai.status",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:02:15Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "status": "degraded",
    "component": "context",
    "reason": "context_unavailable",
    "source": "iacl"
  }
}
```

## `ai.closing.completed`

Ha terminado un cierre (no llegan más eventos de él).

El último evento de un cierre: después no llega ningún
`summary.ready`, `detection.matched` ni `action.proposed` de ese
`closingId`. Dice cuántas acciones y comprobaciones salieron.
Sin contenido.

| Campo de `data` | Tipo | Obligatorio | Nota |
|---|---|---|---|
| `meetingId` | `MeetingId` | sí |  |
| `closingId` | `AiClosingId` | sí |  |
| `status` | `string` (complete, partial, failed) | sí | `partial`: salió algo, pero una de las salidas falló. `failed`: no salió nada. |
| `summaryId` | `AiSummaryId` | no |  |
| `actions` | `integer` | sí | `action.proposed` emitidos. |
| `checks` | `integer` | sí | Comprobaciones cumplidas (`detection.matched` con `stage: closing`). |
| `model` | `AiModelId` | no | El modelo del catálogo que lo produjo (ADR 0055). |
| `excludedParticipants` | `ExcludedParticipants` | sí |  |
| `source` | `AiSource` | sí |  |

Ejemplo:

```json
{
  "id": "evt_01j9z3k4m5n6p7s8",
  "type": "ai.closing.completed",
  "version": 1,
  "tenantId": "ten_9x2kq4m7a1b3c5d7",
  "occurredAt": "2026-10-02T09:52:05Z",
  "data": {
    "meetingId": "mtg_4kq9x2m7a1b3c5d7",
    "closingId": "acl_8r0t2v4x6z8b1d3f",
    "status": "complete",
    "summaryId": "sum_6n8p0r2t4v6x8z1b",
    "actions": 1,
    "checks": 1,
    "excludedParticipants": [],
    "source": "iacl"
  }
}
```

---

<!-- fuente: docs/errors.md -->

# Códigos de error (contrato v1)

> GENERADO desde `packages/contracts/openapi/comms.yaml`. No editar a mano.

Toda respuesta de error tiene esta forma, y un cliente decide por `code`, nunca por `message`:

```json
{ "error": { "code": "plan_limit_reached", "message": "…", "requestId": "req_…", "details": { } } }
```

Un código no cambia de significado dentro de la v1. Añadir uno es MINOR; cambiar o quitar uno es MAJOR.

| Código | HTTP | Significado |
|---|---|---|
| `unauthorized` | 401 | Sin credencial, o la credencial no vale (clave revocada, token caducado o de otra reunión). |
| `forbidden` | 403 | La credencial vale, pero no permite esta acción. |
| `not_found` | 404 | No existe, o es de otro tenant. Indistinguible a propósito. |
| `validation_failed` | 400 | La petición no tiene la forma del contrato. `details.fields` dice qué campos. |
| `conflict` | 409 | El estado actual no permite la acción. |
| `idempotency_conflict` | 409 | La misma `Idempotency-Key` con otro cuerpo. |
| `rate_limited` | 429 | Demasiadas peticiones. Repetir tras `Retry-After`. |
| `plan_limit_reached` | 422 | No cabe en el plan (`details.limit`: concurrentParticipants, participantsPerMeeting, meetingMinutes, video, recording, recordingMinutesPerMonth, aiRealtime, aiPostMeeting, aiConcurrentMeetings, aiRealtimeMinutesPerMonth, aiPostMeetingMinutesPerMonth, aiClosingsPerMonth). |
| `tenant_suspended` | 403 | El tenant está suspendido: sus claves de API dejan de valer (ADR 0056) y no se crean reuniones ni se emiten tokens. Las reuniones en curso siguen, salvo que la operación las corte. |
| `meeting_ended` | 409 | La reunión ya terminó. No se reabre: se crea otra. |
| `meeting_not_call` | 409 | La acción es solo de llamadas (`type: call`), o la llamada ya no suena. |
| `guests_not_allowed` | 403 | La reunión no admite invitados (`settings.guestsAllowed: false`). |
| `person_blocked` | 403 | A esa persona la sacaron de esta reunión con `blockPerson`. |
| `role_not_allowed` | 400 | Rol incompatible: un `guest` con rol que no es guest, o un rol que la reunión no permite. |
| `participant_not_found` | 404 | Esa conexión no está dentro de la reunión. |
| `host_target_invalid` | 409 | No se puede pasar el mando a esa conexión (no está dentro, o es un invitado). |
| `screen_share_busy` | 409 | Otra conexión presenta. `details.presenter` y `details.canTakeOver`. |
| `screen_share_not_allowed` | 403 | Esta conexión no puede compartir pantalla, o no puede quitársela a quien presenta. |
| `chat_not_allowed` | 403 | El chat está apagado en la reunión, o esta conexión no puede escribir. |
| `device_limit_reached` | 409 | Esa persona ya tiene `MAX_CONNECTIONS_PER_PERSON` (3) conexiones en la reunión. |
| `e2ee_not_enabled` | 400 | Se mandó un mensaje `format: encrypted` y la reunión no tiene E2EE (en v1, ninguna). |
| `ai_input_not_supported` | 400 | Una entrada de IA reservada (`screen`) que v1 no procesa. |
| `not_implemented` | 501 | Ruta o valor reservado en el contrato y aún no disponible (p. ej. `video`), o una función que este nodo no tiene activada (grabación, entrega al tenant, transcripción, IA: modos, contexto, cierres y detectores). |
| `e2ee_incompatible_settings` | 400 | La reunión es cifrada de extremo a extremo (`e2ee.mode: tenant_keys`) y lo pedido necesita el contenido en el servidor (grabar, transcribir). `details.fields`. |
| `storage_destination_missing` | 409 | Grabar o transcribir sin destino configurado (`setStorageDestination`). |
| `storage_destination_invalid` | 400 | El destino no pasa la comprobación (el objeto de prueba del bucket, o el `HEAD` firmado al endpoint). `details.reason`: unreachable, access_denied, no_such_bucket, invalid_endpoint. |
| `recording_active` | 409 | Ya hay una grabación activa en la reunión (`details.recordingId`). |
| `recording_not_active` | 409 | La grabación ya no está grabando (o no hay ninguna activa). |
| `recording_not_allowed` | 403 | No se puede empezar a grabar: la conexión no es `host`, o la reunión no tiene `settings.recording.hostControl`; o `details.reason: staging_full`, el disco temporal del nodo para las entregas al tenant está lleno (la llamada sigue; probar más tarde). |
| `recording_excluded_participant` | 409 | `video` (compuesto) con una persona con `recordingExcluded` dentro (no se puede recortar por persona). No aplica a `mixed_audio`: se mezcla de las partes por persona, que ya la dejan fuera. |
| `recording_not_ready` | 409 | La grabación aún no está en el almacenamiento del tenant (`status` distinto de `ready`), o no tiene partes de audio que transcribir. |
| `ai_not_enabled` | 409 | Algo de IA (contexto, cierre, directo) con el plan o el nodo sin esa capacidad, o con `settings.ai.enabled: false`. `details.capability`: realtime, postMeeting. |
| `ai_profile_not_found` | 404 | El `profileId` no es un modo del tenant ni una plantilla de IACL. |
| `ai_context_invalid` | 400 | Un `AiContext` con la forma del contrato pero inaceptable. `details.reason`: too_large (más de 200 kB), location_outside_destination, no_storage_destination. |
| `ai_context_source_invalid` | 400 | La petición de prueba a la fuente de contexto del tenant falló. `details.reason`: unreachable, bad_status, timeout, no_webhook_secret. |
| `ai_transcript_unavailable` | 409 | Un cierre sin ninguna transcripción de la reunión, o `upTo: now` sin transcripción en directo. |
| `ai_closing_active` | 409 | Ya hay un cierre `queued` o `running` en la reunión (`details.closingId`). |
| `ai_detector_limit` | 409 | Más detectores en directo en una reunión que `Plan.ai.liveDetectorsPerMeeting`. `details.limit` y `details.count`. |
| `ai_model_unavailable` | 400 | El modelo de IA pedido no está en el catálogo, no es de ese tipo (`live`, `closing`) o está retirado (ADR 0055). `details.field` dice cuál y `details.available`, los `id` que valen. |
| `key_scope_missing` | 403 | La clave de API vale, pero no tiene el permiso que pide esta ruta (ADR 0056). `details.scope` dice cuál falta. |
| `key_limit_reached` | 422 | La clave de API llegó a uno de sus topes del mes (ADR 0056). `details.limit` (meetingMinutesPerMonth, aiRealtimeMinutesPerMonth, aiClosingsPerMonth), `details.max` y `details.used`. Las reuniones en curso siguen. |
| `live_keys_not_allowed` | 403 | La cuenta todavía no puede tener claves de producción: hace falta un plan de pago activo (ADR 0061). Las de prueba sí. |
| `billing_hold` | 402 | La cuenta tiene un impago: crear reuniones de producción y dar acceso a una que aún no ha empezado está en pausa (ADR 0061). Lo que está en curso y las claves de prueba siguen. `details.since`. |
| `cursor_expired` | 410 | El cursor es más viejo que la ventana de 72 h. Reconstruir con `listMeetings`/`getMeeting`. |
| `webhook_endpoint_invalid` | 400 | La URL del webhook no es `https` o no es alcanzable. |
| `internal_error` | 500 | Fallo nuestro. `requestId` para soporte. |
| `unavailable` | 503 | Servicio no disponible ahora (nodo de medios caído, mantenimiento). Reintentable. |

---

# Referencia de los paquetes

Sacada de los tipos publicados (`dist/*.d.ts`) con su documentación.

---

## Referencia: @iaconsultinglabs/comms-server

SDK de backend (Node ≥ 22): reuniones, accesos, configuración, consumo y webhooks. Usa la API key.

### index.d.ts

```ts
/**
 * @iaconsultinglabs/comms-server — SDK Node de servidor de IACL Comms.
 *
 * Lo usa el backend de cada cliente (por ejemplo, General ERP) para crear reuniones, emitir
 * tokens de participante, verificar webhooks y reconciliar eventos contra el plano de control.
 * También cubre `/participant/*` con el token de una conexión y `/ops/*` con la credencial de
 * operación de IACL (solo el panel de administración).
 * La API key del tenant vive solo en ese backend: este paquete nunca debe acabar en un navegador.
 */
export declare const PACKAGE_NAME: "@iaconsultinglabs/comms-server";
export { createCommsClient } from './client.js';
export type { CommsClient, CommsClientOptions, CreateMeetingInput, CreateMeetingOptions, DetectorCreateInput, DetectorPatchInput, EndMeetingInput, GuestTokenInput, ListDetectorsQuery, ListEventsQuery, ListMeetingsQuery, MemberTokenInput, RemoveParticipantInput, RequestOptions, StartRecordingInput, StartRecordingOptions, StorageDestinationInput, TokenInput, TranscriptionInput, WebhookEndpointInput, } from './client.js';
export type { FetchLike, RetryOptions, TransportOptions } from './http.js';
export type { AiClosingInput, AiContextInput, AiContextSourceInput, AiModelDefaultsInput, AiFeedbackInput, AiMeetingUpdateInput, AiMethods, AiProfileCreateInput, AiProfileUpdateInput, IdempotentOptions, ListAiProfilesQuery, } from './ai.js';
export type { ApiKeyCreateInput, ApiKeyRotateInput, ApiKeyUpdateInput, KeyMethods, UsageQuery } from './keys.js';
export { createParticipantClient } from './participant.js';
export type { ChatMessageInput, ParticipantClient, ParticipantClientOptions, ScreenShareClaimInput, } from './participant.js';
export { createOpsClient } from './ops.js';
export type { CreateApiKeyInput, CreateTenantInput, ListTenantsQuery, OpsClient, OpsClientOptions, RotateApiKeyInput, SuspendTenantInput, TenantPage, TenantPageItem, UpdateApiKeyInput, UpdateTenantInput, } from './ops.js';
export { CommsApiError, CommsError, CommsNetworkError, CursorExpiredError, isCommsApiError, } from './errors.js';
export { WebhookVerificationError, computeSignature, parseSignatureHeader, verifyWebhook, verifyWebhookSignature, } from './webhooks.js';
export type { HeadersInput, ParsedSignature, VerifyWebhookInput, WebhookFailureReason } from './webhooks.js';
export { computeRecordingSignature, createFileRecordingStore, createRecordingIngestHandler, signRecordingDelivery, verifyRecordingDelivery, } from './recordings.js';
export type { RecordingIngestFailure, RecordingIngestHandler, RecordingIngestOptions, RecordingIngestRequest, RecordingIngestResponse, RecordingObjectInfo, RecordingObjectRef, RecordingPutInfo, RecordingStore, VerifyRecordingDeliveryInput, } from './recordings.js';
export { createAiContextSourceHandler } from './ai-context.js';
export type { AiContextSourceHandler, AiContextSourceHandlerOptions, AiContextSourceResponse } from './ai-context.js';
export { createWebhookHandler } from './handler.js';
export type { EventHandlers, WebhookContext, WebhookHandler, WebhookHandlerOptions, WebhookOutcome, WebhookResult, } from './handler.js';
export { DEFAULT_IDEMPOTENCY_TTL_SECONDS, IdempotentProcessor, MemoryIdempotencyStore } from './idempotency.js';
export type { IdempotencyStore, MaybePromise, MemoryIdempotencyStoreOptions, ProcessOutcome } from './idempotency.js';
export { MemoryCursorStore, reconcile } from './reconcile.js';
export type { CursorExpiredContext, CursorStore, ReconcileOptions, ReconcileResult } from './reconcile.js';
export { AI_CLOSING_DOCUMENT_KIND, AI_CLOSING_PART_PATTERN } from '@iaconsultinglabs/comms-contracts';
export type { ActionProposedEvent, AiClosing, AiClosingDocument, AiClosingDocumentAction, AiClosingDocumentCheck, AiClosingDocumentSection, AiContextRequest, AiClosingCompletedEvent, AiContext, AiProfile, AiStatusEvent, AiResultEvent, AiHelpKind, AiHelpSource, AiLiveResultSpec, AiMeetingUsage, AnyEvent, AssistantSuggestionEvent, DetectionMatchedEvent, SummaryReadyEvent, TranscriptSegmentEvent, ChatMessage, ErrorCode, EventOf, EventType, Recording, RecordingDisclosure, RecordingList, ScreenShareGrant, StorageDestination, TenantEndpointDestination, S3Destination, TokenGrant, Transcription, TranscriptionList, } from '@iaconsultinglabs/comms-contracts';
```

### client.d.ts

```ts
type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
    [K in keyof T]?: DeepPartial<T[K]>;
} : T;
/** The body of `createMeeting`: `CreateMeetingRequest` with every setting optional (the plan fills the rest). */
export type CreateMeetingInput = Omit<CreateMeetingRequest, 'settings'> & {
    /** Only what differs from the plan defaults. */
    settings?: DeepPartial<NonNullable<CreateMeetingRequest['settings']>>;
};
/** The body of `endMeeting`; the reason defaults to `ended_by_tenant`. */
export type EndMeetingInput = Partial<EndMeetingRequest>;
/** The body of `removeParticipant`: `scope` defaults to `person`, `blockPerson` to `false`. */
export type RemoveParticipantInput = Partial<RemoveParticipantRequest>;
/** The raw body of `issueToken`. Prefer `issueMemberToken` or `issueGuestToken`, which fill `person.kind` and `role` for you. */
export type TokenInput = Omit<TokenRequest, 'companion' | 'transfer' | 'ttlSeconds' | 'aiExcluded'> & Partial<Pick<TokenRequest, 'companion' | 'transfer' | 'ttlSeconds' | 'aiExcluded'>>;
/** The body of `setWebhookEndpoint`; `enabled` defaults to `true`. */
export type WebhookEndpointInput = Omit<WebhookEndpointRequest, 'enabled'> & Partial<Pick<WebhookEndpointRequest, 'enabled'>>;
/** The body of `createDetector`; `active` defaults to `true`. */
export type DetectorCreateInput = Omit<DetectorInput, 'active'> & Partial<Pick<DetectorInput, 'active'>>;
/** The body of `updateDetector`: only what changes. */
export type DetectorPatchInput = DetectorPatch;
/** `prefix` defaults to `iacl-comms`, `forcePathStyle` to `true`. */
export type StorageDestinationInput = StorageDestinationRequest;
/** The body of `startRecording`: what to record (`kinds`), defaulting to the meeting settings. */
export type StartRecordingInput = StartRecordingRequest;
/** The body of `requestTranscription`: the language of the meeting. */
export type TranscriptionInput = TranscriptionRequest;
/** Filters and paging for `listMeetings` (status, type, `externalRef`, dates, `limit`, `cursor`). */
export type ListMeetingsQuery = NonNullable<operations['listMeetings']['parameters']['query']>;
/** Paging for `listEvents`: `after` (the cursor you persisted), `types` and `limit`. */
export type ListEventsQuery = NonNullable<operations['listEvents']['parameters']['query']>;
/** Filters and paging for `listDetectors`. */
export type ListDetectorsQuery = NonNullable<operations['listDetectors']['parameters']['query']>;
export type { RequestOptions };
/** Per-call options of `createMeeting`. */
export interface CreateMeetingOptions extends RequestOptions {
    /** 8-64 chars of `[A-Za-z0-9_.:-]`. Generated when absent, so a retry never creates two meetings. */
    idempotencyKey?: string;
}
/** Per-call options of `startRecording`. */
export interface StartRecordingOptions extends RequestOptions {
    /** 8-64 chars of `[A-Za-z0-9_.:-]`. Generated when absent, so a retry never starts two recordings. */
    idempotencyKey?: string;
}
/** `retries` counts extra attempts for retry-safe calls (GET, PUT, PATCH, DELETE, POST with Idempotency-Key). */
export interface CommsClientOptions extends TransportOptions {
    /** The tenant API key (`iacl_<env>_<id>.<secret>`). Backend only; never log it. */
    apiKey: string;
}
interface TokenInputBase {
    /** Who joins: your id for the person and the name the room shows. */
    person: {
        /** Your id for this person (your user id, or a key for a guest). */
        id: PersonId;
        /** The name shown in the room. */
        name: string;
    };
    /** The browser's device: `currentDevice()` from `comms-core`, sent up by your page. */
    device: Device;
    /** A second device of a person who is already inside (no audio playback, joins muted). */
    companion?: boolean;
    /**
     * Hand the call over to this device: once it joins, the person's other connections leave
     * with `participant.left` `reason: transferred`. Not with `companion`. Ask for it only when
     * the browser joins (`reason: join`), never on a reconnect.
     */
    transfer?: boolean;
    /** Narrow what this connection may publish (it never widens what the role allows). */
    permissions?: SourcePermissionsPatch;
    /** How long the token is valid. Defaults to the API's (and the browser renews it on its own). */
    ttlSeconds?: number;
    /** Keep this person out of the AI: neither their audio nor their messages are processed. Default `false`. */
    aiExcluded?: boolean;
    /** Do not record this person. When absent it follows `aiExcluded` (who refuses the AI is not recorded either). */
    recordingExcluded?: boolean;
}
/** A member of the organisation: `kind: user`, role `member` (default) or `host`. */
export interface MemberTokenInput extends TokenInputBase {
    /** `member` (default) or `host`, who has the controls of the room. */
    role?: Exclude<Role, 'guest'>;
    /**
     * This connection sees the private live AI help (ADR 0057): suggestions, answers, context
     * facts, alerts, detections and mode results, on top of the mode's audience. Never with
     * `aiExcluded`. A guest can never have it (there is no such field on `GuestTokenInput`).
     * The grant says whether it ended up seeing it: `TokenGrant.aiAssist`.
     */
    aiAssist?: boolean;
}
/** Someone from outside: `kind: guest`, role `guest`. There is no way to ask for another role. */
export type GuestTokenInput = TokenInputBase;
/**
 * The tenant surface of the contract. Recording and transcription are declared here; the
 * meeting AI (context, profiles, closings, feedback) comes from `AiMethods` (`src/ai.ts`), and
 * the account's API keys and usage from `KeyMethods` (`src/keys.ts`).
 */
export interface CommsClient extends AiMethods, KeyMethods {
    /** Idempotent: sends an `Idempotency-Key` (generated if you give none) and is retried on 429/5xx. */
    createMeeting(body: CreateMeetingInput, options?: CreateMeetingOptions): Promise<Meeting>;
    /** One page. Use `iterateMeetings`/`iterateMeetingPages` to walk all of them. */
    listMeetings(query?: ListMeetingsQuery, options?: RequestOptions): Promise<MeetingPage>;
    /** Every page of meetings, following `nextCursor` for you. */
    iterateMeetingPages(query?: Omit<ListMeetingsQuery, 'cursor'>, options?: RequestOptions): AsyncGenerator<MeetingPage, void, undefined>;
    /** Every meeting, one by one, across pages. */
    iterateMeetings(query?: Omit<ListMeetingsQuery, 'cursor'>, options?: RequestOptions): AsyncGenerator<Meeting, void, undefined>;
    /** A meeting with the connections inside right now. `not_found` if it does not exist. */
    getMeeting(meetingId: MeetingId, options?: RequestOptions): Promise<MeetingDetail>;
    /**
     * The connections a person has inside the meeting right now (from `getMeeting`): to ask
     * «you are already in from another device: join here too, or move the call here?».
     * Empty when the person is not inside.
     */
    connectionsOf(meetingId: MeetingId, personId: PersonId, options?: RequestOptions): Promise<MeetingDetail['participants']>;
    /** End the meeting for everyone (`meeting.ended`). Ending an ended meeting returns it as it is. */
    endMeeting(meetingId: MeetingId, body?: EndMeetingInput, options?: RequestOptions): Promise<Meeting>;
    /** A person declines a ringing call (`type: call`, still `scheduled`). Once every invitee has declined, the call ends with `callOutcome: declined`. */
    declineCall(meetingId: MeetingId, body: DeclineCallRequest, options?: RequestOptions): Promise<void>;
    /** The raw token call: you fill `person.kind` and `role`. Prefer `issueMemberToken`/`issueGuestToken`. */
    issueToken(meetingId: MeetingId, body: TokenInput, options?: RequestOptions): Promise<TokenGrant>;
    /**
     * A token for someone of your organisation, to hand to their browser (the `tokenSource` of
     * `comms-core`). Throws `meeting_ended`, `person_blocked`, `plan_limit_reached`…
     *
     * @example
     * ```ts
     * // fragment: `comms` is a CommsClient, `user` is your logged-in user
     * const grant = await comms.issueMemberToken(meetingId, {
     *   person: { id: user.id, name: user.name },
     *   device: req.body.device,
     *   role: 'host',
     * })
     * res.json(grant)
     * ```
     */
    issueMemberToken(meetingId: MeetingId, input: MemberTokenInput, options?: RequestOptions): Promise<TokenGrant>;
    /** A token for someone from outside (`role: guest`). `guests_not_allowed` if the meeting does not allow guests. */
    issueGuestToken(meetingId: MeetingId, input: GuestTokenInput, options?: RequestOptions): Promise<TokenGrant>;
    /** Hand the host controls to another connection (`host.changed`). */
    transferHost(meetingId: MeetingId, body: TransferHostRequest, options?: RequestOptions): Promise<Meeting>;
    /** Take a connection (or the whole person) out of the meeting, optionally blocking them from coming back. */
    removeParticipant(meetingId: MeetingId, identity: Identity, body?: RemoveParticipantInput, options?: RequestOptions): Promise<void>;
    /** One page of events after a cursor. Throws `CursorExpiredError` past the 72 h window. */
    listEvents(query?: ListEventsQuery, options?: RequestOptions): Promise<EventPage>;
    /** Pages from `query.after` until `hasMore` is false. Each page carries the cursor to persist. */
    iterateEventPages(query?: ListEventsQuery, options?: RequestOptions): AsyncGenerator<EventPage, void, undefined>;
    /** Every event after `query.after`, one by one. For a durable cursor and deduplication, use `reconcile`. */
    iterateEvents(query?: ListEventsQuery, options?: RequestOptions): AsyncGenerator<AnyEvent, void, undefined>;
    /** Your webhook endpoint, without the secret. `not_found` when there is none. */
    getWebhookEndpoint(options?: RequestOptions): Promise<WebhookEndpoint>;
    /** Create or replace your webhook endpoint. The first time, the response carries the signing `secret` (only then). */
    setWebhookEndpoint(body: WebhookEndpointInput, options?: RequestOptions): Promise<WebhookEndpointWithSecret>;
    /** Never retried: a repeated rotation would invalidate a secret that was not read yet. */
    rotateWebhookSecret(options?: RequestOptions): Promise<WebhookEndpointWithSecret>;
    /**
     * Detectors (ADR 0050 and 0053): of the tenant, of a profile or of a meeting; live, at the
     * closing or both. While the node has no AI the API answers `not_implemented` (501),
     * thrown as `CommsApiError`.
     */
    createDetector(body: DetectorCreateInput, options?: RequestOptions): Promise<Detector>;
    /** One page of detectors. */
    listDetectors(query?: ListDetectorsQuery, options?: RequestOptions): Promise<DetectorPage>;
    /** One detector. */
    getDetector(detectorId: DetectorId, options?: RequestOptions): Promise<Detector>;
    /** Change a detector: only what you send. */
    updateDetector(detectorId: DetectorId, body: DetectorPatchInput, options?: RequestOptions): Promise<Detector>;
    /** Delete a detector. Its past detections stay in your systems. */
    deleteDetector(detectorId: DetectorId, options?: RequestOptions): Promise<void>;
    /**
     * Where recordings and transcriptions go (ADR 0054). `tenant_endpoint` (recommended): IACL
     * delivers each part to your endpoint with a signed `PUT` and deletes its copy once you
     * acknowledge it; the first response carries `deliverySecret` ONCE (verify with
     * `createRecordingIngestHandler`). `s3`: your own bucket; the API uploads a small test
     * object first. `storage_destination_invalid` with `details.reason` when the check fails.
     */
    setStorageDestination(body: StorageDestinationInput, options?: RequestOptions): Promise<StorageDestination>;
    /** The destination, masked (`accessKeyIdHint`, never the secret). `not_found` when there is none. */
    getStorageDestination(options?: RequestOptions): Promise<StorageDestination>;
    /** `conflict` while a recording is active or parts are still being delivered. What was recorded stays with the tenant. */
    deleteStorageDestination(options?: RequestOptions): Promise<void>;
    /**
     * `tenant_endpoint` only: a new `deliverySecret`, returned ONCE in the response. IACL signs
     * with the new and the previous one for 24 h. `conflict` with an `s3` destination.
     */
    rotateStorageDestinationSecret(options?: RequestOptions): Promise<StorageDestination>;
    /**
     * Start recording each person's audio to the tenant bucket. Idempotent: sends an
     * `Idempotency-Key` (generated if you give none) and is retried on 429/5xx.
     */
    startRecording(meetingId: MeetingId, body?: StartRecordingInput, options?: StartRecordingOptions): Promise<Recording>;
    /** The recordings of a meeting. */
    listRecordings(meetingId: MeetingId, options?: RequestOptions): Promise<RecordingList>;
    /** One recording, with its parts once it is `ready`. */
    getRecording(meetingId: MeetingId, recordingId: RecordingId, options?: RequestOptions): Promise<Recording>;
    /** Stop recording (`recording.stopped`); `recording.ready` follows once every part is in the bucket. Not retried. */
    stopRecording(meetingId: MeetingId, recordingId: RecordingId, options?: RequestOptions): Promise<Recording>;
    /**
     * Ask for the transcription of a recording that is `ready` (202, `queued`). The result goes
     * to the tenant bucket and `transcript.ready` announces it. Not retried: a repeat while one
     * is queued answers `conflict` with `details.transcriptionId`.
     */
    requestTranscription(meetingId: MeetingId, recordingId: RecordingId, body?: TranscriptionInput, options?: RequestOptions): Promise<Transcription>;
    /** The transcriptions of a recording. */
    listTranscriptions(meetingId: MeetingId, recordingId: RecordingId, options?: RequestOptions): Promise<TranscriptionList>;
    /** One transcription; the text itself is in your storage (`location`). */
    getTranscription(meetingId: MeetingId, recordingId: RecordingId, transcriptionId: TranscriptionId, options?: RequestOptions): Promise<Transcription>;
    /**
     * The `/participant/*` routes as one connection, with the `token` of its `TokenGrant`
     * (not the API key). Same `baseUrl`, `fetch`, timeouts and retries as this client.
     */
    participant(token: string): ParticipantClient;
}
/**
 * The client for your backend, with the tenant API key. It retries what is safe to retry,
 * times out, never logs the key and throws `CommsApiError` with the stable `code`.
 *
 * @example
 * ```ts
 * import { createCommsClient } from '@iaconsultinglabs/comms-server'
 *
 * const comms = createCommsClient({
 *   baseUrl: 'https://comms.example.com/v1',
 *   apiKey: process.env.IACL_COMMS_API_KEY ?? '',
 * })
 * const meeting = await comms.createMeeting({ type: 'meeting', title: 'Kick-off' })
 * ```
 */
export declare function createCommsClient(options: CommsClientOptions): CommsClient;
```

### http.d.ts

```ts
/** A `fetch` implementation (the global one by default). */
export type FetchLike = typeof fetch;
/** How retry-safe calls back off between attempts. */
export interface RetryOptions {
    /** First backoff step in ms (doubles each attempt, with full jitter). Default 250. */
    baseDelayMs?: number;
    /** Cap for one backoff step. Default 8000. */
    maxDelayMs?: number;
    /** A `Retry-After` longer than this is not waited for: the error is surfaced. Default 30000. */
    maxRetryAfterMs?: number;
}
export interface TransportConfig {
    /** The bearer credential (tenant API key, participant token or operator token). Never logged. */
    credential: string;
    baseUrl: string;
    fetch: FetchLike;
    timeoutMs: number;
    retries: number;
    retry: Required<RetryOptions>;
    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
    random: () => number;
    userAgent: string;
}
export interface RequestSpec {
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    path: string;
    query?: Record<string, string | number | boolean | readonly string[] | undefined>;
    body?: unknown;
    headers?: Record<string, string>;
    /** May this request be repeated without side effects? GET, PUT, or POST with Idempotency-Key. */
    idempotent: boolean;
    signal?: AbortSignal | undefined;
    timeoutMs?: number | undefined;
    retries?: number | undefined;
}
export declare function defaultSleep(ms: number, signal?: AbortSignal): Promise<void>;
/** Seconds or an HTTP date, as `Retry-After` allows. */
export declare function parseRetryAfter(value: string | null, nowMs: number): number | undefined;
export declare function send<T>(config: TransportConfig, spec: RequestSpec): Promise<T>;
/** The connection settings every client of this SDK shares (tenant, participant, ops). */
export interface TransportOptions {
    /** The API root including `/v1`, e.g. `https://api.comms.example.com/v1`. */
    baseUrl: string;
    /** A `fetch` implementation. Default: the global one. */
    fetch?: FetchLike;
    /** Per-attempt timeout. Default 30 000 ms. */
    timeoutMs?: number;
    /** Extra attempts for retry-safe calls. Default 2. */
    retries?: number;
    /** How the retries back off. */
    retry?: RetryOptions;
    /** Injectable for tests. */
    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
    /** Injectable for tests; returns a number in [0, 1). */
    random?: () => number;
}
/** Options of one call. */
export interface RequestOptions {
    /** Cancel the call (and its retries). */
    signal?: AbortSignal;
    /** Per-attempt timeout for this call, overriding the client's. */
    timeoutMs?: number;
    /** Overrides the client's retry count for this call (only applies when the call is retry-safe). */
    retries?: number;
}
/**
 * Validates the shared options and builds the transport. `who` names the factory in
 * error messages; `credentialName` the option that carries the bearer.
 */
export declare function createTransport(who: string, credentialName: string, credential: unknown, options: TransportOptions): TransportConfig;
export interface CallExtra {
    query?: RequestSpec['query'];
    body?: unknown;
    headers?: Record<string, string>;
    /** Default: every method but POST is retry-safe. */
    idempotent?: boolean;
    options?: RequestOptions | undefined;
}
export type Caller = <T>(method: RequestSpec['method'], path: string, extra?: CallExtra) => Promise<T>;
export declare function caller(config: TransportConfig): Caller;
/** Keeps the credential out of `console.log`/`util.inspect` and `JSON.stringify` of a client. */
export declare function redactClient(client: object, label: string, config: TransportConfig, credentialName: string): void;
```

### ai.d.ts

```ts
type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
    [K in keyof T]?: DeepPartial<T[K]>;
} : T;
/** The body of `createAiProfile`: an AI mode. Left-out `live`/`closing` fields take the contract defaults. */
export type AiProfileCreateInput = Omit<AiProfileInput, 'live' | 'closing'> & {
    /** What comes out live (captions, detections, suggestions). */
    live?: DeepPartial<NonNullable<AiProfileInput['live']>>;
    /** What comes out at the end (summary, actions, checks). */
    closing?: DeepPartial<NonNullable<AiProfileInput['closing']>>;
};
/** The body of `updateAiProfile`: only what changes; `live` and `closing` replace the whole block. */
export type AiProfileUpdateInput = Omit<AiProfilePatch, 'live' | 'closing'> & {
    /** The new live block, whole. */
    live?: DeepPartial<NonNullable<AiProfilePatch['live']>>;
    /** The new closing block, whole. */
    closing?: DeepPartial<NonNullable<AiProfilePatch['closing']>>;
};
/** The body of `requestAiClosing`: which mode, which transcription, which parts and up to when. */
export type AiClosingInput = AiClosingRequest;
/** The body of `setMeetingAiContext`: who is who and the documents the AI should know. */
export type AiContextInput = AiContext;
/** The body of `setAiContextSource`: the URL where you serve each meeting's context. */
export type AiContextSourceInput = AiContextSourceRequest;
/** The body of `updateMeetingAi`: only what changes of `settings.ai`. */
export type AiMeetingUpdateInput = AiMeetingPatch;
/** The body of `sendAiFeedback`: what you did with each proposal. */
export type AiFeedbackInput = AiFeedbackRequest;
/** The body of `setAiModelDefaults`: the account's default live and closing models. */
export type AiModelDefaultsInput = AiModelDefaultsRequest;
/** Paging for `listAiProfiles`. */
export type ListAiProfilesQuery = NonNullable<operations['listAiProfiles']['parameters']['query']>;
/** Per-call options of the idempotent AI calls (`createAiProfile`, `requestAiClosing`). */
export interface IdempotentOptions extends RequestOptions {
    /** 8-64 chars of `[A-Za-z0-9_.:-]`. Generated when absent, so a retry never does it twice. */
    idempotencyKey?: string;
}
/**
 * The meeting AI of the contract (ADR 0053). Comms proposes and never executes: these calls
 * configure the AI, give it context, ask for a closing and send back what the tenant did with
 * each proposal. While the node has no AI, every one of them throws `CommsApiError` with
 * `not_implemented` (501).
 */
export interface AiMethods {
    /**
     * IACL's AI models with their price (ADR 0055). The AI is IACL's: you pick a model from this
     * list (per meeting with `settings.ai.liveModel` / `closingModel`, or for the account with
     * `setAiModelDefaults`), never your own provider or key. Empty while the node has no AI.
     */
    listAiModels(options?: RequestOptions): Promise<AiModelList>;
    /** The models used when a meeting does not pick one, already resolved (`source`: yours or IACL's). */
    getAiModelDefaults(options?: RequestOptions): Promise<AiModelDefaults>;
    /** Both fields at once: a field left out goes back to IACL's. A model not in the catalogue is `ai_model_unavailable`. */
    setAiModelDefaults(body: AiModelDefaultsInput, options?: RequestOptions): Promise<AiModelDefaults>;
    /** Where the API asks the tenant for each meeting's context (the recommended path: Comms never stores it). */
    getAiContextSource(options?: RequestOptions): Promise<AiContextSource>;
    /** Checked with a signed `stage: check` request before it is saved (`ai_context_source_invalid`). */
    setAiContextSource(body: AiContextSourceInput, options?: RequestOptions): Promise<AiContextSource>;
    /** Stop serving context from your URL. */
    deleteAiContextSource(options?: RequestOptions): Promise<void>;
    /** Context held only in memory, up to 24 h. The answer never carries the content. */
    setMeetingAiContext(meetingId: MeetingId, body: AiContextInput, options?: RequestOptions): Promise<AiContextStatus>;
    /** Where the meeting's context will come from. Never the content. */
    getMeetingAiContext(meetingId: MeetingId, options?: RequestOptions): Promise<AiContextStatus>;
    /** Forget the context held for the meeting, before its 24 h. */
    deleteMeetingAiContext(meetingId: MeetingId, options?: RequestOptions): Promise<void>;
    /**
     * What the AI of one meeting has used so far (ADR 0057): person-minutes heard live, turns
     * evaluated, help, detections and mode results sent, closings, and the amount at the price
     * frozen when the meeting started. No content. Zeros while the node has no AI.
     *
     * @example
     * const usage = await comms.getMeetingAiUsage(meeting.id)
     * console.log(usage.realtimeMinutes, usage.help, usage.amountEur)
     */
    getMeetingAiUsage(meetingId: MeetingId, options?: RequestOptions): Promise<AiMeetingUsage>;
    /** Switch the AI of a meeting that has not ended; the change is announced to everyone in it. */
    updateMeetingAi(meetingId: MeetingId, body: AiMeetingUpdateInput, options?: RequestOptions): Promise<AiDisclosure>;
    /** Idempotent: sends an `Idempotency-Key` (generated if you give none) and is retried on 429/5xx. */
    createAiProfile(body: AiProfileCreateInput, options?: IdempotentOptions): Promise<AiProfile>;
    /** One page of your AI modes. */
    listAiProfiles(query?: ListAiProfilesQuery, options?: RequestOptions): Promise<AiProfilePage>;
    /** IACL's read-only templates (sales, project follow-up, interview). */
    listAiProfileTemplates(options?: RequestOptions): Promise<AiProfileList>;
    /** One AI mode (yours or an IACL template). */
    getAiProfile(profileId: AiProfileId, options?: RequestOptions): Promise<AiProfile>;
    /** Each change raises `version`. A template answers `forbidden`. */
    updateAiProfile(profileId: AiProfileId, body: AiProfileUpdateInput, options?: RequestOptions): Promise<AiProfile>;
    /** Delete one of your AI modes. */
    deleteAiProfile(profileId: AiProfileId, options?: RequestOptions): Promise<void>;
    /** `202`: the closing is queued. Idempotent like `createAiProfile`. */
    requestAiClosing(meetingId: MeetingId, body?: AiClosingInput, options?: IdempotentOptions): Promise<AiClosing>;
    /** The AI closings of a meeting. */
    listAiClosings(meetingId: MeetingId, options?: RequestOptions): Promise<AiClosingList>;
    /** One closing, without content (the summary is in your storage, the actions came by event). */
    getAiClosing(meetingId: MeetingId, closingId: AiClosingId, options?: RequestOptions): Promise<AiClosing>;
    /** Only the decision (accepted, edited, rejected, ignored), to measure quality. Retry-safe: a repeat replaces it. */
    sendAiFeedback(meetingId: MeetingId, body: AiFeedbackInput, options?: RequestOptions): Promise<void>;
}
export declare function idempotencyHeader(key: string | undefined): Record<string, string>;
export declare function aiMethods(call: Caller): AiMethods;
```

### keys.d.ts

```ts
/**
 * The body of `createApiKey`: a label and, optionally, `mode` (`live` by default; a `test` key
 * can only create `test` keys), `scopes` (all but `keys:manage` by default) and `limits`.
 */
export type ApiKeyCreateInput = CreateApiKeyRequest;
/** The body of `updateApiKey`: label, scopes or limits (`limits: null` removes them). */
export type ApiKeyUpdateInput = UpdateApiKeyRequest;
/** The body of `rotateApiKey`: how long the previous secret keeps working (24 h by default). */
export type ApiKeyRotateInput = RotateApiKeyRequest;
/** What `getUsage` asks for. */
export interface UsageQuery {
    /** The month, `YYYY-MM` (UTC). Without it, the current one. */
    period?: string;
    /** `apiKey` adds `byApiKey`: the usage of every key. */
    breakdown?: 'apiKey';
}
/**
 * Your account's API keys and usage (ADR 0056). Managing keys needs a key with the
 * `keys:manage` scope; reading usage, `usage:read`. The secret of a key is returned only by
 * `createApiKey` and `rotateApiKey`, once: store it in your secrets manager straight away.
 */
export interface KeyMethods {
    /**
     * Every key of the account, revoked ones included, without secrets. A `test` key only sees
     * `test` keys.
     *
     * @throws {CommsApiError} `key_scope_missing` without `keys:manage`.
     */
    listApiKeys(options?: RequestOptions): Promise<ApiKeyList>;
    /**
     * Create a key. Never retried: the secret is shown once, and a repeat would create a
     * second key.
     *
     * @example
     * ```ts
     * const { apiKey, secret } = await comms.createApiKey({ label: 'Staging', mode: 'test' })
     * // secret: iacl_test_….…  — shown only now
     * ```
     * @throws {CommsApiError} `forbidden` when a `test` key asks for a `live` one;
     *   `key_scope_missing` without `keys:manage`.
     */
    createApiKey(body: ApiKeyCreateInput, options?: RequestOptions): Promise<ApiKeyCreated>;
    /** One key, without its secret. */
    getApiKey(apiKeyId: ApiKeyId, options?: RequestOptions): Promise<ApiKey>;
    /**
     * Rename a key or change its scopes or limits. It applies from the key's next request.
     *
     * @throws {CommsApiError} `conflict` when a key would remove `keys:manage` from itself.
     */
    updateApiKey(apiKeyId: ApiKeyId, body: ApiKeyUpdateInput, options?: RequestOptions): Promise<ApiKey>;
    /**
     * Give a key a new secret without downtime: the previous one keeps working for
     * `graceSeconds` (24 h by default, 0 cuts it now, 7 days at most). Never retried.
     *
     * @example
     * ```ts
     * const { secret } = await comms.rotateApiKey(apiKeyId, { graceSeconds: 3600 })
     * // deploy `secret` everywhere within the hour
     * ```
     */
    rotateApiKey(apiKeyId: ApiKeyId, body?: ApiKeyRotateInput, options?: RequestOptions): Promise<ApiKeyCreated>;
    /**
     * Revoke a key: it stops working at once, its previous secret too. Meetings it created
     * go on.
     *
     * @throws {CommsApiError} `conflict` when a key would revoke itself.
     */
    revokeApiKey(apiKeyId: ApiKeyId, options?: RequestOptions): Promise<void>;
    /**
     * The usage of a month: live totals, `test` apart (not billable), and with
     * `breakdown: 'apiKey'` the usage of every key, with AI per model. A finished month has
     * `closed: true` and never changes again.
     *
     * @example
     * ```ts
     * const usage = await comms.getUsage({ period: '2026-10', breakdown: 'apiKey' })
     * for (const k of usage.byApiKey ?? []) console.log(k.label, k.usage.meetingMinutes)
     * ```
     */
    getUsage(query?: UsageQuery, options?: RequestOptions): Promise<Usage>;
}
/** The implementation of `KeyMethods` over the client's caller. */
export declare function keyMethods(call: Caller): KeyMethods;
```

### participant.d.ts

```ts
/** `takeover` defaults to `false`, as in the contract. */
export type ScreenShareClaimInput = Partial<ScreenShareClaimRequest>;
/** The body of `sendChatMessage`. */
export type ChatMessageInput = ChatMessageRequest;
export interface ParticipantClientOptions extends TransportOptions {
    /**
     * The `token` of a `TokenGrant`: valid for ONE connection of ONE meeting, until its
     * `expiresAt`. Everything this client does is done as that connection.
     */
    token: string;
}
/**
 * The `/participant/*` surface of the contract, called with a connection's token.
 *
 * The contract reserves these routes for the browser, which holds the token. A backend
 * that arbitrates the screen turn itself (General ERP's Radio, CR-2) can call them on
 * behalf of a connection with the token it issued; this wrapper gives that call types,
 * retries and the SDK's errors instead of a hand-written `fetch`.
 */
export interface ParticipantClient {
    /**
     * `POST /participant/chat-messages`. Retried on 429/5xx only when `clientId` is set:
     * the API de-duplicates by it, so a repeat never posts the message twice.
     */
    sendChatMessage(body: ChatMessageInput, options?: RequestOptions): Promise<ChatMessage>;
    /**
     * `POST /participant/screen-share`: take the screen turn. `screen_share_busy` (409)
     * carries `details.presenter` and `details.canTakeOver`; repeat with `{ takeover: true }`.
     * Retry-safe: claiming a turn this connection already holds answers `granted` again
     * (a retried takeover then reports `tookOverFrom: null`).
     */
    claimScreenShare(body?: ScreenShareClaimInput, options?: RequestOptions): Promise<ScreenShareGrant>;
    /** `DELETE /participant/screen-share`: give the turn back. Retry-safe; a no-op when not presenting. */
    releaseScreenShare(options?: RequestOptions): Promise<void>;
    /**
     * `POST /participant/recording`: the host starts recording from the meeting. Only `role: host`
     * and only with `settings.recording.hostControl` (`recording_not_allowed` otherwise). Not retried.
     */
    startRecordingAsHost(body?: StartRecordingRequest, options?: RequestOptions): Promise<Recording>;
    /** `DELETE /participant/recording`: the host stops the active recording (`recording_not_active` if none). */
    stopRecordingAsHost(options?: RequestOptions): Promise<Recording>;
    /**
     * `POST /participant/ai/feedback`: «useful» or «not useful» on a private suggestion
     * (`iacl.ai.suggestion`), only from a connection of a person it was sent to (`not_found`
     * otherwise). Only measures; sending it again replaces it, so it is retry-safe.
     */
    sendAiSuggestionFeedback(body: AiSuggestionFeedbackRequest, options?: RequestOptions): Promise<void>;
}
/** The `/participant/*` routes as one connection, from its token. `CommsClient.participant(token)` is the same with your client's settings. */
export declare function createParticipantClient(options: ParticipantClientOptions): ParticipantClient;
```

### ops.d.ts

```ts
type Schemas = components['schemas'];
/** The body of `createTenant`: name, plan and your reference. */
export type CreateTenantInput = Schemas['CreateTenantRequest'];
/** The body of `updateTenant`: only what changes. */
export type UpdateTenantInput = Schemas['UpdateTenantRequest'];
/** The body of `createApiKey`: a label, and optionally `mode`, `scopes` (here `keys:manage` too) and `limits`. */
export type CreateApiKeyInput = Schemas['CreateApiKeyRequest'];
/** The body of `updateApiKey`: label, scopes or limits. */
export type UpdateApiKeyInput = Schemas['UpdateApiKeyRequest'];
/** The body of `rotateApiKey`: how long the previous secret keeps working. */
export type RotateApiKeyInput = Schemas['RotateApiKeyRequest'];
/** The body of `suspendTenant`: whether meetings in progress end too. */
export type SuspendTenantInput = Schemas['SuspendTenantRequest'];
/** One page of tenants. */
export type TenantPage = Schemas['TenantPage'];
/** One tenant as listed. */
export type TenantPageItem = TenantPage['items'][number];
/** Filters and paging for `listTenants`. */
export type ListTenantsQuery = NonNullable<operations['listTenants']['parameters']['query']>;
export interface OpsClientOptions extends TransportOptions {
    /**
     * IACL's operator credential (the admin panel). Never in a tenant's backend, never in a
     * browser. `/ops/*` only answers from the allowed IPs (ADR 0013); from any other it
     * answers `not_found`, which this client surfaces as `CommsApiError` with that code.
     */
    operatorToken: string;
}
/** The `/ops/*` surface of the contract: tenants, their API keys and the platform summary. */
export interface OpsClient {
    /** The platform at a glance: nodes, tenants, alerts and AI quality. */
    getSummary(options?: RequestOptions): Promise<OpsSummary>;
    /** One page. Use `iterateTenants`/`iterateTenantPages` to walk all of them. */
    listTenants(query?: ListTenantsQuery, options?: RequestOptions): Promise<TenantPage>;
    /** Every page of tenants, following the cursor for you. */
    iterateTenantPages(query?: Omit<ListTenantsQuery, 'cursor'>, options?: RequestOptions): AsyncGenerator<TenantPage, void, undefined>;
    /** Every tenant, one by one, across pages. */
    iterateTenants(query?: Omit<ListTenantsQuery, 'cursor'>, options?: RequestOptions): AsyncGenerator<TenantPageItem, void, undefined>;
    /** Never retried: the contract gives this POST no `Idempotency-Key`, so a repeat could create two tenants. */
    createTenant(body: CreateTenantInput, options?: RequestOptions): Promise<Tenant>;
    /** One tenant with its API keys, this month's usage and its webhook health. */
    getTenant(tenantId: TenantId, options?: RequestOptions): Promise<TenantDetail>;
    /** Change the plan, the name, the `externalRef` or suspend (`status`). Retry-safe: the patch sets values. */
    updateTenant(tenantId: TenantId, body: UpdateTenantInput, options?: RequestOptions): Promise<Tenant>;
    /**
     * Cut a tenant's access (ADR 0056): every key stops working at once (`tenant_suspended`).
     * Meetings in progress go on until they end, unless `endActiveMeetings: true`.
     */
    suspendTenant(tenantId: TenantId, body?: SuspendTenantInput, options?: RequestOptions): Promise<Tenant>;
    /** Give a suspended tenant its access back: its non-revoked keys work again at once. */
    reactivateTenant(tenantId: TenantId, options?: RequestOptions): Promise<Tenant>;
    /**
     * What billing lets a tenant do (ADR 0061): `liveKeys` (it may create live keys; without a paid
     * plan, `live_keys_not_allowed`) and `hold` (a failed payment: new live meetings get
     * `billing_hold`, meetings in progress and test keys go on). Same as `updateTenant({ billing })`.
     */
    setTenantBilling(tenantId: TenantId, billing: TenantBillingPatch, options?: RequestOptions): Promise<Tenant>;
    /** A tenant's usage in a month (the current one without `period`), always per key and per AI model. */
    getTenantUsage(tenantId: TenantId, query?: {
        period?: string;
    }, options?: RequestOptions): Promise<Usage>;
    /**
     * A tenant's configuration in one mode (ADR 0059): webhook, recording destination, context
     * source, default models and how many profiles and detectors it has. Read-only and without
     * secrets. `mode` is required so nobody mistakes the test configuration for the live one.
     */
    getTenantConfig(tenantId: TenantId, query: {
        mode: ApiKeyMode;
    }, options?: RequestOptions): Promise<TenantConfig>;
    /** A tenant's keys, revoked ones included, without secrets. */
    listApiKeys(tenantId: TenantId, options?: RequestOptions): Promise<ApiKeyList>;
    /**
     * Never retried: the secret is shown once, and a repeat would create a second key. The first
     * key of a new client usually gets `keys:manage` so the client manages the rest itself.
     */
    createApiKey(tenantId: TenantId, body: CreateApiKeyInput, options?: RequestOptions): Promise<ApiKeyCreated>;
    /** Rename a key or change its scopes or limits. */
    updateApiKey(tenantId: TenantId, apiKeyId: ApiKeyId, body: UpdateApiKeyInput, options?: RequestOptions): Promise<ApiKey>;
    /** A new secret, shown once; the previous one works for `graceSeconds` more (24 h by default). Never retried. */
    rotateApiKey(tenantId: TenantId, apiKeyId: ApiKeyId, body?: RotateApiKeyInput, options?: RequestOptions): Promise<ApiKeyCreated>;
    /** Revoke a key: it stops working at once. */
    revokeApiKey(tenantId: TenantId, apiKeyId: ApiKeyId, options?: RequestOptions): Promise<void>;
}
/** The client for IACL's operation panel (`/ops/*`), with the operator token. Not for tenants. */
export declare function createOpsClient(options: OpsClientOptions): OpsClient;
```

### errors.d.ts

```ts
/** Base of every error this SDK throws on purpose. */
export declare class CommsError extends Error {
    /** The class name, also after bundling: check it instead of `instanceof` across realms. */
    name: string;
}
/** What a `CommsApiError` is built from. */
export interface CommsApiErrorInit {
    /** The stable error code. */
    code: ErrorCode;
    /** The HTTP status. */
    status: number;
    /** The human-readable message. */
    message: string;
    /** The request id, for support. */
    requestId?: string | undefined;
    /** The error details (`error.details`). */
    details?: Record<string, unknown> | undefined;
    /** The `code` the server sent when it is not in this SDK's `ErrorCode` list (a newer MINOR). */
    rawCode?: string | undefined;
    /** From `Retry-After`. */
    retryAfterSeconds?: number | undefined;
}
/**
 * The API answered with an error. Decide by `code` (ADR 0011), never by `message`.
 * `requestId` is what support needs.
 *
 * @example
 * ```ts
 * import { isCommsApiError } from '@iaconsultinglabs/comms-server'
 *
 * try {
 *   await comms.endMeeting(meetingId)
 * } catch (error) {
 *   if (isCommsApiError(error, 'not_found')) console.log('Already gone')
 *   else throw error
 * }
 * ```
 */
export declare class CommsApiError extends CommsError {
    /** Always `CommsApiError` (or the subclass name). */
    name: string;
    /** The stable error code: decide by this. */
    readonly code: ErrorCode;
    /** The HTTP status. */
    readonly status: number;
    /** The request id the API returned, for support. */
    readonly requestId: string | undefined;
    /** Extra details of the error (e.g. `transcriptionId` on a `conflict`, `reason` on `storage_destination_invalid`). */
    readonly details: Record<string, unknown> | undefined;
    /** Set only when the server sent a code this SDK version does not know. */
    readonly rawCode: string | undefined;
    /** From the `Retry-After` header, when present. */
    readonly retryAfterSeconds: number | undefined;
    constructor(init: CommsApiErrorInit);
}
/** `cursor_expired`: the cursor is older than the 72 h window. Rebuild state, then resume. */
export declare class CursorExpiredError extends CommsApiError {
    /** Always `CursorExpiredError`. */
    name: string;
}
/** The request never got an answer (connection error, DNS, timeout). */
export declare class CommsNetworkError extends CommsError {
    /** Always `CommsNetworkError`. */
    name: string;
    /** The attempt ran out of time (`timeoutMs`), as opposed to failing to connect. */
    readonly timedOut: boolean;
    constructor(message: string, options?: {
        cause?: unknown;
        timedOut?: boolean;
    });
}
export declare function isErrorCode(value: unknown): value is ErrorCode;
/** Type guard; with `code`, also narrows to that code. */
export declare function isCommsApiError(err: unknown, code?: ErrorCode): err is CommsApiError;
/** The closest contract code for an answer that has no usable error body (a proxy's 502...). */
export declare function codeForStatus(status: number): ErrorCode;
```

### webhooks.d.ts

```ts
/**
 * Why a delivery was rejected. `raw_body_required`: you passed a parsed object; give the raw
 * body. `missing_signature`/`malformed_signature`: no or bad `IACL-Signature`. `no_secret`: no
 * secret configured. `signature_mismatch`: wrong secret or altered body. `timestamp_too_old`/
 * `timestamp_in_future`: outside the tolerance (replay protection). `invalid_body`/
 * `invalid_envelope`: not a Comms event. `unknown_event_type`/`unsupported_event_version`:
 * authentic but newer than this SDK (`ignorable`).
 */
export type WebhookFailureReason = 'raw_body_required' | 'missing_signature' | 'malformed_signature' | 'no_secret' | 'signature_mismatch' | 'timestamp_too_old' | 'timestamp_in_future' | 'invalid_body' | 'invalid_envelope' | 'unknown_event_type' | 'unsupported_event_version';
/** A webhook delivery that must not be trusted (or, if `ignorable`, cannot be understood yet). */
export declare class WebhookVerificationError extends CommsError {
    /** Always `WebhookVerificationError`. */
    name: string;
    /** Why it was rejected. */
    readonly reason: WebhookFailureReason;
    /** The signature was valid; this SDK just does not know the event. Reply 2xx and ignore it. */
    readonly ignorable: boolean;
    /** Present when the signature was valid and the envelope parsed (so `ignorable` cases can be logged). */
    readonly envelope: Readonly<Record<string, unknown>> | undefined;
    constructor(reason: WebhookFailureReason, message: string, envelope?: Record<string, unknown>);
}
/** The request headers: a `Headers` object (fetch, Hono…) or a plain record (Express, Fastify, Node `IncomingMessage`). */
export type HeadersInput = {
    /** Read one header, case-insensitively. */
    get(name: string): string | null;
} | Readonly<Record<string, string | readonly string[] | undefined>>;
/** What `verifyWebhook` and `verifyWebhookSignature` need. */
export interface VerifyWebhookInput {
    /** The body exactly as it arrived (bytes or string). Never `JSON.stringify(req.body)`. */
    rawBody: string | Uint8Array;
    /** The request headers (`IACL-Signature` is read from them). */
    headers: HeadersInput;
    /** Current secret, or current + previous during a rotation. Any one may match. */
    secrets: string | readonly string[];
    /** Default 300 s (`WEBHOOK_TOLERANCE_SECONDS`). */
    toleranceSeconds?: number;
    /** Clock, in milliseconds since the epoch (or a Date). For tests. */
    now?: () => number | Date;
}
/** An `IACL-Signature` header, parsed. */
export interface ParsedSignature {
    /** `t`: when it was signed, in Unix seconds. */
    timestamp: number;
    /** Every `v1` value (two during a secret rotation). */
    signatures: string[];
}
/** Strict parser of `t=<unix>,v1=<hex>[,v1=<hex>...]`. */
export declare function parseSignatureHeader(header: string): ParsedSignature;
/** `v1` for `secret`: lowercase hex of HMAC-SHA256 over `${t}.${rawBody}`. */
export declare function computeSignature(secret: string, timestamp: number | string, rawBody: string | Uint8Array): string;
/**
 * Checks only the signature and the clock of a request signed like a webhook (`IACL-Signature`
 * over `${t}.${rawBody}`): what IACL also uses to call YOUR context source (ADR 0053). Throws
 * `WebhookVerificationError`. `verifyWebhook` does this and then checks the event envelope.
 */
export declare function verifyWebhookSignature(input: VerifyWebhookInput): void;
/**
 * Checks the signature, the clock and the envelope of a webhook delivery and returns the
 * typed event. Throws `WebhookVerificationError` otherwise.
 *
 * The envelope shape is checked here (ids, `version`, `data` is an object, known `type`).
 * The per-type `data` schema is not re-validated at runtime: the signature already proves
 * IACL produced it, and the generated types describe it. Add your own validation in
 * `onEvent` if you want belt and braces.
 */
export declare function verifyWebhook(input: VerifyWebhookInput): AnyEvent;
```

### recordings.d.ts

```ts
/**
 * Which object: `partId` is `audio-1`, `video-2`, `mixed`, `manifest`, `transcripts/trn_….json|.md` or
 * `summaries/acl_….json|.md`. `recordingId` is the recording (`rec_…`), or the meeting (`mtg_…`) for a
 * live transcript and for the AI closing made from it, which have no recording.
 */
export interface RecordingObjectRef {
    /** The recording (`rec_…`), or the meeting (`mtg_…`) for what has no recording. */
    recordingId: string;
    /** The part within it (`audio-1`, `transcripts/trn_….json`…). */
    partId: string;
}
/** What the store knows of a stored object. */
export interface RecordingObjectInfo {
    /** Its size in bytes. */
    sizeBytes: number;
    /** Lowercase hex sha256 of the bytes. */
    sha256: string;
    /** Its media type (`audio/ogg`, `application/json`…). */
    contentType: string;
}
/** What the store gets with a new object to write. */
export interface RecordingPutInfo extends RecordingObjectInfo {
    /** `audio`, `video`, `mixed`, `manifest`, `transcript` or `summary` (`IACL-Part-Kind`). */
    kind: string;
    /** The person of an audio or video part (`IACL-Person-Id`). */
    personId: string | null;
}
/**
 * Where the delivered files live. Implement it over your disk, your database or your bucket.
 *
 * `put` receives the body as an async iterable that THROWS at the end if the bytes do not
 * match the announced length and sha256: write to a temporary place and only make the object
 * visible once the iterable has finished without throwing. The handler never calls `put` for
 * an object that `head` already reports.
 */
export interface RecordingStore {
    /** What is stored under `ref`, or `null` if nothing. */
    head(ref: RecordingObjectRef): MaybePromise<RecordingObjectInfo | null>;
    /** Write a new object. Make it visible only once `body` finished without throwing. */
    put(ref: RecordingObjectRef, body: AsyncIterable<Uint8Array>, info: RecordingPutInfo): MaybePromise<void>;
    /** Read an object back (IACL reads parts to transcribe them), or `null` if nothing. */
    get(ref: RecordingObjectRef): MaybePromise<{
        /** The bytes. */
        body: AsyncIterable<Uint8Array>;
        /** What is known of them. */
        info: RecordingObjectInfo;
    } | null>;
}
/**
 * Why a delivery request was refused: the signature reasons of the webhooks, plus
 * `bad_request` (unknown path), `length_required`/`too_large`/`length_mismatch`/`sha256_mismatch`
 * (the body), `conflict` (the same part with another sha256), `not_found` (a `GET` of something
 * you do not have), `method_not_allowed` and `store_failed` (your store threw).
 */
export type RecordingIngestFailure = 'missing_signature' | 'malformed_signature' | 'no_secret' | 'signature_mismatch' | 'timestamp_too_old' | 'timestamp_in_future' | 'bad_request' | 'length_required' | 'too_large' | 'sha256_mismatch' | 'length_mismatch' | 'conflict' | 'not_found' | 'method_not_allowed' | 'store_failed';
/** How `createRecordingIngestHandler` verifies and stores deliveries. */
export interface RecordingIngestOptions {
    /** The current `deliverySecret`, or current + previous during a rotation. A function loads them per request. */
    secrets: string | readonly string[] | (() => MaybePromise<string | readonly string[]>);
    /** Where the files go: yours, or `createFileRecordingStore(dir)`. */
    store: RecordingStore;
    /** Default 300 s (`RECORDING_DELIVERY_TOLERANCE_SECONDS`). */
    toleranceSeconds?: number;
    /** Refuse bodies above this (413). Default: no limit. */
    maxBytes?: number;
    /**
     * When a proxy strips part of the path before your app sees it, the part it strips
     * (`/api`): the signature covers the path IACL sent.
     */
    pathPrefix?: string;
    /** For tests: milliseconds since the epoch. */
    now?: () => number;
    /** Every refused request and every store failure. Never throws into the response. */
    onError?: (error: {
        reason: RecordingIngestFailure;
        message: string;
        ref?: RecordingObjectRef;
    }) => void;
    /** After a part is stored for the first time (not on idempotent repeats). */
    onStored?: (ref: RecordingObjectRef, info: RecordingPutInfo) => MaybePromise<void>;
}
/** A request to the ingest endpoint, framework-agnostic. */
export interface RecordingIngestRequest {
    /** `PUT`, `GET` or `HEAD`. */
    method: string;
    /** The URL path as received (the query, if any, is ignored). */
    path: string;
    /** The request headers. */
    headers: HeadersInput;
    /** The request body (`PUT`). Not needed for `GET` and `HEAD`. */
    body?: AsyncIterable<Uint8Array> | null;
}
/** The answer to send back. */
export interface RecordingIngestResponse {
    /** The HTTP status. */
    status: number;
    /** The response headers. */
    headers: Record<string, string>;
    /** JSON text, or the file for `GET`. */
    body?: string | AsyncIterable<Uint8Array>;
}
/** The recording delivery endpoint, ready to plug into any framework. */
export interface RecordingIngestHandler {
    /** Framework-agnostic entry: verify, store and answer one request. */
    handle(request: RecordingIngestRequest): Promise<RecordingIngestResponse>;
    /** A `node:http` listener (Express, Fastify's `raw`…). Do NOT put a body parser in front of it. */
    nodeListener(): (req: IncomingMessage, res: ServerResponse) => void;
}
/** `v1` for one secret: lowercase hex HMAC-SHA256 over `<t>.<METHOD>.<path>.<sha256>`. */
export declare function computeRecordingSignature(secret: string, timestamp: number, method: string, path: string, sha256?: string): string;
/** The whole `IACL-Signature` header, as IACL sends it (for tests and for your own tools). */
export declare function signRecordingDelivery(secrets: string | readonly string[], timestamp: number, method: string, path: string, sha256?: string): string;
/** What `verifyRecordingDelivery` needs. */
export interface VerifyRecordingDeliveryInput {
    /** The request method. */
    method: string;
    /** The URL path as IACL sent it (without the query). */
    path: string;
    /** The request headers. */
    headers: HeadersInput;
    /** The `deliverySecret`, or current + previous during a rotation. */
    secrets: string | readonly string[];
    /** Default 300 s. */
    toleranceSeconds?: number;
    /** Clock in milliseconds, for tests. */
    now?: () => number;
}
/**
 * Checks `IACL-Signature` of a delivery request. Throws `WebhookVerificationError` (same
 * reasons as the webhooks). For `PUT`, the signed sha256 is the `IACL-Content-SHA256` header:
 * you still have to check the body against it (the handler does).
 */
export declare function verifyRecordingDelivery(input: VerifyRecordingDeliveryInput): void;
/**
 * The endpoint that receives recordings, transcripts and AI closings from IACL Comms
 * (destination `tenant_endpoint`). It checks the signature, the length and the sha256, stores
 * each file once and answers the receipt IACL needs to delete its copy.
 *
 * @example
 * ```ts
 * import { createServer } from 'node:http'
 * import { createFileRecordingStore, createRecordingIngestHandler } from '@iaconsultinglabs/comms-server'
 *
 * const ingest = createRecordingIngestHandler({
 *   secrets: process.env.IACL_COMMS_DELIVERY_SECRET ?? '',
 *   store: createFileRecordingStore('/var/lib/my-app/recordings'),
 *   onStored: (ref) => console.log('stored', ref.recordingId, ref.partId),
 * })
 * // No body parser in front: the handler reads the stream. The path IACL calls must reach it
 * // whole (with Express, `app.all('/comms/recordings/*', …)`, not `app.use`, or set `pathPrefix`).
 * createServer(ingest.nodeListener()).listen(8080)
 * ```
 */
export declare function createRecordingIngestHandler(options: RecordingIngestOptions): RecordingIngestHandler;
/**
 * A `RecordingStore` on a directory: `<dir>/<recordingId>/<partId>` plus `<partId>.meta.json`
 * (size, sha256, type). Writes go to a temporary file and are renamed only when the body
 * was complete and matched: a broken delivery leaves nothing behind. Keep `dir` out of any
 * web root; serve the files through your own authorization.
 */
export declare function createFileRecordingStore(dir: string): RecordingStore;
```

### ai-context.d.ts

```ts
/**
 * The tenant side of the AI context source (ADR 0053 §1): IACL Comms never stores the
 * context of a meeting; when the AI needs it (at the start of each closing), the API asks
 * YOUR endpoint with a `POST` signed like a webhook (`IACL-Signature`, your WEBHOOK secret)
 * and forgets it afterwards. This is the reference endpoint, so you do not reimplement the
 * checks:
 *
 * - the signature and the clock (300 s), with the current and the previous webhook secret
 *   during a rotation;
 * - the body (`AiContextRequest`: `meetingId`, `externalRef`, `contextRef`, `stage`);
 * - `stage: check` (sent when you register the URL with `setAiContextSource`) answers `204`
 *   without calling you;
 * - your `resolve` returns the `AiContext` (→ `200`) or `null` (→ `204`, no context).
 *
 * Give the AI only what helps to understand the meeting, and keep it under 200 kB: Comms
 * drops a larger or malformed answer and goes on without context.
 */
/** How `createAiContextSourceHandler` verifies requests and finds the context. */
export interface AiContextSourceHandlerOptions {
    /** Your WEBHOOK secret (current, or current + previous during a rotation). A function loads them per request. */
    secrets: string | readonly string[] | (() => MaybePromise<string | readonly string[]>);
    /** The context of this meeting, or `null` when you have none. Use `contextRef`/`externalRef` to find it. */
    resolve: (request: AiContextRequest) => MaybePromise<AiContext | null>;
    /** How far the signature clock may be from yours. Default 300 s. */
    toleranceSeconds?: number;
    /** Clock, for tests. */
    now?: () => number | Date;
    /** Every refused request and every failing `resolve`. Never throws into the response. */
    onError?: (error: unknown) => void;
}
/** The answer to send back. */
export interface AiContextSourceResponse {
    /** `200` with the context, `204` without, `4xx` when refused. */
    status: number;
    /** The response headers. */
    headers: Record<string, string>;
    /** The JSON body, with `200`. */
    body?: string;
}
/** Your AI context endpoint, ready to plug into any framework. */
export interface AiContextSourceHandler {
    /** Framework-agnostic entry: the RAW body and the headers. */
    handle(input: {
        method?: string;
        rawBody: string | Uint8Array;
        headers: HeadersInput;
    }): Promise<AiContextSourceResponse>;
    /** A `node:http` listener. Do NOT put a JSON body parser in front of it: the signature covers the raw bytes. */
    nodeListener(): (req: IncomingMessage, res: ServerResponse) => void;
}
/**
 * The endpoint where Comms asks for each meeting's AI context, so Comms never stores it.
 * Register its URL with `setAiContextSource`.
 *
 * @example
 * ```ts
 * import { createServer } from 'node:http'
 * import { createAiContextSourceHandler } from '@iaconsultinglabs/comms-server'
 *
 * const context = createAiContextSourceHandler({
 *   secrets: process.env.IACL_COMMS_WEBHOOK_SECRET ?? '',
 *   // Find the meeting by the externalRef you gave it, and say who is who.
 *   resolve: async (request) => ({
 *     participants: [{ personId: 'u_1', name: 'Ana', role: 'Sales' }],
 *     documents: [{ title: 'Offer', text: 'Price: 1,200 EUR per month.' }],
 *   }),
 * })
 * createServer(context.nodeListener()).listen(8080)
 * ```
 */
export declare function createAiContextSourceHandler(options: AiContextSourceHandlerOptions): AiContextSourceHandler;
```

### handler.d.ts

```ts
/** What `onEvent` and the per-type handlers get besides the event. */
export interface WebhookContext {
    /** From `IACL-Delivery-Attempt`: 1 on the first delivery. Informational: the header is not signed. */
    attempt: number | undefined;
}
/** One typed handler per event type: `{ 'meeting.ended': (event) => … }`. */
export type EventHandlers = {
    [T in EventType]?: (event: EventOf<T>, context: WebhookContext) => MaybePromise<void>;
};
/** How `createWebhookHandler` verifies, deduplicates and dispatches deliveries. */
export interface WebhookHandlerOptions {
    /** Current secret, or current + previous during a rotation. A function lets you load them per request. */
    secrets: string | readonly string[] | (() => MaybePromise<string | readonly string[]>);
    /** Called once per new event. Throwing makes the delivery fail (500) so IACL retries it. */
    onEvent?: (event: AnyEvent, context: WebhookContext) => MaybePromise<void>;
    /** Typed alternative to `onEvent`: one handler per event type. Both may be given; this runs first. */
    handlers?: EventHandlers;
    /**
     * Deduplication by event `id`. Default: an in-memory store (single process only).
     * `false` turns it off (only if your handlers are idempotent on their own).
     */
    idempotency?: IdempotencyStore | false;
    /** How long an id is remembered. Default twice the 72 h delivery window. */
    idempotencyTtlSeconds?: number;
    /** How far the signature clock may be from yours. Default 300 s (`WEBHOOK_TOLERANCE_SECONDS`). */
    toleranceSeconds?: number;
    /** Clock, for tests. */
    now?: () => number | Date;
    /** An authentic event of a type or version this SDK does not know. It is acknowledged (2xx). */
    onUnknownEvent?: (error: WebhookVerificationError) => MaybePromise<void>;
    /** Called for every rejected delivery and every failing handler. Never throws into the response. */
    onError?: (error: unknown) => void;
}
/**
 * What happened to a delivery: `processed` (200), `duplicate` (200, already processed),
 * `ignored` (200, authentic but unknown to this SDK), `rejected` (400/401/500, not trusted),
 * `failed` (500, a handler threw: IACL retries) or `in_flight` (409, the same event is being
 * processed right now: IACL retries).
 */
export type WebhookOutcome = 'processed' | 'duplicate' | 'ignored' | 'rejected' | 'failed' | 'in_flight';
/** The answer `handle()` computed: send `status` and `body` as JSON. */
export interface WebhookResult {
    /** HTTP status to answer with. */
    status: number;
    /** JSON body to answer with. Never contains secrets or internal error messages. */
    body: {
        /** The delivery was accepted (any 2xx). */
        received: boolean;
        /** What happened. */
        outcome: WebhookOutcome;
        /** Why, when it was not processed (`signature_mismatch`, `handler_failed`…). */
        reason?: string;
    };
    /** What happened (same as `body.outcome`). */
    outcome: WebhookOutcome;
    /** The verified event (also for `duplicate`). */
    event?: AnyEvent;
}
/** A webhook endpoint ready to plug into any framework. */
export interface WebhookHandler {
    /** Framework-agnostic entry: give it the RAW body and the headers, answer with `status` and `body`. */
    handle(input: {
        rawBody: string | Uint8Array;
        headers: HeadersInput;
    }): Promise<WebhookResult>;
    /**
     * A `node:http` listener. Reads the body from the stream, or uses `req.body` when it is
     * already a Buffer/string (Express with `express.raw()`). It must NOT sit behind `express.json()`.
     */
    nodeListener(): (req: IncomingMessage & {
        body?: unknown;
    }, res: ServerResponse) => void;
}
/**
 * Your webhook endpoint: verifies the signature and the clock, deduplicates by event id and calls
 * your handlers once per event. Answers 2xx only when your handlers succeeded, so IACL retries
 * what failed.
 *
 * @example
 * ```ts
 * import { createServer } from 'node:http'
 * import { createWebhookHandler } from '@iaconsultinglabs/comms-server'
 *
 * const webhooks = createWebhookHandler({
 *   secrets: process.env.IACL_COMMS_WEBHOOK_SECRET ?? '',
 *   handlers: {
 *     'meeting.ended': async (event) => console.log('ended', event.data.meetingId),
 *   },
 * })
 * // It reads the raw body itself. With Express: `express.raw()`, never `express.json()`.
 * createServer(webhooks.nodeListener()).listen(8080)
 * ```
 */
export declare function createWebhookHandler(options: WebhookHandlerOptions): WebhookHandler;
```

### idempotency.d.ts

```ts
/** A value or a promise of it: your store or handler may be sync or async. */
export type MaybePromise<T> = T | Promise<T>;
/**
 * Remembers which event ids were already processed. Deliveries are "at least once"
 * (ADR 0005): the same `id` can arrive twice, and reconciliation can replay it.
 *
 * Implement it on the storage you already have. Mongo: a collection with a unique
 * index on `_id` (the event id) and a TTL index on `expiresAt`; `seen` is a `findOne`,
 * `remember` an upsert. Redis: `seen` is `EXISTS evt:<id>`, `remember` is
 * `SET evt:<id> 1 EX <ttlSeconds>`. See the README for complete examples.
 */
export interface IdempotencyStore {
    /** Was this event id already processed (and not expired)? */
    seen(id: string): MaybePromise<boolean>;
    /** Remember that this event id was processed, for `ttlSeconds`. */
    remember(id: string, ttlSeconds: number): MaybePromise<void>;
}
/**
 * How long a processed id is remembered by default: twice the delivery/reconcile
 * window, so a replay can never outlive the memory of it.
 */
export declare const DEFAULT_IDEMPOTENCY_TTL_SECONDS: number;
/** Options of `MemoryIdempotencyStore`. */
export interface MemoryIdempotencyStoreOptions {
    /** Upper bound on remembered ids; the oldest are dropped first. Default 100 000. */
    maxEntries?: number;
    /** Clock in milliseconds, for tests. */
    now?: () => number;
}
/** In-process store with TTL. Good for one process; use a shared store when you scale out. */
export declare class MemoryIdempotencyStore implements IdempotencyStore {
    #private;
    constructor(options?: MemoryIdempotencyStoreOptions);
    /** How many ids are remembered now (expired ones included until the next prune). */
    get size(): number;
    /** Was this id processed and not expired? */
    seen(id: string): boolean;
    /** Remember this id for `ttlSeconds`, dropping the oldest past `maxEntries`. */
    remember(id: string, ttlSeconds: number): void;
}
/** `processed`: `fn` ran and succeeded. `duplicate`: already processed, skipped. `in_flight`: the same id is running right now. */
export type ProcessOutcome = 'processed' | 'duplicate' | 'in_flight';
/**
 * Runs `fn` once per event id: skips what the store has seen, refuses a second
 * concurrent run of the same id, and remembers the id only after `fn` succeeded
 * (a failed run is retried, which is what "at least once" needs).
 *
 * The in-flight guard is per instance. Across processes, make `fn`'s own writes
 * idempotent (see the README).
 */
export declare class IdempotentProcessor {
    #private;
    private readonly store;
    private readonly ttlSeconds;
    constructor(store: IdempotencyStore, ttlSeconds?: number);
    /** Run `fn` for this event id unless it was already processed or is running. If `fn` throws, the id is not remembered and the error propagates. */
    run(id: string, fn: () => MaybePromise<void>): Promise<ProcessOutcome>;
}
```

### reconcile.d.ts

```ts
/** Where reconciliation remembers how far it got. Persist it durably (a row, a Mongo document...). */
export interface CursorStore {
    /** The last stored cursor, or nothing to start from the oldest retained event. */
    get(): MaybePromise<string | null | undefined>;
    /** Store the cursor after a fully processed page. */
    set(cursor: string): MaybePromise<void>;
}
/** A trivial in-memory cursor store, for tests and scripts. */
export declare class MemoryCursorStore implements CursorStore {
    private cursor;
    constructor(cursor?: string | null);
    /** The cursor in memory. */
    get(): string | null;
    /** Keep the cursor in memory. */
    set(cursor: string): void;
}
/** What `onCursorExpired` gets: the cursor that expired and where reconciliation will resume. */
export interface CursorExpiredContext {
    /** The cursor that no longer works. */
    staleCursor: string;
    /** Where reconciliation resumes once you have rebuilt: the current head of the event stream. */
    resumeCursor: string;
    /** The error the API returned. */
    error: CursorExpiredError;
}
/** What `reconcile` needs. */
export interface ReconcileOptions {
    /** Your `CommsClient` (only `listEvents` is used). */
    client: Pick<CommsClient, 'listEvents'>;
    /** Where the cursor is kept between runs. Persist it durably. */
    cursorStore: CursorStore;
    /** Called in order, once per event id. Throwing stops the run; the cursor stays before this page. */
    onEvent: (event: AnyEvent) => MaybePromise<void>;
    /**
     * The cursor is older than 72 h: events were lost. Rebuild your state from
     * `listMeetings`/`getMeeting` here. The head of the stream is captured BEFORE this runs, so
     * anything that happens during the rebuild is replayed afterwards instead of lost. Without
     * this callback, `CursorExpiredError` is thrown.
     */
    onCursorExpired?: (context: CursorExpiredContext) => MaybePromise<void>;
    /** Share the store with `createWebhookHandler` so an event delivered twice by both paths runs once. */
    idempotency?: IdempotencyStore;
    /** How long an id is remembered. Default twice the 72 h window. */
    idempotencyTtlSeconds?: number;
    /** Only these event types. Default: all. */
    types?: readonly EventType[];
    /** Page size, 1-200. */
    limit?: number;
    /** Stop between pages. */
    signal?: AbortSignal;
}
/** What a `reconcile` run did. */
export interface ReconcileResult {
    /** Events your `onEvent` processed. */
    processed: number;
    /** Events skipped because they were already processed (by a webhook or an earlier run). */
    duplicates: number;
    /** Pages read. */
    pages: number;
    /** The cursor persisted at the end (null if there were never any events). */
    cursor: string | null;
    /** True when `onCursorExpired` ran. */
    rebuilt: boolean;
}
/**
 * Catches up on events missed by the webhook (your server was down, a delivery was lost).
 * Reads `listEvents` from the stored cursor, runs `onEvent` in order with deduplication, and
 * stores the cursor after each fully processed page. Safe to run on a timer and at startup.
 */
export declare function reconcile(options: ReconcileOptions): Promise<ReconcileResult>;
```

---

## Referencia: @iaconsultinglabs/comms-core

Cliente del navegador sin framework: entrar a la reunión con un acceso, medios, chat y `meeting.ai`.

### index.d.ts

```ts
/**
 * @iaconsultinglabs/comms-core — cliente de IACL Comms independiente de framework.
 *
 * Un solo motor de reunión (`createMeeting`) para miembros e invitados: lo único
 * que cambia es cómo consigue el token el integrador (`TokenSource`). El
 * servidor de medios vive en `src/adapters/` y ningún tipo ni nombre suyo sale
 * por aquí: esta es toda la API pública del paquete.
 *
 * El protocolo de la sala (temas y paquetes), la máquina de estados y las utilidades
 * de cola y reintento son internos: viven en `@iaconsultinglabs/comms-core/internal`,
 * que solo usa `comms-vue` y no sigue semver.
 */
export declare const PACKAGE_NAME: "@iaconsultinglabs/comms-core";
export { CommsMeeting, createMeeting } from './meeting.js';
export type { JoinOptions, LocalMediaState, LocalMediaStopped, LocalTracksMode, MeetingEvents, MeetingOptions, PublishSource, PublishTrackOptions, TokenReason, TokenRequestContext, TokenSource } from './meeting.js';
export type { ConnectionState, ConnectionStatus, DisconnectReason } from './state.js';
export { CLIENT_ERROR_CODES, CommsError, ScreenShareBusyError, errorFromResponse, isCommsError } from './errors.js';
export type { ClientErrorCode, CommsErrorCode } from './errors.js';
export { countPeople, groupPeople, presenterOf } from './participants.js';
export type { MeetingParticipant, ParticipantMedia, Person, Publishing } from './participants.js';
export type { VideoQuality, VideoSource, VideoView, VideoViewSize } from './video-view.js';
export { bestGrid, focusOf, stageMode } from './layout.js';
export type { GridShape, StageMode, StageTileLike } from './layout.js';
export { planStage } from './stage.js';
export type { StagePlan, StageTile } from './stage.js';
export { AI_HELP_KINDS, AI_OFF, AI_SUGGESTION_TRIGGERS, nextCaptionLines } from './ai.js';
export type { AiCaption, AiDetection, AiHelp, AiPacketEvent, AiResult, AiRoomStatus, AiSpeaker, AiSuggestion, AiSuggestionFeedback, CaptionLine, CaptionLinesOptions, KnownAiPacket, MeetingAi } from './ai.js';
export type { MeetingAiApi, MeetingAiEvents, MeetingAiState } from './ai-api.js';
export { RECORDING_OFF } from './recording.js';
export { CHAT_MAX_LENGTH } from './chat.js';
export type { ChatEntry, ChatEntryStatus } from './chat.js';
export { currentDevice, deviceKey, deviceLabel } from './identity.js';
export { devicesFrom, facingOf, isHandheld, listDevices, nextCamera, screenShareSupported } from './devices.js';
export type { DeviceList, Facing, MediaDeviceOption } from './devices.js';
export { blurSupported } from './blur/index.js';
export type { BlurAssets, BlurStrength } from './blur/index.js';
export { DEFAULT_RETRY_POLICY } from './retry.js';
export type { RetryPolicy } from './retry.js';
export { chimeJoin, chimeKnock, chimeLeave } from './tones.js';
export type { DebugEntry, DebugLevel } from './debug.js';
export type { Listener } from './emitter.js';
export type { FetchLike } from './api.js';
```

### meeting.d.ts

```ts
/**
 * Quién abre la cámara y el micro:
 *   · `'devices'` (por defecto): el motor, con `setMicrophone`/`setCamera`.
 *   · `'integrator'`: el integrador, que da sus pistas con `publishTrack()`. El
 *     motor no llama nunca a `getUserMedia`, no para sus pistas y lee el
 *     silencio de `track.enabled` (CR-8).
 */
export type LocalTracksMode = 'devices' | 'integrator';
/** Lo que el integrador puede publicar con su propia pista. */
export type PublishSource = 'microphone' | 'camera' | 'screenShare';
/** Opciones de `publishTrack()`. */
export interface PublishTrackOptions {
    /** Solo pantalla: quitar el turno a quien presenta (como `startScreenShare`). */
    readonly takeover?: boolean;
    /** Solo pantalla: el audio de la pantalla, si lo hay. */
    readonly audio?: MediaStreamTrack | null;
}
/** Para qué se pide el token. */
export type TokenReason = 'join' | 'rejoin' | 'refresh';
/** Lo que recibe el `TokenSource` en cada petición: para qué es y qué conexión había. */
export interface TokenRequestContext {
    /** `join`: entrar; `rejoin`: volver tras perder la conexión; `refresh`: renovar el token antes de que caduque. */
    readonly reason: TokenReason;
    /** La conexión que ya se tenía (al volver o al renovar), o null al entrar. */
    readonly identity: string | null;
    /** Intento de volver a entrar (0 al entrar). */
    readonly attempt: number;
}
/**
 * Cómo se consigue un token. Lo da el integrador: una llamada a SU backend,
 * que es quien llama a `POST /meetings/{id}/tokens` con su clave de API.
 */
export type TokenSource = (context: TokenRequestContext) => Promise<TokenGrant>;
/** Cómo se crea una reunión en el navegador (`createMeeting`). Solo `tokenSource` y `apiUrl` son obligatorios. */
export interface MeetingOptions {
    /** Cómo se pide el token a TU backend. Se llama al entrar, al volver tras perder la red y al renovar. */
    readonly tokenSource: TokenSource;
    /** La base de la API de Comms, con `/v1`. Para `/participant/*` (chat y turno de pantalla). */
    readonly apiUrl: string;
    /** Reproducir el audio de los demás (por defecto, sí; nunca en un aparato complementario). */
    readonly autoPlayAudio?: boolean;
    /** Dónde están el wasm y el modelo del desenfoque. Sin esto, no se ofrece desenfocar. */
    readonly blur?: BlurAssets;
    /** Cómo se vuelve a entrar tras perder la conexión. Lo que no se da, de `DEFAULT_RETRY_POLICY`. */
    readonly retry?: Partial<RetryPolicy>;
    /** Escribir en consola cada paso (el rastro se guarda siempre, ver `debugLog()`). */
    readonly debug?: boolean;
    /** Reservado para E2EE (ADR 0010): en v1 se acepta y se ignora con un aviso. */
    readonly keyProvider?: KeyProvider;
    /** Otro `fetch` para hablar con la API (por defecto, el del navegador). */
    readonly fetch?: FetchLike;
    /**
     * Quién abre la cámara y el micro. Con `'integrator'` el motor solo publica
     * lo que le dan con `publishTrack()` (CR-8). Por defecto, `'devices'`.
     */
    readonly localTracks?: LocalTracksMode;
    /** @internal Para los tests: otro transporte. */
    readonly transport?: TransportFactory;
}
/** Con qué se entra en la reunión (`join()`). */
export interface JoinOptions {
    /** Entrar con el micro abierto. Por defecto sí (en un aparato complementario, no). */
    readonly microphone?: boolean;
    /** Entrar con la cámara encendida. Por defecto sí (en un aparato complementario, no). */
    readonly camera?: boolean;
    /** El micro con el que entrar (`deviceId` de `listDevices()`). Sin él, el del sistema. */
    readonly microphoneDeviceId?: string;
    /** La cámara con la que entrar. Sin ella, la del sistema. */
    readonly cameraDeviceId?: string;
    /** Por dónde suena la reunión. Sin él, la salida del sistema. */
    readonly speakerDeviceId?: string;
    /** Entrar con el fondo desenfocado (solo si `localMedia.canBlur`). */
    readonly blur?: boolean;
}
/** Mi micro, mi cámara, mi pantalla y mis aparatos, en este momento. Cambia con el evento `localMedia`. */
export interface LocalMediaState {
    /** El micro está abierto. */
    readonly microphone: boolean;
    /** La cámara está encendida. */
    readonly camera: boolean;
    /** Estoy compartiendo pantalla. */
    readonly screenShare: boolean;
    /** El fondo de la cámara está desenfocado. */
    readonly blur: boolean;
    /** El micro elegido, o `null` si es el del sistema. */
    readonly microphoneDeviceId: string | null;
    /** La cámara elegida, o `null` si es la del sistema. */
    readonly cameraDeviceId: string | null;
    /** La salida de audio elegida, o `null` si es la del sistema. */
    readonly speakerDeviceId: string | null;
    /** El audio de los demás silenciado en este aparato. */
    readonly speakerMuted: boolean;
    /** Hacia dónde mira la cámara en un móvil (`user` o `environment`), si se sabe. */
    readonly facing: Facing | null;
    /** Operaciones en marcha (para deshabilitar el botón mientras espera). */
    readonly pending: {
        /** Se está abriendo o cerrando el micro. */
        readonly microphone: boolean;
        /** Se está encendiendo o apagando la cámara. */
        readonly camera: boolean;
        /** Se está empezando o dejando de compartir pantalla. */
        readonly screenShare: boolean;
    };
    /** Se puede desenfocar el fondo (hay `MeetingOptions.blur` y el navegador puede). */
    readonly canBlur: boolean;
    /** Este navegador puede compartir pantalla. */
    readonly canShareScreen: boolean;
    /** Quién abre la cámara y el micro (`MeetingOptions.localTracks`). */
    readonly localTracks: LocalTracksMode;
}
/** Por qué se apagó solo mi micro o mi cámara (`MeetingEvents.localMediaStopped`). */
export interface LocalMediaStopped {
    /** Qué se apagó. */
    readonly source: 'microphone' | 'camera';
    /** `permission`: el servidor ya no deja publicarla; `device`: el aparato o el sistema la cortó. */
    readonly cause: 'permission' | 'device';
}
/**
 * Los eventos de una reunión: el nombre y lo que llega. Se escuchan con `meeting.on(nombre, fn)`,
 * que devuelve la función para dejar de escuchar.
 *
 * @example
 * ```ts
 * // fragmento: `meeting` es un CommsMeeting
 * const off = meeting.on('participants', (list) => console.log(list.length))
 * meeting.on('error', (error) => console.warn(error.code))
 * off()
 * ```
 */
export interface MeetingEvents {
    /** Cambió el estado de la conexión (entrando, dentro, reconectando, fuera…). */
    state: ConnectionState;
    /** Cambió la lista de conexiones o algo de alguna (micro, cámara, quién habla, red). */
    participants: readonly MeetingParticipant[];
    /** Entró una conexión. */
    participantJoined: MeetingParticipant;
    /** Salió una conexión. */
    participantLeft: MeetingParticipant;
    /** Cambió quién habla más fuerte (`identity`), o nadie. */
    activeSpeaker: string | null;
    /** Cambió mi micro, mi cámara, mi pantalla o mis aparatos. */
    localMedia: LocalMediaState;
    /** Cambió el chat (llegó un mensaje, se confirmó o falló uno mío). Llega la lista entera. */
    chat: readonly ChatEntry[];
    /** Un mensaje nuevo de otra conexión (para avisar con un punto o un sonido). */
    chatMessage: ChatEntry;
    /** El servidor me quitó la pantalla (relevo de quien manda). */
    screenShareRevoked: {
        /** Quién la pidió y se la quedó, si se sabe. */
        readonly by: ConnectionRef | null;
    };
    /** El navegador bloqueó (o soltó) el audio por la reproducción automática: hace falta un clic y `startAudio()`. */
    audioBlocked: boolean;
    /**
     * Cambió lo que se sabe de la IA de la reunión (ADR 0050): aviso, `features`,
     * `processorPresent`, `status` y, desde el ADR 0057, si esta conexión ve la ayuda. Llega el
     * `meeting.ai` nuevo (lo mismo que `meeting.ai.on('status')`).
     */
    ai: MeetingAiApi;
    /** @deprecated Usa `meeting.ai.on('caption', …)` (ADR 0057). Se quita en 1.0. */
    aiCaption: AiCaption;
    /** @deprecated Usa `meeting.ai.on('detection', …)` (ADR 0057). Se quita en 1.0. */
    aiDetection: AiDetection;
    /** @deprecated Usa `meeting.ai.on('help', …)` (ADR 0057). Se quita en 1.0. */
    aiSuggestion: AiSuggestion;
    /** @deprecated Usa `meeting.ai.on('feedback', …)` (ADR 0057). Se quita en 1.0. */
    aiSuggestionFeedback: AiSuggestionFeedback;
    /** @deprecated Usa `meeting.ai.on('packet', …)` (ADR 0057). Se quita en 1.0. */
    aiPacket: AiPacketEvent;
    /** Empieza o deja de grabarse la reunión (ADR 0051). */
    recording: RecordingDisclosure;
    /**
     * Mi micro o mi cámara se apagaron sin que yo lo pidiera: el servidor me quitó
     * el permiso de esa fuente (`permission`) o el aparato dejó de mandar
     * (`device`: se desenchufó, el sistema lo cortó). `localMedia` ya lo dice; esto
     * es para avisar (un lector de pantalla no ve el botón cambiar).
     */
    localMediaStopped: LocalMediaStopped;
    /** Se conectó o desconectó un micro, una cámara o una salida de audio: vuelve a llamar a `listDevices()`. */
    devicesChanged: undefined;
    /** Algo falló (con su código estable). Las promesas también lo rechazan; esto es para avisar en la interfaz. */
    error: CommsError;
}
/**
 * Una reunión en el navegador: entra, publica micro, cámara y pantalla, recibe a los demás,
 * chatea, ve la grabación y la IA, y vuelve a entrar sola si se pierde la red. Se crea con
 * `createMeeting()`; los componentes de `comms-vue` están hechos sobre esta clase.
 *
 * @example
 * ```ts
 * import { createMeeting } from '@iaconsultinglabs/comms-core'
 *
 * const meeting = createMeeting({
 *   apiUrl: 'https://comms.example.com/v1',
 *   // Tu backend pide el token a Comms con su API key y te lo devuelve.
 *   tokenSource: async () => (await fetch('/api/meetings/abc/token', { method: 'POST' })).json(),
 * })
 * meeting.on('participants', (list) => console.log(list.length, 'conexiones'))
 * await meeting.join({ camera: false })
 * ```
 */
export declare class CommsMeeting extends Emitter<MeetingEvents> {
    #private;
    constructor(options: MeetingOptions);
    /** El estado de la conexión ahora (`status`, y `reason`/`error` al salir o fallar). */
    get state(): ConnectionState;
    /** La reunión, en cuanto hay token; `null` antes de entrar. */
    get meetingId(): string | null;
    /**
     * A qué aparato se pasó la llamada, cuando `state.reason` es `transferred` (`null` si el
     * otro aparato no dijo cuál es). `undefined` en cualquier otro caso.
     */
    get transferredTo(): DeviceLabel | null | undefined;
    /** Mi conexión (`Identity`), en cuanto hay token; `null` antes de entrar. */
    get identity(): string | null;
    /** Mi rol en la reunión (`host`, `member` o `guest`), en cuanto hay token. */
    get role(): Role | null;
    /** Lo que el token deja hacer a esta conexión. */
    get permissions(): SourcePermissions | null;
    /**
     * La IA de la reunión, en un solo sitio (ADR 0057): lo que todos saben de ella (con
     * `enabled`, la UI enseña SIEMPRE un indicador, también a los invitados: ADR 0050), si esta
     * conexión ve la ayuda privada (`assist`), lo que va llegando (`help`, `detections`,
     * `results`), `on`/`off` tipados, `onResult` y `sendFeedback`. Es de solo lectura.
     *
     * @example
     * ```ts
     * // fragmento: `meeting` es un CommsMeeting
     * meeting.ai.on('help', (help) => {
     *   if (help.kind === 'answer') console.log('Respuesta:', help.text, help.sources)
     * })
     * ```
     */
    get ai(): MeetingAiApi;
    /** @deprecated Usa `meeting.ai.detections` (ADR 0057). Se quita en 1.0. */
    get aiDetections(): readonly AiDetection[];
    /** @deprecated Usa `meeting.ai.help` (ADR 0057). Se quita en 1.0. */
    get aiSuggestions(): readonly AiSuggestion[];
    /** @deprecated Usa `meeting.ai.sendFeedback` (ADR 0057). Se quita en 1.0. */
    sendAiSuggestionFeedback(suggestionId: string, decision: AiSuggestionFeedbackDecision): Promise<AiSuggestionFeedback>;
    /** El tenant me excluyó de la IA en esta reunión. */
    get aiExcluded(): boolean;
    /**
     * Si se graba la reunión. Con `active`, la UI enseña SIEMPRE «Grabando», también
     * a los invitados (ADR 0051).
     */
    get recording(): RecordingDisclosure;
    /** El tenant dijo que a esta persona no se la graba. */
    get recordingExcluded(): boolean;
    /**
     * El anfitrión empieza a grabar (`POST /participant/recording`). Solo con
     * `role: host` y si la reunión tiene `settings.recording.hostControl`; si no,
     * `recording_not_allowed`. El estado se actualiza al contestar la API y con el
     * aviso que llega a toda la sala.
     */
    startRecording(kinds?: RecordingKind[]): Promise<RecordingDisclosure>;
    /** El anfitrión para la grabación (`DELETE /participant/recording`). */
    stopRecording(): Promise<RecordingDisclosure>;
    /** Todas las conexiones de la sala, la mía incluida. Una persona con dos aparatos sale dos veces: para personas, `people`. */
    get participants(): readonly MeetingParticipant[];
    /** Las personas de la sala: las conexiones agrupadas por `personId`. */
    get people(): readonly Person[];
    /**
     * Avisar de que se pinta el vídeo `source` de la conexión `identity`, y de su
     * tamaño en pantalla (`update`): así se recibe solo la calidad que hace falta,
     * y nada de lo que no se ve. Cada vista lleva su `update` al cambiar de
     * tamaño o de visibilidad, y su `release` al quitarla. Una pista que tuvo
     * vistas y se queda sin ninguna deja de recibirse; una de la que nunca se
     * informó se recibe como siempre. Las de este navegador se ignoran.
     */
    observeVideo(identity: string, source?: VideoSource): VideoView;
    /** Mi conexión dentro de la sala, o `null` si no estoy dentro. */
    get localParticipant(): MeetingParticipant | null;
    /** Quien presenta ahora (yo incluido). */
    get presenter(): MeetingParticipant | null;
    /** La conexión que habla más fuerte ahora (`identity`), o `null`. */
    get activeSpeaker(): string | null;
    /** Mi micro, cámara, pantalla y aparatos ahora. */
    get localMedia(): LocalMediaState;
    /** El chat de la sala desde que entré, el más nuevo al final. El chat no se guarda: al volver a entrar empieza vacío. */
    get chat(): readonly ChatEntry[];
    /** Quién abre la cámara y el micro (`MeetingOptions.localTracks`). */
    get localTracks(): LocalTracksMode;
    /**
     * La pista que el integrador dio para esa fuente (modo `'integrator'`), o null.
     * Sirve para medir el nivel del micro sin abrirlo otra vez.
     */
    providedTrack(source: PublishSource): MediaStreamTrack | null;
    /** El navegador bloqueó el audio de la reunión: enseña un botón que llame a `startAudio()`. */
    get audioBlocked(): boolean;
    /** Los últimos pasos de la reunión, para soporte. */
    debugLog(): readonly DebugEntry[];
    /**
     * Los micros, cámaras y salidas de audio de este aparato. Los nombres solo llegan después de
     * que la persona dé permiso de micro o de cámara.
     */
    listDevices(): Promise<DeviceList>;
    /**
     * Entrar. Si ya se está dentro (o entrando), no hace nada.
     *
     * @throws {@link CommsError} con `token_source_failed` (tu backend no dio el token),
     *   `connection_failed` (no se llegó al servidor de medios) o el código que devolvió la API al
     *   pedir el token (`meeting_ended`, `person_blocked`, `guests_not_allowed`…).
     */
    join(options?: JoinOptions): Promise<void>;
    /** Salir. Idempotente. */
    leave(): Promise<void>;
    /**
     * Volver a entrar YA con un token nuevo, sin salir de la sala: p. ej. un aparato
     * complementario que pasa a ser el principal («Pasar la llamada aquí»). El integrador
     * recibe `reason: 'join'` en su `tokenSource` y pide el token que toque (con `transfer`).
     * Mientras tanto la sala está `reconnecting`; la pantalla compartida se suelta. Sin
     * opciones, el micro se enciende y la cámara se queda como estaba.
     */
    renew(options?: {
        microphone?: boolean;
        camera?: boolean;
    }): Promise<void>;
    /** Tras `failed`: volver a intentarlo a mano (el botón «Reintentar»). */
    retry(): Promise<void>;
    /** Salir y soltar todo. La instancia no se puede volver a usar. */
    destroy(): Promise<void>;
    /**
     * Abrir o cerrar el micro. Con `localTracks: 'integrator'` no abre nada: pone
     * `enabled` a la pista que dio el integrador y avisa a la sala del silencio.
     */
    setMicrophone(enabled: boolean): Promise<void>;
    /** Abrir el micro si está cerrado, y al revés. */
    toggleMicrophone(): Promise<void>;
    /** Encender o apagar la cámara. Con pistas del integrador, como `setMicrophone`. */
    setCamera(enabled: boolean): Promise<void>;
    /** Encender la cámara si está apagada, y al revés. */
    toggleCamera(): Promise<void>;
    /** Desenfocar el fondo de la cámara (si el integrador dio `blur`). */
    setBlur(enabled: boolean): Promise<void>;
    /** Cambiar de cámara sin cortar: la publicación sigue, cambia la pista. */
    switchCamera(deviceId: string): Promise<void>;
    /** «Girar la cámara»: a la que mira al otro lado, o a la siguiente. */
    flipCamera(): Promise<void>;
    /** Cambiar de micro sin cortar. No se puede con `localTracks: 'integrator'`. */
    switchMicrophone(deviceId: string): Promise<void>;
    /**
     * Publicar una pista que ya tiene el integrador (solo con
     * `localTracks: 'integrator'`). El motor no la para nunca: es del integrador.
     *
     *   · `microphone` / `camera`: se publica (o se guarda hasta entrar, y se
     *     vuelve a publicar la MISMA al volver tras perder la red). Otra pista de
     *     la misma clase se cambia sin renegociar. Silenciar es
     *     `track.enabled = false` (o `setMicrophone(false)`): los demás lo ven
     *     silenciado. `null` deja de publicar sin parar la pista.
     *   · `screenShare`: pide el turno a la API antes de publicar, como
     *     `startScreenShare` (`ScreenShareBusyError` si presenta otro;
     *     `takeover: true` para quitárselo). `null` deja de compartir y suelta
     *     el turno. Si ya se comparte, cambia la pista sin pedir otra vez.
     *
     * Respeta los permisos por fuente del token: sin permiso, `forbidden`
     * (`screen_share_not_allowed` para la pantalla).
     */
    publishTrack(source: PublishSource, track: MediaStreamTrack | null, options?: PublishTrackOptions): Promise<void>;
    /** Elegir por dónde suena la reunión. */
    setSpeaker(deviceId: string): void;
    /** Dejar de oír la reunión en este aparato (no afecta a lo que se manda). */
    setSpeakerMuted(muted: boolean): void;
    /**
     * SOLO PARA PRUEBAS. Tira la conexión con el servidor de medios como si la
     * red la hubiera perdido del todo, para ejercitar el camino «el transporte se
     * rinde → volver a entrar con un token nuevo». Existe porque en un entorno
     * local el audio y vídeo van por loopback y la emulación de red del navegador
     * no los corta (apps/example-vue/E2E-RESULTS.md).
     */
    simulateConnectionLoss(): void;
    /** Desde un clic: suelta el audio que el navegador bloqueó por la reproducción automática. */
    startAudio(): Promise<void>;
    /**
     * Compartir pantalla. Pide el turno a la API ANTES de abrir el selector.
     * Si presenta otra conexión, lanza `ScreenShareBusyError` (con
     * `canTakeOver`); la UI pregunta y vuelve a llamar con `takeover: true`.
     */
    startScreenShare({ takeover }?: {
        takeover?: boolean;
    }): Promise<void>;
    /** Dejar de compartir y soltar el turno. Idempotente. */
    stopScreenShare(): Promise<void>;
    /**
     * Mandar un mensaje. Aparece al momento como pendiente y se confirma con la API.
     *
     * @throws {@link CommsError} con `not_connected`, `chat_not_allowed`,
     *   `invalid_message` (vacío o más largo que `CHAT_MAX_LENGTH`) o el error de la API al
     *   mandarlo (p. ej. `rate_limited`); el mensaje queda como fallido y se reintenta con `retryChat`.
     */
    sendChat(text: string): Promise<ChatEntry>;
    /** Volver a mandar un mensaje que falló (mismo `clientId`: idempotente). */
    retryChat(clientId: string): Promise<ChatEntry | null>;
}
/**
 * Una reunión nueva. No conecta hasta `join()`.
 *
 * @example
 * ```ts
 * import { createMeeting } from '@iaconsultinglabs/comms-core'
 *
 * const meeting = createMeeting({
 *   apiUrl: 'https://comms.example.com/v1',
 *   tokenSource: async ({ reason }) => {
 *     const res = await fetch('/api/comms/token', { method: 'POST', body: JSON.stringify({ reason }) })
 *     return res.json()
 *   },
 * })
 * await meeting.join()
 * ```
 */
export declare function createMeeting(options: MeetingOptions): CommsMeeting;
```

### state.d.ts

```ts
/**
 * Los seis estados que la interfaz tiene que saber pintar: `idle` (sin empezar), `connecting`
 * (entrando), `connected` (dentro), `reconnecting` (se movió la red y estamos volviendo),
 * `disconnected` (fuera, con `reason`) y `failed` (no se pudo entrar o volver; `retry()` lo
 * vuelve a intentar).
 */
export type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
/**
 * Por qué se está fuera:
 *   · `left`           me fui yo;
 *   · `removed`        me sacaron (el backend del tenant);
 *   · `meeting_ended`  la reunión terminó para todos;
 *   · `replaced`       entré con la misma identidad desde otra pestaña/recarga;
 *   · `transferred`    pasé la llamada a otro aparato (`TokenRequest.transfer`): sigo
 *                      dentro desde allí, aquí no;
 *   · `network`        se perdió la red y no se pudo volver;
 *   · `error`          no se pudo entrar (token, servidor de medios).
 */
export type DisconnectReason = 'left' | 'removed' | 'meeting_ended' | 'replaced' | 'transferred' | 'network' | 'error';
/** Las razones que no se arreglan volviendo a entrar solo. */
export declare const FINAL_REASONS: ReadonlySet<DisconnectReason>;
/** El estado de la conexión de una reunión (`meeting.state` y el evento `state`). */
export interface ConnectionState {
    /** En qué estado está. */
    readonly status: ConnectionStatus;
    /** Por qué se está fuera (`disconnected` o `failed`); `null` si se está dentro o entrando. */
    readonly reason: DisconnectReason | null;
    /** Intentos de volver a entrar desde la última vez que se estuvo dentro. */
    readonly attempt: number;
    /** El último error, si lo hubo (con `failed`, siempre). */
    readonly error: CommsError | null;
}
/** Lo que mueve la máquina de estados de la conexión (`transition`). Interno del motor; se exporta para probarlo. */
export type ConnectionEvent = {
    /** Empezar a entrar. */
    type: 'connect';
} | {
    /** Ya dentro. */
    type: 'connected';
} | {
    /** No se pudo entrar. */
    type: 'connect_failed';
    /** Por qué. */
    error: CommsError;
} | {
    /** El transporte está rehaciendo la conexión. */
    type: 'transport_reconnecting';
} | {
    /** El transporte la rehizo. */
    type: 'transport_reconnected';
} | {
    /** El transporte se rindió. */
    type: 'transport_lost';
    /** Por qué. */
    reason: DisconnectReason;
} | {
    /** Volver a entrar con un token nuevo. */
    type: 'rejoin';
} | {
    /** Dejar de intentarlo. */
    type: 'give_up';
    /** El último error, si lo hubo. */
    error: CommsError | null;
} | {
    /** Salir. */
    type: 'leave';
};
/** El estado antes de `join()`. */
export declare const INITIAL_STATE: ConnectionState;
/** El estado siguiente. Una transición que no tiene sentido deja el estado igual. */
export declare function transition(state: ConnectionState, event: ConnectionEvent): ConnectionState;
/** ¿Está dentro (o volviendo), de modo que tiene sentido mandar algo? */
export declare function isInside(state: ConnectionState): boolean;
```

### errors.d.ts

```ts
/** Lo que solo puede fallar en el navegador. No son códigos del contrato. */
export declare const CLIENT_ERROR_CODES: readonly ["not_connected", "token_source_failed", "connection_failed", "network_error", "media_permission_denied", "media_device_not_found", "media_device_busy", "screen_share_cancelled", "screen_share_unsupported", "invalid_message"];
/** Un código de error que solo existe en el navegador (`CLIENT_ERROR_CODES`). */
export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[number];
/** Cualquier código de un `CommsError`: los de la API (`ErrorCode`) y los del navegador. */
export type CommsErrorCode = ErrorCode | ClientErrorCode;
/** Lo que acompaña al código al crear un `CommsError`. */
export interface CommsErrorInit {
    /** El estado HTTP, si vino de la API. */
    status?: number;
    /** El `requestId` de la respuesta, para soporte. */
    requestId?: string;
    /** Los detalles del error (`error.details` de la API). */
    details?: Record<string, unknown>;
    /** Con `rate_limited`: cuánto esperar. */
    retryAfterSeconds?: number;
    /** El error original. */
    cause?: unknown;
}
/**
 * Todo lo que falla en `comms-core` lanza (y emite como `error`) un `CommsError`. Decide por
 * `code`, que es estable; `message` es para personas y puede cambiar.
 *
 * @example
 * ```ts
 * import { isCommsError } from '@iaconsultinglabs/comms-core'
 *
 * try {
 *   await meeting.join()
 * } catch (error) {
 *   if (isCommsError(error, 'media_permission_denied')) console.log('Pide permiso de cámara')
 *   else if (isCommsError(error) && error.retryable) console.log('Prueba otra vez')
 *   else throw error
 * }
 * ```
 */
export declare class CommsError extends Error {
    /** El código estable: de la API (`ErrorCode`) o del navegador (`ClientErrorCode`). */
    readonly code: CommsErrorCode;
    /** Estado HTTP, si vino de la API. */
    readonly status: number | null;
    /** Para soporte: el mismo que la cabecera de respuesta. */
    readonly requestId: string | null;
    /** Los detalles del error: p. ej. `max` en `invalid_message`, `rawCode` con un código desconocido. */
    readonly details: Record<string, unknown>;
    /** Con `rate_limited`: cuánto esperar (cabecera `Retry-After`). */
    readonly retryAfterSeconds: number | null;
    constructor(code: CommsErrorCode, message: string, init?: CommsErrorInit);
    /** ¿Lo puede arreglar volver a intentarlo más tarde? */
    get retryable(): boolean;
}
/** Otra conexión presenta. Lleva quién y si se le puede quitar. */
export declare class ScreenShareBusyError extends CommsError {
    /** Quién presenta ahora, si se sabe. */
    readonly presenter: ConnectionRef | null;
    /** Esta conexión puede quitarle el turno (`startScreenShare({ takeover: true })`). */
    readonly canTakeOver: boolean;
    constructor(message: string, init?: CommsErrorInit);
}
/** ¿Es un CommsError (de un código concreto, si se dice)? */
export declare function isCommsError(error: unknown, code?: CommsErrorCode): error is CommsError;
/**
 * Un código que no está en la lista cerrada (una API más nueva que este
 * cliente) se trata como `internal_error`, guardando el original en
 * `details.rawCode`: añadir un código es MINOR y no puede romper a nadie.
 */
export declare function apiCode(raw: unknown): {
    code: ErrorCode;
    rawCode: string | null;
};
/** La respuesta de error de la API, como CommsError. */
export declare function errorFromResponse(status: number, body: unknown, headers?: {
    get(name: string): string | null;
}): CommsError;
/**
 * Un fallo de `getUserMedia` / `getDisplayMedia` (DOMException), traducido.
 * `screen` distingue el selector de pantalla, donde «NotAllowedError» es casi
 * siempre que la persona lo cerró.
 */
export declare function errorFromMedia(error: unknown, { screen }?: {
    screen?: boolean | undefined;
}): CommsError;
```

### participants.d.ts

```ts
/** Lo que publica una conexión, por fuente (la forma de `Participant.publishing`). */
export interface Publishing {
    /** Publica cámara (aunque esté en pausa). */
    readonly camera: boolean;
    /** Publica micro (aunque esté silenciado). */
    readonly microphone: boolean;
    /** Comparte pantalla. */
    readonly screenShare: boolean;
}
/** Las pistas de una conexión, listas para un `<video>`/`<audio>` (`srcObject`). */
export interface ParticipantMedia {
    /** El vídeo de la cámara, o `null`. */
    readonly camera: MediaStream | null;
    /** El audio del micro, o `null`. El motor ya lo reproduce (`autoPlayAudio`): no lo pongas en otro `<audio>`. */
    readonly microphone: MediaStream | null;
    /** El vídeo de la pantalla compartida, o `null`. */
    readonly screen: MediaStream | null;
    /** El audio de la pantalla compartida, si lo tiene. */
    readonly screenAudio: MediaStream | null;
}
/** Una conexión dentro de la reunión, vista desde este navegador. */
export interface MeetingParticipant {
    /** La conexión (`Identity`): una por aparato. */
    readonly identity: string;
    /** La persona, con el id que le dio el tenant. */
    readonly personId: string;
    /** `user` (de la organización) o `guest` (de fuera). */
    readonly personKind: PersonKind;
    /** `host`, `member` o `guest`. */
    readonly role: Role;
    /** El nombre que dio el tenant en el token. */
    readonly name: string;
    /** El aparato de la conexión, si el token lo dijo. */
    readonly device: Device | null;
    /** Qué tipo de aparato es (`desktop`, `tablet`, `phone`), si se sabe. */
    readonly deviceLabel: DeviceLabel | null;
    /** Otro aparato de una persona que ya está dentro. */
    readonly companion: boolean;
    /** Es esta conexión (este navegador). */
    readonly isLocal: boolean;
    /** El tenant excluyó a esta persona de la IA (ADR 0050). No se enseña nada especial. */
    readonly aiExcluded: boolean;
    /** Qué publica (micro, cámara, pantalla). */
    readonly publishing: Publishing;
    /** Sus pistas, para pintarlas. */
    readonly media: ParticipantMedia;
    /** Está hablando ahora. */
    readonly speaking: boolean;
    /** Volumen de 0 a 1, aproximado. */
    readonly audioLevel: number;
    /** La calidad de su red. */
    readonly connectionQuality: ConnectionQuality;
    /** Cuándo entró (ISO 8601), si se sabe. */
    readonly joinedAt: string | null;
}
/** Lo que va dentro de los metadatos de una conexión. */
export interface ConnectionMetadata {
    /** La persona. Sin metadatos, la propia conexión. */
    readonly personId: string;
    /** `user` o `guest`. */
    readonly personKind: PersonKind;
    /** El rol; nunca se supone más del que se ve. */
    readonly role: Role;
    /** Es un aparato complementario de alguien que ya está dentro. */
    readonly companion: boolean;
    /** El aparato, si el token lo dijo. */
    readonly device: Device | null;
    /** El tenant la excluyó de la IA. */
    readonly aiExcluded: boolean;
}
/**
 * Los metadatos de una conexión. Si faltan o no se entienden, lo prudente:
 * la persona es la propia conexión, y nunca se le supone más rol del que se
 * ve (un `guest` sin metadatos sigue siendo `guest` si así lo dice su kind).
 */
export declare function parseConnectionMetadata(raw: string | null | undefined, identity: string): ConnectionMetadata;
/** Una persona, con sus conexiones agrupadas. */
export interface Person {
    /** La persona, con el id que le dio el tenant. */
    readonly personId: string;
    /** Su nombre. */
    readonly name: string;
    /** `user` o `guest`. */
    readonly personKind: PersonKind;
    /** El rol más alto entre sus conexiones. */
    readonly role: Role;
    /** Una de sus conexiones es este navegador. */
    readonly isLocal: boolean;
    /** Sus conexiones: la principal primero, luego las complementarias. */
    readonly connections: readonly MeetingParticipant[];
    /** La conexión que la representa (la principal, o la primera). */
    readonly main: MeetingParticipant;
    /** Habla desde alguno de sus aparatos. */
    readonly speaking: boolean;
    /** Micro abierto en su conexión principal. */
    readonly microphone: boolean;
    /** Cámara en cualquiera de sus aparatos. */
    readonly camera: boolean;
    /** Pantalla desde cualquiera de sus aparatos. */
    readonly screenShare: boolean;
}
/**
 * Las personas, con sus aparatos agrupados: la lista del panel. Yo primero,
 * luego quien manda, luego quien habla, y por nombre.
 */
export declare function groupPeople(participants: readonly MeetingParticipant[]): Person[];
/** Cuántas PERSONAS hay dentro (los aparatos complementarios no suman). */
export declare function countPeople(participants: readonly MeetingParticipant[]): number;
/** Quién presenta: la conexión que publica pantalla (la remota antes que la mía, si hubiera carrera). */
export declare function presenterOf(participants: readonly MeetingParticipant[]): MeetingParticipant | null;
/**
 * ¿Dice lo mismo? Para conservar el mismo objeto cuando nada cambia: así un
 * framework que compara por referencia (Vue, React) no repinta el recuadro de
 * quien no ha cambiado cada vez que otro empieza a hablar.
 */
export declare function sameParticipant(a: MeetingParticipant, b: MeetingParticipant): boolean;
```

### video-view.d.ts

```ts
/** La pista de vídeo de una conexión que se pinta. */
export type VideoSource = 'camera' | 'screenShare';
/** Calidad que se pide de un vídeo remoto. */
export type VideoQuality = 'low' | 'medium' | 'high';
/** Cómo se pinta ahora una vista: su tamaño en píxeles CSS y si se ve. */
export interface VideoViewSize {
    /** El ancho en píxeles CSS. */
    readonly width: number;
    /** El alto en píxeles CSS. */
    readonly height: number;
    /** `devicePixelRatio` de la pantalla (por defecto, el de la ventana, o 1). */
    readonly pixelRatio?: number;
    /** Se ve de verdad (no está fuera de la pantalla ni en una pestaña oculta). Por defecto, sí. */
    readonly visible?: boolean;
}
/** Una vista de un vídeo remoto: se actualiza al cambiar de tamaño y se suelta al quitarla. */
export interface VideoView {
    /** El tamaño o la visibilidad cambió (llámalo desde un `ResizeObserver` o un `IntersectionObserver`). */
    update(size: VideoViewSize): void;
    /** Ya no se pinta. Idempotente. */
    release(): void;
}
/** Lo que se pide al servidor de medios para una pista. */
export type VideoDemand = {
    readonly enabled: false;
} | {
    readonly enabled: true;
    readonly quality: VideoQuality;
    readonly width: number;
    readonly height: number;
};
/** Hasta este alto físico (normalizado a 16:9) basta la capa baja; hasta el segundo, la media. */
export declare const QUALITY_THRESHOLDS: {
    readonly low: 200;
    readonly medium: 400;
};
/** Cuánto se espera antes de bajar de calidad o dejar de recibir. */
export declare const DOWNGRADE_DELAY_MS = 1500;
/**
 * La calidad que cubre una vista de `width`×`height` píxeles FÍSICOS. Cuenta
 * el lado que más pide de un vídeo 16:9: una vista alta y estrecha (un
 * teléfono en vertical, recortando) necesita alto; una ancha, ancho.
 */
export declare function videoQualityFor(width: number, height: number): VideoQuality;
/** Lo que piden juntas varias vistas de la misma pista (null: ninguna vista). */
export declare function combineViews(sizes: readonly VideoViewSize[], source: VideoSource, defaultRatio?: number): VideoDemand | null;
/** ¿`next` pide menos que `current`? (menos calidad, o dejar de recibir). */
export declare function isDowngrade(current: VideoDemand | null, next: VideoDemand): boolean;
export declare function sameDemand(a: VideoDemand | null, b: VideoDemand | null): boolean;
/**
 * Todas las vistas de una reunión, agrupadas por pista. `apply` recibe lo que
 * hay que pedir cada vez que cambia (el motor se lo pasa al transporte).
 */
export declare class VideoViews {
    #private;
    constructor(apply: (identity: string, source: VideoSource, demand: VideoDemand) => void, options?: {
        readonly delayMs?: number;
    });
    /** Una vista nueva de la pista `source` de `identity`. Hasta el primer `update`, no pide nada. */
    observe(identity: string, source: VideoSource): VideoView;
    /** Lo que se pide ahora de cada pista (para dárselo a un transporte nuevo). */
    current(): {
        identity: string;
        source: VideoSource;
        demand: VideoDemand;
    }[];
    /** Olvidar las pistas de una conexión que se fue (sus vistas ya no piden nada). */
    forget(identity: string): void;
    /** Parar los temporizadores (al destruir la reunión). */
    dispose(): void;
}
```

### layout.d.ts

```ts
/** Cómo repartir los recuadros en una cuadrícula (`bestGrid`). */
export interface GridShape {
    /** Columnas. */
    readonly cols: number;
    /** Filas. */
    readonly rows: number;
    /** El ancho de cada recuadro, en píxeles. */
    readonly tileWidth: number;
    /** El alto de cada recuadro, en píxeles. */
    readonly tileHeight: number;
}
/** Las columnas que mejor reparten `count` recuadros en `width`×`height`. */
export declare function bestGrid(count: number, width: number, height: number, { gap, aspect }?: {
    gap?: number | undefined;
    aspect?: number | undefined;
}): GridShape;
/** Lo mínimo que el reparto necesita saber de un recuadro. */
export interface StageTileLike {
    /** Estable entre repintados. */
    readonly key: string;
    /** Es una pantalla compartida. */
    readonly presentation?: boolean;
    /** Soy yo. */
    readonly self?: boolean;
    /** La conexión del recuadro (para saber quién habla). */
    readonly identity?: string;
}
/** `grid`: todos iguales. `focus`: uno grande y el resto en una tira. */
export type StageMode = 'grid' | 'focus';
/**
 * Qué modo toca: `grid` (todos iguales) o `focus` (uno grande y el resto en
 * la tira). Manda lo compartido, luego quien se fija; si no, cuadrícula.
 */
export declare function stageMode({ tiles, pinned }: {
    tiles: readonly StageTileLike[];
    pinned: string | null;
}): StageMode;
/** El recuadro grande del modo `focus`: lo fijado, la pantalla, quien habla, o el primero. */
export declare function focusOf<T extends StageTileLike>({ tiles, pinned, activeSpeaker }: {
    tiles: readonly T[];
    pinned: string | null;
    activeSpeaker: string | null;
}): T | null;
```

### stage.d.ts

```ts
/** Un recuadro del escenario: una cámara o una pantalla compartida. */
export interface StageTile extends StageTileLike {
    /** Estable entre planes: úsalo como `key` al pintar la lista. */
    readonly key: string;
    /** La conexión del recuadro. */
    readonly identity: string;
    /** La conexión entera, para el nombre, el micro y la red. */
    readonly participant: MeetingParticipant;
    /** El vídeo del recuadro: la cámara, o la pantalla si es una presentación. */
    readonly stream: MediaStream | null;
    /** Es una pantalla compartida. */
    readonly presentation: boolean;
    /** Soy yo. */
    readonly self: boolean;
}
/** Qué recuadros pintar y en qué orden (`planStage`). */
export interface StagePlan {
    /** Los recuadros, en orden: las pantallas primero. */
    readonly tiles: readonly StageTile[];
    /** Mi vídeo va flotando aparte (no está en `tiles`). */
    readonly floatingSelf: StageTile | null;
}
/**
 * Con `previous` (el plan anterior), cada recuadro que no cambió conserva su
 * objeto: el framework no repinta los recuadros de quien no ha cambiado.
 */
export declare function planStage(participants: readonly MeetingParticipant[], previous?: StagePlan | null): StagePlan;
```

### ai.d.ts

```ts
/** El aviso a TODA la sala (`AiDisclosurePacket`). */
export declare const AI_TOPIC = "iacl.ai";
/** Subtítulos (`AiCaptionPacket`), a todas las conexiones, con `live.transcript: captions`. */
export declare const AI_CAPTION_TOPIC = "iacl.ai.transcript";
/** Detecciones en directo (`AiDetectionPacket`), solo a `live.detectionAudience`, nunca a invitados. */
export declare const AI_DETECTION_TOPIC = "iacl.ai.detection";
/** Sugerencias privadas (`AiSuggestionPacket`), solo a su audiencia. */
export declare const AI_SUGGESTION_TOPIC = "iacl.ai.suggestion";
/** Las salidas en directo del modo (`AiResultPacket`, ADR 0057), solo a quien ve la ayuda. */
export declare const AI_RESULT_TOPIC = "iacl.ai.result";
/** Los temas de la IA: `iacl.ai` y todo lo que cuelga de `iacl.ai.`. */
export declare const AI_TOPIC_PREFIX = "iacl.ai.";
/** ¿Es un tema de la IA (`iacl.ai` o `iacl.ai.*`)? */
export declare function isAiTopic(topic: string | null): topic is string;
/**
 * En qué está la IA en esta sala, deducido del aviso:
 * - `off`: no hay IA;
 * - `waiting`: hay IA en directo pero el procesador aún no está dentro (entrando, o caído);
 * - `live`: el procesador está dentro y oye;
 * - `postMeeting`: solo trabaja al terminar (resumen, acciones), no oye en directo.
 */
export type AiRoomStatus = 'off' | 'waiting' | 'live' | 'postMeeting';
/** `AiDisclosure` con todo lo opcional resuelto y el estado deducido. Es lo que da `meeting.ai`. */
export interface MeetingAi extends AiDisclosure {
    /** Qué hace la IA (`AiDisclosure.features`); vacío si la API no lo dice. */
    features: AiFeature[];
    /** En qué está la IA en esta sala ahora (`off`, `waiting`, `live` o `postMeeting`). */
    readonly status: AiRoomStatus;
}
/** La IA apagada: lo que da `meeting.ai` antes de entrar, o si la API no dice nada de IA. */
export declare const AI_OFF: MeetingAi;
/** Un `MeetingAi` bien formado a partir de lo que llegue; si no se entiende, IA apagada. */
export declare function normalizeAi(value: unknown): MeetingAi;
/** El aviso de la sala `{ kind: 'ai', ai }`, o null si no lo es. */
export declare function parseAiPacket(payload: Uint8Array | string): MeetingAi | null;
/** El `AiDisclosure` del contrato, sin lo que deduce el motor. */
export declare function toDisclosure(ai: MeetingAi): AiDisclosure;
/** ¿Dicen lo mismo dos `MeetingAi`? Para no avisar de un cambio que no lo es. */
export declare function sameAi(a: MeetingAi, b: MeetingAi): boolean;
/** Un subtítulo (`AiCaptionPacket`) que cumple el contrato, o null. */
export declare function parseCaptionPacket(value: unknown): AiCaptionPacket | null;
/** Una detección en directo (`AiDetectionPacket`) que cumple el contrato, o null. */
export declare function parseDetectionPacket(value: unknown): AiDetectionPacket | null;
/** Los disparadores de una ayuda (`AiSuggestionTriggerType`; ADR 0057 añade `question`, `context_fact` y `risk`). */
export declare const AI_SUGGESTION_TRIGGERS: readonly AiSuggestionTriggerType[];
/** Los tipos de ayuda (`AiHelpKind`, ADR 0057). */
export declare const AI_HELP_KINDS: readonly AiHelpKind[];
/** Una sugerencia privada (`AiSuggestionPacket`) que cumple el contrato, o null. */
export declare function parseSuggestionPacket(value: unknown): AiSuggestionPacket | null;
/** Una salida en directo del modo (`AiResultPacket`, ADR 0057) que cumple el contrato, o null. */
export declare function parseResultPacket(value: unknown): AiResultPacket | null;
/** Un paquete de la IA que el motor conoce, ya validado. */
export type KnownAiPacket = {
    /** El aviso a toda la sala. */
    readonly topic: typeof AI_TOPIC;
    /** El aviso, validado. */
    readonly packet: AiDisclosurePacket;
} | {
    /** Un subtítulo. */
    readonly topic: typeof AI_CAPTION_TOPIC;
    /** El subtítulo, validado. */
    readonly packet: AiCaptionPacket;
} | {
    /** Una detección en directo. */
    readonly topic: typeof AI_DETECTION_TOPIC;
    /** La detección, validada. */
    readonly packet: AiDetectionPacket;
} | {
    /** Una sugerencia privada. */
    readonly topic: typeof AI_SUGGESTION_TOPIC;
    /** La sugerencia, validada. */
    readonly packet: AiSuggestionPacket;
} | {
    /** Una salida en directo del modo (ADR 0057). */
    readonly topic: typeof AI_RESULT_TOPIC;
    /** La salida, validada. */
    readonly packet: AiResultPacket;
};
/**
 * Lo que entrega el evento genérico `aiPacket` por CADA paquete de un tema de la IA que llega
 * del servidor: `known: true` con el paquete tipado y validado; `known: false` con el JSON tal
 * cual (un tema nuevo de una API más moderna) o `raw: undefined` si ni siquiera es JSON. Un
 * paquete de un tema conocido que no cumple el contrato llega con `known: false` y `invalid: true`.
 */
export type AiPacketEvent = (KnownAiPacket & {
    /** El motor conoce el tema y el paquete cumple el contrato. */
    readonly known: true;
}) | {
    /** Un tema que el motor no conoce, o un paquete que no cumple el contrato. */
    readonly known: false;
    /** El tema tal cual (`iacl.ai.…`). */
    readonly topic: string;
    /** El JSON tal cual, o `undefined` si no era JSON. */
    readonly raw: unknown;
    /** `true` si el tema es conocido pero el paquete no cumple el contrato. */
    readonly invalid: boolean;
};
/** Clasificar un paquete de un tema de la IA. */
export declare function classifyAiPacket(topic: string, payload: Uint8Array | string): AiPacketEvent;
/** Quién: la conexión y, si el motor la ha visto en la sala, su persona y su nombre. */
export interface AiSpeaker {
    /** La conexión que habló. */
    readonly identity: string;
    /** Su persona, si el motor la vio en la sala; si no, `null`. */
    readonly personId: string | null;
    /** Su nombre, si el motor lo conoce; si no, `null` (enseña uno genérico). */
    readonly name: string | null;
}
/**
 * Un subtítulo, provisional (`isFinal: false`) o final, con quién habla. Llega con el evento
 * `aiCaption`; nunca una revisión vieja ni repetida.
 *
 * @example
 * ```ts
 * // fragmento: `meeting` es un CommsMeeting
 * meeting.on('aiCaption', (caption) => {
 *   const who = caption.speaker.name ?? 'Alguien'
 *   console.log(`${who}: ${caption.text}${caption.isFinal ? '' : '…'}`)
 * })
 * ```
 */
export interface AiCaption {
    /** El segmento: sus correcciones llegan con el mismo id y `revision` mayor. */
    readonly segmentId: string;
    /** Sube con cada corrección del mismo segmento: la mayor gana. */
    readonly revision: number;
    /** `true`: ya no cambia. `false`: provisional, lo sustituirá una revisión mayor. */
    readonly isFinal: boolean;
    /** Lo dicho. */
    readonly text: string;
    /** Desde el inicio de la reunión. */
    readonly startMs: number;
    /** Dónde acaba, desde el inicio de la reunión. */
    readonly endMs: number;
    /** El idioma reconocido (`es`, `ca`…). */
    readonly language: string;
    /** Quién lo dijo. */
    readonly speaker: AiSpeaker;
    /** Cuándo llegó a este navegador (ms de época). */
    readonly receivedAt: number;
    /** El modelo del catálogo de IACL que lo transcribió (ADR 0055), o null si la API no lo dice. */
    readonly model: string | null;
}
/** Una detección en directo, para quien organiza (evento `aiDetection`; nunca llega a un invitado). */
export interface AiDetection {
    /** El id de la detección, el mismo que en el webhook `detection.matched`. */
    readonly matchId: string;
    /** El detector que se cumplió. */
    readonly detectorId: string;
    /** El nombre del detector, para enseñarlo. */
    readonly detectorName: string;
    /** El fragmento: texto copiado de la transcripción, nunca del modelo. */
    readonly evidence: AiDetectionPacket['evidence'] & {
        /** Quién lo dijo. */
        readonly speaker: AiSpeaker;
    };
    /** Lo extraído, validado contra el `outputSchema` del detector. */
    readonly data: Record<string, unknown>;
    /** De 0 a 1: cuánto se fía la IA. */
    readonly confidence: number;
    /** Cuándo llegó a este navegador (ms de época). */
    readonly receivedAt: number;
    /** El modelo del catálogo de IACL que lo detectó (ADR 0055), o null. */
    readonly model: string | null;
}
/**
 * Una ayuda privada en directo, solo para quien ve la ayuda (`meeting.ai.on('help')`; antes, el
 * evento `aiSuggestion`). Es una sugerencia, una respuesta, un dato del contexto o un aviso
 * (`kind`, ADR 0057).
 */
export interface AiSuggestion {
    /** El id, para valorarla con `meeting.ai.sendFeedback`. */
    readonly suggestionId: string;
    /** Qué tipo de ayuda es: `suggestion`, `answer`, `fact` o `alert`. */
    readonly kind: AiHelpKind;
    /** La ayuda, escrita por la IA para quien la recibe. */
    readonly text: string;
    /** De qué trata, en pocas palabras, o null. */
    readonly topic: string | null;
    /** Con `answer` y `fact`: los documentos del contexto en que se apoya (el `excerpt` sale del documento). */
    readonly sources: readonly AiHelpSource[];
    /** Qué dicho de la reunión la disparó (y la detección, si fue una). */
    readonly trigger: AiSuggestionPacket['trigger'];
    /** Cuándo llegó a este navegador (ms de época). */
    readonly receivedAt: number;
    /** El modelo del catálogo de IACL que la escribió (ADR 0055), o null. */
    readonly model: string | null;
    /** Lo que dijo esta persona de ella (`sendAiSuggestionFeedback`), o null si aún nada. */
    readonly feedback: AiSuggestionFeedbackDecision | null;
}
/** Una ayuda privada en directo (ADR 0057): el nombre nuevo de `AiSuggestion`. */
export type AiHelp = AiSuggestion;
/**
 * Una salida en directo del modo de la reunión (el `result` genérico, ADR 0057), con sus
 * datos validados contra el `outputSchema` de esa salida. `T` es la forma de esos datos, la
 * que declara tu modo: `meeting.ai.onResult<{ fecha: string }>('fecha_entrega', …)`.
 */
export interface AiResult<T extends Record<string, unknown> = Record<string, unknown>> {
    /** El id, el mismo que en el webhook `ai.result`. */
    readonly resultId: string;
    /** El modo que la declara. */
    readonly profileId: string;
    /** La salida del modo (`AiProfile.live.results[].id`). */
    readonly outputId: string;
    /** Lo extraído, validado contra el `outputSchema` de la salida. */
    readonly data: T;
    /** El fragmento que la justifica: texto de la transcripción (o del chat), nunca del modelo. */
    readonly evidence: AiDetection['evidence'];
    /** De 0 a 1: cuánto se fía la IA. */
    readonly confidence: number;
    /** Cuándo llegó a este navegador (ms de época). */
    readonly receivedAt: number;
    /** El modelo del catálogo de IACL que la produjo (ADR 0055), o null. */
    readonly model: string | null;
}
/** «Útil» o «no útil» sobre una sugerencia, ya anotado en la API. */
export interface AiSuggestionFeedback {
    /** La sugerencia valorada. */
    readonly suggestionId: string;
    /** `useful` o `not_useful`. */
    readonly decision: AiSuggestionFeedbackDecision;
}
/**
 * Qué revisión se ha visto de cada segmento, para no entregar una vieja ni repetir una
 * (la sala no garantiza el orden). Un final cierra el segmento. Recuerda los últimos
 * `limit` segmentos.
 */
export declare class CaptionRevisions {
    #private;
    constructor(limit?: number);
    /** ¿Es nuevo? Si lo es, queda apuntado. */
    accept(caption: Pick<AiCaptionPacket, 'segmentId' | 'revision' | 'isFinal'>): boolean;
    /** Olvidarlo todo (al salir de la reunión). */
    clear(): void;
}
/** Una línea de subtítulos en pantalla. */
export interface CaptionLine {
    /** El segmento: una línea por segmento. */
    readonly segmentId: string;
    /** La revisión que se enseña. */
    readonly revision: number;
    /** Ya no cambia; se quita a los `finalMs`. */
    readonly isFinal: boolean;
    /** El texto que se enseña. */
    readonly text: string;
    /** Quién lo dijo. */
    readonly speaker: AiSpeaker;
    /** Desde cuándo se enseña así (para quitar los finales al rato). */
    readonly updatedAt: number;
}
/** Opciones de `nextCaptionLines`. */
export interface CaptionLinesOptions {
    /** Cuántas líneas a la vez, como mucho. Por defecto 3. */
    readonly max?: number;
    /** Cuánto se queda un final en pantalla. Por defecto 7 s. */
    readonly finalMs?: number;
}
/**
 * Las líneas que se enseñan, tras llegar un subtítulo: una por segmento, la revisión mayor
 * sustituye a la anterior en su sitio (el provisional no salta), los finales se van a los
 * `finalMs` y quedan como mucho `max`. Pura: para cualquier framework.
 */
export declare function nextCaptionLines(lines: readonly CaptionLine[], caption: AiCaption | null, now: number, options?: CaptionLinesOptions): CaptionLine[];
```

### ai-api.d.ts

```ts
/** Lo que se sabe de la IA en esta conexión: lo de todos (\`MeetingAi\`) y lo propio. */
export interface MeetingAiState extends MeetingAi {
    /**
     * Esta conexión ve la ayuda privada en directo (\`TokenGrant.aiAssist\`): el panel de
     * ayuda solo se enseña si es \`true\`. Nunca en un invitado ni con \`aiExcluded\`.
     */
    readonly assist: boolean;
    /** El tenant excluyó a esta persona de la IA: no se procesa nada suyo. */
    readonly excluded: boolean;
}
/** Los eventos de \`meeting.ai\`: el nombre y lo que llega con él. */
export interface MeetingAiEvents {
    /** Un subtítulo nuevo, provisional o final. Nunca una revisión vieja ni repetida. */
    caption: AiCaption;
    /** Una detección en directo para esta conexión (nunca a un invitado). */
    detection: AiDetection;
    /** Una ayuda privada: sugerencia, respuesta, dato del contexto o aviso. */
    help: AiHelp;
    /** Una salida en directo del modo (el \`result\` genérico), con sus datos validados. */
    result: AiResult;
    /** Cambió el estado de la IA (aviso, procesador dentro, modelos…). Llega el estado nuevo. */
    status: MeetingAiState;
    /** Esta persona valoró una ayuda y la API lo anotó. */
    feedback: AiSuggestionFeedback;
    /** Cada paquete de un tema \`iacl.ai*\`: tipado si se conoce, en bruto si no (para lo que aún no tiene evento). */
    packet: AiPacketEvent;
}
/**
 * La IA de la reunión (\`meeting.ai\`). Las propiedades del estado se leen; las listas son las
 * últimas que llegaron a esta conexión (la más nueva al final); los métodos no cambian de un
 * estado al siguiente.
 *
 * @example
 * ```ts
 * // fragmento: `meeting` es un CommsMeeting
 * if (meeting.ai.assist) {
 *   meeting.ai.on('help', (help) => console.log(help.kind, help.text))
 *   meeting.ai.onResult<{ fecha: string }>('fecha_entrega', (r) => console.log(r.data.fecha))
 * }
 * meeting.ai.on('status', (ai) => console.log(ai.status))
 * ```
 */
export interface MeetingAiApi extends MeetingAiState {
    /** Las últimas ayudas que llegaron a esta conexión (como mucho 50). */
    readonly help: readonly AiHelp[];
    /** Las últimas detecciones (como mucho 50). */
    readonly detections: readonly AiDetection[];
    /** Las últimas salidas del modo (como mucho 50). */
    readonly results: readonly AiResult[];
    /** Escuchar un evento de la IA. Devuelve con qué dejar de escuchar. */
    on<K extends keyof MeetingAiEvents>(event: K, handler: (payload: MeetingAiEvents[K]) => void): () => void;
    /** Dejar de escuchar. */
    off<K extends keyof MeetingAiEvents>(event: K, handler: (payload: MeetingAiEvents[K]) => void): void;
    /**
     * Las salidas de UNA salida del modo, con la forma de sus datos (\`T\`, la de su
     * \`outputSchema\`). Devuelve con qué dejar de escuchar.
     */
    onResult<T extends Record<string, unknown> = Record<string, unknown>>(outputId: string, handler: (result: AiResult<T>) => void): () => void;
    /** Las salidas que ya llegaron de una salida del modo. */
    resultsOf<T extends Record<string, unknown> = Record<string, unknown>>(outputId: string): readonly AiResult<T>[];
    /** «Útil» o «no útil» sobre una ayuda que llegó a esta conexión. Solo mide; repetirla la sustituye. */
    sendFeedback(helpId: string, decision: AiSuggestionFeedbackDecision): Promise<AiSuggestionFeedback>;
}
/** Lo que \`meeting.ai\` necesita de la reunión (por dentro; no es API pública). */
export interface AiSource {
    readonly help: () => readonly AiHelp[];
    readonly detections: () => readonly AiDetection[];
    readonly results: () => readonly AiResult[];
    readonly sendFeedback: (helpId: string, decision: AiSuggestionFeedbackDecision) => Promise<AiSuggestionFeedback>;
}
/** Los oyentes de \`meeting.ai\`: uno por reunión, compartido por todos sus estados. */
export declare class AiEvents extends Emitter<MeetingAiEvents> {
    /** Avisar (solo la reunión). */
    notify<K extends keyof MeetingAiEvents>(type: K, payload: MeetingAiEvents[K]): void;
    /** Quitar todos los oyentes (al cerrar la reunión). */
    clear(): void;
}
/** El objeto congelado de \`meeting.ai\` para un estado. */
export declare function aiView(state: MeetingAiState, events: AiEvents, source: AiSource): MeetingAiApi;
```

### recording.d.ts

```ts
/** El tema del canal de datos por el que la API avisa a toda la sala de la grabación. */
export declare const RECORDING_TOPIC = "iacl.recording";
/** Sin grabación: lo que da `meeting.recording` antes de entrar, o si la API no dice nada. */
export declare const RECORDING_OFF: RecordingDisclosure;
/** Un `RecordingDisclosure` bien formado a partir de lo que llegue; si no se entiende, no se graba. */
export declare function normalizeRecording(value: unknown): RecordingDisclosure;
/** El aviso de la sala `{ kind: 'recording', recording }`, o null si no lo es. */
export declare function parseRecordingPacket(payload: Uint8Array | string): RecordingDisclosure | null;
export declare function sameRecording(a: RecordingDisclosure, b: RecordingDisclosure): boolean;
```

### chat.d.ts

```ts
/** El tema del canal de datos por el que la API retransmite el chat. */
export declare const CHAT_TOPIC = "iacl.chat";
/** El mensaje más largo que se puede mandar, en caracteres. */
export declare const CHAT_MAX_LENGTH = 4000;
/** Un `clientId` nuevo (`^[A-Za-z0-9_-]{8,64}$`). */
export declare function newClientId(): string;
/** El sobre de un texto. Lanza `invalid_message` si está vacío o es demasiado largo. */
export declare function textBody(text: string): ChatMessageBody;
/** El cuerpo de `POST /participant/chat-messages` para un texto, con un `clientId` nuevo. Lanza `invalid_message` como `textBody`. */
export declare function chatRequest(text: string, clientId?: string): ChatMessageRequest;
/** ¿Tiene la forma de un `ChatMessage` del contrato? */
export declare function isChatMessage(value: unknown): value is ChatMessage;
/**
 * Lo que llega por el canal de datos con el tema del chat:
 * `{ kind: 'chat', message: ChatMessage }` en JSON UTF-8. Cualquier otra cosa
 * se ignora (null): un paquete raro no puede romper la reunión.
 */
export declare function parseChatPacket(payload: Uint8Array | string): ChatMessage | null;
/** `pending`: mandado, sin confirmar; `sent`: confirmado; `failed`: no se pudo mandar (se puede reintentar). */
export type ChatEntryStatus = 'pending' | 'sent' | 'failed';
/** Un mensaje en la lista del chat, tal como lo ve este navegador. */
export interface ChatEntry {
    /** Id estable para la lista: el `clientId` si lo hay, si no el `id`. */
    readonly key: string;
    /** El id que dio la API, o `null` mientras está pendiente. */
    readonly id: string | null;
    /** El `clientId` del emisor, si lo puso (los míos, siempre). */
    readonly clientId: string | null;
    /** Quién lo mandó. */
    readonly from: ConnectionRef;
    /** El sobre del mensaje, tal cual. */
    readonly body: ChatMessageBody;
    /** El texto, o null si el sobre es `encrypted` (E2EE, reservado). */
    readonly text: string | null;
    /** Cuándo se mandó (ISO 8601). */
    readonly sentAt: string;
    /** Pendiente, mandado o fallido. */
    readonly status: ChatEntryStatus;
    /** Lo mandé yo (desde esta conexión). */
    readonly mine: boolean;
    /** Por qué falló, con `status: failed`. */
    readonly error: CommsError | null;
}
export declare class ChatLog {
    #private;
    constructor(limit?: number);
    /** Los mensajes, el más nuevo al final. */
    get entries(): readonly ChatEntry[];
    /** Mi mensaje, antes de que conteste la API. */
    addPending(request: ChatMessageRequest, from: ConnectionRef, now?: Date): ChatEntry;
    /** La API (o el eco del canal) confirma un mensaje. Devuelve si cambió algo. */
    receive(message: ChatMessage, localIdentity: string | null): boolean;
    /** Mi mensaje no se pudo mandar: queda `failed` con su error. Devuelve si cambió algo. */
    fail(clientId: string, error: CommsError): boolean;
    /** Un mensaje que falló vuelve a pendiente (para reintentarlo con el mismo `clientId`). */
    retry(clientId: string): ChatEntry | null;
    /** Vaciar la lista (al volver a entrar). */
    clear(): void;
}
```

### identity.d.ts

```ts
/** La clave de este aparato (esta pestaña), estable mientras no se cierre. */
export declare function deviceKey(storage?: Pick<Storage, 'getItem' | 'setItem'> | null): string;
/**
 * Qué clase de aparato es, para agrupar los aparatos de una persona. Un iPad
 * con iPadOS dice ser un Mac: se le reconoce por la pantalla táctil.
 */
export declare function deviceLabel(agent?: string, touchPoints?: number): DeviceLabel;
/** El `device` del TokenRequest de este aparato. */
export declare function currentDevice(): {
    /** La clave de esta pestaña (`deviceKey()`). */
    key: string;
    /** Qué tipo de aparato es (`deviceLabel()`). */
    label: DeviceLabel;
};
```

### devices.d.ts

```ts
/** Hacia dónde mira una cámara: `user` (a mí) o `environment` (a lo que enseño). */
export type Facing = 'user' | 'environment';
/** Un micro, una cámara o una salida de audio de este aparato. */
export interface MediaDeviceOption {
    /** Para elegirlo (`switchCamera`, `switchMicrophone`, `setSpeaker`, `JoinOptions`). */
    readonly deviceId: string;
    /** El aparato físico: un micro y un altavoz del mismo casco comparten `groupId`. */
    readonly groupId: string;
    /** El nombre, vacío hasta que la persona da permiso de micro o de cámara. */
    readonly label: string;
    /** Qué es. */
    readonly kind: 'camera' | 'microphone' | 'speaker';
    /** Hacia dónde mira, solo en cámaras y si se sabe. */
    readonly facing: Facing | null;
}
/** Lo que hay enchufado en este aparato (`listDevices()`). */
export interface DeviceList {
    /** Las cámaras. */
    readonly cameras: readonly MediaDeviceOption[];
    /** Los micros. */
    readonly microphones: readonly MediaDeviceOption[];
    /** Las salidas de audio (vacío en navegadores que no dejan elegirla, como Safari). */
    readonly speakers: readonly MediaDeviceOption[];
}
/** Hacia dónde mira una cámara: 'user' (a mí), 'environment' (a lo que enseño) o null. */
export declare function facingOf(source: {
    label?: string;
    getSettings?: () => MediaTrackSettings;
} | null | undefined): Facing | null;
/** ¿Es un teléfono o una tableta? Decide si se ofrece «girar» antes que «elegir cámara». */
export declare function isHandheld(): boolean;
/** Lo que hay enchufado. Sin permiso todavía, los `label` vienen vacíos. */
export declare function listDevices(): Promise<DeviceList>;
/** La lista ordenada a partir de lo que dice `enumerateDevices`. */
export declare function devicesFrom(all: readonly Pick<MediaDeviceInfo, 'deviceId' | 'groupId' | 'kind' | 'label'>[]): DeviceList;
/**
 * La cámara a la que pasar al pulsar «Cambiar cámara». Si se sabe hacia dónde
 * mira cada una, la primera que mire al otro lado; si no, la siguiente de la
 * lista, en círculo. Null si no hay otra.
 */
export declare function nextCamera(cameras: readonly MediaDeviceOption[], currentId: string | null, currentFacing: Facing | null): MediaDeviceOption | null;
/** ¿Este navegador puede compartir pantalla? (La mayoría de móviles, no.) */
export declare function screenShareSupported(): boolean;
```

### blur/index.d.ts

```ts
export type { BlurAssets } from './segmenter.js';
export type { BlurStrength } from './mask.js';
/** ¿Se puede ofrecer? Sin canvas con filtros o sin WebAssembly, no se enseña el interruptor. */
export declare function blurSupported(): boolean;
/** Un procesador de cámara que desenfoca el fondo. Uno por cámara encendida. */
export declare function createBlurProcessor(assets: BlurAssets): VideoProcessor;
```

### retry.d.ts

```ts
/** Cómo se vuelve a entrar tras perder la conexión (`MeetingOptions.retry`). */
export interface RetryPolicy {
    /** Espera antes del segundo intento (el primero va al momento). */
    readonly minDelayMs: number;
    /** Tope de espera entre intentos. */
    readonly maxDelayMs: number;
    /** Intentos antes de rendirse (estado `failed`). */
    readonly maxAttempts: number;
}
/** 10 intentos, de 1 s a 15 s entre ellos. */
export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
/**
 * Cuánto esperar antes del intento `attempt` (empezando en 1). Null si ya no
 * hay que intentarlo más.
 */
export declare function retryDelay(attempt: number, policy?: RetryPolicy): number | null;
/**
 * El freno de GENERAL (`autoRetry.js`) para reintentos disparados desde fuera
 * (volver a la pestaña, recuperar la red): como mucho `maxInWindow` en
 * `windowMs`, con espera creciente entre ellos.
 */
export declare class AutoRetry {
    #private;
    constructor({ minMs, maxMs, windowMs, maxInWindow }?: {
        minMs?: number | undefined;
        maxMs?: number | undefined;
        windowMs?: number | undefined;
        maxInWindow?: number | undefined;
    });
    /** Se agotaron los intentos de la ventana: hasta `reset()` no se vuelve solo. */
    get stuck(): boolean;
    /** ¿Puedo volver a entrar solo ahora? Si sí, cuenta como intento. */
    allow(now?: number): boolean;
    /** La persona pulsó «Reintentar», o la reunión acabó: se empieza de cero. */
    reset(): void;
}
```

### tones.d.ts

```ts
/** Alguien espera en la puerta. Como mucho uno cada 4 s: diez invitados a la vez no son diez timbres. */
export declare function chimeKnock(): void;
/** Alguien entra en la reunión. */
export declare function chimeJoin(): void;
/** Alguien sale de la reunión. */
export declare function chimeLeave(): void;
```

### debug.d.ts

```ts
/** La gravedad de un paso del rastro. */
export type DebugLevel = 'debug' | 'info' | 'warn' | 'error';
/** Un paso del rastro de la reunión (`debugLog()`), para adjuntarlo a una incidencia de soporte. */
export interface DebugEntry {
    /** Cuándo (ISO 8601). */
    readonly at: string;
    /** La gravedad. */
    readonly level: DebugLevel;
    /** Qué pasó, en inglés y estable (`join failed`, `screen share granted`…). */
    readonly message: string;
    /** Los datos del paso (códigos de error, intentos…). */
    readonly data?: Record<string, unknown>;
}
export declare class DebugLog {
    #private;
    constructor({ max, verbose }?: {
        max?: number | undefined;
        verbose?: boolean | undefined;
    });
    log(level: DebugLevel, message: string, data?: Record<string, unknown>): void;
    /** Del más viejo al más nuevo. */
    entries(): readonly DebugEntry[];
}
```

### emitter.d.ts

```ts
/** Un oyente de un evento: recibe lo que llega con él. */
export type Listener<T> = (payload: T) => void;
/** Emisor de eventos tipado. Un oyente que lanza no tumba a los demás: se avisa por consola y se sigue. */
export declare class Emitter<Events extends object> {
    #private;
    /** Escuchar un evento. Devuelve con qué dejar de escuchar. */
    on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void;
    /** Escuchar una sola vez. */
    once<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void;
    /** Dejar de escuchar (lo mismo que llamar a lo que devolvió `on`). */
    off<K extends keyof Events>(type: K, listener: Listener<Events[K]>): void;
    /** Avisar a los oyentes de un evento. */
    protected emit<K extends keyof Events>(type: K, payload: Events[K]): void;
    /** Quitar todos los oyentes. */
    protected removeAllListeners(): void;
}
```

### api.d.ts

```ts
/** Lo que se necesita de `fetch`: para dar otro (pruebas, un proxy). */
export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
export interface ParticipantApiOptions {
    /** La base de la API de Comms, con el `/v1` (p. ej. `https://api.comms.example.com/v1`). */
    readonly apiUrl: string;
    /** El token vigente. */
    readonly token: () => string | null;
    /** Pide un token nuevo (por `unauthorized`) y devuelve el nuevo. */
    readonly refreshToken: () => Promise<string>;
    readonly fetch?: FetchLike;
}
export declare class ParticipantApi {
    #private;
    constructor(options: ParticipantApiOptions);
    /** Mandar un mensaje al chat de la sala. Idempotente por `clientId`. */
    sendChatMessage(request: ChatMessageRequest): Promise<ChatMessage>;
    /**
     * Pedir el turno de pantalla. Si presenta otra conexión y no se pide
     * `takeover`, lanza `ScreenShareBusyError` (con `canTakeOver`).
     */
    claimScreenShare(takeover?: boolean): Promise<ScreenShareGrant>;
    /** Soltar el turno. Idempotente. */
    releaseScreenShare(): Promise<void>;
    /** El anfitrión empieza a grabar (ADR 0051). Solo con `role: host` y `settings.recording.hostControl`. */
    startRecording(kinds?: RecordingKind[]): Promise<Recording>;
    /** El anfitrión para la grabación activa. */
    stopRecording(): Promise<Recording>;
    /** «Útil» o «no útil» sobre una sugerencia privada (solo mide; repetirla la sustituye). */
    sendAiSuggestionFeedback(suggestionId: string, decision: AiSuggestionFeedbackDecision): Promise<void>;
}
```

---

## Referencia: @iaconsultinglabs/comms-vue

Componentes y composables de Vue 3, y custom elements para usarlo sin Vue.

### index.d.ts

```ts
/**
 * @iaconsultinglabs/comms-vue — composables y componentes Vue 3 de IACL Comms.
 *
 * Construido sobre la API pública de @iaconsultinglabs/comms-core; no habla con el
 * servidor de medios. Los estilos van aparte (`@iaconsultinglabs/comms-vue/style.css`);
 * los mismos componentes, como custom elements, en `@iaconsultinglabs/comms-vue/elements`.
 */
export declare const PACKAGE_NAME: "@iaconsultinglabs/comms-vue";
export { CAPTIONS_PREFERENCE_KEY, provideMeeting, resolveMeeting, useAi, useAiDisclosure, useConnectionState, useLocalMedia, useMeeting, useMeetingChat, useParticipants, useRecording, useScreenShare, useVideoView, } from './composables.js';
export type { UseAi, UseAiDisclosure, UseConnectionState, UseLocalMedia, UseMeeting, UseMeetingChat, UseParticipants, UseRecording, UseScreenShare, } from './composables.js';
export { DEFAULT_MESSAGES, createCommsI18n, errorText, provideCommsI18n, useCommsI18n } from './i18n.js';
export type { CommsI18n, CommsLocale, Messages, Translate } from './i18n.js';
export type { JoinMode, Knock, LobbyChoices, LobbyRequest, LobbyStatus, OtherDevice, PanelName, ThemeMode, TransferFrom } from './types.js';
export { default as AiIndicator } from './components/AiIndicator.vue';
export { default as AiLivePanel } from './components/AiLivePanel.vue';
export { default as LiveCaptions } from './components/LiveCaptions.vue';
export { default as RecordingIndicator } from './components/RecordingIndicator.vue';
export { default as CallStage } from './components/CallStage.vue';
export { default as ChatPanel } from './components/ChatPanel.vue';
export { default as ControlsBar } from './components/ControlsBar.vue';
export { default as DeviceSettings } from './components/DeviceSettings.vue';
export { default as GuestLobby } from './components/GuestLobby.vue';
export { default as KnockCards } from './components/KnockCards.vue';
export { default as LevelMeter } from './components/LevelMeter.vue';
export { default as MediaView } from './components/MediaView.vue';
export { default as MeetingRoom } from './components/MeetingRoom.vue';
export { default as ParticipantTile } from './components/ParticipantTile.vue';
export { default as ParticipantsPanel } from './components/ParticipantsPanel.vue';
export { default as SelfView } from './components/SelfView.vue';
```

### composables.d.ts

```ts
/** Dar una reunión a los componentes de debajo. */
export declare function provideMeeting(meeting: CommsMeeting): void;
/** La reunión dada como argumento o la de arriba. */
export declare function resolveMeeting(meeting?: CommsMeeting | null): CommsMeeting;
/**
 * Decirle a la reunión cómo se pinta un vídeo remoto (`CommsMeeting.observeVideo`):
 * su tamaño en pantalla y si se ve (fuera de la pantalla o con la pestaña oculta,
 * no). Así llega la capa que hace falta, y nada de lo que no se ve.
 *
 * `element` es la caja donde va el vídeo; `target`, de quién y qué pista es (null
 * para no informar: mi propio vídeo, o sin vídeo). Sin reunión (ni dada ni de
 * arriba), no hace nada. Lo usan `MediaView` y `ParticipantTile`; un integrador
 * que pinte sus propios `<video>` lo puede usar igual.
 *
 * `options.scale`: cuánto está ampliado el vídeo dentro de la caja (el zoom de
 * una pantalla compartida). Se dice el tamaño que se pinta de verdad, la caja por
 * el zoom (con tope, `zoomedViewSize`), para que llegue la capa alta.
 */
export declare function useVideoView(element: Readonly<Ref<HTMLElement | null>>, target: () => {
    readonly identity: string;
    readonly source: VideoSource;
} | null, meeting?: CommsMeeting | null, options?: {
    readonly scale?: () => number;
}): void;
/** Lo que da `useMeeting`. */
export interface UseMeeting {
    /** La reunión de `comms-core`, para lo que no tenga composable. */
    readonly meeting: CommsMeeting;
    /** El estado de la conexión, reactivo. */
    readonly state: Readonly<ShallowRef<ConnectionState>>;
    /** Lo que todos ven de la IA de la reunión (ADR 0050). */
    readonly ai: Readonly<ShallowRef<MeetingAi>>;
    /** El último error de la reunión (también el de entrar), o `null`. */
    readonly lastError: Readonly<ShallowRef<CommsError | null>>;
    /** Entrar (como `meeting.join`). */
    join(options?: JoinOptions): Promise<void>;
    /** Salir (como `meeting.leave`). */
    leave(): Promise<void>;
}
/**
 * Crear (con opciones) o tomar (con una instancia) la reunión y darla a los
 * componentes de debajo. Si la crea aquí, la destruye al desmontar.
 *
 * @example
 * ```ts
 * // fragmento: dentro del <script setup> de tu componente
 * import { useMeeting } from '@iaconsultinglabs/comms-vue'
 *
 * const { state, join } = useMeeting({
 *   apiUrl: 'https://comms.example.com/v1',
 *   tokenSource: async () => (await fetch('/api/comms/token', { method: 'POST' })).json(),
 * })
 * void join()
 * ```
 */
export declare function useMeeting(source: MeetingOptions | CommsMeeting): UseMeeting;
/** Lo que da `useConnectionState`. */
export interface UseConnectionState {
    /** El estado entero. */
    readonly state: Readonly<ShallowRef<ConnectionState>>;
    /** Solo el `status`. */
    readonly status: ComputedRef<ConnectionState['status']>;
    /** Estoy dentro. */
    readonly connected: ComputedRef<boolean>;
    /** Se movió la red y estamos volviendo. */
    readonly reconnecting: ComputedRef<boolean>;
    /** La calidad de MI conexión. */
    readonly quality: ComputedRef<ConnectionQuality>;
    /** Volver a intentarlo tras `failed` (el botón «Reintentar»). */
    retry(): Promise<void>;
}
/** El estado de la conexión y la calidad de mi red, para el aviso de «Reconectando». */
export declare function useConnectionState(meeting?: CommsMeeting): UseConnectionState;
/** Lo que da `useParticipants`. */
export interface UseParticipants {
    /** Todas las conexiones, la mía incluida. */
    readonly participants: Readonly<ShallowRef<readonly MeetingParticipant[]>>;
    /** Las personas, con sus aparatos agrupados. */
    readonly people: ComputedRef<readonly Person[]>;
    /** Mi conexión, o `null` si no estoy dentro. */
    readonly local: ComputedRef<MeetingParticipant | null>;
    /** Quién habla más fuerte (`identity`), o `null`. */
    readonly activeSpeaker: Readonly<ShallowRef<string | null>>;
    /** Quién comparte pantalla, o `null`. */
    readonly presenter: ComputedRef<MeetingParticipant | null>;
    /** Personas dentro (los aparatos complementarios no suman). */
    readonly count: ComputedRef<number>;
}
/** Quién está en la reunión, por conexiones y por personas. */
export declare function useParticipants(meeting?: CommsMeeting): UseParticipants;
/** Lo que da `useLocalMedia`. Las acciones no lanzan: un fallo queda en `lastError`. */
export interface UseLocalMedia {
    /** Mi micro, cámara, pantalla y aparatos. */
    readonly media: Readonly<ShallowRef<LocalMediaState>>;
    /** Los aparatos de este equipo (vacío hasta `refreshDevices()`). */
    readonly devices: Readonly<Ref<DeviceList>>;
    /** El último fallo de micro, cámara o aparatos (p. ej. `media_permission_denied`), o `null`. */
    readonly lastError: Readonly<ShallowRef<CommsError | null>>;
    /** Abrir o cerrar el micro. */
    toggleMicrophone(): Promise<void>;
    /** Encender o apagar la cámara. */
    toggleCamera(): Promise<void>;
    /** Desenfocar el fondo. */
    setBlur(enabled: boolean): Promise<void>;
    /** Cambiar de cámara sin cortar. */
    switchCamera(deviceId: string): Promise<void>;
    /** Cambiar de micro sin cortar. */
    switchMicrophone(deviceId: string): Promise<void>;
    /** Elegir por dónde suena la reunión. */
    setSpeaker(deviceId: string): void;
    /** Girar la cámara (delantera ↔ trasera en un móvil). */
    flipCamera(): Promise<void>;
    /** Volver a leer los aparatos (llámalo al abrir el selector). */
    refreshDevices(): Promise<void>;
    /** Con `localTracks: 'integrator'`, la pista que dio el integrador (o null). */
    providedTrack(source: PublishSource): MediaStreamTrack | null;
}
/** Mi micro, mi cámara y mis aparatos, con acciones que no lanzan (el fallo queda en `lastError`). */
export declare function useLocalMedia(meeting?: CommsMeeting): UseLocalMedia;
/** Lo que da `useScreenShare`. */
export interface UseScreenShare {
    /** Estoy compartiendo. */
    readonly sharing: ComputedRef<boolean>;
    /** Empezando o dejando de compartir. */
    readonly pending: ComputedRef<boolean>;
    /** Este navegador puede compartir pantalla. */
    readonly supported: ComputedRef<boolean>;
    /** Quién comparte ahora, o `null`. */
    readonly presenter: ComputedRef<MeetingParticipant | null>;
    /** Otra conexión presenta: quién y si se le puede quitar. Se limpia con `dismiss()`. */
    readonly busy: Readonly<ShallowRef<ScreenShareBusyError | null>>;
    /** Me quitaron la pantalla (relevo). Se limpia con `dismiss()`. */
    readonly revokedBy: Readonly<ShallowRef<ConnectionRef | null | false>>;
    /** Otro fallo al compartir, o `null`. */
    readonly lastError: Readonly<ShallowRef<CommsError | null>>;
    /** Compartir. Si presenta otra conexión, queda en `busy`. */
    start(): Promise<void>;
    /** Compartir quitándole el turno a quien presenta. */
    takeOver(): Promise<void>;
    /** Dejar de compartir. */
    stop(): Promise<void>;
    /** Compartir si no, y al revés. */
    toggle(): Promise<void>;
    /** Limpiar `busy`, `revokedBy` y `lastError` (al cerrar el aviso). */
    dismiss(): void;
}
/** Compartir pantalla con el turno resuelto: quién presenta, quitárselo y el aviso de relevo. */
export declare function useScreenShare(meeting?: CommsMeeting): UseScreenShare;
/** Lo que da `useMeetingChat`. */
export interface UseMeetingChat {
    /** Los mensajes, el más nuevo al final. */
    readonly messages: Readonly<ShallowRef<readonly ChatEntry[]>>;
    /** Puedo escribir (estoy dentro y el token lo permite). */
    readonly canChat: ComputedRef<boolean>;
    /** Mensajes de otros desde la última vez que se llamó a `markRead()`. */
    readonly unread: Readonly<Ref<number>>;
    /** El último fallo al mandar, o `null`. */
    readonly lastError: Readonly<ShallowRef<CommsError | null>>;
    /** Mandar un texto. `false` si falló (el motivo, en `lastError`). */
    send(text: string): Promise<boolean>;
    /** Volver a mandar un mensaje mío que falló. */
    retry(clientId: string): Promise<void>;
    /** Poner `unread` a 0 (al abrir el chat). */
    markRead(): void;
}
/** El chat de la sala, con no leídos y reintento. */
export declare function useMeetingChat(meeting?: CommsMeeting): UseMeetingChat;
/** Lo que da `useRecording`. */
export interface UseRecording {
    /** Lo que todos ven de la grabación (ADR 0051). */
    readonly recording: Readonly<ShallowRef<RecordingDisclosure>>;
    /** Se está grabando. */
    readonly active: ComputedRef<boolean>;
    /** A esta persona no se la graba. */
    readonly excluded: ComputedRef<boolean>;
    /** Soy el anfitrión: puedo pedir grabar (la API dice si la reunión lo deja: `hostControl`). */
    readonly isHost: ComputedRef<boolean>;
    /** Empezando o parando. */
    readonly pending: Readonly<Ref<boolean>>;
    /** El último fallo (p. ej. `recording_not_allowed`), o `null`. */
    readonly lastError: Readonly<ShallowRef<CommsError | null>>;
    /** Empezar a grabar (anfitrión). */
    start(): Promise<void>;
    /** Parar (anfitrión). */
    stop(): Promise<void>;
    /** Empezar o parar. */
    toggle(): Promise<void>;
    /** Limpiar `lastError`. */
    dismiss(): void;
}
/** «Grabando» para todos y, para el anfitrión, grabar y parar (ADR 0051). */
export declare function useRecording(meeting?: CommsMeeting): UseRecording;
/** Lo que da `useAiDisclosure`. */
export interface UseAiDisclosure {
    /** Lo que todos saben de la IA de la reunión. */
    readonly ai: Readonly<ShallowRef<MeetingAi>>;
    /** Hay IA: enseña siempre el indicador. */
    readonly active: ComputedRef<boolean>;
    /** A esta persona la IA no la oye. */
    readonly excluded: ComputedRef<boolean>;
}
/** Lo que todos ven de la IA (ADR 0050). */
export declare function useAiDisclosure(meeting?: CommsMeeting): UseAiDisclosure;
/** Dónde se recuerda, en este navegador, si cada persona quiere los subtítulos. */
export declare const CAPTIONS_PREFERENCE_KEY = "iacl-comms.captions";
/** Lo que da `useAi`. */
export interface UseAi {
    /**
     * `meeting.ai` (ADR 0057), reactivo: el estado (aviso, `features`, `processorPresent`,
     * `status`, `assist`) y sus métodos (`on`, `onResult`, `sendFeedback`…).
     */
    readonly ai: Readonly<ShallowRef<MeetingAiApi>>;
    /**
     * Esta conexión ve la ayuda privada en directo (`TokenGrant.aiAssist`). El panel de ayuda
     * solo se enseña con esto, y nunca a un invitado.
     */
    readonly assist: ComputedRef<boolean>;
    /** Soy un invitado: nunca ve el panel de ayuda. */
    readonly isGuest: ComputedRef<boolean>;
    /** Hay IA en la reunión. */
    readonly active: ComputedRef<boolean>;
    /** En qué está la IA (`off`, `waiting`, `live`, `postMeeting`). */
    readonly status: ComputedRef<AiRoomStatus>;
    /** Qué hace la IA (`captions`, `detections`, `suggestions`…). */
    readonly features: ComputedRef<readonly AiFeature[]>;
    /**
     * Los modelos del catálogo de IACL que hacen la IA de esta reunión (ADR 0055): `live` el
     * directo, `closing` el cierre. Null si esa parte está apagada o la API no lo dice.
     */
    readonly models: ComputedRef<{
        /** El modelo del directo (`iacl-live-fast`…), o `null`. */
        readonly live: string | null;
        /** El modelo del cierre, o `null`. */
        readonly closing: string | null;
    }>;
    /** A esta persona la IA no la oye. */
    readonly excluded: ComputedRef<boolean>;
    /** Soy el anfitrión (ve las detecciones). */
    readonly isHost: ComputedRef<boolean>;
    /** El modo da subtítulos (`features: captions`), o ya han llegado. */
    readonly captionsAvailable: ComputedRef<boolean>;
    /** Esta persona quiere verlos (se recuerda en el navegador; por defecto, no). */
    readonly captionsOn: Readonly<Ref<boolean>>;
    /** Las líneas que se ven ahora: una por segmento, la revisión mayor gana, los finales se van. */
    readonly captions: Readonly<ShallowRef<readonly CaptionLine[]>>;
    /** Las detecciones en directo que llegaron a esta conexión (la más nueva al final). */
    readonly detections: Readonly<ShallowRef<readonly AiDetection[]>>;
    /**
     * Las ayudas privadas que llegaron a esta conexión (sugerencias, respuestas, datos del
     * contexto y avisos: `kind`), sin las descartadas. La más nueva al final.
     */
    readonly help: ComputedRef<readonly AiHelp[]>;
    /** Las salidas en directo del modo (el `result` genérico) que llegaron, la más nueva al final. */
    readonly results: Readonly<ShallowRef<readonly AiResult[]>>;
    /** @deprecated Usa `help` (ADR 0057). Se quita en 1.0. */
    readonly suggestions: ComputedRef<readonly AiSuggestion[]>;
    /** Detecciones, ayudas y salidas desde la última vez que se llamó a `markSeen()`. */
    readonly unseen: Readonly<Ref<number>>;
    /** Poner o quitar los subtítulos para esta persona (se recuerda en el navegador). */
    setCaptions(on: boolean): void;
    /** Poner los subtítulos si no están, y al revés. */
    toggleCaptions(): void;
    /** Quitar una ayuda de la lista (solo en esta pantalla). */
    dismissHelp(helpId: string): void;
    /**
     * «Útil» o «no útil» sobre una ayuda (`meeting.ai.sendFeedback`). La ayuda queda con su
     * `feedback`; si la API falla, lanza y no cambia nada.
     */
    rateHelp(helpId: string, decision: AiSuggestionFeedbackDecision): Promise<void>;
    /** @deprecated Usa `dismissHelp` (ADR 0057). Se quita en 1.0. */
    dismissSuggestion(suggestionId: string): void;
    /** @deprecated Usa `rateHelp` (ADR 0057). Se quita en 1.0. */
    rateSuggestion(suggestionId: string, decision: AiSuggestionFeedbackDecision): Promise<void>;
    /** Poner `unseen` a 0 (al abrir el panel de IA). */
    markSeen(): void;
}
/**
 * La IA de la reunión para la interfaz, sobre `meeting.ai` (ADR 0057): el aviso, los
 * subtítulos, las detecciones, la ayuda privada y las salidas del modo. Para pintarla a tu
 * manera; `LiveCaptions` y `AiLivePanel` están hechos con esto.
 *
 * @example
 * ```ts
 * // fragmento: dentro del <script setup> de un componente que está debajo de useMeeting
 * import { useAi } from '@iaconsultinglabs/comms-vue'
 *
 * const { assist, captions, help, results, models, setCaptions } = useAi()
 * setCaptions(true)
 * // help.value: las ayudas (help.value[0].kind: 'suggestion' | 'answer' | 'fact' | 'alert');
 * // results.value: las salidas del modo; assist.value: si esta conexión ve la ayuda.
 * ```
 */
export declare function useAi(meeting?: CommsMeeting): UseAi;
```

### i18n.d.ts

```ts
/** Los idiomas que traen los componentes. Otro `locale` cae en castellano. */
export type CommsLocale = 'es' | 'ca' | 'en' | 'fr';
/** Textos por clave (`controls.microphone`, `error.media_permission_denied`…); `{nombre}` se sustituye. */
export type Messages = Record<string, string>;
/** Todos los textos de los componentes, por idioma: para ver las claves y sustituir las que quieras. */
export declare const DEFAULT_MESSAGES: Readonly<Record<CommsLocale, Messages>>;
/** Traducir una clave, con sus parámetros. Una clave que no existe se devuelve tal cual. */
export type Translate = (key: string, params?: Record<string, string | number>) => string;
/** Los textos de una reunión: el idioma en uso y la función para traducir. */
export interface CommsI18n {
    /** El idioma en uso. */
    readonly locale: ComputedRef<CommsLocale>;
    /** Traducir una clave. */
    readonly t: Translate;
}
/** Crea los textos para un `locale` (castellano por defecto) con sustituciones opcionales. */
export declare function createCommsI18n(locale?: MaybeRef<string | undefined>, overrides?: MaybeRef<Messages | undefined>): CommsI18n;
/** Para un componente de primer nivel: crea los textos y los da a sus hijos. */
export declare function provideCommsI18n(locale: MaybeRef<string | undefined>, overrides?: MaybeRef<Messages | undefined>): CommsI18n;
/** Los textos que dio el componente de arriba, o castellano por defecto. */
export declare function useCommsI18n(): CommsI18n;
/** El texto para un código de error (del contrato o del cliente). */
export declare function errorText(t: Translate, code: string | null | undefined): string;
```

### types.d.ts

```ts
/** Alguien en la puerta de la reunión. Lo da el integrador (su backend). */
export interface Knock {
    /** Tu id para esta petición: vuelve en los eventos `admit` y `reject`. */
    readonly id: string;
    /** El nombre que dio quien llama. */
    readonly name: string;
    /** Lo que el integrador quiera enseñar debajo (correo, reunión…). */
    readonly detail?: string;
    /** Cuántas veces lo ha pedido. */
    readonly requests?: number;
}
/** En qué punto está el invitado en el vestíbulo; lo decide el integrador. */
export type LobbyStatus = 'form' | 'waiting' | 'admitted' | 'rejected' | 'error';
/** Lo que se elige en el vestíbulo para entrar (también lo que se recuerda para la próxima vez). */
export interface LobbyChoices {
    /** Entrar con el micro abierto. */
    readonly microphone: boolean;
    /** Entrar con la cámara encendida. */
    readonly camera: boolean;
    /** Entrar con el fondo desenfocado (solo si el vestíbulo lo ofrece: `blurAvailable`). */
    readonly blur?: boolean;
    /** La cámara elegida. */
    readonly cameraDeviceId?: string;
    /** El micro elegido. */
    readonly microphoneDeviceId?: string;
    /** La salida de audio elegida. */
    readonly speakerDeviceId?: string;
}
/** Lo que se pide al llamar a la puerta. Encaja en `JoinOptions` (salvo `name`, `consentAccepted` y `mode`). */
export interface LobbyRequest extends LobbyChoices {
    /** El nombre que escribió el invitado. */
    readonly name: string;
    /** Presente (true) cuando el vestíbulo pedía aceptar unas condiciones (`consent`). */
    readonly consentAccepted?: boolean;
    /**
     * Solo si la persona ya estaba dentro desde otro aparato (`otherDevices`): `companion` =
     * «Unirme también desde aquí» (token con `companion: true`; entra sin micro y sin sonido);
     * `transfer` = «Pasar la llamada a este aparato» (token con `transfer: true`).
     */
    readonly mode?: JoinMode;
}
/** Cómo entra quien ya está dentro desde otro aparato. */
export type JoinMode = 'companion' | 'transfer';
/**
 * Otro aparato desde el que la persona ya está dentro. Lo sabe el backend del tenant
 * (`getMeeting`, o `connectionsOf` del SDK de servidor) y se lo pasa al vestíbulo.
 */
export interface OtherDevice {
    /** Qué tipo de aparato es, si se sabe. */
    readonly label?: 'desktop' | 'tablet' | 'phone';
    /** Ese aparato ya es complementario. */
    readonly companion?: boolean;
}
/** Desde dónde se pide pasar la llamada a este aparato: el aviso de complementario o la pantalla del final. */
export type TransferFrom = 'companion' | 'transferred';
/** El tema de los componentes: `auto` sigue al sistema. */
export type ThemeMode = 'auto' | 'light' | 'dark';
/** Los paneles laterales de `MeetingRoom`. */
export type PanelName = 'chat' | 'people' | 'settings' | 'ai' | 'devices';
```

### Componentes

Generado desde los `.vue` con vue-component-meta. Las props, eventos y slots que no salen aquí no son API pública.

## AiIndicator

«IA activa». Siempre a la vista mientras la IA de la reunión está encendida, para todos, invitados incluidos (ADR 0050): no se puede ocultar ni cerrar. Lleva el modo (`purpose`) si lo hay; el texto accesible dice qué hace (`features`) y si el asistente ya está en la sala. El punto late con el asistente dentro (`status: live`); mientras entra, está quieto. No es una región viva: que empieza o termina lo anuncia la sala, una vez (`MeetingRoom`); aquí es una imagen con nombre que se puede leer cuando se quiera.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `ai` | `{ closingModel?: string; enabled: boolean; features?: ("transcript" \| "captions" \| "detections" \| "suggestions" \| "results" \| "summary" \| "actions")[]; inputs: ("audio" \| "chat" \| "screen")[]; liveModel?: string; postMeeting: boolean; processorPresent: boolean; purpose?: string; realtime: boolean; }` | — | Lo que todos saben de la IA (`useAi().ai`). |
| `excluded`? | `boolean \| undefined` | `false` | A esta persona la IA no la oye (lo dice el texto accesible). |

## AiLivePanel

El panel de ayuda en directo: lo que la IA manda SOLO a esta conexión (ADR 0053 y 0057). La ayuda privada (`iacl.ai.suggestion`: sugerencias, respuestas apoyadas en el contexto, datos del contexto y avisos, cada una con su tipo escrito y, si las tiene, sus fuentes), las salidas en directo del modo (`iacl.ai.result`) y las detecciones (`iacl.ai.detection`). De cada detección y cada salida: el fragmento de la transcripción que la justifica, quién lo dijo, cuándo y los datos extraídos. Comms propone; decidir qué hacer con ello es del tenant. **Nunca se pinta para un invitado**, aunque le llegara algo. Cada lista es un registro (role=log) con el nombre de su encabezado: lo nuevo se oye sin interrumpir mientras el panel está abierto.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `resultLabels`? | `Readonly<Record<string, string>> \| undefined` | `{}` | Cómo se llama en pantalla cada salida del modo (`outputId` → texto), p. ej. `{ fecha_entrega: 'Fecha de entrega' }`. Sin él, el `outputId` con espacios. |

### Slots

| Slot | Datos | Descripción |
| --- | --- | --- |
| `result` | `{ result: AiResult<Record<string, unknown>>; }` | Pintar una salida del modo a tu manera (por ejemplo, con un botón «Crear tarea»). |

## CallStage

Quién se ve y cómo, como en Google Meet (el reparto sale de @iaconsultinglabs/comms-core: planStage, bestGrid, stageMode, focusOf; nada de posiciones a mano):

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `activeSpeaker` | `string \| null` | — | Quién habla más fuerte (`identity`), para el aro y el modo foco. |
| `participants` | `readonly MeetingParticipant[]` | — | Las conexiones que pintar (`useParticipants().participants`). |
| `screenZoom`? | `boolean \| undefined` | `true` | Ampliar la pantalla compartida dentro de su recuadro. Con `false`, no se amplía. |

### Slots

| Slot | Datos | Descripción |
| --- | --- | --- |
| `default` | `Record<string, never>` | Lo que va encima del escenario (avisos, subtítulos). |

## ChatPanel

El chat de la reunión: retransmitido, no guardado (ADR 0006). Mi mensaje sale al momento como «Enviando…» y se confirma cuando la API lo acepta; si falla se queda marcado y se puede reintentar (mismo clientId, sin duplicar).

## ControlsBar

Los botones de la reunión. Pensados primero para un teléfono en una mano (de GENERAL): grandes, abajo, al alcance del pulgar; «Girar cámara» a la vista en un móvil, porque la trasera es la herramienta de trabajo.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `aiPanel`? | `boolean \| undefined` | `false` | El botón del panel de la IA en directo (al anfitrión, o a quien le llegue algo). |
| `captions`? | `boolean \| undefined` | `false` | El botón «Subtítulos» (solo si el modo los da: `features: captions`). |
| `connectDevice`? | `boolean \| undefined` | `false` | El botón «Otro aparato» (conectar otro aparato de la misma persona: lo pinta el integrador en el panel). |
| `panel`? | `string \| null \| undefined` | `null` | El panel abierto ahora (para marcar su botón), o `null`. |
| `panelId`? | `string \| null \| undefined` | `null` | El `id` del panel que abren los botones de paneles (para `aria-controls`). |
| `recordingControl`? | `boolean \| undefined` | `false` | Enseñar al anfitrión «Grabar» (la reunión necesita `settings.recording.hostControl`). |
| `shortcuts`? | `boolean \| undefined` | `false` | Anunciar los atajos del micro y la cámara (los atiende `MeetingRoom`). |
| `unread`? | `number \| undefined` | `0` | Mensajes de chat sin leer (el punto del botón del chat). |
| `waiting`? | `number \| undefined` | `0` | Personas esperando en la puerta (el punto del botón de personas). |

### Eventos

| Evento | Datos | Descripción |
| --- | --- | --- |
| `leave` | `[]` | El botón «Salir». |
| `panel` | `[name: PanelName]` | Abrir o cerrar un panel. |

## DeviceSettings

Cámara, micro y altavoz de ESTE aparato, y el desenfoque. Cambiar de aparato no corta la reunión: se cambia la pista, la publicación sigue. Con `localTracks: 'integrator'` los aparatos son del integrador: no se ofrecen cámara ni micro, y el nivel se mide sobre SU pista (CR-8).

## GuestLobby

El vestíbulo, antes de entrar (de GENERAL, GuestMeetingPage): la reunión, la cámara para verse, el micro con su nivel, qué cámara, micro y altavoz usar, el desenfoque, el nombre y «Pedir entrar» (o «Entrar» si no hay sala de espera, p. ej. para alguien de la organización). Solo UI: llamar a la puerta, esperar y recibir el token son cosa del backend del tenant (ADR 0004). El integrador cambia `status` según lo que le diga su backend y escucha `request` para llamar a la puerta. Lo elegido aquí viaja en `request` para entrar con ello (JoinOptions). La vista previa se apaga al salir del vestíbulo: el motor abre la cámara de nuevo al entrar, con lo que se haya elegido aquí.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `ai`? | `{ closingModel?: string; enabled: boolean; features?: ("transcript" \| "captions" \| "detections" \| "suggestions" \| "results" \| "summary" \| "actions")[]; inputs: ("audio" \| "chat" \| "screen")[]; liveModel?: string; postMeeting: boolean; processorPresent: boolean; purpose?: string; realtime: boolean; } \| null \| undefined` | `null` | Lo que el tenant ya sepa de la IA de la reunión, para avisar antes de entrar. |
| `askName`? | `boolean \| undefined` | `true` | Pedir el nombre. Sin él (alguien con sesión), se usa `initialName`. |
| `autoPreview`? | `boolean \| undefined` | `false` | Abrir la vista previa al montar, sin esperar al botón. |
| `blurAvailable`? | `boolean \| undefined` | `false` | Ofrecer «Desenfocar el fondo» (la reunión se crea con `blur`). |
| `consent`? | `{ text: string; href?: string; linkText?: string; } \| null \| undefined` | `null` | Condiciones que hay que aceptar para entrar (las guarda el tenant). Sin aceptarlas no se emite `request`. `href` (opcional): dónde leerlas enteras, en otra pestaña; `linkText`, el texto del enlace. |
| `error`? | `string \| undefined` | `""` | El código de error que enseñar con `status: error` (se traduce con los textos `error.<code>`). |
| `initialChoices`? | `LobbyChoices \| null \| undefined` | `null` | Lo que eligió la última vez (aparatos, micro, cámara, desenfoque). |
| `initialName`? | `string \| undefined` | `""` | El nombre con el que empieza el campo (o el que se usa sin `askName`). |
| `locale`? | `string \| undefined` | `"es"` | El idioma de los textos. |
| `meetingTitle` | `string` | — | El título (no `title`: en un custom element taparía el atributo nativo). |
| `messages`? | `Messages \| undefined` | — | Textos que sustituyen a los de serie. |
| `organizer`? | `string \| undefined` | `""` | Quién organiza, para enseñarlo debajo del título. |
| `otherDevices`? | `readonly OtherDevice[] \| null \| undefined` | `null` | Los aparatos desde los que esta persona YA está dentro (sin el de ahora). Con alguno, se pregunta «¿también desde aquí o pasar la llamada aquí?» en vez de «Entrar». |
| `requiresApproval`? | `boolean \| undefined` | `true` | Si el backend del tenant tiene sala de espera («Pedir entrar») o deja entrar directamente («Entrar»). |
| `status`? | `LobbyStatus \| undefined` | `"form"` | En qué punto está: `form` (eligiendo), `waiting` (llamó a la puerta), `admitted`, `rejected` o `error`. Lo cambia tu página según conteste tu backend. |
| `theme`? | `"auto" \| "light" \| "dark" \| undefined` | `"auto"` | Claro, oscuro o el del sistema. |

### Eventos

| Evento | Datos | Descripción |
| --- | --- | --- |
| `cancel` | `[]` | Ya no quiere entrar (mientras esperaba). |
| `choices` | `[choices: LobbyChoices]` | Cambió lo elegido (aparatos, micro, cámara, desenfoque): guárdalo para la próxima vez. |
| `request` | `[request: LobbyRequest]` | «Pedir entrar» o «Entrar»: llama a tu backend con esto y pon `status` según conteste. |

### Slots

| Slot | Datos | Descripción |
| --- | --- | --- |
| `waiting` | `Record<string, never>` | Lo que se enseña mientras espera a que le admitan (`status: waiting`). |

## KnockCards

«Marc García quiere entrar» [Rechazar] [Admitir] (de GENERAL, KnockCards). Solo UI: la sala de espera vive en el backend del tenant (ADR 0004). Los datos los da el integrador (`knocks`) y las decisiones salen como eventos; quien admite es el backend del tenant, que entonces pide el token `guest`. Varios a la vez se apilan; con dos o más, «Admitir a todos».

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `knocks` | `readonly Knock[]` | — | Quien llama a la puerta, del más antiguo al más nuevo (lo da tu backend). |
| `locale`? | `string \| undefined` | `"es"` | El idioma de los textos. |
| `max`? | `number \| undefined` | `3` | Cuántas tarjetas a la vez, como mucho. |
| `messages`? | `Messages \| undefined` | — | Textos que sustituyen a los de serie. |
| `theme`? | `"auto" \| "light" \| "dark" \| undefined` | `"auto"` | Claro, oscuro o el del sistema. |

### Eventos

| Evento | Datos | Descripción |
| --- | --- | --- |
| `admit` | `[id: string]` | Admitir a esta persona (`Knock.id`). |
| `admitAll` | `[]` | Admitir a todos los que esperan. |
| `reject` | `[id: string]` | Rechazar a esta persona (`Knock.id`). |

## LevelMeter

El nivel del micrófono, en barras. Mide la pista que se le da (la vista previa del vestíbulo o el micro propio dentro de la reunión) con un AnalyserNode del navegador: no publica ni graba nada. Para un lector de pantalla es un medidor (role=meter) con nombre: su valor va de 10 en 10 (no cambia doce veces por segundo) y, silenciado, lo dice.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `active`? | `boolean \| undefined` | `true` | Medir; con `false` (micro cerrado), a cero. |
| `label`? | `string \| undefined` | `""` | El nombre del medidor para un lector de pantalla. |
| `stream`? | `MediaStream \| null \| undefined` | `null` | El audio que medir (la vista previa o mi micro). |

## LiveCaptions

Subtítulos de la IA en directo (ADR 0053, `live.transcript: captions`). Cada persona los pone o los quita para sí (`useAi().toggleCaptions()`, o el botón «Subtítulos» de la barra); se recuerda en su navegador. Una línea por frase con quién habla: el provisional se corrige en su sitio (la revisión mayor gana) y se ve más tenue hasta que es final; los finales se van a los pocos segundos. Para un lector de pantalla es un registro (role=log, que avisa sin interrumpir): solo están en él las frases finales; las provisionales cambian varias veces por segundo y quedan fuera (`aria-hidden`). Cuando una frase se cierra, su línea se pinta de nuevo (otra `key`) para que el registro la reciba como frase nueva. Se oyen solo si la persona pone los subtítulos.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `force`? | `boolean \| undefined` | `false` | Enseñarlos aunque esta persona no los haya puesto (p. ej. una pantalla de sala). |
| `maxLines`? | `number \| undefined` | `3` | Cuántas líneas a la vez, como mucho. |
| `position`? | `"overlay" \| "inline" \| undefined` | `"overlay"` | Dónde: encima del escenario (`overlay`, abajo y centrado) o en el flujo de la página (`inline`). |

## MediaView

El vídeo de una conexión. `srcObject` no es un atributo: se pone a mano. Siempre `muted`: el audio lo reproduce el motor (@iaconsultinglabs/comms-core), en un solo sitio, con la salida elegida.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `fit`? | `"auto" \| "cover" \| "contain" \| undefined` | `"cover"` | Cómo encajar la imagen: `cover`, `contain` o `auto`. |
| `identity`? | `string \| null \| undefined` | `null` | La conexión remota de este vídeo: con ella se pide solo la calidad que hace falta. |
| `mirror`? | `boolean \| undefined` | `false` | En espejo (mi propia cámara). |
| `source`? | `VideoSource \| undefined` | `"camera"` | Qué pista es (por defecto, la cámara). |
| `stream` | `MediaStream \| null` | — | El vídeo que pintar (`participant.media.camera`, `.screen`…), o `null`. |
| `zoom`? | `ZoomView \| null \| undefined` | `null` | Ampliado dentro de la caja (escala y desplazamiento en px CSS). Solo pantallas compartidas: lo pone `ScreenZoom`. |
| `zooming`? | `boolean \| undefined` | `false` | Un gesto en marcha: sin transición y con `will-change`. |

## MeetingRoom

La reunión completa: escenario, avisos, botones y paneles (chat, personas, ajustes). Funciona igual para un miembro y para un invitado: lo único que cambia es el token que da el integrador.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `aiPanel`? | `boolean \| undefined` | `false` | El panel de la IA en directo (detecciones y sugerencias), con su botón: al anfitrión, o a quien le llegue algo. |
| `apiUrl`? | `string \| undefined` | `""` | La base de la API de Comms, con `/v1` (para crear la reunión aquí, con `tokenSource`). |
| `autoJoin`? | `boolean \| undefined` | `true` | Entrar al montar. |
| `blurAssets`? | `BlurAssets \| null \| undefined` | `null` | Dónde están el wasm y el modelo del desenfoque (`blur` choca con HTMLElement.blur() en un custom element). |
| `captions`? | `boolean \| undefined` | `false` | Subtítulos de la IA en directo: el botón «Subtítulos» (cada uno los pone para sí) y las líneas sobre el escenario. |
| `connectDevice`? | `boolean \| undefined` | `false` | «Otro aparato» en los controles: abre el panel con el hueco `connect-device` (QR y enlace del integrador). |
| `joinOptions`? | `JoinOptions \| null \| undefined` | `null` | Con qué entrar: micro, cámara, aparatos y desenfoque (lo que eligió en el vestíbulo). |
| `knocks`? | `readonly Knock[] \| undefined` | `[]` | Quien llama a la puerta (los da el backend del tenant). |
| `locale`? | `string \| undefined` | `"es"` | El idioma de los textos (`es`, `ca`, `en`, `fr`). |
| `meeting`? | `CommsMeeting \| null \| undefined` | `null` | Una reunión ya creada con `createMeeting()`. |
| `meetingTitle`? | `string \| undefined` | `""` | El título (no `title`: en un custom element taparía el atributo nativo). |
| `messages`? | `Messages \| undefined` | — | Textos que sustituyen a los de serie, por clave (`DEFAULT_MESSAGES`). |
| `offerTransfer`? | `boolean \| undefined` | `false` | Ofrecer «Pasar la llamada aquí» (en un complementario) y «Volver a este aparato» (tras `transferred`). |
| `recordingControl`? | `boolean \| undefined` | `false` | El botón «Grabar» para el anfitrión (la reunión necesita `settings.recording.hostControl`). |
| `screenZoom`? | `boolean \| undefined` | `true` | La pantalla compartida se amplía dentro de su recuadro (dedos, rueda, teclado), aunque la página bloquee su zoom. Con `false`, no. |
| `shortcuts`? | `boolean \| undefined` | `true` | Atajos de teclado Ctrl/⌘+D (micro) y Ctrl/⌘+E (cámara), como en Meet. Con `false`, ninguno. |
| `theme`? | `ThemeMode \| undefined` | `"auto"` | Claro, oscuro o el del sistema. |
| `tokenSource`? | `TokenSource \| null \| undefined` | `null` | O lo necesario para crearla aquí. |

### Eventos

| Evento | Datos | Descripción |
| --- | --- | --- |
| `admit` | `[id: string]` | El anfitrión admite a quien llama (`Knock.id`): tu backend le da ahora el token. |
| `admitAll` | `[]` | El anfitrión admite a todos los que esperan. |
| `connectDevice` | `[]` | Se abrió «Conectar otro aparato»: el integrador pide ahora su código y lo pinta en `connect-device`. |
| `left` | `[]` | Esta persona pulsó «Salir» y ya está fuera. Que la reunión termine o la saquen llega por `state`. |
| `reject` | `[id: string]` | El anfitrión rechaza a quien llama (`Knock.id`). |
| `state` | `[state: ConnectionState]` | Cambió el estado de la conexión. |
| `transfer` | `[from: TransferFrom]` | Pasar la llamada a ESTE aparato: desde el aviso de complementario o desde la pantalla de `transferred`. Sale ANTES de pedir el token: el integrador marca que el próximo lleva `transfer: true`. |

### Slots

| Slot | Datos | Descripción |
| --- | --- | --- |
| `connect-device` | `{ close: () => void; }` | Tu forma de conectar otro aparato (un QR, un enlace) en el panel «Otro aparato»; `close` lo cierra. |
| `person-actions` | `{ person: Person; }` | Tus acciones sobre una persona en el panel de personas (sacar, pasar el mando…): las ejecuta tu backend. |

## ParticipantTile

Un recuadro del escenario (portado de GENERAL, CallTile): su vídeo si lo manda y llega; si no, su cara —nunca un rectángulo negro—. El aro verde es «está hablando»; el micro tachado, «está silenciado»; el velo, que su conexión se ha perdido y se está rehaciendo.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `fitDefault`? | `"auto" \| "cover" \| "contain" \| undefined` | `"auto"` | Cómo encajar el vídeo: `cover` (llena, recortando), `contain` (entero) o `auto` (según la orientación). |
| `main`? | `boolean \| undefined` | `false` | Es el recuadro grande del modo foco. |
| `pinned`? | `boolean \| undefined` | `false` | Está fijado. |
| `tile` | `StageTile` | — | El recuadro que pintar (de `planStage`). |
| `zoom`? | `boolean \| undefined` | `false` | Ampliar con los dedos, la rueda o el teclado, si es una pantalla compartida (una cámara, nunca). |

### Eventos

| Evento | Datos | Descripción |
| --- | --- | --- |
| `select` | `[]` | Se pulsó para fijarlo o soltarlo. |

## ParticipantsPanel

Las PERSONAS (no las conexiones): una fila por persona, con sus aparatos debajo cuando tiene más de uno (ADR 0003). Las acciones de quien manda (sacar, pasar el mando) son del backend del tenant, no del navegador: aquí solo hay un hueco (`actions`) para que el integrador ponga las suyas.

### Slots

| Slot | Datos | Descripción |
| --- | --- | --- |
| `actions` | `{ person: Person; }` | Tus acciones sobre cada persona (sacar, pasar el mando…): las ejecuta tu backend. |
| `before` | `Record<string, never>` | Encima de la lista (p. ej. quien espera en la puerta). |

## RecordingIndicator

«Grabando». Siempre a la vista mientras se graba la reunión, para todos, invitados incluidos (ADR 0051): no se puede ocultar ni cerrar. El punto rojo late; el texto accesible dice qué se graba y si a esta persona no. No es una región viva: que empieza o termina lo anuncia la sala, una vez y sin esperar (`MeetingRoom`); aquí es una imagen con nombre que se lee cuando se quiera.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `excluded`? | `boolean \| undefined` | `false` | A esta persona no se la graba (lo dice el texto accesible). |
| `recording` | `{ active: boolean; kinds: ("audio_per_participant" \| "video_per_participant" \| "mixed_audio" \| "video")[]; startedAt: string \| null; }` | — | Lo que todos saben de la grabación (`useRecording().recording`). |

## SelfView

Mi vídeo, pequeño y flotante (de GENERAL). Se arrastra y se queda en la esquina más cercana; un toque lo encoge a una burbuja para ver entero lo que manda el otro, y otro toque lo vuelve a abrir. En espejo, como un espejo. Con teclado es un botón: Intro o Espacio lo encoge o lo abre (`aria-expanded`) y las flechas lo llevan a otra esquina.

### Props

| Prop | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `label` | `string` | — | Mi nombre, para el lector de pantalla. |
| `stream` | `MediaStream \| null` | — | Mi vídeo, o `null`. |


### elements

## Variables

### GuestLobbyElement

```ts
const GuestLobbyElement: VueElementConstructor;
```

`GuestLobby` como custom element (`<iacl-guest-lobby>`).

***

### KnockCardsElement

```ts
const KnockCardsElement: VueElementConstructor;
```

`KnockCards` como custom element (`<iacl-knock-cards>`).

***

### MeetingElement

```ts
const MeetingElement: VueElementConstructor;
```

`MeetingRoom` como custom element (`<iacl-meeting>` tras `defineCommsElements()`).

## Functions

### defineCommsElements()

```ts
function defineCommsElements(prefix?): void;
```

Registra los elementos con un prefijo (por defecto `iacl`). No hace nada si ya existen.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `prefix?` | `string` |

#### Returns

`void`

## References

### JoinMode

Re-exports [JoinMode](index.md#joinmode)

***

### Knock

Re-exports [Knock](index.md#knock)

***

### LobbyRequest

Re-exports [LobbyRequest](index.md#lobbyrequest)

***

### LobbyStatus

Re-exports [LobbyStatus](index.md#lobbystatus)

***

### OtherDevice

Re-exports [OtherDevice](index.md#otherdevice)

***

### ThemeMode

Re-exports [ThemeMode](index.md#thememode)

***

### TransferFrom

Re-exports [TransferFrom](index.md#transferfrom)


---

## Referencia: @iaconsultinglabs/comms-contracts

Tipos y constantes del contrato. Las formas de cada recurso y evento salen del OpenAPI; aquí van las piezas escritas a mano.

### index.d.ts

```ts
export type { components, operations, paths, webhooks };
export * from './generated/constants.js';
export * from './keyProvider.js';
export * from './webhookSignature.js';
export * from './recordingDelivery.js';
export * from './aiClosing.js';
export * from './limits.js';
type Schemas = components['schemas'];
/**
 * Lo genera la API.
 */
export type TenantId = Schemas['TenantId'];
/**
 * Lo genera la API. No es el nombre de la sala del servidor de medios (ese es interno y lleva el tenant delante).
 */
export type MeetingId = Schemas['MeetingId'];
/**
 * Una CONEXIÓN dentro de una reunión. Determinista: misma reunión + misma persona + mismo aparato = misma identidad (recargar es volver).
 */
export type Identity = Schemas['Identity'];
/**
 * La PERSONA, con el id que le da el tenant (su usuario, o la clave de su invitado). Opaco para la API: no se interpreta ni se guarda fuera de las reuniones activas y los eventos.
 */
export type PersonId = Schemas['PersonId'];
/**
 * La clave del aparato, generada por el navegador (sessionStorage) y estable mientras dura la pestaña.
 */
export type DeviceKey = Schemas['DeviceKey'];
/**
 * El id de un evento (`evt_…`). Sirve para deduplicar: el mismo evento llega con el mismo id por webhook y por `GET /events`.
 */
export type EventId = Schemas['EventId'];
/**
 * El id de una API key del tenant (`key_…`). No es el secreto: el secreto solo se ve una vez, al crearla.
 */
export type ApiKeyId = Schemas['ApiKeyId'];
/**
 * El id de un mensaje del chat en sala (`msg_…`), lo da la API al aceptarlo.
 */
export type MessageId = Schemas['MessageId'];
/**
 * El id que el tenant quiera asociar (su hilo, su evento de calendario). Se devuelve en reuniones y eventos.
 */
export type ExternalRef = Schemas['ExternalRef'];
/**
 * `call` = llamada 1:1 con timbre (eventos `call.*`). Lo demás es igual.
 */
export type MeetingType = Schemas['MeetingType'];
/**
 * En qué punto está la reunión: `scheduled` (creada, sin nadie dentro), `active` (con alguien conectado) o `ended` (terminada; no vuelve a abrirse).
 */
export type MeetingStatus = Schemas['MeetingStatus'];
/**
 * `host` entra con el mando (quien organiza). `member` es alguien de la organización. `guest` es alguien de fuera: nunca manda.
 */
export type Role = Schemas['Role'];
/**
 * `user`: una persona del tenant (su usuario). `guest`: alguien de fuera, invitado con enlace.
 */
export type PersonKind = Schemas['PersonKind'];
/**
 * El tipo de aparato desde el que se conecta una persona: `desktop`, `tablet` o `phone`. Lo usa la interfaz para decir «conectado desde el móvil».
 */
export type DeviceLabel = Schemas['DeviceLabel'];
/**
 * Una fuente que una conexión puede publicar: `camera`, `microphone` o `screenShare`.
 */
export type Source = Schemas['Source'];
/**
 * Qué puede PUBLICAR una conexión, por fuente, y si puede escribir en el chat de la sala.
 */
export type SourcePermissions = Schemas['SourcePermissions'];
/**
 * Solo recorta (un `true` no amplía lo que no da el rol o la reunión).
 */
export type SourcePermissionsPatch = Schemas['SourcePermissionsPatch'];
/**
 * El aparato de una conexión: su clave estable (`key`) y qué tipo es (`label`).
 */
export type Device = Schemas['Device'];
/**
 * Una persona por su id (`id`), el que le da el tenant.
 */
export type PersonRef = Schemas['PersonRef'];
/**
 * Una conexión concreta (`identity`) y la persona a la que pertenece (`personId`).
 */
export type ConnectionRef = Schemas['ConnectionRef'];
/**
 * Pares clave-valor del tenant. Se devuelven tal cual; no son contenido de comunicaciones (no meter ahí texto de nadie).
 */
export type Metadata = Schemas['Metadata'];
/**
 * La configuración de una reunión: aforo, vídeo, invitados, pantalla compartida, chat, timbre, tiempos, cifrado, IA y grabación. Lo que no se manda toma el valor del plan.
 */
export type MeetingSettings = Schemas['MeetingSettings'];
/**
 * Reservado. En v1 solo vale `mode: off`. Con `tenant_keys` (futuro), las claves las genera el backend del tenant y llegan al navegador por su `KeyProvider`; la infraestructura central nunca las ve. Una reunión `tenant_keys` no se puede grabar ni transcribir en el servidor (`e2ee_incompatible_settings`).
 */
export type E2eeSettings = Schemas['E2eeSettings'];
/**
 * Una reunión, sin la lista de participantes. Es lo que devuelven `createMeeting` y `listMeetings`.
 */
export type Meeting = Schemas['Meeting'];
/**
 * Una reunión con sus participantes conectados en este momento (`getMeeting`).
 */
export type MeetingDetail = Schemas['MeetingDetail'];
/**
 * La reunión, como viaja en los eventos (sin participantes).
 */
export type MeetingSummary = Schemas['MeetingSummary'];
/**
 * Una página de reuniones. Si `nextCursor` no es `null`, hay más: se pide la siguiente con ese cursor.
 */
export type MeetingPage = Schemas['MeetingPage'];
/**
 * Una conexión dentro de una reunión. La lista de personas se obtiene agrupando por `personId`.
 */
export type Participant = Schemas['Participant'];
/**
 * La calidad de la red de una conexión, como la mide el servidor de medios: `excellent`, `good`, `poor`, `lost` o `unknown`.
 */
export type ConnectionQuality = Schemas['ConnectionQuality'];
/**
 * Por qué terminó una reunión: la terminó el tenant, se fueron todos, llegó a la duración máxima, una llamada no contestada, rechazada o cancelada, o el tenant está suspendido.
 */
export type EndReason = Schemas['EndReason'];
/**
 * Cómo acabó una llamada (`type: call`): `answered`, `missed`, `declined` o `cancelled`.
 */
export type CallOutcome = Schemas['CallOutcome'];
/**
 * El cuerpo de `createMeeting`. Solo `type` es obligatorio; lo que no se manda toma el valor del plan.
 */
export type CreateMeetingRequest = Schemas['CreateMeetingRequest'];
/**
 * El cuerpo de `endMeeting`: el motivo, que llega en `meeting.ended`.
 */
export type EndMeetingRequest = Schemas['EndMeetingRequest'];
/**
 * El cuerpo de `declineCall`: quién rechaza la llamada.
 */
export type DeclineCallRequest = Schemas['DeclineCallRequest'];
/**
 * Lo que el backend del tenant pide para que una persona entre: quién es, con qué rol, desde qué aparato, qué puede publicar y si la IA o la grabación la deben dejar fuera.
 */
export type TokenRequest = Schemas['TokenRequest'];
/**
 * El pase para entrar en una reunión: el token para el navegador, la conexión que le corresponde y lo que esa persona verá de la IA y de la grabación. Caduca en `expiresAt`.
 */
export type TokenGrant = Schemas['TokenGrant'];
/**
 * El cuerpo de `transferHost`: la conexión que pasa a tener el mando.
 */
export type TransferHostRequest = Schemas['TransferHostRequest'];
/**
 * El cuerpo de `removeParticipant`: si se saca solo esa conexión o a la persona entera, y si se le impide volver a entrar.
 */
export type RemoveParticipantRequest = Schemas['RemoveParticipantRequest'];
/**
 * El cuerpo de un mensaje del chat en sala, como sobre con formato. En v1 solo se acepta `text`. `encrypted` está definido y reservado para E2EE: la API lo reenviará sin poder leerlo (solo comprueba el tamaño), y el `keyId` dice con qué clave del `KeyProvider` del tenant se cifró.
 */
export type ChatMessageBody = Schemas['ChatMessageBody'];
/**
 * Un mensaje de chat en texto plano (`format: text`).
 */
export type ChatMessageTextBody = Schemas['ChatMessageTextBody'];
/** Reservado (E2EE): en v1 la API lo rechaza con `e2ee_not_enabled`. */
export type ChatMessageEncryptedBody = Schemas['ChatMessageEncryptedBody'];
/**
 * El cuerpo para mandar un mensaje al chat de la sala. `clientId` lo pone el emisor para reconocer su propio mensaje cuando vuelve.
 */
export type ChatMessageRequest = Schemas['ChatMessageRequest'];
/**
 * Un mensaje del chat de la sala, tal como lo reciben todos.
 */
export type ChatMessage = Schemas['ChatMessage'];
/**
 * El cuerpo para pedir la pantalla compartida. Con `takeover`, se la quita a quien la tenga (si el rol lo permite).
 */
export type ScreenShareClaimRequest = Schemas['ScreenShareClaimRequest'];
/**
 * La respuesta a pedir la pantalla compartida: si se concedió y, si se le quitó a alguien, a quién.
 */
export type ScreenShareGrant = Schemas['ScreenShareGrant'];
/**
 * El endpoint donde el tenant recibe los webhooks, sin el secreto.
 */
export type WebhookEndpoint = Schemas['WebhookEndpoint'];
/**
 * El cuerpo de `setWebhookEndpoint`: la URL, si está activo y qué tipos de evento quiere recibir.
 */
export type WebhookEndpointRequest = Schemas['WebhookEndpointRequest'];
/**
 * El endpoint de webhooks con su secreto de firma. Solo se devuelve al crearlo o al rotar el secreto.
 */
export type WebhookEndpointWithSecret = Schemas['WebhookEndpointWithSecret'];
/**
 * Cómo van las entregas de webhooks: pendientes, fallidas y entregadas en las últimas 24 h, y la más antigua sin entregar.
 */
export type WebhookDeliveryStats = Schemas['WebhookDeliveryStats'];
/**
 * Estables en toda la v1 (ver docs/errors.md). Un cliente decide por `code`, nunca por `message`.
 */
export type ErrorCode = Schemas['ErrorCode'];
/**
 * El cuerpo de toda respuesta de error de la API: `error.code` (estable, para decidir), `error.message` (para personas) y, a veces, `error.details`.
 */
export type ErrorResponse = Schemas['ErrorResponse'];
/**
 * Todos los tipos de evento que puede emitir la API. La lista con el contenido de cada uno está en el catálogo de eventos.
 */
export type EventType = Schemas['EventType'];
/**
 * El sobre común de TODOS los eventos. `version` es la del esquema de `data` para ese `type`: un cambio incompatible sube la versión y, durante la transición, se emiten las dos.
 */
export type EventEnvelope = Schemas['EventEnvelope'];
/**
 * Una página de `GET /events`. Mientras `hasMore` sea `true`, se pide la siguiente con `nextCursor`.
 */
export type EventPage = Schemas['EventPage'];
/**
 * Cualquier evento de la API. Se distingue por `type`, y TypeScript estrecha `data` al comprobarlo.
 */
export type AnyEvent = Schemas['AnyEvent'];
/**
 * `meeting.created`: se ha creado una reunión.
 */
export type MeetingCreatedEvent = Schemas['MeetingCreatedEvent'];
/**
 * `meeting.started`: ha entrado la primera conexión y la reunión está activa.
 */
export type MeetingStartedEvent = Schemas['MeetingStartedEvent'];
/**
 * `meeting.ended`: la reunión ha terminado, con el motivo y la duración.
 */
export type MeetingEndedEvent = Schemas['MeetingEndedEvent'];
/**
 * `participant.joined`: una conexión ha entrado en la reunión.
 */
export type ParticipantJoinedEvent = Schemas['ParticipantJoinedEvent'];
/**
 * `participant.left`: una conexión ha salido de la reunión, con el motivo.
 */
export type ParticipantLeftEvent = Schemas['ParticipantLeftEvent'];
/**
 * `guest.admitted`: quien organiza ha dejado entrar a un invitado que esperaba.
 */
export type GuestAdmittedEvent = Schemas['GuestAdmittedEvent'];
/**
 * `screenshare.started`: alguien ha empezado a compartir pantalla.
 */
export type ScreenshareStartedEvent = Schemas['ScreenshareStartedEvent'];
/**
 * `screenshare.stopped`: se ha dejado de compartir pantalla.
 */
export type ScreenshareStoppedEvent = Schemas['ScreenshareStoppedEvent'];
/**
 * `host.changed`: el mando de la reunión ha pasado a otra conexión.
 */
export type HostChangedEvent = Schemas['HostChangedEvent'];
/**
 * `call.ringing`: una llamada está sonando en los aparatos de quien la recibe.
 */
export type CallRingingEvent = Schemas['CallRingingEvent'];
/**
 * `call.missed`: una llamada ha terminado sin que nadie la conteste.
 */
export type CallMissedEvent = Schemas['CallMissedEvent'];
/**
 * `message.sent`: se ha enviado un mensaje al chat de la sala. **Lleva contenido**: es la entrega al tenant de un mensaje que la API no guarda.
 */
export type MessageSentEvent = Schemas['MessageSentEvent'];
/**
 * `recording.started`: ha empezado una grabación.
 */
export type RecordingStartedEvent = Schemas['RecordingStartedEvent'];
/**
 * `recording.stopped`: se ha parado una grabación, con el motivo. Las partes llegan después, en `recording.ready`.
 */
export type RecordingStoppedEvent = Schemas['RecordingStoppedEvent'];
/**
 * `recording.ready`: todas las partes de una grabación están entregadas (o perdidas) en el almacenamiento del tenant.
 */
export type RecordingReadyEvent = Schemas['RecordingReadyEvent'];
/**
 * `transcript.segment`: un trozo de la transcripción en directo. **Lleva contenido** (lo dicho). Por webhook solo salen los finales; los provisionales van solo a la sala, como subtítulos.
 */
export type TranscriptSegmentEvent = Schemas['TranscriptSegmentEvent'];
/**
 * `transcript.ready`: una transcripción está lista en el almacenamiento del tenant.
 */
export type TranscriptReadyEvent = Schemas['TranscriptReadyEvent'];
/**
 * `summary.ready`: el resumen de un cierre de IA está listo en el almacenamiento del tenant.
 */
export type SummaryReadyEvent = Schemas['SummaryReadyEvent'];
/**
 * El id de una grabación (`rec_…`).
 */
export type RecordingId = Schemas['RecordingId'];
/**
 * El id de una transcripción (`trn_…`).
 */
export type TranscriptionId = Schemas['TranscriptionId'];
/**
 * - `audio_per_participant`: un `.ogg` (Opus) por persona y micrófono, sin mezclar. Es lo que usa la transcripción, y lo de por defecto.
 * - `video_per_participant`: un `.webm` por persona y pista de vídeo (cámara o pantalla), tal cual llega, sin recodificar ni componer (`.mp4` si el navegador publica H.264). Solo si se pide.
 * - `mixed_audio`: UN `.ogg` (Opus, mono, ≈ 48 kbps) con todas las voces de la reunión, cada una en su momento, para escuchar o descargar. Se hace al terminar a partir de las partes de `audio_per_participant` (que hay que pedir a la vez y que se siguen entregando: la transcripción usa esas). Su `recording.ready` lleva una sola parte con `personId` e `identity` a `null`, `offsetMs: 0` y, con `tenant_endpoint`, `partId: mixed`. Sin audio que mezclar, `parts: []`.
 * - `video`: reservado (el vídeo compuesto); responde `not_implemented`.
 */
export type RecordingKind = Schemas['RecordingKind'];
/**
 * Cómo se graba la reunión (ADR 0051). Grabar exige un destino de almacenamiento del tenant y un plan que lo permita.
 */
export type RecordingSettings = Schemas['RecordingSettings'];
/**
 * Lo que TODOS ven de la grabación, invitados incluidos, para que la interfaz enseñe «Grabando» mientras `active`. Viaja en la reunión (`Meeting.recording`), en el acceso (`TokenGrant.recording`) y, al cambiar, a la sala por el canal de datos (tema `iacl.recording`).
 */
export type RecordingDisclosure = Schemas['RecordingDisclosure'];
/**
 * Quién empezó la grabación: el backend del tenant (`by: api`), quien organiza desde la sala (`by: host`, con su `identity`) o la propia reunión (`by: auto`, con `settings.recording.mode: auto`).
 */
export type RecordingStartedBy = Schemas['RecordingStartedBy'];
/**
 * Por qué se paró una grabación: se pidió, terminó la reunión, llegó a la duración máxima o al tope del plan, entró alguien excluido de la grabación, o falló.
 */
export type RecordingStopReason = Schemas['RecordingStopReason'];
/**
 * Una parte de una grabación, en el almacenamiento del TENANT. Con `tenant_endpoint`, también las grabadas que no se pudieron entregar (`delivered: false`, sin `location`).
 */
export type RecordingPart = Schemas['RecordingPart'];
/**
 * Una grabación. Sin contenido; dónde está cada parte llega en `recording.ready`.
 */
export type Recording = Schemas['Recording'];
/**
 * Las grabaciones de una reunión.
 */
export type RecordingList = Schemas['RecordingList'];
/**
 * El cuerpo de `startRecording`: qué se graba (`kinds`). Sin él, lo de `settings.recording.kinds`.
 */
export type StartRecordingRequest = Schemas['StartRecordingRequest'];
/**
 * El idioma de una transcripción bajo demanda: `es`, `ca`, `en` o `fr`.
 */
export type TranscriptionLanguage = Schemas['TranscriptionLanguage'];
/**
 * El cuerpo de `requestTranscription`: el idioma de la reunión.
 */
export type TranscriptionRequest = Schemas['TranscriptionRequest'];
/**
 * Una transcripción de una grabación. El texto no está aquí: está en el almacenamiento del tenant (`location`).
 */
export type Transcription = Schemas['Transcription'];
/**
 * Las transcripciones de una grabación.
 */
export type TranscriptionList = Schemas['TranscriptionList'];
/**
 * El destino de las grabaciones y transcripciones (`type`).
 */
export type StorageDestinationRequest = Schemas['StorageDestinationRequest'];
/**
 * El destino, enmascarado (`type`).
 */
export type StorageDestination = Schemas['StorageDestination'];
/**
 * La entrega al endpoint del tenant. `deliverySecret` solo viene en la respuesta del primer `setStorageDestination` y de `rotateStorageDestinationSecret`.
 */
export type TenantEndpointDestination = Schemas['TenantEndpointDestination'];
/**
 * Configurar la entrega de grabaciones a un endpoint del tenant (`type: tenant_endpoint`), el destino recomendado.
 */
export type TenantEndpointDestinationRequest = Schemas['TenantEndpointDestinationRequest'];
/**
 * El bucket S3, enmascarado. Nunca lleva el secreto.
 */
export type S3Destination = Schemas['S3Destination'];
/**
 * Configurar la escritura de grabaciones en un bucket S3 del tenant (`type: s3`), con sus credenciales. Las credenciales no se devuelven nunca.
 */
export type S3DestinationRequest = Schemas['S3DestinationRequest'];
/**
 * Política de IA de la reunión (ADR 0050 y 0053). Con `realtime`, el procesador entra en la reunión y la oye; con `postMeeting`, al terminar se hace el cierre (resumen, comprobaciones y acciones propuestas). Qué hace exactamente lo dice el modo (`profileId`). Con el nodo sin IA, la API acepta y devuelve estos campos y no procesa nada.
 *
 * **Lo que nunca se procesa, sin opción para activarlo:** los mensajes privados (dirigidos a una parte de los participantes), y el audio y los mensajes de un participante con `aiExcluded`. **Si la IA falla, la llamada sigue.**
 */
export type AiSettings = Schemas['AiSettings'];
/**
 * Lo que TODOS los participantes, invitados incluidos, saben de la IA de la reunión, para que la interfaz enseñe siempre un indicador mientras está activa, y **qué** hace (`features`) y con qué modo (`purpose`). Viaja en el acceso (`TokenGrant.ai`), en la reunión (`Meeting.ai`) y, si cambia durante la reunión, a la sala (tema `iacl.ai`, `AiDisclosurePacket`).
 */
export type AiDisclosure = Schemas['AiDisclosure'];
/**
 * Qué hace la IA en la reunión, para enseñarlo a todos. `transcript`: transcribe en directo. `captions`: además, subtítulos en la sala. `detections`: busca lo que dicen los detectores. `suggestions`: sugerencias privadas a unas conexiones. `summary`: resumen al terminar. `actions`: propone acciones al terminar.
 */
export type AiFeature = Schemas['AiFeature'];
/**
 * De dónde viene lo que procesa la IA. Hoy solo `iacl` (una reunión de IACL Comms). Los demás quedan reservados para procesar grabaciones subidas (`upload`), llamadas telefónicas (`phone`) y reuniones de otras plataformas (`teams`, `meet`, `zoom`) sin cambiar el contrato.
 */
export type AiSource = Schemas['AiSource'];
/**
 * El fragmento que justifica algo: lo dicho, quién y cuándo. `excerpt` es siempre **texto de la transcripción** (o del chat público), copiado de ella, **nunca texto escrito por el modelo**: una evidencia que no está en la transcripción se descarta antes de emitir.
 */
export type AiEvidence = Schemas['AiEvidence'];
/**
 * `live`: en directo, durante la reunión. `closing`: en un cierre.
 */
export type AiStage = Schemas['AiStage'];
/**
 * El id de un segmento de transcripción (`transcript.segment`, y en el `.json` de la transcripción). Estable entre las correcciones de un mismo segmento.
 */
export type TranscriptSegmentId = Schemas['TranscriptSegmentId'];
/**
 * Un modo del tenant (`aip_…`) o una plantilla de IACL (`aip_tpl_…`).
 */
export type AiProfileId = Schemas['AiProfileId'];
/**
 * El id de un cierre de IA (`acl_…`).
 */
export type AiClosingId = Schemas['AiClosingId'];
/**
 * El id de una detección (`dtm_…`): cada vez que un detector se cumple.
 */
export type AiDetectionMatchId = Schemas['AiDetectionMatchId'];
/**
 * El id de una acción propuesta por la IA (`act_…`).
 */
export type AiActionId = Schemas['AiActionId'];
/**
 * El id de una sugerencia privada (`sug_…`).
 */
export type AiSuggestionId = Schemas['AiSuggestionId'];
/**
 * El id de un resumen de un cierre (`sum_…`).
 */
export type AiSummaryId = Schemas['AiSummaryId'];
/**
 * El nombre del tipo de acción, el que use el tenant (p. ej. `task.create`, `quote.request`).
 */
export type AiActionTypeName = Schemas['AiActionTypeName'];
/**
 * Qué la disparó, siempre algo dicho en la reunión y nunca el paso del tiempo: una detección (`detection`, con su `matchId`), una objeción (`objection`), una pregunta que se quedó sin responder (`unanswered_question`), un dato que falta para avanzar (`missing_info`), un tema del contexto que no se ha tratado (`uncovered_topic`), o una pregunta de alguien de la audiencia (`request`, reservado: aún no se emite).
 */
export type AiSuggestionTrigger = Schemas['AiSuggestionTrigger'];
/**
 * Qué tipo de cosa dicha en la reunión disparó una sugerencia: una detección, una petición, una objeción, una pregunta sin responder, un dato que falta o un tema sin tratar.
 */
export type AiSuggestionTriggerType = Schemas['AiSuggestionTriggerType'];
/**
 * Qué tipo de ayuda en directo es (ADR 0057): `suggestion` (qué decir o preguntar ahora), `answer` (respuesta a una pregunta que ha salido, apoyada en el contexto), `fact` (un dato del contexto que viene al caso) o `alert` (un aviso).
 */
export type AiHelpKind = Schemas['AiHelpKind'];
/**
 * Un documento del contexto en que se apoya una ayuda (`answer`, `fact`): su título y, si se comprobó, las palabras del documento que lo dicen.
 */
export type AiHelpSource = Schemas['AiHelpSource'];
/**
 * Una salida en directo del modo (`AiProfile.live.results`, ADR 0057): qué extraer en lenguaje natural y con qué esquema. Sale como `ai.result`.
 */
export type AiLiveResultSpec = Schemas['AiLiveResultSpec'];
/** El id de una salida en directo emitida (`res_…`). */
export type AiResultId = Schemas['AiResultId'];
/** El nombre de una salida en directo del modo (`AiLiveResultSpec.id`). */
export type AiLiveResultOutputId = Schemas['AiLiveResultOutputId'];
/**
 * Lo que el tenant aporta antes de la reunión para que la IA la entienda. **Es contenido**: el central no lo guarda (lo sirve el tenant con `setAiContextSource`, o vive solo en memoria con caducidad con `setMeetingAiContext`). Como mucho 200 kB serializado.
 */
export type AiContext = Schemas['AiContext'];
/**
 * Quién es quién en la reunión.
 */
export type AiContextParticipant = Schemas['AiContextParticipant'];
/**
 * Un documento del contexto, como texto o como ubicación en el almacenamiento del tenant; nunca los dos.
 */
export type AiContextDocument = Schemas['AiContextDocument'];
/**
 * Un documento del contexto de IA mandado como texto.
 */
export type AiContextTextDocument = Schemas['AiContextTextDocument'];
/**
 * Un documento del contexto de IA que está en el almacenamiento del tenant: se manda su ubicación y no su contenido.
 */
export type AiContextLocationDocument = Schemas['AiContextLocationDocument'];
/**
 * El PDF llegará cuando se apruebe una librería para leerlo.
 */
export type AiContextContentType = Schemas['AiContextContentType'];
/**
 * De dónde saldrá el contexto de la reunión. **Nunca lleva el contenido.**
 */
export type AiContextStatus = Schemas['AiContextStatus'];
/**
 * El cuerpo de `setAiContextSource`: la URL del tenant a la que la API pedirá el contexto de cada reunión, y cuánto esperarla.
 */
export type AiContextSourceRequest = Schemas['AiContextSourceRequest'];
/**
 * La URL donde el tenant sirve el contexto de IA de sus reuniones, y cuándo se comprobó por última vez.
 */
export type AiContextSource = Schemas['AiContextSource'];
/**
 * El cuerpo de la petición **que hace la API al tenant** (`POST` a la `url` de `setAiContextSource`), firmada como un webhook (`IACL-Signature`). El tenant contesta `200` con un `AiContext` o `204` sin contexto. `stage: check` es la petición de prueba.
 */
export type AiContextRequest = Schemas['AiContextRequest'];
/**
 * Un modo: «qué queremos que haga la IA» en un tipo de reunión. Es configuración del tenant (o una plantilla de IACL, `template: true`), con `version` que sube en cada cambio. Sus detectores son recursos aparte (`scope: { type: profile }`).
 */
export type AiProfile = Schemas['AiProfile'];
/**
 * El cuerpo para crear un modo de IA: nombre, instrucciones, idiomas y qué sale en directo y al cierre. Con `fromTemplate`, parte de una plantilla de IACL.
 */
export type AiProfileInput = Schemas['AiProfileInput'];
/**
 * Solo cambia lo que se manda; `live` y `closing` se sustituyen enteros.
 */
export type AiProfilePatch = Schemas['AiProfilePatch'];
/**
 * Una página de modos de IA del tenant. Si `nextCursor` no es `null`, hay más.
 */
export type AiProfilePage = Schemas['AiProfilePage'];
/**
 * Una lista de modos de IA, sin paginar (p. ej. las plantillas de IACL).
 */
export type AiProfileList = Schemas['AiProfileList'];
/**
 * Lo que sale en directo (con `settings.ai.realtime`).
 */
export type AiLiveOutputs = Schemas['AiLiveOutputs'];
/**
 * Cómo salen las sugerencias privadas en directo: a quién, por qué disparadores, con qué confianza mínima y con qué frecuencia máxima.
 */
export type AiSuggestionOutputs = Schemas['AiSuggestionOutputs'];
/**
 * Lo que sale al terminar (con `settings.ai.postMeeting`, o en `requestAiClosing`).
 */
export type AiClosingOutputs = Schemas['AiClosingOutputs'];
/**
 * Cómo es el resumen del cierre: si se hace, qué longitud tiene y qué secciones lleva.
 */
export type AiSummaryOutputs = Schemas['AiSummaryOutputs'];
/**
 * Una sección del resumen: su título y qué debe contar.
 */
export type AiSummarySection = Schemas['AiSummarySection'];
/**
 * Qué acciones puede proponer la IA al cierre: los tipos que el tenant sabe ejecutar.
 */
export type AiActionOutputs = Schemas['AiActionOutputs'];
/**
 * Un tipo de acción que el tenant sabe ejecutar en SU sistema. La IA solo propone acciones de los tipos declarados, con `arguments` que validan contra `argumentsSchema`.
 */
export type AiActionType = Schemas['AiActionType'];
/**
 * Un detector de una plantilla de IACL, tal como se crea al clonarla.
 */
export type AiDetectorTemplate = Schemas['AiDetectorTemplate'];
/**
 * Lo que se puede cambiar de `settings.ai` mientras la reunión no ha terminado. Solo cambia lo que se manda.
 */
export type AiMeetingPatch = Schemas['AiMeetingPatch'];
/**
 * Una parte del cierre: `summary` (resumen), `actions` (acciones propuestas) o `checks` (comprobaciones).
 */
export type AiClosingOutput = Schemas['AiClosingOutput'];
/**
 * El cuerpo de `requestAiClosing`: con qué modo, sobre qué transcripción, qué partes y hasta qué momento de la reunión.
 */
export type AiClosingRequest = Schemas['AiClosingRequest'];
/**
 * Un cierre de una reunión. Sin contenido: el resumen está en el almacenamiento del tenant y las acciones llegan por evento.
 */
export type AiClosing = Schemas['AiClosing'];
/**
 * Los cierres de IA de una reunión.
 */
export type AiClosingList = Schemas['AiClosingList'];
/**
 * El cuerpo de `sendAiFeedback`: qué decidió el tenant sobre las acciones y detecciones propuestas.
 */
export type AiFeedbackRequest = Schemas['AiFeedbackRequest'];
/**
 * La decisión del tenant sobre una acción o una detección. Sin contenido.
 */
export type AiFeedbackItem = Schemas['AiFeedbackItem'];
/**
 * Qué hizo el tenant con lo que propuso la IA: `accepted`, `edited`, `rejected` o `ignored`.
 */
export type AiFeedbackDecision = Schemas['AiFeedbackDecision'];
/**
 * Por qué se rechazó lo propuesto: `wrong`, `duplicate`, `not_useful` u `other`.
 */
export type AiFeedbackReason = Schemas['AiFeedbackReason'];
/**
 * Lo que le pareció la sugerencia a quien la recibió.
 */
export type AiSuggestionFeedbackDecision = Schemas['AiSuggestionFeedbackDecision'];
/**
 * El cuerpo para valorar una sugerencia privada desde la sala.
 */
export type AiSuggestionFeedbackRequest = Schemas['AiSuggestionFeedbackRequest'];
/**
 * Tema `iacl.ai`, a TODAS las conexiones: la IA de la reunión ha cambiado (`updateMeetingAi`, o el procesador entra o sale).
 */
export type AiDisclosurePacket = Schemas['AiDisclosurePacket'];
/**
 * Tema `iacl.ai.transcript`, a todas las conexiones, solo con `live.transcript: captions`: provisionales y finales para los subtítulos. No sale por webhook (lo final sí, como `transcript.segment`).
 */
export type AiCaptionPacket = Schemas['AiCaptionPacket'];
/**
 * Tema `iacl.ai.suggestion`, **solo a las conexiones de la audiencia** (nadie más la recibe).
 */
export type AiSuggestionPacket = Schemas['AiSuggestionPacket'];
/**
 * Tema `iacl.ai.detection`, **solo a las conexiones de `live.detectionAudience`** del modo (nunca a invitados): la misma detección que `detection.matched` con `stage: live`, para pintarla en la sala sin pasar por el tenant.
 */
export type AiDetectionPacket = Schemas['AiDetectionPacket'];
/**
 * Tema `iacl.ai.result`, **solo a quien ve la ayuda privada** (nunca invitados): la misma salida que `ai.result` (ADR 0057).
 */
export type AiResultPacket = Schemas['AiResultPacket'];
/**
 * Los límites de IA de un plan. Lo fija la operación de IACL. Al llegar a un tope en directo, el procesador sale (`ai.status`, `reason: plan_limit`) y la llamada sigue; al pedir algo, `plan_limit_reached` con `details.limit`.
 */
export type AiPlan = Schemas['AiPlan'];
/**
 * Un modelo del catálogo de IACL (`iacl-live-fast`). Estable: nunca se reutiliza para otro modelo.
 */
export type AiModelId = Schemas['AiModelId'];
/**
 * `live`: la IA en directo (subtítulos, detectores, sugerencias). `closing`: el cierre al terminar.
 */
export type AiModelKind = Schemas['AiModelKind'];
/**
 * Lo que sabe hacer un modelo: en directo, `captions` (subtítulos), `detections` y `suggestions`; al cierre, `summary`, `actions` y `checks`.
 */
export type AiModelCapability = Schemas['AiModelCapability'];
/**
 * Una clase y no milisegundos: `fast` contesta antes, `precise` entiende mejor y tarda más.
 */
export type AiModelLatency = Schemas['AiModelLatency'];
/**
 * El precio de venta de un modelo, en euros, por la unidad que diga `unit`.
 */
export type AiModelPrice = Schemas['AiModelPrice'];
/**
 * `person_minute`: cada minuto con la IA en directo, por cada persona que oye (como `Usage.aiRealtimeMinutes`). `meeting`: cada reunión cerrada (como `Usage.aiClosedMeetings`).
 */
export type AiModelPriceUnit = Schemas['AiModelPriceUnit'];
/**
 * `preview`: se puede usar, pero puede cambiar. `deprecated`: se retira en `until`; usar `replacedBy`.
 */
export type AiModelStatus = Schemas['AiModelStatus'];
/**
 * Un modelo de IA de IACL (ADR 0055). Es la cara pública: qué hace, en qué idiomas, cómo de rápido y cuánto cuesta. Quién lo procesa por debajo es cosa de IACL (siempre en la UE) y no forma parte del contrato.
 */
export type AiModel = Schemas['AiModel'];
/**
 * El catálogo de modelos de IA que se pueden elegir (`listAiModels`).
 */
export type AiModelList = Schemas['AiModelList'];
/**
 * Los modelos que usa la cuenta cuando la reunión no elige. `source` dice si los eligió el tenant o son los de IACL. Sin modelo de un tipo (el nodo no tiene esa IA), sin el campo.
 */
export type AiModelDefaults = Schemas['AiModelDefaults'];
/**
 * El cuerpo de `setAiModelDefaults`: los modelos que usa la cuenta cuando la reunión no elige.
 */
export type AiModelDefaultsRequest = Schemas['AiModelDefaultsRequest'];
/**
 * Lo consumido en el mes con un modelo: minutos-persona en directo, reuniones cerradas, cierres e importe al precio de cada reunión.
 */
export type AiModelUsage = Schemas['AiModelUsage'];
/**
 * El consumo de IA de una reunión (`getMeetingAiUsage`, ADR 0057): minutos-persona, turnos, ayudas, detecciones, salidas, cierres e importe al precio congelado. Sin contenido.
 */
export type AiMeetingUsage = Schemas['AiMeetingUsage'];
/**
 * Lo que consume la IA en el nodo y sus límites, para la operación de IACL. Sin contenido. Lo de cada tenant (minutos-persona en directo y cierres) está en su `Usage`.
 */
export type OpsNodeAi = Schemas['OpsNodeAi'];
/**
 * Qué hicieron los tenants con lo que propuso la IA (`sendAiFeedback`, AI-14), por detector, por tipo de acción y por disparador de las sugerencias, en los últimos `windowDays` días. Sin contenido: recuentos. En una sugerencia, `accepted` cuenta las «útiles» y `rejected` las «no útiles». `precision` es (aceptadas + editadas) / (aceptadas + editadas + rechazadas); `ignored` no cuenta. Por debajo de `reviewBelow` con al menos `minDecided` decisiones, `needsReview` (ADR 0053 §3.5: un detector por debajo del 50 % se revisa).
 */
export type OpsAiQuality = Schemas['OpsAiQuality'];
/**
 * La calidad de un detector, tipo de acción o disparador: cuántas propuestas se aceptaron, editaron, rechazaron o ignoraron, y si hay que revisarlo.
 */
export type OpsAiQualityItem = Schemas['OpsAiQualityItem'];
/**
 * `live`: en directo. `closing`: una vez, al cierre, sobre la transcripción completa (una comprobación). `both`: en los dos.
 */
export type DetectorWhen = Schemas['DetectorWhen'];
/**
 * `none`: basta una evaluación. `persistence`: se tiene que cumplir en dos ventanas seguidas (+5–10 s). `model`: lo confirma un modelo mayor con más ventana (+≈1 s).
 */
export type DetectorConfirmation = Schemas['DetectorConfirmation'];
/**
 * JSON Schema (draft 2020-12) de los datos que el tenant quiere extraer cuando se cumple. Como mucho 16 kB.
 */
export type DetectorOutputSchema = Schemas['DetectorOutputSchema'];
/**
 * `ai.closing.completed`: el último evento de un cierre de IA, con cuántas acciones y comprobaciones salieron. Sin contenido.
 */
export type AiClosingCompletedEvent = Schemas['AiClosingCompletedEvent'];
/**
 * El id de un detector (`det_…`).
 */
export type DetectorId = Schemas['DetectorId'];
/**
 * Un detector: algo que la IA busca en la conversación (en directo, al cierre o en los dos), con los datos que extrae cuando se cumple.
 */
export type Detector = Schemas['Detector'];
/**
 * El cuerpo para crear un detector.
 */
export type DetectorInput = Schemas['DetectorInput'];
/**
 * Lo que se puede cambiar de un detector. Solo cambia lo que se manda.
 */
export type DetectorPatch = Schemas['DetectorPatch'];
/**
 * A qué reuniones se aplica un detector: a todas las del tenant (`tenant`), a las de un modo (`profile`) o a una reunión concreta (`meeting`).
 */
export type DetectorScope = Schemas['DetectorScope'];
/**
 * Una página de detectores. Si `nextCursor` no es `null`, hay más.
 */
export type DetectorPage = Schemas['DetectorPage'];
/**
 * `detection.matched`: un detector se ha cumplido, con la evidencia y los datos extraídos.
 */
export type DetectionMatchedEvent = Schemas['DetectionMatchedEvent'];
/**
 * `assistant.suggestion`: la IA ha hecho una sugerencia privada a la audiencia de la reunión.
 */
export type AssistantSuggestionEvent = Schemas['AssistantSuggestionEvent'];
/**
 * `ai.result`: una salida en directo del modo de la reunión (el `result` genérico, ADR 0057), con los datos según su esquema.
 */
export type AiResultEvent = Schemas['AiResultEvent'];
/**
 * `action.proposed`: la IA propone una acción al cierre. Comms nunca la ejecuta: decide el tenant.
 */
export type ActionProposedEvent = Schemas['ActionProposedEvent'];
/**
 * `ai.status`: el procesador de IA entra (`joined`), sale (`left`), falla (`failed`), se recupera (`recovered`) o sigue con una parte caída (`degraded`). Que falle nunca afecta a la llamada.
 */
export type AiStatusEvent = Schemas['AiStatusEvent'];
/** El evento de un tipo concreto: `EventOf<'meeting.ended'>`. */
export type EventOf<T extends EventType> = Extract<AnyEvent, OfType<T>>;
/** Lo que tienen en común los eventos de un tipo. */
interface OfType<T extends EventType> {
    /** El tipo del evento. */
    type: T;
}
/**
 * Los límites del plan de un tenant: personas a la vez, aforo, minutos, vídeo, grabación e IA. Lo fija la operación de IACL.
 */
export type Plan = Schemas['Plan'];
/**
 * Un tenant (una empresa que integra Comms), para la operación de IACL.
 */
export type Tenant = Schemas['Tenant'];
/**
 * Un tenant con sus API keys, su consumo del mes y el estado de sus webhooks.
 */
export type TenantDetail = Schemas['TenantDetail'];
/**
 * `active` o `suspended`. Lo cambia la operación de IACL; las reuniones que termina una suspensión acaban con `tenant_suspended`.
 */
export type TenantStatus = Schemas['TenantStatus'];
/**
 * Lo que el cobro deja hacer a una cuenta (ADR 0061): si puede tener claves de producción y si
 * está en pausa por impago (`billing_hold`). Lo pone la operación, normalmente el portal de clientes.
 */
export type TenantBilling = Schemas['TenantBilling'];
/**
 * Un cambio parcial de {@link TenantBilling}, al crear o actualizar un tenant desde la operación.
 */
export type TenantBillingPatch = Schemas['TenantBillingPatch'];
/**
 * Una API key de un tenant, sin el secreto: solo su prefijo, para reconocerla.
 */
export type ApiKey = Schemas['ApiKey'];
/**
 * Una API key recién creada con su secreto. Es la única vez que se ve el secreto.
 */
export type ApiKeyCreated = Schemas['ApiKeyCreated'];
/**
 * `test` (prueba: IA simulada, límites de prueba y consumo aparte) o `live` (producción). Se ve en el prefijo de la clave.
 */
export type ApiKeyMode = Schemas['ApiKeyMode'];
/**
 * La configuración de un cliente en un modo (`getTenantConfig`, solo operación): webhook, destino de
 * grabaciones, fuente de contexto, modelos por defecto y cuántos modos y detectores tiene. Sin
 * secretos. Test y live van por separado (ADR 0059).
 */
export type TenantConfig = Schemas['TenantConfig'];
/**
 * Un permiso de una clave de API (`meetings:write`, `usage:read`…). Cada ruta del tenant pide uno; sin él, `key_scope_missing`.
 */
export type ApiKeyScope = Schemas['ApiKeyScope'];
/**
 * Los límites propios de una clave: peticiones por minuto y topes del mes (minutos de reunión, IA en directo, cierres).
 */
export type ApiKeyLimits = Schemas['ApiKeyLimits'];
/**
 * Lo que se manda para crear una clave: nombre y, si se quiere, modo, permisos y límites.
 */
export type CreateApiKeyRequest = Schemas['CreateApiKeyRequest'];
/**
 * Lo que se cambia de una clave: nombre, permisos o límites (el modo y el secreto, no).
 */
export type UpdateApiKeyRequest = Schemas['UpdateApiKeyRequest'];
/**
 * Cuánto sigue valiendo el secreto anterior al rotar una clave (por defecto 24 h).
 */
export type RotateApiKeyRequest = Schemas['RotateApiKeyRequest'];
/**
 * Una lista de claves de API (`data`), sin secretos.
 */
export type ApiKeyList = Schemas['ApiKeyList'];
/**
 * Al suspender un tenant: si se terminan también las reuniones en curso.
 */
export type SuspendTenantRequest = Schemas['SuspendTenantRequest'];
/**
 * Lo acumulado en un periodo, sin lo activo: el consumo de prueba (`Usage.test`) y el de cada clave.
 */
export type UsageCounters = Schemas['UsageCounters'];
/**
 * El consumo de las reuniones creadas con una clave en un periodo (`Usage.byApiKey`).
 */
export type ApiKeyUsage = Schemas['ApiKeyUsage'];
/**
 * Lo medido en el mes en curso. Para facturar y para el panel.
 */
export type Usage = Schemas['Usage'];
/**
 * Un nodo de la plataforma. Se añade solo al arrancar y se identifica por `nodeId`.
 */
export type OpsNode = Schemas['OpsNode'];
/**
 * Un aviso para la operación de IACL: qué pasa, lo grave que es, desde cuándo y a qué afecta.
 */
export type OpsAlert = Schemas['OpsAlert'];
/**
 * El estado de la plataforma para la operación de IACL: nodos, tenants, avisos y calidad de la IA.
 */
export type OpsSummary = Schemas['OpsSummary'];
```

### generated/constants.d.ts

```ts
/** La versión del contrato con la que se generaron estos tipos (`info.version` de `openapi/comms.yaml`). */
export declare const CONTRACT_VERSION: "0.2.0";
/** Todos los tipos de evento (`EventType`), en el orden del contrato. */
export declare const EVENT_TYPES: readonly ["meeting.created", "meeting.started", "meeting.ended", "participant.joined", "participant.left", "guest.admitted", "screenshare.started", "screenshare.stopped", "host.changed", "call.ringing", "call.missed", "message.sent", "recording.started", "recording.stopped", "recording.ready", "transcript.segment", "transcript.ready", "summary.ready", "detection.matched", "assistant.suggestion", "action.proposed", "ai.status", "ai.closing.completed", "ai.result"];
/** Definidos en el contrato y reservados: no se emiten en v1. */
export declare const RESERVED_EVENT_TYPES: readonly [];
/** Todos los códigos de error estables (`ErrorCode`). Un cliente decide por `code`, nunca por `message`. */
export declare const ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "validation_failed", "conflict", "idempotency_conflict", "rate_limited", "plan_limit_reached", "tenant_suspended", "meeting_ended", "meeting_not_call", "guests_not_allowed", "person_blocked", "role_not_allowed", "participant_not_found", "host_target_invalid", "screen_share_busy", "screen_share_not_allowed", "chat_not_allowed", "device_limit_reached", "e2ee_not_enabled", "ai_input_not_supported", "not_implemented", "e2ee_incompatible_settings", "storage_destination_missing", "storage_destination_invalid", "recording_active", "recording_not_active", "recording_not_allowed", "recording_excluded_participant", "recording_not_ready", "ai_not_enabled", "ai_profile_not_found", "ai_context_invalid", "ai_context_source_invalid", "ai_transcript_unavailable", "ai_closing_active", "ai_detector_limit", "ai_model_unavailable", "key_scope_missing", "key_limit_reached", "live_keys_not_allowed", "billing_hold", "cursor_expired", "webhook_endpoint_invalid", "internal_error", "unavailable"];
/** Los roles de una conexión (`Role`). */
export declare const ROLES: readonly ["host", "member", "guest"];
/** Los tipos de reunión (`MeetingType`). */
export declare const MEETING_TYPES: readonly ["meeting", "call"];
/** Los estados de una reunión (`MeetingStatus`). */
export declare const MEETING_STATUSES: readonly ["scheduled", "active", "ended"];
/** Las fuentes que una conexión puede publicar (`Source`). */
export declare const SOURCES: readonly ["camera", "microphone", "screenShare"];
/** Los motivos por los que termina una reunión (`EndReason`). */
export declare const END_REASONS: readonly ["ended_by_tenant", "everyone_left", "max_duration", "call_missed", "call_declined", "call_cancelled", "tenant_suspended"];
/** Cómo puede acabar una llamada (`CallOutcome`). */
export declare const CALL_OUTCOMES: readonly ["answered", "missed", "declined", "cancelled"];
/** Los modos de una clave de API (`ApiKeyMode`): `test` (prueba) o `live` (producción). */
export declare const API_KEY_MODES: readonly ["test", "live"];
/** Todos los permisos que puede tener una clave de API (`ApiKeyScope`). Cada ruta del tenant pide uno. */
export declare const API_KEY_SCOPES: readonly ["meetings:read", "meetings:write", "tokens:create", "events:read", "recordings:read", "recordings:write", "storage:manage", "webhooks:manage", "ai:read", "ai:configure", "ai:run", "usage:read", "keys:manage"];
```

### keyProvider.d.ts

```ts
/** Una clave de cifrado de una reunión. */
export interface E2eeKey {
    /**
     * Identifica la clave. Es el `keyId` que viaja en un mensaje de chat
     * `format: encrypted` (ChatMessageEncryptedBody), para saber con cuál descifrar.
     */
    readonly keyId: string;
    /** Orden de la clave para la rotación (sube con cada clave nueva). */
    readonly keyIndex: number;
    /** 32 bytes aleatorios generados por el backend del tenant. */
    readonly material: ArrayBuffer;
    /** Cuándo la generó el tenant (ISO 8601). */
    readonly createdAt: string;
}
/**
 * Lo que implementa el tenant para dar las claves de una reunión a su
 * navegador.
 */
export interface KeyProvider {
    /** La clave vigente de la reunión. Se llama al entrar. */
    getKey(meetingId: string): Promise<E2eeKey>;
    /**
     * Avisar de una clave nueva (rotación: entra o sale alguien, o por tiempo).
     * Devuelve con qué dejar de escuchar.
     */
    onKeyRotated(meetingId: string, listener: (key: E2eeKey) => void): () => void;
}
/** Los modos de E2EE que entiende el contrato. En v1 solo `off`. */
export type E2eeMode = 'off';
```

### webhookSignature.d.ts

```ts
/** Las cabeceras de cada webhook. */
export declare const WEBHOOK_HEADERS: {
    /** La firma: `t=<unix segundos>,v1=<hex>[,v1=<hex>]`. */
    readonly signature: "IACL-Signature";
    /** El id del evento (`evt_…`): para deduplicar, porque la entrega es «al menos una vez». */
    readonly eventId: "IACL-Event-Id";
    /** El tipo del evento (`meeting.started`…), para enrutar sin leer el cuerpo. */
    readonly eventType: "IACL-Event-Type";
    /** El número de intento de esta entrega, empezando por 1. */
    readonly deliveryAttempt: "IACL-Delivery-Attempt";
};
/** El receptor rechaza firmas con el reloj más lejos que esto (anti-replay). */
export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
/** Cuánto se reintenta una entrega, y cuánto se puede reconciliar por cursor. */
export declare const EVENT_RETENTION_HOURS = 72;
/** Cuánto tarda como mucho el tenant en contestar 2xx antes de contarse como fallo. */
export declare const WEBHOOK_TIMEOUT_SECONDS = 10;
/** Cuánto se firma con el secreto viejo y el nuevo a la vez tras una rotación. */
export declare const WEBHOOK_SECRET_OVERLAP_HOURS = 24;
/** La versión del esquema de firma (el `v1=` de la cabecera). */
export declare const WEBHOOK_SIGNATURE_SCHEME: "v1";
```

### recordingDelivery.d.ts

```ts
/** Las cabeceras de cada `PUT` de la entrega de grabaciones al endpoint del tenant. */
export declare const RECORDING_DELIVERY_HEADERS: {
    /** La firma: `t=<unix segundos>,v1=<hex>[,v1=<hex>]`. */
    readonly signature: "IACL-Signature";
    /** El sha256 del cuerpo, en hex. El tenant lo comprueba y lo devuelve en el recibo. */
    readonly contentSha256: "IACL-Content-SHA256";
    /** La grabación (`rec_…`). */
    readonly recordingId: "IACL-Recording-Id";
    /** La parte (`audio-1`, `video-2`, `mixed`, `manifest`…). */
    readonly partId: "IACL-Part-Id";
    /** De quién es la parte (solo en las pistas por persona). */
    readonly personId: "IACL-Person-Id";
    /** Qué es la parte (`RecordingPartKind`). */
    readonly partKind: "IACL-Part-Kind";
};
/**
 * Lo que puede ser una parte entregada. `mixed`: la mezcla de la reunión (`mixed_audio`,
 * `partId: mixed`), solo si el tenant la pidió.
 */
export declare const RECORDING_PART_KINDS: readonly ["audio", "video", "mixed", "manifest", "transcript", "summary"];
/** Qué es una parte entregada: uno de `RECORDING_PART_KINDS` (cabecera `IACL-Part-Kind`). */
export type RecordingPartKind = (typeof RECORDING_PART_KINDS)[number];
/** El receptor rechaza firmas con el reloj más lejos que esto (anti-replay). */
export declare const RECORDING_DELIVERY_TOLERANCE_SECONDS = 300;
/** Cuánto reintenta Comms una entrega antes de borrar su copia (`delivery_expired`). */
export declare const RECORDING_DELIVERY_RETENTION_HOURS = 72;
/** Cuánto se firma con el secreto viejo y el nuevo a la vez tras `rotateStorageDestinationSecret`. */
export declare const RECORDING_DELIVERY_SECRET_OVERLAP_HOURS = 24;
/** El recurso que pide Comms al registrar el destino: firma mala → 401; buena → 404 (o 200). */
export declare const RECORDING_DELIVERY_CHECK_PATH = "iacl-check/check";
/** `{partId}` de una parte: `audio-1`, `video-2`…, `mixed` (la mezcla de `mixed_audio`) y `manifest`. */
export declare const RECORDING_PART_ID_PATTERN: RegExp;
/** El texto que se firma: `<t>.<MÉTODO>.<path>.<sha256 o vacío>`. */
export declare function recordingDeliveryPayload(timestamp: number, method: string, path: string, sha256?: string): string;
/** Lo que contesta el tenant a un `PUT` cuando ya tiene el fichero (201 o 200). Comms solo borra su copia con esto y el mismo sha256. */
export interface RecordingDeliveryReceipt {
    /** Siempre `true`: el fichero está guardado. */
    stored: true;
    /** El sha256 del fichero guardado; tiene que ser el de `IACL-Content-SHA256`. */
    sha256: string;
}
```

### aiClosing.d.ts

```ts
type Schemas = components['schemas'];
/** `kind` del documento, para reconocerlo. */
export declare const AI_CLOSING_DOCUMENT_KIND: "iacl.ai.closing";
/** `{partId}` del `.json` y del `.md` de un cierre en la entrega al endpoint del tenant. */
export declare const AI_CLOSING_PART_PATTERN: RegExp;
/** Una sección del resumen, con el título que pide el modo. */
export interface AiClosingDocumentSection {
    /** El título de la sección, el de `AiSummarySection.title` del modo. */
    title: string;
    /** El texto de la sección, en Markdown. */
    content: string;
    /** Los segmentos de la transcripción que lo respaldan (`seg_…`). */
    segmentIds: string[];
}
/** Una acción que la IA propone. Comms nunca la ejecuta: la decide el tenant. */
export interface AiClosingDocumentAction {
    /** El id de la acción, el mismo que en `action.proposed` y en `sendAiFeedback`. */
    actionId: Schemas['AiActionId'];
    /** El tipo de acción, uno de los que declaró el modo (p. ej. `task.create`). */
    actionType: Schemas['AiActionTypeName'];
    /** Un título corto para enseñarla. */
    name: string;
    /** Qué propone y por qué, para la persona que la aprueba. */
    description: string;
    /** Validan contra el `argumentsSchema` del tipo en el modo. */
    arguments: Record<string, unknown>;
    /** De 0 a 1: cuánto se fía la IA de la propuesta. */
    confidence: number;
    /** Lo dicho en la reunión que la justifica, copiado de la transcripción. */
    evidence: Schemas['AiEvidence'][];
    /** Siempre `proposed`: la decisión del tenant vuelve por `sendAiFeedback`. */
    status: 'proposed';
}
/** Una comprobación al cierre: un detector con `when: closing` (o `both`) que se cumplió. */
export interface AiClosingDocumentCheck {
    /** El id de la detección, el mismo que en `detection.matched`. */
    matchId: Schemas['AiDetectionMatchId'];
    /** El detector que se cumplió. */
    detectorId: Schemas['DetectorId'];
    /** El nombre del detector cuando se hizo el cierre. */
    detectorName: string;
    /** De 0 a 1: cuánto se fía la IA de que se cumple. */
    confidence: number;
    /** El fragmento que lo justifica, copiado de la transcripción. */
    evidence: Schemas['AiEvidence'];
    /** Todos los segmentos que lo respaldan (`seg_…`). */
    evidenceSegmentIds: string[];
    /** Los datos extraídos, que validan contra el `outputSchema` del detector. */
    data: Record<string, unknown>;
}
/**
 * El documento entero de un cierre de IA: el `.json` que recibe el tenant al lado de su `.md`.
 * Es contenido del tenant: Comms no se queda con él.
 */
export interface AiClosingDocument {
    /** Siempre `iacl.ai.closing`, para reconocer el documento. */
    kind: typeof AI_CLOSING_DOCUMENT_KIND;
    /** La versión del formato del documento. */
    version: 1;
    /** El cierre del que sale. */
    closingId: Schemas['AiClosingId'];
    /** El id del resumen, el mismo que en `summary.ready`. */
    summaryId: Schemas['AiSummaryId'];
    /** La reunión. */
    meetingId: Schemas['MeetingId'];
    /** Null si el cierre salió de la transcripción en directo (`transcriptOrigin: live`): no hay grabación. */
    recordingId: Schemas['RecordingId'] | null;
    /** La transcripción que leyó la IA. */
    transcriptionId: Schemas['TranscriptionId'];
    /** De dónde salió la transcripción (como `AiClosing.transcript.origin`). */
    transcriptOrigin: 'recording' | 'live';
    /** Solo con `upTo: now`: un resumen «hasta ahora», con la reunión aún activa. */
    upTo?: 'now';
    /** El modo de IA con el que se hizo. */
    profileId: Schemas['AiProfileId'];
    /** La versión del modo en ese momento: un cambio posterior del modo no cambia este documento. */
    profileVersion: number;
    /** El idioma del documento (`es`, `ca`…). */
    language: string;
    /** Cuándo se generó (ISO 8601). */
    generatedAt: string;
    /** Null si el resumen no se pudo generar (el cierre sale `partial`). */
    summary: {
        /** El resumen en un párrafo. */
        abstract: string;
        /** Las secciones que pide el modo, en su orden. */
        sections: AiClosingDocumentSection[];
    } | null;
    /** Las acciones propuestas. */
    actions: AiClosingDocumentAction[];
    /** Las comprobaciones que se cumplieron. */
    checks: AiClosingDocumentCheck[];
    /** Quién estaba excluido de la IA (`aiExcluded`): lo suyo no se leyó. */
    excludedParticipants: Schemas['ConnectionRef'][];
}
```

### limits.d.ts

```ts
/**
 * Cuánto tiempo aparta una plaza del plan la emisión de un token, si la
 * conexión no entra antes. Al entrar se vuelve a comprobar: con la reserva
 * caducada y sin plaza, la conexión se rechaza (ADR 0009).
 */
export declare const PLAN_RESERVATION_SECONDS = 60;
/** Conexiones a la vez de una misma persona en una reunión: la principal y dos complementarias. */
export declare const MAX_CONNECTIONS_PER_PERSON = 3;
/**
 * Límites de peticiones de lo que pide el navegador (`/participant/*`), por
 * conexión. Por encima: `rate_limited` con `Retry-After`.
 */
export declare const RATE_LIMITS: {
    /** Mensajes de chat en sala. */
    readonly chatMessages: {
        /** Cuántas peticiones caben en la ventana. */
        readonly max: 20;
        /** La ventana, en segundos. */
        readonly windowSeconds: 10;
    };
    /** Pedir o soltar el turno de pantalla. */
    readonly screenShareClaims: {
        /** Cuántas peticiones caben en la ventana. */
        readonly max: 10;
        /** La ventana, en segundos. */
        readonly windowSeconds: 60;
    };
};
```