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/sdknpm 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 projectInicio 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ón | Predeterminado | Descripción |
|---|---|---|
apiKey | DCISION_API_KEY | dcs_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. |
baseUrl | https://api.dcision.io | Debe 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. |
timeoutMs | 30000 | Timeout de cada intento, en milisegundos. |
maxRetries | 2 | Reintentos tras un error de red, un timeout, 429, 502, 503 o 504. |
fetch | el fetch global | Una 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ón | Descripción |
|---|---|
idempotencyKey | El 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. |
includeProbabilities | Agrega probabilities, la distribución completa de cada pregunta (?include=probabilities). |
functions | Handlers para los destinos de función. |
onMissingFunction | "throw" (predeterminado) o "ignore". |
signal | Un 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 dedestinations, 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,
decidelanzaDcisionErrorFUNCTION_NOT_REGISTEREDy no se ejecuta ningún handler — a menos que pasesonMissingFunction: "ignore". - Un handler lanza un error: los siguientes handlers no se llaman y
decidelanzaDcisionErrorFUNCTION_FAILED, concause(lo que lanzó el handler),decisionyfunctionResults(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 adecidede nuevo con el mismoidempotencyKeyreproduce la respuesta guardada y vuelve a despachar sus funciones, así que haz los handlers idempotentes — por ejemplo, indexados pordecision.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;
}| Campo | Descripción |
|---|---|
code | Un código estable: decide en función de él, no de message. |
message | Una explicación legible para personas. |
status | El estado HTTP; undefined cuando no hubo respuesta (error de red, timeout) o la comprobación fue local. |
requestId | El request_id de la solicitud (X-Request-ID): inclúyelo cuando contactes a soporte. |
details | Datos adicionales para algunos códigos — consulta Errores. |
retryAfter | Segundos del header Retry-After, cuando lo hubo. |
idempotencyKey | El Idempotency-Key que envió decide: reutilízalo para reintentar de forma segura más tarde. |
cause | El error subyacente: un fallo de red, la excepción de un handler. |
decision, functionResults | Solo FUNCTION_NOT_REGISTERED y FUNCTION_FAILED. |
Los códigos de la API se listan en Errores. El SDK agrega:
| Código | Cuándo |
|---|---|
NETWORK_ERROR | Sin respuesta de la API: fallo de DNS, conexión rechazada o reiniciada, error de TLS. Se reintenta. |
TIMEOUT | Un intento tardó más que timeoutMs. Se reintenta. |
FUNCTION_NOT_REGISTERED | Un destino de función no tiene handler en functions. |
FUNCTION_FAILED | Un handler lanzó un error. |
INVALID_SIGNATURE | Un 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 reintenta | No se reintenta |
|---|---|
| Errores de red y timeouts | 500 INTERNAL_ERROR |
409 IDEMPOTENCY_CONFLICT con Retry-After: la primera solicitud con la clave todavía se está ejecutando | 409 sin Retry-After — otra solicitud reutilizó la clave — y los demás 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED y ENGINE_INVALID_REQUEST: fallan igual cada vez |
Otros errores 502, 503 y 504 | Errores de función y de firma |
- Hasta
maxRetriesreintentos: 2 de forma predeterminada, es decir, 3 intentos. - El SDK espera
Retry-Aftercuando la API lo envía, hasta 30 s. UnRetry-Aftermás largo no se espera: el error se lanza de inmediato, conretryAfterdefinido, 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()yexecutionsse 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, comostring,Uint8ArrayoBuffer, o unArrayBuffer;header— el headerDcision-Signature;secret— el secreto de firma (whsec_…, en Configuración → Destinos), o un array de secretos mientras lo rotas;toleranceSec— cuánto puede alejarse denowel timestamp de la firma;now— segundos Unix o unDate, 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
| Runtime | Notas |
|---|---|
| Node.js 20+ | ESM (import) y CommonJS (require). |
| Bun | Igual que Node.js. |
| Deno | Importa 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 Edge | Pasa apiKey desde tus bindings o tu entorno. |
| Navegadores | No 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 enJSON.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.
Resumen de los SDKs
Los SDKs oficiales de TypeScript y Python — qué agregan frente a HTTPS directo, cómo se comparan y cómo compilarlos desde el código fuente hasta que se publiquen en npm y PyPI.
SDK de Python
El paquete dcision para Python 3.9+ — compilación desde el código fuente, decide, destinos y funciones, errores, reintentos idempotentes, ejecuciones, me() y verificación de webhooks con Flask o FastAPI.