Witnium Vault SDK

A 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.

Installation

npm install witnium-vault-sdk

Quick Start

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: '[email protected]',
  password: 'your-password'
});

// List files
const result = await client.files.list({ page: 1, limit: 20 });
if (result.success) {
  console.log('Files:', result.data.files);
}

Features

• 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

Authentication

The SDK uses cookie-based authentication, which works automatically in browser environments:

// Login
await client.login({
  email: '[email protected]',
  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();

MFA Support

If the user has MFA enabled, provide the TOTP code:

await client.login({
  email: '[email protected]',
  password: 'password',
  totp: '123456' // From authenticator app
});

// Or use a backup code
await client.login({
  email: '[email protected]',
  password: 'password',
  backupCode: 'ABCD-EFGH-1234'
});

API Methods

Generic Methods

The SDK provides generic HTTP methods that work with any endpoint:

// 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' });

Convenience Methods

For common operations, use the typed convenience methods:

Files

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

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

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

// 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();

Error Handling

All methods return an ApiResult type that indicates success or failure:

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:

import { WitniumApiError } from 'witnium-vault-sdk';

try {
  await client.login({ email: '[email protected]', 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');
    }
  }
}

Endpoint Registry (For AI Tools)

The SDK includes a runtime endpoint registry for AI tools like Lovable:

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

Configuration

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
});

TypeScript Types

The SDK exports all types for use in your application:

import type {
  // Client types
  WitniumVaultClientConfig,
  ApiResult,
  ApiError,
  LoginCredentials,
  
  // API types
  FileMetadata,
  FilesListResponse,
  EvidenceBinder,
  SearchResult,
  
  // Resource options
  ListFilesOptions,
  SearchOptions,
  CreateBinderOptions,
} from 'witnium-vault-sdk';

Examples

Upload and Process a File

// 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');
}

Export Evidence Binder

// 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);
  }
}

Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Generate types from OpenAPI spec
npm run generate-types

# Type check
npm run typecheck

License

MIT