/** * @copyright Sister Software * @license AGPL-3.0 * @author Teffen Ellis, et al. * * API response utilities. */ /** * Whether an HTTP status is a 2xx success. * * Exists so a caller that opts out of throwing — `validateStatus: () => true`, for a graceful non-2xx path — can still * ask the question by name. Written against axios's own `HttpStatusCode` because this package already owns that * dependency; a consumer package spelling `>= 200 && < 300` inline would either name two bare thresholds or take an * undeclared dependency to avoid it. */ export declare function isSuccessStatus(status: number): boolean; /** * A response container, wrapping the actual response body. */ export interface ResponseContainer { data: Body; } export type ResponseLike = ResponseContainer | Body; /** * Type-helper to pluck the response body, possibly from within an Axios response. * * This is useful when normalizing a new Axios response and a cached local response. * * @internal */ export type ExtractResponseData = T extends ResponseContainer ? Body : T; /** * Type-helper to recursively pluck the `data` property from a response body. * * This is useful when an API nests the actual response body within a `data` property. * * @internal */ export type ExtractResponseBodyData = Body extends { data: infer Data; } ? ExtractResponseBodyData : Body; /** * Helper function to recursively pluck the `data` property from a response body. * * This is useful when an API nests the actual response body within a `data` property. * * @internal */ export declare function pluckResponseData(responseContainer: ResponseContainer): ExtractResponseBodyData; /** * The `kind` component of a {@linkcode ResourceError}'s `(source, kind, reason)` URN, as produced by * {@linkcode delegateAxiosError}. This is the axis {@linkcode isTransientResourceError} branches on, so a caller never * has to pattern-match an error message. */ export declare const ResourceErrorKind: { /** * The request never reached an HTTP response: a connect failure, a DNS failure, a timeout, or a body read that died * mid-transfer. */ readonly Network: "network"; /** * An HTTP response came back and carried a failing status. */ readonly Response: "response"; /** * The request was rejected before (or independently of) the network — a caller-initiated cancel, a malformed config. * Never transient: re-issuing the identical request can only fail identically. */ readonly Request: "request"; /** * A response arrived with a SUCCESS status, but its body could not be decoded into the requested type — the classic * case being an upstream that serves an HTML error page under a 200. * * Never transient, deliberately: retrying an unchanged bad body cannot help, and a client that treated this as * retryable would spend its whole attempt budget re-downloading the same broken payload. */ readonly Payload: "payload"; }; /** * The `kind` component of a {@linkcode ResourceError}'s URN. */ export type ResourceErrorKind = (typeof ResourceErrorKind)[keyof typeof ResourceErrorKind]; /** * The `kind` component of `error`'s URN, or `null` when it isn't a {@linkcode ResourceError} carrying one. * * Exposed so a caller can assert on the taxonomy directly (`kind === ResourceErrorKind.Network`) instead of splitting * the URN — or, worse, matching on `message` prose — at the call site. */ export declare function resourceErrorKind(error: unknown): ResourceErrorKind | null; /** * Whether `error` is the kind of failure a caller should REQUEUE rather than give up on — every network-class failure * (connect, DNS, timeout, mid-transfer drop) and every transient HTTP status (408/429/5xx). * * This stays `true` even after a client exhausted its OWN bounded attempts: the client's ceiling is a statement about * one call, while a caller's requeue is a new, separate attempt budget minutes or hours later. Callers branch on this * plus {@linkcode ResourceError.status} — 404 to skip, 403 to abort — and never on message text. */ export declare function isTransientResourceError(error: unknown): boolean; /** * Delegate Axios errors to an appropriate error handler. * * ALWAYS throws — every failure past this point is a {@linkcode ResourceError} carrying a numeric `status`, a `(source, * kind, reason)` URN on `name`, and the originating `AxiosError` on `cause`. A non-Axios error is rethrown untouched. * * WHAT CHANGED, measured rather than recalled — a differential against `98c4dda1` across 18 failure shapes in the exact * `TileAPI` configuration found **16 of them changed**, not the two originally claimed: * * - Every RESPONSELESS failure (`ERR_NETWORK`, `ECONNREFUSED`, `ECONNRESET`, `ECONNABORTED`, `ETIMEDOUT`, `ERR_CANCELED`) * used to collapse into a uniform 500; they now split into 503 / 504 / 400 by cause, and `ERR_CANCELED` flips from * transient to terminal, which is the point — a caller who cancelled should not requeue. * - Every non-401 HTTP status used to rethrow the raw `AxiosError`, so `status`-based branching (404 → skip, 403 → abort) * had to reach into `error.response`. 401's own message and URN changed too. * * The earlier claim that `ECONNABORTED`/`ETIMEDOUT`/`ERR_CANCELED` RESOLVED the chain with `undefined` was wrong FOR * EVERY SHAPE AXIOS ACTUALLY PRODUCES: the old `if (!response) throw` ran BEFORE that `switch`, and axios never * attaches a `response` to a timeout or a cancellation, so a real one threw `axios:response:missing` 500 — a * misclassified 500, not a `TypeError` at the caller. Note the `return` arms were not unreachable in general, only * unreachable via axios: reaching the `switch` required a response to be PRESENT, and an error carrying both a * `response` and `ECONNABORTED` did resolve with `undefined`. Stock adapters never pair those, but this repo's own * `axiosLikeError(message, code, config, response)` helper builds that shape in one argument. No regression follows * from any of this — the sole call site has no `.catch`, and every shape that rejects now also rejected before. * * @internal */ export declare function delegateAxiosError(error: unknown): Promise; //# sourceMappingURL=responses.d.ts.map