Vix11 Node.js SDK

Official Node.js SDK for the Vix11 AI agent security platform. Provides a typed client for the Vix11 API and drop-in Express middleware.

Installation

npm install vix11

Quick Start

import { Vix11Client } from 'vix11';

const client = new Vix11Client({
  baseUrl: 'https://vix11.example.com',
  agentId: 'my-agent',
  apiKey: 'your-api-key',
});

const result = await client.detect({
  endpoint: '/api/chat',
  payload: '{"prompt": "hello"}',
});

if (result.detection.action === 'block') {
  console.log('Request blocked:', result.detection);
} else {
  console.log('Request allowed');
}

Express Middleware

The SDK includes middleware that automatically intercepts every incoming request, runs it through the Vix11 detection pipeline, and blocks or throttles suspicious traffic.

import express from 'express';
import { vix11Middleware } from 'vix11';

const app = express();

app.use(vix11Middleware({
  baseUrl: 'https://vix11.example.com',
  agentId: 'my-agent',
  apiKey: 'your-api-key',
}));

app.post('/api/chat', (req, res) => {
  // req.vix11 contains the detection result for downstream use
  console.log('Detection score:', req.vix11);
  res.json({ reply: 'Hello!' });
});

app.listen(3000);

Middleware behavior:

• block action: responds with 403 and a JSON error body.
• throttle action: responds with 429 and a retryAfterMs field.
• allow / shadow-ban: calls next() and attaches the detection result to req.vix11.
• On detection failure, the middleware fails open and forwards the error to the Express error handler.

API Reference

new Vix11Client(config)

Creates a new client instance.

client.detect(payload): Promise<DetectResponse>

Run the 11-layer detection pipeline against a request.

Parameters:

| Field | Type | Required | Description | |------------|----------|----------|------------------------------------| | agentId | string | Yes | Agent identifier | | endpoint | string | Yes | Target endpoint path | | payload | string | No | Request body as a string | | ip | string | No | Client IP address |

Returns: DetectResponse containing the detection result with action (allow, block, throttle, shadow-ban) and layer scores.

client.shield(payload): Promise<ShieldResponse>

Run the shielded-request flow, which combines passport verification with the detection pipeline.

Parameters: Same as detect.

Returns: ShieldResponse with passport verification status and detection result.

client.getAnalyticsSummary(from?, to?): Promise<AnalyticsSummary>

Retrieve the analytics summary for a time range, including the "$X saved" distillation metric.

Parameters:

| Field | Type | Required | Description | |--------|----------|----------|------------------------------| | from | number | No | Start timestamp (epoch ms) | | to | number | No | End timestamp (epoch ms) |

client.getAnalyticsEvents(page?, limit?): Promise<PaginatedEvents>

Retrieve paginated detection events.

Parameters:

| Field | Type | Required | Description | |---------|----------|----------|------------------------| | page | number | No | Page number | | limit | number | No | Events per page |

client.getComplianceReport(): Promise<ComplianceReport>

Retrieve the current OWASP ASI compliance report.

client.getDetectionStats(): Promise<DetectionStats>

Retrieve detection pipeline statistics, including per-layer performance and thresholds.

client.health(): Promise<{ status: string }>

Check API health. Returns { status: "ok" } when the service is operational.

Error Handling

All API errors are thrown as Vix11Error instances.

import { Vix11Error } from 'vix11';

try {
  await client.detect({ endpoint: '/api/chat', payload: '...' });
} catch (err) {
  if (err instanceof Vix11Error) {
    console.error('Vix11 API error:', err.message);
    console.error('HTTP status:', err.status);
    console.error('Response body:', err.body);
  }
}

Vix11Error properties:

| Property | Type | Description | |-----------|-----------|--------------------------------------------------| | message | string | Human-readable error message | | status | number | HTTP status code (0 for timeouts) | | body | unknown | Raw response body, if available |

Timeout errors have status set to 0 and a message indicating the configured timeout value.

Configuration

| Option | Type | Required | Default | Description | |-----------|----------|----------|---------|-----------------------------------------------| | baseUrl | string | Yes | -- | Base URL of the Vix11 API | | agentId | string | Yes | -- | Agent identifier sent with every request | | apiKey | string | No | -- | API key for authenticated requests | | timeout | number | No | 5000 | Request timeout in milliseconds |

TypeScript

The SDK is written in TypeScript and exports all types used across the API:

import type {
  Vix11Config,
  DetectRequest,
  DetectResponse,
  ShieldRequest,
  ShieldResponse,
  AnalyticsSummary,
  PaginatedEvents,
  ComplianceReport,
  DetectionStats,
} from 'vix11';

No @types package is needed. Type definitions are bundled with the package.

License

MIT