TypeScript SDK for the Witnium Vault API
npm install witnium-vault-sdkA TypeScript SDK for interacting with the Witnium Vault API. Provides type-safe access to all API endpoints with cookie-based authentication for seamless browser integration.
``bash`
npm install witnium-vault-sdk
`typescript
import { WitniumVaultClient } from 'witnium-vault-sdk';
// Create a client
const client = new WitniumVaultClient({
baseUrl: 'https://witniumvault.witnium.tech'
});
// Login (sets session cookie)
await client.login({
email: 'user@example.com',
password: 'your-password'
});
// List files
const result = await client.files.list({ page: 1, limit: 20 });
if (result.success) {
console.log('Files:', result.data.files);
}
`
- Type-safe: Full TypeScript support with generated types from OpenAPI spec
- Cookie-based auth: Seamless browser integration with automatic session management
- Generic + Convenience methods: Use client.get('/api/files') or client.files.list()
- Self-documenting: Runtime endpoint registry for AI tools (Lovable, etc.)
- Error handling: Structured error responses with typed error objects
The SDK uses cookie-based authentication, which works automatically in browser environments:
`typescript
// Login
await client.login({
email: 'user@example.com',
password: 'password'
});
// Check authentication status
const status = await client.getAuthStatus();
if (status.authenticated) {
console.log('Logged in as:', status.user?.email);
}
// Logout
await client.logout();
`
If the user has MFA enabled, provide the TOTP code:
`typescript
await client.login({
email: 'user@example.com',
password: 'password',
totp: '123456' // From authenticator app
});
// Or use a backup code
await client.login({
email: 'user@example.com',
password: 'password',
backupCode: 'ABCD-EFGH-1234'
});
`
The SDK provides generic HTTP methods that work with any endpoint:
`typescript
// GET request
const result = await client.get('/api/files', { page: '1', limit: '20' });
// POST request (search)
const result = await client.post('/api/search', {
query: 'contract',
path: '/documents'
});
// PUT request
const result = await client.put('/api/files', {
action: 'restore',
fileId: 'file-123'
});
// DELETE request
const result = await client.delete('/api/files', { id: 'file-123' });
`
For common operations, use the typed convenience methods:
#### Files
`typescript
// List files with pagination
const files = await client.files.list({ page: 1, limit: 20 });
// Get a specific file
const file = await client.files.get('file-123');
// Delete a file (soft delete)
await client.files.delete('file-123');
// Permanently delete
await client.files.delete('file-123', true);
// Restore a deleted file
await client.files.restore('file-123');
// Get version history
const history = await client.files.getHistory('file-group-123');
`
#### Search
`typescript
// Simple search
const results = await client.search.query('contract');
// Search with filters
const results = await client.search.query('invoice', {
fileTypes: ['pdf', 'docx'],
dateRange: { from: '2024-01-01' },
folderPath: '/documents',
limit: 20
});
`
#### Evidence Binders
`typescript
// List binders
const binders = await client.evidenceBinders.list();
// Create a binder
const binder = await client.evidenceBinders.create({
name: 'Q1 2024 Contracts',
description: 'All contracts signed in Q1 2024'
});
// Export a binder
const exportJob = await client.evidenceBinders.export('binder-123', 'pdf');
`
#### Workspace
`typescript
// Get audit logs
const logs = await client.workspace.getAuditLogs({
page: 1,
limit: 50,
eventType: 'file.upload'
});
// Get folder tree
const tree = await client.workspace.getFolderTree();
// Get usage statistics
const usage = await client.workspace.getUsage();
`
All methods return an ApiResult type that indicates success or failure:
`typescript
const result = await client.files.get('invalid-id');
if (result.success) {
console.log('File:', result.data.file);
} else {
console.error('Error:', result.error.error);
console.error('Status:', result.error.status);
console.error('Code:', result.error.code);
}
`
For authentication errors, you can use the WitniumApiError class:
`typescript
import { WitniumApiError } from 'witnium-vault-sdk';
try {
await client.login({ email: 'user@example.com', password: 'wrong' });
} catch (error) {
if (error instanceof WitniumApiError) {
if (error.isUnauthorized()) {
console.log('Invalid credentials');
}
if (error.code === 'MFA_REQUIRED') {
console.log('MFA code needed');
}
}
}
`
The SDK includes a runtime endpoint registry for AI tools like Lovable:
`typescript
import { EndpointRegistry } from 'witnium-vault-sdk';
// Get info about an endpoint
const info = EndpointRegistry.getEndpoint('/api/files');
console.log(info?.methods.GET?.description);
// Output: "List files in the current workspace"
// List all endpoints
const endpoints = EndpointRegistry.listEndpoints();
// Find endpoints by tag
const authEndpoints = EndpointRegistry.findByTag('Auth');
// Search endpoints
const fileEndpoints = EndpointRegistry.search('upload');
// Get a summary for AI context
const summary = EndpointRegistry.getSummary();
console.log(summary);
// Output: Markdown-formatted list of all endpoints
`
`typescript`
const client = new WitniumVaultClient({
// Required: API base URL
baseUrl: 'https://witniumvault.witnium.tech',
// Optional: Custom timeout (default: 30000ms)
timeout: 60000,
// Optional: Default headers for all requests
defaultHeaders: {
'X-Custom-Header': 'value'
},
// Optional: Custom fetch implementation (for testing)
fetch: customFetchFunction
});
The SDK exports all types for use in your application:
`typescript`
import type {
// Client types
WitniumVaultClientConfig,
ApiResult,
ApiError,
LoginCredentials,
// API types
FileMetadata,
FilesListResponse,
EvidenceBinder,
SearchResult,
// Resource options
ListFilesOptions,
SearchOptions,
CreateBinderOptions,
} from 'witnium-vault-sdk';
`typescript
// Note: File uploads use multipart/form-data, not JSON
// Use the generic fetch or a form submission for uploads
// After upload, trigger AI processing
const result = await client.files.processAI('file-123');
if (result.success) {
console.log('Processing started');
}
`
`typescript
// Create and export a binder
const binder = await client.evidenceBinders.create({
name: 'Legal Discovery',
description: 'Documents for case #12345'
});
if (binder.success) {
const exportJob = await client.evidenceBinders.export(
binder.data.binder._id,
'pdf'
);
if (exportJob.success) {
console.log('Export started:', exportJob.data.exportId);
}
}
`
`bashInstall dependencies
npm install
MIT