/**
 * @fileoverview Turns a failed Census API request into an error a caller can act on, and keeps
 * the upstream error page out of the response whatever the status was.
 * @module services/census-api/errors
 */
import { McpError } from '@cyanheads/mcp-ts-core/errors';
/**
 * Render a year list with contiguous runs collapsed — `[2005…2019, 2021…2024]` reads as
 * "2005-2019, 2021-2024". The lists run to fifteen vintages, and a caller looking for the
 * gap in a flat sequence of numbers has to find it by eye.
 */
export declare function formatYears(years: number[]): string;
/**
 * The vintage a query named is not one this server can query the dataset for.
 *
 * Two causes, one answer: the Census API publishes no such vintage at all (`pep/charv` serves
 * 2023 alone, and 2020 through 2022 are values of its own `YEAR` dimension inside that vintage),
 * or it publishes one that rejects the `NAME` column every query here sends (`cbp` before 2012,
 * `nonemp` 2008 through 2011). The wording says the year cannot be queried rather than that the
 * dataset does not publish it, because the second kind is published — it just cannot be read in
 * the shape every query here takes.
 */
export declare function yearNotAvailable(dataset: string, year: number, availableYears: number[] | undefined): McpError;
/**
 * Translate a thrown Census API fetch failure.
 *
 * `fetchWithTimeout` attaches the first 500 bytes of the response body to `data.body` and
 * `data.responseBody`. That body is worth keeping when it is the Census API's one-line rejection
 * and worth dropping when it is the servlet container's HTML error page, so it is read rather
 * than forwarded or stripped wholesale: a short unmarked-up line becomes `upstreamMessage` and
 * lands in the error text, and anything else is discarded. Either way `body` and `responseBody`
 * are gone, so no markup reaches a caller from any status.
 *
 * A 404 on a vintage the catalog does not list is `year_not_available`. A 404 on one it does
 * list is not — the years were validated before the request, so the catalog has drifted from the
 * API and answering "no such vintage" while naming that vintage as available says nothing a
 * caller can act on. Every other status keeps the status-mapped code it already had, which is
 * what decides whether `withRetry` tries again. Anything that is not an HTTP failure (timeout,
 * abort, network error) is returned unchanged for its own handling.
 *
 * Returns the error to throw rather than throwing, so the call site reads as a `throw`.
 */
export declare function censusHttpError(error: unknown, scope: {
    dataset: string;
    year: number;
    availableYears?: number[] | undefined;
}): unknown;
//# sourceMappingURL=errors.d.ts.map