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/sdknpm 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 projectIní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ção | Padrão | Descrição |
|---|---|---|
apiKey | DCISION_API_KEY | dcs_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. |
baseUrl | https://api.dcision.io | Precisa 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. |
timeoutMs | 30000 | Timeout de cada tentativa, em milissegundos. |
maxRetries | 2 | Retries depois de um erro de rede, um timeout, 429, 502, 503 ou 504. |
fetch | o fetch global | Uma 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ção | Descrição |
|---|---|
idempotencyKey | O 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. |
includeProbabilities | Acrescenta probabilities, a distribuição completa de cada pergunta (?include=probabilities). |
functions | Handlers para destinos de função. |
onMissingFunction | "throw" (padrão) ou "ignore". |
signal | Um 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 dedestinations, 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,
decidelançaDcisionErrorFUNCTION_NOT_REGISTEREDe nenhum handler roda — a menos que você passeonMissingFunction: "ignore". - Um handler lança um erro: os handlers seguintes não são chamados e
decidelançaDcisionErrorFUNCTION_FAILED, comcause(o que o handler lançou),decisionefunctionResults(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. Chamardecidede novo com o mesmoidempotencyKeyrepete a resposta guardada e despacha as funções dela de novo, então torne os handlers idempotentes — por exemplo, indexados pordecision.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;
}| Campo | Descrição |
|---|---|
code | Um código estável: use-o no switch, não o message. |
message | Uma explicação legível. |
status | O status HTTP; undefined quando não houve resposta (erro de rede, timeout) ou a checagem foi local. |
requestId | O request_id da requisição (X-Request-ID): cite-o quando falar com o suporte. |
details | Dados extras para alguns códigos — veja Erros. |
retryAfter | Os segundos do header Retry-After, quando houve um. |
idempotencyKey | O Idempotency-Key que decide enviou: reutilize-o para tentar de novo com segurança depois. |
cause | O erro subjacente: uma falha de rede, a exceção de um handler. |
decision, functionResults | Só em FUNCTION_NOT_REGISTERED e FUNCTION_FAILED. |
Os códigos da API estão listados em Erros. O SDK acrescenta:
| Código | Quando |
|---|---|
NETWORK_ERROR | Nenhuma resposta da API: falha de DNS, conexão recusada ou resetada, erro de TLS. Recebe retry. |
TIMEOUT | Uma tentativa demorou mais que timeoutMs. Recebe retry. |
FUNCTION_NOT_REGISTERED | Um destino de função não tem handler em functions. |
FUNCTION_FAILED | Um handler lançou um erro. |
INVALID_SIGNATURE | Um 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 retry | Não recebe retry |
|---|---|
| Erros de rede e timeouts | 500 INTERNAL_ERROR |
409 IDEMPOTENCY_CONFLICT com Retry-After: a primeira requisição com a chave ainda está rodando | 409 sem Retry-After — uma requisição diferente reutilizou a chave — e os demais 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED e ENGINE_INVALID_REQUEST: falham do mesmo jeito toda vez |
Outros erros 502, 503 e 504 | Erros de função e de assinatura |
- Até
maxRetriesretries: 2 por padrão, ou seja, 3 tentativas. - O SDK espera o
Retry-Afterquando a API o envia, até 30 s. UmRetry-Aftermaior não é aguardado: o erro é lançado na hora, comretryAfterpreenchido, 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()eexecutionsrecebem 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, comostring,Uint8ArrayouBuffer, ouArrayBuffer;header— o headerDcision-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 denow;now— segundos Unix ou umDate, 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
| Runtime | Observações |
|---|---|
| Node.js 20+ | ESM (import) e CommonJS (require). |
| Bun | Igual ao Node.js. |
| Deno | Importe 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 Edge | Passe apiKey a partir dos seus bindings ou do ambiente. |
| Navegadores | Nã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 emJSON.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.
Visão geral dos SDKs
Os SDKs oficiais de TypeScript e Python — o que eles acrescentam ao HTTPS puro, como se comparam e como compilá-los do código-fonte até serem publicados no npm e no PyPI.
SDK Python
O pacote dcision para Python 3.9+ — build a partir do código-fonte, decide, destinos e funções, erros, retries idempotentes, execuções, me() e verificação de webhooks com Flask ou FastAPI.