nlcurl 0.1.0 → 0.2.0

package/dist/core/response.d.ts

@@ -1,48 +1,132 @@
+import type { RequestTimings, HttpMethod } from './request.js';
+import type { Readable } from 'node:stream';
 /**
- * NLcURL response model.
+ * 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.
  */
-import type { RequestTimings, HttpMethod } from './request.js';
 export interface ResponseMeta {
     url: string;
     method: HttpMethod;
     headers: Record<string, string>;
     command?: string;
 }
+/**
+ * Represents the complete HTTP response from a successful request. Provides
+ * convenience accessors for common content-type parsing, streaming, and
+ * header inspection.
+ *
+ * @template T - Expected shape of the JSON-decoded body when calling {@link NLcURLResponse.json}.
+ */
 export declare class NLcURLResponse<T = unknown> {
+    /** HTTP status code (e.g. `200`, `404`). */
     readonly status: number;
+    /** HTTP status text (e.g. `"OK"`, `"Not Found"`). */
     readonly statusText: string;
+    /** Normalized, lowercase response headers. Duplicate values are joined by `, `. */
     readonly headers: Record<string, string>;
-    /** Raw header pairs preserving duplicates (e.g. multiple Set-Cookie). */
+    /** All response header name-value pairs exactly as received, in transmission order. */
     readonly rawHeaders: Array<[string, string]>;
+    /** Fully buffered response body. Empty when the response was opened in streaming mode. */
     readonly rawBody: Buffer;
+    /** Readable stream of the response body, or `null` for buffered responses. */
+    readonly body: Readable | null;
+    /** HTTP protocol version string (e.g. `"HTTP/1.1"`, `"HTTP/2.0"`). */
     readonly httpVersion: string;
+    /** Final URL of the response after any redirects. */
     readonly url: string;
+    /** Number of redirects followed before this response was received. */
     readonly redirectCount: number;
+    /** Granular timing measurements for each phase of the request lifecycle. */
     readonly timings: RequestTimings;
+    /** Metadata about the originating request. */
     readonly request: ResponseMeta;
     private _json;
     private _text;
+    /**
+     * Creates a new NLcURLResponse instance.
+     *
+     * @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.
+     */
     constructor(init: {
         status: number;
         statusText: string;
         headers: Record<string, string>;
         rawHeaders?: Array<[string, string]>;
         rawBody: Buffer;
+        body?: Readable | null;
         httpVersion: string;
         url: string;
         redirectCount: number;
         timings: RequestTimings;
         request: ResponseMeta;
     });
-    /** Whether the status code is 2xx. */
+    /**
+     * Returns `true` when the HTTP status code is in the 200–299 (successful)
+     * range, `false` otherwise.
+     *
+     * @returns {boolean} Whether the response indicates success.
+     */
     get ok(): boolean;
-    /** Decode the body as UTF-8 text. Result is cached. */
+    /**
+     * Decodes the raw body as a UTF-8 string and returns it. The result is
+     * memoized after the first call.
+     *
+     * @returns {string} The response body decoded as UTF-8.
+     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     */
     text(): string;
-    /** Parse the body as JSON. Result is cached. Throws on invalid JSON. */
+    /**
+     * Parses the raw body as JSON and returns the decoded value. The result is
+     * memoized after the first call.
+     *
+     * @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`).
+     * @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;
-    /** Content-Length as reported by the server, or the actual body size. */
+    /**
+     * Returns the `Content-Length` as a number. Falls back to the buffer byte
+     * length when the header is absent or unparseable.
+     *
+     * @returns {number} The content length in bytes.
+     */
     get contentLength(): number;
-    /** Shorthand for the content-type header value. */
+    /**
+     * Returns the value of the `Content-Type` response header, or an empty
+     * string when the header is absent.
+     *
+     * @returns {string} The `Content-Type` header value.
+     */
     get contentType(): string;
+    /**
+     * 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`.
+     *
+     * @param {string} name - The case-insensitive header name to look up.
+     * @returns {string[]} All header values for the given name, or an empty array.
+     */
+    getAll(name: string): string[];
 }
 //# sourceMappingURL=response.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D,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,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO;IACrC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,yEAAyE;IACzE,SAAgB,UAAU,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,OAAO,EAAE,cAAc,CAAC;IACxC,SAAgB,OAAO,EAAE,YAAY,CAAC;IAEtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAqB;gBAEtB,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACrC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,cAAc,CAAC;QACxB,OAAO,EAAE,YAAY,CAAC;KACvB;IAaD,sCAAsC;IACtC,IAAI,EAAE,IAAI,OAAO,CAEhB;IAED,uDAAuD;IACvD,IAAI,IAAI,MAAM;IASd,wEAAwE;IACxE,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAOhB,yEAAyE;IACzE,IAAI,aAAa,IAAI,MAAM,CAO1B;IAED,mDAAmD;IACnD,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AACA,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;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACrC,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,cAAc,CAAC;QACxB,OAAO,EAAE,YAAY,CAAC;KACvB;IAcD;;;;;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;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAM/B"}

package/dist/core/response.js

@@ -1,38 +1,84 @@
 /**
- * NLcURL response model.
+ * Represents the complete HTTP response from a successful request. Provides
+ * convenience accessors for common content-type parsing, streaming, and
+ * header inspection.
+ *
+ * @template T - Expected shape of the JSON-decoded body when calling {@link NLcURLResponse.json}.
  */
 export class NLcURLResponse {
+    /** HTTP status code (e.g. `200`, `404`). */
     status;
+    /** HTTP status text (e.g. `"OK"`, `"Not Found"`). */
     statusText;
+    /** Normalized, lowercase response headers. Duplicate values are joined by `, `. */
     headers;
-    /** Raw header pairs preserving duplicates (e.g. multiple Set-Cookie). */
+    /** All response header name-value pairs exactly as received, in transmission order. */
     rawHeaders;
+    /** Fully buffered response body. Empty when the response was opened in streaming mode. */
     rawBody;
+    /** Readable stream of the response body, or `null` for buffered responses. */
+    body;
+    /** HTTP protocol version string (e.g. `"HTTP/1.1"`, `"HTTP/2.0"`). */
     httpVersion;
+    /** Final URL of the response after any redirects. */
     url;
+    /** Number of redirects followed before this response was received. */
     redirectCount;
+    /** Granular timing measurements for each phase of the request lifecycle. */
     timings;
+    /** Metadata about the originating request. */
     request;
     _json;
     _text;
+    /**
+     * Creates a new NLcURLResponse instance.
+     *
+     * @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.
+     */
     constructor(init) {
         this.status = init.status;
         this.statusText = init.statusText;
         this.headers = init.headers;
         this.rawHeaders = init.rawHeaders ?? Object.entries(init.headers);
         this.rawBody = init.rawBody;
+        this.body = init.body ?? null;
         this.httpVersion = init.httpVersion;
         this.url = init.url;
         this.redirectCount = init.redirectCount;
         this.timings = init.timings;
         this.request = init.request;
     }
-    /** Whether the status code is 2xx. */
+    /**
+     * Returns `true` when the HTTP status code is in the 200–299 (successful)
+     * range, `false` otherwise.
+     *
+     * @returns {boolean} Whether the response indicates success.
+     */
     get ok() {
         return this.status >= 200 && this.status < 300;
     }
-    /** Decode the body as UTF-8 text. Result is cached. */
+    /**
+     * Decodes the raw body as a UTF-8 string and returns it. The result is
+     * memoized after the first call.
+     *
+     * @returns {string} The response body decoded as UTF-8.
+     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     */
     text() {
+        if (this.body) {
+            throw new Error('Cannot read text from a streaming response. Consume the .body stream instead.');
+        }
         let cached = this._text;
         if (cached === undefined) {
             cached = this.rawBody.toString('utf8');
@@ -40,14 +86,34 @@ export class NLcURLResponse {
         }
         return cached;
     }
-    /** Parse the body as JSON. Result is cached. Throws on invalid JSON. */
+    /**
+     * Parses the raw body as JSON and returns the decoded value. The result is
+     * memoized after the first call.
+     *
+     * @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`).
+     * @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) {
+            throw new Error('Cannot read JSON from a streaming response. Consume the .body stream instead.');
+        }
         if (this._json === undefined) {
             this._json = JSON.parse(this.text());
         }
         return this._json;
     }
-    /** Content-Length as reported by the server, or the actual body size. */
+    /**
+     * Returns the `Content-Length` as a number. Falls back to the buffer byte
+     * length when the header is absent or unparseable.
+     *
+     * @returns {number} The content length in bytes.
+     */
     get contentLength() {
         const cl = this.headers['content-length'];
         if (cl !== undefined) {
@@ -57,9 +123,28 @@ export class NLcURLResponse {
         }
         return this.rawBody.length;
     }
-    /** Shorthand for the content-type header value. */
+    /**
+     * Returns the value of the `Content-Type` response header, or an empty
+     * string when the header is absent.
+     *
+     * @returns {string} The `Content-Type` header value.
+     */
     get contentType() {
         return this.headers['content-type'] ?? '';
     }
+    /**
+     * 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`.
+     *
+     * @param {string} name - The case-insensitive header name to look up.
+     * @returns {string[]} All header values for the given name, or an empty array.
+     */
+    getAll(name) {
+        const lower = name.toLowerCase();
+        return this.rawHeaders
+            .filter(([k]) => k.toLowerCase() === lower)
+            .map(([, v]) => v);
+    }
 }
 //# sourceMappingURL=response.js.map

package/dist/core/response.js.map

@@ -1 +1 @@
-{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,OAAO,cAAc;IACT,MAAM,CAAS;IACf,UAAU,CAAS;IACnB,OAAO,CAAyB;IAChD,yEAAyE;IACzD,UAAU,CAA0B;IACpC,OAAO,CAAS;IAChB,WAAW,CAAS;IACpB,GAAG,CAAS;IACZ,aAAa,CAAS;IACtB,OAAO,CAAiB;IACxB,OAAO,CAAe;IAE9B,KAAK,CAAgB;IACrB,KAAK,CAAqB;IAElC,YAAY,IAWX;QACC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,sCAAsC;IACtC,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;IACjD,CAAC;IAED,uDAAuD;IACvD,IAAI;QACF,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACtB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,wEAAwE;IACxE,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC,KAAU,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,IAAI,aAAa;QACf,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAC1C,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,mDAAmD;IACnD,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;CACF"}
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -1,18 +1,25 @@
-/**
- * NLcURL Session.
- *
- * A persistent session that maintains cookies, connection pools,
- * default configuration, and middleware across multiple requests.
- */
 import type { NLcURLRequest, NLcURLSessionConfig, RequestBody } from './request.js';
 import { NLcURLResponse } from './response.js';
 import { CookieJar } from '../cookies/jar.js';
 import { type RequestInterceptor, type ResponseInterceptor } from '../middleware/interceptor.js';
 import { type RateLimitConfig } from '../middleware/rate-limiter.js';
 /**
- * Convenience options for HTTP method shortcuts.
+ * Request options that can be passed alongside a URL and HTTP method. All
+ * fields from {@link NLcURLRequest} except `url`, `method`, and `body`.
+ *
+ * @typedef {Omit<NLcURLRequest, 'url'|'method'|'body'>} RequestOptions
  */
 export type RequestOptions = Omit<NLcURLRequest, 'url' | 'method' | 'body'>;
+/**
+ * Stateful HTTP client session that persists connections, cookies, interceptors,
+ * and configuration across multiple requests. Prefer using a session when making
+ * many requests to the same origin, or when you need shared cookie state.
+ *
+ * @example
+ * const session = new NLcURLSession({ impersonate: 'chrome136' });
+ * const response = await session.get('https://example.com');
+ * session.close();
+ */
 export declare class NLcURLSession {
     private readonly config;
     private readonly negotiator;
@@ -20,37 +27,125 @@ export declare class NLcURLSession {
     private readonly interceptors;
     private rateLimiter;
     private closed;
+    /**
+     * Creates a new NLcURLSession.
+     *
+     * @param {NLcURLSessionConfig} [config={}] - Session-level defaults applied to every request.
+     */
     constructor(config?: NLcURLSessionConfig);
     /**
-     * Register a request interceptor.
+     * Registers a request interceptor that is invoked (in registration order)
+     * before each request is dispatched. The interceptor may return a modified
+     * request object or a `Promise` that resolves to one.
      *
-     * Interceptors run before dispatch and may modify the outgoing request.
+     * @param {RequestInterceptor} fn - The interceptor function to add.
+     * @returns {this} The session instance, enabling a fluent call chain.
      */
     onRequest(fn: RequestInterceptor): this;
     /**
-     * Register a response interceptor.
+     * Registers a response interceptor that is invoked (in registration order)
+     * after each response is received. The interceptor may return a modified
+     * response object or a `Promise` that resolves to one.
      *
-     * Interceptors run after a response is received and may transform it.
+     * @param {ResponseInterceptor} fn - The interceptor function to add.
+     * @returns {this} The session instance, enabling a fluent call chain.
      */
     onResponse(fn: ResponseInterceptor): this;
     /**
-     * Enable per-session rate limiting.
+     * Applies a token-bucket rate limit to all requests issued by this session.
+     * Requests that exceed the configured rate will wait until a token becomes
+     * available before proceeding.
+     *
+     * @param {RateLimitConfig} config - Rate limit parameters (`maxRequests` per `windowMs`).
+     * @returns {this} The session instance, enabling a fluent call chain.
      */
     setRateLimit(config: RateLimitConfig): this;
+    /**
+     * Issues a `GET` request and resolves with the complete response.
+     *
+     * @param {string}          url      - The URL to request.
+     * @param {RequestOptions}  [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     get(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues a `POST` request and resolves with the complete response.
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestBody}    [body]   - Request body payload.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     post(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues a `PUT` request and resolves with the complete response.
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestBody}    [body]   - Request body payload.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     put(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues a `PATCH` request and resolves with the complete response.
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestBody}    [body]   - Request body payload.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     patch(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues a `DELETE` request and resolves with the complete response.
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     delete(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues a `HEAD` request and resolves with the complete response (no body).
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     head(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Issues an `OPTIONS` request and resolves with the complete response.
+     *
+     * @param {string}         url      - The URL to request.
+     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
     options(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Executes a fully described HTTP request, applying session defaults, request
+     * interceptors, redirect following, cookie management, and response
+     * interceptors in sequence.
+     *
+     * @param {NLcURLRequest} input - The request descriptor.
+     * @returns {Promise<NLcURLResponse>} Resolves with the final response after all redirects.
+     * @throws {NLcURLError}     If the session has been closed.
+     * @throws {AbortError}      If the provided `AbortSignal` fires before completion.
+     * @throws {TimeoutError}    If any configured timeout is exceeded.
+     * @throws {ConnectionError} If a TCP connection cannot be established.
+     * @throws {TLSError}        If the TLS handshake fails.
+     * @throws {ProxyError}      If the proxy tunnel cannot be established.
+     * @throws {NLcURLError}     If the maximum number of redirects is exceeded (`ERR_MAX_REDIRECTS`).
+     */
     request(input: NLcURLRequest): Promise<NLcURLResponse>;
     /**
-     * Return the session cookie jar, or `null` when cookie management is disabled.
+     * Returns the active {@link CookieJar} for this session, or `null` if
+     * cookie management was disabled via `cookieJar: false`.
+     *
+     * @returns {CookieJar|null} The shared cookie jar, or `null`.
      */
     getCookies(): CookieJar | null;
     /**
-     * Close the session and release pooled connections.
+     * Closes the session, releasing any pooled connections. After calling this
+     * method, issuing further requests will throw an `NLcURLError` with code
+     * `ERR_SESSION_CLOSED`. Subsequent calls are no-ops.
      */
     close(): void;
     private mergeDefaults;

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EAGnB,WAAW,EAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAoB,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnH,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAMlF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;AAE5E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,mBAAwB;IAiB5C;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI;IAKvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAKzC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAO3C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAInE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIvF,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIzF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAItE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAMjE,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IA2C5D;;OAEG;IACH,UAAU,IAAI,SAAS,GAAG,IAAI;IAM9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,aAAa;IA4DrB,OAAO,CAAC,cAAc;YAYR,oBAAoB;CA+HnC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EAGnB,WAAW,EAGZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAoB,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnH,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAOlF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,GAAE,mBAAwB;IAc5C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI;IAKvC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAKzC;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAK3C;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAInE;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxF;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIvF;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIzF;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAItE;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAIvE;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAqD5D;;;;;OAKG;IACH,UAAU,IAAI,SAAS,GAAG,IAAI;IAI9B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,aAAa;IAwDrB,OAAO,CAAC,cAAc;YAYR,oBAAoB;CAmHnC"}