SDK de Node.js | Lectico Docs

Instalación

npm install @lectico/api

Requiere Node.js 18 o superior. El paquete es ESM only (sin CommonJS). Si tu proyecto todavía usa require(), tendrás que migrar a import o esperar a la build CJS futura.

Primer uso

import Lectico from "@lectico/api";

const lectico = new Lectico({ apiKey: process.env.LECTICO_API_KEY! });

const agent = await lectico.agents.create({
  type: "support",
  name: "Soporte Demo",
});

console.log(agent.id, agent.slug);

Configuración

new Lectico({
  apiKey: "sk_live_...",              // obligatorio
  baseUrl: "https://api.lectico.com", // por defecto
  timeoutMs: 30000,                   // timeout por peticion
  maxRetries: 2,                      // reintentos en 429 y 5xx
});

Recursos disponibles

lectico.agents          // CRUD + iterAll + messages
lectico.knowledge       // list, create, delete
lectico.conversations   // list, get
lectico.leads           // list, get, delete
lectico.webhooks        // CRUD + deliveries + test
lectico.files           // create (presigned URL), get, delete
lectico.usage           // summary

Cada recurso expone los métodos descritos en la referencia REST.

Streaming de mensajes

Por defecto, agents.messages.create devuelve un AsyncIterable de eventos SSE:

const stream = await lectico.agents.messages.create(agent.id, {
  message: "Hola, que puedes hacer?",
});

for await (const ev of stream as AsyncIterable<any>) {
  if (ev.type === "token") process.stdout.write(ev.content ?? "");
  if (ev.type === "sources") console.log("\nFuentes:", ev.sources);
  if (ev.type === "done") console.log("\n[Fin]");
}

Para recibir JSON plano en lugar de streaming, pasa stream: false:

const reply = await lectico.agents.messages.create(agent.id, {
  message: "Hola",
  stream: false,
});
// reply es un ChatMessage

Tipos de evento: token, sources, chunks, done, expert_thinking, expert_mode, escalation_offer, support_contact, error.

Auto-paginación

for await (const lead of lectico.leads.iterAll({ limit: 100 })) {
  await enviarACrm(lead);
}

El SDK se encarga de pasar starting_after entre páginas. Funciona para todos los recursos con listas.

Verificación de webhooks

El módulo /webhooks expone constructEvent:

import { constructEvent } from "@lectico/api/webhooks";

const event = constructEvent(
  req.body,                          // Buffer (raw)
  req.header("Lectico-Signature"),
  process.env.LECTICO_WEBHOOK_SECRET!,
);

Ver verificación de firma para el ejemplo completo con Express.

Manejo de errores

Todos los errores de la API son subclases de LecticoError:

import {
  LecticoError,
  AuthenticationError,
  PaymentRequiredError,
  PermissionDeniedError,
  NotFoundError,
  ConflictError,
  InvalidRequestError,
  RateLimitError,
  InternalServerError,
} from "@lectico/api";

try {
  await lectico.agents.get("agt_missing");
} catch (err) {
  if (err instanceof NotFoundError) return null;
  if (err instanceof RateLimitError) {
    await sleep(err.retryAfterSeconds * 1000);
    // reintentar manualmente
  }
  throw err;
}

El SDK reintenta automáticamente 429 y 5xx con backoff exponencial hasta maxRetries veces. No tienes que hacerlo tú salvo que quieras lógica custom.

Idempotencia

Pasa idempotencyKey como opción en cualquier POST:

await lectico.agents.create(
  { type: "support", name: "Bot" },
  { idempotencyKey: crypto.randomUUID() },
);

AbortSignal

Soporta cancelación nativa:

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 5000);

await lectico.agents.list({}, { signal: ctrl.signal });

Recursos

npm: @lectico/api
GitHub: lectico/lectico-sdk-node
Changelog: esta sección

En esta página