curl-cffi-node 0.1.7

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * curl-cffi-node — Node.js binding for curl-impersonate
+ *
+ * Provides browser-impersonating HTTP client with TLS/JA3/HTTP2 fingerprinting.
+ *
+ * @module curl-cffi-node
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Curl = exports.BrowserType = exports.CurlInfo = exports.CurlOpt = exports.curlVersion = exports.nativeVersion = exports.hello = exports.WS_CLOSE = exports.WS_BINARY = exports.WS_TEXT = exports.CurlWebSocket = exports.Session = exports.parseCurlError = exports.CurlCode = exports.ProxyError = exports.TLSError = exports.ConnectionError = exports.TimeoutError = exports.CurlError = exports.Headers = exports.Response = void 0;
+exports.get = get;
+exports.post = post;
+exports.put = put;
+exports.del = del;
+exports.head = head;
+exports.patch = patch;
+const binding_js_1 = require("./binding.js");
+// ─── Re-exports ──────────────────────────────────────────────────────────────
+var response_js_1 = require("./response.js");
+Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return response_js_1.Response; } });
+Object.defineProperty(exports, "Headers", { enumerable: true, get: function () { return response_js_1.Headers; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CurlError", { enumerable: true, get: function () { return errors_js_1.CurlError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return errors_js_1.ConnectionError; } });
+Object.defineProperty(exports, "TLSError", { enumerable: true, get: function () { return errors_js_1.TLSError; } });
+Object.defineProperty(exports, "ProxyError", { enumerable: true, get: function () { return errors_js_1.ProxyError; } });
+Object.defineProperty(exports, "CurlCode", { enumerable: true, get: function () { return errors_js_1.CurlCode; } });
+Object.defineProperty(exports, "parseCurlError", { enumerable: true, get: function () { return errors_js_1.parseCurlError; } });
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_js_1.Session; } });
+var websocket_js_1 = require("./websocket.js");
+Object.defineProperty(exports, "CurlWebSocket", { enumerable: true, get: function () { return websocket_js_1.CurlWebSocket; } });
+Object.defineProperty(exports, "WS_TEXT", { enumerable: true, get: function () { return websocket_js_1.WS_TEXT; } });
+Object.defineProperty(exports, "WS_BINARY", { enumerable: true, get: function () { return websocket_js_1.WS_BINARY; } });
+Object.defineProperty(exports, "WS_CLOSE", { enumerable: true, get: function () { return websocket_js_1.WS_CLOSE; } });
+// ─── Native Bindings ─────────────────────────────────────────────────────────
+/**
+ * Returns a greeting from the native module to verify binding works.
+ */
+exports.hello = binding_js_1.nativeBinding.hello;
+/**
+ * Returns the version of the native Rust module.
+ */
+exports.nativeVersion = binding_js_1.nativeBinding.nativeVersion;
+/**
+ * Returns the version string from the linked libcurl-impersonate library.
+ */
+exports.curlVersion = binding_js_1.nativeBinding.curlVersion;
+// ─── Curl Handle Class (Low-level) ──────────────────────────────────────────
+var enums_js_1 = require("./enums.js");
+Object.defineProperty(exports, "CurlOpt", { enumerable: true, get: function () { return enums_js_1.CurlOpt; } });
+Object.defineProperty(exports, "CurlInfo", { enumerable: true, get: function () { return enums_js_1.CurlInfo; } });
+Object.defineProperty(exports, "BrowserType", { enumerable: true, get: function () { return enums_js_1.BrowserType; } });
+exports.Curl = binding_js_1.nativeBinding.Curl;
+// ─── Shorthand Functions (Story 3.5) ────────────────────────────────────────
+const session_js_2 = require("./session.js");
+/** Shorthand for a GET request. Creates a temporary session. */
+async function get(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.get(url, options);
+}
+/** Shorthand for a POST request. */
+async function post(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.post(url, options);
+}
+/** Shorthand for a PUT request. */
+async function put(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.put(url, options);
+}
+/** Shorthand for a DELETE request. */
+async function del(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.delete(url, options);
+}
+/** Shorthand for a HEAD request. */
+async function head(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.head(url, options);
+}
+/** Shorthand for a PATCH request. */
+async function patch(url, options) {
+    const session = new session_js_2.Session({ impersonate: options?.impersonate });
+    return session.patch(url, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/response.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Headers wrapper with case-insensitive access.
+ *
+ * Parses raw header string into a Map for efficient lookup.
+ */
+export declare class Headers {
+    private _map;
+    constructor(raw: string);
+    /** Get the first value for a header (case-insensitive). */
+    get(name: string): string | null;
+    /** Check if a header exists (case-insensitive). */
+    has(name: string): boolean;
+    /** Get all values for a header. */
+    getAll(name: string): string[];
+    /** Iterate over all headers. */
+    forEach(callback: (value: string, key: string) => void): void;
+    /** Get all header keys. */
+    keys(): IterableIterator<string>;
+    /** Get all entries as [key, value] pairs (first value only). */
+    entries(): IterableIterator<[string, string]>;
+}
+/**
+ * Response timing information in milliseconds.
+ */
+export interface Timing {
+    /** DNS resolution time in ms. */
+    dns: number;
+    /** TCP connection time in ms. */
+    connect: number;
+    /** TLS handshake time in ms. */
+    tls: number;
+    /** Total request time in ms. */
+    total: number;
+}
+/**
+ * High-level Response class wrapping the raw PerformResult.
+ *
+ * Provides convenient access to status, headers, body, and timing.
+ *
+ * @example
+ * ```ts
+ * const response = await session.get('https://httpbin.org/get');
+ * console.log(response.status);     // 200
+ * console.log(response.ok);         // true
+ * console.log(response.headers.get('content-type')); // 'application/json'
+ * const data = response.json();     // parsed JSON
+ * console.log(response.timing);     // { dns: 5.2, connect: 12.1, tls: 45.3, total: 123.4 }
+ * ```
+ */
+export declare class Response {
+    /** HTTP status code (e.g., 200, 404, 500). */
+    readonly status: number;
+    /** Parsed response headers with case-insensitive access. */
+    readonly headers: Headers;
+    /** Raw response headers string. */
+    readonly rawHeaders: string;
+    /** The effective URL after any redirects. */
+    readonly url: string;
+    /** Raw response body as a Buffer. */
+    readonly content: Buffer;
+    /** Response timing information in milliseconds. */
+    readonly timing: Timing;
+    /** Total elapsed time in milliseconds. */
+    readonly elapsed: number;
+    constructor(raw: {
+        body: Buffer;
+        headers: string;
+        statusCode: number;
+        effectiveUrl: string;
+        dnsTimeMs: number;
+        connectTimeMs: number;
+        tlsTimeMs: number;
+        totalTimeMs: number;
+    });
+    /** Returns true if status is 200-299. */
+    get ok(): boolean;
+    /** Returns the response body as a UTF-8 string. */
+    text(): string;
+    /** Parses the response body as JSON. */
+    json<T = unknown>(): T;
+    /** Returns the raw response body as a Buffer. */
+    buffer(): Buffer;
+    /** Returns the response body as a Node.js Readable stream. */
+    stream(): import('stream').Readable;
+}
+//# sourceMappingURL=response.d.ts.map

package/dist/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../lib/response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,IAAI,CAAoC;gBAEpC,GAAG,EAAE,MAAM;IAgBvB,2DAA2D;IAC3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKhC,mDAAmD;IACnD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAI9B,gCAAgC;IAChC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAQ7D,2BAA2B;IAC3B,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIhC,gEAAgE;IAChE,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAO9C;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACnB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,GAAG,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;IAeD,yCAAyC;IACzC,IAAI,EAAE,IAAI,OAAO,CAEhB;IAED,mDAAmD;IACnD,IAAI,IAAI,MAAM;IAId,wCAAwC;IACxC,IAAI,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC;IAUtB,iDAAiD;IACjD,MAAM,IAAI,MAAM;IAIhB,8DAA8D;IAC9D,MAAM,IAAI,OAAO,QAAQ,EAAE,QAAQ;CAKpC"}

package/dist/response.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Response = exports.Headers = void 0;
+/**
+ * Headers wrapper with case-insensitive access.
+ *
+ * Parses raw header string into a Map for efficient lookup.
+ */
+class Headers {
+    _map = new Map();
+    constructor(raw) {
+        for (const line of raw.split('\r\n')) {
+            const idx = line.indexOf(':');
+            if (idx === -1)
+                continue;
+            const key = line.slice(0, idx).trim().toLowerCase();
+            const value = line.slice(idx + 1).trim();
+            if (!key)
+                continue;
+            const existing = this._map.get(key);
+            if (existing) {
+                existing.push(value);
+            }
+            else {
+                this._map.set(key, [value]);
+            }
+        }
+    }
+    /** Get the first value for a header (case-insensitive). */
+    get(name) {
+        const values = this._map.get(name.toLowerCase());
+        return values ? values[0] : null;
+    }
+    /** Check if a header exists (case-insensitive). */
+    has(name) {
+        return this._map.has(name.toLowerCase());
+    }
+    /** Get all values for a header. */
+    getAll(name) {
+        return this._map.get(name.toLowerCase()) || [];
+    }
+    /** Iterate over all headers. */
+    forEach(callback) {
+        this._map.forEach((values, key) => {
+            for (const v of values) {
+                callback(v, key);
+            }
+        });
+    }
+    /** Get all header keys. */
+    keys() {
+        return this._map.keys();
+    }
+    /** Get all entries as [key, value] pairs (first value only). */
+    entries() {
+        const entries = [];
+        this._map.forEach((values, key) => {
+            entries.push([key, values[0]]);
+        });
+        return entries[Symbol.iterator]();
+    }
+}
+exports.Headers = Headers;
+/**
+ * High-level Response class wrapping the raw PerformResult.
+ *
+ * Provides convenient access to status, headers, body, and timing.
+ *
+ * @example
+ * ```ts
+ * const response = await session.get('https://httpbin.org/get');
+ * console.log(response.status);     // 200
+ * console.log(response.ok);         // true
+ * console.log(response.headers.get('content-type')); // 'application/json'
+ * const data = response.json();     // parsed JSON
+ * console.log(response.timing);     // { dns: 5.2, connect: 12.1, tls: 45.3, total: 123.4 }
+ * ```
+ */
+class Response {
+    /** HTTP status code (e.g., 200, 404, 500). */
+    status;
+    /** Parsed response headers with case-insensitive access. */
+    headers;
+    /** Raw response headers string. */
+    rawHeaders;
+    /** The effective URL after any redirects. */
+    url;
+    /** Raw response body as a Buffer. */
+    content;
+    /** Response timing information in milliseconds. */
+    timing;
+    /** Total elapsed time in milliseconds. */
+    elapsed;
+    constructor(raw) {
+        this.status = raw.statusCode;
+        this.rawHeaders = raw.headers;
+        this.headers = new Headers(raw.headers);
+        this.url = raw.effectiveUrl;
+        this.content = raw.body;
+        this.elapsed = raw.totalTimeMs;
+        this.timing = {
+            dns: raw.dnsTimeMs,
+            connect: raw.connectTimeMs,
+            tls: raw.tlsTimeMs,
+            total: raw.totalTimeMs,
+        };
+    }
+    /** Returns true if status is 200-299. */
+    get ok() {
+        return this.status >= 200 && this.status < 300;
+    }
+    /** Returns the response body as a UTF-8 string. */
+    text() {
+        return this.content.toString('utf8');
+    }
+    /** Parses the response body as JSON. */
+    json() {
+        try {
+            return JSON.parse(this.text());
+        }
+        catch (err) {
+            throw new Error(`Failed to parse response as JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Returns the raw response body as a Buffer. */
+    buffer() {
+        return this.content;
+    }
+    /** Returns the response body as a Node.js Readable stream. */
+    stream() {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { Readable } = require('stream');
+        return Readable.from(this.content);
+    }
+}
+exports.Response = Response;
+//# sourceMappingURL=response.js.map

package/dist/response.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,93 @@
+/**
+ * High-level Session class for making HTTP requests with browser impersonation.
+ *
+ * Uses a persistent curl handle for cookie persistence and connection reuse.
+ *
+ * @example
+ * ```ts
+ * const session = new Session({ impersonate: 'chrome116' });
+ * const response = await session.get('https://httpbin.org/get');
+ * console.log(response.json());
+ * ```
+ */
+import { Response } from './response.js';
+/** Options for creating a Session. */
+export interface SessionOptions {
+    /** Browser to impersonate (e.g., 'chrome116', 'safari15_5'). */
+    impersonate?: string;
+    /** Default headers for all requests. */
+    headers?: Record<string, string>;
+    /** Default timeout in seconds. */
+    timeout?: number;
+    /** Whether to follow redirects (default: true). */
+    followRedirects?: boolean;
+    /** Maximum number of redirects (default: 30). */
+    maxRedirects?: number;
+    /** Proxy URL (e.g., 'http://host:port', 'socks5://user:pass@host:port'). */
+    proxy?: string;
+    /** Whether to verify SSL certificates (default: true). */
+    verify?: boolean;
+    /** Whether to apply default browser headers (default: true). */
+    defaultHeaders?: boolean;
+    /** Pre-existing cookies in Netscape format to restore. */
+    cookies?: string[];
+}
+/** Options for individual requests. */
+export interface RequestOptions {
+    /** Custom headers for this request. */
+    headers?: Record<string, string>;
+    /** Request body as string, Buffer, or JSON object. */
+    data?: string | Buffer | Record<string, unknown>;
+    /** URL query parameters. */
+    params?: Record<string, string | number | boolean>;
+    /** Timeout in seconds (overrides session default). */
+    timeout?: number;
+    /** Whether to follow redirects (overrides session default). */
+    followRedirects?: boolean;
+    /** Maximum redirects (overrides session default). */
+    maxRedirects?: number;
+    /** Proxy URL (overrides session default). */
+    proxy?: string;
+    /** Whether to verify SSL (overrides session default). */
+    verify?: boolean;
+    /** Browser to impersonate (overrides session default). */
+    impersonate?: string;
+}
+export declare class Session {
+    private _options;
+    /** Persistent handle for connection reuse and cookie persistence. */
+    private _handle;
+    constructor(options?: SessionOptions);
+    get(url: string, options?: RequestOptions): Promise<Response>;
+    post(url: string, options?: RequestOptions): Promise<Response>;
+    put(url: string, options?: RequestOptions): Promise<Response>;
+    delete(url: string, options?: RequestOptions): Promise<Response>;
+    head(url: string, options?: RequestOptions): Promise<Response>;
+    patch(url: string, options?: RequestOptions): Promise<Response>;
+    options(url: string, options?: RequestOptions): Promise<Response>;
+    /** Get all cookies in Netscape format. */
+    get cookies(): string[];
+    /** Export cookies as serialized Netscape-format strings (for persistence). */
+    exportCookies(): string[];
+    /** Import cookies from Netscape-format strings. */
+    importCookies(cookies: string[]): void;
+    /** Clear all cookies. */
+    clearCookies(): void;
+    /** Clear cookies for a specific domain. */
+    clearCookies(domain: string): void;
+    /**
+     * Core request method — uses the persistent handle directly for cookie
+     * persistence and connection reuse. Per-request options are set on the
+     * handle before each perform call.
+     *
+     * **WARNING**: This method calls `curl.perform()` which is a synchronous
+     * blocking FFI call. The Node.js event loop is blocked for the duration
+     * of the HTTP request. For high-concurrency server environments, consider
+     * using the low-level `Curl` API with `performAsync()` instead.
+     *
+     * A non-blocking Session implementation using `curl_multi` + libuv polling
+     * is planned for a future release.
+     */
+    private _request;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

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

package/dist/session.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * High-level Session class for making HTTP requests with browser impersonation.
+ *
+ * Uses a persistent curl handle for cookie persistence and connection reuse.
+ *
+ * @example
+ * ```ts
+ * const session = new Session({ impersonate: 'chrome116' });
+ * const response = await session.get('https://httpbin.org/get');
+ * console.log(response.json());
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const binding_js_1 = require("./binding.js");
+const response_js_1 = require("./response.js");
+const errors_js_1 = require("./errors.js");
+const NativeCurl = binding_js_1.nativeBinding.Curl;
+const NativeCurlOpt = binding_js_1.nativeBinding.CurlOpt;
+class Session {
+    _options;
+    /** Persistent handle for connection reuse and cookie persistence. */
+    _handle;
+    constructor(options = {}) {
+        this._options = {
+            followRedirects: true,
+            maxRedirects: 30,
+            verify: true,
+            defaultHeaders: true,
+            timeout: 0,
+            ...options,
+        };
+        // Create the persistent handle
+        this._handle = new NativeCurl();
+        // Enable cookie engine
+        this._handle.enableCookies();
+        // Set impersonation once on the persistent handle
+        if (this._options.impersonate) {
+            this._handle.impersonateStr(this._options.impersonate, this._options.defaultHeaders);
+        }
+        // Import pre-existing cookies
+        if (options.cookies) {
+            for (const line of options.cookies) {
+                this._handle.addCookie(line);
+            }
+        }
+    }
+    // ─── HTTP Methods ─────────────────────────────────────────────────────
+    async get(url, options) {
+        return this._request('GET', url, options);
+    }
+    async post(url, options) {
+        return this._request('POST', url, options);
+    }
+    async put(url, options) {
+        return this._request('PUT', url, options);
+    }
+    async delete(url, options) {
+        return this._request('DELETE', url, options);
+    }
+    async head(url, options) {
+        return this._request('HEAD', url, options);
+    }
+    async patch(url, options) {
+        return this._request('PATCH', url, options);
+    }
+    async options(url, options) {
+        return this._request('OPTIONS', url, options);
+    }
+    // ─── Cookie Management ────────────────────────────────────────────────
+    /** Get all cookies in Netscape format. */
+    get cookies() {
+        return this._handle.getCookies();
+    }
+    /** Export cookies as serialized Netscape-format strings (for persistence). */
+    exportCookies() {
+        return this._handle.getCookies();
+    }
+    /** Import cookies from Netscape-format strings. */
+    importCookies(cookies) {
+        for (const line of cookies) {
+            this._handle.addCookie(line);
+        }
+    }
+    clearCookies(domain) {
+        if (domain) {
+            // Filter by domain: get all, clear all, re-add non-matching
+            const all = this._handle.getCookies();
+            this._handle.clearCookies();
+            for (const line of all) {
+                // Netscape format: domain \t ... — first field is domain
+                const parts = line.split('\t');
+                if (parts[0] !== domain && parts[0] !== `.${domain}`) {
+                    this._handle.addCookie(line);
+                }
+            }
+        }
+        else {
+            this._handle.clearCookies();
+        }
+    }
+    // ─── Internal ─────────────────────────────────────────────────────────
+    /**
+     * Core request method — uses the persistent handle directly for cookie
+     * persistence and connection reuse. Per-request options are set on the
+     * handle before each perform call.
+     *
+     * **WARNING**: This method calls `curl.perform()` which is a synchronous
+     * blocking FFI call. The Node.js event loop is blocked for the duration
+     * of the HTTP request. For high-concurrency server environments, consider
+     * using the low-level `Curl` API with `performAsync()` instead.
+     *
+     * A non-blocking Session implementation using `curl_multi` + libuv polling
+     * is planned for a future release.
+     */
+    async _request(method, url, options) {
+        const curl = this._handle;
+        // Per-request impersonation override
+        if (options?.impersonate && options.impersonate !== this._options.impersonate) {
+            try {
+                curl.impersonateStr(options.impersonate, this._options.defaultHeaders);
+            }
+            catch (e) {
+                throw (0, errors_js_1.parseCurlError)(e instanceof Error ? e.message : String(e));
+            }
+        }
+        // Build URL with params
+        let finalUrl = url;
+        if (options?.params) {
+            const entries = {};
+            for (const [k, v] of Object.entries(options.params)) {
+                entries[k] = String(v);
+            }
+            const qs = new URLSearchParams(entries).toString();
+            finalUrl += (url.includes('?') ? '&' : '?') + qs;
+        }
+        curl.setoptStr(NativeCurlOpt.Url, finalUrl);
+        // HTTP method — always set explicitly to prevent method leakage
+        // between requests on the persistent handle (P2 fix)
+        curl.setoptStr(NativeCurlOpt.CustomRequest, method);
+        if (method === 'GET' || method === 'HEAD' || method === 'DELETE') {
+            curl.setoptLong(NativeCurlOpt.Post, 0);
+        }
+        else {
+            // Re-enable POST mode for POST/PUT/PATCH — required after a
+            // previous GET explicitly disabled it (P2 lifecycle fix)
+            curl.setoptLong(NativeCurlOpt.Post, 1);
+        }
+        // Headers: merge session + request
+        const headerList = [];
+        if (this._options.headers) {
+            for (const [k, v] of Object.entries(this._options.headers)) {
+                headerList.push(`${k}: ${v}`);
+            }
+        }
+        if (options?.headers) {
+            for (const [k, v] of Object.entries(options.headers)) {
+                headerList.push(`${k}: ${v}`);
+            }
+        }
+        // Always set headers to prevent stale headers from previous requests (P4 fix)
+        curl.setoptList(NativeCurlOpt.HttpHeader, headerList.length > 0 ? headerList : ['_:']);
+        // Body
+        if (options?.data !== undefined) {
+            let body;
+            if (Buffer.isBuffer(options.data)) {
+                body = options.data.toString('utf8');
+            }
+            else if (typeof options.data === 'object') {
+                body = JSON.stringify(options.data);
+                if (!headerList.some((h) => h.toLowerCase().startsWith('content-type'))) {
+                    curl.setoptList(NativeCurlOpt.HttpHeader, [
+                        ...headerList,
+                        'Content-Type: application/json',
+                    ]);
+                }
+            }
+            else {
+                body = options.data;
+            }
+            // Reset PostFieldSize to -1 (auto-detect from string length) before
+            // setting PostFields. This is required because a previous bodyless
+            // request may have set PostFieldSize=0, causing curl to ignore the
+            // body even when PostFields is set (P3 lifecycle fix).
+            curl.setoptLong(NativeCurlOpt.PostFieldSize, -1);
+            curl.setoptStr(NativeCurlOpt.PostFields, body);
+        }
+        else {
+            // Clear any previous POST body to prevent data leakage (P3 fix)
+            curl.setoptLong(NativeCurlOpt.PostFieldSize, 0);
+        }
+        // Timeout
+        const timeout = options?.timeout ?? this._options.timeout;
+        if (timeout && timeout > 0) {
+            curl.setoptLong(NativeCurlOpt.TimeoutMs, Math.floor(timeout * 1000));
+        }
+        else {
+            curl.setoptLong(NativeCurlOpt.TimeoutMs, 0);
+        }
+        // Redirects
+        const followRedirects = options?.followRedirects ?? this._options.followRedirects;
+        curl.setoptLong(NativeCurlOpt.FollowLocation, followRedirects ? 1 : 0);
+        const maxRedirects = options?.maxRedirects ?? this._options.maxRedirects;
+        curl.setoptLong(NativeCurlOpt.MaxRedirs, maxRedirects);
+        // Proxy
+        const proxy = options?.proxy ?? this._options.proxy;
+        if (proxy) {
+            curl.setoptStr(NativeCurlOpt.Proxy, proxy);
+        }
+        // SSL
+        const verify = options?.verify ?? this._options.verify;
+        if (verify === false) {
+            curl.setoptLong(NativeCurlOpt.SslVerifyPeer, 0);
+            curl.setoptLong(NativeCurlOpt.SslVerifyHost, 0);
+        }
+        // Perform synchronously on the persistent handle (keeps cookies!)
+        try {
+            const result = curl.perform();
+            return new response_js_1.Response(result);
+        }
+        catch (e) {
+            throw (0, errors_js_1.parseCurlError)(e instanceof Error ? e.message : String(e));
+        }
+    }
+}
+exports.Session = Session;
+//# sourceMappingURL=session.js.map