/**
 * @fileoverview Helper utilities for error inspection and normalization.
 * Enhanced with cause chain extraction and circular reference detection.
 * @module src/utils/internal/error-handler/helpers
 */
import { ZodError } from 'zod';
/**
 * Formats a ZodError as a human-readable sentence.
 *
 * `ZodError.message` is a serialized JSON array of `ZodIssue` objects — useful for
 * debugging but unreadable in logs, client error messages, and UI surfaces. This
 * helper extracts the first issue's message (typically the most actionable) and
 * appends path + overflow count so `error.message` reads as prose.
 *
 * Pair with `ErrorHandler.classifyOnly` (which returns `data: { issues }`) to
 * preserve the structured issue array for clients that can render field-level
 * errors.
 *
 * @param err - The ZodError to format.
 * @returns A single-line sentence, e.g. `"Expected string at nctId (+2 more)"`.
 */
export declare function formatZodErrorMessage(err: ZodError): string;
/**
 * 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