SDK de TypeScript | SignalCore

@signalcore/sdk es la API en TypeScript: cada endpoint de la referencia es un método, con sus tipos. Para tu servidor, con una clave secreta; nunca en una página (para eso están los componentes).

npm install @signalcore/sdk@2

Node 22 o posterior, Deno o Bun. Sin dependencias. La versión 2 es la de SignalCore 2.0.

Hablar con un agente

import { SignalCore } from "@signalcore/sdk";
const client = new SignalCore("sk_..."); // o la variable SIGNALCORE_API_KEY
const [equipo] = await client.squads.list();
const agente = await client.agents.create(equipo!.id, {
  name: "Recepción",
  instructions: "Responde breve.",
});
const conversacion = await client.conversations.start(agente.id);
const respuesta = await client.conversations.say(conversacion.id, {
  text: "¿Abrís el sábado?",
  wait: true,
});
console.log(respuesta.status, respuesta.replies[0]?.text);

Con wait: true la respuesta llega cuando el agente termina (hasta un minuto). status es done, waiting (espera una respuesta o un sí, en waiting) o failed (con error).

Organizaciones de tus clientes

const cliente = await client.orgs.create({ name: "Clínica Norte" });
const suyo = new SignalCore("sk_...", { org: cliente.id }); // cada llamada lleva SignalCore-Org

Tokens de persona

Tu servidor crea el token y tu página lo usa con los componentes:

const { token } = await client.tokens.create({
  agents: [agente.id],
  external_id: "user_42",
  name: "Lucía Pérez",
});

En directo

Lo que pasa en la conversación, mensaje a mensaje, como un iterable asíncrono:

const live = client.conversations.live(conversacionId);
await live.say("Hola");
for await (const frame of live) {
  if (frame.type === "done") break; // al salir del bucle se cierra
}

Webhooks

verify comprueba la firma sobre el cuerpo tal como llega (el texto, sin parsear) y te da el evento:

import { SignatureError, verify } from "@signalcore/sdk";
app.post("/signalcore", express.text({ type: "*/*" }), async (req, res) => {
  try {
    const evento = await verify(req.body, req.headers, process.env.WEBHOOK_SECRET!);
    res.sendStatus(204);
  } catch (error) {
    if (error instanceof SignatureError) return res.sendStatus(400);
    throw error;
  }
});

Errores

Todo lo que la API rechaza es un ApiError con status, code (para tu código) y detail (en palabras), los mismos de la API.

import { ApiError } from "@signalcore/sdk";
try {
  await client.agents.get("agt_...");
} catch (error) {
  if (error instanceof ApiError && error.code === "not_found") {
    // ...
  }
}

Cada endpoint

El método se llama como la operación de la referencia, en camelCase: agents_memories_create es client.agents.memoriesCreate(...). Primero los parámetros de la ruta, luego el cuerpo y la consulta como objetos, y al final { idempotencyKey, signal }. Las listas largas se recorren con iter (for await (const run of client.runs.iter())).