rezo 1.0.43 → 1.0.45

package/dist/crawler.d.ts

@@ -6,43 +6,24 @@ import { SecureContext, TLSSocket } from 'node:tls';
 import { Cookie as TouchCookie, CookieJar as TouchCookieJar, CreateCookieOptions } from 'tough-cookie';
 
 /**
- * FileCacher - Cross-runtime SQLite-based file caching system
+ * CrawlerCache - High-performance SQLite-based response caching for web crawlers
  *
- * Provides persistent key-value storage with namespace support, TTL expiration,
- * and optional zstd compression for efficient data storage.
+ * Optimized specifically for crawler workloads with:
+ * - WAL mode for high-throughput concurrent reads/writes
+ * - Batch operations for efficient bulk storage
+ * - Domain-based namespacing for organized cache management
+ * - Optional zstd compression for storage efficiency
  *
  * @module cache/file-cacher
  * @author Rezo HTTP Client Library
- *
- * @example
- * ```typescript
- * import { FileCacher } from 'rezo';
- *
- * // Create a file cacher instance
- * const cacher = await FileCacher.create({
- *   cacheDir: './cache',
- *   ttl: 3600000, // 1 hour
- *   compression: true,
- *   encryptNamespace: true
- * });
- *
- * // Store and retrieve data
- * await cacher.set('user:123', { name: 'John' }, 3600000, 'users');
- * const user = await cacher.get('user:123', 'users');
- *
- * // Check existence and cleanup
- * const exists = await cacher.has('user:123', 'users');
- * await cacher.delete('user:123', 'users');
- * await cacher.close();
- * ```
  */
 /**
- * Configuration options for FileCacher
+ * Configuration options for CrawlerCache
  */
 export interface FileCacherOptions {
 	/**
 	 * Directory path for storing cache databases
-	 * @default './cache'
+	 * @default '/tmp/rezo-crawler/cache'
 	 */
 	cacheDir?: string;
 	/**
@@ -51,23 +32,18 @@ export interface FileCacherOptions {
 	 */
 	ttl?: number;
 	/**
-	 * Enable zstd compression for stored values
+	 * Enable zstd compression for stored values (Node.js 22.15+)
 	 * Reduces storage size but adds CPU overhead
 	 * @default false
 	 */
 	compression?: boolean;
 	/**
-	 * Enable soft delete (mark as deleted instead of removing)
-	 * @default false
-	 */
-	softDelete?: boolean;
-	/**
-	 * Hash namespace names for privacy/security
+	 * Hash namespace names for privacy
 	 * @default false
 	 */
 	encryptNamespace?: boolean;
 	/**
-	 * Maximum number of entries per namespace (0 = unlimited)
+	 * Maximum entries per namespace (0 = unlimited)
 	 * @default 0
 	 */
 	maxEntries?: number;
@@ -77,155 +53,63 @@ declare class FileCacher {
 	private readonly options;
 	private readonly cacheDir;
 	private closed;
-	/**
-	 * Private constructor - use FileCacher.create() instead
-	 */
 	private constructor();
 	/**
 	 * Create a new FileCacher instance
-	 *
-	 * @param options - Configuration options
-	 * @returns Promise resolving to initialized FileCacher instance
-	 *
-	 * @example
-	 * ```typescript
-	 * const cacher = await FileCacher.create({
-	 *   cacheDir: './my-cache',
-	 *   ttl: 3600000,
-	 *   compression: true
-	 * });
-	 * ```
 	 */
 	static create(options?: FileCacherOptions): Promise<FileCacher>;
 	/**
-	 * Get or create database for a namespace
+	 * Get or create optimized database for a namespace (domain)
 	 */
 	private getDatabase;
 	/**
-	 * Store a value in the cache
-	 *
-	 * @param key - Unique key for the cached item
-	 * @param value - Value to cache (will be JSON serialized)
-	 * @param ttl - Time-to-live in milliseconds (uses default if not specified)
-	 * @param namespace - Namespace for isolation (default: 'default')
-	 * @returns Promise resolving when stored
-	 *
-	 * @example
-	 * ```typescript
-	 * // Store with default TTL
-	 * await cacher.set('key1', { data: 'value' });
-	 *
-	 * // Store with custom TTL and namespace
-	 * await cacher.set('key2', responseData, 3600000, 'api-responses');
-	 * ```
+	 * Store a response in the cache
 	 */
 	set<T = any>(key: string, value: T, ttl?: number, namespace?: string): Promise<void>;
 	/**
-	 * Retrieve a value from the cache
-	 *
-	 * @param key - Key of the cached item
-	 * @param namespace - Namespace to search in (default: 'default')
-	 * @returns Promise resolving to cached value or null if not found/expired
-	 *
-	 * @example
-	 * ```typescript
-	 * const data = await cacher.get<MyType>('key1', 'my-namespace');
-	 * if (data) {
-	 *   console.log('Cache hit:', data);
-	 * }
-	 * ```
+	 * Store multiple responses in a single transaction (batch operation)
+	 */
+	setMany<T = any>(entries: Array<{
+		key: string;
+		value: T;
+		ttl?: number;
+	}>, namespace?: string): Promise<void>;
+	/**
+	 * Retrieve a cached response
 	 */
 	get<T = any>(key: string, namespace?: string): Promise<T | null>;
 	/**
-	 * Check if a key exists in the cache and is not expired
-	 *
-	 * @param key - Key to check
-	 * @param namespace - Namespace to search in (default: 'default')
-	 * @returns Promise resolving to true if key exists and is valid
-	 *
-	 * @example
-	 * ```typescript
-	 * if (await cacher.has('key1', 'my-namespace')) {
-	 *   const data = await cacher.get('key1', 'my-namespace');
-	 * }
-	 * ```
+	 * Check if a key exists and is not expired
 	 */
 	has(key: string, namespace?: string): Promise<boolean>;
+	/**
+	 * Check multiple keys at once (batch operation)
+	 */
+	hasMany(keys: string[], namespace?: string): Promise<Set<string>>;
 	/**
 	 * Delete a key from the cache
-	 *
-	 * @param key - Key to delete
-	 * @param namespace - Namespace to delete from (default: 'default')
-	 * @returns Promise resolving to true if key was deleted
-	 *
-	 * @example
-	 * ```typescript
-	 * await cacher.delete('obsolete-key', 'my-namespace');
-	 * ```
 	 */
 	delete(key: string, namespace?: string): Promise<boolean>;
 	/**
 	 * Clear all entries in a namespace
-	 *
-	 * @param namespace - Namespace to clear (default: 'default')
-	 * @returns Promise resolving when cleared
-	 *
-	 * @example
-	 * ```typescript
-	 * // Clear all cached data for a domain
-	 * await cacher.clear('example.com');
-	 * ```
 	 */
 	clear(namespace?: string): Promise<void>;
 	/**
-	 * Remove all expired entries from a namespace
-	 *
-	 * @param namespace - Namespace to cleanup (default: 'default')
-	 * @returns Promise resolving to number of entries removed
-	 *
-	 * @example
-	 * ```typescript
-	 * const removed = await cacher.cleanup('my-namespace');
-	 * console.log(`Removed ${removed} expired entries`);
-	 * ```
+	 * Remove all expired entries
 	 */
 	cleanup(namespace?: string): Promise<number>;
 	/**
-	 * Get statistics for a namespace
-	 *
-	 * @param namespace - Namespace to get stats for (default: 'default')
-	 * @returns Promise resolving to cache statistics
-	 *
-	 * @example
-	 * ```typescript
-	 * const stats = await cacher.stats('my-namespace');
-	 * console.log(`${stats.count} entries, ${stats.size} bytes`);
-	 * ```
+	 * Get cache statistics for a namespace
 	 */
 	stats(namespace?: string): Promise<{
 		count: number;
 		expired: number;
-		deleted: number;
 	}>;
 	/**
-	 * Close all database connections and release resources
-	 *
-	 * @returns Promise resolving when all connections are closed
-	 *
-	 * @example
-	 * ```typescript
-	 * // Always close when done
-	 * await cacher.close();
-	 * ```
+	 * Close all database connections
 	 */
 	close(): Promise<void>;
-	/**
-	 * Check if the cacher has been closed
-	 */
 	get isClosed(): boolean;
-	/**
-	 * Get the cache directory path
-	 */
 	get directory(): string;
 }
 export interface CrawlSession {
@@ -1644,6 +1528,35 @@ export type OnTimeoutHook = (event: TimeoutEvent, config: RezoConfig) => void;
  * Use for cleanup, logging
  */
 export type OnAbortHook = (event: AbortEvent, config: RezoConfig) => void;
+/**
+ * Rate limit wait event data - fired when waiting due to rate limiting
+ */
+export interface RateLimitWaitEvent {
+	/** HTTP status code that triggered the wait (e.g., 429, 503) */
+	status: number;
+	/** Time to wait in milliseconds */
+	waitTime: number;
+	/** Current wait attempt number (1-indexed) */
+	attempt: number;
+	/** Maximum wait attempts configured */
+	maxAttempts: number;
+	/** Where the wait time was extracted from */
+	source: "header" | "body" | "function" | "default";
+	/** The header or body path used (if applicable) */
+	sourcePath?: string;
+	/** URL being requested */
+	url: string;
+	/** HTTP method of the request */
+	method: string;
+	/** Timestamp when the wait started */
+	timestamp: number;
+}
+/**
+ * Hook called when rate limit wait occurs
+ * Informational only - cannot abort the wait
+ * Use for logging, monitoring, alerting
+ */
+export type OnRateLimitWaitHook = (event: RateLimitWaitEvent, config: RezoConfig) => void | Promise<void>;
 /**
  * Hook called before a proxy is selected
  * Can return a specific proxy to override selection
@@ -1724,6 +1637,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Configuration object that encapsulates comprehensive request execution metadata and response processing information.
@@ -2549,6 +2463,91 @@ export interface RezoRequestConfig<D = any> {
 		/** Weather to stop or continue retry when certain condition is met*/
 		condition?: (error: RezoError) => boolean | Promise<boolean>;
 	};
+	/**
+	 * Rate limit wait configuration - wait and retry when receiving rate limit responses.
+	 *
+	 * This feature runs BEFORE the retry system. When a rate-limiting status code is received,
+	 * the client will wait for the specified time and automatically retry the request.
+	 *
+	 * **Basic Usage:**
+	 * - `waitOnStatus: true` - Enable waiting on 429 status (default behavior)
+	 * - `waitOnStatus: [429, 503]` - Enable waiting on specific status codes
+	 *
+	 * **Wait Time Sources:**
+	 * - `'retry-after'` - Use standard Retry-After header (default)
+	 * - `{ header: 'X-RateLimit-Reset' }` - Use custom header
+	 * - `{ body: 'retry_after' }` - Extract from JSON response body
+	 * - Custom function for complex logic
+	 *
+	 * @example
+	 * ```typescript
+	 * // Wait on 429 using Retry-After header
+	 * await rezo.get(url, { waitOnStatus: true });
+	 *
+	 * // Wait on 429 using custom header
+	 * await rezo.get(url, {
+	 *   waitOnStatus: true,
+	 *   waitTimeSource: { header: 'X-RateLimit-Reset' }
+	 * });
+	 *
+	 * // Wait on 429 extracting time from JSON body
+	 * await rezo.get(url, {
+	 *   waitOnStatus: true,
+	 *   waitTimeSource: { body: 'data.retry_after' }
+	 * });
+	 *
+	 * // Custom function for complex APIs
+	 * await rezo.get(url, {
+	 *   waitOnStatus: [429, 503],
+	 *   waitTimeSource: (response) => {
+	 *     const reset = response.headers.get('x-ratelimit-reset');
+	 *     return reset ? parseInt(reset) - Math.floor(Date.now() / 1000) : null;
+	 *   }
+	 * });
+	 * ```
+	 */
+	waitOnStatus?: boolean | number[];
+	/**
+	 * Where to extract the wait time from when rate-limited.
+	 *
+	 * - `'retry-after'` - Standard Retry-After header (default)
+	 * - `{ header: string }` - Custom header name (e.g., 'X-RateLimit-Reset')
+	 * - `{ body: string }` - JSON path in response body (e.g., 'data.retry_after', 'wait_seconds')
+	 * - Function - Custom logic receiving the response, return seconds to wait or null
+	 *
+	 * @default 'retry-after'
+	 */
+	waitTimeSource?: "retry-after" | {
+		header: string;
+	} | {
+		body: string;
+	} | ((response: {
+		status: number;
+		headers: RezoHeaders;
+		data?: any;
+	}) => number | null);
+	/**
+	 * Maximum time to wait for rate limit in milliseconds.
+	 * If the extracted wait time exceeds this, the request will fail instead of waiting.
+	 * Set to 0 for unlimited wait time.
+	 *
+	 * @default 60000 (60 seconds)
+	 */
+	maxWaitTime?: number;
+	/**
+	 * Default wait time in milliseconds if the wait time source returns nothing.
+	 * Used as fallback when Retry-After header or body path is not present.
+	 *
+	 * @default 1000 (1 second)
+	 */
+	defaultWaitTime?: number;
+	/**
+	 * Maximum number of wait attempts before giving up.
+	 * After this many waits, the request will proceed to retry logic or fail.
+	 *
+	 * @default 3
+	 */
+	maxWaitAttempts?: number;
 	/** Whether to use a secure context for HTTPS requests */
 	useSecureContext?: boolean;
 	/** Custom secure context for TLS connections */
@@ -6232,17 +6231,25 @@ declare class Decodo {
 	/**
 	 * Create a new Decodo client instance
 	 *
-	 * @param config - Decodo API configuration
-	 * @throws Error if username or password is missing
+	 * @param config - Decodo API configuration (supports username/password OR token auth)
+	 * @throws Error if authentication credentials are missing
 	 *
 	 * @example
 	 * ```typescript
+	 * // Username/password authentication
 	 * const decodo = new Decodo({
 	 *   username: 'user',
 	 *   password: 'password',
 	 *   headless: 'html',
 	 *   country: 'US'
 	 * });
+	 *
+	 * // Token authentication (alternative)
+	 * const decodo = new Decodo({
+	 *   token: 'your_api_token',
+	 *   headless: 'html',
+	 *   country: 'US'
+	 * });
 	 * ```
 	 */
 	constructor(config: DecodoConfig);
@@ -6472,6 +6479,42 @@ export interface ICrawlerOptions {
 	} | {
 		enable: false;
 	} | undefined | false;
+	/** Decodo proxy service configuration for specific domains or global use */
+	decodo?: {
+		enable: true;
+		labs: [
+			{
+				domain: Domain;
+				isGlobal?: boolean;
+				options: DecodoOptions;
+				queueOptions: queueOptions$1;
+			}
+		];
+	} | {
+		enable: false;
+	} | undefined | false;
+	/** Maximum crawl depth from start URL (0 = unlimited, default: 0) */
+	maxDepth?: number;
+	/** Maximum total URLs to crawl (0 = unlimited, default: 0) */
+	maxUrls?: number;
+	/** Maximum response size in bytes to process (0 = unlimited, default: 0) */
+	maxResponseSize?: number;
+	/** Respect robots.txt rules (default: false) */
+	respectRobotsTxt?: boolean;
+	/** Follow rel="nofollow" links (default: false - ignores nofollow links) */
+	followNofollow?: boolean;
+	/** Enable automatic throttling based on server response times (default: true) */
+	autoThrottle?: boolean;
+	/** Target request delay in ms for AutoThrottle (default: 1000) */
+	autoThrottleTargetDelay?: number;
+	/** Minimum delay between requests in ms (default: 100) */
+	autoThrottleMinDelay?: number;
+	/** Maximum delay between requests in ms (default: 60000) */
+	autoThrottleMaxDelay?: number;
+	/** Maximum time to wait on 429 response in ms (default: 1800000 = 30 min) */
+	maxWaitOn429?: number;
+	/** Always wait on 429 regardless of time, shows warning (default: false) */
+	alwaysWaitOn429?: boolean;
 }
 /**
  * Advanced web crawler configuration class with support for domain-specific settings
@@ -6548,6 +6591,28 @@ export declare class CrawlerOptions {
 	throwFatalError?: boolean;
 	/** Enable debug logging */
 	debug?: boolean;
+	/** Maximum crawl depth from start URL (0 = unlimited) */
+	maxDepth: number;
+	/** Maximum total URLs to crawl (0 = unlimited) */
+	maxUrls: number;
+	/** Maximum response size in bytes to process (0 = unlimited) */
+	maxResponseSize: number;
+	/** Respect robots.txt rules */
+	respectRobotsTxt: boolean;
+	/** Follow rel="nofollow" links */
+	followNofollow: boolean;
+	/** Enable automatic throttling based on server response times */
+	autoThrottle: boolean;
+	/** Target request delay in ms for AutoThrottle */
+	autoThrottleTargetDelay: number;
+	/** Minimum delay between requests in ms */
+	autoThrottleMinDelay: number;
+	/** Maximum delay between requests in ms */
+	autoThrottleMaxDelay: number;
+	/** Maximum time to wait on 429 response in ms */
+	maxWaitOn429: number;
+	/** Always wait on 429 regardless of time */
+	alwaysWaitOn429: boolean;
 	/** Internal storage for Oxylabs configurations with domain mapping */
 	oxylabs: {
 		domain?: Domain;
@@ -6929,13 +6994,44 @@ export interface EmailDiscoveryEvent {
 	discoveredAt: string;
 	timestamp: Date;
 }
+interface RedirectEvent$1 {
+	originalUrl: string;
+	finalUrl: string;
+	redirectCount: number;
+	statusCode: number;
+}
+/**
+ * Export format options
+ */
+export type ExportFormat = "json" | "jsonl" | "csv";
 /**
- * Generic handler function type for crawler event callbacks.
- * All crawler event handlers must return a Promise<void>.
+ * Handler with element bound to `this` context.
+ * Use `function` syntax (not arrow functions) to access `this`.
  *
- * @template T - The type of element or data passed to the handler
+ * @example
+ * ```typescript
+ * crawler.onText('h1', async function(text) {
+ *   console.log(text, this.tagName); // `this` is the element
+ * });
+ * ```
  */
-export type CrawlerHandler<T = any> = (element: T) => Promise<void>;
+export type ElementBoundHandler<TValue, TElement = Element> = (this: TElement, value: TValue) => Promise<void>;
+/**
+ * Handler for attribute extraction with element bound to `this`.
+ * Receives both the attribute value and attribute name.
+ */
+export type AttributeHandler = (this: Element, value: string, attributeName: string) => Promise<void>;
+/**
+ * Crawl statistics
+ */
+export interface CrawlStats {
+	urlsVisited: number;
+	urlsQueued: number;
+	urlsFailed: number;
+	startTime: number;
+	endTime?: number;
+	currentDepth: number;
+}
 /**
  * A powerful web crawler that provides event-driven HTML parsing and data extraction.
  * Supports caching, proxy rotation, retry mechanisms, and email lead discovery.
@@ -6992,6 +7088,25 @@ export declare class Crawler {
 	/** Adapter-specific request executor */
 	private adapterExecutor;
 	private adapterType;
+	/** Track pending execute() calls for proper done() behavior */
+	private pendingExecutions;
+	/** robots.txt parser and validator */
+	private robotsTxt;
+	/** AutoThrottle: track response times per domain for adaptive rate limiting */
+	private domainResponseTimes;
+	private domainCurrentDelay;
+	/** Crawl statistics */
+	private crawlStats;
+	/** URL depth tracking for maxDepth limit */
+	private urlDepthMap;
+	/** Lifecycle event handlers */
+	private startHandlers;
+	private finishHandlers;
+	private redirectHandlers;
+	/** Data collection for export */
+	private collectedData;
+	/** Flag to track if crawl has started */
+	private crawlStarted;
 	/**
 	 * Creates a new Crawler instance with the specified configuration.
 	 *
@@ -7160,6 +7275,54 @@ export declare class Crawler {
 	 * ```
 	 */
 	onEmailLeads(handler: (emails: string[]) => Promise<void>): Crawler;
+	/**
+	 * Registers a handler called before crawling starts.
+	 * Useful for initialization, logging, or setup tasks.
+	 *
+	 * @param handler - Function to call before crawling begins
+	 * @returns The crawler instance for method chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * crawler.onStart(async () => {
+	 *   console.log('Crawl session started');
+	 *   await initializeDatabase();
+	 * });
+	 * ```
+	 */
+	onStart(handler: () => Promise<void>): Crawler;
+	/**
+	 * Registers a handler called when crawling finishes.
+	 * Receives crawl statistics including URLs visited, failed, and timing.
+	 *
+	 * @param handler - Function to call when crawling completes
+	 * @returns The crawler instance for method chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * crawler.onFinish(async (stats) => {
+	 *   console.log(`Crawl completed: ${stats.urlsVisited} URLs in ${stats.endTime - stats.startTime}ms`);
+	 *   await generateReport(stats);
+	 * });
+	 * ```
+	 */
+	onFinish(handler: (stats: CrawlStats) => Promise<void>): Crawler;
+	/**
+	 * Registers a handler called when a redirect is followed.
+	 * Provides information about the original URL, final URL, and redirect count.
+	 *
+	 * @param handler - Function to handle redirect events
+	 * @returns The crawler instance for method chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * crawler.onRedirect(async (event) => {
+	 *   console.log(`Redirect: ${event.originalUrl} -> ${event.finalUrl}`);
+	 *   trackRedirects(event);
+	 * });
+	 * ```
+	 */
+	onRedirect(handler: (event: RedirectEvent$1) => Promise<void>): Crawler;
 	/**
 	 * Registers a handler for raw response data.
 	 * Triggered for all responses, providing access to the raw Buffer data.
@@ -7255,21 +7418,23 @@ export declare class Crawler {
 	/**
 	 * Registers a handler for href attributes from anchor and link elements.
 	 * Automatically resolves relative URLs to absolute URLs.
+	 * Use `function` syntax (not arrow) to access `this` as the element.
 	 *
-	 * @param handler - Function to handle href URLs as strings
+	 * @param handler - Function receiving href string, with `this` bound to the element
 	 * @returns The crawler instance for method chaining
 	 *
 	 * @example
 	 * ```typescript
-	 * crawler.onHref(async (href) => {
+	 * crawler.onHref(async function(href) {
 	 *   console.log('Found URL:', href);
+	 *   console.log('Link text:', this.textContent); // `this` is the anchor/link element
 	 *   if (href.includes('/api/')) {
 	 *     await crawler.visit(href);
 	 *   }
 	 * });
 	 * ```
 	 */
-	onHref(handler: (href: string) => Promise<void>): Crawler;
+	onHref(handler: ElementBoundHandler<string, HTMLAnchorElement | HTMLLinkElement>): Crawler;
 	/**
 	 * Registers a handler for elements matching a CSS selector.
 	 * Provides fine-grained control over which elements to process.
@@ -7311,55 +7476,57 @@ export declare class Crawler {
 	/**
 	 * Registers a handler for HTML element attributes.
 	 * Can extract specific attributes from all elements or from elements matching a selector.
+	 * Use `function` syntax (not arrow) to access `this` as the element.
 	 *
 	 * @param attribute - The attribute name to extract
-	 * @param handler - Function to handle attribute values
+	 * @param handler - Function receiving (value, attrName), with `this` bound to element
 	 * @returns The crawler instance for method chaining
 	 *
 	 * @overload
 	 * @param selection - CSS selector to filter elements
 	 * @param attribute - The attribute name to extract
-	 * @param handler - Function to handle attribute values
+	 * @param handler - Function receiving (value, attrName), with `this` bound to element
 	 * @returns The crawler instance for method chaining
 	 *
 	 * @example
 	 * ```typescript
 	 * // Extract all 'data-id' attributes
-	 * crawler.onAttribute('data-id', async (value) => {
-	 *   console.log('Found data-id:', value);
+	 * crawler.onAttribute('data-id', async function(value, attrName) {
+	 *   console.log('Found', attrName, ':', value, 'on:', this.tagName);
 	 * });
 	 *
 	 * // Extract 'src' attributes from images only
-	 * crawler.onAttribute('img', 'src', async (src) => {
-	 *   console.log('Image source:', src);
+	 * crawler.onAttribute('img', 'src', async function(value) {
+	 *   console.log('Image source:', value, 'alt:', this.getAttribute('alt'));
 	 * });
 	 * ```
 	 */
-	onAttribute(attribute: string, handler: CrawlerHandler<string>): Crawler;
-	onAttribute(selection: string, attribute: string, handler: CrawlerHandler<string>): Crawler;
+	onAttribute(attribute: string, handler: AttributeHandler): Crawler;
+	onAttribute(selection: string, attribute: string, handler: AttributeHandler): Crawler;
 	/**
 	 * Registers a handler for text content of elements matching a CSS selector.
 	 * Extracts and processes the textContent of matching elements.
+	 * Use `function` syntax (not arrow) to access `this` as the element.
 	 *
 	 * @param selection - CSS selector to match elements
-	 * @param handler - Function to handle extracted text content
+	 * @param handler - Function receiving text string, with `this` bound to element
 	 * @returns The crawler instance for method chaining
 	 *
 	 * @example
 	 * ```typescript
-	 * // Extract all heading text
-	 * crawler.onText('h1, h2, h3', async (text) => {
-	 *   console.log('Heading:', text.trim());
+	 * // Extract all heading text with element context
+	 * crawler.onText('h1, h2, h3', async function(text) {
+	 *   console.log('Heading:', text.trim(), 'Tag:', this.tagName);
 	 * });
 	 *
-	 * // Extract product prices
-	 * crawler.onText('.price', async (price) => {
-	 *   const numericPrice = parseFloat(price.replace(/[^\d.]/g, ''));
-	 *   console.log('Price value:', numericPrice);
+	 * // Extract product prices with element context
+	 * crawler.onText('.price', async function(text) {
+	 *   const numericPrice = parseFloat(text.replace(/[^\d.]/g, ''));
+	 *   console.log('Price:', numericPrice, 'Product:', this.closest('.product')?.id);
 	 * });
 	 * ```
 	 */
-	onText(selection: string, handler: CrawlerHandler<string>): Crawler;
+	onText(selection: string, handler: ElementBoundHandler<string>): Crawler;
 	private _onBody;
 	private _onAttribute;
 	private _onText;
@@ -7374,6 +7541,86 @@ export declare class Crawler {
 	private _onEmailLeads;
 	private _onRawResponse;
 	private _onResponse;
+	/**
+	 * Calculate adaptive delay based on server response times (AutoThrottle)
+	 */
+	private calculateAutoThrottleDelay;
+	/**
+	 * Get current AutoThrottle delay for a domain
+	 */
+	private getAutoThrottleDelay;
+	/**
+	 * Handle 429 Too Many Requests response with Retry-After header parsing
+	 */
+	private handle429Response;
+	/**
+	 * Check if URL passes all crawl limit checks
+	 */
+	private checkCrawlLimits;
+	/**
+	 * Check if a link should be followed based on nofollow rules
+	 */
+	private shouldFollowLink;
+	/**
+	 * Check response size against maxResponseSize limit
+	 */
+	private checkResponseSize;
+	/**
+	 * Collect data for later export
+	 *
+	 * @param data - Data to collect (will be added to export buffer)
+	 * @returns The crawler instance for method chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * crawler.onDocument(async (doc) => {
+	 *   crawler.collect({
+	 *     title: doc.title,
+	 *     url: doc.URL,
+	 *     h1: doc.querySelector('h1')?.textContent
+	 *   });
+	 * });
+	 * ```
+	 */
+	collect(data: any): Crawler;
+	/**
+	 * Get all collected data
+	 */
+	getCollectedData(): any[];
+	/**
+	 * Clear collected data
+	 */
+	clearCollectedData(): Crawler;
+	/**
+	 * Export collected data to a file
+	 *
+	 * @param filePath - Output file path
+	 * @param format - Export format: 'json', 'jsonl', or 'csv'
+	 *
+	 * @example
+	 * ```typescript
+	 * await crawler.waitForAll();
+	 * await crawler.exportData('./output.json', 'json');
+	 * await crawler.exportData('./output.csv', 'csv');
+	 * ```
+	 */
+	exportData(filePath: string, format?: ExportFormat): Promise<void>;
+	/**
+	 * Get current crawl statistics
+	 */
+	getStats(): CrawlStats;
+	/**
+	 * Trigger onStart handlers (called once on first visit)
+	 */
+	private triggerStartHandlers;
+	/**
+	 * Trigger onFinish handlers
+	 */
+	private triggerFinishHandlers;
+	/**
+	 * Trigger onRedirect handlers
+	 */
+	private triggerRedirectHandlers;
 	private buildUrl;
 	/**
 	 * Visits a URL and processes it according to registered event handlers.
@@ -7489,6 +7736,17 @@ export declare class Crawler {
 	 */
 	done(): Promise<void>;
 	close(): Promise<void>;
+	/**
+	 * Destroys the crawler instance and releases all resources.
+	 * Clears all queued tasks, closes caches, and cleans up event handlers.
+	 * @returns Promise that resolves when destruction is complete
+	 * @example
+	 * ```typescript
+	 * await crawler.destroy();
+	 * // Crawler is now fully cleaned up
+	 * ```
+	 */
+	destroy(): Promise<void>;
 }
 
 export {};