create-request 0.0.1-beta.9 → 1.1.0

package/dist/library/index.esm.js

@@ -48,18 +48,6 @@ var RedirectMode;
     RedirectMode["FOLLOW"] = "follow";
     RedirectMode["MANUAL"] = "manual";
 })(RedirectMode || (RedirectMode = {}));
-/**
- * Enum for cache modes
- */
-var CacheMode;
-(function (CacheMode) {
-    CacheMode["DEFAULT"] = "default";
-    CacheMode["RELOAD"] = "reload";
-    CacheMode["NO_STORE"] = "no-store";
-    CacheMode["NO_CACHE"] = "no-cache";
-    CacheMode["FORCE_CACHE"] = "force-cache";
-    CacheMode["ONLY_IF_CACHED"] = "only-if-cached";
-})(CacheMode || (CacheMode = {}));
 /**
  * Enum for cookie SameSite policies
  */
@@ -101,7 +89,8 @@ class RequestError extends Error {
         this.method = method;
         this.status = options.status;
         this.response = options.response;
-        this.timeoutError = options.timeoutError;
+        this.isTimeout = options.isTimeout;
+        this.isAborted = options.isAborted;
         // For better stack traces in modern environments
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, RequestError);
@@ -113,30 +102,90 @@ class RequestError extends Error {
      * Static methods for creating specific types of RequestError
      */
     static timeout(url, method, timeoutMs) {
-        return new RequestError(`Request timed out after ${timeoutMs}ms`, url, method, {
-            timeoutError: true,
+        return new RequestError(`Timeout: ${timeoutMs}ms`, url, method, {
+            isTimeout: true,
         });
     }
     static fromResponse(response, url, method) {
-        return new RequestError(`Request failed with status ${response.status}`, url, method, {
+        return new RequestError(`HTTP ${response.status}`, url, method, {
             status: response.status,
             response,
         });
     }
     static networkError(url, method, originalError) {
-        const error = new RequestError(`Network error: ${originalError.message}`, url, method);
-        error.stack = originalError.stack;
+        // Provide more descriptive error messages for common network errors
+        let message = originalError.message;
+        // Check for Node.js error codes (e.g., from undici/dns errors)
+        const errorCode = originalError.code;
+        const errorName = originalError.name;
+        const stack = originalError.stack || "";
+        const errorMessageLower = message.toLowerCase();
+        // Check for timeout errors (Node.js/undici TimeoutError)
+        const isTimeoutError = errorName === "TimeoutError" ||
+            errorMessageLower.includes("timeout") ||
+            errorMessageLower.includes("aborted due to timeout") ||
+            errorCode === "ETIMEDOUT" ||
+            stack.includes("TimeoutError") ||
+            stack.includes("timeout");
+        // If the error message is generic "fetch failed", provide more context
+        if (message === "fetch failed" || message === "Failed to fetch") {
+            // Check for DNS resolution errors
+            const isDnsError = errorCode === "ENOTFOUND" ||
+                errorCode === "EAI_AGAIN" ||
+                errorCode === "EAI_NODATA" ||
+                stack.includes("getaddrinfo") ||
+                stack.includes("ENOTFOUND") ||
+                stack.includes("EAI_AGAIN");
+            // Check for connection errors (but not timeout errors)
+            const isConnectionError = !isTimeoutError && (errorCode === "ECONNREFUSED" || errorCode === "ECONNRESET" || stack.includes("ECONNREFUSED") || stack.includes("connect"));
+            if (isTimeoutError) {
+                message = `Network error: Request timeout for ${url}`;
+            }
+            else if (isDnsError) {
+                message = `Network error: Unable to resolve hostname for ${url}`;
+            }
+            else if (isConnectionError) {
+                message = `Network error: Connection refused for ${url}`;
+            }
+            else {
+                message = `Network error: Failed to fetch ${url}`;
+            }
+        }
+        const error = new RequestError(message, url, method, {
+            ...(isTimeoutError ? { isTimeout: true } : {}),
+        });
+        // Create a proper RequestError stack trace, but append the original stack for debugging
+        // This way Node.js will show "RequestError: ..." instead of "TypeError: ..."
+        if (originalError.stack) {
+            // Get the current stack (which will start with RequestError)
+            const currentStack = error.stack || "";
+            // Append the original error's stack as "Caused by:" for debugging context
+            error.stack = `${currentStack}\n\nCaused by: ${originalError.stack}`;
+        }
         return error;
     }
+    static abortError(url, method) {
+        return new RequestError("Aborted", url, method, {
+            isAborted: true,
+        });
+    }
 }
 
 /**
  * Wrapper for HTTP responses with methods to transform the response data
+ * Provides caching and conversion between different response formats.
  */
 class ResponseWrapper {
-    constructor(response) {
+    constructor(response, url, method, graphQLOptions) {
         this.bodyUsed = false;
         this.response = response;
+        this.url = url;
+        this.method = method;
+        if (graphQLOptions) {
+            this.graphQLOptions = {
+                throwOnError: graphQLOptions.throwOnError,
+            };
+        }
     }
     // Wrapper properties
     get status() {
@@ -154,29 +203,109 @@ class ResponseWrapper {
     get raw() {
         return this.response;
     }
-    // Response body methods with caching
+    /**
+     * Check for GraphQL errors and throw if throwOnError is enabled
+     * @param data - The parsed JSON data
+     * @throws RequestError if GraphQL response contains errors and throwOnError is enabled
+     */
+    checkGraphQLErrors(data) {
+        var _a;
+        if (!((_a = this.graphQLOptions) === null || _a === void 0 ? void 0 : _a.throwOnError) || typeof data !== "object" || data === null)
+            return;
+        const responseData = data;
+        if (!Array.isArray(responseData.errors) || responseData.errors.length === 0)
+            return;
+        const errors = responseData.errors;
+        const errorMessages = errors.map(x => typeof x === "string" ? x : x && typeof x === "object" && "message" in x ? String(x.message || "Unknown error") : String(x));
+        const errorMessage = errorMessages.join(", ");
+        throw new RequestError(`GraphQL request failed with errors: ${errorMessage}`, this.url || "", this.method || "", {
+            status: this.response.status,
+            response: this.response,
+        });
+    }
+    /**
+     * Parse the response body as JSON
+     * Caches the result for subsequent calls.
+     * If GraphQL options are set with throwOnError=true, will check for GraphQL errors and throw.
+     *
+     * @returns The parsed JSON data
+     * @throws {RequestError} When the request fails, JSON parsing fails, GraphQL errors occur (if throwOnError enabled), or body is already consumed
+     *
+     * @example
+     * const data = await response.getJson();
+     * console.log(data.items);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await response.getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
+     */
     async getJson() {
         if (this.jsonCache !== undefined) {
+            this.checkGraphQLErrors(this.jsonCache);
             return this.jsonCache;
         }
         if (this.bodyUsed) {
             // If we already have text, try to parse it as JSON
             if (this.textCache !== undefined) {
                 try {
-                    // Fix unsafe assignment by explicitly casting to unknown first
-                    this.jsonCache = JSON.parse(this.textCache);
-                    return this.jsonCache;
+                    const parsed = JSON.parse(this.textCache);
+                    this.jsonCache = parsed;
+                    this.checkGraphQLErrors(parsed);
+                    return parsed;
                 }
-                catch (e) {
-                    throw new Error("Cannot parse cached text as JSON");
+                catch (error) {
+                    // Re-throw RequestErrors from checkGraphQLErrors without wrapping
+                    if (error instanceof RequestError) {
+                        throw error;
+                    }
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    throw new RequestError(`Invalid JSON: ${errorMessage}`, this.url || "", this.method || "", {
+                        status: this.response.status,
+                        response: this.response,
+                    });
                 }
             }
-            throw new Error("Response body has already been consumed in a different format");
+            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
         }
         this.bodyUsed = true;
-        this.jsonCache = (await this.response.json());
-        return this.jsonCache;
+        try {
+            const parsed = await this.response.json();
+            this.jsonCache = parsed;
+            this.checkGraphQLErrors(parsed);
+            return parsed;
+        }
+        catch (error) {
+            // Re-throw RequestErrors from checkGraphQLErrors without wrapping
+            if (error instanceof RequestError) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new RequestError(`Invalid JSON: ${errorMessage}`, this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
+        }
     }
+    /**
+     * Get the response body as text
+     * Caches the result for subsequent calls. Attempts to convert from JSON or Blob
+     * if the body has already been consumed in those formats.
+     *
+     * @returns The response text
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const text = await response.getText();
+     */
     async getText() {
         if (this.textCache !== undefined) {
             return this.textCache;
@@ -189,15 +318,48 @@ class ResponseWrapper {
             }
             // If we have blob, convert to text
             if (this.blobCache !== undefined) {
-                this.textCache = await this.blobCache.text();
-                return this.textCache;
+                try {
+                    this.textCache = await this.blobCache.text();
+                    return this.textCache;
+                }
+                catch (e) {
+                    const errorMessage = e instanceof Error ? e.message : String(e);
+                    throw new RequestError(`Cannot convert to text: ${errorMessage}`, this.url || "", this.method || "", {
+                        status: this.response.status,
+                        response: this.response,
+                    });
+                }
             }
-            throw new Error("Response body has already been consumed in a format that cannot be converted to text");
+            throw new RequestError("Cannot convert to text", this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
         }
         this.bodyUsed = true;
-        this.textCache = await this.response.text();
-        return this.textCache;
+        try {
+            this.textCache = await this.response.text();
+            return this.textCache;
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            throw new RequestError(`Read failed: ${errorMessage}`, this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
+        }
     }
+    /**
+     * Get the response body as a Blob
+     * Caches the result for subsequent calls. Attempts to convert from text
+     * if the body has already been consumed as text.
+     *
+     * @returns The response as a Blob
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const blob = await response.getBlob();
+     * const url = URL.createObjectURL(blob);
+     */
     async getBlob() {
         if (this.blobCache !== undefined) {
             return this.blobCache;
@@ -208,367 +370,191 @@ class ResponseWrapper {
                 this.blobCache = new Blob([this.textCache], { type: "text/plain" });
                 return this.blobCache;
             }
-            throw new Error("Response body has already been consumed in a format that cannot be converted to Blob");
+            throw new RequestError("Cannot convert to Blob", this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
         }
         this.bodyUsed = true;
-        this.blobCache = await this.response.blob();
-        return this.blobCache;
-    }
-    async getArrayBuffer() {
-        if (this.arrayBufferCache !== undefined) {
-            return this.arrayBufferCache;
+        try {
+            this.blobCache = await this.response.blob();
+            return this.blobCache;
         }
-        if (this.bodyUsed) {
-            // If we have text, convert to ArrayBuffer
-            if (this.textCache !== undefined) {
-                const encoder = new TextEncoder();
-                // Fix ArrayBufferLike by explicitly casting to ArrayBuffer
-                const uint8Array = encoder.encode(this.textCache);
-                this.arrayBufferCache = uint8Array.buffer;
-                return this.arrayBufferCache;
-            }
-            // If we have blob, convert to ArrayBuffer
-            if (this.blobCache !== undefined) {
-                this.arrayBufferCache = await this.blobCache.arrayBuffer();
-                return this.arrayBufferCache;
-            }
-            throw new Error("Response body has already been consumed in a format that cannot be converted to ArrayBuffer");
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            throw new RequestError(`Read failed: ${errorMessage}`, this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
         }
-        this.bodyUsed = true;
-        this.arrayBufferCache = await this.response.arrayBuffer();
-        return this.arrayBufferCache;
     }
+    /**
+     * Get the raw response body as a ReadableStream
+     * This method consumes the body and should only be called once.
+     *
+     * @returns The response body as a ReadableStream or null
+     * @throws {RequestError} When the response body has already been consumed
+     *
+     * @example
+     * const stream = response.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream
+     * }
+     */
     getBody() {
         if (this.bodyUsed) {
-            throw new Error("Response body has already been consumed");
+            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
         }
         this.bodyUsed = true;
         return this.response.body;
     }
-}
-
-/**
- * Parse size strings like "10MB" into bytes
- * @param size Size as number or string with units
- */
-function parseSize(size) {
-    var _a;
-    if (typeof size === "number")
-        return size;
-    const match = size.match(/^(\d+(?:\.\d+)?)\s*(KB|MB|GB)?$/i);
-    if (!match)
-        return 0;
-    const num = parseFloat(match[1]);
-    const unit = (_a = match[2]) === null || _a === void 0 ? void 0 : _a.toUpperCase();
-    switch (unit) {
-        case "KB":
-            return num * 1024;
-        case "MB":
-            return num * 1024 * 1024;
-        case "GB":
-            return num * 1024 * 1024 * 1024;
-        default:
-            return num;
-    }
-}
-/**
- * Create a memory storage provider using Map
- */
-function createMemoryStorage() {
-    const store = new Map();
-    return {
-        get(key) {
-            return store.get(key) || null;
-        },
-        set(key, value) {
-            store.set(key, value);
-        },
-        has(key) {
-            return store.has(key);
-        },
-        delete(key) {
-            store.delete(key);
-        },
-        clear() {
-            store.clear();
-        },
-    };
-}
-/**
- * Create a localStorage-based storage provider
- */
-function createLocalStorageStorage() {
-    return {
-        get(key) {
-            if (typeof localStorage === "undefined")
-                return null;
-            return localStorage.getItem(key);
-        },
-        set(key, value) {
-            if (typeof localStorage === "undefined")
-                return;
-            try {
-                localStorage.setItem(key, value);
+    /**
+     * Extract specific data using a selector function
+     * If no selector is provided, returns the full JSON response.
+     *
+     * @param selector - Optional function to extract and transform data
+     * @returns A promise that resolves to the selected data
+     * @throws {RequestError} When the request fails, JSON parsing fails, or the selector throws an error
+     *
+     * @example
+     * // Get full response
+     * const data = await response.getData();
+     *
+     * // Extract specific data
+     * const users = await response.getData(data => data.results.users);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await response.getData();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
+     */
+    async getData(selector) {
+        try {
+            const data = await this.getJson();
+            // If no selector is provided, return the raw JSON data
+            if (!selector)
+                return data;
+            // Apply the selector if provided
+            return selector(data);
+        }
+        catch (error) {
+            // If it's already a RequestError, re-throw it
+            if (error instanceof RequestError) {
+                throw error;
             }
-            catch (e) {
-                // Handle quota exceeded errors
-                console.warn("Cache storage quota exceeded, clearing cache");
-                void this.clear();
-                try {
-                    localStorage.setItem(key, value);
-                }
-                catch (e) {
-                    console.error("Failed to set cache item even after clearing cache");
-                }
+            // Enhance selector errors with context
+            if (selector) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new RequestError(`Data selector failed: ${errorMessage}`, this.url || "", this.method || "", {
+                    status: this.response.status,
+                    response: this.response,
+                });
             }
-        },
-        has(key) {
-            if (typeof localStorage === "undefined")
-                return false;
-            return localStorage.getItem(key) !== null;
-        },
-        delete(key) {
-            if (typeof localStorage === "undefined")
-                return;
-            localStorage.removeItem(key);
-        },
-        clear() {
-            if (typeof localStorage === "undefined")
-                return;
-            localStorage.clear();
-        },
-    };
+            // If we get here and it's not a RequestError, wrap it
+            // This should rarely happen as getJson() should throw RequestError
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            throw RequestError.networkError(this.url || "", this.method || "", errorObj);
+        }
+    }
 }
-/**
- * Create a sessionStorage-based storage provider
- */
-function createSessionStorageStorage() {
-    return {
-        get(key) {
-            if (typeof sessionStorage === "undefined")
-                return null;
-            return sessionStorage.getItem(key);
-        },
-        set(key, value) {
-            if (typeof sessionStorage === "undefined")
-                return;
-            try {
-                sessionStorage.setItem(key, value);
+
+class CookieUtils {
+    /**
+     * Formats cookies for a request
+     * @param cookies Object containing cookie name-value pairs or cookie options
+     * @returns Formatted cookie string for the Cookie header
+     */
+    static formatRequestCookies(cookies) {
+        const cookiePairs = [];
+        Object.entries(cookies).forEach(([name, valueOrOptions]) => {
+            let value;
+            if (typeof valueOrOptions === "string") {
+                value = valueOrOptions;
             }
-            catch (e) {
-                // Handle quota exceeded errors
-                console.warn("Cache storage quota exceeded, clearing cache");
-                void this.clear();
-                try {
-                    sessionStorage.setItem(key, value);
-                }
-                catch (e) {
-                    console.error("Failed to set cache item even after clearing cache");
-                }
+            else {
+                // Extract value from options object without validation
+                value = valueOrOptions.value;
             }
-        },
-        has(key) {
-            if (typeof sessionStorage === "undefined")
-                return false;
-            return sessionStorage.getItem(key) !== null;
-        },
-        delete(key) {
-            if (typeof sessionStorage === "undefined")
-                return;
-            sessionStorage.removeItem(key);
-        },
-        clear() {
-            if (typeof sessionStorage === "undefined")
-                return;
-            sessionStorage.clear();
-        },
-    };
-}
-/**
- * Create a storage provider from a cache options object
- */
-function createStorageProvider(options) {
-    const { storage } = options || {};
-    if (!storage) {
-        // Default to memory storage
-        return createMemoryStorage();
-    }
-    // Check if storage is already a StorageProvider
-    if (typeof storage.get === "function" && typeof storage.set === "function") {
-        return storage;
-    }
-    // Check if it's localStorage or sessionStorage
-    if (storage === localStorage) {
-        return createLocalStorageStorage();
-    }
-    if (storage === sessionStorage) {
-        return createSessionStorageStorage();
-    }
-    // Check if it's a Map
-    if (storage instanceof Map) {
-        return {
-            get(key) {
-                return storage.get(key) || null;
-            },
-            set(key, value, _ttl) {
-                storage.set(key, value);
-            },
-            has(key) {
-                return storage.has(key);
-            },
-            delete(key) {
-                storage.delete(key);
-            },
-            clear() {
-                storage.clear();
-            },
-        };
+            // Add the cookie to the request
+            cookiePairs.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+        });
+        return cookiePairs.join("; ");
     }
-    // Default to memory storage
-    console.warn("Unsupported storage type, falling back to memory storage");
-    return createMemoryStorage();
 }
 
 /**
- * Cache manager that handles storage operations
+ * Utility class for CSRF token management
  */
-class CacheManager {
-    constructor(options = {}) {
-        this.entryCount = 0;
-        this.totalSize = 0;
-        this.options = options;
-        this.storage = createStorageProvider(options);
-    }
+class CsrfUtils {
     /**
-     * Generate a cache key based on request details
+     * Extracts CSRF token from a meta tag in the document head
+     * @param metaName The name attribute of the meta tag (default: "csrf-token")
+     * @returns The CSRF token or null if not found
      */
-    generateKey(url, method, headers, body) {
-        // Use custom key generator if provided
-        if (this.options.keyGenerator) {
-            const customKey = this.options.keyGenerator(url, method, headers, body);
-            return this.options.keyPrefix ? `${this.options.keyPrefix}:${customKey}` : customKey;
-        }
-        // Default key generation
-        let key = `${method}:${url}`;
-        // Add vary headers to key if specified
-        if (this.options.varyByHeaders && headers) {
-            const varyHeaders = {};
-            this.options.varyByHeaders.forEach(header => {
-                const normalizedHeader = header.toLowerCase();
-                // Find the header in case-insensitive way
-                Object.keys(headers).forEach(h => {
-                    if (h.toLowerCase() === normalizedHeader) {
-                        varyHeaders[normalizedHeader] = headers[h];
-                    }
-                });
-            });
-            if (Object.keys(varyHeaders).length > 0) {
-                key += `:${JSON.stringify(varyHeaders)}`;
-            }
-        }
-        // Include body in cache key for non-GET requests if it's a simple value
-        if (method !== "GET" && body !== undefined && body !== null) {
-            try {
-                if (typeof body === "string" || typeof body === "number" || typeof body === "boolean") {
-                    key += `:${String(body)}`;
-                }
-                else if (typeof body === "object") {
-                    key += `:${JSON.stringify(body)}`;
-                }
-            }
-            catch (e) {
-                console.warn("Failed to stringify request body for cache key");
-            }
+    static getTokenFromMeta(metaName = "csrf-token") {
+        if (typeof document === "undefined") {
+            return null;
         }
-        // Add prefix if specified
-        return this.options.keyPrefix ? `${this.options.keyPrefix}:${key}` : key;
+        const meta = document.querySelector(`meta[name="${metaName}"]`);
+        return (meta === null || meta === void 0 ? void 0 : meta.getAttribute("content")) || null;
     }
     /**
-     * Get a value from cache
+     * Extracts CSRF token from a cookie
+     * @param cookieName The name of the cookie containing the CSRF token
+     * @returns The CSRF token or null if not found
      */
-    async get(key) {
-        const value = await Promise.resolve(this.storage.get(key));
-        if (!value)
+    static getTokenFromCookie(cookieName = "csrf-token") {
+        if (typeof document === "undefined") {
             return null;
-        try {
-            const entry = JSON.parse(value);
-            // Check if the entry has expired
-            if (entry.expiry && entry.expiry < Date.now()) {
-                await Promise.resolve(this.storage.delete(key));
-                return null;
-            }
-            return entry;
         }
-        catch (e) {
-            // If we can't parse the cached value, remove it
-            await Promise.resolve(this.storage.delete(key));
-            return null;
+        const cookies = document.cookie.split(";");
+        for (const cookie of cookies) {
+            const [name, value] = cookie.trim().split("=");
+            if (name === cookieName) {
+                return decodeURIComponent(value);
+            }
         }
+        return null;
     }
     /**
-     * Set a value in cache
+     * Validates if the provided string is a potential CSRF token
+     * Checks if the token meets security requirements
+     * @param token The token to validate
+     * @returns Whether the token is valid
      */
-    async set(key, value, headers) {
-        const now = Date.now();
-        const ttl = this.options.ttl;
-        const entry = {
-            value,
-            timestamp: now,
-            expiry: ttl ? now + ttl : null,
-            headers,
-        };
-        const serialized = JSON.stringify(entry);
-        // Check size constraints if applicable
-        if (this.options.maxSize) {
-            const maxBytes = parseSize(this.options.maxSize);
-            const entrySize = new TextEncoder().encode(serialized).length;
-            // If a single entry exceeds the max size, reject it without clearing the cache
-            if (entrySize > maxBytes) {
-                console.warn(`Cache entry size (${entrySize} bytes) exceeds maximum cache size (${maxBytes} bytes)`);
-                return;
-            }
-            // Only clear if adding this entry would exceed the total limit
-            if (this.totalSize + entrySize > maxBytes) {
-                // Simple strategy: clear everything
-                // A more sophisticated strategy would remove oldest entries first
-                await Promise.resolve(this.storage.clear());
-                this.totalSize = 0;
-                this.entryCount = 0;
-            }
-            this.totalSize += entrySize;
+    static isValidToken(token) {
+        // Basic checks for null/undefined and type
+        if (typeof token !== "string") {
+            return false;
         }
-        // Check max entries constraint
-        if (this.options.maxEntries) {
-            this.entryCount++;
-            if (this.entryCount > this.options.maxEntries) {
-                // Simple strategy: clear everything
-                // A more sophisticated strategy would use LRU cache
-                await Promise.resolve(this.storage.clear());
-                this.entryCount = 1;
+        if (token.length < 8)
+            return false;
+        // If token is longer than 10 chars, perform additional security checks
+        if (token.length > 10) {
+            // Check for valid character set (alphanumeric & common token symbols)
+            const validTokenRegex = /^[A-Za-z0-9\-_=+/.]+$/;
+            if (!validTokenRegex.test(token)) {
+                return false;
             }
+            // For longer tokens, check for sufficient entropy (at least 2 character types)
+            const hasUpperCase = /[A-Z]/.test(token);
+            const hasLowerCase = /[a-z]/.test(token);
+            const hasNumbers = /[0-9]/.test(token);
+            const hasSpecials = /[-_=+/.]/.test(token);
+            const characterTypesCount = [hasUpperCase, hasLowerCase, hasNumbers, hasSpecials].filter(Boolean).length;
+            return characterTypesCount >= 2;
         }
-        // Pass ttl to storage provider if available
-        await Promise.resolve(this.storage.set(key, serialized, ttl));
-    }
-    /**
-     * Check if a key exists in the cache
-     */
-    async has(key) {
-        return Promise.resolve(this.storage.has(key));
-    }
-    /**
-     * Delete a key from the cache
-     */
-    async delete(key) {
-        return Promise.resolve(this.storage.delete(key));
-    }
-    /**
-     * Clear the entire cache
-     */
-    async clear() {
-        this.entryCount = 0;
-        this.totalSize = 0;
-        return Promise.resolve(this.storage.clear());
+        // For shorter tokens (8-10 chars), just return true if we reached here
+        return true;
     }
 }
 
@@ -584,9 +570,20 @@ class Config {
         this.csrfToken = null;
         this.enableAutoXsrf = true;
         this.enableAntiCsrf = true; // X-Requested-With header
+        // Interceptor configuration
+        this.requestInterceptors = [];
+        this.responseInterceptors = [];
+        this.errorInterceptors = [];
+        this.nextInterceptorId = 1;
     }
     /**
-     * Get the singleton instance
+     * Get the singleton instance of the Config class
+     *
+     * @returns The global configuration instance
+     *
+     * @example
+     * const config = Config.getInstance();
+     * config.setCsrfToken('token123');
      */
     static getInstance() {
         if (!Config.instance) {
@@ -596,231 +593,432 @@ class Config {
     }
     /**
      * Set a global CSRF token to be used for all requests
+     *
+     * @param token - The CSRF token value
+     * @returns The config instance for chaining
+     *
+     * @example
+     * Config.getInstance().setCsrfToken('myToken123');
      */
     setCsrfToken(token) {
         this.csrfToken = token;
         return this;
     }
     /**
-     * Get the global CSRF token
+     * Get the global CSRF token that will be automatically applied to requests
+     *
+     * @returns The current CSRF token or null if not set
      */
     getCsrfToken() {
         return this.csrfToken;
     }
     /**
-     * Set the CSRF header name (default is X-CSRF-Token)
+     * Set the CSRF header name used when sending the token
+     *
+     * @param name - The header name to use
+     * @returns The config instance for chaining
+     *
+     * @example
+     * Config.getInstance().setCsrfHeaderName('X-My-CSRF-Token');
      */
     setCsrfHeaderName(name) {
         this.csrfHeaderName = name;
         return this;
     }
     /**
-     * Get the CSRF header name
+     * Get the configured CSRF header name
+     *
+     * @returns The current CSRF header name
      */
     getCsrfHeaderName() {
         return this.csrfHeaderName;
     }
     /**
-     * Set the XSRF cookie name to look for (default is XSRF-TOKEN)
+     * Set the XSRF cookie name to look for when extracting tokens from cookies
+     *
+     * @param name - The cookie name to look for
+     * @returns The config instance for chaining
+     *
+     * @example
+     * Config.getInstance().setXsrfCookieName('MY-XSRF-COOKIE');
      */
     setXsrfCookieName(name) {
         this.xsrfCookieName = name;
         return this;
     }
     /**
-     * Get the XSRF cookie name
+     * Get the configured XSRF cookie name
+     *
+     * @returns The current XSRF cookie name
      */
     getXsrfCookieName() {
         return this.xsrfCookieName;
     }
     /**
-     * Set the XSRF header name to send the token in (default is X-XSRF-TOKEN)
+     * Set the XSRF header name for sending tokens extracted from cookies
+     *
+     * @param name - The header name to use
+     * @returns The config instance for chaining
      */
     setXsrfHeaderName(name) {
         this.xsrfHeaderName = name;
         return this;
     }
     /**
-     * Get the XSRF header name
+     * Get the configured XSRF header name
+     *
+     * @returns The current XSRF header name
      */
     getXsrfHeaderName() {
         return this.xsrfHeaderName;
     }
     /**
-     * Enable or disable automatic XSRF token extraction from cookies
+     * Enable or disable automatic extraction of XSRF tokens from cookies
+     * When enabled, the library will look for XSRF tokens in cookies and
+     * automatically add them to request headers.
+     *
+     * @param enable - Whether to enable this feature
+     * @returns The config instance for chaining
+     *
+     * @example
+     * Config.getInstance().setEnableAutoXsrf(false); // Disable XSRF extraction
      */
     setEnableAutoXsrf(enable) {
         this.enableAutoXsrf = enable;
         return this;
     }
     /**
-     * Check if automatic XSRF is enabled
+     * Check if automatic XSRF token extraction is enabled
+     *
+     * @returns True if automatic XSRF is enabled
      */
     isAutoXsrfEnabled() {
         return this.enableAutoXsrf;
     }
     /**
      * Enable or disable automatic addition of anti-CSRF headers
+     * When enabled, X-Requested-With: XMLHttpRequest will be added to all requests.
+     *
+     * @param enable - Whether to enable this feature
+     * @returns The config instance for chaining
      */
     setEnableAntiCsrf(enable) {
         this.enableAntiCsrf = enable;
         return this;
     }
     /**
-     * Check if anti-CSRF is enabled
+     * Check if anti-CSRF protection is enabled
+     *
+     * @returns True if anti-CSRF protection is enabled
      */
     isAntiCsrfEnabled() {
         return this.enableAntiCsrf;
     }
     /**
-     * Reset all configuration options to their defaults
+     * Add a global request interceptor
+     * Request interceptors can modify the request configuration or return an early response
+     *
+     * @param interceptor - The request interceptor function
+     * @returns The interceptor ID for later removal
+     *
+     * @example
+     * const id = Config.getInstance().addRequestInterceptor((config) => {
+     *   config.headers['X-Custom'] = 'value';
+     *   return config;
+     * });
      */
-    reset() {
-        this.csrfToken = null;
-        this.csrfHeaderName = "X-CSRF-Token";
-        this.enableAntiCsrf = true;
-        this.xsrfCookieName = "XSRF-TOKEN";
-        this.xsrfHeaderName = "X-XSRF-TOKEN";
-        this.enableAutoXsrf = true;
-        return this;
+    addRequestInterceptor(interceptor) {
+        const id = this.nextInterceptorId++;
+        this.requestInterceptors.push({ id, interceptor });
+        return id;
     }
-}
-
-class CookieUtils {
     /**
-     * Formats cookies for a request
-     * @param cookies Object containing cookie name-value pairs or cookie options
-     * @returns Formatted cookie string for the Cookie header
+     * Add a global response interceptor
+     * Response interceptors can transform the response
+     *
+     * @param interceptor - The response interceptor function
+     * @returns The interceptor ID for later removal
+     *
+     * @example
+     * const id = Config.getInstance().addResponseInterceptor((response) => {
+     *   console.log('Response received:', response.status);
+     *   return response;
+     * });
      */
-    static formatRequestCookies(cookies) {
-        const cookiePairs = [];
-        Object.entries(cookies).forEach(([name, valueOrOptions]) => {
-            let value;
-            if (typeof valueOrOptions === "string") {
-                value = valueOrOptions;
-            }
-            else {
-                // Extract value from options object without validation
-                value = valueOrOptions.value;
-            }
-            // Add the cookie to the request
-            cookiePairs.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
-        });
-        return cookiePairs.join("; ");
+    addResponseInterceptor(interceptor) {
+        const id = this.nextInterceptorId++;
+        this.responseInterceptors.push({ id, interceptor });
+        return id;
     }
-}
-
-/**
- * Utility class for CSRF token management
- */
-class CsrfUtils {
     /**
-     * Extracts CSRF token from a meta tag in the document head
-     * @param metaName The name attribute of the meta tag (default: "csrf-token")
-     * @returns The CSRF token or null if not found
+     * Add a global error interceptor
+     * Error interceptors can handle or transform errors
+     *
+     * @param interceptor - The error interceptor function
+     * @returns The interceptor ID for later removal
+     *
+     * @example
+     * const id = Config.getInstance().addErrorInterceptor((error) => {
+     *   console.error('Request failed:', error);
+     *   throw error;
+     * });
      */
-    static getTokenFromMeta(metaName = "csrf-token") {
-        if (typeof document === "undefined") {
-            return null;
-        }
-        const meta = document.querySelector(`meta[name="${metaName}"]`);
-        return (meta === null || meta === void 0 ? void 0 : meta.getAttribute("content")) || null;
+    addErrorInterceptor(interceptor) {
+        const id = this.nextInterceptorId++;
+        this.errorInterceptors.push({ id, interceptor });
+        return id;
     }
     /**
-     * Extracts CSRF token from a cookie
-     * @param cookieName The name of the cookie containing the CSRF token
-     * @returns The CSRF token or null if not found
+     * Remove a request interceptor by its ID
+     *
+     * @param id - The interceptor ID returned from addRequestInterceptor
+     *
+     * @example
+     * Config.getInstance().removeRequestInterceptor(id);
      */
-    static getTokenFromCookie(cookieName = "csrf-token") {
-        if (typeof document === "undefined") {
-            return null;
-        }
-        const cookies = document.cookie.split(";");
-        for (const cookie of cookies) {
-            const [name, value] = cookie.trim().split("=");
-            if (name === cookieName) {
-                return decodeURIComponent(value);
-            }
-        }
-        return null;
+    removeRequestInterceptor(id) {
+        this.requestInterceptors = this.requestInterceptors.filter(item => item.id !== id);
     }
     /**
-     * Validates if the provided string is a potential CSRF token
-     * Checks if the token meets security requirements
-     * @param token The token to validate
-     * @returns Whether the token is valid
+     * Remove a response interceptor by its ID
+     *
+     * @param id - The interceptor ID returned from addResponseInterceptor
+     *
+     * @example
+     * Config.getInstance().removeResponseInterceptor(id);
      */
-    static isValidToken(token) {
-        // Basic checks for null/undefined and type
-        if (typeof token !== "string") {
-            return false;
-        }
-        if (token.length < 8)
-            return false;
-        // If token is longer than 10 chars, perform additional security checks
-        if (token.length > 10) {
-            // Check for valid character set (alphanumeric & common token symbols)
-            const validTokenRegex = /^[A-Za-z0-9\-_=+/.]+$/;
-            if (!validTokenRegex.test(token)) {
-                return false;
-            }
-            // For longer tokens, check for sufficient entropy (at least 2 character types)
-            const hasUpperCase = /[A-Z]/.test(token);
-            const hasLowerCase = /[a-z]/.test(token);
-            const hasNumbers = /[0-9]/.test(token);
-            const hasSpecials = /[-_=+/.]/.test(token);
-            const characterTypesCount = [hasUpperCase, hasLowerCase, hasNumbers, hasSpecials].filter(Boolean).length;
-            return characterTypesCount >= 2;
-        }
-        // For shorter tokens (8-10 chars), just return true if we reached here
-        return true;
+    removeResponseInterceptor(id) {
+        this.responseInterceptors = this.responseInterceptors.filter(item => item.id !== id);
+    }
+    /**
+     * Remove an error interceptor by its ID
+     *
+     * @param id - The interceptor ID returned from addErrorInterceptor
+     *
+     * @example
+     * Config.getInstance().removeErrorInterceptor(id);
+     */
+    removeErrorInterceptor(id) {
+        this.errorInterceptors = this.errorInterceptors.filter(item => item.id !== id);
+    }
+    /**
+     * Clear all interceptors (request, response, and error)
+     *
+     * @example
+     * Config.getInstance().clearInterceptors();
+     */
+    clearInterceptors() {
+        this.requestInterceptors = [];
+        this.responseInterceptors = [];
+        this.errorInterceptors = [];
+    }
+    /**
+     * Get all global request interceptors (in registration order)
+     * @internal
+     */
+    getRequestInterceptors() {
+        return this.requestInterceptors.map(item => item.interceptor);
+    }
+    /**
+     * Get all global response interceptors (in registration order)
+     * @internal
+     */
+    getResponseInterceptors() {
+        return this.responseInterceptors.map(item => item.interceptor);
+    }
+    /**
+     * Get all global error interceptors (in registration order)
+     * @internal
+     */
+    getErrorInterceptors() {
+        return this.errorInterceptors.map(item => item.interceptor);
+    }
+    /**
+     * Reset all configuration options to their default values
+     *
+     * @returns The config instance for chaining
+     *
+     * @example
+     * Config.getInstance().reset();
+     */
+    reset() {
+        this.csrfToken = null;
+        this.csrfHeaderName = "X-CSRF-Token";
+        this.enableAntiCsrf = true;
+        this.xsrfCookieName = "XSRF-TOKEN";
+        this.xsrfHeaderName = "X-XSRF-TOKEN";
+        this.enableAutoXsrf = true;
+        this.clearInterceptors();
+        return this;
     }
 }
 
-// Base class with common functionality for all request types
+/**
+ * Base class with common functionality for all request types
+ * Provides the core request building and execution capabilities.
+ */
 class BaseRequest {
-    constructor() {
+    constructor(url) {
         this.requestOptions = {
             headers: {},
         };
         this.queryParams = new URLSearchParams();
         this.autoApplyCsrfProtection = true;
-        this.cacheEnabled = false;
+        // Per-request interceptors
+        this.requestInterceptors = [];
+        this.responseInterceptors = [];
+        this.errorInterceptors = [];
+        this.url = url;
+    }
+    /**
+     * Get GraphQL options if set (only for BodyRequest subclasses)
+     * @returns GraphQL options or undefined
+     */
+    getGraphQLOptions() {
+        return undefined;
+    }
+    /**
+     * Creates a fluent API for setting enum-based options
+     * Combines direct setter with convenience methods
+     */
+    createFluentSetter(optionName, options) {
+        const fluent = {};
+        // Create convenience methods for each enum value
+        Object.entries(options).forEach(([key, value]) => {
+            fluent[key] = () => {
+                this.requestOptions[optionName] = value;
+                return this;
+            };
+        });
+        // Create the callable setter
+        const callable = (value) => {
+            this.requestOptions[optionName] = value;
+            return this;
+        };
+        return Object.assign(callable, fluent);
+    }
+    validateUrl(url) {
+        if (!(url === null || url === void 0 ? void 0 : url.trim()))
+            throw new RequestError("URL cannot be empty", url, this.method);
+        if (url.includes("\0") || url.includes("\r") || url.includes("\n")) {
+            throw new RequestError("Invalid URL (control chars)", url, this.method);
+        }
+        const trimmed = url.trim();
+        if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+            try {
+                new URL(trimmed);
+            }
+            catch (_a) {
+                throw new RequestError(`Invalid URL: ${trimmed}`, trimmed, this.method);
+            }
+        }
     }
+    /**
+     * Add multiple HTTP headers to the request
+     *
+     * @param headers - Key-value pairs of header names and values
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withHeaders({
+     *   'Accept': 'application/json',
+     *   'X-Custom-Header': 'value'
+     * });
+     */
     withHeaders(headers) {
+        // Filter out null and undefined values
+        const filteredHeaders = {};
+        Object.entries(headers).forEach(([key, value]) => {
+            if (value !== null && value !== undefined) {
+                filteredHeaders[key] = value;
+            }
+        });
         this.requestOptions.headers = {
-            ...this.requestOptions.headers,
-            ...headers,
+            ...this.getHeadersRecord(),
+            ...filteredHeaders,
         };
         return this;
     }
+    /**
+     * Add a single HTTP header to the request
+     *
+     * @param key - The header name
+     * @param value - The header value
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withHeader('Accept', 'application/json');
+     */
     withHeader(key, value) {
-        return this.withHeaders({ [key]: value });
+        // Ignore null and undefined values
+        if (value !== null && value !== undefined) {
+            return this.withHeaders({ [key]: value });
+        }
+        return this;
     }
+    /**
+     * Set a timeout for the request
+     * If the request takes longer than the specified timeout, it will be aborted.
+     *
+     * @param timeout - The timeout in milliseconds
+     * @returns The request instance for chaining
+     * @throws RequestError if timeout is not a positive number
+     *
+     * @example
+     * request.withTimeout(5000); // 5 seconds timeout
+     */
     withTimeout(timeout) {
         if (!Number.isFinite(timeout) || timeout <= 0)
-            throw new Error("Timeout must be a positive number");
+            throw new RequestError("Timeout must be a positive number", this.url, this.method);
         this.requestOptions.timeout = timeout;
         return this;
     }
+    /**
+     * Configure automatic retry behavior for failed requests
+     *
+     * @param retries - Number of retry attempts before failing
+     * @returns The request instance for chaining
+     * @throws RequestError if retries is not a non-negative integer
+     *
+     * @example
+     * request.withRetries(3); // Retry up to 3 times
+     */
     withRetries(retries) {
         if (!Number.isInteger(retries) || retries < 0)
-            throw new Error("Retry count must be a non-negative integer");
+            throw new RequestError("Retry count must be a non-negative integer", this.url, this.method);
         this.requestOptions.retries = retries;
         return this;
     }
+    /**
+     * Set a callback to be invoked before each retry attempt
+     * Useful for implementing backoff strategies or logging retry attempts.
+     *
+     * @param callback - Function to call before retrying
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.onRetry(({ attempt, error }) => {
+     *   console.log(`Retry attempt ${attempt} after error: ${error.message}`);
+     *   return new Promise(resolve => setTimeout(resolve, attempt * 1000));
+     * });
+     */
     onRetry(callback) {
         this.requestOptions.onRetry = callback;
         return this;
     }
     /**
-     * Sets the credentials policy for the request
-     * @param credentialsPolicy - Can be 'omit', 'same-origin', or 'include'
-     * @returns The instance for chaining
+     * Sets credentials policy - supports both direct call and fluent API
+     * @example
+     * request.withCredentials("include")
+     * request.withCredentials(CredentialsPolicy.INCLUDE)
+     * request.withCredentials.INCLUDE()
      */
-    withCredentials(credentialsPolicy = CredentialsPolicy.SAME_ORIGIN) {
-        this.requestOptions.credentials = credentialsPolicy;
-        return this;
+    get withCredentials() {
+        return this.createFluentSetter("credentials", {
+            INCLUDE: CredentialsPolicy.INCLUDE,
+            OMIT: CredentialsPolicy.OMIT,
+            SAME_ORIGIN: CredentialsPolicy.SAME_ORIGIN,
+        });
     }
     /**
      * Allows providing an external AbortController to cancel the request
@@ -841,22 +1039,37 @@ class BaseRequest {
         return this;
     }
     /**
-     * Sets the referrer policy for the request
-     * @param policy - The referrer policy to use
-     * @returns The instance for chaining
+     * Sets referrer policy - supports both direct call and fluent API
+     * @example
+     * request.withReferrerPolicy("no-referrer")
+     * request.withReferrerPolicy(ReferrerPolicy.NO_REFERRER)
+     * request.withReferrerPolicy.NO_REFERRER()
      */
-    withReferrerPolicy(policy) {
-        this.requestOptions.referrerPolicy = policy;
-        return this;
+    get withReferrerPolicy() {
+        return this.createFluentSetter("referrerPolicy", {
+            ORIGIN: ReferrerPolicy.ORIGIN,
+            UNSAFE_URL: ReferrerPolicy.UNSAFE_URL,
+            SAME_ORIGIN: ReferrerPolicy.SAME_ORIGIN,
+            NO_REFERRER: ReferrerPolicy.NO_REFERRER,
+            STRICT_ORIGIN: ReferrerPolicy.STRICT_ORIGIN,
+            ORIGIN_WHEN_CROSS_ORIGIN: ReferrerPolicy.ORIGIN_WHEN_CROSS_ORIGIN,
+            NO_REFERRER_WHEN_DOWNGRADE: ReferrerPolicy.NO_REFERRER_WHEN_DOWNGRADE,
+            STRICT_ORIGIN_WHEN_CROSS_ORIGIN: ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN,
+        });
     }
     /**
-     * Sets the redirect policy for the request
-     * @param redirect - Can be 'follow', 'error', or 'manual'
-     * @returns The instance for chaining
+     * Sets redirect mode - supports both direct call and fluent API
+     * @example
+     * request.withRedirect("follow")
+     * request.withRedirect(RedirectMode.FOLLOW)
+     * request.withRedirect.FOLLOW()
      */
-    withRedirect(redirect) {
-        this.requestOptions.redirect = redirect;
-        return this;
+    get withRedirect() {
+        return this.createFluentSetter("redirect", {
+            FOLLOW: RedirectMode.FOLLOW,
+            ERROR: RedirectMode.ERROR,
+            MANUAL: RedirectMode.MANUAL,
+        });
     }
     /**
      * Sets the keepalive flag for the request
@@ -868,13 +1081,18 @@ class BaseRequest {
         return this;
     }
     /**
-     * Sets the priority of the request
-     * @param priority - Can be 'high', 'low', or 'auto'
-     * @returns The instance for chaining
+     * Sets request priority - supports both direct call and fluent API
+     * @example
+     * request.withPriority("high")
+     * request.withPriority(RequestPriority.HIGH)
+     * request.withPriority.HIGH()
      */
-    withPriority(priority) {
-        this.requestOptions.priority = priority;
-        return this;
+    get withPriority() {
+        return this.createFluentSetter("priority", {
+            HIGH: RequestPriority.HIGH,
+            LOW: RequestPriority.LOW,
+            AUTO: RequestPriority.AUTO,
+        });
     }
     /**
      * Adds query parameters to the request URL
@@ -912,13 +1130,19 @@ class BaseRequest {
         return this;
     }
     /**
-     * Sets the mode of the request
-     * @param mode - The mode for the request (cors, no-cors, same-origin, navigate)
-     * @returns The instance for chaining
+     * Sets request mode - supports both direct call and fluent API
+     * @example
+     * request.withMode("cors")
+     * request.withMode(RequestMode.CORS)
+     * request.withMode.CORS()
      */
-    withMode(mode) {
-        this.requestOptions.mode = mode;
-        return this;
+    get withMode() {
+        return this.createFluentSetter("mode", {
+            CORS: RequestMode.CORS,
+            NO_CORS: RequestMode.NO_CORS,
+            SAME_ORIGIN: RequestMode.SAME_ORIGIN,
+            NAVIGATE: RequestMode.NAVIGATE,
+        });
     }
     /**
      * Shorthand for setting the Content-Type header
@@ -968,7 +1192,7 @@ class BaseRequest {
         if (typeof Buffer !== "undefined")
             return Buffer.from(str).toString("base64");
         // Fallback (should never happen in modern environments)
-        throw new Error("Base64 encoding is not supported in this environment");
+        throw new RequestError("Base64 encoding is not supported", this.url, this.method);
     }
     /**
      * Sets the bearer token for authentication
@@ -978,13 +1202,23 @@ class BaseRequest {
     withBearerToken(token) {
         return this.withAuthorization(`Bearer ${token}`);
     }
+    /**
+     * Safely get headers as a Record<string, string>
+     * @returns The headers object
+     */
+    getHeadersRecord() {
+        if (typeof this.requestOptions.headers === "object" && this.requestOptions.headers !== null) {
+            return this.requestOptions.headers;
+        }
+        return {};
+    }
     /**
      * Helper function to check for header presence in a case-insensitive way
-     * @param headers Headers object
      * @param headerName Header name to check
      * @returns Boolean indicating if the header exists (case-insensitive)
      */
-    hasHeader(headers, headerName) {
+    hasHeader(headerName) {
+        const headers = this.getHeadersRecord();
         return Object.keys(headers).some(key => key.toLowerCase() === headerName.toLowerCase());
     }
     /**
@@ -993,12 +1227,11 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withCookies(cookies) {
-        const cookieEntries = Object.entries(cookies);
+        const cookieEntries = Object.entries(cookies || {});
         if (cookieEntries.length === 0) {
             return this;
         }
-        // Get current headers or initialize empty object
-        const currentHeaders = this.requestOptions.headers || {};
+        const currentHeaders = this.getHeadersRecord();
         // Get all existing cookie headers with different cases
         const cookieValues = [];
         const cookieHeaderKeys = [];
@@ -1067,110 +1300,200 @@ class BaseRequest {
         });
     }
     /**
-     * Enables caching for the request with the specified options
-     * @param options The cache configuration options
+     * Add a request interceptor for this specific request
+     * Request interceptors can modify the request configuration or return an early response
+     *
+     * @param interceptor - The request interceptor function
+     * @returns The instance for chaining
+     *
+     * @example
+     * request.withRequestInterceptor((config) => {
+     *   config.headers['X-Custom'] = 'value';
+     *   return config;
+     * });
+     */
+    withRequestInterceptor(interceptor) {
+        this.requestInterceptors.push(interceptor);
+        return this;
+    }
+    /**
+     * Add a response interceptor for this specific request
+     * Response interceptors can transform the response
+     *
+     * @param interceptor - The response interceptor function
+     * @returns The instance for chaining
+     *
+     * @example
+     * request.withResponseInterceptor((response) => {
+     *   console.log('Status:', response.status);
+     *   return response;
+     * });
+     */
+    withResponseInterceptor(interceptor) {
+        this.responseInterceptors.push(interceptor);
+        return this;
+    }
+    /**
+     * Add an error interceptor for this specific request
+     * Error interceptors can handle or transform errors
+     *
+     * @param interceptor - The error interceptor function
      * @returns The instance for chaining
+     *
+     * @example
+     * request.withErrorInterceptor((error) => {
+     *   console.error('Request failed:', error);
+     *   throw error;
+     * });
      */
-    withCache(options = {}) {
-        this.cacheEnabled = true;
-        this.cacheManager = new CacheManager(options);
+    withErrorInterceptor(interceptor) {
+        this.errorInterceptors.push(interceptor);
         return this;
     }
     /**
-     * Send the request to the specified URL
-     * @param url The URL to send the request to
+     * Execute the request and return the ResponseWrapper
+     * This is the base method for getting the full response.
+     *
+     * @returns A promise that resolves to the ResponseWrapper
+     *
+     * @example
+     * const response = await request.getResponse();
+     * console.log(response.status);
+     */
+    async getResponse() {
+        const url = this.formatUrlWithQueryParams(this.url);
+        this.applyCsrfProtection();
+        const fetchOptions = {
+            ...this.requestOptions,
+            method: this.method,
+        };
+        return !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
+    }
+    /**
+     * Execute the request and parse the response as JSON
+     *
+     * @returns A promise that resolves to the parsed JSON data
+     * @throws {RequestError} When the request fails, JSON parsing fails, GraphQL errors occur (if throwOnError enabled), or body is already consumed
+     *
+     * @example
+     * const users = await request.getJson<User[]>();
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await request.getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
+     */
+    async getJson() {
+        const response = await this.getResponse();
+        return response.getJson();
+    }
+    /**
+     * Execute the request and get the response as text
+     *
+     * @returns A promise that resolves to the response text
+     *
+     * @example
+     * const text = await request.getText();
+     */
+    async getText() {
+        const response = await this.getResponse();
+        return response.getText();
+    }
+    /**
+     * Execute the request and get the response as a Blob
+     *
+     * @returns A promise that resolves to the response Blob
+     *
+     * @example
+     * const blob = await request.getBlob();
+     */
+    async getBlob() {
+        const response = await this.getResponse();
+        return response.getBlob();
+    }
+    /**
+     * Execute the request and get the response body as a ReadableStream
+     *
+     * @returns A promise that resolves to the response body stream
+     *
+     * @example
+     * const stream = await request.getBody();
+     */
+    async getBody() {
+        const response = await this.getResponse();
+        return response.getBody();
+    }
+    /**
+     * Execute the request and extract specific data using a selector function
+     * If no selector is provided, returns the full JSON response.
+     *
+     * @param selector - Optional function to extract and transform data
+     * @returns A promise that resolves to the selected data
+     * @throws {RequestError} When the request fails, JSON parsing fails, or the selector throws an error
+     *
+     * @example
+     * // Get full response
+     * const data = await request.getData();
+     *
+     * // Extract specific data
+     * const users = await request.getData(data => data.results.users);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await request.getData();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
+     */
+    async getData(selector) {
+        const response = await this.getResponse();
+        return response.getData(selector);
+    }
+    /**
+     * Apply CSRF protection headers based on configuration
      */
-    sendTo(url) {
-        // Format the URL with query parameters
-        url = this.formatUrlWithQueryParams(url);
-        // Apply automatic CSRF protection if enabled
-        if (this.autoApplyCsrfProtection) {
-            const config = Config.getInstance();
-            // Apply anti-CSRF headers if enabled
-            if (config.isAntiCsrfEnabled()) {
+    applyCsrfProtection() {
+        if (!this.autoApplyCsrfProtection)
+            return;
+        const config = Config.getInstance();
+        // Apply anti-CSRF headers if enabled
+        if (config.isAntiCsrfEnabled()) {
+            this.withHeaders({
+                "X-Requested-With": "XMLHttpRequest",
+            });
+        }
+        // Apply global CSRF token if set
+        const globalToken = config.getCsrfToken();
+        if (globalToken) {
+            const csrfHeaderName = config.getCsrfHeaderName();
+            const hasLocalToken = this.hasHeader("X-CSRF-Token") || this.hasHeader(csrfHeaderName);
+            if (!hasLocalToken) {
                 this.withHeaders({
-                    "X-Requested-With": "XMLHttpRequest",
+                    [csrfHeaderName]: globalToken,
                 });
             }
-            // Apply global CSRF token if set
-            const globalToken = config.getCsrfToken();
-            if (globalToken) {
-                // Check if local token exists using case-insensitive comparison
-                const headers = this.requestOptions.headers;
-                const csrfHeaderName = config.getCsrfHeaderName();
-                const hasLocalToken = this.hasHeader(headers, "X-CSRF-Token") || this.hasHeader(headers, csrfHeaderName);
+        }
+        // Check for XSRF token in cookies and send it as a header
+        if (config.isAutoXsrfEnabled() && typeof document !== "undefined") {
+            const xsrfToken = CsrfUtils.getTokenFromCookie(config.getXsrfCookieName());
+            if (xsrfToken && CsrfUtils.isValidToken(xsrfToken)) {
+                const xsrfHeaderName = config.getXsrfHeaderName();
+                const hasLocalToken = this.hasHeader("X-XSRF-TOKEN") || this.hasHeader(xsrfHeaderName);
                 if (!hasLocalToken) {
                     this.withHeaders({
-                        [csrfHeaderName]: globalToken,
+                        [xsrfHeaderName]: xsrfToken,
                     });
                 }
             }
-            // check for XSRF token in cookies and send it as a header
-            if (config.isAutoXsrfEnabled() && typeof document !== "undefined") {
-                const xsrfToken = CsrfUtils.getTokenFromCookie(config.getXsrfCookieName());
-                if (xsrfToken && CsrfUtils.isValidToken(xsrfToken)) {
-                    const headers = this.requestOptions.headers;
-                    const xsrfHeaderName = config.getXsrfHeaderName();
-                    const hasLocalToken = this.hasHeader(headers, "X-XSRF-TOKEN") || this.hasHeader(headers, xsrfHeaderName);
-                    if (!hasLocalToken) {
-                        this.withHeaders({
-                            [xsrfHeaderName]: xsrfToken,
-                        });
-                    }
-                }
-            }
-        }
-        // Cast the request options to RequestInit to ensure compatibility
-        const fetchOptions = {
-            ...this.requestOptions,
-            method: this.method,
-        };
-        // Create the base promise - handle caching if enabled
-        let basePromise;
-        if (this.cacheEnabled && this.cacheManager) {
-            const cacheKey = this.cacheManager.generateKey(url, this.method, this.requestOptions.headers, this.requestOptions.body);
-            basePromise = this.executeWithCache(url, fetchOptions, cacheKey);
         }
-        else {
-            basePromise = !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
-        }
-        const responsePromise = basePromise;
-        // Attach convenience methods that begin processing immediately
-        responsePromise.getJson = async () => {
-            return basePromise.then(response => response.getJson());
-        };
-        responsePromise.getText = async () => {
-            return basePromise.then(response => response.getText());
-        };
-        responsePromise.getBlob = async () => {
-            return basePromise.then(response => response.getBlob());
-        };
-        responsePromise.getArrayBuffer = async () => {
-            return basePromise.then(response => response.getArrayBuffer());
-        };
-        responsePromise.getBody = async () => {
-            return basePromise.then(response => response.getBody());
-        };
-        responsePromise.getData = async (selector) => {
-            try {
-                const data = await basePromise.then(response => response.getJson());
-                // If no selector is provided, return the raw JSON data
-                if (!selector)
-                    return data;
-                // Apply the selector if provided
-                return selector(data);
-            }
-            catch (error) {
-                if (error instanceof Error) {
-                    // If selector fails, enhance the error with the original data
-                    const enhancedError = new Error(`Data selector failed: ${error.message}. Original data: ${JSON.stringify(await basePromise.then(response => response.getJson()), null, 2)}`);
-                    enhancedError.stack = error.stack;
-                    throw enhancedError;
-                }
-                throw error;
-            }
-        };
-        return responsePromise;
     }
     /**
      * Formats the URL with any query parameters
@@ -1178,7 +1501,8 @@ class BaseRequest {
      * @returns The URL with query parameters appended
      */
     formatUrlWithQueryParams(url) {
-        if (!this.queryParams.toString()) {
+        const queryString = this.queryParams.toString();
+        if (!queryString) {
             return url;
         }
         try {
@@ -1194,7 +1518,7 @@ class BaseRequest {
             // Handle relative URLs
             const hasExistingParams = url.includes("?");
             const separator = hasExistingParams ? "&" : "?";
-            return `${url}${separator}${this.queryParams.toString()}`;
+            return `${url}${separator}${queryString}`;
         }
     }
     /**
@@ -1202,136 +1526,298 @@ class BaseRequest {
      * @param url The formatted URL to send the request to
      * @param fetchOptions The fetch options to use
      * @returns A wrapped response object
+     * @throws RequestError if the request fails after all retries
      */
     async executeWithRetries(url, fetchOptions) {
-        let attempt = 0;
         const maxRetries = this.requestOptions.retries || 0;
-        do {
+        const method = typeof fetchOptions.method === "string" ? fetchOptions.method : "GET";
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 return await this.executeRequest(url, fetchOptions);
             }
             catch (error) {
-                const requestError = error instanceof RequestError ? error : RequestError.networkError(url, fetchOptions.method, error);
-                // Don't retry on timeout errors or if we've reached the max retries
-                if (attempt >= maxRetries || requestError.timeoutError)
+                const requestError = error instanceof RequestError ? error : RequestError.networkError(url, method, error instanceof Error ? error : new Error(String(error)));
+                if (attempt >= maxRetries)
                     throw requestError;
-                attempt++;
                 if (this.requestOptions.onRetry) {
-                    await this.requestOptions.onRetry({ attempt, error: requestError });
+                    await this.requestOptions.onRetry({ attempt: attempt + 1, error: requestError });
                 }
             }
-        } while (attempt <= maxRetries);
-        // If we somehow get here, we throw an error to avoid undefined behavior
-        throw new RequestError(`Max retries reached (${maxRetries}) but request still failed`, url, fetchOptions.method);
+        }
+        // This should never happen but is needed for type safety
+        throw new RequestError(`Max retries reached`, url, method);
     }
-    async executeRequest(url, fetchOptions) {
-        // Create a request controller for timeout if needed, or use the provided one
-        const controller = this.abortController || new AbortController();
-        const { signal } = controller;
-        // Use the controller signal for the fetch request, but don't overwrite an existing signal
-        fetchOptions.signal = fetchOptions.signal || signal;
-        let timeoutId;
-        // Flag to track if abort was caused by our timeout
-        let abortedByTimeout = false;
-        // Handle timeout regardless of whether an external controller is provided
-        if (this.requestOptions.timeout) {
-            if (this.abortController) {
-                // If we have an external controller, create a separate timeout controller
-                // that won't interfere with the external one
-                // Use AbortSignal.timeout if available (modern browsers)
-                if (typeof AbortSignal.timeout === "function") {
-                    const timeoutSignal = AbortSignal.timeout(this.requestOptions.timeout);
-                    // Add event listener to propagate the abort to the main controller
-                    timeoutSignal.addEventListener("abort", () => {
-                        if (!controller.signal.aborted) {
-                            abortedByTimeout = true;
-                            controller.abort();
-                        }
-                    });
+    /**
+     * Run request interceptors in order: global interceptors first, then per-request
+     * @param configParam - The request configuration
+     * @returns Modified config or a Response to short-circuit
+     */
+    async runRequestInterceptors(configParam) {
+        const globalConfig = Config.getInstance();
+        const allInterceptors = [...globalConfig.getRequestInterceptors(), ...this.requestInterceptors];
+        let currentConfig = configParam;
+        for (let i = 0; i < allInterceptors.length; i++) {
+            try {
+                const result = await allInterceptors[i](currentConfig);
+                // If interceptor returns a Response, short-circuit
+                if (result instanceof Response) {
+                    return result;
+                }
+                currentConfig = result;
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new RequestError(`Request interceptor failed: ${errorMessage}`, currentConfig.url, currentConfig.method);
+            }
+        }
+        return currentConfig;
+    }
+    /**
+     * Run response interceptors in reverse order: per-request interceptors first, then global in reverse
+     * @param response - The response wrapper
+     * @returns Modified response wrapper
+     */
+    async runResponseInterceptors(response) {
+        const globalConfig = Config.getInstance();
+        const globalInterceptors = globalConfig.getResponseInterceptors();
+        // Per-request in order, then global in reverse
+        const allInterceptors = [...this.responseInterceptors, ...globalInterceptors.reverse()];
+        let currentResponse = response;
+        for (let i = 0; i < allInterceptors.length; i++) {
+            try {
+                currentResponse = await allInterceptors[i](currentResponse);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const url = currentResponse.url || "";
+                const method = currentResponse.method || "";
+                throw new RequestError(`Response interceptor failed: ${errorMessage}`, url, method);
+            }
+        }
+        return currentResponse;
+    }
+    /**
+     * Run error interceptors in reverse order: per-request interceptors first, then global in reverse
+     * @param error - The error that occurred
+     * @returns Modified error or a ResponseWrapper to recover
+     */
+    async runErrorInterceptors(error) {
+        const globalConfig = Config.getInstance();
+        const globalInterceptors = globalConfig.getErrorInterceptors();
+        // Per-request in order, then global in reverse
+        const allInterceptors = [...this.errorInterceptors, ...globalInterceptors.reverse()];
+        let currentError = error;
+        for (let i = 0; i < allInterceptors.length; i++) {
+            try {
+                // If previous interceptor recovered with a response, stop processing
+                if (currentError instanceof ResponseWrapper) {
+                    return currentError;
+                }
+                const result = await allInterceptors[i](currentError);
+                currentError = result;
+            }
+            catch (interceptorError) {
+                // If an error interceptor throws, that becomes the new error
+                if (interceptorError instanceof RequestError) {
+                    currentError = interceptorError;
                 }
                 else {
-                    // Fallback for browsers without AbortSignal.timeout
-                    timeoutId = setTimeout(() => {
-                        if (!controller.signal.aborted) {
-                            abortedByTimeout = true;
-                            controller.abort();
-                        }
-                    }, this.requestOptions.timeout);
+                    const errorMessage = interceptorError instanceof Error ? interceptorError.message : String(interceptorError);
+                    // Always wrap in RequestError when we have context
+                    if (currentError instanceof RequestError) {
+                        currentError = new RequestError(`Error interceptor ${i + 1} failed: ${errorMessage}`, currentError.url, currentError.method, {
+                            status: currentError.status,
+                            response: currentError.response,
+                        });
+                    }
+                    else if (currentError instanceof ResponseWrapper && currentError.url && currentError.method) {
+                        // If it's a ResponseWrapper, we can still create a proper RequestError from its context
+                        currentError = new RequestError(`Error interceptor ${i + 1} failed: ${errorMessage}`, currentError.url, currentError.method, {
+                            status: currentError.status,
+                        });
+                    }
+                    else {
+                        // Last resort: if we have no context at all, use the original error's context
+                        // This shouldn't happen in practice, but handle it gracefully
+                        const errorObj = interceptorError instanceof Error ? interceptorError : new Error(String(interceptorError));
+                        currentError = RequestError.networkError(error.url, error.method, errorObj);
+                    }
                 }
             }
+        }
+        return currentError;
+    }
+    /**
+     * Helper to create an abort signal with timeout support
+     * Handles various AbortSignal API levels gracefully
+     */
+    createAbortSignal(timeoutMs, externalController) {
+        let timeoutId;
+        let timeoutController;
+        let isTimeout = false;
+        // No timeout - just use external controller
+        if (!timeoutMs) {
+            return {
+                signal: externalController === null || externalController === void 0 ? void 0 : externalController.signal,
+                cleanup: () => { },
+                wasTimeout: () => false,
+            };
+        }
+        // Check if AbortSignal.any() is available (modern browsers)
+        const hasAbortSignalAny = typeof AbortSignal.any === "function";
+        const hasAbortSignalTimeout = typeof AbortSignal.timeout === "function";
+        // Create timeout signal
+        const createTimeoutSignal = () => {
+            if (hasAbortSignalTimeout) {
+                const signal = AbortSignal.timeout(timeoutMs);
+                signal.addEventListener("abort", () => (isTimeout = true), { once: true });
+                return signal;
+            }
             else {
+                timeoutController = new AbortController();
                 timeoutId = setTimeout(() => {
-                    abortedByTimeout = true;
-                    controller.abort();
-                }, this.requestOptions.timeout);
+                    isTimeout = true;
+                    timeoutController.abort();
+                }, timeoutMs);
+                return timeoutController.signal;
             }
+        };
+        const timeoutSignal = createTimeoutSignal();
+        // Combine signals if we have both timeout and external controller
+        const finalSignal = externalController && hasAbortSignalAny
+            ? AbortSignal.any([externalController.signal, timeoutSignal])
+            : externalController
+                ? this.combineSignalsManually(externalController.signal, timeoutSignal)
+                : timeoutSignal;
+        return {
+            signal: finalSignal,
+            cleanup: () => {
+                if (timeoutId !== undefined)
+                    clearTimeout(timeoutId);
+            },
+            wasTimeout: () => isTimeout,
+        };
+    }
+    /**
+     * Manually combine two abort signals for older environments
+     * Returns the first signal and listens to the second
+     */
+    combineSignalsManually(signal1, signal2) {
+        // If either is already aborted, use that one
+        if (signal1.aborted)
+            return signal1;
+        if (signal2.aborted)
+            return signal2;
+        // Use a controller to create a combined signal
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        signal1.addEventListener("abort", abort, { once: true });
+        signal2.addEventListener("abort", abort, { once: true });
+        return controller.signal;
+    }
+    /**
+     * Convert fetchOptions to RequestConfig with proper typing
+     */
+    createRequestConfig(url, fetchOptions) {
+        const method = typeof fetchOptions.method === "string" ? fetchOptions.method : "GET";
+        const headers = this.getHeadersRecord();
+        const extendedOptions = fetchOptions;
+        return {
+            url,
+            method,
+            headers,
+            body: fetchOptions.body,
+            signal: fetchOptions.signal || undefined,
+            credentials: fetchOptions.credentials,
+            mode: fetchOptions.mode,
+            redirect: fetchOptions.redirect,
+            referrer: fetchOptions.referrer,
+            referrerPolicy: fetchOptions.referrerPolicy,
+            keepalive: fetchOptions.keepalive,
+            priority: extendedOptions.priority,
+        };
+    }
+    /**
+     * Apply interceptor results back to fetchOptions
+     */
+    applyRequestConfig(config, fetchOptions) {
+        fetchOptions.headers = config.headers;
+        if (config.body !== undefined) {
+            fetchOptions.body = config.body;
         }
+    }
+    async executeRequest(url, fetchOptions) {
+        const method = typeof fetchOptions.method === "string" ? fetchOptions.method : "GET";
+        // Setup abort signal with timeout
+        const abortSignal = this.createAbortSignal(this.requestOptions.timeout, this.abortController);
         try {
+            // Run request interceptors before making the request
+            const requestConfig = this.createRequestConfig(url, fetchOptions);
+            const interceptorResult = await this.runRequestInterceptors(requestConfig);
+            // If interceptor returned a Response, short-circuit and wrap it
+            if (interceptorResult instanceof Response) {
+                const graphQLOptions = this.getGraphQLOptions();
+                const wrappedResponse = new ResponseWrapper(interceptorResult, this.url, this.method, graphQLOptions);
+                return await this.runResponseInterceptors(wrappedResponse);
+            }
+            // Update fetchOptions with interceptor modifications
+            url = interceptorResult.url;
+            this.validateUrl(url);
+            this.applyRequestConfig(interceptorResult, fetchOptions);
+            // Set the combined abort signal
+            fetchOptions.signal = abortSignal.signal;
+            // Execute fetch
             let response;
             try {
                 response = await fetch(url, fetchOptions);
             }
             catch (error) {
-                // Check if this is an abort error that was specifically caused by our timeout
-                if (error instanceof DOMException && error.name === "AbortError" && abortedByTimeout) {
-                    throw RequestError.timeout(url, fetchOptions.method, this.requestOptions.timeout);
+                // Check if it's an abort error (DOMException in browsers, or AbortSignal abort)
+                if (error instanceof DOMException && error.name === "AbortError") {
+                    if (abortSignal.wasTimeout()) {
+                        throw RequestError.timeout(url, method, this.requestOptions.timeout);
+                    }
+                    throw RequestError.abortError(url, method);
                 }
-                // Otherwise it's either a user-triggered abort or another network error
-                throw RequestError.networkError(url, fetchOptions.method, error);
+                // Check for Node.js/undici TimeoutError
+                const errorObj = error instanceof Error ? error : new Error(String(error));
+                const errorName = errorObj.name;
+                const errorMessage = errorObj.message.toLowerCase();
+                // Detect timeout errors from Node.js/undici (TimeoutError)
+                const isTimeoutError = errorName === "TimeoutError" || errorMessage.includes("timeout") || errorMessage.includes("aborted due to timeout") || abortSignal.wasTimeout();
+                if (isTimeoutError && this.requestOptions.timeout) {
+                    throw RequestError.timeout(url, method, this.requestOptions.timeout);
+                }
+                throw RequestError.networkError(url, method, errorObj);
             }
             if (!response.ok) {
-                throw RequestError.fromResponse(response, url, fetchOptions.method);
-            }
-            // Return a wrapped response instead of parsing it
-            return new ResponseWrapper(response);
-        }
-        finally {
-            if (timeoutId) {
-                clearTimeout(timeoutId);
+                throw RequestError.fromResponse(response, url, method);
             }
+            const graphQLOptions = this.getGraphQLOptions();
+            const wrappedResponse = new ResponseWrapper(response, url, method, graphQLOptions);
+            return await this.runResponseInterceptors(wrappedResponse);
         }
-    }
-    /**
-     * Executes a request using cache when possible
-     * @param url The formatted URL to send the request to
-     * @param fetchOptions The fetch options to use
-     * @param cacheKey The cache key for this request
-     */
-    async executeWithCache(url, fetchOptions, cacheKey) {
-        // Try to get from cache first
-        if (this.cacheManager) {
-            const cachedEntry = await this.cacheManager.get(cacheKey);
-            if (cachedEntry) {
-                // Create a synthetic Response object from cached data
-                const cachedResponse = new Response(JSON.stringify(cachedEntry.value), {
-                    status: 200,
-                    headers: new Headers(cachedEntry.headers || {}),
-                });
-                return new ResponseWrapper(cachedResponse);
+        catch (error) {
+            // Convert to RequestError if needed
+            let requestError;
+            if (error instanceof RequestError) {
+                requestError = error;
             }
-        }
-        // Not in cache, make the actual request
-        const response = await (!this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions));
-        // Cache the successful response if caching is enabled
-        // Only cache successful responses
-        if (response.ok && this.cacheManager) {
-            // Clone the response so we don't consume it
-            try {
-                const responseData = await response.getJson();
-                // Extract headers to store in cache
-                const headers = {};
-                response.headers.forEach((value, key) => {
-                    headers[key] = value;
-                });
-                // Store in cache
-                await this.cacheManager.set(cacheKey, responseData, headers);
+            else {
+                const errorObj = error instanceof Error ? error : new Error(String(error));
+                requestError = RequestError.networkError(url, method, errorObj);
             }
-            catch (error) {
-                // Failed to cache, but we can still return the response
-                console.warn("Failed to cache response:", error);
+            // Run error interceptors
+            const interceptorResult = await this.runErrorInterceptors(requestError);
+            // If error interceptor returned a ResponseWrapper, recover from error
+            if (interceptorResult instanceof ResponseWrapper) {
+                return interceptorResult;
             }
+            throw interceptorResult;
+        }
+        finally {
+            abortSignal.cleanup();
         }
-        return response;
     }
 }
 
@@ -1339,6 +1825,10 @@ class BaseRequest {
  * Base class for requests that can have a body (POST, PUT, PATCH)
  */
 class BodyRequest extends BaseRequest {
+    constructor(url) {
+        super(url);
+        this.graphQLOptions = undefined;
+    }
     /**
      * Sets the body of the request
      * @param body - The request body
@@ -1360,7 +1850,8 @@ class BodyRequest extends BaseRequest {
                 JSON.stringify(body);
             }
             catch (error) {
-                throw new Error(`Failed to stringify request body: ${String(error)}`);
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new RequestError(`JSON stringify failed: ${errorMessage}`, this.url, this.method);
             }
         }
         else {
@@ -1368,18 +1859,93 @@ class BodyRequest extends BaseRequest {
         }
         return this;
     }
-    setContentTypeIfNeeded(contentType) {
-        // Only set if not already set
+    /**
+     * Sets a GraphQL query or mutation as the request body
+     * Automatically formats the body as JSON and sets Content-Type to application/json
+     *
+     * @param query - The GraphQL query or mutation string
+     * @param variables - Optional variables object to pass with the query
+     * @param options - Optional GraphQL-specific options
+     * @returns The request instance for chaining
+     *
+     * @example
+     * const request = new PostRequest('/graphql')
+     *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
+     *
+     * @example
+     * const request = new PostRequest('/graphql')
+     *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
+     *
+     * @example
+     * // Throw an error if the GraphQL response contains errors
+     * const request = new PostRequest('/graphql')
+     *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
+     */
+    withGraphQL(query, variables, options) {
+        if (typeof query !== "string" || query.length === 0) {
+            throw new RequestError("Invalid GraphQL query", this.url, this.method);
+        }
+        const graphQLBody = {
+            query: query,
+        };
+        if (variables !== undefined) {
+            if (typeof variables !== "object" || variables === null || Array.isArray(variables)) {
+                throw new RequestError("Invalid GraphQL variables", this.url, this.method);
+            }
+            graphQLBody.variables = variables;
+        }
+        // Store GraphQL options if provided
+        if (options !== undefined) {
+            if (typeof options !== "object" || options === null || Array.isArray(options)) {
+                throw new RequestError("Invalid GraphQL options", this.url, this.method);
+            }
+            // Store only the known GraphQL options properties
+            const opts = options;
+            this.graphQLOptions = {
+                throwOnError: typeof opts.throwOnError === "boolean" ? opts.throwOnError : undefined,
+            };
+        }
+        // Validate JSON is stringifiable early
+        try {
+            JSON.stringify(graphQLBody);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new RequestError(`JSON stringify failed: ${errorMessage}`, this.url, this.method);
+        }
+        this.body = graphQLBody;
+        this.bodyType = BodyType.JSON;
+        this.setContentTypeIfNeeded("application/json");
+        return this;
+    }
+    /**
+     * Check if Content-Type header is already set (case-insensitive)
+     */
+    hasContentType() {
         const headers = this.requestOptions.headers;
-        if (!Object.keys(headers).some(header => header.toLowerCase() === "content-type")) {
+        if (typeof headers === "object" && headers !== null) {
+            const headersObj = headers;
+            return Object.keys(headersObj).some(header => header.toLowerCase() === "content-type");
+        }
+        return false;
+    }
+    setContentTypeIfNeeded(contentType) {
+        if (!this.hasContentType()) {
             this.withContentType(contentType);
         }
     }
     /**
-     * Send the request to the specified URL
+     * Get the GraphQL options if set
+     * @returns The GraphQL options or undefined
+     */
+    getGraphQLOptions() {
+        return this.graphQLOptions;
+    }
+    /**
+     * Execute the request and return the ResponseWrapper
      * Overrides the base implementation to add body handling
      */
-    sendTo(url) {
+    async getResponse() {
         if (this.body !== undefined) {
             // Remove previous body if it exists
             if (this.requestOptions.body)
@@ -1392,100 +1958,222 @@ class BodyRequest extends BaseRequest {
                 this.requestOptions.body = this.body;
             }
         }
-        return super.sendTo(url);
+        return super.getResponse();
     }
 }
 
-// Methods without body
+/**
+ * HTTP GET request implementation
+ * Used for retrieving data from an API endpoint.
+ *
+ * @example
+ * const request = new GetRequest('/api/users')
+ *   .withQueryParams({ id: '123' });
+ * const data = await request.getData();
+ */
 class GetRequest extends BaseRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.GET;
     }
 }
+/**
+ * HTTP HEAD request implementation
+ * Similar to GET but returns only headers without a response body.
+ *
+ * @example
+ * const request = new HeadRequest('/api/users/123');
+ * const response = await request.getResponse();
+ */
 class HeadRequest extends BaseRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.HEAD;
     }
 }
+/**
+ * HTTP OPTIONS request implementation
+ * Used to describe the communication options for the target resource.
+ *
+ * @example
+ * const request = new OptionsRequest('/api/users');
+ * const response = await request.getResponse();
+ */
 class OptionsRequest extends BaseRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.OPTIONS;
     }
 }
+/**
+ * HTTP DELETE request implementation
+ * Used to delete a resource on the server.
+ *
+ * @example
+ * const request = new DeleteRequest('/api/users/123');
+ * await request.getData();
+ */
 class DeleteRequest extends BaseRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.DELETE;
     }
 }
-// Methods with body
+/**
+ * HTTP POST request implementation
+ * Used to create a new resource or submit data for processing.
+ *
+ * @example
+ * const request = new PostRequest('/api/users')
+ *   .withJson({ name: 'John', email: 'john@example.com' });
+ * const data = await request.getData();
+ */
 class PostRequest extends BodyRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.POST;
     }
 }
+/**
+ * HTTP PUT request implementation
+ * Used to replace or update an existing resource.
+ *
+ * @example
+ * const request = new PutRequest('/api/users/123')
+ *   .withJson({ id: '123', name: 'John', email: 'john@example.com' });
+ * const data = await request.getData();
+ */
 class PutRequest extends BodyRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.PUT;
     }
 }
+/**
+ * HTTP PATCH request implementation
+ * Used to apply partial modifications to a resource.
+ *
+ * @example
+ * const request = new PatchRequest('/api/users/123')
+ *   .withJson({ email: 'new.email@example.com' });
+ * const data = await request.getData();
+ */
 class PatchRequest extends BodyRequest {
-    constructor() {
-        super(...arguments);
+    constructor(url) {
+        super(url);
         this.method = HttpMethod.PATCH;
     }
 }
 
 /**
  * Create a GET request
+ * Used for retrieving resources from the server.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new GET request instance
+ *
+ * @example
+ * const request = get('/api/users')
+ *   .withQueryParams({ limit: 10 });
+ * const users = await request.getData();
  */
-function get() {
-    return new GetRequest();
+function get(url) {
+    return new GetRequest(url);
 }
 /**
  * Create a POST request
+ * Used for creating new resources or submitting data.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new POST request instance
+ *
+ * @example
+ * const request = post('/api/users')
+ *   .withJson({ name: 'John', email: 'john@example.com' });
+ * const newUser = await request.getData();
  */
-function post() {
-    return new PostRequest();
+function post(url) {
+    return new PostRequest(url);
 }
 /**
  * Create a PUT request
+ * Used for replacing or updating an existing resource.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new PUT request instance
+ *
+ * @example
+ * const request = put('/api/users/123')
+ *   .withJson({ name: 'John Updated', email: 'john@example.com' });
+ * const updatedUser = await request.getData();
  */
-function put() {
-    return new PutRequest();
+function put(url) {
+    return new PutRequest(url);
 }
 /**
  * Create a DELETE request
- * Note: We use 'del' to avoid JS keyword conflict
+ * Used for removing resources from the server.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new DELETE request instance
+ *
+ * @example
+ * const request = del('/api/users/123');
+ * await request.getData();
  */
-function del() {
-    return new DeleteRequest();
+function del(url) {
+    return new DeleteRequest(url);
 }
 /**
  * Create a PATCH request
+ * Used for applying partial modifications to a resource.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new PATCH request instance
+ *
+ * @example
+ * const request = patch('/api/users/123')
+ *   .withJson({ status: 'active' });
+ * const patchedUser = await request.getData();
  */
-function patch() {
-    return new PatchRequest();
+function patch(url) {
+    return new PatchRequest(url);
 }
 /**
  * Create a HEAD request
+ * Similar to GET but returns only headers without a body.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new HEAD request instance
+ *
+ * @example
+ * const request = head('/api/users/123');
+ * const response = await request.getResponse();
+ * console.log(response.headers.get('Last-Modified'));
  */
-function head() {
-    return new HeadRequest();
+function head(url) {
+    return new HeadRequest(url);
 }
 /**
  * Create an OPTIONS request
+ * Used to describe the communication options for a resource.
+ *
+ * @param url - The URL to send the request to
+ * @returns A new OPTIONS request instance
+ *
+ * @example
+ * const request = options('/api/users');
+ * const response = await request.getResponse();
+ * console.log(response.headers.get('Allow'));
  */
-function options() {
-    return new OptionsRequest();
+function options(url) {
+    return new OptionsRequest(url);
 }
 
-// Create the main API object with configuration
+/**
+ * Main API object for creating HTTP requests
+ * Provides factory methods for all HTTP methods and access to global configuration.
+ */
 const create = {
     get,
     post,
@@ -1494,8 +2182,8 @@ const create = {
     patch,
     head,
     options,
-    // Add configuration access
     config: Config.getInstance(),
 };
 
-export { CacheManager, CacheMode, CookieUtils, CredentialsPolicy, DeleteRequest, GetRequest, HeadRequest, HttpMethod, OptionsRequest, PatchRequest, PostRequest, PutRequest, RedirectMode, ReferrerPolicy, RequestError, RequestMode, RequestPriority, ResponseWrapper, SameSitePolicy, createLocalStorageStorage, createMemoryStorage, createSessionStorageStorage, create as default };
+export { CookieUtils, CredentialsPolicy, DeleteRequest, GetRequest, HeadRequest, HttpMethod, OptionsRequest, PatchRequest, PostRequest, PutRequest, RedirectMode, ReferrerPolicy, RequestError, RequestMode, RequestPriority, ResponseWrapper, SameSitePolicy, create as default };
+//# sourceMappingURL=index.esm.js.map