nlcurl 0.7.0 → 0.8.0

package/dist/core/request.d.ts

@@ -6,13 +6,11 @@ import type { CacheConfig, CacheMode } from "../cache/types.js";
 import type { HSTSConfig } from "../hsts/types.js";
 import type { DNSConfig } from "../dns/types.js";
 import type { ECHOptions } from "../tls/ech.js";
+import type { AuthConfig } from "./auth.js";
+import type { EarlyHintsCallback } from "../http/early-hints.js";
+import type { RequestEncoding } from "../utils/compression.js";
 /**
- * Progress event data emitted during upload or download.
- *
- * @typedef  {Object}  ProgressEvent
- * @property {number}  bytes      - Bytes transferred so far.
- * @property {number}  totalBytes - Total bytes expected (`0` if unknown).
- * @property {number}  percent    - Completion percentage (`0`–`100`), or `0` if total is unknown.
+ * Describes the progress of an upload or download operation.
  */
 export interface ProgressEvent {
     bytes: number;
@@ -20,28 +18,18 @@ export interface ProgressEvent {
     percent: number;
 }
 /**
- * Callback invoked during data transfer to report progress.
+ * Callback invoked during upload or download progress.
  *
  * @callback ProgressCallback
- * @param {ProgressEvent} event - Current transfer progress.
+ * @param {ProgressEvent} event - The current progress snapshot.
  */
 export type ProgressCallback = (event: ProgressEvent) => void;
 /**
- * Union of all HTTP method strings accepted by the library.
- *
- * @typedef {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'|'HEAD'|'OPTIONS'} HttpMethod
+ * Supported HTTP request methods.
  */
-export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
 /**
- * Granular timing measurements recorded during a single request, in
- * milliseconds elapsed from request initiation.
- *
- * @typedef  {Object} RequestTimings
- * @property {number} dns       - Time spent resolving the hostname via DNS.
- * @property {number} connect   - Time spent establishing the TCP connection.
- * @property {number} tls       - Time spent completing the TLS handshake.
- * @property {number} firstByte - Time from connection open to the first response byte received.
- * @property {number} total     - Total wall-clock time for the entire request.
+ * Timing measurements for each phase of a request lifecycle, in milliseconds.
  */
 export interface RequestTimings {
     dns: number;
@@ -51,14 +39,7 @@ export interface RequestTimings {
     total: number;
 }
 /**
- * Per-phase timeout limits for a single request, in milliseconds. Omitting
- * a field means no limit is applied for that phase.
- *
- * @typedef  {Object}  TimeoutConfig
- * @property {number}  [connect]  - Maximum milliseconds to establish the TCP connection.
- * @property {number}  [tls]      - Maximum milliseconds to complete the TLS handshake.
- * @property {number}  [response] - Maximum milliseconds to receive the first response byte.
- * @property {number}  [total]    - Maximum total milliseconds for the whole request.
+ * Per-phase timeout thresholds for a request, in milliseconds.
  */
 export interface TimeoutConfig {
     connect?: number;
@@ -67,42 +48,12 @@ export interface TimeoutConfig {
     total?: number;
 }
 /**
- * Accepted body types for an outgoing request. Arrays, plain objects, and
- * plain strings are serialized automatically; raw `Buffer`s and
- * `URLSearchParams` are used verbatim.
- *
- * @typedef {string|Buffer|URLSearchParams|Record<string,unknown>|ReadableStream<Uint8Array>|null} RequestBody
+ * Acceptable request body types for outgoing HTTP requests.
  */
 export type RequestBody = string | Buffer | URLSearchParams | Record<string, unknown> | ReadableStream<Uint8Array> | FormData | null;
 /**
- * Describes a single HTTP request. All options at the request level override
- * any matching session-level defaults set on {@link NLcURLSessionConfig}.
- *
- * @typedef  {Object}                          NLcURLRequest
- * @property {string}                          url              - Absolute or relative URL to request.
- * @property {HttpMethod}                      [method='GET']   - HTTP method.
- * @property {Record<string,string>}           [headers]        - Request headers to merge with session defaults.
- * @property {RequestBody}                     [body]           - Request body payload.
- * @property {number|TimeoutConfig}            [timeout]        - Timeout in ms (flat) or per-phase config object.
- * @property {AbortSignal}                     [signal]         - Signal used to cancel the request early.
- * @property {string}                          [impersonate]    - Browser profile name (e.g. `"chrome136"`).
- * @property {string}                          [ja3]            - Custom JA3 fingerprint string override.
- * @property {string}                          [akamai]         - Custom Akamai HTTP/2 fingerprint override.
- * @property {boolean}                         [stealth]        - Use the custom stealth TLS engine.
- * @property {boolean}                         [followRedirects=true]  - Follow HTTP redirects automatically.
- * @property {number}                          [maxRedirects=20]       - Maximum number of redirects to follow.
- * @property {boolean}                         [insecure]       - Skip TLS certificate verification.
- * @property {string}                          [proxy]          - Proxy URL (`http://`, `socks4://`, `socks5://`).
- * @property {[string,string]}                 [proxyAuth]      - Proxy credentials as `[username, password]`.
- * @property {'1.1'|'2'}                       [httpVersion]    - Force a specific HTTP protocol version.
- * @property {string}                          [baseURL]        - Base URL prepended to relative `url` values.
- * @property {Record<string,string|number|boolean>} [params]   - Query parameters appended to the URL.
- * @property {boolean|string}                  [cookieJar]      - Enable a per-request cookie jar.
- * @property {string}                          [acceptEncoding] - Override the `Accept-Encoding` header value.
- * @property {string[]}                        [headerOrder]    - Explicit header ordering for fingerprinting.
- * @property {4|6}                             [dnsFamily]      - Force IPv4 (`4`) or IPv6 (`6`) DNS resolution.
- * @property {boolean}                         [stream]         - Return a streaming response body.
- * @property {Logger}                          [logger]         - Logger instance for request-scoped diagnostics.
+ * Full request descriptor for a single HTTP request, including URL, method,
+ * headers, body, TLS fingerprinting, proxy, caching, and timeout options.
  */
 export interface NLcURLRequest {
     url: string;
@@ -130,29 +81,21 @@ export interface NLcURLRequest {
     stream?: boolean;
     logger?: Logger;
     tls?: TLSOptions;
-    /** DNS-over-HTTPS configuration for this request. Overrides session-level DNS config. */
     dns?: DNSConfig;
-    /** Encrypted Client Hello (ECH) options for this request. */
     ech?: ECHOptions;
     onUploadProgress?: ProgressCallback;
     onDownloadProgress?: ProgressCallback;
     throwOnError?: boolean;
-    /** HTTP cache mode for this request. Overrides session-level cache config. */
     cache?: CacheMode;
-    /**
-     * Range header value for partial content requests (RFC 9110 §14).
-     * Example: `"bytes=0-499"` or `"bytes=500-999"` or `"bytes=-500"`.
-     */
     range?: string;
+    auth?: AuthConfig;
+    onEarlyHints?: EarlyHintsCallback;
+    expect100Continue?: boolean;
+    compressBody?: RequestEncoding;
+    methodOverride?: "QUERY";
 }
 /**
- * Server-Sent Event parsed from an SSE stream (W3C EventSource specification).
- *
- * @typedef  {Object}  ServerSentEvent
- * @property {string}  event - Event type (defaults to `"message"`).
- * @property {string}  data  - Event data payload.
- * @property {string}  id    - Last event ID.
- * @property {number|undefined} retry - Reconnection time in ms suggested by the server.
+ * Represents a single server-sent event from an SSE stream.
  */
 export interface ServerSentEvent {
     event: string;
@@ -161,14 +104,7 @@ export interface ServerSentEvent {
     retry?: number;
 }
 /**
- * Configuration for automatic request retry with backoff.
- *
- * @typedef  {Object}   RetryConfig
- * @property {number}   count      - Maximum number of retry attempts after the initial request.
- * @property {number}   delay      - Base delay in milliseconds between attempts.
- * @property {'linear'|'exponential'} backoff - Strategy for increasing the delay on repeated failures.
- * @property {number}   jitter     - Maximum random jitter in milliseconds added to each delay.
- * @property {Function} [retryOn]  - Optional predicate; return `true` to allow a retry.
+ * Configuration for automatic request retry behavior.
  */
 export interface RetryConfig {
     count: number;
@@ -178,28 +114,7 @@ export interface RetryConfig {
     retryOn?: (error: Error | null, statusCode?: number) => boolean;
 }
 /**
- * Session-level defaults applied to every request issued through an
- * {@link NLcURLSession}. Individual request options always take precedence.
- *
- * @typedef  {Object}                NLcURLSessionConfig
- * @property {string}                [baseURL]        - Base URL prepended to relative request URLs.
- * @property {Record<string,string>} [headers]        - Headers merged into every request.
- * @property {number|TimeoutConfig}  [timeout]        - Default timeout applied to all requests.
- * @property {string}                [impersonate]    - Default browser profile for fingerprinting.
- * @property {string}                [ja3]            - Default JA3 fingerprint string.
- * @property {string}                [akamai]         - Default Akamai HTTP/2 fingerprint.
- * @property {boolean}               [stealth]        - Use the stealth TLS engine by default.
- * @property {string}                [proxy]          - Default proxy URL.
- * @property {[string,string]}       [proxyAuth]      - Default proxy credentials.
- * @property {boolean}               [followRedirects=true] - Follow redirects by default.
- * @property {number}                [maxRedirects=20]      - Default maximum redirect count.
- * @property {boolean}               [insecure]       - Skip TLS verification by default.
- * @property {'1.1'|'2'}             [httpVersion]    - Force an HTTP protocol version for all requests.
- * @property {boolean|string}        [cookieJar]      - Persistent cookie jar for the session.
- * @property {Partial<RetryConfig>}  [retry]          - Automatic retry configuration.
- * @property {string}                [acceptEncoding] - Default `Accept-Encoding` header value.
- * @property {4|6}                   [dnsFamily]      - Force IPv4 or IPv6 for DNS resolution.
- * @property {Logger}                [logger]         - Logger instance for session-scoped diagnostics.
+ * Session-level configuration shared across all requests in a session.
  */
 export interface NLcURLSessionConfig {
     baseURL?: string;
@@ -224,15 +139,12 @@ export interface NLcURLSessionConfig {
     throwOnError?: boolean;
     onUploadProgress?: ProgressCallback;
     onDownloadProgress?: ProgressCallback;
-    /** HTTP cache configuration for the session (RFC 9111). */
     cacheConfig?: CacheConfig;
-    /** HSTS configuration for the session (RFC 6797). */
     hsts?: HSTSConfig;
-    /** DNS-over-HTTPS configuration for the session (RFC 8484). */
     dns?: DNSConfig;
-    /** Encrypted Client Hello (ECH) configuration for the session (draft-ietf-tls-esni). */
     ech?: ECHOptions;
-    /** Enable Alt-Svc (RFC 7838) for automatic HTTP/3 discovery. @default true */
     altSvc?: boolean;
+    auth?: AuthConfig;
+    compressBody?: RequestEncoding;
 }
 //# sourceMappingURL=request.d.ts.map

package/dist/core/request.d.ts.map

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

package/dist/core/response.d.ts

@@ -1,67 +1,53 @@
 import type { RequestTimings, HttpMethod } from "./request.js";
 import type { Readable } from "node:stream";
 /**
- * Metadata about the originating request that produced a response.
- *
- * @typedef  {Object}              ResponseMeta
- * @property {string}              url     - The final URL after all redirects.
- * @property {HttpMethod}          method  - The HTTP method used for the request.
- * @property {Record<string,string>} headers - The request headers that were sent.
- * @property {string}              [command] - An optional cURL-equivalent command string for debugging.
+ * Metadata about the request that produced a given response.
  */
 export interface ResponseMeta {
     url: string;
     method: HttpMethod;
     headers: Record<string, string>;
     command?: string;
+    tlsVersion?: string;
+    tlsCipher?: string;
+    alpnProtocol?: string;
 }
 /**
- * Represents the complete HTTP response from a successful request. Provides
- * convenience accessors for common content-type parsing, streaming, and
- * header inspection.
+ * Encapsulates an HTTP response with status, headers, body, timing data,
+ * and convenience accessors for common header values and body parsing.
  *
- * @template T - Expected shape of the JSON-decoded body when calling {@link NLcURLResponse.json}.
+ * @class
+ * @template T - The expected JSON body type.
  */
 export declare class NLcURLResponse<T = unknown> {
-    /** HTTP status code (e.g. `200`, `404`). */
+    /** The HTTP status code. */
     readonly status: number;
-    /** HTTP status text (e.g. `"OK"`, `"Not Found"`). */
+    /** The HTTP reason phrase. */
     readonly statusText: string;
-    /** Normalized, lowercase response headers. Duplicate values are joined by `, `. */
+    /** Response headers as a case-insensitive key-value map. */
     readonly headers: Record<string, string>;
-    /** All response header name-value pairs exactly as received, in transmission order. */
+    /** Raw header pairs preserving original casing and duplicates. */
     readonly rawHeaders: Array<[string, string]>;
-    /** Fully buffered response body. Empty when the response was opened in streaming mode. */
+    /** The full response body as a Buffer. */
     readonly rawBody: Buffer;
-    /** Readable stream of the response body, or `null` for buffered responses. */
+    /** A readable stream for streaming responses, or `null` for buffered responses. */
     readonly body: Readable | null;
-    /** HTTP protocol version string (e.g. `"HTTP/1.1"`, `"HTTP/2.0"`). */
+    /** The negotiated HTTP version (e.g. "1.1", "2"). */
     readonly httpVersion: string;
-    /** Final URL of the response after any redirects. */
+    /** The final URL after any redirects. */
     readonly url: string;
-    /** Number of redirects followed before this response was received. */
+    /** The number of redirects followed to reach this response. */
     readonly redirectCount: number;
-    /** Granular timing measurements for each phase of the request lifecycle. */
+    /** Timing measurements for each request phase. */
     readonly timings: RequestTimings;
     /** Metadata about the originating request. */
     readonly request: ResponseMeta;
     private _json;
     private _text;
     /**
-     * Creates a new NLcURLResponse instance.
+     * Creates a new NLcURLResponse from the provided initialization fields.
      *
-     * @param {Object}                         init                 - Response initialization data.
-     * @param {number}                         init.status          - HTTP status code.
-     * @param {string}                         init.statusText      - HTTP status text.
-     * @param {Record<string,string>}          init.headers         - Normalized response headers.
-     * @param {Array<[string,string]>}         [init.rawHeaders]    - Raw header pairs; defaults to entries of `headers`.
-     * @param {Buffer}                         init.rawBody         - Fully buffered response body.
-     * @param {Readable|null}                  [init.body]          - Streaming body, or `null`.
-     * @param {string}                         init.httpVersion     - Protocol version string.
-     * @param {string}                         init.url             - Final URL after redirects.
-     * @param {number}                         init.redirectCount   - Number of redirects followed.
-     * @param {RequestTimings}                 init.timings         - Lifecycle timing measurements.
-     * @param {ResponseMeta}                   init.request         - Originating request metadata.
+     * @param {Object} init - Response initialization fields.
      */
     constructor(init: {
         status: number;
@@ -77,77 +63,74 @@ export declare class NLcURLResponse<T = unknown> {
         request: ResponseMeta;
     });
     /**
-     * Returns `true` when the HTTP status code is in the 200–299 (successful)
-     * range, `false` otherwise.
+     * Returns `true` if the response status is in the 2xx range.
      *
      * @returns {boolean} Whether the response indicates success.
      */
     get ok(): boolean;
     /**
-     * Decodes the raw body as a UTF-8 string and returns it. The result is
-     * memoized after the first call.
+     * Decodes the raw body as a UTF-8 string. Throws if the response is streaming.
      *
-     * @returns {string} The response body decoded as UTF-8.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @returns {string} The response body as text.
+     * @throws {Error} If the response is a streaming response.
      */
     text(): string;
     /**
-     * Parses the raw body as JSON and returns the decoded value. The result is
-     * memoized after the first call.
+     * Parses the response body as JSON. Throws if the response is streaming.
      *
-     * @template R - Expected type of the decoded JSON value; defaults to `T`.
-     * @returns {R} The JSON-decoded response body.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @template R - The expected parsed type.
+     * @returns {R} The parsed JSON value.
+     * @throws {Error} If the response is a streaming response.
      * @throws {SyntaxError} If the body is not valid JSON.
-     *
-     * @example
-     * const data = response.json<{ id: number; name: string }>();
-     * console.log(data.id);
      */
     json<R = T>(): R;
     /**
-     * Returns the `Content-Length` as a number. Falls back to the buffer byte
-     * length when the header is absent or unparseable.
+     * Returns the Content-Length header value, or the raw body length as a fallback.
      *
      * @returns {number} The content length in bytes.
      */
     get contentLength(): number;
     /**
-     * Returns the value of the `Content-Type` response header, or an empty
-     * string when the header is absent.
+     * Returns the Content-Type header value.
      *
-     * @returns {string} The `Content-Type` header value.
+     * @returns {string} The content type, or an empty string if absent.
      */
     get contentType(): string;
     /**
-     * Returns the `ETag` response header value, or `undefined` when absent.
+     * Returns the ETag header value, if present.
+     *
+     * @returns {string|undefined} The entity tag.
      */
     get etag(): string | undefined;
     /**
-     * Returns the `Last-Modified` response header value, or `undefined` when absent.
+     * Returns the Last-Modified header value, if present.
+     *
+     * @returns {string|undefined} The last modified date string.
      */
     get lastModified(): string | undefined;
     /**
-     * Returns the `Cache-Control` response header value, or `undefined` when absent.
+     * Returns the Cache-Control header value, if present.
+     *
+     * @returns {string|undefined} The cache control directive string.
      */
     get cacheControl(): string | undefined;
     /**
-     * Returns the `Content-Range` response header value, or `undefined` when absent.
-     * Present on 206 Partial Content responses (RFC 9110 §14.4).
+     * Returns the Content-Range header value, if present.
+     *
+     * @returns {string|undefined} The content range descriptor.
      */
     get contentRange(): string | undefined;
     /**
-     * Returns the `Accept-Ranges` response header value, or `undefined` when absent.
-     * Indicates whether the server supports range requests (RFC 9110 §14.3).
+     * Returns the Accept-Ranges header value, if present.
+     *
+     * @returns {string|undefined} The accepted range unit.
      */
     get acceptRanges(): string | undefined;
     /**
-     * Returns all values for a response header, in transmission order,
-     * supporting multi-value headers such as `Set-Cookie` which are joined
-     * when accessed through `headers`.
+     * Retrieves all values for a given header name from the raw headers array.
      *
-     * @param {string} name - The case-insensitive header name to look up.
-     * @returns {string[]} All header values for the given name, or an empty array.
+     * @param {string} name - The header name (case-insensitive).
+     * @returns {string[]} All values for the specified header.
      */
     getAll(name: string): string[];
 }

package/dist/core/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO;IACrC,4CAA4C;IAC5C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,qDAAqD;IACrD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,mFAAmF;IACnF,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,uFAAuF;IACvF,SAAgB,UAAU,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,0FAA0F;IAC1F,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,8EAA8E;IAC9E,SAAgB,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtC,sEAAsE;IACtE,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,qDAAqD;IACrD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,4EAA4E;IAC5E,SAAgB,OAAO,EAAE,cAAc,CAAC;IACxC,8CAA8C;IAC9C,SAAgB,OAAO,EAAE,YAAY,CAAC;IAEtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAqB;IAElC;;;;;;;;;;;;;;;OAeG;gBACS,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE;IAcjR;;;;;OAKG;IACH,IAAI,EAAE,IAAI,OAAO,CAEhB;IAED;;;;;;OAMG;IACH,IAAI,IAAI,MAAM;IAYd;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAUhB;;;;;OAKG;IACH,IAAI,aAAa,IAAI,MAAM,CAO1B;IAED;;;;;OAKG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAI/B"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO;IACrC,4BAA4B;IAC5B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,8BAA8B;IAC9B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,4DAA4D;IAC5D,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,kEAAkE;IAClE,SAAgB,UAAU,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,0CAA0C;IAC1C,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,mFAAmF;IACnF,SAAgB,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtC,qDAAqD;IACrD,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,yCAAyC;IACzC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,kDAAkD;IAClD,SAAgB,OAAO,EAAE,cAAc,CAAC;IACxC,8CAA8C;IAC9C,SAAgB,OAAO,EAAE,YAAY,CAAC;IAEtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAqB;IAElC;;;;OAIG;gBACS,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE;IAcjR;;;;OAIG;IACH,IAAI,EAAE,IAAI,OAAO,CAEhB;IAED;;;;;OAKG;IACH,IAAI,IAAI,MAAM;IAYd;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAUhB;;;;OAIG;IACH,IAAI,aAAa,IAAI,MAAM,CAO1B;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAI/B"}

package/dist/core/response.js

@@ -1,50 +1,39 @@
 /**
- * Represents the complete HTTP response from a successful request. Provides
- * convenience accessors for common content-type parsing, streaming, and
- * header inspection.
+ * Encapsulates an HTTP response with status, headers, body, timing data,
+ * and convenience accessors for common header values and body parsing.
  *
- * @template T - Expected shape of the JSON-decoded body when calling {@link NLcURLResponse.json}.
+ * @class
+ * @template T - The expected JSON body type.
  */
 export class NLcURLResponse {
-    /** HTTP status code (e.g. `200`, `404`). */
+    /** The HTTP status code. */
     status;
-    /** HTTP status text (e.g. `"OK"`, `"Not Found"`). */
+    /** The HTTP reason phrase. */
     statusText;
-    /** Normalized, lowercase response headers. Duplicate values are joined by `, `. */
+    /** Response headers as a case-insensitive key-value map. */
     headers;
-    /** All response header name-value pairs exactly as received, in transmission order. */
+    /** Raw header pairs preserving original casing and duplicates. */
     rawHeaders;
-    /** Fully buffered response body. Empty when the response was opened in streaming mode. */
+    /** The full response body as a Buffer. */
     rawBody;
-    /** Readable stream of the response body, or `null` for buffered responses. */
+    /** A readable stream for streaming responses, or `null` for buffered responses. */
     body;
-    /** HTTP protocol version string (e.g. `"HTTP/1.1"`, `"HTTP/2.0"`). */
+    /** The negotiated HTTP version (e.g. "1.1", "2"). */
     httpVersion;
-    /** Final URL of the response after any redirects. */
+    /** The final URL after any redirects. */
     url;
-    /** Number of redirects followed before this response was received. */
+    /** The number of redirects followed to reach this response. */
     redirectCount;
-    /** Granular timing measurements for each phase of the request lifecycle. */
+    /** Timing measurements for each request phase. */
     timings;
     /** Metadata about the originating request. */
     request;
     _json;
     _text;
     /**
-     * Creates a new NLcURLResponse instance.
+     * Creates a new NLcURLResponse from the provided initialization fields.
      *
-     * @param {Object}                         init                 - Response initialization data.
-     * @param {number}                         init.status          - HTTP status code.
-     * @param {string}                         init.statusText      - HTTP status text.
-     * @param {Record<string,string>}          init.headers         - Normalized response headers.
-     * @param {Array<[string,string]>}         [init.rawHeaders]    - Raw header pairs; defaults to entries of `headers`.
-     * @param {Buffer}                         init.rawBody         - Fully buffered response body.
-     * @param {Readable|null}                  [init.body]          - Streaming body, or `null`.
-     * @param {string}                         init.httpVersion     - Protocol version string.
-     * @param {string}                         init.url             - Final URL after redirects.
-     * @param {number}                         init.redirectCount   - Number of redirects followed.
-     * @param {RequestTimings}                 init.timings         - Lifecycle timing measurements.
-     * @param {ResponseMeta}                   init.request         - Originating request metadata.
+     * @param {Object} init - Response initialization fields.
      */
     constructor(init) {
         this.status = init.status;
@@ -60,8 +49,7 @@ export class NLcURLResponse {
         this.request = init.request;
     }
     /**
-     * Returns `true` when the HTTP status code is in the 200–299 (successful)
-     * range, `false` otherwise.
+     * Returns `true` if the response status is in the 2xx range.
      *
      * @returns {boolean} Whether the response indicates success.
      */
@@ -69,11 +57,10 @@ export class NLcURLResponse {
         return this.status >= 200 && this.status < 300;
     }
     /**
-     * Decodes the raw body as a UTF-8 string and returns it. The result is
-     * memoized after the first call.
+     * Decodes the raw body as a UTF-8 string. Throws if the response is streaming.
      *
-     * @returns {string} The response body decoded as UTF-8.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @returns {string} The response body as text.
+     * @throws {Error} If the response is a streaming response.
      */
     text() {
         if (this.body) {
@@ -87,17 +74,12 @@ export class NLcURLResponse {
         return cached;
     }
     /**
-     * Parses the raw body as JSON and returns the decoded value. The result is
-     * memoized after the first call.
+     * Parses the response body as JSON. Throws if the response is streaming.
      *
-     * @template R - Expected type of the decoded JSON value; defaults to `T`.
-     * @returns {R} The JSON-decoded response body.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @template R - The expected parsed type.
+     * @returns {R} The parsed JSON value.
+     * @throws {Error} If the response is a streaming response.
      * @throws {SyntaxError} If the body is not valid JSON.
-     *
-     * @example
-     * const data = response.json<{ id: number; name: string }>();
-     * console.log(data.id);
      */
     json() {
         if (this.body) {
@@ -109,8 +91,7 @@ export class NLcURLResponse {
         return this._json;
     }
     /**
-     * Returns the `Content-Length` as a number. Falls back to the buffer byte
-     * length when the header is absent or unparseable.
+     * Returns the Content-Length header value, or the raw body length as a fallback.
      *
      * @returns {number} The content length in bytes.
      */
@@ -124,53 +105,58 @@ export class NLcURLResponse {
         return this.rawBody.length;
     }
     /**
-     * Returns the value of the `Content-Type` response header, or an empty
-     * string when the header is absent.
+     * Returns the Content-Type header value.
      *
-     * @returns {string} The `Content-Type` header value.
+     * @returns {string} The content type, or an empty string if absent.
      */
     get contentType() {
         return this.headers["content-type"] ?? "";
     }
     /**
-     * Returns the `ETag` response header value, or `undefined` when absent.
+     * Returns the ETag header value, if present.
+     *
+     * @returns {string|undefined} The entity tag.
      */
     get etag() {
         return this.headers["etag"];
     }
     /**
-     * Returns the `Last-Modified` response header value, or `undefined` when absent.
+     * Returns the Last-Modified header value, if present.
+     *
+     * @returns {string|undefined} The last modified date string.
      */
     get lastModified() {
         return this.headers["last-modified"];
     }
     /**
-     * Returns the `Cache-Control` response header value, or `undefined` when absent.
+     * Returns the Cache-Control header value, if present.
+     *
+     * @returns {string|undefined} The cache control directive string.
      */
     get cacheControl() {
         return this.headers["cache-control"];
     }
     /**
-     * Returns the `Content-Range` response header value, or `undefined` when absent.
-     * Present on 206 Partial Content responses (RFC 9110 §14.4).
+     * Returns the Content-Range header value, if present.
+     *
+     * @returns {string|undefined} The content range descriptor.
      */
     get contentRange() {
         return this.headers["content-range"];
     }
     /**
-     * Returns the `Accept-Ranges` response header value, or `undefined` when absent.
-     * Indicates whether the server supports range requests (RFC 9110 §14.3).
+     * Returns the Accept-Ranges header value, if present.
+     *
+     * @returns {string|undefined} The accepted range unit.
      */
     get acceptRanges() {
         return this.headers["accept-ranges"];
     }
     /**
-     * Returns all values for a response header, in transmission order,
-     * supporting multi-value headers such as `Set-Cookie` which are joined
-     * when accessed through `headers`.
+     * Retrieves all values for a given header name from the raw headers array.
      *
-     * @param {string} name - The case-insensitive header name to look up.
-     * @returns {string[]} All header values for the given name, or an empty array.
+     * @param {string} name - The header name (case-insensitive).
+     * @returns {string[]} All values for the specified header.
      */
     getAll(name) {
         const lower = name.toLowerCase();