rezo 1.0.2 → 1.0.4

package/dist/platform/node.d.ts

@@ -104,7 +104,7 @@ export type RezoHeadersInit = [
 	string,
 	string
 ][] | Record<string, string> | Headers | RezoHttpHeaders | RezoHeaders | OutgoingHttpHeaders;
-declare class RezoHeaders extends Headers {
+export declare class RezoHeaders extends Headers {
 	constructor(init?: RezoHeadersInit);
 	getAll(name: "set-cookie" | "Set-Cookie"): string[];
 	getSetCookie(): string[];
@@ -194,7 +194,7 @@ declare class Cookie extends TouchCookie {
 	 */
 	static isCookie(cookie: any): cookie is Cookie;
 }
-declare class RezoCookieJar extends TouchCookieJar {
+export declare class RezoCookieJar extends TouchCookieJar {
 	constructor();
 	constructor(cookies: Cookie[]);
 	constructor(cookies: Cookie[], url: string);
@@ -283,7 +283,7 @@ export interface Options extends ReadableOptions {
 	maxDataSize?: number;
 	pauseStreams?: boolean;
 }
-declare class RezoFormData extends NodeFormData {
+export declare class RezoFormData extends NodeFormData {
 	constructor(options?: Options);
 	/**
 	 * Get field entries as array of [name, value] pairs
@@ -899,6 +899,292 @@ export interface RezoDownloadResponse extends DownloadResponse {
  */
 export interface RezoUploadResponse extends UploadResponse {
 }
+/**
+ * Rezo ProxyManager Types
+ * Type definitions for advanced proxy rotation and management
+ *
+ * @module proxy/types
+ * @author Yuniq Solutions Team
+ * @version 1.0.0
+ */
+/** Supported proxy protocols */
+export type ProxyProtocol = "socks4" | "socks5" | "http" | "https";
+/**
+ * Proxy information structure
+ * Represents a single proxy server with its connection details
+ */
+export interface ProxyInfo {
+	/** Unique identifier for the proxy (auto-generated if not provided) */
+	id?: string;
+	/** The proxy protocol to use */
+	protocol: ProxyProtocol;
+	/** Proxy server hostname or IP address */
+	host: string;
+	/** Proxy server port number */
+	port: number;
+	/** Optional authentication credentials for the proxy */
+	auth?: {
+		/** Username for proxy authentication */
+		username: string;
+		/** Password for proxy authentication */
+		password: string;
+	};
+	/** Optional label for identification/logging */
+	label?: string;
+	/** Optional metadata for custom tracking */
+	metadata?: Record<string, unknown>;
+}
+/**
+ * Proxy rotation strategies
+ * - `random`: Select a random proxy from the pool for each request
+ * - `sequential`: Use proxies in order, optionally rotating after N requests
+ * - `per-proxy-limit`: Use each proxy for a maximum number of requests, then permanently remove
+ */
+export type RotationStrategy = "random" | "sequential" | "per-proxy-limit";
+/**
+ * Rotation configuration for different strategies
+ */
+export type RotationConfig = {
+	/** Random selection from available proxies */
+	rotation: "random";
+} | {
+	/** Sequential rotation through proxy list */
+	rotation: "sequential";
+	/** Number of requests before rotating to next proxy (default: 1) */
+	requestsPerProxy?: number;
+} | {
+	/** Use each proxy for a limited number of total requests, then remove */
+	rotation: "per-proxy-limit";
+	/** Maximum requests per proxy before permanent removal */
+	limit: number;
+};
+/**
+ * Cooldown configuration for disabled proxies
+ */
+export interface ProxyCooldownConfig {
+	/** Whether to enable automatic re-enabling after cooldown */
+	enabled: boolean;
+	/** Duration in milliseconds before re-enabling a disabled proxy */
+	durationMs: number;
+}
+/**
+ * Base proxy manager configuration (without rotation)
+ * Complete configuration for proxy rotation, filtering, and failure handling
+ */
+export interface ProxyManagerBaseConfig {
+	/** Array of proxies to manage */
+	proxies: ProxyInfo[];
+	/**
+	 * Whitelist patterns for URLs that should use proxy
+	 * - String: exact domain match (e.g., 'api.example.com') or subdomain match (e.g., 'example.com' matches '*.example.com')
+	 * - RegExp: regex pattern to test against full URL
+	 * If not set, all URLs use proxy
+	 */
+	whitelist?: (string | RegExp)[];
+	/**
+	 * Blacklist patterns for URLs that should NOT use proxy (go direct)
+	 * - String: exact domain match or subdomain match
+	 * - RegExp: regex pattern to test against full URL
+	 * Blacklist is checked after whitelist
+	 */
+	blacklist?: (string | RegExp)[];
+	/**
+	 * Automatically disable proxies after consecutive failures
+	 * @default false
+	 */
+	autoDisableDeadProxies?: boolean;
+	/**
+	 * Number of consecutive failures before disabling a proxy
+	 * Only applies when autoDisableDeadProxies is true
+	 * @default 3
+	 */
+	maxFailures?: number;
+	/**
+	 * Cooldown configuration for disabled proxies
+	 * If not set or enabled: false, proxies are permanently removed when disabled
+	 */
+	cooldown?: ProxyCooldownConfig;
+	/**
+	 * Whether to throw error when no proxy is available
+	 * - true (default): Throw RezoError when no proxies available
+	 * - false: Proceed with direct connection (no proxy)
+	 * @default true
+	 */
+	failWithoutProxy?: boolean;
+	/**
+	 * Whether to retry the request with next proxy on failure
+	 * @default false
+	 */
+	retryWithNextProxy?: boolean;
+	/**
+	 * Maximum retry attempts when retryWithNextProxy is enabled
+	 * @default 3
+	 */
+	maxProxyRetries?: number;
+}
+/**
+ * Full proxy manager configuration
+ * Combines base config with rotation strategy
+ */
+export type ProxyManagerConfig = ProxyManagerBaseConfig & RotationConfig;
+/**
+ * Internal proxy state tracking
+ * Used internally by ProxyManager to track usage and failures
+ */
+export interface ProxyState {
+	/** The proxy info */
+	proxy: ProxyInfo;
+	/** Number of requests made through this proxy */
+	requestCount: number;
+	/** Number of consecutive failures */
+	failureCount: number;
+	/** Total number of successful requests */
+	successCount: number;
+	/** Total number of failed requests */
+	totalFailures: number;
+	/** Whether the proxy is currently active */
+	isActive: boolean;
+	/** Reason for being disabled (if applicable) */
+	disabledReason?: "dead" | "limit-reached" | "manual";
+	/** Timestamp when proxy was disabled */
+	disabledAt?: number;
+	/** Timestamp when proxy will be re-enabled (if cooldown enabled) */
+	reenableAt?: number;
+	/** Last successful request timestamp */
+	lastSuccessAt?: number;
+	/** Last failure timestamp */
+	lastFailureAt?: number;
+	/** Last error message */
+	lastError?: string;
+}
+/**
+ * Proxy manager status snapshot
+ * Provides overview of all proxies in the manager
+ */
+export interface ProxyManagerStatus {
+	/** Active proxies available for use */
+	active: ProxyInfo[];
+	/** Disabled proxies (dead or limit reached) */
+	disabled: ProxyInfo[];
+	/** Proxies in cooldown waiting to be re-enabled */
+	cooldown: ProxyInfo[];
+	/** Total number of proxies */
+	total: number;
+	/** Current rotation strategy */
+	rotation: RotationStrategy;
+	/** Total requests made through the manager */
+	totalRequests: number;
+	/** Total successful requests */
+	totalSuccesses: number;
+	/** Total failed requests */
+	totalFailures: number;
+}
+/**
+ * Result from proxy selection
+ */
+export interface ProxySelectionResult {
+	/** Selected proxy (null if should go direct) */
+	proxy: ProxyInfo | null;
+	/** Reason for selection result */
+	reason: "selected" | "whitelist-no-match" | "blacklist-match" | "no-proxies-available" | "disabled";
+}
+/**
+ * Context for beforeProxySelect hook
+ */
+export interface BeforeProxySelectContext {
+	/** Request URL */
+	url: string;
+	/** Available active proxies */
+	proxies: ProxyInfo[];
+	/** Whether this is a retry attempt */
+	isRetry: boolean;
+	/** Retry count (0 for initial request) */
+	retryCount: number;
+}
+/**
+ * Context for afterProxySelect hook
+ */
+export interface AfterProxySelectContext {
+	/** Request URL */
+	url: string;
+	/** Selected proxy (null if going direct) */
+	proxy: ProxyInfo | null;
+	/** Selection reason */
+	reason: ProxySelectionResult["reason"];
+}
+/**
+ * Context for beforeProxyError hook
+ */
+export interface BeforeProxyErrorContext {
+	/** The proxy that failed */
+	proxy: ProxyInfo;
+	/** The error that occurred */
+	error: Error;
+	/** Request URL */
+	url: string;
+	/** Current failure count for this proxy */
+	failureCount: number;
+	/** Whether proxy will be disabled after this error */
+	willBeDisabled: boolean;
+}
+/**
+ * Context for afterProxyError hook
+ */
+export interface AfterProxyErrorContext {
+	/** The proxy that failed */
+	proxy: ProxyInfo;
+	/** The error that occurred */
+	error: Error;
+	/** Action taken after error */
+	action: "retry-next-proxy" | "disabled" | "continue";
+	/** Next proxy for retry (if action is 'retry-next-proxy') */
+	nextProxy?: ProxyInfo;
+}
+/**
+ * Context for beforeProxyDisable hook
+ * Return false to prevent disabling
+ */
+export interface BeforeProxyDisableContext {
+	/** The proxy about to be disabled */
+	proxy: ProxyInfo;
+	/** Reason for disabling */
+	reason: "dead" | "limit-reached" | "manual";
+	/** Current proxy state */
+	state: ProxyState;
+}
+/**
+ * Context for afterProxyDisable hook
+ */
+export interface AfterProxyDisableContext {
+	/** The proxy that was disabled */
+	proxy: ProxyInfo;
+	/** Reason for disabling */
+	reason: "dead" | "limit-reached" | "manual";
+	/** Whether cooldown is enabled for re-enabling */
+	hasCooldown: boolean;
+	/** Timestamp when proxy will be re-enabled (if cooldown enabled) */
+	reenableAt?: number;
+}
+/**
+ * Context for afterProxyRotate hook
+ */
+export interface AfterProxyRotateContext {
+	/** Previous proxy (null if first selection) */
+	from: ProxyInfo | null;
+	/** New proxy */
+	to: ProxyInfo;
+	/** Reason for rotation */
+	reason: "scheduled" | "failure" | "limit-reached";
+}
+/**
+ * Context for afterProxyEnable hook
+ */
+export interface AfterProxyEnableContext {
+	/** The proxy that was enabled */
+	proxy: ProxyInfo;
+	/** Reason for enabling */
+	reason: "cooldown-expired" | "manual";
+}
 /**
  * Context provided to beforeRequest hook
  * Contains metadata about the current request state
@@ -1177,6 +1463,46 @@ export type OnTimeoutHook = (event: TimeoutEvent, config: RezoConfig) => void;
  * Use for cleanup, logging
  */
 export type OnAbortHook = (event: AbortEvent, config: RezoConfig) => void;
+/**
+ * Hook called before a proxy is selected
+ * Can return a specific proxy to override selection
+ */
+export type BeforeProxySelectHook = (context: BeforeProxySelectContext) => ProxyInfo | void | Promise<ProxyInfo | void>;
+/**
+ * Hook called after a proxy is selected
+ * Use for logging, analytics
+ */
+export type AfterProxySelectHook = (context: AfterProxySelectContext) => void | Promise<void>;
+/**
+ * Hook called before a proxy error is processed
+ * Use for error inspection, custom handling
+ */
+export type BeforeProxyErrorHook = (context: BeforeProxyErrorContext) => void | Promise<void>;
+/**
+ * Hook called after a proxy error is processed
+ * Use for error logging, fallback logic
+ */
+export type AfterProxyErrorHook = (context: AfterProxyErrorContext) => void | Promise<void>;
+/**
+ * Hook called before a proxy is disabled
+ * Return false to prevent disabling
+ */
+export type BeforeProxyDisableHook = (context: BeforeProxyDisableContext) => boolean | void | Promise<boolean | void>;
+/**
+ * Hook called after a proxy is disabled
+ * Use for notifications, logging
+ */
+export type AfterProxyDisableHook = (context: AfterProxyDisableContext) => void | Promise<void>;
+/**
+ * Hook called when proxy rotation occurs
+ * Use for monitoring rotation patterns
+ */
+export type AfterProxyRotateHook = (context: AfterProxyRotateContext) => void | Promise<void>;
+/**
+ * Hook called when a proxy is re-enabled
+ * Use for notifications, logging
+ */
+export type AfterProxyEnableHook = (context: AfterProxyEnableContext) => void | Promise<void>;
 /**
  * Collection of all hook types
  * All hooks are arrays to allow multiple handlers
@@ -1193,12 +1519,29 @@ export interface RezoHooks {
 	afterParse: AfterParseHook[];
 	beforeCookie: BeforeCookieHook[];
 	afterCookie: AfterCookieHook[];
+	beforeProxySelect: BeforeProxySelectHook[];
+	afterProxySelect: AfterProxySelectHook[];
+	beforeProxyError: BeforeProxyErrorHook[];
+	afterProxyError: AfterProxyErrorHook[];
+	beforeProxyDisable: BeforeProxyDisableHook[];
+	afterProxyDisable: AfterProxyDisableHook[];
+	afterProxyRotate: AfterProxyRotateHook[];
+	afterProxyEnable: AfterProxyEnableHook[];
 	onSocket: OnSocketHook[];
 	onDns: OnDnsHook[];
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
 }
+/**
+ * Create empty hooks object with all arrays initialized
+ */
+export declare function createDefaultHooks(): RezoHooks;
+/**
+ * Merge base hooks with override hooks
+ * Overrides are appended to base hooks (base runs first)
+ */
+export declare function mergeHooks(base: RezoHooks, overrides?: Partial<RezoHooks>): RezoHooks;
 /**
  * Configuration object that encapsulates comprehensive request execution metadata and response processing information.
  * This interface serves as the central configuration hub for HTTP requests, containing both input parameters
@@ -1540,7 +1883,58 @@ export interface RezoConfig {
 	 */
 	useCookies: boolean;
 }
-declare class RezoError<T = any> extends Error {
+export declare enum RezoErrorCode {
+	CONNECTION_REFUSED = "ECONNREFUSED",
+	CONNECTION_RESET = "ECONNRESET",
+	CONNECTION_TIMEOUT = "ETIMEDOUT",
+	DNS_LOOKUP_FAILED = "ENOTFOUND",
+	DNS_TEMPORARY_FAILURE = "EAI_AGAIN",
+	HOST_UNREACHABLE = "EHOSTUNREACH",
+	NETWORK_UNREACHABLE = "ENETUNREACH",
+	BROKEN_PIPE = "EPIPE",
+	HTTP_ERROR = "REZ_HTTP_ERROR",
+	REDIRECT_DENIED = "REZ_REDIRECT_DENIED",
+	MAX_REDIRECTS = "REZ_MAX_REDIRECTS_EXCEEDED",
+	REDIRECT_CYCLE = "REZ_REDIRECT_CYCLE_DETECTED",
+	MISSING_REDIRECT_LOCATION = "REZ_MISSING_REDIRECT_LOCATION",
+	DECOMPRESSION_ERROR = "REZ_DECOMPRESSION_ERROR",
+	REQUEST_TIMEOUT = "UND_ERR_REQUEST_TIMEOUT",
+	HEADERS_TIMEOUT = "UND_ERR_HEADERS_TIMEOUT",
+	CONNECT_TIMEOUT = "UND_ERR_CONNECT_TIMEOUT",
+	ABORTED = "ABORT_ERR",
+	DOWNLOAD_FAILED = "REZ_DOWNLOAD_FAILED",
+	UPLOAD_FAILED = "REZ_UPLOAD_FAILED",
+	STREAM_ERROR = "REZ_STREAM_ERROR",
+	BODY_TOO_LARGE = "REZ_BODY_TOO_LARGE",
+	RESPONSE_TOO_LARGE = "REZ_RESPONSE_TOO_LARGE",
+	INVALID_JSON = "REZ_INVALID_JSON",
+	INVALID_URL = "ERR_INVALID_URL",
+	INVALID_PROTOCOL = "ERR_INVALID_PROTOCOL",
+	INVALID_ARGUMENT = "ERR_INVALID_ARG_TYPE",
+	FILE_PERMISSION = "REZ_FILE_PERMISSION_ERROR",
+	PROXY_CONNECTION_FAILED = "REZ_PROXY_CONNECTION_FAILED",
+	PROXY_AUTH_FAILED = "REZ_PROXY_AUTHENTICATION_FAILED",
+	PROXY_TARGET_UNREACHABLE = "REZ_PROXY_TARGET_UNREACHABLE",
+	PROXY_TIMEOUT = "REZ_PROXY_TIMEOUT",
+	PROXY_ERROR = "REZ_PROXY_ERROR",
+	PROXY_INVALID_PROTOCOL = "REZ_PROXY_INVALID_PROTOCOL",
+	PROXY_INVALID_CONFIG = "REZ_PROXY_INVALID_HOSTPORT",
+	SOCKS_CONNECTION_FAILED = "REZ_SOCKS_CONNECTION_FAILED",
+	SOCKS_AUTH_FAILED = "REZ_SOCKS_AUTHENTICATION_FAILED",
+	SOCKS_TARGET_UNREACHABLE = "REZ_SOCKS_TARGET_CONNECTION_FAILED",
+	SOCKS_PROTOCOL_ERROR = "REZ_SOCKS_PROTOCOL_ERROR",
+	SOCKS_UNSUPPORTED_VERSION = "REZ_SOCKS_UNSUPPORTED_VERSION",
+	TLS_HANDSHAKE_TIMEOUT = "ERR_TLS_HANDSHAKE_TIMEOUT",
+	TLS_PROTOCOL_ERROR = "EPROTO",
+	TLS_PROTOCOL_VERSION = "ERR_TLS_INVALID_PROTOCOL_VERSION",
+	CERTIFICATE_HOSTNAME_MISMATCH = "ERR_TLS_CERT_ALTNAME_INVALID",
+	CERTIFICATE_EXPIRED = "CERT_HAS_EXPIRED",
+	CERTIFICATE_SELF_SIGNED = "SELF_SIGNED_CERT_IN_CHAIN",
+	CERTIFICATE_VERIFY_FAILED = "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	RATE_LIMITED = "REZ_RATE_LIMITED",
+	UNKNOWN_ERROR = "REZ_UNKNOWN_ERROR"
+}
+export declare class RezoError<T = any> extends Error {
 	readonly code?: string;
 	readonly errno?: number;
 	readonly config: RezoConfig;
@@ -1589,16 +1983,13 @@ declare class RezoError<T = any> extends Error {
 	toString(): string;
 	getFullDetails(): string;
 }
-/**
- * Supported proxy protocols for network requests
- */
-export type ProxyProtocol = "http" | "https" | "socks4" | "socks5";
+type ProxyProtocol$1 = "http" | "https" | "socks4" | "socks5";
 /**
  * Configuration options for proxy connections
  */
 export type ProxyOptions = {
 	/** The proxy protocol to use */
-	protocol: ProxyProtocol;
+	protocol: ProxyProtocol$1;
 	/** Proxy server hostname or IP address */
 	host: string;
 	/** Proxy server port number */
@@ -1639,6 +2030,51 @@ export type RezoString = string;
  * Standard HTTP methods supported by Rezo
  */
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT";
+/**
+ * Response data types that control how Rezo parses the response body.
+ *
+ * @description
+ * Specifies how the response body should be parsed and returned in `response.data`.
+ * Choose the type that matches your expected response format.
+ *
+ * **Available Types:**
+ *
+ * - `'json'` - Parse response as JSON. Returns parsed object/array.
+ *   Best for REST APIs that return JSON data.
+ *
+ * - `'text'` - Return response as a string. No parsing applied.
+ *   Best for HTML, XML, plain text, or when you need raw content.
+ *
+ * - `'blob'` - Return as Blob object (browser environments).
+ *   Best for binary data in browsers (images, files, etc).
+ *
+ * - `'arrayBuffer'` - Return as ArrayBuffer.
+ *   Best for binary data processing, cryptographic operations.
+ *
+ * - `'buffer'` - Return as Node.js Buffer.
+ *   Best for binary data in Node.js (files, images, binary protocols).
+ *
+ * - `'auto'` - Auto-detect based on Content-Type header (default).
+ *   JSON for `application/json`, text for `text/*`, buffer otherwise.
+ *
+ * **Streaming Operations:**
+ * For streaming, use dedicated methods instead of responseType:
+ * - `rezo.stream(url)` - Returns StreamResponse for real-time data
+ * - `rezo.download(url, saveTo)` - Returns DownloadResponse with progress
+ * - `rezo.upload(url, data)` - Returns UploadResponse with progress
+ *
+ * @example
+ * // Get JSON data (default for JSON APIs)
+ * const { data } = await rezo.get('/api/users', { responseType: 'json' });
+ *
+ * // Get HTML as text
+ * const { data: html } = await rezo.get('/page', { responseType: 'text' });
+ *
+ * // Get image as buffer
+ * const { data: imageBuffer } = await rezo.get('/image.png', { responseType: 'buffer' });
+ *
+ * @default 'auto'
+ */
 type ResponseType$1 = "json" | "text" | "blob" | "arrayBuffer" | "buffer" | "auto";
 /**
  * MIME content types for request/response bodies
@@ -2096,6 +2532,162 @@ declare class ResponseCache {
 	get isPersistent(): boolean;
 	getConfig(): ResponseCacheConfig;
 }
+type BeforeProxySelectHook$1 = (context: BeforeProxySelectContext) => ProxyInfo | void | Promise<ProxyInfo | void>;
+type AfterProxySelectHook$1 = (context: AfterProxySelectContext) => void | Promise<void>;
+type BeforeProxyErrorHook$1 = (context: BeforeProxyErrorContext) => void | Promise<void>;
+type AfterProxyErrorHook$1 = (context: AfterProxyErrorContext) => void | Promise<void>;
+type BeforeProxyDisableHook$1 = (context: BeforeProxyDisableContext) => boolean | void | Promise<boolean | void>;
+type AfterProxyDisableHook$1 = (context: AfterProxyDisableContext) => void | Promise<void>;
+type AfterProxyRotateHook$1 = (context: AfterProxyRotateContext) => void | Promise<void>;
+type AfterProxyEnableHook$1 = (context: AfterProxyEnableContext) => void | Promise<void>;
+/**
+ * Proxy hooks collection for ProxyManager events
+ */
+export interface ProxyHooks {
+	beforeProxySelect: BeforeProxySelectHook$1[];
+	afterProxySelect: AfterProxySelectHook$1[];
+	beforeProxyError: BeforeProxyErrorHook$1[];
+	afterProxyError: AfterProxyErrorHook$1[];
+	beforeProxyDisable: BeforeProxyDisableHook$1[];
+	afterProxyDisable: AfterProxyDisableHook$1[];
+	afterProxyRotate: AfterProxyRotateHook$1[];
+	afterProxyEnable: AfterProxyEnableHook$1[];
+}
+declare class ProxyManager {
+	/** Configuration for the proxy manager */
+	readonly config: ProxyManagerConfig;
+	/** Internal proxy states map (proxyId -> state) */
+	private states;
+	/** Current index for sequential rotation */
+	private currentIndex;
+	/** Request counter for current proxy (sequential rotation) */
+	private currentProxyRequests;
+	/** Last selected proxy (for rotation tracking) */
+	private lastSelectedProxy;
+	/** Cooldown timers map (proxyId -> timerId) */
+	private cooldownTimers;
+	/** Total requests through manager */
+	private _totalRequests;
+	/** Total successful requests */
+	private _totalSuccesses;
+	/** Total failed requests */
+	private _totalFailures;
+	/** Proxy hooks */
+	hooks: ProxyHooks;
+	/**
+	 * Create a new ProxyManager instance
+	 * @param config - Proxy manager configuration
+	 */
+	constructor(config: ProxyManagerConfig);
+	/**
+	 * Create initial state for a proxy
+	 */
+	private createInitialState;
+	/**
+	 * Check if a URL should use proxy based on whitelist/blacklist
+	 * @param url - The request URL to check
+	 * @returns true if URL should use proxy, false if should go direct
+	 */
+	shouldProxy(url: string): boolean;
+	/**
+	 * Match a URL against a pattern
+	 */
+	private matchPattern;
+	/**
+	 * Get active proxies (not disabled)
+	 */
+	getActive(): ProxyInfo[];
+	/**
+	 * Get disabled proxies
+	 */
+	getDisabled(): ProxyInfo[];
+	/**
+	 * Get proxies in cooldown
+	 */
+	getCooldown(): ProxyInfo[];
+	/**
+	 * Process expired cooldowns and re-enable proxies
+	 */
+	private processExpiredCooldowns;
+	/**
+	 * Get next proxy based on rotation strategy
+	 * @param url - The request URL (for whitelist/blacklist checking)
+	 * @returns Selected proxy or null if should go direct
+	 */
+	next(url: string): ProxyInfo | null;
+	/**
+	 * Get detailed selection result with reason
+	 * @param url - The request URL
+	 * @returns Selection result with proxy and reason
+	 */
+	select(url: string): ProxySelectionResult;
+	/**
+	 * Select proxy based on rotation strategy
+	 */
+	private selectProxy;
+	/**
+	 * Report a successful request through a proxy
+	 * @param proxy - The proxy that succeeded
+	 */
+	reportSuccess(proxy: ProxyInfo): void;
+	/**
+	 * Report a failed request through a proxy
+	 * @param proxy - The proxy that failed
+	 * @param error - The error that occurred
+	 * @param url - Optional URL for hook context
+	 */
+	reportFailure(proxy: ProxyInfo, error: Error, url?: string): void;
+	/**
+	 * Disable a proxy from the pool
+	 * @param proxy - The proxy to disable
+	 * @param reason - Reason for disabling
+	 */
+	disableProxy(proxy: ProxyInfo, reason?: "dead" | "limit-reached" | "manual"): void;
+	/**
+	 * Enable a previously disabled proxy
+	 * @param proxy - The proxy to enable
+	 * @param reason - Reason for enabling
+	 */
+	enableProxy(proxy: ProxyInfo, reason?: "cooldown-expired" | "manual"): void;
+	/**
+	 * Add proxies to the pool
+	 * @param proxies - Proxies to add
+	 */
+	add(proxies: ProxyInfo | ProxyInfo[]): void;
+	/**
+	 * Remove proxies from the pool
+	 * @param proxies - Proxies to remove
+	 */
+	remove(proxies: ProxyInfo | ProxyInfo[]): void;
+	/**
+	 * Reset all proxies - re-enable all and reset counters
+	 */
+	reset(): void;
+	/**
+	 * Get current status of all proxies
+	 */
+	getStatus(): ProxyManagerStatus;
+	/**
+	 * Get state for a specific proxy
+	 * @param proxy - The proxy to get state for
+	 */
+	getProxyState(proxy: ProxyInfo): ProxyState | undefined;
+	/**
+	 * Check if any proxies are available
+	 */
+	hasAvailableProxies(): boolean;
+	/**
+	 * Destroy the manager and cleanup timers
+	 */
+	destroy(): void;
+	private runBeforeProxySelectHooksSync;
+	private runAfterProxySelectHooksSync;
+	private runBeforeProxyErrorHooksSync;
+	private runAfterProxyErrorHooksSync;
+	private runAfterProxyRotateHooks;
+	private runAfterProxyDisableHooks;
+	private runAfterProxyEnableHooks;
+}
 export type queueOptions = Options$1<PriorityQueue, QueueAddOptions>;
 export interface CacheConfig {
 	/** Response cache configuration */
@@ -2222,6 +2814,35 @@ export interface RezoDefaultOptions {
 	 * DNS cache defaults: 1 min TTL, 1000 entries
 	 */
 	cache?: CacheOption;
+	/**
+	 * Proxy manager for advanced proxy rotation and pool management
+	 * - Provide a `ProxyManager` instance for full control
+	 * - Or provide `ProxyManagerConfig` to auto-create internally
+	 *
+	 * Note: ProxyManager overrides `proxy` option when set.
+	 * Use `useProxyManager: false` per-request to bypass.
+	 *
+	 * @example
+	 * ```typescript
+	 * // With config (auto-creates ProxyManager)
+	 * const client = new Rezo({
+	 *   proxyManager: {
+	 *     rotation: 'random',
+	 *     proxies: [
+	 *       { protocol: 'socks5', host: '127.0.0.1', port: 1080 },
+	 *       { protocol: 'http', host: 'proxy.example.com', port: 8080 }
+	 *     ],
+	 *     whitelist: ['api.example.com'],
+	 *     autoDisableDeadProxies: true
+	 *   }
+	 * });
+	 *
+	 * // With ProxyManager instance
+	 * const pm = new ProxyManager({ rotation: 'sequential', proxies: [...] });
+	 * const client = new Rezo({ proxyManager: pm });
+	 * ```
+	 */
+	proxyManager?: ProxyManager | ProxyManagerConfig;
 }
 export interface httpAdapterOverloads {
 	request<T = any>(options: RezoRequestOptions): Promise<RezoResponse<T>>;
@@ -3085,7 +3706,14 @@ export declare class Rezo {
 	readonly dnsCache?: DNSCache;
 	/** The adapter function used for HTTP requests */
 	private readonly adapter;
+	/** Proxy manager for advanced proxy rotation and pool management */
+	private readonly _proxyManager;
 	constructor(config?: RezoDefaultOptions, adapter?: AdapterFunction);
+	/**
+	 * Get the ProxyManager instance (if configured)
+	 * @returns ProxyManager instance or null
+	 */
+	get proxyManager(): ProxyManager | null;
 	/**
 	 * Clear all caches (response and DNS)
 	 */
@@ -3191,12 +3819,46 @@ export declare class Rezo {
 	 */
 	upload(url: string | URL, data: Buffer | FormData | RezoFormData | string | Record<string, any>, options?: RezoHttpRequest): RezoUploadResponse;
 }
+/**
+ * Extended Rezo instance with Axios-compatible static helpers.
+ * Provides drop-in replacement API surface for Axios users.
+ */
 export interface RezoInstance extends Rezo {
+	/** Create a new Rezo instance with custom configuration */
 	create(config?: RezoDefaultOptions): Rezo;
+	/** Type guard to check if an error is a RezoError instance */
+	isRezoError: typeof RezoError.isRezoError;
+	/** Check if an error is a cancellation error */
+	isCancel: (error: unknown) => boolean;
+	/** Alias for RezoError (Axios compatibility) */
+	Cancel: typeof RezoError;
+	/** AbortController for request cancellation (Axios compatibility) */
+	CancelToken: typeof AbortController;
+	/** Promise.all wrapper (Axios compatibility) */
+	all: typeof Promise.all;
+	/** Spread array arguments to callback function (Axios compatibility) */
+	spread: <T extends unknown[], R>(callback: (...args: T) => R) => (array: T) => R;
 }
-export declare const rezo: RezoInstance;
+export declare const isRezoError: typeof RezoError.isRezoError;
+export declare const Cancel: typeof RezoError;
+export declare const CancelToken: {
+	new (): AbortController;
+	prototype: AbortController;
+};
+export declare const isCancel: (error: unknown) => boolean;
+export declare const all: {
+	<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>;
+	<T extends readonly unknown[] | [
+	]>(values: T): Promise<{
+		-readonly [P in keyof T]: Awaited<T[P]>;
+	}>;
+};
+export declare const spread: <T extends unknown[], R>(callback: (...args: T) => R) => (array: T) => R;
+export declare const VERSION: string;
+declare const rezo: RezoInstance;
 
 export {
+	ResponseType$1 as ResponseType,
 	rezo as default,
 };