npm package: @principal-ai/vanta-sdk
Description: SDK for interacting with Vanta API for compliance and security monitoring, with GitHub coverage calculator integration
Latest version: 0.1.2

# @principal-ai/vanta-sdk

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

## Installation

```bash
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:

```json
{
  "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](https://developer.vanta.com/docs/api-access-setup) for more details.

## Usage

### Basic Authentication

```typescript
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

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```bash
# 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