@decionis/sdk-node

Node SDK for the canonical Decionis policy-evaluation route.

Install

npm install @decionis/sdk-node

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

Core pattern

1. Build a Decionis decision request from the incoming HTTP request.
2. Call Decionis before the route mutates state.
3. Continue on APPROVE, or deny on REJECT, REVIEW, and ESCALATE by default.
4. 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-node";

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-node";

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

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

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

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,
);