SDK TypeScript

@dcision/sdk para Node.js, Bun, Deno e runtimes edge — compilar do código-fonte, decide, destinos e funções, erros, retries idempotentes, execuções, me() e verificação de webhooks.

@dcision/sdk é o SDK oficial para JavaScript e TypeScript. Ele não tem dependências — usa só fetch e Web Crypto —, traz ESM, CommonJS e tipos, e roda em Node.js 20+, Bun, Deno e runtimes edge.

Instalação

Ainda não está no npm

@dcision/sdk não está publicado no npm. Compile-o a partir de um checkout do repositório da Dcision; até esta página dizer que ele foi publicado, um pacote com esse nome no npm não vem da 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 com uma pasta a vincula ao seu projeto; pnpm, yarn e bun aceitam o mesmo caminho. Para copiar o pacote — para uma imagem Docker, outra máquina —, gere um tarball e instale-o:

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

Início rápido

Crie uma API key em API Keys e defina-a como DCISION_API_KEY no ambiente do seu 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 do mesmo jeito: const { Dcision } = require("@dcision/sdk").

Configuração

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",
});
OpçãoPadrãoDescrição
apiKeyDCISION_API_KEYdcs_live_… ou dcs_test_…. Uma chave ausente, ou que não começa com dcs_, lança DcisionError INVALID_API_KEY na hora — nada é enviado.
baseUrlhttps://api.dcision.ioPrecisa usar https — http simples só para uma API num endereço de loopback. Um prefixo de caminho é aceito; credenciais, query string ou fragmento são recusados.
timeoutMs30000Timeout de cada tentativa, em milissegundos.
maxRetries2Retries depois de um erro de rede, um timeout, 429, 502, 503 ou 504.
fetcho fetch globalUma implementação personalizada: (url, init) => Promise<Response>.
userAgent—O identificador do seu app, colocado antes do identificador do SDK: acme-crm/2.1 dcision-sdk-js/0.1.0.

Crie um cliente e compartilhe-o: ele não guarda estado por requisição.

Executar uma decisão

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

state é o que a decisão avalia — uma string, um objeto ou um array, conforme a decisão declara. O slug é conferido localmente (letras minúsculas, dígitos e hifens simples) antes de qualquer envio.

OpçãoDescrição
idempotencyKeyO Idempotency-Key: de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Padrão: um novo UUID por chamada, reutilizado por todos os retries dela.
includeProbabilitiesAcrescenta probabilities, a distribuição completa de cada pergunta (?include=probabilities).
functionsHandlers para destinos de função.
onMissingFunction"throw" (padrão) ou "ignore".
signalUm AbortSignal: abortar interrompe a requisição e os retries dela, e decide rejeita com signal.reason.

decide resolve para um Decision: todos os campos da resposta da API — decision_id, execution_id, schema, version, result, confidence, scores, composites, action, action_reason, probabilities, metrics, destinations — mais functionResults e dispatch(). destinations é sempre um array: [] quando a decisão não tem nenhum ou nenhum disparou.

Uma decisão com onEngineError: "fallback" responde com a ação de fallback quando o engine falha: nesse caso, action_reason.type é "engine_error" e result e confidence são objetos vazios.

Destinos

decision.destinations traz as entradas de destinos da resposta. Destination é uma união que você estreita por type e 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 função

Um destino de função nomeia uma função e os params dela. Passe os handlers em functions e o SDK os chama depois da decisão:

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> }]
  • Os handlers são chamados como functions[name](params, decision), na ordem de destinations, um de cada vez: um handler assíncrono é aguardado antes que o próximo comece.
  • Só são chamadas as entradas de função que dispararam — não as ignoradas, nem as de outros tipos.
  • Handler ausente: todos os handlers são procurados antes de o primeiro rodar. Se faltar um, decide lança DcisionError FUNCTION_NOT_REGISTERED e nenhum handler roda — a menos que você passe onMissingFunction: "ignore".
  • Um handler lança um erro: os handlers seguintes não são chamados e decide lança DcisionError FUNCTION_FAILED, com cause (o que o handler lançou), decision e functionResults (os handlers que terminaram). A decisão já rodou — e foi cobrada.
  • Os handlers rodam uma vez por chamada de decide, depois da resposta final: os retries dentro da chamada nunca despacham duas vezes. Chamar decide de novo com o mesmo idempotencyKey repete a resposta guardada e despacha as funções dela de novo, então torne os handlers idempotentes — por exemplo, indexados por decision.execution_id.

Despache depois, ou em outro lugar, a partir de uma resposta 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" });

Erros

Tudo o que o SDK lança por uma resposta da API, uma falha de rede, um handler ou uma assinatura é um 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;
}
CampoDescrição
codeUm código estável: use-o no switch, não o message.
messageUma explicação legível.
statusO status HTTP; undefined quando não houve resposta (erro de rede, timeout) ou a checagem foi local.
requestIdO request_id da requisição (X-Request-ID): cite-o quando falar com o suporte.
detailsDados extras para alguns códigos — veja Erros.
retryAfterOs segundos do header Retry-After, quando houve um.
idempotencyKeyO Idempotency-Key que decide enviou: reutilize-o para tentar de novo com segurança depois.
causeO erro subjacente: uma falha de rede, a exceção de um handler.
decision, functionResultsSó em FUNCTION_NOT_REGISTERED e FUNCTION_FAILED.

Os códigos da API estão listados em Erros. O SDK acrescenta:

CódigoQuando
NETWORK_ERRORNenhuma resposta da API: falha de DNS, conexão recusada ou resetada, erro de TLS. Recebe retry.
TIMEOUTUma tentativa demorou mais que timeoutMs. Recebe retry.
FUNCTION_NOT_REGISTEREDUm destino de função não tem handler em functions.
FUNCTION_FAILEDUm handler lançou um erro.
INVALID_SIGNATUREUm webhook não passou na verificação.

As checagens locais reutilizam os códigos da API com status indefinido: INVALID_API_KEY para uma chave ausente ou malformada, INVALID_REQUEST para um slug inválido, um idempotencyKey inválido ou um estado ausente. Uma resposta que não vem da API — uma página HTML de um proxy, um redirecionamento — mantém o status HTTP dela, com um código de fallback: INVALID_API_KEY (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), PAYLOAD_TOO_LARGE (413), RATE_LIMITED (429), INVALID_REQUEST (outros 4xx) ou INTERNAL_ERROR. Os redirecionamentos nunca são seguidos.

Retries e idempotência

decide envia um Idempotency-Key, gerado uma vez por chamada e reutilizado por todos os retries. Se uma tentativa rodou a decisão mas a resposta se perdeu, o retry recebe a resposta guardada: os retries nunca rodam — nem cobram — uma decisão duas vezes.

Recebe retryNão recebe retry
Erros de rede e timeouts500 INTERNAL_ERROR
409 IDEMPOTENCY_CONFLICT com Retry-After: a primeira requisição com a chave ainda está rodando409 sem Retry-After — uma requisição diferente reutilizou a chave — e os demais 4xx
429 RATE_LIMITED502 ENGINE_AUTH_FAILED e ENGINE_INVALID_REQUEST: falham do mesmo jeito toda vez
Outros erros 502, 503 e 504Erros de função e de assinatura
  • Até maxRetries retries: 2 por padrão, ou seja, 3 tentativas.
  • O SDK espera o Retry-After quando a API o envia, até 30 s. Um Retry-After maior não é aguardado: o erro é lançado na hora, com retryAfter preenchido, para você agendar o retry.
  • Sem Retry-After, ele espera 0,5 s, 1 s, 2 s… — dobrando, no máximo 8 s — mais até 25% de jitter aleatório.
  • me() e executions recebem retry do mesmo jeito.

O caso 409 é o que torna um timeout seguro: se uma tentativa estoura o tempo enquanto a decisão ainda está rodando, o retry encontra a chave reservada, espera um segundo (Retry-After: 1) e tenta de novo até receber a resposta guardada — ou esgota os retries e lança IDEMPOTENCY_CONFLICT com a chave em error.idempotencyKey, para tentar de novo depois.

Passe a sua própria chave para tornar os retries seguros entre processos ou reinícios, por exemplo o ID da coisa sobre a qual você decide:

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

timeoutMs vale para cada tentativa; para um prazo na chamada inteira, passe um signal: { signal: AbortSignal.timeout(15_000) }. Mantenha timeoutMs acima do timeoutMs da própria decisão (5 s por padrão, 30 s no máximo) mais o timeout do destino LLM ou de agente sync mais lento dela, para que uma tentativa tenha mesmo terminado do lado da Dcision antes de receber retry.

Conta e execuções

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() busca a próxima página só quando você chega a ela, então um break o interrompe. As leituras nunca são cobradas e têm a própria janela de rate limit — veja Obter conta e uso e Listar execuções.

Modo parceiro

Os parceiros mantêm um sub-workspace por cliente. withWorkspace() devolve um cliente que age num deles (header Dcision-Workspace); workspaces e embed os gerenciam — no servidor, com a sua API key.

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 — o body bruto, como string, Uint8Array ou Buffer, ou ArrayBuffer;
  • header — o header Dcision-Signature;
  • secret — o segredo de assinatura (whsec_…, em Configurações → Destinos), ou um array de segredos enquanto você o troca;
  • toleranceSec — o quanto o timestamp da assinatura pode se afastar de now;
  • now — segundos Unix ou um Date, para testes.

Ele lança DcisionError INVALID_SIGNATURE quando o header está ausente ou malformado, nenhuma assinatura combina (comparada em tempo constante), o timestamp está fora da tolerância ou o body não é um evento JSON — responda 400. Um uso incorreto, como a falta de segredo ou um body já parseado, lança um TypeError — responda 500, para que a Dcision continue tentando até a correção ser publicada.

verifySignature(body, header, secret, options) faz as mesmas checagens sem parsear o body: use-o para requisições de API e agentes, cujos bodies não são eventos.

Receptores completos para Express e Next.js estão em Webhooks.

TypeScript

Tipe as respostas de uma decisão com um generic — interfaces também funcionam:

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;

O pacote exporta Dcision, Decision, DcisionError, verifyWebhook, verifySignature e VERSION, e tipos como DecisionResponse, Destination, QueuedDestination, SkippedDestination, FunctionDestination, WebhookEvent, Me, Execution, ExecutionPage e DcisionErrorCode.

Runtimes suportados

RuntimeObservações
Node.js 20+ESM (import) e CommonJS (require).
BunIgual ao Node.js.
DenoImporte o build: import { Dcision } from "/path/to/dcision/packages/sdk/dist/esm/index.js". Libere a rede (--allow-net=api.dcision.io) e, para ler DCISION_API_KEY, --allow-env=DCISION_API_KEY — ou passe apiKey.
Cloudflare Workers, Vercel EdgePasse apiKey a partir dos seus bindings ou do ambiente.
NavegadoresNão suportados: uma API key num navegador é pública. Chame a Dcision a partir do seu servidor.

Notas de segurança

  • A API key fica privada. Ela vive num campo privado — não é impressa por console.log, não aparece em JSON.stringify — e nunca aparece numa mensagem de erro. Um valor que não é uma chave da Dcision é recusado antes de qualquer requisição.
  • Transporte. Só https, e os redirecionamentos nunca são seguidos, então a chave nunca chega a outro host.
  • Caminhos. O slug é validado e codificado: nada mais pode acabar no caminho da URL.
  • Webhooks. HMAC-SHA256 comparado em tempo constante, timestamps fora da tolerância rejeitados, verificação só sobre os bytes brutos.

Nesta página