Vaikora Node.js SDK

The official Node.js SDK for the Vaikora AI Agent Security Platform.

Installation

npm install @vaikora/sdk
# or
yarn add @vaikora/sdk
# or
pnpm add @vaikora/sdk

Quick Start

Simple Configuration (Recommended)

import { configure, register, wrapAction, validateData } from '@vaikora/sdk';

// Configure the global client
configure('your-api-key');

// Register your AI agent
const agent = await register({
  name: 'my-assistant',
  agentType: 'autonomous',
  capabilities: ['data_access', 'email_send', 'api_call'],
});

console.log(`Agent registered: ${agent.id}`);

Secure Your Actions

import { configure, register, wrapAction } from '@vaikora/sdk';

configure('your-api-key');
await register({ name: 'my-agent' });

// Wrap any async function with security controls
const secureDbQuery = wrapAction(
  { actionType: 'database_query', resource: 'users' },
  async (query: string) => {
    return await database.execute(query);
  }
);

// Action is now secured - will be evaluated against policies
const users = await secureDbQuery('SELECT * FROM users WHERE active = true');

Validate Data

import { configure, validateData } from '@vaikora/sdk';

configure('your-api-key');

const result = await validateData(
  {
    name: 'John Doe',
    email: '[email protected]',
    ssn: '123-45-6789',
    message: 'Hello world',
  },
  {
    checkPii: true,
    checkAnomalies: true,
    checkToxicity: true,
    autoClean: true,
  }
);

if (!result.isValid) {
  console.log('PII detected:', result.piiDetections);
  console.log('Cleaned data:', result.cleanedData);
}

Use the Interceptor for Advanced Control

import { configure, register, getClient, createInterceptor, InterceptorAction } from '@vaikora/sdk';

configure('your-api-key');
await register({ name: 'my-agent' });

const client = getClient();

// Create an interceptor with full configuration
const intercept = createInterceptor(client, {
  actionType: 'sensitive_operation',
  validateInputs: true,
  validateOutputs: true,
  checkPii: true,
  checkToxicity: true,
  evaluatePolicy: true,
  onPolicyDeny: InterceptorAction.BLOCK,
  requireApproval: true,
  approvalTimeoutSeconds: 3600,
});

// Wrap your function
const secureSendEmail = intercept(async (to: string, subject: string, body: string) => {
  await emailService.send({ to, subject, body });
  return { sent: true };
});

// Execute with full security
const result = await secureSendEmail('[email protected]', 'Hello', 'Message content');
console.log('Action ID:', result.actionId);
console.log('Validation issues:', result.validationIssues);

Class-Based Client Usage

For more control, use the VaikoraClient class directly:

import { VaikoraClient } from '@vaikora/sdk';

const client = new VaikoraClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.vaikora.ai',
  timeout: 30000,
  retryCount: 3,
});

// Register an agent
const agent = await client.agents.register({
  name: 'my-ai-agent',
  agentType: 'autonomous',
  capabilities: ['database_write', 'api_call', 'file_access'],
});

// Submit an action for approval
const result = await client.actions.submit({
  agentId: agent.id,
  actionType: 'database_write',
  resource: 'users_table',
  payload: { userId: 123, data: { name: 'John' } },
});

if (result.approved) {
  // Proceed with the action
} else {
  console.log(`Action blocked: ${result.denialReason}`);
}

Features

• TypeScript First: Full TypeScript support with complete type definitions
• Simple API: Convenience functions for quick integration
• Action Control: Submit actions for policy evaluation before execution
• Data Validation: Check for PII, anomalies, and toxicity
• Interceptor: Wrap functions with security controls
• Anomaly Detection: Automatic detection of unusual agent behavior
• Policy Enforcement: Server-side policy evaluation
• Human-in-the-Loop: Approval workflows for sensitive actions
• Alerting: Real-time alerts for security events
• Retry Logic: Built-in exponential backoff for failed requests

Configuration Options

import { VaikoraClient } from '@vaikora/sdk';

const client = new VaikoraClient({
  apiKey: 'your-api-key',        // Required
  baseUrl: 'https://api.vaikora.ai', // Default
  timeout: 30000,                // Request timeout in milliseconds
  retryCount: 3,                 // Number of retries for failed requests
  agentId: 'default-agent-id',   // Default agent for actions
});

API Reference

Convenience Functions

// Configure global client
configure(apiKey: string, options?: ConfigureOptions): VaikoraClient

// Get configured client
getClient(): VaikoraClient

// Register an agent
register(options: RegisterOptions): Promise<Agent>

// Get/set agent ID
getAgentId(): string | null
setAgentId(agentId: string): void

// Validate data
validateData(data: unknown, options?: ValidateDataOptions): Promise<DataValidationResult>

// Submit an action
submitAction(options: SubmitActionOptions): Promise<ActionResult>

// Wrap a function with security
wrapAction<TArgs, TResult>(options: SecureActionOptions, fn: Function): Function

Agents API

// Register a new agent
const agent = await client.agents.register({
  name: 'my-agent',
  agentType: 'autonomous', // 'autonomous' | 'semi_autonomous' | 'supervised'
  capabilities: ['capability1', 'capability2'],
  metadata: { custom: 'data' },
});

// Get agent by ID
const agent = await client.agents.get('agent-id');

// Update agent
const updated = await client.agents.update('agent-id', {
  status: 'active',
  capabilities: ['new_capability'],
});

// List agents
const agents = await client.agents.list({
  page: 1,
  pageSize: 20,
  status: 'active',
});

// Delete agent
await client.agents.delete('agent-id');

Actions API

// Submit action for evaluation
const result = await client.actions.submit({
  agentId: 'agent-id',
  actionType: 'database_write',
  resource: 'users_table',
  payload: { data: 'value' },
  metadata: { context: 'info' },
});

// Mark action as complete
await client.actions.complete('action-id', {
  status: 'executed',
  executionTimeMs: 150,
});

// List actions
const actions = await client.actions.list({
  agentId: 'agent-id',
  status: 'executed',
  isAnomaly: false,
  startDate: new Date('2024-01-01'),
  endDate: new Date(),
});

Policies API

// List policies
const policies = await client.policies.list({
  enabled: true,
  policyType: 'deny',
});

// Get policy by ID
const policy = await client.policies.get('policy-id');

Alerts API

// List alerts
const alerts = await client.alerts.list({
  status: 'open',
  severity: 'high',
});

// Acknowledge alert
await client.alerts.acknowledge('alert-id');

// Resolve alert
await client.alerts.resolve('alert-id', {
  notes: 'Issue was a false positive',
});

// Ignore alert
await client.alerts.ignore('alert-id');

Interceptor Configuration

The interceptor provides comprehensive security controls:

interface InterceptorConfig {
  actionType: string;           // Required: Type of action
  resource?: string;            // Resource being accessed
  agentId?: string;             // Override agent ID

  // Validation
  validateInputs?: boolean;     // Validate function inputs (default: true)
  validateOutputs?: boolean;    // Validate function outputs (default: false)
  validationStrict?: boolean;   // Throw on validation issues (default: false)
  checkPii?: boolean;           // Check for PII (default: true)
  checkAnomalies?: boolean;     // Check for anomalies (default: true)
  checkToxicity?: boolean;      // Check for toxic content (default: true)
  autoClean?: boolean;          // Auto-clean data (default: false)

  // Policy
  evaluatePolicy?: boolean;     // Evaluate against policies (default: true)
  onPolicyDeny?: InterceptorAction; // Action on deny (default: BLOCK)

  // Approval
  requireApproval?: boolean;    // Require human approval (default: false)
  approvalTimeoutSeconds?: number; // Approval timeout (default: 3600)
  approvalNotifyChannels?: string[]; // Notification channels

  // Fallback
  fallbackFunction?: Function;  // Fallback on policy deny

  // Metadata
  metadata?: Record<string, unknown>;
  tags?: string[];
}

Error Handling

import {
  VaikoraError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  RateLimitError,
  PolicyViolationError,
  ValidationException,
  PolicyDeniedException,
  ApprovalRequiredException,
} from '@vaikora/sdk';

try {
  const result = await client.actions.submit({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof PolicyViolationError) {
    console.log(`Blocked by policy: ${error.policyId}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after: ${error.retryAfter}s`);
  } else if (error instanceof ValidationException) {
    console.log('Validation issues:', error.issues);
  }
}

Environment Variables

VAIKORA_API_KEY=your-api-key
VAIKORA_BASE_URL=https://api.vaikora.ai

TypeScript Types

All types are exported from the package:

import type {
  Agent,
  AgentType,
  AgentStatus,
  Action,
  ActionStatus,
  ActionResult,
  Policy,
  Alert,
  AlertSeverity,
  DataValidationResult,
  InterceptorConfig,
  InterceptorResult,
} from '@vaikora/sdk';

License

MIT