shelving/api/provider/ClientAPIProvider.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "../../util/function.js";
import { type RequestBodyMethod, type RequestHeadMethod, type RequestOptions } from "../../util/http.js";
import type { Nullish } from "../../util/null.js";
import { type PossibleURIParams } from "../../util/uri.js";
import { type PossibleURL } from "../../util/url.js";
import type { Endpoint } from "../endpoint/Endpoint.js";
import { APIProvider } from "./APIProvider.js";
/** Options for a `ClientAPIProvider`. */
export interface ClientAPIProviderOptions {
    /**
     * The common base URL for all rendered endpoint requests.
     *
     * Note: When resolving URLs for endpoints this is treated as if it ends in a slash.
     * - e.g. in `http://p.com/a/b/c` the path will be relative to `c` as if a `/` trailing slash was present.
     * - This is different to the default behaviour of `new URL()`, but is the more natural expected result
     * - This is consistent with our e.g. `getURL()` utilities.
     */
    readonly url: PossibleURL;
    /**
     * Options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
     * - Omits `signal` because it's not relevant at the provider level.
     */
    readonly options?: Omit<RequestOptions, "signal">;
    /**
     * Timeout in milliseconds before the request is aborted with `TimeoutError`.
     * - Defaults to `20_000` (20 seconds) — chosen to fire before common platform wall-clock caps (Cloudflare Workers ~30s, Vercel/AWS API Gateway ~29s) so the abort propagates as a clean rejection instead of an opaque runtime termination.
     * - Pass `0` to disable the timeout (e.g. for streaming or long-poll endpoints). Raise it for specifically slow endpoints.
     */
    readonly timeout?: number | undefined;
}
/**
 * A client-side API provider that sends requests over the network using `fetch()`.
 * - Can be used on a server environment to make outgoing API calls, or in a browser environment to call a server API.
 * - Renders endpoint paths and query params into the URL and sends body payloads as JSON.
 * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
 * - Extendable with custom request-building and response-parsing logic by overriding `createRequest()` and `parseResponse()`.
 * - Wrap in `ValidationAPIProvider` to add automatic validation of request payloads and response results against endpoint schemas.
 */
export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProvider<P, R> {
    /** The common base URL for all rendered endpoint requests. */
    readonly url: URL;
    /** Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()` */
    readonly options: RequestOptions;
    /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
    readonly timeout: number;
    constructor({ url, options, timeout }: ClientAPIProviderOptions);
    renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
    /** Internal implementation function for `createRequest()` used for requests that have no body. */
    protected _createHeadRequest(method: RequestHeadMethod, //
    url: PossibleURL, params: Nullish<PossibleURIParams>, options: RequestOptions, caller: AnyCaller): Request;
    /** Internal implementation function for `createRequest()` used for requests that have a body.  */
    protected _createBodyRequest(method: RequestBodyMethod, //
    url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
    fetch(request: Request): Promise<Response>;
    parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
}