@altsafe/aidirector 1.0.0 → 1.0.1

package/README.md

@@ -1,8 +1,8 @@
-# @aidirector/client
+# @altsafe/aidirector
 
 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)
+[![npm version](https://img.shields.io/npm/v/@altsafe/aidirector.svg)](https://www.npmjs.com/package/@altsafe/aidirector)
 [![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)
 
@@ -18,21 +18,21 @@ Official TypeScript SDK for **AI Director** — the intelligent AI API gateway w
 ## Installation
 
 ```bash
-npm install @aidirector/client
+npm install @altsafe/aidirector
 # or
-bun add @aidirector/client
+bun add @altsafe/aidirector
 # or
-pnpm add @aidirector/client
+pnpm add @altsafe/aidirector
 ```
 
 ## Quick Start
 
 ```typescript
-import { AIDirector } from '@aidirector/client';
+import { AIDirector } from '@altsafe/aidirector';
 
 const client = new AIDirector({
   secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
-  baseUrl: 'https://api.aidirector.dev', // Optional
+  baseUrl: 'https://your-api.example.com',
 });
 
 const result = await client.generate({
@@ -55,7 +55,7 @@ if (result.success) {
 ```typescript
 'use server';
 
-import { AIDirector } from '@aidirector/client';
+import { AIDirector } from '@altsafe/aidirector';
 
 const client = new AIDirector({
   secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
@@ -74,7 +74,7 @@ export async function generateContent(prompt: string) {
 ```typescript
 // app/api/generate/route.ts
 import { NextResponse } from 'next/server';
-import { AIDirector } from '@aidirector/client';
+import { AIDirector } from '@altsafe/aidirector';
 
 const client = new AIDirector({
   secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
@@ -110,8 +110,10 @@ import {
   AIDirector, 
   TimeoutError, 
   RateLimitError,
-  isAIDirectorError 
-} from '@aidirector/client';
+  ValidationError,
+  isAIDirectorError,
+  isRetryableError,
+} from '@altsafe/aidirector';
 
 try {
   const result = await client.generate({ chainId, prompt });
@@ -120,8 +122,15 @@ try {
     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 (error instanceof ValidationError) {
+    console.log('Validation failed:', error.validationErrors);
   } else if (isAIDirectorError(error)) {
     console.log('AI Director error:', error.code, error.message);
+    
+    // Check if we should retry
+    if (isRetryableError(error)) {
+      console.log('This error is retryable');
+    }
   }
 }
 ```
@@ -140,6 +149,8 @@ try {
 
 ### `client.generate(options)`
 
+Generate content using your fallback chain.
+
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `chainId` | `string` | Yes | Fallback chain ID |
@@ -148,39 +159,186 @@ try {
 | `timeout` | `number` | No | Override timeout for this request |
 | `options.temperature` | `number` | No | Randomness (0-2) |
 | `options.maxTokens` | `number` | No | Max output tokens |
+| `options.topP` | `number` | No | Nucleus sampling (0-1) |
+| `options.topK` | `number` | No | Top-K sampling |
+| `options.systemPrompt` | `string` | No | System prompt to prepend |
+
+**Returns:** `Promise<GenerateResult>`
+
+```typescript
+interface GenerateResult {
+  success: boolean;
+  data: {
+    valid: unknown[];      // Schema-compliant objects
+    invalid: unknown[];    // Failed validation but parsed
+    rawContent?: string;   // Raw AI response
+  };
+  meta: {
+    cached: boolean;
+    modelUsed: string;
+    tokensUsed: { input: number; output: number };
+    latencyMs: number;
+    attemptedModels: string[];
+    finishReason?: string;
+  };
+  error?: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+  };
+}
+```
+
+### `client.generateStream(options, callbacks)`
+
+Stream responses in real-time.
+
+```typescript
+interface StreamCallbacks {
+  onChunk?: (chunk: string) => void;
+  onComplete?: (result: GenerateResult) => void;
+  onError?: (error: Error) => void;
+  onProgress?: (progress: StreamProgress) => void;
+}
+```
+
+### `client.listModels()`
 
-### Other Methods
+List all available AI models.
 
 ```typescript
-// List available models
 const models = await client.listModels();
+// Returns: ModelInfo[]
+```
+
+### `client.listChains()`
 
-// Get your chains (requires auth)
+Get your fallback chains (requires session auth).
+
+```typescript
 const chains = await client.listChains();
+// Returns: ChainInfo[]
+```
+
+### `client.getUsage(options?)`
+
+Get usage statistics for your account.
 
-// Usage statistics
+```typescript
 const usage = await client.getUsage({ 
-  startDate: new Date('2024-01-01') 
+  startDate: new Date('2024-01-01'),
+  endDate: new Date(),
 });
+// Returns: UsageStats
+```
+
+### `client.health()`
+
+Health check to verify API connection.
+
+```typescript
+const { ok, latencyMs, version } = await client.health();
+```
+
+### `client.withConfig(overrides)`
 
-// Health check
-const { ok, latencyMs } = await client.health();
+Create a new client with different configuration.
 
-// Create new client with different config
+```typescript
 const debugClient = client.withConfig({ debug: true });
+const fastClient = client.withConfig({ timeout: 30000 });
 ```
 
 ## 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 |
+| Error | Code | Retryable | Properties | Description |
+|-------|------|-----------|------------|-------------|
+| `ConfigurationError` | `CONFIGURATION_ERROR` | No | — | Invalid client setup |
+| `AuthenticationError` | `AUTH_ERROR` | No | `statusCode` | Invalid credentials |
+| `RateLimitError` | `RATE_LIMITED` | Yes | `retryAfterMs` | Too many requests |
+| `TimeoutError` | `TIMEOUT` | Yes | `timeoutMs` | Request timed out |
+| `NetworkError` | `NETWORK_ERROR` | Yes | `originalError` | Connection failed |
+| `ChainExecutionError` | `CHAIN_FAILED` | No | `attemptedModels` | All models failed |
+| `ValidationError` | `VALIDATION_ERROR` | No | `validationErrors` | Schema validation failed |
+| `ServerError` | `SERVER_ERROR` | Yes | `statusCode` | Internal server error |
+
+### Error Helpers
+
+```typescript
+import { isAIDirectorError, isRetryableError } from '@altsafe/aidirector';
+
+// Check if error is from AI Director
+if (isAIDirectorError(error)) {
+  console.log(error.code, error.message);
+}
+
+// Check if error should be retried
+if (isRetryableError(error)) {
+  // Implement retry logic
+}
+```
+
+## Advanced: HMAC Utilities
+
+For custom integrations, you can use the HMAC utilities directly:
+
+```typescript
+import { 
+  generateSignature, 
+  getKeyPrefix, 
+  isValidSecretKey 
+} from '@altsafe/aidirector';
+
+// Validate a secret key format
+if (isValidSecretKey(key)) {
+  console.log('Valid key');
+}
+
+// Get key prefix for headers
+const prefix = getKeyPrefix(secretKey); // "aid_sk_xxxx"
+
+// Generate signature for custom requests
+const signature = await generateSignature(
+  secretKey,
+  'POST',
+  '/api/v1/generate',
+  JSON.stringify(body),
+  Date.now()
+);
+```
+
+## TypeScript Types
+
+All types are exported for your convenience:
+
+```typescript
+import type {
+  // Configuration
+  AIDirectorConfig,
+  
+  // Generation
+  GenerateOptions,
+  GenerateResult,
+  GenerateData,
+  GenerateMeta,
+  GenerateError,
+  GenerationParameters,
+  TokenUsage,
+  
+  // Streaming
+  StreamCallbacks,
+  StreamProgress,
+  
+  // Chains & Models
+  ChainInfo,
+  ChainStep,
+  ModelInfo,
+  
+  // Usage & Health
+  UsageStats,
+  HealthResult,
+} from '@altsafe/aidirector';
+```
 
 ## Security
 
@@ -200,4 +358,4 @@ AIDIRECTOR_SECRET_KEY=aid_sk_your_secret_key_here
 
 ## License
 
-MIT © AI Director
+MIT © altsafe

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@altsafe/aidirector",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Official TypeScript SDK for AI Director - Intelligent AI API Gateway with automatic failover, caching, and JSON extraction",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",