@vaikora/sdk 0.2.0

package/README.md

@@ -0,0 +1,403 @@
+# Vaikora Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/@vaikora/sdk.svg)](https://www.npmjs.com/package/@vaikora/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Node.js SDK for the Vaikora AI Agent Security Platform.
+
+## Installation
+
+```bash
+npm install @vaikora/sdk
+# or
+yarn add @vaikora/sdk
+# or
+pnpm add @vaikora/sdk
+```
+
+## Quick Start
+
+### Simple Configuration (Recommended)
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+import { configure, validateData } from '@vaikora/sdk';
+
+configure('your-api-key');
+
+const result = await validateData(
+  {
+    name: 'John Doe',
+    email: 'john@example.com',
+    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
+
+```typescript
+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('user@example.com', '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:
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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:
+
+```typescript
+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
+
+```typescript
+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
+
+```bash
+VAIKORA_API_KEY=your-api-key
+VAIKORA_BASE_URL=https://api.vaikora.ai
+```
+
+## TypeScript Types
+
+All types are exported from the package:
+
+```typescript
+import type {
+  Agent,
+  AgentType,
+  AgentStatus,
+  Action,
+  ActionStatus,
+  ActionResult,
+  Policy,
+  Alert,
+  AlertSeverity,
+  DataValidationResult,
+  InterceptorConfig,
+  InterceptorResult,
+} from '@vaikora/sdk';
+```
+
+## License
+
+MIT