Official Node.js SDK for the AetherGuard AI Gateway proxy engine. A drop-in replacement for OpenAI-compatible clients that routes all requests through AetherGuard's 8-stage security pipeline — providing prompt injection prevention, PII redaction, toxicity detection, model attestation, and immutable audit provenance without changing your application code.
Note: This SDK is for calling the AetherGuard proxy API (chat completions, streaming, tool calling). All management features (policies, API keys, analytics, providers) are available exclusively through the AetherGuard Admin Portal.
- 🔌 OpenAI Compatible — Drop-in replacement; just change the base URL
- 🛡️ Security Pipeline — Every request passes through 8 stages of security checks automatically
- 🛠️ Tool Calling — Full support for function/tool calling with convenience helpers
- 🖼️ Multimodal — Vision support (text + images) via content parts
- 📡 Streaming — Real-time SSE streaming with security scanning
- 📋 JSON Mode — Structured output via
response_format - 🔧 TypeScript — Full type definitions for all request/response shapes
Before using this SDK you need an AetherGuard account with a configured provider and model:
- Go to https://portal.aetherguard.ai and sign up
- Add an LLM Provider (OpenAI, Anthropic, Azure, Bedrock, etc.) with your provider API key
- Register a Model and link it to your provider
- Generate an API Key — this is what you'll pass to the SDK
Once you have your API key and proxy URL, you're ready to go.
npm install @aetherguard/sdkIf working on the SDK itself:
cd aetherguard-sdk
npm install
npm run buildconst { AetherGuardClient } = require('@aetherguard/sdk');
const client = new AetherGuardClient({
apiKey: process.env.AETHERGUARD_API_KEY,
baseUrl: process.env.AETHERGUARD_BASE_URL || 'https://proxy.aetherguard.ai'
});
async function main() {
const response = await client.createChatCompletion({
model: 'gpt-4',
messages: [
{ role: 'user', content: 'What is artificial intelligence?' }
],
max_tokens: 150
});
console.log(response.choices[0].message.content);
}
main();const client = new AetherGuardClient({
apiKey: 'your-api-key', // Required: issued via Admin Portal
baseUrl: 'https://proxy.aetherguard.ai', // Optional: proxy endpoint (default: http://localhost:8080)
timeout: 30000, // Optional: request timeout in ms (default: 30000)
retries: 3, // Optional: max retry attempts (default: 3)
debug: false // Optional: log requests/responses (default: false)
});export AETHERGUARD_API_KEY="your-api-key"
export AETHERGUARD_BASE_URL="https://proxy.aetherguard.ai"Standard OpenAI-compatible chat completions — all requests are automatically scanned by the security pipeline:
const response = await client.createChatCompletion({
model: 'gpt-4',
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'Explain quantum computing' }
],
max_tokens: 200,
temperature: 0.7
});
console.log(response.choices[0].message.content);
console.log('Tokens used:', response.usage.total_tokens);Real-time streaming responses with security scanning applied per-chunk:
await client.createChatCompletionStream(
{
model: 'gpt-4',
messages: [{ role: 'user', content: 'Write a story about AI' }],
max_tokens: 300
},
(chunk) => {
const content = chunk.choices[0]?.delta?.content;
if (content) process.stdout.write(content);
},
(error) => console.error('Stream error:', error),
() => console.log('\nDone.')
);Define tools the model can invoke, handle the results, and submit them back:
const { createTool, hasToolCalls, extractToolCalls } = require('@aetherguard/sdk');
// Define tools
const tools = [
createTool('get_weather', 'Get current weather for a location', {
type: 'object',
properties: {
location: { type: 'string', description: 'City name' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
},
required: ['location']
})
];
// Request with tools
const response = await client.createToolCompletion({
model: 'gpt-4',
messages: [{ role: 'user', content: 'What is the weather in London?' }],
tools,
tool_choice: 'auto'
});
// Handle tool calls
if (hasToolCalls(response)) {
const calls = extractToolCalls(response);
const toolOutputs = calls.map(tc => {
const args = JSON.parse(tc.arguments);
const result = getWeather(args.location, args.unit); // your implementation
return { tool_call_id: tc.id, content: JSON.stringify(result) };
});
// Submit results back
const finalResponse = await client.submitToolOutputs(
'gpt-4',
[...messages, response.choices[0].message],
toolOutputs
);
console.log(finalResponse.choices[0].message.content);
}Send images alongside text:
const response = await client.createChatCompletion({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: [
{ type: 'text', text: 'What is in this image?' },
{ type: 'image_url', image_url: { url: 'https://example.com/photo.png', detail: 'high' } }
]
}
],
max_tokens: 300
});Force structured JSON output:
const response = await client.createChatCompletion({
model: 'gpt-4',
messages: [
{ role: 'system', content: 'Respond with JSON containing name and age.' },
{ role: 'user', content: 'Tell me about Albert Einstein' }
],
response_format: { type: 'json_object' }
});
const data = JSON.parse(response.choices[0].message.content);The proxy returns structured errors when requests are blocked by the security pipeline:
try {
const response = await client.createChatCompletion(request);
} catch (error) {
switch (error.code) {
case 'CONTENT_BLOCKED':
console.log('Blocked by security policy');
break;
case 'RATE_LIMIT_EXCEEDED':
console.log('Rate limited — retry later');
break;
case 'UNAUTHORIZED':
console.log('Invalid or expired API key');
break;
case 'PROVIDER_UNAVAILABLE':
console.log('Upstream LLM provider is down');
break;
default:
console.log('Error:', error.message);
}
if (error.request_id) {
console.log('Request ID:', error.request_id);
}
}// Simple connectivity test
const isUp = await client.testConnection(); // true/false
// Detailed status
const status = await client.getStatus();
// { proxy_engine: "running", pipeline: "8-stage", stages: [...] }
// Metrics
const metrics = await client.getMetrics();
// { status: "healthy", version: "2.0.0", pipeline_stages: 8, pipeline: "zero-trust-8-stage" }const {
createSimpleRequest,
extractResponseText,
estimateTokens,
validateApiKey,
sanitizeForLogging,
isSecurityViolation,
createTool,
extractToolCalls,
hasToolCalls,
retryWithBackoff
} = require('@aetherguard/sdk');
// Quick request builder
const request = createSimpleRequest('Explain ML', 'gpt-4', {
maxTokens: 200,
temperature: 0.7,
systemPrompt: 'Be concise.'
});
// Extract text from response
const text = extractResponseText(response);
// Check if response was blocked
if (isSecurityViolation(response)) {
console.log('Request was blocked by security pipeline');
}
// Retry with exponential backoff
const result = await retryWithBackoff(() => client.createChatCompletion(request), 3);Full type support:
import {
AetherGuardClient,
ChatCompletionRequest,
ChatCompletionResponse,
ChatMessage,
Tool,
ToolChoice,
ToolCall,
StreamChunk,
StreamDelta,
MessageContent
} from '@aetherguard/sdk';
const client = new AetherGuardClient({
apiKey: process.env.AETHERGUARD_API_KEY!
});
const request: ChatCompletionRequest = {
model: 'gpt-4',
messages: [{ role: 'user', content: 'Hello' }],
tools: [{ type: 'function', function: { name: 'greet', parameters: {} } }],
tool_choice: 'auto'
};
const response: ChatCompletionResponse = await client.createChatCompletion(request);Every request through this SDK is automatically processed by AetherGuard's 8-stage pipeline:
| Stage | Name | What it does |
|---|---|---|
| 1 | Auth | API key validation, tenant resolution, rate limiting |
| 2 | Ingress | Prompt injection detection, PII scanning, secrets detection |
| 3 | Policy | OPA policy enforcement, complexity scoring |
| 4 | AetherSign | Model registry lookup, cryptographic signing |
| 5 | Attestation | Enclave/TEE verification (when applicable) |
| 6 | Inference | Secure forwarding to LLM provider |
| 7 | Output | Toxicity scanning, hallucination detection, watermarking |
| 8 | Provenance | Immutable audit logging to immudb |
You don't need to do anything — the pipeline runs transparently. If a request is blocked, you'll receive a structured error with the reason.
Check out the examples directory for complete working examples:
- Basic Usage — Chat completions, simple completions, proxy status
- Streaming Chat — Real-time streaming responses
- Tool Calling — Full tool-calling loop with local execution
- Advanced Features — JSON mode, vision, retry logic, batch processing
npm run build # Compile TypeScript to dist/
npm run dev # Watch mode
npm test # Run tests
npm run lint # ESLint- Node.js >= 16.0.0
AetherGuard-2026 Copyright