@pauly4010/evalai-sdk 1.3.0

package/dist/context.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Context Propagation System
+ * Tier 2.9: Automatic metadata injection
+ *
+ * NOTE: In Node.js, uses AsyncLocalStorage for true async context propagation.
+ * In browsers, uses a simpler stack-based approach (not safe across async boundaries).
+ *
+ * @example
+ * ```typescript
+ * import { createContext } from '@ai-eval-platform/sdk';
+ *
+ * const context = createContext({ userId: '123', sessionId: 'abc' });
+ *
+ * await context.run(async () => {
+ *   // All SDK calls inherit the context
+ *   await client.traces.create({ name: 'test' });
+ *   // ^ Automatically includes userId and sessionId
+ * });
+ * ```
+ */
+/**
+ * Context metadata that will be automatically injected
+ */
+export interface ContextMetadata {
+    [key: string]: any;
+}
+/**
+ * Context manager for automatic metadata propagation
+ */
+export declare class EvalContext {
+    private metadata;
+    constructor(metadata: ContextMetadata);
+    /**
+     * Run a function with this context
+     *
+     * @example
+     * ```typescript
+     * const context = new EvalContext({ userId: '123' });
+     *
+     * await context.run(async () => {
+     *   // All operations inherit context
+     *   await client.traces.create({ name: 'test' });
+     * });
+     * ```
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Run a synchronous function with this context
+     */
+    runSync<T>(fn: () => T): T;
+    /**
+     * Get the current context metadata
+     */
+    getMetadata(): ContextMetadata;
+    /**
+     * Merge additional metadata into context
+     */
+    with(additionalMetadata: ContextMetadata): EvalContext;
+}
+/**
+ * Create a new context with metadata
+ *
+ * @example
+ * ```typescript
+ * const context = createContext({
+ *   userId: '123',
+ *   sessionId: 'abc',
+ *   environment: 'production'
+ * });
+ *
+ * await context.run(async () => {
+ *   // All SDK operations inherit context
+ * });
+ * ```
+ */
+export declare function createContext(metadata: ContextMetadata): EvalContext;
+/**
+ * Get the current context metadata (if any)
+ *
+ * @example
+ * ```typescript
+ * const metadata = getCurrentContext();
+ * if (metadata) {
+ *   console.log(metadata.userId);
+ * }
+ * ```
+ */
+export declare function getCurrentContext(): ContextMetadata | undefined;
+/**
+ * Merge current context with additional metadata
+ * Returns combined metadata for use in API calls
+ *
+ * @example
+ * ```typescript
+ * const params = {
+ *   name: 'My Trace',
+ *   metadata: mergeWithContext({ custom: 'value' })
+ * };
+ * ```
+ */
+export declare function mergeWithContext(metadata?: Record<string, any>): Record<string, any>;
+/**
+ * Run with nested context (merges parent context)
+ *
+ * @example
+ * ```typescript
+ * await withContext({ userId: '123' }, async () => {
+ *   await withContext({ requestId: 'req-456' }, async () => {
+ *     // Has both userId and requestId
+ *     const ctx = getCurrentContext();
+ *     console.log(ctx); // { userId: '123', requestId: 'req-456' }
+ *   });
+ * });
+ * ```
+ */
+export declare function withContext<T>(metadata: ContextMetadata, fn: () => Promise<T>): Promise<T>;
+/**
+ * Run with nested context (synchronous)
+ */
+export declare function withContextSync<T>(metadata: ContextMetadata, fn: () => T): T;
+/**
+ * Decorator for automatic context injection (for class methods)
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @WithContext({ service: 'MyService' })
+ *   async process() {
+ *     // Automatically has service context
+ *   }
+ * }
+ * ```
+ */
+export declare function WithContext(metadata: ContextMetadata): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/context.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Context Propagation System
+ * Tier 2.9: Automatic metadata injection
+ *
+ * NOTE: In Node.js, uses AsyncLocalStorage for true async context propagation.
+ * In browsers, uses a simpler stack-based approach (not safe across async boundaries).
+ *
+ * @example
+ * ```typescript
+ * import { createContext } from '@ai-eval-platform/sdk';
+ *
+ * const context = createContext({ userId: '123', sessionId: 'abc' });
+ *
+ * await context.run(async () => {
+ *   // All SDK calls inherit the context
+ *   await client.traces.create({ name: 'test' });
+ *   // ^ Automatically includes userId and sessionId
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvalContext = void 0;
+exports.createContext = createContext;
+exports.getCurrentContext = getCurrentContext;
+exports.mergeWithContext = mergeWithContext;
+exports.withContext = withContext;
+exports.withContextSync = withContextSync;
+exports.WithContext = WithContext;
+// Detect environment
+const isNode = typeof process !== 'undefined' &&
+    process.versions?.node &&
+    typeof require !== 'undefined';
+// Browser fallback: simple context stack
+class BrowserContextStorage {
+    constructor() {
+        this.stack = [];
+    }
+    run(context, fn) {
+        this.stack.push(context);
+        try {
+            return fn();
+        }
+        finally {
+            this.stack.pop();
+        }
+    }
+    getStore() {
+        return this.stack[this.stack.length - 1];
+    }
+}
+/**
+ * Context storage implementation
+ * Uses AsyncLocalStorage in Node.js, simple stack in browsers
+ */
+let contextStorage;
+if (isNode) {
+    try {
+        // Dynamic import for Node.js only
+        const { AsyncLocalStorage } = require('async_hooks');
+        // Create without type argument due to require() being untyped
+        contextStorage = new AsyncLocalStorage();
+    }
+    catch (error) {
+        // Fallback if async_hooks is not available
+        contextStorage = new BrowserContextStorage();
+    }
+}
+else {
+    // Use browser storage for non-Node environments
+    contextStorage = new BrowserContextStorage();
+}
+/**
+ * Context manager for automatic metadata propagation
+ */
+class EvalContext {
+    constructor(metadata) {
+        this.metadata = metadata;
+    }
+    /**
+     * Run a function with this context
+     *
+     * @example
+     * ```typescript
+     * const context = new EvalContext({ userId: '123' });
+     *
+     * await context.run(async () => {
+     *   // All operations inherit context
+     *   await client.traces.create({ name: 'test' });
+     * });
+     * ```
+     */
+    async run(fn) {
+        return contextStorage.run(this.metadata, fn);
+    }
+    /**
+     * Run a synchronous function with this context
+     */
+    runSync(fn) {
+        return contextStorage.run(this.metadata, fn);
+    }
+    /**
+     * Get the current context metadata
+     */
+    getMetadata() {
+        return { ...this.metadata };
+    }
+    /**
+     * Merge additional metadata into context
+     */
+    with(additionalMetadata) {
+        return new EvalContext({ ...this.metadata, ...additionalMetadata });
+    }
+}
+exports.EvalContext = EvalContext;
+/**
+ * Create a new context with metadata
+ *
+ * @example
+ * ```typescript
+ * const context = createContext({
+ *   userId: '123',
+ *   sessionId: 'abc',
+ *   environment: 'production'
+ * });
+ *
+ * await context.run(async () => {
+ *   // All SDK operations inherit context
+ * });
+ * ```
+ */
+function createContext(metadata) {
+    return new EvalContext(metadata);
+}
+/**
+ * Get the current context metadata (if any)
+ *
+ * @example
+ * ```typescript
+ * const metadata = getCurrentContext();
+ * if (metadata) {
+ *   console.log(metadata.userId);
+ * }
+ * ```
+ */
+function getCurrentContext() {
+    return contextStorage.getStore();
+}
+/**
+ * Merge current context with additional metadata
+ * Returns combined metadata for use in API calls
+ *
+ * @example
+ * ```typescript
+ * const params = {
+ *   name: 'My Trace',
+ *   metadata: mergeWithContext({ custom: 'value' })
+ * };
+ * ```
+ */
+function mergeWithContext(metadata) {
+    const current = getCurrentContext();
+    if (!current)
+        return metadata || {};
+    return { ...current, ...metadata };
+}
+/**
+ * Run with nested context (merges parent context)
+ *
+ * @example
+ * ```typescript
+ * await withContext({ userId: '123' }, async () => {
+ *   await withContext({ requestId: 'req-456' }, async () => {
+ *     // Has both userId and requestId
+ *     const ctx = getCurrentContext();
+ *     console.log(ctx); // { userId: '123', requestId: 'req-456' }
+ *   });
+ * });
+ * ```
+ */
+async function withContext(metadata, fn) {
+    const current = getCurrentContext() || {};
+    const merged = { ...current, ...metadata };
+    return contextStorage.run(merged, fn);
+}
+/**
+ * Run with nested context (synchronous)
+ */
+function withContextSync(metadata, fn) {
+    const current = getCurrentContext() || {};
+    const merged = { ...current, ...metadata };
+    return contextStorage.run(merged, fn);
+}
+/**
+ * Decorator for automatic context injection (for class methods)
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @WithContext({ service: 'MyService' })
+ *   async process() {
+ *     // Automatically has service context
+ *   }
+ * }
+ * ```
+ */
+function WithContext(metadata) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            return withContext(metadata, () => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Enhanced SDK Error system with documentation links
+ * Tier 1.5: Rich Error Messages
+ */
+export interface ErrorDocumentation {
+    code: string;
+    message: string;
+    documentation: string;
+    solutions: string[];
+    retryable: boolean;
+}
+/**
+ * Enhanced SDK Error class with rich error information and documentation
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.traces.create({ ... });
+ * } catch (error) {
+ *   if (error instanceof EvalAIError) {
+ *     console.log(error.code); // 'RATE_LIMIT_EXCEEDED'
+ *     console.log(error.documentation); // Link to docs
+ *     console.log(error.solutions); // Array of solutions
+ *     console.log(error.retryable); // true/false
+ *
+ *     if (error.retryAfter) {
+ *       console.log(`Retry after ${error.retryAfter} seconds`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class EvalAIError extends Error {
+    /** Error code for programmatic handling */
+    code: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Link to detailed documentation */
+    documentation: string;
+    /** Array of suggested solutions */
+    solutions: string[];
+    /** Whether this error is retryable */
+    retryable: boolean;
+    /** Additional error details from the API */
+    details?: any;
+    /** When to retry (for rate limit errors) in seconds */
+    retryAfter?: number;
+    /** When the limit resets (for feature limit errors) */
+    resetAt?: Date;
+    constructor(message: string, code: string, statusCode: number, details?: any);
+    /**
+     * Get formatted error message with solutions
+     */
+    getDetailedMessage(): string;
+    /**
+     * Check if this error should be retried
+     */
+    shouldRetry(): boolean;
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * Create an error from an HTTP response
+ */
+export declare function createErrorFromResponse(response: Response, data: any): EvalAIError;
+export declare class RateLimitError extends EvalAIError {
+    constructor(message: string, retryAfter?: number);
+}
+export declare class AuthenticationError extends EvalAIError {
+    constructor(message?: string);
+}
+export declare class ValidationError extends EvalAIError {
+    constructor(message?: string, details?: any);
+}
+export declare class NetworkError extends EvalAIError {
+    constructor(message?: string);
+}
+export { EvalAIError as SDKError };

package/dist/errors.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * Enhanced SDK Error system with documentation links
+ * Tier 1.5: Rich Error Messages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDKError = exports.NetworkError = exports.ValidationError = exports.AuthenticationError = exports.RateLimitError = exports.EvalAIError = void 0;
+exports.createErrorFromResponse = createErrorFromResponse;
+/**
+ * Comprehensive error documentation
+ */
+const ERROR_DOCS = {
+    MISSING_API_KEY: {
+        code: 'MISSING_API_KEY',
+        message: 'API key is required to initialize the SDK',
+        documentation: 'https://docs.ai-eval-platform.com/errors/missing-api-key',
+        solutions: [
+            'Set EVALAI_API_KEY environment variable',
+            'Pass apiKey in config: new AIEvalClient({ apiKey: "..." })',
+            'Get your API key from https://platform.ai-eval-platform.com/settings/api-keys'
+        ],
+        retryable: false
+    },
+    MISSING_ORGANIZATION_ID: {
+        code: 'MISSING_ORGANIZATION_ID',
+        message: 'Organization ID is required for this operation',
+        documentation: 'https://docs.ai-eval-platform.com/errors/missing-org-id',
+        solutions: [
+            'Set EVALAI_ORGANIZATION_ID environment variable',
+            'Pass organizationId in config: new AIEvalClient({ organizationId: 123 })',
+            'Pass organizationId in method params'
+        ],
+        retryable: false
+    },
+    RATE_LIMIT_EXCEEDED: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Rate limit exceeded',
+        documentation: 'https://docs.ai-eval-platform.com/errors/rate-limit',
+        solutions: [
+            'Wait before retrying (check retryAfter property)',
+            'Upgrade your plan for higher rate limits',
+            'Implement exponential backoff in your application'
+        ],
+        retryable: true
+    },
+    TIMEOUT: {
+        code: 'TIMEOUT',
+        message: 'Request timed out',
+        documentation: 'https://docs.ai-eval-platform.com/errors/timeout',
+        solutions: [
+            'Increase timeout: new AIEvalClient({ timeout: 60000 })',
+            'Check your network connection',
+            'The service may be experiencing high load'
+        ],
+        retryable: true
+    },
+    NETWORK_ERROR: {
+        code: 'NETWORK_ERROR',
+        message: 'Network connectivity issue',
+        documentation: 'https://docs.ai-eval-platform.com/errors/network',
+        solutions: [
+            'Check your internet connection',
+            'Verify the baseUrl is correct',
+            'Check if you can reach the API endpoint'
+        ],
+        retryable: true
+    },
+    UNAUTHORIZED: {
+        code: 'UNAUTHORIZED',
+        message: 'Authentication failed',
+        documentation: 'https://docs.ai-eval-platform.com/errors/unauthorized',
+        solutions: [
+            'Verify your API key is correct',
+            'Check if your API key has expired',
+            'Ensure your API key has the required permissions'
+        ],
+        retryable: false
+    },
+    FORBIDDEN: {
+        code: 'FORBIDDEN',
+        message: 'Access forbidden',
+        documentation: 'https://docs.ai-eval-platform.com/errors/forbidden',
+        solutions: [
+            'Check if you have permission for this resource',
+            'Verify you\'re using the correct organization ID',
+            'Contact support if you believe this is an error'
+        ],
+        retryable: false
+    },
+    NOT_FOUND: {
+        code: 'NOT_FOUND',
+        message: 'Resource not found',
+        documentation: 'https://docs.ai-eval-platform.com/errors/not-found',
+        solutions: [
+            'Verify the resource ID is correct',
+            'Check if the resource was deleted',
+            'Ensure you\'re querying the correct organization'
+        ],
+        retryable: false
+    },
+    VALIDATION_ERROR: {
+        code: 'VALIDATION_ERROR',
+        message: 'Request validation failed',
+        documentation: 'https://docs.ai-eval-platform.com/errors/validation',
+        solutions: [
+            'Check the error details for specific validation failures',
+            'Verify all required fields are provided',
+            'Ensure field types match the expected format'
+        ],
+        retryable: false
+    },
+    INTERNAL_SERVER_ERROR: {
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Internal server error',
+        documentation: 'https://docs.ai-eval-platform.com/errors/server-error',
+        solutions: [
+            'Retry the request after a brief delay',
+            'Check status page: https://status.ai-eval-platform.com',
+            'Contact support if the issue persists'
+        ],
+        retryable: true
+    },
+    FEATURE_LIMIT_REACHED: {
+        code: 'FEATURE_LIMIT_REACHED',
+        message: 'Feature usage limit reached',
+        documentation: 'https://docs.ai-eval-platform.com/errors/feature-limit',
+        solutions: [
+            'Upgrade your plan for higher limits',
+            'Wait for your usage to reset (check resetAt property)',
+            'Optimize your usage patterns'
+        ],
+        retryable: false
+    }
+};
+/**
+ * Enhanced SDK Error class with rich error information and documentation
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.traces.create({ ... });
+ * } catch (error) {
+ *   if (error instanceof EvalAIError) {
+ *     console.log(error.code); // 'RATE_LIMIT_EXCEEDED'
+ *     console.log(error.documentation); // Link to docs
+ *     console.log(error.solutions); // Array of solutions
+ *     console.log(error.retryable); // true/false
+ *
+ *     if (error.retryAfter) {
+ *       console.log(`Retry after ${error.retryAfter} seconds`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class EvalAIError extends Error {
+    constructor(message, code, statusCode, details) {
+        super(message);
+        this.name = 'EvalAIError';
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        // Get documentation and solutions
+        const errorDoc = ERROR_DOCS[code];
+        if (errorDoc) {
+            this.documentation = errorDoc.documentation;
+            this.solutions = errorDoc.solutions;
+            this.retryable = errorDoc.retryable;
+        }
+        else {
+            this.documentation = 'https://docs.ai-eval-platform.com/errors';
+            this.solutions = ['Check the API documentation for more information'];
+            this.retryable = false;
+        }
+        // Extract retry-after for rate limits
+        if (code === 'RATE_LIMIT_EXCEEDED' && details?.retryAfter) {
+            this.retryAfter = details.retryAfter;
+        }
+        // Extract reset time for feature limits
+        if (code === 'FEATURE_LIMIT_REACHED' && details?.resetAt) {
+            this.resetAt = new Date(details.resetAt);
+        }
+        // Ensure proper prototype chain
+        Object.setPrototypeOf(this, EvalAIError.prototype);
+    }
+    /**
+     * Get formatted error message with solutions
+     */
+    getDetailedMessage() {
+        let msg = `${this.code}: ${this.message}\n\n`;
+        msg += `Documentation: ${this.documentation}\n\n`;
+        msg += 'Suggested solutions:\n';
+        this.solutions.forEach((solution, i) => {
+            msg += `  ${i + 1}. ${solution}\n`;
+        });
+        if (this.retryAfter) {
+            msg += `\nRetry after: ${this.retryAfter} seconds`;
+        }
+        if (this.resetAt) {
+            msg += `\nLimit resets at: ${this.resetAt.toISOString()}`;
+        }
+        return msg;
+    }
+    /**
+     * Check if this error should be retried
+     */
+    shouldRetry() {
+        return this.retryable;
+    }
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            documentation: this.documentation,
+            solutions: this.solutions,
+            retryable: this.retryable,
+            retryAfter: this.retryAfter,
+            resetAt: this.resetAt,
+            details: this.details
+        };
+    }
+}
+exports.EvalAIError = EvalAIError;
+exports.SDKError = EvalAIError;
+/**
+ * Create an error from an HTTP response
+ */
+function createErrorFromResponse(response, data) {
+    const status = response.status;
+    let code = data?.code || 'UNKNOWN_ERROR';
+    let message = data?.error || data?.message || response.statusText;
+    // Map HTTP status to error codes
+    if (!data?.code) {
+        if (status === 401)
+            code = 'UNAUTHORIZED';
+        else if (status === 403)
+            code = 'FORBIDDEN';
+        else if (status === 404)
+            code = 'NOT_FOUND';
+        else if (status === 408)
+            code = 'TIMEOUT';
+        else if (status === 422)
+            code = 'VALIDATION_ERROR';
+        else if (status === 429)
+            code = 'RATE_LIMIT_EXCEEDED';
+        else if (status >= 500)
+            code = 'INTERNAL_SERVER_ERROR';
+    }
+    return new EvalAIError(message, code, status, data);
+}
+// Specific error types
+class RateLimitError extends EvalAIError {
+    constructor(message, retryAfter) {
+        super(message, 'RATE_LIMIT_EXCEEDED', 429, { retryAfter });
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+class AuthenticationError extends EvalAIError {
+    constructor(message = 'Authentication failed') {
+        super(message, 'AUTHENTICATION_ERROR', 401);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class ValidationError extends EvalAIError {
+    constructor(message = 'Validation failed', details) {
+        super(message, 'VALIDATION_ERROR', 400, details);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class NetworkError extends EvalAIError {
+    constructor(message = 'Network request failed') {
+        super(message, 'NETWORK_ERROR', 0);
+        this.name = 'NetworkError';
+        this.retryable = true;
+    }
+}
+exports.NetworkError = NetworkError;