@autometa/http 1.4.20 → 2.0.0-rc.1

package/dist/http.d.ts

@@ -0,0 +1,300 @@
+/// <reference types="node" />
+import { AutomationError } from "@autometa/errors";
+import { HTTPRequest } from "./http-request";
+import type { HeaderPrimitive } from "./http-request";
+import { HTTPResponse } from "./http-response";
+import type { HTTPPlugin } from "./plugins";
+import type { HTTPTransport } from "./transport";
+import type { HTTPAdditionalOptions, HTTPMethod, HTTPRetryOptions, QueryParamSerializationOptions, RequestHook, ResponseHook, SchemaParser, StatusCode } from "./types";
+export declare class HTTPError extends AutomationError {
+    readonly request: HTTPRequest<unknown>;
+    readonly response: HTTPResponse<unknown> | undefined;
+    readonly originalError: unknown;
+    constructor(message: string, request: HTTPRequest<unknown>, response?: HTTPResponse<unknown>, cause?: unknown);
+}
+export declare class HTTPTransportError extends HTTPError {
+    constructor(request: HTTPRequest<unknown>, cause: unknown);
+}
+export declare class HTTPSchemaValidationError extends HTTPError {
+    constructor(request: HTTPRequest<unknown>, response: HTTPResponse<unknown>, cause: unknown);
+}
+export declare class HTTPServerError extends HTTPError {
+    constructor(request: HTTPRequest<unknown>, response: HTTPResponse<unknown>);
+}
+/**
+ * Optional configuration applied during {@link HTTP.create}.
+ */
+export interface HTTPCreateOptions {
+    /**
+     * Custom transport implementation overriding the default Fetch based transport.
+     */
+    transport?: HTTPTransport;
+    /**
+     * Plugins that will be registered on every derived client instance.
+     */
+    plugins?: HTTPPlugin[];
+}
+/**
+ * Fluent HTTP client with pluggable transport, schema validation and hook support.
+ */
+export declare class HTTP {
+    private static sharedPlugins;
+    private transport;
+    private builder;
+    private meta;
+    private sharedPlugins;
+    private scopedPlugins;
+    private constructor();
+    /**
+     * Factory helper that prepares an {@link HTTP} instance with shared state.
+     */
+    static create(options?: HTTPCreateOptions): HTTP;
+    /**
+     * Registers a plugin applied to every client created via {@link HTTP.create}.
+     */
+    static registerSharedPlugin(plugin: HTTPPlugin): void;
+    /**
+     * Replaces the shared plugin registry used by {@link HTTP.create}.
+     */
+    static setSharedPlugins(plugins: readonly HTTPPlugin[]): void;
+    /**
+     * Returns a copy of the currently registered shared plugins.
+     */
+    static getSharedPlugins(): readonly HTTPPlugin[];
+    /**
+     * Registers a plugin that runs for every request executed by this instance and its clones.
+     */
+    use(plugin: HTTPPlugin): this;
+    /**
+     * Returns a scoped clone with an additional plugin applied only to that clone.
+     */
+    plugin(plugin: HTTPPlugin): HTTP;
+    /**
+     * Mutates the current instance to use a different transport implementation.
+     */
+    useTransport(transport: HTTPTransport): this;
+    /**
+     * Produces a new client with an alternate transport without changing the original instance.
+     */
+    withTransport(transport: HTTPTransport): HTTP;
+    /**
+     * Sets the base URL shared by subsequent requests.
+     */
+    url(url: string): this;
+    /**
+     * Applies additional transport specific options to every request executed by this instance.
+     */
+    sharedOptions(options: HTTPAdditionalOptions<unknown>): this;
+    /**
+     * Returns a derived client with extra transport options applied only to that clone.
+     */
+    withOptions(options: HTTPAdditionalOptions<unknown>): HTTP;
+    /**
+     * Registers an {@link AbortSignal} that will be forwarded to every request issued by this instance.
+     */
+    sharedAbortSignal(signal: AbortSignal | null): this;
+    /**
+     * Returns a derived client configured with the provided {@link AbortSignal}.
+     */
+    abortSignal(signal: AbortSignal | null): HTTP;
+    /**
+     * Configures automatic retries for this instance and all derived clients.
+     */
+    sharedRetry(options: HTTPRetryOptions | null): this;
+    /**
+     * Returns a derived client with custom retry behaviour.
+     */
+    retry(options: HTTPRetryOptions | null): HTTP;
+    /**
+     * Forces subsequent requests to return raw response streams without parsing.
+     */
+    sharedStreamResponse(enabled: boolean): this;
+    /**
+     * Returns a derived client configured for streaming responses.
+     */
+    streamResponse(enabled: boolean): HTTP;
+    /**
+     * Convenience helper that returns a clone configured for streaming responses.
+     */
+    asStream(): HTTP;
+    /**
+     * Executes a GET request while preserving the raw response stream.
+     */
+    stream<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Sets a shared timeout (in milliseconds) applied to every request from this instance.
+     */
+    sharedTimeout(duration: number | null): this;
+    /**
+     * Returns a derived client with a per-request timeout in milliseconds.
+     */
+    timeout(duration: number | null): HTTP;
+    /**
+     * Configures whether schema validation is required before resolving a response.
+     */
+    requireSchema(required: boolean): this;
+    /**
+     * Returns a clone with overridden plain text handling mode.
+     */
+    allowPlainText(allow: boolean): HTTP;
+    /**
+     * Sets plain text handling for the current instance and all future requests.
+     */
+    sharedAllowPlainText(allow: boolean): this;
+    /**
+     * Adds path segments that will be included in every request.
+     */
+    sharedRoute(...segments: (string | number | boolean)[]): this;
+    /**
+     * Executes a request using the provided method.
+     *
+     * Use this when the verb is dynamic (e.g. provided by a parameter). It
+     * behaves like calling {@link get}/{@link post}/{@link patch}, respecting any
+     * route/headers/body configured earlier in the chain.
+     */
+    fetchWith<TResponse>(method: HTTPMethod | Lowercase<HTTPMethod>, options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Returns a clone with additional path segments.
+     */
+    route(...segments: (string | number | boolean)[]): HTTP;
+    /**
+     * Applies query serialization preferences to all future requests originating from this instance.
+     */
+    sharedQueryFormat(options: QueryParamSerializationOptions): this;
+    /**
+     * Returns a derived client with custom query serialization that does not affect the source instance.
+     */
+    queryFormat(options: QueryParamSerializationOptions): HTTP;
+    /**
+     * Registers schema validation for one or more status codes on the current instance.
+     */
+    sharedSchema(parser: SchemaParser, ...codes: StatusCode[]): HTTP;
+    sharedSchema(parser: SchemaParser, ...ranges: {
+        from: StatusCode;
+        to: StatusCode;
+    }[]): HTTP;
+    /**
+     * Returns a clone with schema validation limited to the derived instance.
+     */
+    schema(parser: SchemaParser, ...codes: StatusCode[]): HTTP;
+    schema(parser: SchemaParser, ...ranges: {
+        from: StatusCode;
+        to: StatusCode;
+    }[]): HTTP;
+    /**
+     * Sets a shared query parameter for all future requests.
+     */
+    sharedParam(name: string, value: Record<string, unknown>): HTTP;
+    sharedParam(name: string, value: (string | number | boolean | null | undefined)[]): HTTP;
+    sharedParam(name: string, ...value: (string | number | boolean)[]): HTTP;
+    /**
+     * Derives a client with additional query parameters.
+     */
+    param(name: string, value: Record<string, unknown>): HTTP;
+    param(name: string, value: (string | number | boolean | null | undefined)[]): HTTP;
+    param(name: string, ...value: (string | number | boolean)[]): HTTP;
+    /**
+     * Merges multiple shared query parameters into the instance.
+     */
+    sharedParams(dict: Record<string, unknown>): this;
+    /**
+     * Derives a client with additional query parameters applied together.
+     */
+    params(dict: Record<string, unknown>): HTTP;
+    /**
+     * Sets a shared request body used by every request from this instance.
+     */
+    sharedData<T>(data: T | undefined): this;
+    /**
+     * Derives a client with a one-off request body.
+     */
+    data<T>(data: T | undefined): HTTP;
+    /**
+     * Registers a header that will be resolved for every request on this instance.
+     */
+    sharedHeader(name: string, value: string | number | boolean | null | (string | number | boolean)[] | (() => HeaderPrimitive | Promise<HeaderPrimitive>)): this;
+    /**
+     * Returns a clone with a header applied only to the resulting client.
+     */
+    header(name: string, value: string | number | boolean | null | (string | number | boolean)[] | (() => HeaderPrimitive | Promise<HeaderPrimitive>)): HTTP;
+    /**
+     * Registers multiple shared headers for every downstream request.
+     */
+    sharedHeaders(dict: Record<string, HeaderPrimitive | HeaderPrimitive[]>): this;
+    /**
+     * Returns a derived client with additional headers.
+     */
+    headers(dict: Record<string, HeaderPrimitive | HeaderPrimitive[]>): HTTP;
+    /**
+     * Registers a request hook that runs before every execution on this instance.
+     */
+    sharedOnSend(description: string, hook: RequestHook): this;
+    /**
+     * Returns a clone with a request hook used only for that clone.
+     */
+    onSend(description: string, hook: RequestHook): HTTP;
+    /**
+     * Registers a response hook executed after every transport response.
+     */
+    sharedOnReceive(description: string, hook: ResponseHook<unknown>): this;
+    /**
+     * Returns a derived client with a response hook limited to that client.
+     */
+    onReceive(description: string, hook: ResponseHook<unknown>): HTTP;
+    /**
+     * Configures whether server errors (>=500) throw by default for every request.
+     */
+    sharedThrowOnServerError(value: boolean): this;
+    /**
+     * Returns a derived client with custom server error behaviour.
+     */
+    throwOnServerError(value: boolean): HTTP;
+    /**
+     * Executes a GET request using the current configuration.
+     */
+    get<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a POST request using the current configuration.
+     */
+    post<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a PUT request using the current configuration.
+     */
+    put<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a PATCH request using the current configuration.
+     */
+    patch<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a DELETE request using the current configuration.
+     */
+    delete<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a HEAD request using the current configuration.
+     */
+    head<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes an OPTIONS request using the current configuration.
+     */
+    options<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a TRACE request using the current configuration.
+     */
+    trace<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    /**
+     * Executes a CONNECT request using the current configuration.
+     */
+    connect<TResponse>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponse>>;
+    private execute;
+    private runRequestPlugins;
+    private runResponsePlugins;
+    private runErrorPlugins;
+    private runOnSendHooks;
+    private runOnReceiveHooks;
+    private validateResponse;
+    private buildResponse;
+    private plugins;
+    private shouldRetryRequest;
+    private delayRetry;
+    private derive;
+}