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/sdknpm 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",
});| Параметр | По умолчанию | Описание |
|---|---|---|
apiKey | DCISION_API_KEY | dcs_live_… или dcs_test_…. Отсутствующий ключ или ключ, который не начинается с dcs_, сразу выбрасывает DcisionError INVALID_API_KEY — ничего не отправляется. |
baseUrl | https://api.dcision.io | Должен использовать https — обычный http только для API на loopback-адресе. Префикс пути допустим; учётные данные, строка запроса или фрагмент отклоняются. |
timeoutMs | 30000 | Тайм-аут каждой попытки, в миллисекундах. |
maxRetries | 2 | Повторы после сетевой ошибки, тайм-аута, 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 проверяется локально (строчные буквы, цифры и одиночные дефисы) до отправки чего-либо.
| Параметр | Описание |
|---|---|
idempotencyKey | Idempotency-Key: от 1 до 128 символов из A–Z a–z 0–9 . _ : -. По умолчанию — новый UUID на каждый вызов, который переиспользуется всеми его повторами. |
includeProbabilities | Добавляет probabilities, полное распределение по каждому вопросу (?include=probabilities). |
functions | Обработчики для функций-назначений. |
onMissingFunction | "throw" (по умолчанию) или "ignore". |
signal | AbortSignal: прерывание останавливает запрос и его повторы, а 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выбрасываетDcisionErrorFUNCTION_NOT_REGISTERED, и ни один обработчик не запускается — если только вы не передалиonMissingFunction: "ignore". - Обработчик выбрасывает исключение: следующие обработчики не вызываются, а
decideвыбрасываетDcisionErrorFUNCTION_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 | Понятное человеку объяснение. |
status | HTTP-статус; undefined, если ответа не было (сетевая ошибка, тайм-аут) или проверка была локальной. |
requestId | request_id запроса (X-Request-ID): указывайте его при обращении в поддержку. |
details | Дополнительные данные для некоторых кодов — см. Ошибки. |
retryAfter | Секунды из заголовка Retry-After, если он был. |
idempotencyKey | Idempotency-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_LIMITED | 502 ENGINE_AUTH_FAILED и ENGINE_INVALID_REQUEST: они каждый раз завершаются одинаково |
Прочие ошибки 502, 503 и 504 | Ошибки функций и подписи |
- До
maxRetriesповторов: по умолчанию 2, то есть 3 попытки. - SDK ждёт
Retry-After, когда API его присылает, — до 30 с. Более длинныйRetry-Afterне ожидается: ошибка выбрасывается сразу с заполненнымretryAfter, чтобы вы могли запланировать повтор. - Без
Retry-AfterSDK ждёт 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 сравнивается за постоянное время, метки времени вне допуска отклоняются, проверка выполняется только по сырым байтам.
Обзор SDK
Официальные SDK для TypeScript и Python — что они добавляют к обычному HTTPS, чем отличаются и как собрать их из исходников, пока они не опубликованы в npm и PyPI.
Python SDK
Пакет dcision для Python 3.9+ — сборка из исходников, decide, назначения и функции, ошибки, идемпотентные повторы, выполнения, me() и проверка вебхуков во Flask или FastAPI.