/**
 * @fileoverview Defines standardized error codes, a custom error class, and related schemas
 * for handling errors within the Model Context Protocol (MCP) server and its components.
 * This module provides a structured way to represent and communicate errors, ensuring
 * consistency and clarity for both server-side operations and client-side error handling.
 * @module src/types-global/errors
 */
import { z } from 'zod';
/**
 * Defines JSON-RPC 2.0 error codes, including standard and implementation-defined codes.
 * @see https://www.jsonrpc.org/specification#error_object
 */
export declare enum JsonRpcErrorCode {
    ParseError = -32700,
    InvalidRequest = -32600,
    MethodNotFound = -32601,
    InvalidParams = -32602,
    InternalError = -32603,
    ServiceUnavailable = -32000,
    NotFound = -32001,
    Conflict = -32002,
    RateLimited = -32003,
    Timeout = -32004,
    Forbidden = -32005,
    Unauthorized = -32006,
    ValidationError = -32007,
    ConfigurationError = -32008,
    InitializationFailed = -32009,
    DatabaseError = -32010,
    SerializationError = -32070,// Data serialization/deserialization failed
    UnknownError = -32099
}
/**
 * Custom error class for MCP-specific errors, extending the built-in `Error` class.
 * It standardizes error reporting by encapsulating a `JsonRpcErrorCode`, a descriptive
 * human-readable message, and optional structured data for more context.
 *
 * This class is central to error handling within the MCP framework, allowing for
 * consistent error creation and propagation.
 */
export declare class McpError extends Error {
    /**
     * The standardized error code from {@link JsonRpcErrorCode}.
     */
    readonly code: JsonRpcErrorCode;
    /**
     * Optional additional data about the error, conforming to the JSON-RPC 2.0 specification.
     * This can be any structured data that helps in understanding or debugging the error.
     * @see https://www.jsonrpc.org/specification#error_object
     */
    readonly data?: Record<string, unknown>;
    /**
     * Creates an instance of McpError.
     *
     * @param code - The standardized error code that categorizes the error.
     * @param message - A human-readable description of the error.
     * @param data - Optional. A record containing additional structured data about the error.
     */
    constructor(code: JsonRpcErrorCode, message?: string, data?: Record<string, unknown>, options?: {
        cause?: unknown;
    });
}
/** Options shared by all error factory functions (re-uses the ES2022 built-in). */
export type ErrorFactoryOptions = ErrorOptions;
/** Create an InvalidParams (-32602) error. */
export declare const invalidParams: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create an InvalidRequest (-32600) error. */
export declare const invalidRequest: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a NotFound (-32001) error. */
export declare const notFound: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a Forbidden (-32005) error. */
export declare const forbidden: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create an Unauthorized (-32006) error. */
export declare const unauthorized: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a ValidationError (-32007) error. */
export declare const validationError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a Conflict (-32002) error. */
export declare const conflict: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a RateLimited (-32003) error. */
export declare const rateLimited: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a Timeout (-32004) error. */
export declare const timeout: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a ServiceUnavailable (-32000) error. */
export declare const serviceUnavailable: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a ConfigurationError (-32008) error. */
export declare const configurationError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create an InternalError (-32603) error. */
export declare const internalError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a SerializationError (-32070) error — JSON/XML/parser failures. */
export declare const serializationError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/** Create a DatabaseError (-32010) error. */
export declare const databaseError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
/**
 * Zod schema for validating error objects. This schema can be used for:
 * - Validating error structures when parsing error responses from external services.
 * - Ensuring consistency when creating or handling error objects internally.
 * - Generating TypeScript types for error objects.
 *
 * The schema enforces the presence of a `code` (from {@link JsonRpcErrorCode}) and a `message`,
 * and allows for optional `data`.
 */
export declare const ErrorSchema: z.ZodObject<{
    code: z.ZodEnum<typeof JsonRpcErrorCode>;
    message: z.ZodString;
    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>;
/**
 * TypeScript type inferred from the {@link ErrorSchema}.
 * This type represents the structure of a validated error object, commonly used
 * for error responses or when passing error information within the application.
 */
export type ErrorResponse = z.infer<typeof ErrorSchema>;
/**
 * Declarative entry in a tool or resource's `errors[]` contract.
 *
 * Lets a definition advertise what it can fail with — the JSON-RPC code, a
 * stable machine-readable `reason`, and a human-readable `when` description.
 *
 * **Validation.** Checked by the startup linter — invalid codes, duplicate
 * `reason` strings within a single definition, and (with the conformance check
 * enabled) handler bodies that throw codes not in the contract are flagged.
 *
 * **Authoring guidance:**
 * - Keep `reason` short, snake_case, stable. Treat it like a CSS class name
 *   the client can switch on. Don't change them across versions without notice.
 * - Use `when` for the natural-language explanation, not the message that ends
 *   up on the error itself. The error's runtime `message` is per-occurrence;
 *   `when` is the type-level description.
 * - Set `retryable` on every entry where retry behavior matters. It drives two
 *   things: (1) `withRetry`'s default predicate fails fast when
 *   `data.retryable === false`, even for transient-coded errors — so deterministic
 *   failures don't hammer the upstream; (2) `ctx.fail` auto-populates
 *   `data.retryable` from the contract entry so no per-throw-site flag is needed.
 *   A caller can still override per-occurrence by passing `data.retryable`
 *   explicitly. When omitted, callers infer retryability from the code.
 *
 * @example
 * ```ts
 * tool('pubmed_fetch_articles', {
 *   // ...
 *   errors: [
 *     { code: JsonRpcErrorCode.NotFound, reason: 'no_pmid_match',
 *       when: 'None of the requested PMIDs returned data.',
 *       recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
 *     { code: JsonRpcErrorCode.RateLimited, reason: 'queue_full',
 *       when: 'Local request queue is at capacity.', retryable: true,
 *       recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
 *     { code: JsonRpcErrorCode.ServiceUnavailable, reason: 'ncbi_down',
 *       when: 'NCBI E-utilities is unreachable after 6 retries.', retryable: true,
 *       recovery: 'NCBI is degraded; retry in a few minutes.' },
 *   ],
 *   // ...
 * });
 * ```
 */
export interface ErrorContract {
    /** JSON-RPC error code this entry surfaces as. */
    code: JsonRpcErrorCode;
    /**
     * Stable machine-readable identifier for this failure mode.
     * Should be `snake_case`, unique within a single definition's `errors[]`,
     * and treated as part of the public API — clients may switch on it.
     */
    reason: string;
    /**
     * Human-readable description of what the agent should do when this failure
     * occurs. Forcing function for the author: declaring a failure mode without
     * articulating recovery leaves the agent without a next move.
     *
     * **Type-level only — not auto-injected at runtime.** The contract `recovery`
     * is descriptive metadata read by the linter, scaffolding skills, and dev
     * tools. The wire payload's `data.recovery.hint` (which the framework mirrors
     * into `content[]` text per the error-path parity invariant) is populated
     * separately at the throw site, where dynamic context (input values, attempted
     * IDs, queue state) is available. Authors who want recovery on the wire pass
     * it explicitly: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`.
     *
     * **Validation.** Required, non-empty, minimum 5 words (lint warning under
     * that floor). Specific, actionable guidance beats placeholders like
     * "Try again." or "Check input."
     */
    recovery: string;
    /**
     * Whether the failure is transient (eligible for retry).
     *
     * This field is now wired to two distinct audiences:
     *
     * **Retry engine (`withRetry`).** The default predicate (`defaultIsTransient`)
     * checks `error.data.retryable === false` and fails fast when set, even when the
     * error code is in the transient set (`Timeout`, `ServiceUnavailable`,
     * `RateLimited`). This lets deterministic upstream failures (e.g. a query too
     * expensive to ever succeed) fail immediately without hammering the upstream
     * through all retry attempts.
     *
     * **Auto-population via `ctx.fail`.** `createFail` uses the contract entry's
     * `retryable` as a base default on `data.retryable`, so every `ctx.fail(reason)`
     * call automatically carries the right flag — no per-throw-site flag needed.
     * A caller can still override it per-occurrence by passing `data.retryable`
     * explicitly; `reason` is always forced last regardless.
     *
     * **Client backoff hint.** Clients that don't use `withRetry` can read
     * `error.data.retryable` to decide their own backoff strategy; when omitted,
     * they fall back to inferring from the code.
     *
     * When omitted from a contract entry, no `retryable` key is injected onto
     * `data` — callers can still infer from the code.
     */
    retryable?: boolean;
    /**
     * Human-readable description of when this error occurs. Surfaced to LLMs and
     * UI clients via `tools/list`. Type-level, not per-occurrence — different
     * from the actual `error.message` thrown at runtime.
     */
    when: string;
}
//# sourceMappingURL=errors.d.ts.map