@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/internal/error-handler/errorHandler.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Main ErrorHandler implementation with logging and telemetry integration.
+ * Provides error classification, formatting, and consistent error handling patterns.
+ * @module src/utils/internal/error-handler/errorHandler
+ */
+import { JsonRpcErrorCode } from '../../../types-global/errors.js';
+import type { ErrorHandlerOptions, ErrorMapping } from './types.js';
+/**
+ * A utility class providing static methods for comprehensive error handling.
+ */
+export declare class ErrorHandler {
+    /**
+     * Determines an appropriate `JsonRpcErrorCode` for a given error.
+     *
+     * Resolution order:
+     * 1. `McpError` instances — returns `error.code` directly.
+     * 2. Standard JS error constructor names via `ERROR_TYPE_MAPPINGS` (e.g. `TypeError` → `ValidationError`).
+     * 3. Provider-specific patterns (AWS, HTTP status codes, Supabase, OpenRouter) — checked before common patterns for specificity.
+     * 4. Common message/name patterns (auth, not-found, rate-limit, etc.).
+     * 5. `AbortError` name — mapped to `Timeout`.
+     * 6. Falls back to `JsonRpcErrorCode.InternalError`.
+     *
+     * @param error - The error instance or value to classify.
+     * @returns The most specific `JsonRpcErrorCode` that fits the error.
+     *
+     * @example
+     * ```ts
+     * ErrorHandler.determineErrorCode(new McpError(JsonRpcErrorCode.NotFound, 'missing'));
+     * // → JsonRpcErrorCode.NotFound
+     *
+     * ErrorHandler.determineErrorCode(new TypeError('bad input'));
+     * // → JsonRpcErrorCode.ValidationError
+     *
+     * ErrorHandler.determineErrorCode(new Error('status code 429'));
+     * // → JsonRpcErrorCode.RateLimited
+     * ```
+     */
+    static determineErrorCode(error: unknown): JsonRpcErrorCode;
+    /**
+     * Handles an error with consistent logging, OpenTelemetry integration, and optional transformation.
+     *
+     * Steps performed:
+     * 1. Records the exception on the active OTel span and sets span status to ERROR.
+     * 2. Sanitizes `options.input` via `sanitizeInputForLogging` before including in logs.
+     * 3. Extracts and consolidates error data, original stack, and the full cause chain.
+     * 4. Wraps non-`McpError` errors in a new `McpError` (or delegates to `options.errorMapper`).
+     * 5. Logs the result at `error` level via the global logger with full structured context.
+     * 6. Returns the processed error, or rethrows it if `options.rethrow` is `true`.
+     *
+     * @param error - The error instance or value that occurred.
+     * @param options - Configuration controlling transformation, logging, and rethrow behavior.
+     * @returns The processed `Error` instance (a `McpError` unless `errorMapper` returns something else).
+     *
+     * @example
+     * ```ts
+     * // Log and return without rethrowing
+     * const handled = ErrorHandler.handleError(err, { operation: 'fetchUser', context: { requestId } });
+     *
+     * // Log and rethrow
+     * ErrorHandler.handleError(err, { operation: 'fetchUser', rethrow: true });
+     *
+     * // Custom error transformation
+     * ErrorHandler.handleError(err, {
+     *   operation: 'fetchUser',
+     *   errorMapper: (e) => new MyDomainError(getErrorMessage(e)),
+     * });
+     * ```
+     */
+    static handleError(error: unknown, options: ErrorHandlerOptions): Error;
+    /**
+     * Maps an error to a specific error type `T` by testing it against an ordered list of `ErrorMapping` rules.
+     *
+     * Each mapping's `pattern` is tested (case-insensitively) against both the error message and error name.
+     * The first matching rule's `factory` is called with the original error and the mapping's `additionalContext`.
+     * If no rule matches and `defaultFactory` is provided, it is called instead.
+     * If neither matches, returns the original `Error` or wraps non-Error values in a plain `Error`.
+     *
+     * @template T The target error type, extending `Error`.
+     * @param error - The error instance or value to map.
+     * @param mappings - An ordered array of mapping rules; first match wins.
+     * @param defaultFactory - Optional factory invoked when no mapping rule matches.
+     * @returns The mapped error of type `T`, or the original/wrapped error if no rule matched.
+     *
+     * @example
+     * ```ts
+     * const mapped = ErrorHandler.mapError(err, [
+     *   {
+     *     pattern: /not found/i,
+     *     errorCode: JsonRpcErrorCode.NotFound,
+     *     factory: (e) => new McpError(JsonRpcErrorCode.NotFound, getErrorMessage(e)),
+     *   },
+     * ]);
+     * ```
+     */
+    static mapError<T extends Error>(error: unknown, mappings: ReadonlyArray<ErrorMapping<T>>, defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
+    /**
+     * Formats an error into a consistent `{ code, message, data }` structure for API responses or structured logging.
+     *
+     * - `McpError` → `{ code: error.code, message: error.message, data: error.data ?? {} }`
+     * - `Error` → `{ code: determineErrorCode(error), message: error.message, data: { errorType: error.name } }`
+     * - Other values → `{ code: JsonRpcErrorCode.UnknownError, message: getErrorMessage(value), data: { errorType: getErrorName(value) } }`
+     *
+     * @param error - The error instance or value to format.
+     * @returns A plain object with `code` (numeric `JsonRpcErrorCode`), `message` (string), and `data` (object).
+     *
+     * @example
+     * ```ts
+     * const formatted = ErrorHandler.formatError(new McpError(JsonRpcErrorCode.NotFound, 'Item missing'));
+     * // → { code: -32001, message: 'Item missing', data: {} }
+     *
+     * const formatted2 = ErrorHandler.formatError(new TypeError('bad arg'));
+     * // → { code: -32007, message: 'bad arg', data: { errorType: 'TypeError' } }
+     * ```
+     */
+    static formatError(error: unknown): Record<string, unknown>;
+    /**
+     * Safely executes a synchronous or asynchronous function, logging and rethrowing any error.
+     *
+     * Equivalent to wrapping `fn` in a try/catch that calls `ErrorHandler.handleError` with `rethrow: true`.
+     * The processed `McpError` (or custom-mapped error) is always thrown — this method never swallows errors.
+     * Use this in service code where you want structured logging and OTel integration without duplicating
+     * error-handling boilerplate.
+     *
+     * @template T The expected return type of `fn`.
+     * @param fn - The function to execute. May be synchronous or return a `Promise`.
+     * @param options - Error handling options passed to `handleError` (`rethrow` is always `true` and cannot be overridden).
+     * @returns A promise that resolves with the return value of `fn` on success.
+     * @throws {McpError | Error} The processed error from `ErrorHandler.handleError` on failure.
+     *
+     * @example
+     * ```ts
+     * const user = await ErrorHandler.tryCatch(
+     *   () => db.findUser(id),
+     *   { operation: 'findUser', context: { requestId, userId: id } },
+     * );
+     * ```
+     */
+    static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, 'rethrow'>): Promise<T>;
+}
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/utils/internal/error-handler/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/errorHandler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAYtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpE;;GAEG;AAEH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACW,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAuClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;WACW,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,KAAK;IAmI9E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACW,QAAQ,CAAC,CAAC,SAAS,KAAK,EACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EACxC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GACxE,CAAC,GAAG,KAAK;IAkBZ;;;;;;;;;;;;;;;;;;OAkBG;WACW,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBlE;;;;;;;;;;;;;;;;;;;;;OAqBG;WACiB,QAAQ,CAAC,CAAC,EAC5B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC;CAWd"}

package/dist/utils/internal/error-handler/errorHandler.js

@@ -0,0 +1,318 @@
+/**
+ * @fileoverview Main ErrorHandler implementation with logging and telemetry integration.
+ * Provides error classification, formatting, and consistent error handling patterns.
+ * @module src/utils/internal/error-handler/errorHandler
+ */
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { generateUUID } from '../../../utils/security/idGenerator.js';
+import { sanitizeInputForLogging } from '../../../utils/security/sanitization.js';
+import { extractErrorCauseChain, getErrorMessage, getErrorName } from './helpers.js';
+import { COMPILED_ERROR_PATTERNS, COMPILED_PROVIDER_PATTERNS, ERROR_TYPE_MAPPINGS, getCompiledPattern, } from './mappings.js';
+/**
+ * A utility class providing static methods for comprehensive error handling.
+ */
+// biome-ignore lint/complexity/noStaticOnlyClass: public API surface — preserving class for namespace semantics
+export class ErrorHandler {
+    /**
+     * Determines an appropriate `JsonRpcErrorCode` for a given error.
+     *
+     * Resolution order:
+     * 1. `McpError` instances — returns `error.code` directly.
+     * 2. Standard JS error constructor names via `ERROR_TYPE_MAPPINGS` (e.g. `TypeError` → `ValidationError`).
+     * 3. Provider-specific patterns (AWS, HTTP status codes, Supabase, OpenRouter) — checked before common patterns for specificity.
+     * 4. Common message/name patterns (auth, not-found, rate-limit, etc.).
+     * 5. `AbortError` name — mapped to `Timeout`.
+     * 6. Falls back to `JsonRpcErrorCode.InternalError`.
+     *
+     * @param error - The error instance or value to classify.
+     * @returns The most specific `JsonRpcErrorCode` that fits the error.
+     *
+     * @example
+     * ```ts
+     * ErrorHandler.determineErrorCode(new McpError(JsonRpcErrorCode.NotFound, 'missing'));
+     * // → JsonRpcErrorCode.NotFound
+     *
+     * ErrorHandler.determineErrorCode(new TypeError('bad input'));
+     * // → JsonRpcErrorCode.ValidationError
+     *
+     * ErrorHandler.determineErrorCode(new Error('status code 429'));
+     * // → JsonRpcErrorCode.RateLimited
+     * ```
+     */
+    static determineErrorCode(error) {
+        if (error instanceof McpError) {
+            return error.code;
+        }
+        const errorName = getErrorName(error);
+        const errorMessage = getErrorMessage(error);
+        // Check against standard JavaScript error types
+        const mappedFromType = ERROR_TYPE_MAPPINGS[errorName];
+        if (mappedFromType) {
+            return mappedFromType;
+        }
+        // Check provider-specific patterns first (more specific)
+        for (const mapping of COMPILED_PROVIDER_PATTERNS) {
+            if (mapping.compiledPattern.test(errorMessage) || mapping.compiledPattern.test(errorName)) {
+                return mapping.errorCode;
+            }
+        }
+        // Then check common error patterns (using pre-compiled patterns for performance)
+        for (const mapping of COMPILED_ERROR_PATTERNS) {
+            if (mapping.compiledPattern.test(errorMessage) || mapping.compiledPattern.test(errorName)) {
+                return mapping.errorCode;
+            }
+        }
+        // Special-case common platform errors
+        if (typeof error === 'object' &&
+            error !== null &&
+            'name' in error &&
+            error.name === 'AbortError') {
+            return JsonRpcErrorCode.Timeout;
+        }
+        return JsonRpcErrorCode.InternalError;
+    }
+    /**
+     * Handles an error with consistent logging, OpenTelemetry integration, and optional transformation.
+     *
+     * Steps performed:
+     * 1. Records the exception on the active OTel span and sets span status to ERROR.
+     * 2. Sanitizes `options.input` via `sanitizeInputForLogging` before including in logs.
+     * 3. Extracts and consolidates error data, original stack, and the full cause chain.
+     * 4. Wraps non-`McpError` errors in a new `McpError` (or delegates to `options.errorMapper`).
+     * 5. Logs the result at `error` level via the global logger with full structured context.
+     * 6. Returns the processed error, or rethrows it if `options.rethrow` is `true`.
+     *
+     * @param error - The error instance or value that occurred.
+     * @param options - Configuration controlling transformation, logging, and rethrow behavior.
+     * @returns The processed `Error` instance (a `McpError` unless `errorMapper` returns something else).
+     *
+     * @example
+     * ```ts
+     * // Log and return without rethrowing
+     * const handled = ErrorHandler.handleError(err, { operation: 'fetchUser', context: { requestId } });
+     *
+     * // Log and rethrow
+     * ErrorHandler.handleError(err, { operation: 'fetchUser', rethrow: true });
+     *
+     * // Custom error transformation
+     * ErrorHandler.handleError(err, {
+     *   operation: 'fetchUser',
+     *   errorMapper: (e) => new MyDomainError(getErrorMessage(e)),
+     * });
+     * ```
+     */
+    static handleError(error, options) {
+        // --- OpenTelemetry Integration ---
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+            if (error instanceof Error) {
+                activeSpan.recordException(error);
+            }
+            activeSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // --- End OpenTelemetry Integration ---
+        const { context = {}, operation, input, rethrow = false, errorCode: explicitErrorCode, includeStack = true, critical = false, errorMapper, } = options;
+        const sanitizedInput = input !== undefined ? sanitizeInputForLogging(input) : undefined;
+        const originalErrorName = getErrorName(error);
+        const originalErrorMessage = getErrorMessage(error);
+        const originalStack = error instanceof Error ? error.stack : undefined;
+        let finalError;
+        let loggedErrorCode;
+        const errorDataSeed = error instanceof McpError && typeof error.data === 'object' && error.data !== null
+            ? { ...error.data }
+            : {};
+        const consolidatedData = {
+            ...errorDataSeed,
+            ...context,
+            originalErrorName,
+            originalMessage: originalErrorMessage,
+        };
+        if (originalStack && !(error instanceof McpError && error.data?.originalStack)) {
+            consolidatedData.originalStack = originalStack;
+        }
+        const cause = error instanceof Error ? error : undefined;
+        // Extract cause chain only when the error actually has a cause
+        if (error instanceof Error && error.cause) {
+            const causeChain = extractErrorCauseChain(error);
+            if (causeChain.length > 0) {
+                const rootCause = causeChain[causeChain.length - 1];
+                if (rootCause) {
+                    consolidatedData.rootCause = {
+                        name: rootCause.name,
+                        message: rootCause.message,
+                    };
+                }
+                consolidatedData.causeChain = causeChain;
+            }
+        }
+        if (error instanceof McpError) {
+            loggedErrorCode = error.code;
+            finalError = errorMapper
+                ? errorMapper(error)
+                : new McpError(error.code, error.message, consolidatedData, {
+                    cause,
+                });
+        }
+        else {
+            loggedErrorCode = explicitErrorCode || ErrorHandler.determineErrorCode(error);
+            const message = `Error in ${operation}: ${originalErrorMessage}`;
+            finalError = errorMapper
+                ? errorMapper(error)
+                : new McpError(loggedErrorCode, message, consolidatedData, {
+                    cause,
+                });
+        }
+        if (finalError !== error &&
+            error instanceof Error &&
+            finalError instanceof Error &&
+            !finalError.stack &&
+            error.stack) {
+            finalError.stack = error.stack;
+        }
+        const logRequestId = typeof context.requestId === 'string' && context.requestId
+            ? context.requestId
+            : generateUUID();
+        const logTimestamp = typeof context.timestamp === 'string' && context.timestamp
+            ? context.timestamp
+            : new Date().toISOString();
+        const stack = finalError instanceof Error ? finalError.stack : originalStack;
+        const logContext = {
+            requestId: logRequestId,
+            timestamp: logTimestamp,
+            operation,
+            input: sanitizedInput,
+            critical,
+            errorCode: loggedErrorCode,
+            originalErrorType: originalErrorName,
+            finalErrorType: getErrorName(finalError),
+            ...Object.fromEntries(Object.entries(context).filter(([key]) => key !== 'requestId' && key !== 'timestamp')),
+            errorData: finalError instanceof McpError && finalError.data ? finalError.data : consolidatedData,
+            ...(includeStack && stack ? { stack } : {}),
+        };
+        logger.error(`Error in ${operation}: ${finalError.message || originalErrorMessage}`, logContext);
+        if (rethrow) {
+            throw finalError;
+        }
+        return finalError;
+    }
+    /**
+     * Maps an error to a specific error type `T` by testing it against an ordered list of `ErrorMapping` rules.
+     *
+     * Each mapping's `pattern` is tested (case-insensitively) against both the error message and error name.
+     * The first matching rule's `factory` is called with the original error and the mapping's `additionalContext`.
+     * If no rule matches and `defaultFactory` is provided, it is called instead.
+     * If neither matches, returns the original `Error` or wraps non-Error values in a plain `Error`.
+     *
+     * @template T The target error type, extending `Error`.
+     * @param error - The error instance or value to map.
+     * @param mappings - An ordered array of mapping rules; first match wins.
+     * @param defaultFactory - Optional factory invoked when no mapping rule matches.
+     * @returns The mapped error of type `T`, or the original/wrapped error if no rule matched.
+     *
+     * @example
+     * ```ts
+     * const mapped = ErrorHandler.mapError(err, [
+     *   {
+     *     pattern: /not found/i,
+     *     errorCode: JsonRpcErrorCode.NotFound,
+     *     factory: (e) => new McpError(JsonRpcErrorCode.NotFound, getErrorMessage(e)),
+     *   },
+     * ]);
+     * ```
+     */
+    static mapError(error, mappings, defaultFactory) {
+        const errorMessage = getErrorMessage(error);
+        const errorName = getErrorName(error);
+        for (const mapping of mappings) {
+            const regex = getCompiledPattern(mapping.pattern);
+            if (regex.test(errorMessage) || regex.test(errorName)) {
+                // c8 ignore next
+                return mapping.factory(error, mapping.additionalContext);
+            }
+        }
+        if (defaultFactory) {
+            return defaultFactory(error);
+        }
+        return error instanceof Error ? error : new Error(String(error));
+    }
+    /**
+     * Formats an error into a consistent `{ code, message, data }` structure for API responses or structured logging.
+     *
+     * - `McpError` → `{ code: error.code, message: error.message, data: error.data ?? {} }`
+     * - `Error` → `{ code: determineErrorCode(error), message: error.message, data: { errorType: error.name } }`
+     * - Other values → `{ code: JsonRpcErrorCode.UnknownError, message: getErrorMessage(value), data: { errorType: getErrorName(value) } }`
+     *
+     * @param error - The error instance or value to format.
+     * @returns A plain object with `code` (numeric `JsonRpcErrorCode`), `message` (string), and `data` (object).
+     *
+     * @example
+     * ```ts
+     * const formatted = ErrorHandler.formatError(new McpError(JsonRpcErrorCode.NotFound, 'Item missing'));
+     * // → { code: -32001, message: 'Item missing', data: {} }
+     *
+     * const formatted2 = ErrorHandler.formatError(new TypeError('bad arg'));
+     * // → { code: -32007, message: 'bad arg', data: { errorType: 'TypeError' } }
+     * ```
+     */
+    static formatError(error) {
+        if (error instanceof McpError) {
+            return {
+                code: error.code,
+                message: error.message,
+                data: typeof error.data === 'object' && error.data !== null ? error.data : {},
+            };
+        }
+        if (error instanceof Error) {
+            return {
+                code: ErrorHandler.determineErrorCode(error),
+                message: error.message,
+                data: { errorType: error.name || 'Error' },
+            };
+        }
+        return {
+            code: JsonRpcErrorCode.UnknownError,
+            message: getErrorMessage(error),
+            data: { errorType: getErrorName(error) },
+        };
+    }
+    /**
+     * Safely executes a synchronous or asynchronous function, logging and rethrowing any error.
+     *
+     * Equivalent to wrapping `fn` in a try/catch that calls `ErrorHandler.handleError` with `rethrow: true`.
+     * The processed `McpError` (or custom-mapped error) is always thrown — this method never swallows errors.
+     * Use this in service code where you want structured logging and OTel integration without duplicating
+     * error-handling boilerplate.
+     *
+     * @template T The expected return type of `fn`.
+     * @param fn - The function to execute. May be synchronous or return a `Promise`.
+     * @param options - Error handling options passed to `handleError` (`rethrow` is always `true` and cannot be overridden).
+     * @returns A promise that resolves with the return value of `fn` on success.
+     * @throws {McpError | Error} The processed error from `ErrorHandler.handleError` on failure.
+     *
+     * @example
+     * ```ts
+     * const user = await ErrorHandler.tryCatch(
+     *   () => db.findUser(id),
+     *   { operation: 'findUser', context: { requestId, userId: id } },
+     * );
+     * ```
+     */
+    static async tryCatch(fn, options) {
+        try {
+            return await Promise.resolve(fn());
+        }
+        catch (caughtError) {
+            const handled = ErrorHandler.handleError(caughtError, {
+                ...options,
+                rethrow: false,
+            });
+            throw handled;
+        }
+    }
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/utils/internal/error-handler/errorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/errorHandler.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/error-handler/helpers.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Helper utilities for error inspection and normalization.
+ * Enhanced with cause chain extraction and circular reference detection.
+ * @module src/utils/internal/error-handler/helpers
+ */
+/**
+ * Retrieves a descriptive name for an error object or value.
+ *
+ * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`.
+ * - `null` → `'NullValueEncountered'`
+ * - `undefined` → `'UndefinedValueEncountered'`
+ * - Non-plain objects with a named constructor → `'<ConstructorName>Encountered'`
+ * - Everything else → `'<typeof value>Encountered'` (e.g. `'stringEncountered'`)
+ *
+ * @param error - The error object or value.
+ * @returns A stable, human-readable string identifying the error's type.
+ *
+ * @example
+ * ```ts
+ * getErrorName(new TypeError('bad'));   // → 'TypeError'
+ * getErrorName('oops');                 // → 'stringEncountered'
+ * getErrorName(null);                   // → 'NullValueEncountered'
+ * ```
+ */
+export declare function getErrorName(error: unknown): string;
+/**
+ * Extracts a human-readable message string from any thrown value.
+ *
+ * Handles every JavaScript type so that `catch (e)` blocks never produce `[object Object]`:
+ * - `AggregateError` → combines up to 3 inner error messages after the outer message.
+ * - `Error` → `error.message`
+ * - `null` / `undefined` → descriptive literal strings.
+ * - Primitives (`string`, `number`, `boolean`, `bigint`, `symbol`) → string-coerced value.
+ * - Functions → `[function <name>]`
+ * - Objects → JSON-serialized if possible; otherwise constructor name fallback.
+ * - If conversion itself throws, returns a safe fallback describing the conversion error.
+ *
+ * @param error - The thrown value to extract a message from.
+ * @returns A non-empty string describing the error.
+ *
+ * @example
+ * ```ts
+ * getErrorMessage(new Error('oops'));              // → 'oops'
+ * getErrorMessage('string thrown');               // → 'string thrown'
+ * getErrorMessage(42);                            // → '42'
+ * getErrorMessage(null);                          // → 'Null value encountered as error'
+ * getErrorMessage(new AggregateError([new Error('a'), new Error('b')], 'multi'));
+ * // → 'multi: a; b'
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Represents a single node in an error cause chain produced by `extractErrorCauseChain`.
+ * Each node captures the identity, message, and optional metadata of one error in the chain,
+ * with `depth: 0` being the original (outermost) error and increasing depth tracking nested causes.
+ */
+export interface ErrorCauseNode {
+    /** Additional data from McpError instances */
+    data?: Record<string, unknown>;
+    /** Depth in the cause chain (0 = original error) */
+    depth: number;
+    /** Error message */
+    message: string;
+    /** Error name/type */
+    name: string;
+    /** Stack trace if available */
+    stack?: string;
+}
+/**
+ * Extracts the complete error cause chain into a flat array of `ErrorCauseNode` objects.
+ *
+ * Starts at `error` (depth 0) and follows `error.cause` links until:
+ * - a non-Error value is encountered (appended as the terminal node, then stops),
+ * - a circular reference is detected (sentinel node appended, then stops),
+ * - or `maxDepth` is reached (sentinel node appended, then stops).
+ *
+ * String causes are treated as terminal `StringError` nodes.
+ * `McpError` nodes include the `data` property when present.
+ * Circular references are detected via `WeakSet` identity tracking.
+ *
+ * @param error - The outermost error to start traversal from.
+ * @param maxDepth - Maximum number of nodes to traverse before stopping. Defaults to `20`.
+ * @returns An array of `ErrorCauseNode` objects ordered from outermost (depth 0) to deepest cause.
+ *          An empty array is returned if `error` itself is falsy.
+ *
+ * @example
+ * ```ts
+ * const inner = new Error('db connection failed');
+ * const outer = new Error('user lookup failed', { cause: inner });
+ * const chain = extractErrorCauseChain(outer);
+ * // → [
+ * //   { name: 'Error', message: 'user lookup failed', depth: 0, stack: '...' },
+ * //   { name: 'Error', message: 'db connection failed', depth: 1, stack: '...' },
+ * // ]
+ * ```
+ */
+export declare function extractErrorCauseChain(error: unknown, maxDepth?: number): ErrorCauseNode[];
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/internal/error-handler/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAoBnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAkDtD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,cAAc,EAAE,CAkEtF"}