@evalgate/sdk 2.0.0

package/dist/client.request.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.request.test.js

@@ -0,0 +1,232 @@
+"use strict";
+var __createBinding =
+	(this && this.__createBinding) ||
+	(Object.create
+		? function (o, m, k, k2) {
+				if (k2 === undefined) k2 = k;
+				var desc = Object.getOwnPropertyDescriptor(m, k);
+				if (
+					!desc ||
+					("get" in desc ? !m.__esModule : desc.writable || desc.configurable)
+				) {
+					desc = {
+						enumerable: true,
+						get: function () {
+							return m[k];
+						},
+					};
+				}
+				Object.defineProperty(o, k2, desc);
+			}
+		: function (o, m, k, k2) {
+				if (k2 === undefined) k2 = k;
+				o[k2] = m[k];
+			});
+var __setModuleDefault =
+	(this && this.__setModuleDefault) ||
+	(Object.create
+		? function (o, v) {
+				Object.defineProperty(o, "default", { enumerable: true, value: v });
+			}
+		: function (o, v) {
+				o["default"] = v;
+			});
+var __importStar =
+	(this && this.__importStar) ||
+	(function () {
+		var ownKeys = function (o) {
+			ownKeys =
+				Object.getOwnPropertyNames ||
+				function (o) {
+					var ar = [];
+					for (var k in o)
+						if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+					return ar;
+				};
+			return ownKeys(o);
+		};
+		return function (mod) {
+			if (mod && mod.__esModule) return mod;
+			var result = {};
+			if (mod != null)
+				for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+					if (k[i] !== "default") __createBinding(result, mod, k[i]);
+			__setModuleDefault(result, mod);
+			return result;
+		};
+	})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const client_1 = require("./client");
+const errorsModule = __importStar(require("./errors"));
+vitest_1.vi.mock("./cache", () => {
+	const cacheTracker = { invalidatedPatterns: [] };
+	const shouldCache = vitest_1.vi.fn().mockReturnValue(true);
+	const getTTL = vitest_1.vi.fn().mockReturnValue(1000);
+	const makeKey = (method, url, params) =>
+		`${method}:${url}:${JSON.stringify(params ?? null)}`;
+	return {
+		__esModule: true,
+		shouldCache,
+		getTTL,
+		cacheTracker,
+		RequestCache: class RequestCache {
+			constructor() {
+				this.store = new Map();
+			}
+			get(method, url, params) {
+				const key = makeKey(method, url, params);
+				return this.store.get(key) ?? null;
+			}
+			set(method, url, data, _ttl, params) {
+				const key = makeKey(method, url, params);
+				this.store.set(key, data);
+			}
+			invalidatePattern(pattern) {
+				cacheTracker.invalidatedPatterns.push(pattern);
+			}
+			invalidate(_method, _url, _params) {
+				// no-op for tests
+			}
+			clear() {
+				this.store.clear();
+			}
+		},
+	};
+});
+const cache_1 = require("./cache");
+(0, vitest_1.describe)("AIEvalClient.request", () => {
+	(0, vitest_1.beforeEach)(() => {
+		process.env.EVALAI_API_KEY = "test";
+		cache_1.shouldCache.mockReset().mockReturnValue(true);
+		cache_1.getTTL.mockReset().mockReturnValue(1000);
+		cache_1.cacheTracker.invalidatedPatterns.length = 0;
+	});
+	(0, vitest_1.it)(
+		"caches GET responses and reuses data without re-fetching",
+		async () => {
+			const client = new client_1.AIEvalClient({
+				apiKey: "test",
+				baseUrl: "http://localhost",
+				timeout: 1000,
+			});
+			const payload = { items: [1, 2, 3] };
+			const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+				ok: true,
+				status: 200,
+				json: async () => payload,
+			});
+			globalThis.fetch = fetchMock;
+			const first = await client.request("/api/traces", { method: "GET" });
+			const second = await client.request("/api/traces", { method: "GET" });
+			(0, vitest_1.expect)(first).toEqual(payload);
+			(0, vitest_1.expect)(second).toEqual(payload);
+			(0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(1);
+		},
+	);
+	(0, vitest_1.it)("propagates non-ok responses as SDK errors", async () => {
+		const client = new client_1.AIEvalClient({
+			apiKey: "test",
+			baseUrl: "http://localhost",
+		});
+		const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+			ok: false,
+			status: 429,
+			json: async () => ({ error: { code: "RATE_LIMIT_EXCEEDED" } }),
+		});
+		globalThis.fetch = fetchMock;
+		const createErrorSpy = vitest_1.vi
+			.spyOn(errorsModule, "createErrorFromResponse")
+			.mockReturnValue(
+				new errorsModule.EvalAIError(
+					"rate limited",
+					"RATE_LIMIT_EXCEEDED",
+					429,
+				),
+			);
+		await (0, vitest_1.expect)(
+			client.request("/api/fail", { method: "GET" }),
+		).rejects.toHaveProperty("code", "RATE_LIMIT_EXCEEDED");
+		createErrorSpy.mockRestore();
+	});
+	(0, vitest_1.it)(
+		"retries on retryable SDK errors and eventually succeeds",
+		async () => {
+			const client = new client_1.AIEvalClient({
+				apiKey: "test",
+				baseUrl: "http://localhost",
+				timeout: 1000,
+			});
+			vitest_1.vi.spyOn(client, "calculateBackoff").mockReturnValue(0);
+			const failureResponse = {
+				ok: false,
+				status: 429,
+				json: async () => ({ error: { code: "RATE_LIMIT_EXCEEDED" } }),
+			};
+			const successResponse = {
+				ok: true,
+				status: 200,
+				json: async () => ({ ok: true }),
+			};
+			const createErrorSpy = vitest_1.vi
+				.spyOn(errorsModule, "createErrorFromResponse")
+				.mockReturnValue(
+					new errorsModule.EvalAIError(
+						"rate limited",
+						"RATE_LIMIT_EXCEEDED",
+						429,
+					),
+				);
+			const fetchMock = vitest_1.vi
+				.fn()
+				.mockResolvedValueOnce(failureResponse)
+				.mockResolvedValueOnce(successResponse);
+			globalThis.fetch = fetchMock;
+			const result = await client.request("/api/retry", { method: "GET" });
+			(0, vitest_1.expect)(result).toEqual({ ok: true });
+			(0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(2);
+			createErrorSpy.mockRestore();
+		},
+	);
+	(0, vitest_1.it)("throws a TIMEOUT SDK error when fetch aborts", async () => {
+		const client = new client_1.AIEvalClient({
+			apiKey: "test",
+			baseUrl: "http://localhost",
+			timeout: 1000,
+		});
+		const abortError = Object.assign(new Error("aborted"), {
+			name: "AbortError",
+		});
+		const fetchMock = vitest_1.vi.fn().mockRejectedValue(abortError);
+		globalThis.fetch = fetchMock;
+		await (0, vitest_1.expect)(
+			client.request("/api/timeout", { method: "GET" }),
+		).rejects.toMatchObject({
+			code: "TIMEOUT",
+		});
+	});
+	(0, vitest_1.it)(
+		"invalidates related cache entries for mutation requests",
+		async () => {
+			const client = new client_1.AIEvalClient({
+				apiKey: "test",
+				baseUrl: "http://localhost",
+				timeout: 1000,
+			});
+			cache_1.shouldCache.mockReturnValue(false);
+			const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+				ok: true,
+				status: 201,
+				json: async () => ({ result: "ok" }),
+			});
+			globalThis.fetch = fetchMock;
+			await client.request("/api/evaluations", {
+				method: "POST",
+				body: JSON.stringify({}),
+			});
+			(0, vitest_1.expect)(cache_1.cacheTracker.invalidatedPatterns).toContain(
+				"evaluations",
+			);
+		},
+	);
+});

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]: unknown;
+}
+/**
+ * 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 unknown)
+ *
+ * @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, unknown>): Record<string, unknown>;
+/**
+ * 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: unknown, _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("node: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 unknown)
+ *
+ * @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 (_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,82 @@
+/**
+ * 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 EvalGateError) {
+ *     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 EvalGateError 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?: unknown;
+    /** When to retry (for rate limit errors) in seconds */
+    retryAfter?: number;
+    /** When the limit resets (for feature limit errors) */
+    resetAt?: Date;
+    /** Request ID from API (for correlation/debugging) */
+    requestId?: string;
+    constructor(message: string, code: string, statusCode: number, details?: unknown);
+    /**
+     * 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, unknown>;
+}
+/**
+ * Create an error from an HTTP response
+ */
+export declare function createErrorFromResponse(response: Response, data: unknown): EvalGateError;
+export declare class RateLimitError extends EvalGateError {
+    constructor(message: string, retryAfter?: number);
+}
+export declare class AuthenticationError extends EvalGateError {
+    constructor(message?: string);
+}
+export declare class ValidationError extends EvalGateError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class NetworkError extends EvalGateError {
+    constructor(message?: string);
+}
+export { EvalGateError as SDKError };