nlcurl 0.6.0 → 0.8.0

package/dist/core/session.d.ts

@@ -3,22 +3,17 @@ 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";
+import { CacheStore } from "../cache/store.js";
+import { HSTSStore } from "../hsts/store.js";
 /**
- * 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
+ * Request options excluding URL, method, and body — used for convenience method signatures.
  */
 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.
+ * Manages a persistent HTTP session with connection pooling, cookie storage,
+ * caching, HSTS enforcement, interceptors, rate limiting, and retry logic.
  *
- * @example
- * const session = new NLcURLSession({ impersonate: 'chrome136' });
- * const response = await session.get('https://example.com');
- * session.close();
+ * @class
  */
 export declare class NLcURLSession {
     private readonly config;
@@ -27,126 +22,142 @@ export declare class NLcURLSession {
     private readonly interceptors;
     private readonly logger;
     private rateLimiter;
+    private readonly cacheStore;
+    private readonly hstsStore;
     private closed;
     /**
-     * Creates a new NLcURLSession.
+     * Creates a new session with the given configuration.
      *
-     * @param {NLcURLSessionConfig} [config={}] - Session-level defaults applied to every request.
+     * @param {NLcURLSessionConfig} [config={}] - Session-level defaults and feature toggles.
+     * @throws {NLcURLError} If configuration values are invalid.
      */
     constructor(config?: NLcURLSessionConfig);
     /**
-     * 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.
+     * Registers a request interceptor invoked before each outgoing request.
      *
-     * @param {RequestInterceptor} fn - The interceptor function to add.
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {RequestInterceptor} fn - The interceptor function.
+     * @returns {this} The session instance for chaining.
      */
     onRequest(fn: RequestInterceptor): this;
     /**
-     * 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.
+     * Registers a response interceptor invoked after each incoming response.
      *
-     * @param {ResponseInterceptor} fn - The interceptor function to add.
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {ResponseInterceptor} fn - The interceptor function.
+     * @returns {this} The session instance for chaining.
      */
     onResponse(fn: ResponseInterceptor): this;
     /**
-     * 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.
+     * Configures a token-bucket rate limiter for this session.
      *
-     * @param {RateLimitConfig} config - Rate limit parameters (`maxRequests` per `windowMs`).
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {RateLimitConfig} config - Rate limit parameters.
+     * @returns {this} The session instance for chaining.
+     * @throws {NLcURLError} If the rate limit config is invalid.
      */
     setRateLimit(config: RateLimitConfig): this;
     /**
-     * Issues a `GET` request and resolves with the complete response.
+     * Sends an HTTP GET request.
      *
-     * @param {string}          url      - The URL to request.
-     * @param {RequestOptions}  [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP POST request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP PUT request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP PATCH request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP DELETE request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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).
+     * Sends an HTTP HEAD request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP OPTIONS request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @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.
+     * Sends an HTTP QUERY request (RFC 9110).
+     *
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The query body.
+     * @param {RequestOptions} [options] - Additional request options.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
+    query(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Sends an HTTP request with full session features including caching,
+     * HSTS upgrade, cookie handling, compression, retry, and interceptors.
      *
-     * @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`).
+     * @param {NLcURLRequest} input - The complete request descriptor.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     * @throws {NLcURLError} If the session is closed.
+     * @throws {HTTPError} If `throwOnError` is enabled and the response is non-2xx.
      */
     request(input: NLcURLRequest): Promise<NLcURLResponse>;
     /**
-     * Returns the active {@link CookieJar} for this session, or `null` if
-     * cookie management was disabled via `cookieJar: false`.
+     * Returns the session's cookie jar, or `null` if cookies are disabled.
      *
-     * @returns {CookieJar|null} The shared cookie jar, or `null`.
+     * @returns {CookieJar|null} The cookie jar instance.
      */
     getCookies(): CookieJar | null;
     /**
-     * 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.
+     * Returns the session's cache store, or `null` if caching is disabled.
+     *
+     * @returns {CacheStore|null} The cache store instance.
+     */
+    getCache(): CacheStore | null;
+    /**
+     * Returns the session's HSTS store, or `null` if HSTS is disabled.
+     *
+     * @returns {HSTSStore|null} The HSTS store instance.
+     */
+    getHSTS(): HSTSStore | null;
+    /**
+     * Returns the session's Alt-Svc store for HTTP alternative service lookups.
+     *
+     * @returns {import("../http/alt-svc.js").AltSvcStore} The Alt-Svc store instance.
+     */
+    getAltSvc(): import("../http/alt-svc.js").AltSvcStore;
+    /**
+     * Closes the session and releases all pooled connections.
      */
     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,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAA2B,WAAW,EAAiC,MAAM,cAAc,CAAC;AAC5I,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;AASlF;;;;;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,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,GAAE,mBAAwB;IAkB5C;;;;;;;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;IAM3C;;;;;;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;IA6D5D;;;;;OAKG;IACH,UAAU,IAAI,SAAS,GAAG,IAAI;IAI9B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,aAAa;IA6DrB,OAAO,CAAC,cAAc;YASR,oBAAoB;CA2HnC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"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"}