SDK

TypeScript / Node.js

@inceptiva/sdk es el SDK oficial para Node.js 18 o posterior. Es un módulo ES e incluye tipos TypeScript.

Instalación

npm

npm install @inceptiva/sdk

Crear el cliente

import { Inceptiva } from "@inceptiva/sdk";

const client = new Inceptiva({
  apiKey: process.env.INCEPTIVA_API_KEY!,
  agentId: process.env.INCEPTIVA_AGENT_ID!,
});

apiKey y agentId son obligatorios. baseUrl y una implementación personalizada de fetch son opcionales.

Consultar el agente

const agent = await client.getAgent();

console.log(agent.name);
console.log(agent.capabilities);

Las capacidades indican si el canal admite conversaciones, citas, extractos, documentos y voz.

Crear respuestas

const first = await client.responses.create({
  message: "Analiza esta oportunidad comercial",
  metadata: { source: "crm" },
});

const followUp = await client.responses.create({
  message: "¿Qué acción recomiendas?",
  conversationId: first.conversationId,
});

console.log(followUp.response);
console.log(followUp.citations);

client.invoke(input) permanece disponible como alias compatible de responses.create(input).

Streaming SSE

import { collectStream } from "@inceptiva/sdk";

const events = client.responses.stream({
  message: "Resume la oportunidad",
  conversationId: followUp.conversationId,
  signal: controller.signal,
});

for await (const event of events) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Cuando necesitas el resultado final compatible con responses.create():

const result = await collectStream(client.responses.stream({
  message: "Resume la oportunidad",
  conversationId: followUp.conversationId,
}));

El iterador termina al recibir response.completed o error. Un stream iniciado nunca se reintenta automáticamente.

Historial

const history = await client.conversations.getMessages(
  followUp.conversationId,
);

for (const message of history.items) {
  console.log(message.role, message.content, message.citations);
}

Eliminar una conversación

await client.conversations.delete(followUp.conversationId);

Citas

Cada cita expone documentName, knowledgeBaseName, excerpt, section, page, distance y documentAvailable. Los campos opcionales se normalizan a null.

El SDK nunca acepta ni devuelve retrieval_sources; solamente expone citas públicas autorizadas por el canal.

Cancelación

const controller = new AbortController();

const pending = client.responses.create({
  message: "Genera un resumen",
  signal: controller.signal,
});

controller.abort();
await pending;

Consulta Errores y la referencia preservada de v0.1.

Idempotencia, referencia externa e historial paginado

const result = await client.responses.create({
  message: "Actualiza el resumen",
  externalReference: "ticket-4821",
  idempotencyKey: crypto.randomUUID(),
  metadata: { customer_id: "123", source: "helpcenter" },
});

const history = await client.conversations.getMessages(result.conversationId, { page: 1, pageSize: 50 });
console.log(result.responseMetadata.idempotencyReplayed);
console.log(result.responseMetadata.rateLimit.remaining);
console.log(history.total, history.hasMore);

Una clave puede tener hasta 128 caracteres. Reutilizarla con otro payload produce InceptivaConflictError y el código idempotency_key_reused.