nlcurl 0.1.0 → 0.2.0

package/dist/cookies/jar.js

@@ -1,20 +1,21 @@
-/**
- * Cookie jar (RFC 6265).
- *
- * Thread-safe, in-memory cookie storage with domain/path matching
- * and expiration handling.
- */
 import { parseSetCookie, serializeCookies } from './parser.js';
-/** Maximum number of cookies stored (per RFC 6265 §6.1 guidance). */
 const MAX_COOKIES = 3000;
 const MAX_COOKIES_PER_DOMAIN = 50;
+/**
+ * In-memory cookie store implementing RFC 6265 semantics. Manages cookie
+ * scoping by domain and path, enforces per-domain and global cookie limits,
+ * and supports Netscape cookie file import/export for persistence.
+ */
 export class CookieJar {
     cookies = [];
     /**
-     * Store cookies from Set-Cookie response headers.
+     * Parses all `Set-Cookie` values from `headers` (or from `rawHeaders` when
+     * available to handle multiple `Set-Cookie` entries) and stores any valid
+     * cookies scoped to the request URL.
      *
-     * Accepts either a flat Record (with optional rawHeaders for proper
-     * multi-value handling) or processes the merged header value.
+     * @param {Record<string, string>}    headers    - Normalized response headers.
+     * @param {URL}                       requestUrl - URL of the originating request (used for domain scoping).
+     * @param {Array<[string, string]>}   [rawHeaders] - Original header pairs, allowing multiple `set-cookie` entries.
      */
     setCookies(headers, requestUrl, rawHeaders) {
         const setCookieValues = this.extractSetCookieValues(headers, rawHeaders);
@@ -26,15 +27,19 @@ export class CookieJar {
         }
     }
     /**
-     * Get the Cookie header value for a request URL.
-     * Returns empty string if no cookies match.
+     * Builds the `Cookie` request header value for cookies that match `url`.
+     * Cookies are sorted by longest path prefix first, then by creation time.
+     * Expired cookies are excluded automatically.
+     *
+     * @param {URL} url - The URL of the outgoing request.
+     * @returns {string} Serialized cookie string suitable for the `Cookie` header,
+     *   or an empty string if no cookies match.
      */
     getCookieHeader(url) {
         const now = Date.now();
         const matching = this.cookies.filter((c) => this.matches(c, url, now));
         if (matching.length === 0)
             return '';
-        // Sort by path length (longest first), then creation time (earliest first)
         matching.sort((a, b) => {
             if (a.path.length !== b.path.length)
                 return b.path.length - a.path.length;
@@ -43,48 +48,109 @@ export class CookieJar {
         return serializeCookies(matching);
     }
     /**
-     * Clear all cookies.
+     * Removes all cookies from the jar.
      */
     clear() {
         this.cookies = [];
     }
     /**
-     * Clear cookies for a specific domain.
+     * Removes all cookies whose domain matches `domain` (case-insensitive).
+     *
+     * @param {string} domain - Domain string to clear (e.g. `"example.com"`).
      */
     clearDomain(domain) {
         this.cookies = this.cookies.filter((c) => c.domain !== domain.toLowerCase());
     }
     /**
-     * Get all stored cookies (for inspection/debugging).
+     * Returns a read-only snapshot of all cookies currently in the jar,
+     * including any that may already be expired.
+     *
+     * @returns {ReadonlyArray<Cookie>} All stored cookies.
      */
     all() {
         return this.cookies;
     }
+    /**
+     * Returns the total number of cookies currently in the jar.
+     *
+     * @returns {number} Cookie count.
+     */
     get size() {
         return this.cookies.length;
     }
-    // ---- Internal ----
+    /**
+     * Serializes all cookies to Netscape cookie file format. The output can be
+     * saved to disk and reloaded via {@link CookieJar.loadNetscapeString}.
+     *
+     * @returns {string} Netscape-format cookie file content (newline-terminated).
+     */
+    toNetscapeString() {
+        const lines = ['# Netscape HTTP Cookie File'];
+        for (const c of this.cookies) {
+            const domain = c.domain.startsWith('.') ? c.domain : '.' + c.domain;
+            const includeSubdomains = domain.startsWith('.') ? 'TRUE' : 'FALSE';
+            const path = c.path || '/';
+            const secure = c.secure ? 'TRUE' : 'FALSE';
+            let expires = '0';
+            if (c.maxAge !== undefined) {
+                expires = String(Math.floor((c.createdAt + c.maxAge * 1000) / 1000));
+            }
+            else if (c.expires) {
+                expires = String(Math.floor(c.expires.getTime() / 1000));
+            }
+            lines.push(`${domain}\t${includeSubdomains}\t${path}\t${secure}\t${expires}\t${c.name}\t${c.value}`);
+        }
+        return lines.join('\n') + '\n';
+    }
+    /**
+     * Imports cookies from a Netscape cookie file string. Lines beginning with
+     * `#` or blank lines are ignored. Cookies with invalid formats are skipped.
+     * Imported cookies are merged with any existing cookies in the jar.
+     *
+     * @param {string} content - Netscape cookie file content.
+     */
+    loadNetscapeString(content) {
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const parts = trimmed.split('\t');
+            if (parts.length < 7)
+                continue;
+            const [domain, , path, secure, expires, name, value] = parts;
+            const cookie = {
+                name: name,
+                value: value,
+                domain: domain.startsWith('.') ? domain.slice(1) : domain,
+                path: path,
+                secure: secure === 'TRUE',
+                httpOnly: false,
+                sameSite: undefined,
+                createdAt: Date.now(),
+            };
+            const expiresNum = parseInt(expires, 10);
+            if (expiresNum > 0) {
+                cookie.expires = new Date(expiresNum * 1000);
+            }
+            this.store(cookie);
+        }
+    }
     store(cookie) {
-        // Max-Age = 0 means delete
         if (cookie.maxAge !== undefined && cookie.maxAge <= 0) {
             this.cookies = this.cookies.filter((c) => !(c.name === cookie.name && c.domain === cookie.domain && c.path === cookie.path));
             return;
         }
-        // Replace existing cookie with same name/domain/path
         const idx = this.cookies.findIndex((c) => c.name === cookie.name && c.domain === cookie.domain && c.path === cookie.path);
         if (idx >= 0) {
             this.cookies[idx] = cookie;
         }
         else {
-            // Enforce per-domain limit
             const domainCount = this.cookies.filter((c) => c.domain === cookie.domain).length;
             if (domainCount >= MAX_COOKIES_PER_DOMAIN) {
-                // Evict oldest cookie for this domain
                 const oldest = this.cookies.findIndex((c) => c.domain === cookie.domain);
                 if (oldest >= 0)
                     this.cookies.splice(oldest, 1);
             }
-            // Enforce global limit
             if (this.cookies.length >= MAX_COOKIES) {
                 this.cookies.shift();
             }
@@ -92,21 +158,17 @@ export class CookieJar {
         }
     }
     matches(cookie, url, now) {
-        // Check expiration
         if (cookie.maxAge !== undefined) {
             if (now > cookie.createdAt + cookie.maxAge * 1000)
                 return false;
         }
         if (cookie.expires && now > cookie.expires.getTime())
             return false;
-        // Domain matching
         const host = url.hostname.toLowerCase();
         if (!this.domainMatches(host, cookie.domain))
             return false;
-        // Path matching
         if (!this.pathMatches(url.pathname, cookie.path))
             return false;
-        // Secure flag
         if (cookie.secure && url.protocol !== 'https:')
             return false;
         return true;
@@ -114,7 +176,6 @@ export class CookieJar {
     domainMatches(host, domain) {
         if (host === domain)
             return true;
-        // Host must end with .domain
         return host.endsWith('.' + domain);
     }
     pathMatches(requestPath, cookiePath) {
@@ -129,13 +190,11 @@ export class CookieJar {
         return false;
     }
     extractSetCookieValues(headers, rawHeaders) {
-        // Prefer raw headers to preserve individual Set-Cookie values
         if (rawHeaders) {
             return rawHeaders
                 .filter(([k]) => k.toLowerCase() === 'set-cookie')
                 .map(([, v]) => v);
         }
-        // Fallback: extract from merged Record
         const values = [];
         for (const [key, value] of Object.entries(headers)) {
             if (key.toLowerCase() === 'set-cookie') {

package/dist/cookies/jar.js.map

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

package/dist/cookies/parser.d.ts

@@ -1,5 +1,17 @@
 /**
- * Cookie parser and serializer (RFC 6265).
+ * Represents a parsed HTTP cookie as stored in the `CookieJar`.
+ *
+ * @typedef  {Object}                           Cookie
+ * @property {string}                           name       - Cookie name.
+ * @property {string}                           value      - Cookie value.
+ * @property {string}                           domain     - Effective domain (without leading dot).
+ * @property {string}                           path       - Cookie path scope.
+ * @property {Date}                             [expires]  - Absolute expiry date (from the `Expires` attribute).
+ * @property {number}                           [maxAge]   - Relative lifetime in seconds (from the `Max-Age` attribute).
+ * @property {boolean}                          secure     - Whether the cookie is restricted to HTTPS.
+ * @property {boolean}                          httpOnly   - Whether the cookie is inaccessible to client-side scripts.
+ * @property {'strict' | 'lax' | 'none'}        [sameSite] - SameSite policy.
+ * @property {number}                           createdAt  - Unix timestamp (ms) when the cookie was created.
  */
 export interface Cookie {
     name: string;
@@ -14,11 +26,21 @@ export interface Cookie {
     createdAt: number;
 }
 /**
- * Parse a Set-Cookie header value into a Cookie object.
+ * Parses a `Set-Cookie` header value into a {@link Cookie} object.
+ * Validates the cookie against the request URL to enforce domain and path
+ * scoping rules per RFC 6265.
+ *
+ * @param {string} header     - Raw `Set-Cookie` header value.
+ * @param {URL}    requestUrl - URL of the request that received the header.
+ * @returns {Cookie | null} Parsed cookie, or `null` if the header is invalid or
+ *   the domain attribute fails validation against the request origin.
  */
 export declare function parseSetCookie(header: string, requestUrl: URL): Cookie | null;
 /**
- * Serialize cookies for the Cookie header.
+ * Serializes an array of cookies into the `Cookie` request header value.
+ *
+ * @param {Cookie[]} cookies - Cookies to serialize (in desired send order).
+ * @returns {string} Semicolon-separated `name=value` string suitable for the `Cookie` header.
  */
 export declare function serializeCookies(cookies: Cookie[]): string;
 //# sourceMappingURL=parser.d.ts.map

package/dist/cookies/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cookies/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CA0E7E;AASD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cookies/parser.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAwE7E;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D"}

package/dist/cookies/parser.js

@@ -1,8 +1,12 @@
 /**
- * Cookie parser and serializer (RFC 6265).
- */
-/**
- * Parse a Set-Cookie header value into a Cookie object.
+ * Parses a `Set-Cookie` header value into a {@link Cookie} object.
+ * Validates the cookie against the request URL to enforce domain and path
+ * scoping rules per RFC 6265.
+ *
+ * @param {string} header     - Raw `Set-Cookie` header value.
+ * @param {URL}    requestUrl - URL of the request that received the header.
+ * @returns {Cookie | null} Parsed cookie, or `null` if the header is invalid or
+ *   the domain attribute fails validation against the request origin.
  */
 export function parseSetCookie(header, requestUrl) {
     const parts = header.split(';').map((s) => s.trim());
@@ -37,10 +41,8 @@ export function parseSetCookie(header, requestUrl) {
                 let d = attrValue.toLowerCase();
                 if (d.startsWith('.'))
                     d = d.substring(1);
-                // Validate domain matches request host (RFC 6265 §5.3.6)
                 const host = requestUrl.hostname.toLowerCase();
                 if (d !== host && !host.endsWith('.' + d)) {
-                    // Reject cookie — domain doesn't match request
                     return null;
                 }
                 cookie.domain = d;
@@ -85,7 +87,10 @@ function defaultPath(path) {
     return path.substring(0, lastSlash);
 }
 /**
- * Serialize cookies for the Cookie header.
+ * Serializes an array of cookies into the `Cookie` request header value.
+ *
+ * @param {Cookie[]} cookies - Cookies to serialize (in desired send order).
+ * @returns {string} Semicolon-separated `name=value` string suitable for the `Cookie` header.
  */
 export function serializeCookies(cookies) {
     return cookies.map((c) => `${c.name}=${c.value}`).join('; ');

package/dist/cookies/parser.js.map

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

package/dist/core/client.d.ts

@@ -1,77 +1,93 @@
-/**
- * NLcURL client.
- *
- * The primary public interface for making HTTP requests with browser
- * fingerprint impersonation.  Provides both a session-based API for
- * persistent connections and cookie handling, and standalone convenience
- * functions for one-off requests.
- */
 import type { NLcURLRequest, NLcURLSessionConfig, RequestBody } from './request.js';
 import { NLcURLResponse } from './response.js';
 import { NLcURLSession, type RequestOptions } from './session.js';
 /**
- * Create a new persistent session.
+ * Creates a new {@link NLcURLSession} with the given configuration. Use a
+ * session when you need to share cookies, connection pools, or interceptors
+ * across multiple requests. Call {@link NLcURLSession.close} when finished.
  *
- * Sessions maintain a connection pool, cookie jar, and default
- * configuration across multiple requests.
+ * @param {NLcURLSessionConfig} [config] - Session-level defaults.
+ * @returns {NLcURLSession} A new session instance.
  *
  * @example
- * ```ts
  * const session = createSession({ impersonate: 'chrome136' });
- * const response = await session.get('https://httpbin.org/get');
- * console.log(response.json());
+ * const r = await session.get('https://example.com');
  * session.close();
- * ```
  */
 export declare function createSession(config?: NLcURLSessionConfig): NLcURLSession;
 /**
- * Send an HTTP request.
+ * Sends a one-shot HTTP request by creating a temporary session internally.
+ * The session is closed automatically after the response is received.
+ * For repeated requests to the same origin, prefer {@link createSession}.
  *
- * Creates a temporary session, sends the request, and closes the session.
- * For multiple requests, use `createSession()` instead for better
- * performance via connection reuse.
- *
- * @example
- * ```ts
- * const resp = await request({
- *   url: 'https://httpbin.org/get',
- *   impersonate: 'chrome136',
- * });
- * ```
+ * @param {NLcURLRequest} input - Complete request descriptor.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+ * @throws {AbortError}      If the `signal` in `input` fires before completion.
+ * @throws {TimeoutError}    If any configured timeout is exceeded.
+ * @throws {ConnectionError} If the TCP connection cannot be established.
+ * @throws {TLSError}        If the TLS handshake fails.
+ * @throws {ProxyError}      If the proxy tunnel cannot be established.
  */
 export declare function request(input: NLcURLRequest): Promise<NLcURLResponse>;
 /**
- * Send a GET request.
+ * Issues a one-shot `GET` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export declare function get(url: string, options?: RequestOptions & {
     impersonate?: string;
 }): Promise<NLcURLResponse>;
 /**
- * Send a POST request.
+ * Issues a one-shot `POST` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export declare function post(url: string, body?: RequestBody, options?: RequestOptions & {
     impersonate?: string;
 }): Promise<NLcURLResponse>;
 /**
- * Send a PUT request.
+ * Issues a one-shot `PUT` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export declare function put(url: string, body?: RequestBody, options?: RequestOptions & {
     impersonate?: string;
 }): Promise<NLcURLResponse>;
 /**
- * Send a PATCH request.
+ * Issues a one-shot `PATCH` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export declare function patch(url: string, body?: RequestBody, options?: RequestOptions & {
     impersonate?: string;
 }): Promise<NLcURLResponse>;
 /**
- * Send a DELETE request.
+ * Issues a one-shot `DELETE` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export declare function del(url: string, options?: RequestOptions & {
     impersonate?: string;
 }): Promise<NLcURLResponse>;
 /**
- * Send a HEAD request.
+ * Issues a one-shot `HEAD` request. The response body will be empty.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the response (headers only, no body).
  */
 export declare function head(url: string, options?: RequestOptions & {
     impersonate?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAEzE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAO3E;AAED;;GAEG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAsB,KAAK,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAEzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAoB3E;AAED;;;;;;GAMG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;;GAOG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;;GAOG;AACH,wBAAsB,KAAK,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;GAMG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,OAAO,CAAC,cAAc,CAAC,CAEzB"}

package/dist/core/client.js

@@ -1,47 +1,50 @@
-/**
- * NLcURL client.
- *
- * The primary public interface for making HTTP requests with browser
- * fingerprint impersonation.  Provides both a session-based API for
- * persistent connections and cookie handling, and standalone convenience
- * functions for one-off requests.
- */
 import { NLcURLSession } from './session.js';
 /**
- * Create a new persistent session.
+ * Creates a new {@link NLcURLSession} with the given configuration. Use a
+ * session when you need to share cookies, connection pools, or interceptors
+ * across multiple requests. Call {@link NLcURLSession.close} when finished.
  *
- * Sessions maintain a connection pool, cookie jar, and default
- * configuration across multiple requests.
+ * @param {NLcURLSessionConfig} [config] - Session-level defaults.
+ * @returns {NLcURLSession} A new session instance.
  *
  * @example
- * ```ts
  * const session = createSession({ impersonate: 'chrome136' });
- * const response = await session.get('https://httpbin.org/get');
- * console.log(response.json());
+ * const r = await session.get('https://example.com');
  * session.close();
- * ```
  */
 export function createSession(config) {
     return new NLcURLSession(config);
 }
-// ---- One-shot request functions ----
 /**
- * Send an HTTP request.
- *
- * Creates a temporary session, sends the request, and closes the session.
- * For multiple requests, use `createSession()` instead for better
- * performance via connection reuse.
+ * Sends a one-shot HTTP request by creating a temporary session internally.
+ * The session is closed automatically after the response is received.
+ * For repeated requests to the same origin, prefer {@link createSession}.
  *
- * @example
- * ```ts
- * const resp = await request({
- *   url: 'https://httpbin.org/get',
- *   impersonate: 'chrome136',
- * });
- * ```
+ * @param {NLcURLRequest} input - Complete request descriptor.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+ * @throws {AbortError}      If the `signal` in `input` fires before completion.
+ * @throws {TimeoutError}    If any configured timeout is exceeded.
+ * @throws {ConnectionError} If the TCP connection cannot be established.
+ * @throws {TLSError}        If the TLS handshake fails.
+ * @throws {ProxyError}      If the proxy tunnel cannot be established.
  */
 export async function request(input) {
     const session = new NLcURLSession(extractSessionConfig(input));
+    if (input.stream) {
+        let response;
+        try {
+            response = await session.request(input);
+        }
+        catch (err) {
+            session.close();
+            throw err;
+        }
+        const cleanup = () => session.close();
+        response.body?.once('close', cleanup);
+        if (response.body === null)
+            session.close();
+        return response;
+    }
     try {
         return await session.request(input);
     }
@@ -50,45 +53,68 @@ export async function request(input) {
     }
 }
 /**
- * Send a GET request.
+ * Issues a one-shot `GET` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export async function get(url, options) {
     return request({ ...options, url, method: 'GET' });
 }
 /**
- * Send a POST request.
+ * Issues a one-shot `POST` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export async function post(url, body, options) {
     return request({ ...options, url, method: 'POST', body });
 }
 /**
- * Send a PUT request.
+ * Issues a one-shot `PUT` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export async function put(url, body, options) {
     return request({ ...options, url, method: 'PUT', body });
 }
 /**
- * Send a PATCH request.
+ * Issues a one-shot `PATCH` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestBody}                                         [body]   - Request body payload.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export async function patch(url, body, options) {
     return request({ ...options, url, method: 'PATCH', body });
 }
 /**
- * Send a DELETE request.
+ * Issues a one-shot `DELETE` request.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the server response.
  */
 export async function del(url, options) {
     return request({ ...options, url, method: 'DELETE' });
 }
 /**
- * Send a HEAD request.
+ * Issues a one-shot `HEAD` request. The response body will be empty.
+ *
+ * @param {string}                                              url      - Absolute URL to request.
+ * @param {RequestOptions & { impersonate?: string }}          [options] - Optional per-request settings.
+ * @returns {Promise<NLcURLResponse>} Resolves with the response (headers only, no body).
  */
 export async function head(url, options) {
     return request({ ...options, url, method: 'HEAD' });
 }
-// ---- Internal ----
-/**
- * Extract session-level configuration from a request object.
- */
 function extractSessionConfig(req) {
     return {
         impersonate: req.impersonate,