@harborclient/http 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) HarborClient
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @harborclient/http
+
+**Full documentation:** [https://harborclient.github.io/http/](https://harborclient.github.io/http/)
+
+**Outbound HTTP utilities for HarborClient.**
+
+@harborclient/http is a library for URL and header validation, request body encoding, fetch execution (with optional undici dispatcher for SSL and proxy settings), response size limits, and redirect following:
+
+- **Request execution:** `Requester` with configurable timeouts, SSL verification, proxy support, and redirect following.
+- **Validation and encoding:** URL/header validation and request body encoding via `QueryString` and related helpers.
+- **Safety limits:** Built-in response size caps via `HARD_MAX_RESPONSE_SIZE_MB`.
+
+## Documentation
+
+| Topic           | Link                                                             |
+| --------------- | ---------------------------------------------------------------- |
+| Getting started | [Introduction](https://harborclient.github.io/http/)             |
+| Installation    | [Installation](https://harborclient.github.io/http/installation) |
+| Usage           | [Usage](https://harborclient.github.io/http/usage)               |
+
+Canonical docs live in [`docs/`](./docs/). Edit those pages directly, then run `pnpm docs:build:nav` to refresh the VitePress sidebar.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm docs:serve    # VitePress dev server with nav watcher
+pnpm docs:build    # production docs build
+```
+
+## License
+
+MIT

package/dist/Body.d.ts

@@ -0,0 +1,28 @@
+import type { BuildMultipartResult, IBody } from './IBody.js';
+/**
+ * Encodes request bodies for multipart, urlencoded, and preview display.
+ */
+export declare class Body implements IBody {
+    /**
+     * Builds a human-readable summary of multipart form parts for request preview.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     * @returns Summary string for SentRequest.body.
+     */
+    summarizeFormParts(body: string): string;
+    /**
+     * Builds a FormData body from serialized multipart form parts.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     * @returns FormData ready for fetch, or an error message when a file cannot be read.
+     */
+    buildMultipart(body: string): Promise<BuildMultipartResult>;
+    /**
+     * Builds an application/x-www-form-urlencoded body from serialized key-value rows.
+     *
+     * @param body - JSON array stored in the request body field.
+     * @returns URL-encoded query string for the request body.
+     */
+    buildUrlEncoded(body: string): string;
+}
+//# sourceMappingURL=Body.d.ts.map

package/dist/Body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Body.d.ts","sourceRoot":"","sources":["../src/Body.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE9D;;GAEG;AACH,qBAAa,IAAK,YAAW,KAAK;IAChC;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAkBxC;;;;;OAKG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwBjE;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAQtC"}

package/dist/Body.js

@@ -0,0 +1,72 @@
+import { readFile } from 'fs/promises';
+import { basename } from 'path';
+import { parseFormParts } from './formData.js';
+import { parseUrlEncodedParts } from './urlencoded.js';
+/**
+ * Encodes request bodies for multipart, urlencoded, and preview display.
+ */
+export class Body {
+    /**
+     * Builds a human-readable summary of multipart form parts for request preview.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     * @returns Summary string for SentRequest.body.
+     */
+    summarizeFormParts(body) {
+        const parts = parseFormParts(body).filter((part) => part.enabled && part.key.trim());
+        if (parts.length === 0) {
+            return '';
+        }
+        return parts
+            .map((part) => {
+            const key = part.key.trim();
+            if (part.type === 'file') {
+                const names = part.files.map((filePath) => basename(filePath)).join(', ');
+                return `${key}: [${names || 'no files'}]`;
+            }
+            return `${key}: ${part.value}`;
+        })
+            .join('\n');
+    }
+    /**
+     * Builds a FormData body from serialized multipart form parts.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     * @returns FormData ready for fetch, or an error message when a file cannot be read.
+     */
+    async buildMultipart(body) {
+        const parts = parseFormParts(body).filter((part) => part.enabled && part.key.trim());
+        const formData = new FormData();
+        for (const part of parts) {
+            const key = part.key.trim();
+            if (part.type === 'file') {
+                for (const filePath of part.files) {
+                    try {
+                        const data = await readFile(filePath);
+                        formData.append(key, new Blob([Uint8Array.from(data)]), basename(filePath));
+                    }
+                    catch {
+                        return { error: `Failed to read file: ${filePath}` };
+                    }
+                }
+                continue;
+            }
+            formData.append(key, part.value);
+        }
+        return { formData };
+    }
+    /**
+     * Builds an application/x-www-form-urlencoded body from serialized key-value rows.
+     *
+     * @param body - JSON array stored in the request body field.
+     * @returns URL-encoded query string for the request body.
+     */
+    buildUrlEncoded(body) {
+        const rows = parseUrlEncodedParts(body).filter((row) => row.enabled && row.key.trim());
+        const params = new URLSearchParams();
+        for (const row of rows) {
+            params.append(row.key.trim(), row.value);
+        }
+        return params.toString();
+    }
+}

package/dist/Headers.d.ts

@@ -0,0 +1,25 @@
+import type { BodyType, KeyValue } from './types.js';
+import type { ApplyCookieResult, BuildHeadersResult, IHeaders } from './IHeaders.js';
+/**
+ * Builds request headers and merges cookie jar values for outbound requests.
+ */
+export declare class Headers implements IHeaders {
+    /**
+     * Builds request headers from enabled key-value pairs and body type defaults.
+     *
+     * Rejects hop-by-hop headers and fields containing control characters or CRLF.
+     *
+     * @param headers - User-defined headers.
+     * @param bodyType - Body type used to infer Content-Type when absent.
+     * @returns Header map ready for fetch, or an error when a field is invalid.
+     */
+    build(headers: KeyValue[], bodyType: BodyType): BuildHeadersResult;
+    /**
+     * Validates and merges a cookie jar header when no Cookie header is already present.
+     *
+     * @param headers - Mutable header map to update on success.
+     * @param cookieHeader - Optional Cookie header value from the cookie jar.
+     */
+    applyCookie(headers: Record<string, string>, cookieHeader: string | undefined): ApplyCookieResult;
+}
+//# sourceMappingURL=Headers.d.ts.map

package/dist/Headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Headers.d.ts","sourceRoot":"","sources":["../src/Headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGrF;;GAEG;AACH,qBAAa,OAAQ,YAAW,QAAQ;IACtC;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,kBAAkB;IAgClE;;;;;OAKG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,iBAAiB;CAcrB"}

package/dist/Headers.js

@@ -0,0 +1,62 @@
+import { validateHeaderField } from './httpHeaders.js';
+/**
+ * Builds request headers and merges cookie jar values for outbound requests.
+ */
+export class Headers {
+    /**
+     * Builds request headers from enabled key-value pairs and body type defaults.
+     *
+     * Rejects hop-by-hop headers and fields containing control characters or CRLF.
+     *
+     * @param headers - User-defined headers.
+     * @param bodyType - Body type used to infer Content-Type when absent.
+     * @returns Header map ready for fetch, or an error when a field is invalid.
+     */
+    build(headers, bodyType) {
+        const result = {};
+        for (const header of headers) {
+            if (header.enabled && header.key.trim()) {
+                const key = header.key.trim();
+                if (bodyType === 'multipart' && key.toLowerCase() === 'content-type') {
+                    continue;
+                }
+                const validationError = validateHeaderField(key, header.value);
+                if (validationError) {
+                    return { ok: false, error: validationError };
+                }
+                result[key] = header.value;
+            }
+        }
+        const hasContentType = Object.keys(result).some((key) => key.toLowerCase() === 'content-type');
+        if (!hasContentType) {
+            if (bodyType === 'json') {
+                result['Content-Type'] = 'application/json';
+            }
+            else if (bodyType === 'text') {
+                result['Content-Type'] = 'text/plain';
+            }
+            else if (bodyType === 'urlencoded') {
+                result['Content-Type'] = 'application/x-www-form-urlencoded';
+            }
+        }
+        return { ok: true, headers: result };
+    }
+    /**
+     * Validates and merges a cookie jar header when no Cookie header is already present.
+     *
+     * @param headers - Mutable header map to update on success.
+     * @param cookieHeader - Optional Cookie header value from the cookie jar.
+     */
+    applyCookie(headers, cookieHeader) {
+        const hasCookieHeader = Object.keys(headers).some((key) => key.toLowerCase() === 'cookie');
+        if (!cookieHeader || hasCookieHeader) {
+            return { ok: true };
+        }
+        const cookieError = validateHeaderField('Cookie', cookieHeader);
+        if (cookieError) {
+            return { ok: false, error: cookieError };
+        }
+        headers.Cookie = cookieHeader;
+        return { ok: true };
+    }
+}

package/dist/IBody.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Result of building a multipart request body.
+ */
+export type BuildMultipartResult = {
+    formData: FormData;
+} | {
+    error: string;
+};
+/**
+ * Request body encoding for multipart, urlencoded, and preview summaries.
+ */
+export interface IBody {
+    /**
+     * Builds a human-readable summary of multipart form parts for request preview.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     */
+    summarizeFormParts(body: string): string;
+    /**
+     * Builds a FormData body from serialized multipart form parts.
+     *
+     * @param body - Serialized multipart form parts JSON.
+     */
+    buildMultipart(body: string): Promise<BuildMultipartResult>;
+    /**
+     * Builds an application/x-www-form-urlencoded body from serialized key-value rows.
+     *
+     * @param body - JSON array stored in the request body field.
+     */
+    buildUrlEncoded(body: string): string;
+}
+//# sourceMappingURL=IBody.d.ts.map

package/dist/IBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IBody.d.ts","sourceRoot":"","sources":["../src/IBody.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzC;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE5D;;;;OAIG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC"}

package/dist/IBody.js

@@ -0,0 +1 @@
+export {};

package/dist/IHeaders.d.ts

@@ -0,0 +1,40 @@
+import type { BodyType, KeyValue } from './types.js';
+/**
+ * Result of building request headers from user input.
+ */
+export type BuildHeadersResult = {
+    ok: true;
+    headers: Record<string, string>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Result of merging a cookie jar header into a request header map.
+ */
+export type ApplyCookieResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Request header construction and cookie header merging.
+ */
+export interface IHeaders {
+    /**
+     * Builds request headers from enabled key-value pairs and body type defaults.
+     *
+     * @param headers - User-defined headers.
+     * @param bodyType - Body type used to infer Content-Type when absent.
+     */
+    build(headers: KeyValue[], bodyType: BodyType): BuildHeadersResult;
+    /**
+     * Validates and merges a cookie jar header when no Cookie header is already present.
+     *
+     * @param headers - Mutable header map to update on success.
+     * @param cookieHeader - Optional Cookie header value from the cookie jar.
+     */
+    applyCookie(headers: Record<string, string>, cookieHeader: string | undefined): ApplyCookieResult;
+}
+//# sourceMappingURL=IHeaders.d.ts.map

package/dist/IHeaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IHeaders.d.ts","sourceRoot":"","sources":["../src/IHeaders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,CAAC;IAEnE;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAAC;CACnG"}

package/dist/IHeaders.js

@@ -0,0 +1 @@
+export {};

package/dist/IQueryString.d.ts

@@ -0,0 +1,20 @@
+import type { KeyValue } from './types.js';
+/**
+ * URL query string building and validation for outbound HTTP requests.
+ */
+export interface IQueryString {
+    /**
+     * Appends enabled query parameters to a base URL.
+     *
+     * @param baseUrl - Request URL before query string merging.
+     * @param params - Key-value pairs to append as search params.
+     */
+    buildUrl(baseUrl: string, params: KeyValue[]): string;
+    /**
+     * Returns whether a URL is safe to send via fetch: absolute http(s) or root-relative path.
+     *
+     * @param url - Request URL before or after query string merging.
+     */
+    isValidRequestUrl(url: string): boolean;
+}
+//# sourceMappingURL=IQueryString.d.ts.map

package/dist/IQueryString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IQueryString.d.ts","sourceRoot":"","sources":["../src/IQueryString.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAEtD;;;;OAIG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC"}

package/dist/IQueryString.js

@@ -0,0 +1 @@
+export {};

package/dist/IRequester.d.ts

@@ -0,0 +1,17 @@
+import type { SendRequestInput, SendResult } from './types.js';
+import type { RequestSettings } from './settings.js';
+/**
+ * Executes outbound HTTP requests and returns timing and response metadata.
+ */
+export interface IRequester {
+    /**
+     * Executes an HTTP request via fetch and returns timing and response metadata.
+     *
+     * @param input - Method, URL, headers, params, body, and body type.
+     * @param settings - General request settings for timeout, size limits, SSL verification, and redirect following.
+     * @param signal - Optional abort signal to cancel the in-flight request.
+     * @param cookieHeader - Optional Cookie header value from the cookie jar.
+     */
+    executeRequest(input: SendRequestInput, settings?: RequestSettings, signal?: AbortSignal, cookieHeader?: string): Promise<SendResult>;
+}
+//# sourceMappingURL=IRequester.d.ts.map

package/dist/IRequester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRequester.d.ts","sourceRoot":"","sources":["../src/IRequester.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,cAAc,CACZ,KAAK,EAAE,gBAAgB,EACvB,QAAQ,CAAC,EAAE,eAAe,EAC1B,MAAM,CAAC,EAAE,WAAW,EACpB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB"}

package/dist/IRequester.js

@@ -0,0 +1 @@
+export {};

package/dist/IResponseReader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of reading a response body with size limits applied.
+ */
+export type ReadResponseBodyResult = {
+    body: string;
+    sizeBytes: number;
+    bodyBase64?: string;
+} | {
+    error: string;
+};
+/**
+ * Response body reading with configurable and hard size limits.
+ */
+export interface IResponseReader {
+    /**
+     * Resolves the effective response size limit in megabytes.
+     *
+     * @param maxResponseSizeMb - User setting; 0 means no configurable limit.
+     */
+    resolveMaxResponseSizeMb(maxResponseSizeMb: number): number;
+    /**
+     * Reads a response body, enforcing a max size in megabytes.
+     *
+     * @param response - Fetch response to read.
+     * @param maxResponseSizeMb - Maximum body size in MB; 0 uses the hard cap only.
+     */
+    read(response: Response, maxResponseSizeMb: number): Promise<ReadResponseBodyResult>;
+}
+//# sourceMappingURL=IResponseReader.d.ts.map

package/dist/IResponseReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResponseReader.d.ts","sourceRoot":"","sources":["../src/IResponseReader.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5D;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACtF"}

package/dist/IResponseReader.js

@@ -0,0 +1 @@
+export {};

package/dist/QueryString.d.ts

@@ -0,0 +1,40 @@
+import type { KeyValue } from './types.js';
+import type { IQueryString } from './IQueryString.js';
+/**
+ * Builds and validates URLs and query strings for outbound requests.
+ */
+export declare class QueryString implements IQueryString {
+    /**
+     * HTTP schemes allowed for outbound requests.
+     */
+    private static readonly ALLOWED_PROTOCOLS;
+    /**
+     * Returns whether a URL string is a root-relative path (`/api`), not protocol-relative (`//cdn`).
+     *
+     * @param url - Trimmed URL string.
+     */
+    private isRootRelativePath;
+    /**
+     * Appends query parameters via string concatenation for root-relative paths.
+     *
+     * @param trimmed - Trimmed base URL that failed absolute URL parsing.
+     * @param enabledParams - Enabled key-value pairs to append.
+     */
+    private appendQueryFallback;
+    /**
+     * Appends enabled query parameters to a base URL.
+     *
+     * @param baseUrl - Request URL before query string merging.
+     * @param params - Key-value pairs to append as search params.
+     * @returns URL with merged query parameters.
+     */
+    buildUrl(baseUrl: string, params: KeyValue[]): string;
+    /**
+     * Returns whether a URL is safe to send via fetch: absolute http(s) or root-relative path.
+     *
+     * @param url - Request URL before or after query string merging.
+     * @returns True when the URL uses http/https or is a root-relative path.
+     */
+    isValidRequestUrl(url: string): boolean;
+}
+//# sourceMappingURL=QueryString.d.ts.map

package/dist/QueryString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryString.d.ts","sourceRoot":"","sources":["../src/QueryString.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAEzE;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM;IAwBrD;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAUxC"}

package/dist/QueryString.js

@@ -0,0 +1,78 @@
+/**
+ * Builds and validates URLs and query strings for outbound requests.
+ */
+export class QueryString {
+    /**
+     * HTTP schemes allowed for outbound requests.
+     */
+    static ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+    /**
+     * Returns whether a URL string is a root-relative path (`/api`), not protocol-relative (`//cdn`).
+     *
+     * @param url - Trimmed URL string.
+     */
+    isRootRelativePath(url) {
+        return url.startsWith('/') && !url.startsWith('//');
+    }
+    /**
+     * Appends query parameters via string concatenation for root-relative paths.
+     *
+     * @param trimmed - Trimmed base URL that failed absolute URL parsing.
+     * @param enabledParams - Enabled key-value pairs to append.
+     */
+    appendQueryFallback(trimmed, enabledParams) {
+        const separator = trimmed.includes('?') ? '&' : '?';
+        const query = enabledParams
+            .map((p) => `${encodeURIComponent(p.key.trim())}=${encodeURIComponent(p.value)}`)
+            .join('&');
+        return `${trimmed}${separator}${query}`;
+    }
+    /**
+     * Appends enabled query parameters to a base URL.
+     *
+     * @param baseUrl - Request URL before query string merging.
+     * @param params - Key-value pairs to append as search params.
+     * @returns URL with merged query parameters.
+     */
+    buildUrl(baseUrl, params) {
+        const trimmed = baseUrl.trim();
+        if (!trimmed)
+            return trimmed;
+        const enabledParams = params.filter((p) => p.enabled && p.key.trim());
+        if (enabledParams.length === 0)
+            return trimmed;
+        try {
+            const url = new URL(trimmed);
+            if (!QueryString.ALLOWED_PROTOCOLS.has(url.protocol)) {
+                return trimmed;
+            }
+            for (const param of enabledParams) {
+                url.searchParams.set(param.key.trim(), param.value);
+            }
+            return url.toString();
+        }
+        catch {
+            if (!this.isRootRelativePath(trimmed)) {
+                return trimmed;
+            }
+            return this.appendQueryFallback(trimmed, enabledParams);
+        }
+    }
+    /**
+     * Returns whether a URL is safe to send via fetch: absolute http(s) or root-relative path.
+     *
+     * @param url - Request URL before or after query string merging.
+     * @returns True when the URL uses http/https or is a root-relative path.
+     */
+    isValidRequestUrl(url) {
+        const trimmed = url.trim();
+        if (!trimmed)
+            return false;
+        try {
+            return QueryString.ALLOWED_PROTOCOLS.has(new URL(trimmed).protocol);
+        }
+        catch {
+            return this.isRootRelativePath(trimmed);
+        }
+    }
+}

package/dist/Requester.d.ts

@@ -0,0 +1,100 @@
+import type { SendRequestInput, SendResult } from './types.js';
+import { type RequestSettings } from './settings.js';
+import type { IBody } from './IBody.js';
+import type { IHeaders } from './IHeaders.js';
+import type { IQueryString } from './IQueryString.js';
+import type { IRequester } from './IRequester.js';
+import type { IResponseReader } from './IResponseReader.js';
+/** HTTP status codes treated as redirects when following manually. */
+export declare const REDIRECT_STATUSES: Set<number>;
+/** Maximum redirect hops before returning an error. */
+export declare const MAX_REDIRECTS = 20;
+/**
+ * Optional collaborators injected into {@link IRequester} implementations.
+ */
+export interface RequesterDeps {
+    queryString?: IQueryString;
+    headers?: IHeaders;
+    body?: IBody;
+    responseReader?: IResponseReader;
+}
+/**
+ * Executes outbound HTTP requests via fetch with configurable collaborators.
+ */
+export declare class Requester implements IRequester {
+    private readonly queryString;
+    private readonly headers;
+    private readonly body;
+    private readonly responseReader;
+    /**
+     * Creates a requester with optional collaborators defaulting to the standard implementations.
+     *
+     * @param deps - Optional query string, header, body, and response reader implementations.
+     */
+    constructor(deps?: RequesterDeps);
+    /**
+     * Combines optional cancel and timeout signals for fetch.
+     *
+     * @param signal - Optional user cancel signal.
+     * @param timeoutMs - Request timeout in milliseconds; 0 disables timeout.
+     */
+    private buildEffectiveSignal;
+    /**
+     * Maps fetch errors to user-facing messages.
+     *
+     * @param err - Thrown fetch error.
+     * @param timeoutMs - Configured request timeout in milliseconds.
+     */
+    private mapFetchError;
+    /**
+     * Returns a shared undici Agent that skips TLS certificate verification.
+     */
+    private getInsecureDispatcher;
+    /**
+     * Builds a failed {@link SendResult} with consistent error fields.
+     *
+     * @param error - User-facing error message.
+     * @param request - Sent request metadata captured before or during the attempt.
+     * @param timeMs - Elapsed time in milliseconds.
+     * @param responseHeaders - Optional response headers when available before failure.
+     * @param setCookieHeaders - Optional Set-Cookie headers from the response.
+     */
+    private errorResult;
+    /**
+     * Logs the outbound request when very-verbose mode is enabled.
+     *
+     * Records the HTTP verb, resolved URL, request headers, body type, and request
+     * body. Response headers and response bodies are intentionally omitted.
+     *
+     * @param request - Final request metadata sent to fetch.
+     */
+    private logOutgoingRequest;
+    /**
+     * Builds the fetch request body for one hop.
+     *
+     * @param input - Original send input (body source).
+     * @param bodyType - Body type for this hop.
+     * @param shouldSendBody - Whether a body should be attached.
+     */
+    private buildRequestBody;
+    /**
+     * Resolves the fetch dispatcher from general settings.
+     *
+     * @param settings - General request settings.
+     */
+    private resolveDispatcher;
+    /**
+     * Executes an HTTP request via fetch and returns timing and response metadata.
+     *
+     * When redirect following is enabled, 3xx responses are followed manually so
+     * each hop can be recorded in {@link SendResult.redirects}.
+     *
+     * @param input - Method, URL, headers, params, body, and body type.
+     * @param settings - General request settings for timeout, size limits, SSL verification, and redirect following.
+     * @param signal - Optional abort signal to cancel the in-flight request.
+     * @param cookieHeader - Optional Cookie header value from the cookie jar.
+     * @returns Response status, headers, body, timing, size, and optional redirect chain; error field on failure.
+     */
+    executeRequest(input: SendRequestInput, settings?: RequestSettings, signal?: AbortSignal, cookieHeader?: string): Promise<SendResult>;
+}
+//# sourceMappingURL=Requester.d.ts.map