@altsafe/aidirector - Client SDK

Production-grade TypeScript SDK for the AI Director API gateway.

Installation

npm install @altsafe/aidirector
# or
pnpm add @altsafe/aidirector

Quick Start

import { AIDirector } from '@altsafe/aidirector';

const client = new AIDirector({
  secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
  baseUrl: 'https://your-instance.vercel.app',
});

// Generate content
const result = await client.generate({
  chainId: 'my-chain',
  prompt: 'Generate 5 user profiles',
});

if (result.success) {
  console.log(result.data.valid);
}

Features

• 🔐 HMAC Authentication - Secure request signing
• ⚡ 3-Step Architecture - Token → Worker → Complete (minimizes costs)
• 📎 File Attachments - Upload and process documents
• 🔄 Automatic Retries - Exponential backoff on failures
• 💾 Smart Caching - Hybrid Redis caching with 7-day TTL
• 🎯 TypeScript - Full type safety

Streaming (Recommended for Large Responses)

await client.generateStream(
  {
    chainId: 'my-chain',
    prompt: 'Generate 100 product descriptions',
  },
  {
    onObject: (obj, index) => {
      console.log(`Object ${index}:`, obj);
      renderToUI(obj); // Render immediately!
    },
    onComplete: (result) => {
      console.log(`Done! ${result.objectCount} objects`);
    },
    onError: (error) => {
      console.error('Stream failed:', error);
    },
  }
);

File Attachments

import fs from 'fs';

const fileBuffer = fs.readFileSync('report.pdf');

const result = await client.generate({
  chainId: 'document-analysis',
  prompt: 'Summarize this document',
  files: [{
    data: fileBuffer.toString('base64'),
    filename: 'report.pdf',
    mimeType: 'application/pdf',
  }],
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | secretKey | string | required | Your API key (aid_sk_...) | | baseUrl | string | http://localhost:3000 | API base URL | | timeout | number | 600000 | Request timeout (10 min) | | maxRetries | number | 3 | Max retry attempts | | debug | boolean | false | Enable debug logging | | useOptimized | boolean | true | Use 3-step Worker flow |

API Methods

| Method | Description | |--------|-------------| | generate(options) | Generate content with fallback chain | | generateStream(options, callbacks) | Stream JSON objects in real-time | | listModels() | List available AI models | | listChains() | List your fallback chains | | getUsageStats(options) | Get usage statistics | | healthCheck() | Check API health |

Error Handling

import { 
  RateLimitError,
  TimeoutError,
  AuthenticationError,
} from '@altsafe/aidirector';

try {
  const result = await client.generate({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfterMs}ms`);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  }
}

Pricing

BYOK (Bring Your Own Key) - You pay for AI costs directly to providers.

| Tier | Price | Requests | Overage | |------|-------|----------|---------| | Free | $0 | 1K | Blocked | | Starter | $9 | 25K | $0.50/1K | | Pro | $29 | 100K | $0.40/1K | | Scale | $79 | 500K | $0.30/1K |

License

MIT