@cognexuslabs/artzain — CogNEXUS Decision API client for Node.js

Gate agent actions through the CogNEXUS decision engine and get back a sealed, auditable allow / deny / review outcome.

npm install @cognexuslabs/artzain   # Node >= 18, zero runtime dependencies

import { configure, decide, DecisionError } from "@cognexuslabs/artzain";

configure({ apiKey: process.env.COGNEXUS_API_KEY }); // or just set the env var

const decision = await decide({
  action: "send_email",
  target: "crm:contact:123",
  payload: draftEmailBody,
});

if (decision.outcome === "allow") {
  await sendEmail(draftEmailBody);
} else {
  console.warn(`Blocked (${decision.outcome}) — sealed decision ${decision.decision_id}`);
}

Configuration

| Source | Key | |---|---| | configure({ apiKey, baseUrl }) | explicit, wins | | COGNEXUS_API_KEY (or MYAPP_API_KEY) | API key from Account → API Keys | | ~/.artzain/credentials.toml | Profile written by artzain login (Python CLI); read after the env vars on Node 20.16+ / 22.3+. COGNEXUS_CREDENTIALS_PATH overrides the path. | | COGNEXUS_API_BASE_URL | your deployment (default https://app.cognexuslabs.ai) |

Surface

• decide(options) → DecisionResponse — POST /api/v1/decisions. Deny/review outcomes are returned, not thrown; DecisionError is thrown for transport failures, missing keys, and typed engine refusals (kill_switch_active, audit_unavailable — the engine fails closed and so should you).
• postSdkEvent(options) — fire-and-forget guard-event telemetry (POST /api/events); never throws.
• fetchApiKeyIdentity() — validate the configured key (GET /api/api-keys/me).

Divergence from the Python SDK

This SDK is remote-only: there is no offline local-guard fallback. If no API key is configured, decide() throws instead of screening locally. Use the Python SDK (pip install artzain) where offline guard parity matters.

Development

npm ci
npm run build   # tsc → dist/
npm test        # vitest