@pauly4010/evalai-sdk 1.3.0

package/dist/logger.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Debug Mode with Request Logging
+ * Tier 4.17: Troubleshooting utilities
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@ai-eval-platform/sdk';
+ *
+ * const logger = createLogger({ level: 'debug', pretty: true });
+ *
+ * logger.debug('Trace created', { traceId: '123' });
+ * logger.error('Request failed', { error: err });
+ * ```
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+export interface LoggerOptions {
+    /** Log level (default: 'info') */
+    level?: LogLevel;
+    /** Pretty print logs (default: false) */
+    pretty?: boolean;
+    /** Include timestamps (default: true) */
+    timestamps?: boolean;
+    /** Custom log handler */
+    handler?: (entry: LogEntry) => void;
+    /** Prefix for all logs */
+    prefix?: string;
+}
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    data?: any;
+    prefix?: string;
+}
+/**
+ * Logger for SDK debugging and troubleshooting
+ */
+export declare class Logger {
+    private options;
+    constructor(options?: LoggerOptions);
+    /**
+     * Log a trace message
+     */
+    trace(message: string, data?: any): void;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, data?: any): void;
+    /**
+     * Log HTTP request
+     */
+    logRequest(method: string, url: string, data?: any): void;
+    /**
+     * Log HTTP response
+     */
+    logResponse(method: string, url: string, status: number, duration: number, data?: any): void;
+    /**
+     * Create child logger with prefix
+     */
+    child(prefix: string): Logger;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Check if level is enabled
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    private log;
+    private defaultHandler;
+}
+/**
+ * Create a logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ level: 'debug', pretty: true });
+ * logger.debug('Starting evaluation');
+ * ```
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * Get global logger (creates one if it doesn't exist)
+ */
+export declare function getLogger(): Logger;
+/**
+ * Set global logger
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * Request/Response interceptor for logging
+ */
+export declare class RequestLogger {
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Log request before sending
+     */
+    logRequest(request: {
+        method: string;
+        url: string;
+        headers?: Record<string, string>;
+        body?: any;
+    }): void;
+    /**
+     * Log response after receiving
+     */
+    logResponse(response: {
+        method: string;
+        url: string;
+        status: number;
+        duration: number;
+        headers?: Record<string, string>;
+        body?: any;
+    }): void;
+}

package/dist/logger.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Debug Mode with Request Logging
+ * Tier 4.17: Troubleshooting utilities
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@ai-eval-platform/sdk';
+ *
+ * const logger = createLogger({ level: 'debug', pretty: true });
+ *
+ * logger.debug('Trace created', { traceId: '123' });
+ * logger.error('Request failed', { error: err });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestLogger = exports.Logger = void 0;
+exports.createLogger = createLogger;
+exports.getLogger = getLogger;
+exports.setLogger = setLogger;
+const LOG_LEVELS = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4
+};
+const LOG_COLORS = {
+    trace: '\x1b[90m', // gray
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m' // red
+};
+const COLOR_RESET = '\x1b[0m';
+/**
+ * Logger for SDK debugging and troubleshooting
+ */
+class Logger {
+    constructor(options = {}) {
+        this.options = {
+            level: options.level || 'info',
+            pretty: options.pretty ?? false,
+            timestamps: options.timestamps ?? true,
+            handler: options.handler || this.defaultHandler.bind(this),
+            prefix: options.prefix || 'EvalAI'
+        };
+    }
+    /**
+     * Log a trace message
+     */
+    trace(message, data) {
+        this.log('trace', message, data);
+    }
+    /**
+     * Log a debug message
+     */
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    /**
+     * Log an info message
+     */
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    /**
+     * Log a warning message
+     */
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    /**
+     * Log an error message
+     */
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    /**
+     * Log HTTP request
+     */
+    logRequest(method, url, data) {
+        this.debug(`→ ${method} ${url}`, data);
+    }
+    /**
+     * Log HTTP response
+     */
+    logResponse(method, url, status, duration, data) {
+        const level = status >= 400 ? 'error' : status >= 300 ? 'warn' : 'debug';
+        this.log(level, `← ${method} ${url} ${status} (${duration}ms)`, data);
+    }
+    /**
+     * Create child logger with prefix
+     */
+    child(prefix) {
+        return new Logger({
+            ...this.options,
+            prefix: `${this.options.prefix}:${prefix}`
+        });
+    }
+    /**
+     * Set log level
+     */
+    setLevel(level) {
+        this.options.level = level;
+    }
+    /**
+     * Check if level is enabled
+     */
+    isLevelEnabled(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.options.level];
+    }
+    log(level, message, data) {
+        if (!this.isLevelEnabled(level))
+            return;
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            data,
+            prefix: this.options.prefix
+        };
+        this.options.handler(entry);
+    }
+    defaultHandler(entry) {
+        const parts = [];
+        // Timestamp
+        if (this.options.timestamps) {
+            const time = this.options.pretty
+                ? new Date(entry.timestamp).toLocaleTimeString()
+                : entry.timestamp;
+            parts.push(this.options.pretty ? `\x1b[90m${time}${COLOR_RESET}` : time);
+        }
+        // Level
+        const levelStr = entry.level.toUpperCase().padEnd(5);
+        parts.push(this.options.pretty
+            ? `${LOG_COLORS[entry.level]}${levelStr}${COLOR_RESET}`
+            : levelStr);
+        // Prefix
+        if (entry.prefix) {
+            parts.push(this.options.pretty
+                ? `\x1b[35m[${entry.prefix}]${COLOR_RESET}`
+                : `[${entry.prefix}]`);
+        }
+        // Message
+        parts.push(entry.message);
+        // Log
+        const logLine = parts.join(' ');
+        if (entry.level === 'error') {
+            console.error(logLine);
+        }
+        else if (entry.level === 'warn') {
+            console.warn(logLine);
+        }
+        else {
+            console.log(logLine);
+        }
+        // Data
+        if (entry.data !== undefined) {
+            if (this.options.pretty) {
+                console.log(JSON.stringify(entry.data, null, 2));
+            }
+            else {
+                console.log(JSON.stringify(entry.data));
+            }
+        }
+    }
+}
+exports.Logger = Logger;
+/**
+ * Create a logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ level: 'debug', pretty: true });
+ * logger.debug('Starting evaluation');
+ * ```
+ */
+function createLogger(options) {
+    return new Logger(options);
+}
+/**
+ * Global logger instance
+ */
+let globalLogger;
+/**
+ * Get global logger (creates one if it doesn't exist)
+ */
+function getLogger() {
+    if (!globalLogger) {
+        globalLogger = new Logger();
+    }
+    return globalLogger;
+}
+/**
+ * Set global logger
+ */
+function setLogger(logger) {
+    globalLogger = logger;
+}
+/**
+ * Request/Response interceptor for logging
+ */
+class RequestLogger {
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Log request before sending
+     */
+    logRequest(request) {
+        this.logger.logRequest(request.method, request.url, {
+            headers: request.headers,
+            body: request.body
+        });
+    }
+    /**
+     * Log response after receiving
+     */
+    logResponse(response) {
+        this.logger.logResponse(response.method, response.url, response.status, response.duration, {
+            headers: response.headers,
+            body: response.body
+        });
+    }
+}
+exports.RequestLogger = RequestLogger;

package/dist/pagination.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Cursor-based pagination utilities for efficient data fetching
+ */
+export interface PaginationParams {
+    limit?: number;
+    cursor?: string;
+    offset?: number;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        hasMore: boolean;
+        nextCursor?: string;
+        prevCursor?: string;
+        total?: number;
+        limit: number;
+        offset?: number;
+    };
+}
+export interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Iterator for paginated results
+ * Allows for easy iteration over all pages
+ */
+export declare class PaginatedIterator<T> implements AsyncIterableIterator<T[]> {
+    private fetchFn;
+    private limit;
+    private currentOffset;
+    private hasMore;
+    constructor(fetchFn: (offset: number, limit: number) => Promise<{
+        data: T[];
+        hasMore: boolean;
+    }>, limit?: number);
+    next(): Promise<IteratorResult<T[]>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T[]>;
+    /**
+     * Collect all pages into a single array
+     * Warning: Use with caution on large datasets
+     */
+    toArray(): Promise<T[]>;
+}
+/**
+ * Helper to create paginated iterator
+ */
+export declare function createPaginatedIterator<T>(fetchFn: (offset: number, limit: number) => Promise<{
+    data: T[];
+    hasMore: boolean;
+}>, limit?: number): PaginatedIterator<T>;
+/**
+ * Auto-paginate helper that fetches all pages automatically
+ */
+export declare function autoPaginate<T>(fetchFn: (offset: number, limit: number) => Promise<T[]>, limit?: number): AsyncGenerator<T, void, unknown>;
+/**
+ * Encode cursor for pagination (base64)
+ */
+export declare function encodeCursor(data: any): string;
+/**
+ * Decode cursor from base64
+ */
+export declare function decodeCursor(cursor: string): any;
+/**
+ * Create pagination metadata from response
+ */
+export declare function createPaginationMeta<T>(items: T[], limit: number, offset: number, total?: number): PaginatedResponse<T>['pagination'];
+/**
+ * Parse pagination params from cursor or offset
+ */
+export declare function parsePaginationParams(params: PaginationParams): {
+    limit: number;
+    offset: number;
+};

package/dist/pagination.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Cursor-based pagination utilities for efficient data fetching
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginatedIterator = void 0;
+exports.createPaginatedIterator = createPaginatedIterator;
+exports.autoPaginate = autoPaginate;
+exports.encodeCursor = encodeCursor;
+exports.decodeCursor = decodeCursor;
+exports.createPaginationMeta = createPaginationMeta;
+exports.parsePaginationParams = parsePaginationParams;
+/**
+ * Iterator for paginated results
+ * Allows for easy iteration over all pages
+ */
+class PaginatedIterator {
+    constructor(fetchFn, limit = 50) {
+        this.fetchFn = fetchFn;
+        this.limit = limit;
+        this.currentOffset = 0;
+        this.hasMore = true;
+    }
+    async next() {
+        if (!this.hasMore) {
+            return { done: true, value: undefined };
+        }
+        const result = await this.fetchFn(this.currentOffset, this.limit);
+        this.hasMore = result.hasMore;
+        this.currentOffset += this.limit;
+        return {
+            done: false,
+            value: result.data,
+        };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /**
+     * Collect all pages into a single array
+     * Warning: Use with caution on large datasets
+     */
+    async toArray() {
+        const allItems = [];
+        for await (const page of this) {
+            allItems.push(...page);
+        }
+        return allItems;
+    }
+}
+exports.PaginatedIterator = PaginatedIterator;
+/**
+ * Helper to create paginated iterator
+ */
+function createPaginatedIterator(fetchFn, limit = 50) {
+    return new PaginatedIterator(fetchFn, limit);
+}
+/**
+ * Auto-paginate helper that fetches all pages automatically
+ */
+async function* autoPaginate(fetchFn, limit = 50) {
+    let offset = 0;
+    let hasMore = true;
+    while (hasMore) {
+        const items = await fetchFn(offset, limit);
+        if (items.length === 0) {
+            break;
+        }
+        for (const item of items) {
+            yield item;
+        }
+        hasMore = items.length === limit;
+        offset += limit;
+    }
+}
+/**
+ * Encode cursor for pagination (base64)
+ */
+function encodeCursor(data) {
+    const json = JSON.stringify(data);
+    if (typeof globalThis !== 'undefined' && 'btoa' in globalThis) {
+        return globalThis.btoa(json);
+    }
+    else {
+        return Buffer.from(json).toString('base64');
+    }
+}
+/**
+ * Decode cursor from base64
+ */
+function decodeCursor(cursor) {
+    try {
+        let json;
+        if (typeof globalThis !== 'undefined' && 'atob' in globalThis) {
+            json = globalThis.atob(cursor);
+        }
+        else {
+            json = Buffer.from(cursor, 'base64').toString('utf-8');
+        }
+        return JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error('Invalid cursor format');
+    }
+}
+/**
+ * Create pagination metadata from response
+ */
+function createPaginationMeta(items, limit, offset, total) {
+    const hasMore = items.length === limit;
+    return {
+        hasMore,
+        limit,
+        offset,
+        total,
+        nextCursor: hasMore ? encodeCursor({ offset: offset + limit, limit }) : undefined,
+        prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit), limit }) : undefined,
+    };
+}
+/**
+ * Parse pagination params from cursor or offset
+ */
+function parsePaginationParams(params) {
+    if (params.cursor) {
+        const decoded = decodeCursor(params.cursor);
+        return {
+            limit: decoded.limit || 50,
+            offset: decoded.offset || 0,
+        };
+    }
+    return {
+        limit: params.limit || 50,
+        offset: params.offset || 0,
+    };
+}