@altsafe/aidirector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Director
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @aidirector/client
+
+Official TypeScript SDK for **AI Director** — the intelligent AI API gateway with automatic failover, response caching, and JSON extraction.
+
+[![npm version](https://img.shields.io/npm/v/@aidirector/client.svg)](https://www.npmjs.com/package/@aidirector/client)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔐 **HMAC Authentication** — Secure request signing (Node.js & browser)
+- ⚡ **10-minute Timeout** — Handles long-running AI requests
+- 🔄 **Automatic Retries** — Exponential backoff with configurable limits
+- 📦 **Structured Errors** — Type-safe error handling
+- 🌊 **Streaming Support** — Real-time response streaming
+- 🎯 **Full TypeScript** — Complete type definitions
+
+## Installation
+
+```bash
+npm install @aidirector/client
+# or
+bun add @aidirector/client
+# or
+pnpm add @aidirector/client
+```
+
+## Quick Start
+
+```typescript
+import { AIDirector } from '@aidirector/client';
+
+const client = new AIDirector({
+  secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
+  baseUrl: 'https://api.aidirector.dev', // Optional
+});
+
+const result = await client.generate({
+  chainId: 'your-chain-id',
+  prompt: 'Generate 5 user profiles with name and email',
+  schema: { name: 'string', email: 'string' },
+});
+
+if (result.success) {
+  console.log('Users:', result.data.valid);
+  console.log('Model:', result.meta.modelUsed);
+  console.log('Cached:', result.meta.cached);
+}
+```
+
+## Usage Examples
+
+### Next.js Server Actions
+
+```typescript
+'use server';
+
+import { AIDirector } from '@aidirector/client';
+
+const client = new AIDirector({
+  secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
+});
+
+export async function generateContent(prompt: string) {
+  return client.generate({
+    chainId: process.env.DEFAULT_CHAIN_ID!,
+    prompt,
+  });
+}
+```
+
+### API Routes
+
+```typescript
+// app/api/generate/route.ts
+import { NextResponse } from 'next/server';
+import { AIDirector } from '@aidirector/client';
+
+const client = new AIDirector({
+  secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
+});
+
+export async function POST(request: Request) {
+  const { prompt, chainId } = await request.json();
+  const result = await client.generate({ chainId, prompt });
+  return NextResponse.json(result);
+}
+```
+
+### Streaming
+
+```typescript
+await client.generateStream(
+  {
+    chainId: 'my-chain',
+    prompt: 'Write a long story...',
+  },
+  {
+    onChunk: (chunk) => process.stdout.write(chunk),
+    onComplete: (result) => console.log('\nDone!', result.meta),
+    onError: (error) => console.error('Error:', error),
+  }
+);
+```
+
+### Error Handling
+
+```typescript
+import { 
+  AIDirector, 
+  TimeoutError, 
+  RateLimitError,
+  isAIDirectorError 
+} from '@aidirector/client';
+
+try {
+  const result = await client.generate({ chainId, prompt });
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log('Request timed out after', error.timeoutMs, 'ms');
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limited, retry after', error.retryAfterMs, 'ms');
+  } else if (isAIDirectorError(error)) {
+    console.log('AI Director error:', error.code, error.message);
+  }
+}
+```
+
+## API Reference
+
+### `new AIDirector(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secretKey` | `string` | — | **Required.** Your API secret key |
+| `baseUrl` | `string` | `localhost:3000` | API base URL |
+| `timeout` | `number` | `600000` | Request timeout (ms) |
+| `maxRetries` | `number` | `3` | Max retry attempts |
+| `debug` | `boolean` | `false` | Enable console logging |
+
+### `client.generate(options)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `chainId` | `string` | Yes | Fallback chain ID |
+| `prompt` | `string` | Yes | Prompt to send |
+| `schema` | `object` | No | JSON schema for validation |
+| `timeout` | `number` | No | Override timeout for this request |
+| `options.temperature` | `number` | No | Randomness (0-2) |
+| `options.maxTokens` | `number` | No | Max output tokens |
+
+### Other Methods
+
+```typescript
+// List available models
+const models = await client.listModels();
+
+// Get your chains (requires auth)
+const chains = await client.listChains();
+
+// Usage statistics
+const usage = await client.getUsage({ 
+  startDate: new Date('2024-01-01') 
+});
+
+// Health check
+const { ok, latencyMs } = await client.health();
+
+// Create new client with different config
+const debugClient = client.withConfig({ debug: true });
+```
+
+## Error Classes
+
+| Error | Code | Retryable | Description |
+|-------|------|-----------|-------------|
+| `ConfigurationError` | `CONFIGURATION_ERROR` | No | Invalid client setup |
+| `AuthenticationError` | `AUTH_ERROR` | No | Invalid credentials |
+| `RateLimitError` | `RATE_LIMITED` | Yes | Too many requests |
+| `TimeoutError` | `TIMEOUT` | Yes | Request timed out |
+| `NetworkError` | `NETWORK_ERROR` | Yes | Connection failed |
+| `ChainExecutionError` | `CHAIN_FAILED` | No | All models failed |
+| `ServerError` | `SERVER_ERROR` | Yes | Internal server error |
+
+## Security
+
+⚠️ **Server-side only!** Never expose your secret key to browsers.
+
+- ✅ Next.js API routes / Server Actions
+- ✅ Express.js / Fastify
+- ✅ Angular Universal (SSR)
+- ✅ Edge Functions (Vercel, Cloudflare)
+- ❌ Client-side JavaScript
+
+Store your secret key in environment variables:
+
+```bash
+AIDIRECTOR_SECRET_KEY=aid_sk_your_secret_key_here
+```
+
+## License
+
+MIT © AI Director