index.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */

export declare class ImpitError extends Error {}
export declare class HTTPError extends ImpitError {}
export declare class RequestError extends ImpitError {}
export declare class TransportError extends RequestError {}
export declare class TimeoutError extends TransportError {}
export declare class ConnectTimeout extends TimeoutError {}
export declare class ReadTimeout extends TimeoutError {}
export declare class WriteTimeout extends TimeoutError {}
export declare class PoolTimeout extends TimeoutError {}
export declare class NetworkError extends TransportError {}
export declare class ConnectError extends NetworkError {}
export declare class ReadError extends NetworkError {}
export declare class WriteError extends NetworkError {}
export declare class CloseError extends NetworkError {}
export declare class ProtocolError extends TransportError {}
export declare class LocalProtocolError extends ProtocolError {}
export declare class RemoteProtocolError extends ProtocolError {}
export declare class ProxyError extends TransportError {}
export declare class ProxyTunnelError extends ProxyError {
  status?: number
}
export declare class ProxyAuthRequired extends ProxyError {}
export declare class UnsupportedProtocol extends TransportError {}
export declare class DecodingError extends RequestError {}
export declare class TooManyRedirects extends RequestError {}
export declare class HTTPStatusError extends HTTPError {}
export declare class InvalidURL extends ImpitError {}
export declare class CookieConflict extends ImpitError {}
export declare class StreamError extends ImpitError {}
export declare class StreamConsumed extends StreamError {}
export declare class ResponseNotRead extends StreamError {}
export declare class RequestNotRead extends StreamError {}
export declare class StreamClosed extends StreamError {}

export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array
/**
 * The main class of the `impit` package
 *
 * This class is the primary interface for making HTTP requests.
 * It provides methods to configure the Impit instance and to perform requests.
 *
 * @example
 * ```ts
 * import { Impit } from 'impit';
 *
 * const impit = new Impit();
 * const response = await impit.fetch('https://example.com');
 * console.log(await response.text());
 * ```
 *
 * One `Impit` instance represents a single (possibly impersonated) user agent.
 *
 * Note that all the requests made by this instance will share the same configuration,
 * resources (e.g. cookie jar and connection pool), and other settings.
 */
export declare class Impit {
  /**
   * Creates a new `Impit` instance with the given options.
   *
   * The `options` parameter allows you to customize the behavior of the Impit instance.
   * If no options are provided, default settings will be used.
   *
   * @example
   * ```ts
   * import { Impit } from 'impit';
   *
   * const impit = new Impit({
   *    timeout: 5e3, // Set a default timeout of 5000
   *    headers: {
   *       'Authorization: 'Bearer <token>',
   *    },
   *    browser: 'chrome',
   * });
   * ```
   */
  constructor(options?: ImpitOptions | undefined | null)
  /**
   * Fetch a URL with the given options.
   *
   * This method performs an HTTP request to the specified URL using the provided options.
   * It returns a promise that resolves to an {@link ImpitResponse} object containing the response data.
   *
   * This method is designed to be API-compatible with the {@link https://developer.mozilla.org/en-US/docs/Web/API/fetch | Fetch API `fetch`} global method.
   *
   * @example
   * ```ts
   * import { Impit } from 'impit';
   *
   * const impit = new Impit();
   * const response = await impit.fetch('https://example.com', {
   *     method: 'GET',
   *     headers: {
   *         'Accept': 'application/json'
   *     },
   *     timeout: 5e3,
   * });
   * ```
   */
  fetch(resource: string | URL | Request, init?: RequestInit): Promise<ImpitResponse>
}
export type ImpitWrapper = Impit

/**
 * Represents an HTTP response.
 *
 * The `ImpitResponse` class provides access to the response status, headers, and body.
 * It also includes methods to read the response body in various formats such as text, JSON,
 * ArrayBuffer, and as a stream.
 *
 * This class is designed to be API-compatible with the {@link https://developer.mozilla.org/en-US/docs/Web/API/Response | Fetch API Response} class.
 *
 * @hideconstructor
 */
export declare class ImpitResponse {
  /**
   * HTTP status code of the response.
   *
   * Example: `200` for a successful response.
   */
  status: number
  /**
   * Status text of the response.
   *
   * A short description of the status code.
   *
   * Example: "OK" for status code 200.
   */
  statusText: string
  /**
   * HTTP headers of the response.
   *
   * An instance of the {@link https://developer.mozilla.org/en-US/docs/Web/API/Headers | Headers} class.
   */
  headers: Headers
  /** `true` if the response status code is in the range 200-299. */
  ok: boolean
  /**
   * URL of the response.
   *
   * In case of redirects, this will be the final URL after all redirects have been followed.
   */
  url: string
  /** @ignore */
  decodeBuffer(buffer: Buffer): string
  /**
   * Returns the response body as an `ArrayBuffer`.
   *
   * This method is asynchronous and returns a promise that resolves to an `ArrayBuffer` containing the response body data.
   *
   * @example
   * ```ts
   * const response = await impit.fetch('https://example.com');
   * const arrayBuffer = await response.arrayBuffer();
   *
   * console.log(arrayBuffer); // ArrayBuffer([ 0x3c, 0x68, 0x74, 0x6d, 0x6c, ... ])
   * ```
   *
   * Note that you cannot call this method multiple times on the same response instance,
   * as the response body can only be consumed once. Subsequent calls will result in an error.
   */
  arrayBuffer(): Promise<ArrayBuffer>
  /**
   * Returns the response body as a `Uint8Array`.
   *
   * This method is asynchronous and returns a promise that resolves to a `Uint8Array` containing the response body data.
   *
   * @example
   * ```ts
   * const response = await impit.fetch('https://example.com');
   * const uint8Array = await response.bytes();
   *
   * console.log(uint8Array); // Uint8Array([ 0x3c, 0x68, 0x74, 0x6d, 0x6c, ... ])
   * ```
   *
   * Note that you cannot call this method multiple times on the same response instance,
   * as the response body can only be consumed once. Subsequent calls will result in an error.
   */
  bytes(): Promise<Uint8Array>
  /**
   * Returns the response body as a string.
   *
   * This method is asynchronous and returns a promise that resolves to a string containing the response body data.
   *
   * @example
   * ```ts
   * const response = await impit.fetch('https://example.com');
   * const text = await response.text();
   *
   * console.log(text); // "<!doctype html><html>...</html>"
   * ```
   */
  text(): Promise<string>
  /**
   * Parses the response body as JSON.
   *
   * This method is asynchronous and returns a promise that resolves to the parsed JSON object.
   *
   * @example
   * ```ts
   * const response = await impit.fetch('https://api.example.com/data');
   * const data = await response.json();
   *
   * console.log(data); // Parsed JSON object
   * ```
   */
  json(): Promise<any>
  /**
   * Returns the response body as a `ReadableStream`.
   *
   * This property provides access to the response body as a stream of data, allowing you to read it in chunks.
   *
   * @example
   * ```ts
   * const response = await impit.fetch('https://example.com');
   * const reader = response.body.getReader();
   *
   * let result;
   * while (!(result = await reader.read()).done) {
   *    console.log(result.value); // Uint8Array chunk
   * }
   * ```
   */
  get body(): ReadableStream<Uint8Array>
  /**
   * Aborts the response.
   *
   * This API is called internally and can change without notice.
   *
   * Use `fetch(url, { signal: AbortSignal })` to abort a request instead.
   */
  abort(): void
}

/**
 * Supported browsers for emulation.
 *
 * See {@link ImpitOptions.browser} for more details and usage.
 */
export type Browser =  'chrome'|
'chrome100'|
'chrome101'|
'chrome104'|
'chrome107'|
'chrome110'|
'chrome116'|
'chrome124'|
'chrome125'|
'chrome131'|
'chrome136'|
'chrome142'|
'firefox'|
'firefox128'|
'firefox133'|
'firefox135'|
'firefox144';

export type HttpMethod =  'GET'|
'POST'|
'PUT'|
'DELETE'|
'PATCH'|
'HEAD'|
'OPTIONS'|
'TRACE';

/**
 * Options for configuring an {@link Impit} instance.
 *
 * These options allow you to customize the behavior of the Impit instance, including browser emulation, TLS settings, proxy configuration, timeouts, and more.
 *
 * If no options are provided, default settings will be used.
 *
 * See {@link Impit} for usage.
 */
export interface ImpitOptions {
  /**
   * What browser to emulate.
   *
   * @default `undefined` (no browser emulation)
   */
  browser?: Browser
  /**
   * Ignore TLS errors such as invalid certificates.
   *
   * @default `false`
   */
  ignoreTlsErrors?: boolean
  /**
   * Whether to fallback to a vanilla user-agent if the emulated browser
   * is not supported by the target website.
   *
   * @default `false`
   */
  vanillaFallback?: boolean
  /**
   * Proxy URL to use for this Impit instance.
   *
   * Supports HTTP, HTTPS, SOCKS4 and SOCKS5 proxies.
   *
   * **Warning:** Not supported when HTTP/3 is enabled.
   *
   * @default `undefined` (no proxy)
   */
  proxyUrl?: string
  /** Default timeout for this Impit instance in milliseconds. */
  timeout?: number
  /**
   * Enable HTTP/3 support.
   *
   * **Warning:** Proxies are not supported when HTTP/3 is enabled.
   *
   * @default `false`
   */
  http3?: boolean
  /**
   * Whether to follow redirects or not.
   *
   * @default `true`
   */
  followRedirects?: boolean
  /**
   * Maximum number of redirects to follow.
   *
   * If this number is exceeded, the request will be rejected with an error.
   *
   * @default `10`
   */
  maxRedirects?: number
  /**
   * Pass a {@link https://github.com/salesforce/tough-cookie | `ToughCookie`} instance to Impit.
   *
   * This `impit` instance will use the provided cookie jar for both storing and retrieving cookies.
   *
   * @default `undefined` (no cookie jar, i.e., cookies are not stored or sent across requests)
   */
cookieJar?: { setCookie: (cookie: string, url: string, cb?: any) => Promise<void> | void, getCookieString: (url: string) => Promise<string> | string }
/**
 * Additional headers to include in every request made by this Impit instance.
 *
 * Can be an object, a Map, or an array of tuples or an instance of the {@link https://developer.mozilla.org/en-US/docs/Web/API/Headers | Headers} class.
 *
 * These headers override any browser impersonation headers (set via the {@link ImpitOptions.browser} option)
 * and are in turn overridden by request-specific headers (set via {@link RequestInit.headers}).
 * Header matching is **case-insensitive** — for example, setting `user-agent` here will override
 * the impersonation `User-Agent` header.
 *
 * To remove an impersonated header, pass an empty string as the value.
 *
 * @default `undefined` (no additional headers)
 */
headers?: Headers | Record<string, string> | [string, string][]
/**
 * Local address to bind the client to. Useful for testing purposes or when you want to bind the client to a specific network interface.
 *
 * Can be an IP address in the format `xxx.xxx.xxx.xxx` (for IPv4) or `ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff` (for IPv6).
 *
 * @default `undefined` (the OS will choose the local address)
 */
localAddress?: string
}

/**
 * Options for configuring an individual HTTP request.
 *
 * These options allow you to customize the behavior of a specific request, including the HTTP method, headers, body, timeout, and whether to force HTTP/3.
 *
 * If no options are provided, default settings will be used.
 *
 * See {@link Impit.fetch} for usage.
 */
export interface RequestInit {
  /**
   * HTTP method to use for the request. Default is `GET`.
   *
   * Can be one of: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
   */
  method?: HttpMethod
  /**
   * Additional headers to include in the request.
   *
   * Can be an object, a Map, or an array of tuples or an instance of the {@link https://developer.mozilla.org/en-US/docs/Web/API/Headers | Headers} class.
   *
   * Note that headers set here will override any default headers set in {@link ImpitOptions.headers}.
   *
   * Header matching is **case-insensitive** — for example, setting `user-agent` here will override
   * the impersonation `User-Agent` header.
   *
   * To remove an impersonated header, pass an empty string as the value.
   */
  headers?: Headers | Record<string, string> | [string, string][]
  /** Request body. Can be a string, Buffer, ArrayBuffer, TypedArray, DataView, Blob, File, URLSearchParams, FormData or ReadableStream. */
  body?: string | ArrayBuffer | Uint8Array | DataView | Blob | File | URLSearchParams | FormData | ReadableStream
  /** Request timeout in milliseconds. Overrides the Impit-wide timeout option from {@link ImpitOptions.timeout}. */
  timeout?: number
  /** Force the request to use HTTP/3. If the server doesn't expect HTTP/3 or the Impit instance doesn't have HTTP/3 enabled (via the {@link ImpitOptions.http3} option), the request will fail. */
  forceHttp3?: boolean
  /** Abort signal to cancel the request. */
  signal?: AbortSignal
  /**
   * The redirect mode to use for this request.
   *
   * - `'follow'` (default): Follow redirects automatically.
   * - `'manual'`: Do not follow redirects; return the 3xx response as-is.
   * - `'error'`: Throw a `TypeError` if the response is a redirect.
   *
   * When set, this overrides the instance-level {@link ImpitOptions.followRedirects} option for this request.
   *
   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#redirect | Fetch API `redirect` option}
   */
  redirect?: 'follow' | 'manual' | 'error'
}