@principal-ai/vanta-sdk

SDK for interacting with the Vanta API for compliance and security monitoring.

Installation

npm install @principal-ai/vanta-sdk
# or
bun add @principal-ai/vanta-sdk

Setup

1. Create a credentials file at ~/.config/vanta.env with your Vanta API credentials:

{
  "client_id": "vci_your_client_id",
  "client_secret": "vcs_your_client_secret"
}

2. Get your credentials from Vanta:
   • Go to your Vanta account settings
   • Create a new API application
   • Copy the client ID and client secret

See Vanta API Access Setup for more details.

Usage

Basic Authentication

import { VantaSDK } from '@principal-ai/vanta-sdk';

// Create SDK instance (uses ~/.config/vanta.env by default)
const vanta = new VantaSDK();

// Test authentication
const isAuthenticated = await vanta.testAuth();
console.log('Authenticated:', isAuthenticated);

// Get access token
const token = await vanta.getAccessToken();

Custom Configuration

import { VantaSDK } from '@principal-ai/vanta-sdk';

const vanta = new VantaSDK({
  credentialsPath: '/custom/path/to/credentials.json',
  scope: 'vanta-api.all:read', // Custom scope
  baseUrl: 'https://api.vanta.com', // Custom base URL
});

Working with Documents

// List all documents
const docsResponse = await vanta.listDocuments({ pageSize: 10 });
console.log('Documents:', docsResponse.results.data);
console.log('Has more:', docsResponse.results.pageInfo.hasNextPage);

// List documents with filters
const okDocs = await vanta.listDocuments({
  pageSize: 20,
  statusMatchesAny: ['OK'],
  frameworkMatchesAny: ['soc2', 'iso27001']
});

// Get a specific document
const doc = await vanta.getDocument('document-id');
console.log('Document:', doc.title, doc.category);

// Create a new custom document
const newDoc = await vanta.createDocument({
  title: 'Security Policy',
  category: 'Policies',
  description: 'Company security policy document',
  isSensitive: false
});

// Delete a document
await vanta.deleteDocument('document-id');

// Upload a file to a document
const file = new Blob(['file content'], { type: 'application/pdf' });
await vanta.uploadFileForDocument('document-id', file, 'policy.pdf');

Pagination

// List first page
let response = await vanta.listDocuments({ pageSize: 10 });
console.log('Page 1:', response.results.data);

// Get next page if available
if (response.results.pageInfo.hasNextPage) {
  response = await vanta.listDocuments({
    pageSize: 10,
    pageCursor: response.results.pageInfo.endCursor
  });
  console.log('Page 2:', response.results.data);
}

Making Custom API Requests

// Make authenticated requests to any Vanta API endpoint
const response = await vanta.request('/v1/tests');
console.log('Tests:', response);

Features

• ✅ OAuth 2.0 Client Credentials authentication
• ✅ Automatic token refresh
• ✅ Type-safe API requests
• ✅ Configurable credentials path
• ✅ Document management (list, get, create, delete, upload)
• ✅ Pagination support
• ✅ Filtering and query parameters

Development

# Build the package
bun run build

# Watch mode for development
bun run dev

# Type check
bun run type-check

# Run tests
bun test

License

MIT