@decionis/sdk-node

@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

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