doopal
Version:
JavaScript/TypeScript SDK for Doopal AI Governance Platform
704 lines (571 loc) • 16.9 kB
Markdown
# Doopal AI Governance JavaScript SDK
The Doopal JavaScript/TypeScript SDK provides a simple and powerful way to integrate AI governance, redaction, and policy enforcement into your JavaScript applications. Route your LLM API calls through Doopal to ensure compliance, security, and cost control.
## Installation
### npm
```bash
npm install doopal
```
### yarn
```bash
yarn add doopal
```
### CDN (Browser)
```html
<script src="https://unpkg.com/doopal@latest/doopal-client.js"></script>
```
## Quick Start
### Node.js (CommonJS)
```javascript
const { DoopalClient } = require('doopal');
const client = new DoopalClient({
apiKey: 'your-api-key'
});
async function main() {
try {
const response = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [
{ role: 'user', content: 'Hello, how are you?' }
]
});
console.log('Response:', response.response);
console.log('Redacted content:', response.redacted_content);
} catch (error) {
console.error('Error:', error.message);
}
}
main();
```
### ES Modules
```javascript
import { DoopalClient } from 'doopal';
const client = new DoopalClient({
apiKey: 'your-api-key'
});
const response = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [
{ role: 'user', content: 'Hello, how are you?' }
]
});
console.log(response.response);
```
### TypeScript
```typescript
import { DoopalClient, ChatCompletionParams, DoopalResponse } from 'doopal';
const client = new DoopalClient({
apiKey: 'your-api-key',
baseUrl: 'https://api.doopal.com',
timeout: 30000
});
const params: ChatCompletionParams = {
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [
{ role: 'user', content: 'Hello, how are you?' }
],
temperature: 0.7,
maxTokens: 100
};
const response: DoopalResponse = await client.chatCompletion(params);
```
### Browser
```html
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/doopal@latest/doopal-client.js"></script>
</head>
<body>
<script>
const client = new DoopalClient({
apiKey: 'your-api-key'
});
client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [
{ role: 'user', content: 'Hello, how are you?' }
]
}).then(response => {
console.log('Response:', response.response);
}).catch(error => {
console.error('Error:', error.message);
});
</script>
</body>
</html>
```
## Features
### Core AI Gateway
- **Multi-Provider Support**: Works with OpenAI, Anthropic, Azure OpenAI, Cohere, and more
- **Governance & Compliance**: Automatic policy enforcement and compliance checking
- **Content Redaction**: Sensitive data detection and redaction
- **Cost Control**: Budget management and usage tracking
- **Streaming Support**: Real-time streaming responses (Node.js only)
- **Error Handling**: Comprehensive error handling with specific exception types
- **TypeScript Support**: Full TypeScript definitions included
- **Browser & Node.js**: Works in both browser and Node.js environments
### Enterprise Features (v1.1.0+)
- **Organization Management**: Multi-tenant organization administration
- **Role-Based Access Control (RBAC)**: User roles and permissions management
- **Single Sign-On (SSO)**: SAML/OIDC enterprise authentication
- **Advanced Analytics**: Compliance, threat detection, performance, and cost analytics
- **Audit Logging**: Comprehensive audit trails and compliance reporting
- **Security Monitoring**: Real-time threat detection and alerting
- **Policy Management**: Advanced policy creation, testing, and management
- **Provider Management**: AI provider configuration and monitoring
- **Comprehensive Health Checks**: Kubernetes-ready health, readiness, and liveness probes
## Configuration
### Environment Variables
```bash
export DOOPAL_API_KEY="your-api-key"
export DOOPAL_BASE_URL="https://api.doopal.com" # Optional
export DOOPAL_ORG_ID="your-org-id" # Optional for multi-tenant setups
```
### Client Configuration
```javascript
const client = new DoopalClient({
apiKey: 'your-api-key',
baseUrl: 'https://api.doopal.com', // Default
timeout: 30000, // Request timeout in milliseconds
maxRetries: 3, // Maximum retry attempts
organizationId: 'your-org-id' // Optional
});
```
## API Reference
### Chat Completions
```javascript
const response = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is the capital of France?' }
],
temperature: 0.7,
maxTokens: 100,
stream: false
});
```
### Streaming Chat Completions (Node.js only)
```javascript
const streamResponse = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [{ role: 'user', content: 'Tell me a story' }],
stream: true
});
for await (const chunk of streamResponse) {
process.stdout.write(chunk);
}
```
### Text Completions
```javascript
const response = await client.completion({
provider: 'openai',
model: 'gpt-3.5-turbo-instruct',
prompt: 'The capital of France is',
maxTokens: 50
});
```
### Embeddings
```javascript
const response = await client.embeddings({
provider: 'openai',
model: 'text-embedding-ada-002',
inputText: 'Hello world'
});
```
### Usage Statistics
```javascript
const stats = await client.getUsageStats();
console.log(`Total requests: ${stats.total_requests}`);
console.log(`Total cost: $${stats.total_cost}`);
```
### Health Check
```javascript
// Basic health check
const health = await client.healthCheck();
console.log(`Status: ${health.status}`);
// Detailed health status (includes database, redis, etc.)
const detailedHealth = await client.getDetailedHealth();
console.log(`Database: ${detailedHealth.database.status}`);
console.log(`Redis: ${detailedHealth.redis.status}`);
// Kubernetes readiness probe
const readiness = await client.getReadinessStatus();
console.log(`Ready: ${readiness.status}`);
// Kubernetes liveness probe
const liveness = await client.getLivenessStatus();
console.log(`Live: ${liveness.status}`);
```
### Enterprise Organization Management
```javascript
// Get organization information
const org = await client.getOrganization();
console.log(`Organization: ${org.name}`);
// Update organization settings
const updatedOrg = await client.updateOrganization({
name: 'Acme Corp',
settings: {
enableAdvancedAnalytics: true,
complianceFrameworks: ['gdpr', 'hipaa']
}
});
// Get user roles and permissions
const roles = await client.getUserRoles();
console.log(`User role: ${roles.role}`);
console.log(`Permissions: ${roles.permissions}`);
// Get organization members
const members = await client.getOrganizationMembers();
console.log(`${members.length} members in organization`);
// Invite new user
const invitation = await client.inviteUser({
email: 'user@company.com',
role: 'manager'
});
// Configure SSO
const ssoConfig = await client.configureSso({
provider: 'okta',
domain: 'company.okta.com',
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
});
```
### Advanced Analytics
```javascript
// Compliance analytics
const complianceData = await client.getComplianceAnalytics({
framework: 'gdpr',
startDate: '2024-01-01',
endDate: '2024-12-31'
});
// Threat detection analytics
const threats = await client.getThreatAnalytics({
severity: 'high',
timeframe: '24h'
});
// Performance analytics
const performance = await client.getPerformanceAnalytics({
metric: 'response_time',
aggregation: 'avg'
});
// Cost analytics
const costs = await client.getCostAnalytics({
provider: 'openai',
groupBy: 'model'
});
```
### Compliance Reporting
```javascript
// Get compliance status
const status = await client.getComplianceStatus('gdpr');
console.log(`GDPR compliance: ${status.score}%`);
// Generate compliance report
const report = await client.generateComplianceReport({
framework: 'hipaa',
format: 'pdf',
period: 'quarterly'
});
// Get compliance violations
const violations = await client.getComplianceViolations({
severity: 'high',
status: 'open'
});
```
### Policy Management
```javascript
// Get all policies
const policies = await client.getPolicies();
// Create new policy
const newPolicy = await client.createPolicy({
name: 'Content Safety Policy',
description: 'Prevent harmful content generation',
policyType: 'rego',
policyContent: 'package content.safety\n\ndefault allow = false...',
enabled: true,
priority: 1
});
// Update policy
const updatedPolicy = await client.updatePolicy('policy-id', {
enabled: false,
priority: 2
});
// Delete policy
const deleted = await client.deletePolicy('policy-id');
// Test policy
const testResult = await client.testPolicy({
policyId: 'policy-id',
testInput: {
content: 'Test content',
user: { role: 'user' }
}
});
```
### Provider Management
```javascript
// Get available providers
const providers = await client.getProviders();
// Add new provider
const newProvider = await client.addProvider({
name: 'OpenAI Production',
providerType: 'openai',
apiKey: 'sk-...',
modelConfigs: {
'gpt-4': {
maxTokens: 4000,
temperature: 0.7,
costPerToken: 0.00003
}
},
rateLimits: {
requestsPerMinute: 3500,
tokensPerMinute: 90000
}
});
// Update provider
const updatedProvider = await client.updateProvider('provider-id', {
rateLimits: {
requestsPerMinute: 5000
}
});
```
### Security & Monitoring
```javascript
// Get security threats
const threats = await client.getSecurityThreats({
severity: 'high',
timeframe: '1h'
});
// Get observability metrics
const metrics = await client.getObservabilityMetrics({
metric: 'request_rate',
timeframe: '5m'
});
// Get system alerts
const alerts = await client.getAlerts({
status: 'active',
severity: 'critical'
});
```
### Integrations
```javascript
// Get available integrations
const integrations = await client.getIntegrations();
// Configure integration
const configuredIntegration = await client.configureIntegration({
type: 'slack',
config: {
webhookUrl: 'https://hooks.slack.com/...',
channel: '#ai-governance'
}
});
```
### Data Validation
```javascript
// Validate structured data
const validation = await client.validateStructuredData({
schema: {
type: 'object',
properties: {
name: { type: 'string' },
age: { type: 'number' }
}
},
data: { name: 'John', age: 30 }
});
// Validate PII detection
const piiValidation = await client.validatePII({
content: 'My email is john@example.com'
});
console.log(`PII detected: ${piiValidation.piiDetected}`);
```
### Audit Logging
```javascript
// Get audit logs
const auditLogs = await client.getAuditLogs({
action: 'policy_violation',
startDate: '2024-01-01',
endDate: '2024-01-31',
userId: 'user123'
});
console.log(`Found ${auditLogs.length} audit entries`);
```
## Error Handling
The SDK provides specific exception types for different error scenarios:
```javascript
const { DoopalError, PolicyViolationError, RedactionError } = require('doopal');
try {
const response = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [{ role: 'user', content: 'Sensitive content here' }]
});
} catch (error) {
if (error instanceof PolicyViolationError) {
console.error('Policy violation:', error.message);
} else if (error instanceof RedactionError) {
console.error('Content blocked:', error.message);
} else if (error instanceof DoopalError) {
console.error('API error:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
```
## Advanced Usage
### Custom Metadata
```javascript
const response = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [{ role: 'user', content: 'Hello' }],
metadata: {
userId: 'user123',
sessionId: 'session456',
department: 'engineering'
}
});
```
### Multiple Providers
```javascript
// OpenAI
const openaiResponse = await client.chatCompletion({
provider: 'openai',
model: 'gpt-3.5-turbo',
messages: [{ role: 'user', content: 'Hello' }]
});
// Anthropic
const anthropicResponse = await client.chatCompletion({
provider: 'anthropic',
model: 'claude-3-sonnet-20240229',
messages: [{ role: 'user', content: 'Hello' }]
});
// Azure OpenAI
const azureResponse = await client.chatCompletion({
provider: 'azure_openai',
model: 'gpt-35-turbo',
messages: [{ role: 'user', content: 'Hello' }]
});
```
## Response Format
All responses include governance and redaction information:
```javascript
{
"response": "The generated text response",
"provider": "openai",
"model": "gpt-3.5-turbo",
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
},
"metadata": {
"request_id": "req_123",
"processing_time": 1.5,
"policies_applied": ["content_filter", "rate_limit"],
"cost": 0.0001
},
"redacted_content": [
"email@example.com was redacted",
"SSN 123-45-6789 was blocked"
]
}
```
## Browser Considerations
- Streaming is not supported in browser environments due to CORS and security limitations
- Make sure to handle CORS properly when calling from browser applications
- Consider using environment variables or secure configuration for API keys
- Enterprise features require proper authentication and organization context
- Some analytics and monitoring features may have restricted browser access for security
## Enterprise Integration Examples
### Multi-Tenant Setup
```javascript
// Initialize client with organization context
const client = new DoopalClient({
apiKey: 'your-api-key',
baseUrl: 'https://api.your-domain.com',
organizationId: 'org-123' // Important for multi-tenant deployments
});
// All subsequent calls will be scoped to this organization
const orgData = await client.getOrganization();
const compliance = await client.getComplianceStatus('gdpr');
```
### Production Monitoring
```javascript
// Health monitoring for production deployments
const healthChecks = {
basic: await client.healthCheck(),
detailed: await client.getDetailedHealth(),
ready: await client.getReadinessStatus(),
live: await client.getLivenessStatus()
};
console.log('Production health status:', healthChecks);
// Real-time threat monitoring
setInterval(async () => {
const threats = await client.getSecurityThreats({ timeframe: '5m' });
if (threats.length > 0) {
console.warn(`${threats.length} security threats detected!`);
}
}, 30000); // Check every 30 seconds
```
### Compliance Automation
```javascript
// Automated compliance reporting
const complianceReport = await client.generateComplianceReport({
framework: 'sox',
format: 'json',
period: 'monthly',
includeViolations: true,
includeRemediation: true
});
// Send to compliance team
console.log(`Generated SOX report: ${complianceReport.reportId}`);
```
## Development
### Building
```bash
npm run build
```
### Testing
```bash
npm test
```
### Linting
```bash
npm run lint
```
### Formatting
```bash
npm run format
```
## Changelog
### v1.1.0 (Latest)
- ✨ Added enterprise organization management
- ✨ Implemented RBAC and user management
- ✨ Added advanced compliance analytics
- ✨ Comprehensive health checks for Kubernetes
- ✨ Security threat detection and monitoring
- ✨ Policy management and testing capabilities
- ✨ Provider management and configuration
- ✨ Audit logging and compliance reporting
- ✨ Integration management
- ✨ Structured data validation
- 🔧 Updated to support all B2B enterprise features
### v1.0.0
- 🎉 Initial release
- ✨ Basic chat completions and embeddings
- ✨ Multi-provider support
- ✨ Content redaction and policy enforcement
- ✨ Streaming support (Node.js)
- ✨ OpenAI-compatible endpoints
## Support
- Documentation: https://docs.doopal.com
- GitHub Issues: https://github.com/doopal-ai/doopal/issues
- Email: info@doopal.com
- Enterprise Support: info@doopal.com
- Customer Success: info@doopal.com
## License
MIT License - see LICENSE file for details.