@decionis/sdk

@decionis/sdk

Node SDK for the canonical Decionis policy-evaluation route.

Install

npm install @decionis/sdk

It includes:

• a typed client for POST /v1/protocol/evaluate-decision
• a typed execution-authority client for POST /v1/authority/enforce-and-bind
• Express middleware for service-boundary policy gating
• Express verifier middleware for Decionis execution tokens
• Fastify pre-handler hooks for the same pattern
• a runtime adapter so an agent inside any sandbox (e.g. Runta) calls Decionis for the verdict + a single-use grant before a consequential action
• a provider-neutral agent task gateway for pre-prompt reservation, proxy headers, sandbox egress verification, and usage reconciliation

Core pattern

• Build a Decionis decision request from the incoming HTTP request.
• Call Decionis before the route mutates state.
• Continue on APPROVE, or deny on REJECT, REVIEW, and ESCALATE by default.
• Forward Decision Dossier identifiers back through response headers.

Package contents

• ESM and CommonJS builds in dist/
• TypeScript declarations
• middleware helpers that do not require a direct runtime dependency on Express

Release

For repository-backed packaging and publish automation, use the workflow documented in docs/package-distribution.md.

Example

import { createDecionisNodeSdk, createExpressPolicyGate } from "@decionis/sdk";

const client = createDecionisNodeSdk({
  baseUrl: process.env.DECIONIS_BASE_URL!,
  apiKey: process.env.DECIONIS_API_KEY!,
  defaultRequest: {
    policy_version: "payments-v1",
    objective_profile: "risk_conservative",
    mode: "ENFORCEMENT",
  },
});

app.post(
  "/payments/release",
  createExpressPolicyGate({
    client,
    buildDecisionRequest: (req) => ({
      org_id: process.env.DECIONIS_ORG_ID!,
      decision_type: "PAYMENT_RELEASE",
      amount: Number(req.body.amount),
      workflow_key: "payment_release",
      vertical_pack: "finance",
      context: {
        route: req.originalUrl,
        actor_id: req.user?.id,
      },
    }),
  }),
  releasePaymentHandler,
);

Execution Authority

SDK code packages action intent and binds execution through Decionis. Policy rules stay in the Authority API, not in the agent process.

import { createDecionisExecutionClient } from "@decionis/sdk";

const decionis = createDecionisExecutionClient({
  authorityBaseUrl: process.env.DECIONIS_AUTHORITY_URL!,
});

await decionis.enforceAndExecute({
  request: {
    tenant_id: "tenant_demo",
    actor: { id: "research_agent", type: "AI_AGENT", runtime: "mcp" },
    action: { type: "SEND_PAYMENT", resource: "wallet.usdc", amount: 0.25, currency: "USD" },
    downstream_target: {
      system: "payment_api",
      operation: "send_payment",
      endpoint: "POST /payments",
    },
  },
  execute: ({ executionToken }) =>
    paymentApi.sendPayment({
      amount: 0.25,
      token: executionToken,
    }),
});

Grant-required (strict) enforcement

enforceAndExecuteStrict makes the single-use grant a hard precondition — "no valid grant, no execution." It authorizes, then redeems the grant before execute runs, and fails closed on every other path. Because the grant is redeemed up front, a downstream failure requires a fresh decision rather than replaying an ALLOW. Opt-in per surface — the default enforceAndExecute is unchanged.

const result = await decionis.enforceAndExecuteStrict({
  request,
  execute: ({ executionToken, grant }) =>
    paymentApi.sendPayment({ amount: 0.25, token: executionToken }),
});

if (!result.executed) {
  // result.reason: BLOCKED_BY_POLICY | NO_EXECUTION_GRANT | GRANT_NOT_REDEEMABLE | AUTHORITY_ERROR
  return refuse(result.reason);
}

Downstream services should verify and consume the token before mutating state:

import { createExpressExecutionTokenVerifier } from "@decionis/sdk";

app.post(
  "/payments",
  createExpressExecutionTokenVerifier({
    authorityBaseUrl: process.env.DECIONIS_AUTHORITY_URL!,
    buildVerificationRequest: (req) => ({
      actor_id: req.body.actor_id,
      action_type: "SEND_PAYMENT",
      resource: "wallet.usdc",
      amount: Number(req.body.amount),
      currency: "USD",
      downstream_target: {
        system: "payment_api",
        operation: "send_payment",
        endpoint: "POST /payments",
      },
    }),
  }),
  paymentHandler,
);

Agentic checkout (ACP / AP2) authorization primitive

AgenticCheckoutGate is the in-process authorization primitive for agentic commerce: it runs the deterministic gate against a pre-synced signed policy snapshot (zero network on the hot path), mints a single-use, cart-bound Execution Grant on ALLOW, and appends to the ledger off the hot path. authorizeAgenticCheckout returns a flat ACP/AP2 accept/decline result.

import { authorizeAgenticCheckout } from "@decionis/sdk";

const auth = await authorizeAgenticCheckout(
  { snapshot, issueGrant },
  { request, signal: { cartTotal: 100, discountAmount: 0, estimatedCost: 20 } },
  { requireGrant: true }, // strict: an ALLOW without a bound grant is NOT authorized
);

if (!auth.authorized) return decline(auth.acp_status, auth.reasons);
proceedToPayment(auth.execution_grant); // single-use, action-bound

{ requireGrant: true } is the fail-closed posture that pairs with enforceAndExecuteStrict — no bound grant, no authorization.

Agent task reservation and provider proxy

Use DecionisAgentTaskGateway before model traffic. It keeps the Decionis runtime key separate from the provider credential and produces native base URLs and headers for the OpenAI and Anthropic SDKs.

import OpenAI from "openai";
import { createDecionisAgentTaskGateway } from "@decionis/sdk";

const gateway = createDecionisAgentTaskGateway({
  gatewayBaseUrl: process.env.DECIONIS_AGENT_GATEWAY_URL!,
  apiKey: process.env.DECIONIS_API_KEY!,
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  baseURL: gateway.providerBaseUrl("openai"),
  defaultHeaders: gateway.providerHeaders({
    orgId: process.env.DECIONIS_ORG_ID!,
    userId: "[e-mail]",
    sessionId: crypto.randomUUID(),
    idempotencyKey: crypto.randomUUID(),
    host: "codex",
  }),
});

Direct embeddings can call reserve(), authorizeEgress(), reconcile(), and release() instead. The complete boundary and rollout contract is documented in AgentBoundaryGateway.md.