SDK de TypeScript

@dcision/sdk para Node.js, Bun, Deno y runtimes edge — compilación desde el código fuente, decide, destinos y funciones, errores, reintentos idempotentes, ejecuciones, me() y verificación de webhooks.

@dcision/sdk es el SDK oficial de JavaScript y TypeScript. No tiene dependencias — solo usa fetch y Web Crypto —, incluye ESM, CommonJS y tipos, y funciona en Node.js 20+, Bun, Deno y runtimes edge.

Instalación

Todavía no está en npm

@dcision/sdk no está publicado en npm. Compílalo desde un checkout del repositorio de Dcision; hasta que esta página diga que está publicado, un paquete con este nombre en npm no viene de Dcision.

# 1. In a checkout of the Dcision repository (Node.js 22 and pnpm 10)
pnpm install
pnpm --filter @dcision/sdk build

# 2. In your project
npm install /path/to/dcision/packages/sdk

npm install con una carpeta la enlaza en tu proyecto; pnpm, yarn y bun aceptan la misma ruta. Para copiar el paquete en su lugar — a una imagen Docker, a otra máquina — genera un tarball e instálalo:

cd /path/to/dcision/packages/sdk && npm pack   # writes dcision-sdk-0.1.0.tgz
npm install ./dcision-sdk-0.1.0.tgz           # in your project

Inicio rápido

Crea una clave de API en API Keys y defínela como DCISION_API_KEY en el entorno de tu servidor.

import { Dcision } from "@dcision/sdk";

const dcision = new Dcision(); // reads DCISION_API_KEY

const decision = await dcision.decide("lead-qualification", {
  message: "We need pricing for 500 users and want to start next month.",
  company_size: 500,
});

decision.result.route; // "sales"
decision.confidence.route; // 0.85
decision.action; // "continue" | "block" | "escalate" | "fallback"
decision.destinations; // what happens next: replies, queued deliveries, functions…

CommonJS funciona igual: const { Dcision } = require("@dcision/sdk").

Configuración

const dcision = new Dcision({
  apiKey: process.env.DCISION_API_KEY, // default: the DCISION_API_KEY environment variable
  timeoutMs: 30_000,
  maxRetries: 2,
  userAgent: "acme-crm/2.1",
});
OpciónPredeterminadoDescripción
apiKeyDCISION_API_KEYdcs_live_… o dcs_test_…. Una clave ausente, o que no empieza con dcs_, lanza DcisionError INVALID_API_KEY de inmediato — no se envía nada.
baseUrlhttps://api.dcision.ioDebe usar https — http simple solo para una API en una dirección de loopback. Un prefijo de ruta está bien; se rechazan credenciales, query string o fragmento.
timeoutMs30000Timeout de cada intento, en milisegundos.
maxRetries2Reintentos tras un error de red, un timeout, 429, 502, 503 o 504.
fetchel fetch globalUna implementación personalizada: (url, init) => Promise<Response>.
userAgent—El identificador de tu app, antepuesto al del SDK: acme-crm/2.1 dcision-sdk-js/0.1.0.

Crea un solo cliente y compártelo: no guarda estado por solicitud.

Ejecutar una decisión

const decision = await dcision.decide(slug, state, options);

state es lo que evalúa la decisión — un string, un objeto o un array, según declare la decisión. El slug se comprueba localmente (letras minúsculas, dígitos y guiones simples) antes de enviar nada.

OpciónDescripción
idempotencyKeyEl Idempotency-Key: de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Predeterminado: un UUID nuevo por llamada, reutilizado por todos sus reintentos.
includeProbabilitiesAgrega probabilities, la distribución completa de cada pregunta (?include=probabilities).
functionsHandlers para los destinos de función.
onMissingFunction"throw" (predeterminado) o "ignore".
signalUn AbortSignal: abortar detiene la solicitud y sus reintentos, y decide se rechaza con signal.reason.

decide se resuelve en un Decision: todos los campos de la respuesta de la API — decision_id, execution_id, schema, version, result, confidence, scores, composites, action, action_reason, probabilities, metrics, destinations — más functionResults y dispatch(). destinations siempre es un array: [] cuando la decisión no tiene ninguno o ninguno se disparó.

Una decisión con onEngineError: "fallback" responde con su acción de fallback cuando el motor falla: en ese caso action_reason.type es "engine_error" y result y confidence son objetos vacíos.

Destinos

decision.destinations contiene las entradas de destino de la respuesta. Destination es una unión que se acota por type y status:

for (const destination of decision.destinations) {
  if (destination.type === "reply") chat.send(destination.text, destination.buttons);
  else if (destination.type === "llm" && destination.status === "completed") chat.send(destination.text);
  else if (destination.type === "agent" && destination.status === "completed") chat.send(destination.reply ?? "");
  else if (destination.status === "failed") log.warn(`${destination.key}: ${destination.error}`);
  else if (destination.status === "queued") log.info(`${destination.key} queued as ${destination.delivery_id}`);
  else if (destination.status === "skipped") log.info(`${destination.key} skipped: ${destination.reason}`);
}

Destinos de función

Un destino de función nombra una función y sus params. Pasa los handlers en functions y el SDK los llama después de la decisión:

const decision = await dcision.decide("lead-qualification", { message, email }, {
  functions: {
    assignToSales: async (params, decision) => crm.assign(String(params.email), decision.result.route),
    notifySlack: (params) => slack.post(String(params.text)),
  },
});

decision.functionResults;
// [{ key: "assign_owner", function: "assignToSales", result: <what the handler returned> }]
  • Los handlers se llaman como functions[name](params, decision), en el orden de destinations, de uno en uno: un handler asíncrono se espera antes de que empiece el siguiente.
  • Solo se llaman las entradas de función que se dispararon — no las omitidas, ni las de otros tipos.
  • Handler ausente: todos los handlers se buscan antes de que se ejecute el primero. Si falta uno, decide lanza DcisionError FUNCTION_NOT_REGISTERED y no se ejecuta ningún handler — a menos que pases onMissingFunction: "ignore".
  • Un handler lanza un error: los siguientes handlers no se llaman y decide lanza DcisionError FUNCTION_FAILED, con cause (lo que lanzó el handler), decision y functionResults (los handlers que terminaron). La decisión ya se ejecutó — y se facturó.
  • Los handlers se ejecutan una vez por llamada a decide, después de la respuesta final: los reintentos dentro de la llamada nunca despachan dos veces. Llamar a decide de nuevo con el mismo idempotencyKey reproduce la respuesta guardada y vuelve a despachar sus funciones, así que haz los handlers idempotentes — por ejemplo, indexados por decision.execution_id.

Despacha más tarde, o en otro lugar, a partir de una respuesta guardada:

import { Decision } from "@dcision/sdk";

const decision = await dcision.decide("lead-qualification", state); // no functions: nothing is called
await queue.push(JSON.stringify(decision));

// in a worker
const results = await new Decision(JSON.parse(job.payload)).dispatch(handlers, { onMissingFunction: "ignore" });

Errores

Todo lo que el SDK lanza por una respuesta de la API, un fallo de red, un handler o una firma es un DcisionError:

import { DcisionError } from "@dcision/sdk";

try {
  await dcision.decide("lead-qualification", state);
} catch (error) {
  if (error instanceof DcisionError && error.code === "INVALID_STATE") return reportBadInput(error.message);
  throw error;
}
CampoDescripción
codeUn código estable: decide en función de él, no de message.
messageUna explicación legible para personas.
statusEl estado HTTP; undefined cuando no hubo respuesta (error de red, timeout) o la comprobación fue local.
requestIdEl request_id de la solicitud (X-Request-ID): inclúyelo cuando contactes a soporte.
detailsDatos adicionales para algunos códigos — consulta Errores.
retryAfterSegundos del header Retry-After, cuando lo hubo.
idempotencyKeyEl Idempotency-Key que envió decide: reutilízalo para reintentar de forma segura más tarde.
causeEl error subyacente: un fallo de red, la excepción de un handler.
decision, functionResultsSolo FUNCTION_NOT_REGISTERED y FUNCTION_FAILED.

Los códigos de la API se listan en Errores. El SDK agrega:

CódigoCuándo
NETWORK_ERRORSin respuesta de la API: fallo de DNS, conexión rechazada o reiniciada, error de TLS. Se reintenta.
TIMEOUTUn intento tardó más que timeoutMs. Se reintenta.
FUNCTION_NOT_REGISTEREDUn destino de función no tiene handler en functions.
FUNCTION_FAILEDUn handler lanzó un error.
INVALID_SIGNATUREUn webhook no pasó la verificación.

Las comprobaciones locales reutilizan los códigos de la API con status indefinido: INVALID_API_KEY para una clave ausente o mal formada, INVALID_REQUEST para un slug o un idempotencyKey incorrectos o un estado ausente. Una respuesta que no viene de la API — una página HTML de un proxy, una redirección — conserva su estado HTTP, con un código de respaldo: INVALID_API_KEY (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), PAYLOAD_TOO_LARGE (413), RATE_LIMITED (429), INVALID_REQUEST (otros 4xx) o INTERNAL_ERROR. Las redirecciones nunca se siguen.

Reintentos e idempotencia

decide envía un Idempotency-Key, generado una vez por llamada y reutilizado por cada reintento. Si un intento ejecutó la decisión pero su respuesta se perdió, el reintento recibe la respuesta guardada: los reintentos nunca ejecutan, ni facturan, una decisión dos veces.

Se reintentaNo se reintenta
Errores de red y timeouts500 INTERNAL_ERROR
409 IDEMPOTENCY_CONFLICT con Retry-After: la primera solicitud con la clave todavía se está ejecutando409 sin Retry-After — otra solicitud reutilizó la clave — y los demás 4xx
429 RATE_LIMITED502 ENGINE_AUTH_FAILED y ENGINE_INVALID_REQUEST: fallan igual cada vez
Otros errores 502, 503 y 504Errores de función y de firma
  • Hasta maxRetries reintentos: 2 de forma predeterminada, es decir, 3 intentos.
  • El SDK espera Retry-After cuando la API lo envía, hasta 30 s. Un Retry-After más largo no se espera: el error se lanza de inmediato, con retryAfter definido, para que puedas programar el reintento.
  • Sin Retry-After, espera 0.5 s, 1 s, 2 s… — duplicando, como máximo 8 s — más hasta un 25% de jitter aleatorio.
  • me() y executions se reintentan de la misma forma.

El caso 409 es lo que hace seguro un timeout: si un intento agota el tiempo mientras la decisión todavía se ejecuta, el reintento encuentra la clave reservada, espera un segundo (Retry-After: 1) y vuelve a intentarlo hasta obtener la respuesta guardada — o se queda sin reintentos y lanza IDEMPOTENCY_CONFLICT con la clave en error.idempotencyKey, para intentarlo de nuevo más tarde.

Pasa tu propia clave para que los reintentos sean seguros entre procesos o reinicios, por ejemplo el ID de aquello sobre lo que decides:

await dcision.decide("support-routing", ticket, { idempotencyKey: `ticket-${ticket.id}` });

timeoutMs se aplica a cada intento; para un plazo sobre toda la llamada, pasa un signal: { signal: AbortSignal.timeout(15_000) }. Mantén timeoutMs por encima del propio timeoutMs de la decisión (5 s de forma predeterminada, 30 s como máximo) más el timeout de su destino de LLM o de agente sync más lento, para que un intento haya terminado de verdad del lado de Dcision antes de reintentarse.

Cuenta y ejecuciones

const me = await dcision.me();
me.plan.rate_limit_per_minute;
me.usage.used / me.usage.included;

// one page, newest first
const page = await dcision.executions.list({ decision: "lead-qualification", status: "error", limit: 100 });
page.data; // the runs: answers, action, metrics — never the inputs
page.next_cursor; // pass it as `cursor` for the next page; null on the last one

// every page
for await (const run of dcision.executions.iterate({ decision: "lead-qualification", limit: 100 })) {
  console.log(run.created_at, run.result?.route, run.action);
}

iterate() obtiene la siguiente página solo cuando llegas a ella, así que break la detiene. Las lecturas nunca se facturan y tienen su propia ventana de rate limit — consulta Obtener cuenta y uso y Listar ejecuciones.

Modo socio

Los socios mantienen un subespacio por cliente. withWorkspace() devuelve un cliente que actúa en uno de ellos (header Dcision-Workspace); workspaces y embed los gestionan — del lado del servidor, con tu clave de API.

await dcision.workspaces.upsert({ external_id: "acme", name: "Acme Inc", seed: { decisions: ["lead-qualification"], deploy: true } });
await dcision.withWorkspace("ext:acme").decide("lead-qualification", { message: "Pricing?" });
const { url } = await dcision.embed.createSession({ workspace: "ext:acme", user: { id: user.id, name: user.name } });

Webhooks

import { DcisionError, verifyWebhook } from "@dcision/sdk";

const event = await verifyWebhook(rawBody, signatureHeader, process.env.DCISION_WEBHOOK_SECRET!);
event.type; // "decision.completed"
event.id; // "dlv_…": the same on every delivery attempt
event.data.result.route; // "sales"
event.data.params; // the params mapped in the destination (the state itself is never sent)

verifyWebhook(body, header, secret, { toleranceSec = 300, now }):

  • body — el body sin procesar, como string, Uint8Array o Buffer, o un ArrayBuffer;
  • header — el header Dcision-Signature;
  • secret — el secreto de firma (whsec_…, en Configuración → Destinos), o un array de secretos mientras lo rotas;
  • toleranceSec — cuánto puede alejarse de now el timestamp de la firma;
  • now — segundos Unix o un Date, para pruebas.

Lanza DcisionError INVALID_SIGNATURE cuando el header falta o está mal formado, ninguna firma coincide (comparación en tiempo constante), el timestamp está fuera de la tolerancia o el body no es un evento JSON — responde 400. Un uso incorrecto, como no pasar un secreto o pasar un body ya parseado, lanza en cambio un TypeError — responde 500, para que Dcision siga reintentando hasta que se despliegue la corrección.

verifySignature(body, header, secret, options) hace las mismas comprobaciones sin parsear el body: úsalo para solicitudes de API y agentes, cuyos bodies no son eventos.

Hay receptores completos para Express y Next.js en Webhooks.

TypeScript

Tipa las respuestas de una decisión con un genérico — las interfaces también funcionan:

interface LeadResult {
  route: "sales" | "sdr" | "nurture" | "spam" | "other";
  purchase_intent: number;
}

const decision = await dcision.decide<LeadResult>("lead-qualification", state, {
  functions: {
    // handlers can declare the params they expect
    assignToSales: async (params: { email: string }, decision) => crm.assign(params.email, decision.result.route),
  },
});
decision.result.route; // "sales" | "sdr" | "nurture" | "spam" | "other"

const event = await verifyWebhook<LeadResult>(body, header, secret);
event.data.result.route;

El paquete exporta Dcision, Decision, DcisionError, verifyWebhook, verifySignature y VERSION, y tipos como DecisionResponse, Destination, QueuedDestination, SkippedDestination, FunctionDestination, WebhookEvent, Me, Execution, ExecutionPage y DcisionErrorCode.

Runtimes compatibles

RuntimeNotas
Node.js 20+ESM (import) y CommonJS (require).
BunIgual que Node.js.
DenoImporta la compilación: import { Dcision } from "/path/to/dcision/packages/sdk/dist/esm/index.js". Permite la red (--allow-net=api.dcision.io) y, para leer DCISION_API_KEY, --allow-env=DCISION_API_KEY — o pasa apiKey.
Cloudflare Workers, Vercel EdgePasa apiKey desde tus bindings o tu entorno.
NavegadoresNo compatible: una clave de API en un navegador es pública. Llama a Dcision desde tu servidor.

Notas de seguridad

  • La clave de API se mantiene privada. Vive en un campo privado — no la imprime console.log, no aparece en JSON.stringify — y nunca aparece en un mensaje de error. Un valor que no es una clave de Dcision se rechaza antes de cualquier solicitud.
  • Transporte. Solo https, y las redirecciones nunca se siguen, así que la clave nunca llega a otro host.
  • Rutas. El slug se valida y se codifica: nada más puede terminar en la ruta de la URL.
  • Webhooks. HMAC-SHA256 comparado en tiempo constante, timestamps fuera de la tolerancia rechazados, verificación solo sobre los bytes sin procesar.

En esta página