import { type ErrorSeverity, type NodeSettingsErrorCode } from "./errors.js";
import { type ZodIssueSummary } from "./utils/zod-issues.js";
/**
 * Structured, JSON-serialisable view of a thrown error. The shape
 * intentionally mirrors common API-error responses (Stripe / Google
 * Cloud / etc.): one record with stable `code`, severity, message,
 * actionable hint, and a docs URL.
 *
 * The CLI emits this in `--format=json` output; library consumers can
 * use it to feed log aggregators, Sentry breadcrumbs, etc.
 */
export interface ErrorReport {
    /** The stable error code, or `"UNKNOWN"` when `err` is not a recognised throw. */
    code: NodeSettingsErrorCode | "UNKNOWN";
    /** Severity bucket — see {@link ErrorSeverity}. `"unknown"` for unrecognised throws. */
    severity: ErrorSeverity | "unknown";
    /** Short human title (from {@link ERROR_CATALOG}). */
    title: string;
    /** Full diagnostic message, including the `hint:` line if present. */
    message: string;
    /** Remediation tip — what the caller should change to fix this. */
    hint?: string;
    /** Direct link to the long-form doc entry for this code. */
    docsUrl: string;
    /** Path/message pairs when the underlying cause was a `ZodError`. */
    issues?: ZodIssueSummary[];
    /** Wrapped cause, distilled to name + message for safe serialisation. */
    cause?: {
        name: string;
        message: string;
    };
}
export interface ReportErrorOptions {
    /**
     * Override the base URL for `docsUrl`. Useful when a downstream tool
     * re-hosts the docs (`https://internal.example.com/node-settings/ERRORS.md`).
     * Default: {@link DEFAULT_DOCS_BASE}.
     */
    docsBase?: string;
}
/**
 * Convert any thrown value into a structured {@link ErrorReport}.
 *
 *   - `NodeSettingsError` — full report from the catalog.
 *   - `ZodError`           — synthesised report with code `ENV_VALIDATION_FAILED`
 *                            and the issues array populated.
 *   - anything else        — `code: 'UNKNOWN'`, severity `'unknown'`.
 *
 * The returned object is plain JSON (`JSON.stringify` round-trips
 * cleanly), so logging frameworks and the CLI's `--format=json` mode
 * can ship it directly.
 *
 * @example
 * ```ts
 * try {
 *   const settings = loadSettings(process.env);
 * } catch (err) {
 *   const report = reportError(err);
 *   if (report.severity === "runtime") {
 *     console.error(`[boot] ${report.title}: see ${report.docsUrl}`);
 *   }
 *   throw err;
 * }
 * ```
 */
export declare function reportError(err: unknown, options?: ReportErrorOptions): ErrorReport;
//# sourceMappingURL=report-error.d.ts.map