/**
 * Custom error classes for better error handling and logging
 */
/**
 * Closed set of services that can raise a sanitized ApiError
 */
export type ApiServiceName = 'NOAA' | 'OpenMeteo' | 'NCEI' | 'RainViewer' | 'Nominatim' | 'AviationWeather';
/**
 * Base error class for API-related errors
 */
export declare class ApiError extends Error {
    readonly statusCode: number;
    readonly service: ApiServiceName;
    readonly userMessage: string;
    readonly helpLinks: string[];
    readonly isRetryable: boolean;
    constructor(message: string, statusCode: number, service: ApiServiceName, userMessage: string, helpLinks?: string[], isRetryable?: boolean);
    /**
     * Format error for display to user
     */
    toUserMessage(): string;
}
/**
 * Rate limit error - too many requests
 */
export declare class RateLimitError extends ApiError {
    readonly retryAfter?: number;
    constructor(service: ApiServiceName, messageOrRetryAfter?: string | number, retryAfter?: number);
}
/**
 * Service unavailable error - API is down or timing out
 */
export declare class ServiceUnavailableError extends ApiError {
    constructor(service: ApiServiceName, messageOrError?: string | Error, originalError?: Error);
}
/**
 * Invalid location error - coordinates not supported or out of range
 */
export declare class InvalidLocationError extends ApiError {
    readonly latitude?: number;
    readonly longitude?: number;
    constructor(service: ApiServiceName, message: string, latitude?: number, longitude?: number);
}
/**
 * Data not found error - requested data doesn't exist
 */
export declare class DataNotFoundError extends ApiError {
    constructor(service: ApiServiceName, message: string);
}
/**
 * Validation error - invalid input parameters
 */
export declare class ValidationError extends Error {
    readonly field?: string;
    readonly value?: any;
    constructor(message: string, field?: string, value?: any);
}
/**
 * The user-facing text shown when the optional `mqtt` package is absent.
 *
 * This single string reaches the user through three surfaces, so it is defined
 * once and never reworded per-surface:
 *   1. `get_lightning_activity` — as `Error: <this>` via `formatErrorForUser`
 *   2. `get_weather_summary` — inline in its `## lightning (unavailable)` section
 *   3. `docs/ERROR_HANDLING.md` — quoted verbatim
 *
 * It names the package, states plainly that it is not installed, and gives the
 * remedy. It carries no file path and no stack: the reader needs the fix, not
 * our node_modules layout.
 */
export declare const MQTT_UNAVAILABLE_MESSAGE: string;
/**
 * The optional `mqtt` package could not be resolved.
 *
 * Deliberately a plain `Error` and **not** an `ApiError`: `ApiServiceName` is a
 * closed union that does not include Blitzortung, and this is a local packaging
 * state rather than an upstream service failure. `formatErrorForUser` has no
 * branch for it, so it falls through to the generic sanitiser and the user sees
 * `Error: <message>`.
 *
 * This is a **contract** failure, not garnish. Lightning is safety data, so an
 * absent module must never degrade into an empty strike list — that would render
 * as an all-clear built from a missing dependency.
 */
export declare class MqttUnavailableError extends Error {
    constructor(message?: string);
}
/**
 * The user-facing text shown when the optional `mqtt` package is installed but
 * cannot be loaded.
 *
 * A different state from `MQTT_UNAVAILABLE_MESSAGE`, and deliberately a
 * different message: telling someone to reinstall without `--omit=optional`
 * when they never omitted it sends them after the wrong fix. Reaches the same
 * two surfaces (`get_lightning_activity`, `get_weather_summary`).
 *
 * Fixed text with no path and no stack — the underlying failure can carry a
 * `Require stack:` of absolute paths, and none of that belongs in a tool result.
 */
export declare const MQTT_LOAD_FAILED_MESSAGE: string;
/**
 * The optional `mqtt` package resolved but failed to load.
 *
 * Distinct from {@link MqttUnavailableError} so the two remedies stay distinct,
 * but the same **contract** posture: lightning is safety data, and a module that
 * failed to load is not an empty feed. Without this, the loader's "real fault"
 * rethrow fell through `getLightningStrikes`'s generic catch to `return []` and
 * rendered a green safety verdict built from a broken dependency — verified
 * against the built dist with a corrupted `mqtt` and with one of its transitive
 * dependencies removed.
 *
 * Note that a corrupt CommonJS package reports `MODULE_NOT_FOUND`, not
 * `ERR_MODULE_NOT_FOUND`, so it never reaches the absence branch — see
 * `loadMqtt` in `src/services/blitzortung.ts`.
 */
export declare class MqttLoadFailedError extends Error {
    constructor(message?: string);
}
/**
 * Check if an error is retryable
 */
export declare function isRetryableError(error: Error): boolean;
/**
 * Format error for user display
 */
export declare function formatErrorForUser(error: Error): string;
//# sourceMappingURL=ApiError.d.ts.map