TypeScript SDK

@dcision/sdk для Node.js, Bun, Deno и edge-сред — сборка из исходников, decide, назначения и функции, ошибки, идемпотентные повторы, executions, me() и проверка вебхуков.

@dcision/sdk — официальный SDK для JavaScript и TypeScript. У него нет зависимостей — он использует только fetch и Web Crypto, — он поставляется в виде ESM, CommonJS и типов и работает на Node.js 20+, Bun, Deno и edge-средах.

Установка

Пока не в npm

@dcision/sdk не опубликован в npm. Соберите его из checkout репозитория Dcision; пока на этой странице не сказано, что он опубликован, пакет с таким именем в npm не имеет отношения к 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 с папкой подключает пакет в ваш проект по ссылке; pnpm, yarn и bun принимают тот же путь. Чтобы вместо этого скопировать пакет — в Docker-образ, на другую машину, — соберите tarball и установите его:

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

Быстрый старт

Создайте API-ключ в разделе API-ключи и задайте его как DCISION_API_KEY в окружении вашего сервера.

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 работает так же: const { Dcision } = require("@dcision/sdk").

Конфигурация

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",
});
ПараметрПо умолчаниюОписание
apiKeyDCISION_API_KEYdcs_live_… или dcs_test_…. Отсутствующий ключ или ключ, который не начинается с dcs_, сразу выбрасывает DcisionError INVALID_API_KEY — ничего не отправляется.
baseUrlhttps://api.dcision.ioДолжен использовать https — обычный http только для API на loopback-адресе. Префикс пути допустим; учётные данные, строка запроса или фрагмент отклоняются.
timeoutMs30000Тайм-аут каждой попытки, в миллисекундах.
maxRetries2Повторы после сетевой ошибки, тайм-аута, 429, 502, 503 или 504.
fetchглобальный fetchСобственная реализация: (url, init) => Promise<Response>.
userAgent—Идентификатор вашего приложения, добавляемый перед идентификатором SDK: acme-crm/2.1 dcision-sdk-js/0.1.0.

Создайте один клиент и используйте его везде: он не хранит состояния между запросами.

Запуск решения

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

state — то, что оценивает решение: строка, объект или массив, как объявлено в решении. Slug проверяется локально (строчные буквы, цифры и одиночные дефисы) до отправки чего-либо.

ПараметрОписание
idempotencyKeyIdempotency-Key: от 1 до 128 символов из A–Z a–z 0–9 . _ : -. По умолчанию — новый UUID на каждый вызов, который переиспользуется всеми его повторами.
includeProbabilitiesДобавляет probabilities, полное распределение по каждому вопросу (?include=probabilities).
functionsОбработчики для функций-назначений.
onMissingFunction"throw" (по умолчанию) или "ignore".
signalAbortSignal: прерывание останавливает запрос и его повторы, а decide отклоняется с signal.reason.

decide разрешается в Decision: каждое поле ответа API — decision_id, execution_id, schema, version, result, confidence, scores, composites, action, action_reason, probabilities, metrics, destinations — плюс functionResults и dispatch(). destinations — всегда массив: [], когда у решения нет назначений или ни одно не сработало.

Решение с onEngineError: "fallback" отвечает своим fallback-действием, когда движок даёт сбой: тогда action_reason.type равен "engine_error", а result и confidence — пустые объекты.

Назначения

decision.destinations содержит записи назначений ответа. Destination — это объединение типов, которое сужается по type и 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}`);
}

Функции-назначения

Функция-назначение называет функцию и её параметры. Передайте обработчики в functions, и SDK вызовет их после решения:

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> }]
  • Обработчики вызываются как functions[name](params, decision), в порядке destinations, по одному: асинхронный обработчик ожидается до запуска следующего.
  • Вызываются только сработавшие записи функций — не пропущенные и не записи других типов.
  • Отсутствующий обработчик: все обработчики ищутся до запуска первого. Если какого-то нет, decide выбрасывает DcisionError FUNCTION_NOT_REGISTERED, и ни один обработчик не запускается — если только вы не передали onMissingFunction: "ignore".
  • Обработчик выбрасывает исключение: следующие обработчики не вызываются, а decide выбрасывает DcisionError FUNCTION_FAILED с cause (то, что выбросил обработчик), decision и functionResults (завершившиеся обработчики). Решение уже выполнено — и тарифицировано.
  • Обработчики выполняются один раз на вызов decide, после окончательного ответа: повторы внутри вызова никогда не запускают их дважды. Повторный вызов decide с тем же idempotencyKey воспроизводит сохранённый ответ и снова запускает его функции, поэтому делайте обработчики идемпотентными — например, с ключом по decision.execution_id.

Запуск позже или в другом месте — из сохранённого ответа:

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" });

Ошибки

Всё, что SDK выбрасывает из-за ответа API, сетевого сбоя, обработчика или подписи, — это 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;
}
ПолеОписание
codeСтабильный код: делайте switch по нему, а не по message.
messageПонятное человеку объяснение.
statusHTTP-статус; undefined, если ответа не было (сетевая ошибка, тайм-аут) или проверка была локальной.
requestIdrequest_id запроса (X-Request-ID): указывайте его при обращении в поддержку.
detailsДополнительные данные для некоторых кодов — см. Ошибки.
retryAfterСекунды из заголовка Retry-After, если он был.
idempotencyKeyIdempotency-Key, который отправил decide: используйте его повторно, чтобы безопасно повторить запрос позже.
causeИсходная ошибка: сетевой сбой, исключение обработчика.
decision, functionResultsТолько для FUNCTION_NOT_REGISTERED и FUNCTION_FAILED.

Коды API перечислены в разделе Ошибки. SDK добавляет:

КодКогда
NETWORK_ERRORНет ответа от API: сбой DNS, соединение отклонено или сброшено, ошибка TLS. Повторяется.
TIMEOUTПопытка длилась дольше timeoutMs. Повторяется.
FUNCTION_NOT_REGISTEREDУ функции-назначения нет обработчика в functions.
FUNCTION_FAILEDОбработчик выбросил исключение.
INVALID_SIGNATUREВебхук не прошёл проверку.

Локальные проверки используют коды API с неопределённым status: INVALID_API_KEY для отсутствующего или некорректного ключа, INVALID_REQUEST для неверного slug, idempotencyKey или отсутствующего state. Ответ, который пришёл не от API, — HTML-страница от прокси, редирект — сохраняет свой HTTP-статус с резервным кодом: INVALID_API_KEY (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), PAYLOAD_TOO_LARGE (413), RATE_LIMITED (429), INVALID_REQUEST (прочие 4xx) или INTERNAL_ERROR. Редиректы никогда не выполняются.

Повторы и идемпотентность

decide отправляет Idempotency-Key, генерируемый один раз на вызов и переиспользуемый каждым повтором. Если попытка выполнила решение, но её ответ потерялся, повтор получает сохранённый ответ: повторы никогда не выполняют и не тарифицируют решение дважды.

ПовторяетсяНе повторяется
Сетевые ошибки и тайм-ауты500 INTERNAL_ERROR
409 IDEMPOTENCY_CONFLICT с Retry-After: первый запрос с этим ключом ещё выполняется409 без Retry-After — другой запрос использовал тот же ключ — и прочие 4xx
429 RATE_LIMITED502 ENGINE_AUTH_FAILED и ENGINE_INVALID_REQUEST: они каждый раз завершаются одинаково
Прочие ошибки 502, 503 и 504Ошибки функций и подписи
  • До maxRetries повторов: по умолчанию 2, то есть 3 попытки.
  • SDK ждёт Retry-After, когда API его присылает, — до 30 с. Более длинный Retry-After не ожидается: ошибка выбрасывается сразу с заполненным retryAfter, чтобы вы могли запланировать повтор.
  • Без Retry-After SDK ждёт 0,5 с, 1 с, 2 с… — удваивая, максимум 8 с, — плюс до 25% случайного разброса.
  • me() и executions повторяются так же.

Случай 409 делает тайм-аут безопасным: если попытка истекла по тайм-ауту, пока решение ещё выполняется, повтор находит ключ зарезервированным, ждёт одну секунду (Retry-After: 1) и пробует снова, пока не получит сохранённый ответ — или пока не закончатся повторы, и тогда выбрасывает IDEMPOTENCY_CONFLICT с ключом в error.idempotencyKey, чтобы вы попробовали позже.

Передайте собственный ключ, чтобы повторы были безопасными между процессами или перезапусками, например ID того, о чём вы принимаете решение:

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

timeoutMs применяется к каждой попытке; для дедлайна на весь вызов передайте signal: { signal: AbortSignal.timeout(15_000) }. Держите timeoutMs выше собственного timeoutMs решения (по умолчанию 5 с, максимум 30 с) плюс тайм-аут его самого медленного LLM-назначения или sync-агента, чтобы попытка действительно завершилась на стороне Dcision до повтора.

Аккаунт и выполнения

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() загружает следующую страницу только когда вы до неё доходите, поэтому break его останавливает. Чтения никогда не тарифицируются и имеют собственное окно лимита запросов — см. Аккаунт и использование и Список выполнений.

Режим партнёра

Партнёры держат по одному подпространству на клиента. withWorkspace() возвращает клиент, который действует в одном из них (заголовок Dcision-Workspace); workspaces и embed управляют ими — на сервере, с вашим 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 } });

Вебхуки

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 — сырое тело в виде string, Uint8Array или Buffer либо ArrayBuffer;
  • header — заголовок Dcision-Signature;
  • secret — секрет подписи (whsec_…, в Настройки → Назначения) или массив секретов на время ротации;
  • toleranceSec — насколько метка времени подписи может отличаться от now;
  • now — секунды Unix или Date, для тестов.

Функция выбрасывает DcisionError INVALID_SIGNATURE, когда заголовок отсутствует или некорректен, ни одна подпись не совпадает (сравнение за постоянное время), метка времени вне допуска или тело не является JSON-событием, — отвечайте 400. Неправильное использование, например отсутствие секрета или уже разобранное тело, вместо этого выбрасывает TypeError — отвечайте 500, чтобы Dcision продолжал повторять, пока исправление не будет задеплоено.

verifySignature(body, header, secret, options) выполняет те же проверки без разбора тела: используйте его для API-запросов и агентов, чьи тела не являются событиями.

Полные получатели для Express и Next.js — в разделе Вебхуки.

TypeScript

Типизируйте ответы решения с помощью дженерика — интерфейсы тоже подходят:

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;

Пакет экспортирует Dcision, Decision, DcisionError, verifyWebhook, verifySignature и VERSION, а также типы, например DecisionResponse, Destination, QueuedDestination, SkippedDestination, FunctionDestination, WebhookEvent, Me, Execution, ExecutionPage и DcisionErrorCode.

Поддерживаемые среды

СредаПримечания
Node.js 20+ESM (import) и CommonJS (require).
BunКак Node.js.
DenoИмпортируйте сборку: import { Dcision } from "/path/to/dcision/packages/sdk/dist/esm/index.js". Разрешите сеть (--allow-net=api.dcision.io) и, чтобы читать DCISION_API_KEY, --allow-env=DCISION_API_KEY — или передайте apiKey.
Cloudflare Workers, Vercel EdgeПередайте apiKey из своих bindings или окружения.
БраузерыНе поддерживаются: API-ключ в браузере становится публичным. Вызывайте Dcision со своего сервера.

Замечания о безопасности

  • API-ключ остаётся приватным. Он хранится в приватном поле — не выводится console.log, не попадает в JSON.stringify — и никогда не появляется в сообщении об ошибке. Значение, которое не является ключом Dcision, отклоняется до любого запроса.
  • Транспорт. Только https, и редиректы никогда не выполняются, поэтому ключ никогда не попадает на другой хост.
  • Пути. Slug проверяется и кодируется: ничего другого в путь URL попасть не может.
  • Вебхуки. HMAC-SHA256 сравнивается за постоянное время, метки времени вне допуска отклоняются, проверка выполняется только по сырым байтам.

На этой странице