Eventos

Escucha los eventos del workspace en vivo por SSE, o léelos del registro de los últimos 30 días.

met.events es el feed de lo que pasa en tu workspace: runs que terminan, mensajes que entran por un canal, contactos que se crean. Tienes dos formas de leerlo, y sirven para cosas distintas:

• En vivo, por Server-Sent Events, mientras tu proceso está conectado.
• Del registro, que guarda todo evento durante 30 días aunque nadie estuviera escuchando.

Las dos piden el scope events:read.

Escuchar en vivo con stream()

met.events.stream() abre una suscripción SSE efímera que te emite cada evento apenas ocurre. Es la misma fuente de met listen en la CLI: perfecta para el dev-loop y para tiempo real sin montar un endpoint.

const met = new Met(key, { workspaceId });

for await (const ev of met.events.stream()) {
  console.log(ev.type, ev.data);
}

Cada ev es un { id, type, created, livemode, data } — los mismos tipos del catálogo de webhooks salientes.

Filtrar por tipo

Pasa types para recibir solo lo que te interesa:

for await (const ev of met.events.stream({ types: ['run.completed', 'contact.message.received'] })) {
  if (ev.type === 'run.completed') console.log('run listo:', ev.data);
}

Cortar el stream

Rompe el for await (con break) o pasa un AbortSignal para cerrarlo desde afuera:

const ac = new AbortController();
setTimeout(() => ac.abort(), 30_000);   // corta a los 30s

for await (const ev of met.events.stream({ signal: ac.signal })) {
  console.log(ev.type);
}

Algunos tipos útiles del catálogo: run.completed, run.failed, contact.message.received, contact.created, task.completed, conversation.handoff.

De esa lista, con una clave met_test_ solo te llegan run.completed y run.failed. Los demás se emiten siempre en vivo — ver Qué ves y qué no.

stream() vs. webhooks salientes. met.events.stream es efímero: no reintenta y solo llega mientras tu proceso está conectado. Sirve para desarrollo y tiempo real. Para entrega garantizada cross-instancia (que el evento llegue aunque tu servicio esté caído y se reintente), monta un webhook persistente — ver Webhooks.

El registro de eventos

stream() solo te llega mientras estás conectado. El registro guarda todos los eventos del workspace durante 30 días, se hayan entregado a un webhook o no, y lo puedes consultar cuando quieras.

Es lo que responde la pregunta incómoda: *¿y si mi servidor estaba caído el sábado?*

const pagina = await met.events.list({ limit: 50 });

for (const ev of pagina.data) {
  console.log(ev.id, ev.type, ev.created);
}

Cada elemento es el mismo sobre que emite stream() y que se firma en una entrega saliente, con el mismo id. Si recibiste un webhook y quieres volver a leerlo, pídelo por ese id:

const evento = await met.events.retrieve('evt_01M1065RWR7BXJAEE10Y605SMV');

Paginar

La lista trae los más nuevos primero y pagina por cursor, igual que el resto de las listas de la API:

let cursor: string | undefined;
do {
  const pagina = await met.events.list({ limit: 100, starting_after: cursor });
  for (const ev of pagina.data) procesar(ev);
  cursor = pagina.has_more ? pagina.data[pagina.data.length - 1].id : undefined;
} while (cursor);

has_more te dice si quedan eventos más viejos; starting_after recibe el id del último que viste.

Filtrar por tipo

const runs = await met.events.list({ types: ['run.completed', 'run.failed'] });

Qué ves y qué no

• Solo los tipos cuyo permiso de lectura lleva tu clave. Una clave sin billing:read no ve billing.threshold, aunque tenga events:read. Es la misma regla del stream en vivo.
• Una clave de prueba casi no ve nada, y eso es lo que hay que saber antes de escribir el handler. El filtro por livemode no cruza los dos mundos, pero hoy son muy pocas las cosas que se emiten como evento de prueba: run.completed y run.failed de un run que disparaste con esa clave, billing.threshold de la clave misma, y el ping de una entrega de prueba. El resto del catálogo —contact.*, task.completed, conversation.handoff, channel.run.*, app.*, snapshot.*, conversion.*— se emite siempre como evento vivo, así que una clave met_test_ no lo recibe nunca, ni en vivo ni del registro. Para escuchar esos tipos necesitas una clave met_live_.
• 30 días. Lo más viejo se borra.

Historial de cambios del workspace

Otra cosa distinta, y por eso tiene otro nombre: qué entidad se tocó, quién y con qué quedó antes y después. No son los eventos del catálogo.

const cambios  = await met.events.changes();            // cambios del workspace
const actividad = await met.events.activity();          // actividad del workspace
const deItem   = await met.events.itemActivity(1234);   // actividad de un item puntual