@altsafe/aidirector 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,659 @@
+/**
+ * AI Director Client Types
+ * Type definitions for the SDK
+ */
+/**
+ * Configuration for AI Director client
+ */
+interface AIDirectorConfig {
+    /**
+     * Your AI Director secret key
+     * Get this from your dashboard at https://aidirector.dev/dashboard/keys
+     * Format: aid_sk_<random>
+     */
+    secretKey: string;
+    /**
+     * API base URL
+     * @default 'http://localhost:3000' in development
+     * @example 'https://api.aidirector.dev'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 600000 (10 minutes)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retries for failed requests
+     * Set to 0 to disable retries
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Options for the generate method
+ */
+interface GenerateOptions {
+    /**
+     * ID of the fallback chain to use
+     * Get chain IDs from your dashboard
+     */
+    chainId: string;
+    /**
+     * The prompt to send to the AI
+     */
+    prompt: string;
+    /**
+     * Optional JSON schema for response validation
+     * The AI will be instructed to return data matching this schema
+     * @example { name: 'string', age: 'number', tags: 'string[]' }
+     */
+    schema?: Record<string, unknown>;
+    /**
+     * Override the client timeout for this request
+     */
+    timeout?: number;
+    /**
+     * Generation parameters
+     */
+    options?: GenerationParameters;
+}
+/**
+ * AI generation parameters
+ */
+interface GenerationParameters {
+    /**
+     * Controls randomness (0 = deterministic, 2 = very random)
+     * @default 0.7
+     */
+    temperature?: number;
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number;
+    /**
+     * Nucleus sampling parameter
+     * @default 1.0
+     */
+    topP?: number;
+    /**
+     * Top-K sampling parameter
+     */
+    topK?: number;
+    /**
+     * System prompt to prepend
+     */
+    systemPrompt?: string;
+}
+/**
+ * Result from the generate method
+ */
+interface GenerateResult {
+    /**
+     * Whether the request was successful
+     */
+    success: boolean;
+    /**
+     * The generated data
+     */
+    data: GenerateData;
+    /**
+     * Request metadata
+     */
+    meta: GenerateMeta;
+    /**
+     * Error information (only present if success is false)
+     */
+    error?: GenerateError;
+}
+/**
+ * Generated data
+ */
+interface GenerateData {
+    /**
+     * Schema-compliant objects (or all parsed objects if no schema)
+     */
+    valid: unknown[];
+    /**
+     * Objects that failed schema validation but were successfully parsed
+     */
+    invalid: unknown[];
+    /**
+     * Raw AI response text (useful for debugging)
+     */
+    rawContent?: string;
+}
+/**
+ * Generation metadata
+ */
+interface GenerateMeta {
+    /**
+     * Whether the response was served from cache
+     */
+    cached: boolean;
+    /**
+     * The model that generated the response
+     */
+    modelUsed: string;
+    /**
+     * Token usage
+     */
+    tokensUsed: TokenUsage;
+    /**
+     * Request latency in milliseconds
+     */
+    latencyMs: number;
+    /**
+     * Models attempted before success (includes failed models)
+     */
+    attemptedModels: string[];
+    /**
+     * Why the generation stopped
+     */
+    finishReason?: 'stop' | 'length' | 'content_filter' | 'error';
+    /**
+     * Whether JSON recovery was needed
+     */
+    recovered?: boolean;
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    input: number;
+    output: number;
+    total?: number;
+}
+/**
+ * Error information
+ */
+interface GenerateError {
+    /**
+     * Error code for programmatic handling
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Whether the error can be retried
+     */
+    retryable?: boolean;
+    /**
+     * Additional error details
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * Callbacks for streaming generation
+ */
+interface StreamCallbacks {
+    /**
+     * Called for each text chunk received
+     */
+    onChunk?: (chunk: string) => void;
+    /**
+     * Called when streaming is complete
+     */
+    onComplete?: (result: GenerateResult) => void;
+    /**
+     * Called if an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called with progress updates
+     */
+    onProgress?: (progress: StreamProgress) => void;
+}
+/**
+ * Streaming progress information
+ */
+interface StreamProgress {
+    /**
+     * Total characters received so far
+     */
+    charactersReceived: number;
+    /**
+     * Elapsed time in milliseconds
+     */
+    elapsedMs: number;
+    /**
+     * Current model being used
+     */
+    model: string;
+}
+/**
+ * Information about a fallback chain
+ */
+interface ChainInfo {
+    /**
+     * Unique chain identifier
+     */
+    id: string;
+    /**
+     * Human-readable chain name
+     */
+    name: string;
+    /**
+     * Chain description
+     */
+    description?: string;
+    /**
+     * Whether this is the default chain
+     */
+    isDefault: boolean;
+    /**
+     * Chain steps (models to try in order)
+     */
+    steps: ChainStep[];
+    /**
+     * Number of requests using this chain
+     */
+    requestCount?: number;
+    /**
+     * Date chain was created
+     */
+    createdAt?: string;
+}
+/**
+ * A step in a fallback chain
+ */
+interface ChainStep {
+    /**
+     * Model identifier
+     */
+    modelId: string;
+    /**
+     * Human-readable model name
+     */
+    modelName: string;
+    /**
+     * Provider (GEMINI, OPENROUTER)
+     */
+    provider: 'GEMINI' | 'OPENROUTER';
+    /**
+     * Step priority (lower = tried first)
+     */
+    priority: number;
+    /**
+     * Maximum retries for this step
+     */
+    maxRetries?: number;
+    /**
+     * Timeout for this step in milliseconds
+     */
+    timeoutMs?: number;
+}
+/**
+ * Information about an AI model
+ */
+interface ModelInfo {
+    /**
+     * Model identifier (use this in chains)
+     */
+    id: string;
+    /**
+     * Provider name
+     */
+    provider: 'GEMINI' | 'OPENROUTER';
+    /**
+     * Human-readable model name
+     */
+    displayName: string;
+    /**
+     * Model description
+     */
+    description?: string;
+    /**
+     * Maximum input tokens
+     */
+    inputTokenLimit?: number;
+    /**
+     * Maximum output tokens
+     */
+    outputTokenLimit?: number;
+    /**
+     * Whether model supports JSON mode
+     */
+    supportsJsonMode: boolean;
+    /**
+     * Whether model supports streaming
+     */
+    supportsStreaming?: boolean;
+    /**
+     * Whether model supports thinking/reasoning
+     */
+    supportsThinking?: boolean;
+    /**
+     * Whether model is free to use
+     */
+    isFree: boolean;
+    /**
+     * Pricing per 1M tokens (if available)
+     */
+    pricing?: {
+        input: number;
+        output: number;
+        currency: string;
+    };
+}
+/**
+ * Usage statistics
+ */
+interface UsageStats {
+    /**
+     * Total requests in period
+     */
+    totalRequests: number;
+    /**
+     * Successful requests
+     */
+    successfulRequests: number;
+    /**
+     * Failed requests
+     */
+    failedRequests: number;
+    /**
+     * Cached responses served
+     */
+    cachedResponses: number;
+    /**
+     * Total tokens used
+     */
+    totalTokens: TokenUsage;
+    /**
+     * Usage by model
+     */
+    byModel: Record<string, {
+        requests: number;
+        tokens: TokenUsage;
+    }>;
+    /**
+     * Average latency in milliseconds
+     */
+    avgLatencyMs: number;
+    /**
+     * Period start date
+     */
+    periodStart: string;
+    /**
+     * Period end date
+     */
+    periodEnd: string;
+}
+/**
+ * Health check result
+ */
+interface HealthResult {
+    /**
+     * Whether the API is healthy
+     */
+    ok: boolean;
+    /**
+     * Response latency in milliseconds
+     */
+    latencyMs: number;
+    /**
+     * API version
+     */
+    version?: string;
+    /**
+     * Current time on server
+     */
+    timestamp?: string;
+}
+
+/**
+ * AI Director Client SDK
+ *
+ * Production-grade client for the AI Director API gateway.
+ * Use in Next.js API routes, Server Actions, or any Node.js/Edge environment.
+ *
+ * Features:
+ * - 🔐 HMAC Authentication with browser support
+ * - ⚡ Configurable timeout (default 10 minutes)
+ * - 🔄 Automatic retries with exponential backoff
+ * - 📦 Structured error handling
+ * - 🎯 Full TypeScript support
+ *
+ * @example
+ * ```typescript
+ * import { AIDirector } from '@aidirector/client';
+ *
+ * const client = new AIDirector({
+ *   secretKey: process.env.AIDIRECTOR_SECRET_KEY!,
+ *   baseUrl: 'https://api.aidirector.dev',
+ * });
+ *
+ * const result = await client.generate({
+ *   chainId: 'my-chain',
+ *   prompt: 'Generate 5 user profiles',
+ *   schema: { name: 'string', age: 'number' },
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.data.valid);
+ * }
+ * ```
+ */
+declare class AIDirector {
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly keyPrefix;
+    private readonly debug;
+    constructor(config: AIDirectorConfig);
+    /**
+     * Generate content using your fallback chain
+     *
+     * @param options - Generation options
+     * @returns Promise resolving to GenerateResult
+     * @throws AIDirectorError subclasses on failure
+     *
+     * @example
+     * ```typescript
+     * const result = await client.generate({
+     *   chainId: 'production-chain',
+     *   prompt: 'List 3 programming languages',
+     *   options: { temperature: 0.7 },
+     * });
+     * ```
+     */
+    generate(options: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * Generate content with streaming (for long responses)
+     *
+     * @param options - Generation options
+     * @param callbacks - Streaming callbacks
+     *
+     * @example
+     * ```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),
+     *   }
+     * );
+     * ```
+     */
+    generateStream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void>;
+    /**
+     * List available AI models
+     *
+     * @returns Array of available models
+     */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * Get your fallback chains
+     * Note: Requires cookies/session from authenticated context
+     *
+     * @returns Array of chain configurations
+     */
+    listChains(): Promise<ChainInfo[]>;
+    /**
+     * Get usage statistics for your account
+     *
+     * @param options - Date range options
+     * @returns Usage statistics
+     */
+    getUsage(options?: {
+        startDate?: Date;
+        endDate?: Date;
+    }): Promise<UsageStats>;
+    /**
+     * Health check - verify API connection
+     *
+     * @returns Health status with latency
+     */
+    health(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+        version?: string;
+    }>;
+    /**
+     * Create a new client with different configuration
+     * Useful for testing or switching environments
+     *
+     * @param overrides - Configuration overrides
+     * @returns New AIDirector instance
+     */
+    withConfig(overrides: Partial<AIDirectorConfig>): AIDirector;
+    /**
+     * Make authenticated API request
+     */
+    private makeAuthenticatedRequest;
+    /**
+     * Fetch with timeout
+     */
+    private fetchWithTimeout;
+    /**
+     * Parse API error response
+     */
+    private parseError;
+    /**
+     * Check if error is retryable
+     */
+    private isRetryable;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/**
+ * AI Director Error Classes
+ * Structured error types for better error handling
+ */
+/**
+ * Base error class for AI Director errors
+ */
+declare class AIDirectorError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly statusCode?: number;
+    readonly originalError?: Error;
+    constructor(message: string, code: string, options?: {
+        retryable?: boolean;
+        statusCode?: number;
+        cause?: Error;
+    });
+}
+/**
+ * Configuration error - invalid client setup
+ */
+declare class ConfigurationError extends AIDirectorError {
+    constructor(message: string);
+}
+/**
+ * Authentication error - invalid or expired credentials
+ */
+declare class AuthenticationError extends AIDirectorError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Rate limit error - too many requests
+ */
+declare class RateLimitError extends AIDirectorError {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs?: number);
+}
+/**
+ * Timeout error - request took too long
+ */
+declare class TimeoutError extends AIDirectorError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Network error - connection failed
+ */
+declare class NetworkError extends AIDirectorError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Chain error - fallback chain execution failed
+ */
+declare class ChainExecutionError extends AIDirectorError {
+    readonly attemptedModels: string[];
+    constructor(message: string, attemptedModels?: string[]);
+}
+/**
+ * Validation error - schema validation failed
+ */
+declare class ValidationError extends AIDirectorError {
+    readonly validationErrors: unknown[];
+    constructor(message: string, validationErrors?: unknown[]);
+}
+/**
+ * Server error - internal server error
+ */
+declare class ServerError extends AIDirectorError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Check if error is an AI Director error
+ */
+declare function isAIDirectorError(error: unknown): error is AIDirectorError;
+/**
+ * Check if error is retryable
+ */
+declare function isRetryableError(error: unknown): boolean;
+
+/**
+ * HMAC Signature Generation
+ *
+ * Supports both Node.js (crypto) and browser (Web Crypto API) environments.
+ * The signature algorithm matches the server-side verification.
+ */
+/**
+ * Generate HMAC signature for request authentication
+ *
+ * Automatically detects environment and uses appropriate implementation.
+ *
+ * IMPORTANT: We hash the secret key first, then use the hash as HMAC key.
+ * This allows the server to verify using the stored hash (it never sees the full key).
+ */
+declare function generateSignature(secretKey: string, method: string, path: string, body: string, timestamp: number): Promise<string>;
+/**
+ * Get the key prefix for identification (sent in headers)
+ */
+declare function getKeyPrefix(secretKey: string): string;
+/**
+ * Validate secret key format
+ */
+declare function isValidSecretKey(secretKey: string): boolean;
+
+export { AIDirector, type AIDirectorConfig, AIDirectorError, AuthenticationError, ChainExecutionError, type ChainInfo, type ChainStep, ConfigurationError, type GenerateData, type GenerateError, type GenerateMeta, type GenerateOptions, type GenerateResult, type GenerationParameters, type HealthResult, type ModelInfo, NetworkError, RateLimitError, ServerError, type StreamCallbacks, type StreamProgress, TimeoutError, type TokenUsage, type UsageStats, ValidationError, generateSignature, getKeyPrefix, isAIDirectorError, isRetryableError, isValidSecretKey };