@memberjunction/network-utils 0.0.0 → 6.1.0-edge.4

package/dist/HttpClient.d.ts

@@ -0,0 +1,620 @@
+/**
+ * A dependency-free HTTP client built on Node's native `fetch`.
+ *
+ * This exists to replace `axios` across the MJ codebase. Node 18+ ships a spec-compliant `fetch`,
+ * so a third-party HTTP client buys nothing but supply-chain surface — while costing us the ability
+ * to route every outbound request through one place. That one place matters: {@link HttpClient}
+ * and {@link HttpRequest} can opt into the SSRF guard in this same package (`ValidateUrl`), which
+ * is impossible to enforce when every package reaches for `axios` directly.
+ *
+ * The shape deliberately mirrors the parts of axios MJ actually used — a config object, a response
+ * with a parsed `Data`, a throw-on-non-2xx default, per-instance defaults, and request/retry hooks
+ * standing in for interceptors — so call sites port over mechanically.
+ *
+ * SSRF NOTE: `ValidateUrl` defaults to **false** here. That is intentional. Most MJ call sites talk
+ * to fixed, well-known provider endpoints, and some legitimately talk to internal hosts (MJServer
+ * posting to its own API, MetadataSync resolving a `@url:` reference on a dev box). Guarding those
+ * by default would break them. Set `ValidateUrl: true` — or use {@link SafeFetch} directly —
+ * wherever the URL is caller-controlled.
+ */
+/** HTTP methods supported by {@link HttpRequest}. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/**
+ * How to interpret the response body.
+ * - `json` — parse as JSON; falls back to raw text when the body is empty or not valid JSON.
+ * - `text` — return the body as a string.
+ * - `arraybuffer` — return the body as an `ArrayBuffer` (binary downloads).
+ * - `blob` — return the body as a `Blob`.
+ * - `stream` — return the raw `ReadableStream` body without consuming it.
+ * - `none` — discard the body and return `null`.
+ */
+export type HttpResponseType = "json" | "text" | "arraybuffer" | "blob" | "stream" | "none";
+/**
+ * Values accepted in a query-string object. Arrays are serialized as repeated keys, and `Date`
+ * values as ISO 8601 — matching how axios's default param serializer rendered them.
+ */
+export type HttpQueryValue = string | number | boolean | Date | null | undefined | ReadonlyArray<string | number | boolean | Date>;
+/**
+ * The result of a request. Returned for 2xx responses, and — when `ThrowOnError` is disabled —
+ * for any response at all.
+ *
+ * The axios equivalent is its response object, with the fields renamed to MJ's `PascalCase`
+ * convention: `data` -> `Data`, `status` -> `Status`, `headers` -> `Headers`.
+ *
+ * @typeParam T - the shape of the parsed response body. Supply it at the call site
+ *   (`HttpGet<Payload>(...)`) so `Data` is typed rather than `unknown`.
+ *
+ * @example
+ * ```ts
+ * interface Repo { id: number; full_name: string }
+ * const response = await HttpGet<Repo>('https://api.github.com/repos/a/b');
+ * response.Data.full_name;   // typed as string
+ * response.Status;           // 200
+ * response.Headers['etag'];  // header keys are always lower-cased
+ * ```
+ */
+export interface HttpResponse<T = unknown> {
+    /** The parsed response body, per the request's `ResponseType`. */
+    Data: T;
+    /** HTTP status code. */
+    Status: number;
+    /** HTTP status text. */
+    StatusText: string;
+    /** Response headers, lower-cased keys. */
+    Headers: Record<string, string>;
+    /** The final URL the response came from (after any redirects). */
+    Url: string;
+    /** True when `Status` is in the 2xx range. */
+    Ok: boolean;
+}
+/**
+ * Everything {@link HttpRequest} accepts. Only `Url` is required.
+ *
+ * When used through {@link HttpClient}, each field falls back to the client's corresponding
+ * option, except `Headers`, which is *merged* over the client's defaults key-by-key.
+ *
+ * @example
+ * ```ts
+ * await HttpRequest({
+ *     Url: '/reports',
+ *     BaseURL: 'https://api.example.com/v2',
+ *     Method: 'POST',
+ *     Query: { format: 'json', tag: ['a', 'b'] },   // -> ?format=json&tag=a&tag=b
+ *     Body: { name: 'Q3' },                          // JSON-encoded automatically
+ *     Timeout: 15000,
+ *     ValidateUrl: false,
+ * });
+ * ```
+ */
+export interface HttpRequestConfig {
+    /** Target URL. Resolved against `BaseURL` when that is set and this is relative. */
+    Url: string;
+    /** HTTP method. Default: `GET`. */
+    Method?: HttpMethod;
+    /** Prefix applied to a relative `Url`. */
+    BaseURL?: string;
+    /** Request headers. Merged over any client-level defaults. */
+    Headers?: Record<string, string>;
+    /** Query-string parameters appended to the URL. */
+    Query?: Record<string, HttpQueryValue>;
+    /**
+     * Request body. A plain object or array is JSON-encoded (with a `Content-Type: application/json`
+     * default); `string`, `URLSearchParams`, `FormData`, `Blob`, `ArrayBuffer`, and typed arrays are
+     * passed through to `fetch` untouched so it can set the right `Content-Type` itself.
+     */
+    Body?: unknown;
+    /** How to interpret the response body. Default: `json`. */
+    ResponseType?: HttpResponseType;
+    /** Request timeout in milliseconds. Default: 30000. Pass 0 to disable. */
+    Timeout?: number;
+    /** When true, run the URL through the SSRF guard (and re-check every redirect hop). Default: false. */
+    ValidateUrl?: boolean;
+    /**
+     * Maximum redirect hops to follow. Default: 5.
+     *
+     * With `ValidateUrl` off, `0` returns the 3xx response itself rather than following it. With
+     * `ValidateUrl` on, {@link SafeFetch} drives redirects manually, so `0` makes a redirected
+     * request throw once the cap is hit rather than returning the 3xx.
+     */
+    MaxRedirects?: number;
+    /** When true (default), a non-2xx status throws {@link HttpError} instead of returning. */
+    ThrowOnError?: boolean;
+    /** Caller-supplied abort signal, honored alongside `Timeout`. */
+    Signal?: AbortSignal;
+    /**
+     * HTTP Basic credentials. Encoded into an `Authorization: Basic ...` header — the replacement
+     * for axios's `auth` option. An explicit `Authorization` header takes precedence.
+     */
+    BasicAuth?: {
+        Username: string;
+        Password: string;
+    };
+}
+/**
+ * Thrown for a non-2xx response (when `ThrowOnError` is on), a timeout, a caller-initiated
+ * cancellation, or a transport failure.
+ *
+ * Unlike axios's error — which nests response details under `error.response` and leaves you
+ * guessing whether that property exists — every field here is always present. A request that
+ * never reached a server reports `Status: 0`, so `error.Status === 404` is safe to write without
+ * an optional-chain dance.
+ *
+ * Distinguish the three failure modes with `Status`, {@link HttpError.IsTimeout}, and
+ * {@link HttpError.IsCancelled}.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await client.Get('/thing');
+ * } catch (error) {
+ *     if (!IsHttpError(error)) throw error;
+ *     if (error.IsCancelled) return;                       // caller aborted; not a failure
+ *     if (error.IsTimeout) LogError('upstream slow');
+ *     else if (error.Status === 404) LogError('missing');
+ *     else if (error.Status === 429) await backOff(error.Headers['retry-after']);
+ *     else LogError(`HTTP ${error.Status}`, error.Data);
+ * }
+ * ```
+ */
+export declare class HttpError extends Error {
+    /** HTTP status code, or 0 when the request never produced a response (timeout / network error). */
+    readonly Status: number;
+    /** HTTP status text, empty when there was no response. */
+    readonly StatusText: string;
+    /** Parsed response body, when one was received. */
+    readonly Data: unknown;
+    /** Response headers, lower-cased keys. Empty when there was no response. */
+    readonly Headers: Record<string, string>;
+    /** The URL that was requested. */
+    readonly Url: string;
+    /** The HTTP method used. */
+    readonly Method: HttpMethod;
+    /** True when the failure was this request's own `Timeout` elapsing. */
+    readonly IsTimeout: boolean;
+    /** True when the caller's own `Signal` aborted the request — the `axios.isCancel` equivalent. */
+    readonly IsCancelled: boolean;
+    constructor(message: string, details: {
+        Status?: number;
+        StatusText?: string;
+        Data?: unknown;
+        Headers?: Record<string, string>;
+        Url: string;
+        Method: HttpMethod;
+        IsTimeout?: boolean;
+        IsCancelled?: boolean;
+    });
+}
+/**
+ * Narrows an unknown caught value to {@link HttpError} — the replacement for axios's
+ * `isAxiosError`.
+ *
+ * @param error - the value from a `catch` block.
+ * @returns true when the value is an {@link HttpError}, narrowing its type for the caller.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *     if (IsHttpError(error) && error.Status === 403) { ... }
+ *     throw error;   // anything else is not ours to interpret
+ * }
+ * ```
+ */
+export declare function IsHttpError(error: unknown): error is HttpError;
+/**
+ * True when a request failed because the caller's own `Signal` aborted it — the replacement for
+ * axios's `isCancel`.
+ *
+ * A request's own {@link HttpRequestConfig.Timeout} elapsing is NOT a cancellation; that reports
+ * {@link HttpError.IsTimeout} instead. The distinction matters because a cancellation is usually
+ * an expected outcome to swallow, while a timeout is a fault worth logging or retrying.
+ *
+ * A native `AbortError` — thrown when the signal was already aborted before the request
+ * started — also counts.
+ *
+ * @param error - the value from a `catch` block.
+ * @returns true when the failure was caller-initiated cancellation.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *     if (IsCancellationError(error)) return null;   // the caller gave up; stay quiet
+ *     throw error;
+ * }
+ * ```
+ */
+export declare function IsCancellationError(error: unknown): boolean;
+/**
+ * Serializes a parameter object into a URL-encoded query string.
+ *
+ * Exported because it is occasionally useful on its own; {@link HttpRequest} applies it to
+ * `Query` automatically, so you rarely need to call it directly.
+ *
+ * Rules: `null` and `undefined` entries are omitted entirely (rather than becoming the strings
+ * `"null"`/`"undefined"`), arrays expand to repeated keys, and `Date` values render as ISO 8601.
+ *
+ * @param query - the parameters to serialize.
+ * @returns the encoded query string, WITHOUT a leading `?`. Empty when nothing survives.
+ *
+ * @example
+ * ```ts
+ * BuildQueryString({ q: 'a b', tag: ['x', 'y'], skip: null });
+ * // 'q=a+b&tag=x&tag=y'
+ * ```
+ */
+export declare function BuildQueryString(query: Record<string, HttpQueryValue>): string;
+/**
+ * Performs a single HTTP request using native `fetch`. This is the primitive the rest of the
+ * module is built on — the method shorthands and {@link HttpClient} all funnel through it.
+ *
+ * Reach for a shorthand ({@link HttpGet}, {@link HttpPost}, …) for one-off calls, and for
+ * {@link HttpClient} when several requests share a base URL, credentials, or retry policy.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param config - the request configuration; see {@link HttpRequestConfig}.
+ * @returns the {@link HttpResponse}, whose `Data` is parsed per `ResponseType`.
+ * @throws {HttpError} on a non-2xx status (unless `ThrowOnError` is disabled), on a timeout, on
+ *   caller cancellation, or on a transport failure. Inspect `Status` / `IsTimeout` / `IsCancelled`
+ *   to tell them apart.
+ * @throws {SSRFError} when `ValidateUrl` is enabled and the URL — or any redirect hop — resolves
+ *   to a private or reserved address. This propagates as itself rather than being wrapped in an
+ *   {@link HttpError}, so a security decision is never mistaken for an unreachable host.
+ *
+ * @example Reading a JSON payload
+ * ```ts
+ * const response = await HttpRequest<{ items: Item[] }>({
+ *     Url: 'https://api.example.com/items',
+ *     Query: { page: 1 },
+ * });
+ * return response.Data.items;
+ * ```
+ *
+ * @example Inspecting a non-2xx instead of catching it
+ * ```ts
+ * const response = await HttpRequest({ Url: url, ThrowOnError: false });
+ * if (response.Status === 404) return null;
+ * ```
+ */
+export declare function HttpRequest<T = unknown>(config: HttpRequestConfig): Promise<HttpResponse<T>>;
+/**
+ * Sends a `GET` request. Shorthand for {@link HttpRequest} with `Method: 'GET'`.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param config - optional per-request settings (query, headers, timeout, …).
+ * @returns the {@link HttpResponse}.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ *
+ * @example
+ * ```ts
+ * const { Data } = await HttpGet<User[]>('https://api.example.com/users', {
+ *     Query: { active: true },
+ *     Headers: { Authorization: `Bearer ${token}` },
+ * });
+ * ```
+ */
+export declare function HttpGet<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * Sends a `POST` request. Shorthand for {@link HttpRequest} with `Method: 'POST'`.
+ *
+ * A plain object or array `body` is JSON-encoded and given a JSON `Content-Type`. Pass a
+ * `URLSearchParams` for form encoding or a `FormData` for multipart, and `fetch` sets the correct
+ * `Content-Type` (including the multipart boundary) itself.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param body - the request body.
+ * @param config - optional per-request settings.
+ * @returns the {@link HttpResponse}.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ *
+ * @example
+ * ```ts
+ * await HttpPost('https://api.example.com/items', { name: 'Widget' });               // JSON
+ * await HttpPost(tokenUrl, new URLSearchParams({ grant_type: 'refresh_token' }));    // form
+ * ```
+ */
+export declare function HttpPost<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * Sends a `PUT` request. Shorthand for {@link HttpRequest} with `Method: 'PUT'`.
+ * Body handling matches {@link HttpPost}.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param body - the request body.
+ * @param config - optional per-request settings.
+ * @returns the {@link HttpResponse}.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ */
+export declare function HttpPut<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * Sends a `PATCH` request. Shorthand for {@link HttpRequest} with `Method: 'PATCH'`.
+ * Body handling matches {@link HttpPost}.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param body - the request body.
+ * @param config - optional per-request settings.
+ * @returns the {@link HttpResponse}.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ */
+export declare function HttpPatch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * Sends a `DELETE` request. Shorthand for {@link HttpRequest} with `Method: 'DELETE'`.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param config - optional per-request settings.
+ * @returns the {@link HttpResponse}.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ */
+export declare function HttpDelete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * Sends a `HEAD` request. Shorthand for {@link HttpRequest} with `Method: 'HEAD'`.
+ *
+ * `ResponseType` is forced to `none` because a HEAD response has no body by definition, so `Data`
+ * is always `null` — use `Status` and `Headers`. Pair with `ThrowOnError: false` when probing a
+ * URL's reachability, so a 4xx is reported as a status rather than thrown.
+ *
+ * @typeParam T - unused in practice; `Data` is always `null`.
+ * @param url - absolute URL, or a path when `config.BaseURL` is supplied.
+ * @param config - optional per-request settings.
+ * @returns the {@link HttpResponse}, with `Data` set to `null`.
+ * @throws {HttpError} on a non-2xx status (unless `ThrowOnError` is disabled), timeout,
+ *   cancellation, or transport failure.
+ *
+ * @example Probing whether a link is alive
+ * ```ts
+ * const response = await HttpHead(url, { ThrowOnError: false, Timeout: 10000 });
+ * const reachable = response.Status >= 200 && response.Status < 400;
+ * ```
+ */
+export declare function HttpHead<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+/**
+ * {@link HttpRequest} with the SSRF guard switched on — equivalent to passing
+ * `ValidateUrl: true`, but named so a reviewer can see at a glance that the call site handles an
+ * untrusted URL.
+ *
+ * Use this (or set `ValidateUrl` explicitly) wherever the URL can be influenced by an AI agent, an
+ * Action parameter, an API caller, or stored data those can write. Prefer {@link SafeFetch} when
+ * you want the raw `Response` rather than a parsed body.
+ *
+ * @typeParam T - the expected shape of the parsed response body.
+ * @param config - the request configuration; `ValidateUrl` is forced on.
+ * @returns the {@link HttpResponse}.
+ * @throws {SSRFError} when the URL, or any redirect hop, resolves to a private or reserved address.
+ * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     const response = await SafeHttpRequest({ Url: userSuppliedUrl });
+ *     return response.Data;
+ * } catch (error) {
+ *     if (error instanceof SSRFError) {
+ *         return { Success: false, ResultCode: 'SSRF_BLOCKED' };
+ *     }
+ *     throw error;
+ * }
+ * ```
+ */
+export declare function SafeHttpRequest<T = unknown>(config: HttpRequestConfig): Promise<HttpResponse<T>>;
+/**
+ * Per-instance defaults and hooks for {@link HttpClient}.
+ *
+ * The three hooks replace what axios interceptors did, with one important difference: they are
+ * plain options on the instance rather than entries appended to a mutable global chain, so what a
+ * given client does is visible at its construction site and cannot be changed from elsewhere.
+ *
+ * | axios | here |
+ * |---|---|
+ * | `interceptors.request.use(fn)` | {@link HttpClientOptions.OnRequest} |
+ * | `interceptors.response.use(onOk)` | {@link HttpClientOptions.OnResponse} |
+ * | `interceptors.response.use(_, onErr)` | {@link HttpClientOptions.OnRetry} |
+ */
+export interface HttpClientOptions {
+    /** Prefix applied to every relative request URL. */
+    BaseURL?: string;
+    /** Headers merged under each request's own headers. */
+    Headers?: Record<string, string>;
+    /** Default request timeout in milliseconds. Default: 30000. */
+    Timeout?: number;
+    /** When true, every request runs through the SSRF guard. Default: false. */
+    ValidateUrl?: boolean;
+    /** Default maximum redirect hops. Default: 5. */
+    MaxRedirects?: number;
+    /** Maximum retry attempts allowed when `OnRetry` asks for one. Default: 3. */
+    MaxRetries?: number;
+    /** Default HTTP Basic credentials applied to every request. */
+    BasicAuth?: {
+        Username: string;
+        Password: string;
+    };
+    /**
+     * Called before each request with the fully merged config; return the config to actually send.
+     * The replacement for an axios request interceptor — this is where token injection, request
+     * signing, and per-request query defaults belong.
+     *
+     * Treat the incoming config as immutable and return a new object; it is re-derived on every
+     * retry attempt, so a token read here is always current rather than captured at construction.
+     *
+     * @example
+     * ```ts
+     * OnRequest: (config) => ({
+     *     ...config,
+     *     Headers: { ...config.Headers, Authorization: `Bearer ${this.getAccessToken()}` },
+     * })
+     * ```
+     */
+    OnRequest?: (config: HttpRequestConfig) => HttpRequestConfig | Promise<HttpRequestConfig>;
+    /**
+     * Called after each successful response. Observation only: whatever this does, the response is
+     * still returned to the caller unchanged. Replaces the success half of an axios response
+     * interceptor — logging, metrics, and rate-limit headroom tracking belong here.
+     *
+     * @example
+     * ```ts
+     * OnResponse: (response) => {
+     *     const remaining = response.Headers['x-rate-limit-remaining'];
+     *     if (remaining) LogStatus(`Rate limit remaining: ${remaining}`);
+     * }
+     * ```
+     */
+    OnResponse?: (response: HttpResponse<unknown>) => void | Promise<void>;
+    /**
+     * Called when a request fails. Return `true` to retry, `false` to let the error propagate.
+     * Replaces the error half of an axios response interceptor — 429 back-off, and one-shot token
+     * refresh on a 401, belong here.
+     *
+     * Retries are bounded by `MaxRetries` (default 3) so a hook that always returns `true` cannot
+     * loop forever. Await the back-off inside the hook; the retry fires as soon as it resolves, and
+     * `OnRequest` runs again first, so a refreshed token is picked up automatically.
+     *
+     * Only an {@link HttpError} reaches this hook — an {@link SSRFError} is a security decision and
+     * is never retried.
+     *
+     * @example
+     * ```ts
+     * OnRetry: async (error, attempt) => {
+     *     if (error.Status !== 429) return false;
+     *     const retryAfter = Number(error.Headers['retry-after']) || 2 ** attempt;
+     *     await new Promise((r) => setTimeout(r, retryAfter * 1000));
+     *     return true;
+     * }
+     * ```
+     */
+    OnRetry?: (error: HttpError, attempt: number) => boolean | Promise<boolean>;
+}
+/**
+ * A configured HTTP client — the replacement for `axios.create(...)`.
+ *
+ * Holds a base URL, default headers, a timeout, and the {@link HttpClientOptions} hooks that stand
+ * in for axios interceptors. Construct one per upstream API, typically behind a lazy getter on a
+ * provider base class so the cost is paid only when that provider is actually used.
+ *
+ * Instances are stateless apart from their options and safe to share across concurrent requests.
+ * Nothing is cached between calls, so a client whose `OnRequest` reads a token always sends the
+ * current one.
+ *
+ * @example A provider client with auth injection and 429 back-off
+ * ```ts
+ * private _client: HttpClient | null = null;
+ *
+ * protected get httpClient(): HttpClient {
+ *     if (!this._client) {
+ *         this._client = new HttpClient({
+ *             BaseURL: 'https://graph.facebook.com/v18.0',
+ *             Timeout: 30000,
+ *             Headers: { Accept: 'application/json' },
+ *
+ *             // Runs before every attempt, so a refreshed token is picked up automatically.
+ *             OnRequest: (config) => ({
+ *                 ...config,
+ *                 Query: { ...config.Query, access_token: this.getAccessToken() },
+ *             }),
+ *
+ *             // Bounded by MaxRetries (default 3).
+ *             OnRetry: async (error) => {
+ *                 if (error.Status !== 429) return false;
+ *                 await this.handleRateLimit(60);
+ *                 return true;
+ *             },
+ *         });
+ *     }
+ *     return this._client;
+ * }
+ *
+ * // Then, at the call sites:
+ * const response = await this.httpClient.Get<FacebookPagedResponse<Post>>('/me/feed');
+ * return response.Data.data;
+ * ```
+ */
+export declare class HttpClient {
+    private readonly _options;
+    constructor(options?: HttpClientOptions);
+    /**
+     * The options this client was constructed with. Read-only — a client's behavior is fixed at
+     * construction, so build a second client rather than trying to mutate one.
+     */
+    get Options(): Readonly<HttpClientOptions>;
+    /**
+     * Sends a request using this client's defaults and hooks. Every other method on the class
+     * delegates here.
+     *
+     * Per-request values win over client defaults, except `Headers`, which are merged key-by-key so
+     * one request can override a single default header without discarding the rest. `OnRequest`
+     * then gets the last word on the merged config.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param config - per-request configuration, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} when the request fails and `OnRetry` does not ask for another attempt, or
+     *   once `MaxRetries` is exhausted.
+     * @throws {SSRFError} when `ValidateUrl` is enabled and the target resolves to a blocked
+     *   address. Never retried.
+     */
+    Request<T = unknown>(config: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `GET` request through this client.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Get<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `POST` request through this client. Body handling matches {@link HttpPost}.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param body - the request body.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Post<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `PUT` request through this client. Body handling matches {@link HttpPost}.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param body - the request body.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Put<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `PATCH` request through this client. Body handling matches {@link HttpPost}.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param body - the request body.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Patch<T = unknown>(url: string, body?: unknown, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `DELETE` request through this client.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Delete<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+    /**
+     * Sends a `HEAD` request through this client. `ResponseType` is forced to `none`, so `Data` is always `null`.
+     *
+     * @typeParam T - the expected shape of the parsed response body.
+     * @param url - absolute URL, or a path resolved against the client's `BaseURL`.
+     * @param config - optional per-request settings, merged over the client's defaults.
+     * @returns the {@link HttpResponse}.
+     * @throws {HttpError} on a non-2xx status, timeout, cancellation, or transport failure.
+     */
+    Head<T = unknown>(url: string, config?: Omit<HttpRequestConfig, "Url" | "Method" | "Body">): Promise<HttpResponse<T>>;
+}
+//# sourceMappingURL=HttpClient.d.ts.map

package/dist/HttpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../src/HttpClient.ts"],"names":[],"mappings":"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"}