rezo 1.0.44 → 1.0.46

package/dist/adapters/entries/curl.d.ts

@@ -1416,6 +1416,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
@@ -1496,6 +1525,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Create empty hooks object with all arrays initialized
@@ -2426,6 +2456,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 */

package/dist/adapters/entries/fetch.d.ts

@@ -1416,6 +1416,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
@@ -1496,6 +1525,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Create empty hooks object with all arrays initialized
@@ -2426,6 +2456,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 */

package/dist/adapters/entries/http.d.ts

@@ -1416,6 +1416,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
@@ -1496,6 +1525,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Create empty hooks object with all arrays initialized
@@ -2426,6 +2456,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 */

package/dist/adapters/entries/http2.d.ts

@@ -1416,6 +1416,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
@@ -1496,6 +1525,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Create empty hooks object with all arrays initialized
@@ -2426,6 +2456,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 */

package/dist/adapters/entries/react-native.d.ts

@@ -1416,6 +1416,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
@@ -1496,6 +1525,7 @@ export interface RezoHooks {
 	onTls: OnTlsHook[];
 	onTimeout: OnTimeoutHook[];
 	onAbort: OnAbortHook[];
+	onRateLimitWait: OnRateLimitWaitHook[];
 }
 /**
  * Create empty hooks object with all arrays initialized
@@ -2426,6 +2456,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 */