create-request 1.4.2 → 1.4.3-rc.1

package/dist/library/index.cjs

@@ -85,7 +85,7 @@ exports.ReferrerPolicy = void 0;
 /**
  * Cache modes for fetch requests
  */
-var CacheMode;
+exports.CacheMode = void 0;
 (function (CacheMode) {
     CacheMode["RELOAD"] = "reload";
     CacheMode["DEFAULT"] = "default";
@@ -93,7 +93,7 @@ var CacheMode;
     CacheMode["NO_STORE"] = "no-store";
     CacheMode["FORCE_CACHE"] = "force-cache";
     CacheMode["ONLY_IF_CACHED"] = "only-if-cached";
-})(CacheMode || (CacheMode = {}));
+})(exports.CacheMode || (exports.CacheMode = {}));
 
 class RequestError extends Error {
     status;
@@ -103,7 +103,7 @@ class RequestError extends Error {
     isTimeout;
     isAborted;
     constructor(message, url, method, options = {}) {
-        super(message);
+        super(message, { cause: options.cause });
         this.name = "RequestError";
         this.url = url;
         this.method = method;
@@ -122,7 +122,7 @@ class RequestError extends Error {
      * Static methods for creating specific types of RequestError
      */
     static timeout(url, method, timeoutMs) {
-        return new RequestError(`Timeout: ${timeoutMs}ms`, url, method, {
+        return new RequestError(`Timeout ${timeoutMs}ms`, url, method, {
             isTimeout: true,
         });
     }
@@ -164,16 +164,16 @@ class RequestError extends Error {
             // 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}`;
+                message = `Timeout ${url}`;
             }
             else if (isDnsError) {
-                message = `Network error: Unable to resolve hostname for ${url}`;
+                message = `DNS error ${url}`;
             }
             else if (isConnectionError) {
-                message = `Network error: Connection refused for ${url}`;
+                message = `Connection refused ${url}`;
             }
             else {
-                message = `Network error: Failed to fetch ${url}`;
+                message = `Network error ${url}`;
             }
         }
         const error = new RequestError(message, url, method, {
@@ -200,11 +200,15 @@ class RequestError extends Error {
  * Wrapper for HTTP responses with methods to transform the response data
  */
 class ResponseWrapper {
-    response;
     url;
     method;
-    // GraphQL-specific options
+    response;
     graphQLOptions;
+    // Cache the body as the last used method
+    cachedBlob;
+    cachedText;
+    cachedJson;
+    cachedArrayBuffer;
     constructor(response, url, method, graphQLOptions) {
         this.response = response;
         this.url = url;
@@ -231,6 +235,18 @@ class ResponseWrapper {
     get raw() {
         return this.response;
     }
+    /**
+     * Check if the response body has already been consumed and throw an error if so
+     * @throws RequestError if the body has already been consumed
+     */
+    checkBodyNotConsumed() {
+        if (this.response.bodyUsed) {
+            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
+                status: this.response.status,
+                response: this.response,
+            });
+        }
+    }
     /**
      * Check for GraphQL errors and throw if throwOnError is enabled
      * @param data - The parsed JSON data
@@ -245,18 +261,17 @@ class ResponseWrapper {
         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 || "", {
+        throw new RequestError(`GraphQL errors: ${errorMessage}`, this.url || "", this.method || "", {
             status: this.response.status,
             response: this.response,
         });
     }
     /**
      * Parse the response body as JSON
-     * Note: This consumes the response body and can only be called once.
      * 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
+     * @throws {RequestError} When the request fails, JSON parsing fails, or GraphQL errors occur (if throwOnError enabled).
      *
      * @example
      * const data = await response.getJson();
@@ -273,19 +288,16 @@ class ResponseWrapper {
      * }
      */
     async getJson() {
-        if (this.response.bodyUsed) {
-            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
-                status: this.response.status,
-                response: this.response,
-            });
-        }
+        if (this.cachedJson !== undefined)
+            return this.cachedJson;
+        this.checkBodyNotConsumed();
         try {
             const parsed = await this.response.json();
+            this.cachedJson = parsed;
             this.checkGraphQLErrors(parsed);
             return parsed;
         }
         catch (error) {
-            // Re-throw RequestErrors from checkGraphQLErrors without wrapping
             if (error instanceof RequestError) {
                 throw error;
             }
@@ -298,23 +310,21 @@ class ResponseWrapper {
     }
     /**
      * Get the response body as text
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response text
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const text = await response.getText();
      */
     async getText() {
-        if (this.response.bodyUsed) {
-            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
-                status: this.response.status,
-                response: this.response,
-            });
-        }
+        if (this.cachedText !== undefined)
+            return this.cachedText;
+        this.checkBodyNotConsumed();
         try {
-            return await this.response.text();
+            const text = await this.response.text();
+            this.cachedText = text;
+            return text;
         }
         catch (e) {
             const errorMessage = e instanceof Error ? e.message : String(e);
@@ -326,24 +336,22 @@ class ResponseWrapper {
     }
     /**
      * Get the response body as a Blob
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response as a Blob
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const blob = await response.getBlob();
      * const url = URL.createObjectURL(blob);
      */
     async getBlob() {
-        if (this.response.bodyUsed) {
-            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
-                status: this.response.status,
-                response: this.response,
-            });
-        }
+        if (this.cachedBlob !== undefined)
+            return this.cachedBlob;
+        this.checkBodyNotConsumed();
         try {
-            return await this.response.blob();
+            const blob = await this.response.blob();
+            this.cachedBlob = blob;
+            return blob;
         }
         catch (e) {
             const errorMessage = e instanceof Error ? e.message : String(e);
@@ -355,24 +363,23 @@ class ResponseWrapper {
     }
     /**
      * Get the response body as an ArrayBuffer
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response as an ArrayBuffer
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const buffer = await response.getArrayBuffer();
      * const uint8Array = new Uint8Array(buffer);
      */
     async getArrayBuffer() {
-        if (this.response.bodyUsed) {
-            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
-                status: this.response.status,
-                response: this.response,
-            });
+        if (this.cachedArrayBuffer !== undefined) {
+            return this.cachedArrayBuffer;
         }
+        this.checkBodyNotConsumed();
         try {
-            return await this.response.arrayBuffer();
+            const arrayBuffer = await this.response.arrayBuffer();
+            this.cachedArrayBuffer = arrayBuffer;
+            return arrayBuffer;
         }
         catch (e) {
             const errorMessage = e instanceof Error ? e.message : String(e);
@@ -385,6 +392,7 @@ class ResponseWrapper {
     /**
      * Get the raw response body as a ReadableStream
      * Note: This consumes the response body and should only be called once.
+     * Unlike other methods, streams cannot be cached, so this will throw if the body is already consumed.
      *
      * @returns The response body as a ReadableStream or null
      * @throws {RequestError} When the response body has already been consumed
@@ -397,12 +405,7 @@ class ResponseWrapper {
      * }
      */
     getBody() {
-        if (this.response.bodyUsed) {
-            throw new RequestError("Body already consumed", this.url || "", this.method || "", {
-                status: this.response.status,
-                response: this.response,
-            });
-        }
+        this.checkBodyNotConsumed();
         return this.response.body;
     }
     /**
@@ -894,17 +897,17 @@ class BaseRequest {
     }
     validateUrl(url) {
         if (!url?.trim())
-            throw new RequestError("URL cannot be empty", url, this.method);
+            throw new RequestError("Invalid URL", url, this.method);
         if (url.includes("\0") || url.includes("\r") || url.includes("\n")) {
-            throw new RequestError("Invalid URL (control chars)", url, this.method);
+            throw new RequestError("Invalid URL", url, this.method);
         }
         const trimmed = url.trim();
-        if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+        if (/^https?:\/\//.test(trimmed)) {
             try {
                 new URL(trimmed);
             }
             catch {
-                throw new RequestError(`Invalid URL: ${trimmed}`, trimmed, this.method);
+                throw new RequestError("Invalid URL", trimmed, this.method);
             }
         }
     }
@@ -945,11 +948,7 @@ class BaseRequest {
      * request.withHeader('Accept', 'application/json');
      */
     withHeader(key, value) {
-        // Ignore null and undefined values
-        if (value !== null && value !== undefined) {
-            return this.withHeaders({ [key]: value });
-        }
-        return this;
+        return this.withHeaders({ [key]: value });
     }
     /**
      * Set a timeout for the request
@@ -964,7 +963,7 @@ class BaseRequest {
      */
     withTimeout(timeout) {
         if (!Number.isFinite(timeout) || timeout <= 0)
-            throw new RequestError("Timeout must be a positive number", this.url, this.method);
+            throw new RequestError("Invalid timeout", this.url, this.method);
         this.requestOptions.timeout = timeout;
         return this;
     }
@@ -1348,13 +1347,7 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withQueryParam(key, value) {
-        if (value === null || value === undefined)
-            return this;
-        if (Array.isArray(value))
-            value.forEach(v => this.queryParams.append(key, String(v)));
-        else
-            this.queryParams.append(key, String(value));
-        return this;
+        return this.withQueryParams({ [key]: value });
     }
     /**
      * Sets the request mode, which determines the CORS (Cross-Origin Resource Sharing) behavior
@@ -1398,9 +1391,7 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withContentType(contentType) {
-        return this.withHeaders({
-            "Content-Type": contentType,
-        });
+        return this.withHeader("Content-Type", contentType);
     }
     /**
      * Shorthand for setting the Authorization header
@@ -1408,9 +1399,7 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withAuthorization(authValue) {
-        return this.withHeaders({
-            Authorization: authValue,
-        });
+        return this.withHeader("Authorization", authValue);
     }
     /**
      * Shorthand for setting up Basic authentication
@@ -1440,7 +1429,7 @@ class BaseRequest {
         if (typeof Buffer !== "undefined")
             return Buffer.from(str).toString("base64");
         // Fallback (should never happen in modern environments)
-        throw new RequestError("Base64 encoding is not supported", this.url, this.method);
+        throw new RequestError("Encoding not supported", this.url, this.method);
     }
     /**
      * Sets the bearer token for authentication
@@ -1525,9 +1514,7 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withCsrfToken(token, headerName = "X-CSRF-Token") {
-        return this.withHeaders({
-            [headerName]: token,
-        });
+        return this.withHeader(headerName, token);
     }
     /**
      * Disables automatic anti-CSRF protection.
@@ -1543,9 +1530,7 @@ class BaseRequest {
      * @returns The instance for chaining
      */
     withAntiCsrfHeaders() {
-        return this.withHeaders({
-            "X-Requested-With": "XMLHttpRequest",
-        });
+        return this.withHeader("X-Requested-With", "XMLHttpRequest");
     }
     /**
      * Add a request interceptor for this specific request
@@ -1714,9 +1699,7 @@ class BaseRequest {
         const config = Config.getInstance();
         // Apply anti-CSRF headers if enabled
         if (config.isAntiCsrfEnabled()) {
-            this.withHeaders({
-                "X-Requested-With": "XMLHttpRequest",
-            });
+            this.withAntiCsrfHeaders();
         }
         // Apply global CSRF token if set
         const globalToken = config.getCsrfToken();
@@ -1724,9 +1707,7 @@ class BaseRequest {
             const csrfHeaderName = config.getCsrfHeaderName();
             const hasLocalToken = this.hasHeader("X-CSRF-Token") || this.hasHeader(csrfHeaderName);
             if (!hasLocalToken) {
-                this.withHeaders({
-                    [csrfHeaderName]: globalToken,
-                });
+                this.withHeader(csrfHeaderName, globalToken);
             }
         }
         // Check for XSRF token in cookies and send it as a header
@@ -1736,9 +1717,7 @@ class BaseRequest {
                 const xsrfHeaderName = config.getXsrfHeaderName();
                 const hasLocalToken = this.hasHeader("X-XSRF-TOKEN") || this.hasHeader(xsrfHeaderName);
                 if (!hasLocalToken) {
-                    this.withHeaders({
-                        [xsrfHeaderName]: xsrfToken,
-                    });
+                    this.withHeader(xsrfHeaderName, xsrfToken);
                 }
             }
         }
@@ -1797,7 +1776,7 @@ class BaseRequest {
                     const delay = typeof retriesConfig.delay === "function" ? retriesConfig.delay({ attempt: attempt + 1, error: requestError }) : retriesConfig.delay;
                     // Validate delay result
                     if (typeof delay !== "number" || !Number.isFinite(delay) || delay < 0) {
-                        throw new RequestError(`Invalid retry delay: ${delay}`, url, method);
+                        throw new RequestError(`Invalid delay: ${delay}`, url, method);
                     }
                     // Wait for the delay
                     if (delay > 0) {
@@ -1807,7 +1786,7 @@ class BaseRequest {
             }
         }
         // This should never happen but is needed for type safety
-        throw new RequestError(`Max retries reached`, url, method);
+        throw new RequestError(`EO`, url, method);
     }
     /**
      * Run request interceptors in order: global interceptors first, then per-request
@@ -1829,7 +1808,7 @@ class BaseRequest {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new RequestError(`Request interceptor failed: ${errorMessage}`, currentConfig.url, currentConfig.method);
+                throw new RequestError(`Req Interceptor failed: ${errorMessage}`, currentConfig.url, currentConfig.method);
             }
         }
         return currentConfig;
@@ -1853,7 +1832,7 @@ class BaseRequest {
                 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);
+                throw new RequestError(`Res Interceptor failed: ${errorMessage}`, url, method);
             }
         }
         return currentResponse;
@@ -1887,14 +1866,14 @@ class BaseRequest {
                     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, {
+                        currentError = new RequestError(`Err 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, {
+                        currentError = new RequestError(`Err Interceptor ${i + 1} failed: ${errorMessage}`, currentError.url, currentError.method, {
                             status: currentError.status,
                         });
                     }
@@ -2137,7 +2116,7 @@ class BodyRequest extends BaseRequest {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new RequestError(`JSON stringify failed: ${errorMessage}`, this.url, this.method);
+                throw new RequestError(`Invalid JSON: ${errorMessage}`, this.url, this.method);
             }
         }
         else {
@@ -2169,21 +2148,21 @@ class BodyRequest extends BaseRequest {
      */
     withGraphQL(query, variables, options) {
         if (typeof query !== "string" || query.length === 0) {
-            throw new RequestError("Invalid GraphQL query", this.url, this.method);
+            throw new RequestError("Invalid 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);
+                throw new RequestError("Invalid vars", 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);
+                throw new RequestError("Invalid options", this.url, this.method);
             }
             // Store only the known GraphQL options properties
             const opts = options;
@@ -2197,7 +2176,7 @@ class BodyRequest extends BaseRequest {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new RequestError(`JSON stringify failed: ${errorMessage}`, this.url, this.method);
+            throw new RequestError(`Invalid JSON: ${errorMessage}`, this.url, this.method);
         }
         this.body = graphQLBody;
         this.bodyType = BodyType.JSON;
@@ -2456,15 +2435,280 @@ function options(url) {
     return new OptionsRequest(url);
 }
 
+/**
+ * Resolves a URL against a base URL.
+ * If the URL is absolute (starts with http:// or https://), it is returned as-is.
+ * Otherwise, it is resolved relative to the base URL.
+ *
+ * @param baseURL - The base URL to resolve against, or undefined if not set
+ * @param url - The URL to resolve, or undefined to return the base URL
+ * @returns The resolved absolute URL string
+ * @example
+ * resolveURL("https://api.example.com", "/users") // "https://api.example.com/users"
+ * resolveURL("https://api.example.com", "users") // "https://api.example.com/users"
+ * resolveURL("https://api.example.com", "https://other.com") // "https://other.com"
+ */
+function resolveURL(baseURL, url) {
+    if (!url)
+        return baseURL || "";
+    if (!baseURL)
+        return url;
+    if (/^https?:\/\//.test(url))
+        return url;
+    try {
+        return new URL(url, baseURL.endsWith("/") ? baseURL : baseURL + "/").toString();
+    }
+    catch {
+        return baseURL.replace(/\/$/, "") + (url.startsWith("/") ? url : "/" + url);
+    }
+}
+/**
+ * API builder for creating configured API instances with default settings.
+ * Allows you to set default headers, timeouts, authentication, and other options
+ * that will be applied to all requests created through this builder.
+ *
+ * @example
+ * ```typescript
+ * const api = create.api()
+ *   .withBaseURL("https://api.example.com")
+ *   .withBearerToken("token123")
+ *   .withTimeout(5000);
+ *
+ * // All requests will use the base URL, bearer token, and timeout
+ * await api.get("/users").getJson();
+ * await api.post("/posts").withBody({ title: "Hello" }).getJson();
+ * ```
+ */
+class ApiBuilder {
+    baseURL;
+    modifiers;
+    /**
+     * Sets the base URL for all requests created through this API builder.
+     * Relative URLs will be resolved against this base URL.
+     *
+     * @param baseURL - The base URL to use for all requests
+     * @returns The API builder instance for method chaining
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.get("/users").getJson(); // Requests https://api.example.com/users
+     * ```
+     */
+    withBaseURL(baseURL) {
+        this.baseURL = baseURL;
+        return this;
+    }
+    /**
+     * Adds a modifier function that will be applied to all requests created through this builder.
+     *
+     * @private
+     * @param modifier - A function that modifies a request and returns it
+     * @returns The API builder instance for method chaining
+     */
+    addModifier(modifier) {
+        if (!this.modifiers)
+            this.modifiers = [];
+        this.modifiers.push(modifier);
+        return this;
+    }
+    /**
+     * Creates a GET request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A GetRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.get("/users").getJson();
+     * await api.get("https://other.com/data").getJson(); // Absolute URL overrides base
+     * ```
+     */
+    get = (url) => {
+        const request = get(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a POST request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PostRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.post("/users").withBody({ name: "John" }).getJson();
+     * ```
+     */
+    post = (url) => {
+        const request = post(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a PUT request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PutRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.put("/users/123").withBody({ name: "Jane" }).getJson();
+     * ```
+     */
+    put = (url) => {
+        const request = put(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a DELETE request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A DeleteRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.del("/users/123").getResponse();
+     * ```
+     */
+    del = (url) => {
+        const request = del(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a PATCH request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PatchRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.patch("/users/123").withBody({ name: "Updated" }).getJson();
+     * ```
+     */
+    patch = (url) => {
+        const request = patch(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a HEAD request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A HeadRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * const response = await api.head("/users").getResponse();
+     * ```
+     */
+    head = (url) => {
+        const request = head(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates an OPTIONS request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns An OptionsRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.options("/users").getResponse();
+     * ```
+     */
+    options = (url) => {
+        const request = options(resolveURL(this.baseURL, url));
+        if (this.modifiers)
+            for (const modifier of this.modifiers)
+                modifier(request);
+        return request;
+    };
+    /**
+     * Creates a new ApiBuilder instance with a Proxy that enables dynamic method forwarding.
+     * The Proxy allows calling any `with*` method from BaseRequest on the API builder,
+     * which will apply that configuration to all requests created through this builder.
+     *
+     * @internal
+     */
+    constructor() {
+        const proxy = new Proxy(this, {
+            get(target, prop) {
+                const propertyValue = target[prop];
+                if (propertyValue !== undefined) {
+                    if (typeof propertyValue === "function") {
+                        return (...args) => {
+                            const result = propertyValue.apply(target, args);
+                            return result === target ? proxy : result;
+                        };
+                    }
+                    return propertyValue;
+                }
+                if (typeof prop === "string" && prop.startsWith("with") && prop !== "withBaseURL") {
+                    if (prop === "withAbortController" || prop === "withBody" || prop === "withGraphQL")
+                        return undefined;
+                    const prototypeMethod = BaseRequest.prototype[prop];
+                    if (typeof prototypeMethod === "function") {
+                        return (...args) => {
+                            target.addModifier((request) => prototypeMethod.apply(request, args));
+                            return proxy;
+                        };
+                    }
+                }
+                return undefined;
+            },
+        });
+        return proxy;
+    }
+}
+/**
+ * Creates a new API builder instance for configuring default request settings.
+ * The builder allows you to set base URLs, authentication, headers, timeouts,
+ * and other options that will be applied to all requests created through it.
+ *
+ * @returns A new ApiBuilder instance with all configuration methods available
+ * @example
+ * ```typescript
+ * // Create an API instance with default configuration
+ * const api = create.api()
+ *   .withBaseURL("https://api.example.com")
+ *   .withBearerToken("your-token")
+ *   .withTimeout(5000)
+ *   .withHeaders({ "X-Custom": "value" });
+ *
+ * // All requests will use these defaults
+ * const users = await api.get("/users").getJson();
+ * const newUser = await api.post("/users").withBody({ name: "John" }).getJson();
+ * ```
+ */
+function api() {
+    return new ApiBuilder();
+}
+
 /**
  * Main API object for creating HTTP requests
  * Provides factory methods for all HTTP methods and access to global configuration.
  */
 const create = {
+    api,
     get,
-    post,
     put,
     del,
+    post,
     patch,
     head,
     options,